pref(runtime)：控制面语义收敛

[phantom5099]

1) 目标问题（Why）

当前 runtime 主循环已经被 PR 365 推向“顺序 Todo + inline subagent + dispatch phase”的新模型，但现有计划仍停留在旧控制面语义上，导致问题定义与实现方向已经出现偏移。本issue只解决当前阶段必须收敛的控制面语义问题：

1. 完成判定问题：assistant 本轮无 tool call 仍容易被误判为完成，且在顺序 Todo + inline subagent 模型下，这个信号可靠性更弱。
2. 进展判定问题：当前 repeat-cycle / no-progress 仍偏向旧式“重复调用 + 弱证据”判断，容易误伤合理探索；同时 PR 365 已移除其硬停止语义，现有计划中的 stop 设计已过时。
3. 状态机问题：runtime 实际上已经引入 dispatch 阶段，但旧方案仍以 Plan -> Execute -> Verify 为主链，无法准确描述新的执行闭环。
4. 控制面分散问题：completion / progress / stop / dispatch / subagent 相关语义仍散落在 run loop、tool 执行和事件层，不利于后续 budget、ledger、resume 稳定接入。

本阶段目标不是引入更多能力，而是先让 runtime 的主循环语义与 PR 365 对齐，并形成可测试、可观测、可继续扩展的控制面契约。

2) 设计（How）

2.1 控制面不变量

本阶段先固定以下运行时不变量，后续实现与测试均以此为准：

1. assistant 本轮无 tool call != completed。
2. 只要仍有 pending agent todo、pending subagent todo、inline subagent in-flight、未验证写入，就不能 completed。
3. no-progress 与 repeat-cycle 不是本阶段的硬 stop reason，只能作为 soft control / stalled 信号。
4. Dispatch 是正式 phase，不再是隐含流程。
5. 同一 turn 只能产出一个最终硬停止结果，本阶段仅允许：
   • STOP_FATAL_ERROR
   • STOP_COMPLETED
   • STOP_USER_INTERRUPT

2.2 运行状态机

本阶段固定 RunState：

• Plan
• Execute
• Dispatch
• Verify
• Compacting
• WaitingPermission
• Stopped

主链迁移固定为：

• Plan -> Execute -> Dispatch -> Verify -> Plan

补充迁移：

• * -> WaitingPermission -> previous_state
• * -> Compacting -> Plan
• * -> Stopped

语义约束：

• Plan
  • 负责本轮规划、顺序 Todo 更新、决定当前 todo 的 executor
• Execute
  • 负责主 agent 的普通工具执行
• Dispatch
  • 负责 executor=subagent 的 todo、inline subagent 触发与结果回灌
• Verify
  • 负责验证与 closure
• Compacting / WaitingPermission / Stopped
  • 保持治理/中断/终止语义，不承载业务推进

2.3 CompletionGate 设计

CompletionState 固定包含：

• HasPendingAgentTodos
• HasPendingSubagentTodos
• HasInlineSubAgentRunning
• HasUnverifiedWrites
• LastTurnExecutedTools
• LastTurnVerifyPassed
• RequiresVerification
• CompletionBlockedReason

规则固定为：

1. 本轮 assistant 无 tool call，不直接视为完成。
2. 有 pending agent todo 时不能 completed。
3. 有 pending subagent todo 时不能 completed。
4. 有 inline subagent 尚未回灌完成时不能 completed。
5. 有未验证写入时不能 completed。
6. 只有 RequiresVerification=false 或 LastTurnVerifyPassed=true 时，才允许结束。
7. 纯读取、纯检索、纯解释型执行不自动要求 verify；写入类动作和显式 verify-required 工具会置 RequiresVerification=true。

2.4 进展判定设计

ProgressEvidence 仅允许结构化证据：

• TASK_STATE_CHANGED
• TODO_STATE_CHANGED
• TODO_EXECUTOR_CHANGED
• WRITE_APPLIED
• VERIFY_PASSED
• NEW_INFO_NON_DUP
• PHASE_ADVANCED
• DISPATCH_COMPLETED
• SUBAGENT_RESULT_APPLIED

证据分级固定为：

• 强证据
  • TASK_STATE_CHANGED
  • TODO_STATE_CHANGED
  • VERIFY_PASSED
  • DISPATCH_COMPLETED
  • SUBAGENT_RESULT_APPLIED
• 中证据
  • TODO_EXECUTOR_CHANGED
  • WRITE_APPLIED
  • PHASE_ADVANCED
• 弱证据
  • NEW_INFO_NON_DUP

ProgressScore 至少包含：

• HasBusinessProgress
• HasExplorationProgress
• StrongEvidenceCount
• MediumEvidenceCount
• WeakEvidenceCount
• NoProgressStreak
• RepeatCycleStreak
• SameToolSignature
• SameResultFingerprint
• SameSubgoal
• StalledProgressState
• ReminderKind

规则固定为：

1. 出现任一强证据，或出现 WRITE_APPLIED + VERIFY_PASSED 闭环，才算 HasBusinessProgress=true。
2. 只有 NEW_INFO_NON_DUP 或仅有 PHASE_ADVANCED 时，不算业务进展。
3. HasExplorationProgress 仅在 Plan / Execute / Dispatch 阶段有效，用于给合理探索留缓冲，不直接视为业务推进。
4. NoProgressStreak 只在无业务进展且 exploration 缓冲已耗尽时递增。
5. RepeatCycleStreak 只在以下条件同时成立时递增：
   • SameToolSignature=true
   • SameResultFingerprint=true
   • SameSubgoal=same
   • HasBusinessProgress=false
6. SameSubgoal 使用三态：same / different / unknown；unknown 不推动 repeat。
7. no-progress / repeat-cycle 不直接 stop，只能推动 stalled 与 reminder。

2.5 stalled 软纠偏设计

本阶段新增 StalledProgressState：

• healthy
• stalled

规则：

1. 当 NoProgressStreak 或 RepeatCycleStreak 首次达到阈值时，不直接终止 run。
2. 首次达到阈值后，进入 stalled，并注入一次固定的自修复提醒。
3. 提醒内容固定聚焦：
   • 总结 blocker
   • 更新当前 todo / 子目标
   • 说明是否继续重复调用
   • 若位于 Dispatch，说明为何仍需 subagent 或改回 agent 执行
4. stalled 期间允许继续运行；真正硬终止由后续 budget / turn / time 边界负责，不由 progress 直接负责。

2.6 Dispatch / inline subagent 设计

本阶段将 spawn_subagent(mode=inline) 正式纳入控制面，不再视为普通附属工具：

1. Dispatch 阶段的职责是识别 executor=subagent 的 todo、触发 inline subagent、接收结构化结果并回灌。
2. inline subagent 结果一律按结构化 tool result 处理，不作为普通 assistant continuation。
3. todo.executor 只允许 agent / subagent 两种合法输入语义。
4. 本阶段的 dispatch 语义固定为“顺序 todo + inline child execution”，不承诺一般化 DAG 自动调度。

2.7 事件与观测设计

本阶段固定最小事件集：

• phase_changed
• progress_evaluated
• stop_reason_decided

其中 progress_evaluated 必须显式带出：

• HasBusinessProgress
• HasExplorationProgress
• NoProgressStreak
• RepeatCycleStreak
• SameToolSignature
• SameResultFingerprint
• SameSubgoal
• StalledProgressState
• CurrentTodoExecutor
• HasPendingSubagentTodos
• HasInlineSubAgentRunning

本阶段不重做全部 subagent 事件，但 runtime 主事件必须能表达 dispatch/subagent 对 completion 和 progress 的影响。

3) 一次性交付清单（What）

基于上述控制面设计，本阶段一次性交付以下内容：

1. 状态机与 gate 收敛

• 固化 RunState
• 落地状态迁移表
• 固化 PermissionGate -> CompletionGate -> ProgressGate -> StopReasonResolver

2. Completion 语义收敛

• 实装 CompletionState
• 将 completion 改成顺序 todo + inline subagent 感知
• 移除 “本轮无 tool call == completed” 的直接分支

3. Progress 语义收敛

• 扩展 ProgressEvidence
• 落地证据分级
• 落地 ProgressScore
• 引入 stalled 软纠偏
• 将 STOP_NO_PROGRESS / STOP_REPEAT_CYCLE 从本阶段最终 stop reason 中移除

4. Dispatch / subagent 接入控制面

• 将 todo.executor 纳入 completion / progress 判定
• 将 spawn_subagent(mode=inline) 正式写入 Dispatch 语义
• 将 dispatch/subagent 结果作为结构化证据进入 progress 计算

5. 事件与消费侧对齐

• 补齐 phase_changed / progress_evaluated / stop_reason_decided
• TUI 改为消费新的 progress/stalled/dispatch 观测字段

4) 验收模型（DoD）

统一按三类验收：

1. 正常路径

• assistant 无 tool call，但仍有 pending agent todo，不应 completed
• assistant 无 tool call，但仍有 pending subagent todo，不应 completed
• inline subagent 已 dispatch 但尚未回灌完成，不应 completed
• 纯读取/检索型执行结束后，无 pending todo 且不需要 verify，可 completed
• Dispatch 成功消费 inline subagent 结果后，允许继续进入 Verify 或返回 Plan

2. 异常路径

• 重复工具签名但结果不同，不应推动 repeat-cycle
• 重复工具签名且结果相同，但 SameSubgoal=unknown 时，不应推动 repeat-cycle
• 重复工具签名且结果相同、子目标相同、无业务进展时，首次达到阈值只进入 stalled，不 hard stop
• exploration 只在 phase 宽容窗口内起缓冲作用，超过窗口后开始累计 NoProgressStreak
• 同一 turn 最终只允许一个硬 stop result

3. 恢复/一致性路径

• 已有 session/todo 读取路径在接入新控制面后不应丢失 executor 语义
• phase_changed / progress_evaluated / stop_reason_decided 事件字段在恢复已有会话后仍保持结构一致
• 本阶段虽不引入 ledger/resume，但不得破坏后续 resume 对 phase/todo/progress 的接入前提

5) 非目标（明确边界）

1. 不做动态 token 预算。
2. 不做 RunLedger / ResumeCheckpoint。
3. 不做 secret 延迟解析。
4. 不做 internal/instructions 与 internal/repository 分层。
5. 不做通用 DAG 调度产品语义。
6. 不把 no-progress / repeat-cycle 重新做回硬 stop。

[fanfeilong]

@phantom5099 issue是怎么产生的，还是不规范

[phantom5099]

@phantom5099 issue是怎么产生的，还是不规范

我重新按照之前那个RFC写了一版，已经修改上去了

[fanfeilong]

@xgopilot LLM 很喜欢用控制面这词，实际上我以前很少听到这词，你给解释下，另外它大概率从哪里被污染了这个术语

[fennoai]

解释

你这个问题很准。

“控制面（control plane）”本意是分层术语，最早在网络/分布式系统里常和“数据面（data plane）”成对出现：

• 控制面：做策略、调度、状态管理、路由决策、治理规则
• 数据面：真正执行流量/任务/请求

放到你这个 runtime 场景里，phase/gate/stop/progress/dispatch/subagent 这些都属于“控制面语义”，而 tool 真正执行命令/读写文件更像“执行面/数据面”。

大概率来源

你说“被污染”基本可以理解为术语迁移：

• 云原生/K8s/Service Mesh/SDN 这套词被大量工程师带进 AI Agent 设计
• LLM Agent 框架近两年大量借用了 workflow/orchestration 话语体系，中文社区常直接翻译成“控制面”
• 再叠加 RFC/架构文档写作习惯，词频被放大

所以不是错词，更像是基础设施语境在 Agent 领域的迁移。如果团队里有人不习惯，可以在文档里加一句术语对照：控制面 = 运行时编排与治理语义，读起来会更直观。

已完成：术语解释与来源分析。
未执行：代码修改（本次是概念问答）。

View job run

[fanfeilong]

@xgopilot 我还是不太懂的，你给举例，比如为什么这个issue里你会用这个词。如果我要理解一个术语是什么，我也想知道一个相近的场景它不是这个「什么」。所以你除了要解释当前issue，也要给两个正反对比的例子。

[fennoai]

你这个 issue 里为什么用“控制面”

在这个 issue 里，“控制面”指的是 runtime 如何决定和治理执行过程，不是具体去执行某个工具动作。

放到你这份设计里，像这些都属于控制面语义：

• RunState 阶段迁移（Plan -> Execute -> Dispatch -> Verify）
• CompletionGate / ProgressGate / StopReasonResolver
• stalled 软纠偏
• dispatch/subagent 对完成判定与进展判定的影响

一句话判断：凡是“决定下一步怎么跑、何时停、是否算有进展”的，都在控制面。

两组正反对比（是什么 / 不是什么）

1. 例子 A（Completion）

• 是控制面：assistant 本轮无 tool call 时，仍要看 pending todo / inline subagent / 未验证写入 才能决定 completed。
• 不是控制面：filesystem 工具具体如何读文件、返回什么内容，这是工具执行面。

2. 例子 B（Dispatch/Subagent）

• 是控制面：Dispatch 阶段决定 todo.executor=agent|subagent、何时触发 inline subagent、何时把结构化结果回灌到主循环。
• 不是控制面：subagent 内部具体调用了 bash 还是 webfetch、命令细节和输出文本，这是执行面。

一个快速区分法

问自己三句话：

• 它是在“做决策/治理”还是在“做动作”？
• 它改变的是 phase/gate/stop/progress，还是工具输入输出？
• 去掉它会让“流程规则”坏掉，还是只让“某次执行能力”缺失？

前者基本是控制面，后者基本不是。

本次完成情况

已完成：术语在本 issue 中的落点解释、两个正反对比例子。
未执行：代码修改（本次是概念澄清）。

View job run

[fanfeilong]

@xgopilot 我感觉你这样说就更糊涂了，就以Neocode来说，你理解下它的构架，然后详细挨个解释哪些是控制面，哪些不是。

[fennoai]

先给结论

在 NeoCode 里，控制面不是“某个目录名”，而是“负责决策与治理运行流程的那层语义”。

一句话区分：

• 控制面：决定 下一步做什么 / 是否算进展 / 何时停止 / 阶段如何迁移
• 非控制面：真正去 执行工具 / 发模型请求 / 渲染 UI / 持久化数据

按 NeoCode 架构逐项拆分

1. internal/runtime/controlplane：是控制面核心

• phase.go：定义 phase 语义（plan/execute/dispatch/verify）
• progress.go：定义 progress 证据与 streak 计算
• stop_reason.go + decider.go：定义并决议唯一 stop reason
• envelope.go：控制面事件 payload 版本

2. internal/runtime：一半是控制面编排，一半是执行编排

• 属于控制面的部分：
  • run_lifecycle.go 的 phase 迁移与 stop_reason 终止决议发射
  • run.go 里“何时进入下一轮、何时结束、何时发 progress_evaluated”
• 不属于控制面的部分：
  • 具体工具并发执行细节（toolexec.go）
  • provider 调用重试实现细节、消息落库细节

3. internal/tools：默认不是控制面（是执行面能力）

• filesystem/bash/webfetch/todo_write/spawn_subagent 这些是“能力实现”
• 它们提供 action，不负责决定“整轮 run 是否完成”
• 例外：工具返回的结构化结果会被控制面消费，作为判定输入，但工具本身不是控制面

4. internal/provider：不是控制面

• 负责协议适配、流式解析、错误映射
• 这是模型 I/O 适配层，不做 run 级治理决策

5. internal/context：主要不是控制面（是上下文构建层）

• 负责 system prompt 组装、裁剪、compact 决策建议
• 它可影响运行效果，但不直接做最终 stop/completion 决议

6. internal/session：不是控制面（是状态存储面）

• 保存 messages/todos/task_state/token 等 durable state
• 它是“被治理对象”，不是“治理规则本身”

7. internal/tui：不是控制面（是展示与交互面）

• 消费 runtime 事件并渲染
• 不应自己决定 completion/progress/stop

8. internal/app、internal/config：不是控制面核心

• app 是装配层
• config 是策略参数来源（阈值、provider、workdir），参数可被控制面使用，但它本身不是控制面判定器

对应到你这个 #386，哪些是“控制面语义收敛”

你 issue 里这些都属于控制面：

• CompletionGate（完成判定）
• ProgressEvidence/ProgressScore（进展判定）
• StopReasonResolver（硬停止唯一决议）
• Phase 状态机（Plan/Execute/Dispatch/Verify...）
• stalled 软纠偏
• dispatch/subagent 对 completion/progress 的影响

这些不属于控制面本体：

• bash 命令怎么跑、filesystem 怎么读写
• provider 各厂商字段差异解析
• TUI 组件怎么显示

你现在觉得“糊涂”的核心点

你前面困惑是对的，因为当前仓库存在“语义已定义、主循环未完全兑现”的过渡态：

• PhaseDispatch 已在控制面类型中定义
• 但当前主循环仍主要是 plan -> execute -> verify（测试里也有注释说明当前不自动进入 dispatch）

所以讨论 #386 时，建议始终分两层说：

• 现状控制面（已经落地的）
• 目标控制面（这次要收敛到的）

本次完成情况

已完成：基于 NeoCode 当前代码结构，逐模块说明“控制面 vs 非控制面”，并映射到 #386 语义。
未执行：代码修改（你这次是架构解释请求）。

View job run

[fanfeilong]

@xgopilot 如果强迫你不用【控制面】这个词，传统软件开发里，你会用哪些命名来替代 controlplane？编排？调度？执行器？工作流？状态机？

[fennoai]

分析

a. 事件类型：issue comment，用户在 #386 里追问术语命名。 b. 请求类型：分析/问答，不是实现或代码评审。 c. 关键输入：用户希望不用“控制面(controlplane)”这个词，询问传统软件开发可替代命名。 d. 挑战：需要与本 issue 已定义语义对齐（Plan/Execute/Dispatch/Verify、Completion/Progress/Stop 等），避免泛化成空词。 e. 计划：基于当前 issue 语义给出“术语->适用范围->是否推荐”的映射，并给出一个可直接落地的命名组合；不做代码变更与测试。 f. 受限项：本次无代码改动，无需构建/测试。

命名建议

如果强制不用“控制面”，在传统软件工程里我会按语义拆成三层命名，而不是找一个词全包：

1. Orchestration（编排层）
   适合描述跨 phase 的流程推进（Plan -> Execute -> Dispatch -> Verify）。

2. Coordination（协调层）
   适合描述 gate 与决策（PermissionGate / CompletionGate / ProgressGate / StopReasonResolver）。

3. Execution State Machine（执行状态机）
   适合描述 RunState、迁移规则和硬停止唯一性。

在你这个 issue 里的推荐落地

建议主名用：Runtime Orchestration，并在子模块中明确：

1. Completion Coordinator
2. Progress Evaluator
3. Stop Reason Resolver
4. Dispatch Executor（仅指 subagent dispatch，不要泛化成全部执行器）
5. RunState Machine

这样比“调度/执行器/工作流”单词更稳：

1. 调度(Scheduler) 太容易被理解成资源/队列调度，不贴合你现在的 gate 语义。
2. 执行器(Executor) 过窄，更像工具调用执行，不覆盖 completion/progress/stop。
3. 工作流(Workflow) 偏业务编排，弱化了运行时治理和停止判定。

完成情况

已完成：问题分析与命名替代方案。
未执行：代码修改、测试、提 PR（本次请求不需要）。

View job run

[fanfeilong]

@xgopilot 如果你说的这样，那岂不是拆成 编排/协调/执行状态机 更明确好理解？是否可以认为你在一个模块里干了一堆大杂烩。

[fennoai]

分析

a. 事件类型：issue comment 追问（#386），非 PR review。 b. 请求类型：架构问答/分析，不是代码实现。 c. 关键诉求：是否应拆成“编排/协调/执行状态机”，以及当前是否已成“大杂烩”。 d. 风险点：若直接做物理大拆分，可能偏离 #386 本阶段“语义收敛优先、非大重构”的边界。 e. 执行策略：给出分层结论 + 最小落地方式（先语义分层，后物理拆分）。 f. 本次无代码修改、无构建测试。

结论

可以这么理解：你的判断是对的，按“编排 / 协调 / 执行状态机”拆开会更清晰；如果这些职责现在混在同一模块里，确实会表现出“大杂烩”风险。

但在 #386 这个阶段，建议做法是：

1. 先做语义拆分，不先做大规模目录重构。
2. 编排层只负责 phase 主链推进与事件发射（Plan->Execute->Dispatch->Verify）。
3. 协调层只负责 Completion/Progress/Stop 的 gate 与决议，不直接执行工具。
4. 执行状态机只负责状态定义与迁移表，不承载业务判定。

这样既回应你说的“更明确好理解”，也不会把 #386 做成一次高风险重构。

如何判断是否还在“大杂烩”

1. 一个函数里同时做 phase 迁移 + progress 评分 + stop 决议 + tool 调用，就是杂糅。
2. assistant 无 tool call == completed 这类捷径逻辑散落在 run loop 各处，就是杂糅。
3. dispatch/subagent 结果既参与执行又参与 completion/progress，但没有统一入口，也是杂糅。

所以答案是：你提出的拆分方向正确；应以“职责边界先收敛、物理结构后演进”的方式推进。

View job run

[fanfeilong]

@xgopilot 那么，如果是要拆成 编排/协调/状态机 ，你总得给出它们是对谁的编排，对谁的协调，对谁的状态控制？理清模块间关系。输入和输出。

[fennoai]

结论

你这个追问可以落成一句话：

• 编排（Orchestration）：对 一次 Run 的执行链路 编排。
• 协调（Coordination）：对 各类判定器/Gate 协调。
• 状态机（RunState Machine）：对 Run 生命周期状态 控制。

不是对工具实现本身做编排，也不是对 provider 协议细节做状态控制。

模块关系（对谁做什么）

1. Runtime Orchestrator（编排层）

• 对象：provider 调用、tool 执行、subagent dispatch、session 持久化、runtime 事件发射。
• 职责：按 phase 推进主链路，调用下游执行器，回灌结果。
• 输入：UserInput + SessionSnapshot + Config + ToolSpecs。
• 输出：ExecutionResults + SessionMutations + RuntimeEvents。

2. Runtime Coordinator（协调层）

• 对象：PermissionGate / CompletionGate / ProgressGate / StopReasonResolver。
• 职责：把多源信号（todo、subagent、verify、progress）汇总成“能不能继续/能不能结束/是否 stalled”。
• 输入：CoordinationInput(phase, todos, subagent_state, verify_state, progress_evidence, errors)。
• 输出：CoordinationDecision(allow_execute, allow_complete, stalled_state, stop_reason)。

3. RunState Machine（状态机层）

• 对象：RunState 本身（Plan/Execute/Dispatch/Verify/...）。
• 职责：只维护合法迁移，不做业务判定。
• 输入：current_state + transition_trigger。
• 输出：next_state + phase_changed event。

I/O 边界（避免大杂烩）

1. 编排层不直接写 completion/progress 规则，只“调用协调层拿结论”。
2. 协调层不执行工具，不调用 provider，只做判定。
3. 状态机层不看 tool result 内容，只看触发条件与迁移表。
4. tools/provider/tui 都是下游或消费侧，不进入这三层的规则定义。

对齐 #386 的落地映射

1. Plan -> Execute -> Dispatch -> Verify：归状态机定义，归编排层驱动。
2. assistant 无 tool call != completed、pending subagent todo、inline in-flight、unverified writes：归协调层 CompletionGate。
3. no-progress/repeat-cycle 仅 soft control（stalled）：归协调层 ProgressGate，不归 stop 硬终止。
4. stop_reason_decided 单一硬停止：归协调层决议，编排层只发最终事件。

当前代码现状（用于共识）

• phase/stop/progress 类型与事件已存在；
• 但主循环仍是 plan->execute->verify 为主，dispatch 还未成为每轮正式迁移；
• 所以 pref(runtime)：控制面语义收敛 #386 应先做“语义分层 + 契约收敛”，再做物理拆包，避免一次性大重构。

View job run

[fanfeilong]

@xgopilot 绘制下你拆解出来的这3个核心对象之间的关系图。选流程图还是时序图？或者其他？