FC-Consumer-Opencode

npm 包名：fc-consumer-opencode。Redis Streams 任务消费器：监听 FC-webhook 中控队列，在 headless 下调用 OpenCode CLI opencode run，执行你已有 OpenCode Agent 项目根目录里的 AGENTS.md。

与 npm 包 fc-consumer-cursor（Cursor 版）共用 Stream / 消息协议 / EXECUTOR_AGENT 路由，可混部。

已有完整 OpenCode Agent 项目？ 见 INTEGRATE.md（推荐先读）。 已有自己的 AGENTS.md 业务规则？ 见 AGENTS-INTEGRATION.md（协议层与业务层如何合并）。

安装与启动

# 在已有 OpenCode Agent 项目根目录（与 AGENTS.md、opencode.json 同目录）
npm install fc-consumer-opencode@1
cp node_modules/fc-consumer-opencode/.env.example .env
# 编辑 .env：REDIS_URL、EXECUTOR_AGENT、FC_AGENT_GROUP

npx fc-consumer-opencode@1

或全局：

npm install -g fc-consumer-opencode@1
cd /path/to/your-opencode-agent
npx fc-consumer-opencode@1

生产建议锁定版本：npx [email protected]。

工作原理

fc:tasks:dev (Redis Stream)
  → fc-consumer-opencode（本包）
  → opencode run（cwd = 你的 OpenCode 项目）
  → 自动读取 AGENTS.md + opencode.json
  → stdout 最后一行 JSON → consumer 判成功/失败

cwd 规则：在哪个目录启动 consumer，就在哪读 .env / AGENTS.md / opencode.json。不要把业务代码搬进本包仓库；consumer 只是挂在你项目上的「领任务进程」。

配置摘要

| 变量 | 说明 | |------|------| | REDIS_URL | 中控 Redis | | EXECUTOR_AGENT | 与名册 agent_key 一致 | | FC_AGENT_GROUP | 固定 agent-{EXECUTOR_AGENT} | | OPENCODE_BIN | 默认 opencode | | OPENCODE_MODEL | 可选，覆盖 opencode.json | | RUN_WORKDIR | 默认 .（OpenCode 项目根） |

完整列表见 .env.example。

AGENTS.md 要求（接入中控最少改动）

OpenCode 每次 opencode run 会把项目根目录 AGENTS.md 整篇作为系统指令注入（与你在 IDE 里跑 OpenCode 时一致）。

集成做法（与 Cursor 版不同，OpenCode 通常没有 .cursor/rules）：

• 保留你已有的业务规则（能力范围、lark-cli 工具表、Phase 2/3 步骤等）
• 在文件最前面合并本包提供的「fc-consumer-opencode 协议约束」（4 条硬约束）
• 不要用 AGENTS.md.example 整份覆盖你已有的 AGENTS.md

协议 4 条：

1. Phase 1：开头按格式打印任务元信息（task_id / title / approved_by / approved_at / doc_url / trace_id）
2. Phase 4：完成后给 approved_by 发飞书私聊（成功/失败 + 摘要）
3. 最后一行严格输出 JSON：{"task_id":"...","status":"succeeded|failed",...} —— consumer 靠这一行判定成败
4. 终端编码：bash 命令前 chcp 65001；PowerShell 用 $OutputEncoding = ... UTF8（见 AGENTS-INTEGRATION.md）

模板与合并步骤：

• AGENTS.md.example · 仅协议层（新建项目用）
• AGENTS-INTEGRATION.md · 与已有 AGENTS.md 合并 + headless 自检 + 踩坑表

模型与 Provider（opencode.json）

已有 OpenCode 项目通常已经有自己的 opencode.json，不要从本包复制覆盖；本节只针对新建项目。

consumer 自己不读 opencode.json，它只是把这个文件留给 opencode run 子进程用。生效优先级：

.env: OPENCODE_MODEL   >   项目根 opencode.json.model   >   ~/.config/opencode/opencode.json

按你的实际 LLM 接入方式，复制对应的 example 起步：

| 你怎么调 Claude | 复制哪份 | 还需要的环境变量 | |---|---|---| | Anthropic 官方 API | opencode.json.example | ANTHROPIC_API_KEY=sk-ant-... | | 中转 / 自建代理 / 三方网关 | opencode.json.proxy.example（填你自己的 api URL 与 models，按代理商发的 key 设对应 env） | 看代理商文档（如 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 等） | | 其它 provider（OpenAI、Bedrock、Gemini…） | 任选一份起步，按 OpenCode provider 文档 改 provider 段 | 看 provider 文档 |

⚠️ opencode.json 里不要写明文 token——按 OpenCode 约定走环境变量；本文件可以提交进 git，敏感凭据放 .env。

切模型不必改文件，改 .env 的 OPENCODE_MODEL 即可（覆盖 opencode.json 的默认值）。

调度型 Agent 的 MCP

执行型 Agent（只消费任务）无需配置 MCP。调度型 Agent（业务流程里要 fc_publish_task 派新任务）需在 opencode.json 的 mcp 中追加 fc_webhook，Token 由中控 admin 创建 UpstreamAgent 时下发，勿提交进 git：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4",
  "mcp": {
    "fc_webhook": {
      "type": "remote",
      "url": "http://<中控IP>:3071/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <UpstreamAgent token>"
      }
    }
  }
}

完整接入流程见 INTEGRATE.md §7。

编程 API

import { startConsumer } from 'fc-consumer-opencode';

const { stop } = await startConsumer({
  redisUrl: 'redis://127.0.0.1:6379',
  executorAgent: 'zhangsan-doc',
  group: 'agent-zhangsan-doc',
  workdir: '/path/to/your-opencode-agent',
});
stop();

开发本仓库

npm install
npm run build
cp .env.example .env && cp AGENTS.md.example AGENTS.md
npm start
npm run pack:check

发布维护（仓库维护者）

npm run typecheck
npm run pack:check
npm publish

License

MIT