---
description: 轻量 KB 变更流程，适用于低风险小改，避免强制走完整 propose/design/plan 链路
argument-hint: <中文变更名> <需求描述>
---

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

## 用户输入

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

---
处理低风险、小范围变更，并保留最小知识库追踪。lite 分为「超轻记录型」「记录型」和「知识同步型」：超轻只记录文件、原因和知识库无需更新结论；记录型补充影响范围；知识同步型额外更新目标知识文件。

**执行 Agent**：**kb-scribe**（01/manifest）+ **kb-release**（外部 sync，可选）+ **kb-builder**（实现）；工种见 [kb-agent-roles.md](../skills/kb-workflow/references/kb-agent-roles.md)

**适用范围**：
- 文案、样式、局部 UI 调整
- 单文件或少量文件的明确 bug 修复
- 不改变 proto、数据库结构、权限、资金、事务、跨端接口契约

若发现超出范围，停止轻量流程，改走 `/kb-propose <中文名称>` 标准流程。

## 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)"`

## 输入

中文变更名称 + 简短变更说明。

## 产出

- `knowledge/变更/进行中/<YYYYMMDDHHMMSS>-<中文名称>/00-manifest.json`
- `knowledge/变更/进行中/<YYYYMMDDHHMMSS>-<中文名称>/01-proposal.md`（轻量变更说明）
- `knowledge/变更/进行中/<YYYYMMDDHHMMSS>-<中文名称>/05-summary.md`
- 可选 `manifest.external`（`integrations` 启用时，含 `registry_record_id`、`notified_events` 含 `"created"`）
- 仅知识同步型 lite 按需更新知识地图、业务域、工程平台知识文件与所属领域/平台 index（wikilink 列表）；只有入口变化或总 index wikilink 失效时更新 `knowledge/index.md`

## 执行步骤

### 1. 判定是否可轻量

先按决策表判断，任一项命中「升级标准」即停止轻量流程，改走 `/kb-propose <中文名称>`。

涉及已有代码行为时，先用 `codegraph_explore` 快速核对影响面；若 CodeGraph 显示跨端、公共接口、数据结构、权限/资金/事务路径受影响，直接升级标准流程。

| 维度 | 可走 lite | 必须升级标准 |
|------|-----------|--------------|
| 需求清晰度 | 用户一句话即可说明变更和验收 | 需要追问多个业务规则或需走 `/kb-propose` 写正式 PRD |
| 修改范围 | 单文件或少量强相关文件 | 涉及多个模块、跨仓目录或共享抽象 |
| 接口契约 | 不改变公开方法、proto、HTTP/gRPC 参数 | 新增/修改/删除跨端接口或枚举 |
| 数据与权限 | 不改数据库结构、权限、资金、事务语义 | 涉及 DDL、余额、订单、权限、审计 |
| 客户端协作 | 只影响单端内部表现 | 需要 Flutter/Rust/Quasar/proto 多端同时配合 |
| 知识库影响 | 不需要更新，或只更新一处当前说明 | 需要知识地图、业务域、工程平台多文件联动或架构说明 |
| 风险回滚 | 可通过一次小补丁回滚 | 回滚依赖数据修复、迁移或跨端发布顺序 |

全部满足 lite 条件后，再确认：
- 用户没有要求完整 PRD、设计或任务拆解。
- 不需要 `02-design.md` 或 `03-tasks.md` 才能说清楚实现边界。
- 能在 `05-summary.md` 内用短句说明影响范围和知识库结论。

不满足时输出升级原因，并建议走标准流程。

为减少主观判断偏差，补充量化分流：

| 判定项 | 命中记分 |
|---|---|
| 涉及 proto / HTTP / gRPC 契约变化 | +3 |
| 涉及数据库结构、资金、权限、事务语义 | +3 |
| 涉及跨端联动（Flutter/Rust/Quasar 至少两端） | +2 |
| 需要新增或重排知识地图、业务域、工程平台多处知识文件 | +2 |
| 需求边界不清，需要 2 个以上关键追问 | +1 |

- 总分 `>= 3`：升级标准流程。
- 总分 `<= 2`：可继续 lite。
- 命中前两项任意一条：不看总分，直接升级标准。

随后判定 lite 类型：

| 类型 | 判定条件 | 执行口径 |
|------|----------|----------|
| 超轻记录型 lite | 纯文案、样式、日志、注释、配置描述，或单点无行为变化修正 | 一轮完成实现、极简总结、manifest 状态与归档迁移；无需 `/kb-index` |
| 记录型 lite | 不改变知识地图、业务域、工程平台当前说明；局部 bug 或小行为修正 | 一轮完成实现、总结、manifest 状态与归档迁移；无需 `/kb-index` |
| 知识同步型 lite | 改变一处当前功能说明、接口说明、架构说明或数据结构说明 | 实现后更新目标知识文件；如 README 失真则更新所属 index，仅入口变化时更新总索引 |
| hotfix-lite | 线上阻断问题，且修复范围可控 | 允许「一轮直通」：实现 + summary + 归档同轮完成；summary 顶部标注 hotfix-lite |

超轻记录型和记录型 lite 都不是“无文档”，必须在 `05-summary.md` 写明「知识库无需更新」的具体原因。

**一步式 lite 口径**：
- 超轻记录型和记录型 lite 可在同一轮内完成：可选外部登记 → 实现小改 → 更新 `manifest.files` → 写 `05-summary.md` → 迁移到 `knowledge/变更/归档/` → commit+push → 可选外部 sync 步骤 10。
- 不要求五角评审，不要求 `04-review.md`，不要求 `06-automation-test.md`。
- 若过程中发现触发接口、数据、权限、资金、事务、跨端协作或多文件知识库更新，立即停止一步式 lite，升级标准流程。

## 外部登记（可选，integrations 启用时）

lite **不是**「无 PRD 就不登记」的硬例外；若 `kb.project.json` 启用了 `integrations.registry` / `notifications`，与 `/kb-propose` 一样应完成外部登记与 created 通知，归档时再走 `/kb-archive` 步骤 10 的 completed sync。

| 项 | 要求 |
|----|------|
| 细则 | [kb-external-sync.md](../skills/kb-workflow/references/kb-external-sync.md)、[kb-external-writeback.md](../skills/kb-workflow/references/kb-external-writeback.md) |
| 登记 | `node "${PI_KB_ROOT}/scripts/kb-external-sync.mjs" --event registry.propose --scan-id <14位前缀>` |
| 通知 | `node "${PI_KB_ROOT}/scripts/kb-external-sync.mjs" --event notify.propose_created --scan-id <14位前缀>` |
| 幂等 | 磁盘已有 `external.registry_record_id` 则**禁止**重复登记/发 created |
| 未启用 integrations | **跳过**，不得阻断 lite 实现与归档 |

**lite 与 propose 的差异**（登记阶段）：

- 正文来源：轻量 `01-proposal.md`（变更说明 + 验收标准），**不要求**完整业务 PRD 八段式。
- Figma：默认 `figma_confirmed=true`、`figma_decision=auto-none`。
- 类型/优先级：主 Agent 向用户确认一项即可（局部 bug 默认 `Bug` + `P2`，文案样式默认 `Bug` + `P3`）。
- 登记时机：写入 `01-proposal.md` 且用户确认后、**实现小改之前**（若启用 integrations）。

## 子 Agent 编排（必遵）

- 读知识库、撰写 `01-proposal.md`、更新 `00-manifest.json`、实现与 `05-summary.md` 由子 Agent 执行。
- 主 Agent：澄清、确认类型/优先级、审核登记结果；**不**直接写文件、**不**直接调用外部 provider API。
- 子 Agent 回报登记成功后，主 Agent 必须用 **shell** 读磁盘确认 `external` 字段（若 integrations 已启用）。

### 2. 创建变更目录与 manifest

时间前缀须按 [kb-change-directory-id.md](../skills/kb-workflow/references/kb-change-directory-id.md) 用 shell 生成（`TZ=Asia/Shanghai date +%Y%m%d%H%M%S`），禁止脑填。

由子 Agent 创建目录并写入 `00-manifest.json`，结构必须符合业务仓 `.kb/kb-manifest.schema.json`。创建前读取**当前流程版本**（shell 解析，口径见 [kb-workflow-version.md](../skills/kb-workflow/references/kb-workflow-version.md)），写入 `workflow_version` 字段。

```json
{
  "name": "<中文名称>",
  "flow": "lite",
  "stage": "applying",
  "tasks": [
    {
      "id": "LITE-01",
      "title": "<一句话任务>",
      "status": "pending",
      "files": []
    }
  ],
  "reviews": [],
  "revisions": [],
  "files": [],
  "updated_at": "<YYYY-MM-DDTHH:mm:ss+08:00>",
  "workflow_version": "<按 kb-workflow-version.md 解析当前版本>"
}
```

> `workflow_version`：创建前按 [kb-workflow-version.md](../skills/kb-workflow/references/kb-workflow-version.md) shell 解析；bootstrap 后尚未 `/kb-evolve` 时可省略。

### 3. 写入轻量 `01-proposal.md` 并可选外部登记

用户确认变更范围后，由子 Agent 写入 `01-proposal.md`（头部 `来源：kb-lite`）。若 integrations 启用，再执行外部登记（见上文「外部登记（可选）」）。

```markdown
# <中文名称>轻量变更说明

> **变更 ID**：`<YYYYMMDDHHMMSS>-<中文名称>`
> **来源**：kb-lite
> **类型**：（确认后补全）
> **优先级**：（确认后补全）
> **外部 PRD**：（外部登记后补全，无则写「无」）
> **任务记录**：（外部登记后补全）
> **Figma 设计图**：无

---

## 变更说明
<一句话说明要改什么>

## 验收标准
<可验证的简短验收>

## 影响范围
<单端/单文件等>
```

登记完成后将 `00-manifest.json.stage` 更新为 `"applying"`（若仍为 `proposed`）。

### 4. 实现小改

派发一个子 Agent 执行，prompt 必须包含：
- 变更说明
- 允许修改的文件范围
- 先用 CodeGraph 核对相关代码上下文和影响面
- 禁止扩散修改
- 关键日志要求
- **AGENTS.md 沉淀**：验收通过后总结犯错经验，将可复用规矩写入涉及目录 `AGENTS.md`；细则见 [kb-agents-precipitation.md](../skills/kb-workflow/references/kb-agents-precipitation.md)

完成后更新 `00-manifest.json`：
- `tasks[0].status = "done"`
- `files[]` 写入所有实际变更文件，使用仓库根目录相对路径
- 变更目录文件标记为 `kind = "change_doc"`，业务/配置文件按实际类型标记

### 5. 写入轻量总结

由子 Agent 写入 `05-summary.md`（超轻/记录型/知识同步型/hotfix-lite 模板同原口径，见 `/kb-archive` 与历史 lite 命令）。

### 6. 归档

超轻记录型和记录型 lite 可由同一轮子 Agent 直接迁移到 `knowledge/变更/归档/`。
**迁移必须用 shell `mv`**，禁止 `cp`/复制后保留 `进行中/`；细则见 [kb-archive-migrate.md](../skills/kb-workflow/references/kb-archive-migrate.md)。
**收尾顺序与 `/kb-archive` 一致**：迁移目录 → commit+push → 可选 `sync.archive_completed`（integrations 启用且有 `registry_record_id` 时）。

## 注意事项

- 轻量流程不是绕过记录，而是减少不必要的 PRD/设计/任务文档。
- 轻量流程不主动执行全量静态检查；仅在用户明确要求或变更说明要求时执行指定范围检查。
- 轻量流程执行中一旦发现升级标准，立即停止继续改代码，先补充当前发现与升级原因。
- `00-manifest.json` 与 `05-summary.md` 必须同轮同步；若二者对任务状态、知识库更新或归档结论冲突，先停止推进并运行 `/kb-check`。
- 提交仍遵守 `/kb-commit` 与仓库提交规范。