@motivation-labs/crosscheck 0.8.0-beta.21 → 0.8.0-beta.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +41 -215
  2. package/README.zh.md +51 -176
  3. package/get-started.zh.md +420 -50
  4. package/package.json +1 -1
package/README.zh.md CHANGED
@@ -6,32 +6,22 @@
6
6
  <img src="./assets/logo.png" alt="crosscheck" width="160" />
7
7
  </p>
8
8
 
9
- # crosscheck
10
-
11
- **一个轻量级编排层，让你的 AI 编程助手互相审查代码——并自动修复问题。**
9
+ <p align="center"><em>用 crosscheck 构建 crosscheck。</em></p>
12
10
 
13
- 当 Claude Code 提交 PR 时，由 Codex 审查；当 Codex 提交 PR 时，由 Claude 审查。发现问题后，原作者 Agent 提交修复并推送回去。这一切都在你的本地机器上运行，使用你已有的订阅，一条命令即可启动。
11
+ # crosscheck
14
12
 
15
- ```
16
- GitHub PR → crosscheck watch → AI 审查意见发布 → 修复提交
17
- ```
13
+ **为使用 Claude Code 和 Codex 的开发者打造的自动化 AI Code Review——按你的方式配置，零额外基础设施。**
18
14
 
19
- > 灵感来自 [Symphony](https://github.com/openai/symphony) —— OpenAI 的规范驱动多智能体框架。Symphony 在产品/交付层面协调 Agent，而 crosscheck 保持在工程师最熟悉的工作层面：Pull Request、代码差异和 Code Review。无需引入新的抽象概念——只是将 CR + 修复的工作流程自动化。
15
+ 当你的 AI Agent 提交 PR 时，另一个 AI 负责审查。发现问题后，原作者 Agent 自动修复并提交跟进 PR。整个流程运行在你已有的订阅上，一条命令即可启动。
20
16
 
21
17
  ---
22
18
 
23
- ## 为什么选择 crosscheck
24
-
25
- AI 编程助手提交代码的速度很快，但也会自信地犯下看似合理的错误。解决方案不是让人类审查每一个 AI 提交的 PR——而是让*另一个* AI 来审查。Claude 和 Codex 有互补的盲点，跨供应商审查比任何单一模型都能发现更多问题，同时不会给每次提交增加人工审查的延迟。
19
+ ## 核心亮点
26
20
 
27
- crosscheck 将这个闭环连接起来：
28
-
29
- | | |
30
- |---|---|
31
- | **本地执行，持续监听** | 在你的机器上运行。`crosscheck watch` 打开隧道后持续运行，无需云服务、基础设施或 SaaS。 |
32
- | **订阅驱动，无额外计费** | 调用 `claude` 和 `codex` 命令行工具，使用你已有的 Claude Pro/Max 和 ChatGPT Plus/Pro 订阅。无需按 token 付费，订阅后审查完全免费。 |
33
- | **默认跨供应商** | Claude 审查 Codex 的 PR；Codex 审查 Claude 的 PR。每个模型有不同的训练数据和不同的故障模式，交叉点正是 Bug 藏身之处。 |
34
- | **持续自我优化** | `crosscheck diagnose` 从日志中发现失败模式，`crosscheck optimize` 将这些模式反馈给 AI，自动更新审查指令。 |
21
+ - **可定制的审查工作流** — 灵活配置完整流水线：仅审查、审查 + 自动修复，或审查 + 修复 + 复查。每个步骤均可定制审查指令，无需手动编辑 Prompt。
22
+ - **跨供应商模式与单供应商模式** — 跨供应商模式将每个 PR 路由给对手 AI 进行独立审查；单供应商模式则使用你拥有的任意一个 AI。一行配置即可切换。
23
+ - **订阅驱动，无需按 token 计费** — 通过 `claude` 和 `codex` 命令行工具运行，使用你已有的 Claude Pro/Max 和 ChatGPT Plus/Pro 订阅。无需 API Key，无额外审查费用。
24
+ - **`watch` 个人使用，`serve` 服务团队** — `crosscheck watch` 在本地笔记本运行并自动建立隧道，适合个人开发者。`crosscheck serve` 绑定到共享机器的固定端口，让整个团队无需任何人保持笔记本在线即可获得覆盖。
35
25
 
36
26
  ---
37
27
 
@@ -44,76 +34,44 @@ npm install -g @anthropic-ai/claude-code && claude # 需要 Claude Pro/Ma
44
34
  npm install -g @openai/codex && codex login --device-auth # 需要 ChatGPT Plus/Pro 订阅
45
35
  brew install gh && gh auth login # GitHub CLI
46
36
 
47
- # 2. 检查运行环境
48
- crosscheck init
49
-
50
- # 3. 对单个 PR 进行测试
51
- crosscheck review https://github.com/your-org/repo/pull/42
52
-
53
- # 4. 持续运行
54
- crosscheck watch
55
- ```
56
-
57
- `crosscheck watch` 会通过 `localhost.run` 建立 SSH 隧道（无需安装任何软件，无需账号），自动注册 GitHub Webhook，然后开始监听。GitHub 推送 PR 事件后，crosscheck 将其路由到正确的审查者。
58
-
59
- ---
60
-
61
- ## 工作原理
37
+ # 2. 引导式配置——选择仓库、供应商模式、工作流流水线
38
+ crosscheck onboard
62
39
 
40
+ # 3. 启动监听
41
+ crosscheck watch # 个人笔记本
42
+ crosscheck serve # 团队常驻服务器
63
43
  ```
64
- ┌────────────────────────────────────────────────────────────────┐
65
- │ 你的笔记本 │
66
- │ │
67
- │ crosscheck watch │
68
- │ ├── SSH 隧道 (localhost.run) ◄──── GitHub Webhook │
69
- │ ├── Webhook 服务器 (:7891) │
70
- │ └── PR 处理器 │
71
- │ ├── 识别来源 (Claude Code? Codex? 其他?) │
72
- │ ├── 克隆 PR 分支 │
73
- │ ├── 运行审查者 (跨供应商分配) │
74
- │ ├── 发布审查评论 │
75
- │ └── 地址步骤 (修复问题，推送 [crosscheck] 提交) │
76
- └────────────────────────────────────────────────────────────────┘
77
- ```
78
-
79
- **路由** 基于 PR 正文的匹配模式。`Generated with [Claude Code]` → 由 Codex 审查；`Generated with [OpenAI Codex]` → 由 Claude 审查。`allowed_authors` 字段将审查限制在你的 Agent 账号提交的 PR 上。
80
44
 
81
- **地址步骤**（可选，通过工作流配置启用）在审查完成后运行。原作者 Agent 读取自己的审查评论并将修复提交回 PR 分支，提交前缀为 `[crosscheck]`，每个 PR 最多提交 5 次修复。
82
-
83
- **反馈闭环** 通过 `crosscheck diagnose` → `crosscheck optimize` 实现。`~/.crosscheck/logs/` 中的失败模式和质量信号会自动反馈为更好的审查指令，无需手动编辑配置。
45
+ `crosscheck onboard` 将引导你完成仓库选择、供应商模式、流水线步骤和隧道选择。完成后，运行 `watch` 或 `serve` 即可。
84
46
 
85
47
  ---
86
48
 
87
- ## watch 运行输出示例
49
+ ## 运行效果
88
50
 
89
51
  ```
90
52
  $ crosscheck watch
91
53
 
92
54
  "Move fast and review things."
93
55
 
94
- crosscheck watch
95
-
96
- repos your-org/your-repo
97
- mode cross-vendor
98
- quality balanced
99
- config ./crosscheck.config.yml ← 编辑此文件可修改配置
56
+ profile personal · cross-vendor · balanced
57
+ users your-github-login (5 repos)
58
+ auto-fix on_issues · same-as-author · pull_request
59
+ config ./crosscheck.config.yml
100
60
 
101
61
  ✓ 隧道已就绪: https://abc123.lhr.life
102
62
  ✓ 已为 your-org/your-repo 注册 Webhook
103
- 等待 PR 事件 — 按 Ctrl+C 停止。
63
+ 等待 PR 事件 — 按 Ctrl+C 停止。
104
64
 
105
65
  PR #47 opened: add retry logic for flaky network calls
106
66
  origin=claude reviewer=codex
107
67
  codex reviewing... (12s)
108
- review complete (12s)
109
- posted → github.com/your-org/your-repo/pull/47
110
68
  NEEDS WORK
69
+ auto-fix claude fixing...
70
+ fix PR #48 opened → github.com/your-org/your-repo/pull/48
111
71
 
112
- PR #48 opened: implement caching layer
72
+ PR #49 opened: implement caching layer
113
73
  origin=codex reviewer=claude
114
74
  claude reviewing... (18s)
115
- review complete (18s)
116
- posted → github.com/your-org/your-repo/pull/48
117
75
  APPROVE
118
76
  ```
119
77
 
@@ -123,140 +81,57 @@ PR #48 opened: implement caching layer
123
81
 
124
82
  ```bash
125
83
  crosscheck init # 检查环境，生成初始配置文件
84
+ crosscheck onboard # 引导式配置——选择仓库、模式和流水线
126
85
  crosscheck review <pr-url> # 对指定 PR 进行一次性审查
127
- crosscheck watch # 本地开发模式——隧道 + 自动 Webhook + 监听
128
- crosscheck serve # 常驻模式——固定端口，手动注册 Webhook
129
- crosscheck status # 查看认证状态、配置、日志摘要、CLI 版本
86
+ crosscheck watch # 个人使用——隧道 + 自动 Webhook + 本地监听
87
+ crosscheck serve # 团队使用——固定端口，一次性注册 Webhook
88
+ crosscheck status # 查看认证状态、配置摘要、CLI 版本
89
+ ```
90
+
91
+ **持续改进** *（实验性）*
92
+
93
+ ```bash
130
94
  crosscheck diagnose # 从审查日志中提取失败模式
131
- crosscheck optimize [--apply] # 根据 diagnose 输出更新审查指令
95
+ crosscheck optimize [--apply] # 根据 diagnose 输出重写审查指令
132
96
  crosscheck impact [--money] # 节省时间、发现问题、代码质量趋势报告
97
+ crosscheck issue # 从近期错误日志起草并提交 Bug 报告
133
98
  ```
134
99
 
135
100
  ---
136
101
 
137
102
  ## 配置说明
138
103
 
139
- `crosscheck.config.yml` 位于项目根目录，AI 编程助手可以直接读取和修改它。
104
+ 配置文件位于 `~/.crosscheck/config.yml`，一个文件覆盖所有仓库。运行 `crosscheck init` 生成，或通过 `crosscheck onboard` 自动写入。
140
105
 
141
106
  ```yaml
142
- # 监听的组织/仓库（至少配置一项）
143
107
  orgs:
144
- - your-org # 覆盖该组织下的所有仓库
108
+ - your-org
145
109
 
146
- # 仅审查这些 GitHub 账号提交的 PR
147
110
  routing:
148
111
  allowed_authors:
149
- - your-claude-bot-account
150
- - your-codex-bot-account
112
+ - your-github-login
151
113
 
152
- # 审查深度
153
114
  quality:
154
- tier: balanced # fast（快速）| balanced（均衡）| thorough（深度）
155
-
156
- # 可选费用上限
157
- budget:
158
- per_review_usd: 2.0
159
- codex_monthly_usd: 50
160
-
161
- # 隧道后端（仅 watch 模式使用）
162
- # localhost.run — 无需安装，自动重连（默认）
163
- # smee — 稳定的频道 URL，离线时事件排队
164
- tunnel:
165
- backend: localhost.run
115
+ tier: balanced # fast（快速）| balanced（均衡）| thorough（深度）
116
+
117
+ post_review:
118
+ auto_fix:
119
+ enabled: true
120
+ trigger: on_issues # on_issues | always | never
121
+ fixer: same-as-author
122
+ delivery:
123
+ mode: pull_request
166
124
  ```
167
125
 
168
126
  完整配置参考：[get-started.zh.md](./get-started.zh.md)
169
127
 
170
128
  ---
171
129
 
172
- ## 持续自我优化
173
-
174
- 每次审查结果都会记录到 `~/.crosscheck/logs/YYYY-MM-DD.ndjson`。随着时间推移，规律会逐渐显现——审查者尝试运行（并失败）的命令、判断分布、审查时长趋势。
175
-
176
- ```bash
177
- # 查看问题所在
178
- $ crosscheck diagnose
179
-
180
- crosscheck diagnose (2026-01-01 → 2026-05-08 · 3 个日志文件)
181
-
182
- 审查总计 47 次 — 28 APPROVE 14 NEEDS WORK 5 BLOCK
183
- 失败率 codex 12% / claude 4%
184
-
185
- 建议
186
- ─────────────────────────────────────────────────────────────
187
- ✦ codex 在审查时尝试运行 `npm test`（7 次）
188
- → 在 instructions 中添加："不要运行 npm、tsc 或测试命令。"
189
- ✦ 3 次审查在大型 PR（>400 行改动）上超时
190
- → 考虑为超过一定大小的 PR 设置 quality.tier: fast
191
-
192
- # 自动应用修复建议
193
- $ crosscheck optimize --apply
194
- agent claude（失败率更低：4% vs codex 12%）
195
- 正在写入 ~/.crosscheck/instructions.md
196
- + 不要运行 npm、tsc、jest 或任何构建/测试命令。
197
- + 将超过 400 行改动的 PR 标记为过大，无法进行深度审查。
198
- 完成
199
-
200
- # 量化累计价值
201
- $ crosscheck impact --money
202
-
203
- crosscheck impact (全部时间 · 47 次审查)
204
-
205
- 节省时间
206
- ──────────────────────────────────────────────
207
- 审查次数 47
208
- AI 平均审查时间 ~14 分钟
209
- 人工预估时间 60 分钟 ⓘ
210
- 共节省时间 ~43 小时
211
-
212
- 发现问题
213
- ──────────────────────────────────────────────
214
- APPROVE 28 (60%)
215
- NEEDS WORK 14 (30%) ← 可操作的反馈
216
- BLOCK 5 (11%) ← 潜在 Bug / 破坏性变更
217
- 共发现问题 19
218
-
219
- 估算价值: ~$8,450
220
- (43h × $150/hr + 19 个问题 × $150/个)
221
- ```
222
-
223
- ---
224
-
225
130
  ## 部署方式
226
131
 
227
- ### 笔记本 — `crosscheck watch`
228
-
229
- 零配置。通过 `localhost.run` 建立 SSH 隧道处理 NAT 穿透，无需端口转发，无需云账号。如果隧道静默断开，健康检查会在约 2 分钟内检测到并强制重连 + 重新注册 Webhook。
230
-
231
- ```bash
232
- crosscheck watch
233
- # → 打开隧道，注册 Webhook，开始监听
234
- ```
235
-
236
- ### 服务器 — `crosscheck serve`
132
+ **个人使用（`crosscheck watch`）** — 运行在你的笔记本上。通过 `localhost.run` 建立 SSH 隧道，无需端口转发，无需云账号。隧道断开时健康检查会自动重连。
237
133
 
238
- 绑定到具有公网 IP 的机器上的固定端口，手动注册一次 Webhook 即可。
239
-
240
- ```bash
241
- crosscheck serve
242
- # → 监听 :7891，手动注册 https://your-server/webhook
243
- ```
244
-
245
- ### smee.io — 稳定中继（可选）
246
-
247
- 当笔记本离线时，`localhost.run` 会丢失事件。[smee.io](https://smee.io) 会将事件排队，在重新连接后回放——适合审查机器不总是在线的团队。
248
-
249
- ```bash
250
- npm install -g smee-client
251
- # 访问 https://smee.io/new — 复制频道 URL
252
- ```
253
-
254
- ```yaml
255
- # crosscheck.config.yml
256
- tunnel:
257
- backend: smee
258
- smee_channel: https://smee.io/your-channel-id
259
- ```
134
+ **团队使用（`crosscheck serve`）** — 绑定到具有公网 IP 的机器上的固定端口，手动注册一次 Webhook，整个团队即可获得覆盖，无需任何人保持笔记本在线。
260
135
 
261
136
  ---
262
137
 
@@ -277,9 +152,9 @@ tunnel:
277
152
 
278
153
  | | |
279
154
  |---|---|
280
- | **[get-started.zh.md](./get-started.zh.md)** | 完整安装指南——前置条件、所有命令与参数、完整配置参考、工作原理、常见问题 |
155
+ | **[get-started.zh.md](./get-started.zh.md)** | 完整安装指南——前置条件、所有命令与参数、完整配置参考、常见问题 |
281
156
  | **[crosscheck.config.example.yml](./crosscheck.config.example.yml)** | 带注释的配置文件示例（每个选项均有说明） |
282
- | **[AGENT.md](./AGENT.md)** | `crosscheck optimize` 使用的 Harness 文档——AI 如何优化审查指令 |
157
+ | **[CHANGELOG.md](./CHANGELOG.md)** | 版本发布记录 |
283
158
 
284
159
  ---
285
160