# Wayfinder｜服务于人类注意力的动态意图佩特里网 > 状态：设计草案。 > > 本设计不是代码、工具调用或日志的可视化。它试图回答：当 coding agent 已经连续调用模型、工具、重试和修复很久时，它总体想完成什么、当前为什么做这一步、接下来准备走向哪里、哪些分支已经失败或仍然未知。 ## 一句话定义 一个把 coding-agent 的**意图、行动路径、条件、分支、证据和恢复循环**组织成分层有色佩特里网的注意力界面：越接近当前行动，描述越具体；越远离当前行动，结构越抽象。 ## 与 Trace 和 Arbor 的边界 ### Trace Trace 回答： > 真实发生了什么？ 它提供 session、turn、tool、error、compact、Git、CI 等事实事件。Trace 可以成为 Wayfinder 的遥测底座，但仅凭这些事件不能可靠解释总体意图。 ### Arbor Arbor 回答： > 人的想法如何被拆分、管理和推进？ 它不连接 coding agent。 ### Wayfinder Wayfinder 回答： > Agent 为什么沿着这条路径行动？人现在需要注意什么？ 它连接 Agent 的自我声明与外部观察，但不展示隐藏 reasoning，也不把工具日志本身当作主界面。 ## 核心问题 Coding agent 长时间运行时，用户通常看到： - 多次模型调用； - 连续工具调用； - 文件读取、修改、测试； - 报错、重试、绕路； - 新的假设和临时修复； - 最终一句“完成”。 用户看见了活动，却看不见行动结构： - 当前动作服务于哪个目标？ - 为什么此时要做它？ - 它成功后会打开哪条路径？ - 它失败后准备走哪个恢复分支？ - 哪些原计划已经作废？ - 哪些只是远期方向，不需要现在理解？ - Agent 的声明和真实行为是否已经偏离？ ## 产品原则 1. **意图优先于工具**：主图显示目标、条件、选择、证据和行动，不显示文件依赖图。 2. **近处清晰，远处模糊**：当前与下一步必须具体；远期只保留方向、约束和关键假设。 3. **声明与观察分离**：Agent 说自己要做什么，与系统观察到它做了什么，是两种不同证据。 4. **允许分歧存在**：声明和行为冲突时显示张力，不用一个覆盖另一个。 5. **不展示隐藏思维链**：只记录 operational intent、预期结果、条件和路径变化。 6. **图是注意力工具，不是完整世界模型**：默认只展示用户此刻需要理解的局部。 7. **结构变化可追溯、可纠正、可回放**。 ## 为什么选择佩特里网 普通任务树很难表达： - 多个并行 Agent； - 一个动作需要多个前置条件； - 测试失败后回到诊断； - 多条分支最终汇合； - 权限、证据或人工判断形成 gate； - 同一个错误循环多次发生； - “Agent 报告完成”与“外部验证通过”是不同状态。 佩特里网提供： - **Place**：条件、目标状态、未知、证据状态； - **Transition**：有意图的行动或决策； - **Execution Token**：Agent 或 subagent 当前执行流所在； - **Split / Join**：并行工作与汇合； - **Loop**：失败、恢复和再次验证； - **Hierarchical transition**：远处是一个抽象动作，靠近时展开为子网。 界面不要求用户学习完整佩特里网理论。形式模型负责保持路径一致，视觉语言使用“条件、行动、分支、证据、阻塞”等自然术语。 ## 两层模型：执行网与注意力视图 Wayfinder 必须区分形式执行模型和 UI 状态，避免把用户关注位置混进工作流语义。 ### Workflow Net Core 这是可回放、可验证的分层有色佩特里网： - Place 只表示条件或状态； - Transition 只表示改变条件的行动或决策； - Execution Token 表示某个 Agent 执行流； - Arc 表示前置条件、产出条件和失败去向； - Hierarchical Transition 可被一个子网 refinement 替换； - Evidence 附着在 Place、Transition 或 firing event 上。 “有色”主要表示 Execution Token 携带 `agentId / threadId / owner / branch` 等类型信息，不表示所有视觉元素都是形式 token。 ### Attention View Overlay 这是从 Workflow Net 派生的用户界面状态： - 当前用户关注的节点； - `NOW / WHY / NEXT / WATCH`； - pin、折叠、缩放和视觉显著性； - 声明/观察冲突； - 需要人工判断的提醒。 Attention、Uncertainty 和 Blocked 不再同时作为多种 Token。关键未知由 Place 属性或 Information Need Place 表示；阻塞由 Gate Place 表示；用户注意力由独立 view state 表示。 ## 领域模型 ### Place Place 表示某个可成立或尚未成立的条件。 | 类型 | 示例 | |---|---| | Goal | 登录刷新问题被可靠修复 | | Condition | 能稳定复现失效场景 | | Information Need | 尚不知道 token 在哪一层丢失 | | Decision Outcome | 已选择 session 层而非 UI 层 | | Gate | 缺少数据库权限，执行流无法通过 | | Verified | 回归测试与原测试全部通过 | | Outcome | 变更已审查并可交付 | Place 不等于文件、函数或命令。文件和工具只能作为 Place/Transition 的证据细节。 ### Transition Transition 表示会改变工作状态的有意图行动。 | 类型 | 示例 | |---|---| | Investigate | 定位 refresh token 丢失位置 | | Decide | 选择服务端修复方案 | | Implement | 修改 session refresh 逻辑 | | Verify | 运行回归测试并检查副作用 | | Recover | 根据失败堆栈收窄假设 | | Ask Human | 请求产品语义或权限判断 | | Branch | 并行验证两个可能原因 | | Conclude | 接受或否定一个假设 | 在 Declared Path 可用时，每个 Near Transition 必须声明： - 为什么现在执行； - 需要哪些前置条件； - 具体要做什么； - 预期看到什么证据； - 什么条件下算完成； - 失败后进入哪个分支或停止。 在 observed-only 降级模式中，字段允许为 `unknown` 或 `inferred`，界面必须显示来源，不能假装达到与 Agent 主动声明相同的精度。 ### Execution Token 每个 Agent 或 subagent execution flow 对应一个带颜色属性的 Execution Token： ```text tokenId agentId threadId owner branch currentPlaceId status: active | waiting | blocked | complete ``` 多个 Execution Token 表达并行 Agent；Join Transition 表达它们需要汇合后才能继续。Block 是 token 的状态和 Gate Place 的组合，而不是另一种独立 token。 ## 动态详细程度：Action Horizon Horizon 是 Attention View 对 Workflow Net 的分层投影，不改变底层网结构。 ### Near｜行动前沿 确定性范围： - 当前 active Transition； - 已 enable 且距离 active token 不超过 2 个 Transition 的后继； - 与当前 Transition 直接相连的主要失败分支； - 用户显式 pin 的节点。 通常为 1–3 个行动单元。Declared Path 模式要求明确： ```text Why now Concrete action Expected evidence Exit condition Failure branch Owner ``` 示例： ```text 现在：复现刷新失败 原因：没有稳定复现就无法判断修复是否有效 行动：运行 auth integration test 并保存失败签名 成功证据：失败稳定发生在 refresh-token assertion 退出条件：获得稳定签名或证明测试本身不可靠 失败分支：先修复测试夹具 ``` 如果 Near Transition 仍是抽象节点，Agent 必须在 firing 前提交 refinement；Agent 没有更新时，Observer 只能建立虚线 provisional refinement，并把缺失字段显示为 Unknown。 ### Mid｜阶段路径 确定性范围：距离 active token 3–6 个 Transition，或当前 hierarchical stage 的其余主要步骤。 只需要明确： - 阶段目标； - 进入条件； - 退出 gate； - 主要未知； - 可能并行的工作流。 示例： ```text 定位根因 → 选择修复层 → 实现 → 验证 → 审查 ``` 不提前展开具体文件和命令。 ### Far｜结果地平线 范围：超出 Mid 的高阶结果、尚未 enable 的替代方向和长期目标。 只保留： - 目的； - 关键约束； - 重要假设； - 何时需要进一步细化。 示例： ```text 可交付的认证修复 约束：不得改变现有登录协议 假设：问题局限于刷新路径 细化时机：根因被确认后 ``` ### Refinement 生命周期 1. Far Transition 允许只有目标、约束和 refinement trigger； 2. 前驱 token 到达其入口 Place 后，节点进入 Mid； 3. 节点被 enable 或成为下一候选行动后，进入 Near； 4. Near 节点在 firing 前必须有 operational fields，缺失则明确显示 Unknown； 5. refinement 优先来自 Agent Path Patch，其次是 Human Patch，Observer 只能提出 provisional subnet； 6. Transition 完成并远离 Attention View 后，其子网折叠为 causal spine，但底层事件与证据不删除； 7. Phase 2 才自动把重复错误聚合为 recovery loop；MVP 仅在 Evidence Drawer 中累计相同错误次数。 ## 主界面 ```text ┌ WAYFINDER · INTENT NET ────────────────────────────────────────────────────┐ │ North Star: 可靠修复登录刷新，并给出可验证证据 │ │ │ │ FAR MID NEAR │ │ │ │ [可交付认证修复] [定位根因] → [选择修复层] ○ 已稳定复现 │ │ ··· │ │ │ │ [降低未来刷新风险] └───────────────→ ▮ 收窄根因 │ │ ▲ execution token │ │ │ │ │ ┌───────────────┴──────────────┐ │ │ ○ 原因已确认 ○ 假设失效 │ │ │ │ │ │ ▮ 实现修复 ▮ 恢复/改道 │ │ │ ├────────────────────────────────────────────────────────────────────────────┤ │ NOW 收窄 refresh token 丢失位置 │ │ WHY 当前失败签名排除了 UI 层 │ │ NEXT 若服务端假设成立，修改 session 层；否则检查测试夹具 │ │ WATCH 已连续 3 次出现同一错误签名 │ └────────────────────────────────────────────────────────────────────────────┘ ``` ### 默认不显示 - 每次 read/edit/bash； - 完整 stdout； - 文件依赖； - token-by-token 文本流； - 每个临时假设； - 没有改变路径的重复动作。 点击 Transition 后，才在 Evidence Drawer 中查看对应 tool episode、文件、测试和错误摘要。 ## 两条信息通道 纯后处理与纯 Agent 自报各有根本缺陷，因此推荐混合方案。 ### 通道 A：Observed Execution｜外部观察 从 Pi/Codex session、tool、error、Git 和测试事件获取事实。 职责： - 证明哪些动作真的发生； - 发现重复工具和错误循环； - 识别外部 gate； - 给 Agent 的路径声明提供校验； - 在 Agent 没有主动更新时进行补全或提出修正建议。 局限： - 能看见“做了什么”，不一定知道“为什么”； - 日志可能缺失； - 从行为反推意图存在歧义； - 逐条把原始日志发送给 LLM 成本高且有隐私风险。 ### 通道 B：Declared Path｜Agent 主动声明 Agent 在行动边界主动提交结构化路径更新。 职责： - 说明当前 operational intent； - 指明当前 Transition； - 说明预期证据和退出条件； - 声明路径变更、分支、放弃与恢复策略； - 让近端路径在行动前就清晰，而不是事后猜测。 局限： - Agent 可能遗漏更新； - 自报可能与真实行为偏离； - 频繁更新会增加 token、延迟和认知负担； - 侵入工作循环，需要新的 Agent 范式。 ## 推荐架构：双通道调和 ```text Human corrections │ ▼ ┌─────────────────┐ ┌──────────────────────┐ │ Agent Path Head │─────▶│ │ │ declared intent │ │ │ └─────────────────┘ │ │ │ Intent Reconciler │──▶ Versioned Petri Net ┌─────────────────┐ │ │ │ Session Adapter │─────▶│ │ │ tool/error/log │ │ │ └────────┬────────┘ └──────────┬───────────┘ │ │ ▼ ▼ Episode Segmenter Drift / conflict detection │ │ ▼ ▼ Semantic Observer LLM Attention View Reducer │ ▼ Pi / Herdr / Web / macOS Pet ``` ### 来源优先级 当来源冲突时： 1. 人类明确的目标、约束和纠正； 2. 外部系统对事实的验证； 3. Agent 对自身意图的声明； 4. Observer LLM 的行为推断。 冲突不直接覆盖，而产生 Tension： ```text Declared: 正在实现修复 Observed: 最近 12 个动作仍在诊断，同一错误重复 3 次 Status: path may be stale ``` ### 观察事件进入主图的准入规则 Tool、文件和日志事件默认只进入 Evidence Drawer。只有满足以下至少一项，Observed Execution 才能改变主图或 Attention View： - 证明或否定一个 Place condition； - 打开、关闭或阻塞一个 Gate； - 提供 active Transition 声明的 expected evidence； - 改变关键 uncertainty； - 支持或反驳路径完成声明； - 足以证明 declared path 已 stale 或 diverged。 仅仅切换文件、增加 tool count、重复读取或输出更多日志，不得生成主图节点。 ### 确定性调和算法 每个 Agent 在任一时刻最多有一个 `activeTransitionId`。Path Patch 生效后，Session Adapter 给后续 episode 标注： ```text activeTransitionId pathRevision agentId turnId telemetryCoverage ``` Episode 与 Transition 的关联顺序： 1. episode 带显式 `transitionId` 时直接关联； 2. 否则关联到事件发生时该 Agent 的 active Transition； 3. Observer LLM 可以提出 alternate association，但只能形成 proposal 或 Tension，不能静默搬移既有证据； 4. 人类纠正可重新关联，原关联保留 provenance。 每个 Near Transition 声明 `allowedEpisodeKinds` 和 `evidenceSelectors`。确定性 reducer 只消费 GraphPatch、Episode、Evidence、Observer annotations 和 Human Patch，输出： ```text pending aligned lagging diverged unknown ``` 完整术语、评估窗口和固定求值顺序见“调和与漂移检测”。LLM 不能直接设置 Alignment 状态。`lagging` 只表示路径可能过期，不表示 Agent 错误；`diverged` 也不会自动重写路径，只打开 Tension 并请求重新锚定。 ### 并发与冲突 所有结构 patch 使用 optimistic revision： - patch 必须携带 `baseRevision`； - 纯 `attach_evidence` 操作可在目标仍存在时自动 rebase； - patch 含任何 create/connect/activate/complete/fail/retire/refine 等结构操作且 base revision 已过期时，整份 patch 拒绝；proposal 是调用方收到冲突后另行提交的独立对象； - 相同 `idempotencyKey` 只应用一次； - 每个 session 的事件存储分配严格递增 `sessionSeq`，作为 replay 顺序。 ## Agent Path Protocol ### 当前可行实现：本地结构化工具 不需要先修改模型 API。Pi extension 注册一个本地工具： ```text update_action_path ``` Agent 在关键边界调用它。该工具不执行代码，只写入路径事件。 工具提交一个原子、带 revision 的 `GraphPatch`，而不是假设 Transition 已存在的松散状态对象： ```json { "schemaVersion": 1, "patchId": "patch_01J...", "baseRevision": 17, "idempotencyKey": "turn_42_strategy_root_cause", "actor": { "type": "agent", "agentId": "main" }, "ops": [ { "op": "create_place", "placeId": "pl_root_cause_known", "type": "Condition", "label": "refresh token 丢失边界已确认" }, { "op": "create_transition", "transitionId": "tr_find_root_cause", "type": "Investigate", "intent": "收窄 refresh token 丢失位置", "whyNow": "稳定失败签名已经排除 UI 层", "expectedEvidence": [ "确认 token 在 session middleware 前后是否存在" ], "evidenceSelectors": [ "assertion:refresh-token", "trace:session-middleware" ], "allowedEpisodeKinds": ["inspect", "test", "instrument"], "exitCondition": "根因被定位到一个明确边界", "failureCondition": "证据相互矛盾或测试夹具不稳定" }, { "op": "connect", "fromId": "pl_failure_reproduced", "toId": "tr_find_root_cause", "arc": "flow" }, { "op": "connect", "fromId": "tr_find_root_cause", "toId": "pl_root_cause_known", "arc": "success" }, { "op": "activate_transition", "transitionId": "tr_find_root_cause", "tokenId": "tok_main" } ] } ``` MVP 支持的结构操作： ```text create_place create_transition connect set_place_state set_transition_contract activate_transition complete_transition fail_transition retire_transition supersede_transition refine_transition attach_evidence mark_gate ``` Phase 1 操作契约： | Op | 必填字段 | 核心效果 | |---|---|---| | `create_place` | `placeId, type, label` | 创建未连接 Place；Gate 另需初始 `gateState` | | `create_transition` | `transitionId, type, intent` | 创建 Transition；Near 节点另需 operational contract | | `connect` | `fromId, toId, arc` | 创建合法二部 arc：`flow/read/success/failure` | | `set_place_state` | `placeId, state, evidenceIds` | 设置普通 Place 的 `unknown/satisfied/invalidated`；Gate 改用 `mark_gate` | | `set_transition_contract` | `transitionId` + 至少一个 contract 字段 | 版本化更新 why/evidence/exit/failure/allowed kinds | | `activate_transition` | `transitionId, tokenId` | 校验 enable 后 reservation 输入 token | | `complete_transition` | `transitionId, tokenId, evidenceIds` | 成功 firing，将 token 移至 success Place | | `fail_transition` | `transitionId, tokenId, evidenceIds` | 失败 firing，将 token 移至 failure Place 或返回输入 Place | | `retire_transition` | `transitionId, reason` | 停用未激活 Transition | | `supersede_transition` | `oldTransitionId, newTransitionId, reason` | 保留旧路径 provenance，以新路径替代 | | `refine_transition` | `transitionId, subnet, entryMap, successExitMap` | 给 hierarchical shell 增加可验证子网 | | `attach_evidence` | `targetId, evidence` | 附着 typed、redacted、provenance-aware Evidence | | `mark_gate` | `placeId, gateState, evidenceIds` | 设置 Gate Place 为 `open/closed/blocked` | ### Place state、Marking 与 Transition firing Execution Token 的正式 marking 只存在于 Place。普通 Place 另有条件状态： ```text unknown | satisfied | invalidated ``` 它不是 token。`set_place_state` 必须携带 Evidence；Gate Place 单独使用 `open | closed | blocked`。 Phase 1 限制每个 Transition： - 恰好一个 `flow` 输入 Place； - 任意数量 `read` 输入 Place； - 恰好一个 `success` 输出 Place； - 最多一个 `failure` 输出 Place； - 不允许 token split、join 或多输出复制。 长时间 Transition 执行采用 reservation： 1. `activate_transition` 要求 flow 输入 Place 持有该 Execution Token；所有普通 read Place 为 `satisfied`，所有 Gate read Place 为 `open`； 2. 激活后对 flow token 建立 reservation。形式 marking 仍记录在输入 Place，但 token 不能被其他 Transition 使用；UI 可把它绘制在 Transition 上； 3. `complete_transition` 在一个事务中移除输入 marking/reservation，并把同一 token 放入唯一 success Place； 4. `fail_transition` 把 token 放入唯一 failure Place；若没有 failure arc，则释放 reservation、返回原 flow 输入 Place，并把 Transition 标为 failed； 5. `retire_transition` 只能作用于未激活节点；活跃节点必须先 complete、fail 或由 Human Patch 强制 supersede； 6. Phase 2 才允许 token split/join 和多前置 flow token。 ### Arc 与操作不变量 - 图必须保持二部结构：Place 只能连 Transition，Transition 只能连 Place； - `Place → Transition` 允许 `flow` 或 `read`；`flow` reservation 后消费 token，`read` 只检查 Place/Gate state，不消费 token； - `Transition → Place` 允许 `success` 或 `failure`； - `mark_gate` 只作用于 Gate Place；`set_place_state` 不得作用于 Gate； - 所有引用节点必须在当前 revision 或同一 patch 的前序 op 中存在； - `activate_transition` 要求所有 input arc 满足、token 未被 reservation、Transition 未 retired； - `complete_transition` 和 `fail_transition` 必须对应当前 reservation； - `set_transition_contract` 不能删除已被 Evidence 引用的 expected-evidence key，只能 supersede； - Phase 1 每个 Agent 最多一个 active Transition。 ### Hierarchical refinement firing Phase 1 允许一层 refinement，但仍遵循单 token 限制： 1. `entryMap` 把父 Transition 的唯一 flow 输入映射到子网唯一 entry Place； 2. 父 Transition 激活时，token 从父输入 Place 移入子网 entry Place，父 shell 状态变为 `active`；父 shell 本身不持有第二个 token； 3. token 在子网中按普通 firing 规则移动；父 shell 的 active 状态由“token 是否仍在该 subnet”派生； 4. token 到达 `successExitMap` 指定的唯一子网 exit Place 后，原子移入父 Transition 的唯一 success 输出，父 shell 标记 completed； 5. token 到达可选 `failureExitMap` 后，原子移入父 failure 输出；若无父 failure 输出，则返回父输入 Place，父 shell 标记 failed； 6. replay 把整个 refinement 作为父 shell 的子作用域展示，不能同时把父 shell 当作另一次 firing。 `refine_transition` 必须提供单一 `entryMap`、单一 `successExitMap` 和可选单一 `failureExitMap`；子网自身必须满足 Phase 1 的二部结构和单 token 不变量。 ### Patch 原子性与返回值 稳定 ID 由调用方提出，extension 在 patch 内先生成完整 `idMap`，随后统一验证，因此后续 op 可以引用同一 patch 中刚创建的 client ID。 一个 patch： - 只推进一次 `graphRevision`； - 在单个 SQLite transaction 内写入多个带 `opIndex` 的事件和最终 `patch.committed`； - replay 只在看到 committed batch 后应用整批，不暴露中间无效状态； - 要么全部应用，要么全部拒绝。 成功返回： ```json { "status": "applied", "revision": 18, "idMap": { "tr_find_root_cause": "tr_find_root_cause" }, "eventIds": ["evt_..."], "snapshotHash": "sha256:..." } ``` 冲突返回当前 revision、冲突节点和可安全 rebase 的 op；结构 op 不自动重排。包含结构 op 的 stale mixed patch 整体拒绝，不写 graph event、不推进 `graphRevision`。调用方若希望保留为 proposal，必须使用独立 `submit_patch_proposal` 接口；proposal 存储不属于 Workflow Net marking，也不会出现在 net replay，直到它被重新基于当前 revision 接受。 ### 何时更新 Agent 不应每次 tool call 都更新。只在以下边界更新： 1. 开始一个新的意图阶段； 2. 当前 Transition 改变； 3. 新证据改变原路径； 4. 同一策略连续失败两次以上； 5. 分裂或汇合 subagent； 6. 需要用户判断或权限； 7. 声称完成前。 ### 不允许写入 - 隐藏思维链； - 逐 token reasoning； - 未经过滤的 prompt； - 密钥和环境变量； - 仅为了显得忙碌而生成的细碎步骤。 Path Protocol 记录的是可操作导航信息，不是模型的内心独白。 ## 多头输出方向 理想的 coding-agent 输出不是单一文本流，而是至少三条逻辑通道： ```text User Head → 面向用户的回答 Action Head → tool calls / execution Path Head → intent net delta ``` ### 为什么值得研究 当前用工具调用模拟 Path Head，会带来： - 额外工具回合； - 模型可能漏调； - 路径更新与真正行动不是原子提交； - UI 需要等待工具调用完成后才看到路径。 原生 Path Head 可以让模型在决定行动时，同时流出严格 schema 的路径 delta。 ### 为什么不作为第一版前提 现有主流端点并不保证这种独立、持续、可靠的第三输出通道。第一版应使用 `update_action_path` 工具验证工作范式；只有确认它显著提升用户定向能力，并且工具模拟的遗漏或延迟成为主要瓶颈后，才值得推动 provider 或 agent-loop 级多头协议。 ## Session 后处理 ### 不逐条把原始 log 直接发送给 LLM 先使用确定性本地 Episode Segmenter，把低层事件聚合为有意义的活动片段： ```text Episode: diagnose refresh failure Duration: 2m18s Tools: read ×4, grep ×2, bash ×3 Files touched: 3 Errors: same assertion signature ×2 Outcome: hypothesis narrowed, not verified ``` ### 触发语义判别的边界 - 一个 turn 结束； - Agent 提交 Path Update； - 新错误签名出现； - 相同错误重复达到阈值； - subagent split/join； - 外部验证 gate 改变； - 路径超过时间或事件阈值仍未更新； - session settle。 ### Observer LLM 的权限 Observer LLM 不能任意重写整张网，只能输出版本化 `ObserverPatch`： ```text no_change attach_evidence annotate_episode propose_place propose_transition propose_refinement ``` `annotate_episode` 只能给 episode 增加 `intentClass / alternateTransitionId / supportsSelector / contradictsSelector / confidence / modelVersion`。`lagging`、`diverged` 等 Alignment 状态由确定性 reducer 计算，不允许 LLM 直接写入。 Phase 1 只启用： ```text no_change attach_evidence annotate_episode ``` Phase 2 才开放 place、transition 和 refinement proposal。改变目标、删除路径、合并主要分支等结构操作必须由 Agent 明确声明或用户确认。 ### 信心阈值 | Confidence | 行为 | |---|---| | ≥ 0.85 | 自动附着证据或更新非结构标签 | | 0.60–0.85 | 以虚线 proposal 显示，等待确认 | | < 0.60 | 不修改结构，只记录 Unknown | ## 调和与漂移检测 每个 active Transition 都维护： ```text declared contract allowedEpisodeKinds expectedEvidence selectors completed episodes since last path update confirming evidence since last path update observer annotations with modelVersion telemetry coverage alignment status ``` ### 术语定义 - **matching activity**：episode 显式带当前 `transitionId`，且 `episode.kind` 位于 `allowedEpisodeKinds`； - **confirming evidence**：Evidence 命中至少一个 `evidenceSelector`，或由 Human/Agent 明确标注满足某个 expected-evidence key； - **explainable progress**：出现新的 matching activity、confirming evidence 或有效 Path Patch；相同 hash 的重复工具/错误不算新进展； - **telemetry coverage**：`full` 表示评估窗口内 session/turn/tool 边界完整；`partial` 表示存在不支持的工具或事件缺口；`unknown` 表示缺少窗口起止或 session 身份。 Observer 的 intent classification 是带 `modelVersion` 的输入事实，不是 reducer 内部的非确定性步骤。同一组 GraphPatch、Episode、Evidence 和 Observer annotations 必须 fold 出相同状态。 ### 评估窗口 窗口从“最近一次 Path Patch 或 confirming evidence”中较晚者开始，最多取最近 3 个 completed episode。每个 episode 结束后按固定顺序求值： 1. Human Patch 明确否定当前 Transition → `diverged`； 2. coverage 为 `unknown`，且没有直接 observed confirming evidence → `unknown`； 3. 连续 2 个 completed episode 被同一 Observer model version 以 ≥0.85 信心标为同一 alternate intent，Agent 未更新路径 → `diverged`； 4. 窗口中存在 matching activity 或 confirming evidence → `aligned`； 5. 累计 3 个 completed episode 仍无 explainable progress → `lagging`； 6. 其余新激活、尚无足够事件的情况 → `pending`。 完整状态集： ```text pending aligned lagging diverged unknown ``` Observer 不可用时，第 3 条不会触发；系统仍可根据 Human Patch、telemetry coverage、expected evidence 和 episode 数量得到 `aligned / lagging / unknown`。 典型漂移包括： - 声明正在实现，但持续发生与 contract 不匹配的诊断 episode； - 声明已完成，但验证 Gate 没有通过； - 连续失败后仍未声明恢复路径； - Phase 2 中 subagent 已结束，但 join condition 没有更新。 Wayfinder 不自动指责 Agent，而显示： ```text Path may be stale Observed work no longer supports the active transition ``` 必要时要求 Agent 在下一个安全边界重新锚定路径。 ## 人类纠正 用户必须能在数秒内修正系统，而不是编辑复杂图： - “总体目标不是修复测试，而是恢复登录行为”； - “这个分支已经不重要”； - “先不要优化，只验证根因”； - “把这里设为需要我判断”； - “当前 Transition 描述不对”。 纠正形成 `HumanIntentPatch`，优先级最高，并在下一次 Agent turn 作为结构化约束注入。历史节点不删除，而标记 superseded，保留 Agent 为什么改道的 provenance。 ## 存储模型 使用 append-only graph event： ```text session.started root_intent.set place.proposed place.confirmed transition.proposed transition.activated transition.fired transition.failed transition.superseded token.moved token.split token.joined evidence.attached path.declared path.diverged human.corrected view.focused ``` 每条领域事件使用统一信封： ```json { "schemaVersion": 1, "eventId": "evt_01J...", "sessionSeq": 184, "ts": "2026-07-14T15:08:11.210Z", "sessionId": "ses_...", "actor": { "type": "agent", "id": "main" }, "source": "declared-path", "kind": "transition.activated", "causationId": "patch_01J...", "correlationId": "turn_42", "graphRevisionBefore": 17, "graphRevisionAfter": 18, "payload": {}, "provenance": { "level": "declared", "confidence": 1, "redacted": true, "rawRefHash": "sha256:..." } } ``` `sessionSeq` 是单 session 的唯一 replay 顺序；`ts` 只用于展示和跨来源近似关联，不能替代顺序号。 Evidence 使用明确类型： ```text agent_declaration tool_episode test_result error_signature git_fact external_gate human_statement observer_inference ``` 每项 Evidence 必须保存 `summary / observedAt / source / confidenceOwner / redactionStatus / rawRefHash`。`confidenceOwner` 说明置信度是谁给出的，避免把 Observer 的 0.9 与外部测试事实混为一谈。 当前佩特里网、Attention View 和 replay 都由事件 fold 得到。 推荐 MVP 使用 SQLite： ```text sessions net_events places transitions tokens episodes evidence patch_proposals human_corrections ``` 原始 session log 不直接成为领域数据库；只保存引用、哈希和经过脱敏的 episode 摘要。 ## 注意力视图算法 主界面不是把整张网塞进屏幕，而是计算一个 `Attention View`。 优先级依据： 1. 与 active Execution token 的图距离； 2. 是否需要人类判断； 3. 是否阻塞多条下游路径； 4. 是否存在声明/观察分歧； 5. 不确定性是否足以改变整体方向； 6. 最近是否发生结构性事件； 7. 用户是否 pin。 默认只突出： ```text NOW 当前 Transition NEXT 最可能的 1–3 条路径 WATCH 高风险未知或恢复循环 WHY 当前动作与 North Star 的关系 ``` 工具数量、token、耗时和日志只作为次级证据，不竞争主注意力。 ## 佩特里网中的错误与恢复 错误不应把主图淹没。MVP 只在 active Transition 的 Evidence Drawer 中累计错误签名和次数；Phase 2 才把确认存在策略循环的错误提升为 recovery subnet。 Phase 2 中，相同签名且确实触发“尝试—验证—恢复”策略的错误折叠为 recovery loop： ```text ○ hypothesis active │ ▼ ▮ attempt fix ───▶ ○ verification ▲ │ fail ×3 └──── ▮ recover ◀─┘ ``` Loop 显示： - 次数； - 最近错误签名； - 每次是否真正改变策略； - 何时应停止当前恢复策略； - 是否需要用户介入。 如果只是重复同一动作而没有新证据，Attention View 将其标为“低信息循环”。 ## Pet 的新角色 macOS Pet 不再只是“工具正在运行”的动画。它可以成为当前 Execution Token 的具象化，同时响应独立的 Attention View： - 在 Transition 间移动，表示路径真的变化； - 在 gate 前等待，表示缺少条件； - 分裂为小 token，表示 subagent 并行； - 回到旧 Place，表示恢复循环； - 当 Attention View 出现人工判断项时抬头提醒用户； - 点击 Pet 打开 `NOW / WHY / NEXT / WATCH`，而不是工具日志。 动画仍必须由真实路径事件驱动。 ## 可行实施路线 ### Phase 1：Single-Agent Intent Corridor 这是最小、独立可用的 vertical slice： - 只支持一个 Pi 主 Agent，不支持 subagent； - `update_action_path` 原子 GraphPatch； - 单 Execution Token； - 一层 hierarchical Transition refinement； - Pi session adapter 和本地 episode segmentation； - observed episode 确定性附着到 active Transition； - Observer LLM 只允许 `no_change / attach_evidence / annotate_episode`，不能自动创建或改写主路径； - 基础 `pending / aligned / lagging / diverged / unknown` 调和； - 一个本地 Web/SVG 主视图，显示 Petri corridor 与 `NOW / WHY / NEXT / WATCH`； - 简单 HumanIntentPatch； - append-only SQLite replay。 第一版不接 Git、CI、Registry、部署系统、Herdr 聚合或 macOS Pet。重复错误只作为当前 Transition 的 evidence counter，不生成 recovery loop。 即使 Observer LLM 不可用，Declared Path + deterministic evidence attachment 仍然可用；如果 Agent 漏报，视图明确降级为 stale/unknown。 ### Phase 2：并行、恢复与语义观察 独立增强： - 多 Execution Token； - subagent split/join； - error signature clustering； - recovery loop； - Observer LLM 的 provisional place/transition/refinement proposal； - 更完整的 path drift； - 外部测试和 Git evidence； - proposal review 与局部 graph merge。 ### Phase 3：环境呈现 独立增强： - Pi 内 near-horizon widget； - Herdr 观察 pane； - macOS Pet； - blocked/diverged/done 通知； - 跨 session Attention Queue。 ### Future：原生 Path Head 不是已承诺实施阶段。只有在 `update_action_path` 工作范式被真实使用证明有效，并确认工具调用的额外回合、遗漏和非原子性是主要瓶颈后，才设计 provider/agent-loop 级多头输出协议。 ## MVP 验收 选择一次至少包含 20 次 tool call 和 3 次重复失败的单 Agent 真实 session。Agent 至少主动声明一次路径变更。用户重新打开 Wayfinder 后，应在 10 秒内正确回答： 1. 总体目标是什么？ 2. 当前 Agent 正在推进哪个意图？ 3. 为什么现在做这一步？ 4. 成功需要什么证据？ 5. 下一步最可能是什么？ 6. 哪个失败分支最值得关注？ 7. 哪些原路径已经作废？ 8. Agent 的声明与真实行为是否一致？ 额外验收： - Declared Path 模式下，Near horizon 的每个 active Transition 都有 expected evidence 和 exit condition；observed-only 时缺失字段明确显示 Unknown； - Far horizon 不被迫生成虚假细节； - 20 次工具调用不会自动生成 20 个主图节点； - 3 次重复错误在 Evidence Drawer 中聚合计数，不污染主图； - 人工纠正会在下一个 Agent turn 生效； - Observer LLM 不可覆盖 human commitment； - 外部 LLM 不可用时，Agent declared path 仍可继续； - Agent 漏报时，Observed channel 能标记 stale/unknown； - 默认数据不包含 reasoning、secret 或未脱敏源码。 ## 风险与防御 ### Agent 为满足协议而产生仪式化路径更新 防御：只在策略边界更新；限制更新频率；检测内容没有变化的空更新；Path Update 不计为完成证据。 ### Observer LLM 过度解释日志 防御：episode segmentation、局部 NetPatch、来源等级、置信阈值、结构修改需确认。 ### 图越来越大 防御：hierarchical transition、Action Horizon、causal spine、稳定位置、默认局部视图、自动折叠无信息循环。 ### 侵入式工具影响 Agent 性能 防御：本地零副作用工具；每个策略阶段最多一次；允许关闭 Declared Path，退化为后处理观察。 ### 外部 LLM 成本和隐私 防御：不逐 log 请求；只发送脱敏 episode + 当前局部网；异步批处理；支持本地模型；结果缓存；失败开放。 ### 形式模型限制真实工作 防御：佩特里网是可修正的导航模型，不是执行引擎。Unknown、proposal、superseded 和 Tension 都是一等状态，不强迫所有工作立即落入确定结构。 ## 最脆弱的假设 本设计假设 Agent 能够在不暴露隐藏 reasoning 的前提下，稳定地产生有用的 operational intent、expected evidence 和 exit condition。 如果 Agent 的路径声明长期流于形式，Declared Path 将失去价值。系统必须允许完全关闭自报通道，并依靠 post-processing + human correction 工作；同时把 `declaration coverage` 和 `declaration usefulness` 作为可测指标，而不是默认相信 Agent 自报。 ## 推荐结论 采用**双通道、分层有色佩特里网**： - Agent 在行动边界声明路径； - 外部观察器用 session episode 验证和补全； - Reconciler 保留分歧和来源； - Action Horizon 让近处具体、远处抽象； - 主界面只回答 `NOW / WHY / NEXT / WATCH`； - 工具日志退居证据层； - 原生多头 Path Head 作为被实践验证后的未来协议，而不是 MVP 前提。