CodeFlowMu

CodeFlowMu 是一个基于 FCoP (File-based Coordination Protocol) 构建的 AI 驱动的协作工作流系统。它通过文件协议实现 AI 团队和人类之间的协作。

快速开始

前置条件

• Node.js v20+
• npm 7+
• Python 3.10+（可选，用于桌面应用）
• Cursor API Key（用于 Claude LLM 集成）

启动项目

cd d:\codeflowmu

# 1. 安装依赖（首次）
npm install

# 2. 配置环境变量
$env:CURSOR_API_KEY = "your-api-key-here"
$env:CURSOR_DEFAULT_MODEL = "claude-sonnet-4-6"

# 3. 启动项目
npm start

项目将启动 Web 面板（默认: http://127.0.0.1:18766）

项目结构

d:\codeflowmu/
├── codeflowmu-shell/          # Node.js 运行时（主应用）
├── codeflowmu-desktop/        # Python 桌面应用
├── packages/
│   ├── codeflowmu-protocol/   # FCoP 协议库
│   └── codeflowmu-runtime/    # 运行时库
├── fcop/                      # FCoP 协议配置和工作区
│   ├── fcop.json              # FCoP 配置
│   ├── tasks/                 # 📥 待处理任务
│   ├── reports/               # ✅ 完成报告
│   ├── reviews/               # 🔍 高风险任务审批单
│   ├── issues/                # 🔴 缺陷/问题
│   ├── log/                   # 📝 操作日志
│   └── shared/                # 📋 共享文档和角色定义
├── workspace/                 # 工作空间
├── .cursor/                   # Cursor IDE 配置
│   └── rules/                 # FCoP 规则文件
├── AGENTS.md                  # AI Agent 配置指南
└── CLAUDE.md                  # Claude 模型规则

FCoP 协议

CodeFlowMu 完全基于 FCoP v2.0.0 运行。所有工作必须遵循 FCoP 规则：

核心原则

1. 文件优先 - 所有通信通过文件进行（TASK-.md, REPORT-.md, ISSUE-*.md）
2. 异步执行 - AI 角色异步处理任务，无需实时响应
3. 完全可审计 - 每个决策都有文件记录，支持完整审查链条
4. 人类监督 - 高风险操作需人类批准
5. Rule 0.a.1 - 所有任务必须遵循 4 步循环：
   • 1️⃣ write_task() - 创建任务
   • 2️⃣ 执行工作 - 在 workspace/ 中完成
   • 3️⃣ write_report() - 提交报告
   • 4️⃣ archive_task() - 归档任务

AI 团队角色

角色	职责	权限
PM	项目规划、任务分配、决策	创建任务、分配任务、最终审批
DEV	代码开发、技术设计	执行开发、修改代码、提交审查
QA	功能测试、缺陷管理	执行测试、提交缺陷报告
OPS	基础设施、部署、运维	部署到测试、修改配置

文档

• fcop/LETTER-TO-ADMIN.md - FCoP 协议完整说明（必读）
• fcop/shared/TEAM-README.md - 团队结构和工作流
• fcop/shared/TEAM-ROLES.md - 每个角色的详细定义
• fcop/shared/TEAM-OPERATING-RULES.md - 运营规则和最佳实践
• AGENTS.md - AI Agent 配置和绑定方式
• .cursor/rules/fcop-rules.mdc - FCoP 核心规则（开发参考）

关键命令

启动和管理

# 启动项目
npm start

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

FCoP 工具（使用 fcop-mcp）

# 审计 FCoP 合规性
fcop_audit(scope="auto")

# 查看项目状态
fcop_report()

# 创建任务
write_task(sender="ADMIN", recipient="PM", title="...", description="...")

# 写报告
write_report(task_id="TASK-...", reporter="DEV", content="...")

# 查看任务
list_tasks()

# 查看报告
list_reports()

环境变量

变量	说明	必需
CURSOR_API_KEY	Claude API 密钥	✅ 是
CURSOR_DEFAULT_MODEL	默认 LLM 模型	⚠️ 可选（默认: claude-sonnet-4-6）
CODEFLOW_SKIP_FCOP_PROBE	跳过 FCoP 探测（开发模式）	⚠️ 可选
PYTHON_BIN	Python 可执行文件路径	⚠️ 可选（桌面应用）

Web 面板

启动后访问：http://127.0.0.1:18766

面板提供：

• 📊 项目状态仪表板
• 📝 任务管理界面
• 👥 AI 团队状态
• 📈 进度跟踪
• 🔍 操作日志

FCoP 高风险审批流程

CodeFlowMu 实现了 FCoP 的高风险任务审批机制：

何时需要人类审批

以下操作需要标记为 risk_level: high：

• 🔴 生产部署
• 🔴 数据库修改或删除
• 🔴 权限变更
• 🔴 重启生产服务
• 🟡 API 破坏性变更

审批流程

PM 派单（标注 risk_level: high）
        ↓
系统自动生成 REVIEW-*.md 在 fcop/reviews/
        ↓
执行角色停手，等待 ADMIN 审批
        ↓
ADMIN 调用 mark_human_approved(review_id=...)
        ↓
执行角色才能继续执行

关键规则

• 未批准不得执行 - 这是最高优先级规则
• 所有高风险操作都必须记录 - 供审计追溯
• 无回滚方案不得执行 - 必须提前准备回滚计划

---

创建第一个 FCoP 任务

1. 作为 ADMIN，创建任务：

   write_task(
     sender="ADMIN",
     recipient="PM",
     title="项目启动规划",
     description="制定项目初始规划和里程碑"
   )

   → 生成 TASK-PM-0001-*.md 在 fcop/tasks/

2. PM 执行任务：

   • 在 workspace/<task-slug>/ 中完成工作
   • 参考文档存放在 fcop/shared/ 中

3. 提交报告：

   write_report(
     task_id="TASK-PM-0001",
     reporter="PM",
     content="规划完成...",
     status="done"
   )

   → 生成 REPORT-PM-0001-*.md 在 fcop/reports/

4. 高风险操作审批（如需要）：

   • PM 标注 risk_level: high
   • 系统自动生成 REVIEW-*.md 在 fcop/reviews/
   • ADMIN 调用 mark_human_approved() 后，执行角色才能继续

5. ADMIN 审批与归档：

   • 审查报告
   • 调用 archive_task() 归档

故障排除

启动错误：PANEL_DIR_MISSING

确保所有目录都存在，包括 codeflowmu-desktop/panel。

FCoP 初始化失败

检查：

# 验证 FCoP 结构
fcop_audit(scope="auto")

# 查看项目状态
fcop_report()

常见问题：

• PYTHON_BIN 未设置 → 需要 Python 环境
• CURSOR_API_KEY 未设置 → 需要 Cursor API 密钥

编译错误

确保所有依赖已安装：

npm install
npm --prefix packages/codeflowmu-protocol install
npm --prefix packages/codeflowmu-runtime install

FCoP 审计失败

运行审计获取详细报告：

fcop_audit(scope="auto")

查看 fcop/shared/INSPECTION-*.md 报告并按照说明修复。

任务派发不工作

检查：

• ✅ fcop/fcop.json 存在且正确
• ✅ fcop/tasks/ 目录存在
• ✅ fcop/reports/ 目录存在
• ✅ fcop/reviews/ 目录存在（用于高风险任务）
• ✅ codeflowmu-shell 进程正在运行
• ✅ CURSOR_API_KEY 已设置

高风险审批卡住

如果任务卡在审批阶段：

• 使用 fcop_list_alerts() 查看是否有待批准的审批单
• ADMIN 调用 mark_human_approved(review_id=...) 继续
• 查看 fcop/reviews/ 中的 REVIEW-*.md 了解阻塞原因

协议版本

• FCoP: v2.0.0
• FCoP Rules: v3.0.0
• FCoP MCP: v2.0.0

许可证

查看 LICENSE 文件

相关资源

• FCoP 官方文档
• Cursor SDK
• Claude API

---

CodeFlowMu - 让 AI 和人类通过文件协议协作 🚀