本文件是 Project Compass（项目罗盘）6 个模型可见工具与 /compass 命令的完整参考。

工具的真实契约是 lib/tools.js 里注册的 JSON Schema 与实现。本文与实现不一致时， 按代码为准，并把它当成文档缺陷上报。

• 调用约定
• project_compass_scan
• project_compass_analyze
• project_compass_report
• project_compass_ask
• project_compass_update
• project_compass_status
• 典型调用序列
• AI Agent 如何用 project_compass_ask 获取项目上下文
• 错误与降级行为
• /compass 命令
• 命令行自测通道

多数工具只返回摘要视图（模块概览、计数、枢纽、流程清单等），完整数据落盘在 ir.json。 这样做的目的是让工具返回值保持小巧——需要细节时读产物，而不是把整个 IR 塞进上下文。

用途：侦察项目并生成结构化「项目画像」（第一步）。目录扫描、忽略规则、语言分布、技术栈与 包管理器、可执行命令、入口点、配置 / CI / 容器 / IaC、测试框架，以及已能确定的工程缺口。

结论全部来自磁盘证据，不含猜测；敏感文件只登记路径与类型，绝不读取内容。

参数

返回字段

产物：<项目>/.project-compass/scan.json（完整 Profile，字段远多于上面的摘要）。

备注

• 敏感登记只出现在 sensitive 与 stats.secretSuspects（计数）里，没有内容；
• commands 只报告「发现」了什么命令，不执行任何命令；
• 单次 scan 不做深度解析，符号 / 导入 / 调用 / 路由属于 analyze。

用途：解析代码并构建统一中间表示（IR）与依赖知识图谱（第二步）：多语言符号 / 导入 / 调用 / 路由抽取 → 模块·文件·符号三级依赖图 → 关键流程识别。

基于内容哈希做增量：未变更的文件直接复用上次解析结果，只有内容、语言或解析器版本变化才重新解析。 跨文件绑定只走显式 import 声明，无法确定的一律标记为未解析——宁可断边也不猜。

参数

本工具不接受 withLlm：分析阶段不调用 LLM，叙事增强属于 report。

返回字段

产物：<项目>/.project-compass/ir.json（完整 IR）+ .project-compass/cache/（解析缓存）。

备注

• 已有画像时直接复用（不重复扫描）；没有画像时先扫描一次并落盘；
• warnings 里可能出现「未解析调用占比过高」这类提示，此时应下调对图的信任度， 并用 ask 补充验证。

用途：生成面向开发者的入门报告（第三步），输出 6 份产物： ONBOARDING.md、ARCHITECTURE.md、MODULE_MAP.md、KEY_FLOWS.md、GETTING_STARTED.md、 project-compass.json。

报告包含 Mermaid 架构图与依赖图、关键调用链时序图、按角色（后端 / 前端 / 测试 / 运维 / 数据） 的阅读路线，每条结论都附 path:line 证据。默认不调用 LLM——全部结论来自静态证据。

参数

返回字段

产物：<outputDir>/ 下 6 个文件（默认 docs/project-compass/）。结构与字段见 OUTPUT-FORMAT.md。

LLM 与验证器：withLlm: true 时使用会话默认模型（或在配置里指定 provider/model）润色叙事， 并且每一条 LLM 声明都必须带引用并通过验证器（路径存在于 IR、行号落在 1..loc 内、 符号能在 IR 中找到）。验证不通过的声明直接丢弃，条数计入 llm.droppedClaims 与报告元信息。 如果配置里 llm.enabled 为 false 而调用方传了 withLlm: true，会记录一条 warning 并尝试使用 会话默认模型。

前置条件：需要已有 IR；没有会明确报错并提示先调用 analyze。

用途：就项目提问并获得带引用的答案。本地 BM25 + 向量混合检索 → RRF 融合 → 重排， 命中源码分块后给出结论与 path:line 证据。默认抽取式回答，不联网、不调用 LLM。

参数

返回字段

产物：不留报告文件；问答留痕追加到 <项目>/.project-compass/qa-log.jsonl（留痕失败不影响回答）。

前置条件：需要已有 IR；没有会明确报错并提示先调用 analyze。

隐私：默认模式下提问内容与命中片段只在本机处理；withLlm: true 才会把检索到的片段作为 唯一事实来源交给模型润色。

用途：增量更新分析结果与报告（第四步）：重新扫描 → 只重新解析变更文件 → 刷新 IR / 图谱 / 流程 → 增量更新检索索引 → 重新生成报告。

参数

返回字段

产物：刷新 .project-compass/scan.json、ir.json、index.json，并按需重写报告。

边界：如果从未分析过（没有 IR），update 不会报错，而是做一次全量分析并在 summary 里明确写出「此前没有分析基线，本轮做了全量分析」——全量与增量的成本差异必须让调用方知情。

用途：查看当前项目的罗盘状态。不修改任何文件。 适合回答「这个项目分析过没有」 「报告在哪」「结果是不是过时了」。

参数

返回字段

典型返回（示意）

{
  "analyzed": true,
  "hasScan": true,
  "hasIndex": true,
  "artifacts": {
    "onboarding": { "path": "/repo/app/docs/project-compass/ONBOARDING.md", "exists": true, "bytes": 18240 }
  },
  "ir": { "stats": { "files": 213, "symbols": 1480, "routes": 26 }, "truncated": false },
  "cache": { "files": 131, "bytes": 4980736 },
  "index": { "chunks": 2140, "files": 198 },
  "nextSteps": ["调用 project_compass_ask 就具体功能提问（带引用回答）"],
  "summary": "已分析：213 文件 / 1480 符号 / 26 路由；报告产物 6/6 份；缓存 131 个条目（4864 KB）；索引 2140 块"
}

project_compass_status  { projectPath }              # 先确认状态，避免重复大分析
project_compass_scan    { projectPath }              # 快速看清这是什么项目（可选，analyze 会复用画像）
project_compass_analyze { projectPath }              # 解析 + IR + 图谱（首次可能较慢）
project_compass_report  { projectPath }              # 生成 6 份产物 + 检索索引
project_compass_ask     { projectPath, question: "认证流程经过哪些模块？" }

project_compass_update  { projectPath }              # 只重算变更文件，刷新 IR/索引/报告

project_compass_status  { projectPath }              # 有 IR 就直接问
project_compass_ask     { projectPath, question: "订单金额在哪里计算？" }

project_compass_status  { projectPath }                          # 看 artifacts 与 nextSteps
project_compass_analyze { projectPath }                          # 增量
project_compass_analyze { projectPath, force: true }             # 强制全量重算
project_compass_ask     { projectPath, question: "…", rebuildIndex: true }

这一节写给「读这段文档的模型」：在动手改代码之前，用 ask 换取有出处的上下文， 而不是靠猜或靠零散 grep。

推荐流程

1. 先看状态，别急着重算

   { "projectPath": "/repo/app" }

   用 project_compass_status 确认是否已有 IR 与索引。analyzed: false 时先 analyze； 已有 IR 但代码刚改过，就用 update。

2. 用具体问题换带引用的答案

   { "projectPath": "/repo/app", "question": "登录流程经过哪些模块？" }

   返回里的 citations[] 是硬通货：path + line 指向真实代码位置，why 说明它支撑了哪条结论。 只使用 citations 里出现过的路径与行号去引用代码。

3. 校验后再引用

   如果答案里出现了一个文件名，但 citations 里没有它，就不要把它写进回答或改动计划。 这是本工具的核心承诺：验证器只放行能在 IR 中核对到的路径、行号与符号。

4. 读置信度决定后续动作

   confidence	建议动作
   high	可以直接据此规划；引用时带上 path:line
   medium	顺着 relatedSymbols / relatedFlows 再读两三个文件确认边界
   low	当成线索而不是结论：换更具体的问法（带上模块名、函数名、报错信息），或用 rebuildIndex: true 重建索引后重试

5. 顺着结果继续追问，而不是重新开一轮

   { "projectPath": "/repo/app", "question": "createSession 被哪些地方调用？改动它的返回值会影响谁？" }

   relatedFlows 给出这条链路在 KEY_FLOWS.md 里的对应条目，可以对照报告一起看。

6. 要长期上下文就生成报告，而不是反复问

   如果你需要的是「整个项目的地图」，一次 project_compass_report 产出的 6 份产物比十次问答更省上下文； 之后把 Markdown 当资料读，只在具体问题上用 ask。

7. 一次问一个问题，并把答案里的引用当唯一事实来源

   多个不相关问题混在一句里会让检索分散命中、置信度下降。拆分提问，并用 limit 控制证据条数 （默认 8；要更宽的召回可以到 20–30，但要注意上下文成本）。

提问技巧

只有入参非法或前置产物缺失才抛错，其余一切情况都尽量返回可用结果：

参数校验集中在 lib/tools.js——这是全插件唯一因为入参问题抛错的地方。

设计原则：分析失败不应该让工具失败。缓存损坏、单个文件畸形、缺 LLM 服务，都不应阻断 「拿到一份可用的项目画像」这件事。

面向人的命令入口，一个命令 + 子命令：

/compass status
/compass analyze
/compass report
/compass ask 登录流程经过哪些模块？

不需要 DSH 宿主即可自测同样的链路：

node --test
node scripts/compass-cli.mjs analyze <项目路径>
node scripts/compass-cli.mjs report  <项目路径>
node scripts/compass-cli.mjs ask     <项目路径> "登录流程经过哪些模块？"
node scripts/compass-cli.mjs status  <项目路径>

CLI 与工具走同一条实现路径，因此可以放心用它做回归；区别是它不经过宿主， 因此 llm.* 相关能力不可用（按「宿主无 LLM 服务」降级）。