ddev-detail

name	ddev-detail
description	代码修改场景下，spec 文档确认后，需要继续以图优先方式梳理结构体定义、数据流和流程时使用

实现结构体与数据流工作流

作用

当 spec 文档已被确认，需要在编码前继续细化结构体、数据流、流程图等实现细节时使用。默认先出图，再补极少文字。本 skill 仅用于代码改动场景。

文档表达原则

detail 文档默认采用“图优先，文辅佐”表达，只写本次改动需要落地的结构体、数据流、流程和约束：

• 图: 新增或修改哪些结构
• 图: 关键数据怎么流动
• 图: 关键流程怎么分发和收敛
• 文: 补少量实现约束

不要把本可画清的关系翻写成长段说明。文字只补限制、例外和阅读提示。

不要写“明确不做什么”“这部分不负责什么”的清单。凡是 detail 文档没有写到的结构、数据流、流程和约束，默认都不属于这次改动范围。

它负责把 spec 文档进一步拆成三类图文产物：

• 结构关系图和结构定义文档
• 数据流图文档
• 关键流程图文档

⚠️ 硬门禁：画图前必须先加载 ddev-diagram

在任何 ASCII 图动笔之前，必须执行 Skill("ddev-diagram") 加载绘制规范。加载完成前禁止写任何 ASCII 图。

详细拆解文档默认落到 docs/plans/YY-MM-DD_<topic>/detail/，按职责拆成：

• <name>-overview.md
• structures/<name>.md
• dataflow/<name>.md
• flows/<name>.md
• tests/<name>.md（可选，由 ddev-pc-test skill 产出）

overview / index 类总览文档必须放在 detail/ 根目录，不要放进 structures/、dataflow/、flows/ 或 tests/。子目录只放对应职责的详述文档和图源。

根目录 overview 必须包含一张"文档分布与说明"文本图，把本次 detail 下生成的所有文档、目录层级、阅读顺序和文档用途可视化出来。

如果某一类文档过长，不要继续往单文件里堆，先在 detail/ 根目录保留短总览，再把详述、错误路径、状态迁移、图文说明拆到对应子目录。

默认处理结构体、缓冲区、协议帧、配置和数据流等实现细节。支持 C / Rust / C++ / Python / TS 等多种语言，输出重点是”状态归属、数据边界、流程分发”。

对于 C 项目（.c / .h），本阶段必须加载 ddev-c-pro 和 ddev-comment-gen skill，将设计规范、命名规范、Doxygen 注释标准落实到结构体定义、API 签名和文档约束中。对于其他语言项目，如果有对应的编码规范 skill，也应在此阶段加载并落实。

何时进入这一步

只有在下面条件基本成立时才进入：

• 已能唯一定位本次改动对应的 spec 文档
• spec 文档中的模块边界、接入点、主流程已经基本确认
• 接下来准备进入实现计划或编码，需要把状态、结构体和流程进一步讲透

如果还在反复改模块边界、职责切分或接入方式，先回到 ddev-spec，不要在这里提前堆细节。

细化范围

这个 skill 只细化本次改动真正相关的结构体、数据流和关键流程。

这里写出来的内容，应当能直接支撑下游实现计划和最终验收；没有写进 detail 文档的部分，默认不进入这次实现拆解。

开始前先收集

开始前至少定位这些输入：

• 已确认的 spec 文档路径
• 本次改动涉及的功能主题或模块名
• 已知会受影响的代码范围或目录

以下为强制步骤，不可跳过：

• 现有结构体定义、状态枚举、协议帧定义：必须从实际源码（头文件 .h）中搜索并读取
• 结构体复用检查：在定义任何新增结构体之前，必须搜索已有结构体中是否存在可管理同类状态的候选——
  • 搜索包含同名/近名字段的已有结构体（grep 字段名）
  • 搜索已有 context/handle 结构体，判断新增状态是否可直接作为其成员
  • 搜索同模块已有的 _t 类型定义，避免创建功能重叠的新类型 结果写入 detail 文档的结构体来源标注中：每个"新增"结构体必须附带"复用/扩展已有不可行的理由"（一句话即可，如"生命周期不同""所属模块不同"）。
• 相关时序图、流程图、接口文档（如有）
• 用户明确点名的约束，如”不能新增全局变量””必须兼容现有协议”

代码现状收集方法（优先级递减）

优先使用 CodeGraph 结构化查询：

1. 从 spec 文档提取涉及的模块名
2. codegraph_search 搜索对应结构体名/枚举名/typedef 名
3. codegraph_node 获取完整定义（含字段类型、注释）
4. codegraph_explore 批量获取相关符号源码

CodeGraph 未初始化时回退方案：

5. grep 在头文件（*.h）中搜索 typedef struct / enum / typedef 声明
6. Read 打开搜索到的头文件，确认精确定义

收集产物

收集结果必须体现在 detail 文档中：

• 每个结构体/枚举必须标注来源：源码路径和行号（若来自已有代码），或”新增”（若为本次新设计）
• 不得凭空定义与源码中已有定义冲突的结构体或枚举

基本流程

1. 读取已确认的 spec 文档，先提取模块边界、主流程、关键状态和接入点。
2. 只提取本次改动涉及的结构体、状态枚举、缓冲区和协议载荷。
3. 区分新增、修改、复用、废弃候选。每个结构体/枚举必须标注来源：
   • 复用/修改：标注源码路径和行号（如 src/module/xxx.h:42）
   • 新增：标注为"新增"，并确认不与源码中已有名称冲突 不要在这一步直接删历史设计。
4. 先画结构关系图，再用极少文字标注职责、生命周期、所有权、读写方和状态归属。
5. 再画数据流图，串清入口、转换点、状态迁移、错误出口和输出。
6. 最后只为关键链路出流程图；能靠图说明的内容，不再重复写成长文。
7. 如果单份文档过长或混了多个职责，就按模块或子流程继续拆分，不要硬塞。

推荐产物顺序

建议按下面顺序落盘，避免前后反复打架：

1. detail/<name>-overview.md
2. detail/structures/*.md
3. detail/dataflow/*.md
4. detail/flows/*.md

detail/<name>-overview.md 必须索引所有子文档。dataflow 和 flows 文档必须引用对应结构体文档名，保证后续 ddev-gate 能做一一映射。总览先给图，再给一句话导航。

长文档拆分策略

拆分目标是避免单份 detail 文档过长，确保 AI 和后续实现者都能快速定位，优先按图的职责拆。

什么时候必须拆

出现下面任一情况，就不要继续维持单文件：

• 一个文档同时覆盖多个彼此相对独立的子模块或子流程
• 一份数据流文档里同时塞了总览、每步细节、错误路径、状态迁移和大段图说明
• 流程图文档已经需要同时解释多条主链路，读者必须频繁上下跳转
• 同一文件里已经出现“总览”和“大段逐步骤说明”互相打架
• 预期编码时不可能每次都把这份文档完整放进上下文

拆分原则

• 先在 detail/ 根目录保留一个短总览文件，负责入口、边界、索引和导航
• 再把高细节内容拆到子文档，不要把细节继续塞回总览
• 图和长说明可以分离；图文强绑定时，保留一个简版图文文件，再把长说明拆出去
• 拆分后文件名必须让人一眼看懂层级，不要出现 final-v2、misc 这类无语义命名
• 总览文件必须反向列出所有子文档，否则拆完只会更难找
• 不要在 dataflow/、flows/ 或 structures/ 目录里创建 *-overview.md；这些目录里的文档应当是具体详述、错误路径、状态迁移、主流程图或结构体说明

推荐拆法

detail 根目录

如果主题较复杂，先建立总览入口：

• <name>-overview.md

其中 overview 只放范围、主链路、边界、引用关系、文档分布图、简图、子文档列表和阅读顺序。

数据流目录

如果数据流较复杂，优先把细节拆成：

• dataflow/<name>-details.md
• dataflow/<name>-errors.md
• dataflow/<name>-states.md

其中：

• details 放逐步骤转换、字段流转、模块协作细节
• errors 放错误入口、回退、重试、异常出口
• states 放状态迁移、状态持有者、枚举含义、并发边界

如果规模更大，再按子链路拆，例如：

• dataflow/rx-details.md
• dataflow/tx-details.md
• dataflow/rx-errors.md
• dataflow/tx-errors.md

流程图目录

如果单张流程图已经覆盖多个问题，优先把图和路径拆成：

• flows/<name>-main.md
• flows/<name>-exceptions.md

其中：

• main 放主流程图和必要简述
• exceptions 放异常路径、超时、失败处理、回退流程

结构体目录

如果结构体很多，不要做一个超长总表。优先按模块或职责拆：

• structures/<module>-context.md
• structures/<module>-payloads.md
• structures/<module>-buffers.md
• structures/<module>-states.md

如果仍需总入口，再补一个：

• detail/<name>-overview.md

总览文件最低要求

总览文件必须位于 detail/ 根目录，至少要包含：

• 这组文档覆盖什么范围
• 这组文档这次实际要落地哪些内容
• 为什么需要拆分
• 文档分布与说明文本图
• 子文档列表及一句话用途
• 关键结构体 / 关键状态 / 关键图源索引
• 阅读顺序建议

文档分布图使用手写 ASCII / text 图，不依赖 PlantUML 渲染。示例：

detail/
├── printer-job-overview.md        # 总入口：范围、阅读顺序、文档分布
├── structures/
│   ├── job-context.md             # 作业上下文与状态所有权
│   └── page-buffer.md             # 页面缓冲区生命周期
├── dataflow/
│   ├── rx-details.md              # 输入到作业上下文的数据转换
│   ├── rx-errors.md               # 输入错误、回退和状态复位
│   └── rx-states.md               # 状态迁移和持有者
├── flows/
│   ├── main.md                    # 主流程图与简述
│   ├── exceptions.md              # 异常路径流程
└── tests/                         # 可选，由 ddev-pc-test 产出
    ├── protocol-overview.md       # 测试总览与可测试性结论
    ├── protocol-cases.md          # 测试用例清单
    └── protocol-env.md            # 测试环境与依赖

阅读顺序：overview -> structures/job-context -> dataflow/rx-details -> flows/main

图文分离规则

如果图本身不复杂，但文字说明很长，优先采用：

• 一个短 detail/<name>-overview.md 放图和 3-8 行说明
• 一个 dataflow/<name>-details.md 或 flows/<name>-main.md 放长解释

如果图本身就复杂到需要独立维护，则采用：

• .md 只放 ASCII 图和用途说明

不要把几十行图源、ASCII 图和长篇解释混在同一个 markdown 里。

引用约束

拆分后必须保证：

• detail/<name>-overview.md 文件能跳到所有子文档
• details/errors/states 文件明确回指 detail/<name>-overview.md
• flows 文档明确指向对应 dataflow 文档
• dataflow 文档明确指向对应 structures 文档

如果拆完之后还需要靠全文搜索才能知道去哪里看，说明拆法失败。

结构约束强化

根据项目语言，在 detail 阶段强化对应语言的结构约束。

C 项目（.c / .h）

必须先加载 ddev-c-pro skill，这一步必须把”禁全局变量、禁分支失控、禁职责混杂”落实到结构体和数据流层，同时加入 ddev-c-pro 的通用编码规范：

• 先找出所有运行时状态，把它们收敛到明确的上下文结构体，而不是散落成多个全局变量
• 状态归属去重：在收敛状态前，先确认同类状态是否已被已有 context 管理。如果已有 context 已管理打印机状态，新增字段应优先扩展该 context，不得创建"第二个打印机状态管理者"（无论是新 context 还是新全局变量）。
• 函数功能去重：对每个新增函数，先搜索已有代码中是否存在功能等价的实现；如果存在可扩展的已有函数，标注为"扩展已有"而非"新增"。
• 区分配置、会话状态、缓存、输入载荷、输出结果，不要堆进一个大而全结构体
• 为每个关键状态标注谁创建、谁修改、谁释放、谁只读
• 对阶段性流程显式定义状态枚举，禁止用裸整数或魔法值表示阶段
• 一旦发现数据流依赖大量条件拼接，回头重构结构和流程，不接受”靠更多 if/else 补齐”
• 若缓冲区、协议帧或配置存在共享读写，必须写清并发边界和责任划分
• 结构体成员注释使用 Doxygen 行内格式（/**< */，必须用中文，参照 ddev-comment-gen skill），公开 API 的 @brief / @param / @return 必须使用中文
• 类型名统一 _t 后缀，公开 API 统一模块前缀，宏全大写 + 模块前缀，私有函数用 static
• 结构体/缓冲区声明中的大数字（≥1024）必须写成 N * 1024 / N * 1024 * 1024 可读表达式并命名宏（如 MOD_TX_BUF_SIZE (16 * 1024)），禁止在结构体定义或示例代码里裸写大数

结构体与数据流文档必须回答的问题

在结构体文档和数据流文档里，至少要明确：

• 哪些字段属于长期状态，哪些只是单次调用临时值
• 哪些缓冲区应该属于上下文，哪些应该停留在局部变量
• 是否存在任何本可封装却被设计成共享可变状态的内容
• 关键分发点是按什么字段或状态驱动的，后续实现准备使用 switch、状态机还是表驱动
• 哪些函数只消费数据，哪些函数负责状态迁移，避免一个函数吞下整条链路
• 错误路径如何退出，资源或状态如何回滚、复位或留待下次继续处理
• 哪些字段或状态必须跨线程 / 回调边界传递，谁负责同步保护
• 公开 API 的 Doxygen 注释格式是否已按 ddev-comment-gen skill 在文档中明确；模块命名前缀、类型 _t 后缀、错误码枚举是否已按 ddev-c-pro skill 在文档中明确

文件组织

建议按职责拆成这些目录：

• references/：规则、模板、判断标准
• structures/：结构体定义文档
• dataflow/：数据流规划文档
• flows/：流程图文档
• tests/：PC 测试用例文档（由 ddev-pc-test skill 产出，可选）

如果内容复杂，可以在这些目录下继续使用“入口索引 + 分主题子文档”的方式，而不是强行维持单层平铺。

结果要求

• 结构体文档要能以图为主回答“干什么、谁在用、依赖什么”
• 数据流文档要能以图为主看清入口、转换、输出和边界
• 流程图文档要和结构体定义、数据流规划互相对得上，且不靠大段文字才能读懂
• 如果做了拆分，总览文档要足够短，详述文档要足够专，不能拆成多个同样冗长的文件

如果是 C 项目，还要额外满足：

• 能看出状态已经从”全局散点”收敛为”结构化上下文”
• 能看出分支复杂度是通过数据建模和流程建模被压下来的，而不是留给实现阶段堆条件
• 能直接支撑后续把函数按单一职责拆开
• 命名规范、错误码约定已按 ddev-c-pro skill 在文档中明确；Doxygen 注释标准已按 ddev-comment-gen skill 在文档中明确，可直接作为编码和审查依据

对于其他语言项目，需要满足：状态所有权清晰、数据边界明确、关键流程分发策略可在图中直接读出。具体编码规范和注释标准由对应语言的审查 skill 决定。

最低验收

完成这一步后，至少应能直接交给下游使用：

• ddev-plan 可以据此拆出精确的实现步骤
• ddev-gate 可以据此对照“结构体、状态、数据流、关键分支”是否按设计落地

如果当前 detail 文档还做不到下面任一项，就不算完成：

• 能唯一指出本次变更涉及哪些结构体是新增、修改还是复用
• 能通过图明确指出主数据链路的入口、出口、转换点和错误路径
• 能指出关键状态由谁持有、谁修改、谁只读
• 能指出关键流程图对应的结构体文档和数据流文档

常见失败模式

• 把 detail 文档写成代码现状复述，没有形成新的实现约束
• 只列字段，不写所有权、生命周期和读写方
• 数据流只写主链路，不写错误出口、回退路径或状态迁移
• 流程图覆盖过宽，把多个子问题硬揉成一张图
• 文档路径、文件名和引用关系不统一，导致下游无法定位
• 还没确认 spec 边界，就在 detail 阶段发明新的模块职责
• 明明已经过长，仍坚持单文件，导致 AI 和实现者都无法快速定位
• 拆了很多文件，但没有总览入口，导致阅读路径比拆分前更差
• 把 overview / index 总览文档放进 dataflow/ 或 flows/，导致 detail 根目录没有统一入口

自检

detail 文档完成后，必须逐项核对：

1. 源码溯源：每个结构体/枚举是否能追溯到实际源码中已有定义（含文件路径和行号），或明确标注为"新增"？
2. 命名冲突检查：新增的结构体/枚举名称是否与源码中已有名称冲突？
3. 所有权明确：每个关键状态是否标注了谁创建、谁修改、谁释放、谁只读？
4. 错误路径覆盖：数据流文档是否包含了错误出口、回退路径或状态迁移？
5. 下游可用性：ddev-plan 是否能据此拆出精确的实现步骤？ddev-gate 是否能据此对照验收？
6. 文档完整性：是否有总览入口？子文档之间是否能互相跳转？
7. 无代码现状复述：文档是否形成了新的实现约束，而非仅仅描述代码现状？
8. 结构体去重：每个标注为"新增"的结构体，是否已确认无已有结构体可管理同类状态？是否有"扩展已有结构体"被误判为"必须新增"？
9. 全局变量合理性：detail 文档中是否引入了文件级/全局级变量？如有，每个是否已给出无法收敛到已有 context / 局部变量的理由？
10. 依赖方向：新增字段/函数的归属模块是否正确？是否出现在 A 模块的 context 中管理 B 模块的专属状态？是否出现底层结构体引用上层类型？

如有任一项不通过，必须在修复后再进入下一步。

完成后

这一步确认完之后：

• 可选进入 ddev-pc-test，判断本次修改是否可在 PC 上写测试 demo 直接验证；如果可以则产出测试用例文档和 demo 代码。如果不需 PC 测试或不可测试，直接跳过。
• 再进入 ddev-plan 把已经确认的内容拆成可执行步骤。

如果实现已完成、准备验收，则把这些 detail 文档作为 ddev-gate 的直接输入。若此前通过 ddev-pc-test 产出了测试 demo，ddev-gate 阶段必须跑通该 demo。

⚠️ 阶段交接硬门禁

本 skill 完成后，禁止 agent 自动进入下游阶段（ddev-pc-test / ddev-plan / ddev-gate）。

• 完成 detail 文档后，向用户报告产出路径和关键结论。
• 提示用户可选的下一步（如"进入 ddev-plan 拆解执行计划"、"进入 ddev-pc-test 评估可测试性"），但必须等待用户明确确认后再加载对应 skill。
• 用户未明确说"进入下一步""继续""开始 plan/pc-test/gate"等指令前，停留在当前阶段，不自行推进。

参考

• 结构体拆分规则
• 结构体文档模板
• 数据流文档模板
• 流程图文档模板