用途
Diffmap 用于把一次代码改动写成一个「活规格」:一个放在 specs/<short-kebab-case-name>.md 的 Markdown 文件,同时呈现系统当前状态、计划以及已完成的工作。计划变化或工作落地后更新该文件。若要讲解已有 pull request,若它已有规格则沿用,否则写到 .diffmap/ 下。写作前先核对仓库中的路径与符号。
准备工作
先确定范围,写作前阅读相关代码。当设计、范围或阶段划分不清晰时,先向用户确认:给出选项和你的建议。
预览与分享
在仓库根目录运行:
npx @tanishqkancharla/diffmap list # 若该文件已在服务中,复用其 URL
npx @tanishqkancharla/diffmap serve specs/<name>.md
npx @tanishqkancharla/diffmap share specs/<name>.md # 仅在用户要求时;输出 https://diffmap.dev/g/<id>
保持服务运行,并把文件路径和 URL 交给用户。仅在被要求时打开浏览器。分享前先提交完成的工作,并让引用指向该提交;否则没有提交的引用只会在打开时显示分享时的文件内容。分享生成的 gist 是非公开列表:任何拿到 URL 的人都能读取,包括其中快照的每个文件。pull request 上的规格也可通过 https://diffmap.dev/<owner>/<repo>/pull/<n>/specs/<name>.md 访问,并固定到某个提交。
结构
面向需要快速理解改动的人写作:从使用者看到的变化(界面、命令、API 调用、报错)说起,再按读者需要深入到实现。规格通常包含问题概述、方案概述、目标与非目标、阶段和 References,具体内容由改动本身决定。
阶段要小到可以单独提交。标题在计划中为普通文本,进行中加 ⏳,完成后加 ✅。每阶段开头用客户端视角写简短的 Today 和 Proposed,然后按改动性质展开说明:新流程可配图和调用栈,重构可用调用栈对比,依赖升级一两句话即可。篇幅与改动匹配,每件事只在合适位置说一次。规格是解释改动的文档,不是任务跟踪器。每阶段以 changes 围栏结束,放在讲解之后、下一阶段或下一节之前;在提交前留空。
可视化
当文字变长时,图、调用栈和代码往往更能说明改动。只在能向读者展示必要信息时添加。
各视图对应同一模型:服务接收消息、更新状态、再发出消息。视图或者在服务之间、或在单个服务内部,覆盖所有路径或单条消息轨迹:
- 所有路径、服务之间:mermaid flowchart,说明谁存在、谁拥有什么
- 单条消息、服务之间:services,展示消息跨服务传递及其改变的状态
- 所有路径、服务内部:伪代码与类型,说明状态、载荷、逻辑
- 单条消息、服务内部:callstack,展示一条消息如何变成结果
当各部分持有状态、并发运行或分叉时用 services;当它们是会返回、分支或提前返回的函数调用时用调用栈。services 图中的 state 指在步骤间暂停时服务内部的内容;被传回的结果是回复事件,不是 state。要说明某一步,在该事件、该更新或独立一行的服务名下加 > 注释。Mermaid sequence 和 state 图是更轻量的选择。视图超过约 7 个服务时应折叠部分并另行说明。
要展示变化,在 mermaid 或 services 后加 diff,每行以 -(仅 Today)、+(仅 Proposed)或空格(两者皆有)开头,调用栈同理。代码使用 diff 围栏。
Mermaid 图标题写在语言后,如 mermaid diff [Invalid records stop before storage]。services 围栏在第一步前用 start "caption" 作为整图标题,其下以 > 行用几句话概括完整过程;为每一步写 caption。节点和箭头使用真实名称,并用 %% ref 指令链接已有源码。
调用栈
每行写成数据流 result = function(inputs),需要时写返回行。用 -(原始)、+(改动)、空格(未变)标记;diff 比较同一函数的前后。用 ├── 和 └── 表示嵌套调用。用源码引用链接真实函数;未链接的辅助函数是伪代码,不是承诺的 API。栈保持约十几行,过深流程拆成概览和每个改动被调用者的栈。
代码
围栏要短,紧扣段落论点;未改动代码用 // ... 省略。在语言后加 {2-3} 高亮行(调用栈在之后加 {3-4} 高亮行),并用脚注说明而非长注释:// [!note symbol] text 针对任意位置出现的名称,// [!note L3-L5] text 针对从围栏顶部计数的行。调用栈用 # 写同样的注释。
链接
用引用链接已有源码;计划中的符号用纯文本。
文字风格
所有正文、注释和图标签遵循 Orwell《Politics and the English Language》中的六条规则。代码名称不算行话。
阶段完成时
进入下一阶段前:提交代码;若阶段含多次提交,在这些步骤中以 <base>..<head> 代替 SHA。把该 SHA 放进阶段末尾的 changes 围栏,它会渲染阶段摘要卡片。在 SHA 下按阅读顺序逐行列出一个评审者应读的文件:通常是面向客户端的入口在前,然后逐层向下。省略无需思考的文件,如锁文件、生成代码、快照、fixture 和机械重命名;卡片会把它们归入“N other files”。把该阶段改动的所有引用(栈行、%% ref 指令、正文)指向该提交。更新图、调用栈和伪代码以匹配实际实现,并把标题标为 ✅。单独提交规格更新,其中写明代码提交的 SHA。重启 serve,它会在启动时检查提交引用。
源码引用
路径相对于仓库根目录。[[path/to/file.ts#symbolName]] 链接 TypeScript 或 JavaScript 声明;有歧义时加限定,如 [[src/store.ts#Store.save]]。[[path]] 链接文件,[[path#L12-L30]] 链接行范围。[[<sha>:path#L12-L30]] 链接提交中的行,或用 <base>..<head> 表示跨多次提交的阶段,其中 <base> 是第一次提交之前的提交。行号按提交后编号,因此删除的行无法链接;可用 git show <sha> -- <path> 和 git show <sha>:<path> | nl -ba 查找。没有提交的引用会打开该文件的未提交改动,若没有则打开当前文件。共享 gist 打开分享时的文件内容。正文中引用渲染为可点击的行内代码;用反引号包裹可显示语法本身。在 Mermaid 中,%% ref node:<id> [[reference]] 链接节点或参与者,%% ref edge:<index> [[reference]] 链接边或消息,索引按声明顺序从零开始。每个目标用一条指令,需要时写多个引用。
围栏类型
mermaid:绘制图表services:服务、其状态及它们之间事件的可视化动画图(两者后都可加 diff 标记 - 或 +)callstack:调用栈行changes:提交或提交范围摘要(未提交改动留空),下方列出待评审文件html:你编写的受信任 HTML
其他语言视为伪代码和类型,可加 {…} 高亮和 [!note …] 行。语言后的 [Title] 可为调用栈、代码围栏或 Mermaid 图加标题,如 callstack [Request flow]。
反馈
当 Diffmap 妨碍使用或用户有反馈(渲染 bug、令人困惑的报错、缺失功能、本技能中无效的建议),到 Diffmap 仓库提 issue。先搜索,匹配则评论而非重复创建:
gh issue list --repo tanishqkancharla/diffmap --search "<keywords>" --state all
gh issue create --repo tanishqkancharla/diffmap --title "<short summary>" --body "<details>"
说明你做了什么、期望什么、实际发生什么,附上 Diffmap 版本(npx @tanishqkancharla/diffmap --version)和能复现问题的最简 Markdown。issue 是公开的,未经用户同意不要包含私有代码、文件内容、路径和 gist 链接。把 issue URL 交给用户。
更多参考
完整参考与围栏语法见 Diffmap README;示例见 annotations、diagrams 和 services fixtures。