宜博 / lemongraph

Commit c2ccac24c056221498df349fe444d94a6730c8cb

Authored by bboonnee
1 parent b47e4364

docs: update implementation-gap-analysis.md's stale entries 

This is a point-in-time snapshot doc (dated 2026-08-03) that's explicitly
meant to be hand-edited in place as gaps close, not rewritten -- three
entries had gone stale relative to work landed since: the Planner-output
review gate (Phase 1, already done back in early August but never marked
here), the Work Graph node execution deblackbox migration, and the new-Goal
auto-dispatch scheduler loop. Updated each to ✅ and refreshed the "most
worth watching" summary and the self-hosting task table row accordingly --
the still-open Deploy Supervisor poll_fn gap is called out explicitly as a
*different*, still-unsolved closed loop so it doesn't get conflated with
the now-solved scheduler entry point gap.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Inline Side-by-side
Showing 1 changed file with 33 additions and 22 deletions
docs/implementation-gap-analysis.md
  View file @c2ccac2
... ... @@ -31,10 +31,16 @@
31 31  
32 32 ## 2. "熄ç¯"å™äº‹æœ¬èº«ï¼šæ²¡æœ‰å¸¸é©»è°ƒåº¦å…¥å£
33 33  
34   -`src/scheduler.py`（U-032）从未被 `backend_server.py` 或任何生产入å£è°ƒç”¨â€”—`backend_server.py` 里åªæœ‰ä¸€å¥æ³¨
35   -释æ到"调度器以åŽä¼šé•¿åœ¨è¿™é‡Œ"（grep 确认，无实际调用）。系统目å‰ä¸å­˜åœ¨ä¸€ä¸ªçœŸæ­£å¸¸é©»ã€è‡ªåŠ¨æ‰«æ `queued` 任务
36   -并派å‘的进程；æ¯ä¸€æ¬¡"è·‘èµ·æ¥"都是脚本/测试手动调用 `run_scheduler_once`/`run_goal_to_completion`。这和"Level
37   -5 自主研å‘系统"çš„å™äº‹æœ‰å®žè´¨å·®è·â€”—机制都é½äº†ï¼Œä½†ç¼º"自己跑起æ¥"这一层。
  34 +**✅ 已修å¤ï¼ˆ2026-08-13，FR-1 æ–° Goal 自动派å‘，`docs/done/scheduler-new-goal-dispatch-requirements.md`）**：
  35 +本节原è¯"系统目å‰ä¸å­˜åœ¨ä¸€ä¸ªçœŸæ­£å¸¸é©»ã€è‡ªåŠ¨æ‰«æ `queued` 任务并派å‘的进程"å·²ä¸æˆç«‹â€”—`backend_server.py::main()`
  36 +现在有两æ¡ç‹¬ç«‹çš„常驻åŽå°çº¿ç¨‹ï¼šå·²å®žçŽ°çš„"在途任务å¤åŽŸ"（`task_reconciliation.py`，300 秒）和新增的"æ–° Goal
  37 +自动派å‘"（`src/new_goal_dispatch.py`，45 秒，`find_queued_tasks()`/`dispatch_once()`，é€ä¸ªå€™é€‰è°ƒç”¨
  38 +`task_execution.start_task_execution_in_background()`）。ä¸æ˜¯ç›´æŽ¥æŽ¥ `scheduler.run_scheduler_once()`（那个函数
  39 +语义是"新建并跑完一批 Goal"，跟"扫æ已存在的 `queued` 任务"ä¸æ˜¯åŒä¸€ä»¶äº‹ï¼Œæœ¬èŠ‚原文和第 6 节任务清å•é¡ºåº 6
  40 +当åˆéƒ½æŠŠè¿™ä¸¤è€…混为一谈了）——实际实现绕开了 `run_scheduler_once()`，直接对已存在的 `queued` task 行派å‘，更贴åˆ
  41 +真实需求。用户已明确æ‹æ¿ï¼šå®Œæ•´å¼€æ”¾ã€å¸¸é©»è½®è¯¢ï¼Œä¸æ˜¯ä¿å®ˆé»˜è®¤å…³é—­ã€‚"自己跑起æ¥"这一层现在是真的有了，但è§"最值得
  42 +关注的三æ¡"：这åªè§£å†³äº†"新任务/å¡ä½ä»»åŠ¡æ€Žä¹ˆè‡ªåŠ¨å¯åŠ¨"，ä¸ç­‰äºŽ PH5 Deploy Supervisor çš„"自动å‘现待部署改动"
  43 +（`poll_fn`）也一并解决了——那是完全独立的å¦ä¸€ä¸ªé—­çŽ¯ï¼Œä»æœªå®žçŽ°ï¼Œè§ä¸‹æ–¹ç¬¬ 1 节。
38 44  
39 45 ## 3. SDD 契约与实现之间已知的简化/åå·®
40 46  
... ... @@ -72,18 +78,17 @@
72 78 场景ä»æœªä¸“门测试过，ä¸ç®—完全清零。
73 79 - `v_artifact_browser`（U-028）有æ„ä¸åš Markdown 渲染/代ç é«˜äº®ï¼ˆ02-V 原型期望有），因为è¦é¿å…引入第一个å‰ç«¯
74 80 第三方库，判断为有æ„简化而éžæ¼åšã€‚
75   -- **Coder 开始实现å‰ï¼ŒPlanner 自己的产出从未被独立å¤æ ¸è¿‡**（2026-08-08 æ–°å‘现，真实å¤çŽ°è§
76   - `docs/todo/validator-test-script-narrative-output-issue.md` 时间线第 5 轮，任务 `2084590a`）：`org_node_lifecycle.py`
77   - 的固定æµç¨‹æ˜¯ `planner → coder → validator`，`artifact_write.py` çš„ `validation_status` 写入时无æ¡ä»¶è®¾æˆ
78   - `'passed'`（自己承认"语义内容校验还没有专属 LLM-judgment 调用"），实际上没有任何机制拦ä½"Planner 产出å™è¿°æ–‡å­—
79   - 冒充 benchmark"这类内容直接æµå…¥ Coder。**设计已完æˆï¼Œå¾…实施**：`docs/todo/org-graph-unification-phase1-review-
80   - gate-design.md`（新增 `planner_reviewer` org role + `reviewing_planner_output` 状æ€ï¼Œæ’在 Planner/Coder 之间）。
81   -- **Work Graph å•èŠ‚点执行层ä»ä¾èµ– Claude Code 原生 Dynamic Workflow，ä¸æ˜¯è‡ªç ”**（2026-08-08 æ–°å‘现）：图编排层
82   - （`work_graph_orchestrate.py`）早已自研（REQ-06 断点续跑驱动），但 `_render_node_script()`/`_llm_judgment_
83   - verify_fn`/`e2e_pipeline._check_prd_consistency` 三处ä»åœ¨ç”Ÿæˆä¸€æ¬¡æ€§ `.claude/workflows/*.js` 脚本ã€ç»
84   - `claude -p 'Run /<name>...'` 执行——`plan_work_graph()` å·²ç»è¯æ˜ŽåŒä¸€ä¸ª"`--agent` 身份 + 结构化输出"需求å¯ä»¥
85   - ä¸ç» Workflowã€é  flat `claude --agent` 调用 + JSON å›´æ æå–解决。**设计已完æˆï¼Œå¾…实施**：
86   - `docs/done/work-graph-node-execution-deblackbox-requirements.md`。
  81 +- **✅ 已修å¤ï¼ˆPhase 1，commit `ea19c7d`，2026-08-08）Coder 开始实现å‰ï¼ŒPlanner 自己的产出从未被独立å¤æ ¸è¿‡**
  82 + （真实å¤çŽ°è§ `docs/done/validator-test-script-narrative-output-issue.md` 时间线第 5 轮，任务 `2084590a`）：
  83 + 新增独立 org role `planner_reviewer` + `reviewing_planner_output` 状æ€ï¼Œæ’在 Planner/Coder 之间，独立å¤æ ¸
  84 + BRD/PRD/SDD/Benchmark 是å¦ä¸ºçœŸå®žç»“æž„åŒ–å†…å®¹ã€‚è¯¦è§ `docs/done/org-graph-unification-phase1-review-gate-design.md`。
  85 +- **✅ 已修å¤ï¼ˆ2026-08-13，`docs/done/work-graph-node-execution-deblackbox-requirements.md`）Work Graph å•èŠ‚点
  86 + 执行层ä¸å†ä¾èµ– Claude Code 原生 Dynamic Workflow**：`_make_run_fn`/`_llm_judgment_verify_fn`/
  87 + `_check_prd_consistency` 三处（以åŠå®žæ–½è¿‡ç¨‹ä¸­é¢å¤–å‘现的 `_run_reflection_perspective`/`_fix_skill_for_node`
  88 + 两处，Phase 2a Reflection-review/Fix-Skill 引入，原设计文档撰写时还ä¸å­˜åœ¨ï¼‰å…¨éƒ¨è¿ç§»åˆ°æ–°å¢žçš„
  89 + `org_node_trigger.trigger_org_node_structured()`——flat `claude --agent` 调用 + JSON å›´æ æå–，`plan_work_graph()`
  90 + 验è¯è¿‡çš„åŒä¸€å¥—机制，ä¸å†ç» Dynamic Workflow。`write_workflow_script`/`execute_work_graph` 确认无生产调用方，
  91 + 标记为历å²é—留（文件ä¿ç•™æœªåˆ é™¤ï¼‰ã€‚
87 92  
88 93 ## 4. 文档本身滞åŽäºŽå®žçŽ°ï¼ˆè¿™æœ¬èº«å°±æ˜¯ä¸€ç§"å·®è·"）
89 94  
... ... @@ -139,8 +144,8 @@ Deploy Supervisor 走到 cutover å‰ï¼Œä»æŒ‰çŽ°æœ‰ä¹ æƒ¯äººå·¥ç¡®è®¤ä¸€æ¬¡ã€‚
139 144 | 3 | ✅ 已修å¤ï¼ˆ2026-08-04，**真正走 graphlemon 自举æµç¨‹éªŒè¯**） Skill 内容未真正è¿ç§»ï¼ˆÂ§3） | ~~把 `~/.hermes/profiles/{code,planning,qa}/skills/` 下 frontmatter 引用到的 Skill 真实内容è¿ç§»è¿›ä»“库 `skills/<skill_id>/`~~ | 中 | å¯åŠ¨å‰å…ˆäººå·¥æ ¸å®žäº† 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`。 |
140 145 | 4 | 部署缺互斥é”（本节新å‘现，§1） | ç»™ `deploy_stage.stage_deployment()` 加"当å‰æ˜¯å¦å·²æœ‰è¿›è¡Œä¸­éƒ¨ç½²"的检查，拒ç»/排队é‡å¤ staging | 中 | 应该在å¯ç”¨å¹¶å‘è‡ªä¸¾ï¼ˆé¡ºåº 6 之åŽï¼‰ä¹‹å‰å®Œæˆï¼Œå¦åˆ™åŽç»­ä»»åŠ¡å¹¶å‘跑时有真实冲çªé£Žé™© |
141 146 | 5 | PH3 å‰ç«¯ä»Žæœªè¢«çœŸäººéªŒè¯ï¼ˆÂ§5） | ä¸é€‚åˆä½œä¸ºè‡ªåŠ¨åŒ– Coder 任务——这是"人用æµè§ˆå™¨ç‚¹ä¸€é"的验è¯ç¼ºå£ï¼Œä¸æ˜¯ä»£ç ç¼ºé™·ï¼›åˆ—在这里是为了ä¸è®©å®ƒè¢«è¯¯å½“æˆå¯è‡ªä¸¾ä»»åŠ¡ | ä¸é€‚用 | 需è¦äººï¼ˆæˆ– claude-in-chrome 之类的æµè§ˆå™¨è‡ªåŠ¨åŒ–）介入，ä¸å»ºè®®å¡žè¿› Planner→Coder 循环 |
142   -| 6 | 调度器接入生产入å£ï¼ˆÂ§2） | ç»™æŸä¸ªå¸¸é©»è¿›ç¨‹ï¼ˆ`backend_server.py` 或独立进程）接入 `scheduler.run_scheduler_once()` 的轮询循环 | 高 | **改å˜ç³»ç»Ÿè‡ªå·±çš„自主æƒè¾¹ç•Œ**，建议å•ç‹¬ä¸€æ‰¹ã€é¢å¤–人工审查 diff，ä¸è¦å’Œå…¶ä»– gap 混跑；完æˆå¹¶ cutover åŽï¼Œç†è®ºä¸ŠåŽç»­ gap æ‰è°ˆå¾—ä¸ŠçœŸæ­£é»‘ç¯ |
143   -| 7 | Deploy Supervisor 缺 `poll_fn`（§1） | 实现"å‘现待部署的 self-target åˆå¹¶"逻辑，接入 `supervisor/deploy_supervisor.py` çš„ `poll_fn` é’©å­ | 高 | ä¾èµ–é¡ºåº 6 先完æˆï¼ˆä¸¤è€…å…±åŒæž„æˆ"真正自驱动"）；且 SDD 里"什么æ¡ä»¶è§¦å‘自部署"本身有文档内部冲çªï¼ˆè®¾è®¡æ–‡æ¡£ vs 规范正文），需è¦äººå·¥å…ˆæ‹æ¿è¿™ä¸ªè®¾è®¡å†³ç­–，ä¸èƒ½è®© Planner 自己悄悄选一ç§ç†è§£ |
  147 +| 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 节更新——ä¸å½±å“下一æ¡ä¾ç„¶å¾…办 |
  148 +| 7 | Deploy Supervisor 缺 `poll_fn`（§1） | 实现"å‘现待部署的 self-target åˆå¹¶"逻辑，接入 `supervisor/deploy_supervisor.py` çš„ `poll_fn` é’©å­ | 高 | é¡ºåº 6 已完æˆï¼Œä½†è¿™æ¡**ä¾ç„¶ç‹¬ç«‹æœªè§£å†³**——"自动å‘现待部署改动"è·Ÿ"自动派å‘新任务"是两个ä¸åŒçš„闭环，ä¸è¦å› ä¸º 6 done 了就误以为这æ¡ä¹Ÿä¸€èµ·è§£å†³äº†ï¼›ä¸” SDD 里"什么æ¡ä»¶è§¦å‘自部署"本身有文档内部冲çªï¼ˆè®¾è®¡æ–‡æ¡£ vs 规范正文），需è¦äººå·¥å…ˆæ‹æ¿è¿™ä¸ªè®¾è®¡å†³ç­–，ä¸èƒ½è®© Planner 自己悄悄选一ç§ç†è§£ |
144 149 | — | Coder é˜¶æ®µçš„å¤šæ¨¡å— Work Graph 规划（§3） | ä¸å»ºè®®åˆ—入这批"ä¿® gap"任务 | ä¸é€‚用 | 这是被明确判断为"超出范围的新能力"，ä¸æ˜¯ç¼ºé™·ï¼›å¦‚æžœè¦åšï¼Œåº”该走正常的新功能立项，ä¸è¯¥åŒ…装æˆ"ä¿®å¤"塞进自动循环 |
145 150  
146 151 **执行建议**：先跑 1→2（验è¯æµç¨‹æœ¬èº«ï¼‰ï¼Œå†è·‘ 3→4（补é½å·²çŸ¥é£Žé™©ç‚¹ï¼‰ï¼Œ5 留给人工/æµè§ˆå™¨è‡ªåŠ¨åŒ–处ç†ï¼Œ6→7 作为
... ... @@ -219,9 +224,15 @@ gap，但**全局而éžæŒ‰é¡¹ç›®çš„并å‘统计**是ä¸æ˜¯æœ‰æ„为之，值得æ
219 224  
220 225 ---
221 226  
222   -## 最值得关注的三æ¡
  227 +## 最值得关注的两æ¡ï¼ˆåŽŸç¬¬ 1 æ¡å·²äºŽ 2026-08-13 解决，è§ä¸‹ï¼‰
223 228  
224   -1. 调度器没接入生产入å£ï¼Œç³»ç»Ÿè¿˜ä¸æ˜¯çœŸæ­£è‡ªé©±åŠ¨çš„（第 2 节）。
225   -2. Deploy Supervisor 缺"自动å‘现待部署改动"çš„ `poll_fn`，PH5 çš„"自动"两个字还没完全兑现（第 1 节）。
  229 +1. ~~调度器没接入生产入å£ï¼Œç³»ç»Ÿè¿˜ä¸æ˜¯çœŸæ­£è‡ªé©±åŠ¨çš„~~ **✅ 已解决（2026-08-13，第 2 节）**：新 Goal 自动派å‘
  230 + + 在途任务å¤åŽŸä¸¤æ¡å¸¸é©»å¾ªçŽ¯éƒ½å·²æŽ¥å…¥ `backend_server.py::main()`。**注æ„ä¸è¦è·Ÿä¸‹ä¸€æ¡æ··ä¸ºä¸€è°ˆ**：这解决的是
  231 + "已存在的 task 行怎么自动å¯åŠ¨/ç»­è·‘"，跟 Deploy Supervisor çš„"自动å‘现待部署的 self-target 改动"是两个完全
  232 + 独立的闭环，下一æ¡ä¾ç„¶æ²¡è§£å†³ã€‚
  233 +2. Deploy Supervisor 缺"自动å‘现待部署改动"çš„ `poll_fn`，PH5 çš„"自动"两个字还没完全兑现（第 1 节）——这是
  234 + "改完代ç åŽè¦ä¸è¦è‡ªåŠ¨ä¸Šçº¿è‡ªå·±"，跟上é¢"è¦ä¸è¦è‡ªåŠ¨å¼€å§‹è·‘一个新任务"是两件ä¸åŒçš„事，一个解决ä¸ä»£è¡¨å¦ä¸€ä¸ª
  235 + 也解决了。
226 236 3. 文档（development-plan/unit_matrix/build-report）本身æŒç»­æ»žåŽäºŽè‡ªä¸¾äº§ç”Ÿçš„æ–°æ交，这个滞åŽä¼šè¶Šæ»šè¶Šå¤§ï¼Œ
227   - 建议找个时间点åšä¸€æ¬¡æ–‡æ¡£æ”¶å£ï¼Œè€Œä¸æ˜¯ç»§ç»­é äº‹åŽè¡¥è®°ç»´æŒå¯è¯»æ€§ï¼ˆç¬¬ 4 节）。
  237 + 建议找个时间点åšä¸€æ¬¡æ–‡æ¡£æ”¶å£ï¼Œè€Œä¸æ˜¯ç»§ç»­é äº‹åŽè¡¥è®°ç»´æŒå¯è¯»æ€§ï¼ˆç¬¬ 4 节）——本文档自己也是这类滞åŽçš„活例å­ï¼š
  238 + 2026-08-03 的快照到 2026-08-13 å·²ç»æ‰‹åŠ¨æ‰“了 4 处"✅ 已修å¤"è¡¥ä¸ï¼Œæ˜¯è¿™æ¡é£Žé™©æœ¬èº«çš„一次真实示范。
... ...