用途
Waypoint 用于为跨多个文件的流水线（pipeline）和流程建立分布式导航标记。每个文件携带一个紧凑的注释块，标明其 ID、在流水线中的角色、相邻节点，以及指向完整地图的指针；每条流水线有一份清单（manifest）保存完整拓扑。grep 任意 8 字符 ID 即可展开整条流水线。
主要能力
- ID 生成：
id <path>...为每个文件打印<id> <path>，ID 由 git 相对路径的 SHA-256 前 8 位十六进制生成，具有确定性。 - 扫描：
scan编目所有地图文件和代码中的块，按流水线分组，用于先检查是否已有 waypoint。 - 清单生成：
manifest从 stdin 读取 JSON 规格，写出.ai/waypoints/<name>.md，包含丰富的地图布局。 - 块生成与放置：
block从 stdin 读取 JSON 规格组合源块；--write --at <line>在文件中放置或更新，--dry-run --at <line>预览放置位置而不写入。 - 漂移检测：
verify [pipeline]检测过期行、孤立块以及 ID 与路径不再匹配的情况。 - ID 校正：
check-ids从路径重新计算 ID，并在文件移动时输出精确的修正列表。
所有子命令均支持 --json 输出机器可读结果；verify 和 check-ids 发现漂移时以非零状态退出。
使用方式
CLI 调用形式：
python3 <skill-path>/scripts/waypoint.py <subcommand> [args]
映射一条流水线的步骤：
- 检查已有内容：运行
waypoint scan。若流水线已映射，读取其清单，将其视为更新而非全新放置，保留仍然正确的节点。 - 跨文件追踪流程：使用常规阅读工具沿导入、脚本调用、Dockerfile 阶段、共享环境变量与版本字符串、CI 步骤顺序等线索追踪。识别两类节点：
- Flow（from/into，显示为 ←/→）：执行链中的文件。
- Reference sinks（reads/feeds，显示为 ◁/▷）：在运行时消费某个值、但不处于构建或部署序列中的文件。 在放置任何内容前确认从入口到出口的完整路径；节点角色不清晰时阅读该文件。
- 生成 ID：对每个文件运行
waypoint id <path>...，一次调用完成。ID 由 git 相对路径确定，不可自行编造。 - 编写清单：组合 JSON 规格（含流水线名称、开头句、有序节点、拓扑），管道传给
waypoint manifest。节点按执行顺序排列，sink 放最后。CLI 从路径推导每个节点的 ID，因此清单与块始终一致。 - 在每个文件中放置块：为每个节点组合块规格并运行
waypoint block --write --at <line>，锚点行由用户选择：配置文件、脚本、清单和流水线专属文件放在文件顶部；源文件放在流水线触及的具体函数或代码段正上方。 - 验证：运行
waypoint verify <pipeline>，解决报告的任何漂移后再报告完成。
当同一源代码行参与两条或更多流水线时，在该块的规格中给出多个 flow，CLI 会将它们堆叠在同一 ID 下。
读取与审计：
- 列出全部/查找入口点：
waypoint scan，然后打开清单第一行。 - 检查漂移：
waypoint verify（全部流水线）或waypoint verify <pipeline>（单条）。 - 文件移动：
waypoint check-ids列出每个过期 ID、新值以及需要更改的相邻引用；应用修正后重新运行 verify。 - 从任意节点追踪：grep 其 8 字符 ID，或沿块和清单拓扑中的 →/← 追踪。
块格式
CLI 负责组合块。Waypoint <id> 锚点和符号图例出现在每个块中，便于首次阅读者即时解码和 grep。单流源块紧凑，参考路径位于头部，结尾一行同时携带 grep 提示和图例。多流行将多个 flow 堆叠在同一 ID 下，各自命名自己的参考。地图文件 .ai/waypoints/<name>.md 保留丰富布局：开头叙述句、按执行顺序排列且 sink 在最后的节点表，以及 ## Topology graph。开头句是系统中最重要的一行，应写成一句话，按顺序走过流水线各阶段，说明每阶段发生什么以及为什么。CLI 写文件，用户写句子。每个块以文件的原生注释语法渲染，CLI 从扩展名解析；注释语法表和 --comment 覆盖选项记录在 references/cli.md。
分工
CLI 负责结构，确保始终正确且不漂移：ID、注释语法、块框架、布局、放置与更新、清单渲染、验证。用户负责文字，因为判断和温度无法模板化：每个文件扮演的角色、每个相邻节点做什么、清单的开头句。写作声音指南位于 references/waypoint-voice.md，在撰写任何角色或相邻描述前加载。用户还需做出 CLI 无法做出的一个放置判断：全新块应放在哪一行之上。CLI 组合文本，用户选择锚点并通过 --at 传入。
适用场景
- 多文件流水线（如 CI/CD、构建、部署流程）的导航与文档化。
- 需要跨文件追踪流程、快速定位入口点和上下游关系的代码库。
- 需要检测和修正流水线文档漂移（文件移动、ID 过期、孤立块）的场景。
限制
- 需要 Python 3 运行 CLI。
- ID 由 git 相对路径确定，文件移动后需通过
check-ids修正。 - 块写入不会删除无法证明属于本流水线的块；遇到格式不完整或属于其他流水线的邻近块时，会插入新块并给出需手动移除的建议。
- 关于收费、价格、平台支持等具体信息，资料中暂未提供。