--- name: wayfinder description: 将单个 agent 会话无法理清的大型工作拆成一组相互关联的决策问题，并通过 issue 追踪器逐步解决，直到后续执行路径明确。 disable-model-invocation: true --- 用户带来一个还很松散的想法：规模大到一个 agent 会话无法完成，而且从现状到**目标**的路径还不清楚。本 skill 负责找出这条路径，而不是直接朝目标动手。 做法是在仓库的 issue 追踪器上建立一张**共享地图**，然后逐个处理其中的**决策项**，直到路径明确。决策项是需要解决的问题，解决后得到一个决定，而不是一块要实现的功能。 目标因工作而异，确定目标是建图的第一步，它会影响每一个决策项。目标可能是一份需要继续迭代的规格、开始规划前必须确定的决定，或者一次可以直接完成的改动（例如数据结构迁移）。地图不限于工程领域，课程内容等工作只要形态合适也可以使用。 目标是交付一个产品、子系统或一组面向用户的功能时，地图还要维护一份**功能清单**，列出要交付的全部功能项，以及每项的发布批次、交互要求和设计依据。格式、位置和修改规则见 `docs/agents/feature-list.md`；没有这个文件时，告诉用户运行 `/setup-dev-skills`。 决策项只保证每个决定都已作出，不保证功能项已梳理完全。所以功能清单也是地图完成条件的一部分，见“路径明确之后”。 ## 只规划，不实现 默认情况下，本 skill 只做**规划**：每个决策项解决一个决定；路径明确、实现前已没有需要决定的事项时，地图就完成了。 想直接动手实现，通常说明规划已经完成，应该进行交接。某项工作可以在地图的**备注**中改变这条规则，把实现也纳入地图；没有这样写时，只产出决定，不产出交付物。 ## 用标题指代 issue 每张地图和每个决策项都是一个 issue，都有标题。在给人阅读的内容中（叙述、地图的“已做决策”），用标题指代 issue，而不是只写 id、编号或 slug。满屏的 `#42, #43, #44` 难以阅读，标题一眼就能看懂。 id 和 URL 仍然保留：把标题写成链接，让它们藏在标题后面，而不是替代标题。 ## 地图 地图是本仓库 issue 追踪器上带 `wayfinder:map` 标签的 issue，是这项工作的正式产物。决策项是地图的子 issue。 地图是**索引**，不存放细节。它列出已经作出的决定，并链接到记录细节的决策项。每个决定只记录在一个地方，也就是对应的决策项中，所以地图不复述决定，只写要点并附链接。 **地图、子 issue、依赖关系和“可领取决策项”查询的具体表达方式取决于追踪器。** issue 追踪器配置应该已经提供给你；如果没有，告诉用户运行 `/setup-dev-skills`。查看追踪器文档中的“寻路操作”一节，了解*本*仓库如何表达它们。完全没有追踪器配置时，默认使用本地 Markdown 追踪器。 ### 地图正文 地图正文是整项工作的概览，每个会话读取一次。未关闭的决策项**不**列在这里：它们是未关闭的子 issue，通过查询获取。 ```markdown ## 目标 <完成这张地图后得到什么：这项工作要确定路径的规格、决定或改动。一两行即可；每个会话选择决策项之前都先对照它。> ## 备注 <所属领域；每个会话都应使用的 skill；这项工作的长期偏好；功能清单的链接（有时）> ## 已做决策 - [<已关闭决策项标题>](链接)：<答案的一句话要点> ## 尚未明确 ## 不在范围内 ``` ### 决策项 每个决策项是地图的一个**子 issue**，追踪器的 issue id 就是它的标识。正文写问题本身，规模应能在一个 agent 会话内解决： ```markdown ## 问题 <这个决策项要解决的决定或调查> ``` 每个决策项带一个 `wayfinder:<类型>` 标签，取值为 `research`、`prototype`、`design`、`grilling`、`task` 之一（见[决策项类型](#决策项类型)）。 **认领**：会话开始处理某个决策项时，**第一件事**就是把它指派给推进地图的开发者，然后才开始任何工作。这样并行的其他会话会跳过它。指派即认领：未关闭且未指派的决策项就是未认领的。 **依赖关系**：使用追踪器**原生**的依赖功能。这一点很重要，因为追踪器界面会直接显示哪些决策项可以领取，人不必打开地图就能看到。只有追踪器不支持原生依赖时，才改用正文约定。 一个决策项的所有前置决策项都关闭后，它就**解除阻塞**。**可领取决策项**是未关闭、未阻塞、未认领的子 issue。 答案不写在正文里，而是在解决时记录（见[推进地图](#推进地图)）。解决过程中产生的资料从 issue 链接出去，不粘贴进正文。 ## 决策项类型 每个决策项要么是 **HITL**（human in the loop，需要一个人实时参与并代表自己发言），要么是 **AFK**（由 agent 独立完成）。HITL 决策项只能通过实时交流解决；agent 不能替人发言（自问自答的追问就违反了这一点）。 - **调研**（AFK）：阅读文档、第三方 API 或本地资源（如知识库），找出某个决定所需的事实。派一个子代理使用 `research` skill 解决。需要当前工作目录之外的知识时使用。 - **原型**（HITL）：做一个低成本、粗略但具体的产物（一份大纲、一个粗略方案、一个桩、UI 或逻辑代码），让讨论更具体。使用 `prototype` skill，并把原型作为资料链接到 issue。关键问题是“它应该是什么样子”或“它应该怎么表现”时使用。 - **设计**（HITL）：为一个或一组功能项产出设计依据。原型一次只回答一个问题；设计决策项要把页面的关键交互和界面形态明确到能照着实现。按设计来源选择做法： - 已有外部设计稿（设计工具文件、导出图）：导出到功能清单约定的设计资料目录，核对关键流程与交互是否齐全，缺的由人补充。 - 需要比较几个方向：使用 `prototype` skill，选定变体后整合决定并作为设计依据。 - 风格方向已经确定，只缺具体页面：agent 按设计系统和已确定的核心页面，做出关键页面原型，请人确认。 - 完成即解决：功能清单中对应功能项的设计依据已链接，关键交互与界面形态已有设计或原型明确说明，并且人已确认。按清单规则，普通页面可以用“参照某个页面实现”或继承通用设计系统作为设计依据，这条决定同样需要人确认。 - **合并处理**：同一业务模块的普通页面可以放进一个设计决策项，在一个会话中做完，由人一次确认。核心页面每个单独一项，或者最多 3 个一组。 - **追问**（HITL）：通过对话解决，这是默认类型。分别使用 `grilling` 和 `domain-modeling` skill。 - **任务**（HITL 或 AFK）：作出某个决定之前必须先完成的手动工作。它本身不需要决定、原型或调研，但讨论因它无法推进，例如注册某个服务以便评估它的 API、开通访问权限、导出数据以便了解其结构。 - 这是唯一一种“做事”而不是“作决定”的类型，它的价值在于让某个决定可以推进，而不是交付目标。 - agent 能独立完成的就独立完成（AFK）；否则给人一份精确的清单（HITL）。需要人来操作时，使用 `wizard` skill。 - 完成即解决；答案记录做了什么，以及后续决策项依赖的结果（凭据存放位置、新 URL、数据行数）。 ## 尚未明确的问题 地图*刻意*保持不完整：还看不清的部分先不写成决策项。当前决策项之外，存在一些**尚未明确的问题**：你能预见它们会出现，但因为依赖尚未解决的问题，现在还无法准确描述。 每解决一个决策项，都可能让一部分尚未明确的问题变得清晰。把已经能够准确描述的问题转化为新的决策项，直到通往目标的路径明确、不再剩下决策项。 地图的**尚未明确**一节用来记录这些问题：猜测中的问题、以后要回头查看的区域。这里的一切都在范围内，只是还不够清晰，无法写成决策项。能写多具体就写多具体，能写多完整就写多完整；它也能让协作者了解这项工作的走向。 **写成决策项，还是放进尚未明确？** 判断标准是你*现在*能否准确描述这个问题，*而不是*现在能否回答它。 - **写成决策项**：问题已经清晰，即使它依赖其他决策项、暂时无法处理。 - **放进尚未明确**：你还无法把它描述清楚。不要提前把它切成决策项的粒度：它比决策项更粗，时机成熟时可能转化为好几个决策项，也可能一个都不需要。 **尚未明确**不包括已经作出的决定（写在“已做决策”）、已经是当前决策项的问题，以及不在范围内的工作（见下一节）。 ## 不在范围内 尚未明确的问题都指向目标。目标确定了范围，所以超出目标的工作属于**不在范围内**，而不是尚未明确的问题。地图上有单独的**不在范围内**一节，记录被有意排除在*这项*工作之外的事项。决定一件事放在这里的是范围，而不是清晰度。 不在范围内的工作不会转化为决策项。只有目标被重新划定时，它才可能重新出现，而且会作为一项新工作，而不是当前工作的延续。 判定某件事不在范围内，是在划定范围，而不是在推进决策。已有的决策项被发现位于目标之外时（建图时误纳入，或某个决策结果揭示了这一点）： 1. **关闭它**，让它明确退出可领取范围； 2. 在**不在范围内**一节加一行：要点和不在范围内的原因，并链接到已关闭的 issue。 它不写进**已做决策**，那里记录的是实际作出的决策；范围边界不属于决策过程。 ## 调用 有三种模式：建立地图、梳理功能清单、推进地图。无论哪种，**每个会话最多解决一个决策项**，调研类决策项除外。 ### 选择模式 - **建立地图**：用户带着一个松散的想法调用。读 [MAP-SETUP.md](MAP-SETUP.md) 的“建立地图”。 - **梳理功能清单**：涉及复杂前端交互或多端产品，需要为地图补充功能项与设计依据时。读 [MAP-SETUP.md](MAP-SETUP.md) 的“梳理功能清单”。 - **推进地图**：用户带着一张地图（URL 或编号）调用。按下文执行。 ### 推进地图 用户带着一张地图（URL 或编号）调用。可以指定决策项，也可以不指定；不指定时，由你而不是用户选择下一个要解决的决定。 1. 读取**地图**：只读概览，不读每个决策项的正文。 2. 选择决策项。用户指定了就用指定的；否则按顺序选第一个可领取决策项。**认领它**：在开始任何工作之前指派给自己。 3. 解决它。**按需查看细节**：随时读取任何相关或已关闭决策项的完整正文；使用**备注**中列出的 skill。拿不准时，分别使用 `grilling` 和 `domain-modeling` skill。 4. 记录结果：把答案发成一条**解决评论**，**关闭** issue，并在地图的“已做决策”中**追加一个上下文指针**。答案影响功能清单时（补上交互要求或设计依据、新增功能项），同步更新清单；满足条件的功能项把结论改为“已确定”。 5. 更新地图： - 添加新发现的决策项（先创建，再建立依赖关系）。 - 把因本次答案而变得清晰的问题转化为决策项，并从**尚未明确**中删除这些问题，让它们只以新决策项的形式存在。 - 答案表明某个决策项（当前这个或其他）位于目标之外时，**判定为不在范围内**，而不是作为决策去解决。涉及功能项时，按清单规则由用户确认后再改结论。 - 本次决定让地图其他部分失效时，更新或删除相应的决策项。 用户可能同时推进多个未阻塞的决策项，所以要预期其他会话也在编辑追踪器。 ## 路径明确之后 路径明确需要同时满足： - 没有可领取或被阻塞的决策项，**尚未明确**一节为空； - 有功能清单时，**当前批次**中没有结论为“待定”的功能项；当前批次每个“已确定”的功能项都明确了交互要求与设计依据（核心页面有设计稿或原型，普通页面至少有“参照某个页面实现”的决定）。更晚批次的功能项可以仍是“待定”；切换到下一个批次时，继续推进同一张地图。 - 当前批次涉及的非功能需求都有可测量的目标值。 功能清单还有缺口时，把缺口转成 `design` 或其他类型的决策项，继续推进地图。 路径明确后，**只交接，不实现**：通过 `/to-spec` 进入主流程，把地图上链接的决定整理成可实现的规格，然后照常运行 `/to-tickets`、`/implement` 或 `/implement-spec`。告诉用户下一步运行哪个命令。