这份记录用来说明 CodeAtlas 里几个主要取舍。它不是完整设计文档，只记录当前版本为什么这么做，以及哪些地方还没做扎实。
一开始没有直接上向量库，主要是为了把主流程先跑通。这个项目最早要验证的是：仓库能不能导入，文件能不能被索引，模型能不能通过工具找到证据，回答能不能返回路径和行号。
所以当前索引只做了三件事：
- 跳过
.git、node_modules、.next、dist等噪声目录。 - 过滤二进制文件和过大的文件。
- 把文本文件按固定行数切成 chunk，保存相对路径、起止行号、语言和哈希。
这样检索质量不算强，但实现可控，测试也容易写。以后如果改成向量检索或重排，可以复用现有的 FileChunk 表结构和工具接口。
我没有把整个仓库拼进 prompt。仓库一大就会有三个问题：上下文成本高、噪声多、很难追踪模型到底依据了什么。
当前做法是把仓库访问收口到四个工具：
list_repo_tree: 先看目录结构。search_repo: 通过关键词找候选片段。read_file: 读取指定文件的行范围。find_symbol: 查找可能的函数、类或导出符号。
回答时会记录工具名、参数摘要和返回数量。这个记录不复杂，但能让用户复核模型是不是确实读了相关文件。
直接让模型改文件风险太高，尤其是多人协作或用户同时在编辑文件时。当前流程拆成了两步：
- 先生成完整文件草案和 unified diff。
- 用户确认后再应用。
应用前会重新读取目标文件，并和草案生成时的 base_content_sha256 比较。如果文件已经变了，后端会拒绝写入。批量 apply 也是先全部校验，再开始写文件，避免只写成功一半。
这个方案还有局限：草案依赖模型返回完整文件内容，所以只适合较小文件。更稳的做法应该是结构化 patch 或局部 diff。
项目里有“应用并验证”的流程，但我不希望后端执行任意命令。现在只根据仓库结构发现有限命令，例如：
python -m pytest testsnpm run typechecknpm run lintnpm run test
运行时用固定参数、固定工作目录，并设置超时和输出截断。这样验证能力比较弱，但执行风险也更低。
后端测试更关注几类容易出错的地方：
- 仓库路径必须限制在 root 内。
- 索引后能通过工具搜索、读取文件、定位符号。
- 问答接口会保存 trace。
- stale patch 会被拒绝。
- 批量 apply 遇到冲突时不会提前写入部分文件。
- checks 失败后，本次写入会被回滚。
- 中英文响应头能影响错误信息和部分输出。
前端目前还缺少自动化交互测试，这一点还没有补上。
- 检索结果排序比较粗糙，复杂问题下容易漏掉相关文件。
find_symbol不是 AST 解析，只能算轻量定位。- 后台任务没有持久化队列，服务重启后的恢复能力有限。
- 没有鉴权和多用户隔离，不适合直接暴露到公网。
- 还没有在几个真实项目上系统记录问答效果。
这些限制没有写成已经完成的能力，因为它们确实还只是待办。