Skip to content

execution-backends.md

Latest commit

 

History

History
58 lines (37 loc) · 6.04 KB

execution-backends.md

File metadata and controls

58 lines (37 loc) · 6.04 KB
Raw

执行底座接入与切换

SpecFlow 现在通过注册目录发现 Maka 和 OpenCode。Maka 继续作为默认内置底座，正式发布来源、签名校验和桌面打包策略保持原有要求。OpenCode 使用单独安装、由用户启动的本机服务，桌面安装包不包含 OpenCode CLI。

使用 OpenCode

  1. 安装官方稳定版 OpenCode，并在可信的 OpenCode 用户级配置中设置模型供应商。
  2. 在本机启动 opencode serve --hostname 127.0.0.1 --port 4096。如服务设置了 OPENCODE_SERVER_PASSWORD，保留对应用户名和密码用于连接。
  3. 打开 SpecFlow 的“工程设置”，将“当前工程使用”切换为 OpenCode。
  4. 填写本机服务地址和可选认证，保存 OpenCode 连接，然后刷新模型目录。
  5. 为分析、设计、实现、复核选择该底座的模型，保存工程设置。

服务地址只接受 localhost、127.0.0.1 或 [::1] 的 HTTP(S) 根地址；不接受远程地址、内嵌凭据、代理子路径、查询参数和重定向。OpenCode 与 SpecFlow 必须运行在能访问同一工作区路径的本机环境中。

本机服务连接由所有工程共享，保存在工程数据目录的 runtime-connections.json，写入采用临时文件与原子替换。文件可能包含服务密码，应按本机凭据文件保管；权限模式为 0600，Windows 实际访问权限取决于用户数据目录的 ACL。接口只返回地址、用户名和 hasPassword，项目导出与运行记录不包含密码。密码字段缺省表示保留，空字符串表示清除；改变服务地址时不会自动转发旧密码。模型供应商凭据仍由 OpenCode 自己管理。

选择与历史记录

  • 没有 executionBackend 字段的真实项目继续使用 Maka，旧示例继续使用 sandbox。
  • 工程选择与四个角色的默认模型一起保存。换底座会清理不匹配的默认模型；新尝试跳过旧流程中属于其他底座的目标。
  • 每次尝试仍冻结自己的 target.backend、模型、输入哈希和执行身份。切换工程默认底座不会修改已有尝试，也不会移动底座会话。
  • 已有执行的停止、交互回答与原身份核对继续发送给原底座。OpenCode 还有未结束或待核对尝试时，不能修改共享连接配置，以免遗失控制通道。
  • sandbox 只用于隔离示例与契约验收，不作为真实工程底座。

OpenCode 执行边界

每次尝试及每个实现任务创建独立会话。适配器确认返回的目录与会话权限规则，使用显式 provider/model 和用户消息 ID 派发异步提示。执行提示由底座提供工具说明：Maka 使用工作区扩展，OpenCode 使用原生工具，复核的两个独立视角都遵守这一边界。

只读阶段默认拒绝工具权限，仅开放读取、查找与问题交互；禁止写入、shell、子代理及未列出的工具。实现阶段的写入和命令执行需要用户授权。外部目录访问和子代理禁用。权限规则属于 OpenCode 工具策略，不构成操作系统沙箱，获准的命令仍具有该用户的系统权限。

OpenCode 允许自定义工具覆盖同名内置工具，HTTP 工具目录不提供来源，无法识别用户级工具覆盖。因此，只读策略以可信的 OpenCode 用户工具与插件配置为前提，不能约束插件内部执行的任意代码。工程仍按工作树变化拒绝只读阶段的异常写入。

适配器在初始化工作区的 HTTP 请求前检查本地目录，拒绝工作区及父目录中的 OpenCode 项目配置和可执行扩展，避免仓库中的同名工具先被加载再校验。当前不支持项目内 opencode.json、opencode.jsonc 或 .opencode 中的工具和插件；模型供应商应放在用户级配置中。项目出现此类配置时会阻塞并解释原因，不会自动删除或覆盖文件。

派发意图先持久化到 opencode/executions。启动回执丢失、断网或会话空闲都不被当成成功，也不会自动重发提示。终态必须有绑定当前消息的完成凭据；读取完整结果，不截断产物。重启后可按原身份重新核对运行或读取已经保存的终态。

OpenCode 当前报告 canResume: false：重新核对原运行受支持；中断后的继续执行需创建新尝试，不冒充 Maka 的原运行恢复协议。实现阶段中断后，服务核对当前任务并重新执行确定性验证；尚有未完成任务时，整个阶段保持阻塞，不将单个任务完成当成阶段完成，也不自动派发剩余任务。

OpenCode 的步数限制采用轮询观察和工具授权预算，属于保护措施，不是原生硬上限；自动允许的读取和两次轮询之间仍可能继续执行。阶段超时继续由 SpecFlow 请求停止，并以底座确认的状态为准。Maka 使用原生 maxSteps。

接入结构与验证

packages/execution-contract/registry.ts 负责底座注册、独立能力检查、目录汇总和关闭。packages/opencode-adapter 封装 OpenCode HTTP 协议及持久化执行记录。工程服务通过注册目录查找每个冻结目标对应的实现，API 和 UI 共用支持的底座类型。

后续接入其他执行协议时，实现 ExecutionBackend 并注册，再扩展明确支持的底座 ID 与相应配置。适配器可提供自己的工具说明；能力和限制必须真实报告。

验证命令：

npm run typecheck
npm test
npm run build
# 指向单独准备的官方稳定版 CLI；脚本不安装 CLI，也不调用真实模型。
$env:SPECFLOW_OPENCODE_CLI = 'C:\path\to\opencode.exe'
npm run opencode:smoke

自动测试覆盖注册与离线隔离、切换和历史身份、API 凭据剔除、权限和问题交互、只读策略、完整结果、停止、断网和重启核对。真实服务验收脚本隔离配置、状态与缓存，仅连接本地模拟供应商。协议依据为 OpenCode Server 和 官方源码，真实验收使用官方稳定版 1.19.3；不把某次验收结果扩展为对所有历史版本的兼容保证。