1. 文档目的
本文用于团队讨论 NeoCode 的“思考流程”改造方向，目标不是直接落代码，而是先统一以下共识：
- 当前架构的真实边界在哪里
- 现有方案哪些方向是正确的
- 为了支持未来新增思考流程，哪些接口需要先稳定
- 这次改造的最小可行落地范围是什么
2. 结论摘要
当前提出的“Flow 抽象 + Service 端统一编排 + TUI 只做展示与交互”的总体方向，适合当前项目，也符合现有代码结构的演进路径。
但如果团队的核心诉求是：
- 后续新增新的思考流程时，不需要再大改函数命名
- 不希望不同流程把工具协议、安全审批、记忆更新各自实现一遍
- 希望未来能从 JSON 工具协议平滑迁移到原生 function calling 或远端执行
那么本次设计应进一步收敛为：
- 把“流程编排”与“工具调用协议”明确解耦
- 把“工具执行”与“审批恢复”明确做成统一入口
- 本轮先升级内部事件流，不立即升级外部传输协议
3. 当前现状确认
从当前仓库实现看，问题定义基本准确：
Service 侧目前仍是单次调用模型并返回文本流，没有形成工具循环，见 chat_service.go- 工具闭环目前在 TUI 中完成，包括：
- 在流结束后判断 assistant 最后一条消息是否为工具 JSON
- 执行工具
- 将工具结果注入 system 消息
- 再次请求模型
见 update.go
- 本地依赖装配点已经集中在 api_client.go 与 runtime_services.go
- 当前工具协议是由 persona 明确约束模型输出 JSON，而不是由后端协议原生承载，见 persona.txt
- 安全审批本质上已经存在统一能力，但恢复流程的控制权仍在 TUI，见 security.go
这说明：当前系统已经具备“统一收口”的基础条件，但真正的流程控制还没有从 UI 层下沉。
4. 为什么这次改造值得做
如果继续保持当前模式，后续每新增一种思考流程，都会在 TUI 或聊天主链路上重复处理这些问题：
- 何时判断模型要不要调工具
- 工具执行结果如何回灌
- 何时需要审批
- 何时更新 working memory / long-term memory
- 如何控制循环次数与错误回退
这会导致两个长期问题：
- 流程能力不断增长，但控制逻辑分散在多个层级
- 每次增加新流程，都会牵动函数命名、消息结构和 UI 行为
因此，改造重点不应只是“加一个 react Flow”，而应是先把“流程控制所依赖的公共契约”稳定下来。
5. 设计建议
5.1 保留 Flow 方向，但先稳定三层抽象
建议本次设计围绕三层抽象展开：
Flow：定义单次响应的执行策略，例如 single_shot、react、plan_executeToolCallParser：定义如何从模型输出中识别工具调用请求ToolExecutor：定义如何执行工具、接入安全检查、返回标准化结果
其中最关键的一点是：
Flow 不应直接绑定当前 JSON 工具协议。
原因很简单：当前的 JSON 协议只是现阶段 persona 驱动的实现方式，不应成为未来所有思考流程的固定耦合点。否则以后切换到原生 function calling 时，表面上新增的是“协议”，实际上会被迫重写所有 Flow。
5.2 统一事件流，但先只做内部升级
建议新增 Service 内部统一事件流，例如：
TextChunkToolCallRequestedToolExecutionStartedToolResultReceivedApprovalRequestedErrorDone
但本轮只在内部使用，不立即修改外部 proto 或现有文本流对外接口。
原因：
- 当前 chat.proto 仍是文本片段流模型
- 现在就升级传输协议，改造面会明显扩大
- 团队目前更紧迫的问题是“统一编排”，不是“远端协议重构”
因此更稳妥的路径是：
- 内部事件流先落地
- 兼容层继续把事件投影为当前文本流
- 等 Flow 稳定后，再评估是否升级外部协议
5.3 审批不应只是事件，还需要恢复语义
现有方案中的 RequireApproval(type,target) 方向是对的，但还不够完整。
对于 react 或 plan_execute 这类会暂停后继续执行的流程，仅仅发出审批事件还不够，还需要明确：
- 哪个流程实例被暂停
- 用户批准后如何恢复
- 拒绝后如何返回失败并继续收尾
因此建议审批模型改为：
ApprovalRequested{token, toolCall, toolType, target}Approve(token)Reject(token)
这样 TUI 负责交互，但“恢复执行哪个流程”由 Service 编排层掌控，而不是由 UI 用额外状态去拼装上下文。
5.4 记忆更新要固定在终态，不随中间步骤漂移
建议统一约束：
- 角色、工作记忆、TODO、检索记忆：在每轮模型调用前构建上下文
- working memory 刷新：仅在最终 assistant 回复完成后执行
- long-term memory 保存：仅保存真实用户输入与最终回复，不保存中间工具上下文
这样可以避免：
- 工具结果污染长期记忆
- 中间计划或工具错误被误写入最终工作记忆
- 不同 Flow 对记忆行为理解不一致
6. 配置建议
建议不要只新增一个平铺字段 ai.thinking_flow，而是直接预留结构化配置：
ai:
flow:
name: single_shot
tool_protocol: json_v1
max_loops: 8
max_tool_calls: 12
planner_model: ""
executor_model: ""
plan_template_path: ""
executor_template_path: ""这样做的好处是：
- 后续增加流程参数时不需要频繁调整顶层命名
flow 成为独立能力域，语义更稳定- 未来支持不同流程使用不同模型时不需要推翻现有结构
同时建议支持环境变量覆盖当前 flow，并在 TUI 中新增 /flow [name] 命令，与现有 /provider、/switch 的风格保持一致，参考 update.go
7. 推荐的落地边界
建议本轮改造边界控制在以下范围：
- 引入 Flow 注册表与选择机制
- 下沉工具解析和工具闭环到 Service
- 新增内部事件流
- TUI 从“流程执行者”改为“事件渲染者 + 审批交互者”
- 保持现有外部文本流契约兼容
- 新增
/flow 与状态栏显示当前 flow
本轮不建议立即做：
- 改造外部 proto 为完整事件流协议
- 一次性引入复杂状态机框架
- 为
plan_execute 设计过重的 schema 或调度系统
- 绑定特定 provider 的原生 function calling 协议
8. 分阶段实施建议
阶段一：收口公共能力
- 引入
Flow、ToolCallParser、ToolExecutor
- 保留
single_shot，行为等价现状
- 为现有
chatService 增加内部事件流兼容层
阶段二：实现 react
- 将工具 JSON 解析从 TUI 下沉到 Service
- 将工具执行、安全检查、审批暂停恢复统一纳入 Flow
- TUI 仅渲染事件，不再负责闭环控制
阶段三：实现 plan_execute
- 先生成结构化计划
- 计划写入 todo / working memory
- 单步执行复用
react 执行器，不另起一套工具循环
阶段四：完善可观测性与兼容层
- 增加 flow、loop、tool-call、approval 的日志与指标
- TUI 状态栏展示当前 model + flow
- 评估是否需要将内部事件流上推至 proto
9. 主要风险与规避
风险一：Flow 与工具协议耦合过深
后果是未来新增协议时，所有 Flow 都要重写。
规避建议：单独抽象 ToolCallParser，Flow 只依赖“是否拿到了标准化工具请求”。
风险二：审批只设计成事件，没有恢复语义
后果是暂停后的执行恢复仍然被迫放在 TUI 维护，编排无法真正下沉。
规避建议：审批设计成 token 化 pause/resume 机制。
风险三：过早改外部协议
后果是本轮改造面过大，测试和兼容压力显著增加。
规避建议：先改内部编排和内部事件流，对外仍保持现有文本流。
风险四：plan_execute 一开始做得过重
后果是设计讨论陷入 planner schema 细节，拖慢主链路收口。
规避建议：先把 plan_execute 定位为“复用公共执行器的上层策略”，不是独立系统。
10. 建议团队重点讨论的问题
本次评审建议重点只讨论四个问题：
Flow 是否只负责策略编排，而不承担工具协议解析细节- 审批是否采用 token 化 pause/resume，而不是仅靠
/y /n 和 UI 状态恢复
- 本轮是否接受“只升级内部事件流，不改外部 proto”
plan_execute 是否明确复用 react 执行器，而不是独立实现一套工具循环
11. 最终建议
建议团队采纳当前方案的大方向，但将其调整为以下表述：
“NeoCode 将引入可注册的 Flow 编排层，在 Service 端统一管理单次响应、工具闭环和计划执行。为保证未来新增思考流程时不需要反复修改函数命名和主链路接口，本次改造将优先稳定内部事件流、工具协议解析抽象和审批恢复机制；外部文本流契约暂时保持兼容，待内部编排收敛后再评估是否升级传输协议。”
这套表述比“先实现三个 Flow”更适合团队讨论，因为它先锁定了长期稳定的边界，而不是先锁定某个具体实现形态。
1. 文档目的
本文用于团队讨论 NeoCode 的“思考流程”改造方向，目标不是直接落代码，而是先统一以下共识：
2. 结论摘要
当前提出的“Flow 抽象 + Service 端统一编排 + TUI 只做展示与交互”的总体方向，适合当前项目，也符合现有代码结构的演进路径。
但如果团队的核心诉求是：
那么本次设计应进一步收敛为：
3. 当前现状确认
从当前仓库实现看，问题定义基本准确：
Service侧目前仍是单次调用模型并返回文本流，没有形成工具循环，见 chat_service.go见 update.go
这说明：当前系统已经具备“统一收口”的基础条件，但真正的流程控制还没有从 UI 层下沉。
4. 为什么这次改造值得做
如果继续保持当前模式，后续每新增一种思考流程，都会在 TUI 或聊天主链路上重复处理这些问题：
这会导致两个长期问题：
因此，改造重点不应只是“加一个
reactFlow”，而应是先把“流程控制所依赖的公共契约”稳定下来。5. 设计建议
5.1 保留 Flow 方向，但先稳定三层抽象
建议本次设计围绕三层抽象展开：
Flow：定义单次响应的执行策略，例如single_shot、react、plan_executeToolCallParser：定义如何从模型输出中识别工具调用请求ToolExecutor：定义如何执行工具、接入安全检查、返回标准化结果其中最关键的一点是：
Flow不应直接绑定当前 JSON 工具协议。原因很简单：当前的 JSON 协议只是现阶段 persona 驱动的实现方式，不应成为未来所有思考流程的固定耦合点。否则以后切换到原生 function calling 时，表面上新增的是“协议”，实际上会被迫重写所有 Flow。
5.2 统一事件流，但先只做内部升级
建议新增 Service 内部统一事件流，例如：
TextChunkToolCallRequestedToolExecutionStartedToolResultReceivedApprovalRequestedErrorDone但本轮只在内部使用，不立即修改外部 proto 或现有文本流对外接口。
原因：
因此更稳妥的路径是：
5.3 审批不应只是事件，还需要恢复语义
现有方案中的
RequireApproval(type,target)方向是对的，但还不够完整。对于
react或plan_execute这类会暂停后继续执行的流程，仅仅发出审批事件还不够，还需要明确：因此建议审批模型改为：
ApprovalRequested{token, toolCall, toolType, target}Approve(token)Reject(token)这样 TUI 负责交互，但“恢复执行哪个流程”由 Service 编排层掌控，而不是由 UI 用额外状态去拼装上下文。
5.4 记忆更新要固定在终态，不随中间步骤漂移
建议统一约束：
这样可以避免：
6. 配置建议
建议不要只新增一个平铺字段
ai.thinking_flow，而是直接预留结构化配置：这样做的好处是：
flow成为独立能力域，语义更稳定同时建议支持环境变量覆盖当前 flow，并在 TUI 中新增
/flow [name]命令，与现有/provider、/switch的风格保持一致，参考 update.go7. 推荐的落地边界
建议本轮改造边界控制在以下范围：
/flow与状态栏显示当前 flow本轮不建议立即做：
plan_execute设计过重的 schema 或调度系统8. 分阶段实施建议
阶段一：收口公共能力
Flow、ToolCallParser、ToolExecutorsingle_shot，行为等价现状chatService增加内部事件流兼容层阶段二：实现
react阶段三：实现
plan_executereact执行器，不另起一套工具循环阶段四：完善可观测性与兼容层
9. 主要风险与规避
风险一：Flow 与工具协议耦合过深
后果是未来新增协议时，所有 Flow 都要重写。
规避建议：单独抽象
ToolCallParser，Flow 只依赖“是否拿到了标准化工具请求”。风险二：审批只设计成事件，没有恢复语义
后果是暂停后的执行恢复仍然被迫放在 TUI 维护，编排无法真正下沉。
规避建议：审批设计成 token 化 pause/resume 机制。
风险三：过早改外部协议
后果是本轮改造面过大，测试和兼容压力显著增加。
规避建议：先改内部编排和内部事件流，对外仍保持现有文本流。
风险四：
plan_execute一开始做得过重后果是设计讨论陷入 planner schema 细节，拖慢主链路收口。
规避建议：先把
plan_execute定位为“复用公共执行器的上层策略”，不是独立系统。10. 建议团队重点讨论的问题
本次评审建议重点只讨论四个问题：
Flow是否只负责策略编排，而不承担工具协议解析细节/y/n和 UI 状态恢复plan_execute是否明确复用react执行器，而不是独立实现一套工具循环11. 最终建议
建议团队采纳当前方案的大方向，但将其调整为以下表述：
“NeoCode 将引入可注册的 Flow 编排层，在 Service 端统一管理单次响应、工具闭环和计划执行。为保证未来新增思考流程时不需要反复修改函数命名和主链路接口，本次改造将优先稳定内部事件流、工具协议解析抽象和审批恢复机制；外部文本流契约暂时保持兼容，待内部编排收敛后再评估是否升级传输协议。”
这套表述比“先实现三个 Flow”更适合团队讨论，因为它先锁定了长期稳定的边界，而不是先锁定某个具体实现形态。