wayfinder

一个松散的想法出现了，它太大，无法在一次 Agent 会话中完成，而且笼罩在迷雾之中：从这里通往目的地的路还看不清。Wayfinding 的目标是找到这条路，而不是直奔目的地。这项技能会在代码仓库的问题跟踪器上绘制一张共享地图，然后逐个处理其中的决策票据（需要通过解决问题来作出决策，而不是可直接执行的构建任务片段），直到路线清晰为止。

每项工作的目的地各不相同，标明目的地是绘制地图的第一步：它会决定每张票据的内容。目的地可能是一份待交接并迭代完善的规范、一个必须在开始规划前敲定的决策，也可能是在原地完成的变更，例如数据结构迁移。这张地图不局限于特定领域：无论是工程工作、课程内容，还是其他符合这种形式的内容，都可以纳入其中。

规划，而非执行

Wayfinder 默认用于规划：每张票据都要解决一个决策；当路线清晰，在有人开始执行前不再有待决定的事项时，地图就算完成。想直接动手通常意味着你已走到地图的边界，该交接了。某项工作可以在其备注中明确覆盖这一默认方式，将执行工作也纳入地图；但若没有这样的说明，就产出决策，而非交付成果。

按名称引用

每张地图和每张票据都是一个问题，因此都有一个名称：它的标题。在人类会阅读的所有内容中（叙述、地图的“已做出的决策”），都要用名称来引用它，绝不要只用 ID、编号或 slug。满屏的 #42, #43, #44 难以辨认；名称则能让人一眼看懂。ID 和 URL 并不会消失；名称会包装其链接，但它们应当_包含在_名称中，绝不能取代名称。

地图

地图是在本代码仓库的问题跟踪器上创建的一张问题，标记为 wayfinder:map，是权威记录。地图的票据是它的子问题。

地图是索引，不是存储库。它会列出已作出的决策，并链接到记录详细内容的票据；每项决策只记录在一个地方，也就是对应的票据中，因此地图不会重述决策，只会概述并附上链接。

地图、子票据、阻塞关系和前沿查询具体存放在哪里，取决于所用的问题跟踪器。 只有当用户或聊天历史指定了问题仓库时，才使用外部问题跟踪器。否则，默认使用本地 Markdown 跟踪器。

地图正文

以低分辨率呈现的完整地图，每个会话只加载一次。开放票据不会列出：它们是开放的子问题，通过查询查找。

## Destination

<what reaching the end of this map looks like: the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

## Notes

<domain; skills every session should consult; standing preferences for this effort>

## Decisions so far



- [<closed ticket title>](link): <one-line gist of the answer>

## Not yet specified



## Out of scope

票据

每张票据都是地图的子问题；问题跟踪器的问题 ID 就是它的身份。其正文是一个问题，工作量应控制在一次 100K token 的 Agent 会话内：

## Question

<the decision or investigation this ticket resolves>

每张票据都带有一个 wayfinder:<type> 标签，类型为 research、prototype、grilling、task 之一（参见票据类型）。

会话开始处理票据时，必须先将票据分配给负责推进地图的开发者，以此认领票据，然后才能开始任何工作，这样并行会话就会跳过它。被分配的人_就是_认领者：开放且未分配的票据即为未认领。

阻塞关系使用问题跟踪器的原生依赖关系：这很重要，因为它会在跟踪器自己的 UI 中_直观地_呈现前沿，让人无需打开地图，就能看到哪些票据可以处理。只有不支持原生阻塞关系的跟踪器，才会改用正文约定。每张阻塞该票据的票据都已关闭时，该票据才算未受阻塞；前沿是开放、未受阻塞且未被认领的子票据，也就是已知范围的边界。

答案不属于正文内容；解决票据时会记录答案（参见处理地图）。解决票据时创建的资源应链接到问题中，而非直接粘贴进去。

工单类型

每个工单要么是 HITL（human in the loop，与人类一起完成，由人类本人发表意见），要么是 AFK，完全由 Agent 独自推进。HITL 工单只能通过这种实时交流来解决；Agent 不能代替人类一方发言（一个自己回答自己问题的 grilling Agent 就违反了这一点）。

• Research（AFK）：阅读文档、第三方 API 或知识库等本地资源，以找出某个决策所依赖的事实。由子代理调用 Skill tool 并传入 "research" 来完成。当需要当前工作目录之外的知识时使用。
• Prototype（HITL）：通过制作一个低成本、粗略但具体的产出物（大纲、粗略方案、桩代码，或 UI/逻辑代码）来提高讨论的保真度，供各方评审。调用 Skill tool 并传入 "prototype" 来完成。将原型作为资产进行链接。当关键问题是"应该长什么样"或"应该如何运作"时使用。
• Grilling（HITL）：对话。这是默认情况。必须调用两次 Skill tool，分别传入 "grilling" 和 "domain-modeling"。
• Task（HITL 或 AFK）：在做出_决策_之前必须完成的手动工作：没有需要决定、制作原型或调研的内容，但讨论在其完成之前无法推进。例如注册某项服务以便评估其 API、开通访问权限、迁移数据以便查看其结构。这是唯一_执行_而非决策的类型，其价值在于解除某个决策的阻塞，而不是交付最终目标。Agent 能独自完成时由其推进（AFK）；否则将精确的清单交给人类（HITL）。完成工作后即视为解决；结果需记录已完成的操作以及后续工单所依赖的结果性事实（如凭据位置、新 URL、行数）。

战争迷雾

地图_有意_保持不完整：不要绘制你还看不清的部分。在现有工单之外，是战争迷雾：对那些你能察觉即将出现、但目前无法明确界定的决策与调查的模糊视图，因为它们依赖于仍未解决的问题。解决一个工单会清除其前方的迷雾，并将现已可明确界定的内容逐一转化为新工单，直到通往目标的路径清晰、不再有遗留工单为止。

地图中的尚未明确部分用于记录这种模糊视图：疑似的问题与之后需要重新审视的区域。它是通往目标的未探索前沿：其中的一切都在范围之内，只是还不够清晰，无法立为工单。可以按视图允许的程度或详或略地书写；它同时也是供协作者了解工作方向的路标。

迷雾还是工单？ 判断标准是你现在能否精确地陈述这个问题，_而不是_你现在能否回答它。

• 当问题已经明确时立为工单，即使它被阻塞、暂时无法行动。
• 当你还无法如此精确地表述时，列入尚未明确。不要把迷雾预先切分成工单大小的片段：它比工单更粗略，一个条目在前沿抵达时可能转化为多个工单，也可能一个都不转化。

尚未明确不包括已决定的内容（已做出的决策）、已存在的现行工单，以及超出范围的内容（下一节）。

超出范围

迷雾只会朝着目的地收敛。目的地界定了范围，因此超出范围的工作就是超出范围：它不是迷雾，也不属于尚未明确。它会在地图上单独列入超出范围部分：你有意识地排除在_本次_工作之外的事项。决定它归入此处的是范围，而非清晰度。

超出范围的工作永远不会进入前沿（前沿止于目的地），因此只有在重新绘制目的地时才会再次出现，而且届时它属于一项全新的工作，而不是继续之前的工作。

将某事排除在范围之外是一项范围界定行为，而不是路线上的一步。如果现有工单后来被发现位于目的地之外（绘制路线时误纳入范围，或在问题得到明确后才显露出来），就关闭它（已关闭的工单明确不在前沿上），并在超出范围部分留下一行说明：概述该事项及其超出范围的原因，并链接到已关闭的工单。它不会列入迄今的决策，因为该部分记录的是实际走过的路线；范围边界并不是路线上的一步。

调用方式

有两种模式。无论哪种，每个会话最多只能解决一个工单，研究工单除外。

绘制地图

用户提出一个宽泛的想法。

1. 明确目的地。 针对 "grilling" 和 "domain-modeling" 各调用一次 Skill 工具，以确定这张地图要找出的目标：规范、决策或变更。目的地界定范围，因此要先确定。
2. 绘制前沿。 再次进行 grilling，不过这次要按广度优先的方式：全面探索整个空间，而不是深入某个单独的主题，找出尚未确定的决策，以及现在可以采取的第一步。如果没有发现任何迷雾（前往目的地的路线已经清晰，整个旅程小到可以在一个会话内完成），就不需要绘制地图。停止并询问用户希望如何继续。
3. 创建地图（标签为 wayfinder:map）：填写 Destination 和 Notes，Decisions-so-far 留空，并将迷雾概略地写入尚未明确部分。
4. 创建现在可以明确具体内容的工单，作为地图的子问题，然后在第二轮中关联阻塞关系（问题需要先有 ID，才能相互引用）。关联后即可区分前沿和受阻事项；尚无法明确具体内容的部分都留在迷雾中，即尚未明确部分。
5. 启动研究子 Agent。 对于刚创建的每个 research 工单，启动一个子 Agent，调用 Skill 工具并传入 "research"，并行解决该工单；将其发现记录在临时的 research/<name> 分支上，并从工单附上上下文指针。
6. 停止：绘制地图是一项单会话工作；不直接解决任何问题。

沿地图推进

用户通过地图（URL 或编号）调用。

1. 加载地图：查看低分辨率概览，而不是每个工单的正文。
2. 选择工单。如果用户指定了工单，就使用该工单；否则按顺序选择前沿中的第一个工单。认领它：开始工作前先将它分配给自己。
3. 解决工单。按需深入查看：需要时获取任何相关工单或已关闭工单的完整正文；调用 ## Notes 区块中提到的技能。若不确定，就针对 "grilling" 和 "domain-modeling" 各调用一次 Skill 工具。
4. 记录解决结果：将答案作为解决结果评论发布，关闭问题，并在地图的 Decisions-so-far 中追加上下文指针。
5. 添加新发现的工单（先创建，再关联）；将答案使其变得可明确具体的迷雾内容提升为工单，并从尚未明确中清除每一块已提升的内容，使其只存在于对应的新工单中。如果答案表明某个工单（当前工单或其他工单）位于目的地之外，就将其排除在范围之外，而不是在路线中解决。如果某项决策使地图的其他部分失效，就更新或删除相应工单。

用户可能会并行处理未受阻的工单，因此要预期其他会话也在同时编辑跟踪器。