架构设计
架构设计是 men（门）Agent 团队的系统蓝图：以 1 个 primary 编排核心与 5 个 subagent 构成星型协作拓扑，通过 10 步编排协议、双层验证体系与自主学习回路，实现从一句话任务到可交付产物的全流程闭环。
协作拓扑
6 个角色通过 men（门）形成星型拓扑：men 是唯一接收用户指令的入口，也是唯一能 spawn 子任务的编排核心。
| 源 | 关系 | 目标 | 说明 |
|---|---|---|---|
| 用户 | 唯一指令入口 | men（门 / primary） | 用户只与 men 对话，所有输入先经 men 分诊 |
| men | spawn task | si（思 / thinker） | 思考与知识管理 |
| men | spawn task | ji（记 / engineer） | 代码与工程 |
| men | spawn task | chi（持 / investor + judge） | 投资分析与独立评审 |
| men | spawn task | yi（艺 / prompt-engine） | 文生图与审美 |
| men | spawn task | xun（寻 / researcher） | 搜索与研究 |
| chi | fresh-context judge | ji（记） | 独立语义复核（虚线关系） |
| chi | fresh-context judge | yi（艺） | 独立语义复核（虚线关系） |
| men | 汇总四段报告 | 用户 | 任务结果最终回流用户 |
- men 唯一 primary：用户只与 men 对话，所有用户输入先经 men 分诊。
- men 唯一 spawner：5 个 subagent 之间禁止互相 spawn（无嵌套）。
- chi 双重角色：既是投资分析角色，又是所有 analyze / team 任务的独立 Judge。
来源：docs/architecture.md · 一、协作拓扑
编排流程
主协议为 10 步（CERTAINTY → TRIAGE → PLAN → DISPATCH → COLLECT → EVALUATE → VERIFY → REPORT → LOOP），M7 新增第 10 步 LEARN，合计 10 步：
| 步 | 节点 | 关键动作与分支 |
|---|---|---|
01 | CERTAINTY 需求确认 | 任务模糊时先向用户追问，直到明确才开工 |
02 | TRIAGE 意图分诊 | 四类意图判定：search / analyze / team / hyperplan |
03 | PLAN si 规划 | team 类 spawn si 产出 plan envelope；hyperplan 类先深度思考多角度方案再交 si |
04 | DISPATCH Wave 调度 | ≤4 并行 / 依赖串行；search 类直接分发 xun，analyze 类单专家 + chi judge |
05 | COLLECT 收集产物 | 收集子 agent 返回结果与落盘产物 |
06 | EVALUATE si 回评 | 产出回传 si 做质量评估，si 只评不改 |
07 | VERIFY 双层验证 | verify.mjs 五项机械检查全 PASS 后，chi fresh-context 语义复核 |
08 | REPORT 汇总汇报 | 四段模板：结论 → 关键信息 → 来源/证据 → 未决问题 |
09 | LOOP 循环重试 | 验证失败回到失败点重试，≤5 次；超过 5 次触发 GATE_EXHAUSTED 报卡住；全部通过则任务完成 |
10 | LEARN 自主学习（M7） | 从事件流提取经验写入知识库；best-effort，不阻塞 REPORT |
来源：docs/architecture.md · 二、编排流程（ultrawork）
验证体系
双层验证：机械检查识破假文件，语义复核识破假内容。两层全部通过才算完成。
| 层 | 工具 | 检查内容 | 判定依据 |
|---|---|---|---|
| 第一层 | verify.mjs | 五项机械检查：output-exists（产物存在）/ secrets（密钥扫描）/ todo-scan（TODO 计数）/ structure（结构合法）/ gate-exit-code（脚本退出码） | 汇总 JSON，退出码非 0 即 FAIL |
| 第二层 | chi judge | fresh-context 独立语义复核 | 只核对实际产物文件，不信自述 |
失败回环：任一机械检查 FAIL 或 chi 判定 FAIL，均回到失败点重试（不从头），重试上限 5 次； chi 连续 3 次失败触发
BLOCKED → 写入 blocker.raised 事件并报卡住。 通过则写入 gate.passed 事件；全部事件落入 events.jsonl 审计留痕。门禁与审计脚本
- gate.mjs：stop-hook 门禁，白名单 typecheck / test / lint，60s 超时，强化次数上限 5。
- event.mjs：append-only events.jsonl，支持 append / list / replay / validate 四子命令。
- 全部纯 Node 零依赖，Windows pwsh 兼容。
学习回路（M7）
- 任务完成后由 men 或 chi 触发 LEARN，事件流进入
learn.mjs（L0 机械聚合 + L1 规则分类），经验写入knowledge/errors/（错误模式）与knowledge/patterns/（协作模式）。 - 评估侧由
eval-metrics.mjs从 events.jsonl 计算 8 项 KPI（最近 10 次任务窗口），输出通过率、回归率、平均耗时等指标。 - 两者均 best-effort：命令失败不阻塞主流程。
来源：docs/architecture.md · 三、验证体系 · 学习回路（M7）
关键目录结构
仓库按职责分层组织，脚本全部纯 Node 零依赖：
| 路径 | 内容 |
|---|---|
AGENTS.md | 项目级共享规则（红线 / Charter / 目录结构） |
opencode.json | default_agent: men；不含 MCP 配置（由 CC Switch 统一管理） |
.opencode/agent/ | 6 个 agent 定义：men（门）/ si（思）/ ji（记）/ chi（持）/ yi（艺）/ xun（寻） |
.opencode/skills/ | 15 个技能包（chi-invest / chi-judge / ji-frontend-design / ji-github / ji-l1-verify 等） |
.opencode/command/ | 3 个自定义命令：ultrawork.md / verify.md / hyperplan.md |
scripts/ | verify.mjs（五项机械检查）/ gate.mjs（门禁）/ event.mjs（事件审计）/ learn.mjs / eval-metrics.mjs 等纯 Node 零依赖脚本 |
docs/ | PRD.md / architecture.md / governance.md / learning-architecture.md / guide/ / research/ |
knowledge/ | 团队知识库：errors/（错误模式）/ patterns/（模式库）/ decisions/（决策记录） |
.agents/state/ | sessions/（events.jsonl 事件审计）/ gates/（gate 状态文件）/ learn/（学习队列） |
.github/ | workflows/ci.yml、PR/Issue 模板、CODEOWNERS、dependabot.yml 等 |
来源：docs/architecture.md · 四、目录结构
设计决策
摘自技术决策记录表（D1–D19），重大变更前必读 docs/research/00-m0-synthesis.md：
| 编号 | 决策 | 状态 |
|---|---|---|
| D1 | men 唯一 primary，用户只与 men 对话 | 已落地 |
| D2 | men 唯一 spawner，subagent 禁止嵌套 spawn | 已落地 |
| D3 | 机械验证优先，拒绝 LLM 自评 | 已落地 |
| D4 | 双层验证：verify.mjs 机械 + chi fresh-context 语义 | 已落地 |
| D5 | M1 先不做插件，OpenCode 原生 agent 定义 + command 起步 | 已落地 |
| D8 | 强化次数上限 5 次，超限诚实报卡住 | 已落地 |
| D12 | 技术栈 TypeScript + Bun（脚本侧用纯 Node） | 已落地 |
| D13 | 自主学习回路：events.jsonl → learn.mjs → errors/ + patterns/ | 已落地 |
来源：docs/architecture.md · 五、技术决策记录