Skip to content

OPERATION-MANUAL.md

Latest commit

 

History

History
2500 lines (1887 loc) · 135 KB

OPERATION-MANUAL.md

File metadata and controls

2500 lines (1887 loc) · 135 KB

CodeFlowMu 操作手册

版本：v0.4.4-alpha · FCoP Protocol v3 · 更新：2026-06-16 2026-06-16 增补：Mobile PWA 一键发布 Gateway、private/gateway-ops-guide.md 私有 SSH 运维指南（取代旧 Bridgeflow 中继文档路径）。 2026-06-15 增补：FCoP-PENDING-0003 任务关系、证据归属、任务 Tree 与子任务归档控制。 2026-06-09 增补：双轨目录（FCoP-PENDING-0002）、ledger 真相源层级、force_archive_task、Panel 物理路径/三态 Tab/报告分组；详见 panel-task-lifecycle-ui-rules.zh.md。

变更摘要（2026-06-16 · Mobile Gateway 发布）

能力 手册章节 主要 delta
Gateway SSH 私有指南 §2.3、§11.11 private/gateway-ops-guide.md（gitignore）；模板 docs/gateway-ops-guide.example.md；不再使用 D:\Bridgeflow\private\relay-keepalive-guide.md
Panel 一键发布 PWA §11.11 设置 → 项目：版本对比 +「发布到 Gateway」→ POST /api/v2/mobile/panel/publish-gateway
发布脚本凭据 §11.11 codeflowmu-gateway/scripts/gateway_ops_credentials.py 统一读密码；环境变量 CODEFLOWMU_GATEWAY_OPS_GUIDE 可覆盖路径

变更摘要（2026-06-15 · PM 执行治理）

能力 手册章节 主要 delta
PM 顺序推进 §16.4.1 DEV → OPS → QA 按当前腿推进；前一腿未完成时返回 sequential_dispatch_guarded
PM 限流停手 §16.4.2 wake_throttled / SDK cooldown 后执行 PM_STOP，不连续 wake / recover
ADMIN force recovery §16.4.3 stale busy、session 异常或 running + inbox 状态升级 ADMIN 一键解除卡死
实时操作输出 §16.4.4 Panel 与 panel-actions-YYYYMMDD.jsonl 显示停手原因、冷却时间、恢复前后状态及原链恢复

变更摘要（2026-06-13 · TASK-20260612-106）

代码模块 手册章节 主要 delta
packages/codeflowmu-runtime/src/ledger/scheduleLedgerRebuild.ts §5.3.1 lifecycle / dispatch 后 debounced 全量 rebuild，保持 fcop/ledger/views/*.todo.md 与 tasks.jsonl 同步
packages/codeflowmu-runtime/src/scheduler/LifecycleGovernor.ts §5.2 / §5.3.1 inbox↔active 治理后触发 ledger rebuild（非仅条件式 ensureFresh）
codeflowmu-shell/src/lifecycle-runtime-bridge.ts §5.2 / §6 lifecycle syscall 成功后 reconcileLedgerAfterJoin（J1 并轨）
packages/codeflowmu-runtime/src/pm/agentTaskQueue.ts §8 / §11.3 每 Agent FIFO 队列 + 暂停态；持久化 .codeflowmu/pm-governance/agent-task-queue.json；API GET /api/v2/agent-queue
codeflowmu-shell/src/review-attention.ts §11.3 / §11.4 从 cycle.jsonl 的 pm.review_check 失败索引 review_attention，任务列表/详情黄条展示
packages/codeflowmu-runtime/src/registry/GoogleGenAiAdapter.ts §15 Gemini Function Calling ↔ MCP stdio 归一化、tool dedupe、结果回灌（Google 工具运行时）
codeflowmu-desktop/panel/index.html §11.3 / §11.15 任务详情：状态区可折叠 + 左边框拖拽调宽；团队配置：5 Agent（含 EVAL-01）、技能市场移至 Agent 成员之后
.codeflowmu/pm-skills.manifest.json §10.1 PM runtime skills：pm.summarize_thread、pm.detect_thread_stall、pm.close_admin_task、pm.wake_downstream、pm.review_check
.codeflowmu/agent-skills.manifest.json §10.1 Playbook 索引层扩展（browser-playwright-check、run-local-command-check、code-search-navigation 等 stub）

扫描命令（只读）：在仓库根目录用 rg / IDE 搜索上述路径；Panel 侧 tdp-alerts-fold、TC_AGENTS（含 EVAL-01）、data-fcop-chain-test="101" 见 codeflowmu-desktop/panel/index.html。

目录

  1. 系统概览
  2. 环境准备
  3. 启动与停止
  4. 配置参考
  5. FCoP v3 Lifecycle 工作流
  6. fcop_mcp 工具速查
  7. 派发任务给 Agent
  8. 监控与审计
  9. 常见问题
  10. 架构速览
  11. Web Panel UI 详解
  12. 自动化测试状态
  13. Agent 自记录日志体系
  14. FCoP 工具权限分层（防 Token 爆炸）
  15. Google Gen AI SDK 通道
  16. adopted/pending、生命周期权责与日常操作速查
  17. 干净初始化（从空现场验证）

Panel 生命周期 UI 细则（摘要）：docs/panel-task-lifecycle-ui-rules.zh.md（与 §11.3 / §11.4 交叉引用，冲突时以 adopted/pending 为准）。

1. 系统概览

CodeFlowMu 是一个基于文件的多 Agent 协作运行时，以 FCoP v3 协议作为协调层， 通过 Cursor SDK 驱动 AI 角色（PM / DEV / QA / OPS）。

协议定位：CodeFlowMu 是 FCoP 的标准示范体——不是「用了 FCoP 的普通应用」， 而是把 Rule 0–9、v3 lifecycle、task → execute/delegate → report → review → done → archive、角色三层文档 完整跑在自身仓库里的 reference implementation。磁盘即协议：生命周期投递在 fcop/_lifecycle/inbox/，IPC 工作面与账本在 fcop/tasks/、fcop/reports/、fcop/ledger/（FCoP-PENDING-0002）， 封存过渡在 fcop/_lifecycle/archive/，产物在 workspace/<slug>/。其他团队可直接 fork 本仓库对照学习。

项目根目录（重要）

区分两层路径：

层 含义 典型路径
CodeFlowMu 工作区 跑 npm start 的 monorepo（含 codeflowmu-shell/、Panel 静态页） 本仓库 D:\codeflowmu
产品开发根 实际做 FCoP 协作的磁盘目录（任务/报告/环境预检均相对此根） 如 D:\xiangqi、D:\weiqi，可与仓库不在同一盘

每个产品开发根各自维护 fcop/（含 fcop.json、_lifecycle/ 等）。列表保存在 %USERPROFILE%\.codeflowmu\v2\projects-registry.json。

项 说明
默认产品开发根 首次启动常为本仓库根（若含 fcop/fcop.json）
FCoP 协作数据 相对当前选中的产品开发根：fcop/_lifecycle/、fcop/reports/ 等
团队配置 各产品开发根下的 codeflowmu.team.json（若有）

Web Panel 设置 → 项目 可登记多个产品开发根、切换当前项；GET /api/v2/health 的 projectRoot 随切换变化。

添加项目 · 本机选路径： 在「添加产品开发根」对话框中，根目录旁有 「浏览…」，由 Shell 在本机弹出系统文件夹选择器（Windows / macOS / Linux+zenity）。须在本机运行 npm start（远程或无图形环境只能手输路径）。选好后可自动用文件夹名填充「项目名称」。

若 projectRoot 仍不对：在 设置 → 项目 切换或添加正确路径，并确认只开一个 Shell（端口 18766）。

两种运行模式

模式 启动命令 访问方式 适用场景
Web Panel 模式（默认） npm start 浏览器 http://localhost:18766 日常操作，图形界面管理
Daemon 无界面模式 npm run daemon 终端 + 文件系统 服务器部署，自动化流水线

推荐新手使用 Web Panel 模式。Web Panel 提供完整的图形操作界面，包含仪表盘、 聊天、任务管理、报告查看、审批、团队配置等 16 个功能页面（详见第 11 章）。

核心数据流：

ADMIN（你）
  │
  ▼  写 TASK 文件到 fcop/_lifecycle/inbox/
  InboxWatcher (codeflowmu-shell)
  │
  ▼  检测到新文件 → 触发
  TaskDispatcher
  │
  ▼  调用 Cursor SDK 创建 Agent Session，注入角色上下文 + fcop_mcp 工具 + adopted/pending 条款
  Agent (PM / DEV / QA / OPS)
  │
  ▼  执行 → write_report → submit_review（active → review）
  ▼  上级 approve_review → done；archive_authority 执行 archive（frozen: true）
  ReportWatcher / LifecycleGovernor 同步 YAML transitions

权责要点（CodeFlowMu 默认，详见 §5.2 与 FCoP-PENDING-0001）：

  • review：有 REPORT 后进入待验收，执行者不得自行 done
  • done：仅 done_authority（主线默认 ADMIN；低风险可 YAML 授权 PM 的 delegated_done: true）
  • archive：须从 done、由 archive_authority 执行，封存后 frozen: true，不可打回
  • 聊天唤醒：绑定原 task_id，不创建 TASK、不移动 lifecycle（见 §11.2）

特点：

  • Web Panel 或 Daemon 均可驱动；45 个 fcop_mcp 工具通过 stdio 注入每个 Agent 会话
  • 任务状态靠文件系统 + TASK YAML transitions 双重跟踪
  • 运行时自动加载 fcop/adopted/pending/ 中 runtime_effective: true 的条款（已采用 · 运行时生效 · 待 ADMIN 决定是否并入正式版；正式 FCoP 仍为 3.2.5）

2. 环境准备

2.1 必要条件

组件 要求 备注
Node.js ≥ 22 —
Python ≥ 3.10 供 fcop_mcp 使用
fcop_mcp pip install fcop-mcp（建议 ≥ 3.2.2） 与 fcop 同版本
Cursor API Key 在 cursor.com 获取 使用 cursor 通道时必填
Gemini API Key 在 aistudio.google.com 获取 使用 google 通道时必填
@google/genai 自动随 npm run install:all 安装 使用 google 通道时必须存在

注意（Google 通道）： @google/genai npm 包是 Google 通道的关键依赖。若遗漏安装， 所有 Agent 启动时会报错并显示「异常」状态。详见 §15.5 Agent 显示「异常」排障。

2.2 首次安装依赖

# 在项目根目录执行（同时安装所有子包依赖，包含 @google/genai）
cd D:\codeflowmu
npm run install:all

若需单独为 codeflowmu-runtime 安装 Google SDK（如包遗漏时的修复方案）：

npm install --prefix packages/codeflowmu-runtime @google/genai@latest

2.3 配置 .env（单一配置真相源）

项目根目录的 .env 文件是整个系统的单一配置真相源。子目录 codeflowmu-shell/.env 已完全合并，请在项目根目录的 .env 中进行以下配置：

# ────────────────────────── 双通道接入切换 ──────────────────────
# 提供者选项：
#   - cursor : 使用 Cursor SDK 驱动（默认）
#   - google : 使用全新 Google Gen AI SDK (Gemini API) 驱动
CODEFLOW_PROVIDER=cursor

# 必填：Cursor API Key (使用 cursor 提供者时必填)
CURSOR_API_KEY=crsr_xxxxxxxxxxxxxxxxxxxxx

# 必填：Gemini API Key (使用 google 提供者时必填)
GEMINI_API_KEY=AIzaSyREPLACE_WITH_YOUR_GEMINI_KEY
GOOGLE_DEFAULT_MODEL=gemini-2.5-flash

# ────────────────────────── 其它可选配置 ─────────────────────────
# 可选：默认模型（推荐 auto，由 Cursor Agent Router 自动匹配）
# 也可在 codeflowmu.team.json 各成员的 model.id 中配置
CURSOR_DEFAULT_MODEL=auto

# 可选：跳过 fcop Python 探测（环境变量缺失时可加速启动）
CODEFLOW_SKIP_FCOP_PROBE=1

# 可选：Python 解释器路径（fcop_mcp / Gateway 发布脚本使用；强烈建议配置）
PYTHON_BIN=D:\codeflowmu\.venv\Scripts\python.exe

# 可选：Gateway SSH 运维指南路径（默认 {仓库根}/private/gateway-ops-guide.md，见 §11.11.1）
# CODEFLOWMU_GATEWAY_OPS_GUIDE=D:\codeflowmu\private\gateway-ops-guide.md

# 可选：自动轮换以降低 Token 累积（防 Token 爆炸）
CODEFLOW_AGENT_AUTO_RECYCLE=1
CODEFLOW_AGENT_RECYCLE_THRESHOLD=10

Gateway PWA 发布（SSH）：Panel「发布到 Gateway」与 sync_mobile_static.py 从 private/gateway-ops-guide.md 解析 密码： 行。首次使用请从 docs/gateway-ops-guide.example.md 复制到 private/ 并填写；勿再使用旧路径 D:\Bridgeflow\private\relay-keepalive-guide.md。详见 §11.11。

2.4 FCoP Python 包版本演进（参考）

CodeFlowMu 示范体要求本机 fcop / fcop-mcp ≥ 3.2.2（两包 lockstep 同版本）。 GET /api/v2/health 的 fcop / fcopMcp 字段即 Python 包版本；与 CodeFlowMu Shell 的 shellVersion（如 0.3.0-alpha）是两套独立版本号，不可混读。

版本 一句话
3.2.2 v3.2.2 — 深度历史归档 + 10 个新 MCP 工具（35 → 45）。新增 history/YYYY-MM-DD/ 日期分片长期归档层；新工具：create_task、archive_to_history、bulk_archive_to_history、list_history、get_history_stats、search_history、move_to_history、cleanup_history、export_history、import_from_history。支持手动/定时把已完成任务-报告对移入 history/。fcop 与 fcop-mcp 双包 lockstep 对齐至 3.2.2。
3.0.2 v3.0.2 — 初始化拓扑修复。3.0.0 / 3.0.1 的 Project._apply_init 只创建了 v2 老桶，跳过 spec §1.1 强制的 v3 _lifecycle/{inbox,active,review,done,archive}/ 五桶；3.0.2 让 fresh init 直接落 v3 拓扑（不再创建被 superseded 的 v2 tasks/ / log/）。scan_workspace 与 role_occupancy() 在 v3 项目下从 _lifecycle/ 读取。新增 audit _scan_lifecycle_topology_compliance()（D9）：P0 = 已初始化但缺 _lifecycle/ 且无 v2 内容；P1 = 两套拓扑共存（建议 migrate --to-v3）。SemVer patch，无 API 表面改动。
3.0.1 v3.0.1 — 路径整合补丁。纯文档/元数据：修正散落链接，统一指向 spec/archived/fcop-runtime-protocol-v1.0.{md,zh.md} 与 canonical spec/fcop-3.0-spec.md；fcop-mcp 的 fcop://spec docstring 与 wheel 打包内容对齐。历史制品按 ADR-0036「历史不重写」保留原文。
3.0.0 v3.0.0 — 协议级 MAJOR ·「文件夹即状态」纪元。完整重写：Layer 1「文件即协议；位置定义状态；事件记录历史」+ Layer 2 语义本体。新增 _lifecycle/{inbox,active,review,done,archive}/ 五桶（与 2.x 不兼容，须 fcop migrate --to-v3）；三层规则集；7 条允许迁移表外不可；write-then-rename 原子性。新增 spec/fcop-3.0-spec.md 与 docs/MIGRATION-3.0.md。

本仓库 fcop/fcop.json 为 protocol_version: 3。若从 纯 FCoP 2.x 升级而来，须先 python -m fcop migrate --to-v3，并删除 v2 单数归档桶 fcop/log/（以及旧 v2 扁平 fcop/tasks/ 若仍作为 inbox 投递桶使用）。 注意区分：CodeFlowMu 在 0002 双轨下 fcop/tasks/ 为合法必需 IPC 工作面（存放已认领 TASK 副本等）， 不是 v2 拓扑残留；环境预检标红的是 legacyV2OnlyDirs（当前仅 log/） 与 layoutRisks，而非 0002 工作目录。 完整 CHANGELOG 见上游 fcop 包内 CHANGELOG.md。

3. 启动与停止

3.1 启动方式

# ─────────────────────────────────────────────────────────────────
# ★ 方式一：带 Web Panel 启动（推荐，图形界面）
# 启动后浏览器访问 http://localhost:18766
# ─────────────────────────────────────────────────────────────────
npm start

# ─────────────────────────────────────────────────────────────────
# 方式二：无 UI 守护进程（适合服务器 / CI 环境）
# ─────────────────────────────────────────────────────────────────
npm run daemon

# 方式三：同 daemon，别名命令
npm run start:no-ui

Web Panel 地址： http://localhost:18766（以 codeflowmu.team.json 的 panel_port 为准）

勿再使用 18765。 若同时存在两个 Shell 实例，环境预检可能显示旧端口或错误项目根（如 D:\Bridgeflow）。 只保留 18766 上的实例；停掉占用 18765 的旧进程后，用浏览器打开上表地址。

也可直接设置环境变量禁用界面：

$env:CODEFLOW_NO_PANEL="1"; npm start

3.2 Web Panel 快速访问

npm start 成功后，打开浏览器访问：

http://localhost:18766

如果 codeflowmu-desktop 已作为独立客户端安装，也可通过桌面程序自动连接面板（同一端口）。

3.2 确认启动成功

启动后终端输出类似：

╔══════════════════════════════════════════════════════╗
║      CodeFlowMu Shell v0.3.0-alpha                  ║
╠══════════════════════════════════════════════════════╣
║  API key      : crsr_d8...e9 (42 chars)             ║
║  Model        : auto                                  ║
║  FCoP inbox   : D:\codeflowmu\fcop\_lifecycle\inbox ║
║  Web panel    : disabled (--no-panel)               ║
╚══════════════════════════════════════════════════════╝
[InboxWatcher] watching D:\codeflowmu\fcop\_lifecycle\inbox

3.3 停止

# 前台进程：Ctrl+C
# 后台进程：找到 PID 后 kill

3.4 干净初始化（快捷入口）

从空现场验证「删运行数据 → 启动 → 自动重建 → 跑通真实任务链」时，使用根目录启动脚本或 npm start，并按 §17 干净初始化 与独立文档 CODEFLOWMU_CLEAN_INIT_RUNBOOK.md 操作。

必删运行现场： fcop/、.fcop/、.codeflowmu/。禁止删除： adoptedSource/（fcop/adopted/ 唯一源）、源码与 .env / node_modules / .venv 等。

4. 配置参考

4.1 配置优先级（后者覆盖前者）

1. 内置默认值
2. ~/.codeflowmu/v2/config.json   （用户级持久配置）
3. ./codeflowmu.config.json        （项目级配置）
4. ~/.codeflowmu/v2/.env           （用户级 .env）
5. ./.env                          （项目级 .env，当前目录）
6. process.env                     （系统环境变量）
7. CLI 参数                        （最高优先级）

4.2 环境变量白名单

变量 说明
CODEFLOW_PROVIDER API 接入通道类型：cursor (默认) 或 google（Gemini 通道）
GEMINI_API_KEY Google Gen AI SDK API 密匙（Gemini 必备密钥）
GOOGLE_DEFAULT_MODEL Google SDK 默认调用的 Gemini 模型 ID（如 gemini-2.5-flash、gemini-2.5-pro）
CURSOR_API_KEY Cursor API 密钥（Cursor 必备密钥）
CURSOR_DEFAULT_MODEL 默认模型（推荐 auto；也可指定具体模型 ID）
CURSOR_LIST_SCOPE local 或 cloud（默认 local）
PYTHON_BIN Python 解释器路径（供 fcop_mcp 使用，强烈建议配置）
CODEFLOW_NO_PANEL 1 禁用 Web Panel
CODEFLOW_SKIP_FCOP_PROBE 1 跳过 Python/fcop 探测
CODEFLOW_DATA_DIR 数据目录（默认 ~/.codeflowmu/v2）
CODEFLOW_RELAY_URL Relay 服务 URL（可选，遗留配置项）
CODEFLOW_ROOM_KEY Relay 房间密钥（可选，遗留配置项）
CODEFLOWMU_GATEWAY_OPS_GUIDE 覆盖 Gateway SSH 运维指南路径（默认 {仓库根}/private/gateway-ops-guide.md）

4.3 CLI 参数

npx tsx src/main.ts \
  --api-key crsr_xxx \   # Cursor API Key
  --no-panel             # 禁用 Web Panel

4.4 项目配置文件 codeflowmu.config.json（可选）

{
  "cursor": {
    "apiKey": "crsr_xxx",
    "defaultModel": "auto",
    "listScope": "local"
  },
  "relay": {
    "url": "wss://relay.example.com",
    "roomKey": "myroom",
    "autoConnect": false
  }
}

5. FCoP v3 Lifecycle 工作流

5.1 目录结构

fcop/
├── fcop.json                    # 项目配置（protocol_version: 3）
├── adopted/
│   └── pending/                 # 已采用 · 运行时生效 · 待 ADMIN 决定是否并入正式版（0001/0002/0003…）
├── _lifecycle/                  # ★ v3 生命周期（位置 = 状态）
│   ├── inbox/                   # 新任务投递（InboxWatcher 监控）
│   ├── active/                  # 执行中（含 waiting_pm_attention 待 PM 处理的任务）
│   ├── review/                  # 已 submit_review，待 approve
│   ├── done/                    # approve_review 通过，待 archive
│   └── archive/                 # archive_task / force_archive_task 封存
├── tasks/                       # ★ 0002 IPC 工作面（TASK 副本，非 v2 残留）
├── reports/                     # ★ 0002 IPC 工作面（REPORT 副本）
├── issues/                      # ISSUE 工作面
├── ledger/                      # ★ jsonl 投影（Panel Kanban 的 ledger_scope 主来源）
│   └── views/                   # ADMIN/PM/DEV… 收件视图
├── attachments/                 # 附件元数据（可选）
├── shared/                      # 团队共享文档（TEAM-ROLES.md 等）
├── internal/
│   └── eval/                    # EVAL 观察输出 OBSERVATION-*.md（非团队 REPORT）
├── history/
│   └── YYYY-MM-DD/
│       └── TASK-stem/           # 深度历史归档（TASK + REPORT 配对）
└── alerts/                      # GAL 告警（可选）

双轨与真相源（FCoP-PENDING-0002）

轨道 目录 用途
生命周期轨 _lifecycle/{inbox…archive}/ 物理位置即状态；Runtime / MCP 生命周期工具移动
IPC + 账本轨 tasks/、reports/、ledger/ 工作副本与 jsonl；API ledger_scope 来自 ledger/tasks.jsonl 的 bucket

真相源优先级：_lifecycle/ 物理 stage > YAML state/transitions > fcop/tasks/ IPC > ledger/*.jsonl > Panel 缓存。
v2 遗留仅指：单数归档桶 fcop/log/（legacyV2OnlyDirs），不是 0002 的 fcop/tasks/。

5.2 任务完整生命周期

CodeFlowMu 默认热路径（review → done → archive）

ADMIN / PM 写 TASK → fcop/_lifecycle/inbox/
  ↓ InboxWatcher → TaskDispatcher（注入 TASK + adopted/pending + 角色文档）
  ↓ LifecycleGovernor 异步 inbox → active（本地 rename，非开工前同步 claim_task）
Agent 执行:
  1. 阅读已注入的 TASK 正文
  2. 执行工作
  3. write_report → fcop/reports/REPORT-*.md
  4. submit_review → active → review（须同步 YAML transitions）
上级验收（done_authority）:
  approve_review → review → done
  reject_review  → review → active（返工）
  reopen_task    → done → active（授权上级重开）
封存（archive_authority）:
  archive_task → done → archive（须已在 done 且 frozen）
  force_archive_task → inbox/active/review → archive（须 archive_reason；ADMIN 对主线可强行作废）
  archive_to_history → archive → fcop/history/YYYY-MM-DD/

pending_pm_review ≠ 物理 review/：fact_check / waiting_pm_attention 语义下，任务可能仍在 active/ 等待 PM；LedgerBuilder 不得仅因 thread 队列将其 Kanban 投影为 review。

两种归档

工具 前置目录 说明
archive_task done/ 正常封存；frozen: true
force_archive_task inbox / active / review 须 archive_reason；操作者视角下 ADMIN 对主线可强制作废

主线 ADMIN→PM 与支线 PM→Agent

类型 执行者 REPORT 给谁 默认 done 默认 archive 低风险例外
主线 ADMIN-to-PM PM ADMIN ADMIN ADMIN TASK 含 delegated_done: true 时 PM 可 done，仍不自动获得 archive
支线 PM-to-DEV/QA/OPS Agent PM PM PM —

禁止： 执行者在无 REPORT 或未 submit_review 时自行把任务推进到 done；正常 archive 前未 done；archive 后再打回（force_archive_task 除外，须原因且 workflow sealed）。

Runtime 与 MCP 分工

  • CodeFlowMu Runtime：LifecycleGovernor 在收到 REPORT 后异步 active→review；校验 done_authority / archive_authority
  • MCP 工具：submit_review / approve_review / reject_review / reopen_task 为推荐路径
  • finish_task：易误导（跳过 review/done 权责），仅作 legacy 兼容；新流程勿以之为默认

纯 MCP 手工治理（调试 / 无 Runtime 时）

claim_task → active → write_report → submit_review → approve_review → archive_task

claim_task 须异步、带超时；不得在 Agent 开工前同步阻塞调用。

5.3 adopted/pending 运行时补充条款（已采用 · 运行时生效 · 待 ADMIN 决定是否并入正式版）

正式 FCoP 包版本仍为 3.2.5。fcop/adopted/pending/ 存放 已采用 · 运行时生效 · 待 ADMIN 决定是否并入正式版 的补充条款：CodeFlowMu 运行时须遵守；是否并入正式 FCoP 版本（计划字段如 target_version: 3.2.6）由 ADMIN 决定。

项 说明
目录 fcop/adopted/pending/
0001 0001-lifecycle-authority-review-done-archive.md（FCoP-PENDING-0001）— review/done/archive 权责
0002 0002-fixed-work-folders-and-ledger.md（FCoP-PENDING-0002）— 双轨目录 + ledger 真相源层级
0003 0003-task-relations-and-evidence-ownership.md（FCoP-PENDING-0003）— parent 强关系、references 弱关系、证据归属与 Tree
生效条件 frontmatter runtime_effective: true（仅 CodeFlowMu 运行时）
加载方 Agent 会话 Primer、PM 角色文档、Runtime 治理校验、LedgerBuilder
0001 实现 docs/CODEFLOWMU_LIFECYCLE_AUTHORITY_IMPLEMENTATION.md
Panel UI 细则 docs/panel-task-lifecycle-ui-rules.zh.md

Agent 与 PM 必须遵守上述 pending 条款，即使尚未写入 bundled .cursor/rules/fcop-rules.mdc。不得将 pending 当作已发布的正式 FCoP 3.2.6 规则。

5.3.1 Ledger 视图自动刷新（2026-06-12+）

写入 TASK/REPORT、lifecycle 迁移（LifecycleGovernor inbox↔active）、Panel lifecycle syscall（lifecycle-runtime-bridge → reconcileLedgerAfterJoin）后，Runtime 通过 scheduleLedgerRebuild(projectRoot)（400ms debounce，始终 full rebuild()）刷新 fcop/ledger/tasks.jsonl 与 fcop/ledger/views/{PM,DEV,OPS,QA}.todo.md。

路径 触发
packages/codeflowmu-runtime/src/ledger/scheduleLedgerRebuild.ts debounced rebuild 入口
LifecycleGovernor dispatch / inbox 恢复后 scheduleLedgerRebuild
lifecycle_cli.ts kernel 成功后 flushScheduledLedgerRebuild
Panel finalizeTaskCreateAfterDiskWrite / reconcileLedgerAfterJoin 写 TASK 或 join 后强制 rebuild
Python fcop_invoke_once _ledger_rebuild MCP write_task / write_report 热路径

Stale 检测：LedgerBuilder.detectViewsStale() 比对 jsonl 与 todo view；MCP-PROBE 自举任务由 probeBootstrapTask.ts 从角色 todo 视图剔除（Panel 列表同步过滤）。

5.4 文件命名规范

类型 格式
TASK TASK-YYYYMMDD-NNN-SENDER-to-RECIPIENT.md
REPORT REPORT-YYYYMMDD-NNN-REPORTER-to-RECIPIENT.md
REVIEW REVIEW-YYYYMMDD-NNN-REVIEWER.md
ISSUE ISSUE-YYYYMMDD-NNN-summary.md
ALERT ALERT-YYYYMMDD-NNN-signal.md（在 fcop/alerts/）

5.5 TASK 文件格式

---
protocol: fcop
version: 1
kind: task
task_id: TASK-20260523-001
sender: PM
recipient: DEV
subject: 实现用户登录功能
priority: P1
thread_key: auth-sprint-1
---

# 任务标题

## 背景
...

## 要求
...

## 验收标准
...

6. fcop_mcp 工具速查

Agent 会话中已注入 45 个 fcop_mcp 工具，最常用的如下：

6.1 生命周期工具

注意： submit_review / approve_review / reject_review / reopen_task 属于 CodeFlowMu adopted/pending 生命周期能力（见 FCoP-PENDING-0001）。若当前 fcop-mcp 3.2.5 尚未提供同名工具，CodeFlowMu Runtime 通过 codeflowmu-shell/src/fcop-lifecycle-tool-aliases.ts 映射到 submit_task / approve_task / reject_task；reopen_task 仍由 Runtime 治理层实现。finish_task 为 legacy 兼容，不推荐作为默认热路径。

工具 作用 示例
create_task 创建 TASK 并写入 inbox —
claim_task inbox → active（可选；热路径由 Runtime 异步 rename） claim_task(task_id="TASK-20260523-001")
write_report 写 REPORT 文件（完成信号，不改变 lifecycle） —
submit_review active → review（执行者提交验收） submit_review(task_id="…")
approve_review review → done（done_authority） approve_review(task_id="…")
reject_review review → active（打回返工） reject_review(task_id="…")
reopen_task done → active（授权上级重开） reopen_task(task_id="…")
archive_task done → archive（archive_authority，frozen: true） archive_task(task_id="…")
force_archive_task inbox/active/review → archive（须 archive_reason；治理层校验操作者） force_archive_task(task_id="…", archive_reason="…")
archive_to_history archive → history/YYYY-MM-DD/ archive_to_history(task_id="…")
finish_task legacy：易跳过 review/done 权责 不推荐作为默认热路径

每次状态变化应同步写入 TASK YAML 的 transitions 数组（见 FCoP-PENDING-0001 §7）。

6.1.1 深度历史归档（3.2.2+）

工具 作用
bulk_archive_to_history 批量：_lifecycle/archive/ → history/ 日期分片
list_history / read_history_task 按日期索引与读取
get_history_stats / search_history 统计与搜索
move_to_history / cleanup_history 移入与清理
export_history / import_from_history 导出 / 导入

6.2 内容工具

工具 作用
write_task 创建新 TASK（投到 inbox）
write_report 创建 REPORT（回执）
write_review 创建 REVIEW（审核记录）
write_issue 创建 ISSUE（问题单）
read_task 读取 TASK 内容
list_tasks 按收件人过滤任务列表
list_reports 查询已有报告

6.3 诊断工具

工具 作用
fcop_report UNBOUND 汇报 / 项目状态总览
fcop_check 验证工作区合规性
fcop_audit 协议体检，生成 INSPECTION 报告
set_project_dir 手动设置项目根目录（工具找不到项目时用）
fcop_list_alerts 查看 GAL 治理告警
fcop_create_alert 手动创建治理告警
mark_human_approved 批准 needs_human 的 REVIEW

7. 派发任务给 Agent

7.1 通过 Cursor MCP 工具（推荐）

在 Cursor IDE 的 MCP 面板或 Chat 中调用 write_task：

write_task(
  sender="PM",
  recipient="DEV",
  subject="实现数据导出功能",
  body="## 要求\n- 支持 CSV 格式\n- 支持时间范围过滤\n\n## 验收标准\n- 导出 1000 行以内 2 秒完成",
  priority="P1",
  thread_key="export-feature"
)

文件会自动落到 fcop/_lifecycle/inbox/，InboxWatcher 检测到后立即触发。

7.2 直接写文件（手动方式）

在 fcop/_lifecycle/inbox/ 下新建 TASK 文件，InboxWatcher 会自动响应。

文件名格式：TASK-20260523-002-ADMIN-to-DEV.md

7.3 查看执行情况

# 查看活跃任务
ls D:\codeflowmu\fcop\_lifecycle\active\

# 查看已完成任务
ls D:\codeflowmu\fcop\_lifecycle\done\

# 查看报告
ls D:\codeflowmu\fcop\reports\

# 查看历史归档
ls D:\codeflowmu\fcop\history\

8. 监控与审计

8.1 项目状态总览

通过 MCP 工具调用：

fcop_report()

输出包括：当前角色占用、活跃线程、未完成任务数量、协议版本等。

8.2 协议体检

fcop_audit(scope="auto")

生成 INSPECTION 报告到 fcop/shared/INSPECTION-YYYYMMDD-NNN-auto.md， 包含 P0（阻塞）/ P1（规范）/ P2（整洁）三级 violation 报告。

8.3 工作区合规检查

fcop_check()

交叉验证 git diff 与 FCoP 账本，列出未关联到任务的文件变更。

8.4 治理告警

fcop_list_alerts()

查看 GAL（Governance Alert Layer）告警：

  • S1: CRITICAL 工具调用 24h 内无对应 REVIEW
  • S3: 执行窗口 > 6h 无独立治理事件
  • S4: 任务超 24h 未归档

9. 常见问题

Q1: 启动后 Agent 没有响应任务

检查步骤：

  1. 确认 CURSOR_API_KEY（Cursor 通道）或 GEMINI_API_KEY（Google 通道）已在 .env 正确填写
  2. 确认 新派单 TASK 是否投递到 fcop/_lifecycle/inbox/（不是 把 inbox 任务误写到别处；**0002 下 fcop/tasks/ 是已认领后的 IPC 工作面，不是投递桶）
  3. 查看终端是否有 [InboxWatcher] watching ... 输出
  4. 检查 TASK 文件的 YAML frontmatter 是否包含所有必填字段
  5. 确认 Panel → Team 页面 Agent 状态为「空闲」而非「异常」（见 Q7）

Q2: Agent 报告 "project not found"

Agent 调用 fcop_mcp 时找不到项目，需要先调用：

set_project_dir(path="D:\\codeflowmu")

Q3: claim_task 说任务不存在

canonical task_id 是短形式 TASK-YYYYMMDD-NNN（不含 -ADMIN-to-PM 与 .md）。 读取类工具会归一化，以下等价：

claim_task(task_id="TASK-20260523-001")
claim_task(task_id="TASK-20260523-001-PM-to-DEV.md")

编号一旦生成即永久占用（done / archive 中的旧任务仍占号），新建任务不会复用 001。 若同一 task_id 对应多个 .md 文件，会报 Ambiguous / Duplicate task id。 详见 TASK-ID-CANONICAL.md。

Q4: Python/fcop_mcp 探测失败

如果 Python 或 fcop_mcp 未安装，fcop_mcp 工具不会注入 Agent Session。 解决方案：

pip install fcop-mcp
# 然后在 .env 设置 Python 路径：
# PYTHON_BIN=python
# 并移除或注释 CODEFLOW_SKIP_FCOP_PROBE=1

Q5: 历史任务怎么查

# 按日期查看
ls D:\codeflowmu\fcop\history\2026-05-23\

# 查看某个任务的完整记录
ls D:\codeflowmu\fcop\history\2026-05-23\TASK-20260523-001\

Q6: 如何切换 Agent 使用的模型

在 .env 修改（Cursor 通道）：

CURSOR_DEFAULT_MODEL=claude-opus-4-5

切换到 Google / Gemini 通道（见 §15）：

CODEFLOW_PROVIDER=google
GEMINI_API_KEY=AIzaSy...
GOOGLE_DEFAULT_MODEL=gemini-2.5-flash

Q7: Panel 中 Agent 全部显示「异常」

症状： Team 页面所有 Agent 状态为红色「异常」，聊天没有回复。

根因： 系统启动时会对每个 Agent 做探活（resume()）。若使用 Google 通道 （CODEFLOW_PROVIDER=google），而 @google/genai npm 包未安装， 探活调用会抛异常，导致 markFailed() 将 Agent 标记为 status=error。

修复流程：

# 步骤 1：验证包是否安装
Test-Path "D:\codeflowmu\packages\codeflowmu-runtime\node_modules\@google\genai"
# 输出 True = 已安装；False = 需要安装

# 步骤 2（若未安装）：安装 Google SDK 包
npm install --prefix packages/codeflowmu-runtime @google/genai@latest

# 步骤 3：重启服务
# Ctrl+C 停止当前进程，然后：
npm start

重启后 Agent 状态应变回「空闲」。若问题持续，检查 .env 中 GEMINI_API_KEY 是否有效。

Q8: 聊天发送消息后无回复（Google 通道）

检查顺序：

  1. 确认 Agent 状态为「空闲」（见 Q7）
  2. 在 .env 确认 GEMINI_API_KEY 已正确填写且未过期
  3. 确认 GOOGLE_DEFAULT_MODEL 设置为有效的模型 ID（如 gemini-2.5-flash）
  4. 在 Panel → Env Check 页面查看 API Key 检查项是否为 ✅
  5. 若 API Key 正确但仍无回复，查看终端日志中的错误信息

Q9: Panel「发布到 Gateway」失败或手机 PWA 不更新

症状： 设置 → 项目里版本不一致，点发布报错；或发布成功但手机仍显示旧版。

检查顺序：

  1. SSH 指南路径 — 确认存在 private/gateway-ops-guide.md（从 docs/gateway-ops-guide.example.md 复制），且含 密码：… 一行。不要使用 D:\Bridgeflow\private\relay-keepalive-guide.md。
  2. paramiko — py -3 -m pip install paramiko
  3. 本地版本一致性 — npm run pwa:check 通过后再发布
  4. Gateway 服务 — 服务器上 systemctl status codeflowmu-gateway 为 active；静态目录为 /opt/codeflowmu-gateway/mobile
  5. 线上校验 — 浏览器打开 {BaseUrl}/m/{instance_id}/mobile/version.json，与本地 codeflowmu-desktop/mobile/version.json 对比

详见 §11.11 与 docs/PWA_RELEASE.md。

10. 架构速览

codeflowmu/
├── codeflowmu-shell/          # 主入口（Node.js / TypeScript）
│   └── src/
│       ├── main.ts            # 应用启动、InboxWatcher 挂载、Web Panel
│       ├── sdk-factory.ts     # 双通道 SDK 工厂（Cursor / Google）+ fcop_mcp MCP 注入
│       ├── config.ts          # 5 层配置加载
│       ├── web-panel.ts       # Web Panel（--no-panel 时跳过）
│       ├── lifecycle-runtime-bridge.ts  # lifecycle syscall → J1 ledger rebuild
│       └── review-attention.ts          # pm.review_check → review_attention 索引
│
├── packages/
│   ├── codeflowmu-runtime/    # 调度器与 Agent 管理
│   │   └── src/
│   │       ├── Runtime.ts           # 统一运行时对象
│   │       ├── registry/
│   │       │   ├── CursorSdkAdapter.ts  # Cursor SDK 适配器
│   │       │   └── GoogleGenAiAdapter.ts # Google Gen AI SDK 适配器（Gemini + MCP 归一化）
│   │       ├── ledger/
│   │       │   ├── LedgerBuilder.ts     # tasks.jsonl + views/*.todo.md 投影
│   │       │   └── scheduleLedgerRebuild.ts  # debounced 全量 rebuild
│   │       └── scheduler/
│   │           ├── InboxWatcher.ts  # 监控 fcop/_lifecycle/inbox/
│   │           ├── TaskDispatcher.ts # 启动 Agent Session，注入角色上下文 + agentTaskQueue
│   │           ├── LifecycleGovernor.ts  # 异步 inbox↔active + ledger rebuild 触发
│   │           ├── ReportWatcher.ts  # 监控 fcop/reports/，触发后续任务
│   │           └── PlanScheduler.ts  # Sprint 计划自动推进
│   └── codeflowmu-protocol/   # 协议类型定义
│
├── fcop/                      # FCoP 协议文件系统
│   ├── fcop.json              # 团队配置（protocol_version: 3）
│   ├── _lifecycle/            # 任务生命周期目录
│   ├── reports/               # 报告文件
│   ├── shared/                # 团队共享文档
│   ├── history/               # 深度历史归档
│   └── issues/                # 问题跟踪
│
├── .codeflowmu/
│   ├── pm-skills.manifest.json      # 现有 PM runtime skills（带 Panel/API/Planner）
│   └── agent-skills.manifest.json   # Agent Playbook Skill 全局总表
│
├── docs/
│   └── skills/                # Skill 长文档、契约、映射、方法论
│
├── skills/                    # 可被 Agent 宿主加载的复用 SKILL.md 包
│   ├── README.md
│   ├── README.zh.md
│   ├── fcop-*/
│   └── pm-*/
│
└── .env                       # 本地环境配置（API Key + 通道选择）

10.1 Agent Playbook Skill 目录关系

CodeFlowMu 的 skill 分两层：MCP Skill 是工具注册层，Agent Playbook Skill 是行为规范层。不要把二者混成一个概念。

路径 用途 面向对象
docs/skills/agent-skills.manifest.json Agent Playbook Skill 的稳定 source-of-truth 总表，随源码保留 初始化修复 / 文档审计 / Agent 调度侧参考
.codeflowmu/agent-skills.manifest.json 本地/runtime 投影副本；.codeflowmu/ 被删时会丢，Shell 启动时会从 docs/skills/agent-skills.manifest.json copy-if-missing 恢复 Runtime / Panel / Agent 调度侧读取
.codeflowmu/pm-skills.manifest.json 已落地的 PM runtime skills，保留现有 pm.* ID，不在 Playbook 中重命名 PM Panel / API / PmGovernancePlanner
docs/skills/ 长文档、共享契约、映射关系、方法论，例如 write-report-contract.md、pm-skills-mapping.md 人和 Agent 都可阅读，用于说明“为什么/边界是什么”
skills/ 跨 Agent 宿主复用的 SKILL.md 包，例如 skills/fcop-report-writing/SKILL.md Codex / Claude / Cursor / Copilot 等加载 skill 时使用

一句话：

.codeflowmu/agent-skills.manifest.json  # 本地/runtime 投影副本
docs/skills/agent-skills.manifest.json  # 稳定 source-of-truth 总表
docs/skills/                            # 长说明、契约、映射、方法论
skills/*/SKILL.md                       # Agent 可直接加载复用的紧凑 skill 包

docs/skills/ 负责把规则讲清楚；skills/ 负责把规则压缩成 Agent 可复用的操作指南。两者都属于 Agent Playbook Skill 层，不代表 runtime API 已实现。

干净初始化或故障恢复时，如果删除了 .codeflowmu/，.codeflowmu/agent-skills.manifest.json 会随之消失。它不是唯一真相源；Shell 启动时（codeflowmu-shell/src/main.ts，在 plantPmSkillManifestIfMissing 之后）会调用 plantAgentSkillsManifestIfMissing(projectRoot)，从 docs/skills/agent-skills.manifest.json copy-if-missing 恢复投影副本。该逻辑定义于 packages/codeflowmu-runtime/src/skills/AgentPlaybookManifest.ts：投影不存在且 source-of-truth 存在时复制；两者都缺时只打 warn，不生成空 manifest；已有投影不会被覆盖。

自动路由：

  • CodeFlowMu Runtime 派单启动 Agent session 时，会把 Agent Skill Routing 注入 session prompt / role context。Cursor SDK 模式当前由 packages/codeflowmu-runtime/src/scheduler/TaskDispatcher.ts 注入。
  • Gemini 接入模式不能依赖 .cursor/rules；GoogleGenAiAdapter 通过 ensureAgentSkillRoutingInSystemPrompt()（packages/codeflowmu-runtime/src/skills/AgentSkillRouting.ts）注入与 Cursor SDK 相同的 Agent Skill Routing 语义。
  • Cursor IDE 手动会话读取 .cursor/rules/codeflowmu-agent-skill-routing.mdc，这是补充通道，不是 Cursor SDK 派单主通道。
  • 用户只需要说业务意图；Agent 根据角色、任务阶段、问题类型选择相关 skills/*/SKILL.md。
  • docs/skills/* 只在需要长契约、边界、映射或更完整 Playbook 解释时打开。
  • Playbook 定“怎么想、怎么写”；pm.* / MCP / FCoP 工具定“怎么验、怎么进 ledger”。

自动注入规则（当前 runtime 落地版）：

  • Manifest 是索引，不是 prompt 内容：禁止把 .codeflowmu/agent-skills.manifest.json 或全部 skills/*/SKILL.md 一次性塞给 Agent。
  • 按场景取 1-3 个：SkillContextRouter 会按 role × intent × task text 匹配少量技能片段，默认最多 3 个；例如 PM 派技术任务时会命中 pm-tech-scope，网页验收会命中 browser-playwright-check。
  • 通用技能全角色可用：browser-playwright-check、code-search-navigation、run-local-command-check、test-selection 等基础技能不属于某个角色，只有任务文本出现浏览器、代码定位、命令验证、测试范围等信号时才注入。
  • 角色 Playbook 只按角色触发：PM/DEV/QA/OPS/EVAL 的 Playbook 不跨角色泛注入；例如 DEV 不会因为 manifest 里有 PM 技能就拿到 PM 全套上下文。
  • PM 有两层技能：5 个 pm.* 是 runtime skills，已经接到 API / Panel / journal / planner；7 个 pm-* 是 PM Playbook skill 包，负责产品、范围、优先级、架构审查、交付计划、验收标准、技术范围选择等行为指导。二者可以映射，但不是同一层。
  • 每次注入要留痕：runtime 自动注入会向 skill invocation journal 记录 auto_inject，方便在“技能库 → 调用记录”追踪用了什么、为什么用。

Panel 使用：

  • “技能库 → 目录”读取 /api/v2/agent-skills/catalog，展示 manifest 中登记的分组、状态、路径和本地包存在性。
  • 点击任意技能卡片，右侧“技能详情”会显示 ID、角色、文档路径、SKILL.md 路径、runtime/MCP/common 映射和使用规则；未手动点击时默认选中当前筛选结果第一项，避免详情区域空白。
  • “打开说明文档”和“打开 SKILL.md”会跳到“文件浏览”并预览对应文件。
  • “技能库 → 调用记录”用于看 runtime skill / playbook auto-inject 的实际调用和结果。

当前 skills/ 目录已有：

  • README.md：英文说明。
  • README.zh.md：中文说明。
  • fcop-* / 基础通用 skill：FCoP 任务读取、报告写作、blocked 处理、lifecycle 边界、网页 Playwright 检查、代码搜索定位、本地命令验证、测试范围选择等 skill 包。
  • pm-*：PM 产品需求、范围控制、优先级、架构审查、交付计划、验收标准等 Playbook skill 包。
  • tm-*：技术经理交付治理、风险依赖、评审路由等 Playbook skill 包。
  • architect-*：架构师系统设计、边界审查、决策记录审查等 Playbook skill 包。
  • dev-*：DEV 代码定位、小范围补丁、测试说明等 Playbook skill 包。
  • qa-*：QA 问题复现、修复验证、回归检查等 Playbook skill 包。
  • ops-*：OPS 运行健康、日志诊断、卡顿流程诊断等 Playbook skill 包。
  • eval-*：EVAL 观察记录、风险差距分析、晋升建议等 Playbook skill 包。
  • ui-*：UI 需求澄清、信息架构、视觉一致性、可用性验收等 Playbook skill 包。

边界：

  • 不要把 skills/*/SKILL.md 当成 Panel/API/runtime 能力。
  • 不要从 skills/ 目录自动提交 GitHub Issue、archive、delete 或移动 lifecycle。
  • 不要重命名 .codeflowmu/pm-skills.manifest.json 中现有 pm.* runtime skill ID。
  • 不要把 docs/skills/ 的方法论直接升级成 FCoP 正式协议；协议变更必须走单独治理。

关键数据流

.env / config.json
    │  CODEFLOW_PROVIDER=cursor|google
    ▼ loadConfig()
  main.ts
    │
    ├─ sdk-factory.ts
    │   ├─ PROVIDER=cursor → CursorSdkAdapter（Cursor API + Claude 模型）
    │   └─ PROVIDER=google → GoogleGenAiAdapter（Gemini API + Google 模型）
    │       ↓ 两种 Adapter 共用同一套 MCP 注入机制（resolveMcpServers）
    │
    ├─ InboxWatcher → 监控 fcop/_lifecycle/inbox/
    │     │
    │     ▼ 检测到 TASK-*.md
    │  TaskDispatcher.dispatchTask()
    │     │
    │     ▼ sdk.create({ mcpServers: { fcop: ... } })
    │  Agent Session（Claude 或 Gemini）
    │     │
    │     ▼ 通过 fcop_mcp 工具操作文件
    │  write_report → submit_review → approve_review → archive
    │
    └─ ReportWatcher → 监控 fcop/reports/
          │
          ▼ 检测到 REPORT-*.md
       触发 PM 汇总 Session

11. Web Panel UI 详解

访问地址： http://localhost:18766（默认端口，可在 .env 中修改 WEB_PANEL_PORT）

Web Panel 是 CodeFlowMu 的图形操作界面，提供 16 个功能页面，通过左侧导航栏切换。 必须以 npm start（不加 --no-panel）启动才能使用。

Web Panel 总览

┌────────────────────────────────────────────────────────────────┐
│  CodeFlowMu Web Panel  · http://localhost:18766               │
├──────────┬─────────────────────────────────────────────────────┤
│          │                                                      │
│  左侧    │                主内容区                              │
│  导航栏  │  （根据选中菜单切换显示）                           │
│          │                                                      │
│ Dashboard│                                                      │
│ Chat     │                                                      │
│ Tasks    │                                                      │
│ Reports  │                                                      │
│ Approvals│                                                      │
│ Doorbell │                                                      │
│ Eval     │                                                      │
│ Files    │                                                      │
│ ErrorLog │                                                      │
│ Git      │                                                      │
│ Mobile   │                                                      │
│ Export   │                                                      │
│ Templates│                                                      │
│ Env      │                                                      │
│ Team     │                                                      │
│ Settings │                                                      │
└──────────┴─────────────────────────────────────────────────────┘

11.1 仪表盘 Dashboard

默认首页，提供系统整体状态的实时概览。大屏/首页动效由 home-reactor 模块驱动（codeflowmu-desktop/panel/home-reactor.js、.css、home-reactor-i18n.js）；懒加载与 smoke 见 codeflowmu-shell/scripts/panel-bigscreen-smoke.mjs。

功能模块 说明
今日用量统计 显示当天 API 调用次数、Token 消耗量（调用 /api/v2/usage/today）
Agent 队列状态 当前正在运行的 Agent 列表，各 Agent 的状态（运行中 / 等待 / 完成）
系统健康指示 Shell / Python fcop / fcop-mcp / protocol_version / MCP 挂载（GET /api/v2/health，见 §11.14）
最近活动流 最新任务创建、报告提交、审批事件的时间线
任务汇总卡片 待处理 / 进行中 / 已完成任务数量快速统计
Home Reactor 首页可视化反应堆/大屏；与 Kanban 共用 ledger 投影，不替代 _lifecycle/ 物理路径

操作： 点击卡片数字可快速跳转到对应的 Tasks / Reports 页面。

11.2 聊天 Chat

与 AI Agent 进行实时对话。Chat 有两种语义，不要混用：

模式 何时使用 行为
快捷派任务 需要新的、可追溯工作项 后端生成 FCoP TASK 写入 inbox/（正式派单）
聊天唤醒 ADMIN 说「继续」「开工」「巡检」等 绑定已有 task_id，发普通 message；不创建 TASK、不移动 lifecycle
功能 说明
消息发送 输入框发送消息，指定目标 Agent（PM / DEV / QA / OPS）
角色选择 顶部下拉选择对话对象角色，默认 PM
思考日志 勾选「显示思考过程」可查看 Agent 推理步骤（/api/v2/thinking/logs）
历史消息 自动保留本次会话的对话历史
快捷派任务 结构化描述 → 新 TASK 文件（见上表）
聊天唤醒 wakeAgent(agentId, taskId, message)：继续原 TASK，写 transcript；聊天里「做完了」不算 REPORT

提示： 正式、可审计的完成信号只有 REPORT 文件 + submit_review。Chat 适合调试、探索或唤醒继续；主线验收仍走 review → done → archive（§5.2）。

11.3 任务 Tasks

FCoP Lifecycle 任务管理中心。Kanban 列来自 ledger 投影（taskEffectiveScopeKey）；列表/详情应同时展示 物理路径 fcop/_lifecycle/{stage}/ 与完整文件名。当 physical_scope !== ledger_scope 时 Panel 显示漂移警告。细则见 panel-task-lifecycle-ui-rules.zh.md。

任务列表区

标签页 对应目录 / 投影 说明
Inbox（待处理） _lifecycle/inbox/ 新到达、等待领取
Active（进行中） _lifecycle/active/ 执行中；含 waiting_pm_attention（仍可能在 active，≠ review）
Review（待验收） _lifecycle/review/ 已 submit_review，等待 done_authority
Done（已验收） _lifecycle/done/ approve_review 通过；物理 archive/ 不得折叠为 done
Archive（过渡归档） _lifecycle/archive/ archive_task / force_archive_task 后；taskIsWorkflowSealed
History（深度历史） fcop/history/YYYY-MM-DD/ archive_to_history（3.2.2+）

归档 Tab 三态（任务列表顶部）：taskArchiveTab = active（默认，不含 archive）| archive（仅 archive/history）| all（再点当前项切回「全部」）。

任务卡片详情

每个任务卡片显示：

  • Task ID 与 磁盘文件名（含 -SENDER-to-RECIPIENT 后缀）
  • 物理 scope 与 ledger scope（不一致时警告）
  • 发件人 → 收件人（角色）
  • 优先级（P0 / P1 / P2 / P3）
  • 当前状态 / root_task_id（报告分组锚点）
  • 任务关系标签：新建任务线 / 接着做 / 子任务
  • 创建时间

任务关系（FCoP-PENDING-0003）

Panel 的「发布任务」始终生成 TASK-*-ADMIN-to-PM.md，不允许 ADMIN 直接选择 DEV / QA / OPS / EVAL。原「意向执行角色」下拉已改为「任务关系」。

选项 何时使用 UI 行为 YAML 结果
新建任务线 独立的新工作 默认选项，不显示旧任务列表 新 thread_key；parent: 为空；references: []
接着做 二期、升级、延续旧任务 显示当前项目任务，可多选 继承第一个所选任务的 thread_key；只写 references；不写 parent
加到此任务 给当前未完成任务增加检查、修复、复验或补充任务 从任务卡片/详情进入；无需任务列表 继承当前任务 thread_key；parent 指向当前任务；references 同时引用当前任务

新建任务线示例：

thread_key: panel-task-023
parent:
references: []

接着做示例：

thread_key: grid-runner
parent:
references:
  - TASK-20260613-020
  - TASK-20260614-004

多选任务属于不同 thread_key 时，仅继承第一个所选任务的 thread_key，其余任务只作为 references。选择范围严格限制为当前产品开发根，不跨项目。

加到此任务示例：

thread_key: grid-runner
parent: TASK-20260614-004
references:
  - TASK-20260614-004

加到此任务 仅对 inbox / active / review 任务可用；当前任务已进入 done / archive 时禁用。

关系语义：

  • parent 是唯一强关系，也是任务 Tree 的唯一推导依据。
  • references 是承接、引用和历史依据，不会重新打开或阻止旧任务归档。
  • thread_key 只负责同线分组，不是父子关系。
  • Tree 是视图，事实来源仍是 TASK frontmatter；不得从正文文字或 references 猜测父任务。

任务详情侧栏的「子任务」列出 parent == 当前任务 ID 的任务；「承接 / 引用」展示 references，但不把引用画进 Tree。

归档控制： 正常归档前只检查是否存在 parent == 当前任务 ID 且仍在 inbox / active / review 的子任务。存在时返回 CHILD_TASKS_OPEN 并列出子任务；done 子任务、references 和 thread_key 均不阻止父任务归档。

证据归属： 新生成的 REPORT / EVAL / ISSUE 应尽量写：

source_task_id: TASK-20260614-004
references: []

旧证据文件没有 source_task_id 时继续使用原有 task_id / references / 文件名兜底，不影响展示和 lifecycle。

操作按钮

按钮 功能
新建任务 打开表单，填写 TASK 元数据，自动写入 inbox/
查看详情 展开 YAML frontmatter、Markdown 正文、物理路径
认领（Claim） 可选：claim_task → active/；热路径由 Runtime 异步 rename
提交验收 执行者：submit_review → review/
批准 / 打回 done_authority：approve_review / reject_review
归档（Archive） 正常：须已在 done/ → archive_task
强行归档 操作者满足 _canOperatorForceArchive 时 → force_archive_task（须原因）
进历史（History） archive_to_history → fcop/history/YYYY-MM-DD/
取消 标记 cancelled（治理层记录）

UI 提示： 执行者「完成」应等价 submit_review，不是 finish_task 直进 done。physical_scope === 'archive' 时 workflow 视为 sealed（taskIsWorkflowSealed），禁止再打回 review。

任务详情侧栏（#task-detail-panel）

点击「查看」打开右侧固定抽屉（--tp-detail-width，默认 760px）：

能力 说明
左边框拖拽 #tdp-resize-handle（ew-resize）；宽度 min 480px、max 92vw；持久化 localStorage['tdp-panel-width']；openTaskDetail / tpSyncDetailPanelLayout 时应用
状态提示折叠 动作按钮下方的黄/蓝提示块（回执摘要、tdp-dispatch-retry、tdp-reject-reason、tdp-review-attention 等）包在 #tdp-alerts-fold；默认展开；折叠后一行摘要；持久化 localStorage['tdp-alerts-collapsed']
review_attention Shell review-attention.ts 从 .codeflowmu/pm-governance/cycle.jsonl 读取 pm.review_check 失败，API 列表 enrichment 后在详情展示 REVIEW 未通过原因
Agent 队列 GET /api/v2/agent-queue 展示 running / queued / paused；数据来自 .codeflowmu/pm-governance/agent-task-queue.json

11.4 报告 Reports

查看 Agent 提交的 FCoP REPORT；工作副本在 fcop/reports/，Kanban/列表数据来自 ledger/ 投影。报告看板按 root_task_id 分组（mergeLedgerRowsByRoot()），不按 thread_key 拆组。归档 Tab 三态：reportArchiveTab = active | archive | all（语义同任务 Tab）。

报告列表

列 说明
Report ID 如 REPORT-20260523-001-PM-to-ADMIN + 物理路径
root_task_id 分组锚点（同一根任务的多份 REPORT 合并展示）
关联 Task 对应 TASK ID / 物理 _lifecycle 阶段
报告者 提交报告的 Agent 角色
状态 done / aborted / escalated；GATE 行可标注 fact_check
ledger vs 物理 physical_scope !== ledger_scope 时漂移警告
提交时间 REPORT 文件写入时间

筛选功能

  • 按角色筛选（PM / DEV / QA / OPS）
  • 按状态筛选（done / aborted）
  • 按时间范围筛选
  • 关键词搜索（搜索 REPORT 正文）
  • 归档 Tab：active / archive / all

操作

按钮 功能
查看详情 REPORT 全文 + 关联 TASK 物理路径
关联任务 跳转到对应 TASK（含 _lifecycle 目录）
导出 导出为 Markdown 或 JSON

11.5 审批 Approvals

处理需要人工审批的 FCoP REVIEW 文件（decision: needs_human）。

审批队列

所有 decision: needs_human 的 REVIEW 文件列于此队列，包括：

  • 高风险任务（risk_level: high / irreversible）由 write_task 自动创建的 REVIEW
  • Agent 主动请求人工判断的 REVIEW

审批卡片内容

字段 说明
Review ID 如 REVIEW-20260523-001-PM
关联 Subject 被审核的 TASK 或 REPORT ID
风险等级 medium / high / irreversible
审核人 建议审核角色
当前决策 needs_human（等待人工）
摘要 REVIEW 文件 Markdown 正文摘要

操作按钮

按钮 功能
✅ 批准（Approve） 调用 fcop_mcp/mark_human_approved，decision 更新为 approved，Agent 继续执行
❌ 拒绝（Reject） 将 decision 更新为 rejected，任务流转停止
📝 批注 填写审批意见（写入 human_approval.note 字段）
查看详情 展开完整 REVIEW 文件

重要： 批准/拒绝操作后，相关 Agent 会话会自动感知并继续/中止执行流程。

11.6 门铃 Doorbell

接收系统事件通知和 FCoP ALERT 告警的收件箱。

通知类型 触发条件 对应 FCoP
新任务到达 inbox 目录新增 TASK 文件 TASK_CREATED 事件
提交验收 Agent submit_review 或 Runtime 将 TASK 移入 review/ REPORT_CREATED / lifecycle 事件
审批请求 生成 needs_human REVIEW REVIEW_CREATED 事件
S1 治理告警 24h 内高风险工具调用无 REVIEW GAL S1 critical_tool_unreviewed
S3 治理告警 执行窗口 > 6h 无独立治理信号 GAL S3 missing_independent_verdict
S4 治理告警 任务超 24h 未归档 GAL S4 long_running_without_reconciliation

操作：

  • 点击通知条目 → 跳转到对应 Task / Report / Approval 详情
  • 标记已读 / 全部已读
  • 调用 fcop_mcp/fcop_list_alerts 刷新告警列表

11.7 EVAL 评测（独立观察员）

EVAL 是 独立观察者，不属于 PM 团队工作流。EVAL 只观察、记录、推荐；不派 TASK、不写团队可见 REPORT、不替 PM/ADMIN 做 done 或 archive 决定。EVAL 的 OBSERVATION 默认只给 ADMIN，不进入 PM 团队链路。

项 说明
定位 协议外质量/行为观察；ADMIN 决策是否采纳
新输出 OBSERVATION-*.md（目录 fcop/internal/eval/）
Legacy 历史 AUDIT-*.md 仍可读，新跑批逐步改用 OBSERVATION 前缀
团队 REPORT EVAL 不写入 fcop/reports/ 作为 PM 汇总链的一部分
Panel 汇总 /api/v2/eval/summary 等指标供 ADMIN 浏览，不触发 lifecycle
ADMIN 处置 忽略 / 继续观察 / 采纳 / 转 TASK / 转 ISSUE / 沉淀 shared/
功能 说明
评测汇总 各 Agent 完成率、响应时间等（/api/v2/eval/summary）
指标图表 历史观察趋势
观察记录 查看 fcop/internal/eval/ 下 OBSERVATION / legacy AUDIT
规则参考 评测标准可写在 fcop/shared/EVAL-*.md（导航用，非 IPC 回执）

详见 docs/CODEFLOWMU_LIFECYCLE_AUTHORITY_IMPLEMENTATION.md §9。

11.8 文件浏览 Files

浏览和管理 FCoP 项目目录的文件结构。

功能 说明
目录树 展示 fcop/ 完整目录树（/api/v2/files/list）
文件预览 点击 .md 文件，右侧显示渲染后的 Markdown 内容
YAML 解析 自动解析 FCoP 文件 frontmatter，高亮展示
文件搜索 按文件名或内容关键词搜索
快速导航 快捷入口：inbox / active / reports / issues / shared / log

11.9 错误日志 Error Log

显示系统运行时的错误记录，便于调试。

功能 说明
实时日志流 WebSocket 订阅，日志实时刷新
日志级别过滤 ERROR / WARN / INFO / DEBUG
来源过滤 按组件过滤：InboxWatcher / TaskDispatcher / SDK / fcop_mcp / WebPanel
时间段筛选 查看特定时间段的日志
导出 导出为 .log 或 .json 格式

11.10 Git 状态

实时查看项目 Git 工作区状态，便于监控 Agent 的文件变更。

功能 说明
当前状态 显示 git status 输出（/api/v2/git/status），标注已修改 / 新增 / 删除的文件
差异对比 点击文件查看 git diff 差异（行级别高亮）
提交记录 展示最近 N 条 git log
暂存区 显示已 staged 的文件列表

注意： 此页面仅展示，不提供 git add / commit / push 操作，所有 Git 操作 仍需在终端执行（遵循 FCoP Rule 7 破坏性操作预声明规则）。

11.11 移动端 Mobile

Mobile 有两条独立能力，不要混用：

形态 入口 用途
Panel 移动视图 Panel → Mobile 页 同局域网扫码打开 Web Panel 简化布局（http://{本机IP}:18766）
Official Gateway PWA 公网 https://ai.chedian.cc/codeflowmu/m/{instance_id}/mobile/ 手机独立 PWA，经 codeflowmu-gateway（端口 5262）转发 PC API

与旧 Bridgeflow 的区别：历史 bridgeflow-relay（5252） 与 D:\Bridgeflow\private\relay-keepalive-guide.md 属于旧中继方案，已停用。CodeFlowMu 只认 codeflowmu-gateway 与仓库内 private/gateway-ops-guide.md。

11.11.1 Gateway SSH 运维指南（本地私有）

服务器 SFTP 上传与 systemctl restart codeflowmu-gateway 需要 root SSH 密码。密码不得写入 Git 或 Panel 配置，统一放在本机私有文件：

项 路径
实际文件（勿提交） {仓库根}/private/gateway-ops-guide.md
可提交模板 docs/gateway-ops-guide.example.md
读取模块 codeflowmu-gateway/scripts/gateway_ops_credentials.py

首次配置：

  1. 复制 docs/gateway-ops-guide.example.md → private/gateway-ops-guide.md
  2. 在正文中保留一行 密码：你的SSH密码（脚本用正则 密码[：:]\s*(\S+) 解析）
  3. 确认 private/ 已在 .gitignore 中（默认已忽略）

可选覆盖： 环境变量 CODEFLOWMU_GATEWAY_OPS_GUIDE 指向其它绝对路径。

禁止： 继续引用 D:\Bridgeflow\private\relay-keepalive-guide.md——该文件描述的是旧中继服务，与当前 Gateway 发布链无关。

11.11.2 Panel 一键发布 PWA 到 Gateway

修改 codeflowmu-desktop/mobile/ 后，仅 push Git 不会更新手机端 PWA；必须让 Gateway 运行机上的静态目录与本地 version.json / mobile.js / sw.js 对齐。完整流程见 docs/PWA_RELEASE.md。

Panel 快捷路径（推荐）：

  1. 本地 bump 并校验版本：npm run pwa:bump -- x.y.z 或 npm run pwa:check
  2. 打开 Panel → 设置 → 项目，找到当前产品开发根的 Mobile / Gateway 同步 卡片
  3. 卡片展示 本地版本 vs 线上 Gateway 版本（GET /api/v2/mobile/panel/version-info）
  4. 若不一致，点击 「发布到 Gateway」 → 确认 → POST /api/v2/mobile/panel/publish-gateway（confirm: true）

发布链（Shell 后端）：

  1. 运行 pwa-version-check
  2. release_mobile_pwa.py push → sync_mobile_static.py（SFTP 上传 codeflowmu-desktop/mobile/ → 服务器 /opt/codeflowmu-gateway/mobile/）
  3. 远程 systemctl restart codeflowmu-gateway
  4. 再次拉取线上 version.json 校验对齐

前置依赖：

依赖 说明
private/gateway-ops-guide.md 缺则报错 PUSH_PASSWORD_GUIDE_MISSING
paramiko py -3 -m pip install paramiko（缺则 PUSH_PARAMIKO_MISSING）
PYTHON_BIN 或 PATH 中的 py/python 执行发布脚本
.codeflowmu/mobile-gateway.json 含 gateway_url、instance_id 等，供线上校验 URL

常见错误码（Panel 文案键）：

错误码 含义
ALREADY_ALIGNED 本地与线上一致，无需发布
PWA_VERSION_CHECK_FAILED 本地五处版本未对齐，先 npm run pwa:check
PUSH_PASSWORD_GUIDE_MISSING 未配置 private/gateway-ops-guide.md
PUSH_PARAMIKO_MISSING 未安装 paramiko
VERIFY_NOT_ALIGNED 上传后线上版本仍不一致（查 Gateway 日志 / 重启）
LOCAL_GATEWAY_MANUAL_RESTART Gateway URL 为 localhost，需本机手动重启服务

命令行等价（无 Panel 时）：

cd D:\codeflowmu
py -3 codeflowmu-gateway\scripts\release_mobile_pwa.py push
# 或
powershell -ExecutionPolicy Bypass -File scripts\publish-mobile-gateway.ps1 -InstanceId pc_xxx -BaseUrl https://ai.chedian.cc/codeflowmu

11.11.3 Panel 移动 QR（局域网）

功能 说明
QR 码生成 Mobile 页显示本机 IP + Panel 端口二维码
局域网 IP 检测 自动检测局域网地址
移动端布局 手机浏览器打开 Panel 小屏视图

本地开发 Gateway（仅 127.0.0.1:5262）见 codeflowmu-gateway/README.md。

11.12 数据导出 Export

将 FCoP 数据导出为多种格式，便于归档和分析。

导出类型 格式 说明
全量任务导出 JSON / CSV 导出所有 TASK 文件的结构化数据
报告导出 JSON / Markdown bundle 导出所有 REPORT，打包为 zip
审计链导出 JSON 导出 TASK → REPORT → REVIEW 的完整审计链
团队效能报表 CSV 按角色统计的任务完成率、耗时等效能指标

11.13 任务模板 Templates

管理任务模板，快速创建标准化 TASK 文件。

功能 说明
模板列表 显示 fcop/shared/SPEC-*.md 中存储的所有模板
新建模板 提供表单，填写 TASK 模板的 YAML frontmatter 和 Markdown 正文框架
使用模板 选择模板 → 填写差异字段 → 一键写入 inbox
编辑 / 删除 直接编辑或删除现有模板

内置模板示例：

  • SPEC-bug-fix — 缺陷修复任务
  • SPEC-feature-dev — 新功能开发任务
  • SPEC-code-review — 代码评审任务
  • SPEC-doc-update — 文档更新任务

11.14 环境预检 Env Check

在启动前或运行时验证所有依赖环境是否就绪（/api/v2/env/check）。

GET /api/v2/health（系统健康）

Web Panel 仪表盘、设置页 About、环境卡片均调用此接口。字段语义：

字段 含义 来源
shellVersion CodeFlowMu Shell 版本 codeflowmu-shell/package.json
version 同 shellVersion（旧 Panel 兼容字段） 同上
fcop Python fcop 包版本 pip / importlib.metadata 子进程探测
fcopMcp Python fcop-mcp 包版本 同上
protocolVersion FCoP 协议纪元 fcop/fcop.json → protocol_version（v3 项目为 3）
rulesVersion 规则文件版本 .cursor/rules/fcop-rules.mdc frontmatter → fcop_rules_version（如 3.0.0）
requiredMinPackage 示范体要求的最低 pip 包版本 固定 3.2.2
packageVersionOk fcop + fcop-mcp 是否均 ≥ requiredMinPackage semver 比较
productRole 产品定位文案 固定 FCoP downstream application
pythonBin 探测用的 Python 解释器路径 PYTHON_BIN 或 PATH
mcpRunning 是否有 Agent 已挂载 MCP MCP 注入器
mcpMountedCount 已挂载 MCP 的 Agent 数量 MCP 注入器
mcpInjectorMode 注入器模式（如 live） MCP 注入器
root / projectRoot FCoP 项目根目录 自动检测

四套版本号不可混读（About 页与 health 均分层展示）：

维度 示例 含义
Shell 0.3.0-alpha codeflowmu-shell npm 包
Python fcop / fcop-mcp 3.2.2+ pip 安装的协作库（示范体硬要求 ≥ 3.2.2）
protocol_version 3 fcop/fcop.json 协议纪元（v3 生命周期布局）
fcop_rules_version 3.0.0 规则文件 MAJOR（对应 fcop@2.0.0 哲学升级，≠ pip 包 2.0.0）

注意：shellVersion 与 fcop（如 3.2.2）是两套独立版本号；rulesVersion（如 3.0.0）也不是 pip 包版本。

GET /api/v2/env/check（分组预检）

检查项 分组 说明
Node.js 版本 runtime 当前 Node 进程版本
Python 版本 runtime python --version
codeflowmu-shell runtime Shell package.json 版本
fcop (Python) runtime 已安装 fcop 包版本 + 解释器路径
fcop-mcp (Python) runtime 已安装 fcop-mcp 或 import fcop_mcp 成功
FCoP protocol_version runtime fcop/fcop.json 中 protocol_version
CURSOR_API_KEY apikeys 是否已设置（可选）
RELAY_URL apikeys 是否已设置（可选）
Web Panel HTTP connectivity Panel 监听地址
MCP 注入器 connectivity 模式 + 已挂载 Agent 数
fcop-mcp 挂载 connectivity 当前是否有 Agent 挂载 fcop MCP
FCoP 任务目录 (v3 inbox) connectivity fcop/_lifecycle/inbox 必须可访问
FCoP v2 遗留目录 connectivity 不得存在 fcop/log/（v2 单数归档桶）；0002 下 fcop/tasks/ 等为必需工作面，不属此项
fcop/reports 目录 connectivity 报告目录可访问
layoutRisks connectivity GET /api/v2/fcop/info → 拓扑风险提示（MIXED、缺 _lifecycle 等）

响应 flat 字段（轻量消费）：shellVersion、fcopVersion、fcopMcpVersion、protocolVersion、rulesVersion、requiredMinPackage、packageVersionOk、mcpMounted、mcpMountedCount、mcpInjectorMode。

每个检查项显示 ✅ 通过 / ❌ 失败 / ⚠️ 警告，点击 ❌ 展开具体错误和修复建议。

操作：

  • 点击 「重新检查」 刷新所有检查项
  • 点击 「修复建议」 查看针对每个失败项的解决方法

11.14.1 FCoP 团队一键智能部署与自愈机制

当您使用 CodeFlowMu 打开一个全新的、空白的或刚从其他 FCoP 团队接手的项目目录时，系统将自动进入未初始化挂起状态，并引导您通过 UI 对话框一键完成「开发团队极简智能部署」。

1. 未初始化安全强锁挂起

当系统检测到当前项目缺失底层 FCoP 元数据（fcop.json 缺失）或应用专属运行态结构时，前端将启用全局阻断器（_isFcopUninitialized = true）。

  • 安全效果与智能自检：强锁挂起状态下，侧边栏所有业务页面（如 Tasks、Chat、Dashboard 等）的跳转请求都会被安全拦截，强行倒回“环境预检”页面，高亮展示未初始化横幅，防止因数据缺失引发的前端白屏或空数据逻辑报错。在拦截挂起的同时，前端会自动且静默地触发运行一次全面的环境依赖检测（无需人工手动点击），以零延迟的方式在界面上实时呈现当前的物理环境故障点与红叉，极大地增强了系统的自愈可见性。
2. 开发团队一键部署 Dialog

预检页将自动呈现场景化自愈横幅，点击“一键初始化/接管项目”会拉起专为软件开发打造的 FCoP dev-team 部署确认面板：

  • 去粗取精：移除了 Solo 单智能体或其它与开发场景无关的混淆选项，专注于经典的 dev-team 软件开发团队。
  • 固定五大角色：直观展示在该模式下固定分配的 5 大岗位（PM、DEV、QA、OPS、EVAL）职责，与顶部状态栏完美呼应。
3. 底盘协议层 vs 专属应用层物理拓扑建立

点击“立即部署/接管项目”后，后端 POST /api/v2/fcop/init 会被触发，在项目物理根目录下瞬间自愈建立两层重要目录结构：

  • 🔑 FCoP 协议底盘（智能体 IPC 协作的法理骨架）：

    • fcop.json：主控配置文件（固定写入 protocol_version: 3，注入团队角色定义）。
    • fcop/_lifecycle/：新建包含 inbox/、active/、review/、done/、archive/ 的五状态核心流转容器。
    • fcop/reports/、fcop/reviews/、fcop/shared/：标准 IPC 数据交换只读区。

  • 💻 CodeFlowMu 宿主专属（人机交互与脑电波思考重播的血肉神经网络）：

    • fcop/logs/（复数，与 FCoP 钦定 fcop/log/ 单数归档桶不同）：运行遥测根目录；POST /api/v2/fcop/init 会 mkdir 子目录，Panel 启动时 ensureFcopLogsAssetLayout 会补齐并写入/升级 fcop/logs/README.md（九类协作数据资产说明，collab-assets-v1）。
    • fcop/logs/thinking/{chat,task}/：按日 thinking-YYYYMMDD.jsonl，对接 Chat / 任务思考流重播。
    • fcop/logs/runtime/：按日 runtime-events-YYYYMMDD.jsonl（门铃冷存储；兼容只读旧 runtime-events.jsonl 与 .codeflowmu/events/runtime-events.jsonl）。
    • fcop/logs/analytics/、usage/、panel-api/：分析账本、用量、面板 API 耗时 JSONL（按日切文件）。
    • fcop/chat/：Direct Chat 按日 chat-YYYYMMDD.jsonl（兼容旧 chat.jsonl）；首次写入时自动建目录。
    • fcop/internal/：调控缓存（如 failures/）；一键 init 会建空目录。
4. 智能重测与呼吸灯上线
  • 1.5s 智能解锁：部署成功后，系统重置缓存并自动触发一次环境探测，红叉瞬间转为绿勾。全局未初始化阻断挂起器自动解除，放行所有页面。
  • 顶部呼吸灯精准上线：顶部状态栏无需进行过度复杂的自适应重构，原本为开发团队定制的静态 PM, DEV, QA, OPS, EVAL LED 指示灯在检测到 agents 数据激活后，瞬间从离线状态（opacity: 0.4 灰色）优雅亮起为在线或工作状态，实现整洁、专注的极致开发调控体验！

11.15 团队配置 Team

Web Panel 团队配置页（page-team）管理运行时 Agent 与模型映射，写入各产品开发根的 codeflowmu.team.json（点「保存配置」）。

区块 说明
模型配置 #tc-model-list：PM-01 / DEV-01 / OPS-01 / QA-01 / EVAL-01 各行独立选 LLM（auto 或 provider 模型列表）
团队身份 / 审批规则 只读展示 fcop/shared/ 团队文档与审批策略（来源 API）
Agent 成员 #ts-agent-list：5 张 Agent 卡（含 EVAL-01 观察员）；⚡ 唤醒、换 AI 阈值、会话统计
技能市场 #tc-skills：位于 Agent 成员之后；内置技能开关（与 PM 技能库 API 分离）
PM 技能 展示 PM 已启用 runtime skills 与最近自动判断（cycle.jsonl / skill-invocations.jsonl）

注意： fcop/fcop.json 中的团队法理骨架仍须通过环境预检「一键初始化」或手动编辑；本页侧重 运行时模型与 Agent 操作，不是替换 deploy_role_templates 部署角色 charter。

11.16 设置 Settings

配置 CodeFlowMu 的运行时参数，修改后热重载生效。

设置项 说明 默认值
Cursor API Key Cursor 账户 API Key —
默认模型 Agent 使用的 AI 模型 auto（与 codeflowmu.team.json 一致）
Python 路径 fcop_mcp 使用的 Python 解释器 python
FCoP 项目根 fcop/fcop.json 所在目录 自动检测（本仓库为 D:\codeflowmu）
Web Panel 端口 Web Panel 监听端口 18766
List Scope Cursor SDK 任务搜索范围（local / global） local
启用 Web Panel 是否启动 Web Panel（对应 --no-panel 标志） 启用
跳过 fcop 探测 加速启动，跳过 Python/fcop_mcp 版本探测 禁用

操作：

  • 修改后点击 「保存」 → 写入 .env / config.json
  • 点击 「重启服务」 → 调用 /api/v2/restart 热重启后端（不影响正在执行的 Agent 任务）

11.16.1 项目 · 多产品开发根

Panel 设置 页签中的 「项目」 用于登记多个产品开发根（与 CodeFlowMu monorepo 工作区可分离）。当前激活项决定任务、报告、环境预检、GET /api/v2/health 的 projectRoot 等 API 所解析的 fcop/ 目录。

操作 说明
添加 填写「项目名称」与「根目录路径」，或点 「浏览…」 在本机弹出系统文件夹选择器
切换 点击列表项 → Shell 调用 applyProjectScopedOpts 并重刷 ledger 缓存 → Panel loadAll()
删除 仅从注册表移除条目，不删除磁盘目录；不能删除当前激活项

持久化： %USERPROFILE%\.codeflowmu\v2\projects-registry.json（首次访问项目 API 时若文件不存在会写入默认项，根路径为 Shell 启动时解析的 bootstrap 根）。测试可用环境变量 CODEFLOW_PROJECTS_REGISTRY 指向临时 JSON。

本机选路径（浏览…）：

  • 请求：POST /api/v2/system/pick-directory，body 可选 { "initial": "D:/已有路径" }
  • 成功：{ "ok": true, "path": "D:\\xiangqi" }
  • 用户取消：{ "ok": false, "cancelled": true }
  • 并发：已有对话框打开时 409，error: "directory picker already open"
  • 实现：codeflowmu-shell/src/pick-directory.ts（Windows FolderBrowserDialog / macOS osascript / Linux zenity）
  • 限制：须在运行 npm start 的本机且有图形界面；SSH 无显示、Docker 无 X11 等场景只能手输路径

项目 REST API：

方法 路径 请求体 说明
GET /api/v2/projects — 返回项目数组，每项含 id、name、root、active（布尔）
POST /api/v2/projects { "name", "root" } 注册新根；root 须存在（pathResolve 后 existsSync）
POST /api/v2/projects/switch { "id" } 切换激活项；响应含 root
DELETE /api/v2/projects/:id — 删除非激活项

切换项目后请对该产品开发根单独做 环境预检 与 一键 FCoP 初始化（若尚无 fcop/fcop.json）。干净初始化步骤见 CODEFLOWMU_CLEAN_INIT_RUNBOOK.md（路径均相对于当前选中的产品开发根）。

关于页 About · FCoP 协议区块

设置 → 关于 标签页展示 CodeFlowMu 作为 FCoP 下游示范体 的协议与工具信息（只读，不可编辑）。

UI 元素 数据来源 说明
版本徽章行 GET /api/v2/fcop/info fcop / fcop-mcp pip 包、protocol v3、rules v3.0.0、Shell 版本
升级告警 packageVersionOk === false pip 包低于 3.2.2 时红色提示
元数据网格 team + projectRoot + MCP 注入 团队模式、主控、已挂载 Agent
v3 生命周期 v3.lifecycle + v3.legacyV2OnlyDirs _lifecycle 五桶是否存在；仅 fcop/log/（v2）应标红；0002 工作面见 workFolders0002
fcop-mcp 工具目录 mcp.toolGroups ~45 个 MCP 工具分组只读展示（类似 Cursor MCP 面板）

GET /api/v2/fcop/info

专用 FCoP 信息端点（About 页、运维脚本可调用）。

字段 类型 含义
ok boolean 请求是否成功
productRole string 产品定位（FCoP downstream application）
shellVersion string Shell npm 版本
fcopVersion string | null Python fcop 包版本
fcopMcpVersion string | null Python fcop-mcp 包版本
protocolVersion number | null fcop.json → protocol_version
rulesVersion string | null fcop-rules.mdc → fcop_rules_version
requiredMinPackage string 最低 pip 要求（3.2.2）
packageVersionOk boolean fcop + fcop-mcp 是否达标
pythonBin string | null 探测用 Python 路径
projectRoot string FCoP 项目根
team object fcop.json 团队摘要（mode / team / leader / roles）
mcp object injectorMode、mountedAgents、toolCount、toolGroups[]
v3.lifecycle object 各生命周期目录是否存在
v3.legacyV2OnlyDirs string[] 仅 v2 单数桶（当前为 log），应为空数组
v3.legacyV2Dirs string[] 同上别名（Panel 兼容字段）
v3.workFolders0002 string[] 0002 必需工作面：tasks、reports、issues、ledger、attachments 等
v3.layoutRisks string[] 拓扑/布局风险提示
versionSemantics object 各版本字段的人类可读说明

示例（节选）：

{
  "ok": true,
  "fcopVersion": "3.2.4",
  "fcopMcpVersion": "3.2.4",
  "protocolVersion": 3,
  "rulesVersion": "3.0.0",
  "requiredMinPackage": "3.2.2",
  "packageVersionOk": true,
  "v3": {
    "legacyV2OnlyDirs": [],
    "workFolders0002": ["tasks", "reports", "issues", "ledger", "attachments"]
  }
}

v2 协议残留验收（运维 / 发版前）

在仓库根执行下列检查。区分：上游纯 FCoP v3 项目不应有 v2 扁平 fcop/tasks/ 作 inbox；CodeFlowMu 0002 示范体必须有 fcop/tasks/ 等工作面。

检查项 命令 / 方式 期望
无 v2 log/ 确认不存在 fcop/log/ 存在则 legacyV2OnlyDirs 非空
0002 工作面齐全 fcop/tasks/、reports/、ledger/、_lifecycle/ 五桶 workFolders0002 全 true
Panel 源码 codeflowmu-desktop/panel/index.html 投递/派单指向 _lifecycle/inbox/，非 v2 扁平 tasks
Shell 源码 codeflowmu-shell/src/fcop-v3-paths.ts FCOP_V2_ONLY_LEGACY_DIRS = ["log"]
在线 API GET …/api/v2/fcop/info legacyV2OnlyDirs: []；含 workFolders0002、layoutRisks
单元测试 `cd codeflowmu-shell && npm test -- --test-name-pattern="WP- fcop-v3

注意：fcop-rules.mdc 的 fcop_rules_version: 3.0.0 与 pip 包 fcop@3.2.x 是不同维度；About 页与 /api/v2/fcop/info 会分别展示。若本机 pip 仍为 2.x，packageVersionOk 为 false，需 pip install -U "fcop>=3.2.2" "fcop-mcp>=3.2.2" 后重启 Shell。

Web Panel 菜单速查表

菜单 图标 核心功能 后端 API
Dashboard 📊 系统概览、今日用量、Agent 状态 /api/v2/usage/today /api/v2/agents
Chat 💬 与 Agent 实时对话、即时派任务 /api/v2/thinking/logs
Tasks ✅ FCoP 任务全生命周期管理 /api/v2/tasks
Reports 📋 查看 Agent 提交的 REPORT 文件 /api/v2/reports
Approvals 🔐 处理 needs_human 审批 /api/v2/approvals
Doorbell 🔔 事件通知 + FCoP 治理告警 GAL S1/S3/S4
Eval 📈 Agent 输出质量评测和统计 /api/v2/eval/summary
Files 📁 FCoP 目录文件浏览和预览 /api/v2/files/list
Error Log 🚨 运行时错误日志实时查看 WebSocket
Git 🌿 Git 工作区状态和差异查看 /api/v2/git/status
Mobile 📱 局域网 Panel QR；设置 → 项目 PWA/Gateway 同步与一键发布 /api/v2/mobile/panel/version-info /api/v2/mobile/panel/publish-gateway
Export 📦 FCoP 数据多格式导出 —
Templates 📝 TASK 模板管理和快速派发 —
Env Check 🔍 运行环境依赖预检 /api/v2/env/check
Team 👥 团队配置和角色职责查看 —
Settings ⚙️ 运行时参数配置 /api/v2/restart

12. 自动化测试状态

最新状态（2026-05-23）：所有测试通过，累计 163 个用例，0 个失败。

测试套件总览

测试套件 文件 用例数 结果 包
Web Panel 集成测试 web-panel.test.ts 13 / 13 ✔ 全部通过 codeflowmu-shell
TaskDispatcher 集成测试 TaskDispatcher.test.ts 4 / 4 ✔ 全部通过 codeflowmu-runtime
E2E 生命周期测试 e2e-lifecycle.test.ts 3 / 3 ✔ 全部通过 codeflowmu-runtime
Runtime 全量单元测试 *.test.ts（runtime 包） 150 / 150 ✔ 全部通过 codeflowmu-runtime

12.1 Web Panel 集成测试（WP-*）

运行命令：

cd codeflowmu-shell && npm test
用例 ID 描述 端点
WP-01 空 Registry 返回 [] GET /api/v2/agents
WP-02 返回 agents 数组 GET /api/v2/agents
WP-03 inboxDir 不存在时返回 [] GET /api/v2/tasks
WP-04 reviewsDir 不存在时返回 [] GET /api/v2/reviews
WP-05 返回 pid + uptime_s GET /api/v2/sessions/current
WP-06 返回 ok: true POST /api/v2/config/reload
WP-07 CORS preflight — 204 + 正确响应头 OPTIONS
WP-08 CORS localhost origin 设置正确 —
WP-09 limit 参数生效 GET /api/v2/tasks?limit=0
WP-10 读取真实 TASK-*.md 文件 GET /api/v2/tasks
WP-11 读取真实 REVIEW-*.md 文件 GET /api/v2/reviews
WP-12 静态文件服务 — 从 panelDir 提供 index.html 静态资源路由
WP-13 GET /health — 就绪探针（QA I-7）返回 ok:true GET /health

13. Agent 自记录日志体系

CodeFlowMu 在 FCoP 协作目录之外，于 fcop/logs/（复数）写入 Agent 运行时遥测，供 ADMIN 排障、日志中心与用量统计。这与 FCoP 钦定的 fcop/log/（单数，任务归档）语义不同，勿混删。

权威边界说明见仓库内 fcop/logs/README.md（由 codeflowmu-shell/src/logs-paths.ts 的 ROOT_README 生成；可用 codeflowmu-shell/scripts/write-fcop-logs-readme.py 同步）。

目录 文件 用途
fcop/logs/thinking/chat/ thinking-YYYYMMDD.jsonl Chat 会话思维链 / 工具流
fcop/logs/thinking/task/ thinking-YYYYMMDD.jsonl 派单 / 巡查等任务思维流
fcop/logs/usage/ usage-YYYYMMDD.jsonl 每 Run 一条结果摘要
fcop/logs/analytics/ events-YYYYMMDD.jsonl 统一分析账本
fcop/logs/runtime/ runtime-events-YYYYMMDD.jsonl 运维链路事件（门铃 JSONL 冷存储）
fcop/logs/panel-api/ panel-api-YYYYMMDD.jsonl 面板 API 耗时遥测
fcop/chat/ chat-YYYYMMDD.jsonl Direct Chat 持久化（非 fcop/logs/）

实现：codeflowmu-shell/src/web-panel.ts（ThinkingFileLogger、RuntimeEventFileLogger、persistDirectChatMsg）；路径常量见 logs-paths.ts、chat-paths.ts。

13.1 thinking 日志（思维链记录）

  • 写入：SDK 事件管线（sdk.thinking、sdk.assistant、sdk.tool_call 等）按日追加 JSONL。
  • 典型字段：ts、at、event_type、agent_id、session_id、payload（含 run_id、文本片段或工具参数/结果）。
  • 注意：sdk.tool_call 的 stdout/stderr 可能含路径、git status 等敏感信息；长期运行需考虑轮转、截断或 ACL。

13.2 usage 日志（执行结果与费用）

  • 粒度：每轮 Run 结束写一条 sdk.result。
  • 典型字段：status（finished | error）、durationMs、model.id、可选完整 Markdown 小结。
  • 用途：日报、成败统计、里程碑复盘；error 行常无栈，需用同一 run_id 联查 thinking。

13.3 日志 API 接口

Web Panel 暴露只读 API（见 codeflowmu-shell 路由）：

接口 说明
GET /api/v2/thinking/logs 按日/Agent 查询 thinking JSONL
GET /api/v2/usage/today 当日 usage 汇总（Dashboard 用量卡片同源）

13.4 日志查询示例

# 查看今日 thinking 行数
(Get-Content D:\codeflowmu\fcop\logs\thinking\thinking-20260530.jsonl | Measure-Object -Line).Lines

# 筛选 error Run
Select-String -Path D:\codeflowmu\fcop\logs\usage\usage-20260530.jsonl -Pattern '"status":"error"'

13.5 日志的意义

维度 thinking usage
排障 细粒度工具链、模型推理片段 Run 成败一览
合规 可能含命令输出，需脱敏 小结仍可能含路径/配置键名
与 FCoP IPC 非 TASK/REPORT，不参与 lifecycle 同上

详见设计报告：docs/design/FCOP-WORKSPACE-AND-THINKING-LOG-REPORT.md。

13.6 九类协作数据资产（固定边界）

fcop/logs/README.md 与代码中的 collab-assets-v1 将下列九类资产划清职责（路径相对项目根，除非另注）：

# 资产 主要落盘位置
1 任务 fcop/_lifecycle/**/TASK-*.md
2 报告 同生命周期目录 REPORT-*.md
3 日志 fcop/logs/{runtime,analytics,usage,panel-api}
4 门铃 内存 DoorbellBuffer + 写入 fcop/logs/runtime/*.jsonl（无独立 doorbell/ 目录）
5 聊天 fcop/chat/chat-YYYYMMDD.jsonl
6 思考流 fcop/logs/thinking/{chat,task}/thinking-YYYYMMDD.jsonl
7 附件 fcop/attachments/YYYYMMDD/
8 统计 由 analytics / usage / runtime 派生，不另建独立真相源
9 涌现 fcop/internal/eval、emergence-log、ADR、.fcop/proposals 等

13.7 Runtime / Chat 按日 JSONL（P1）

资产 新写入路径 只读兼容（不强制迁移）
Runtime 事件 fcop/logs/runtime/runtime-events-YYYYMMDD.jsonl fcop/logs/runtime/runtime-events.jsonl；.codeflowmu/events/runtime-events.jsonl
Direct Chat fcop/chat/chat-YYYYMMDD.jsonl fcop/chat/chat.jsonl
  • 新写入一律按自然日切文件；读取时合并多文件并按 ts 排序。
  • Panel 启动时 migrateLegacyLogsAssets：若仍存在 .codeflowmu/events/runtime-events.jsonl 且尚无 fcop/logs/runtime/runtime-events.jsonl，会复制到 legacy 单文件（不删源文件）。若你已删除 .codeflowmu/，则不会有这次复制；按日文件会在首次写门铃/运维事件时新建。

13.8 对「删 fcop / .fcop / .codeflowmu 后初始化」的影响

删除 fcop/、.fcop/、.codeflowmu/ 后，行为分两层，不要混为一谈：

阶段 触发条件 会自动出现什么 不会自动出现什么
A · 仅启动 Shell/Panel（未点「一键初始化」） npm start 且能解析到项目根（通常仍有 codeflowmu.team.json 等；无 fcop/fcop.json 时可能仅靠 monorepo 根兜底） Runtime ensureLedgerLayout → fcop/tasks、reports、issues、reviews、attachments、ledger、ledger/views、_lifecycle/{inbox,active,review,done,archive} 及空 ledger/*.jsonl；Shell ensureAdoptedFromSource → fcop/adopted/（从 adoptedSource/）；.codeflowmu/pm-skills.manifest.json；Panel ensureFcopLogsAssetLayout → fcop/logs/ 全套子目录 + 九类 README fcop.json、fcop/shared/（团队宪法）、FCoP v3 完整协议骨架、_lifecycle/inbox 下的 ADMIN 任务
B · UI 一键初始化 环境预检 →「立即部署」→ POST /api/v2/fcop/init Python init_project / init_solo → fcop.json、_lifecycle、shared、规则四件套等；同请求内 ensureLedgerLayout、ensureAdoptedFromSource、codeflowDirs mkdir（logs、chat、internal、scripts 等）；若 logs/README.md 尚不存在会写简短 stub，Panel 下次启动会用 collab-assets-v1 覆盖为完整版 历史 TASK/REPORT/JSONL 内容（删了就没了，除非 git 恢复）

.fcop/：删除后不会被 Shell 自动整树重建；丢失 proposals、drawer、migrations 等本地协作缓存，非运行必需。

.codeflowmu/：删除后 Shell 会部分重建（如 pm-skills.manifest.json、项目级 ~/.codeflowmu/projects/<slug>/ 的 inbox 等与 Runtime 相关的目录，见 §3.4）。旧 .codeflowmu/events/runtime-events.jsonl 删除后无法再通过迁移复制到 fcop/logs/runtime/。

.codeflowmu/agent-skills.manifest.json：删除 .codeflowmu/ 后会丢，但 Shell 启动会在 plantPmSkillManifestIfMissing 之后调用 plantAgentSkillsManifestIfMissing(projectRoot)，从 docs/skills/agent-skills.manifest.json 自动恢复（copy-if-missing，不覆盖已有投影）。若 source-of-truth 也缺失，则只打 warn，不造空文件。

推荐干净初始化顺序（与 §17 一致）：关进程 → 删 fcop/、.fcop/、.codeflowmu/ → START-CODEFLOWMU → 必须先完成 UI 一键 FCoP 初始化（出现 fcop/fcop.json）→ 确认 fcop/adopted/pending/ 含 0001/0002/0003 → 刷新预检 → 再建第一个真实 TASK。仅 npm start 而不做步骤 B，不能当作完整 FCoP 团队接管。

14. FCoP 工具权限分层（防 Token 爆炸）

fcop-mcp 全量 45 个工具若注入每个 Agent，工具定义 alone 约 19,320 tokens；4 席位并发约 77k tokens 仅定义开销。CodeFlowMu 按 FCoP layer 分级白名单，经 FCOP_ALLOWED_TOOLS 传给 codeflowmu-shell/src/fcop-mcp-filter.ts 过滤 tools/list。

定义：packages/codeflowmu-runtime/src/skill/FcopToolProfile.ts。

14.1 问题背景

  • MCP tools/list 会把全部工具 schema 注入模型上下文。
  • DEV/QA/OPS 执行层只需 写 REPORT / ISSUE / 建议，不需要 init、audit、archive 全套。
  • 分层后典型 4 人团队工具定义从 ~77k 降至 ~21k tokens（约 73% 节省）。

14.2 工具分类

Profile 典型角色 工具数（约） Token（约）
executor DEV / QA / OPS 3 1,500
leader PM 28 12,000
governance LEAD-* / 审计 36 15,500
admin 初始化 / 升级 45 19,320

14.3 角色权限配置表

executor（worker） — 仅热路径：

  • write_report、write_issue、drop_suggestion
  • 禁止白名单：claim_task、read_task、finish_task（由 Runtime 注入 TASK + 异步 rename）

leader（PM） — 在 executor 基础上增加：

  • 任务派发：create_task / write_task、list_tasks / read_task
  • 生命周期：submit_task、approve_task、reject_task、archive_task、archive_to_history 等
  • Review / 诊断：write_review、fcop_report、fcop_check、list_reports …

governance — 增加：fcop_audit、fcop_list_alerts、new_workspace …

admin — 全量 + init_project、redeploy_rules、finish_task（legacy）

14.4 Token 节省效果

启动 banner 可打印 tokenSavingsSummary()。示例（PM + DEV + QA + OPS）：

无分层：4 × 19,320 ≈ 77,280 tokens
有分层：12,000 + 3 × 3,000 ≈ 21,000 tokens

14.5 实现架构

sdk-factory.ts
  └─ profileForLayer(worker|leader|…)
       └─ FCOP_ALLOWED_TOOLS=逗号分隔列表
            └─ fcop-mcp-filter.ts（过滤 Python fcop_mcp tools/list）
                 └─ python -m fcop_mcp

热路径阻断（RUNTIME_HOT_PATH_BLOCKED_TOOLS）：claim_task、read_task、inspect_task、finish_task — 不得在 Agent 开工前同步调用。

14.6 配置指南

  • 团队层：codeflowmu.team.json 成员 layer 字段（worker / leader / …）
  • 环境变量：FCOP_ALLOWED_TOOLS（由 Runtime 按 profile 注入，一般无需手改）
  • 升级 fcop-mcp 后若新增工具，需同步更新 FcopToolProfile.ts 各层列表

14.7 Agent 轮换（满 N 会话换 AI）

Panel Team 页可配置单席位最大会话数；达上限后 Runtime 轮换新 session，thinking/usage 仍按 agent_id 归档，便于对比质量。

14.8 Cursor 通行规则（.cursorignore）

.cursorignore 可排除 fcop/logs/ 大体积 JSONL，避免 Cursor 索引拖慢 IDE；不影响 Runtime 写入与 Panel API 读取。

15. Google Gen AI SDK 通道

版本： v0.4.0-alpha 起支持 · 对应代码：GoogleGenAiAdapter.ts

CodeFlowMu 支持 两种 AI 接入通道，通过项目根目录 .env 中的 CODEFLOW_PROVIDER 变量进行无缝切换：

通道 提供者 推荐模型 核心配置项 适用场景
cursor（默认） Cursor API auto / claude-3-5-sonnet CURSOR_API_KEY 稳定生产环境，享受 Cursor 云端高速通道
google Google Gen AI SDK gemini-2.5-flash / gemini-2.5-pro GEMINI_API_KEY + GOOGLE_DEFAULT_MODEL 极客调试、高配额场景、直连 Google API 官网通道

15.1 切换到 Google 通道

要将 CodeFlowMu 从默认的 Cursor 通道切换为 Google Gemini 通道，请按照以下步骤操作：

1. 安装 npm 依赖包

确保 @google/genai npm 依赖已在 codeflowmu-runtime 子包中正确安装：

# 验证依赖包是否已存在
Test-Path "D:\codeflowmu\packages\codeflowmu-runtime\node_modules\@google\genai"

# 若输出为 False，则执行以下命令进行安装（通常 npm run install:all 会自动覆盖此项）
npm install --prefix packages/codeflowmu-runtime @google/genai@latest

2. 配置项目根目录 .env 文件

修改项目根目录下的 .env 配置文件，将其切换为 google 驱动：

# 双通道接入切换
CODEFLOW_PROVIDER=google

# 必填：Gemini API Key（在 https://aistudio.google.com 获取）
GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 可选：指定调用的默认模型（推荐使用 gemini-2.5-flash，兼顾速度与成本）
GOOGLE_DEFAULT_MODEL=gemini-2.5-flash

Note

切换为 google 提供者后，原有的 CURSOR_API_KEY 及 CURSOR_DEFAULT_MODEL 配置可以保留在 .env 中，系统会自动忽略它们，不会造成冲突。

3. 重启 CodeFlowMu 服务

通过 Ctrl+C 终结当前的 Node 运行时，然后重新运行启动脚本：

npm start

若启动 banner 显示如下内容，说明 Google 通道已成功激活：

Cursor SDK     : live (GoogleGenAiAdapter; apiKey from process.env.GEMINI_API_KEY, defaultModel="gemini-2.5-flash")

15.2 Google 通道系统架构

在 google 通道下，CodeFlowMu 运行时通过内置的高性能 McpClient 引擎，实现与底层 Python MCP 协作工具链的 stdio 桥接。整体数据流拓扑如下：

[ADMIN / 网页面板] <---> 发送任务与聊天 <---> [Web Panel (localhost:18766)]
                                                │
                                                ▼ (InboxWatcher 监控)
                                         [TaskDispatcher (任务调度)]
                                                │
                                                ▼ (启动并指派角色)
                                     [GoogleGenAiAdapter.ts (运行时)]
                                                │
                 ┌──────────────────────────────┴──────────────────────────────┐
                 ▼ (懒加载导入)                                                ▼ (注入 MCP 插件)
       [@google/genai SDK]                                            [McpClient 桥接客户端]
                 │                                                             │
                 ▼ (Function Calling 交互)                                     ▼ (Stdio Pipe, 无缓冲)
       [Gemini API 官方大脑]                                          [fcop-mcp-filter.ts 过滤代理]
                                                                               │
                                                                               ▼ (过滤 tools/list, 仅保留白名单)
                                                                      [python -u -m fcop_mcp 真实进程]

15.3 MCP 工具挂载与注入

在 Google Gemini SDK 体系中，本地 MCP 工具（如 FCoP 协作工具集）被映射为 Function Calling（函数调用） 协议。Google 工具运行时（GoogleGenAiAdapter）负责：Gemini schema → one-shot MCP 归一化 → tool dedupe → tool result 回灌 → stream 事件；与 Cursor SDK 的 MCP 注入语义对齐，但 不依赖 .cursor/rules。

  1. Schema 转换：GoogleGenAiAdapter 内置的 McpClient 在握手初始化阶段读取 Python 端暴露的工具定义，并将其转换为 Google 官方要求的 FunctionDeclaration 规范 JSON 结构。
  2. 工具注入：在向 Gemini 发起对话请求时，转换后的工具列表被注入到 generationConfig.tools 中。
  3. 闭环调用：当 Gemini 判定需要使用工具时，会返回 functionCalls 响应；GoogleGenAiAdapter 拦截该响应，通过 stdio 发送给底层的 Python MCP 进程执行，并将执行结果封装为 functionResponses 传回 Gemini。

Tip

关于 MCP injector 的说明： Web Panel 中若显示 MCP injector: mode="stub" (0 agents mounted) 属于正常设计现象。该计数器仅用于追踪老版本 Cursor SDK 驱动分支的挂载状态。Google 通道使用内置的 McpClient 直接在 GoogleGenAiAdapter 内部完成了工具挂载，在功能上是完全等价的。

15.4 极客排障：三大底层硬核 Bug 诊断与治理

在接入 Google Gen AI SDK 并在本地桥接 MCP 时，由于 Stdio 流控制、Windows 进程管理、JSON-RPC 类型约束等底层细节差异，极易遭遇严重的死锁与崩溃。以下是三大底层 Bug 的成因剖析与最终修复方案：

1. 套娃式 Python Stdio 缓冲死锁

  • 现象：当 Node.js 试图拉起由 Python 编写的 MCP 服务时（如基于 fastmcp 开发的 fcop_mcp），界面无限挂起，并在 15 秒后触发 MCP Tool call timeout (initialize) 握手超时退栈。
  • 根因：Python 引擎在重定向 sys.stdout 且输出管道不是 TTY（例如通过 Node.js spawn 挂接的 Pipe 管道）时，默认会自动切换为 全缓冲（block buffered） 模式。这意味着 Python 进程不会实时将 JSON-RPC 消息刷入 stdin/stdout，而是积压在内存缓冲区中。Node.js 无法在 15 秒超时前拿到握手响应，宣告死锁。
  • 套娃危机：如果中间过了一层代理（如 fcop-mcp-filter.ts 过滤层），只要第二级 Stdio 没有配置无缓冲，缓冲死锁依然会在第二级发生。
  • 治理方案：在所有 Stdio 管道拉起 Python 进程时，全线强制关闭标准流缓存：
    1. 在 Python 启动参数最前插入 -u 选项（即 python -u ...）。
    2. 为子进程注入 PYTHONUNBUFFERED=1 环境变量。
// GoogleGenAiAdapter.ts 中的 Stdio 加固修复代码：
const isPython = cmd.toLowerCase().includes("python") || this.command.toLowerCase().includes("python");
if (isPython && !spawnArgs.includes("-u")) {
  spawnArgs.unshift("-u"); // 强制开启无缓冲模式
}

const env = { 
  ...process.env,
  PYTHONUNBUFFERED: "1" // 环境变量双重保险
};

2. Windows 下 Monorepo tsx 引导瞬退（退出码 1）

  • 现象：Node 进程以退出码 1 瞬间挂掉（McpClient process exited with code 1），控制台无任何 stderr 报错信息。
  • 根因：为了避免 Windows 下直接 spawn 执行 tsx 抛出 ENOENT 错误，通常会将命令转换为 node --import tsx ... 启动。但在 Monorepo 多包架构中，运行时以项目根目录为 cwd 启动，而 tsx 仅安装在 codeflowmu-shell 的子依赖中。Node.js 的 --import 是在早期引导阶段（Bootstrap phase）由 ESM 加载器处理的，在此阶段 ESM 加载器会完全忽略 NODE_PATH 环境变量，从而因 Cannot find module 'tsx' 抛出致命异常瞬间暴毙。
  • 治理方案：放弃不稳健的 node --import tsx 拼接，改由 npm 自动创建的 .bin/tsx.cmd 批处理软链接 进行安全拉起，并在 Windows 下注入 { shell: true } 选项：
    1. 路径锁定：动态搜寻并锁定子包内绝对存在的本地 tsx.cmd 路径（例如 d:\codeflowmu\codeflowmu-shell\node_modules\.bin\tsx.cmd）。
    2. 安全引导：利用 npm 自身的引导机制去解析局部模块作用域，完全规避了 ESM 加载器的引导死穴。
// GoogleGenAiAdapter.ts 中的 Win32 tsx.cmd 修复代码：
let useShell = false;
if (process.platform === "win32" && cmd === "tsx") {
  const rootDir = this.cwd || process.cwd();
  const localTsxCmd = path.join(rootDir, "node_modules", ".bin", "tsx.cmd");
  const shellTsxCmd = path.join(rootDir, "codeflowmu-shell", "node_modules", ".bin", "tsx.cmd");
  
  if (fs.existsSync(localTsxCmd)) {
    cmd = localTsxCmd;
    useShell = true;
  } else if (fs.existsSync(shellTsxCmd)) {
    cmd = shellTsxCmd;
    useShell = true;
  }
}

// 启动进程：
this.process = spawn(cmd, spawnArgs, {
  cwd: this.cwd || process.cwd(),
  env,
  ...(useShell ? { shell: true } : {}) // Windows 批处理执行必须开启 shell: true
});

3. JSON-RPC 2.0 通告（Notification）强类型校验冲突

  • 现象：完成 initialize 握手后，客户端向 Python MCP 发送初始化确认包 notifications/initialized，但 Python 服务端（如基于 Pydantic 校验的 fastmcp 引擎）瞬间报错崩溃，提示 Invalid request parameters 严重异常。
  • 根因：根据标准的 JSON-RPC 2.0 规范：
    • 请求 (Request)：包含自增的 id 字段，服务端必须响应并返回。
    • 通告 (Notification)：绝对不能包含 id 字段，且服务端绝不应该回复任何内容。 如果使用通用的客户端 call("notifications/initialized", {}) 发送，该数据包会被默认包装为 Request 并携带自增 id。由于 notifications/initialized 并不是服务端注册的合法“可请求方法名”（它被设计为通告），这直接导致 Pydantic 校验器由于类型错误判定该请求不合法，断开连接。
  • 治理方案：在 Node 客户端中增设专属的通告发送通道 notify，强制剥离 id 属性，实现即发即弃的非阻塞通告：
// GoogleGenAiAdapter.ts 中的 JSON-RPC 通告修正：
notify(method: string, params: any): void {
  if (!this.process) return;
  const notification = {
    jsonrpc: "2.0",
    method,
    params, // 绝对不带 id 属性！
  };
  this.process.stdin.write(JSON.stringify(notification) + "\n");
}

15.5 Agent 显示「异常」排障与健康体检手册

如果您在 Web Panel UI 的 Team 页面中发现 Agent 全部显示红色 异常 状态，或者聊天时系统返回 (无回复)，请按照以下自检步骤进行全面体检：

诊断路径一：Gemini 官方 API 连通性直连校验

首先排除本地网络、API Key 有效性以及代理配置的问题，在 PowerShell 中直接调用 Google 官方 API：

curl -s "https://generativelanguage.googleapis.com/v1beta/models?key=$env:GEMINI_API_KEY"
  • 期望结果：返回一个长 JSON 字符串，其中包含 "name": "models/gemini-2.5-flash" 等模型列表。
  • 若报错或无响应：说明本地到 Google 官方服务器的网络不通，或者您的 GEMINI_API_KEY 已过期或配额耗尽。由于 Google Gen AI SDK 运行稳定，无需配置任何中转 BaseURL，建议优先保证网络直连通畅。

诊断路径二：检查 @google/genai npm 包完整性

如果 API Key 正常，但启动时 Agent 状态依然报错，请检查 node_modules 包：

# 运行环境自检命令
node -e "try { require('@google/genai'); console.log('✅ SDK 模块加载正常！'); } catch(e) { console.error('❌ SDK 加载失败，原因：', e.message); }"
  • 若提示 Cannot find module '@google/genai'：说明依赖包在 runtime 模块中缺失。请立即运行一键修复命令： 
    npm install --prefix packages/codeflowmu-runtime @google/genai@latest

诊断路径三：查看实时错误流日志

在启动 npm start 终端中，密切关注带有 [GoogleGenAiAdapter] 标志的实时错误流：

  • [GoogleGenAiAdapter] McpClient stderr: ...：此日志包含 Python 端及 Stdio 通道暴露出的最真实错误栈。
  • [GoogleGenAiAdapter] McpClient process exited with code X, signal Y : 子进程退出状态码。如果为非 0，请检查 PYTHON_BIN 环境变量是否指向了正确的 Python.exe 路径。

15.6 已知限制与演进路线

目前 Google Gemini 通道在 CodeFlowMu 中已达到工业级稳定性，但与老版本的 Cursor SDK 通道相比，依然存在部分小范围差异与已知局限性：

限制项 现状与表现 终极修复方案 / 规避手段 演进计划
多模态输入 目前在 Web Panel 聊天中只支持文本交互，暂不支持图片 / 文件直接拖拽上传。 可先将要引用的文件内容复制到文本框中，或将任务产物保存在 workspace/ 中供 Agent 自动读取。 计划在 v0.5.0-alpha 版本支持多模态 Payload 投递。
Token 费用估算 由于 Google API 采用极低的价格体系，usage.jsonl 日志中记录的 USD 费用数字目前仅作为等额估算参考。 请以 Google AI Studio 控制台 中展现的真实账单消耗为准。 计划在下一阶段优化 Gemini API 专用的 Token 精确费用计算器。
并发工具调度 相比 Cursor SDK 允许并行的多轮次工具调用，Google SDK 对 Stdio 并发读写的时序要求更为苛刻。 已在 GoogleGenAiAdapter 内部实现互斥信号量锁（Mutex Lock），保证单实例 stdio通道时序安全。 持续观测并发压力，保证极限多角色高吞吐下的安全性。

15.7 独立 Python Headless 运行时（FCoP SDK 引擎）

为了彻底摆脱 IDE 窗口焦点与 Electron 睡眠限制，项目根目录下已成功嵌入了完全独立的 Python FCoP SDK 引擎。该引擎与 Node.js 网页端（npm start）共享同一套 FCoP 3.0 协议规范和本地磁盘任务账本，形成了完美的混合双引擎架构。

1. SDK 核心包结构

FCoP SDK 作为一个完全独立的微服务 Agent 开发包，放置在项目根目录 fcop_sdk/ 下：

  • protocol.py：支持符合 FCoP 规范的 Markdown Frontmatter 的原子读写与 Patch。
  • adapters.py：基于 urllib 的零依赖 Google Gemini REST 接口代理适配器（支持 .env 代理直连与自定义 BaseURL）。
  • mcp_client.py：多线程 JSON-RPC 2.0 stdio 管道客户端，可在 Python 中自动拉起并挂载标准的 MCP 服务。
  • agent.py & runner.py：内置多角色（PM/DEV/OPS/QA）标准 FCoP Playbook，并利用 watchdog（或无依赖的 Polling 引擎）实现毫秒级的门铃监听与任务认领。
  • kernel.py：严格的状态机约束器（FCoPStateEnforcer，阻止生命周期越界，违规自动生成 P0 ISSUE）与心跳租约、Journal 恢复引擎。

2. 如何启动独立 Agent 进程

您可以在根目录下直接通过 Python 命令拉起任意角色的常驻守护进程：

# 启动 OPS 自动化运维与巡检 Agent
python run_agent.py OPS

# 启动 PM 调度决策 Agent
python run_agent.py PM

# 启动 DEV 自动编码 Agent
python run_agent.py DEV

3. 与 npm start 的协同无缝闭环

运行 npm start 开启网页端控制面板的同时，在后台启动 python run_agent.py OPS：

  1. 门铃触发：当您在网页端派发任务时，一个 TASK-*.md 任务文件落入 fcop/_lifecycle/inbox/。
  2. 原子认领：Python 守护进程瞬间捕捉到新任务，自动检验并利用 FCoPStateEnforcer 强行将文件状态 Patch 为 active。网页端面板上的卡片会在您眼前毫秒级滑入 "Active（进行中）" 状态滑轨！
  3. 工具调用：Python Agent 驱动官方 Gemini 大脑，通过 Stdio 管道拉起本地 fcop_mcp 完成巡检与执行。
  4. 回执与生命周期：执行完成后写 REPORT-*.md，经 submit_review → approve_review → archive_task 推进（勿默认 finish_task 直进 done）。网页面板随 lifecycle 目录同步展示 Review / Done / Archive。

4. 网络连通性调试（国内直连）

若在执行 test_fcop_sdk.py 或启动 Agent 时遇到 Google API 连通超时（<urlopen error timed out>），请在项目根目录 .env 中进行以下配置之一：

  • 方案 A（网络代理）：取消第 18/19 行的注释，配置您的本地 Clash 等代理端口（例如 HTTPS_PROXY=http://127.0.0.1:7890）。
  • 方案 B（中转域名）：取消第 22 行的注释，配置中转 Base URL（例如 GEMINI_BASE_URL=https://api.openai-proxy.org 或您的其他中转站点）。

16. adopted/pending、生命周期权责与日常操作速查

本章从 ADMIN / PM 日常视角汇总 §5、§11 与 FCoP-PENDING-0001/0002/0003 的要点，便于快速对照，不替代 pending 正文与实现文档。

16.1 三句话记住 adopted/pending

概念 含义
正式 FCoP 当前 bundled 版本仍为 3.2.5（.cursor/rules/fcop-rules.mdc）
adopted/pending fcop/adopted/pending/ 下「已采用 · 运行时生效 · 待 ADMIN 决定是否并入正式版」的补充条款
谁必须遵守 CodeFlowMu 运行时、Agent、PM 现在就要遵守；是否升 3.2.6 由 ADMIN 决定

条款：0001-lifecycle-authority-review-done-archive.md 管权责；0002-fixed-work-folders-and-ledger.md 管双轨与 ledger；0003-task-relations-and-evidence-ownership.md 管任务关系、证据归属与 Tree。实现细节见 docs/CODEFLOWMU_LIFECYCLE_AUTHORITY_IMPLEMENTATION.md 与 docs/panel-task-lifecycle-ui-rules.zh.md。

16.2 生命周期：谁能在哪一步动文件

目录位置 = 当前状态（fcop/_lifecycle/）。热路径：

inbox → active → review → done → archive → history/
         ↑__________|  reject_review
         ↑____________________ reopen_task（done → active，须授权）
阶段 目录 典型动作 谁来做
待领 inbox/ 写 TASK ADMIN / PM 派单
执行 active/ 执行、写 REPORT 执行者（PM 或 DEV/QA/OPS）
待验 review/ submit_review 执行者（须已有 REPORT）
已验 done/ approve_review done_authority（见下表）
封存 archive/ archive_task archive_authority
深归档 history/YYYY-MM-DD/ archive_to_history 同上

主线 vs 支线（默认权责）

任务线 执行者 REPORT 给谁 默认 done 默认 archive
主线 ADMIN-to-PM PM ADMIN ADMIN ADMIN
支线 PM-to-DEV/QA/OPS Agent PM PM PM

禁止： 无 REPORT 或未 submit_review 就进 done；未 done 就正常 archive；archive 后再打回（force_archive 除外，须原因且 sealed）。

0002 真相源（Panel / API 读数顺序）

  1. _lifecycle/ 物理 stage
  2. TASK YAML state / transitions
  3. fcop/tasks/ IPC 副本
  4. ledger/tasks.jsonl 的 bucket（Kanban ledger_scope）
  5. Panel 缓存

强行归档（force_archive）：inbox / active / review → archive，须 archive_reason；ADMIN 对主线可作废未验收任务。与正常 archive_task（须 done/）不可混用。

勿用默认路径： finish_task 会跳过 review/done 权责，仅 legacy 兼容。

0003 任务关系速记：

关系 字段 是否画进 Tree 是否阻止归档
子任务 parent 是 子任务在 inbox / active / review 时阻止，返回 CHILD_TASKS_OPEN
接着做 / 引用 references 否 否
同一任务线 thread_key 否 否

16.3 聊天：派任务 vs 唤醒

你想做什么 正确方式 错误方式
开一项新的可追溯工作 Chat「快捷派任务」或写 TASK → inbox/ 只在聊天里说「你去修 X」不落文件
让 Agent 继续已有 TASK 聊天唤醒：wakeAgent(agentId, taskId, message) 再建一条重复 TASK
宣告工作完成 write_report + submit_review 聊天里说「做完了」

详见 §11.2。正式验收信号只有 REPORT 文件 + lifecycle 推进，不是 Chat 文本。

16.4 PM 派 OPS / DEV / QA（支线）

  1. PM 写 TASK-*-PM-to-OPS.md（或 DEV/QA）→ inbox/
  2. Runtime 注入 TASK + pending 条款 → Agent 在 active/ 执行
  3. Agent 写 REPORT-*-OPS-to-PM.md → submit_review
  4. PM 在 Panel 或 MCP 执行 approve_review → done/
  5. PM 执行 archive_task（须已在 done/ 且满足 frozen 语义）；作废未验收任务时用 force_archive_task（须原因）

PM 不得替 ADMIN 对主线 ADMIN-to-PM 任务自行 approve_review 进 done（除非 TASK 显式 delegated_done: true，且仍不自动获得 archive 权）。

能力边界：下面 §16.4.1–§16.4.4 是 CodeFlowMu Runtime / Panel 的执行治理规则，不是 FCoP 协议规则。它不会修改 _lifecycle 桶语义、TASK/REPORT 命名、ledger 历史或验收权责。

16.4.1 PM 顺序推进

默认支线顺序为 DEV → OPS → QA。PM 每次只允许唤醒当前必要角色：

当前状态 PM 可以 wake PM 不可以 wake
DEV 尚无 done REPORT DEV OPS、QA
DEV 已 done，OPS 尚未 done OPS QA
DEV、OPS 均已 done QA —

被拦截时 Runtime 返回：

{
  "action": "wake_blocked",
  "reason": "sequential_dispatch_guarded",
  "current_leg": "DEV",
  "blocked_target": "OPS",
  "next_allowed_agent": "DEV"
}

这里的 done 必须来自已有任务链中的真实 REPORT / ledger 状态。Runtime 不会伪造完成状态，也不会为了恢复而新建重复任务。

16.4.2 PM 限流停手

同一 task_id + agent_id 在一次异常窗口内：

  • PM 最多 wake 一次；必要时最多 recover 一次。
  • 收到 wake_throttled、SDK_CIRCUIT_OPEN、SdkCooldownActiveError 或 SDK cooldown 后，PM 立即进入 PM_STOP。
  • PM_STOP 后不安排延迟连续 wake，也不连续调用 recover。
  • 单纯限流时由 PM 等待冷却；不要立即 force recovery。

返回字段：

{
  "action": "wake_throttled",
  "remainingMs": 4200,
  "untilMs": 1781500000000,
  "cooldownReason": "SDK_CIRCUIT_OPEN",
  "policy": "PM_STOP"
}

Panel 会显示：“PM 已停手，等待冷却 / ADMIN 恢复”，并展示 remainingMs 与 cooldownReason。此时“恢复执行”按钮会隐藏，避免暗示 PM 连续 recover。

16.4.3 ADMIN force recovery

以下状态不由 PM 硬冲，统一升级 ADMIN：

  • stale_busy_no_session
  • session_unsettled
  • agent_running 但任务仍在 inbox
  • busy 标记残留
  • recover 后仍无有效 new_session_id
  • wake_throttled + stale_busy_no_session

Runtime 返回 policy: ESCALATE_ADMIN_FORCE_RECOVERY；Panel 显示 “建议 ADMIN 一键解除卡死”。

ADMIN 在任务详情或队列卡片点击 “一键解除卡死”。Panel 调用：

POST /api/v2/tasks/:taskId/admin-force-recovery
Content-Type: application/json

{
  "role": "DEV",
  "agent_id": "DEV-01",
  "thread_key": "原 thread_key",
  "operator": "ADMIN"
}

force recovery 依次清理等待/失败标记、SDK cooldown、残留 session 与 busy 状态，必要时轮换 SDK agent，再对原 task_id重新启动 session。成功后清除该 task + agent 的异常窗口，沿原任务链继续；不创建重复 TASK。

16.4.4 实时操作输出

可见位置：

  • Panel 最近运行时动作 / 日志中心
  • Server-Sent Events（Panel 实时流）
  • fcop/logs/runtime/panel-actions-YYYYMMDD.jsonl

关键事件：

action 关键字段 含义
wake_downstream task_id、target_agent、current_leg、result、reason PM 发起当前腿 wake
wake_blocked reason=sequential_dispatch_guarded、current_leg、blocked_target 后续腿被顺序门禁拦截
wake_throttled cooldownReason、remainingMs、untilMs、policy=PM_STOP PM 遇限流停手
recovery_required reason、agent、task_id、policy=ESCALATE_ADMIN_FORCE_RECOVERY stale/session 异常交 ADMIN
pm_stop reason、next_owner、message 明确记录 PM 不再重复 wake/recover
admin_force_recovery before_state、after_state、result、new_session_id ADMIN 恢复前后真实状态
resume_original_chain task_id、current_leg、next_allowed_agent 恢复后继续原链

排障时先看 policy：

  • PM_STOP：等待 untilMs 指定的冷却结束；若同时出现 stale/session 异常，再交 ADMIN。
  • ESCALATE_ADMIN_FORCE_RECOVERY：ADMIN 点击“一键解除卡死”，不要让 PM 重复 recover。
  • sequential_dispatch_guarded：等待 current_leg 真实完成，再推进 next_allowed_agent。

16.5 EVAL：观察员，不是队友

项 规则
定位 独立观察；不派 TASK、不写团队可见 REPORT、不替 PM/ADMIN 做 done/archive
输出 OBSERVATION-*.md → fcop/internal/eval/
受众 默认只给 ADMIN；不进入 PM 团队汇总链
ADMIN 处置 忽略 / 继续观察 / 采纳 / 转 TASK / 转 ISSUE / 沉淀 shared/

详见 §11.7。

16.6 日常操作速查（ADMIN）

场景 建议步骤
开工 npm start → Panel 仪表盘确认 root → 门铃看 inbox
给 PM 派活 写 TASK-*-ADMIN-to-PM.md 或 Chat 快捷派任务
PM 汇报后验收 读 REPORT → approve_review 或 reject_review
主线收尾 done/ 后 archive_task → 可选 archive_to_history
高风险任务 Approvals 队列处理 needs_human REVIEW → mark_human_approved
PM 显示已停手 看 policy：仅限流则等冷却；ESCALATE_ADMIN_FORCE_RECOVERY 则点任务详情 “一键解除卡死”
恢复后检查 最近运行时动作应出现 admin_force_recovery → resume_original_chain，并包含新的 session_id
看 Agent 在想什么 Chat 勾选「显示思考过程」或查 fcop/logs/thinking/
协议合规 fcop_audit / Panel 环境预检；告警见 Doorbell

16.7 相关章节索引

主题 章节
完整 lifecycle 流程图 §5.2
pending 0001 / 0002 §5.3、fcop/adopted/pending/0001-*.md、0002-*.md
Panel 生命周期 UI（物理路径、三态 Tab、分组） panel-task-lifecycle-ui-rules.zh.md、§11.3–11.4
MCP 工具与别名 §6.1（含 force_archive_task）
Panel 各页操作 §11
PM 顺序推进 / 限流停手 / force recovery §16.4.1–§16.4.4
工具权限分层 §14
thinking / usage 日志 §13
干净初始化 / adopted 源 §17、CODEFLOWMU_CLEAN_INIT_RUNBOOK.md

17. 干净初始化（从空现场验证）

用于从空现场重新启动 CodeFlowMu，确认系统能自动初始化目录、从 adoptedSource/ 填充 fcop/adopted/pending/，并跑通真实任务链。

完整步骤、路径表与 12 项验收清单见 docs/CODEFLOWMU_CLEAN_INIT_RUNBOOK.md。下文为操作手册摘要。

17.1 可删与不可删（摘要）

类别 路径
必删（运行现场） fcop/、.fcop/、.codeflowmu/
可选（临时） .pytest_cache/、testtemp/、scratch/、workspace/、fcop_events.jsonl、.tmp-manual-extract.txt
禁止删除 adoptedSource/、packages/、codeflowmu-shell/、codeflowmu-desktop/、fcop_sdk/、scripts/、docs/、tests/、vendor/、node_modules/、.venv/、.cursor/、.git/、.env、package.json、START-CODEFLOWMU.*、D:\FCoP\
勿删（本地私有，非运行现场） private/gateway-ops-guide.md — Gateway SSH 密码指南；删后 Panel 一键发布与 sync_mobile_static.py 会报 PUSH_PASSWORD_GUIDE_MISSING。该目录在 .gitignore，换机需从模板重新复制

adoptedSource/ 是 fcop/adopted/ 的唯一初始化源；Shell 在 fcop/adopted/ 不存在或为空时从该目录 copy-if-missing 复制，不覆盖已有 adopted 文件。源目录缺失时环境预检失败，不会生成空 adopted。

17.2 操作顺序

  1. 关闭 Shell、Panel、Runtime watcher 与各角色会话。
  2. 删除 fcop/、.fcop/、.codeflowmu/（可选删临时目录，见 runbook）。
  3. 启动 START-CODEFLOWMU.bat 或 START-CODEFLOWMU.ps1（等同仓库根 npm start）。

17.3 启动后必须存在的目录（摘要）

协议 + 账本（ensureLedgerLayout / 一键 init 内调用）

  • fcop/tasks/、reports/、issues/、reviews/、attachments/、ledger/、ledger/views/
  • fcop/_lifecycle/{inbox,active,review,done,archive}/
  • fcop/fcop.json —— 仅 一键 init（init_project / init_solo）创建；仅启动 Shell 不会生成

adopted（Shell 启动 ensureAdoptedFromSource）

  • fcop/adopted/pending/ 含 0001-lifecycle-authority-review-done-archive.md、0002-fixed-work-folders-and-ledger.md（与 adoptedSource/pending/ 一致）

CodeFlowMu 数据资产（Panel 启动 ensureFcopLogsAssetLayout + 一键 init 的 codeflowDirs）

  • fcop/logs/ 及 thinking/chat、thinking/task、usage、analytics、runtime、panel-api
  • fcop/logs/README.md（九类资产说明；完整版在 Panel 启动后写入）
  • fcop/chat/（按日 chat-*.jsonl 在首次聊天持久化时创建；目录可在 init 时先建好）
  • fcop/internal/、fcop/scripts/（一键 init 建空目录）

.codeflowmu（部分自动；删整个目录后旧 JSONL 不可恢复）

  • events/、pm-governance/、report-watcher/、pm-skills.manifest.json（manifest 可由 Shell 补种）

按日 JSONL 文件：runtime-events-YYYYMMDD.jsonl、chat-YYYYMMDD.jsonl 等不必在初始化瞬间存在；有运行写入后才会出现。

17.4 验收与失败判断（摘要）

验收：新建真实 TASK → Panel 可见 → PM 收单 → 派 DEV → wake → REPORT → PM review → PM 回 ADMIN → 任务总线 thread → attachments → wake-chain → 首页流畅（共 12 项，见 runbook §五）。

缺失 含义
fcop/adopted/pending/ adopted 初始化失败
fcop/tasks/ 等 + ledger/views/ + _lifecycle/ 基础目录初始化失败
.codeflowmu/pm-skills.manifest.json PM skills 初始化失败

一句话： 可删 fcop、.fcop、.codeflowmu 与临时缓存；不可删 adoptedSource 与源码环境；仅启动会重建 ledger、_lifecycle、fcop/logs/ 子树、adopted、pm-skills.manifest；完整 FCoP 团队还须 UI 一键初始化 得到 fcop.json 与 shared/。

手册版本：2026-06-16 · CodeFlowMu v0.4.4-alpha · 增补：Mobile Gateway 私有 SSH 指南（private/gateway-ops-guide.md）、Panel 一键发布 PWA、与旧 Bridgeflow 中继文档脱钩。此前：2026-06-15（PM 顺序推进、限流停手、ADMIN force recovery）；交叉引用 panel-task-lifecycle-ui-rules.zh.md、PWA_RELEASE.md。