PRD: [Coding Agent 产品名称]
| 元数据 | 内容 |
|---|---|
| 文档状态 | [草稿 / 评审中 / 已定稿] |
| 版本号 | v[0.1.0] |
| 作者 | [姓名] |
| 创建日期 | [YYYY-MM-DD] |
| 最后更新 | [YYYY-MM-DD] |
| Agent 形态 | [IDE 插件 / 命令行工具 / Web IDE / Chat 集成] |
1. 产品概述
1.1 定位与愿景
[用 3-5 句话描述 Coding Agent 的定位。例如：本产品是一个面向[目标用户]的 AI 代码生成 Agent，能够理解编码需求、生成高质量代码、自动修复错误，帮助开发者在[场景]中提升[核心指标]。]
1.2 目标用户
- 主要用户：[如：全栈工程师、前端/后端开发者]
- 使用场景：[如：代码补全、代码审查、Bug 修复、单元测试生成]
- 用户水平：[如：初中级开发者 / 资深工程师]
1.3 用户痛点
- [痛点 1]：[如：重复性编码劳动枯燥且耗时]
- [痛点 2]：[如：不熟悉新框架 API，靠搜索效率低]
- [痛点 3]：[如：代码审查耗时长，低级 Bug 反复出现]
- [痛点 4]：[如：单元测试覆盖率低，缺少自动化手段]
1.4 成功指标
| 指标 | 目标值 | 测量方式 |
|---|---|---|
| 代码生成采纳率 | ≥ [X]% | [如：用户接受生成代码的比率] |
| 代码正确率 | ≥ [X]% | [如：通过单元测试比率] |
| 开发者效率提升 | ≥ [X]% | [如：完成任务时间减少] |
| Bug 引入率 | ≤ [X]% | [如：生成代码导致的新 Bug 比率] |
2. 语言支持策略
2.1 支持的语言
| 语言 | 优先级 | 覆盖范围 | 备注 |
|---|---|---|---|
| [Python] | P0 | 生成、补全、审查、重构 | [如：核心语言，完整支持] |
| [TypeScript / JavaScript] | P0 | 生成、补全、审查、重构 | [如：完整支持] |
| [Go] | P1 | 生成、补全、审查 | [如：仅基础支持] |
| [Rust] | P1 | 补全、审查 | [如：仅补全和审查] |
| [Java] | P1 | 生成、补全、审查 | [如：企业版支持] |
| [其他：SQL/YAML/JSON] | P2 | 补全 | [如：结构化语言补全] |
2.2 语言识别策略
- 自动检测：[如：根据文件扩展名 / 项目配置文件 (package.json, go.mod) 自动识别]
- 显式指定：[如：用户可通过注释
@lang: python覆盖检测结果] - 混合文件处理：[如：单个文件中包含多种语言时，分段识别]
3. 上下文窗口策略
3.1 上下文组成
| 上下文来源 | 最大 Token 分配 | 说明 |
|---|---|---|
| 当前文件 | [如：8K tokens] | [用户正在编辑的文件内容] |
| 相关文件 | [如：8K tokens] | [通过 RAG 检索的相关代码文件] |
| 项目结构 | [如：2K tokens] | [项目目录树、导入关系图] |
| 系统指令 | [如：1K tokens] | [编码规范、框架版本、语言要求] |
| 对话历史 | [如：4K tokens] | [用户与 Agent 的最近对话] |
| 总计 | ≤ 32K tokens | [根据模型上下文窗口调整] |
3.2 上下文窗口管理
- 窗口大小：[如：根据模型支持动态调整，备用窗口为 128K tokens]
- 自动压缩：[如：超出窗口时自动压缩注释、缩减空白、折叠函数体]
- 优先级策略：[如：当前光标位置附近的代码优先保留]
- 文件关联发现：[如：通过 import 分析 / 类引用关系 / 最近的 git diff 发现相关文件]
3.3 长文件处理
- 分段策略：[如：超过窗口限制时，仅加载相关函数/类，而非整个文件]
- RAG 回退：[如：需要搜索整个代码库时，使用向量检索取 Top-K 结果]
4. 代码安全审查
4.1 安全审查清单
| 审查项 | 严重级别 | 检测方式 | 举例 |
|---|---|---|---|
| 硬编码密钥 | 阻塞 | 正则 + LLM 扫描 | [如：API_KEY = "sk-..."] |
| SQL 注入 | 阻塞 | 代码分析 | [如：f-string 拼接 SQL] |
| 命令注入 | 阻塞 | 代码分析 | [如：os.system(f"cmd {input}")] |
| 路径遍历 | 阻塞 | 代码分析 | [如：未校验的 open() 路径] |
| 危险函数调用 | 警告 | 函数名黑名单 | [如：eval() exec() pickle.loads()] |
| 不安全的反序列化 | 警告 | 代码分析 | [如：yaml.load() 不带 SafeLoader] |
| 缺少输入验证 | 建议 | LLM 审查 | [如：直接使用用户输入未校验] |
4.2 安全审查流程
用户请求 → 代码生成 → 自动安全审查
├── 无问题 → 返回代码
├── 警告级别 → 标记高风险代码块 + 建议修复 → 返回代码
└── 阻塞级别 → 拒绝生成 + 解释原因 + 提供安全替代方案4.3 安全策略配置
| 配置项 | 可选值 | 说明 |
|---|---|---|
| 审查级别 | strict / moderate / lenient | [安全审查严格程度] |
| 允许危险函数 | [eval(), exec(), ...] | [白名单例外] |
| 自定义规则 | [用户可添加正则或 API 规则] | [企业自定义安全策略] |
5. 沙箱执行
5.1 执行环境
| 属性 | 规格 |
|---|---|
| 运行时类型 | [Docker 容器 / Firecracker 微 VM / gVisor] |
| 资源限制 | CPU：[X] 核，内存：[X] GB，磁盘：[X] GB |
| 网络策略 | [仅内网 / 禁止网络 / 白名单域名] |
| 文件系统 | [临时文件系统，沙箱退出后清理] |
| 超时限制 | [如：每个执行任务 ≤ 120 秒] |
| 最大输出大小 | [如：stdout ≤ 1MB] |
5.2 沙箱安全策略
- 网络隔离：[如：沙箱环境无外网访问能力，仅允许内网包管理器 Proxy]
- 磁盘写保护：[如：除
/tmp/外所有目录只读] - 系统调用过滤：[如：Seccomp 策略禁用危险 syscall]
- 进程限制：[如：单进程模式，禁止
fork()/exec()] - 资源上限：[如：防止 fork bomb 和无限循环]
5.3 代码执行场景
| 场景 | 是否需要沙箱 | 执行策略 |
|---|---|---|
| 代码补全预览 | [否] | [无需执行] |
| 单元测试运行 | [是] | [在隔离沙箱中运行测试] |
| 代码片段调试 | [是] | [在沙箱中运行并收集输出] |
| 重构效果验证 | [可选] | [可选沙箱验证] |
6. 测试生成策略
6.1 测试类型覆盖
| 测试类型 | 支持程度 | 生成策略 | 示例框架 |
|---|---|---|---|
| 单元测试 | P0 | [根据函数签名和文档生成] | [pytest / Vitest / JUnit] |
| 集成测试 | P1 | [根据 API 文档和 Mock 生成] | [pytest + requests / Supertest] |
| 边界测试 | P1 | [LLM 分析代码逻辑，生成边界 case] | [同上] |
| 性能测试 | P2 | [生成基准测试代码] | [pytest-benchmark] |
| 安全测试 | P2 | [安全审查自动附加] | [OWASP ZAP 集成] |
6.2 测试生成模式
- 模式 1：按需生成 — 用户选中函数 → 右键 → "生成测试"
- 模式 2：自动补全 — 在测试文件中按
Tab自动补全下一个测试用例 - 模式 3：覆盖率增强 — 检测未覆盖代码 → 自动生成缺失的测试
6.3 测试质量标准
| 指标 | 目标值 |
|---|---|
| 测试通过率（自然生成） | ≥ [X]% |
| 代码行覆盖率 | ≥ [X]% |
| 分支覆盖率 | ≥ [X]% |
| 测试可读性评分（人工评估） | ≥ [X]/5 |
7. 非功能需求
7.1 响应性能
| 场景 | 目标延迟 |
|---|---|
| 行内补全 | ≤ [X]ms |
| 代码生成 | ≤ [X]s |
| 测试生成 | ≤ [X]s |
| 安全审查 | ≤ [X]s |
7.2 IDE 集成
| IDE | 支持版本 | 插件架构 | 优先级 |
|---|---|---|---|
| VS Code | ≥ [1.X] | [LSP / Extension API] | P0 |
| JetBrains | ≥ [2024.X] | [Plugin SDK] | P1 |
| Vim / Neovim | ≥ [0.X] | [LSP / Lua Plugin] | P2 |
7.3 离线支持
- 完全离线：[支持/不支持]，使用本地模型 [如：DeepSeek-Coder-V2-Lite / CodeLlama]
- 混合模式：[支持/不支持]，简单任务走本地，复杂任务走云端
8. 实施路线图
| 里程碑 | 时间 | 交付物 | 负责人 |
|---|---|---|---|
| M1：代码补全 | YYYY-MM-DD | VS Code 行内补全，支持 Python/TS | [姓名] |
| M2：代码生成 | YYYY-MM-DD | 自然语言 → 代码生成功能 | [姓名] |
| M3：测试生成 | YYYY-MM-DD | 单元测试自动生成 | [姓名] |
| M4：沙箱执行 | YYYY-MM-DD | 沙箱环境搭建，代码可执行验证 | [姓名] |
| M5：安全审查 | YYYY-MM-DD | 安全审查 + 企业级策略 | [姓名] |
9. 风险与缓解
| 风险 | 概率 | 影响 | 缓解措施 |
|---|---|---|---|
| [生成代码质量不达标] | [高/中/低] | [高/中/低] | [如：设置质量门槛，低于阈值提示用户人工检查] |
| [沙箱逃逸漏洞] | [高/中/低] | [高/中/低] | [如：多层沙箱 + 安全审计 + 限制敏感系统调用] |
| [版权/许可风险] | [高/中/低] | [高/中/低] | [如：代码来源过滤 + 许可证标注 + 企业模型训练] |
| [安全审查误报/漏报] | [高/中/低] | [高/中/低] | [如：配置 whitelist + 人工复核 + 持续优化规则] |
10. 附录
10.1 相关文档
- [模型选型对比分析]
- [沙箱架构设计]
- [IDE 插件开发指南]
10.2 术语表
| 术语 | 定义 |
|---|---|
| 代码采纳率 | [用户接受并使用 AI 生成代码的比率] |
| 沙箱 | [安全的隔离执行环境] |
| Seccomp | [Linux 安全计算模式，用于过滤系统调用] |
10.3 变更日志
| 版本 | 日期 | 变更内容 | 作者 |
|---|---|---|---|
| v0.1.0 | YYYY-MM-DD | 初稿创建 | [姓名] |