跳转至

07 - 实战项目：构建仓库感知的 AI 研发助手

这章不再做“玩具级代码助手”。更值得你在 2028 求职里拿出来讲的，是一个能体现 agent + 检索 + 测试门禁 + 评测 + 可观测性 的交付型项目。

为什么这个项目更值钱

简单的“调用模型生成代码”已经不够构成竞争力。真实岗位更看重你是否理解下面这些问题：

  • agent 如何理解仓库
  • 任务如何拆解和执行
  • 代码改动如何验证和审查
  • 风险如何控制、回滚如何设计
  • 评测体系如何建立

所以这章的项目目标是：

Text Only
做一个能接代码仓库、能理解任务、能给出计划、能生成补丁、能跑测试、能出评测报告的 AI 研发助手。

这个项目比“聊天式代码生成器”更接近大厂真实需求，也更容易写进简历。

项目定位

项目名称

RepoPilot：仓库感知的 AI 研发助手平台

适合投递的方向

  • AI 应用工程
  • AI Coding / AI4SE
  • Agent 工程
  • 平台工程 / DevTools
  • AI 系统设计面试

你最终应该能讲出的项目一句话

Text Only
我做了一个仓库感知的 AI 研发助手，支持任务拆解、代码检索、补丁生成、自动验证和评测审查，能把 AI Coding 纳入真实交付闭环。

项目目标

完成后你应该能交付 5 类资产：

  • 一个可运行的 demo 系统
  • 一套任务执行与验证链路
  • 一套评测与指标看板
  • 一份系统设计文档
  • 一套能写进简历和面试的项目证据链

需求定义

核心功能

  1. 输入自然语言任务
  2. 自动定位相关文件和代码片段
  3. 生成改动计划
  4. 生成 patch 或修改建议
  5. 运行 lint/test/build
  6. 生成风险摘要和交付说明

进阶功能

  • 多轮迭代修复
  • 支持 spec -> plan -> patch -> verify
  • 支持失败重试和错误分类
  • 支持任务评测和历史回放
  • 支持发布前的人工审查门禁

系统架构

Text Only
┌────────────────────┐
│ Web/CLI/IDE 前端   │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Task Orchestrator  │ 任务编排、状态机、重试
└──────┬─────┬───────┘
       │     │
       │     ├──────────────────────┐
       │                            │
       ▼                            ▼
┌───────────────┐           ┌────────────────┐
│ Context Layer │           │ Agent Runtime  │
│ 仓库索引/检索  │           │ 计划/补丁/修复  │
└──────┬────────┘           └───────┬────────┘
       │                            │
       ▼                            ▼
┌───────────────┐           ┌────────────────┐
│ Sandbox Exec  │           │ Eval & Review  │
│ lint/test/run │           │ 指标/报告/审查 │
└───────────────┘           └────────────────┘

模块拆分

模块拆分不是为了看起来专业，而是为了让项目边界、职责和后续扩展路径更清楚。

1. Task Orchestrator

负责把一次任务拆成状态机。

最小状态：

  • created
  • context_ready
  • plan_ready
  • patch_generated
  • verification_passed
  • review_required
  • completed
  • failed

一个简化的数据结构

Python
from dataclasses import dataclass, field
from typing import List, Literal

TaskStatus = Literal[
    "created",
    "context_ready",
    "plan_ready",
    "patch_generated",
    "verification_passed",
    "review_required",
    "completed",
    "failed",
]

@dataclass
class TaskRun:
    task_id: str
    instruction: str
    repo_path: str
    status: TaskStatus = "created"
    related_files: List[str] = field(default_factory=list)
    plan_steps: List[str] = field(default_factory=list)
    verification_commands: List[str] = field(default_factory=list)
    risk_summary: List[str] = field(default_factory=list)

2. Context Layer

负责仓库感知，不要一上来把整个 repo 塞给模型。

你至少应该做三件事：

  • 建立文件索引
  • 按任务检索相关文件
  • 组装最小上下文包

一个最小实现思路

Python
from pathlib import Path

def build_repo_map(repo_root: str) -> list[dict]:
    repo = Path(repo_root)
    result = []
    for path in repo.rglob("*"):
        if path.is_file() and path.suffix in {".py", ".ts", ".tsx", ".md"}:
            result.append(
                {
                    "path": str(path.relative_to(repo)),
                    "name": path.name,
                    "suffix": path.suffix,
                }
            )
    return result

真实项目里你还可以继续做：

  • AST/符号级检索
  • import/call graph
  • 测试文件映射
  • 配置文件识别

3. Agent Runtime

不要直接让 agent 输出最终代码。更稳的模式是两阶段：

阶段 A：plan agent

输出：

  • 根因判断
  • 涉及文件
  • 子任务顺序
  • 测试策略

阶段 B：patch agent

输出：

  • 补丁
  • 改动摘要
  • 风险说明

这样做的好处是：

  • 更容易 review
  • 更容易回滚
  • 更容易做评测

4. Sandbox Execution

这是把项目拉开档次的关键。很多项目只会“生成代码”，不会“验证代码”。

你至少要支持：

  • lint
  • unit test
  • build
  • 可选的 benchmark 或 e2e

一个执行结果结构

Python
from dataclasses import dataclass

@dataclass
class CommandResult:
    command: str
    exit_code: int
    stdout: str
    stderr: str
    duration_ms: int

设计重点

  • 设置超时
  • 限制危险命令
  • 记录输出日志
  • 失败后回传给 agent 进行修复

5. Eval & Review

这是最容易被忽略、但 2028 最值钱的一层。

你不应该只展示 demo 成功，而应该展示：

  • 哪些任务成功
  • 哪些失败
  • 失败原因是什么
  • 是否真的减少了人工时间

建议跟踪的 8 个指标：

指标 含义
任务完成率 agent 最终交付成功的比例
一次通过率 不需要二次修复的比例
测试通过率 修改后通过验证的比例
平均修复轮数 一个任务需要多少轮才能完成
人工返工率 最终仍需大改的比例
误改高风险文件率 agent 触碰敏感区域的比例
平均耗时 单任务从创建到完成的时间
Token/成本消耗 单任务成本和整体预算

第一阶段交付

MVP 范围

建议先限制到单仓库、单语言、单一任务类型。

比如：

  • 只支持 Python 或 TypeScript
  • 只支持 bugfix 和补测试
  • 只支持本地仓库

MVP 功能清单

  • 输入任务
  • 检索文件
  • 输出计划
  • 生成 patch
  • 执行 test
  • 生成报告

做到这一步，已经足够形成高质量项目雏形。

第二阶段升级

可以继续做：

  • 多 agent 协作
  • pull request 评论接入
  • 历史任务回放
  • 错误分类和自动重试
  • 指标 dashboard
  • A/B 比较不同模型或不同提示模板

第三阶段升级

这时才考虑更强的路线：

  • 奖励模型或 judge 模型
  • rollout 数据沉淀
  • PR 接受率优化
  • 语义缓存
  • 多仓库联动

项目目录建议

Text Only
repopilot/
├── apps/
│   ├── api/                 # FastAPI / Node API
│   ├── web/                 # 可视化任务面板
│   └── cli/                 # 命令行入口
├── core/
│   ├── orchestrator/        # 状态机和任务编排
│   ├── context/             # 仓库检索、索引、摘要
│   ├── agent/               # plan/patch/retry
│   ├── sandbox/             # 命令执行和安全限制
│   └── eval/                # 指标和评测
├── docs/
│   ├── architecture.md
│   ├── runbook.md
│   └── evaluation.md
├── tests/
└── examples/

面试最容易被追问的 10 个问题

  1. 为什么不用一个 prompt 直接生成最终代码
  2. 为什么要拆 planner 和 executor
  3. 上下文是怎么检索的
  4. 如何限制 agent 改错文件
  5. 如何设计 sandbox
  6. 如何做失败重试
  7. 如何做结果评测
  8. 如何控制成本和延迟
  9. 如何防止幻觉和危险命令
  10. 如果放到真实团队里，门禁和权限怎么做

如果你这 10 个问题都能答顺，项目价值会明显上一个台阶。

简历怎么写

比起“做了一个 AI 代码助手”，更建议这样写：

Text Only
设计并实现仓库感知的 AI 研发助手，支持任务拆解、代码检索、补丁生成、测试执行与风险摘要。
构建 spec/plan/patch/verify 四阶段执行链路，并通过 lint、单测和回归命令形成自动验证闭环。
设计任务完成率、一次通过率、人工返工率等评测指标，用于比较不同提示模板和模型配置的效果。

如果你有真实数据，继续量化：

  • 任务完成率提升了多少
  • 单任务平均耗时降了多少
  • 回归测试补齐了多少

交付物清单

项目完成前，至少准备好这些材料：

  • 系统架构图
  • 核心模块说明
  • 评测指标定义
  • 典型任务截图或日志
  • 一份失败案例复盘
  • 一份上线前风险清单

这套材料会直接影响你的面试表达质量。

推荐的答辩顺序

  1. 先讲问题和目标
  2. 再讲架构和模块分工
  3. 再讲任务执行链路
  4. 再讲评测指标
  5. 最后讲失败案例和下一步优化

很多人项目讲不清，不是项目弱，而是顺序错了。

本章小结

  • 更接近 2028 招聘需求的，不是玩具式 AI 助手，而是可验证、可评测、可交付的研发助手
  • 这个项目的核心关键词是 repo-aware、agent runtime、sandbox、evaluation
  • 你真正要做的是交付一条完整链路，而不是堆一个模型接口

下一步