---
description: 按 KB manifest 与 summary 白名单提交归档变更并推送到远程
argument-hint: "[commit 说明]"
---

> Pi 包 `@suwenguang/pi-kb`：运行时包根为环境变量 `PI_KB_ROOT`（由 `extensions/kb-root.ts` 注入）。
> 工种子 Agent 通过 **pi-subagents** 派发（已 bundled）；agent 定义见本包 `agents/`。
> 脚本调用示例：`node "$PI_KB_ROOT/scripts/<name>.mjs"`。

## 用户输入

${@:-（未附带参数；结合当前对话上下文执行，缺信息时向用户澄清。）}

---
按 KB 变更白名单提交知识库与业务代码，**commit 成功后默认 `git push`**。

**与 `/kb-archive` 的关系**：`/kb-archive` 步骤 9 与本命令共用同一套白名单 commit+push 规则；本命令用于 **archive 中断恢复**（已归档但未推送）或用户**单独补提交**。

**输入**: 可选 -- 变更名称（**必须为中文**，对应 `knowledge/变更/进行中/` 或 `knowledge/变更/归档/` 下的目录）。

## 子 Agent 编排（必遵）

- 主 Agent 只审核提交范围、提交信息和推送意图；暂存、提交、推送等会改变 git 状态的操作均由子 Agent 执行。

## Bootstrap 门禁（硬阻断）

本命令要求业务仓已完成 KB 初始化（`/kb-init` / `kb-bootstrap`）。开始前**必须**先跑机器门禁；失败则**立即停止**，禁止继续（含禁止用 `mkdir -p knowledge/...` 绕过建目录）。执行：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`

未通过时按脚本输出指引执行 `/kb-init`，或：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap.mjs" --target "$(pwd)"`

## 约束

- **变更名称必须为中文**，如"红包功能"、"设备守卫-用户模糊搜索"
- 禁止使用 kebab-case、camelCase 或英文命名
- 目录格式：`<YYYYMMDDHHMMSS>-<中文名称>`
- 已归档变更位于 `knowledge/变更/归档/<YYYYMMDDHHMMSS>-<中文名称>/`

## 执行步骤

### 1. 检查变更状态

```bash
# 查看所有变更
git status --short
git diff --stat
```

如果指定了 KB 变更名称，先读取对应目录的 `00-manifest.json`：
- `stage = "archived"`：可按正常流程提交。
- `stage = "archived_with_debt"`：可提交，但提交报告必须摘要说明已接受的遗留债务。
- 其他阶段或缺失 manifest：默认停止提交，除非用户明确要求只提交与该 KB 变更无关的文件。

提交前先按 `/kb-check <中文名称>` 的只读口径确认无阻断项；若存在 `open` 评审、未覆盖知识库影响清单、局部 index/总索引缺失或可疑敏感新增文件，停止提交并报告。

### 2. 构建提交白名单

指定变更名称时，必须从三部分合成暂存白名单：

1. `00-manifest.json` 的 `files[].path`。
2. `05-summary.md` 的「实际变更」与「知识库影响清单」列出的文件，包括必要的领域 index、业务域子目录 index、工程平台根 index、工程平台分区 index 和总索引。
3. 命中的变更目录文件：`knowledge/变更/进行中/*-<中文名称>/` 或 `knowledge/变更/归档/*-<中文名称>/` 下的 `00`～`07`。

白名单规则：
- 三部分不一致时停止提交，先运行 `/kb-check <中文名称>`；只存在状态/清单漂移时用 `/kb-repair <中文名称>` 修复。
- 工作区存在未归属改动时停止提交并让用户确认，不能默认纳入。
- 不允许用 `git add .`、`git add -A`、`git add *` 或“当前全部改动”作为默认实现。
- 如用户明确要求提交额外文件，必须把这些文件逐路径列入本次白名单，并在提交报告中说明。

### 3. 暂存文件

由子 Agent 按“先白名单、后确认”的方式暂存，避免把无关改动一并提交：

```bash
# 1) 查看候选改动
git status --short

# 2) 按白名单逐文件暂存（示例）
# git add "knowledge/业务域/礼物/0X-<子模块>.md" "knowledge/index.md" "vkk_client_flutter/lib/xxx.dart"

# 3) 再次确认暂存范围
git diff --cached --name-only
```

禁止直接 `git add quasar/ rust_server/ lib/ vkk_client_flutter/ doger_proto/` 这类目录级全量暂存。即使用户说“提交当前全部改动”，也必须先列出未归属改动并二次确认是否全部纳入。

### 4. 生成提交信息

根据暂存内容自动生成 Conventional Commits 格式的提交信息。

**变更目录 + 知识库更新 + 业务代码**：
```
docs(kb): 归档 <中文名称> 变更，更新知识库与业务代码
```

**仅知识库同步**（/kb-sync 产出）：
```
docs(kb): 同步知识库，更新 <业务域或工程平台范围>
```

**仅索引重建**（/kb-index 产出）：
```
docs(kb): 维护两级 OKF index
```

**工作流配置**：
```
chore(cursor): 更新知识库工作流配置
```

**仅业务代码**：
根据实际变更内容生成合适的 fix/feat/refactor 提交信息。

遵循项目的 Conventional Commits 规范，提交信息主题使用中文。

### 5. 执行提交

由子 Agent 执行提交：

```bash
git commit -m "<生成的提交信息>"
```

### 6. 推送到远程（默认执行）

提交成功后，由子 Agent **默认**推送到远程：

```bash
git push
```

仅当用户**明确指令「不推送」**时跳过本步，并在提交报告中注明。

**失败处理**：push 失败时报告远端/分支/权限原因；勿 `--force` 强推共享分支，除非用户明确要求。

### 7. 输出报告

```
## 提交报告

| 项目 | 内容 |
|------|------|
| 提交信息 | ... |
| 暂存文件 | X 个文件 |
| Git 推送 | 已推送 / 已跳过（用户指令） / 失败待重试 |
| 白名单来源 | manifest.files / 05-summary / 变更目录 |
| 未归属改动 | 无 / 已停止等待确认 |
| 变更统计 | +XX / -XX 行 |
```

## 注意事项

- 只提交白名单内文件；未归属改动必须停止确认
- 提交前确认 `.cursor/` 等本地工具配置若被误纳入暂存，不含令牌与私钥路径