# Plan 6：延期项对齐设计

日期：2026-08-12  
状态：已确认（方案 A）  
父规格：[2026-08-10-host-agent-design.md](./2026-08-10-host-agent-design.md)  
参考 CLI：`/Users/nietao/VSCode-plugins/smart-commit-cli` @ `peerReference.cliVersion`（当前 0.1.21）

## 1. 目标

补齐 Plan 5 明确延期的三项，使 host-agent 对 §4 命令面达到「可宣称对齐 CLI」：

1. `pull-request review` 的 **summary/inline 评论发布** + **approve** + **merge**
2. `my-pull-request batch-review`
3. `report generate`（本地渲染 + AI 段走 turn）

## 2. 非目标（YAGNI）

- 不修改 `smart-commit-cli`
- 不抽共享 npm 包
- host-agent **零** LLM HTTP
- 不在本计划引入 hybrid / chunked review / correction repair（除非写路径强依赖且 CLI 同行为；默认保持现有 single-turn）
- 不为性能并行化 listApi（保持与 CLI 一致）

## 3. 交付顺序

| 切片 | 内容 | 依赖 |
|------|------|------|
| **6.1** | 评论 / approve / merge 写 API + 挂到 `pull-request review` | 现有 `reviewFetch` / `http` / turn review |
| **6.2** | `my-pull-request batch-review` | 6.1 + 现有 list |
| **6.3** | `report generate` | turn `complete`；`passHistory` 配置子集 |

## 4. 切片 6.1 — 平台写操作

### 4.1 从 CLI 移植的模块（对照路径）

| CLI | host-agent 目标 |
|-----|-----------------|
| `src/pullRequest/reviewApi.ts` 写操作 + `getCurrentUser` / list comments | `src/pullRequest/reviewActions.ts`（或扩展现有 `reviewFetch.ts`，优先**新文件**避免与 fetch 混杂） |
| `src/pullRequest/reviewComment.ts` | `src/pullRequest/reviewComment.ts` |
| `src/pullRequest/reviewGate.ts` | `src/pullRequest/reviewGate.ts` |
| `src/pullRequest/mergeGate.ts` | `src/pullRequest/mergeGate.ts` |
| `src/pullRequest/reviewWorkflow.ts` 发布段 | 抽成 `applyPullRequestReviewActions`（host-agent 内），由 `pullRequestReview.ts` 在 turn 审查成功后调用 |

HTTP 一律走现有 `src/pullRequest/http.ts`（`requestJson` / headers / encode helpers）。

### 4.2 配置补齐

扩展 `pullRequestReview`（对齐 CLI 默认值）：

- 已有：`threshold`、`autoApprove`、`autoMerge`
- 新增：`summarySeverities`、`commentSeverities`、`skipSummaryOnPass`、`skipCommentOnPass`
- 可不移植：`configFilePath`、`skillPromptTuning`（host-agent 无 CLI skill 文件路径语义）

### 4.3 行为

审查 turn 得到 `passed`/`blocked` 后（非 `needs_host_agent`）：

1. 按 `reviewGate` 决定是否发 summary / inline
2. dry-run：不 POST；action 字段语义对齐 CLI dry-run
3. `autoApprove` / `autoMerge` + `mergeGate`：对齐 CLI（含已批准跳过、draft 限制等）
4. 输出字段：`summaryCommentAction`、`inlineCommentAction`、`inlinePosted/Skipped/Failed/Unanchored`、`approve`、`merge` 不再写死 deferred skipped

### 4.4 测试

- mocked `fetch`：GitHub/GitLab 各至少一条 summary create、approve；inline 与 merge 至少覆盖主路径
- 现有 review e2e：去掉「永远 skipped」断言，改为 dry-run 或 mock 写成功

## 5. 切片 6.2 — batch-review

### 5.1 移植

| CLI | host-agent |
|-----|------------|
| `batchReviewKinds` 配置 | `myPullRequest.batchReviewKinds`（默认 `["reviewer","assigned"]`） |
| `serialReviewOrchestrator.ts` | `src/pullRequest/serialReviewOrchestrator.ts` |
| `batchReviewSummary.ts` | `src/pullRequest/batchReviewSummary.ts` |
| `commands/myPullRequestBatchReview.ts` | `src/commands/myPullRequestBatchReview.ts` |

### 5.2 Host-agent 差异（唯一允许差异）

- 单条审查不注入 OpenAI `ReviewProvider`，改为可注入的 `reviewOne`：内部走与 `pull-request review` 相同的 turn + 平台 actions 路径
- 若中途 `NeedsHostAgentError`：整命令以 `needs_host_agent` 退出并带 session（与 bridge 多 turn 续跑一致）；或文档约定 batch 在单条续跑——**选定：对齐「单条 review 命令」契约，batch 内遇到 needs_host_agent 则向上抛出/转为该 status，由 skill 写 response 后带 `--session` 续跑同一 batch**（实现计划里写清状态落盘字段）

### 5.3 其它

- account + `remoteHost` 跳过 git（与 list 一致）
- CLI 接线：`my-pull-request batch-review`、schema target、help、parity-matrix、README

## 6. 切片 6.3 — report generate

### 6.1 移植范围

- `src/commands/report.ts` → `src/commands/reportGenerate.ts`
- `src/reporting/*` 本地聚合/渲染必需子集
- `passHistory` 配置子集（enabled / writeStage / outputDirPath / maxEntries），无 LLM connection

### 6.2 AI 段

- CLI `generateAiWorkReport` → host-agent `HostAgentClient.complete`，`purpose: "report"`
- 无 response → `needs_host_agent`；失败可 fallback local（若 CLI 有同等语义则对齐）

### 6.3 测试

- 本地 render 无网络
- AI 路径：fixture turn → 写出报告文件

## 7. 成功标准

1. §4 表中原「未跟进 / 延期」三项在 parity-matrix 标为对齐或部分对齐（注明与 CLI 已知差异，如无 chunked）
2. `npm test` 全绿；CI 无真实网络
3. 零 LLM HTTP；零改 CLI
4. README 以产品能力描述，不引入 Plan 编号叙事

## 8. 开放细节（实现计划锁定）

- batch-review 的 session/续跑状态机精确字段
- `reviewActions` 是新文件还是合并进 `reviewFetch`（规格倾向新文件）
- report 是否需要完整 passHistory 写入桥接（若 CLI report 只读 history，则只读移植）