Wakeflow

<div align="center"> # 流程管控 一套用于多窗口代理工作的纪律严明控制循环 — 每一步都被追踪，每个结果都被证明。 [English](README.md) | [简体中文](README.zh-CN.md) 流程管控将本地 Codex 或 Claude Code 工作空间转变为一个纪律严明的控制器系统：一个控制器窗口，专注的仓库窗口，明确的状态根，紧凑的直接线程或直接会话传递，以及基于证据的验收。控制器以闭环方式运行此循环 — 计划、调度、收集证据、审查、决策、重复 — 并记录每一步，因此整个运行过程在事后可审计。 </div> --- - [为什么需要流程管控](#为什么需要流程管控) - [架构](#架构) - [安装流程管控](#安装流程管控) - [初始化工作空间](#初始化工作空间) - [流程管控创建的内容](#流程管控创建的内容) - [自动化语义](#自动化语义) - [MCP 能力表面](#mcp-能力表面) - [运行时和账本边界](#运行时和账本边界) - [双主机工作空间](#双主机工作空间) - [市场发布](#市场发布) - [在此仓库中工作](#在此仓库中工作) - [设计原则](#设计原则) ## 为什么需要流程管控 大型代理辅助工作很少局限于一个仓库或一次对话。一个目标可能需要一个控制器、产品仓库、设计窗口和真实场景测试窗口。如果没有共享的操作模型，工作就会退化为分散的提示、复制的状态表、不明确的所有权和未完成的证据审查。 流程管控提供了缺失的控制层： - **控制器优先的判断**：父工作空间拥有目标、边界、调度决策、验收、待办事项路由和存档决策。 - **每个需求一个状态根**：任务包、目标结果、审查候选、决策和进度预测都与同一个需求绑定。 - **专注的子窗口**：每个仓库窗口仅在其配置的责任边界内工作。 - **紧凑的交付**：直接线程提示唤醒正确的窗口，带有小信封；状态根和技能保留任务详细信息。 - **证据优先于验收**：目标回填是输入，而不是结论。控制器在完成工作之前仍然审查原始证据。 - **本地优先运行时**：真正的线程 ID 仅存在于本地线程注册表中；窗口配置是派生的可发送视图，活动状态保留在跟踪源之外。 流程管控不是一个命令启动器，带有更漂亮的名称。它是一个可重用的工作流能力，用于保持多窗口代理工作可读、有边界和可恢复。 ## 架构 流程管控是三个层一起工作：一个可见的窗口舰队，一个移动工作的闭环，以及一个在重启后存活的磁盘布局。两个版本 — Codex 和 Claude Code — 运行相同的共享核心；只有传输方式不同（Codex 主线程工具与 tmux 发送助手）。 ### 层 1 — 舰队（你看到的） 每个流程管控窗口都是一个长期存在的代理会话，固定在一个责任上。在 Claude Code 上，舰队存在于一个 tmux 会话中，带有实时状态徽章；在 Codex 上，窗口是主机线程。 | 窗口 | 角色 | 默认推理努力（Claude Code） | | --- | --- | --- | | 控制器 | 拥有目标、调度、证据审查、验收 | `max` | | 设计 | 澄清需求、重新设计非错误结果不匹配、准备交接 | `xhigh` | | 仓库窗口 | 在一个仓库内实施 | `xhigh` | | 测试 | 仓库无法自行运行的真实场景验证 | `xhigh` | ### 层 2 — 环路（工作如何移动） 工作被组织成需求：一个需求 = 一个目标 = 磁盘上的一个状态根。每个需求都经过相同的闭环： ```text 1 初始化 控制器创建需求状态根（未认领） 2 认领 第一个驱动命令将其绑定到一个平台（codex | claude） 3 添加任务 任务包命名目标窗口和范围 4 调度 信封写入 -> 窗口锁定 -> 提示传递 5 工作 目标窗口在其仓库边界内执行 6 结果 目标结果信封落地，带有证据引用 -> 锁定释放 7 审查 控制器读取原始证据，然后接受/重做/阻止 8 完成 只有当所有任务都被接受并且没有阻塞器剩余时 ``` 两个规则使环路保持诚实：**提示唤醒，状态指示**（传递的提示仅命名窗口、任务 ID 和状态根；任务定义存在于状态根和技能中），以及**回填是输入，而不是验收**（控制器在任何决策之前审查原始证据；阻塞的决策在新证据到达后始终可恢复）。 ### 层 3 — 地面（磁盘上有什么） ```text <workspace>/ workspace.config.json 窗口、角色、每台主机旋钮 已提交 AGENTS.md / CLAUDE.md 每台主机控制器门控 已提交 wakeflow-ledger/ 耐用设计、记录、存档 已提交 .wakeflow-active/ 需求状态根（层 2） 本地 .wakeflow-local/wakeflow-delivery/ 本地 dispatch-packets/ delivery-envelopes/ delivery-runs/ 传输记录 target-results/ 证据信封 locks/ 每个窗口一个正在进行的交付，跨主机 hosts/codex/ codex 线程注册表 （主机范围） hosts/claude-code/ claude 会话注册表 + tmux 绑定 ``` 经验法则：**业务真相是主机中立且共享的；传输句柄是主机范围的，永远不会离开 `.wakeflow-local/`。** ### 谁决定什么（信任模型） 脚本和 MCP 工具创建、验证和记录机器数据；它们永远不会接受工作、扩大范围或决定产品行为。目标窗口执行其调度的包。控制器是唯一的验收权限，用户拥有产品决策。 ### 双主机共存 一个工作空间可以同时运行两个版本：需求在认领时绑定到一个平台（在每个驱动命令上强制执行），共享的每个窗口锁序列化跨主机交付，所有权仅通过明确的审计 `adopt-demand-host` 转移。 ## 安装流程管控 流程管控使用与 Lark Remote 相同的两层市场形状：仓库根是开发工作空间，可安装的插件工件位于 `plugins/` 下。仓库提供两个版本的主机版本，从同一个共享核心构建： | 主机 | 工件 | 目录 | | --- | --- | --- | | Codex | `plugins/codex-wakeflow/` | `.agents/plugins/marketplace.json` | | Claude Code | `plugins/claude-code-wakeflow/` | `.claude-plugin/marketplace.json` | 从 Claude Code 中安装 Claude Code 版本： ```text /plugin marketplace add GxFn/Wakeflow /plugin install wakeflow@gxfn ``` Claude Code 版本仅限终端使用：每个流程管控窗口（包括控制器）都是一个 tmux 驻留的交互式 `claude` 会话，位于 `wakeflow` tmux 服务器会话中，线程 ID 是窗口的 Claude Code 会话 ID（在恢复过程中稳定）。有关完整的 Claude Code 指南，请参见 [plugins/claude-code-wakeflow/README.md](plugins/claude-code-wakeflow/README.md)。 安装公共 Codex 插件工件： ```bash npx codex-marketplace add GxFn/Wakeflow/plugins/codex-wakeflow --plugin ``` 对于匹配标签后固定的版本： ```bash npx codex-marketplace add https://github.com/GxFn/Wakeflow/tree/v0.5.6/plugins/codex-wakeflow --plugin ``` 如果 Codex 对话框分离源、引用和稀疏路径，请使用仓库 URL、所需引用和 `plugins/codex-wakeflow` 作为稀疏路径。 对于本地开发，将此检出注册为其自己的本地市场： ```toml [marketplaces.gxfn] source_type = "local" source = "/absolute/path/to/Wakeflow" [plugins."wakeflow@gxfn"] enabled = true [plugins."wakeflow@gxfn".mcp_servers.wakeflow] default_tools_approval_mode = "approve" ``` 流程管控不需要聚合市场仓库。单独的目录仍可以列出流程管控以进行品牌发现，但这不是主要的安装或发布路径。 ## 初始化工作空间 流程管控作为 Codex 或 Claude Code 插件安装。目标工作空间不需要包含流程管控源代码。预期的目标形状是： ```text MyWorkspace/ AGENTS.md 或 CLAUDE.md workspace.config.json .wakeflow-active/ # 忽略活动控制器状态 .wakeflow-local/ # 忽略线程注册表和派生运行时 wakeflow-ledger/ # 耐用项目协调记录 ProductRepo/ CoreRepo/ Design/ # 默认内部需求设计表面 Test/ # 默认内部测试协调表面 ``` 最简单的用户提示是： ```text 使用流程管控初始化当前工作空间。 在写入前先预览计划并等待我的确认。 ``` 操作流程是： 1. Codex 调用 `wakeflow_initialize_workspace`，参数为 `apply: false`。 2. 流程管控返回目录事实和 `agentSelectionProtocol`。 3. Codex 根据这些事实和用户上下文判断工作空间是干净还是凌乱的。 4. 对于干净的工作空间，Codex 调用工具并使用明确的 `repositories` 映射来调用预期的工作窗口。 5. 对于凌乱的工作空间，Codex 在写入前询问哪些目录是托管窗口。 6. 在用户确认新鲜工作空间后，Codex 调用 `wakeflow_initialize_workspace`，参数为 `apply: true`。 7. Codex 创建返回的 Codex 线程，将每个线程标题重置为返回的 `displayTitle`，并将每个真实线程 ID 传递给流程管控的本地注册命令。线程注册表是唯一的线程 ID 权限；窗口配置刷新为派生的视图。 对于已经初始化的工作空间，`wakeflow_initialize_workspace` 不是一个通用的刷新按钮。除非用户明确请求重置初始化，否则它可能不会写入；`apply` 调用必须设置 `resetInitialization: true`，传递明确的 `repositories`，重新确认 Design/Test 模式，并且不能使用 `useDiscovered`。重型或过时的窗口使用替换命令代替。 命令职责保持分离： | 需要 | 命令 | 责任 | | --- | --- | --- | | 首次设置 | `wakeflow_initialize_workspace` | 发现、确认、写入工作空间配置/文档/支持表面，并返回完整的启动计划。 | | 显式重置设置 | `wakeflow_initialize_workspace`，参数为 `resetInitialization: true` | 重新确认工作目录，清理过时的托管窗口卡/运行时，并重写设置表面。 | | 一个重型/过时窗口 | `wakeflow_replace_windows`（传递 `window`） | 返回一个替换启动条目和本地注册命令；不刷新工作空间文档。 | | 几个重型/过时窗口 | `wakeflow_replace_windows` | 返回请求的替换条目和本地注册命令；不相关的窗口不重写。 | 在 Claude Code 版本中，使用相同的预览/应用合约。返回的启动计划由 tmux 主机助手实现，而不是 Codex `create_thread`：每个窗口作为交互式 `claude` 会话启动，返回的 Claude Code 会话 ID 注册为流程管控线程 ID。 Design 和 Test 是默认的新支持表面。现有的类似命名的目录（例如 `<Product>Design` 或 `<Product>Test`）被视为普通目录事实，除非用户明确将它们映射为 Design/Test。 流程管控支持本地化初始化。传递 `language: "zh"` 表示中文工作空间，`language: "en"` 表示英文工作空间，或 `language: "auto"` 表示没有明确偏好。生成的线程标题将窗口名称放在前面，以便在狭窄的侧边栏中保留重要的仓库名称可见。新状态根进度文档和后续统一状态渲染也使用选定的界面语言。 控制器和子窗口可以使用 Codex 或 Claude Code 子代理来加速有界代码搜索、日志分类、测试本地化和证据摘要。子代理输出仅为证据或建议；控制器审查、调度、状态写入和仓库边界仍然由拥有任务的流程管控窗口负责。 ## 流程管控创建的内容 初始化写入仅所需的表面，以便确认工作空间边界： | 表面 | 用途 | | --- | --- | | `AGENTS.md` | 父控制器门控和耐用边界。 | | 子 `AGENTS.md` 访问卡 | 每窗口责任和读取路径。 | | `workspace.config.json` | 托管窗口、仓库路径、角色和默认语言。 | | `.wakeflow-active/` | 活动状态根、当前索引、进度文档、待办事项预测、输入和测试卡。 | | `.wakeflow-local/` | 线程注册表、直接线程运行时、本地覆盖和派生的窗口配置。 | | `wakeflow-ledger/` | 长期项目协调记录和存档。 | | `Design/` | 默认内部需求设计工作空间，如果没有外部 Design 仓库映射。 | | `Test/` | 默认内部测试协调工作空间，如果没有外部 Test 仓库映射。 | 流程管控还同步 `.gitignore`，以便只有 `.wakeflow-active/` 和 `.wakeflow-local/` 保留为本地运行时目录。它不将产品仓库、Design/Test 文件夹、账本、`.DS_Store` 或其他用户工作空间噪音添加到 `.gitignore` 中。 ## 自动化语义 流程管控自动化是直接线程传递加上显式结果返回。 核心规则： - 真实的线程 ID 仅存在于主机范围的本地线程注册表中，位于 `.wakeflow-local/wakeflow-delivery/hosts/<host>/thread-registry/`（`codex` 或 `claude-code`）。 - 窗口配置从 `workspace.config.json` 和线程注册表存在中派生；它不是第二个线程 ID 或窗口语义权限。 - 传递提示保持紧凑和人类可读。 - 主机通过其传输边界发送提示：Codex 线程工具用于 Codex，tmux 主机助手用于 Claude Code。流程管控记录发送和读回证据。 - `group-ready` 在预期目标结果之前等待控制器返回。 - `per-target` 可以唤醒控制器一次目标，同时仍然保留组快照。 - 在记录发送的真实发送带有读回证据后，控制器回合停止。它不会在同一回合中休眠或轮询。 - 保持活动支持仅是运行时协助。它不是任务逻辑、传输权限或验收证据。 - 需求创建是主机中立的：`wakeflow_create_demand` 编写 `controllerHost: null`，以便 Codex 和 Claude Code 都可以在不获取所有权的情况下创建或导入需求材料。 - 第一个真实驱动命令通过写入 `controllerHost: "codex"` 或 `controllerHost: "claude-code"` 来声明需求为其平台。 - 在一个需求被一个主机拥有后，另一个主机在控制器变异和调度准备上关闭，除非所有权被显式转移到 `--adopt-host`。 - `wakeflow_status` 在 `dualHost.demandOwnership` 下公开需求所有权，以便混合主机控制器在采取行动之前看到哪个平台拥有活动工作。 自动化在最终完成、硬门控、用户停止、没有合格的工作、缺少证据、阻塞状态或任何需要控制器或用户判断的条件时停止。 ## MCP 能力表面 Wakeflow仅将稳定的外部工作流合约作为MCP工具公开。运行时脚本仍然是内部实现和测试表面；它们不是公共工具，仅因为它们存在。一个目标的结案使用与控制器调度相同的直接线程交付模型：准备一个信封，发送带有主机线程工具的提示，然后记录交付运行。 主要工具组： | 需求 | MCP工具 | | --- | --- | | 设置和工作空间发现 | `wakeflow_initialize_workspace` | | 责任窗口替换 | `wakeflow_replace_windows` （通过 `window` 进行单个替换，通过 `windows` 进行多个替换） | | 需求和任务状态 | `wakeflow_status` ， `wakeflow_create_demand` ， `wakeflow_claim_next` ， `wakeflow_add_task` ， `wakeflow_next_work` | | 交付和返回 | `wakeflow_prepare_delivery` ， `wakeflow_record_delivery` | | 结果和审查 | `wakeflow_record_target_result` ， `wakeflow_review_pack` ， `wakeflow_reduce_results` ， `wakeflow_decide_review` ， `wakeflow_complete_demand` | | 设计和测试接收 | `wakeflow_deliver` ， `wakeflow_intake_test_card` | | 存档，维护和验证 | `wakeflow_archive` （目标需求/待办事项/文档）， `wakeflow_prune_runtime` ， `wakeflow_verify` ， `wakeflow_view` （范围跟踪） | 公共MCP工具用于外部代理工作流。目标结案被刻意拆分：记录目标结果，审查准备情况，在策略允许时准备控制器返回信封，通过活动主机传输发送，并记录交付证据。控制器审查保持拆分状态为审查包，结果减少和明确决策；结果减少仅创建审查候选人不构成验收。不要将这些步骤折叠成单个目标窗口MCP工具。内部步骤如存档摘要刷新内部，保持活动状态和脚本后端执行，保持在Wakeflow JS/运行时脚本和技能中。公共存档MCP工具仅包装控制器批准的TODO或工作空间文档存档流程；它们不做出验收决策或发送主机消息。 Wakeflow为每个公共工具声明MCP工具注释：只读工具标记为只读，写入工具为本地，非破坏性和封闭世界。Codex审批策略仍由用户的Codex配置控制。对于受信任的本地Wakeflow安装，匹配的Codex服务器策略为： ```toml [plugins."wakeflow@gxfn".mcp_servers.wakeflow] default_tools_approval_mode = "approve" ``` ## 运行时和账本边界 Wakeflow将源代码，活动运行时和持久记录分开： | 路径 | 边界 | | --- | --- | | `skills/` | 随插件安装的可重用操作指令。 | | `scripts/` | 插件打包的运行时实现和验证脚本。 | | `templates/wakeflow-template-bundle.json` | 捆绑的启动状态，设计/测试和账本骨架在设置期间扩展。 | | `.wakeflow-active/` | 目标工作空间中的当前活动工作；被Git忽略。 | | `.wakeflow-local/` | 机器本地线程注册表，派生的运行时视图和本地状态；被Git忽略。 | | `wakeflow-ledger/` | 项目特定的持久记录，位于可重用的Wakeflow源代码之外。 | 源代码仓库跟踪可重用的Wakeflow功能。产品代码，项目特定的活动状态，实际线程ID和派生的本地运行时工件不属于Wakeflow源代码。 ## 双主机工作空间 一个工作空间可以同时运行Codex和Claude Code Wakeflow版本。共享业务状态保持主机中立： `.wakeflow-active/` ， `wakeflow-ledger/` 和 `.wakeflow-local/wakeflow-delivery/` 下的共享交付主干（ `dispatch-packets/` ， `dispatch-groups/` ， `delivery-envelopes/` ， `delivery-runs/` ， `target-results/` 和共享 `locks/` ）。 主机特定的运行时被每个主机分开： - `.wakeflow-local/wakeflow-delivery/hosts/codex/{thread-registry,window-config,keep-live}/` - `.wakeflow-local/wakeflow-delivery/hosts/claude-code/{thread-registry,window-config,window-host,keep-live}/` `AGENTS.md` （Codex）和 `CLAUDE.md` （Claude Code）可以在工作空间和子目录中共存。每个需求仍然只有一个控制器主机：创建是中立的，第一个驱动命令声明所有权，非拥有主机关闭， `--adopt-host` 是明确的传输机制。 ## 市场发布 Wakeflow被打包为双主机插件源代码仓库。公共源代码是： ```text https://github.com/GxFn/Wakeflow.git ``` 仓库包含单独的主机目录： - `.agents/plugins/marketplace.json` 将Codex插件入口指向 `./plugins/codex-wakeflow` 。 - `.claude-plugin/marketplace.json` 将Claude Code插件入口指向 `./plugins/claude-code-wakeflow` 。 发布Wakeflow意味着标记仓库并提交针对目标主机的正确嵌套工件，而不是开发工作空间根目录。 在发布标签之前： 1. 从此存储库运行 `npm test` 。 2. 在可用时运行特定于主机的插件清单验证器。 3. 确认 `plugins/codex-wakeflow/.codex-plugin/plugin.json` 没有超过三个启动提示。 4. 确认两个主机目录仅指向其嵌套插件工件。 5. 确认运行时脚本和已安装的技能不包含特定的项目控制器名称，产品叠加层，本地路径或私有线程ID。 6. 为主机市场应该安装的精确提交标记。 ## 在此存储库中工作 使用此存储库来开发Wakeflow插件本身。 ```sh npm run sync:core # 将 core/ 复制到两个插件工件中 npm run check:core # 当工件与 core/ 漂移时失败 npm run validate # Codex 工件验证 npm run validate:claude npm run smoke # Codex 工件冒烟测试 npm run smoke:claude npm run test:wakeflow npm test # check:core + 两个验证 + 两个冒烟测试 + 测试 ``` 共享核心规则：主机中立的运行时文件位于 `core/` 并使用 `tools/sync-core.mjs` 同步到两个工件中；在 `core/` 中编辑它们，而不是在工件副本中。主机特定文件（主机配置文件，主机工件检查，主机发送适配器，清单，README，内存文件模板，技能，模板包）仅在每个工件内生存。 `npm run check:core` 保持副本诚实。 完整的双版本架构，代码逻辑，本地文件存储（共享业务状态与主机特定运行时拆分）和状态流在 [docs/wakeflow-dual-edition-architecture-and-state-flow.md](docs/wakeflow-dual-edition-architecture-and-state-flow.md) 中有详细说明。 常见源代码区域： | 路径 | 目的 | | --- | --- | | `core/` | 主机中立的运行时源代码，同步到两个工件中。 | | `tools/sync-core.mjs` | 核心同步和漂移检查（ `--check` ）。 | | `plugins/codex-wakeflow/.codex-plugin/plugin.json` | Codex 插件清单和MCP线路。 | | `plugins/claude-code-wakeflow/.claude-plugin/plugin.json` | Claude Code 插件清单和MCP线路。 | | `plugins/claude-code-wakeflow/scripts/lib/wakeflow-host-profile.mjs` | Claude Code 主机配置文件（tmux 窗口模型，CLAUDE.md，会话词汇）。 | | `plugins/codex-wakeflow/mcp/server.cjs` | 独立MCP服务器入口，没有 `node_modules` 依赖。 | | `plugins/codex-wakeflow/scripts/` | 插件附带的设置，状态，交付，接收，存档，验证和CLI运行时。 | | `plugins/codex-wakeflow/skills/` | 控制器，目标，管理和验证操作手册，插件附带。 | | `plugins/codex-wakeflow/templates/wakeflow-template-bundle.json` | 安装的工作空间启动文档和支持表面，捆绑用于市场扫描大小。 | | `plugins/codex-wakeflow/assets/` | 市场和插件展示资产。 | | `test/` | 仅限开发的回归测试，不在市场扫描表面。 | | `docs/` | 开发规划和架构笔记，不在插件工件中。 | 详细命令参考位于 [scripts/README.md](plugins/codex-wakeflow/scripts/README.md)。顶级README解释了系统模型；脚本README是操作手册。 ## 设计原则 1. **判断保持可见**：脚本输出，状态行和目标回填是证据，而不是验收。 2. **一个需求，一个状态根**：JSON状态和Markdown进度表面保持与同一个需求绑定。 3. **提示唤醒，状态指示**：提示应简洁；任务细节属于状态根，任务包和已安装的技能。 4. **存储库边界很重要**：每个窗口拥有其源代码，测试，提交和证据。 5. **自动化移动工作，而不是权限**：直接线程交付证明发送了提示，而不是结果完成。 6. **本地运行时保持本地**：实际线程ID仅在本地线程注册表中，活动运行时状态从不进入跟踪文档。 7. **默认情况下，新支持窗口**：设计和测试创建为清晰的Wakeflow支持表面，除非用户明确映射现有的支持窗口。 Wakeflow旨在使多窗口代理工作安全恢复，易于检查和难以伪造。