# 路线图与已知限制 / ROADMAP

本文件记录 Project Compass（项目罗盘）**尚未实现**的能力、**已知限制**，以及每项的计划方向。
写在这里的东西**不是现有功能**——现有能力见 [README](../README.md#能力矩阵) 与 [TOOLS.md](TOOLS.md)。

> 原则：先把「确定性、可验证、零依赖」这条主干做扎实，再谈增强。
> 任何新能力都必须回答三个问题：会不会引入依赖？会不会破坏可复现性？会不会扩大隐私边界？

- [版本规划](#版本规划)
- [已知限制](#已知限制)
  - [解析精度](#解析精度)
  - [依赖关系](#依赖关系)
  - [检索质量](#检索质量)
  - [报告与叙述](#报告与叙述)
  - [性能与规模](#性能与规模)
  - [平台与运行环境](#平台与运行环境)
- [计划中的能力](#计划中的能力)
- [明确不做的事](#明确不做的事)
- [怎么提需求](#怎么提需求)

---

## 版本规划

| 版本 | 主题 | 内容 |
| --- | --- | --- |
| **0.1.0** | 主干打通 | FR1–FR12 全覆盖：项目扫描、多语言解析（**零依赖自研抽取，非 Tree-sitter**）、统一 IR、依赖图谱、增量缓存、LLM 摘要与验证、RAG 问答、报告生成、DSH 工具注册、配置与预算（**FR10 的流式进度受宿主能力限制，见下文限制表**）、多角色报告、安全隐私 |
| 0.2.x | 精度与体验 | 路径别名解析、增量图算法、报告章节可配置、`ask` 多轮上下文、忽略规则的调试输出增强 |
| 0.3.x | 语言与解析 | 真 AST 解析（可选）、更多语言的深度解析、tree-sitter 可选后端 |
| 1.0 | 稳定承诺 | `schemaVersion` 冻结、公共 API 稳定、性能基线公布 |
| 之后 | 生态 | 远程嵌入（可选）、编辑距离感知的符号改名影响分析、SARIF / 结构化输出、多仓库视图 |

---

## 已知限制

这一节很重要：**下面每一条都是当前版本真实存在的不足**，请按你的场景评估影响。

### 解析精度

| 限制 | 影响 | 现状 |
| --- | --- | --- |
| **不是真 AST** | 无法做类型推断、重载解析、泛型消解、模板/宏展开 | 行扫描 + 括号/缩进配平。符号名与行号可靠，语义分析不可靠 |
| **深度解析只覆盖 TS/JS/TSX/JSX、Python、Java** | 其余语言只能拿到顶层声明、import、TODO，符号稀疏 | 其它语言走 `generic.js` 轻量抽取，输出同构但信息少 |
| **词法级解析对宏/元编程无感** | 装饰器生成的方法、动态定义的属性可能漏报 | 宁可少报，不猜 |
| **`endLine` 在极端缩进风格下可能偏大** | 影响 LOC 统计与分块边界 | 以行为主，宁可标长不标短 |
| **Markdown / YAML / JSON 只做结构级抽取** | 文档里的「架构说明」不会被当作知识来源（只被引用为文档存在证据） | 文档内容仅用于检索分块的 `doc` 类型 |

### 依赖关系

| 限制 | 影响 | 现状 |
| --- | --- | --- |
| **不做路径别名解析** | 用 `tsconfig paths` / webpack alias / `PYTHONPATH` 的项目，跨包 import 会记 `resolved: false`，图中跨模块边偏少 | 明确不猜。报告里会体现为 `unresolved` 较多 |
| **动态 import / 反射 / 依赖注入容器的绑定不解析** | `import(expr)`、`getBean(name)`、注解注入的调用链会断 | 记为 `unresolved` |
| **不做运行时追踪** | 无法知道真实执行路径，链路是静态推断 | 每条链路带 `confidence`，并列出未识别的入口 |
| **循环检测有规模上限** | 超大图只报告有限数量的循环 | 达到上限会在 `warnings` 说明 |
| **图是快照，不是持续同步** | 不监听文件变化；改动后需要 `update` | 由 `status` 的 `stale` 标记提示 |

### 检索质量

| 限制 | 影响 | 现状 |
| --- | --- | --- |
| **本地确定性向量泛化能力弱** | 提问用词与代码用词差异很大时，向量召回不如真嵌入模型 | BM25 是主力，向量补充模糊匹配 |
| **不联网** | 没有远程嵌入、没有云端重排 | 有意如此，保证离线与可复现 |
| **默认抽取式回答** | 不会「总结成一段流畅的话」，只是把有出处的片段组织起来 | 这是刻意的：不生成没有出处的句子 |
| **中文问答依赖标识符与注释的英文词形** | 纯中文提问 + 纯英文命名的项目，召回依赖路径与注释 | 建议提问时带上模块名/文件名 |
| **单轮检索** | 复杂问题需要拆成多个具体问题 | 多轮上下文在计划中 |
| **索引规模受 `maxChunks` 约束** | 超大仓库可能只能索引一部分，`ask` 的召回范围随之受限 | 触顶会在 `notes` 说明 |

### 报告与叙述

| 限制 | 影响 | 现状 |
| --- | --- | --- |
| **报告语言只有中文** | 英文团队读起来有门槛 | 标识符、字段名、JSON 是语言中立的；`locale` 选项已在契约中预留 |
| **章节结构固定** | 不能按团队偏好增删章节 | 可配置模板在计划中 |
| **Mermaid 图节点上限默认 40** | 超大模块图会被裁剪 | 图下方明确标注裁剪与被裁节点数 |
| **「职责」描述基于符号与命名** | 命名差的模块描述会偏空 | 有 LLM 时更顺，但事实仍来自确定性分析 |
| **无证据的推断只能标「未验证」** | 报告会显得保守 | 这是产品承诺，不会为了「好看」而放宽 |

### 性能与规模

| 限制 | 影响 | 现状 |
| --- | --- | --- |
| **预算默认有上界** | 超大仓库默认会触顶（`maxFiles` 20000 / `maxTotalBytes` 64 MiB / `maxDurationMs` 10 分钟） | 触顶明确打标，绝不静默 |
| **单线程 JS 解析** | 并发只掩盖 I/O 延迟，CPU 侧无法并行 | 提高 `concurrency` 收益有限 |
| **`update` 会重算整图** | 图算法是纯计算但仍是全量；超大图下 `update` 不是严格 O(变更) | 增量图算法在计划中 |
| **索引全量重建分块** | `update` 后受影响分块会被重建 | 增量分块在计划中 |
| **缓存体积可达源码的 1–3 倍** | 磁盘占用 | 缓存纯派生，可随时删 |
| **无流式进度（宿主能力限制）** | 大仓库分析期间只有等待。`analyze` 内部已有 `onProgress({phase,done,total,message})` 回调，但宿主 `ToolDefinition` 未提供进度通道（只有 `deferContext` / `concludeTurn`），事件表也没有可发射的进度事件，**插件侧无法把进行中的进度透出** | 工具返回耗时与预算消耗，便于事后判断；宿主一旦提供进度通道，插件只需把已有回调接上去 |

### 平台与运行环境

| 限制 | 影响 | 现状 |
| --- | --- | --- |
| **需要 Node ≥ 20.11** | 更老的运行时不可用 | 依赖内置 `node:test` 等能力 |
| **CLI 通道无 LLM 能力** | `scripts/compass-cli.mjs` 里 LLM 相关能力降级 | 它不经过 DSH 宿主，拿不到 LLM 服务 |
| **未做符号链接环检测以外的特殊文件系统处理** | 极端挂载（网络盘、大小写敏感切换）行为未专门验证 | 忽略规则与相对路径实现是平台无关的 |
| **Windows 路径** | 跨平台使用正斜杠，产物中一律 posix 相对路径 | 已按 `toPosix` 统一，但未在 Windows CI 上验证 |

---

## 计划中的能力

### 近期（0.2.x）

| 能力 | 说明 | 为什么值得做 |
| --- | --- | --- |
| **路径别名解析（可选）** | 读取 `tsconfig.json` / `jsconfig.json` 的 `paths`、webpack/vite alias、`setup.py`/`pyproject` 的包配置，把别名映射为真实路径 | 别名是当前 `unresolved` 的主要来源，直接决定跨模块图质量 |
| **增量图算法** | 只重算受影响子图的扇入扇出、可达性与环检测 | 让 `update` 在大仓库上真正廉价 |
| **增量分块与索引** | 只为变化文件重建分块与其向量 | 同上，问答的刷新成本 |
| **进度流式透出（依赖宿主）** | 需宿主在 `ToolDefinition` 或事件表提供进度通道；插件侧 `onProgress({ phase, done, total, message })` 已就绪，属「接线」工作量（S） | 大仓库一次分析可能数十秒，没有进度就只能干等；这是 FR10 中唯一未交付的一项，且成因在宿主而非插件 |
| **`ask` 多轮上下文** | 允许把上一轮的引用作为本轮检索的偏置 | 追问「那它的调用方呢」是最高频的用法 |
| **忽略规则调试** | 提供「这个路径为什么被忽略 / 为什么没被忽略」的逐步说明 | 忽略规则是当前最容易被误配的部分 |
| **报告章节可配置** | 通过配置选择章节集合与顺序 | 不同团队关心的章节差异很大 |

### 中期（0.3.x）

| 能力 | 说明 | 权衡 |
| --- | --- | --- |
| **真 AST 解析** | 为 TS/JS 与 Python 实现真正的语法解析（自研或可选后端） | 精度提升明显，但要小心容错性退化：畸形文件不能被整体放弃 |
| **tree-sitter 可选接入** | 作为**可选**后端，装在才用；不装则回落到行扫描 | 需要原生模块 → 必须与「零依赖」并存为可选项，绝不设为默认 |
| **更多语言的深度解析** | Go、Rust、C# 优先（结构规整、路由/接口模式清晰） | 每门语言都需要自己的符号与调用模式，成本线性增长 |
| **风险评分模型可调** | 把权重暴露为配置，并在报告里保持「理由与分数一致」 | 让评分贴合团队的实际关注点 |
| **未使用符号 / 死代码识别** | 基于扇入为零 + 非入口生成候选清单 | 只能给候选（动态派发会让静态分析漏报） |

### 远期

| 能力 | 说明 |
| --- | --- |
| **远程嵌入（可选）** | 接入真嵌入模型提升语义召回；必须显式开启，且与本地模式产物可区分（记录在 `meta` 里） |
| **改名影响分析** | 给定一个符号，输出所有需要同步修改的位置，含跨模块 |
| **SARIF / 结构化输出** | 让架构约束检查能进现有代码扫描平台 |
| **多仓库视图** | 分析一组相关仓库（微服务群）并给出跨仓库依赖与调用关系 |
| **报告国际化** | `locale: 'en'` 输出英文报告（标识符与 JSON 已语言中立） |
| **项目级配置** | 把配置随仓库走（例如 `<项目>/.compassrc.yml`），团队共享同一套忽略与预算 |
| **PR 增量评审模式** | 只分析本次 PR 触及的文件与其影响面，输出「这个改动动了哪些模块、影响了谁」 |

---

## 明确不做的事

有些事看起来相关，但本插件**不打算做**——写下来是为了避免误解：

| 不做 | 原因 |
| --- | --- |
| **自动改写代码 / 重构** | 本插件是**读取与说明**工具，不是代码修改工具。它给你上下文，改动由你和 Agent 决定 |
| **执行项目里的任何命令** | `scan` 只报告发现了哪些命令（含来源），**从不执行**。这与「不改变你的项目状态」这条边界一致 |
| **读取敏感文件内容** | 无论配置怎么设，敏感路径只 `stat`。这是红线，不提供绕过开关 |
| **回传任何遥测 / 统计** | 本插件没有任何上报通道 |
| **默认联网** | 默认零网络请求。LLM 与远程嵌入都必须是显式开启的选项 |
| **替代人的架构判断** | 它给出结构化事实与证据，结论由人做。所有无证据推断都标「未验证」 |
| **覆盖其他语言的全部语法特性** | 目标是把常见的结构讲清楚，不是做编译器前端 |

---

## 怎么提需求

- **功能请求**：请描述「你想回答什么问题」，而不只是「加一个字段」——很多时候现有能力配上
  正确的问法就能解决，或者需要的是新的报告章节而不是新工具。
- **限制反馈**：如果你踩到上面「已知限制」里的某一条并造成了实际困扰，请附上项目特征
  （语言、规模、是否用别名、是否 monorepo），我们会据此排优先级。
- **精度问题**：**行号或符号报错是最严重的一类缺陷**（会直接污染报告与问答）。
  请附最小复现片段 + 期望结果，这类问题的修复优先级最高。
- 流程见 [CONTRIBUTING.md](../CONTRIBUTING.md)，安全问题见 [SECURITY.md](../SECURITY.md)。