需求类型
Forgexa 中的每个需求都有一个类型，它决定了 AI Agent 如何分析需求、产出哪些文档、运行哪些执行阶段，以及质量门禁如何评分。选择正确的类型，能确保流水线高效运行、产出内容与实际需要相符。
类型总览
| 类型键 | 显示名称 | 最适合 | 执行阶段数 | 分析文档数 |
|---|---|---|---|---|
feature | 功能 | 新增用户可见的功能 | 4 | 5 |
bugfix | 缺陷修复 | 复现并修复已知 Bug | 4 | 4 |
refactor | 重构 | 在不改变行为的前提下重整代码结构 | 3 | 3 |
documentation | 文档 | 编写或更新文档 | 2 | 2 |
improvement | 改进 | 对已有功能的迭代优化 | 4 | 4 |
task | 任务 | 工程任务、脚本、配置变更 | 1–2 | 2 |
spike | 技术调研 | 技术调研与 PoC 验证 | 2–3 | 2 |
faq | 技术答疑 | 回答技术问题并沉淀答案 | 2 | 2 |
别名支持：
bug→bugfix，story→feature，support→faq。在看板（Board）创建工作项时可直接使用别名，系统会自动映射。
各类型详解
功能（Feature）
适用于从零开始构建新的用户可见功能 — 新的 API 接口、新的页面、新的集成对接等。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 产品需求文档（PRD） | 用户故事、验收标准、边界条件、非功能需求（性能/安全/兼容性等） |
| 技术设计文档（SDD） | 架构决策、API 接口契约、数据模型变更 |
| 任务拆解清单（TASKS） | 子任务列表与执行依赖关系 |
| 测试场景计划 | AI 在测试阶段必须覆盖的结构化测试用例列表 |
执行阶段： 设计 → 实现 → 测试 → 评审
Gate 评分重点： 全维度均衡评分，测试覆盖率（20%）、代码质量（20%）与完整性（20%）并列最高，安全（15%）确保新功能不引入漏洞。
| 维度 | 权重 |
|---|---|
| 测试覆盖 | 20% |
| 代码质量 | 20% |
| 完整性 | 20% |
| 安全 | 15% |
| AI 评审 | 15% |
| 性能 | 10% |
缺陷修复（Bug Fix）
适用于已知 Bug 的诊断与修复。流水线从根因分析开始，在动手写修复代码之前先完成诊断。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 问题诊断简报 | 已知复现步骤、受影响的代码区域、初始错误上下文 |
| 任务拆解清单（TASKS） | 修复子任务列表 |
| 回归测试计划 | 必须能复现并验证原始 Bug 已修复的测试用例 |
执行阶段： 诊断 → 修复 → 验证 → 评审
诊断阶段是 Bug Fix 独有的
AI 会先复现 Bug、定位根因、记录修复方案——然后才开始编写修复代码。这个"先诊断后修复"的流程能有效防止治标不治本的情况。
Gate 评分重点： 完整性与测试覆盖率各占 25%，重点验证修复是否彻底、是否有回归。
| 维度 | 权重 |
|---|---|
| 完整性 | 25% |
| 测试覆盖 | 25% |
| AI 评审 | 15% |
| 代码质量 | 15% |
| 安全 | 10% |
| 性能 | 10% |
重构（Refactor）
适用于在不改变外部行为的前提下优化代码内部结构 — 模块重命名、提取抽象层、消除重复代码等。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 重构方案 | 现有代码结构分析、目标结构设计、行为不变性保证方案、风险评估 |
| 任务拆解清单（TASKS） | 重构子任务列表 |
注意
重构类型不产出测试场景计划，因为没有新增功能，测试目标就是确保现有测试全部通过。
执行阶段： 分析 → 重构 → 验证
Gate 评分重点： 测试覆盖率（30%）和代码质量（30%）并重——核心在于结构优化之后行为必须完全不变。
| 维度 | 权重 |
|---|---|
| 测试覆盖 | 30% |
| 代码质量 | 30% |
| AI 评审 | 15% |
| 完整性 | 10% |
| 安全 | 10% |
| 性能 | 5% |
文档（Documentation）
适用于让 AI 编写或更新文档 — README、API 文档、架构说明、用户手册等。这是最轻量的流水线，无代码变更。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 文档大纲 | 章节结构、各部分内容要点、目标读者说明 |
执行阶段： 撰写 → 评审
INFO
文档类型会跳过自动化测试和验证阶段，仅保留撰写与评审两个节点。
Gate 评分重点： 测试覆盖率、安全、性能三个维度不适用，完整性（35%）与 AI 评审（35%）合计占 70%，内容质量是唯一评判标准。
| 维度 | 权重 |
|---|---|
| 完整性 | 35% |
| AI 评审 | 35% |
| 代码质量 | 30% |
改进（Improvement）
适用于对已有功能的迭代优化 — 更好的用户体验、性能优化、增加配置选项、丰富错误提示等。会发生行为变化，但现有行为必须得到保留。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 改进规格说明 | 现状分析与问题陈述、改进目标、改进前后对比、向后兼容要求 |
| 任务拆解清单（TASKS） | 改进子任务列表 |
| 测试场景计划 | 同时覆盖现有行为不变和新改进行为的测试用例 |
执行阶段： 设计 → 实现 → 测试 → 评审
Gate 评分重点： 全维度均衡评分，代码质量（25%）略高，确保改进不会劣化已有实现。
| 维度 | 权重 |
|---|---|
| 代码质量 | 25% |
| 测试覆盖 | 20% |
| 完整性 | 20% |
| AI 评审 | 15% |
| 安全 | 10% |
| 性能 | 10% |
任务（Task）
适用于不需要架构设计的工程任务 — 编写迁移脚本、调整 CI 配置、添加环境变量、执行数据补录等。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 任务执行计划 | 分步骤的执行计划、预期产出（文件/配置/脚本等）、完成判断标准 |
执行阶段： 执行 → 验证（验证步骤可选）
INFO
任务类型不会生成自动化测试脚本。AI 会按计划执行任务，可选地验证完成情况，但不要求正式的测试套件。
Gate 评分重点： 完整性（40%）权重最高，重点评估任务是否按预期完成。测试覆盖率和性能维度不计分。
| 维度 | 权重 |
|---|---|
| 完整性 | 40% |
| AI 评审 | 25% |
| 代码质量 | 25% |
| 安全 | 10% |
技术调研（Research / Spike）
适用于调研技术问题或验证技术方案可行性 — 评估新库、对比架构方案、构建概念验证（PoC）。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 调研背景文档 | 研究问题陈述、调研范围与约束、关键评估标准 |
执行阶段： 调研 → 原型验证（可选）→ 整理调研报告
INFO
技术调研不产出生产代码。原型阶段是可选的——只有在 PoC 能帮助验证结论时才会执行。最终交付物是包含结论与建议的调研报告。
Gate 评分重点： 完整性（40%）和 AI 评审（35%）合计占 75%，以调研报告的质量与结论完整性为核心标准。不计测试覆盖率和性能。
| 维度 | 权重 |
|---|---|
| 完整性 | 40% |
| AI 评审 | 35% |
| 代码质量 | 15% |
| 安全 | 10% |
技术答疑（FAQ）
适用于回答技术问题并将答案沉淀进知识库 — "X 是怎么工作的？"、"为什么 Y 报错？"、"Z 的正确配置方式是什么？"。答案会被向量化存储，供后续需求分析时自动检索复用。
分析阶段产出文档：
| 文档 | 包含内容 |
|---|---|
| 问题背景文档 | 问题上下文、相关代码片段或错误信息、关联技术领域 |
执行阶段： 作答 → 评审答案
Gate 评分重点： 完整性（45%）和 AI 评审（40%）合计占 85%，完全聚焦答案的准确性与知识价值。
| 维度 | 权重 |
|---|---|
| 完整性 | 45% |
| AI 评审 | 40% |
| 代码质量 | 15% |
如何选择正确的类型
我要做什么？
│
├─ 为用户新增一个功能？
│ └─→ feature（功能）
│
├─ 修复一个已知的 Bug？
│ └─→ bugfix（缺陷修复）
│
├─ 让现有功能变得更好？
│ └─→ improvement（改进）
│
├─ 整理代码结构但不改变行为？
│ └─→ refactor（重构）
│
├─ 编写或更新文档？
│ └─→ documentation（文档）
│
├─ 执行一次性工程任务（脚本/配置/数据处理）？
│ └─→ task（任务）
│
├─ 调研一项技术或验证技术方案可行性？
│ └─→ spike（技术调研）
│
└─ 回答一个技术问题并保存答案？
└─→ faq（技术答疑）Gate 评分维度说明
所有需求类型都根据同样的 7 个维度评分，但各维度的权重因类型而异，以反映每种类型的质量重点。
| 维度 | 说明 | 适用类型 |
|---|---|---|
| 测试通过率 | 单元/集成测试通过（100% / ≥95%） | 功能、缺陷修复、重构、改进 |
| 代码覆盖率 | 行覆盖 ≥80%，分支覆盖 ≥70% | 功能、缺陷修复、重构、改进 |
| 静态检查 | Lint + 类型检查通过 | 所有类型 |
| 安全扫描 | 无高危漏洞（Semgrep + Trivy） | 大多数类型 |
| 变更风险 | 涉及认证/支付/数据库迁移文件时标记 | 大多数类型 |
| AI 评审 | Critic Agent 综合评审结论（建议性） | 所有类型 |
| 需求覆盖度 | 评审阶段识别的补充需求与未解决风险是否已落实 | 所有类型 |
关于需求覆盖度
需求覆盖度对所有类型均有效，但它是派生维度，不在上方各类型的 Gate 评分配置表中单独列出。其权重由配置层的「完整性」维度权重的 30% 派生。
- 得分 = 1.0（满分）：评审阶段没有高危未解决的开放风险 → 满分常见，在雷达图中处于最外圈
- 得分 = 0.0：存在高危且状态为
open的补充需求 → 强制进入人工审核
因此，在日常执行中需求覆盖度大多显示为满分。只有当 AI 评审节点识别出被遗漏的高优先级需求且未修复时，才会触发非满分评分。
分数阈值（可在项目的 WORKFLOW.md 中配置）：
- ≥ 85 分 → 自动批准并合并
- 60 – 84 分 → 在 Gates 页面等待人工审核
- < 40 分 → 自动拒绝，触发 AI 修复循环
高风险变更始终需要人工审核
如果变更涉及认证逻辑、支付处理、数据库迁移或部署脚本，无论分数多高，都必须通过人工审批。
使用建议
- 中途切换类型会触发完整的重新分析，并清除现有的分析文档——请在创建时确认好类型。
- 功能 vs 改进：如果是全新的东西用
feature；如果是在现有功能上迭代用improvement。 - 任务 vs 功能：任务没有设计阶段。如果需要架构决策或 API 设计，请使用
feature。 - 技术调研的成果可以自然地延伸为
feature或improvement需求——在下一个需求描述中引用调研报告即可。