[Indexing] 项目索引：symbol index、依赖图、语义搜索和增量缓存

[v833]

标签建议：area/indexing, area/tools, priority/P1, type/feature, depends-on/indexing

背景

当前能力：

• q-code 已有 @file 文件引用、候选索引缓存、watcher 刷新、grep/glob/read_file 等基础代码定位能力。
• Agent 当前更多依赖文本搜索和文件读取，缺少结构化 symbol index、依赖图和语义搜索。
• 大仓库中，单纯递归搜索或读取文件容易慢、噪音高，并消耗上下文预算。

痛点：

• 用户问“这个函数在哪里被调用”或“改这个模块会影响哪里”时，Agent 需要多轮 grep 才能拼出答案。
• @file 候选能解决路径选择，但不能理解 symbol、import graph、test 关联和模块边界。
• 索引刷新如果阻塞 TUI，会影响输入体验；如果缓存过旧，又会给 Agent 错误上下文。

需要补齐：

• 项目级代码索引服务，覆盖文件、symbol、依赖、引用和测试关联。
• 增量缓存与 watcher，启动可用旧缓存，后台刷新。
• 面向 Agent 工具的低噪音查询接口。

目标

实现项目索引与代码智能检索：建立 symbol index、依赖图、语义搜索和增量缓存，为 @file、工具搜索、Agent 上下文注入和验证策略提供更快、更准、更低噪音的代码定位能力。

用户故事

• 作为开发者，我希望输入函数名就能定位定义、引用和相关测试，以便快速理解代码影响面。
• 作为 Agent，我希望通过结构化工具查询 symbol 和依赖图，以便减少盲目 grep 和大段文件读取。
• 作为大仓库用户，我希望索引后台刷新且不会卡住 TUI 输入，以便启动后马上可用。
• 作为维护者，我希望索引缓存格式可版本化和失效，以便升级后不会使用错误缓存。

详细需求

1. 文件与 symbol index

• 在 <cwd>/.q-code/ 下维护项目级索引缓存，避免纳入提交。
• 支持 TypeScript/JavaScript 的 symbol 定义、export/import、文件摘要、mtime/hash。
• 索引结构需要版本号，版本不匹配时自动重建。

2. 依赖图与影响面

• 建立文件级 import graph，支持查询上游/下游依赖。
• 支持从变更文件推导可能相关测试文件。
• 循环依赖、路径 alias 和 barrel export 应有保守处理。

3. 语义搜索

• 提供可选语义搜索接口，默认不能要求外部服务才能启动。
• 无 embedding provider 时降级为 lexical/fuzzy 搜索。
• 语义索引不得上传源码，除非用户明确配置外部 provider。

4. 增量刷新

• 启动时可先读取旧缓存，后台刷新。
• watcher 失败不得阻塞输入，保留旧索引并显示简短提示。
• 忽略目录遵循 gitignore、现有 file mention ignore 和 Q_CODE_FILE_INDEX_IGNORE。

5. 工具接口

• 提供 Agent 可调用的查询能力，例如 find symbol、references、dependency impact、related tests。
• 查询结果应有预算限制、排序和摘要，避免把大仓库全部塞进上下文。
• 查询行为写入审计日志但不泄露不必要的源码全文。

输出样例

q-code index status

文件: 1,284 indexed / 7 skipped
Symbols: 9,812
Graph edges: 2,346
Cache: .q-code/code-index.json
Status: fresh

查询结果示例：

find_symbol SessionStore
- src/session/store.ts:42 export class SessionStore
- tests/unit/session-management.test.ts:17 import { SessionStore }

验收标准

• TypeScript/JavaScript 文件能建立 symbol 定义和 import graph。
• 索引缓存写入 <cwd>/.q-code/，带版本号且不会纳入提交。
• 启动可使用旧缓存并后台刷新，刷新失败不阻塞 TUI。
• 支持查询 symbol 定义、引用、依赖影响面和相关测试候选。
• 大文件、node_modules、dist、coverage、.q-code 等目录默认忽略。
• 无语义搜索 provider 时功能可降级，不影响启动。
• README/AGENTS 更新索引缓存、忽略规则和工具说明。
• 单元与集成测试覆盖缓存、watcher、路径安全和查询排序。

测试方案

• tests/unit/file-index-cache.test.ts：扩展覆盖索引版本、失效和后台刷新。
• tests/unit/code-index.test.ts：覆盖 symbol 提取、import graph、ignore 规则和查询排序。
• tests/unit/file-mentions.test.ts：确认 @file 与新索引兼容。
• tests/integration/indexing-flow.test.ts：在 fixture workspace 中覆盖增量修改、删除、重命名。
• 手动验证：大仓库首次启动、缓存命中、watcher 失败、Windows 路径大小写。

不在本期范围

• 完整 LSP server 替代。
• 所有语言的一等支持；本期优先 TypeScript/JavaScript。
• 云端代码索引服务。
• 自动重构或代码生成。

依赖 / 风险

• 与现有 src/mentions 候选索引共享边界，需避免重复缓存和 watcher 冲突。
• 大仓库索引可能消耗 CPU/IO，需要后台、节流和预算限制。
• 语义搜索涉及源码隐私，默认必须本地优先且可关闭外部上传。
• 路径安全和 symlink 解析必须沿用现有文件工具约束。

工作量评估

• Symbol/index cache 基础：2 人日
• Import graph 与影响面：2 人日
• 工具查询接口与预算：1.5 人日
• 增量 watcher、测试和文档：2 人日
• 合计：~7.5 人日