vault backup: 2026-06-09 23:15:17

claude-code-best/docs/features/autofix-pr.md

@@ -1,18 +1,27 @@
-# `/autofix-pr` 命令实现规格文档
-
-> **状态**：规划阶段（2026-04-29），等待评审通过后进入实施。
-> **Worktree**：`E:\Source_code\Claude-code-bast-autofix-pr`，分支 `feat/autofix-pr`，基于 `origin/main` 4f1649e2。
-> **架构**：R（Remote-via-CCR），完整版（含 stop 子命令、单例锁、subscribePR、in-process teammate、skills 探测）。
-
+---
+tags: [autofix-pr, CI, PR, 远程, CCR, 规格文档]
+create time: 2026-06-09 22:30
 ---
 
-## 一、背景
+# `/autofix-pr` 命令实现规格文档
 
-### 1.1 问题
+## 概述
+
+`/autofix-pr` 命令用于自动修复 PR 上的 CI 失败。本文档是完整的实现规格，基于 claude.exe 反编译和仓库现有基础设施盘点。
+
+> [!info]
+> **状态**：规划阶段（2026-04-29），等待评审通过后进入实施。
+> **架构**：R（Remote-via-CCR），完整版（含 stop 子命令、单例锁、subscribePR、in-process teammate、skills 探测）。
+
+## 正文
+
+### 背景
+
+#### 问题
 
 本仓库（`Claude-code-bast`）是 Anthropic 官方 `@anthropic-ai/claude-code` 的反编译/重构版本。许多远程能力被 stub 化处理 —— `/autofix-pr` 是其中之一：
 
-```js
+```javascript
 // src/commands/autofix-pr/index.js（当前 stub）
 export default { isEnabled: () => false, isHidden: true, name: 'stub' };
 ```
@@ -25,11 +34,11 @@ export default { isEnabled: () => false, isHidden: true, name: 'stub' };
 | `isHidden` | `true` | 即使被列出也被过滤 |
 | `name` | `'stub'` | 实际注册名是 `'stub'`，输入 `/autofix-pr` 无法匹配 |
 
-### 1.2 用户场景
+#### 用户场景
 
 用户在 fork 仓库（`feat/autonomy-lifecycle-upstream` 分支）尝试对上游 `claude-code-best/claude-code#386` 跑 `/autofix-pr 386`，多次报 `git_repository source setup error`。根因：官方派发的远程 session 落在被 MCP 拒绝访问的仓库（`amdosion/claude-code-bast`），权限/可见性问题。
 
-### 1.3 目标
+#### 目标
 
 | ID | 需求 | 验收 |
 |---|---|---|
@@ -42,15 +51,13 @@ export default { isEnabled: () => false, isHidden: true, name: 'stub' };
 | R7 | 支持 stop/off 子命令 | `/autofix-pr stop` 能终止当前监控 |
 | R8 | 单例锁防止重复派发 | 已监控 PR 时拒绝新启动并提示 |
 
----
+### 反编译调研结论
 
-## 二、反编译调研结论（来源：`C:\Users\12180\.local\bin\claude.exe`）
+`claude.exe` 是 242MB 的 Bun 原生编译产物（JS 源码 embed 在二进制内）。通过对该文件的字符串提取反推出完整调用链。
 
-`claude.exe` 是 242MB 的 Bun 原生编译产物（JS 源码 embed 在二进制内）。通过对该文件的字符串提取（`grep -aoE`）反推出完整调用链。
+#### 主入口函数结构
 
-### 2.1 主入口函数结构
-
-```js
+```javascript
 async function entry(input, q, ctx) {
   const isStop = input === "stop" || input === "off"
   const args = { freeformPrompt: input }
@@ -68,16 +75,16 @@ async function main(args, q, { signal, onProgress }) {
 }
 ```
 
-### 2.2 `teleportToRemote` 调用签名（黄金证据）
+#### `teleportToRemote` 调用签名（黄金证据）
 
-```ts
+```typescript
 const session = await teleportToRemote({
   initialMessage: C,                       // 给远端的初始消息
-  source: "autofix_pr",                    // ⚠️ 新字段，本仓库 teleport.tsx 没有
+  source: "autofix_pr",                    // 新字段，本仓库 teleport.tsx 没有
   branchName: N,                           // PR 头分支
   reuseOutcomeBranch: N,                   // 与 branchName 同 — 远端 push 回原分支
   title: `Autofix PR: ${owner}/${repo}#${prNumber} (${branch})`,
-  useDefaultEnvironment: true,             // ⚠️ 不用 synthetic env（与 ultrareview 不同）
+  useDefaultEnvironment: true,             // 不用 synthetic env
   signal,
   githubPr: { owner, repo, number },
   cwd: repoPath,
@@ -97,9 +104,9 @@ const session = await teleportToRemote({
 | `source` | 不传 | `"autofix_pr"` |
 | `environmentVariables` | `BUGHUNTER_*` 一堆 | 不传 |
 
-### 2.3 `registerRemoteAgentTask` 调用
+#### `registerRemoteAgentTask` 调用
 
-```ts
+```typescript
 registerRemoteAgentTask({
   remoteTaskType: "autofix-pr",
   session: { id: session.id, title: session.title },
@@ -108,34 +115,24 @@ registerRemoteAgentTask({
 })
 ```
 
-### 2.4 子命令解析
+#### 子命令解析
 
 ```
-/autofix-pr <PR#>                    → 启动监控 + 派 CCR session
-/autofix-pr stop                     → 停止当前监控
-/autofix-pr off                      → 同 stop
-/autofix-pr <freeform-prompt>        → 自由 prompt 模式（无 PR 号）
-/autofix-pr <owner>/<repo>#<n>       → 跨仓库（覆盖 R2 验收）
+/autofix-pr <PR#>                    -> 启动监控 + 派 CCR session
+/autofix-pr stop                     -> 停止当前监控
+/autofix-pr off                      -> 同 stop
+/autofix-pr <freeform-prompt>        -> 自由 prompt 模式（无 PR 号）
+/autofix-pr <owner>/<repo>#<n>       -> 跨仓库
 ```
 
-### 2.5 状态模型
+#### 状态模型
 
-- **单例锁**：同一时刻只能监控一个 PR。重复启动报：`already monitoring ${repo}#${prNumber}. Run /autofix-pr stop first.`（error_code: `rc_already_monitoring_other`）
-- **PR 订阅**：调 `kairos.subscribePR(owner, repo, taskId)` —— 依赖 `KAIROS_GITHUB_WEBHOOKS` feature flag（用户已订阅，可用）
+- **单例锁**：同一时刻只能监控一个 PR。重复启动报：`already monitoring ${repo}#${prNumber}. Run /autofix-pr stop first.`
+- **PR 订阅**：调 `kairos.subscribePR(owner, repo, taskId)` —— 依赖 `KAIROS_GITHUB_WEBHOOKS` feature flag
 - **in-process teammate**：注册后台 agent
-  ```ts
-  const teammate = {
-    agentId,
-    agentName: "autofix-pr",
-    teamName: "_autofix",
-    color: undefined,
-    planModeRequired: false,
-    parentSessionId,
-  }
-  ```
-- **Skills 探测**：扫项目里 autofix-related skills（如 `.claude/skills/autofix-*` 或根目录 `AUTOFIX.md`），命中后拼到 prompt：`Run X and Y for custom instructions on how to autofix.`
+- **Skills 探测**：扫项目里 autofix-related skills，命中后拼到 prompt
 
-### 2.6 Telemetry
+#### Telemetry
 
 | 事件 | 字段 |
 |---|---|
@@ -152,27 +149,7 @@ registerRemoteAgentTask({
 | `session_create_failed` | teleport 失败 |
 | `exception` | 未捕获异常 |
 
-### 2.7 错误返回结构
-
-```ts
-function errorResult(message: string, code: string) {
-  d("tengu_autofix_pr_result", { result: "failed", error_code: code })
-  return {
-    kind: "error",
-    message: `Autofix PR failed: ${message}`,
-    code,
-  }
-}
-
-function cancelledResult() {
-  d("tengu_autofix_pr_result", { result: "cancelled" })
-  return { kind: "cancelled" }
-}
-```
-
----
-
-## 三、本仓库现有基础设施盘点
+### 本仓库现有基础设施盘点
 
 下表列出实现 `/autofix-pr` 时**直接复用**的现成能力（已确认完整可用）：
 
@@ -188,9 +165,9 @@ function cancelledResult() {
 | `RemoteSessionProgress` | `src/components/tasks/RemoteSessionProgress.tsx` | 进度面板 UI（已认 autofix-pr 类型） |
 | `detectCurrentRepositoryWithHost` | `src/utils/detectRepository.ts` | 解析 owner/repo |
 | `getDefaultBranch` / `gitExe` | `src/utils/git.ts` | git 工具 |
-| `feature('FLAG')` | `bun:bundle` | feature flag 系统（CLAUDE.md 红线：只能在 if/三元条件位置直接调用） |
+| `feature('FLAG')` | `bun:bundle` | feature flag 系统 |
 
-### 模板答案文件
+#### 模板答案文件
 
 以下三个文件已确认完整工作，是本次实现的"参考答案"：
 
@@ -198,11 +175,9 @@ function cancelledResult() {
 - `src/commands/ultraplan.tsx`（525 行）
 - `src/commands/review/ultrareviewCommand.tsx`（89 行）
 
----
+### 命令对象规格
 
-## 四、命令对象规格
-
-### 4.1 `Command` 类型选择
+#### `Command` 类型选择
 
 `Command` 类型定义在 `src/types/command.ts`，三态之一：`PromptCommand` / `LocalCommand` / `LocalJSXCommand`。
 
@@ -211,9 +186,9 @@ function cancelledResult() {
 - 兄弟命令 `ultraplan` / `ultrareview` 都用 local-jsx
 - 接口签名：`call(onDone, context, args) => Promise<React.ReactNode>`
 
-### 4.2 `index.ts` 完整形状
+#### `index.ts` 完整形状
 
-```ts
+```typescript
 import { feature } from 'bun:bundle'
 import type { Command } from '../../types/command.js'
 
@@ -242,19 +217,17 @@ const autofixPr: Command = {
 export default autofixPr
 ```
 
-### 4.3 参数解析规则
+#### 参数解析规则
 
 ```
-^stop$ | ^off$            → { action: 'stop' }
-^\d+$                     → { action: 'start', prNumber, owner: <git>, repo: <git> }
-^([\w.-]+)/([\w.-]+)#(\d+)$ → { action: 'start', prNumber, owner, repo }
-其他                       → { action: 'start', freeformPrompt: <input> }
-空字符串                   → 错误
+^stop$ | ^off$            -> { action: 'stop' }
+^\d+$                     -> { action: 'start', prNumber, owner: <git>, repo: <git> }
+^([\w.-]+)/([\w.-]+)#(\d+)$ -> { action: 'start', prNumber, owner, repo }
+其他                       -> { action: 'start', freeformPrompt: <input> }
+空字符串                   -> 错误
 ```
 
----
-
-## 五、文件结构
+### 文件结构
 
 ```
 src/commands/autofix-pr/
@@ -279,13 +252,11 @@ src/commands/autofix-pr/
 - `src/utils/teleport.tsx` —— `teleportToRemote` 选项加 `source?: string` 字段并透传
 - `src/commands.ts` —— **不动**（import 路径 `'./commands/autofix-pr/index.js'` 在 ESM/Bun 下会自动解析到 `.ts`）
 
----
+### 模块详细规格
 
-## 六、模块详细规格
+#### `parseArgs.ts`
 
-### 6.1 `parseArgs.ts`
-
-```ts
+```typescript
 export type ParsedArgs =
   | { action: 'stop' }
   | { action: 'start'; prNumber: number; owner?: string; repo?: string }
@@ -312,9 +283,9 @@ export function parseAutofixArgs(raw: string): ParsedArgs {
 }
 ```
 
-### 6.2 `monitorState.ts`
+#### `monitorState.ts`
 
-```ts
+```typescript
 import type { UUID } from 'crypto'
 
 type MonitorState = {
@@ -349,11 +320,11 @@ export function isMonitoring(owner: string, repo: string, prNumber: number): boo
 }
 ```
 
-### 6.3 `inProcessAgent.ts`
+#### `inProcessAgent.ts`
 
 仿官方 `xd9` 函数：
 
-```ts
+```typescript
 import { randomUUID, type UUID } from 'crypto'
 import { getCurrentSessionId } from '../../bootstrap/state.js'
 
@@ -385,9 +356,9 @@ export function createAutofixTeammate(
 }
 ```
 
-### 6.4 `skillDetect.ts`
+#### `skillDetect.ts`
 
-```ts
+```typescript
 import { existsSync } from 'fs'
 import { join } from 'path'
 
@@ -406,11 +377,11 @@ export function formatSkillsHint(skills: string[]): string {
 }
 ```
 
-### 6.5 `launchAutofixPr.ts`
+#### `launchAutofixPr.ts`
 
 主流程伪代码（约 250 行）：
 
-```ts
+```typescript
 import type { LocalJSXCommandCall } from '../../types/command.js'
 import { parseAutofixArgs } from './parseArgs.js'
 import { getActiveMonitor, setActiveMonitor, clearActiveMonitor, isMonitoring } from './monitorState.js'
@@ -553,39 +524,16 @@ function errorResult(message: string, code: string) {
 }
 ```
 
-> **注意**：`feature('KAIROS_GITHUB_WEBHOOKS')` 必须直接放在 if 条件位置，不能赋值给变量（CLAUDE.md 红线）。
+> [!warning]
+> `feature('KAIROS_GITHUB_WEBHOOKS')` 必须直接放在 if 条件位置，不能赋值给变量（CLAUDE.md 红线）。
 
-### 6.6 `teleport.tsx` 补 `source` 字段
+### Feature Flag
 
-```diff
- export async function teleportToRemote(options: {
-   initialMessage: string | null
-   branchName?: string
-   title?: string
-   description?: string
-+  /**
-+   * Identifies which command/flow originated this teleport. CCR backend
-+   * uses this for routing/billing/observability. Known values: 'autofix_pr',
-+   * 'ultrareview', 'ultraplan'. Pass-through field — not interpreted client-side.
-+   */
-+  source?: string
-   model?: string
-   permissionMode?: PermissionMode
-   // ...
- })
-```
-
-并在内部构造 request 时透传到 session_context（具体字段名按现有 review/ultraplan 调用结构对齐）。
-
----
-
-## 七、Feature Flag
-
-### 7.1 新增 flag
+#### 新增 flag
 
 `scripts/defines.ts` 已有的 flag 集合中加 `AUTOFIX_PR`。
 
-### 7.2 启用矩阵
+#### 启用矩阵
 
 | 环境 | 是否默认开启 | 说明 |
 |---|---|---|
@@ -593,18 +541,9 @@ function errorResult(message: string, code: string) {
 | build (production `bun run build`) | 否 | 灰度上线，需要 `FEATURE_AUTOFIX_PR=1` 显式开启 |
 | 测试 | 按需 | 测试文件通过 mock `bun:bundle` 控制 |
 
-### 7.3 与官方上游同步策略
+### 测试计划
 
-如果上游某天恢复官方实现，本仓库的本地实现优先（项目即 fork）：
-1. 保留 `AUTOFIX_PR` flag 名
-2. 保留 `RemoteTaskType` 字段不动
-3. 冲突时合并：吸收上游的 `source` 字段值变更、env var 变更，保留我们的本地 launcher 函数
-
----
-
-## 八、测试计划
-
-### 8.1 测试文件
+#### 测试文件
 
 | 文件 | 覆盖目标 | 测试用例数 |
 |---|---|---|
@@ -613,11 +552,11 @@ function errorResult(message: string, code: string) {
 | `launchAutofixPr.test.ts` | 主流程 happy path + 失败路径 | ~12 |
 | `index.test.ts` | bridge invocation error 校验 | ~5 |
 
-### 8.2 关键断言
+#### 关键断言
 
 `launchAutofixPr.test.ts`：
 
-```ts
+```typescript
 test('start with PR number teleports with correct args', async () => {
   // mock teleportToRemote, registerRemoteAgentTask, detectCurrentRepositoryWithHost
   await callAutofixPr(onDone, context, '386')
@@ -653,25 +592,7 @@ test('stop clears active monitor', async () => {
 })
 ```
 
-### 8.3 Mock 策略
-
-按本仓库 `tests/mocks/` 共享 mock 习惯：
-- `tests/mocks/log.ts` 和 `tests/mocks/debug.ts` —— 必 mock
-- `bun:bundle` —— mock `feature` 返回 `true`
-- `teleportToRemote` —— 模块级 mock，断言入参
-- `registerRemoteAgentTask` —— 模块级 mock，断言入参
-- `detectCurrentRepositoryWithHost` —— mock 返回 `{ owner, name, host }`
-
-### 8.4 类型检查
-
-```bash
-bun run typecheck      # 必须零错误
-bun run test:all       # 必须全绿
-```
-
----
-
-## 九、实施步骤（11 步清单）
+### 实施步骤（11 步清单）
 
 ```
 [ ] Step 1   scripts/defines.ts + scripts/dev.ts 加 AUTOFIX_PR flag
@@ -683,46 +604,31 @@ bun run test:all       # 必须全绿
 [ ] Step 6   新建 src/commands/autofix-pr/inProcessAgent.ts（约 60 行）
 [ ] Step 7   新建 src/commands/autofix-pr/skillDetect.ts（约 30 行）
 [ ] Step 8   新建 src/commands/autofix-pr/launchAutofixPr.ts（约 250 行）
-             照抄 reviewRemote.ts，按 §2.2 差异表改造
+             照抄 reviewRemote.ts，按差异表改造
 [ ] Step 9   新建四份测试文件（约 150 行）
 [ ] Step 10  bun run typecheck && bun run test:all 全绿
 [ ] Step 11  dev 模式手测：
-              a. /autofix-pr 386 → 期望出现 RemoteSessionProgress 面板
-              b. /autofix-pr stop → 期望提示已停止
-              c. /autofix-pr anthropics/claude-code#999 → 期望跨仓库
-              d. 第二次 /autofix-pr 386 → 期望被单例锁拒绝
+              a. /autofix-pr 386 -> 期望出现 RemoteSessionProgress 面板
+              b. /autofix-pr stop -> 期望提示已停止
+              c. /autofix-pr anthropics/claude-code#999 -> 期望跨仓库
+              d. 第二次 /autofix-pr 386 -> 期望被单例锁拒绝
 [ ] Step 12  commit：feat: implement /autofix-pr command (replace stub)
 ```
 
 预计工作量：约 600 行新增代码（含测试 150 行）。
 
----
-
-## 十、风险与回退
+### 风险与回退
 
 | 风险 | 触发场景 | 回退策略 |
 |---|---|---|
-| `source` 字段 CCR 后端不识别 | 后端只认特定枚举 | 不传该字段，看是否能跑通；如不行回头看官方 cli.js 是否传了别的字段 |
-| `subscribePR` API 在本仓库 client 不完整 | KAIROS_GITHUB_WEBHOOKS 客户端代码缺失 | 用 `.catch(() => {})` 容忍失败，订阅是 nice-to-have |
+| `source` 字段 CCR 后端不识别 | 后端只认特定枚举 | 不传该字段，看是否能跑通 |
+| `subscribePR` API 在本仓库 client 不完整 | KAIROS_GITHUB_WEBHOOKS 客户端代码缺失 | 用 `.catch(() => {})` 容忍失败 |
 | 用户账号无 CCR 权限 | `checkRemoteAgentEligibility` 返回 false | 命令降级到错误文案，不破坏会话 |
 | 远端能起 session 但不修代码 | env vars 命名错误 | 看 `getRemoteTaskSessionUrl` 给的会话页容器日志，调整 |
 | PR 在 fork 仓库且 CCR 没访问权 | `git_repository source error` | 命令应在前置检查中识别并提示用户先把 PR 转到主仓 |
 | 上游恢复官方实现导致冲突 | 上游 sync 时 | 项目是 fork，本地实现优先；冲突手工 merge |
 
-### 回退命令
-
-```bash
-# 完全撤回本次实现
-git checkout main
-git worktree remove E:/Source_code/Claude-code-bast-autofix-pr
-git branch -D feat/autofix-pr
-```
-
-`AUTOFIX_PR` flag 默认在 production 关闭，所以即使代码已合入 main，没显式 `FEATURE_AUTOFIX_PR=1` 时不会影响用户。
-
----
-
-## 十一、验收清单
+### 验收清单
 
 实施完成后逐项核对：
 
@@ -735,35 +641,7 @@ git branch -D feat/autofix-pr
 - [ ] R7：`/autofix-pr stop` 终止当前监控
 - [ ] R8：第二次 `/autofix-pr` 不同 PR 时被锁拒绝并提示
 
----
+## 关联笔记
 
-## 十二、附录
-
-### 附录 A：相关文件路径速查
-
-| 路径 | 角色 |
-|---|---|
-| `E:\Source_code\Claude-code-bast-autofix-pr` | 实施 worktree |
-| `C:\Users\12180\.local\bin\claude.exe` | 反编译来源（242MB Bun 编译产物） |
-| `C:\Users\12180\.claude\projects\E--Source-code-Claude-code-bast\memory\project_autofix_pr_implementation.md` | 内存备忘（精简版） |
-| `src/commands/review/reviewRemote.ts` | 主模板 |
-| `src/utils/teleport.tsx:947` | `teleportToRemote` 入口 |
-| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:103` | `REMOTE_TASK_TYPES` |
-| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:526` | `registerRemoteAgentTask` |
-| `src/types/command.ts` | `Command` 类型定义 |
-
-### 附录 B：未决问题
-
-| # | 问题 | 当前处理 | 后续 |
-|---|---|---|---|
-| Q1 | `source` 字段在 CCR backend 是否被解析 | 暂传 `'autofix_pr'`，按官方做法 | 端到端测试时观察远端日志 |
-| Q2 | `subscribePR` 的 client SDK 在本仓库是否完整 | `try/catch` 容忍失败 | Step 11 手测时单独验证 |
-| Q3 | freeform prompt 模式是否实现 | 暂报"not supported" | 第二期再加 |
-
----
-
-## 十三、变更日志
-
-| 日期 | 作者 | 变更 |
-|---|---|---|
-| 2026-04-29 | Claude Opus 4.7 | 初始规格文档创建（基于 claude.exe 反编译 + 仓库现有基础设施盘点） |
+- [[claude-code-best/docs/features/ultraplan]]
+- [[claude-code-best/docs/features/kairos]]