SuperAPI AI 工具集

code-walkthrough

编程与开发

查看项目

更新于 11-01 16:10

技能介绍

用途

code-walkthrough 是 diffmap 仓库下的一个技能,目标是维护一份“活规格”(living spec):用同一份 Markdown 文件在工作的整个生命周期内记录计划中的内容与已经存在于代码树中的内容,并借助 diffmap 把这份文档以可视化页面的形式提供出来,让读者能对照代码与变更来理解工作进展。它强调不要事后另写走查文档,而是持续编辑同一份 spec。

主要能力

  • 维护与仓库真实状态一致的规格文档,混合呈现“已完成”和“仍计划中”的部分。
  • 支持 mermaid 流程图、callstack 调用栈(用 diff 符号表示增删)、[[path]] / [[path#symbol]] 形式的源码链接、伪代码等其他代码块。
  • 阶段落地后,可把真实 git diff 粘贴进 source-diff:id:path 围栏,并将文件级引用重定向到具体的 hunk(如 [[id:new:12-18]]),使 Diff 面板直接打开变更而非整个文件。
  • 提供 list、serve、share 三类命令,用于列出、渲染本地文档,以及生成可分享链接。

使用方式

文档放在 specs/<short-kebab-case-name>.md。在仓库根目录执行:

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>(unlisted gist,并非私有)。PR 上的 spec 形式为 https://diffmap.dev/<owner>/<repo>/pull/<n>/specs/<name>.md(固定到某个 SHA)。分享时不要启动本地服务器。

文档结构建议为:标题、系统流程(mermaid)、问题 / 方案 / 目标 / 非目标、来源,然后是按阶段划分的实施。每个实施阶段以一两句说明该阶段是什么、为何存在;阶段应小到可独立落地(约 200 行)。计划部分用调用栈、mermaid、[[path]] 链接与伪代码勾勒实现;已完成部分则粘贴真实 git diff 并重定向引用。一个文件中同时混合计划与已完成正是其设计意图。

限制与注意事项

  • source-diff 若无效会导致整页空白,因此补丁无效时应跳过并说明。未跟踪文件可用 git diff --no-index -- /dev/null <path>(退出码 1 表示存在差异)。
  • 不应编造 source-diff 的 ID 或 hunk;不要把未写好的符号强行链接。
  • html 围栏为不受信任的 HTML,仅用于自己编写的文件。
  • 完整语法(注解、图表等)参见 diffmap README。

适用场景

解释已落地的代码变更、撰写 PR 走查说明,或在实现过程中让规格文档与代码保持同步;也适合需要向他人展示某项功能“计划 vs 实际”对照的协作场景。