# smart-commit-host-agent 设计规格

日期：2026-08-10  
状态：已评审（brainstorming）  
关联：`smart-commit-cli`（只读参考，本仓不修改、不抽共享模块）  
消费方：`bugfix-gitlab-mr-qax` skill（及后续基于 host-agent 拓展的 skill）

## 1. 背景与目标

### 问题

`bugfix-gitlab-mr-qax` 依赖 `smart-commit-cli`。CLI 的审查、提交信息、MR 文案等步骤需要 `connection.*`（baseUrl / apiKey / model）与 API Key。该 skill 主要在 Cursor、Codex 等 **已具备 LLM 能力的 Host Agent** 中运行，再单独配置一套 LLM 增加摩擦。

现有 CLI 的 `cursorAgent` provider 是调用 Cursor Agent **HTTP API**（仍需 apiKey），**不是**复用当前会话里的 Host Agent。

### 目标

1. 新建独立 npm 包 **`smart-commit-host-agent`**，作为 skill 的 **唯一** 任务流入口。
2. **不依赖** LLM `connection` 配置；「脑力」一律由运行 skill 的 Host Agent 通过 turn 协议回填。
3. **`smart-commit-cli` 仓库零改动**，且 **不抽共享模块**；host-agent 对照 CLI **独立移植** 逻辑。
4. 能力范围不是 skill 现用子集，而是 **CLI 用户命令的全量对等**，并建立可持续跟进 CLI 发版的纪律。
5. 使用自配 LLM 的场景继续直接使用 `smart-commit-cli`；与 skill / host-agent 路径 **分流**，互不污染。

### 非目标

- 不修改 `smart-commit-cli` 源码或发布流程。
- 不在两仓之间抽取公共 npm 包或共享 git submodule。
- 不在 host-agent 内再实现「读 connection 调 OpenAI/Anthropic/Cursor API」的双模运输层。
- skill 路径不回退调用 `smart-commit-cli`。

## 2. 决策摘要

| 决策项 | 选择 |
|--------|------|
| 与 CLI 关系 | 独立包 C：主 CLI 不动、不抽共享 |
| Host 交互 | Turn-based session（写 request → Agent 写 response → `--session` 续跑） |
| Skill 入口 | 始终调用 `smart-commit-host-agent`，默认即 host-agent |
| LLM 配置 | skill / host-agent **禁止依赖**；平台 token 等仍要 |
| 能力范围 | 对齐 CLI **全量** 用户命令，非仅 skill 现用三条 |
| 跟进方式 | 能力矩阵 + `peerReference.cliVersion` + CHANGELOG 对账 |

## 3. 总体架构

```text
bugfix-gitlab-mr-qax (Skill)
  → always: npx/smart-commit-host-agent <command>
       → 需要生成时: status=needs_host_agent + turn request 落盘
       → Host Agent 用自身 LLM 写 turn response
       → --session <path> 续跑
       → 本地完成校验、git、GitLab/GitHub API
  → 摘要 JSON（字段尽量对齐现 skill / CLI 契约）

smart-commit-cli
  → 独立产品线：必须配置 LLM；本设计不改动
```

### 硬边界

1. 不修改 `smart-commit-cli`；不抽共享模块。  
2. skill **不再**配置或探测 `SMART_COMMIT_API_KEY`、`connection.baseUrl/apiKey/model`。  
3. host-agent **从不**自行调用外部 LLM HTTP API。  
4. Prompt / 校验 / 评分 / 编排在 host-agent **独立实现**，以 CLI 为行为参考；漂移通过矩阵显式管理。  
5. 后续 skill 能力拓展：先在 host-agent 具备并对齐矩阵，再改 skill。

## 4. 命令面（全量对等）

对照 `smart-commit-cli` 当前用户命令，host-agent 首版应对齐：

| CLI 命令 | host-agent | 与 CLI 的差异 |
|----------|------------|----------------|
| `config resolve` | 有 | **不**校验 LLM `connection` |
| `bridge`（含 `--review-only`） | 有 | 生成步骤 → turn |
| `commit-message generate` | 有 | 同上 |
| `report generate` | 有 | AI 段 → turn；无 AI 可本地 |
| `pull-request create` | 有 | 标题/描述 → turn |
| `pull-request review` | 有 | 审查 → turn |
| `my-pull-request list` | 有 | 通常无 LLM，行为对齐 |
| `my-pull-request batch-review` | 有 | 审查 → turn |
| `schema print` / help / version | 有 | schema **不含** LLM connection 必填 |

CLI 的 `--base-url` / `--api-key` / `--model` / `--llm-provider` 在 host-agent **不提供**（若误传，明确报错：本工具不使用 LLM 配置）。

对外 JSON 尽量保持 skill / 自动化已依赖的字段，例如：`status`、`phase`、`score`、`threshold`、`reviewDecision`、`reviewSummary`、`reviewDetails`、`commitMessage`、`commitMessageSource`、`didCommit`、`didPush`、`pullRequestCreation`、`error.code` / `error.message` 等。

## 5. Turn 协议

### 会话布局

```text
<sessionDir>/
  session.json           # 元数据：命令、repo、创建时间、cliReferenceVersion
  turns/
    0001.request.json    # host-agent 写出
    0001.response.json   # Host Agent 写出
    0002.request.json    # 校验失败时的 repair turn
    …
```

Session 目录由 host-agent 创建（系统临时目录或仓库下 `.smart-commit-host-agent/sessions/<id>`），流程结束后可清理。

### request.json（host-agent → Agent）

| 字段 | 含义 |
|------|------|
| `turnId` | 如 `0001` |
| `kind` | `complete` \| `review`（语义对齐 CLI `LlmClient`） |
| `purpose` | 业务用途：`code-review` / `commit-message` / `pr-title` / `pr-description` / `report` / … |
| `messages` | `[{ role, content }]`，对照 CLI 侧 prompt 构造 |
| `responseSchema` | 期望输出说明（纯文本或 JSON 形状）；与上游校验一致 |
| `attempt` | correction 轮次（从 0 起） |

### response.json（Agent → host-agent）

| 字段 | 含义 |
|------|------|
| `turnId` | 必须与 request 一致 |
| `content` | 模型原文 string；由 host-agent 按现有 CLI 同等规则解析/校验 |

### 运行循环

1. host-agent 写 `NNNN.request.json`。  
2. 以 `status: "needs_host_agent"` 退出；stdout JSON 含 `sessionPath`、`requestPath`、`turnId`、`purpose`。  
3. Skill/Agent 读 request → 用 Host Agent 能力生成 → 写 `NNNN.response.json`。  
4. 再执行同一命令并带 `--session <sessionPath>`。  
5. 读到匹配 response 后继续；校验失败则按 CLI 同等 correction 语义发下一 turn。  
6. 全部生成步骤完成后，执行 git / 平台 API，输出终态 JSON。

## 6. Skill 约定（`bugfix-gitlab-mr-qax`）

### 调用

- **禁止** 再调用 `smart-commit-cli` / `smart-commit-copilot-cli`。  
- **始终** 调用 `smart-commit-host-agent`（全局或 `npx --yes smart-commit-host-agent`）。  
- 固定循环：

```text
loop:
  run host-agent <cmd> [--session …] --output json
  if needs_host_agent → 填 response → continue
  if passed | blocked | error | created | existing → 跳出，写摘要
```

### 配置

- colocated 配置（如 `smart-commit.qax-gitlab.json`）**删除** `connection` LLM 段。  
- 保留：`review.*`、`commitMessage.validation.*`、`git.*`、`pullRequest.*`、`pullRequestCreation.*`、`pullRequestReview.*`、`output.*` 等非 LLM 项。  
- 环境探测：**去掉** `SMART_COMMIT_API_KEY`；**保留** `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN`（或配置 `env:` 引用）、Node ≥ 20、host-agent 可用、`config resolve`。

### 模式路由

现有三种模式语义不变，仅后端从 CLI 换为 host-agent：

- 本地 Code Review → `bridge --review-only`  
- 提 MR → `bridge` / `pull-request create`（断点续建）  
- 审查 MR → `pull-request review <url>`  

全流程禁止改业务源码、禁止擅自切分支等 skill 约束保持不变。

## 7. 错误处理与退出码

| 情况 | `status` / 建议退出码 | Skill 行为 |
|------|------------------------|------------|
| 等待 Host Agent 回填 | `needs_host_agent` / `10` | 填 response 后 `--session` 续跑 |
| 审查未通过 | `blocked` + `REVIEW_BLOCKED` / `2` | 终止；不改代码、不建 MR |
| 配置错误 | `error` + `CONFIG_ERROR` / `3` | 整 skill 跳过 |
| 运行时失败 | `error` + `RUNTIME_ERROR` / `4` | 按现 skill 多仓规则跳过或终止 |
| 成功 | `passed` / `created` / `existing` / `0` | 写摘要 |

补充：

- Turn 超时、response 缺失、`turnId` 不匹配 → 失败，**禁止**静默改调 `smart-commit-cli`。  
- 摘要与日志 **禁止** 泄露 token（含脱敏展示）。

## 8. 与 CLI 持续跟进（无共享模块）

### 能力矩阵

在 host-agent 仓库维护矩阵文档（建议 `docs/parity-matrix.md`）：

- 行：CLI 命令 / 关键 flag / JSON 字段 / 行为备注  
- 列：host-agent 状态（已对齐 / 部分 / 未跟进）、对应 CLI 版本、备注  

### 版本锚定

- `package.json` 或 README 中声明 `peerReference.cliVersion`（例如对齐 `smart-commit-copilot-cli@x.y.z`）。  
- 每个 host-agent release notes 写明「对齐 CLI @ x.y.z」。  

### 变更对账

1. CLI 发版后，按其 CHANGELOG 更新矩阵。  
2. 凡原 LLM 调用点 → host-agent 改为 turn。  
3. 非 LLM（git / GitHub / GitLab API）对照移植。  
4. 允许短暂落后一个小版本，但矩阵必须标红未跟进项。  

### Skill 拓展

新能力先落在 host-agent 并更新矩阵，再改 skill；skill 仍只调 host-agent。

## 9. 配置与密钥

| 项 | host-agent / skill |
|----|-------------------|
| `connection.baseUrl` / `apiKey` / `model` / `llmProvider` | **不使用** |
| `SMART_COMMIT_API_KEY` | **不要求** |
| `pullRequest.authToken` / `SMART_COMMIT_PULL_REQUEST_AUTH_TOKEN` | **仍要求**（平台操作） |
| review 阈值、语言、git 自动 stage/commit/push、MR assignees/labels 等 | 保留，语义对齐 CLI |

`config resolve`：合并配置并校验 **非 LLM** 必填项；缺平台 token 等仍 `CONFIG_ERROR`。

## 10. 测试策略

1. **单元**：turn 读写、无 connection 的 config、correction 轮次。  
2. **相位集成**：用 fixture `response.json` 跑通 `bridge` / `pull-request review` 等（不调真模型）。  
3. **契约**：关键 JSON 字段名与 status 枚举与 CLI / skill 期望对齐（可由矩阵驱动）。  
4. **不对** `smart-commit-cli` 仓库引入本设计相关改动或测试负担。  

## 11. 迁移计划

1. 本仓库落地实现：对照当前 CLI 能力移植；所有 LLM 点改为 turn。  
2. 建立 `peerReference.cliVersion` 与能力矩阵。  
3. 修改 `bugfix-gitlab-mr-qax`：入口改为 host-agent；删除 LLM 配置与 API Key 探测；加入 `needs_host_agent` 循环；更新 `SETUP.md`。  
4. 在 Cursor / Codex 验证三种 skill 模式零 LLM 配置可用。  
5. 文档声明：自配 LLM 用户继续使用 `smart-commit-cli`；本 skill 仅搭配 host-agent。  

## 12. 仓库与文档落点

- 实现与规格均在 **`smart-commit-host-agent`** 仓（本文路径：`docs/superpowers/specs/2026-08-10-host-agent-design.md`）。  
- **`smart-commit-cli` 仓无代码变更。**  
- skill 仓（`bugfix-gitlab-mr-qax`）在实现阶段再改。  

## 13. 开放实现细节（实现计划阶段细化）

以下不阻塞本规格，留给 writing-plans / 实现时确定：

- session 目录默认路径与清理策略的确切规则  
- `needs_host_agent` 最终退出码是否固定为 `10`  
- npm 包名是否即为 `smart-commit-host-agent`（若注册冲突再定）  
- GitHub vs GitLab API 客户端是从 CLI 逻辑对照手写还是精简重写  
- 与 CLI 字段 100% 兼容的自动化契约测试粒度  

## 14. 成功标准

1. 在 Cursor/Codex 中安装更新后的 skill 后，**无需** LLM `connection` / `SMART_COMMIT_API_KEY` 即可完成本地 review、提 MR、审查 MR（仍需平台 token）。  
2. `smart-commit-cli` 行为与发布物未被本工作改变。  
3. host-agent 命令面覆盖 §4 列表；矩阵可追踪与 CLI 的差距。  
4. Host Agent 交互仅通过 turn 文件 + 进程退出/续跑，在非交互 Agent shell 下稳定可脚本化。