fcoder 详细设计技能深度解析:AI 智能体如何把《详细设计文档》变成可执行的施工蓝图
fcoder 详细设计技能深度解析:AI 智能体如何把《详细设计文档》变成可执行的施工蓝图
《详细设计文档》是软件工程从"架构蓝图"走向"可编码实现"的最后一公里。在 fountain 仓库的 fcoder 项目中,这一环节被封装为一个标准化的 AI 技能(Skill):当用户指示生成《详细设计文档》时,fcoder 智能体会严格按照《需求文档》与《概要设计文档》的约束,为指定功能点输出一份"只谈技术实现方案、不写具体代码"的详细设计,并以约定的 JSON 格式回传,供后续评审、建包、生成声明、实现代码等环节消费。阅读本文后,你将完整掌握 fcoder 中详细设计技能的定义规则、触发条件、硬性约束、JSON 响应协议,以及它在整个智能体事件流水线中的位置和下游消费方式。
一、详细设计技能在 fcoder 中的地位
fcoder(位于 fcoder/README.md)是 fountain 仓库中一个"在命令行运行的人工智能编程工具",它把软件研发流程拆解为"智能体(Agent)—事件(Event)—技能(Skill)—函数(Function)"四层模型。其中:
- 智能体是流程的节点,执行一次流程时,一个智能体可能多次接收不同事件、使用不同技能处理;
- 技能是流程的边,是原子化的,只做一件事;
- 事件是沿着技能边在各个智能体节点之间流转的数据。
详细设计技能正是这条流水线上的一个重要"边"。在 fcoder/docs/agents/软件工程.md 中,fcoder 以"资深软件工程专家"角色把软件开发流程编排为严格有序的九个步骤:
- 发散性阐述功能点及可行性分析(技能:可行性分析);
- 生成《需求文档》(技能:需求分析);
- 评审《需求文档》(技能:评审需求文档);
- 生成《概要设计文档》(技能:概要设计);
- 评审《概要设计文档》(技能:评审概要设计);
- 生成《详细设计文档》(技能:详细设计);
- 评审《详细设计文档》(技能:评审详细设计);
- 创建必要的包路径(技能:创建包路径);
- 生成顶级声明及公共成员声明(技能:生成顶级声明及公共成员声明)。
这些步骤之间是强顺序依赖的:只有用户明确指示进入下一步时才能进入下一步;若用户试图跳过环节(例如拿到《需求文档》后直接要求生成《详细设计文档》),fcoder 会要求先补齐"评审《需求文档》→生成《概要设计文档》→评审《概要设计文档》"等前置步骤。详细设计技能正是在这种流水线纪律的保障下,才拥有可信的输入(已评审的需求与概要设计)作为生成依据。
二、触发条件与必要资料
详细设计技能的完整定义位于 fcoder/docs/skills/详细设计.md,其核心规则如下:
- 触发条件:当用户指示"生成《详细设计文档》"时;
- 任务目标:按照《需求文档》和《概要设计文档》,为指定功能点输出《详细设计文档》,提出详细的技术实现方案;
- 必要资料:《需求文档》、《概要设计文档》。文档明确要求:"如果缺少必要资料请务必告知用户"——即智能体不得在缺少输入文档的情况下自行脑补需求或架构假设;
- 内容要求:文档中特别强调,输出必须"务必提到技术实现细节及可能遇到的困难和问题及坑点",即详细设计不仅要给出"怎么做",还要给出实现路径上的风险清单;
- 信息收集义务:"若对用户请求相关的内容或代码库结构不确定,请使用工具读取文件以收集相关信息,切勿猜测或捏造回复。"
这意味着详细设计技能内置了反幻觉机制:智能体在不确定代码库结构或用户请求语义时,必须先通过工具读取文件取证,而不是凭训练记忆编造设计依据。
三、⚠️ 关键点:详细设计阶段的硬性约束
该技能文档用 ⚠️ 标记 标出了必须遵守的关键点,可归纳为三条红线:
- 只提方案,不写代码:"详细设计阶段仅提出具体且详细的技术实现方案,不要涉及具体代码。"详细设计是编码前的"施工蓝图",过早引入具体代码既会限制后续实现环节的自由度,也会让设计文档与代码实现产生双份维护成本;
- 缺资料必须告知:缺少《需求文档》或《概要设计文档》时,不得强行输出,必须明确告知用户补齐资料;
- 知识缺口必须检索:如果智能体"不知道详细设计应当包含哪些内容",必须调用 search 函数查阅相关概念和知识,而不是凭印象输出一份结构残缺的文档。
其中 search 函数定义在 fcoder/docs/functions.md,其能力为"搜索引擎+本地知识库的'全文+向量'查询",关键参数包括:
| 参数 | 含义 | 默认值/建议 |
|---|---|---|
keywords |
从用户需求提取的关键词列表,多个关键词用英文逗号分隔 | 必填 |
embeddingWeight |
向量匹配权重,文本匹配权重为 1.0 - embeddingWeight |
0.7;专业术语可调低,口语化/语义优先内容可调高 |
minConfidence |
搜索结果可接受的最低置信度 | 0.8 |
maxResults |
搜索结果最大返回数量 | 10 |
这一机制解释了为什么详细设计技能能够保持领域知识的实时性:当设计对象涉及智能体不熟悉的概念时,它通过 search 混合"全文+向量"检索本地知识库与外部搜索,再结合读取代码库文件,形成有证据支撑的设计结论。
四、《详细设计文档》应包含哪些内容
技能文档规定,当智能体不知道详细设计文档的组成结构时,应通过 search 函数查阅相关知识。仓库中与之配套的参考文档 fcoder/docs/references/详细设计.md 给出了完整的知识体系,可作为详细设计文档的内容骨架:
- 计算机科学基础理论——数据结构与算法(数组、链表、树、图、哈希表,排序/查找/递归及复杂度分析)、操作系统原理(进程线程、内存分配、I/O 机制)、数据库系统(关系范式、SQL、索引优化、事务 ACID)、计算机网络(TCP/IP、HTTP/HTTPS),这些是设计的"建筑材料",决定模块在并发处理、资源管理、高性能场景下的正确性与效率;
- 软件设计方法与原则——结构化设计(自顶向下、逐步求精、顺序/选择/循环三种控制结构)、面向对象设计(封装、继承、多态、类/对象/接口、设计模式如工厂/单例)、SOLID 原则(单一职责、开闭、里氏替换等)、领域驱动设计 DDD(领域模型、统一语言、限界上下文);
- 详细设计核心任务技能——模块逻辑设计(用程序流程图、N-S 图、PAD 图或伪代码 PDL 精确描述模块内部处理流程与算法)、数据结构设计(数据库表结构、字段、索引及内存中数据结构组织)、接口设计(模块间与外部系统的调用方式,含 API 参数、返回值、异常处理与通信协议)、人机界面设计(用户控制、减少记忆负担、界面一致性);
- 设计工具与文档规范——UML 建模工具(类图、序列图、状态图)与《详细设计说明书》的编写规范(模块功能、算法描述、接口说明、数据结构、测试用例设计)。
参考文档以知识图谱形式给出了四者的定位关系:
| 知识领域 | 具体知识点 | 应用场景 |
|---|---|---|
| 基础理论 | 数据结构、算法、操作系统、数据库、网络 | 保证设计的正确性、高效性和稳定性 |
| 设计方法 | 结构化设计、面向对象设计、设计模式、DDD | 提升代码的可维护性、可复用性和可扩展性 |
| 核心技能 | 模块逻辑设计、数据结构设计、接口设计 | 将宏观架构转化为微观的、可编码的实现方案 |
| 工具与规范 | UML 建模、伪代码、详细设计说明书 | 清晰传递设计意图,便于团队协作和后期维护 |
结合详细设计技能本身的约束("提出详细的技术实现方案""提到技术实现细节及可能遇到的困难和问题及坑点"),一份合格的 fcoder 详细设计文档可以理解为:以需求与概要设计为输入,围绕上述知识体系组织"模块逻辑、数据结构、接口、异常与边界、风险坑点"五个维度,输出一份不含具体代码、但足够指导编码的精确施工指令。
五、响应格式:智能体与技能的 JSON 协议
详细设计技能通过结构化的 JSON 与上层智能体通信,这是其"可被其他程序稳定调用和集成"的关键。协议分两种情形:
情形一:需要调用函数(如 search 查询知识)时:
{
"function": "函数名",
"params": ["参数1", "参数2"...]
}
情形二:直接返回详细设计文档时:
{
"details": "以markdown格式描述详细设计文档"
}
也就是说,详细设计文档本身以 Markdown 格式承载,但被包裹在 details 字段中作为结构化 JSON 返回。这种"内容用 Markdown、传输用 JSON"的双层设计,既保证了文档的可读性与富文本表达能力,又保证了智能体事件流对返回数据的程序化解析能力——下游智能体不必去"理解"自然语言,只需按 details 键取值即可。
六、详细设计文档的下游消费链
详细设计文档不是终点,它是 fcoder 流水线中后续多个环节的共同输入,形成一条完整的"设计→评审→建包→声明→实现→测试"消费链:
1. 评审环节
fcoder/docs/skills/评审详细设计.md 规定:评审《详细设计文档》时,需对照《需求文档》、《概要设计文档》、《详细设计文档》及功能点的详细描述,确认是否满足了需求并确认技术方案可行性,必要时指出存在的问题、错误和疏漏。缺资料时返回:
{
"necessary": ["缺省的必要资料名称", "一份资料一个字符串"]
}
评审通过后输出:
{
"review": "markdown格式描述评审结果"
}
2. 创建包路径
fcoder/docs/skills/创建包路径.md 要求"按照提供的《详细设计文档》输出必要包目录",返回:
{
"packages": ["path/of/package1", "path/of/package2"]
}
详细设计中规划的数据结构、接口归属哪个模块,在这里落地为真实的包目录结构。
3. 生成顶级声明及公共成员声明
fcoder/docs/skills/生成顶级声明及公共成员声明.md 以《详细设计文档》+ 包目录结构 + 目标语言为输入,生成带文档注释的顶级声明与公共成员声明,且明确要求只生成声明、不提供具体实现。声明注释需描述:顶级声明的能力、成员声明的功能、函数形参的意义、返回的类型。返回格式为 JSON 数组,每个代码文件一个对象:
[{
"packageName": "path/of/package_name",
"codeFileName": "top_level_declaration.cj",
"declarationCode": "顶级声明的代码,包含顶级声明内的成员声明,只有声明不要包含具体实现"
}]
4. 实现功能点
fcoder/docs/skills/实现功能点.md 规定实现指定功能点时,必要资料为《详细设计文档》、包结构、《语言》与工具库摘要;不确定时通过 select 函数查阅标准库/工具库、通过 search 函数搜索信息。实现代码同样以 JSON 数组返回(含 packageName、codeFileName、implementation 字段)。
5. 单元测试与代码评审
fcoder/docs/fagency.md 显示:测试技能以《详细设计文档》、待测代码文件、语言与单元测试规范为必要资料生成白盒单元测试用例;代码评审技能则以《详细设计文档》与代码文件为准绳,确认是否"正确实现了相应功能点"。详细设计文档因此成为衡量实现是否符合预期的评审基准。
七、详细设计环节在智能体事件流中的位置
fcoder/docs/agents/agent&event.md 以事件表形式刻画了详细设计相关节点在整条流水线中的流转:
| Agent | 接收事件 | 发送事件 |
|---|---|---|
| Supervisor | Start, SpecReview, CodeReview | Requirements, FeasibilityReview, FeasibilityReport, RequirementReview, RequirementSpec, PreliminaryReview, PreliminarySpec, DetailReview, DetailSpec, Code&Spec, CodeCommitation, ToCommit |
| ApplicationArchitect | PreliminarySpec, DetailReview | DetailPreview |
| DetailReviewer | DetailPreview | SpecReview |
| SeniorEngineer | DetailSpec | Decl |
| Developer | Decl, Code&Spec | Impl&Spec |
可见详细设计的完整事件链为:DetailReview(详细设计评审请求)→ ApplicationArchitect 产出 DetailPreview(详细设计预览/草案)→ DetailReviewer 评审后回 SpecReview → 通过后生成 DetailSpec(详细设计规格)→ SeniorEngineer 接收 DetailSpec 产出 Decl(声明)→ Developer 接收 Decl 与 Code&Spec 产出 Impl&Spec(实现与规格)。详细设计文档在事件流中以 DetailSpec 的形态,成为从架构设计(PreliminarySpec)到代码声明(Decl)之间的关键数据载体。
八、从详细设计技能看 Skill 设计的最佳实践
fcoder/README.md 的"良好 skills 指南"总结了五条技能设计原则,详细设计技能正是这五条原则的典型体现:
- 原子性(Atomicity):详细设计技能只做一件事——把已评审的需求与概要设计"翻译"为不含代码的实现方案,边界清晰,便于与评审、建包、声明、实现等技能组合复用;
- 给例子(Few-Shot Prompting):技能文档直接给出两种响应情形的完整 JSON 示例,模型无需理解抽象描述即可照格式输出;
- 立规矩(Structured Instructions):定角色(资深软件工程专家)、拆步骤(触发→检查必要资料→收集信息→输出)、画红线(不写代码、缺资料必须告知、不确定必须查证),三道防线共同抑制幻觉;
- 造接口(Interface Design):
{"function": ...}与{"details": ...}两个固定 JSON 协议,使技能可以被任何遵循协议的智能体稳定调用; - 勤复盘(Iterative Refinement):技能文档用 ⚠️ 标注强化关键约束,实际使用中的"Bad Case"(如漏提技术细节、编造代码库结构)可不断沉淀为新的规则与反例。
同时,从 fcoder/README.md 的"规范驱动开发(Specification-Driven Development)"视角看,详细设计文档对应其中 Plan(技术方案设计) 阶段的 design.md 产物——它记录架构设计图、数据模型变更、API 接口定义、技术选型理由与潜在风险评估,为后续 Tasks(任务分解) 与 Implement(代码生成与实现) 提供唯一权威依据。
总结
fcoder 的详细设计技能以 fcoder/docs/skills/详细设计.md 为核心定义,通过"必要资料强校验、⚠️ 关键点约束、search/read 取证、JSON 结构化输出"四重机制,把软件工程中"详细设计"这一专业环节固化为智能体可稳定执行、可被下游程序化消费的原子能力。它衔接需求与概要设计(上游)、评审与建包声明实现(下游),是 fcoder 智能体流水线中承上启下的关键"边"。对于想要在自建 AI 编程工具中复刻类似能力的开发者,这份技能定义本身就是一份高质量的 Skill 范本:清晰的触发条件、明确的输入输出协议、强制性的反幻觉规则,以及围绕"技术细节 + 困难 + 坑点"的产出要求,都值得直接借鉴。