docs 索引

文档按状态分为三个目录：

• done/ — 描述已实现 / 当前有效的架构与功能的文档（含长期参考手册）。
• todo/ — 当前正在推进的路线图/设计草案。
• todo/future/ — 尚未实现、但不是当前重心的待办（暂缓，等主线腾出手再回来处理）。

判断依据：文档正文的显式「状态」标记（✅ 已完成 / 已实现 vs 📝 设计中 / 未实现）、未勾选的 checklist，以及与代码库实际实现的交叉核对（见各条目备注）。

当前主线：Graph Agent 架构重构（27-graph-agent-architecture.md）。 该系列已完成的阶段文档（P1 / P2 / P3 收尾 P3C）移入 done/，其余非主线待办在 todo/future/。 当前未完成的是：P3B 真跑跑道的几条验收、P3/P4 那笔「真实路径 smoke 进 CI」的欠账、P4（未实现）、28-followups。

done/

文件	说明
LEMONBOSS-SYSTEM-DESIGN.md	系统设计主索引 v2.0，含 27 章 system-design/ 的总目录
architecture-v5.md	v5.3 架构方案，Phase 1-6 已完成（Phase 7 认知架构条目单独见 todo/）
claude-code-cron.md	Claude Code 原生 Cron 调度功能参考手册
claude-cli-session-leak.md	常驻 CLI 子进程泄漏排查手册 — ✅ 已修复（b0b2b62 + 2092a2e）：系统里有两个互不相干的会话池（routes/agent-chat.js 的 sessions / src/core/session-pool.js），各漏各的。含按 cwd 判断孤儿归属的方法、变异检验为什么必要、三步定位脚本，以及 DISABLE_BACKGROUND_AGENTS=1 —— 跑全量测试前关掉后台驱动的开关
open-api-manual.md	ArenaSK Open API 外部调用手册
production-deploy.md	生产部署环境与上线流程 — 服务器地址、/opt/lemonboss 部署拓扑、Docker 容器、git pull + 重启的具体步骤
qa_judge_req.md	QA Judge Agent 需求文档 — 已在 system/agents/qa-judge/ 落地
task_timeline_design.md	Task Timeline View 设计文档 — 已实现（server/routes/tasks.js、server/services/task-service.js、web/src/views/TaskTimeline.vue）
user-guides/08-base-agent-4-phase-guide.md	Base Agent 四阶段使用指南
system-design/27-p1-virtual-reference.md	P1 虚拟引用寻址 — ✅ 已实现（commit 226489d，server/services/graph-service.js）：agent.md 不再逐公司拷贝，改为 config.json.systemAgentRef 引用 + company-context.md 承载公司语境
system-design/27-p2-org-graph.md	P2 Org Graph — ✅ 已实现（70a4727 + f20d0d8）：org graph 定位为 company 级 workflow（执行流边），orggraph-planning agent 建公司时自动规划并招聘。真实建公司端到端验证通过
system-design/27-p3c-goal-task-model.md	P3 收尾 goal / task 两级模型 + 控制台任务列表 — ✅ 已完成（2026-08-20）：五批实施 + §十七 清尾。含队列 / 并行槽位、task-planning、两套任务体系统一、墙钟预算改「只算活跃时长」。§17.5 是真跑验收 —— 返工闭环第一次由真 agent（不是注入的假 executor）走通
system-design/27-p3c-batch3-handover.md	批 3 交接 —— ✅ 已收口（2026-08-20）。事故记录归档：一份未经复核的代码被第三方会话提交进 main。留着是因为 §六 那几条多会话协作规则是真踩出来的
system-design/38-auth-multi-tenant-isolation.md	登录鉴权 + 公司级多租户隔离 —— ✅ Phase 0/1/2/3 全部完成（2026-08-25）。种子账号 admin/hex1234 + 登录页；全站挂 requireAuth（agent-chat.js 用 requireAuthOrInternal 放行三处服务端自环调用）；company.json 加 ownerId，canAccessCompany 是全仓库唯一归属判据，company.js/graph-run.js/devloop.js 分别接入（graph-run.js 双挂载点参数形状不同，设计阶段描述不准确，实现时才发现）；okr.js 因是零导航入口的孤儿页面改挂 requireAdmin 而非归属校验。Phase 3 验证阶段真查出一个漏洞：agent-chat.js 靠 :agentId 的 "companyId:role" 前缀区分会话归属却从没做过归属校验，任意登录用户可跨租户读别家公司会话，已修复。全量 vitest 1433 passed
system-design/01-26	系统设计正文 01～26 章（14、25-harness-engineering-improvements 例外，见 todo/future/；27 例外，见 todo/），各章节状态见文内「状态」标记

todo/（当前主线）

Graph Agent 架构重构（27 系列）。已完成的阶段文档已移入 done/（P1、P2），下面是仍在推进或长期有效的部分。

文件	说明
27-graph-agent-architecture.md	总纲。P0-P6 分阶段路线图与整体架构。P0-P3+P4 已实现，P4（新）/P5/P6 待做
27-requirement.md	需求源头。用户原话照搬（R-1..R-16）+ 需求→设计落点速查。其余文档都是对它的转述，出现分歧以此为准
27-naming-conventions.md	命名规范。{作用域}-{职能}；图节点按层级轴命名；节点名 ≠ 本体名；三种 benchmark 消歧；OKR 正名。新增 agent id / 表名 / 字段名前必读
27-e2e-task-execution-flow.md	端到端流程总览：建公司 → 下达任务 → org graph 逐节点执行 → work graph 规划与循环 → 验收收敛。含与 DevLoop 既有实现的对应关系分析
27-example-dev-company-walkthrough.md	参考场景走查（虚构的「配图工厂」），把架构跑一遍具体的数：各阶段 JSON 形态、成本估算、断点清单
27-p3-p4-work-graph-console.md	P3+P4（原 P4 回退+Loop-Validator 已并入）图执行引擎与执行控制台 — ✅ 已实现（c3abf4a）。仍留 todo 的原因：§十 末「四条硬规矩」第 2 条那笔欠账已还大半 —— graph-real-chain-smoke.test.js（零注入、只换掉真 CLI 子进程）已进 CI，agent_call 与 subgraph 两支都覆盖。剩下的是真 LLM（进不了 CI）、多节点 / 回退边 / 熔断的形状、以及按需 hire 那一段
27-p3b-real-run-runway.md	P3 收尾之真跑跑道（从 mock 走到真 Claude CLI）— 📝 只剩验收 9。2026-08-20 第四次真跑（§六ter）验掉 2 与 8，验收 4 由零注入链路验掉，7 早已修好。验收 9 的准确状态是「产出端通了、消费端没等到那个形状」—— 需要一次 org 层回退边指向 subgraph 节点。⚠️ 这份文档里 ⛔/🟡 的段落多为当时的现场记录，读之前先看头部状态行
27-goal-contract-format.md	验收契约格式（goal-benchmark / goal-test-data / goal-test-script 的产物形态与跨节点传递）
27-p4-parallel-and-artifacts.md	P4（回收编号）并行执行与产物索引 — 📝 设计中，未实现。fan-out 真并发 + 同 agent 多实例隔离 + files.json 产物索引。三个 Phase，C 可插队
28-followups.md	28 号（Agent 注册表统一）的遗留清单 — 主文档已在 done/，这份装没做完的：dream 机制（设计见 29 号，已实现，见下）、source_kind（✅已删）/legacy_path（不能删）删列、三项「已实施未验证」。任务态清理（✅已实现，见下）。§五 是已立起来的守卫清单（别重复造，也别删）
29-dream-design.md	dream（经验汇流）— ✅ 已实现。定时整理所有 agent 在所有公司的记忆，提炼后跨公司沉淀（不泄漏公司信息）。四条取舍已拍板并实现：去敏独立判定、四落点分层写入（经验/SKILL.md/soul.md/agent.md，受管区块+三道闸门）、每日定时（串行+空转保护）、引用真伪自动查、REST+控制台入口（/api/dream/*、/dream）。innovator-evolver 真 CLI 跑通一次。仍缺的：「结论对不对」只能人抽查；「套进 org/work graph 来跑」评估后用户选了不做（作用域不匹配，见文内 §5.7）
30-task-delegation-reliability-gaps.md	任务委派可靠性现状— 📝 调研记录，非设计方案。DevLoop runUnit、Company 招聘装配、Graph 执行三条链路核对结论一致：都是「失败预算耗尽 → 停等人工」，没有「卡住了主动通知人」这一层；DevLoop 当前还默认走 mock，真实 CLI 成功率无实证数据。2026-08-23 追加真实实例并已修：infra_flake 原地重跑没有熔断线，真撞上过一次确定性死循环（节点把诊断结论误判成自己的执行结果，反复重跑却从不路由到诊断建议的目标节点）；已加 infra_flake_count 列 + 硬顶 3 次熔断，连续判 infra_flake 超过硬顶就改判 blocked 交给人工
31-work-graph-fail-fallback-coverage.md	work graph 兜底边覆盖不全 — ✅ 已完成（除入口节点外强制兜底边，planner.json/executor-fanout.json 补 6 条边），978/978 单测通过；2026-08-21 又用真实 LLM 起了一条新任务做端到端回归验证，org-planner-sdd 自判失败后自动打回 org-planner-prd（3 次，零人工介入），修复确认生效
39-boss-agent-task-supervision.md	📝 设计评估中，未实现。评估用户提出的五阶段方案（雇 boss agent 监督 goal/task 看板、独立任务看板页、心跳挨个调度、org/work graph 产出的 bug/新任务回写看板、公司级目标代码目录）。结论：P2 看板已实现、P1/P3 心跳与 ceo 本体基础设施已有大半、P5 的 linked-existing 模式已在 path-resolver.js 完整实现只差公司级默认值，真正从零开始的是 P4（回写闭环）——当前没有任何 agent 工具能读写 goal/task 板。建议顺序倒过来先建 P4 地基
37-org-graph-department-scoping.md	📝 设计讨论，调用点扫描已完成，尚未立项实现。现状 org graph 按 company_id 单例（27-P2 标题原文即"公司级"），塞不下 HR/财务/市场这类跟"交付流水线"无关的公司常设职能——system/agents/hr/（"招·留·管·退"）本体已存在却从没被装进任何图，全靠 fire-and-forget chat 招聘、无图执行审计轨迹。提议把 org graph 作用域从 company_id 升级为 (company_id, department_id)，一家公司可装配多张部门图，每张仍保持人工固定/慢变/可审计。全仓库调用点扫描结论：改造面是最初估算的 4 倍——真正的单点真相在 work-graph-db.js:readDefGraph 的裸 SQL 不变式（不在服务层），还牵涉两个易混淆服务文件间必须字节级一致的重复唯一索引、独立的 graph-seed-service.js 对账子系统、company-hire-org-layer.test.js 专属测试、orggraph-planning/task-planning 两份 agent 人设文档的自我认知改写
36-prd-agent-methodology-training-feasibility.md	📝 调研 + 阶段一/二均已完成。回应"落地页太单薄是不是该用 Innovator 先训练专业 agent、再用 Dream 持续迭代"——认同方向。阶段一：graph-engine.js 结算节点后把 success/fail:<reason> 写进本体 memory.md（此前只有人类对话路径会写，Dream 天天空转）。阶段二：新建独立试验节点 prd-methodology-trial 走真实 Hunt→Digest→Evolve，2 轮收敛（96/97 分，真实基线 50 分），三个真实历史项目反推验证方法论有效；过程中连带修复同一个 2026-08-16 改名批次遗留的 5 处 innovator→org-innovator 死链（后端两处硬编码、前端"重新训练"按钮、/api/agent/list 展示 id 来源的四个 config.json），以及 AgentScaffold 默认模板一处裸相对路径缺陷。结论：FDE 对方法论类角色确实管用，但收敛速度/验收严谨度依赖任务书显式写明的自纠正要求，非免人工黑盒。环节 3（训练产物 → 雇佣本体转换）尚未开工
35-validation-rigor-and-body-readiness-proposal.md	📝 复盘 + 改进方案，四条提案全部已实施。承接 31/32/33/34 号的复盘结论：任务结果差主要是架构问题（完整性闸门 missingBodyDefinition 只在招聘时查、图执行侧完全没有第二道防线——新发现）+ 一个具体的招聘装配可靠性 bug，不是 agent 能力问题。提案 A：本体不完整时图执行前置判 fail_reason=body_not_ready，不扣预算。提案 D：goal-contract.js 的 evidence_hint 命中浏览器类关键词的维度必须有证据支撑，否则判不过。提案 C：新增 scripts/visual-acceptance-check.mjs 复用检查工具。提案 B：控制台「验收证据」小节展示每个维度有没有证据支撑
34-validator-scored-without-real-deliverable.md	📝 调研记录，checklist 已查完。最初以为 org-coder-impl 从未产出任何 HTML/CSS，后来发现真实网站其实存在于 graph_files 索引不覆盖的「项目根」目录（已顺手修：控制台「产物」面板现在会展示项目根）。追加查清 validator 有没有真的做浏览器级检查——中途自我订正一次：不是"没工具做不到"（bash 能走到仓库自带的 Playwright，另一条对照任务证明可行），是没人教它这么做；抽查另外两个项目根后发现验证严谨度完全不稳定（同类任务有的做了真实 Playwright 级验证、有的只做静态正则、有的没验证就被取消），根因很可能是新招聘的 unit-tester 本体撞上了 32 号文档 那类"装配没填充完"的真实样本，不是平台工具限制
40-agent-chat-streaming-interrupt.md	📝 需求文档，讨论中，未实现。回应"前端刷新不及时/没有打字机效果，要不要把 SSE 换成 WebSocket"——排查后结论是传输层不是瓶颈（对照 hermes-webui/hermes-agent/deepseek-harness 三个参考实现，全部走 SSE，不用 WebSocket）。真正的三个独立缺口：① 打字机不流畅（ACP chunk 粒度太粗，方案是前后端都做匀速切片/渲染缓冲）；② 执行中无法打断并接上新消息（现状"先 Stop 再发"两步，方案是深度 1 的打断-排队，顺带发现服务端对同 convId 并发缺闸门这个现存 bug）；③ 串台已在 9b1c3f1 修复但没有回归测试兜底
33-needs-gate-role-filter-bug.md	✅ 已修复。executor.json/executor-fanout.json 里 produces:["log"] 声明了一个 test/integration 类节点永远不会被索引到的 kind，导致 org-coder-validator 被 missing_required_input 反复误判 blocked；改成 required:false（对齐 validator.json 既有写法）。文档记录了一条走过的弯路（按 role 过滤 inboundContracts 会削弱 T-mt25ecbd 的产出闸门，已撤回），发现于 31 号文档的真实回归验证过程中，与兜底边问题无关

todo/future/（暂缓，非当前重心）

文件	说明
architecture_todo_list.md	FDE Pipeline 架构待办清单（Judge 系统 / 反馈闭环等五大维度）。与 Graph Agent 架构基本正交，其中第 4 点「版本回滚」与 27 号文档 P5 阶段的 git 版本化 memory.md 有部分重叠，P5 落地后可回来划掉
system-design/14-milestones.md	早期里程碑规划（v1.1，checklist 未勾选）。已被后续实际实现大幅绕过，主要留作历史存档，不建议优先处理
system-design/25-harness-engineering-improvements.md	Harness Engineering 改进提案（单 Agent 上下文管理），Phase 3-5 未落地。与 Graph Agent 架构（多 Agent 组织/图执行）维度不同，互不阻塞

未纳入整理的目录

以下目录本身是活跃系统的一部分（不是静态文档），保持原位不动：

• prd/ — DevLoop 的 PRD/SDD 规格站点源文件。prd/newfunction/*.html 由 npm run spec:extract 读取生成 prd/newfunction/_spec/*.md，是代码依赖的机器可读规格，不是待归档的说明文档。
• create-drama/ — 独立的 Skill 工具子项目（含自身 package.json / node_modules），不是设计文档。

维护说明

新增文档时，先判断它描述的是已实现的能力（放 done/）、当前正在推进的重心（放 todo/），还是尚未开始且非当前重心（放 todo/future/）。功能落地后，将对应文档从 todo/（或 todo/future/）移到 done/ 并更新本索引与 LEMONBOSS-SYSTEM-DESIGN.md 中的链接；当主线切换时（比如 Graph Agent 架构完成后），把 todo/future/ 里优先级提升的条目挪回 todo/。