跳转至

Windsurf 工作区路由

  • 作者: @n3wth
  • 状态: 提案。等待维护者范围批准和设计评审。
  • 日期: 2026-11-10
  • 跟踪: #376

问题陈述

Windsurf Cascade 从 .windsurf/rules/*.md 加载工作区规则,并从 .windsurf/workflows/*.md 加载斜杠工作流。在 Windsurf 中打开 EGM 仓库的用户没有针对七个 EGM 工作流的原生入口点。将技能说明复制到 .windsurf/workflows/ 会导致与 skills/*/SKILL.md 发生漂移,并违反 Goldfish 新上下文审查者隔离。

本规范为 Windsurf Cascade 定义了一个实验性工作区路由适配器。每个 Windsurf 入口点都直接路由到仓库根目录下的规范 skills/、agents/ 和 resources/ 文件。只要 Windsurf 缺乏隔离的只读子代理委派,Goldfish 群体工作流就会立即停止。

范围

本节定义了 #376 下实验性 Windsurf 工作区路由的边界。

目标

实验性适配器提供四项能力:

  • 将所有七个 EGM 工作流暴露为 .windsurf/workflows/egm-*.md 斜杠命令,最多 15 行,且不复制技能说明。
  • 定义一个 .windsurf/rules/egm.md 工作区规则(trigger: model_decision),将 EGM 请求路由到共享根文件。
  • 当新上下文的只读子代理不可用时,停止 Goldfish 群体工作流(egm-brainstorm、egm-review、egm-review-loop)。
  • 在 tests/unit/test_windsurf.py 中离线验证路由契约、技能覆盖和行数限制。

非目标

此变更排除四项:

  • 在实时工作流执行、只读强制和审查者隔离测试通过之前,声明已验证的 Windsurf 支持。
  • 在 .windsurf/ 内复制 skills/*/SKILL.md 或 agents/*.md 中的提示规则。
  • 不支持非根安装或文件系统符号链接,这些会破坏 Windows 检出和多 harness 插件验证器。
  • 在第一阶段构建自定义 Windsurf 扩展二进制文件或 MCP 子代理服务器。

现有组件与所有权

所有规范工作流行为仍保留在仓库根目录的 skills/、agents/ 和 resources/ 中。有关当前宿主边界,请参阅 harnesses 和 TESTING.md。

Windsurf 适配器贡献者维护 .windsurf/、harnesses 中的状态条目以及 tests/unit/test_windsurf.py。仓库维护者批准功能范围,并决定何时实际测试记录足以将 Windsurf 从实验状态升级。人类用户掌控所有设计决策和工作流审批门。

拟议架构

该适配器需要一个工作区根检出,其中 .windsurf/ 与 skills/、agents/ 和 resources/ 并排。它在 .windsurf/ 下添加八个精简 Markdown 文件、harnesses 中的一个状态段落,以及一个单元测试模块。

组件布局

下表列出了适配器中的每个文件及其契约。

路径 角色 约束
.windsurf/rules/egm.md 工作区路由和 Goldfish 隔离规则 使用 trigger: model_decision frontmatter,并保持在 20 行以内
.windsurf/workflows/egm-*.md 指向 skills/egm-*/SKILL.md 的七个斜杠命令指针 保持在 15 行以内,且不复制任何技能说明
docs/harnesses.md 面向用户的宿主状态记录 将 Windsurf 标记为实验性,并注明缺少实时隔离证据
tests/unit/test_windsurf.py 离线契约测试 验证规则 frontmatter、技能对等性、目标路径和隔离拆分

执行与隔离流程

当用户在仓库根目录下的 Windsurf Cascade 中运行 /egm-<workflow> 时,执行遵循以下规则:

  1. Cascade 读取 .windsurf/workflows/egm-<workflow>.md 和 .windsurf/rules/egm.md。
  2. Cascade 相对于工作区根目录解析 skills/egm-<workflow>/SKILL.md、agents/*.md 和 resources/document_standards/*.md。
  3. 可内联运行的工作流(egm-draft、egm-resolve、egm-drift-report、egm-bootstrap)在当前会话中运行。在 egm-bootstrap 中,当没有子代理工具时,Cascade 内联运行侦察步骤,与 egm-bootstrap 一致。
  4. Goldfish 群体工作流(egm-brainstorm、egm-review、egm-review-loop)需要隔离、只读且零父历史的子代理。在执行审查者提示之前,工作流包装器指示 Cascade 在原生只读子代理委派不可用时停止。Cascade 报告同上下文审查不是 Goldfish 审查,并且不调用任何写入或 shell 工具。
  5. 每个 Goldfish 审查者都在宿主的只读子代理配置文件(Devin CLI 中的 subagent_explore,不暴露任何写入、编辑或 shell 工具)上启动。规则和三个 Goldfish 包装器禁止可写配置文件,并禁止恢复审查者。审查者以文本形式返回发现。只有父级写文件:技能分配给它的输出,或用户要求的、经用户批准写入后的文件。

人工审批门

当没有可用的结构化问题小部件时,Windsurf Cascade 使用普通聊天响应。该适配器保留规范技能中的所有人工暂停点:

  • Brainstorm:在 Goldfish 分派之前等待用户就绪,并在交接之前等待简报批准。
  • Draft:等待输入签核、章节批准和输出路径批准。
  • Review:一旦子代理委派存在,等待预设选择和阶段暂停选择。
  • Resolve:展示拟议修复和有争议的项目,并在编辑文件前等待用户明确批准。

验证与发布门禁

验证将密封式 CI 测试与实时的 Windsurf Cascade 探针区分开来,与 additional-harnesses.md 和 TESTING.md 保持一致。

离线测试

自动化 CI 在未安装 Windsurf 的 Linux 和 Windows 上运行 tests/unit/test_windsurf.py:

  • 验证 .windsurf/rules/egm.md 能解析有效的 YAML frontmatter,设置 trigger: model_decision,并声明 fresh-context 规则。
  • 验证 .windsurf/workflows/*.md 与 EXPECTED_SKILLS 一一对应,且每个文件保持不超过 15 行。
  • 验证 Goldfish swarm 工作流(egm-brainstorm、egm-review、egm-review-loop)带有子代理停止规则,而单会话和内联工作流(egm-draft、egm-resolve、egm-drift-report、egm-bootstrap)不会误停止。
  • 验证该规则和三个 Goldfish 包装器指定只读子代理配置文件,禁止恢复审阅者,并将文件写入保留给父级。

实时晋升门禁

在贡献者为三个门禁在固定的 Windsurf 版本上记录实时证据之前,Windsurf 保持实验状态:

  1. 工作流执行:从干净的工作区运行 egm-brainstorm、egm-draft 和 egm-review,并验证交互式的人工暂停。
  2. 只读强制:尝试从 Goldfish 审阅者子代理写入一个一次性工作区文件,并验证主机工具拒绝。
  3. 新上下文隔离:在父会话中放置一个随机标记。检查 Windsurf 轨迹日志,验证子审阅者既不会收到父历史,也不会收到同级发现。

门禁 2 需要两个探针。一个未指定任何 EGM 工作流的请求不会加载 model_decision 规则,因此它无法测试适配器。通过让只读配置文件上的子代理创建一个文件来探测主机。通过在 /egm-review 内请求每位审阅者保存各自的笔记来探测适配器。

记录的 CLI 证据(2026-11-10)

Cognition 于 2026-06-02 将 Windsurf 更名为 Devin Desktop。Devin Local 取代 Cascade 成为本地代理,传统 Cascade 代理于 2026-07-01 终止。Devin Desktop 和 Devin CLI 运行同一个 Devin Local 代理。这些运行未安装 Devin Desktop。作者在 macOS 27.2 上,从 Muse 1.4.15 会话中,通过 tmux 以无头模式和交互方式,针对 #379 适配器驱动 Devin CLI 3000.12.43。CLI 将 .windsurf/rules/egm.md 列为一条 Windsurf 规则。它未将 .windsurf/workflows/ 列为斜杠命令;/egm-* 请求通过该规则路由。每次文件写入都被拒绝,因此没有工作流运行到其最终产物。

门禁 CLI 结果 证据
工作流执行 路由与暂停均通过 egm-brainstorm、egm-draft 和 egm-review 读取了各自的 SKILL.md。Draft 在任何写入前暂停了三次。Brainstorm 在分派七位审阅者前等待就绪。Review 在接收阶段暂停
只读强制 通过 只读配置文件上的子代理没有任何可写入的工具。在 EGM 工作流内部,22 次审阅者启动中有 22 次使用该配置文件且无恢复。用户要求的一份审阅者笔记文件以父级写入提示的形式到达用户处,并未被写入
新上下文隔离 通过 该标记出现在 0/2 的审阅者任务文本中,以及 0/70 的主机会话存储子转录节点中

这些运行不满足晋升门禁。它们使用了 CLI 而非 IDE,并且在最终产物之前停止。

Alternatives considered

下表根据维护成本和隔离安全性评估设计备选方案。

备选方案 决策 理由
将 SKILL.md 正文复制到 .windsurf/workflows/*.md 已拒绝 Windsurf 将每个工作流限制为 12,000 个字符,并且复制的提示会在每次编辑时发生漂移
将 .windsurf/workflows/ 符号链接到 skills/ 已拒绝 Windsurf 期望扁平的 .md 文件,而符号链接在 Windows 检出和打包器中会失败
在单个聊天中顺序模拟 Goldfish 角色 已拒绝 共享的对话历史违反 EGM 新上下文审阅者独立性
构建 MCP 服务器以生成外部审阅者 已推迟 MCP 服务器会增加运行时设置和 API 密钥处理;如果 Windsurf 不添加原生子代理 API,这应归入单独的提案
将所有 Windsurf 文件推迟到实时隔离通过 已拒绝 最简路由文件让用户可以安全地运行 egm-draft 和 egm-resolve,同时阻止模拟审阅

风险与缓解措施

下表列出了技术约束、安全风险和缓解措施。

风险 影响 缓解措施
Cascade 忽略散文规则并模拟内联审阅 破坏 Goldfish 隔离并暴露工作区写入工具 保持 Windsurf 实验状态,在三个 Goldfish 包装器中放置即时停止指令,并禁止审阅路径中的写入或 shell 调用
Windsurf 对每个工作流文件强制执行 12,000 字符限制 大型工作流在 Cascade 中无法加载 在 test_windsurf.py 中将 .windsurf/workflows/*.md 限制为 15 行,并将完整提示保留在 skills/ 中
用户复制 .windsurf/ 而没有仓库根目录 相对的 skills/ 路径无法打开 在 .windsurf/rules/egm.md 中说明工作区根目录布局要求,使缺失文件立即失败
一个未指定任何 EGM 工作流的请求要求一个审阅者子代理 主机不会加载该规则,选择具有写入能力的配置文件,并主动为审阅者写入 超出适配器范围。该规则仅管辖 EGM 工作流;上述门禁 2 探针在其中运行
用户在交互式会话中拒绝权限提示 主机在没有任何消息的情况下结束其回合,并丢弃批量工具调用 主机行为。发送后续消息以继续;在 harnesses 中将其记录为限制
个人会话钩子或 MCP 服务器注入指令 无头运行可能在读取技能之前因被拒绝的工具调用而停止 使用没有钩子的主机配置运行实时探针
新增 EGM 技能在没有 Windsurf 工作流的情况下落地 斜杠命令列表落后于 skills/ test_windsurf.py 在每次 PR 上断言与 EXPECTED_SKILLS 完全相等

发布与回滚

发布采用基于 #376 的双 PR 栈:

  1. 合并此第 1 阶段规范及其在 README.md 中的索引行(Refs #376)。
  2. 合并叠加的第 2 阶段实现(见 #379)(Refs #376),并在实际 Windsurf 验证通过之前保持 #376 处于打开状态。

回滚只需对 #379 执行一次 revert。Revert 会移除 .windsurf/、适配器 中的状态说明以及 tests/unit/test_windsurf.py,不会影响任何其他适配器。

待定决策与评审状态

  • 在 #379 合并之前,维护者必须根据 #376 评审此第 1 阶段范围。
  • 作者于 2026-11-10 在 Devin CLI 上运行了子代理委派、只读拒绝和会话存储检查;参见 已记录的 CLI 证据。尚无贡献者在 Windsurf IDE(Devin Desktop)中运行这些检查,或针对最终产物运行它们。
  • 维护者需要决定 Devin CLI 证据是否计入晋级门槛,还是只有 IDE 证据才计入。这两个界面都运行 Devin Local。
  • 作者于 2026-11-10 针对功能规范标准运行了 EGM Structural、Style 和 Design Critic Goldfish 评审器,并解决了本草案及 #379 中的所有 Blocker 和 Major 发现。

研究参考资料

评审于 2026-11-10。这些链接记录的是 Windsurf 界面,而非 EGM 验证证据:

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model