- 后端
- Web框架
【免费下载链接】fountain
一个用于服务器应用开发的综合工具库。 - 零配置文件 - 环境变量和命令行参数配置 - 约定优于配置 - 深刻利用仓颉语言特性 - 只需要开发动态链接库，fboot负责加载、初始化并运行 - 覆盖服务器应用开发的各种场景
导读
本文聚焦 fountain 仓库中 fcoder（喷泉开源软件工作室的人工智能编程工具）的《评审需求文档》技能，讲解该技能如何依据《{ }列表》对《需求文档》做功能点覆盖性评审，并以 JSON 契约输出评审结果。读完本文，你将掌握该技能在 fcoder 软件工程流程中的定位、触发规则、必要资料校验、响应格式，以及技能在数据库表与智能体事件调度层面的落地实现。
技能定位：软件工程流水线上的"需求质量闸门"
在 fcoder 中，《评审需求文档》不是孤立存在的，它是规范驱动开发流程中承上启下的关键一环。从 软件工程.md 可以看清它在完整工作流中的位置：
- 按用户需求，从五个角度发散阐述功能点并做可行性分析（技能：可行性分析）
- 生成《需求文档》（技能：需求分析）
- 评审《需求文档》（技能：评审需求文档）
- 生成《概要设计文档》（技能：概要设计）
- 评审《概要设计文档》（技能：评审概要设计）
- 生成《详细设计文档》（技能：详细设计）
- 评审《详细设计文档》（技能：评审详细设计）
- 创建必要的包路径
- 生成顶级声明及公共成员声明
可以看到，评审环节被严格编排为"生成之后、设计之前"的必经步骤。软件工程智能体（agent）的主提示词 fagency.md 同样明确了这一职责："当用户指示评审《需求文档》时，评审《需求文档》是否覆盖了提到的所有功能点"，并强制要求先补齐必要资料。如果用户试图跳过评审直接进入《详细设计文档》，智能体会回复用户必须先完成"评审《需求文档》"、"生成《概要设计文档》"、"评审《概要设计文档》"等前置步骤。
在智能体组织层面，该技能被分配给"文档评审专家"角色。见 文档评审.md：文档评审智能体（资深文档评审专家）的职责列表中，第一项即是"评审《需求文档》——技能：评审需求文档"，后续还包含评审概要设计、评审详细设计两项职责，且允许按需执行、不必严格按顺序。
触发方式与评审目标
技能文件 评审需求文档.md 定义的触发条件是：当用户指示评审《需求文档》时。
评审的唯一核心问题是：
评审《需求文档》是否覆盖了提到的所有功能点
这里的"提到的所有功能点"指用户需求中所列出的功能点集合，也就是必要资料中的《{ }列表》。评审的实质是一次覆盖性（coverage）检查：逐一核对需求文档是否把功能点列表中的每一项都写进去了，是否存在漏项、丢项或含糊带过的功能点。
从 需求分析.md 对《需求文档》的生成要求可以推断，评审时除了核对功能点名称是否出现，还应检查每个功能点是否包含了"具体操作步骤和使用方法"——因为生成需求文档的硬性要求就是"务必覆盖提到的每一个功能点，及每个功能的具体操作步骤和使用方法"。若需求文档对某个功能点只字未提、或只提了名字却没有展开操作步骤，就属于覆盖不完整，应当写入评审结果。
必要资料：缺一不可，缺失必须告知用户
执行评审前，技能要求先确认必要资料是否齐全：
- 《{ }列表》——用户需求中提到的功能点清单；
- 《需求文档》——由《需求分析》技能（需求分析.md）按照功能点列表生成的需求文档。
技能文件明确规定："如果缺少必要资料请务必告知用户"。这一点与 fcoder 其他评审类技能（评审概要设计、评审详细设计、评审代码）的约束完全一致——所有技能都遵循"先校验资料、后执行任务"的原则，且"若对用户请求相关的内容或代码库结构不确定，请使用工具读取文件以收集相关信息，切勿猜测或捏造回复"（见 评审需求文档.md 与 可行性分析.md）。
响应格式契约：necessary 与 review 两种结构化输出
《评审需求文档》技能的输出被严格约束为 JSON，这是 fcoder 技能体系"造接口（Interface Design）"思想的直接体现——像设计软件 API 一样定义技能的输入参数与输出格式，使技能可以被智能体程序稳定调用和解析。
情形一：缺少必要资料时
{ "necessary": ["缺省的必要资料名称", "一份资料一个字符串"] }necessary数组的每个元素是一个缺失资料的名称字符串。例如用户只提供了《需求文档》而没有《{ }列表》，则应返回：
{ "necessary": ["{<feature>}列表"] }这样智能体就能明确告知用户缺什么，用户补齐后再重新触发评审。
情形二：评审完成时
{ "review": "markdown格式描述评审结果" }review字段的值是一段 Markdown 格式的评审结果文本（原技能文件中该 JSON 示例缺少收尾引号与右花括号，实际输出时应保证是合法完整的 JSON）。评审结果以 Markdown 描述，既便于人类阅读，也便于其他技能（如后续的概要设计生成）引用其中结论。
两种响应是互斥的：资料不齐走necessary，资料齐备走review。这正是 fagency.md 中"智能体执行技能，按照大模型返回的数据调用函数"模式下的标准返回形态。
评审结果的组织建议
技能文件只定义了"以 Markdown 格式描述评审结果"，未限定具体章节。结合需求文档的生成约束与其他评审技能的惯例，一份高质量的review输出可以按以下结构组织（以下为基于仓库相邻文档推导的实操建议）：
- 评审结论摘要：先用一两句话给出总体结论——需求文档是否完整覆盖了全部功能点；
- 逐功能点覆盖矩阵：将《{ }列表》中的功能点逐一列出，标注其在《需求文档》中的覆盖状态（已覆盖 / 部分覆盖 / 缺失），并给出所在章节或说明；
- 操作步骤与使用方法核对：对照 需求分析.md 中"覆盖每个功能点及每个功能的具体操作步骤和使用方法"的要求，指出哪些功能点缺少使用说明；
- 遗漏与疏漏清单：列出未覆盖的功能点、表述含糊导致无法指导后续设计的条目；
- 改进建议：对每个问题给出可执行的修改建议。
值得注意的是，评审类技能（含 评审概要设计.md、评审详细设计.md）都遵循"如有必要，请指出可能存在的问题、错误和疏漏"的精神。评审不是简单的"通过/不通过"二分，而是要主动发现问题。
与相邻评审技能的分工协作
《评审需求文档》只是 fcoder 文档评审链条上的第一站，它与后续评审技能构成递进关系：
| 技能 | 必要资料 | 评审核心 |
|---|---|---|
| 评审需求文档 | 《{ }列表》、《需求文档》 | 需求文档是否覆盖所有功能点 |
| 评审概要设计 | 《需求文档》、《概要设计文档》、《{ }列表》及《{ }详细描述》 | 是否为每个功能点提出技术概要方案并确认可行性 |
| 评审详细设计 | 《需求文档》、《概要设计文档》、《详细设计文档》、{ }的详细描述 | 是否满足需求、技术方案是否可行 |
| 评审代码（评审代码.md） | 《详细设计文档》、{ }、{ }、《{ }》等 | 代码是否正确实现了指定功能点（不查代码风格） |
可以看到，每一层评审都以"上一层产出 + 本层产出 + 功能点资料"作为输入，评审范围从"功能点覆盖"逐步收窄到"方案可行性"再到"代码实现正确性"。需求文档评审若放水，后续所有环节都会建立在残缺的需求之上，因此它在链条中的地位最为基础。
底层实现：技能如何被智能体按事件调度
理解了技能的作用与格式，再看仓库中的实现证据，能更清楚这套评审机制是如何运转的。
技能持久化：skills表
在 fagency.sql 中，每个技能都被持久化为skills表的一行记录，关键字段包括：
accepted_event：技能接收的事件名称（如评审需求文档技能接收的评审事件）；returned_event：技能返回的事件名称；title：技能名称，idx_skills_title唯一索引保证技能名称全局唯一（对应 README 中"技能名称必须唯一"的约束）；details：技能详细定义——即 评审需求文档.md 这类技能文件的正文；skill_type：主技能（primary）或辅助技能（auxiliary），"主技能跟智能体一直全部加载，辅助技能按需加载"（见 fcoder/README.md）。
技能与智能体、事件的关联：agent_skills表
agent_skills(agent_id, skill_id)将技能挂载到具体智能体。文档评审智能体要能执行"评审需求文档"，正是通过这条关联实现的。
按"智能体+事件"查询技能：SkillsDAO
在 SkillsDAO.cj 中，findSkills(agentId, event)使用 ORM 注解@DAO执行 SQL：
select s.id, ag.agent_id, s.accepted_event, s.returned_event, s.title, s.metadata, s.details from skills as s inner join agent_skills as ag on s.id = ag.skill_id where ag.agent_id = ${arg(agentId)} and s.accepted_event = ${arg(event)}这段查询印证了 fcoder 的事件驱动技能模型："智能体+事件确定若干主技能和若干辅助技能"——当一个智能体收到某事件时，就按agent_id与该事件的accepted_event匹配出对应技能，加载其details（技能定义）作为本次处理的指令。评审需求文档技能被选中后，智能体便按照其中的规则与响应格式执行评审。
评审流程在事件拓扑中的位置：agent&event 表
agent&event.md 给出了智能体间的事件流转关系，例如RequirementReviewer接收RequirementsPreview事件，处理后发送SpecReview事件；SystemArchitect接收RequirementSpec、PreliminaryReview等事件。评审类智能体产出的SpecReview事件会继续驱动后续设计与评审环节，形成"需求分析 → 需求评审 → 概要设计 → 概要评审 → 详细设计 → 详细评审 → 声明生成 → 代码实现 → 代码评审 → 提交"的完整闭环。
知识检索支撑
评审过程中若对功能点含义、领域知识不确定，技能允许调用 functions.md 中定义的函数：search（搜索引擎+本地知识库的"全文+向量"查询）、read（本地知识库的确切标题搜索）、select（本地知识库的"全文+向量"查询），从knowledge表（见 fagency.sql）检索规范、经验、技术文章等知识，避免凭空捏造评审结论。
使用建议与注意事项
- 先补资料再评审：发起评审前先确认两份必要资料齐备；缺任何一份，技能都会以
necessary响应要求补齐，无需勉强开工。 - 评审结果保持 Markdown 结构化：
review字段内尽量使用标题、表格、列表组织结论，让后续智能体（概要设计生成、详细设计生成）能够直接引用其中的覆盖结论。 - 只审覆盖性，不越界：需求文档评审只关注"功能点是否覆盖 + 操作步骤/使用方法是否齐全"，不应在此阶段要求技术方案细节——那是概要设计评审的职责。
- 保持流程完整：按照 软件工程.md 的要求，每一步都可能与用户交互多次，只有用户明确指示时才进入下一步；若用户想跳过评审，应礼貌说明必须先完成哪些步骤。
- 语言与 token 考量：fcoder 运行手册（fcoder/README.md）指出在 token 信息密度上中文更有优势，因此评审结果与评审过程中尽量使用中文描述，既节省 token 也便于与中文需求文档对齐。
小结
《评审需求文档》是 fcoder 规范驱动开发流程中第一道也是最重要的一道质量闸门：它以《{ }列表》为标尺，对《需求文档》做功能点覆盖性检查，通过necessary/review两种 JSON 响应与智能体程序完成稳定交互。其背后是skills、agent_skills等数据库表与事件驱动调度机制的支撑——理解了这张技能卡片，也就理解了 fcoder 技能体系"原子化、结构化、可调度"的设计全貌。
- 后端
- Web框架
【免费下载链接】fountain
一个用于服务器应用开发的综合工具库。 - 零配置文件 - 环境变量和命令行参数配置 - 约定优于配置 - 深刻利用仓颉语言特性 - 只需要开发动态链接库，fboot负责加载、初始化并运行 - 覆盖服务器应用开发的各种场景
相关推荐
详细设计评审技能实战指南：fcoder 智能体如何对照需求与概要设计评审《详细设计文档》
详细设计评审技能实战指南：fcoder 智能体如何对照需求与概要设计评审《详细设计文档》 导读 在 fcoder（喷泉开源软件工作室的人工智能编程工具）的规范驱
后端Web框架fcoder 评审《概要设计文档》技能解析：功能点覆盖与方案可行性双重校验的 Agent 规范
fcoder 评审《概要设计文档》技能解析：功能点覆盖与方案可行性双重校验的 Agent 规范 本篇指南围绕 fcoder（喷泉开源软件工作室的智能软件工程工具
后端Web框架fountain 项目 fcoder 智能体「评审代码」技能规范解析：基于详细设计文档的代码评审工作流
fountain 项目 fcoder 智能体「评审代码」技能规范解析：基于详细设计文档的代码评审工作流 在 fountain 仓库的 fcoder 子系统中，
后端Web框架
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
