# Changelog

本仓库跟踪 **@suwenguang/pi-kb**（Pi Package）版本。每节注明对应 Claude 插件 `kb-workflow` 版本（若有同步）。

---

## 0.1.16 - 知识图谱自进化 + stage 状态机 / 新建默认 lite

### 变更摘要

1. **知识图谱写时演化（A-MEM-lite）**：archive/sync/librarian 强制构笔记 → 建链 → 邻接回写；细则 `kb-knowledge-evolve.md`；`SKILL.md` 原则 21。
2. **时效字段（Graphiti-lite）**：概念 frontmatter 可选 `status` / `supersedes` / `keywords`；`kb-okf-check` 校验；检索默认降权 `superseded`。
3. **贡献分（EvoRAG-lite）**：`.kb/knowledge-utility.json` + `scripts/kb-knowledge-utility.mjs`（bump/penalize/rank/summary）；接入 `/kb-query` / archive / apply / health；bootstrap 空模板。
4. **`scripts/kb-stage-next.mjs`**：读 `00-manifest.json` 输出下一跳 JSON；`--intent new` 默认 `/kb-lite`；`kb-admin` / orchestrator 派发前必跑。
5. **口径对齐**：`SKILL.md` stage 枚举补 `applied_audited`；原则 8 / 工种 SSOT 同步。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. 若缺 `.kb/knowledge-utility.json`：重跑 bootstrap 或手动复制包内 `bootstrap/knowledge-utility.json`（默认**提交进 git**）。
3. 存量概念无需强制补 `status`（缺省 = current）；取代旧模块时再写 `supersedes` / `status: superseded`。

### 相关文档

- [skills/kb-workflow/references/kb-knowledge-evolve.md](skills/kb-workflow/references/kb-knowledge-evolve.md)
- [docs/evolution/20260727095607-knowledge-evolve-utility.md](docs/evolution/20260727095607-knowledge-evolve-utility.md)
- [docs/evolution/20260727094925-stage-next-lite-default.md](docs/evolution/20260727094925-stage-next-lite-default.md)

---

## 0.1.15 - bundled Figma Remote MCP（pi-figma-remote-auth）

### 变更摘要

1. **bundled `pi-figma-remote-auth`**：`dependencies` + `bundledDependencies`；`pi.extensions` 引用 `node_modules/pi-figma-remote-auth/index.ts`。装本包即可用 `/figma-remote-auth`（配合已 bundled `pi-mcp-adapter`），**无需**单独 `pi install npm:pi-figma-remote-auth`。
2. **Token sync（对齐业务仓）**：`extensions/figma-mcp-oauth-sync.ts`（`/figma-oauth-sync` + `session_start` 自动）+ `scripts/import-figma-mcp-oauth.mjs`（明文 → 适配器遗留路径 + OS 密钥环）。修复 login 后仍 **needs auth**。
3. **配置引导**：`/kb-figma-setup`；实践 SSOT `kb-figma-remote.md`；`/kb-init` / README / HINT / SKILL / SOP / orchestrator 同步。
4. **与提案闸门分工**：产品侧有无设计图仍走 `/kb-propose`；读帧/组件走 Figma MCP OAuth + sync。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. `/kb-figma-setup`，或：`/figma-remote-auth setup --project` → `login` → `/figma-oauth-sync` → `/mcp reconnect figma`。
3. 可从 `.pi/settings.json` 移除单独的 `npm:pi-figma-remote-auth`；若有项目级 `.pi/extensions/figma-mcp-oauth-sync.ts` 可删以免重复。

### 相关文档

- [skills/kb-workflow/references/kb-figma-remote.md](skills/kb-workflow/references/kb-figma-remote.md)
- [docs/evolution/20260726135200-figma-remote.md](docs/evolution/20260726135200-figma-remote.md)

---

## 0.1.14 - Cursor Agent 配套接入（pi-cursor-sdk）

### 变更摘要

1. **Cursor Agent 一等公民文档**：新增 `pi-overlays/kb-cursor-sdk.md` → `skills/kb-workflow/references/kb-cursor-sdk.md`；斜杠 `/kb-cursor-setup`（豁免 Bootstrap）。
2. **不 bundled**：`pi-cursor-sdk` / `@cursor/sdk` 含按平台 optional binary，故保持业务仓 `pi install npm:pi-cursor-sdk -l --approve`；`package.json` 声明 optional peer `pi-cursor-sdk`。
3. **入口同步**：HINT、`/kb-init`、README、SKILL、SOP、orchestrator 路由；`migrate` 跳过覆盖 `kb-cursor-setup.md`。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. 需要 Cursor 模型时执行 `/kb-cursor-setup`，或：
   ```bash
   pi install npm:pi-cursor-sdk -l --approve
   # /login → Cursor，或 export CURSOR_API_KEY=...
   pi --approve --model cursor/composer-2-5
   ```

### 相关文档

- [skills/kb-workflow/references/kb-cursor-sdk.md](skills/kb-workflow/references/kb-cursor-sdk.md)
- [docs/evolution/20260726133500-cursor-sdk.md](docs/evolution/20260726133500-cursor-sdk.md)

---

## 0.1.13 - bundled DeepSeek Search + 归档门禁 + 依赖升级

### 变更摘要

1. **bundled `pi-deepseek-search`**：`dependencies` + `bundledDependencies`；`pi.extensions` 引用 `node_modules/pi-deepseek-search/index.ts`。安装本包即可用工具 `web_search`（DeepSeek 服务端搜索），**无需**单独 `pi install npm:pi-deepseek-search`。
2. **配置引导**：`/kb-deepseek-search-setup`；会话启动时若无 DeepSeek Key 则提示；`/kb-init` / README / HINT 同步。
3. **最佳实践 SSOT**：`skills/kb-workflow/references/kb-deepseek-search.md`（`pi-overlays/` 维护）；SKILL / 工种 agents / propose·design·apply·evolve 引入实践口径。
4. **归档测试门禁 + files 对象格式 + commit 收尾校验**（#IK4057 / #IK4058 / #IK4059）：`06` 有失败用例阻断归档；manifest `files` 支持 string | 对象；archive 步骤 9 区分变更产物与结构迁移并校验工作区干净。
5. **依赖升级**：`pi-subagents` `^0.35.1` → `^0.37.0`；`pi-mcp-adapter` `^2.13.0` → `^2.15.0`。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. `/login` 选 DeepSeek，或 `export DEEPSEEK_API_KEY=...`，再确认工具 `web_search` 可用。
3. 可从 `.pi/settings.json` 移除单独的 `npm:pi-deepseek-search` 条目（若仅为本包而装）。

### 相关文档

- [skills/kb-workflow/references/kb-deepseek-search.md](skills/kb-workflow/references/kb-deepseek-search.md)
- [docs/evolution/20260726001000-deepseek-search.md](docs/evolution/20260726001000-deepseek-search.md)
- [docs/evolution/20260726000900-archive-gate-audit-files-commit.md](docs/evolution/20260726000900-archive-gate-audit-files-commit.md)

---

## 0.1.12 - EvoMap 回传默认改为「是」（publish=true 已授权）

### 变更摘要

1. **EvoMap 回传默认执行**（#IK3ZZK）：削弱硬规则「禁止静默 publish」。`publish=true` 视为 setup 阶段已授权，`/kb-evolve` 步骤 7 默认回传（首次回传提示一次「将开始回传 EvoMap」）；用户当轮明示拒绝则跳过；`publish=false` 仍禁止上传。同步更新 `kb-evolve.md` / `kb-evomap.md` / `kb-feedback-gitee.md` 三文件口径。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. `/kb-evolve` 步骤 7 不再每轮询问是否回传 EvoMap（`publish=true` 时默认回传）。

### 相关文档

- [docs/evolution/20260725223000-evomap-default-publish.md](docs/evolution/20260725223000-evomap-default-publish.md)

---

## 0.1.11 - MR target-branch 自动探测 + EvoMap publish schema 文档化

### 变更摘要

1. **MR 默认 target-branch 自动探测**（#IK3ZW2）：`kb-gitee-issue.mjs mr` 默认 `master` 改为自动探测（`git symbolic-ref refs/remotes/origin/HEAD` -> `git remote show origin` -> fallback `main`）；`/kb-evolve` MR 示例补 target-branch 注释。
2. **EvoMap publish bundle schema 文档化 + 错误提示增强**（#IK3ZW3）：`kb-evomap.md` 补完整 publish bundle schema 章节（Gene/Capsule/EvolutionEvent 字段表、asset_id canonical JSON 计算规则、完整 bundle 示例）；`kb-evomap.mjs publish` 失败时解析 hub details 给出字段级提示（path/message/correction.fix）。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. `/kb-evolve` 提 MR 不再需手动 `--target-branch main`（自动探测）。
3. EvoMap publish 回传失败时错误提示更友好（显示缺字段路径与修复建议）。

### 相关文档

- [docs/evolution/20260725193000-mr-target-evomap-schema.md](docs/evolution/20260725193000-mr-target-evomap-schema.md)

---

## 0.1.10 - audit 全新仓库修复 + schema 合法值扩展 + 编号口径统一

### 变更摘要

1. **audit 脚本全新仓库修复**（#IK3ZFP）：`kb-audit-apply.mjs` 无 commit 时 `git diff HEAD` 降级为仅 untracked；新增 bootstrap 产物排除（`.kb/`、`kb.project.json` 等）；路径归一化补变更目录前缀再比对；schema/prompt 明确 `files` 为相对业务仓根路径。
2. **schema 合法值扩展**（#IK3ZFQ）：`files[].source` +`test`；`files[].kind` +`test`；`external.task_type` 补中文说明；propose/test/SKILL 同步文档化。
3. **编号口径统一为中文数字**（#IK3ZFR）：kb-design/kb-plan 的 `## N、` -> `## 中文数字、`、`### N.M` -> `### （一）/（二）/（三）`；AGENTS 引用「5」->「§六」、「6」->「§七」。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. 既有变更目录的 `02-design.md` / `03-tasks.md` 无需改动（编号口径以 AGENTS 为准，本次仅修正命令模板与 AGENTS 对齐）。
3. 全新仓库首次 `/kb-apply` 的 audit 误判 drift 问题已修复。

### 相关文档

- [docs/evolution/20260725190148-audit-schema-numbering.md](docs/evolution/20260725190148-audit-schema-numbering.md)

---

## 未发布 - bundled `pi-mcp-adapter`

### 变更摘要

1. **bundled `pi-mcp-adapter`**：`dependencies` + `bundledDependencies`；`pi.extensions` 引用 `node_modules/pi-mcp-adapter/index.ts`。
2. 安装 `@suwenguang/pi-kb` 即可用 MCP 适配（含 CodeGraph 等），**无需**单独 `pi install npm:pi-mcp-adapter`。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后 `/reload`。
2. 可从 `.pi/settings.json` 移除单独的 `npm:pi-mcp-adapter` 条目（若仅为本包而装）。
3. CodeGraph 仍须业务仓项目级 MCP 配置（`bootstrap/examples/mcp/`）。

### 相关文档

- [README.md](README.md)

---

## 未发布 — 反馈闭环摩擦修复

### 变更摘要

1. **Bootstrap 豁免反馈类命令**（#IK3YG9）：`/kb-feedback`、`/kb-session-retro` 不再硬拦未 `/kb-init` 的业务仓；SKILL/SOP/扩展 HINT 同步。
2. **`--check` 优先 cwd**（#IK3YG8）：`kb-evolve-setup.mjs --check` 优先认定源码仓 cwd，避免 setup 后未 `/reload` 时旧 `PI_KB_ROOT`（node_modules）误报 `ok:false`；清单提示 env 滞后。
3. **Gitee token 持久化**（#IK3Y6W）：`kb-token-lib.mjs` + `kb-config.mjs set-token|show-source`；解析顺序 env → `~/.config/pi-kb/token` → `.kb-token`。
4. **旁路摩擦候选**（#IK3Y69）：扩展检测到流程摩擦时写入候选池；`kb-feedback-candidates.mjs`；`/kb-session-retro` 合并候选并可 ack/dismiss。
5. **离开会话零确认自动 retro**：`/new` / resume 前若检测到摩擦，不再弹确认，直接取消切换并注入 `/kb-session-retro`。

### 业务仓动作

1. 本地 `-l` 或更新包后 `/reload`。
2. 推荐一次：`node "$PI_KB_ROOT/scripts/kb-config.mjs" set-token`。
3. 未初始化仓可直接 `/kb-feedback` / `/kb-session-retro`。

### 相关文档

- `prompts/kb-feedback.md`、`prompts/kb-session-retro.md`、`prompts/kb-evolve-setup.md`
- `skills/kb-workflow/references/kb-feedback-gitee.md`
- `scripts/kb-config.mjs`、`scripts/kb-feedback-candidates.mjs`、`scripts/kb-token-lib.mjs`

---

## 0.1.9 — apply 范围对账闸门

### 变更摘要

1. **`/kb-apply` 标准流新增范围对账闸门**：apply 全通过后、写 `stage=applied` 之后、`/kb-review` 之前自动运行 `kb-audit-apply.mjs`。
2. **新脚本 `scripts/kb-audit-apply.mjs`**：对比 `00-manifest.json.tasks[].files`（plan 范围）与 `git diff --name-only`（实际改动），输出 `{result: ok|drift, missing_files, extra_files, drift_report, checked_at}`。
3. **schema 扩展**：`manifest.audit` 字段记录对账结论；`stage` enum 新增 `applied_audited`（audit 通过后的中间态，review 起始态）。
4. **drift 处理**：缺失或多余文件时回退 `stage=applying`、在 `02-plan.md` 追加「对账漂移报告」小节、阻断进入 review。
5. 关联 Issue：#IK3Y25。

---

## 未发布 — EvoMap 接入（开发中）

### 变更摘要

1. **可选 EvoMap 网络进化**（默认关闭）：`/kb-evomap-setup` 由 Agent 驱动注册节点、展示 `claim_url`、enable/disable。
2. 脚本 `scripts/kb-evomap.mjs`：`status` / `enable` / `disable` / `register` / `search` / `publish`（直连 A2A，不依赖 Evolver）。
3. `/kb-evolve`：仅当 `~/.config/pi-kb/evomap.json` 的 `enabled=true` 时检索网络路径；`publish=true` 时经用户确认可回传 Gene+Capsule+EvolutionEvent。
4. **网络韧性**：直连失败时自动探测本机常见代理端口（Clash `7890`/`7897`、`1080`、`1897` 等）并 HTTP CONNECT 重试；支持 `HTTPS_PROXY` / 配置 `proxy`；`search` 仍失败则 soft-fail 不阻断进化。
5. 口径：`references/kb-evomap.md`；`migrate` 跳过 `kb-evomap-setup`；sync 保留 `kb-evomap.mjs`。

### 业务仓动作

1. 更新包后 `/reload`；确认帮助可见 `/kb-evomap-setup`。
2. 需要网络路径时再跑 `/kb-evomap-setup`（浏览器 claim 一次）；否则无需任何配置。
3. 若直连 Hub 失败，先开 Clash 等本地代理（常见 mixed 7890）；一般无需手写代理，脚本会自动探测。

### 相关文档

- `prompts/kb-evomap-setup.md`、`prompts/kb-evolve.md`
- `skills/kb-workflow/references/kb-evomap.md`
- README §4.1

---

## 0.1.8 — 2026-07-25

### 变更摘要

1. **新增 `/kb-session-retro`**（Pi 自有 prompt）：对本会话总结 KB 流程失败/摩擦经验，并对可改进项**自动**创建或追加 Gitee Issue（label `pi-kb-feedback`）；不写业务仓本地反馈目录。
2. **扩展自动催促**：`extensions/kb-root.ts` 启发式检测本会话流程摩擦；在 `/new` / resume 切换前**零确认**取消切换并注入 `/kb-session-retro`；退出时仅通知。
3. `migrate:prompts` 跳过 `kb-session-retro`；反馈口径 overlay / README / SKILL 已同步。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或本地 `-l`）后重启 / `/reload`。
2. 确认启动帮助可见 `/kb-session-retro`。
3. 提流程反馈前仍需 `GITEE_ACCESS_TOKEN`（无令牌时回顾报告仍可出，Issue 草稿保留）。

### 相关文档

- `prompts/kb-session-retro.md`
- `skills/kb-workflow/references/kb-feedback-gitee.md`
- README §3、§5

---

## 0.1.7 — 2026-07-25

### 变更摘要

1. **修复 prompts 未注册**：`argument-hint` 含 `[...]` 时 YAML frontmatter 解析失败，Pi 会跳过该文件（含 `/kb-evolve-setup`、`/kb-design`、`/kb-plan` 等）。现改为合法引号字符串；`migrate:prompts` 同步用 `JSON.stringify` 写出。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb` 后重启 / `/reload`。
2. 启动帮助里应能看到 `/kb-evolve-setup` 以及 design/plan/apply 等命令。

### 相关文档

- README §5 常用斜杠命令

---

## 0.1.6 — 2026-07-25

### 变更摘要

1. **Pi 自有反馈/进化模型**（与 Claude Code 本地 `反馈/FB-*.md` 解耦）：
   - `/kb-feedback` → 仅向 `gitee.com/suveng/pi-kb` 建 Issue（label `pi-kb-feedback`），业务仓不留本地反馈目录。
   - `/kb-evolve-setup` → 克隆/fork 源码、业务仓改挂本地路径、拉 evolve 分支。
   - `/kb-evolve` → 仅源码检出；拉 Issue → 改包 → `docs/evolution/` → 提 MR 到 master。
2. 新增脚本：`kb-gitee-issue.mjs`、`kb-evolve-setup.mjs`、`apply-pi-feedback-overlay.mjs`。
3. `migrate:prompts` 跳过 `kb-feedback` / `kb-evolve` / `kb-evolve-setup`；`sync` 后自动应用 Pi 口径 overlay。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或本地 `-l`）后重启 / `/reload`。
2. 提流程反馈前设置 `GITEE_ACCESS_TOKEN`。
3. 若要本地改流程：`/kb-evolve-setup`，再用 `/kb-root` 确认非 `node_modules`。

### 相关文档

- `skills/kb-workflow/references/kb-feedback-gitee.md`
- `docs/evolution/README.md`
- README §3–§4

---

## 0.1.5 — 2026-07-25

### 变更摘要

1. 同步 `kb-workflow@0.7.5`：**CodeGraph explore-first**；废弃 `codegraph_context`；MCP 示例 / launcher 增加 `CODEGRAPH_MCP_TOOLS` allowlist。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或本地 `-l` 重装）后重启 / `/reload`。
2. 项目级 `.mcp.json` 合并示例中的 `CODEGRAPH_MCP_TOOLS=explore,status,search,callers,callees,impact,node,files`。
3. 确认可用 `codegraph_explore`。

### 相关文档

- 对应 Claude 插件：`kb-workflow@0.7.5`
- 细则：`skills/kb-workflow/references/kb-codegraph.md`

---

## 0.1.4 — 2026-07-25

### 变更摘要

1. 同步 `kb-workflow@0.7.3`：**Bootstrap 硬门禁**（`kb-bootstrap-check.mjs`）；除 `/kb-init` 外未初始化直接拒绝。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或本地 `-l` 重装）后重启 / `/reload`。
2. 未初始化仓先 `/kb-init`，或 `node "$PI_KB_ROOT/scripts/kb-bootstrap.mjs" --target "$(pwd)"`。

### 相关文档

- 对应 Claude 插件：`kb-workflow@0.7.3`

---

## 0.1.3 — 2026-07-25

### 变更摘要

1. **Pi prompt 用户输入**：所有 `prompts/kb-*.md` 增加 `argument-hint` 与 `$@` 占位；修复 `/kb-*` 展开后丢失用户附带参数的问题。
2. **工种 Agent 注册失败**：`pi.subagents.agents` 误写为 `./agents/*.md`；pi-subagents 按**目录**解析（非 glob），导致包内 `kb-*` 无法发现，主会话只能看到 builtin。已改为 `./agents`。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）后重启 Pi / `/reload`。
2. 用 `subagent({ action: "list" })` 或自然语言「列出可用子 Agent」确认可见 `kb-admin` / `kb-scribe` 等。

### 相关文档

- 对应 Claude 插件：`kb-workflow@0.7.2`
- pi-subagents：`package.json` → `pi.subagents.agents` 须为目录路径

---

## 0.1.2 — 2026-07-25

### 变更摘要

1. **bundled `pi-subagents`**：`dependencies` + `bundledDependencies`；`pi.extensions` 引用 `node_modules/pi-subagents/index.ts`。
2. 安装 `@suwenguang/pi-kb` 即可用工种 `kb-*` agent 与 `subagent` 工具，**无需**单独 `pi install npm:pi-subagents`。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重装 `-l`）。
2. 可从 `.pi/settings.json` 移除单独的 `npm:pi-subagents` 条目（若仅为本包而装）。

### 相关文档

- 对应 Claude 插件：`kb-workflow@0.7.2`

---

## 0.1.1 — 2026-07-24

### 变更摘要

1. `package.json` `author` 改为 `suwenguang`。

### 业务仓动作

1. `pi update npm:@suwenguang/pi-kb`（或重新 `pi install npm:@suwenguang/pi-kb -l`）。

### 相关文档

- 对应 Claude 插件：`kb-workflow@0.7.2`

---

## 0.1.0 — 2026-07-24

### 变更摘要

1. 首发 Pi 原生包：`prompts/`（25）、`agents/`（8）、`extensions/kb-root.ts`（注入 `PI_KB_ROOT`）。
2. 共享核自 `kb/plugin` 同步：`skills/`、`scripts/`、`bootstrap/`、`schema/`；`PI_KB_ROOT` → `PI_KB_ROOT`。
3. 维护脚本：`npm run sync` / `migrate:prompts` / `migrate:agents` / `migrate`。
4. 分发：公共 npm `pi install npm:@suwenguang/pi-kb -l`；本地路径亦可。

### 影响范围

| 对象 | 影响 | 是否 breaking |
|------|------|---------------|
| Pi 业务仓 | 可 project scope 安装本包并跑 `/kb-*` | 否（新包） |
| Claude `kb-workflow` | 无变更 | 否 |
| 业务仓 `knowledge/` | 仍由 bootstrap 写入，不进包 | 否 |

### 业务仓动作

1. `pi install npm:pi-subagents`（推荐）+ `pi install npm:@suwenguang/pi-kb -l`（或本地路径）。
2. `/kb-init` 或 `node "$PI_KB_ROOT/scripts/kb-bootstrap.mjs" --target "$(pwd)"`。
3. 按需配置 CodeGraph MCP（`pi-mcp-adapter` + `bootstrap/examples/mcp/`）。

### 相关文档

- [README.md](README.md)
- 对应 Claude 插件：`kb-workflow@0.7.2`