用途:使用 hal-walk CLI 探索 HAL+JSON API,并通过跟随链接发现 API 能力,最终把一次探索过程固化为无需推理即可重放的确定性路径规范。
主要能力:start 从 API 根开始会话;position 查看当前位置、响应与可用链接;describe 获取某链接关系的文档(输出 markdown,而非 JSON);follow 跟随关系执行请求;goto 本地跳回已记录位置;render 生成会话图的 Mermaid 图;export 从会话图导出路径规范;session-viewer 启动网页界面查看会话图。除 describe 外,各命令向 stdout 输出 JSON。
使用方式:先用 npx hal-walk start -s session.json <API根URL> 建立会话,再 position 查看可跟随的链接,对不熟悉的关系用 describe 读文档获取 HTTP 方法、输入 schema 与响应示例,然后用 follow 执行。follow 支持 --body、--body-schema、--uri-template-values(RFC 6570)、--headers、--header-schema、-m/--method、-n/--note;默认 GET,提供 --body 时默认 POST,PUT/DELETE 需显式 --method。探索完成后用 render 可视化、export 导出路径规范,可用 --from/--to 导出子路径。
核心原则:不要手工构造 URL,一切从当前位置的可用链接出发;遇到陌生关系先 describe 再操作;CURIE 如 wiki:v1:pages 由 describe 自动展开;会话本身是图,可随时 goto 回溯。
适用场景:发现、浏览或对接 HAL API 时进行链接驱动式探索与集成记录,把探索过程沉淀为可被简单执行器重放的规范。
限制:同一交互需依赖 hal-walk CLI 与 Node 环境;仅针对 HAL+JSON 风格 API;探索需遵循 API 文档给出的方法与 schema,资料未提供具体收费、平台支持范围或其他约束信息。