必须在项目根目录运行cody index构建本地代码图，并启用"cody.experimental.localgraph": true配置，确保vscode工作区路径与索引路径一致，且语言服务器稳定。
VSCode 配置 Cody AI 读取整个项目代码库的关键前提
Cody AI 要真正理解你的本地项目，不是靠“打开文件”就能自动推断上下文的。它依赖明确的代码索引（code graph）和项目结构感知，而 VSCode 默认不提供这个能力——必须通过 Cody 官方 CLI cody 在本地构建并维护一个符号数据库。
常见错误现象包括：Cody 回答泛泛而谈、无法定位函数定义、对跨文件调用关系一无所知、提问“这个 service 是怎么被 controller 调用的”直接返回“我不清楚”。这些都不是模型问题，而是它根本没看到你的完整代码树。
- 必须在项目根目录运行
cody index（不是cody init），且该命令需识别到package.json、pyproject.toml、go.mod等语言标识文件 - 索引过程会扫描所有
**/*.ts、**/*.py等源码，但默认跳过node_modules/、venv/、.git/—— 若你有自定义的生成代码目录（如src/gen/），需手动加到.codyignore - 首次索引耗时取决于项目大小：10 万行 TypeScript 项目约需 2–5 分钟；若卡在 “Scanning files…” 超过 10 分钟，大概率是权限问题或符号链接环（
ls -la | grep "\->"检查）
确保 Cody 插件加载本地索引而非仅依赖云端上下文
Cody VSCode 插件有两个独立的上下文来源：一个是当前编辑器打开的文件（轻量级），另一个是你本地运行 cody index 后生成的 .cody/ 目录（全量）。后者才是理解复杂项目的核心，但插件默认可能只用前者。
检查是否生效最直接的方式：在任意未打开的 .ts 文件里右键 → “Ask Cody about this file”，如果返回 “No local code graph available”，说明插件没连上本地索引。
- 确认 VSCode 设置中启用了本地索引支持：
"cody.experimental.localGraph": true（写入.vscode/settings.json，不是用户设置） - 必须重启 VSCode 或重新加载窗口（
Ctrl+Shift+P→Developer: Reload Window），因为插件在启动时才读取该配置 - 路径必须严格匹配：Cody CLI 运行
cody index的目录，要和 VSCode 打开的工作区根目录完全一致（不能是子文件夹，也不能是符号链接路径） - Linux/macOS 用户注意：若用
zsh启动 VSCode（如终端执行code .），确保cody命令在$PATH中；否则插件找不到 CLI，会静默降级为无索引模式
处理多模块/单体仓库（monorepo）的典型陷阱
像 Nx、Turborepo、pnpm workspaces 这类结构，Cody 默认只索引工作区根目录，不会递归进 packages/ 或 apps/ 子目录——即使它们有独立的 tsconfig.json。
结果就是：你在 packages/ui/src/Button.tsx 里问“Button 组件被哪些测试文件 import 了？”，Cody 只能查到同目录下的 __tests__/，却找不到 apps/web/src/pages/Home.test.tsx 里的引用。
- 方案一（推荐）：在每个子包根目录下单独运行
cody index，然后在各自.vscode/settings.json中设"cody.codebase": "file:///full/path/to/packages/ui" - 方案二：用
cody index --include="packages/**/src/**/*.{ts,tsx,js,jsx}"强制指定路径，但需确保.codyignore不拦截这些 glob - 绝对不要依赖
"cody.codebase": "file://./"这种相对路径，Cody 插件解析时容易出错，尤其在远程开发（SSH/Dev Container）场景下
为什么改了代码后 Cody 还“不知道”？增量索引没生效
cody index 不是监听文件变化的守护进程。它是一次性构建操作。你新增一个 utils/date.ts，或者重命名了 services/auth.ts → services/authentication.ts，Cody 依然沿用旧索引，直到你手动重建。
这不是 bug，是设计权衡：实时监听会显著增加 CPU 和内存占用，尤其对大型项目。
- 日常开发中，建议把
cody index加进 pre-commit hook 或 CI 流程，而不是每次改完立刻跑 - 快速验证索引更新：删掉
.cody/目录 + 重新运行cody index，比尝试cody index --incremental更可靠（后者在重命名/移动文件时经常漏掉引用） - VSCode 状态栏右下角会显示 “Cody: Indexed N files” —— 这个数字必须和你
find . -name "*.ts" | wc -l的结果接近，否则说明部分文件被过滤了（查.codyignore或日志输出）
最常被忽略的一点：Cody 的本地索引能力高度依赖语言服务器（LSP）的稳定性。如果你的项目里 typescript-language-server 或 pyright 报错、反复崩溃，Cody 的符号解析就会退化成纯文本匹配——这时候再怎么配 cody.index 都白搭。先确保 Ctrl+Click 能正常跳转定义，再折腾 Cody。
