mirror of
https://github.com/aiclientproxy/proxycast.git
synced 2026-10-16 07:16:36 +08:00
546 lines
16 KiB
Markdown
546 lines
16 KiB
Markdown
# Lime 如何借鉴 Codex 的工程方法：从“已有基础”到“快而稳的迭代系统”
|
||
|
||
> 目的不是照抄 Codex 的技术栈，而是借鉴它背后的工程方法，并结合 Lime 当前仓库的真实现状，收敛出一条适合我们的落地路径。
|
||
|
||
## 1. 背景
|
||
|
||
这份文档基于两部分事实：
|
||
|
||
1. 对 `openai/codex` 仓库的结构、规则、CI、测试、发布流程做了实际阅读；
|
||
2. 对 Lime 当前仓库的工程入口、脚本、工作流、测试和发布链路做了核对。
|
||
|
||
结论先写在前面：
|
||
|
||
**Lime 并不缺“零起点能力”，而是已经有不少关键积木。**
|
||
|
||
我们现在更需要的，不是继续堆更多脚本，而是把已有能力收敛成一条清晰、分层、可执行的开发与交付路径。
|
||
|
||
如果要把这些工程方法进一步落实到 Lime 的 Agent / Harness 改造，请继续阅读：
|
||
|
||
- `docs/tech/harness/README.md`
|
||
|
||
Codex 值得借鉴的，不是 Bazel、不是纯 Rust、也不是它的体量；
|
||
真正值得借鉴的是：
|
||
|
||
**他们把“如何开发、如何验证、如何发布”写进了仓库本身。**
|
||
|
||
对 Lime 来说，这一点尤其重要。
|
||
|
||
因为 Lime 当前已经不是一个简单的单体项目，而是一个同时包含：
|
||
|
||
- React + TypeScript 前端
|
||
- Tauri 桌面壳
|
||
- Rust workspace
|
||
- 多 Provider / 网关 / MCP / 插件 / 浏览器桥接
|
||
- 文档站点
|
||
- 多平台发布
|
||
|
||
的复合型仓库。
|
||
|
||
从 `src-tauri/Cargo.toml` 看，当前 Rust workspace 已经有 `20` 个 crate；
|
||
从 `package.json` 看，前端、桥接、契约、发布、本地验证、AI 验证、治理脚本都已经存在。
|
||
|
||
这意味着：
|
||
|
||
**Lime 已经进入“需要系统化工程节奏”的阶段。**
|
||
|
||
## 2. Lime 当前已经具备的基础
|
||
|
||
在讨论“借鉴 Codex”之前，先明确 Lime 不是从零开始。
|
||
|
||
### 2.1 仓库级规则已经存在
|
||
|
||
根 `AGENTS.md` 已经提供了不少高价值工程约束，例如：
|
||
|
||
- 全部输出与文档统一使用中文
|
||
- 涉及 UI 先看 `docs/aiprompts/design-language.md`
|
||
- 默认同时考虑 macOS / Windows
|
||
- 优先使用 `npm`、`cargo`、Tauri 命令与项目内封装
|
||
- 明确给出了构建、测试、代码检查入口
|
||
|
||
这意味着 Lime 已经有“仓库级规则入口”，这是非常好的基础。
|
||
|
||
### 2.2 本地验证脚本已经不弱
|
||
|
||
当前 `package.json` 里已经有一整组工程命令：
|
||
|
||
- `npm run lint`
|
||
- `npm run typecheck`
|
||
- `npm test`
|
||
- `npm run test:bridge`
|
||
- `npm run test:contracts`
|
||
- `npm run test:rust`
|
||
- `npm run verify:local`
|
||
- `npm run verify:local:full`
|
||
- `npm run ai-verify`
|
||
|
||
其中 `scripts/local-ci.mjs` 已经实现了**按改动范围智能选择任务**：
|
||
|
||
- 前端改动 -> `lint` + `typecheck` + `test`
|
||
- bridge 改动 -> `test:bridge` + `test:contracts`
|
||
- Rust 改动 -> `cargo test`
|
||
- `--full` 时再补 `cargo clippy`
|
||
|
||
这其实已经很接近 Codex 仓库里“按 changed paths 决定 CI 跑什么”的思路了。
|
||
|
||
### 2.3 Git hook 也已经上线
|
||
|
||
`.husky/pre-commit` 当前会执行：
|
||
|
||
`npx tsx scripts/ai-code-verify.ts`
|
||
|
||
也就是说，Lime 已经不是“完全依赖人工自觉”的状态，而是开始把工程约束前移到提交流程。
|
||
|
||
### 2.4 契约与一致性检查已经有雏形
|
||
|
||
当前仓库里至少已经有两个很重要的“机器校验型”脚本：
|
||
|
||
- `scripts/check-app-version-consistency.mjs`
|
||
- `scripts/check-command-contracts.mjs`
|
||
|
||
前者会检查：
|
||
|
||
- `package.json`
|
||
- `src-tauri/Cargo.toml`
|
||
- `src-tauri/tauri.conf.json`
|
||
- `src-tauri/tauri.conf.headless.json`
|
||
|
||
的版本是否一致。
|
||
|
||
后者会检查：
|
||
|
||
- 前端 `safeInvoke` / `invoke` 实际调用了哪些 Tauri 命令
|
||
- `src-tauri/src/app/runner.rs` 里真正注册了哪些命令
|
||
- mock priority 命令集合是否同步
|
||
|
||
这已经非常接近 Codex 那种“把接口契约变成可自动验证对象”的方向了。
|
||
|
||
### 2.5 发布链路也已具备完整骨架
|
||
|
||
当前 `.github/workflows/release.yml` 已经具备：
|
||
|
||
- tag 驱动发布
|
||
- 多平台构建（macOS arm64 / x64，Windows x64）
|
||
- 版本同步到 Tauri 配置
|
||
- release notes 生成
|
||
- GitHub Release 上传
|
||
|
||
再加上：
|
||
|
||
- `deploy-docs.yml`
|
||
- `update-homebrew.yml`
|
||
|
||
说明 Lime 已经不是没有交付能力，而是已经有了一个基础发布流水线。
|
||
|
||
## 3. Lime 当前最明显的缺口
|
||
|
||
和 Codex 对比后，我认为 Lime 当前最核心的缺口不是“工具不够多”，而是下面三件事还没有完全收敛。
|
||
|
||
### 3.1 缺少一个统一的 PR 质量主入口
|
||
|
||
当前 GitHub Actions 里：
|
||
|
||
- `ci.yml` 主要覆盖 `src-tauri/**` 改动下的 **Windows OpenClaw regression**
|
||
- `deploy-docs.yml` 只负责文档站点
|
||
- `release.yml` 只负责发布
|
||
|
||
这意味着，Lime 当前很多重要校验虽然**本地可跑**，但还没有成为 PR 上稳定、清晰、统一的 required status，例如：
|
||
|
||
- 前端 `lint`
|
||
- 前端 `typecheck`
|
||
- Vitest
|
||
- `test:contracts`
|
||
- GUI headless smoke
|
||
- Rust 全量测试 / `clippy`
|
||
- bridge / smoke 校验
|
||
|
||
也就是说，我们已经有很多验证动作，但还没有把它们真正收束成“团队共同依赖的一条质量主链路”。
|
||
|
||
### 3.2 现有脚本之间还偏“并列”，没有形成明确分层
|
||
|
||
现在仓库里已经有：
|
||
|
||
- pre-commit 的 `ai-verify`
|
||
- 本地智能校验 `verify:local`
|
||
- 前端和 Rust 单独测试命令
|
||
- bridge / smoke / contracts 脚本
|
||
|
||
但还缺一件事：
|
||
|
||
**每一层到底该挡什么问题，团队的预期还不够明确。**
|
||
|
||
比如现在容易出现的疑问：
|
||
|
||
- `ai-verify` 是补充提醒，还是硬门禁？
|
||
- `verify:local` 是建议执行，还是提交前标准动作？
|
||
- `test:contracts` 什么时候必须跑？
|
||
- `smoke:social-workbench` 该放本地还是 CI？
|
||
|
||
Codex 很强的一点，就是每一层的角色很清楚。
|
||
|
||
Lime 现在更像是“积木已经有了，但还没拼成系统”。
|
||
|
||
### 3.3 契约检查已有基础，但还没有完全上升为“关键接口演进规范”
|
||
|
||
`check-command-contracts.mjs` 已经很有价值，但它目前更像一个检查脚本，而不是一整套“接口演进流程”的中心。
|
||
|
||
对 Lime 这种项目来说，真正高风险的契约不止是 Tauri command 名称，还包括：
|
||
|
||
- Tauri command 参数结构
|
||
- 前后端共享数据结构
|
||
- bridge 交互协议
|
||
- OpenClaw / Gateway / Workspace 相关状态快照
|
||
- 插件 / MCP 相关 manifest 或接口字段
|
||
|
||
Codex 的经验告诉我们：
|
||
|
||
**接口文档、生成物、测试、实现，最好一起演进。**
|
||
|
||
这正是 Lime 接下来最该补齐的一层。
|
||
|
||
## 4. Codex 最值得 Lime 借鉴的五个方法
|
||
|
||
下面只写“适合 Lime 的”，不写那些和我们技术栈不匹配的。
|
||
|
||
### 4.1 借鉴一：建立单一的“质量主入口”
|
||
|
||
Codex 很重要的一个做法，是把很多检查统一收口到一个最终状态上。
|
||
|
||
对 Lime 来说，最值得借鉴的是：
|
||
|
||
**新增一个主质量工作流，让 PR 的主要质量信号只看这一条。**
|
||
|
||
建议名称可以是：
|
||
|
||
- `.github/workflows/quality.yml`
|
||
|
||
这个工作流不需要一开始就做得很重，但应该具备三个特征：
|
||
|
||
1. **按改动范围决定执行内容**
|
||
2. **聚合前端 / Rust / bridge / docs 的核心信号**
|
||
3. **最后产出一个统一 results job 作为 required status**
|
||
|
||
这件事最好优先复用已有逻辑，而不是重写。
|
||
|
||
最合适的方式是：
|
||
|
||
- 继续保留 `scripts/local-ci.mjs` 作为本地入口
|
||
- 抽一层共享的 changed-path 规则到独立脚本
|
||
- 本地与 CI 共同复用这套判断逻辑
|
||
|
||
这样才能保证：
|
||
|
||
- 本地怎么判断改动范围
|
||
- CI 怎么判断改动范围
|
||
|
||
尽量一致。
|
||
|
||
### 4.2 借鉴二：把现有验证动作分层，而不是继续堆并列命令
|
||
|
||
建议把 Lime 的工程验证分成四层：
|
||
|
||
#### Layer 0：提交前快速提醒
|
||
|
||
保留 `.husky/pre-commit` 的 `ai-verify`，但明确定位为：
|
||
|
||
- 快速提醒
|
||
- 风险提示
|
||
- 代码卫生检查
|
||
|
||
**不要把它视为“提交前完整验证”的替代品。**
|
||
|
||
#### Layer 1：开发者本地标准入口
|
||
|
||
继续以 `npm run verify:local` 为核心。
|
||
|
||
建议将它明确成：
|
||
|
||
**所有功能型改动在发起 PR 前默认至少跑一次。**
|
||
|
||
这样 Lime 就不需要额外引入 `justfile` 一类新工具，仍然符合我们仓库“优先使用 `npm` / `cargo` / Tauri 命令”的跨平台约束。
|
||
|
||
#### Layer 2：PR 级智能 CI
|
||
|
||
这里建议接入：
|
||
|
||
- 前端：`npm run lint`、`npm run typecheck`、`npm test`
|
||
- bridge：`npm run test:bridge`、`npm run test:contracts`
|
||
- Rust：`cargo test --manifest-path "src-tauri/Cargo.toml"`
|
||
- Rust 扩展：按路径触发的 `cargo clippy`
|
||
|
||
#### Layer 3：高风险路径专项验证
|
||
|
||
这层不必每个 PR 都跑，但应该对特定路径生效，例如：
|
||
|
||
- `src/lib/dev-bridge/**`
|
||
- `src/lib/tauri-mock/**`
|
||
- `src/components/openclaw/**`
|
||
- `src-tauri/src/services/openclaw_service/**`
|
||
- `src-tauri/src/app/**`
|
||
- Workspace / browser-runtime / MCP / plugin 高风险路径
|
||
|
||
可以复用现有命令：
|
||
|
||
- `npm run bridge:health`
|
||
- `npm run verify:gui-smoke`
|
||
- `npm run bridge:e2e`
|
||
- `npm run smoke:workspace-ready`
|
||
- `npm run smoke:social-workbench`
|
||
|
||
其中如果明确把 Lime 看作 **GUI 桌面产品**，我更建议把高风险路径的最小专项护栏优先收口成一个统一入口：
|
||
|
||
- `npm run verify:gui-smoke`
|
||
|
||
它适合作为：
|
||
|
||
- headless Tauri 启动验证
|
||
- DevBridge 健康检查
|
||
- 默认 workspace 准备态 smoke
|
||
|
||
这样既不会一开始就把所有页面都推进重型 E2E，也能确保桌面壳、前端入口、bridge 和 workspace 基本链路至少有一条稳定的自动回归。
|
||
|
||
#### Layer 4：发布前全量验证
|
||
|
||
发布时建议至少统一收口：
|
||
|
||
- `npm run verify:app-version`
|
||
- `npm run test:frontend`
|
||
- `npm run test:contracts`
|
||
- `npm run test:rust`
|
||
- `npm run lint:rust`
|
||
|
||
这样 release workflow 才不会只在“能构建”层面把关，而能同时覆盖“接口一致性”和“核心回归风险”。
|
||
|
||
### 4.3 借鉴三：把“命令契约”升级成 Lime 的正式工程边界
|
||
|
||
Codex 很强调契约一致性。
|
||
|
||
Lime 现在已经有 `check-command-contracts.mjs`，这是非常好的起点。
|
||
|
||
建议下一步不要只把它当脚本，而是把它升级成：
|
||
|
||
**Lime 的正式工程边界规范之一。**
|
||
|
||
具体建议：
|
||
|
||
1. **PR CI 默认跑 `npm run test:contracts`**
|
||
2. **凡是修改 `src-tauri/src/app/runner.rs`、前端 `safeInvoke` 调用、bridge mock 命令集合的改动，都要求契约检查通过**
|
||
3. **后续逐步扩展到“命令名之外的参数契约”**
|
||
|
||
这里不建议一上来做成很重的 schema 系统，而是先做最小闭环：
|
||
|
||
- 命令名一致
|
||
- 参数结构不出现静默漂移
|
||
- mock / runtime / frontend 三方同步
|
||
|
||
这是 Lime 当前最值得优先工程化的一条“接口护栏”。
|
||
|
||
### 4.4 借鉴四：让治理脚本进入主流程，而不是停留在工具箱
|
||
|
||
Codex 的一个显著特点，是“治理不是旁路”。
|
||
|
||
Lime 当前已经有：
|
||
|
||
- `npm run governance:legacy-report`
|
||
- `scripts/report-legacy-surfaces.mjs`
|
||
|
||
同时我们也已经在 `docs/develop/` 下沉淀了不少退场与治理文档，例如：
|
||
|
||
- `execution-tracker-deprecation-plan.md`
|
||
- `execution-tracker-p0-acceptance-report.md`
|
||
|
||
这意味着 Lime 已经具备治理意识，但还可以更进一步：
|
||
|
||
### 建议做法
|
||
|
||
1. 把 `governance:legacy-report` 纳入定期检查或专项 CI
|
||
2. 对明确已经进入退场窗口的旧路径，增加“新增引用即报警”的守卫
|
||
3. 每个重要治理主题都要求同时有：
|
||
- 技术计划
|
||
- 退场计划
|
||
- 验收报告
|
||
- 守卫脚本
|
||
|
||
也就是说，治理不要只写文档，最好同时配一个可执行的检测机制。
|
||
|
||
这正是 Codex 的典型思路。
|
||
|
||
### 4.5 借鉴五：把发布从“打 tag 构建”升级成“分层交付”
|
||
|
||
Lime 当前的 `release.yml` 已经有不错的发布骨架。
|
||
|
||
但如果借鉴 Codex，我们可以把“发布”进一步拆成两个层级：
|
||
|
||
#### A. 稳定版交付
|
||
|
||
继续保留当前正式 tag 驱动的 GitHub Release、Homebrew 更新、Tauri 构建发布。
|
||
|
||
#### B. 预发布交付
|
||
|
||
针对风险较高、改动较大的版本，建议引入：
|
||
|
||
- `beta` / `rc` / `prerelease`
|
||
- 或内部 nightly / weekly 构建
|
||
|
||
原因很简单：
|
||
|
||
Lime 现在涉及：
|
||
|
||
- 桌面壳
|
||
- bridge
|
||
- 浏览器 runtime
|
||
- Provider / Gateway
|
||
- OpenClaw 安装与运行态
|
||
- 文档站点
|
||
|
||
这些链路任何一处变化，都可能需要在正式 tag 前先经过一次“真实用户环境暴露”。
|
||
|
||
Codex 的 alpha 节奏说明了一点：
|
||
|
||
**快速发布不等于鲁莽发布，预发布本身就是风险管理工具。**
|
||
|
||
## 5. 结合 Lime 实际，哪些不要照抄
|
||
|
||
借鉴 Codex，不代表要复制它的全部做法。
|
||
|
||
以下几件事我认为对 Lime 当前阶段不适合直接照搬。
|
||
|
||
### 5.1 不要为了“看起来更专业”引入额外构建系统
|
||
|
||
Codex 同时处理 Cargo / Bazel，是它自己的历史和规模决定的。
|
||
|
||
Lime 当前已经有：
|
||
|
||
- `npm`
|
||
- `cargo`
|
||
- Tauri
|
||
|
||
这套组合已经足够复杂。
|
||
|
||
现阶段不应该再额外引入一层类似 Bazel、Buck 或新的任务系统。
|
||
|
||
### 5.2 不要一下子把所有页面都做成重型 E2E
|
||
|
||
Lime 当前已经有 bridge / smoke / headless 相关脚本，这很好。
|
||
|
||
但如果一下子把所有页面都推进到全量 E2E，只会显著拉高维护成本。
|
||
|
||
更适合的做法是：
|
||
|
||
- 优先选高风险路径
|
||
- 选用户感知强、状态复杂、跨端联动重的页面
|
||
- 先做 smoke，再决定是否需要完整 E2E
|
||
|
||
### 5.3 不要让 AI 验证替代编译与测试
|
||
|
||
`.husky/pre-commit` 里的 `ai-verify` 很有价值，但它更适合做：
|
||
|
||
- 提醒
|
||
- 自检
|
||
- 风险暴露
|
||
|
||
不适合替代：
|
||
|
||
- `typecheck`
|
||
- `cargo test`
|
||
- `test:contracts`
|
||
- `clippy`
|
||
|
||
Codex 借鉴给我们的，不是“让 AI 代替工程”，而是：
|
||
|
||
**把工程流程做好之后，再让 AI 增强它。**
|
||
|
||
## 6. 建议的 Lime 落地顺序
|
||
|
||
下面给出一条尽量现实、成本可控的落地路径。
|
||
|
||
## Phase 0：收口现有入口（1 周内）
|
||
|
||
目标：先让团队对“标准本地验证路径”达成一致。
|
||
|
||
建议动作：
|
||
|
||
1. 在根 `AGENTS.md` 和开发文档中明确：
|
||
- 功能改动默认执行 `npm run verify:local`
|
||
- 大范围改动执行 `npm run verify:local:full`
|
||
2. 明确 `ai-verify` 是快速提醒层，不替代完整验证
|
||
3. 为 `test:contracts` 和 `verify:app-version` 增加更明确的使用说明
|
||
|
||
产出结果：
|
||
|
||
- 开发者知道“提交前至少跑什么”
|
||
- review 时可以默认假设这些动作已执行
|
||
|
||
## Phase 1：建立统一质量工作流（1~2 周）
|
||
|
||
目标：把本地已有能力上升为 PR 门禁。
|
||
|
||
建议动作：
|
||
|
||
1. 新增 `quality.yml`
|
||
2. 引入 changed-path detection
|
||
3. 按改动范围执行：
|
||
- frontend
|
||
- bridge/contracts
|
||
- rust
|
||
- docs build
|
||
4. 增加单一 `results` 汇总 job
|
||
|
||
产出结果：
|
||
|
||
- PR 有统一 required status
|
||
- 本地与 CI 质量路径更一致
|
||
|
||
## Phase 2：加强高风险边界（2~4 周）
|
||
|
||
目标：让最容易出事故的路径拥有专项护栏。
|
||
|
||
优先建议覆盖：
|
||
|
||
1. `safeInvoke` / Tauri command 契约
|
||
2. OpenClaw 安装与运行态相关路径
|
||
3. bridge / headless / smoke 相关路径
|
||
4. Workspace 准备态相关 smoke
|
||
|
||
可复用现有脚本：
|
||
|
||
- `npm run test:contracts`
|
||
- `npm run bridge:health`
|
||
- `npm run bridge:e2e`
|
||
- `npm run smoke:workspace-ready`
|
||
- `npm run smoke:social-workbench`
|
||
|
||
## Phase 3：把治理与预发布纳入节奏（1~2 个月）
|
||
|
||
目标：让“旧路径收口”和“风险前移”进入长期机制。
|
||
|
||
建议动作：
|
||
|
||
1. 给 `governance:legacy-report` 找到稳定的执行时机
|
||
2. 对重要治理主题建立“技术计划 + 退场计划 + 验收报告 + 守卫脚本”闭环
|
||
3. 为大改版本增加 prerelease / beta 节奏
|
||
|
||
## 7. 最终判断
|
||
|
||
如果只从表面看，Codex 和 Lime 的仓库差异很大。
|
||
|
||
但从工程方法看，Lime 其实已经有不少和 Codex 同方向的基础：
|
||
|
||
- 有仓库级规则
|
||
- 有本地智能校验
|
||
- 有 AI 验证 hook
|
||
- 有命令契约检查
|
||
- 有版本一致性检查
|
||
- 有多平台 release
|
||
- 有治理脚本和退场文档
|
||
|
||
所以 Lime 现在最需要做的，不是“再发明一套全新的方法论”，而是：
|
||
|
||
**把已有能力收口成一条清晰、稳定、分层的工程路径。**
|
||
|
||
如果用一句话概括这份文档的核心建议，那就是：
|
||
|
||
**对 Lime 来说，借鉴 Codex 的重点不是“学他们用了什么工具”，而是“把我们的规则、脚本、测试、治理和发布真正串成系统”。**
|
||
|
||
一旦这件事完成，Lime 的迭代速度和稳定性都会一起上一个台阶。
|