wayfinder

用途

Wayfinder 用于规划一大块工作——大到超过单个智能体会话所能容纳的规模，并且从当前到目的地的路径还被迷雾笼罩、尚不可见。它的核心思路是“找路”，而不是直接冲向目的地：先把路径绘制成一张共享地图，放在仓库的 issue tracker 上，然后逐个解决地图上的决策工单，直到路线清晰。

目的地因每次工作而异，命名目的地是绘制地图的第一步，它决定了每一张工单的形态。目的地可能是一份用于交接和迭代的规格说明、一个在规划开始前需要锁定的决策，或者一项就地完成的变更（例如数据结构迁移）。地图与领域无关：工程工作、课程内容，只要符合这种形态都可以。

主要能力

• 规划而非执行：默认情况下，每张工单解决一个决策；当路径清晰、在有人动手去做之前不再有任何待决事项时，地图即告完成。想要直接动手的冲动通常意味着你已经到达地图边缘，该交接了。某次工作可以在 Notes 中覆盖这一默认，把执行纳入地图本身，但除此之外，产出的是决策而非交付物。
• 按名称引用：每张地图和工单都是一个 issue，因此都有名称（标题）。在人类阅读的一切内容（叙述、地图的 Decisions-so-far）中，都用名称引用，绝不用裸 id、编号或 slug。id 和 URL 不会消失，名称包裹着链接，但链接藏在名称之内，绝不代替名称。
• 地图即索引：地图是仓库 issue tracker 上单个带 wayfinder:map 标签的 issue，是权威产物；它的工单是地图的子 issue。地图是索引而非仓库：它列出已做出的决策，并指向承载细节的工单；一个决策只存在于一个地方——它的工单，地图从不复述，只做摘要并链接。
• 迷雾机制（Fog of war）：地图刻意保持不完整，不绘制还看不见的东西。活跃工单之外是迷雾：你能感觉到即将到来、但还无法确定的决策与调查，因为它们依赖尚未解决的问题。解决一张工单会清除它前方的迷雾，把现在可以明确表述的内容逐张升级为新工单，直到通往目的地的路径清晰、不再有工单为止。地图的 Not yet specified 部分记录这种模糊视图。判断“迷雾还是工单”的标准是：你现在能否精确陈述这个问题，而不是现在能否回答它。
• 范围之外（Out of scope）：迷雾只朝目的地聚集。目的地决定范围，超出目的地的工作属于范围之外，不是迷雾，也不属于 Not yet specified，而是单独放在地图的 Out of scope 部分。范围之外的工作永远不会升级（frontier 止于目的地），只有当目的地被重新绘制时才会作为一次全新工作回归。

使用方式

有两种模式，无论哪种，一次会话都不得解决超过一张工单（research 工单除外）。

绘制地图（Chart the map）：用户带着一个粗略想法调用。步骤包括：命名目的地（调用 Skill 工具两次，分别为 "grilling" 和 "domain-modeling"，确定这张地图要通往的规格、决策或变更）；绘制 frontier（再次 grilling，这次是广度优先，在整个空间铺开，浮现出待决事项和现在可采取的第一步；如果没有浮现迷雾，说明不需要地图，停下来询问用户如何继续）；创建地图（标签 wayfinder:map，填写 Destination 和 Notes，Decisions-so-far 留空，把迷雾勾勒进 Not yet specified）；把现在能明确的工单创建为地图的子 issue，然后在第二遍中连接阻塞边（issue 需要先有 id 才能互相引用），交叉引用也在这一遍用真实 id 写入；为每张 research 工单启动子智能体并行解决，把发现记录在一次性 research/<name> 分支上并从工单给出上下文指针，推送分支但不打开 PR（永不合并）；然后停止——绘制地图是一次会话的工作，不解决任何工单。

推进地图（Work through the map）：用户带着一张地图（URL 或编号）调用，工单可选；不指定工单时由你挑选下一个决策，而不是用户。步骤包括：加载地图（低分辨率视图，不是每张工单的正文）；选择工单（用户指定则用之，否则取 frontier 中按顺序的第一张），并在任何工作之前先把它分配给自己作为认领；按其 wayfinder:<type> 标签所命名的类型解决它（读标签，而不只是正文，正文从不声明类型），按需放大（按需获取任何相关或已关闭工单的完整正文，调用 Notes 块中列出的技能，如有疑问则调用 "grilling" 和 "domain-modeling"）；记录解决结果（把答案作为解决评论发布，关闭 issue，并向地图的 Decisions-so-far 追加一个上下文指针）；添加新浮现的工单（先创建后连接），把答案使其可明确表述的迷雾升级，并从 Not yet specified 中清除每个已升级的片段，使其只作为新工单存在；如果答案揭示某张工单（本张或另一张）位于目的地之外，则将其列为范围之外，而不是在路线上解决它；如果决策使地图其他部分失效，则更新或删除那些工单。用户可能并行运行未阻塞的工单，因此要预期其他会话会并发编辑 tracker。

工单类型

每张工单要么是 HITL（human in the loop，与能为自己发声的人类一起工作），要么是 AFK（由智能体独自驱动）。HITL 工单只能通过那种实时交流解决，智能体绝不代替人类那一方（一个自问自答的 grilling 智能体已经破坏了这一点）。

• Research（AFK）：阅读文档、第三方 API 或本地资源（如知识库），以浮现某个决策所等待的事实。由调用 Skill 工具并传入 "research" 的子智能体解决。当需要当前工作目录之外的知识时使用。
• Prototype（HITL）：通过制作一个廉价、粗糙、具体的产物（大纲、粗略方案、桩代码或 UI/逻辑代码）来提高讨论的保真度，调用 Skill 工具并传入 "prototype"。把原型作为资产链接。当“它应该长什么样”或“它应该如何表现”是关键问题时使用。
• Grilling（HITL）：对话。默认情况。始终调用 Skill 工具两次，分别为 "grilling" 和 "domain-modeling"。
• Task（HITL 或 AFK）：在做出决策之前必须发生的手动工作：没有什么可决策、可原型化或可研究的，但在它完成之前讨论被阻塞。例如注册某项服务以便评判其 API、配置访问权限、移动数据以便看清其形态。这是唯一“做”而非“决策”的类型，它靠解除某个决策的阻塞来赢得位置，而不是靠交付目的地。智能体在能独自驱动时独自驱动（AFK）；否则交给人类一份精确的清单（HITL）。工作完成即解决；答案记录做了什么以及后续工单依赖的任何事实（凭据位置、新 URL、行数）。

适用场景

当一项工作大到单个智能体会话无法容纳、且路径尚不清晰时适用。地图与领域无关，可用于工程工作、课程内容等符合这种形态的工作。

限制

• 默认只做规划、不做交付；除非在 Notes 中覆盖，否则产出决策而非交付物。
• 一次会话不得解决超过一张工单（research 工单除外）。
• 地图刻意保持不完整，不绘制还看不见的东西。
• 范围之外的工作永远不会升级，只有当目的地被重新绘制时才作为全新工作回归。
• 地图、子工单、阻塞和 frontier 查询的物理存放位置因 tracker 而异；issue tracker 应由用户提供，若未提供，需告知用户运行 /setup-matt-pocock-skills；若仍未提供 tracker，则默认使用 local-markdown tracker。
• 关于 tracker 如何表达这些内容，需查阅 tracker 文档的 "Wayfinding operations" 部分。
• 阻塞使用 tracker 原生的依赖关系；只有缺少原生阻塞的 tracker 才回退到正文约定。
• 工单正文大小以单个 100K token 智能体会话为限。
• wayfinder: 标签是地图及其工单携带的唯一标签，绝不携带 ready-for-agent 之类的分诊标签。
• 认领方式是把工单分配给自己；打开且未分配的工单即未被认领。
• 答案不属于正文，而是在解决时记录；解决工单时创建的资产从 issue 链接，而不是粘贴进去。