FC-Consumer-Cursor

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

与 npm 包 fc-consumer-opencode（OpenCode 版，仓库 FC-Consumer-Opencode）共用 Stream / 消息协议 / EXECUTOR_AGENT 路由，可混部。

已有完整 Agent？ 见 INTEGRATE.md（推荐先读）。 已经在用 .cursor/rules/*.mdc？ 先看 RULES-INTEGRATION.md 选集成方案。

安装与启动

# 在已有 Agent 项目根目录
npm install fc-consumer-cursor@1
cp node_modules/fc-consumer-cursor/.env.example .env
# 编辑 .env：REDIS_URL、EXECUTOR_AGENT、FC_AGENT_GROUP、CURSOR_API_KEY

npx fc-consumer-cursor@1

或全局：

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

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

工作原理

fc:tasks:dev (Redis Stream)
  → fc-consumer-cursor（本包）
  → cursor-agent -p --force（cwd = 你的项目）
  → 读 AGENTS.md + .cursor/mcp.json
  → 最后一行 JSON → consumer 判成功/失败

cwd 规则：在哪个目录启动 consumer，就读哪里的 .env / AGENTS.md。不要把业务代码搬进本包仓库。

配置摘要

| 变量 | 说明 | |------|------| | REDIS_URL | 中控 Redis | | EXECUTOR_AGENT | 与名册 agent_key 一致 | | FC_AGENT_GROUP | 固定 agent-{EXECUTOR_AGENT} | | CURSOR_API_KEY | headless 必填 | | CURSOR_AGENT_BIN | Windows 建议绝对路径 | | RUN_WORKDIR | 默认 .（项目根） |

完整列表见 .env.example。

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

cursor-agent CLI 会同时加载 AGENTS.md 与 .cursor/rules/*.mdc 作为 system prompt，二者并存不冲突。 集成做法：AGENTS.md 只装 fc-consumer 协议层（4 条硬约束），业务规则保持在 .cursor/rules/*.mdc。

协议 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|partial",...} —— consumer 靠这一行判定成败
4. Windows PowerShell 命令前加 $OutputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8;

模板与详细说明：

• AGENTS.md.example · 协议层模板
• RULES-INTEGRATION.md · AGENTS.md 与 mdc 职责分离 + 验证清单 + 踩坑表

调度型 Agent 的 MCP

需在 .cursor/mcp.json 注册 fc_webhook（下划线）才能 fc_publish_task。执行型可省略。示例结构见 INTEGRATE.md。

编程 API

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

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

开发本仓库

npm install
npm run build
cp .env.example .env && cp AGENTS.md.example AGENTS.md
npm start          # 开发：tsx 直跑 src
npm run pack:check # 发布前检查 tarball 内容

License

MIT