feat!: 0.6.0 —— 侧边栏重组为 工程/库生态/缓存，并修完两轮真实验收问题

.agents/docs/README.md

@@ -0,0 +1,20 @@
+# .agents/docs
+
+本目录存放 **面向贡献者与 agent 的设计/背景文档**：对 mcpp-vscode 当前架构、跨仓库契约
+与决策的记录。使用说明请看仓库根目录的 `README.md`。
+
+| 文件 | 内容 | 状态 |
+| --- | --- | --- |
+| [`architecture.md`](architecture.md) | mcpp-vscode 的分层结构、模块职责与扩展点 | 现状 |
+| [`mcpp-integration.md`](mcpp-integration.md) | 与 `mcpp-community/mcpp`（mcpp CLI）的接口契约 | 现状 |
+| [`mcppls-integration.md`](mcppls-integration.md) | 与 `sunrisepeak.mcpp-language-server`（mcppls）的依赖与命令桥接契约 | 现状 |
+| [`2026-10-02-plugin-optimisation-plan.md`](2026-10-02-plugin-optimisation-plan.md) | 插件优化方案 **v4**：目录树与 README、mcppls 依赖韧性、稳定基座、`mcpp.toml` 与 `build.mcpp` 编辑体验、缓存统计与两级清理、配色与可视化、i18n、统一配置模块与配置面板、**mcppls 状态与管理（§3.9）** | **待评审** |
+
+边界：
+
+- `docs/`（仓库根）= **用户文档**（安装、命令、设置、排错）；
+- `.agents/docs/` = **贡献者/agent 文档**（设计、契约、方案、决策）；
+- `.agents/superpowers/` = **过程文档**（原 `docs/superpowers/`，plans/specs）；
+- `.agents/reviews/` = **分析与评审记录**，已加入 `.gitignore`，不进入版本库。
+
+背景分析见 `.agents/reviews/2026-10-02-mcpp-vscode-architecture-and-mcppls-dependency-review.md`。

.agents/docs/architecture.md

@@ -0,0 +1,77 @@
+# mcpp-vscode 架构
+
+> 状态：0.4.0（mcppls 语言服务迁移之后）。本文记录**当前**结构；变动请同步更新。
+
+## 1. 一句话定位
+
+mcpp-vscode 是 **mcpp CLI 的 IDE 前端**：工程发现、任务（build/run/test/clean）、工具链管理、
+`mcpp.toml` 的语法与结构补全。C++ 模块语义（诊断/补全/跳转/引用/模块图/状态）由扩展依赖
+`sunrisepeak.mcpp-language-server`（mcppls）提供，本扩展**不创建 LSP 客户端**。
+
+## 2. 分层
+
+```
+extension.ts                 VS Code 装配层：激活、命令注册、provider 注册、资源释放
+├── cliController.ts         CLI 编排层：快捷菜单、任务、工具链、新工程、操作互斥
+│   ├── newProject.ts        新建工程流程（纯函数 + 注入的动作）
+│   └── commands.ts          命令 ID 与快捷菜单清单（纯数据）
+├── languageServer.ts        mcppls 桥接层：只调用 4 个公开 VS Code 命令
+├── moduleSetup.ts           一键流程状态机（build → 刷新语言服务）
+├── inProject.ts             `mcpp.inProject` 上下文键
+├── mcppTomlCompletion.ts    mcpp.toml 补全查询层（段头 + 写法模板）
+├── mcppTomlParser.ts        容错 TOML 解析器（纯函数）
+├── discovery.ts             最近的 mcpp.toml 发现（纯函数）
+├── cli.ts                   mcpp CLI 输出解析（工具链清单）
+├── process.ts               runProcess 封装
+└── tasks.ts                 任务计划、退出码分类、操作注册表（纯函数）
+```
+
+**约束**：`tasks.ts` / `moduleSetup.ts` / `discovery.ts` / `cli.ts` / `mcppTomlParser.ts` /
+`newProject.ts` 不 import `vscode`，因此可用 `node --test` 直接测。`extension.ts` 与
+`cliController.ts` 是唯一接触 VS Code API 的地方。
+
+## 3. 运行时边界
+
+| 触发 | 行为 |
+| --- | --- |
+| 打开含 `mcpp.toml` 的工作区 | 激活；不执行 `mcpp`，不下载工具链 |
+| 执行 mcpp 命令 | 通过 `vscode.Task` + `ProcessExecution` 在专用终端运行 |
+| build 结束（含失败） | 调用一次 `mcppls.restartServer`（单飞，取消除外） |
+| run/test/clean 结束 | 不触碰语言服务 |
+| 未受信任工作区 | 只保留语法高亮与 TOML 结构补全 |
+
+## 4. 并发模型
+
+`McppOperationRegistry`（`tasks.ts`）做两级互斥：
+
+- **项目级**（键 = 工程根）：build/run/test/clean 互斥；
+- **全局**：工具链安装 / 设置全局默认，与所有项目级操作互斥。
+
+任务结束**先释放锁、再刷新语言服务**，避免刷新期间用户操作被拒。该顺序由
+`test/artifacts.test.ts` 钉住。
+
+## 5. 与 mcppls 的唯一接口
+
+`languageServer.ts` 是全部耦合面：
+
+| 本扩展命令 | 转发到 |
+| --- | --- |
+| `mcpp.configureLanguageServer`（+ 弃用别名 `mcpp.configureClangd`） | `mcppls.selectContext` |
+| `mcpp.checkModuleSupport` | `mcppls.restartServer` |
+| `mcpp.showModuleGraph` | `mcppls.showModuleGraph` |
+| `mcpp.showLanguageServerLogs` | `mcppls.showLogs` |
+| build 之后 | `mcppls.restartServer` |
+
+不读 `mcppls.*` 设置、不解析 LSP、不写跨扩展配置。详见
+[`mcppls-integration.md`](mcppls-integration.md)。
+
+## 6. 已知的结构性债务
+
+- `src/configureOnly.ts`、`src/ideWorkflow.ts` 在 0.4.0 迁移后已无生产调用者（仅被自身测试引用），
+  它们描述的是 `compile_commands.json` 时代的行为，与当前职责边界冲突。
+- `cli.ts` 用正则解析 `mcpp toolchain list` 的**人类输出**，而 mcpp 已提供
+  `--format json` 的稳定契约。
+- 命令 ID `mcpp.refreshCompilationDatabase` / `mcpp.checkModuleSupport` 是历史拼写，与当前语义
+  （build / restart）不符。
+
+具体建议见 `.agents/reviews/` 下的评审报告。

.agents/docs/mcpp-integration.md

@@ -0,0 +1,80 @@
+# 与 mcpp CLI 的集成契约
+
+> 对象：`mcpp-community/mcpp`（C++23 模块优先构建工具，下称 mcpp）。本文记录本扩展**实际
+> 调用**的 mcpp 接口，以及 mcpp 已经提供、本扩展尚未使用的稳定接口。
+
+## 1. 本扩展实际调用的命令
+
+| 调用点 | 命令 | 依赖的输出 |
+| --- | --- | --- |
+| `cliController.newProject` | `mcpp new <name>` | 退出码 |
+| `tasks.projectTaskPlan` | `mcpp build` / `run` / `test` / `clean` | 退出码（VS Code Task） |
+| `cliController.readToolchainInventory` | `mcpp toolchain list` | **人类文本**（正则解析） |
+| `cliController.selectDefaultToolchainFromInventory` | `mcpp toolchain default <spec>` | 退出码 |
+| `cliController.pickInstallSpec` → `installToolchain` | `mcpp toolchain install <spec>` | 退出码 |
+
+`mcpp.path` 为空时用 `"mcpp"`，由 VS Code 进程的 `PATH` 解析。
+
+## 2. mcpp 已提供的稳定机读接口（本扩展未使用）
+
+mcpp 有正式的机读输出协议（`docs/50-machine-output.md`）。**检测规则**：解析 stdout，
+要求 `schemaVersion` 与 `kind` 存在；**不要**用退出码或"命令没报错"来判断支持与否。
+
+| 命令 | `kind` | 用途 |
+| --- | --- | --- |
+| `mcpp --protocol-version` | `mcpp.protocol` | 静态探测：信封版本、各 kind 版本、每个命令的 `effects`；无副作用 |
+| `mcpp self env --format json` | `mcpp.env` | `mcppHome` / `registry` / `xlingsBinary` / `config` / `buildCache` / `mcppVersion` / `defaultToolchain`；**只读**，不会创建 `$MCPP_HOME` |
+| `mcpp toolchain list --format json` | `mcpp.toolchain.list` | `{host, toolchains[], targets[]}`，字段 `family`/`version`/`default`/`source`，target 行含 `target`/`note`/`toolchain`/`pin`/`status`/`default` |
+| `mcpp emit build-database [--spec s1\|compile-commands] --format json` | `mcpp.build-database` | 构建计划；**不写工程目录**（`--configure-only` 会写 `compile_commands.json`） |
+| `mcpp why toolchain --format json` | `mcpp.why.toolchain` | 某个 (target, toolchain) 的解析依据，含 `reason` token |
+
+信封形态：
+
+```jsonc
+{ "schemaVersion": 1, "kind": "...", "kindVersion": 1,
+  "effects": [], "mcpp": { "version": "2026.9.30.2",
+                           "protocol": { "min": 1, "max": 1 } },
+  "data": {}, "diagnostics": [] }
+```
+
+`kind` 内字段只增不删、含义不变；破坏性变更提升 `kindVersion`。
+
+## 3. 流与退出码
+
+- **stdout = 结果，stderr = 叙述**（2026.9.30.2 起；此前叙述在 stdout）。`mcpp toolchain list`
+  这样的"列表"命令，列表本身在 stdout。
+- `--format json`（带信封）与 `--json`（裸文档，如 `mcpp cache list --json`）是两种**永久并存**
+  的输出；`ndjson` 不被 `--format` 接受。
+- `mcpp build --configure-only` 在规划失败（无 `mcpp.toml`、工具链/依赖解析失败）时返回 **2**，
+  而不是 1；`mcpp emit build-database` 对同类失败返回 **1** 并给出信封与 `diagnostics`。
+- 完整退出码契约（SPEC-003）：`0` 成功、`1` 运行期失败、`2` 用法错误、**`4` 环境未就绪**、
+  `70` 内部错误、`101` **仅 `mcpp run`** 的构建失败、`127` 未知命令。
+- **退出码不得用于协议识别**：判断某功能是否支持，唯一跨版本成立的判据是解析 stdout。
+- `1` 可以与 stdout 上的信封同时出现，不要因为非零退出就丢弃已解析到的文档。
+- `mcpp run` 透传被运行程序的退出码（`0–124`）；`125/126/127` 是 spawn 被拒。
+
+## 4. 明确不是接口的东西
+
+`docs/51-supported-versions.md` 的表面稳定性表把 `mcpp.toml` 键、CLI 命令与标志、机读输出、
+`build.mcpp` 指令协议、`mcpp.lock`、target 行列为 additive；而 **构建指纹、缓存布局与
+`target/` 下的内容不是接口**，无通知即变。判断"要不要重新规划"请用
+`mcpp emit build-database` 的 `watch` 与 `inputs-fingerprint`。
+
+## 5. mcpp 版本
+
+形如 `2026.10.1.3`（`年.月.日.序号`），数字**不携带**兼容性承诺。`mcpp --version` 输出
+`mcpp <version>`（**无** `v` 前缀）；`mcpp --help` 的横幅反而带 `v`，不要从那里抓版本。
+机读版本号在 `mcpp self env --format json` 的 `data.mcppVersion`，以及任何信封的
+`mcpp.version`。mcpp 自身仍标注为早期项目，接口与行为可能变化；`docs/50` 与 `docs/specs/`
+是兼容性承诺的来源。
+
+## 6. 本扩展对 mcpp 的已知假设（需要随 mcpp 版本复核）
+
+1. `mcpp toolchain list` 的人类输出包含 `Toolchains:` / `Targets:` / `Available toolchains...:` 段，
+   用 `*` 标记有效项，并用 `global default is '<spec>'` 报告全局默认。
+   —— 在 mcpp 2026.9.30.2 上已观察不到该 `global default` 行，解析器会退化为用"有效项"充当
+   全局默认。
+2. `mcpp toolchain list` 的每一行可用 `family version [/ version...]` 或 `family@version` 形式解析。
+3. `mcpp new <name>` 的模板不做 TOML/C++ 转义，且名字包含 `PROJECT` 时模板替换不终止
+   （mcpp#380）；`newProject.ts` 因此做名称白名单校验。
+4. `--configure-only` 会写 `compile_commands.json`，成功条件是退出码 0 且该文件可解析。