taskflow 0.3 文档

面向 coding-agent 工作流的 Trusted Effects：声明 effect，验证类型化路径，让已准入的文件修改经过唯一 resource authority。

0.3.0-beta.1.2——beta channel candidate，尚未 GA。 这个页面描述为 beta 发布准备的 Trusted Effects MVP；0.3-C Control Plane 仍是后续 candidate 轨道。

taskflow 是面向 coding-agent 工作流的声明式运行时。它把任务图变成可验证的执行合同，让阶段隔离运行，并把中间 transcript 留在宿主对话之外。0.3 candidate 增加了 Trusted Effects：为已准入的文件 effect 提供类型化声明与受 resources 控制的提交路径。

先选择正确路径

Trusted Effects 总览

理解 effects[]、PathRef、labels、resource transaction 与 why-* evidence，同时看清 resolve-only 执行的边界。

运行无 LLM fixture

不连接 live model，执行仓库内的文件写入 vertical slice。

运行普通 flow

安装宿主，运行带 agent 阶段、gate、审批与 resume 的声明式 DAG。

理解 0.2 基础

TypeScript 编写、FlowIR、trace、replay、后台运行与增量重算。

Trusted Effects 不是 OS sandbox。0.3 MVP 通过 resources 路径保护已准入的已声明文件目标。在 resolve-only 执行下，未声明路径的写入仍取决于宿主策略；这一版没有 SecretRef 的 live vault 后端或 ServiceRef 的网络后端。

0.3 合同

声明。 给 phase 附加封闭的 effects[] 列表。每个 effect 写明 kind、类型化 target、purpose，以及可选的 confidentiality/integrity labels。

验证并准入。 校验 EffectIR，解析 PathRef，检查 information-flow labels 与 mutating-path 重叠，再把声明目标绑定到 resource intent。

Stage 并提交。 Resources 层负责 snapshot、lease、journal、stage 与原子提交；事务无法完成时就 restore and reject。

解释。 通过 taskflow_why_effect 或 core why-* API 查看结构化、ledger-backed 原因。声明本身永远不被当作授权。

在你的宿主上使用

0.3 beta 可从 npm 的 beta channel 安装，也可从仓库源码运行。若未显式选择 beta，稳定宿主指南仍使用已发布的 0.2.x package pin。

所有 taskflow package 都要求 Node.js 22.19.0 或更高版本。Candidate 的源码与 fixture 检查使用仓库内的 pnpm。

Pi

原生扩展、/tf 命令、运行视图与交互式审批。

Codex

Plugin 与 stdio MCP 交付。

Claude Code

Plugin 与 stdio MCP 交付。

OpenCode

MCP 配置与生成的 skill。

Grok Build

带显式宿主 profile 的 MCP 配置。

Hermes Agent

带显式子代理 toolset 与隔离策略的 MCP 交付。

理解基础层

核心概念

DAG、阶段类型、插值、验证、隔离与续跑。

语法参考

Flow 字段、控制流、预算、缓存与审批。

编译器与运行时

JSON、TypeScript DSL、FlowIR、trace、replay 与 recompute。

命令与 MCP 工具

宿主命令与当前 20 个 MCP 工具，包括 taskflow_why_effect。

发布边界

当前 0.3 有两条相关轨道：

Trusted Effects MVP： 面向发布的产品定义。覆盖 EffectIR、类型化 ref、labels、受 resources 控制的文件 transaction、重叠准入、诚实的宿主基线与 ledger-backed why-* explainers。
0.3-C Control Plane： 后续实现轨道；当前代码是 ControlHost / 拟议合同的脚手架。项目 store、协调、审批、receipts 与 evidence UI 属于后续阶段，不是 0.3 MVP 的 GA 定义，WebUI 也尚未在当前 candidate 交付。

规范范围请读仓库中的 MVP 冻结定义与 0.3-C 计划。