排期按照单人全职开发估算。 每个 Sprint 为一周（5 个工作日），共 7 个 Sprint。 每个 Sprint 结束时有一个可验证的交付物。 铁律：每天结束时代码必须能跑，不允许"写了一半明天继续"的状态。
上午：
☐ 创建 Python 项目结构（pyproject.toml / src / tests）
☐ 创建虚拟环境，安装核心依赖
☐ 配置 .env（GitHub Token + Google API Key）
☐ 配置 .gitignore，git init，首次提交
下午：
☐ 写一个最简单的 LangGraph 图（2 个节点，1 条边），确认框架能跑通
☐ 写一个最简单的 GitHub API 调用，确认 Token 有效、能拿到数据
☐ 写一个最简单的 Gemini API 调用，确认模型能响应
☐ 三个都跑通后，提交代码
Sprint 0 验收标准：
python -m reposense能运行不报错- GitHub API 能返回任意一个仓库的信息
- Gemini 能返回一段文本
- 代码已提交到 Git
为什么要有 Sprint 0： 真实项目中，环境问题浪费的时间比你想象的多。API Key 配错、版本冲突、依赖装不上——这些琐事必须在第一天全部解决，不能拖到功能开发时才发现。
Day 2（周二）：仓库元信息 + 目录树
☐ 实现 GitHubClient 类，封装认证和基础请求
☐ 实现 get_repo_meta() — 名称、描述、语言、star、fork、最近提交时间
☐ 实现 get_file_tree() — 递归获取完整目录树
☐ 对 3 个不同仓库测试，确认数据正确
☐ 编写单元测试
Day 3（周三）：文件内容获取 + 缓存
☐ 实现 get_file_content() — 获取单个文件内容（处理 Base64 解码）
☐ 实现文件内容缓存 — 读过的文件存在内存中，不重复请求
☐ 处理二进制文件（图片、字体等）— 识别并跳过
☐ 处理大文件（>1MB）— 跳过并标注
☐ 编写单元测试
Day 4（周四）：Issue 获取 + 错误处理
☐ 实现 get_issues() — 获取 Open Issues，支持标签筛选
☐ 实现 API 限流处理 — 检测 429 状态码，指数退避重试
☐ 实现请求超时处理 — 5 秒超时，3 次重试
☐ 实现错误日志 — 每次失败记录原因，不静默吞掉错误
☐ 编写单元测试
Day 5（周五）：集成测试 + 文档
☐ 用 5 个不同规模的仓库做集成测试：
- 小型：< 50 文件（某个个人项目）
- 中型：100-500 文件（如 click、httpx）
- 大型：> 1000 文件（如 langgraph、fastapi）
☐ 记录每个仓库的 API 调用次数和耗时
☐ 修复发现的边界情况
☐ 提交代码，写本周小结
Sprint 1 验收标准：
- 对任意公开 GitHub 仓库，能稳定获取元信息、目录树、文件内容、Issue 列表
- API 限流时自动重试而不是崩溃
- 有完整的单元测试覆盖
- 5 个测试仓库全部通过
这周的踩坑记录（面试素材）：
- GitHub API 返回的文件内容是 Base64 编码的，需要解码
- 目录树 API 对超过 100,000 个文件的仓库会截断，需要递归获取
- 二进制文件解码会报错，需要提前识别跳过
- API 限流的 Reset 时间在响应头里，可以精确等待而不是盲目重试
Day 6（周一）：State 定义 + 路由节点
☐ 定义 RepoSenseState（整合之前讨论的五类上下文）：
- 仓库上下文：repo_url, repo_meta, file_tree, file_contents
- 对话上下文：messages, current_intent, selected_issue, focused_files
- 索引状态：index_built
- 分析缓存：code_summaries, directory_summaries
- 控制变量：react_loop_count, token_budget_remaining
☐ 实现路由节点 — 判断用户意图（扫描/问答/贡献）
☐ 编写路由节点的测试用例
Day 7（周二）：扫描节点 + 三级漏斗策略
☐ 实现扫描节点的三级漏斗：
第一级：目录树扫描
- 将完整目录树发给 LLM
- LLM 返回：每个顶层目录的职责标注 + 核心目录列表
第二级：文件级摘要
- 对核心目录下的文件，提取前 50 行 + 函数/类签名
- LLM 返回：每个文件的一句话摘要
第三级：关键文件深读
- 对 LLM 标记为"关键"的文件，读取完整内容
- LLM 返回：详细的逻辑分析
☐ 每一级都有 Token 计数，超过预算停止并输出已有结果
Day 8（周三）：分析节点 + Prompt 工程
☐ 设计分析 Prompt（最关键的一天）：
- System Prompt：角色定义 + 输出格式要求 + 防幻觉指令
- 仓库上下文模板：如何组装目录树和文件摘要
- 关键指令尾部重复："所有文件引用必须真实存在"
☐ 对 3 个仓库测试 Prompt 效果，迭代优化
☐ 记录每次 Prompt 修改和效果变化（面试素材）
Day 9（周四）：输出节点 + 报告格式化
☐ 实现报告模板（Markdown 格式）
☐ 实现 Rich 终端输出（美化显示）
☐ 串联完整 Graph：路由 → 扫描 → 分析 → 输出
☐ 首次端到端运行！
Day 10（周五）：测试 + 修复 + 本周小结
☐ 对 5 个测试仓库运行全景扫描
☐ 人工检查每份报告：
- 目录职责标注是否准确？
- 入口文件定位是否正确？
- 核心模块识别是否合理？
- 阅读顺序建议是否有帮助？
☐ 记录准确率（粗略版，为后续正式评估打基础）
☐ 修复明显的错误
☐ 提交代码，写本周小结
Sprint 2 验收标准：
- 输入任意 GitHub URL，5 分钟内输出全景报告
- 报告包含：项目概览、技术栈、目录结构解读、入口定位、阅读顺序
- 三级漏斗正常工作：大项目不会超出上下文窗口
- 至少在 3/5 个测试仓库上输出基本准确的报告
这周的技术决策记录（面试素材）：
- 为什么用三级漏斗而不是一次全部读取
- Prompt 迭代了几个版本，每版改了什么、效果如何
- Token 预算设多少合适，怎么测出来的
Day 11（周一）：tree-sitter 代码切分
☐ 集成 tree-sitter，实现 Python 文件的 AST 解析
☐ 实现按函数/类切分策略：
- 每个函数 → 一个 chunk
- 每个类 → 一个 chunk（如果太大则按方法拆分）
- 模块级代码（import、常量）→ 一个 chunk
☐ 每个 chunk 附加元数据：文件路径、起止行号、函数/类名
☐ 对比测试：按 AST 切分 vs 按固定行数切分，记录差异
Day 12（周二）：扩展语言支持 + 降级策略
☐ 添加 TypeScript/JavaScript 的 tree-sitter 支持
☐ 实现降级策略：tree-sitter 不支持的语言 → 按空行 + 缩进做简单切分
☐ 测试多语言仓库的切分效果
Day 13（周三）：Embedding + ChromaDB 索引
☐ 集成 Embedding 模型
☐ 实现代码块向量化和 ChromaDB 写入
☐ 实现索引构建流程：文件获取 → AST 切分 → 向量化 → 存储
☐ 记录索引构建时间和存储大小
Day 14（周四）：语义检索实现
☐ 实现检索接口：query → top-K 相关代码块
☐ 实现检索结果格式化：附带文件路径、行号、代码内容
☐ 手动测试 10 个问题的检索效果：
- "入口在哪？"
- "错误处理逻辑在哪？"
- "状态是怎么管理的？"
- ……
☐ 调整检索参数（top-K 值、相似度阈值）
Day 15（周五）：检索质量评估 + 本周小结
☐ 对比测试：AST 语义切分 vs 按行切分的检索准确率
☐ 记录具体数字（这是简历上要写的）
☐ 修复检索质量问题
☐ 提交代码，写本周小结
Day 15.5（追加）：BM25 关键词检索 + 混合检索 + RRF Rerank ☐ 集成 rank-bm25 库，实现 BM25Searcher - 对已切分的代码块构建 BM25 索引 - 支持精确关键词匹配（函数名、变量名、类名） ☐ 实现 HybridRetriever： - 同时调用向量检索（ChromaDB）和 BM25 检索 - 使用 Reciprocal Rank Fusion（RRF）合并两路结果 - 去重 + 按融合分数排序 ☐ 对比测试： - 纯向量检索 vs 纯 BM25 vs 混合检索 - 测试用例覆盖：语义类问题 + 精确函数名问题 - 记录各策略命中率对比数据
**Sprint 3 验收标准：**
- 代码库能在 2 分钟内完成索引
- 语义检索对 10 个测试问题的命中率 ≥ 70%
- 混合检索（向量 + BM25）整体命中率 ≥ 90%
- 精确函数名/类名查询命中率 ≥ 90%（BM25 贡献）
- AST 切分 vs 行切分的对比数据已记录
- Python 和 TypeScript 文件均可正确切分和检索
---
## Sprint 4：问答系统 + 防幻觉 + 多轮对话（Day 16-20）
### 目标：用户可以和 Agent 对话式地深入理解项目
Day 16（周一）：问答工作流 ☐ 在 LangGraph 中添加问答路径： 路由 → 检索 → 分析 → 校验 → 输出 ☐ 实现 ReAct 循环： - Reason：判断需要什么信息 - Act：调用检索 / 读取文件 - Observe：评估结果够不够 - 循环上限：15 次 ☐ 实现 Token 预算控制
Day 17（周二）：确定性校验层（重点） ☐ 实现引用提取器：从 LLM 输出中提取所有文件路径和代码片段 ☐ 实现文件路径校验：检查路径是否在 file_tree 中存在 ☐ 实现代码片段校验：检查引用的代码是否与文件内容匹配 ☐ 实现函数/类名校验：检查 AST 中是否存在该符号 ☐ 校验未通过 → 标记为"存疑"或打回重新分析 ☐ 记录校验前后的幻觉率对比（简历数据）
Day 18（周三）：多轮对话 + 状态持久化 ☐ 集成 LangGraph MemorySaver（Checkpointer） ☐ 实现 thread_id 管理，支持多轮对话 ☐ 实现对话上下文传递：Agent 知道之前聊了什么 ☐ 测试多轮场景： - "分析仓库" → "入口在哪？" → "这个函数做了什么？" - 确认每轮都能正确引用之前的上下文
Day 19（周四）：对话历史压缩 ☐ 实现滑动窗口策略：保留最近 3 轮原文，更早的压缩为摘要 ☐ 实现摘要生成：用 LLM 将旧对话压缩为关键信息 ☐ 测试 10+ 轮对话后 Agent 是否仍然记得关键上下文 ☐ 记录压缩前后的 Token 消耗对比
Day 20（周五）：集成测试 + 本周小结 ☐ 端到端测试完整流程： 扫描仓库 → 提问 → 追问 → 再追问（5+ 轮） ☐ 检查校验层工作情况：统计幻觉拦截率 ☐ 检查多轮对话状态是否正确维护 ☐ 修复问题，提交代码
**Sprint 4 验收标准：**
- 能进行 5+ 轮有上下文的连贯对话
- 校验层将幻觉引用率降低到 10% 以下
- 对话历史压缩后 Agent 仍能记住关键信息
- ReAct 循环不会超过 15 次上限
---
## Sprint 5：贡献引导 + Issue 分析（Day 21-25）
### 目标：能分析 Issue 并给出带代码定位的修改建议
Day 21（周一）：Issue 获取 + 筛选 ☐ 实现 Issue 获取流程：拉取 Open Issues，按标签筛选 ☐ 实现 Issue 解析：提取标题、描述、标签、评论 ☐ 实现难度预估：基于描述长度、涉及关键词、标签
Day 22（周二）：Issue 到代码的语义关联 ☐ 实现 Issue 文本 → 代码库检索的关联 ☐ 对每个 Issue，找到最相关的 3-5 个代码文件 ☐ 生成修改建议：该看哪些文件、可能的实现思路 ☐ 测试 10 个真实 Issue 的关联准确率
Day 23（周三）：贡献路线图生成 ☐ 实现路线图模板：按难度排序，每个 Issue 附带代码定位 ☐ 实现与问答系统的衔接：用户选中某个 Issue 后可以继续追问 ☐ 测试完整流程："我想贡献" → 展示路线图 → 选中一个 → 追问怎么改
Day 24（周四）：Prompt 组装策略优化 ☐ 实现完整的 Prompt 组装顺序： System Prompt（开头）→ 仓库上下文 → 对话摘要 → RAG 检索结果 → 当前消息 → 关键指令重复（结尾） ☐ A/B 测试：调整组装顺序对回答质量的影响 ☐ 记录最佳 Prompt 组装方案
Day 25（周五）：集成测试 + 本周小结 ☐ 端到端测试完整用户旅程： 1. 输入仓库 URL → 获得全景报告 2. 追问架构细节 → 获得带代码引用的回答 3. 要求贡献引导 → 获得 Issue 路线图 4. 选中一个 Issue → 获得修改建议 5. 追问测试怎么写 → 获得测试建议 ☐ 完整旅程在 3 个仓库上测试通过 ☐ 提交代码
**Sprint 5 验收标准：**
- Issue 与代码定位关联准确率 ≥ 70%
- 完整用户旅程（5 步）能流畅走通
- Prompt 组装策略确定并记录
---
## Sprint 6：MCP 工具层 + 可观测性（Day 26-30）
### 目标：工具层标准化为 MCP 协议；具备完整的运行数据记录
Day 26（周一）：MCP Server 实现 ☐ 将 GitHub API 工具封装为 MCP Server ☐ 将代码解析工具封装为 MCP Server ☐ 将 RAG 检索封装为 MCP Server ☐ Agent 通过 MCP 协议调用工具（替换之前的直接函数调用）
Day 27（周二）：MCP 测试 + 错误处理标准化 ☐ 测试 MCP 工具发现和调用流程 ☐ 统一错误处理：所有 MCP 工具返回标准化的错误格式 ☐ 实现工具调用日志：记录每次调用的参数、结果、耗时
Day 28（周三）：可观测性系统 ☐ 实现节点级计时：每个 LangGraph 节点记录执行时间 ☐ 实现 Token 计数：每次 LLM 调用记录 input/output Token ☐ 实现成本计算：Token 数 × 模型单价 → 单次分析成本 ☐ 实现执行报告输出
Day 29（周四）：错误恢复 + 降级策略 ☐ 实现 LLM 降级切换：Gemini 不可用 → 自动切换 Claude ☐ 实现全局错误恢复：任何节点失败 → 跳过并标注 → 继续执行 ☐ 实现 Token 预算熔断：超出预算 → 停止分析 → 输出已有结果 ☐ 压力测试：故意制造各种错误，验证恢复机制
Day 30（周五）：集成测试 + 本周小结 ☐ MCP 工具调用全流程测试 ☐ 可观测性数据收集测试 ☐ 生成一份完整的执行报告示例 ☐ 提交代码
**Sprint 6 验收标准：**
- 所有工具通过 MCP 协议调用
- 每次运行输出完整的执行报告（耗时、Token、成本）
- Gemini 宕机时自动切换 Claude 且用户无感知
- 任何单点故障不会导致整体崩溃
---
## Sprint 7：评估体系 + 包装交付（Day 31-35）
### 目标：有量化数据证明效果；项目可展示
Day 31（周一）：测试集标注 ☐ 选定 10 个测试仓库（覆盖不同语言、不同规模）： - Python：langgraph, httpx, click - TypeScript：zustand, zod - Go：cobra, gin - 混合语言：excalidraw, deno, supabase ☐ 对每个仓库人工标注"正确答案"： - 项目类型、核心目录、入口文件、关键模块 - 准备 5 个问题和标准答案
Day 32（周二）：自动化评估脚本 ☐ 实现 benchmark.py： - 自动对 10 个仓库运行全景扫描 - 自动提交 5 个标准问题 - 将 Agent 输出与标注答案对比 - 计算准确率、引用有效率、响应时间、成本 ☐ 运行首次完整评估，记录基线数据
Day 33（周三）：根据评估结果优化 ☐ 分析评估结果，找出薄弱环节 ☐ 针对性优化（Prompt 调整 / 检索参数调整 / 漏斗策略调整） ☐ 重新运行评估，记录优化后数据 ☐ 整理优化前后的对比数据（简历核心数据）
Day 34（周四）：README + Demo ☐ 编写 README.md： - 项目简介 + 架构图 - 安装和使用方法 - 技术选型说明 - 评估结果展示 ☐ 录制 Demo 视频（2-3 分钟）： - 输入仓库 URL → 全景报告 - 提问 → 带代码引用的回答 - 贡献引导 → Issue 分析
Day 35（周五）：最终验收 ☐ 完整用户旅程回归测试 ☐ 代码清理：删除调试代码、补充注释 ☐ 最终评估数据确认 ☐ Git 历史整理，确保提交记录清晰 ☐ 项目正式交付
**Sprint 7 验收标准：**
- 10 个测试仓库的自动化评估全部完成
- 全景报告准确度 ≥ 85%
- 代码引用有效率 ≥ 90%
- README 完整，Demo 视频录好
- 代码干净，提交历史清晰
---
## 总览甘特图
Week1 Week2 Week3 Week4 Week5 Week6 Week7
Sprint0+1 Sprint2 Sprint3 Sprint4 Sprint5 Sprint6 Sprint7
─────── ─────── ─────── ─────── ─────── ─────── ───────
环境 ██ GitHub ████████ LangGraph ████████ 全景扫描 ████████ RAG 索引 ████████ 问答系统 ████████ 防幻觉 ████████ 多轮对话 ████████ 贡献引导 ████████ Prompt ████████ MCP ████████ 可观测性 ████████ 评估 ████████ 包装 ████████
里程碑: M1 M2 M3 M4 M5 M6 M7 环境就绪 全景报告 RAG检索 多轮问答 完整旅程 生产级 可交付 能跑 能用 能聊 走通 稳定 展示
---
## 每日工作节奏
09:00 - 09:15 回顾昨天进度，确认今天目标 09:15 - 12:00 核心开发（最难的任务放在上午） 12:00 - 13:00 午休 13:00 - 15:00 继续开发 / 写测试 15:00 - 15:30 运行测试，修复问题 15:30 - 17:00 代码整理 + 踩坑记录 + 提交 17:00 - 17:30 写当天小结：做了什么、遇到什么坑、明天计划
---
## 踩坑记录模板
> 每天结束时花 10 分钟填这个。面试时这就是你的弹药库。
```markdown
### Day X — [日期]
**今天做了什么：**
- ...
**遇到了什么问题：**
- 问题描述：
- 排查过程：
- 最终解决方案：
- 花了多长时间：
**做了什么技术决策：**
- 决策：选择了 A 而不是 B
- 原因：
- 对比过的备选方案：
**明天计划：**
- ...
整个排期中预留了以下缓冲：
| 环节 | 预估耗时 | 缓冲 | 说明 |
|---|---|---|---|
| Sprint 2（全景扫描） | 5 天 | +2 天 | Prompt 工程可能需要大量迭代 |
| Sprint 4（防幻觉） | 5 天 | +1 天 | 校验层边界情况可能很多 |
| Sprint 7（评估） | 5 天 | +2 天 | 标注工作量可能超预期 |
如果某个 Sprint 提前完成，把时间用于：
- 补充测试用例
- 优化 Prompt
- 记录更详细的踩坑笔记
如果某个 Sprint 延期，优先砍的是：
- 多语言支持（只保留 Python）
- 对话历史压缩（保留最近 5 轮原文即可）
- Demo 视频（文字版 README 足够）
绝对不能砍的：
- 校验层（防幻觉是核心价值）
- 自动化评估（没有数据简历没法写）
- 错误恢复（没有这个不能叫"工程"）