Skip to content

README.md

Latest commit

 

History

History
298 lines (219 loc) · 7.52 KB

README.md

File metadata and controls

298 lines (219 loc) · 7.52 KB

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 文件

相关资源

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