Shudesu/line-harness-oss · 上手攻略

  • 仓库：Shudesu/line-harness-oss
  • 链接：https://github.com/Shudesu/line-harness-oss
  • 分类：CRM / Marketing Automation / LINE Messaging API
  • 作者：spark
  • 更新：2026-09-11

注：仓库原名 line-harness-oss，2026-08-19 起产品展示名统一为「L Harness」，仓库 URL、create-line-harness、@line-harness/* 等保留为兼容标识（详见 BRAND.md）。下文按官方 README 用「L Harness」指代产品本身，仍以仓库原名 line-harness-oss 作为安装与文件路径引用。

是什么

L Harness 是一个自托管的 LINE 官方账号 CRM，基于 Cloudflare Workers + D1 + Pages（Next.js 15），用 TypeScript 写成，MIT 协议开源。它把 LINE 官方账号的运营拆成四件事：好友管理、消息/广播/场景式触达（步骤配信）、表单/预约/调查（LIFF），以及基于规则 + 外部 AI 的自动化。软件本体免费，但要付 LINE 官方账号的投递费、Cloudflare 资源费、外部 AI 服务费，以及自己投入运维和域名。

从工程视角看，它和「L 社」「U 社」等付费 SaaS 的最大差异是：

维度 L 社 U 社 L Harness（OSS）
月费 2 万日元起 1 万日元起 0（软件本体）
步骤/分段/广播 ✅ ✅ ✅
评分 / IF-THEN / API 公开 部分 部分 全部 ✅
Claude Code / MCP ❌ ❌ 内置 MCP server
多账号 / BAN 池 / 重号检测 单独签约 单独签约 标准内置
源码 闭源 闭源 MIT

⚠️ 表格里的对比来自仓库自述（README §比較表），不是独立第三方测评；请以最新 BRAND.md 和官方页 https://the-harness.com/line-harness/pricing/ 为准。

解决什么问题

做 LINE 营销/客服的人，几乎只能选「L 社 / U 社」这类 SaaS：上手快，但要付月费 + 受限于 API 上限 + 数据托管在第三方 + 想接自己的 AI 流程要等官方放开 webhook。L Harness 的解法是：

  1. 数据自治：好友、标签、行为日志全部在自己 Cloudflare D1 上；
  2. 可扩展：插件机制允许把自定义 Worker 抽出去跑，本体升级不踩坏自家代码；
  3. AI 友好：内置 MCP server，Claude Code 等 IDE 助手能用自然语言操控「列未回复会话 / 创建场景 / 起草广播文案」；
  4. 多账号 + 反封：把多个 LINE 官方账号接入同一个面板，自动检测 BAN 并把流量切到健康账号（pool 功能）。

它面向的是技术团队、中小型代理商，以及「想自己掌控 LINE 运营数据 + 自动化链路」的个人/小工作室。

快速安装

仓库 README 给的是「5 分钟 CLI 一键启动」，实际前置条件比较硬：

  • Cloudflare 账号（免费档即可，但 D1 免费档有读写上限，到顶会报错而非超额扣费——README 自承）；
  • LINE 官方账号 + 已开通的 Messaging API channel；
  • Node.js 22+；
  • pnpm；
  • 一个自己的域名（管理面板托管在 Cloudflare Pages，免费 *.pages.dev 子域也能跑）。

最简步骤（来自 README）：

# 1. 安装脚手架
npm i -g create-line-harness   # 或 npx create-line-harness

# 2. 在仓库根目录（或新目录）启动 CLI，按提示逐项授权
pnpm create line-harness       # 或 npx create-line-harness

# 3. CLI 会自动：
#    - wrangler login 鉴权 Cloudflare
#    - 创建 D1 数据库 + 应用迁移
#    - 部署 Worker 与 Pages 管理后台
#    - 注册 LINE credentials
#    - 创建 LIFF app
#    - 建 Owner 账户

# 4. 完成后访问 https://<your-name>-admin.pages.dev

确认版本的命令：

# 仓库根目录
git describe --tags          # README 自报当前 v0.21.0（截至 2026-09-10）

# 升级 CLI / 插件到指定版本（pnpm workspace）
pnpm up -r @line-harness/sdk @line-harness/mcp-server

⚠️ 我没有真实环境跑过这个 CLI，所以「约 5 分钟」「D1 免费档行为」都是仓库自述，使用前建议先在非生产 channel 试一遍，并把 Cloudflare 计费告警打开。

核心用法

1) 投递基础设施

# Worker 单独跑本地开发
pnpm --filter worker dev

# 全栈并行（Worker + Next.js 管理后台）
pnpm dev

部署到 Cloudflare：

pnpm --filter worker deploy          # API + LIFF + Webhook
pnpm --filter web deploy             # 管理后台（Pages）
pnpm --filter @line-harness/db migrate:prod   # D1 schema 升级

2) 用 MCP / Claude Code 操控

仓库自带 @line-harness/mcp-server，在 Claude Code 的 MCP 配置里挂上即可（路径以实际安装为准）：

// ~/.claude/mcp_servers.json  示例结构（README 未给完整 JSON，按 npm 文档推断）
{
  "mcpServers": {
    "line-harness": {
      "command": "npx",
      "args": ["-y", "@line-harness/mcp-server"],
      "env": {
        "LINE_HARNESS_BASE_URL": "https://<your-name>-admin.pages.dev",
        "LINE_HARNESS_API_KEY": "<your staff key>"
      }
    }
  }
}

然后在 Claude Code 里就能：

  • list_conversations —— 拉未回复会话（自动过滤系统消息）；
  • create_scenario / update_step —— AI 起草步骤式触达场景；
  • broadcast / send_message —— 推送消息（按 README 描述需要二次确认）。

⚠️ 上面 JSON 字段名是我按 README 描述+通用 MCP 约定推断的，仓库 README 没给完整的 server 配置示例；正式接入前请看 packages/mcp-server/README.md 与 npm 页 https://www.npmjs.com/package/@line-harness/mcp-server 的真实字段。

3) 用 TypeScript SDK 写自定义逻辑

@line-harness/sdk 是零依赖、ESM+CJS 双产物的薄 SDK：

import { createClient } from "@line-harness/sdk";

const client = createClient({
  baseUrl: process.env.LINE_HARNESS_BASE_URL!,
  apiKey: process.env.LINE_HARNESS_API_KEY!, // Staff / Admin / Owner 任一即可
});

const { conversations } = await client.conversations.list({ status: "unreplied" });
for (const c of conversations) {
  await client.messages.reply(c.id, { text: "已收到，我们稍后联系您" });
}

4) 插件机制（核心扩展点）

# 在仓库根目录起一个独立插件工程
pnpm plugin:create ../my-plugin

生成的插件位于独立目录，发布后能挂在管理画面「插件市场」（β 版）。README 强调两件事：

  • API 兼容性 ≠ 不被覆盖：SDK 与接口是兼容契约，但本体升级时仍要在测试环境验证；
  • 不要把业务代码塞回主仓：本体更新时会被覆盖。

5) 多账号 + 反封（pool）

把多个 LINE 官方账号接入同一个面板后：

  • 各自独立场景/标签/送达作用域；
  • 触发 BAN 检测 → 自动把后续流量切到下一个健康账号；
  • 跨账号 picture_url 中间 token 匹配，识别「同一个人重复加好友」并打标签。

典型适用场景

  • 中小代理商做客户托管：每个客户一个 LINE 账号，全收在一个面板里；
  • 课程 / 活动 / 社群运营：步骤配信 + 表单 + 直播 CTA 一条龙；
  • Affiliate 项目：案件管理 + last-touch 归因 + 重号反作弊 + LINE push 通知给推广者；
  • AI-native 客服：用 MCP 把 LINE 后台接到 Claude Code，让 AI 起草回复草稿 / 监控未回复；
  • 数据敏感业务：好友/行为数据在自己 Cloudflare D1，避免托管在第三方 SaaS。

坑与注意

  1. D1 免费档是硬性上限：日读写超限直接报错（README 自承），不会按超额扣费；流量稳定后建议升到付费 Workers Paid 计划；
  2. Cloudflare Pages + 自定义域名：默认 *.pages.dev 可用，但生产部署建议挂自己的域（HTTPS + 品牌一致）；
  3. LINE 官方账号投递费：LINE 本身按消息条数收费，与 L Harness 无关，但脚本里如果忘了 delay_minutes、短时间猛发会触发 LINE 限频；
  4. MCP / SDK 版本：CLI 自动装的版本与 README 描述版本可能漂移，发布到生产前用 pnpm why @line-harness/sdk 锁版本；
  5. 插件市场 β 状态：README 自标 β，每个插件要单独安装，不要假设「装一次就有」；
  6. Worker 冷启动：Cloudflare Workers 在低流量时会有冷启动延迟，对 webhook 接收瞬时敏感的场景要做 P99 测试；
  7. 品牌名变动：产品名 2026-08-19 改为「L Harness」，仓库名仍是 line-harness-oss。搜文档/提 issue 时要注意新旧称呼；
  8. README 自评 ≠ 第三方测评：竞品对比表来自仓库本身，没有独立审计；
  9. iOS 应用：README 提到 GET /api/capabilities 用于 iOS app the-harness-ios 兼容判断，但该 app 不在仓库内，需另行获取；
  10. 多账号 pool 是反封辅助而非保证：LINE 侧检测依旧最终决定是否封号，pool 只是帮你快速换号继续发。

与同类对比

  • L 社 / U 社付费 SaaS：上手快、月费 ≥1 万日元、API 受限、不开源、数据托管第三方；
  • 自建 + LINE SDK 直写：能完全定制，但要自己写好友存储、定时投递、限频回退、LIFF、MCP server 等；L Harness 就是把这部分提前做好；
  • Botpress / Rasa 等开源 chatbot 框架：偏 NLP 对话机器人，没有 LINE 官方账号 CRM 的好友/标签/广播/计费概念；
  • n8n / Make 做集成：可以作为 L Harness 的插件 partner（Webhook IN/OUT），但不能替代 CRM 本体。

一句话：想要「数据可控 + AI 友好 + 不付 SaaS 月费」的 LINE 运营，这是当前 GitHub 上最完整的一个开源起点；想要「5 分钟上线、不碰运维」，还是去用 L 社 / U 社。

一句话推荐结论

如果你或你的客户已经在认真做 LINE 私域，又不愿意把好友数据托管给闭源 SaaS、还希望把 AI 接进日常运营——L Harness 是 2026 年开源阵营里最值得先跑一遍 PoC 的选择；但生产上线前务必把 D1 上限、Cloudflare 计费、LINE 投递费三条账单线分别算清楚。

参考来源（fetch 验证）

  • 主仓库 README：https://github.com/Shudesu/line-harness-oss（2026-09-10 fetch）
  • 品牌迁移说明：BRAND.md（仓库根）
  • 官方产品页：https://the-harness.com/line-harness/
  • 官方定价页：https://the-harness.com/line-harness/pricing/
  • Cloudflare D1 计费：https://developers.cloudflare.com/d1/platform/pricing/
  • Claude 套餐/计费：https://claude.com/pricing
  • npm 包：@line-harness/sdk / @line-harness/mcp-server / create-line-harness（见 https://www.npmjs.com/）

⚠️ 本攻略基于公开 README 与官方页抓取所得版本（v0.21.0，2026-09-10），未跑通端到端部署。CLI 一键流程、MCP 字段、SDK 调用形态均以仓库自述为准，实际使用前请以最新 release tag、npm 页面与 packages/*/README.md 为准。