tako 文档 GitHub

74 · 并行任务工作区隔离:责任分工、执行环境与发布恢复

性质:已落地。本稿解决并行 Task 共用项目目录互相覆盖的问题:Task/DAG 保持通用,WorkspaceProvider 按真实项目提供 Git 或目录隔离现场,引擎协调执行、结果验收与发布恢复。 状态:✅ 已落地;2026-11-11 按责任边界重写并方案收口,2026-11-12 施工并活体验收。 施工包:tmp/74-并行任务工作区隔离/施工包.md(施工期材料;用户验收后留档 doc/log/)。 日期:2026-11-11 成文,2026-11-12 落地。 代码落点:internal/runengine/workspace_{provider,engine,git,directory,result,publish,verify,view}.go、agent_task_artifact.go(artifact + retry-publication)、agent_task_{graph,api,tools,scheduler,runner,store,types,attention}.go、worker.go、sandbox.go/bash.go/bashspill.go、store.go/pgstore.go、auth.go(117111–117113)、server.go;前端 web/src/{TasksView.vue,App.vue,api.ts}。验收:scripts/acceptance/workspace_{git,directory,publication,crash}_live.sh(51/42/34/57)、expected.json 用例 57–60、go test ./internal/runengine、既有 70–73 回归与 spotcheck.sh 全绿;接缝明细见 §12。 前置真源:doc/70(通用持久 Task 与 DAG)、doc/71(普通文件短写入)、doc/72(修订、Task HITL 与唤醒)、doc/73(通知与交付恢复)。 后续方案:doc/75(目标可行性、修订或继任组)与 doc/76(项目内容根与资源容器)——两篇 2026-11-13 已落地,与本文合并一个施工包;shared 组同样发布进 content/,发布准入按项目静默判定,受阻后与 isolated 共用同一条 retry-publication 恢复(见 doc/76 §10.5)。 重写说明:旧稿把 Git 字段带进 Task 与 PG 设计,混淆了通用业务对象和执行环境。本稿从责任分工重新推导;旧稿已删除,不作引用或施工依据。

1. 原点:Task 与 Git 没有必然关系

Task 是一件通用持久工作:有输入、执行者、依赖、执行 run、状态、结果和恢复方式。调研、写作、数据处理、文件整理和编码都可以是 Task。

只有同时满足以下条件,一次 Task 的执行环境才涉及 Git:

  1. 目标要求持续修改当前项目,而不是只读分析或单独交付一份文件;
  2. 当前项目已经是 Git 仓库;
  3. 修改需要合并回这个项目;
  4. LLM 为并行执行请求了隔离工作区,WorkspaceProvider 因而选择 Git 实现。

在 Git 仓库里做只读审查不需要 worktree;修改非 Git 目录不需要 Git;生成独立报告也不需要分支。Git 是可选的执行环境实现,不是 Task 类型,也不是编排协议的一部分。

本方案真正要解决的问题是:多个 Task 并行修改同一项目时,怎样让执行者各有工作现场、让下游得到确定输入、让最终结果安全回到项目,并在故障后恢复。

2. 一个具体失败故事

用户提出:

A 整理调研材料,B 制作数据表,C 合并成最终报告

当前所有 Task 共用项目目录。A 用 bash 运行生成器,B 同时保存同名汇总文件;文件工具里的逐路径锁管不到 bash 内部的每次写入。C 最后看到的是两份执行者都没有完整验证过的混合目录。

把整场 run 都锁住会让小时级任务互相排队;给 Task 增加 Git 字段又会在非 Git 目录里失效。因此需要从“谁来决定、谁来创建、谁来验证、谁来发布”重新设计,而不是先选 Git 表结构。

3. 责任分工:先钉死谁不做什么

角色 负责 明确不负责
LLM/mAgent 拆解目标;决定 A/B/C、依赖与并行关系;表达需要共享还是隔离工作区;给出通用验证要求;处理执行中的语义冲突 不决定宿主路径、数据库列或 Git 引用名;不直接证明创建、验证或发布已经成功
Task/DAG 模型 保存目标、内容、执行者、依赖、状态、结果摘要和结果版本 不知道 branch、commit、worktree、repo path 或文件哈希
WorkspaceProvider 根据项目真实形态实现隔离工作区;准备基线与 Task 目录;生成对应 prompt 补充;保存不可变结果;实现合并、读取、发布与清理 不决定 DAG,不改变 Task 业务状态,不绕过 run 权限
运行引擎 调度与领取 run;调用 Provider;校验当前 run/epoch;执行通用结果验收;协调项目准入与发布;驱动恢复、事件和交付 不把 Provider 的内部字段复制进 PG,不用 prompt 代替程序检查
system prompt 补充 告诉执行者当前工作区怎样使用、何时提交结果、如何运行验证和处理冲突 不是安全边界,不是执行事实,不是恢复记录
PG 保存通用业务状态、当前执行者、结果版本、发布状态与执行代次 不保存 Git 分支、commit、仓库路径或目录文件哈希
共享持久卷 保存工作区、Provider 状态、不可变结果和发布恢复记录 不参与 DAG 裁决,不取代 PG 的多副本执行协调

一句话操作版:LLM 决定“要什么工作区”,Provider 决定“怎样实现”,引擎决定“现在谁能执行和发布”,prompt 只告诉模型“怎么配合”。

4. 通用调用契约:只表达工作区需求

创建单件 Task 或编排组时,LLM 只增加通用、可选的工作区意图:

{
  "workspaceMode": "isolated",
  "verifyCommand": "npm test"
}

Provider 在创建或第一次执行前检查真实项目:

已有 Git 仓库 + isolated + 需要发布回项目 → GitWorkspaceProvider
非 Git 目录 + isolated + 需要发布回项目 → DirectoryWorkspaceProvider
shared → 按同一套 Provider 选择准备 `work/shared`(doc/76 §4:shared 与 isolated 都先 PrepareGroup 再 PrepareTask,区别只在现场是整组共用还是每 Task 独立)

不自动 git init,不要求非 Git 任务先变成 Git 项目,也不根据模型猜测伪造项目类型。

5. WorkspaceProvider 的真实职责

Provider 不是一段提示词,也不是一张数据库表。它是引擎调用的一组文件与版本操作,输入是组、Task 和现有结果版本,输出是可执行工作现场或可读取结果。

操作 输入 → 输出 不完成会怎样
准备编排组 原项目与编排组 ID(orchestrationId)→ 编排组基线、Provider 状态目录 没有共同起点,无法判断发布时是否覆盖新工作
准备 Task 组基线、父 Task 的结果版本 → 当前 Task 的工作目录与 prompt 补充 执行者没有独立现场,或下游拿不到父结果
接受结果 当前 work、Task ID、resultRevision → 不可变结果引用与产物入口 模型说完成但结果可能继续变化,恢复时找不到
读取结果 Task ID + resultRevision + 产物路径 → 该版本的文件字节 主项目同路径文件可能不是当时结果
发布结果 最终不可变结果 → 原项目已更新,或明确受阻原因 结果只停留在内部工作区,用户项目得不到它
恢复与清理 组目录、实际文件/版本状态 → 可继续现场或安全清理 崩溃后只能靠重做,清理可能删掉唯一工作

Provider 的状态写在共享持久卷。PG 不保存 Provider 的内部版本标识;需要展示或恢复时,引擎通过 Provider 现读。

6. 共享持久卷上的组目录

所有实现共用下面的逻辑布局;路径由组与 Task ID 推导,不由模型传入:

<tenant>/.tako/orchestrations/<orchestrationId>/workspace/
  state.json                 # 通用 Provider 类型、格式版本、生命周期状态
  provider/                  # Provider 自己的基线与内部状态
  work/<taskId>/             # 当前 Task 的工作目录
  results/<taskId>/<resultRevision>/
    result.json              # 不可变结果描述与 Provider 引用
    artifacts/...            # 需要独立保存的产物
  publication/               # 每次发布的恢复记录

state.json 可以记录 Provider 类型和少量启动配置。Provider 自己的 Git 引用或目录清单放在 provider/ 与 results/,不复制进 PG。

状态文件的每次修改使用现有短临界区:按组协调、锁内重读、同目录临时文件、原子 rename。多副本下可以使用 PG advisory lock 协调这次文件修改,但锁在 PG 不等于 Git 数据进 PG。

7. 端到端主链

用户提出目标
→ LLM 创建 A/B/C、依赖边、workspaceMode 与通用 verifyCommand
→ PG 保存通用组、Task、依赖与配置
→ 引擎按依赖和容量领取 A/B
→ 引擎调用 WorkspaceProvider 准备组基线与 A/B 的工作目录
→ Provider 返回目录与 prompt 补充
→ A/B 各自执行,调用 submit_task_result
→ 引擎校验当前 run/epoch、通用结果格式与验证命令
→ Provider 把结果保存成不可变版本
→ run complete 后 A/B succeeded

→ C 具备执行资格
→ Provider 按父 Task ID + resultRevision 读取 A/B 的不可变结果
→ Provider 把这些结果带进 C 的工作目录,并标出交接冲突
→ C 在自己的目录中解决冲突、完成工作、提交结果
→ 最终结果经验证并持久保存

→ 引擎取得项目发布准入,调用 Provider 发布最终结果
→ 发布成功且最终 run complete,最终 Task 与组才 succeeded
→ 现有协调通知回到来源会话
→ doc/73 的交付 run 展示摘要和不可变产物
→ 通知 consumed,组 delivered

每一步的输出是下一步输入:不可变父结果是 C 的输入;已验证的最终结果是发布输入;发布事实与 run 终态是组收口输入;组收口事实才是交付通知输入。

8. GitWorkspaceProvider:只在合适时出现

8.1 创建与隔离

Git Provider 使用:

原始项目仓库
  └── 本组中间 bare clone
        ├── 每 Task 一个 linked worktree
        └── 每 Task 一个内部分支

这些是 Provider 的文件与 Git 操作,不进入 Task 业务模型。

8.2 结果与父结果交接

执行者通过 prompt 补充得知“完成工作后提交修改”。但结果是否可接受由程序检查:

通过后,Provider 用当前 resultRevision 写结果引用:

refs/tako/results/<taskId>/<resultRevision> → 已验证提交

该引用先保存在本组中间仓库,再由引擎控制的 Provider 导出到原始仓库的内部引用。原始主分支与工作树此时不变。PG 只存已有的 resultRevision,不存 commit;API 和下游通过引用现读 commit。

C 准备时,Provider 按 PG 中已有的父 Task ID 与结果版本解析这些引用,合并对应提交。父 worktree 是否还在不影响读取。

8.3 发布

发布前由引擎排除项目内其他活 run 并设置通用发布标记,Provider 再检查原始仓库:

这里 LLM 决定是否合并与怎样解决语义冲突;Provider 执行 Git 操作;引擎决定何时允许发布。prompt 本身不证明任何一步成功。

9. DirectoryWorkspaceProvider:非 Git 也有完整链

9.1 基线与 Task 工作目录

Directory Provider 不初始化 Git。准备组时:

  1. 遍历允许进入工作区的普通文件,排除引擎运行时目录、特殊文件与越界软链;
  2. 把基线文件保存到组级 Provider 目录;
  3. 写基线清单:每个相对路径对应内容哈希、文件类型与权限;
  4. 为每个 Task 从该基线复制独立工作目录。

目录与结果都计入租户存储配额。没有 Git 不代表可以忽略存储、路径与权限边界。

9.2 结果清单与父子交接

接受结果时,Provider 比较 Task 工作目录与组基线,生成:

{
  "added": [{"path": "report/final.md", "sha256": "…"}],
  "modified": [{"path": "data/summary.csv", "sha256": "…"}],
  "deleted": [{"path": "draft/old.md"}]
}

清单与结果文件一起保存进 results/<taskId>/<resultRevision>/。PG 仍只保存结果版本,不保存这些文件哈希。

子任务准备时按父 Task key 的固定顺序应用结果:

9.3 发布与恢复记录

发布时逐路径比较原项目当前内容与组基线:

新增与修改使用同目录临时文件 + 原子替换;删除先在发布恢复记录中登记。每个路径的实际完成状态都写入恢复记录,进程崩溃后据此对账。

**Directory 只保证单文件原子替换,不宣称多文件发布是一次原子事务。**发生中途失败时,页面展示已完成与未完成的实际状态,由恢复流程继续;不能把“部分发布”标成完整成功。

10. 通用结果、发布与恢复契约

10.1 PG 只保存通用事实

现有表继续使用;若需要新增字段,只允许与 Provider 无关的配置和状态:

agent_orchestrations:
  workspace_mode           -- shared / isolated
  verify_command           -- 通用验证配置,可为空
  publication_status       -- 空 / pending / publishing / blocked / published
  publication_error_code   -- 通用机器原因
  publication_epoch        -- 当前发布代次

workspaces:
  publication_orchestration_id
  publication_epoch        -- 与当前发布者配对,防旧发布者清理新标记

不新增 agent_task_git,不新增 base_commit、result_commit、repo_path、worktree_path、publication_commit 等字段。

Task 结果仍保存摘要、产物引用、通用 metadata、resultRevision、resultRunID 与 resultEpoch。Provider 引用和文件清单在结果目录中,不进 Task JSON。

10.2 通用结果验收顺序

确认 Task running
→ 确认 submit 来自当前 run 与当前 epoch
→ 校验摘要、产物数量与通用路径规则
→ Provider 校验自己的工作现场并形成不可变结果
→ 若配置 verifyCommand,在沙箱中实际执行
→ Provider 固化结果与产物
→ PG 保存 resultRevision 与通用结果
→ 发 Task 变更事件

Provider 固化失败或 PG 保存失败都不能返回成功。崩溃发生在两者之间时,恢复按 Task ID + run + epoch + resultRevision 检查已有结果,不制造另一份结果版本。

10.3 发布受阻与人工恢复

通用发布原因只有业务可处理的几类:

最终 run 仍在场时,执行者收到工具回执并继续处理。最终 run 已结束时,Task 进入 blocked,左侧“需要我处理”出现发布项;用户点击“重新发布”后,引擎为同一最终 Task 创建新处理 run,Provider 从不可变最终结果恢复工作现场。父 Task 与整张 DAG 不重跑。

10.4 发布后与交付失败

发布成功后如果最终 run error:

11. API、prompt、页面与事件

11.1 API

现有创建接口只增加 §4 的两个通用字段(workspaceMode、verifyCommand)。shared 详情字节不变(18 键,不带 workspace);isolated 详情在末尾追加第 19 键 workspace,组体(GET /api/orchestrations/:id)同形。键序固定 mode → provider → verification → publication。

刚创建、Provider 尚未准备工作现场时(provider="pending",验证已配置但未跑):

{
  "workspace": {
    "mode": "isolated",
    "provider": "pending",
    "verification": {"configured": true, "status": ""},
    "publication": {"status": "", "errorCode": "", "epoch": 0}
  }
}

Directory Provider 执行并验证后(configured=false 表示未配 verifyCommand,空验证平凡通过,仍写证据文件):

{
  "workspace": {
    "mode": "isolated",
    "provider": "directory",
    "verification": {"configured": false, "status": "passed", "exitCode": 0, "outputPath": "verification/<taskId>.out"},
    "publication": {"status": "", "errorCode": "", "epoch": 0}
  }
}

字段词表(实测字节,机器真源 scripts/acceptance/expected.json 用例 57/58):

Provider 自己的版本详情(分支、commit、worktree 路径、目录哈希)通过独立诊断读取,不进入 Task 结果模型,也不落 PG 的 Task/组表。

新增统一结果产物入口:

GET /api/tasks/:id/artifact?path=<结果中声明的相对路径>

按 Task 当前 resultRevision 调用 Provider 读取不可变结果,成功回原始字节逐字(不进信封),不读主项目里的同路径文件。项目当前文件仍走现有 GET /api/media。错误:产物缺失/不在清单/越界 409 117110、未知任务 404 117001、未登录 401 111102、跨租户 404 117001。shared 与 isolated 都有不可变结果,读口同一条(doc/76 §4 取代了本条的“shared 400 111002”)。

新增人工恢复:

POST /api/tasks/:id/retry-publication

只接受最终 Task 的发布受阻状态,创建同 Task 的新处理 run。成功 202,data 键序 taskId → runId → status → publicationEpoch(status="running",publicationEpoch=当前+1);已有活 run 时 200 幂等命中同形。双击、多标签页与多副本同时请求只能成功一次。错误:租户容量满 429 113001、结果缺失 409 117110、非 blocked/非最终 409 117112、未知 404 117001、viewer 403 111203、跨租户 404 117001。shared 受阻后同样可重新发布(doc/76 §10.5 第 3 条)。

以上字节已对运行中的引擎 curl 验收,钉在 expected.json 用例 57(创建与读面)/58(artifact)/59(retry-publication)。

11.2 prompt 补充

Provider 只返回当前执行者需要的行为约定。例如 Git worktree 中提示提交修改,Directory 中提示不要写当前目录之外,配置了验证命令时提示执行检查。

prompt 不承担路径准入、结果校验、发布条件或恢复裁决。模型忽略 prompt 时,程序检查仍必须拒绝不合格结果。

11.3 页面与事件

12. 代码落点与施工顺序

已落地。通用 Task 侧的接缝(全部在 internal/runengine/):

位置 实际落点
agent_task_graph.go 通用 workspaceMode/verifyCommand 创建输入与幂等计划 hash(省略 = shared,旧字节不变)
agent_task_api.go / agent_task_tools.go 通用创建输入、详情读面(workspace 摘要由 workspace_view.go 现读拼装)
agent_task_artifact.go(新增) GET /api/tasks/:id/artifact 与 POST /api/tasks/:id/retry-publication 两个端点
agent_task_scheduler.go / agent_task_runner.go 调度仍归引擎;领取/恢复前经 workspace_engine.go 调 Provider 准备工作现场;submit_task_result 经 wrapToolErrors 入池
agent_task_store.go / agent_task_types.go 通用结果版本、当前 run/epoch、发布状态列与枚举(pending/publishing/blocked/published)
agent_task_attention.go 通用 publication_blocked 处理项(不出现 Git 专属业务状态)
worker.go 将 Provider 返回的工作目录装入 WorkspaceRef;WorkspaceID 保持原项目
sandbox.go / bash.go / bashspill.go 按 Provider 声明开放工作目录与执行环境路径,不开放原始仓库管理目录;验证命令复用同一 bash 沙箱
store.go / pgstore.go 通用项目发布准入、发布代次(publicationEpoch)与删除保护
web/src/{TasksView.vue,App.vue,api.ts} 通用工作区、验证、发布受阻面板、不可变产物与「项目当前文件」入口
scripts/acceptance/workspace_{git,directory,publication,crash}_live.sh(新增) Git/Directory/发布协调/崩溃四场活体

Provider 分层(新增文件,逻辑边界与方案一致;shared 行为留在既有引擎,未单拆 workspace_shared.go):

internal/runengine/workspace_provider.go    # Provider 接口、GroupHandle、CleanupReport
internal/runengine/workspace_engine.go      # 引擎装配层:Store→组句柄/配额,领取/恢复时准备工作现场
internal/runengine/workspace_git.go         # GitWorkspaceProvider(中间 bare 仓 + linked worktree)
internal/runengine/workspace_directory.go   # DirectoryWorkspaceProvider(基线冻结 + 变更集)
internal/runengine/workspace_result.go      # 不可变结果固化(staging→原子 rename)与读取
internal/runengine/workspace_publish.go     # 发布准入、Provider 发布、收尾对账、过窗清理(Cleanup 在此调用)
internal/runengine/workspace_verify.go      # 通用验证命令执行口(现有 bash 沙箱,10 分钟超时)
internal/runengine/workspace_view.go        # 详情/列表的 workspace 摘要读面(PG 通用列 + 现读 state.json)

Provider 内部状态(branch/commit/repo path/worktree path/目录哈希)只落在共享卷的组目录与 Provider 自己的持久记录,不反向渗入 Task 表与调度事务。过窗清理由 workspace_publish.go 的发布对账慢路径按组生命周期调 Provider.Cleanup,未改 archive_sweep.go;scope.go/subprocesspath.go 未改(工作目录开放走 sandbox.go)。

施工按以下顺序完成(施工包 = tmp/74-并行任务工作区隔离/施工包.md,已点头):

  1. 用真实端点钉死通用创建、详情、产物与恢复契约;
  2. 完成 shared 不变、组目录、不可变结果和通用发布状态;
  3. 分别实现 Git 与 Directory Provider 的准备、交接、验证、发布和恢复;
  4. 接通引擎调度、沙箱、权限、事件与前端;
  5. 完成双副本、kill -9、项目变化、发布受阻、清理与既有回归,主 Agent 审查实际 diff。

13. 验收与完成线

13.1 责任边界测试

  1. 同一通用 Task/DAG 创建请求可用于 Git 与非 Git 项目,Task JSON 与 PG 不出现 Git 字段。
  2. LLM 决定节点、依赖和 workspaceMode;Provider 决定实现;引擎决定执行与发布资格。
  3. 删除或改变 prompt 补充不会绕过工作区检查、结果验收与发布条件。
  4. PG 中没有 branch、commit、repo path、worktree path 或目录哈希;这些都能从 Provider 与共享持久卷恢复。
  5. shared 模式同样有组工作现场 work/shared 与不可变结果,经发布链进 content/(doc/76 §4 改写了本条的“不创建组目录”)。

13.2 Git 活体

  1. 已有 Git 项目中 A/B 并行修改,C 合并两者的确定结果,原始项目在最终结果验证前不变。
  2. 父合并冲突只出现在 C 的 worktree;解决并验证后发布。
  3. 未提交结果、缺父提交、验证失败均不接受;结果引用可按 resultRevision 读取。
  4. 原始主分支前进时不覆盖;合并新基线并重新验证后发布成功。
  5. 中间仓库损坏后,已接受结果能从原始仓库内部引用恢复。
  6. 原始仓库与其他组目录始终不在执行者读写范围内。

13.3 Directory 活体

  1. 非 Git 目录中 A/B 修改不同文件,C 得到两份结果;同路径不同内容形成可见冲突并由 C 解决。
  2. 新增、修改、删除清单与真实字节一致;结果目录在 work 清理后仍可读。
  3. 原项目文件在基线后发生变化时拒绝覆盖;处理后可重新发布。
  4. 多文件发布中途 kill -9:恢复记录能区分已写与未写,不把部分发布标成成功。
  5. 未跟踪文件、软链越界、特殊文件、配额不足和跨租户访问均按边界拒绝。

13.4 通用故障与回归

完成不是“支持 Git”,而是:通用 Task 不需知道执行环境;LLM 能选择隔离意图;Git 与非 Git 都有准备、执行、交接、验证、发布和恢复闭环;共享模式不受影响。

14. 参照证据与取舍

15. 开工前需要点头的责任裁决

决策 本稿结论
Task 是否认识 Git 否;Task 与 DAG 永远通用
谁决定拆任务与隔离需求 LLM
谁选择 Git 或 Directory WorkspaceProvider 根据真实项目与通用隔离请求选择
谁实际创建工作区 引擎调用 Provider 执行,不是 prompt 自己完成
Git 状态是否进 PG 否;Git 引用与 Provider 文件承担
PG 还管什么 通用 Task、run、结果版本、执行代次、发布状态与项目准入
prompt 管什么 只指导模型配合,不提供安全、完成或恢复保证
非 Git 怎么办 DirectoryProvider 完整支持,不自动 git init
同组 Git 隔离边界 原始仓库硬隔离;同组共享中间仓库元数据,是合作写者
多文件目录发布 单文件原子替换 + 发布恢复记录,不宣称整体原子
默认行为 shared,现有 Task 与普通聊天不变

这些责任裁决随方案与施工包一起交审;用户点头前不改代码、不建施工脚手架。

16. 所以这解决了什么

本稿把问题从“Task 怎样保存 Git 信息”纠正为“并行 Task 怎样获得合适的执行环境”。

LLM 负责规划,Task 模型保持通用,Provider 负责工作区实现,引擎负责执行与发布协调,prompt 负责行为指导,PG 只保存业务事实,共享持久卷保存工作现场与不可变结果。这样 Git 不会污染通用业务模型,非 Git 任务也不会被落下,同时并行写入、结果交接、发布冲突与崩溃恢复都仍有明确负责人。