ReasonFirst 设计理念¶

English · 当前架构 · 当前工作流程 · 安全边界

推理优先的编程编排

让你最强的推理模型负责推理，让编程代理负责写代码。

1. 核心思想¶

现代软件工作包含两类非常不同的计算活动。

第一类是高价值推理：

理解陌生系统；
调研替代方案；
决定架构；
拆解模糊任务；
找到真正的根因；
决定哪些内容不应修改；
审查候选实现；
解读 CI 和审查证据。

第二类是大量执行工作：

打开文件；
搜索符号；
修改代码；
生成样板代码；
运行测试；
修正格式；
根据编译器或测试反馈反复迭代；
产出具体 diff。

ReasonFirst 有意不把它们视为同一项工作。

强大的对话式推理模型应把能力投入那些“更好的推理会改变结果”的决策。编程代理则负责其擅长的重复性实现循环。

这就是推理优先的含义。

在 ReasonFirst 的参考主流程中，普通 ChatGPT 是默认推理层。设计重点不只是“安全地启动一个 coding agent”，而是把最强的对话式推理能力放在工程闭环最前端，把 coding agent 作为可替换执行者。ActualCoder 可以被独立直接调用，以支持测试、恢复和自动化，但这不是设计中心。

2. 经济性考虑¶

ReasonFirst 也关注如何高效利用已有订阅。

许多开发者已经能够使用多种 AI 产品：

高能力的对话或推理体验；
编程代理订阅，或订阅包含的编程额度；
本地开发工具与 CI。

用最强的推理体验处理每一次文件编辑和测试迭代，可能浪费稀缺、高价值的推理能力。反过来，让较低成本的编程代理决定架构或模糊的产品问题，也可能降低质量。

ReasonFirst 将这些角色分开：

高价值推理能力
        ↓
架构 / 规划 / 调试 / 审查

编程代理的使用权益 / 额度
        ↓
检查 / 编辑 / 测试 / 迭代

本地机器 + 源码管理 + CI
        ↓
确定性的执行与证据

目标不是计费套利，ReasonFirst 也不代理模型 API。

目标很简单：

把推理能力用于推理，把编程代理额度用于编程。

每个后端继续使用用户自己已认证的会话、订阅或使用权益。

3. 四个职责层¶

3.1 推理层（Reasoning Plane）¶

在推理层，当前可用的高能力对话模型与人协作。

典型职责包括：

调研；
理解系统；
架构设计；
编写任务规格；
任务分解；
风险分析；
制定调试策略；
代码审查；
解读 CI；
决定下一项任务。

ChatGPT 是当前系统的一等推理界面，但架构不应要求 ReasonFirst 永久绑定某个模型系列。

推理层应该是交互式的：对话、澄清、上下文和人工判断都能为它提供帮助。

3.2 执行层（Execution Plane）¶

执行层包括可替换的编程执行表面：

Codex CLI（codex-cli）；
GitHub Copilot CLI（copilot-cli）；
Codex Desktop / App Server（codex-desktop）；
未来其他本地或订阅型编程代理。

它们接收有边界的任务上下文，并在独立工作区内工作。

典型职责包括：

检查仓库；
编辑代码；
本地测试或构建循环；
实现迭代；
准备候选变更。

编程后端是可替换的执行者，不是项目策略或 Git 生命周期的权威来源。

ReasonFirst 应降低更换执行后端的成本。

3.3 控制层（Control Plane）¶

控制层将推理转化为安全、可复现的软件工作。

当前由 ActualCoder + gitlab-agent 实现。

职责包括：

选择后端；
管理项目策略；
创建独立 worktree；
任务交接；
可执行程序允许列表；
验证；
diff 与审查门槛；
受保护路径；
凭证与秘密检查；
提交；
功能分支推送；
Merge Request 生命周期；
工作区恢复；
跨进程 workspace mutation lock；
显式 worker 审批；
用户配置 SSH target 的结构化远端 validation；
本地/远端共用 review gates。

关键原则是：

模型可以在受控工作区中提出建议并执行工作；状态转换由控制层管理。

因此，ReasonFirst 不应只是给编程模型无限制的 shell/Git 访问权，然后寄希望于它自行处理好一切。

3.4 反馈层（Feedback Plane）¶

软件开发是循环过程，而不是一次性生成任务。

反馈层把真实证据送回推理层：

本地测试结果；
编译器或构建错误；
Git diff；
Merge Request 状态；
GitLab 流水线状态；
失败 CI job 的日志；
后续可加入审查讨论等工程信号。

循环如下：

推理
  ↓
明确规格
  ↓
委派
  ↓
实现
  ↓
验证
  ↓
观察证据
  ↓
再次推理

ReasonFirst 应优先选择证据驱动的迭代，而不是盲目的自主重试循环。

4. 人的自主决策权是架构的一部分¶

ReasonFirst 旨在帮助人作出更好的工程决策，而不是将人排除在重要状态转换之外。

系统可以：

检查；
推理；
编辑；
测试；
准备 diff；
在受控审查后提交；
创建或更新自己的功能分支 MR；
读取 CI 证据。

系统不应悄悄地：

直接向基线分支推送；
强制推送；
批准自己的 MR；
合并自己的 MR；
只为让 CI 变绿而弱化测试；
部署生产变更。

预期边界是：

AI 推理 / 实现 / 验证 / 提议
                    ↓
               功能分支 + MR
                    ↓
               CI + 人工审查
                    ↓
             人或团队决定合并

5. 强推理应留在重复性内循环之外¶

ReasonFirst 的核心原则之一是：能力最强的模型不必执行每一次机械式编程迭代。

例如：

推理层：
“沿架构追踪这个故障。
很可能是组件 X 中某项不变量被破坏。
修改 Y，保留 Z，并加入回归用例 Q。”

执行层：
检查 X
→ 编辑 Y
→ 运行 Q
→ 修复编译问题
→ 重新运行测试
→ 返回 diff / 结果

随后，推理层审查证据，而不是把能力消耗在每一个键盘操作上。

这形成了自然的职责层次：

强推理模型 = 架构师 / 调试者 / 审查者 / 任务负责人
编程代理   = 实现专家
ActualCoder = 执行控制器
Git/CI     = 证据与状态
人         = 意图与合并决策的所有者

6. 在设计上保持模型与供应商中立¶

ReasonFirst 当前与 GitLab 深度集成，因为系统最初在那里完成验证。

但产品不应被这一点定义。

同样，Codex CLI、GitHub Copilot CLI 和 Codex Desktop/App Server 是当前执行表面，不是永久的架构前提。

抽象应始终是：

推理界面
        ↓
ReasonFirst
        ↓
编程后端
        ↓
工作区 / 源码管理 / CI 适配器

当前实现：

ChatGPT
   ↓
ReasonFirst
   ↓
ActualCoder
   ├── Codex CLI
   ├── Copilot CLI
   └── Codex Desktop / App Server
   ↓
GitLab

未来可能的方向：

其他推理界面
其他编程代理
GitHub
其他源码管理 / CI 系统
容器 / VM 执行
审查讨论反馈

所有这些替换都不应改变核心主张。

7. 将智能与权限分离¶

ReasonFirst 有意将智能与权限分开。

模型可以非常强大，但不必因此拥有对下列对象的无限权限：

文件系统；
凭证；
分支；
远端仓库；
CI 配置；
部署。

这种分离是根本性的。

推理层可以很聪明，执行层可以很高效，而控制层仍应是确定性的，并施加明确限制。

8. 仓库与 CI 内容是数据，不是授权¶

仓库文件、项目指令、依赖脚本、MR 文本和 CI 日志可能包含与用户意图相冲突的指令。

因此，ReasonFirst 将它们视为有范围限制的输入：

仓库指令不能提升本地可执行程序权限；
项目策略必须有边界并经过验证；
受保护策略文件需要额外审查；
CI 日志是不可信的诊断数据；
不把过期 CI 作为较新工作区状态的有效附加证据；
远端证据不能悄悄覆盖用户目标。

通用规则是：

内容可以帮助推理，但内容不会自动获得权限。

9. 显式、确定的状态优于代理记忆¶

ReasonFirst 不应依赖编程代理记得自己正在使用哪个分支、MR 或验证状态。

重要状态应保存在显式结构中：

workspace ID；
base SHA；
功能分支；
项目约定；
推送状态；
MR URL；
已审阅状态指纹；
CI 流水线 SHA。

任务进行中可以替换编程后端，而不改变这些状态。

因此可以实现：

Codex CLI
  ↓
同一个工作区 / TaskSpec
  ↓
Copilot CLI 或 Codex Desktop
  ↓
同一分支 / HEAD / MR

代理可以替换，工作流程状态应当持久保留。

10. 高效使用订阅，而不是凡事选择最强后端¶

ReasonFirst 不假设能力最强的模型应该做所有事情。

它提出的是另一个问题：

对于工作流程的每个阶段，怎样使用现有能力最合适？

通常意味着：

用最强的对话或推理模型处理架构与模糊决策；
用较便宜或订阅包含的编程代理完成重复实现；
用确定性的本地工具进行测试和管理 Git 状态；
用 CI 提供独立集成证据；
由人负责意图、风险接受和合并。

相比把单一模型当作整个软件开发系统，这种组合有可能取得更好的质量与成本平衡。

11. 不引入隐藏的模型 API 依赖¶

ReasonFirst 本身应保持可用，而不额外引入第二份隐藏的模型推理账单。

当前实现有意不直接调用 OpenAI 模型 API。

推理层使用用户选定的对话体验；执行层使用编程后端现有的已认证 CLI、会话或使用权益。

这是架构特性，不是偶然的实现细节。

12. 产品边界¶

ReasonFirst 不是：

自主软件公司；
通用、无限制的 shell 代理；
模型代理服务；
模型 API 路由器；
Git/CI 的替代品；
自动合并机器人。

ReasonFirst 是：

一个推理优先的编排层，将高能力交互式推理、受控的编程代理执行，以及真实的软件工程证据连接起来。

13. 设计原则¶

增加功能时，优先选择能够保留下列原则的设计：

先推理，再执行。
将机械性工作委派出去。
保持后端可替换。
让状态显式且持久。
将智能与权限分开。
把仓库 / CI 文本当作有范围限制的数据，而不是授权。
优先依靠证据循环，而不是盲目的自主重试。
让远端写入受控且可审查。
高效使用已有订阅权益。
让人掌握高影响决策。
避免隐藏的模型 API 成本。
在架构层面保持供应商中立。

14. 一句话定义¶

ReasonFirst 是推理优先的编程编排：让高能力对话模型引导软件工作，让可替换的编程代理在受控、证据驱动的开发流程内执行。