用途
uw-graph 的用途是导出 docs/unwind/rebuild-graph.json —— 即 Unwind 仪表盘所渲染的合并知识图谱构件。它将确定性的扫描结果、覆盖差异和分层文档融合成一张图,图中每个节点都带有一个 rebuild 信息块。
何时需要
只在希望不启动服务器就生成该 JSON 时需要:静态部署、CI、分享或对构件做 diff。交互式查看不需要它,unwind:uw-dashboard 在启动前会自行重新生成图谱。这是可选的导出,不是必须经过的流程检查点。
两种图谱的区别
scan-manifest.json(由 uw-scan 生成)是事实来源,是驱动种子、覆盖差异和完整性的文件/符号/导入图;分析类技能读取它,而不读取本技能的输出。rebuild-graph.json(本技能输出)是 manifest + 覆盖 + 文档的可刷新投影,只有仪表盘会读取,上游不读回。因此它位于线性流程末端(此时信息最丰富),但不驱动分析,也并非严格必须最后执行:可在 uw-scan 之后立即生成结构视图,并在任何阶段后重新运行以刷新。任何时候重新生成都安全。
回退行为
若 Node/pnpm 或 @unwind/core 不可用,或尚无 scan-manifest.json,脚本会以非零状态退出并给出明确提示。需先运行 uw-scan;该图谱是增强项,不是硬依赖。
输入(均为确定性数据)
- 结构:docs/unwind/.cache/scan-manifest.json,提供文件/函数/类/表/端点节点及导入边。
- 覆盖:docs/unwind/.cache/coverage/{layer}.json,提供 rebuild.coverage(scanned / documented / verified)。
- 分层文档:docs/unwind/layers/**/*.md,提供 rebuild.priority(MUST/SHOULD/DON'T)与 rebuild.docRef。
- 进度覆盖(可选):docs/unwind/.cache/rebuild-progress.json,提供 rebuild.rebuildStatus(人工维护,不会被覆盖)。 前两项由 uw-scan 和 uw-verify 技能生成。覆盖与文档为可选项,缺失时图谱仍会构建,所有节点标记为 scanned / not-started。
使用方式
步骤一:构建图谱。先定位已安装的 Unwind 插件,加载核心辅助脚本,然后运行 build-graph.mjs:
UNWIND_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${UNWIND_PLUGIN_ROOT:-}}"
[ -f "$UNWIND_PLUGIN_ROOT/skills/scripts/_resolve-plugin-root.sh" ] || \
UNWIND_PLUGIN_ROOT="$(ls -dt "$HOME"/.claude/plugins/cache/*/unwind/*/ 2>/dev/null | head -1)"
source "${UNWIND_PLUGIN_ROOT%/}/skills/scripts/_resolve-plugin-root.sh"
ensure_unwind_core || { echo "core unavailable — skip rebuild graph"; exit 0; }
node "$UNWIND_PLUGIN_ROOT/skills/scripts/build-graph.mjs" "$(pwd)"
脚本会加载 manifest(候选 id 方案保证节点与覆盖报告 1:1 关联),构建节点(文件及其符号)与边(contains、imports、按路径约定生成的 tested_by),并充实每个节点的 rebuild 块:coverage(covered-by-anchor-id → verified,covered-by-name → documented,missing → scanned,DON'T 标记 → excluded);priority 与 docRef(从 [MUST]/[SHOULD]/[DON'T] 标记及记录该条目的 markdown 文件中解析);contractKind(db-table / api-endpoint / event-schema / formula);rebuildStatus(若存在 rebuild-progress.json 则合并,否则由覆盖推导,覆盖层始终优先,重新生成不会抹除人工进度)。随后用 validateRebuildGraph 校验(id 唯一、无悬空边、每个节点有明确优先级)并写出文件,最后打印节点/边/层数量及覆盖明细摘要。
步骤二:报告。转述打印的摘要,并告知用户产物位置 docs/unwind/rebuild-graph.json。由于这是构件导出路径,可提及用户运行它的可能原因(静态部署 / CI / 分享)。若用户实际想查看图谱,应指向 unwind:uw-dashboard,而不是把本步骤当作必需环节。
流程为:scan → analyze → grill → plan → dashboard。uw-graph 是位于旁侧的可选导出,仪表盘会自行构建图谱。
rebuild 块结构
{
"priority": "MUST", // MUST | SHOULD | DON'T | null
"contractKind": "db-table", // db-table | api-endpoint | event-schema | formula | null
"coverage": "verified", // scanned | documented | verified | excluded | stale
"docRef": "docs/unwind/layers/database/tables.md",
"rebuildStatus": "verified" // not-started | in-progress | done | verified
}
重新运行
每次扫描或文档变更后重新运行都安全。要记录人工重建进度,可按节点 id 写入 docs/unwind/.cache/rebuild-progress.json,例如:
{ "table:src/db/schema.ts:users": { "rebuildStatus": "in-progress" } }
适用场景与限制
适用于需要静态部署、CI 集成、分享或 diff 图谱构件的场景。限制:需已安装插件并具备 Node/pnpm 与 @unwind/core,否则跳过;缺少 scan-manifest.json 时无法构建;覆盖与文档可缺失但会降低图谱信息丰富度;本技能不驱动分析,也不替代仪表盘的交互式查看。