Windsurf 工作区路由¶
问题陈述¶
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> 时,执行遵循以下规则:
- Cascade 读取
.windsurf/workflows/egm-<workflow>.md和.windsurf/rules/egm.md。 - Cascade 相对于工作区根目录解析
skills/egm-<workflow>/SKILL.md、agents/*.md和resources/document_standards/*.md。 - 可内联运行的工作流(
egm-draft、egm-resolve、egm-drift-report、egm-bootstrap)在当前会话中运行。在egm-bootstrap中,当没有子代理工具时,Cascade 内联运行侦察步骤,与 egm-bootstrap 一致。 - Goldfish 群体工作流(
egm-brainstorm、egm-review、egm-review-loop)需要隔离、只读且零父历史的子代理。在执行审查者提示之前,工作流包装器指示 Cascade 在原生只读子代理委派不可用时停止。Cascade 报告同上下文审查不是 Goldfish 审查,并且不调用任何写入或 shell 工具。 - 每个 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 保持实验状态:
- 工作流执行:从干净的工作区运行
egm-brainstorm、egm-draft和egm-review,并验证交互式的人工暂停。 - 只读强制:尝试从 Goldfish 审阅者子代理写入一个一次性工作区文件,并验证主机工具拒绝。
- 新上下文隔离:在父会话中放置一个随机标记。检查 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 阶段规范及其在 README.md 中的索引行(
Refs #376)。 - 合并叠加的第 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