> 中文 — trampelpfadanalyse 官方中文版本。

欲望路径分析 (Desire-Path Analysis) — 让约定对 LLM 具备实证可见性

一种用于揭示 Pipeline 和控制文件工作流中并非源自代码 Bug、而是源于约定对 LLM 不可见的错误的分析方法。无需猜测 README 或规则是否“足够清晰”，而是通过实证方式进行测量：让毫无先验知识的朴素（naive）子 Agent 在工作流中运行，其行为构成基线（Baseline）；针对性的文档修改（“路标” / signpost）作为干预措施（Intervention）；全新的朴素子 Agent 进行重测（Retest）。与 Baseline 的 Diff 即为成功测量指标。

该名称源自欲望路径（德语：Trampelpfad，即人们因日常踩踏而自然形成的羊肠小道）：人们实际行走的地方才是应该铺设道路的地方。同理，朴素 LLM 的行走路径展示了究竟在哪里才真正需要文档/防护栏（Guardrails），而非我们主观假设的位置。

何时使用此 Skill

• 尽管已有文档说明，Agent 仍反复忽略某条规则/约定。
• 希望在撰写更多文档前了解某项流程对 LLM 是否可见/易发现（“这里有人是在对着墙说话吗？”）。
• 在重构之后（如新建目录、重命名文件）：Agent 是否仍能找到入口点？
• 进行了文档修改，并希望证明其有效——而非仅凭希望。
• 在将新 LLM Partner 集成到 Pipeline 之前的入职测试（Onboarding test）。

不适用于：纯代码 Bug（→ 参考 bugfix-protocol / 系统化调试），或为生产任务选择 Swarm 协调模式（→ 参考 swarm-operations）。本 Skill 仅将朴素 Agent 组成的 Swarm 用作测量工具。

一句话核心思想

将文档视为 UX：重要的不是你写了什么，而是无偏见的用户（此处指朴素 Agent）实际上用它做了什么——你需要对此进行测量、修改并再次测量。

流程：5 个步骤

1. BASELINE       naive subagents → measure current behavior (quantitative)
2. PATH ANALYSIS  where exactly does it fail? which doc location misleads?
3. INTERVENTION   put up a "signpost" (README/convention made more prominent)
4. RETEST         FRESH naive subagents, identical test case
5. DIFF           retest vs. baseline → success measurement + honest assessment

步骤 1 — Baseline：以朴素方式测量当前行为

首先将问题表述为一个可测试的问题，例如：“Agent 是否在约定指定的路径下创建了日志？”或“Agent 是否找到了 Pipeline 的入口点？”。

然后让朴素子 Agent 运行：

• 朴素（Naive）意味着： 无项目记忆、无 Skill、无先验提示——Agent 仅知道入口路径和任务。这测量的是基于现有文档的纯粹可发现性，而非 Agent 的先验知识。
• 隔离的 Sandbox 副本： 每个探测 Agent 在受影响文件夹/工作流的独立副本中工作，避免相互影响，且保持真实状态不受破坏。
• 相同测试用例，多次重复： 存在随机变异性。单次探测只是偶然现象；n 次重复（如 3 次，必要时更多）才能得出统计率。
• 采用性价比高、较“朴素”的模型即可且更符合实际——它不应进行聪明盲猜，而应展示文档会将普通 Agent 引导至何处。

最小探测 Prompt（请替换占位符）：

You are exploring <SYSTEM>. It is located at: <PATH>.
TASK: <specific task>.
RULES:
1. You only know the path above, nothing else.
2. Explore to complete the task. Max. <N> steps.
3. Report at the end: VISITED_DIRECTORIES, READ_FILES,
   TASK_COMPLETED (yes/no), MOST_HELPFUL_FILE.

记录为 Baseline 指标（必须是定量的，绝不能凭“感觉更好”）：

| 指标 | 含义 | |---|---| | 成功率 | 按照约定完成任务的频率（如 0/3） | | 错误行为 | 使用错误位置/方法的频率（如 3/3 均使用了汇总日志而非单条日志） | | 达标路径 | 达到目标所需的步骤数/迂回次数 | | 盲区 | 没有任何 Agent 打开的相关文件/位置 |

步骤 2 — 路径分析（Path Analysis）：究竟在哪里失败？

共同评估探测报告（绘制一份访问位置的“热力图”即可）：

• 哪个文件被频繁阅读（热点 / HOT）？如果那里缺少指引，那就是设置路标最有效的位置。
• 哪个相关位置从未被打开（冷点 / COLD / 盲区）？无论其内容多好，实际上它是不可见的。
• Agent 在哪里产生循环或绕过了约定（死胡同、规避行为）？这标志着具体的文档缺口。

发现结果表：

| 发现 | 含义 | 行动（→ 步骤 3） | |---|---|---| | HOT + 无指引 | 高流量，无路标 | 直接在此处设置路标 | | WARM + 发生错误 | Agent 到达但遭遇困难 | 添加示例/澄清说明 | | COLD | 位置从未被找到 | 从 HOT 文件中建立链接指向它 | | 规避行为 | 约定被绕过 | 在规避发生点添加提示 |

步骤 2 的产出：一个具体的、局部化的假设——“Agent 阅读了 X，但 X 未提及该约定；因此他们最终走到了 Y。”

步骤 3 — 干预（Intervention）：设立路标 (Signpost)

仅设立一个路标（每次测试仅改变一个变量，否则 Diff 无法解释）。典型的路标形式：

• 将约定显著放置在 HOT 路径必经之处（例如在阅读量最大的 README/控制文件顶部放置一段简明、明确的提示）。
• 在中央架构/概览文件的开头提供快速导航表，指向以前的盲区。
• 从 HOT 文件向 COLD 位置添加指引/交叉引用 (Cross-reference)。
• 可选：针对危险或违反约定的行为设置防护栏 (Guardrail)（例如 PreToolUse 提示）。

保持路标简短且醒目——Agent 习惯快速浏览，很少长篇大论地阅读。

步骤 4 — 使用全新的朴素子 Agent 进行 Retest

完全相同地重复步骤 1——相同的任务、相同的重复次数、相同的模型、相同的朴素条件——但在带有新路标的 Sandbox 副本上运行。重要注意：

• 使用全新的 Agent，不能带有 Baseline 运行的记忆（否则测量的是学习能力而非可发现性）。
• 与 Baseline 配置相比，仅存在路标差异。

步骤 5 — 与 Baseline 进行 Diff 对比 + 客观的成功测量

将 Retest 和 Baseline 直接并排对比：

| 指标 | Baseline | 设立路标后 | Δ | |---|---|---|---| | 成功率 | 例：0/3 | 例：3/3 | +3 | | 错误行为 | 例：3/3 | 例：0/3 | −3 | | 盲区 | 例：1 | 例：0 | −1 |

评估——切勿美化结果：

• 有效（错误行为显著减少）：保留该路标并记录文档。
• 无效（Δ 变化微弱）：路标位置摆放错误或不够明显 → 返回步骤 2/3，更换路标并重新测量。
• 坦诚说明局限性： 较小的 n 样本仅作为参考而非严密证明；朴素 Agent 模拟的是“平均无知状态”，而非每一位真实用户；在成功评分中显式检查误报/漏报（究竟什么才被算作“完成”？）。

迷你案例研究（真实数据）

问题：某个 Ticket Pipeline 约定轻量级完成项各自需拥有一个专属的 Ticket 日志——但 Agent 却将所有内容都写入了一个汇总日志中。

• 步骤 1 (Baseline)： 3 个朴素子 Agent，相同任务 → 3/3 使用了汇总日志（未遵循约定）。
• 步骤 2 (路径分析)： 阅读量最大的 README 在可见位置未提及单 Ticket 日志规则 → 朴素路径直接引导到了汇总日志。
• 步骤 3 (干预)： 在 README 的显眼位置放置了一段关于日志约定的简短、明确的“路标”。
• 步骤 4 (Retest)： 3 个全新的朴素子 Agent，相同任务。
• 步骤 5 (Diff)： 3/3 错误 → 0/3 错误，三个 Agent 均创建了正确的单 Ticket 日志。（记录于 Ticket T-20260621-44 中。）

教训：约定并非“措辞过于软弱”——而是在实际被阅读的路径上不可见。在正确的位置设立路标，并通过实证验证，解决了问题。

来源与相关方法

本方法源自欲望路径分析 v2.0（Desire-Path Analysis v2.0，将 Swarm 作为 LLM 行为的实证测量工具）。大规模运行（100 个朴素 probe）的原始参考结果作为源证据已被记录：最大的盲区是一个帮助目录，0/100 的 Agent 访问了该目录（尽管包含许多帮助文件）；而“创建新 Skill”任务的成功率为 0%，因为没有人找到模板目录——这两者都是典型的可见性问题，而非内容问题。

参见

• swarm-operations (dev) — 生产任务的 Swarm 协调模式目录；它仅将欲望路径分析作为概念章节。本 Skill 是包含 Baseline→Retest 循环的可操作流程变体。
• pipeline-optimizer (dev) — 6 步 Pipeline 改造流程；其使用全新子 Agent 的重测对应于此处步骤 4–5。
• bugfix-protocol / 系统化调试 — 用于解决真实代码 Bug 而非可见性问题。

修改日志

0.1.0 (2026-06-21)

• 首次从 Desire-Path Analysis v2.0 移植（来源：swarm-ai/BACH）。
• 专注于可操作的 5 步流程（Baseline → 路径分析 → 干预 → Retest → Diff）；故意省略 Swarm 协调模式（保留在 swarm-operations 中）。包含占位符的用户中立说明；真实迷你案例研究。