用途
generate-spec 用于为一项工作维护一份“活规范”(living spec)。这份 Markdown 文件应与仓库保持同步:既说明已经存在的内容,也说明仍然计划中的内容。整个任务只使用同一个文件,持续编辑它,不要在之后另起一份走查文档。
主要能力
- 在 specs/<短横线命名>.md 位置创建规范文件,写之前先查清当前路径。
- 规范结构包括:标题、问题与解决方案(系统流程写在这两节)、目标、非目标、阶段,以及底部的参考。
- “Planned”部分描述实现思路,可用 Mermaid 图、调用栈和伪代码表达;调用栈中 - 表示现有代码,+ 表示拟议代码。
- 用 [[path]] 或 [[path#symbol]] 链接当前已存在的源码;尚未写出的符号不加链接。
- 某个阶段代码提交后,在 source-diff:id:path 代码块中粘贴指定文件的真实 git diff(含 diff --git、---、+++、@@ 行),并把该阶段调用栈行与 Mermaid %% ref 行指向改动行,如 [[id:new:12-18]] 或 [[id:old:…]]。
- 一份规范可以同时包含计划中的工作和已完成的工作。
- 提供 Mermaid 图、调用栈、source-diff、代码块、html 等围栏语法;html 围栏内容不会被净化,只应写在自己编写的文件中。
使用方式
在仓库根目录运行:
npx @tanishqkancharla/diffmap list npx @tanishqkancharla/diffmap serve specs/<name>.md
npx @tanishqkancharla/diffmap specs/<name>.md 与 serve 等效。若 list 已显示该文件,直接用已打印的 URL,不要启动第二个服务器。保持服务器运行,告知文件路径和 URL;除非用户要求,不要打开浏览器。关闭服务器会向 /__diffmap/shutdown 发送请求;服务器在 24 小时无使用后也会停止。托管 gist 和 GitHub 查看器没有本地服务器,因此不显示该按钮。
分享规范:
npx @tanishqkancharla/diffmap share specs/<name>.md
该命令会打印 https://diffmap.dev/g/<id>。gist 为不公开列出(unlisted),但并非私密。PR 上的规范地址为 https://diffmap.dev/<owner>/<repo>/pull/<n>/specs/<name>.md,该 URL 固定在一个提交上。分享时不要启动本地服务器。
适用场景
- 规划一项功能并需要一份可随代码演进的设计说明。
- 在 PR 中向他人展示已完成与计划中的工作。
- 代码落地后仍需更新规范以保持与仓库一致。
- 仅为说明某个 PR 做了什么、且尚无规范时,可把文件放在 tmp/ 下。
限制
- 无效的 source-diff 会导致整个页面空白;若补丁会无效,应跳过并说明。
- 对 git 尚未跟踪的文件,可运行 git diff --no-index -- /dev/null <path>,退出码为 1 表示文件不同。
- 不要编造 id 或行号范围。
- 仅在答案会改变阶段划分时才提问;否则直接写页面。
- 计划变更或用户要求实现时更新该文件,代码落地后也要更新。
以上功能、命令与行为均来自资料原文;资料未提供的收费、平台支持等信息暂未提供。