feat(libraries): official catalog and shared package/module dependency graphs

.agents/docs/architecture.md

@@ -1,6 +1,6 @@
 # mcpp-vscode 架构
 
-> 状态：0.4.0（mcppls 语言服务迁移之后）。本文记录**当前**结构；变动请同步更新。
+> 第 1–6 节保留 0.4.0 迁移背景；Libraries 的当前架构与边界见第 7 节（2026-10-18）。
 
 ## 1. 一句话定位
 
@@ -75,3 +75,29 @@ extension.ts                 VS Code 装配层：激活、命令注册、provide
   （build / restart）不符。
 
 具体建议见 `.agents/reviews/` 下的评审报告。
+
+
+## 7. Libraries（2026-10-18）
+
+- `library/indexLocator.ts`：显式索引路径或 CLI home 下的官方索引发现；新位置 `indices/mcpplibs` 优先，兼容 `registry/data/mcpplibs`。不默认收集 xim。缓存按源路径、平台、描述符 stat 和更新标记区分；项目状态是单独的 overlay。
+- `library/projectState.ts`：复用 TOML 解析器，区分普通、开发与构建声明、源码依赖、锁定结果和有歧义的短名；生成清单预览的目标 section/key。
+- `library/libraryView.ts` 与 `library/detailPanel.ts`：VS Code 生命周期和 CLI 编排；搜索响应绑定请求代次，添加操作绑定包、项目、页面代次，详情读取还单独校验渲染请求顺序。
+- `library/libraryHtml.ts`、`library/detailHtml.ts`：纯渲染器。初始文档只安装一次；mounted 仅请求重放最新数据，后续用 message 更新局部 DOM，保留查询、版本、依赖类型、折叠状态与焦点，不形成 reload loop。
+- `library/projectWatcher.ts`：只比较选中项目的 manifest/lock 内容；详情实际读到的内容更新比较基线，保证短暂 lock 状态也能恢复。监听和计时器随窗口或项目切换释放。
+- `library/addDependency.ts`：普通和开发依赖由 `mcpp add` 修改，构建依赖/分组迁移只提供复制片段与打开清单。扩展不自行改写 TOML，也不将 lock-only 误称为已声明/已安装。
+
+本地真实 UI 验证入口：`tools/test-libraries-ui.mjs`；专用 profile 和产物均在 gitignored 的 `.dev-profile/`。
+
+- `library/examples.ts`：官方安装版索引未携带测试时，读取带来源提交的内置测试快照；checkout 的本地测试优先，自定义索引不使用此兜底。完整代码通过只读 `mcpp-example` 文档打开。
+- `projects/dependencyGraph.ts`：纯声明图遍历，默认三跳（公共画布可请求更深数据），处理路径包、共享节点和循环；lock 只补版本。`dependencyGraphPanel.ts` 负责只读文件编排和本地 Mermaid Webview。Mermaid 固定版本与许可证由编译脚本复制至 `dist/vendor`，无需 CDN。
+
+- `views/models.ts` 与 Libraries 共用直接声明解析，树节点携带项目、依赖和分组身份；点击进入声明图并居中高亮对应节点。Webview 使用 SVG 平移/缩放变换，滚轮保留鼠标锚点，Pointer Events 区分点击与拖动；Fit 可恢复完整图。
+
+## 8. Shared dependency canvas and C++ Modules graph
+
+- `graphs/model.ts` defines a provider-independent graph, component roots, depth/branch projection, 150-node/300-edge layout budgets and escaped Mermaid output. Complete module data is retained independently of the visible subgraph.
+- `projects/dependencyGraphPanel.ts` owns one persistent Webview with separate per-project/per-kind graph and navigation states. `graphs/panelHtml.ts` and `media/graph.js` share rendering, wheel/pointer navigation, folding, focus, search and theme handling. Layouts are serialized; obsolete provider requests are discarded.
+- `cli/moduleGraph.ts` is a trust-gated, time/output-bounded consumer of mcppls CLI JSON. This extends the integration boundary with structured queries, without taking over C++ parsing, resolution, LSP ownership or mcppls settings. Prefer the installed dependency extension's payload, with PATH fallback when absent.
+- `projects/moduleGraph.ts` validates the result, reads manifest entry conventions and determines file ownership by the nearest project manifest. Preserve all internal edges and just the first hop into another package; `external=false` alone cannot identify project ownership. Generated sources outside the project boundary are conservatively treated as external.
+- `webview/readOnlyDocuments.ts` is the shared content-addressed virtual-document store used by examples and graph navigation; graph messages contain node identities, and the host opens only provider files attached to those identities.
+- Basics contains C++ Modules Deps; declared package Dependencies follow as a collapsed sibling before Common commands. Existing language-server module-graph forwarding commands remain compatible.

.agents/docs/mcpp-integration.md

@@ -7,6 +7,11 @@
 
 | 调用点 | 命令 | 依赖的输出 |
 | --- | --- | --- |
+| `library/indexLocator` | `mcpp self env --format json` | `mcpp.env` 信封中的 `mcppHome`，按 CLI/项目上下文缓存 |
+| `library/detailPanel` | `mcpp xpkg parse <file> --json` | 裸 JSON；按需解析单个描述符，失败时标明文本回退 |
+| `library/libraryView` | `mcpp search <keyword>` | 尽力解析人类文本，仅产生有限预览 |
+| `library/addDependency` | `mcpp add <id>@<version> [--dev]` | 退出码；完成后重读 manifest/lock |
+| `extension` | `mcpp index update` | 退出码；与本地只读重载区分 |
 | `cliController.newProject` | `mcpp new <name>` | 退出码 |
 | `tasks.projectTaskPlan` | `mcpp build` / `run` / `test` / `clean` | 退出码（VS Code Task） |
 | `cliController.readToolchainInventory` | `mcpp toolchain list` | **人类文本**（正则解析） |
@@ -15,7 +20,7 @@
 
 `mcpp.path` 为空时用 `"mcpp"`，由 VS Code 进程的 `PATH` 解析。
 
-## 2. mcpp 已提供的稳定机读接口（本扩展未使用）
+## 2. mcpp 已提供的稳定机读接口
 
 mcpp 有正式的机读输出协议（`docs/50-machine-output.md`）。**检测规则**：解析 stdout，
 要求 `schemaVersion` 与 `kind` 存在；**不要**用退出码或"命令没报错"来判断支持与否。
@@ -78,3 +83,11 @@ mcpp 有正式的机读输出协议（`docs/50-machine-output.md`）。**检测
 3. `mcpp new <name>` 的模板不做 TOML/C++ 转义，且名字包含 `PROJECT` 时模板替换不终止
    （mcpp#380）；`newProject.ts` 因此做名称白名单校验。
 4. `--configure-only` 会写 `compile_commands.json`，成功条件是退出码 0 且该文件可解析。
+
+
+## Libraries 的 CLI 边界（本机 mcpp 2026.10.16.3 验证）
+
+- 官方索引位于 `<mcppHome>/indices/mcpplibs`；`registry/data/xim-pkgindex` 是工具索引，不能作为官方库缺失时的替代。旧版官方路径 `registry/data/mcpplibs` 仅作兼容。
+- `MCPP_HOME` 优先；CLI 还可能按可执行文件位置确定自包含 home，扩展应使用 `self env` 的答案，不能合并多个安装的同名索引。
+- `mcpp add --help` 只提供 `--dev`。没有 `--build`，也不承诺在普通与开发分组之间迁移声明；扩展对这两类清单编辑提供 TOML 预览与打开文件入口。
+- 当前环境平台来自 extension host，不能称为工程交叉编译目标或完整 ABI 兼容性结论。

.agents/docs/mcppls-integration.md

@@ -178,3 +178,13 @@ mcppls 侧发生以下任一变化时，本文件与 `src/languageServer.ts` 必
 - 平台矩阵变化；
 - 出现新的公开刷新/状态命令；
 - 服务器 `executeCommandProvider` 列表变化（影响 §3 的命名约束）。
+
+## 结构化模块图查询（2026-10-19）
+
+项目的共享依赖画布另通过依赖扩展随附的 mcppls CLI 调用
+`query module --graph --root <root> --timeout 20 --format json`。这与原有
+`mcppls.showModuleGraph` UI 转发入口并存，不解析那个命令生成的 Markdown。
+`modules{name,files,external}` / `imports{from,to}` / `snapshot` / `truncated`
+在消费边界校验，非零退出或不兼容结果可刷新重试。仅受信任工作区调用，宿主
+30 秒超时、8 MiB 输出限制；全图接口自身当前最多返回 500 个模块并标明截断。
+本扩展负责图布局、项目边界过滤和只读文件导航，C++ 语法与语义仍完全归 mcppls。