---
description: 强制同步知识库，基于最新代码分析重新生成知识文件。变更目录名必须为中文。
argument-hint: "[scan-id 或说明]"
---

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

## 用户输入

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

---
强制同步知识库，确保 knowledge/ 目录反映代码的最新现状。

**输入**: 可选 -- 指定要同步的范围（知识地图/业务域/工程平台，或具体中文领域），不指定则全量同步。

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

## CodeGraph 门禁（硬阻断）

本命令依赖 CodeGraph。开始前**必须**先跑机器门禁；失败则停止并输出脚本指引，禁止继续。执行：

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

门禁通过后，再确认 MCP 工具 `codegraph_*`（至少能调用 `codegraph_explore`（或 `codegraph_status`））可用。若工具不可用：阻断，并指引用户从插件示例复制项目级 MCP 配置：

按 [kb-codegraph.md](../skills/kb-workflow/references/kb-codegraph.md) §一，从 `${PI_KB_ROOT}/bootstrap/examples/mcp/` **只写当前宿主**对应文件（Claude/其他 → 根 `.mcp.json`；Cursor → `.cursor/mcp.json`；禁止无脑双写），配置后 Reload / 重启会话，再重试本命令。

## 子 Agent 编排（必遵）

- 同步前先确认 CodeGraph 可用；对每个受影响领域或每个「粗粒度目录」（如 `rust_server/src`、`vkk_client_flutter/lib`），**并行**派发 `Task`（`generalPurpose` 只读模式）产出与现有知识地图、业务域、工程平台的差异摘要。
- 子 Agent 必须优先使用 `codegraph_explore` 查当前实现；需要调用链或影响面时使用 `codegraph_impact` / `codegraph_callers` / `codegraph_callees`；只有 CodeGraph 不足时才读取具体文件。主 Agent 审核后确认更新结构，实际写回知识文件由子 Agent 执行。

## 执行步骤

### 1. 检测变更范围

```bash
# 优先查看工作区与当前分支相对远端的变更
git status --short
git diff --stat
git diff --stat @{upstream}...HEAD -- rust_server/ quasar/src/ lib/ doger_proto/ 2>/dev/null || true
```

根据变更范围确定需要同步的知识目标（业务域内落到对应子模块文件的相应段，结构见 [`knowledge/AGENTS.md`](../../knowledge/AGENTS.md)；跨子模块聚合落 `01-概览`）：
- `doger_proto/` 变更 → 相关子模块文件「五、接口」「六、数据」段；必须重新生成相关代码
- `rust_server/src/endpoints/`、HTTP/gRPC 入参出参变更 → 相关子模块「五、接口」「三、服务端规则」段
- `rust_server/src/services/`、跨模块调用链变更 → 相关子模块「三、服务端规则」与 `01-概览` 架构/依赖；跨域复用能力补工程平台
- `rust_server/src/infrastructure/`、数据库模型、缓存、队列变更 → 相关子模块「六、数据」「七、非功能与可观测」段；跨域基础设施补工程平台
- `vkk_client_flutter/lib/` 用户可见功能变更 → 相关子模块「1、能力范围」「4、客户端流程」段与 `01-概览`；端工程通用规则补工程平台
- `quasar/src/` 管理后台功能变更 → 后台相关子模块「4、客户端流程」段与 `01-概览`；后台工程通用规则补工程平台

### 2. 使用子 Agent 并行探索（`Task`）

对每个受影响的业务域、工程平台主题或仓库切片，**并行**启动 `Task`（`generalPurpose` 只读模式）重新分析对应代码：

- 子 Agent 先用 CodeGraph 获取代码事实，再对比知识文件、输出差异报告（表格或条列）
- 主 Agent 审核差异，决定哪些需要更新

### 3. 更新知识文件（子 Agent 写入）

- 每个文件保持 <= 3000 字符
- 使用中文
- 保留现有十段式结构框架（见 [`knowledge/AGENTS.md`](../../knowledge/AGENTS.md)），只更新变更段落；同步维护「十、相关」（子模块）或「十一、相关」（概览）与 frontmatter `related` / `depends_on`（正文链接 ⊇ 并集）
- **写时演化**：按 [kb-knowledge-evolve.md](../skills/kb-workflow/references/kb-knowledge-evolve.md) 构笔记 → 建链 → 邻接回写；可选 `keywords` / `supersedes`；确认知识曾误导时对路径 `penalize`
- 如果变更导致子模块文件超限或一篇混入 3 个以上独立主题，拆成更多编号子模块文件；仍庞大时才拆入 `knowledge/业务域/<领域>/<中文子目录>/` 并维护子目录 index；领域 index 只保留 `01-概览` 与子模块/子目录入口。
- 工程平台内容一律写入 `knowledge/工程平台/<中文平台分区>/` 并维护分区 index，不在工程平台根目录新增叶子文件。

### 4. 更新知识地图与局部 index（子 Agent 写入）

如新增/删除/重命名业务域或工程平台知识文件，先更新所属 `knowledge/业务域/<领域>/index.md`、`knowledge/业务域/<领域>/<中文子目录>/index.md` 或 `knowledge/工程平台/<中文平台分区>/index.md`（列表项 `* [[wikilink]] - description`，见 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md)）。业务域子目录入口变化时更新领域 index；工程平台分区入口变化时更新平台根 index；只有新增/删除/重命名领域入口或平台入口时，才同步更新 `knowledge/知识地图.md` 中的 `[[wikilink]]`。

### 5. 维护两级索引

本轮必须按实际范围判断：
- 业务域根叶子文件或子目录入口新增、删除、重命名：运行 `/kb-index 业务域/<领域>`；业务域子目录内叶子文件变化运行 `/kb-index 业务域/<领域>/<中文子目录>`。
- 工程平台分区内叶子文件新增、删除、重命名：运行 `/kb-index 工程平台/<中文平台分区>`；分区入口变化再运行 `/kb-index 工程平台`。
- 领域/平台入口变化、index wikilink 失效或总入口失真：运行 `/kb-index 总索引` 更新 `knowledge/index.md`。
- 纯正文微调且 index wikilink 与总索引仍准确：报告“无需更新两级索引”。

### 6. 输出同步报告

```
## 同步报告

| 范围 | 更新文件数 | 新增 | 删除 |
|------|-----------|------|------|
| 知识地图 | 0 | 0 | 0 |
| 业务域/礼物 | 2 | 1 | 0 |
| 工程平台 | 0 | 0 | 0 |
```

## 注意事项

- 全量同步耗时较长，优先使用增量同步（指定业务域或工程平台主题）
- 不要删除用户手动添加的知识文件
- 同步后不主动运行全量编译或静态检查；如用户明确要求，再执行指定范围验证
- 同步报告必须说明两级索引处理结果：已更新 / 无需更新 / 被阻断