NeoCode 运行时与能力分层优化计划（修订版）

[fennoai]

更新时间：2026-04-14

本文是对 #268 的修订版，目标是解决前序评审指出的关键问题：

• 停止规则无唯一判定与优先级
• progress 判定易被伪进展欺骗
• capability / token estimation 缺少一致性与误差治理
• 阶段 1 过载、验收不可量化
• 与现有 issue（Gateway / Skills / Todo / TUI）存在排期冲突

0. 关系声明与冲突处置

本计划作为 #268 的修订执行版本，原则上以本 issue 为后续拆分依据。

0.1 与现有 issue 的关系矩阵

1. #243（runtime 职责重构）：merge（并入本计划阶段 1A/1B，作为控制面收敛子任务）。
2. #247（架构 2.0）：merge（保留“分层方向”，但主链路阶段不要求 Gateway 必经）。
3. #249（Gateway 研讨）：defer（保留为远期架构议题，不阻塞当前主链路演进）。
4. #250（Gateway 进程骨架）：keep as experiment（保持实验属性，不作为本计划依赖）。
5. #255~#260（Skills）：keep + reschedule（纳入本计划中后段，明确依赖边界）。
6. #261/#262（Todo）：keep + advance（从原阶段 8 前置到阶段 3，作为 progress 证据输入）。
7. #266（TUI 简化）：merge（与统一执行入口阶段联动，不独立走分叉语义）。
8. #268：superseded-by-this-issue（保留历史记录，不再作为执行主单）。

0.2 顶层拍板（避免双轨）

1. 当前主链路仍为 TUI -> Runtime -> Provider/ToolManager；Gateway 不是近期必经入口。
2. Todo 不再后置，前置进入运行时判定链路。
3. Skills 不再“未定义顺序”，明确安排在 Repository 分层之后。

1. 术语与判定规范（先于阶段实施）

1.1 统一 StopReason（互斥 + 优先级）

运行停止必须产出唯一 StopReason，优先级固定如下（从高到低）：

1. STOP_FATAL_ERROR
2. STOP_BUDGET_HARD_TURN
3. STOP_BUDGET_WALL_TIME
4. STOP_BUDGET_TOOL_CALLS
5. STOP_BUDGET_ESTIMATED_PROMPT
6. STOP_BUDGET_OBSERVED_TOKENS
7. STOP_NO_PROGRESS
8. STOP_REPEAT_CYCLE
9. STOP_COMPLETED
10. STOP_USER_INTERRUPT

约束：

1. 同一轮只能有一个 StopReason（唯一写入事件与 ledger）。
2. 预算类与行为类冲突时，按优先级决议，不允许并列。
3. 事件层与持久化层使用同一枚举，禁止字符串散落。

1.2 Progress 证据模型（Evidence）

progress 不再基于“看起来在动”，而是基于证据计分（可持久化）：

1. EVIDENCE_TASK_STATE_CHANGED：Todo/Task 状态发生合法迁移。
2. EVIDENCE_WRITE_APPLIED：写工具成功且产生有效文件差异。
3. EVIDENCE_VERIFY_PASSED：验证命令或验证工具通过。
4. EVIDENCE_NEW_INFO_NON_DUP：工具结果产生新信息哈希。
5. EVIDENCE_PHASE_ADVANCED：phase 合法推进。

规则：

1. 仅 EVIDENCE_NEW_INFO_NON_DUP 不能单独抵消 no-progress（防噪声）。
2. 每轮计算 ProgressScore，低于阈值则 streak +1。
3. compact 成功仅重置 repeat-cycle，不直接记作业务进展。

1.3 事件协议（Runtime Event Schema）

新增并冻结最小事件集合：

1. phase_changed
2. budget_checked
3. progress_evaluated
4. compact_applied
5. stop_reason_decided
6. permission_requested
7. permission_resolved
8. ledger_reconciled

每个事件最小字段：run_id, turn, phase, timestamp, payload_version。

2. 目标边界（修订版）

2.1 runtime（控制面）

负责：budget/phase/progress 判定、tool 回灌编排、permission 等待与恢复、事件发射。

不负责：规则解析、repo 检索、tokenizer 细节、Git 语义、审批策略判定。

2.2 provider（协议与计数能力）

负责：模型协议适配、能力基线解析、token 分段估算器、流式解析、usage 原始采集。

不负责：stop 决策、context 选择策略、progress 判定、repo-aware 检索。

关键修订：provider 输出“分段估算值”，runtime 汇总并执行预算判定。

2.3 config（静态配置）

负责：预算档位/profile、provider/model 选择、capability override。

不负责：运行中 streak、动态缓存、reconciled 账本。

2.4 session（持久化）

负责：transcript、run ledger、todo/task state、resume checkpoint。

2.5 context / instructions / repository / tools / tui

1. instructions：规则发现与合并，输出 InstructionBundle。
2. repository：repo-aware 结构化输入，输出有 token 上限与来源字段。
3. context：纯 composer，不做规则发现与 repo 检索。
4. tools：统一可调用能力与参数校验（含 git/review/workspace checkpoint）。
5. tui：展示与控制，不直接执行工作区操作。

3. 能力基线与估算治理

3.1 Capability 解析一致性协议

解析顺序：config override > catalog cache > builtin table > live discovery > conservative fallback。

必须补齐：

1. cache_ttl 与 stale-while-revalidate。
2. invalidation 触发：model 切换、provider 版本变化、显式刷新。
3. conflict_resolution：高优先级来源覆盖低优先级来源并记录来源链。
4. CapabilitySource 与 CapabilityConfidence 统一枚举。

3.2 Token Estimation 误差治理

provider 输出：

1. EstimatedPromptTokens
2. EstimatedInjectedTokens
3. EstimatedToolSchemaTokens
4. EstimationConfidence

runtime 维护误差统计：

1. error_ratio = |observed-estimated| / max(observed,1)。
2. 按 provider+model 维护滑动窗口（如最近 N 轮）。
3. 超阈处理：降级使用更保守预算系数，并发出 estimation_degraded 事件。

4. 运行模型（修订后）

1. Capability Baseline（含一致性协议）
2. Preflight Estimation（分段估算）
3. Budget + Phase + Evidence Progress
4. Usage Reconciliation（estimated/observed/reconciled）
5. Resume Checkpoint（原子性定义）
6. Context Health（compact + retrieval）
7. Delivery Surface（git/review/workspace checkpoint）

5. 分阶段实施（重排）

阶段 1A：判定语义最小闭环（runtime + config）

目标：先把“怎么停、怎么判进展、怎么发事件”定死。

完成项：

1. StopReason 枚举、优先级与互斥规则。
2. Phase 最小机（plan/execute/verify）与并行 tool call 决议规则。
3. Progress evidence 与 no-progress/repeat-cycle 计数器。
4. runtime 事件协议最小集合。

不做：capability/estimation/ledger/checkpoint。

验收（量化）：

1. StopReason 决议一致性测试通过（冲突输入下 100% 唯一结果）。
2. phase 迁移测试覆盖并行 tool call 场景。
3. progress 判定误触发回归用例覆盖完成。

阶段 1B：预算与 compact 预算化（runtime + provider + catalog + config）

目标：在 1A 语义稳定后接入预算。

完成项：

1. capability 一致性协议（TTL/失效/冲突仲裁）。
2. provider 分段 token estimation 接口。
3. budget stop 生效（estimated + observed 两条线）。
4. auto_compact_budget 与 reactive_compact_budget。

验收（量化）：

1. discovery 缺失时能力基线仍可回退且来源可追踪。
2. estimation 与 observed 误差统计可落库并可查询。
3. 预算耗尽触发的 stop reason 与事件一致。

阶段 2：Run Ledger 与 Usage 调和（runtime + session + provider）

目标：把预算从“临时判断”升级为“可恢复账本”。

完成项：

1. session 持久化 estimated / observed / reconciled。
2. 每轮调和策略与异常保留策略。
3. compact / budget 判定切换到 reconciled ledger。

验收：usage 缺失、usage 异常、usage 正常三类路径均稳定。

阶段 3：Todo 前置接入（session + runtime + context，关联 #261/#262）

目标：让 progress 有任务语义证据，不再依赖文本猜测。

完成项：

1. 结构化 todo/task state 持久化与恢复。
2. context 暴露 todo 给模型。
3. runtime 使用 todo 变化参与 progress 判定。

验收：todo 状态迁移与 no-progress 判定一致可测。

阶段 4：Resume Checkpoint（session + runtime）

目标：预算耗尽可断点续跑。

完成项：

1. ResumeCheckpoint 最小字段集。
2. checkpoint 写入原子性：transcript/tool_result/ledger/checkpoint 同事务提交。
3. 恢复冲突策略：checkpoint 版本不匹配时降级为新 run 并保留告警。

验收：中断恢复后 phase、预算、todo、ledger 一致。

阶段 5：Instructions 分层（instructions + context + app）

目标：把规则解析从 context 抽离。

完成项：

1. 规则发现与合并迁入 internal/instructions。
2. context 仅消费 InstructionBundle 进行 composer。
3. AGENTS/CLAUDE 等规则加载边界与截断策略测试补齐。

阶段 6：Repository 能力层（repository + context + runtime）

目标：context health 从“只压缩”升级为“压缩+检索”。

完成项：

1. RepositoryBundle 契约：summary, changed_files, entrypoints, retrieval_hits。
2. 每类输出 token budget 上限与排序规则。
3. 每条检索结果带来源字段（path/line/hash）。

验收：context 注入在 token 预算内，且来源可追踪。

阶段 7：Skills 与 Tools/Security 边界收敛（关联 #255~#260）

目标：把技能能力放入既有执行治理链路，而非旁路。

完成项：

1. skills activation 与 context 注入链路。
2. skills 调工具必须经过 ToolManager/PermissionEngine/Sandbox。
3. 会话可观测字段与 runtime 事件对齐。

阶段 8：Git / Review / Workspace Checkpoint 工具化（tools + security + runtime）

目标：补齐交付面，避免 verify 依赖裸 bash。

完成项：

1. tools/git、tools/review、tools/workspacecheckpoint。
2. 权限拒绝行为矩阵：retry / degrade / stop 明确。
3. runtime 仅消费结果，不吸纳 Git 语义。

阶段 9：TUI 收口与文档归真（tui + docs）

目标：统一执行入口，清理语义分叉。

完成项：

1. 收敛 & <command> 到工具链并提供替代提示。
2. slash 命令保留控制面职责。
3. 文档与真实实现对齐（含 gateway 的定位说明）。

6. 失败路径与降级策略（统一）

1. capability discovery 失败：使用 cache/builtin/fallback，标记低置信度。
2. usage 缺失：走 estimated + 低置信度，继续运行。
3. 权限被拒：按工具策略执行 retry/degrade/stop，并发 permission_resolved。
4. compact 失败：不终止 run，递增 retry 计数并保留 stop 判定权。

7. 配置策略（防止过度暴露）

只对外暴露高阶配置：

1. runtime_profile（safe/balanced/aggressive）
2. budget 核心上限（turn/time/token/tool_calls）
3. compact 双预算

细粒度阈值默认留在 runtime policy 常量或 profile 映射，不直接散落在用户配置。

8. 测试映射（阶段 -> 测试类型）

1. 阶段 1A：判定优先级表驱动测试、phase 迁移测试、事件快照测试。
2. 阶段 1B：capability 来源仲裁测试、估算误差测试、预算停止测试。
3. 阶段 2：ledger 调和测试、缺失/异常 usage 回归。
4. 阶段 3~4：todo 与 checkpoint 一致性测试、恢复回归。
5. 阶段 5~9：分层边界测试、权限拒绝矩阵测试、TUI 迁移行为测试。

9. 全程禁止事项（保持不变）

1. 不保留旧新运行模型双轨。
2. 不让 runtime 吸纳规则解析/repo 检索/Git 语义/tokenizer 细节。
3. 不让 config 保存动态运行态。
4. 不做无结构化信号的语义猜测。
5. 不拆空心模块。
6. 不混淆 resume checkpoint 与 workspace checkpoint。

10. 预期结果

完成后，NeoCode 将具备：

1. 可判定、可测试、可恢复的运行控制面。
2. 有一致性协议的能力基线与可治理的 token 估算。
3. 基于结构化证据的 progress 判定（含 todo 语义）。
4. 清晰的规则层、仓库输入层、交付工具层边界。
5. 与现有 issue 体系不冲突的统一实施路径。

[phantom5099]

@xgopilot 说一说有没有职责不清的地方

[fennoai]

职责不清点（基于 #272 当前文本）

1. permission 归属仍有交叉
   runtime 负责 permission 等待/恢复（2.1），但阶段 7 又要求 skills 必须经过 ToolManager/PermissionEngine/Sandbox。PermissionEngine 属于 tools 子系统还是独立控制面组件，当前未定。

2. Progress 证据的“生产者/判定者”边界不完整
   runtime 做 ProgressScore 判定，但 EVIDENCE_WRITE_APPLIED（有效 diff）、EVIDENCE_VERIFY_PASSED（验证通过）需要工具层产出标准化证据。现在只定义了 evidence 类型，未定义证据由谁生成、谁签名、谁可回放。

3. Capability baseline 的缓存归属不明确
   3.1 写了 catalog cache + TTL + SWR + invalidation，但 2.3 又明确 config 不管动态缓存。缓存最终落在 provider、catalog 还是 session，需要单点归属。

4. Token 估算误差窗口的持久化边界不清
   3.2 要求 runtime 维护滑动窗口并降级；阶段 2 又引入 session ledger 持久化。误差窗口是“仅运行时内存态”还是“跨 run 持久态”，当前未明确，影响恢复一致性。

5. STOP_USER_INTERRUPT 优先级与语义冲突窗口未定义
   当前排在最低优先级；若同轮同时满足预算停止与用户中断，谁生效虽然可由优先级决定，但是否允许“用户中断抢占”没有明确策略，可能导致交互预期不一致。

6. Checkpoint 原子性定义与存储能力存在落差风险
   阶段 4 要求 transcript/tool_result/ledger/checkpoint 同事务提交；若底层仍是 JSON 文件存储，事务边界实现方式（WAL/临时文件+rename/两阶段标记）需在职责上先定，否则要求不可验证。

7. Repository 与 Context 的 token 预算执行边界不够硬
   阶段 6 既要求 repository 输出各类内容预算上限，又说 context 负责 composer。预算“决策权”和“最终裁剪权”在两层之间谁负责，尚未写死。

建议在 issue 中补 7 条“拍板句”

1. PermissionEngine 归属到 internal/tools（或独立 internal/security），runtime 只消费 permission_requested/resolved 事件，不做策略判定。
2. 新增 ProgressEvidenceRecord 契约：由 tool/runtime 适配器产出，runtime 只聚合评分。
3. CapabilityCache 单点归属 catalog（建议），config 仅提供 profile/override，不持有运行态。
4. 明确误差窗口策略：in-memory per run 或 persisted per provider+model 二选一，并写入阶段 2 验收。
5. 明确用户中断策略：要么提升优先级，要么声明“同轮不抢占，仅下一判定点生效”。
6. 为 checkpoint 增加“文件存储原子提交方案”说明与测试验收条目。
7. 明确 token 预算职责：repository 负责候选排序，context 负责最终裁剪与超限兜底。

本次处理范围

• 已完成：按你这条评论要求，定位并说明“职责不清”点。
• 未执行：代码修改、测试、提交（本次是分析答复，不涉及实现）。

View job run

[phantom5099]

@xgopilot 再评估一次有没有和当前项目或是issue计划相冲突或者是已完成的地方

[fennoai]

再评估结论

有冲突，也有已完成项。最大的矛盾是：#272 的阶段顺序假设“先做 1A/1B 再做 3”，但仓库里已经提前落地了部分“阶段 3（TaskState/Todo 语义）”，而“阶段 1A 核心判定语义”仍未落地。

已完成或已部分完成（相对 #272）

1. 主链路仍是 TUI -> Runtime -> Provider/ToolManager，Gateway 不是必经。internal/app/bootstrap.go:114 直接装配 runtime + provider + toolManager；Gateway 以独立进程存在（cmd/neocode-gateway/main.go:23）。
2. Todo/TaskState 的“前置接入基础”已存在：会话持久化有 task_state（internal/session/store.go:33），context 会注入 TaskState（internal/context/builder.go:31、internal/context/source_task_state.go:16），compact 会回写 TaskState（internal/runtime/compact.go:140）。
3. capability 基线有一部分：catalog 已有 TTL + 后台刷新（internal/provider/catalog/service.go:15、internal/provider/catalog/service.go:184），并有 configured/discovered/default 合并（internal/provider/catalog/service.go:127）。
4. permission 等待/恢复链路已存在（permission_request/permission_resolved）：internal/runtime/events.go:73、internal/runtime/events.go:75。

与当前计划冲突/未完成点

1. 阶段 1A 关键语义未落地：未见 StopReason 枚举与优先级决议；当前停止主要是 max_loops 报错或取消（internal/runtime/run.go:73、internal/runtime/errors.go:15）。
2. progress 证据模型未落地：未见 EVIDENCE_*、ProgressScore、no-progress/repeat-cycle 计数器。
3. 事件协议与 NeoCode 运行时与能力分层优化计划（修订版） #272 不一致：当前 RuntimeEvent 只有 Type/RunID/SessionID/Payload（internal/runtime/events.go:9），缺少 turn/phase/timestamp/payload_version；且事件名是 permission_request，不是 permission_requested（internal/runtime/events.go:73）。
4. 阶段 1B/2 的预算与调和未落地：provider 仅有最终 Usage（internal/provider/types/request.go:11），未见分段估算字段（EstimatedPromptTokens 等）、误差治理、reconciled ledger。
5. 阶段 5 目标（instructions 分层）未完成：规则发现仍在 context 内（internal/context/builder.go:30、internal/context/source_rules.go:1），未见独立 internal/instructions。
6. 阶段 6 目标（repository 能力层）未完成：当前无 internal/repository 模块。
7. 阶段 8 工具化未完成：当前工具列表仍是 filesystem/bash/webfetch/memo（docs/tools-and-tui-integration.md:14），未见 tools/git、tools/review、tools/workspacecheckpoint。
8. 阶段 9 存在直接冲突：& <command> 仍在 TUI 与 README 中（internal/tui/core/app/input_features.go:17、README.md:93）。
9. Skills 处于“有模块、未进主链路”状态：internal/skills 已有实现（internal/skills/loader.go:1），但 app/runtime/context 装配链路未见接入点（internal/app/bootstrap.go:62 起）。

建议（针对 #272 文案）

1. 把“阶段 3（Todo/TaskState）”标注为“已部分完成（需补 runtime progress 判定联动）”，避免阶段顺序失真。
2. 把“阶段 1A”设为最高优先级补齐项：先补 StopReason + progress evidence + 事件协议冻结，再谈预算调和。
3. 把“阶段 9”前移或拆成并行修正：先明确 & <command> 的去留与替代路径，否则与当前文档/行为长期冲突。
4. 在 issue 中明确“event naming 迁移策略”（permission_request -> permission_requested 等）与兼容窗口，避免 TUI/日志侧断裂。

本次处理范围

仅完成再评估与对照分析；未做代码改动、未跑测试。

View job run

[phantom5099]

@xgopilot 把计划中的阶段1A、1B写成两篇issue（注意comment中提出的问题），并comment到这个issue下（不要你单开issue）

[fennoai]

阶段 1A Issue 草案（可直接复制）

Title
runtime: 阶段1A 判定语义最小闭环（StopReason/Phase/Progress/Event）

Body

关联：#272（修订版总计划）
来源：吸收本 issue 评论中“职责不清/冲突”反馈，先冻结运行时判定语义。

目标

在不引入 capability/estimation/ledger/checkpoint 的前提下，先把 runtime 的“怎么停、怎么判进展、怎么发事件”做成唯一、可测、可回放的控制面语义。

范围（In Scope）

1. StopReason 统一枚举与固定优先级（互斥、单轮唯一）。
2. Phase 最小状态机：plan -> execute -> verify，并定义并行 tool call 的 phase 归属与回收规则。
3. ProgressEvidenceRecord 契约落地：
   • 证据生产者：tools adapter/runtime adapter 负责产出标准化记录。
   • 证据判定者：runtime 只做聚合计分（不直接猜测语义）。
4. ProgressScore + no-progress/repeat-cycle 计数器。
5. 运行时事件最小集合冻结：
   • phase_changed
   • budget_checked（仅预留事件壳，1A 不做预算判停）
   • progress_evaluated
   • compact_applied
   • stop_reason_decided
   • permission_requested
   • permission_resolved
   • ledger_reconciled（仅预留事件壳）
6. 事件最小公共字段：run_id, turn, phase, timestamp, payload_version。

关键拍板（解决评论中职责不清）

1. PermissionEngine 归属 internal/tools（或 internal/security），runtime 仅消费 permission 结果事件，不做审批策略判定。
2. STOP_USER_INTERRUPT 语义：非抢占，在“下一判定点”生效；同轮冲突按优先级决议，不并列写入。
3. 事件命名迁移策略：兼容窗口内支持 permission_request -> permission_requested 映射，窗口结束后统一新枚举。

不在本阶段（Out of Scope）

1. capability baseline / token estimation。
2. usage reconciliation / run ledger 持久化。
3. resume checkpoint 原子提交。

验收标准（量化）

1. 冲突输入下 StopReason 决议 100% 唯一（表驱动测试覆盖）。
2. phase 迁移覆盖并行 tool call 场景（含失败/取消/重试分支）。
3. EVIDENCE_NEW_INFO_NON_DUP 单独出现时不能抵消 no-progress（回归用例覆盖）。
4. 事件快照测试验证字段齐全且 payload_version 可升级。

测试映射

1. 判定优先级表驱动测试。
2. phase 迁移测试。
3. progress 证据评分与 streak 回归测试。
4. 事件协议快照测试。

风险与回滚

1. 风险：旧事件名消费者（TUI/日志）断裂。
2. 缓解：提供命名兼容映射 + 迁移告警计数。
3. 回滚：仅回滚事件映射层，不回滚 StopReason 枚举。

---

阶段 1B Issue 草案（可直接复制）

Title
runtime/provider: 阶段1B 预算化与能力一致性（Capability/Estimation/Budget+Compact）

Body

依赖：阶段 1A 完成（判定语义冻结）
关联：#272

目标

在 1A 语义稳定后，接入 capability 一致性协议与分段 token estimation，使 budget stop 与 compact budget 可执行、可观测、可追踪来源。

范围（In Scope）

1. Capability 解析顺序固定：
   config override > catalog cache > builtin table > live discovery > conservative fallback。
2. CapabilityCache 单点归属：internal/provider/catalog（不落到 config/runtime/session）。
3. cache 机制：cache_ttl + stale-while-revalidate + invalidation（model 切换/provider 版本变化/显式刷新）。
4. 冲突仲裁：高优先级来源覆盖低优先级来源，并记录来源链。
5. provider 分段估算输出：
   • EstimatedPromptTokens
   • EstimatedInjectedTokens
   • EstimatedToolSchemaTokens
   • EstimationConfidence
6. runtime 预算判定：estimated 与 observed 双线生效，且 StopReason 与事件一致。
7. compact 预算化：auto_compact_budget 与 reactive_compact_budget。
8. 误差治理：
   • error_ratio = |observed-estimated| / max(observed,1)
   • 滑动窗口策略：1B 先用 in-memory per run；跨 run 持久化放到阶段 2（ledger）
   • 超阈触发保守系数降级 + estimation_degraded 事件。

关键拍板（解决评论中职责不清）

1. config 只提供 profile/override，不持有动态缓存。
2. token 估算器细节只在 provider 层，runtime 仅做汇总与判停。
3. 误差窗口跨 run 持久化不在 1B 实施，避免与阶段 2 边界冲突。

不在本阶段（Out of Scope）

1. session ledger estimated/observed/reconciled 持久化与调和。
2. checkpoint 原子提交。
3. todo/task 语义进展接入（阶段 3）。

验收标准（量化）

1. discovery 缺失时 capability 可回退，且来源链可追踪。
2. estimation 与 observed 误差统计可查询（run 内）。
3. 预算耗尽时 StopReason 与 stop_reason_decided 事件完全一致。
4. compact 预算触发与重试路径可复现且不破坏主循环。

测试映射

1. capability 来源仲裁测试（含 TTL/SWR/invalidation）。
2. estimation 误差与降级阈值测试。
3. budget stop（estimated/observed）一致性测试。
4. compact budget 触发与失败降级测试。

风险与回滚

1. 风险：provider 差异导致估算漂移过大，误触发预算 stop。
2. 缓解：按 provider+model 降级系数与置信度门限。
3. 回滚：仅关闭降级开关，保留误差观测与事件。

---

说明

已按你的要求把阶段 1A、1B 拆成两篇独立 issue 草案，并把历史评论中提出的关键问题（职责归属、命名迁移、中断语义、缓存归属、误差窗口边界）纳入正文。未新开 issue、未做代码改动。

View job run

[phantom5099]

@xgopilot 根据PR295，分析当前计划有没有要修改的地方

[fennoai]

结论

需要改。基于 PR #295（截至 2026-04-14 为 OPEN），#272 不需要推翻重写，但应做“状态校准 + 新增边界条款”，否则阶段描述会和现状错位。

建议修改点（按优先级）

1. 将“阶段 1A”改为“1A 已部分落地，进入补齐”。
   PR295 已引入 runtime/controlplane 的基础骨架（StopReason/Phase/Event envelope/Progress），但与 NeoCode 运行时与能力分层优化计划（修订版） #272 目标仍有差距：

• StopReason 目前仅 success/max_loops/error/canceled，未覆盖 NeoCode 运行时与能力分层优化计划（修订版） #272 定义的 10 项停止原因与预算细分。
• 优先级仍是 canceled > max_loops > error > success，不等于 NeoCode 运行时与能力分层优化计划（修订版） #272 的统一优先级表。
• Progress 当前只有 EVIDENCE_NEW_INFO_NON_DUP，且实现上会单独重置 no-progress streak，这和 NeoCode 运行时与能力分层优化计划（修订版） #272 的“该证据不能单独抵消 no-progress”冲突。

2. 在 NeoCode 运行时与能力分层优化计划（修订版） #272 中新增“SubAgent 并行轨约束”（对应 feat(subagent): 引入 WorkerRuntime 抽象与角色策略（researcher/coder/reviewer） #274 / PR295），避免计划遗漏。
   PR295 新增 internal/subagent + runtime.RunSubAgentTask + subagent_* 事件，说明运行时已出现第二执行轨；建议在 NeoCode 运行时与能力分层优化计划（修订版） #272 明确：

• SubAgent 当前是独立能力，不改变主链路 TUI -> Runtime -> Provider/ToolManager。
• SubAgent 后续接入必须经过 ToolManager/Permission/Sandbox，不得旁路。
• SubAgent 事件与主 Run Ledger/StopReason 的映射规则需单独定义（否则阶段 2 的账本与阶段 1A 的 stop 判定会有口径分叉）。

3. 关系矩阵补一条：#274/#295 = keep + guardrails。
   当前 0.1 关系矩阵未覆盖这条已发生的实现线，建议补上并标注“非主链路替代，只是能力扩展”。

4. 事件迁移策略从“计划项”升级为“已有事实 + 收尾项”。
   PR295 已做兼容别名（permission_request -> permission_requested、compact_done -> compact_applied），NeoCode 运行时与能力分层优化计划（修订版） #272 应改成：

• 已完成兼容映射；
• 还需定义兼容窗口结束条件与清理节点。

5. 阶段验收文案建议同步“基线已存在”的现实。
   把 1A/1B 的验收描述从“从零建设”改为“在 PR295 基线之上补齐缺口”，避免重复交付与排期误判。

可保持不变

1. 顶层主链路拍板（Gateway 非近期必经）可保持不变。
2. Todo 前置到 progress 判定链路（阶段 3）可保持不变。
3. runtime/provider/config/session 的分层边界定义整体仍成立。

本次范围

仅完成分析与计划修订建议；未做代码改动、未运行测试。

View job run

[phantom5099]

@xgopilot 分析当前runtime的边界是否足够清晰、职责是否不清

[fennoai]

结论

当前 runtime 的主边界是可见的，但还不够“收敛为单一控制面”；存在多处职责混杂，尤其是 provider 重试策略、progress 证据生产、permission 展示语义映射 和 事件协议一致性。

主要职责不清点（按影响）

1. runtime 承担了 provider 重试策略，和既定分层冲突。
   internal/runtime/run.go:307 开始实现 retry/backoff（含 providerRetryBackoff），而 provider 层也有独立 transport retry 语义；这会导致“重试归属”双轨。

2. StopReason 语义与主循环停止机制不一致。
   internal/runtime/controlplane/stop_reason.go:7 仅有 success/max_loops/error/canceled；但 Run 主循环已去掉内部 max-loops（internal/runtime/run.go:58 注释、for turn := 0; ; turn++ 在 internal/runtime/run.go:101）。这使 max_loops 成为弱语义，决议口径不稳定。

3. progress 的“证据生产者/判定者”边界仍混在 runtime。
   当前仅有 EVIDENCE_NEW_INFO_NON_DUP（internal/runtime/controlplane/progress.go:7），且由 runtime 通过扫描 tool 消息和 IsError 推断（internal/runtime/run.go:157-163），不是由 tools/provider 输出结构化 evidence。

4. permission 相关的展示语义与策略映射落在 runtime。
   internal/runtime/permission.go:27-42、308-339 在 runtime 内定义了 decision/status/category 映射和文案常量；这部分更接近 security/approval 或展示协议层，runtime 应主要做编排与事件转发。

5. 事件协议存在“统一 envelope + 局部旁路”并存。
   internal/runtime/subagent_run.go:137-149 直接写 s.events（非 emitWithEnvelope 路径），与主事件发射路径不一致，协议一致性和背压行为会分叉。

6. runtime 吸收了工具领域语义判断（todo 冲突）。
   internal/runtime/toolexec.go:248-250 通过 reason_code 字符串包含 conflict 判定事件类型，这属于工具结果语义解析，长期会把工具域规则耦合进 runtime。

7. 文档与实现的事件边界有漂移。
   docs/runtime-provider-event-flow.md:5 声称“稳定小集合”，但实现新增了 subagent_* 事件（internal/runtime/events_subagent.go:22），文档口径未同步，会放大职责理解偏差。

建议（最小收敛顺序）

1. 先定“重试归属”：provider 内聚，runtime 只保留调用编排。
2. 补齐 stop reason 与预算/行为停止的一致枚举，清理不可达 max_loops 路径。
3. 引入 ProgressEvidenceRecord 生产契约（tools/provider 产出，runtime 只聚合计分）。
4. 将 permission 的 category/status 映射下沉到 approval/security 协议层。
5. 子代理事件改为统一走 emitWithEnvelope，避免旁路。

本次范围

已完成：按当前代码分析 runtime 边界与职责不清点。
未执行：代码修改、测试、提交。

View job run

[phantom5099]

结论

当前 runtime 的主边界是可见的，但还不够“收敛为单一控制面”；存在多处职责混杂，尤其是 provider 重试策略、progress 证据生产、permission 展示语义映射 和 事件协议一致性。

主要职责不清点（按影响）

1. runtime 承担了 provider 重试策略，和既定分层冲突。
   internal/runtime/run.go:307 开始实现 retry/backoff（含 providerRetryBackoff），而 provider 层也有独立 transport retry 语义；这会导致“重试归属”双轨。
2. StopReason 语义与主循环停止机制不一致。
   internal/runtime/controlplane/stop_reason.go:7 仅有 success/max_loops/error/canceled；但 Run 主循环已去掉内部 max-loops（internal/runtime/run.go:58 注释、for turn := 0; ; turn++ 在 internal/runtime/run.go:101）。这使 max_loops 成为弱语义，决议口径不稳定。
3. progress 的“证据生产者/判定者”边界仍混在 runtime。
   当前仅有 EVIDENCE_NEW_INFO_NON_DUP（internal/runtime/controlplane/progress.go:7），且由 runtime 通过扫描 tool 消息和 IsError 推断（internal/runtime/run.go:157-163），不是由 tools/provider 输出结构化 evidence。
4. permission 相关的展示语义与策略映射落在 runtime。
   internal/runtime/permission.go:27-42、308-339 在 runtime 内定义了 decision/status/category 映射和文案常量；这部分更接近 security/approval 或展示协议层，runtime 应主要做编排与事件转发。
5. 事件协议存在“统一 envelope + 局部旁路”并存。
   internal/runtime/subagent_run.go:137-149 直接写 s.events（非 emitWithEnvelope 路径），与主事件发射路径不一致，协议一致性和背压行为会分叉。
6. runtime 吸收了工具领域语义判断（todo 冲突）。
   internal/runtime/toolexec.go:248-250 通过 reason_code 字符串包含 conflict 判定事件类型，这属于工具结果语义解析，长期会把工具域规则耦合进 runtime。
7. 文档与实现的事件边界有漂移。
   docs/runtime-provider-event-flow.md:5 声称“稳定小集合”，但实现新增了 subagent_* 事件（internal/runtime/events_subagent.go:22），文档口径未同步，会放大职责理解偏差。

建议（最小收敛顺序）

1. 先定“重试归属”：provider 内聚，runtime 只保留调用编排。
2. 补齐 stop reason 与预算/行为停止的一致枚举，清理不可达 max_loops 路径。
3. 引入 ProgressEvidenceRecord 生产契约（tools/provider 产出，runtime 只聚合计分）。
4. 将 permission 的 category/status 映射下沉到 approval/security 协议层。
5. 子代理事件改为统一走 emitWithEnvelope，避免旁路。

本次范围

已完成：按当前代码分析 runtime 边界与职责不清点。 未执行：代码修改、测试、提交。

View job run

@xgopilot 忽略掉subagent，分析其他问题的解决方法，并给我输出一版方案