From c2ccac24c056221498df349fe444d94a6730c8cb Mon Sep 17 00:00:00 2001 From: bboonnee Date: Thu, 13 Aug 2026 14:44:32 +0800 Subject: [PATCH] docs: update implementation-gap-analysis.md's stale entries --- docs/implementation-gap-analysis.md | 55 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/docs/implementation-gap-analysis.md b/docs/implementation-gap-analysis.md index 02ac5bb..456e923 100644 --- a/docs/implementation-gap-analysis.md +++ b/docs/implementation-gap-analysis.md @@ -31,10 +31,16 @@ ## 2. "熄灯"叙事本身：没有常驻调度入口 -`src/scheduler.py`（U-032）从未被 `backend_server.py` 或任何生产入口调用——`backend_server.py` 里只有一句注 -释提到"调度器以后会长在这里"（grep 确认，无实际调用）。系统目前不存在一个真正常驻、自动扫描 `queued` 任务 -并派发的进程；每一次"跑起来"都是脚本/测试手动调用 `run_scheduler_once`/`run_goal_to_completion`。这和"Level -5 自主研发系统"的叙事有实质差距——机制都齐了，但缺"自己跑起来"这一层。 +**✅ 已修复（2026-08-13，FR-1 新 Goal 自动派发，`docs/done/scheduler-new-goal-dispatch-requirements.md`）**： +本节原话"系统目前不存在一个真正常驻、自动扫描 `queued` 任务并派发的进程"已不成立——`backend_server.py::main()` +现在有两条独立的常驻后台线程：已实现的"在途任务复原"（`task_reconciliation.py`，300 秒）和新增的"新 Goal +自动派发"（`src/new_goal_dispatch.py`，45 秒，`find_queued_tasks()`/`dispatch_once()`，逐个候选调用 +`task_execution.start_task_execution_in_background()`）。不是直接接 `scheduler.run_scheduler_once()`（那个函数 +语义是"新建并跑完一批 Goal"，跟"扫描已存在的 `queued` 任务"不是同一件事，本节原文和第 6 节任务清单顺序 6 +当初都把这两者混为一谈了）——实际实现绕开了 `run_scheduler_once()`，直接对已存在的 `queued` task 行派发，更贴合 +真实需求。用户已明确拍板：完整开放、常驻轮询，不是保守默认关闭。"自己跑起来"这一层现在是真的有了，但见"最值得 +关注的三条"：这只解决了"新任务/卡住任务怎么自动启动"，不等于 PH5 Deploy Supervisor 的"自动发现待部署改动" +（`poll_fn`）也一并解决了——那是完全独立的另一个闭环，仍未实现，见下方第 1 节。 ## 3. SDD 契约与实现之间已知的简化/偏差 @@ -72,18 +78,17 @@ 场景仍未专门测试过，不算完全清零。 - `v_artifact_browser`（U-028）有意不做 Markdown 渲染/代码高亮（02-V 原型期望有），因为要避免引入第一个前端 第三方库，判断为有意简化而非漏做。 -- **Coder 开始实现前，Planner 自己的产出从未被独立复核过**（2026-08-08 新发现，真实复现见 - `docs/todo/validator-test-script-narrative-output-issue.md` 时间线第 5 轮，任务 `2084590a`）：`org_node_lifecycle.py` - 的固定流程是 `planner → coder → validator`，`artifact_write.py` 的 `validation_status` 写入时无条件设成 - `'passed'`（自己承认"语义内容校验还没有专属 LLM-judgment 调用"），实际上没有任何机制拦住"Planner 产出叙述文字 - 冒充 benchmark"这类内容直接流入 Coder。**设计已完成，待实施**：`docs/todo/org-graph-unification-phase1-review- - gate-design.md`（新增 `planner_reviewer` org role + `reviewing_planner_output` 状态，插在 Planner/Coder 之间）。 -- **Work Graph 单节点执行层仍依赖 Claude Code 原生 Dynamic Workflow，不是自研**（2026-08-08 新发现）：图编排层 - （`work_graph_orchestrate.py`）早已自研（REQ-06 断点续跑驱动），但 `_render_node_script()`/`_llm_judgment_ - verify_fn`/`e2e_pipeline._check_prd_consistency` 三处仍在生成一次性 `.claude/workflows/*.js` 脚本、经 - `claude -p 'Run /...'` 执行——`plan_work_graph()` 已经证明同一个"`--agent` 身份 + 结构化输出"需求可以 - 不经 Workflow、靠 flat `claude --agent` 调用 + JSON 围栏提取解决。**设计已完成，待实施**： - `docs/done/work-graph-node-execution-deblackbox-requirements.md`。 +- **✅ 已修复（Phase 1，commit `ea19c7d`，2026-08-08）Coder 开始实现前，Planner 自己的产出从未被独立复核过** + （真实复现见 `docs/done/validator-test-script-narrative-output-issue.md` 时间线第 5 轮，任务 `2084590a`）： + 新增独立 org role `planner_reviewer` + `reviewing_planner_output` 状态，插在 Planner/Coder 之间，独立复核 + BRD/PRD/SDD/Benchmark 是否为真实结构化内容。详见 `docs/done/org-graph-unification-phase1-review-gate-design.md`。 +- **✅ 已修复（2026-08-13，`docs/done/work-graph-node-execution-deblackbox-requirements.md`）Work Graph 单节点 + 执行层不再依赖 Claude Code 原生 Dynamic Workflow**：`_make_run_fn`/`_llm_judgment_verify_fn`/ + `_check_prd_consistency` 三处（以及实施过程中额外发现的 `_run_reflection_perspective`/`_fix_skill_for_node` + 两处，Phase 2a Reflection-review/Fix-Skill 引入，原设计文档撰写时还不存在）全部迁移到新增的 + `org_node_trigger.trigger_org_node_structured()`——flat `claude --agent` 调用 + JSON 围栏提取，`plan_work_graph()` + 验证过的同一套机制，不再经 Dynamic Workflow。`write_workflow_script`/`execute_work_graph` 确认无生产调用方， + 标记为历史遗留（文件保留未删除）。 ## 4. 文档本身滞后于实现（这本身就是一种"差距"） @@ -139,8 +144,8 @@ Deploy Supervisor 走到 cutover 前，仍按现有习惯人工确认一次。 | 3 | ✅ 已修复（2026-08-04，**真正走 graphlemon 自举流程验证**） Skill 内容未真正迁移（§3） | ~~把 `~/.hermes/profiles/{code,planning,qa}/skills/` 下 frontmatter 引用到的 Skill 真实内容迁移进仓库 `skills//`~~ | 中 | 启动前先人工核实了 12 个 skill_id 的真实源路径（8 个比预想深一层，藏在分类子目录里）并把精确映射直接写进 goal_text，避免 Coder 会话浪费真实 token 去搜索——原先担心的"读取仓库外路径权限"最后证明不是问题，`Bash`/`Read` 能正常读 `~/.hermes/...`。真实跑的路上还顺带遇到并修好两个操作性问题：① 一次真实 API 网络瞬断（`ENOTFOUND`）导致任务阻塞，直接推动修了 `manual_resume` 不会真的续跑这个 bug（见下方"顺带修复"）；② 我自己用一次性脚本调 `start_task_execution_in_background()` 导致 daemon 线程随脚本退出被误杀，改用 `nohup` 持久进程后正常跑完。**结果**：12 个 Skill 目录全部真实迁移（`SKILL.md`+`references`/`templates`/`scripts`），Validator 做了逐字节 `diff -rq` 核对（9/12 完全一致，3/12 只差一行——主动发现并脱敏了源文件里一个真实泄漏的飞书 API token，跟仓库已有先例一致，不是内容改写），`agent_profile.py` 的 `FRONTMATTER` 与新目录名逐一核对一致。Validator 顺带报过一次 `supervisor/test_deploy_rollback.RollbackPathBFailureTest` 失败并称"确认是迁移前就有的";事后独立复核（单独跑 + 全量跑 `supervisor/`）**没能复现**，大概率是这个套件已知的孤儿进程/资源竞争类偶发失败，不算新缺口，先记录观察。**顺带修复**：`src/backend_server.py` 的 `manual_resume` 之前只对 `user_paused`/`user_stopped` 自动续跑，`execution_error`（网络瞬断等）resume 后卡死——改成除 `budget_exceeded`/`loop_limit_reached` 外都自动续跑，见 commit `db62570`。 | | 4 | 部署缺互斥锁（本节新发现，§1） | 给 `deploy_stage.stage_deployment()` 加"当前是否已有进行中部署"的检查，拒绝/排队重复 staging | 中 | 应该在启用并发自举（顺序 6 之后）之前完成，否则后续任务并发跑时有真实冲突风险 | | 5 | PH3 前端从未被真人验证（§5） | 不适合作为自动化 Coder 任务——这是"人用浏览器点一遍"的验证缺口，不是代码缺陷；列在这里是为了不让它被误当成可自举任务 | 不适用 | 需要人（或 claude-in-chrome 之类的浏览器自动化）介入，不建议塞进 Planner→Coder 循环 | -| 6 | 调度器接入生产入口（§2） | 给某个常驻进程（`backend_server.py` 或独立进程）接入 `scheduler.run_scheduler_once()` 的轮询循环 | 高 | **改变系统自己的自主权边界**，建议单独一批、额外人工审查 diff，不要和其他 gap 混跑；完成并 cutover 后，理论上后续 gap 才谈得上真正黑灯 | -| 7 | Deploy Supervisor 缺 `poll_fn`（§1） | 实现"发现待部署的 self-target 合并"逻辑，接入 `supervisor/deploy_supervisor.py` 的 `poll_fn` 钩子 | 高 | 依赖顺序 6 先完成（两者共同构成"真正自驱动"）；且 SDD 里"什么条件触发自部署"本身有文档内部冲突（设计文档 vs 规范正文），需要人工先拍板这个设计决策，不能让 Planner 自己悄悄选一种理解 | +| 6 | ✅ 已修复（2026-08-13） 调度器接入生产入口（§2） | ~~给某个常驻进程（`backend_server.py` 或独立进程）接入 `scheduler.run_scheduler_once()` 的轮询循环~~ | 高 | **改变系统自己的自主权边界**，用户已单独拍板、单独实施（`docs/done/scheduler-new-goal-dispatch-requirements.md`，不是走本节"自举修 gap"流程，是这次交互式会话直接改代码）。实际实现没有直接接 `run_scheduler_once()`，见第 2 节更新——不影响下一条依然待办 | +| 7 | Deploy Supervisor 缺 `poll_fn`（§1） | 实现"发现待部署的 self-target 合并"逻辑，接入 `supervisor/deploy_supervisor.py` 的 `poll_fn` 钩子 | 高 | 顺序 6 已完成，但这条**依然独立未解决**——"自动发现待部署改动"跟"自动派发新任务"是两个不同的闭环，不要因为 6 done 了就误以为这条也一起解决了；且 SDD 里"什么条件触发自部署"本身有文档内部冲突（设计文档 vs 规范正文），需要人工先拍板这个设计决策，不能让 Planner 自己悄悄选一种理解 | | — | Coder 阶段的多模块 Work Graph 规划（§3） | 不建议列入这批"修 gap"任务 | 不适用 | 这是被明确判断为"超出范围的新能力"，不是缺陷；如果要做，应该走正常的新功能立项，不该包装成"修复"塞进自动循环 | **执行建议**：先跑 1→2（验证流程本身），再跑 3→4（补齐已知风险点），5 留给人工/浏览器自动化处理，6→7 作为 @@ -219,9 +224,15 @@ gap，但**全局而非按项目的并发统计**是不是有意为之，值得 --- -## 最值得关注的三条 +## 最值得关注的两条（原第 1 条已于 2026-08-13 解决，见下） -1. 调度器没接入生产入口，系统还不是真正自驱动的（第 2 节）。 -2. Deploy Supervisor 缺"自动发现待部署改动"的 `poll_fn`，PH5 的"自动"两个字还没完全兑现（第 1 节）。 +1. ~~调度器没接入生产入口，系统还不是真正自驱动的~~ **✅ 已解决（2026-08-13，第 2 节）**：新 Goal 自动派发 + + 在途任务复原两条常驻循环都已接入 `backend_server.py::main()`。**注意不要跟下一条混为一谈**：这解决的是 + "已存在的 task 行怎么自动启动/续跑"，跟 Deploy Supervisor 的"自动发现待部署的 self-target 改动"是两个完全 + 独立的闭环，下一条依然没解决。 +2. Deploy Supervisor 缺"自动发现待部署改动"的 `poll_fn`，PH5 的"自动"两个字还没完全兑现（第 1 节）——这是 + "改完代码后要不要自动上线自己"，跟上面"要不要自动开始跑一个新任务"是两件不同的事，一个解决不代表另一个 + 也解决了。 3. 文档（development-plan/unit_matrix/build-report）本身持续滞后于自举产生的新提交，这个滞后会越滚越大， - 建议找个时间点做一次文档收口，而不是继续靠事后补记维持可读性（第 4 节）。 + 建议找个时间点做一次文档收口，而不是继续靠事后补记维持可读性（第 4 节）——本文档自己也是这类滞后的活例子： + 2026-08-03 的快照到 2026-08-13 已经手动打了 4 处"✅ 已修复"补丁，是这条风险本身的一次真实示范。 -- libgit2 0.21.4