wayfinder

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

一个松散的想法到来了——大到一个 agent 会话装不下，而且裹在迷雾里：从此处到**目的地**的路径尚不可见。寻路（Wayfinding）关乎找到那条路，而不是朝目的地猛冲。这个技能把路径绘制成仓库工单跟踪器上的一张**共享地图**，然后逐个处理它的**决策工单**——那些其解决就是一个决策（而非要执行的构建切片）的问题——直到路线清晰。

目的地因工作而异，而给它命名是绘图的第一个动作——它塑造了每一个工单。它可能是一份要交接并迭代的规格、一个在规划开始前要锁定的决策，或者一个就地做出的改动（如数据结构迁移）。这张地图是领域无关的——工程工作、课程内容，只要合乎这个形状都行。

## 规划，不做执行

Wayfinder 默认是**规划**：每个工单解决一个决策，而当路径清晰时地图就完成了——在有人去把事情做出来之前，没有剩下什么要决定的了。想要直接去做那份工作的冲动，通常是你已经到了地图边缘、该交接的信号。一项工作可以在它的 **Notes** 里覆盖这一点——把执行也带进地图本身——但在没有这一点的情况下，产出决策，而非交付物。

## 按名字指代

每个地图和工单都是一个 issue，所以它有一个**名字**——它的标题。在人类会读到的一切里——旁白、地图的 Decisions-so-far——都用那个名字指代它，绝不用一个裸的 id、编号或 slug。一堵 `#42, #43, #44` 的墙是难以辨认的；名字一眼就能读懂。id 和 URL 不会消失——一个名字包着它的链接——但它们乘在名字*内部*，绝不替代名字。

## 地图

地图是本仓库工单跟踪器上的一个单一 issue，打了 `wayfinder:map` 标签——规范的产物。它的工单是地图的子 issue。

地图是一个**索引**，不是一个存储。它列出已做出的决策并指向持有其细节的工单；一个决策恰好活在一个地方——它的工单——所以地图从不复述它，只给它一个要点并链接过去。

**地图、它的子工单、阻塞和前沿查询在物理上活在哪里，是跟踪器专属的。** 工单跟踪器应当已经提供给你——如果没有，运行 `/setup-matt-pocock-skills`。查阅跟踪器文档的「寻路操作」一节，了解*这个*仓库如何表达它们。如果没有提供跟踪器，默认走本地 markdown 跟踪器。

### 地图正文

整张地图的低分辨率版，每个会话加载一次。未关闭的工单**不**列出——它们是未关闭的子 issue，靠查询找到。

```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

<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->

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

## Not yet specified

<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->

## Out of scope

<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
```

### 工单

每个工单都是地图的一个**子 issue**；跟踪器的 issue id 是它的身份。它的正文是那个问题，大小裁到一个 100K token 的 agent 会话：

```markdown
## Question

<the decision or investigation this ticket resolves>
```

每个工单携带一个 `wayfinder:<type>` 标签——`research`、`prototype`、`grilling`、`task` 之一（见[工单类型](#ticket-types)）。

一个会话通过把工单分配给推进地图的开发者来**领取**它，在任何工作**之前**这么做，好让并发的会话跳过它。那个 assignee *就是*领取：一个未关闭、未分配的工单是未领取的。

阻塞使用跟踪器的**原生**依赖关系——这至关重要，因为它在跟踪器自己的 UI 里*可视化地*渲染前沿，所以人类不用打开地图就能看到什么是可取的。只有缺乏原生阻塞的跟踪器才回退到正文约定。当阻塞它的每个工单都被关闭时，一个工单就**解除阻塞**；**前沿**是那些未关闭、未阻塞、未领取的子工单——已知的边缘。

答案不是正文的一部分——它在解决时才被记录（见[逐个走过地图](#work-through-the-map)）。解决一个工单时创建的资产从该 issue 链接过去，而不是粘贴进去。

## 工单类型

每个工单要么是 **HITL**——人在环中，*与*一个为自己发声的人一起处理——要么是 **AFK**，由 agent 独自推进。一个 HITL 工单只通过那次实时交流才能解决；agent 绝不替人类那一方发声（一个自问自答的拷问 agent 已经破坏了这一点）。

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

## 战争迷雾

地图是*刻意*不完整的：别去绘制你还看不见的东西。在活跃工单之外躺着**战争迷雾**——那些你能感觉到即将到来、却还钉不下来的决策和调查的朦胧视野，因为它们悬于仍然未决的问题之上。解决一个工单会清除它前方的迷雾，把如今可规范化的东西毕业为新鲜的工单——一次一个，直到通往目的地的路径清晰、没有工单剩下。

地图的 **Not yet specified** 一节就是把那朦胧视野写下来的地方：可疑的问题、稍后要重访的区域。它是*朝向*目的地的未探索前沿——这里的一切都在范围内，只是还不够锐利到能开工单。视野允许多松就写多松、允许多满就写多满；它还兼作一块路标，供阅读这项工作去向的协作者参考。

**迷雾还是工单？** 判据是你现在能否精确陈述这个问题——*而不是*你现在能否回答它。

- **开工单，当**问题已经锐利——即便它被阻塞、你还不能对它行动。
- **归为 Not yet specified，当**你还不能把它表述得那么锐利。别把迷雾预先切成工单大小的块：它比一个工单更粗，一块可能在前沿抵达它时毕业成若干工单，或者一个都不毕业。

**Not yet specified** 排除已经决定的（Decisions so far）、已经是一个活跃工单的，以及范围之外的（下一节）。

## 范围之外

迷雾只会*朝向*目的地聚集。目的地固定了范围，所以它之外的工作是**范围之外**——它不是迷雾，也不属于 **Not yet specified**。它在地图上有自己的 **Out of scope** 一节：你有意识地排除出*这项*工作的工作。是范围、而非锐利度，把它落到这里。

范围之外的工作从不毕业——前沿在目的地处停止——所以它只在目的地被重画时才返回，而且那时是作为一项新的工作，不是一次续接。

把某样东西判为范围之外是一个划定范围的动作，不是路线上的一步。当一个已经存在的工单结果坐落在目的地之外时——绘图时误纳入的，或被某次解决暴露的——**关闭它**（一个关闭的工单明确无疑地不在前沿上），并在 **Out of scope** 一节留一行：要点加上它为何在范围之外，链接那个关闭的工单。它不进 **Decisions so far**，后者记录的是实际走过的路线——一个范围边界不是它上面的一步。

## 调用

两种模式。无论哪种，**每个会话绝不解决超过一个工单**——研究工单例外。

### 绘制地图

用户带着一个松散的想法调用。

1. **给目的地命名。** 运行一次 `/grilling` 和 `/domain-modeling` 会话，钉下这张地图在找路通往什么——那份规格、决策或改动。目的地固定了范围，所以它最先定夺。
2. **勘测前沿。** 再拷问一次，这次**广度优先**：在整个空间里铺开，而不是在任何一条线上钻深，浮现出那些未决的决策和现在可迈出的第一步。**如果这浮现不出迷雾**——通往目的地的路径已经清晰，整段旅程小到一个会话就够——你不需要地图。停下并问用户他们想如何推进。
3. **创建地图**（标签 `wayfinder:map`）：填好 Destination 和 Notes，Decisions-so-far 留空，把迷雾勾进 **Not yet specified**。
4. **创建你现在能规范化的工单**，作为地图的子 issue——然后在**第二遍**里接上阻塞边（issue 得先有 id 才能互相引用）。接线把它们分拣进前沿和被阻塞的；你还不能规范化的一切留在迷雾里——**Not yet specified** 一节。
5. **发射研究子 agent。** 对你刚创建的每个 `research` 工单，起一个 `/research` 子 agent 并行解决它，把它的发现捕获在一个用完即弃的 `research/<name>` 分支上，并从工单留一个上下文指针。
6. 停——绘图是一个会话的工作；它不亲手解决任何东西。

### 逐个走过地图

用户带着一张地图（URL 或编号）调用。工单是**可选的**——没有工单时，由你、而非用户来挑下一个决策。

1. 加载**地图**——那个低分辨率视图，而不是每一个工单正文。
2. 选择工单。如果用户点名了一个，就用它。否则按顺序取第一个前沿工单。**领取它**：在任何工作之前把它分配给你自己。
3. 解决它——**按需缩放**：按需获取任何相关或已关闭工单的完整正文；调用 `## Notes` 块点名的那些技能。如有疑问，用 `/grilling` 和 `/domain-modeling`。
4. 记录解决：把答案作为一条**解决评论**发出，**关闭**该 issue，并向地图的 Decisions-so-far **追加一个上下文指针**。

From WenWuZhiDao/mattpocock-skills-zh, MIT.

More from WenWuZhiDao/mattpocock-skills-zh