从目标到交付。

介绍

Wave Flow 是一个本机运行的 AI Agent 工作流桌面应用。你用对话描述目标，主控提出工作流方案；确认后，由真实的 Codex、DeepSeek Harness 或 Claude Code 会话按阶段执行。

它不是把多个聊天窗口拼在一起。阶段、依赖、并行与完成条件写在 Workflow 里；每个 Agent 节点绑定一条独立的 ACP 会话，下游不会隐式继承上游聊天历史。

Web 只展示和控制 Run；Runtime 负责动态调度与节点状态；ACP Adapter 负责经 stdio 启动本地 Agent 并管理会话与流式事件。每一层都不越过自己的职责。

安装与运行

当前提供 v0.2.5 预编译 dmg（macOS 12+ / Apple Silicon）。可在 下载页 一键安装，或准备以下环境从源码运行：

• macOS 12.0 或更高版本
• Bun，用于安装依赖与编译 Engine sidecar
• Rust 工具链与 Xcode Command Line Tools
• 至少一个已登录的本机 CLI：Codex、DeepSeek Harness 或 Claude Code

克隆仓库并以开发模式启动桌面应用：

git clone https://github.com/Oliver-Ysq/wave-flow.git
cd wave-flow
bun install
bun run desktop:dev

开发模式使用独立的窗口配置与 bundle id，不会覆盖正式安装的应用。只迭代工作台界面时，可以运行 bun run web:dev。

构建可运行的 macOS 应用：

bun run desktop:build

产物位于 src-tauri/target/release/bundle/。当前 desktop:prepare 只产出 Apple Silicon（aarch64-apple-darwin）的 Engine sidecar；Intel 构建需要另加目标并验证。开发机没有证书时使用 ad-hoc 签名；正式分发仍需单独配置签名与公证。

第一次任务

1. 描述目标。在项目中新建任务，用一段话说明要完成什么、范围在哪、哪些事情不能做。在输入框输入 / 可以打开命令菜单，用 /wave-flow 让主控直接基于目标生成 Workflow 草案。
2. 先看方案。主控会把目标整理成 Workflow 提案；你可以继续对话，调整阶段、Prompt 或 CLI 分配。
3. 确认后启动。在方案页确认输入参数、每个节点的 CLI，以及写入任务需要的 Git 授权。
4. 按阶段查看。执行页按 Phase → Agent 展示状态、流式正文和工具活动；点击节点可以看到当前动作。
5. 结束并复核。执行结束后查看结构化交付与执行总结。需要你输入时，Agent 会显式 block，答案只会唤醒原命令，是否继续仍由原 Agent 决定。

内置预置工作流

除了用对话生成方案，你也可以直接选一个内置预置开始。它们是随应用分发的编排脚本，参数由你在保存前确认；三个预置全程只读，不修改任何文件，也不运行构建或测试。

• 代码审查。两个顺序只读 Worker：先审查指定范围，再由另一个 Worker 独立复核证据，剔除无依据的结论。
• 深度调研。计划 Agent 先把主题拆成可并行核验的研究问题，并等你确认或调整方向；随后并行多源调研，每条结论必须带原文摘录与来源地址，并由独立核验员重新打开来源逐条复核；再交叉检查互相矛盾、单一来源承重等问题；deep 模式还会按证据缺口做第二轮定向补证；最后经红队反向审查与修订，产出带引用与置信度分级的报告。
• 深度代码审查。先摸底变更面、模块结构与仓库内的审查规范，再由六个专项审查员（正确性、安全、并发与状态、错误处理与资源、接口与数据兼容、意图与测试）并行审查；每个发现都要带文件、行区间、触发场景与置信度，并由独立复核员重新打开源码逐条核实、剔除误报；之后跨维度去重排序、给出合并建议，并扫描出未被覆盖的高风险文件。

编写 Workflow

本地 Workflow 是项目内你明确选择的受信任 .ts 文件。它是 ESM 模块：导入作者 API、导出纯字面量 meta、默认导出一个 run(args)。新任务还必须声明纯字面量的 meta.inputSchema，它是 JSON-safe 对象参数 Schema，不是节点结果 Schema。

import { agent, log, parallel, phase } from "wave-flow";

export const meta = {
  name: "cross-review",
  description: "多 Agent 交叉代码审查",
  phases: [{ title: "独立审查" }, { title: "集中复核" }],
  inputSchema: {
    type: "object",
    properties: { target: { type: "string", minLength: 1 } },
    required: ["target"],
    additionalProperties: false,
  },
};

export default async function run(args: { target: string }) {
  phase("独立审查");
  log(`审查目标：${args.target}`);
  const reviews = await parallel([
    () => agent("独立审查变更，只报告有证据的问题。", {
      id: "codex-review", cli: "codex",
    }),
    () => agent("从安全与副作用角度复核。", {
      id: "dsh-review", cli: "dsh",
    }),
  ]);

  phase("集中复核");
  return agent("比较两份结论，标出冲突与未验证假设。", {
    id: "verdict", cli: "claude",
  });
}

meta 契约

• name 使用 kebab-case，例如 deep-research。
• description 是非空单行说明，用于方案标题，不要把完整目标塞进去。
• phases 是非空有序数组，标题唯一；每次 phase(title) 必须精确匹配其中一项。
• exampleArgs 可选，键必须对应 run(args) 实际读取的字段。
• meta 必须是纯字面量：不能含变量、调用、展开、计算属性或模板字符串。

保存方案时会重新预检：只读取文件、校验形状与 Schema，不会运行脚本。主控提交的受限草案不是模块，禁止任何 import / export，只能使用运行时注入的 API；两种形态不要混用。

作者 API

优先使用下面五个原语表达依赖关系。不要臆造嵌套 workflow()、重试或预算字段。

agent() 的 sandbox 只支持 read-only（默认）与 workspace-write。它不是安全沙箱，只约束 Adapter 启动的 CLI，不约束 Workflow JavaScript。

需要解析的 Agent 结果应同时提供 JSON-safe schema 与对应的 TypeScript 类型。直接 await 的失败会把节点标记为 interrupted；并发任务失败时结果为 null。

并行与写入

并行写共享同一工作现场，宿主不做冲突检测或自动合并。任务分配必须按模块或文件分区：同一文件、同一函数或同一配置块只能有一个 writer；依赖前序结果的写入放到后续 phase。

写入类 Workflow 使用受管 Git worktree，执行不会自动 commit、合并或 push。完成后宿主不保存任何成果快照、不写证据 ref、不创建 commit，HEAD 与真实索引不变；结果就是该 worktree 当前的未提交文件，不写入主工作区，查看、修改、提交或清理由你自行决定。

状态与完成

业务状态只由受管会话中的 wave-flow complete、block、continue 改变；wave-flow answer 只交付信息，不能直接改变节点状态。不能从终端 ANSI、自然语言“完成”或空闲提示推断状态。

complete 只有在 JSON 结果、Schema 校验记录与 Journal 都耐久落盘后才生效。用户停止记为 cancelled；未知进程或会话异常记为 interrupted，不存在 Agent 主动上报的业务失败状态。

Agent 上报会携带 Run、节点、会话标识与当前 Engine 颁发的 capability。稳定三元组只用于定位候选会话；Engine 还会验证 Journal、ACP session binding 与节点状态。

暂停与恢复

关闭窗口不会停止 Engine 或 Agent。Engine 重启后不会跨进程认领 ACP 会话：旧的 active 节点一律收敛为 interrupted，只有你在执行页显式恢复才会创建新 attempt。

恢复只复用同一 Execution 内严格匹配的已完成前缀。匹配项包括 Workflow hash、cwd、Runtime 版本、id、调用顺序、CLI、输入、sandbox、model 与 Schema 指纹；第一个重启节点之后的下游节点不会复用旧结果。

Journal 是执行证据，不是虚拟机快照：恢复不会回滚文件，也不会撤销外部副作用。Worker 原生会话持续五分钟无实质进展（正文/工具/计划事件）时，执行器只记录一条停滞诊断提示，不自动中断、不重发任务，唯一出口是你显式停止。

停止与退出会撤销排队及初始化中的启动许可；Journal 写入失败会 fail closed，停止流程仍尽力通知真实 Worker。writer 在 spawn 前记录启动意图，崩溃后无法核验时拒绝直接恢复，避免双写。大批量路径采用流式收集并分页读取；执行详情只在上一请求结束后继续轮询，避免大响应使页面持续加载。

支持的 CLI

三个 CLI 均已完成主控与 Worker 双角色真实验收，可以在设置页设为主控。当前由你手动分配 CLI，不提供自动模型路由。

每个 Agent 节点绑定独立会话，使用你选择的 CLI 及其默认模型。下游不会隐式复用上游聊天历史，因此每个 prompt 都必须自包含任务、范围、相关上游结果与期望产出。

边界

• 一期是本机单用户桌面产品：不做登录、多人协作、云端同步、远程控制或可视化 Workflow 编辑。
• Workflow 只允许本地加载；不支持 URL、自动下载或未知来源。它是受信任扩展模块，不是不可信代码沙箱。
• 主控默认开启感知模式：可读取项目内容与已登录工具，但不会写入当前项目；修改项目仍必须提出 Workflow 并经你确认。感知模式可在设置中关闭。Worker 使用可信原生 CLI 配置与权限，不额外施加 Wave Flow OS 文件隔离。
• 写入类任务使用独立 worktree；不自动合并或 push。worktree 不能阻止跨目录写入，Git 记录也不覆盖工作区外影响。
• 模型请求仍由所选 CLI 发送给其服务商；本地运行不代表离线推理或数据不出本机。
• 完整执行总结、当前现场补充与 writer 安全交接是修订启动的前置条件；Schema 通过不是验收。
• 中断恢复只复用同一执行内严格匹配的已完成前缀；不会回滚文件或撤销外部副作用。