v0 baseline 闭环：22 commits + 182 tests + ADR-0002 完工#45
Merged
Conversation
按 PRD-0001 用 to-issues 拆 23 条 vertical slice（21 子任务 + 2 HITL），按依赖序 严格发布到 GitHub。tmp/issues/ 保留 22 份 issue body 草稿 + 2 份 num.txt 供审计： - #22 父 PRD（HITL） - #23-#42 v0-issue-1..19（AFK：骨架/AST/schema/Bus/解析/执行/装配/GUI/fixture） - #43 v0-issue-20（HITL：不变量守护） - #44 v0-issue-21（HITL：ADR-0002 完工） 策略决策：先 #13 Executor 骨架（mock sink，不依赖真 Bus）→ #5 真 Bus； PyQt6 可选（requirements-gui.txt 单独列）；HITL 由人工守护不变。 无任何代码变更。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 8 步工作流重建（仓库还原后）： - 设计层 7 页（vision / 设计哲学 / 命名空间语义 / 术语表 / 强约束 / 自创名词索引 / 约束） - 架构层 4 页（三上下文 / AST / 多进程 / 状态机） - 协议层 2 页（消息 / 总线） - 任务层 2 页（看板 / 依赖图） - 验证层 1 页（chapter01 fixture） - 元信息 2 页（wiki-meta / 作者画像） - raw-docs/ 32 个仓库原文快照（含 ADR / CONTEXT / PRD / 工程笔记） 双向引用验证：18 wiki 页 0 孤岛 / 32 raw-docs 100% 被引
基于 raw-docs 32 文件审计，修正以下内容（每条都有 raw-docs 出处）： W5/W6 bus.md / multi-process.md: 删除 ProtocolError（v0-issue-3/4/5 一致决策不引入）；ValueError 直接传播 W7 bus.md: 删除 timeout 参数（v0-issue-5 接口签名无此参数） W8 bus.md: 测试契约改为 v0-issue-5 acceptance 实际列出的 4 条 W14/W23/W24 messages.md / state-machine.md: 类名错拼 → DecoratorEvt / LogEvt / ChapterEndEvt W14 messages.md: 删除 Literal["narration","echo"]（v0-issue-4 spec 用 str + 默认值） W15 messages.md: ChapterEndedEvent → ChapterEndEvt，删除 reason 字段 W19 dashboard.md: 20 ready-for-agent → 19 W21 overview.md / dependency-graph.md / wiki-meta.md: 澄清包结构（物理 src/core/engine/，import 不带 src）
按 issue #23 acceptance criteria 落地： - pyproject.toml（PEP 621，setuptools backend，optional dev/gui extras） - requirements.txt / requirements-dev.txt / requirements-gui.txt 三档拆分 - pytest.ini（testpaths=tests, pythonpath=src, --strict-markers） - README.md（中文，v0 状态"骨架已就位"） - src/{core,core/engine,core/decorators,runtime,runtime/gui,editor}__init__.py - tests/{parser,executor}/inputs/ 占位 + tests/test_skeleton_smoke.py 测试：8 passed in 0.01s，覆盖 import + pyproject 字段 + requirements 拆分 + pytest.ini 配置 + README v0 状态。TDD 流程：red (3 failed) → green (8 passed)。 tmp/triage-23-comment.md 留作 agent brief 审计。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #24 落地 src/core/engine/ast_nodes.py：17 个 dataclass + 3 个 sentinel 单例 + ParserError 错误类。纯数据结构层，不引用 executor / interpreter / bus / protocol。 关键 shape 决策（prototype 推演，见 tmp/ast-shape-prototype.md）： - If.cond: tuple[str, str] = (kind, name)，kind ∈ {"var", "expr"} - Branch.target: NextDecl | CallExpression（CallExpression = echo/in 简写） - sentinel 用 frozen dataclass + 模块级单例（START/END/ID_START） 测试：8 passed in 0.03s，覆盖 import + frozen+slots 反射 + sentinel 单例 + Text/NextDecl/If/Branch/ParserError 实例化与 loc 字段。 TDD 流程：red（ast_nodes 缺）→ green（实现 + 8 pass）→ refactor（删 test 中绕过 frozen 的 dead code，用 pytest.raises 真实验证 frozen 语义）。 本仓库测试总览：16 passed（8 skeleton + 8 AST），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #25 落地 src/core/engine/protocol.py 的命令部分：3 条 cmd dataclass （LoadChapterCmd / UserInputCmd / ShutdownCmd）+ parse_cmd 工厂函数。 约定严格按 issue body： - to_dict() 不做 json.dumps（bus 负责序列化） - from_dict() 不做 json.loads（bus 负责反序列化） - 字段缺失 / 类型错抛 ValueError（不引入 ProtocolError） - parse_cmd 按 d["cmd"] 字段值分发 Refactor 提两个 helper：_check_dict / _require_str 消 3 处重复校验逻辑。 测试：8 passed in 0.01s，覆盖 3 条 round-trip + parse_cmd 分发 + 未知 cmd / 缺 cmd / 缺字段 / 字段类型错四种 ValueError 路径。 本仓库测试总览：24 passed（8 skeleton + 8 AST + 8 cmd），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #26 追加 src/core/engine/protocol.py 事件部分：6 条 evt dataclass （TextEvt / PromptInputEvt / DecoratorEvt / RouteEvt / ChapterEndEvt / LogEvt） + parse_evt 工厂函数。 沿用 v0-issue-3 约定： - to_dict / from_dict 不做 json 序列化（bus 负责） - 字段缺失 / 类型错抛 ValueError - 复用 _check_dict / _require_str helper；新增 _require_str_list helper 关键细节： - TextEvt.style 默认 "narration"（issue body 明确） - DecoratorEvt.args 用 list[str]（便于 JSON 数组） + to_dict 时 list() 防御性拷贝 - 6 条事件全部 round-trip 一致 测试：11 passed in 0.04s，覆盖 6 条 round-trip + parse_evt 分发 + 未知 event / 缺字段 / 字段类型错（tuple/set/int 而非 str/list）三种 ValueError 路径。 本仓库测试总览：35 passed（8 skeleton + 8 AST + 8 cmd + 11 evt），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #27 落地 src/core/engine/bus.py 的 EngineBus： - 双向 Queue：cmd_q (GUI→Engine) + evt_q (Engine→GUI) - default 注入：use_multiprocessing=True → multiprocessing.Queue；False → queue.Queue - JSON 序列化：to_dict → json.dumps(bytes UTF-8) → put；get → json.loads → parse_cmd/parse_evt - ValueError 直接传播（不包装） - close() 排空残留 + 关闭 multiprocessing queue 设计陷阱与对策： - Python 3.14 multiprocessing.Queue 是工厂函数（不是类），isinstance 不工作 → 用 duck type：hasattr(q, "close") + 不是 thread_queue.Queue 即关 - JSON 序列化用 bytes（统一跨 multiprocessing/thread 两种 queue） 测试：8 passed in 0.04s，覆盖 default 注入 + 双向 round-trip + TextEvt 默认 style 保留 + 坏 dict 抛 ValueError + close 排空不抛。 本仓库测试总览：43 passed（8 + 8 + 8 + 11 + 8），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #28 落地 src/core/engine/interpreter.py 的第一阶段： extract_neon_blocks(markdown_text) -> list[NeonBlock]。 行为（ADR §2.1 严格）： - 逐行 .strip() 比较，只匹配精确 ```neon（不支持 ```Neon / ```NEON 变体） - 不嵌套；未关闭抛 ParserError("unclosed neon fence at line N") - 围栏外（标题/```markdown/前后文本）全忽略 - 多块顺序保留 NeonBlock(lineno, content, raw) — lineno 1-indexed 围栏开行； content 围栏内（含末换行）；raw 完整原文（含开闭围栏）。 实现细节：splitlines(keepends=True) 保留行尾换行，content/raw 都直接 join 还原。 测试：10 passed in 0.04s，覆盖单块/无块/多块顺序/markdown 围栏忽略/ 标题序言忽略/lineno 1-indexed/多行 content/未关闭 ParserError/ 大小写变体忽略/空围栏。 本仓库测试总览：53 passed（8 + 8 + 8 + 11 + 8 + 10），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #29 落地 src/core/engine/interpreter.py 的第二阶段： parse_block_skeleton(neon_content, lineno) -> (BlockSkeleton, rest)。 BlockSkeleton: - meta_lines: node start 之前非空非注释行 - body_lines: node start 之后到 node end 之前 - start_lineno: 围栏开行 1-indexed 行为： - 整行注释（行首 #，strip 后）跳过 - 空行（strip 后为空）跳过 - 缺/多 node start/end 抛 ParserError（带 lineno） - 第二返回值是 node end 之后剩余行（多块管线留接口） 测试：10 passed in 0.02s，覆盖标准块 / 缺多 start+end 四种错误 / 注释跳过 / 空行跳过 / start_lineno / 剩余行 / node start 前空行注释。 修 docstring 警告：用 `\`\`\`` 转义代替 \s 转义（Python 3.14 警告未来版本 将拒绝 docstring 里的非法转义序列）。 本仓库测试总览：63 passed（8 + 8 + 8 + 11 + 8 + 10 + 10），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #30 落地 src/core/engine/interpreter.py 第三阶段： parse_block_meta(meta_lines, start_lineno) -> BlockMeta。 IdSpec / BlockMeta 落地： - IdSpec(kind, id, x, route_chapter, lineno) - kind="start": id="start", x=None, route_chapter=None - kind="end": id=None, x=int(X)|None, route_chapter=可选 - kind="normal": id="xxx", x=None, route_chapter=None 行为： - 元数据区只允许 id: 前缀；其他前缀（next: 等）抛 ParserError - 同块内 id:xxx 重复抛 ParserError - endX 中 X 必须自然数（isdigit 检查自动拒负数/浮点/字母） - lineno = start_lineno + 1 + 行 index（跳过围栏开行） 测试：10 passed in 0.03s，覆盖 id:start / id:xxx / id:end 无 X / endX / endX:chapterYY / 多 ID 顺序 / 重复 / 未识别前缀 / endX 浮点/字母 / 负数。 本仓库测试总览：73 passed（8 + 8 + 8 + 11 + 8 + 10 + 10 + 10），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #31 落地 src/core/engine/interpreter.py 第四阶段： parse_next_decls(meta_lines, start_lineno) -> list[NextDecl]。 行为（ADR §3.2.1-3）： - 单 next（0/1 条）：bare / named 都允许 - 多 next（2+ 条）：必须全 named；bare 混合 → ParserError - 重复 var_name → ParserError - 重复 target_id：合法 复用 ast_nodes.NextDecl（v0-issue-2 已有）。 测试：8 passed in 0.04s，覆盖单 bare / 单 named / 多 named / 混合语法 / 多 next 含 1 bare / 重复 var / 重复 target 合法 / 空输入返回 []。 本仓库测试总览：81 passed（8 + 8 + 8 + 11 + 8 + 10 + 10 + 10 + 8），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #32 落地 src/core/engine/interpreter.py 第五阶段： parse_block_body(body_lines, start_lineno, *, block_meta) -> list[Node]。 行为（ADR §3.3）： - 强化首条/末条检查：body_lines[0] 必须是 'node start'，body_lines[-1] 必须是 'node end' - 'node start' / 'node end' 不生成 AST 节点——返回 list 含 Start() 在首 + End() 在末 - 'node in ->var' / 'node in->var' → In(var)（两种格式都接受） - 'node echo var' → Echo(var) - 'node xxx' → NextId(target_id=xxx)（校验留给 v0-issue-16） - '@xxx' 保留为 Text（v0-issue-12 二次处理为 DecoratorCall/DecoratorStop） - 普通文本行 → Text(content=line) - 'node echo' 空变量 / 'node in' 空 var → ParserError block_meta 参数**当前不用**——留接口给 v0-issue-16 跨块校验。 测试：9 passed in 0.04s，覆盖全语句类型 / node in 两种格式 / echo / next_id / 文本行 / @ 保留 / 缺 start / 缺 end / echo 空变量。 本仓库测试总览：90 passed（8 + 8 + 8 + 11 + 8 + 10 + 10 + 10 + 8 + 9），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #33 落地 src/core/engine/interpreter.py 第六阶段： parse_if_stmt(line, lineno, *, next_table) -> If，支持 3 种 if 形态 + 4 种 分支项语法 + next_table 校验。 形态（按 prototype 笔记 tmp/if-parse-prototype.md）： - 二元 node if cond[a,b] → If(cond=("var","cond"), branches=[...]) - 多元 node if var [1:a,2:b,3:echo p_pick] → 含 echo/in CallExpression 占位 - 简略二元 node [a?b:c] → If(cond=("expr","a"), branches=[...]) 分支项语法（不变量 #10）： - 'xxx'（裸变量）/ 'node xxx' → NextDecl（查 next_table） - 'echo xxx' / 'node echo xxx' → CallExpression(kind="echo", var="xxx") - 'in ->xxx' / 'in->xxx' → CallExpression(kind="in", var="xxx") - 其他 → ParserError next_table 校验：分支变量名不在 next_table → ParserError（用 _lookup helper wrap KeyError）。 集成（v0-issue-10 路由）： - parse_block_body 加 next_table 参数（None 时 node if 抛错） - 'node if' / 'node [...]' 前缀 → 转交 parse_if_stmt 测试：11 passed（9 if 单元 + 2 集成到 parse_block_body），无 regression。 本仓库测试总览：101 passed（90 旧 + 11 新），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #34 落地 src/core/engine/interpreter.py 第七阶段： parse_decorator(line, lineno) -> DecoratorCall | DecoratorStop。 判定规则： - 所有 args 都是裸 key（无 ':'）→ DecoratorStop(name=xxx, key=first_key) - 任一 arg 含 ':' → DecoratorCall(name=xxx, args=(...)) - 无 args → DecoratorStop(name=xxx, key="") 错误： - 缺名（@ 后空）→ ParserError - 非法名（非 snake_case 标识符 [a-z_]\\w*）→ ParserError 集成（v0-issue-10 路由）： - @ 前缀 → 转交 parse_decorator（替代之前"保留为 Text"的行为） 测试：6 decorator 单元 passed + v0-issue-10 test 6 改写为 DecoratorCall 验证。 本仓库测试总览：107 passed（101 旧 + 6 新），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #36 落地 src/core/engine/executor.py 第一步： - EventSink Protocol 抽象接口（隔离 EngineBus 依赖） - MemoryEventSink: 测试用内存事件累积器 - GameState(vars, path, next_table)：执行期状态，vars 全字符串 - Executor(story, sink, *, entry_id="start")： - 找 id:start 块，找不到 ValueError - run() 入口 → run_block() - run_block(block) 遍历 body： - Start sentinel 跳过 - End sentinel：id:endX:chapterYY → RouteEvt；普通 id:endX → ChapterEndEvt；无 id:end → RuntimeError - 其他节点 → NotImplementedError（v0-issue-14 落地） 关键约束：executor 模块**不** import core.engine.bus（AST 扫描验证）。 测试：8 passed in 0.04s，覆盖 GameState 默认字段 / MemoryEventSink 累积 / start 块跑 Start sentinel 不抛 / 缺 id:start ValueError / Text NotImplementedError / end+chapter RouteEvt / end 无 chapter ChapterEndEvt / end 无 id RuntimeError。 本仓库测试总览：115 passed（107 旧 + 8 新），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #37 落地 src/core/engine/executor.py 第二步： 节点实现： - Text → TextEvt(content, style="narration") - In(var) → PromptInputEvt(var) + sink.get_cmd() 拿 UserInputCmd 写 state.vars - Echo(var) → TextEvt(content=state.vars[var])；未设抛 KeyError - NextId(target_id) → self.next = (None, target_id) NEXT 跳转逻辑： - 进入新块清 self.next=None - 块末 self.next 非空 → 主循环跳到对应 id 块 - 块末 self.next 空 + id:end route_chapter → RouteEvt - 块末 self.next 空 + id:end 无 chapter → ChapterEndEvt - 块末 self.next 空 + 无 id:end → RuntimeError 跨块 ID 校验：构造时遍历 next_table + NextId 目标，必须在 story 内 MemoryInputSink(MemoryEventSink) 加 get_cmd() 返回 UserInputCmd 测试：11 passed in 0.06s，覆盖 Text/In/Echo/NextId/bare next 跳转/ end+chapter/end 无 chapter/无 end 标记 RuntimeError/Echo 未设 KeyError/ NextId 目标不存在 ValueError/MemoryInputSink 顺序消费。 v0-issue-13 test 3 + test 5 改写：test 3 加 id:end0（避免 v0-issue-14 引入的 严格 RuntimeError），test 5 移除（Text 已实现，不再抛 NotImplementedError）。 本仓库测试总览：125 passed（115 旧 + 11 新 - 1 删 = 125），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #38 落地 src/core/engine/executor.py 第三步： 实现： - Executor._deco_state: dict[name, dict[key, val]] 状态表 - _emit_decorator 处理 DecoratorCall / DecoratorStop - DecoratorCall：按 ':' split args → 更新 _deco_state + 广播 DecoratorEvt(args=原始 token 列表) - DecoratorStop：state 删 key + 广播 DecoratorEvt(args=[key]) - run_block 开头 self._deco_state.clear()（v0 行为选择：进入时清） last-wins 语义：同 key 后到覆盖前到（dict 赋值天然覆盖）。 测试：5 passed in 0.04s，覆盖单 key:val / 多 key:val / 休止符 / 块级作用域 / last-wins。 本仓库测试总览：130 passed（125 旧 + 5 新），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #39 落地 src/core/engine/executor.py 第四步： 实现： - _execute_if(if_node)：v0 永远选 branches[0]，广播 LogEvt - NextDecl target → self.next = (var, target_id) - CallExpression echo target → 广播 TextEvt（v0 打桩不跳） - CallExpression in target → 广播 PromptInputEvt（v0 打桩不阻塞） - _validate_target_ids 补全：加 If.branches[i].target 是 NextDecl 的 target_id 校验 测试：7 passed in 0.04s，覆盖多元 if 选第一分支 + LogEvt / 二元 if / 简略二元 if / 多元 echo 第一分支 / 总是 LogEvt / 构造时 next 校验 / 构造时 if 分支校验。 本仓库测试总览：137 passed（130 旧 + 7 新），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #40 落地 src/core/engine/main.py：装配 EngineBus + 加载章节 + 命令循环 + GUI 降级。 实现： - main(chapter_path: str) -> int - _load_story 用 v0-issue-6..12 全管线编译 chapter → Story - _try_spawn_gui 容错 FileNotFoundError（v0-issue-18 尚未落地） - 加载失败 / Executor 异常 → LogEvt error + 退出 1 - 成功退出 0 + bus.close() + gui terminate 修复 v0 实施链 3 个上游 bug： - ast_nodes.IdEnd.x 改为 int | None（接受 id:end 简写） - parse_block_meta 改用 IdMeta / IdEnd（弃用未注册的 IdSpec） - parse_block_meta 跳过 next: 行（容错 v0 mixed meta 区） - parse_next_decls 跳过 id: 行（容错 v0 mixed meta 区） - parse_block_skeleton 保留 node start/end 在 body_lines（v0-issue-10 sentinel 检查依赖此形态） 测试：4 passed in 0.04s + 修复 1 test 期望 / 改 2 个 v0-issue-7 test / 重写 v0-issue-8 test 用 IdMeta/IdEnd。 本仓库测试总览：141 passed（137 旧 + 4 新 - 3 改 = 141），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #41 路径 B 落地 src/runtime/gui/main.py（CLI print+input， 不依赖 PyQt6）。 实现： - main(bus=None) -> int：拿事件 → 打印 / input → put_cmd - 事件分发（v0 spec 严格）： - TextEvt → print(f"[text] {content}") - PromptInputEvt → print(f"[prompt_input] {var}") + input() + put_cmd(UserInputCmd) - DecoratorEvt / LogEvt → 静默 - RouteEvt → print(f"[route → {target}]") + 返回 0 - ChapterEndEvt → print("[chapter end]") + 返回 0 - bus.get_evt() 返回 None → 退出循环 - 接受 bus 参数便于测试（fake bus） 测试：6 passed in 0.04s，覆盖 import / text / prompt_input→user_input cmd / chapter_end 退出 0 / route 退出 0 / decorator+log 静默。 本仓库测试总览：147 passed（141 旧 + 6 新），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
按 issue #42 落地： - chapters/chapter01.md 精确复制 ADR §附录 A（v0 官方 fixture） 演示元数据、单/多 next、node start/end、文本行、node in/echo、 多元 node if、@Style 修饰器（含休止符）、id:endX:chapterYY 路由、 id:endX 普通结局、整行注释 - tests/test_echo.md 最小 fixture（in → echo → end） - tests/integration/test_echo_path.py 端到端：MemoryInputSink 跑 test_echo.md 断言事件流 + 变量写入 + EngineBus 真 round-trip - tests/integration/test_chapter01_e2e.py 端到端： - subprocess spawn 验证 main 至少能启动（GUI 缺时 headless 阻塞——预期） - _load_story 验证 chapter01.md 走 v0-issue-6..12 全管线解析成 6 块 Story v0 限制： - 跨进程真 spawn + 喂 input 留给 v1 阶段（GUI 进程真实现 input 阻塞时） - test_echo.md start 块加 id:end0（v0-issue-14 严格化块末 end marker 后必需） 测试：5 passed in 1.23s（2 chapter01 + 3 echo_path 单元式端到端）。 本仓库测试总览：152 passed（147 旧 + 5 新），无 regression。 Co-authored-by: Cursor <cursoragent@cursor.com>
基于 2026-06-15 cursor 落地的 19 个 feat commit（HEAD 1a76382，152/152 测试通过）， 重新审计代码 vs spec 偏差，新增 implementation-deviations.md。 ## 实测更新 - 新增 [[30-protocol/implementation-deviations]]——3 条真实偏差 + 7 条确认 - dashboard.md：完成度 0/22 → 20/22（代码）+ 2/22 HITL 待 owner - 00-index/README.md：实测 HEAD/测试数/包结构 - README.md：双推状态 + 实测 + HITL 链接 - vision.md：M1 标 ✅，剩 HITL - 10-design/vision.md：仓库状态改为实测 - 90-meta/wiki-meta.md：增量 cursor 实施事件 + 偏差审计行 - 90-meta/about-author.md：新增 CallExpression / 不替 owner 拍板 原则 - 20-architecture/ast-nodes.md：用实测代码替换 spec 描述 + CallExpression 标注 ## 3 条偏差 - D1-confirmed：decorator_state 在 run_block 开头清（v0-issue-15 决策，与 ADR §4.1 不一致） - D-NEW-1：Branch.target 用 CallExpression 包装（spec 是 NextDecl | Echo | In） - D-NEW-2：ParserError.loc 变可选（spec 必填） - D-main：v0-issue-17 main.py 不读 cmd_q（v0 简化） ## 双推 - main 分支：origin/cursor/setup-issues-v0-vertical-slices - wiki 分支：origin/wiki（强制同步） 注：codegraph MCP 不可用（stdio 模式未对外暴露），用直接读 7 个 .py 全文的方式做偏差审计，效果等价。
codegraph init 建立索引（37 文件 / 470 nodes / 1566 edges in 233ms）， 通过 stdio MCP 协议直连 codegraph serve --mcp，4 个 tool 全可用： - codegraph_search - codegraph_callers - codegraph_node - codegraph_explore 基于 codegraph_explore 自动检测，发现 4 个 internal helper 没覆盖单测： - GAP-1: EngineBus._drain / _close_queue（bus.py:63-74） - GAP-2: Executor._emit_decorator（executor.py:214） - GAP-3: Executor._validate_target_ids（executor.py:84） - GAP-4: main._try_spawn_gui（main.py:54） 这些都是 internal helper（只被 self 调用 1 次），pytest 152/152 全过 = 间接覆盖足够，但无"边界路径"专门单测。owner 在 v0-issue-20/21 HITL 阶段决定是否补这些单测（ADR-0002 决策：v0 范围还是 v1+）。 ## 同步 - implementation-deviations.md 增 CodeGraph 调用关系图 + 4 GAP - .gitignore 加 .codegraph/ 注释（SQLite 索引本地生成，不入仓） - .obsidian/ 从 index 删除（之前 commit 误加，重新 --cached 移除） 双推：main + wiki 分支（force sync）
owner @HeDaas-Code 在 2026-06-15 明确指示"帮我把两个需要 HITL 的 iss 做了"。 本 commit 是 HITL 代执行产物，所有"owner 接受"决策需 owner 事后审查。 ## 新增文件 - docs/adr/0002-v0-engine-implementation.md（9.4 KB） - 4 条实现 vs spec 偏差登记（D1-confirmed / D-NEW-1 / D-NEW-2 / D-main） - 4 条 CodeGraph 覆盖盲点 GAP（推到 v1+） - 19 条 v0-issue feat commit 索引 - 验收对照（§8 MVP 18 条 + §11 不变量 10 条 + 3 条 grep） - 已知未实现清单 + 后续 ADR 修订建议 - owner 必审查项（§10）—— agent 越权代做的"反悔点" - HITL 代执行声明（§11）—— 明确登记"不接受隐式覆盖" - docs/audit/v0-invariant-audit.md（8.4 KB） - §11 不变量 10 条逐条结果 - 3 条 grep 守护实测（全部 0 命中） - §8 MVP 表 18 条逐条勾（含端到端） - 已知未实现 + 偏差 + 覆盖盲点 - tests/test_invariants.py（6.2 KB，11 用例） - 10 条 §11 不变量守护 - 1 条 TODO/FIXME 守护 - 全部通过 subprocess 调 pytest / grep 实现"自检"机制 - tests/test_mvp_table.py（6.3 KB，19 用例） - 18 条 §8 MVP 表逐条勾 - 1 条 v0 唯一跑通路径端到端 - 全部 PASSED ## 测试结果 ``` pytest tests/ -q --no-header 182 passed in 8.04s ``` （152 原有 + 30 新增 = 182） ## owner 必审查（agent 越权代做） 1. §10 ADR-0002 §5 4 条偏差的"接受"是否符合你的设计意图 2. §10 §6 4 GAP 是否要在 v0 补，还是按计划推到 v1+ 3. §10 §8 GUI 路径 A 推迟到 v1 是否同意 如有不同意，直接编辑 docs/adr/0002-v0-engine-implementation.md 或在本 commit 评论里指出。
HITL #43 #44 由 agent 在 owner 指示下代执行验收 + close 全部 22 个 GH issue。 本 commit 同步 wiki 反映 v0 已闭环状态。 ## wiki 同步 - dashboard.md：22/22 CLOSED，182/182 PASSED，"owner 必做清单" → "owner 必审查清单" - 00-index/README.md：HEAD 125f237 / 测试 182/182 / Issue 22 CLOSED - README.md：v0 全部完成 + ADR-0002 + audit 报告 + owner 必审查链接 - 10-design/vision.md：M1 标 ✅ v0 完工 + commit 125f237 - 90-meta/wiki-meta.md：v0 闭环状态 + owner 必审查清单 ## 双推 - main 分支：origin/cursor/setup-issues-v0-vertical-slices - wiki 分支：origin/wiki（force sync）
之前 README 是 v0-issue-1 落地时的占位版本（"v0-issue-1 骨架已就位，引擎未实现"）。 v0 全部 19 条 AFK vertical slice + 2 条 HITL 已落地，22/22 issue closed，182/182 测试通过。 ## 新 README 内容 - 顶部状态表：v0 闭环 + 182 测试 + 22/22 issue closed + 4 条偏差登记 - "这是什么"段：v0 设计核心（Markdown + neon DSL / NEXT 引用语义 / 双进程 / 修饰器） - 快速跑通：安装 + pytest + 引擎入口 + 端到端 fixture - 双进程架构图（Engine ↔ GUI 走 EngineBus） - 7 个核心模块表（来源：codegraph files 索引，37 文件 / 470 nodes / 1566 edges） - 项目结构树（含 chapters/、docs/、工作Wiki/、tests/） - 文档与设计表（ADR-0001/0002、PRD-0001、audit、wiki、CLAUDE.md、CONTEXT-MAP.md） - v0 4 条实现偏差摘要（D1-confirmed / D-NEW-1 / D-NEW-2 / D-main） - v0 已知未实现清单（推到 v1+） - 开发段：跑测 + CodeGraph CLI 用法 - 分支与 commit 约定 ## 验证 - 14 个文档 / 代码 link 全部存在 - python3 -m pytest tests/ -q → 182 passed in 11.63s - 与 ADR-0002 / audit 报告内容一致 Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Pull request overview
该 PR 将 cursor/setup-issues-v0-vertical-slices 分支的 v0 baseline 闭环内容合并进 main：包含引擎核心实现（AST/解析器/执行器/总线/入口/CLI GUI 占位）、章节与测试夹具、以及大量 ADR/PRD/审计与工作 Wiki 的规格与记录文件，用于支撑后续 v1 设计。
Changes:
- 新增/完善
src/core/engine/*（AST、protocol、EngineBus、interpreter、executor、main）与src/runtime/gui/main.py（CLI GUI 占位）。 - 新增大批 pytest 用例、端到端/集成测试与 fixture（
chapters/chapter01.md、tests/test_echo.md等）。 - 补齐仓库工程化配置与文档/Wiki（
pyproject.toml、requirements、pytest.ini、CONTEXT*、各 v0 issue 规格草案等）。
Reviewed changes
Copilot reviewed 136 out of 152 changed files in this pull request and generated 25 comments.
Show a summary per file
| File | Description |
|---|---|
pytest.ini |
pytest 配置（testpaths/pythonpath/addopts） |
pyproject.toml |
包元数据与可选依赖（dev/gui） |
requirements.txt |
运行时依赖占位说明 |
requirements-dev.txt |
dev extras 安装入口 |
requirements-gui.txt |
gui extras 安装入口 |
.gitignore |
忽略 .codegraph/、.obsidian/ 等本地文件 |
.codegraph/.gitignore |
忽略 CodeGraph 本地数据文件 |
src/core/engine/ast_nodes.py |
v0 AST 数据结构与 ParserError |
src/core/engine/bus.py |
EngineBus：Queue + JSON 序列化/反序列化 |
src/core/engine/interpreter.py |
neon fence 提取、块骨架/元数据/next/body/if/装饰器解析 |
src/core/engine/executor.py |
v0 执行器：核心节点、装饰器、if stub、路由/结局处理 |
src/core/engine/main.py |
引擎入口：加载章节、装配总线、尝试 spawn GUI、运行 executor |
src/core/engine/__init__.py |
包初始化 |
src/core/__init__.py |
包初始化 |
src/core/decorators/__init__.py |
包初始化 |
src/runtime/__init__.py |
包初始化 |
src/runtime/gui/__init__.py |
包初始化 |
src/runtime/gui/main.py |
CLI GUI 占位：打印事件 + input 回传 |
src/editor/__init__.py |
editor 上下文包初始化占位 |
chapters/chapter01.md |
v0 章节演示 fixture |
tests/__init__.py |
测试包初始化 |
tests/core/__init__.py |
core 测试包初始化 |
tests/parser/__init__.py |
parser 测试包初始化 |
tests/parser/inputs/.gitkeep |
占位目录 |
tests/executor/__init__.py |
executor 测试包初始化 |
tests/executor/inputs/.gitkeep |
占位目录 |
tests/test_skeleton_smoke.py |
骨架 smoke tests（import/config/readme 等） |
tests/test_echo.md |
最小可跑通路径 fixture（in→echo→end） |
tests/core/test_protocol_cmd.py |
cmd schema 测试 |
tests/core/test_protocol_evt.py |
evt schema 测试 |
tests/core/test_extract_neon.py |
neon fence 提取测试 |
tests/core/test_block_skeleton.py |
块骨架解析测试 |
tests/core/test_block_meta.py |
元数据区解析测试 |
tests/core/test_next_decls.py |
next 声明解析测试 |
tests/core/test_block_body.py |
body 解析测试 |
tests/core/test_if_parse.py |
node if 解析测试 |
tests/core/test_decorator_parse.py |
decorator 解析测试 |
tests/core/test_executor_skeleton.py |
Executor 骨架测试 |
tests/core/test_executor_nodes.py |
Text/In/Echo/NextId 与 NEXT 跳转测试 |
tests/core/test_executor_decorator.py |
decorator 执行测试 |
tests/core/test_executor_if.py |
if stub + target id 校验测试 |
tests/core/test_engine_bus.py |
EngineBus 测试 |
tests/core/test_main_entry.py |
main() 入口测试 |
tests/runtime/test_gui_protocol.py |
CLI GUI 占位协议测试 |
tests/integration/test_echo_path.py |
test_echo.md + MemoryInputSink 集成测试 |
tests/integration/test_chapter01_e2e.py |
chapter01 解析/启动的端到端测试 |
工作Wiki/raw-docs/工程笔记/v0-issue-2-ast.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-3-cmd.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-4-evt.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-5-bus.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-6-neon.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-7-skel.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-8-meta.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-9-next.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-10-body.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-11-if.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-12-deco.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-13-exec.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-14-nodes.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-15-deco-exec.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-16-if-end.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-17-core-main.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-18-gui.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-19-fixture.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-20-invariant.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/v0-issue-21-adr.md |
v0-issue 规格草案 |
工作Wiki/raw-docs/工程笔记/01-parent.md |
v0 父任务说明草案 |
工作Wiki/raw-docs/工程笔记/02-skeleton.md |
skeleton 任务草案 |
工作Wiki/raw-docs/triage-labels.md |
issue 标签映射说明 |
工作Wiki/raw-docs/issue-tracker.md |
GitHub issue tracker 操作约定 |
工作Wiki/raw-docs/domain.md |
Domain docs / context map 说明 |
工作Wiki/raw-docs/CONTEXT-MAP.md |
多上下文映射表 |
工作Wiki/raw-docs/CONTEXT-core.md |
core 上下文术语表 |
工作Wiki/raw-docs/CONTEXT-editor.md |
editor 上下文术语表 |
工作Wiki/raw-docs/CONTEXT-runtime.md |
runtime 上下文术语表 |
工作Wiki/raw-docs/CLAUDE.md |
项目沟通/约定说明 |
工作Wiki/10-design/vision.md |
v0 愿景/里程碑整理 |
工作Wiki/10-design/design-philosophy.md |
设计哲学说明 |
工作Wiki/90-meta/about-author.md |
meta 文档（作者侧写/协作建议） |
tmp/v0-issue-1-done-comment.md |
临时/生成文档 |
tmp/v0-issue-2-done-comment.md |
临时/生成文档 |
tmp/triage-23-comment.md |
临时/生成文档 |
tmp/triage-25-comment.md |
临时/生成文档 |
tmp/triage-26-comment.md |
临时/生成文档 |
tmp/triage-27-comment.md |
临时/生成文档 |
tmp/triage-28-comment.md |
临时/生成文档 |
tmp/triage-29-comment.md |
临时/生成文档 |
tmp/triage-30-comment.md |
临时/生成文档 |
tmp/triage-31-comment.md |
临时/生成文档 |
tmp/triage-32-comment.md |
临时/生成文档 |
tmp/triage-33-comment.md |
临时/生成文档 |
tmp/triage-34-comment.md |
临时/生成文档 |
tmp/triage-36-comment.md |
临时/生成文档 |
tmp/triage-37-comment.md |
临时/生成文档 |
tmp/triage-38-comment.md |
临时/生成文档 |
tmp/triage-39-comment.md |
临时/生成文档 |
tmp/triage-40-comment.md |
临时/生成文档 |
tmp/triage-41-comment.md |
临时/生成文档 |
tmp/triage-42-comment.md |
临时/生成文档 |
tmp/ast-shape-prototype.md |
临时原型推导 |
tmp/if-parse-prototype.md |
临时原型推导 |
tmp/issues/* |
临时/镜像 issue 文本草案 |
Comments suppressed due to low confidence (2)
工作Wiki/90-meta/about-author.md:7
- 该文档包含对“项目所有者身份/账号”“本机已登录 gh”“操作系统/本机 PATH”等个人与环境信息的推断与记录（即使是自述/推断，也会在仓库里长期留存）。这类内容与代码实现无关，且容易造成隐私与安全风险。建议改为仅记录可复用的协作流程/工程经验，去掉个人身份与本机环境细节。
工作Wiki/90-meta/about-author.md:29 - 这一段记录/推断具体操作系统、工具链路径等本机环境信息（含绝对路径），属于与项目无关的敏感信息，容易造成隐私/安全风险，也会让文档产生“人身侧写”的不适感。建议直接删除整段或改成一句通用的协作约定说明。
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1
to
+4
| [pytest] | ||
| testpaths = ["tests"] | ||
| pythonpath = ["src"] | ||
| addopts = "-ra --strict-markers" |
Comment on lines
+10
to
+11
| REPO_ROOT = "/home/hedaas/桌面/Neural Engine" | ||
| sys.path.insert(0, f"{REPO_ROOT}/src") |
Comment on lines
+10
to
+11
| REPO_ROOT = "/home/hedaas/桌面/Neural Engine" | ||
| sys.path.insert(0, f"{REPO_ROOT}/src") |
Comment on lines
+9
to
+10
| REPO_ROOT = "/home/hedaas/桌面/Neural Engine" | ||
| sys.path.insert(0, f"{REPO_ROOT}/src") |
Comment on lines
+9
to
+10
| REPO_ROOT = "/home/hedaas/桌面/Neural Engine" | ||
| sys.path.insert(0, f"{REPO_ROOT}/src") |
Comment on lines
+54
to
+65
| def _try_spawn_gui() -> subprocess.Popen | None: | ||
| """尝试 spawn GUI 子进程。失败（v0-issue-18 尚未落地）返回 None。""" | ||
| try: | ||
| proc = subprocess.Popen( | ||
| [sys.executable, "-m", "runtime.gui.main"], | ||
| stdout=subprocess.DEVNULL, | ||
| stderr=subprocess.DEVNULL, | ||
| ) | ||
| return proc | ||
| except FileNotFoundError: | ||
| return None | ||
|
|
| ``` | ||
|
|
||
| ```neon | ||
| id:ca |
| ``` | ||
|
|
||
| ```neon | ||
| id:cb |
Comment on lines
+58
to
+60
| ```neon | ||
| id:end1:chapter02 | ||
| # 路由标记：endX 后第三段是目标章节名 |
Comment on lines
+50
to
+53
| exe = Executor(story, sink) | ||
| # c1 块 t_a 跳 ca → ca 块 body 有 text + end 但 meta 无 id:end → RuntimeError | ||
| with pytest.raises(RuntimeError): | ||
| exe.run() |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
摘要
把
cursor/setup-issues-v0-vertical-slices分支（22 commits，v0 闭环）合并到main。内容
测试
ADR / PRD 链接
状态
后续
合并后准备设计 v1。