智能体工作流编排 toustifer/agentflow

agentflow

AI Agent 团队的软件项目生命周期编排引擎

面向 AI agent 团队的本地生命周期编排器

中文 ·

中文概览

agentflow 是一个本地优先、MCP 原生、感知 git/worktree 的 AI agent 项目生命周期编排引擎。

它把项目初始化、任务拆解、分支执行、review handoff 和项目记忆串成一条真实工作流：
- project_init 把本地代码仓库绑定到 namespace
- DAG 表达 branch-scoped 工作流，task 表达可依赖、可审查、可恢复的工作单元
- leader / worker / reviewer 三个角色按默认 behavior tree 推进主链
- docs / handbooks / diaries 持久化项目知识与交付记录

运行形态：
- Go MCP server：系统事实源、状态机、工具注册、SQLite 持久化
- Python BT sidecar：leader / worker / reviewer 默认行为树执行层
- Git + worktree：每个 DAG 绑定分支、每个 task 绑定 worktree

核心模型

| 概念 | 含义 |
| namespace | 一个项目的隔离边界 |
| DAG | 一条 branch-scoped 的工作流，通常对应一个功能分支 |
| task | 一个有状态、有依赖、有审查流转的工作单元 |
| worker | 执行任务的角色，跨 DAG 共享 |
| reviewer | 读取提交元数据并做 pass / rework 决策的角色 |
| leader | 负责 phase 判断、派发、监控、阻塞汇报、完成收口 |

除了任务状态，agentflow 还内建项目记忆面：
- doc_：项目文档
- worker_handbook_ / find_knowledge / find_pitfalls：Worker 经验库
- worker_diary_：Worker 工作日记
- leader_diary_：Leader 项目日记

生命周期总览

项目不是直接从“建 task”开始，而是按 phase 推进：

setup -> shape -> plan -> execute -> stuck -> done

| Phase | 含义 |
| setup | 还没有完成项目初始化 |
| shape | 正在确认最终形态、范围和角色分工 |
| plan | 已有 worker / namespace，但还没拆出 DAG / task |
| execute | 已有任务主链，正在 dispatch / 实现 / review |
| stuck | 当前没有可派发任务，也没有活跃任务，需要人工处理阻塞 |
| done | 当前 DAG / 项目任务已完成 |

高层入口：
- project_next_steps：看项目当前在哪个 phase、下一步该做什么
- leader_tick：让 leader 默认 BT 按 phase 做一次调度
- lifecycle_tick：在一条调用里串 leader -> worker -> reviewer 的完整主链

执行模型：Git / Branch / Worktree

这是当前系统最重要的运行约束之一。

1. project_init 是推荐入口

project_init 会：
- 创建或绑定 namespace
- 校验 / 初始化 git 仓库
- 设置主分支信息
- 记录 workdir / worktree root
- 写入 .claude/agentflow-git.md

.claude/agentflow-git.md 是 repo-local 的执行规则文件，约束 worker 如何在 worktree 中工作、如何提交、哪些动作被禁止。

2. 一 DAG 一分支

每个 DAG 绑定一个 feature branch。DAG 不是纯逻辑分组，而是和 git 分支直接关联的执行单元。

3. 一 task 一 worktree

task 在自己的 worktree 中执行，而不是直接在 repo root 改文件。

典型约束：
- worker 只修改自己的 worktree_path
- task 的 git branch 必须和 DAG branch 一致
- start / resume 会准备 task 的 git runtime
- git_status / worktree_get 用来检查当前 git/worktree 状态

4. submit 是带交付契约的

submit 不只是一次状态转换。对 git-backed task，提交前需要满足：
- clean worktree
- 已有 worker diary
- 能记录 review.commit
- 能记录 review.diff

reviewer 围绕这些 review metadata 做 pass / rework，而不是脱离 git 上下文推进状态。

默认 Behavior Tree 角色流

Leader

trees/leader-default.json 的主线语义：

refresh_phase
-> setup_actions | shape_actions | plan_actions
-> execute: dispatch_task | monitor_tasks
-> stuck: report_stuck
-> done: report_done

leader 负责判断项目处于哪个 phase，并按 phase 决定下一步动作。

Worker

trees/worker-default.json 的默认链路：

doc_search_prepare
-> task_get_confirm
-> enter_worktree
-> implement_code
-> git_commit_changes
-> doc_write_record
-> diary_write_entry
-> task_submit_for_review

这条链路明确表达：worker 的交付不是“改完代码就算结束”，而是要连同 commit、文档、日记和 review handoff 一起完成。

Reviewer

trees/reviewer-default.json 的默认链路：

fetch_work_diff
-> review_decide
-> task_review_pass | task_review_rework

reviewer 基于 review.commit / review.diff 决策，而不是脱离 git 上下文做抽象状态推进。

MCP 能力面

README 不再硬编码工具数量；当前工具面请以 pkg/server/mcp.go 为准。

更适合按能力域理解：

Bootstrap / Project Setup
- project_init
- project_next_steps
- namespace_create
- namespace_get
- namespace_list
- namespace_delete

DAG / Task / Worker State
- dag_create, dag_get, dag_list, dag_update, dag_report, dag_flowchart
- task_create, task_get, task_list, task_query, task_history, task_create_batch, task_transition
- worker_register, worker_get, worker_list, worker_update, worker_status, worker_prompt_get

Lifecycle / Behavior Trees
- leader_tick
- lifecycle_tick
- bt_list_trees
- bt_show_tree
- bt_validate_tree
- bt_tick

Git / Worktree / Review Handoff
- git_status
- worktree_get
- task metadata 中的 git.
- review.commit / review.diff

Docs / Handbooks / Diaries
- doc_write, doc_get, doc_list, doc_search, doc_delete
- worker_handbook_write, worker_handbook_get, worker_handbook_list
- find_knowledge, find_pitfalls
- worker_diary_write, worker_diary_get, worker_diary_list
- leader_diary_write, leader_diary_get, leader_diary_list

Reporting / Project Queries
- project_next_tasks
- project_blockers
- project_report
- flow_ping

agentflow ↔ agent-hub：单向投影、soft-fail、默认关闭

agentflow 可以把任务与分支状态单向投影到 agent-hub 控制平面，让多机团队看到同一张任务大盘。三条铁律：

1. 单向 L→H：只从 agentflow 推送到 Hub，从不把 Hub 状态读回本地。agentflow 的 SQLite 永远是唯一真源。
2. soft-fail：Hub 的任何故障（连接拒绝 / 超时 / 401 / 500）都不会让 MCP 工具调用失败，也不会回滚本地状态。发生了什么只体现在返回值里的一个 note 字符串。
3. 默认关闭：没有绑定 team code 或没有凭据 ⇒ 直接跳过，零出网请求。不配置就不会有“用户不知情就被上报”。

接线了哪些时机

| 工具 | 投影内容 | 回填的 note 键 |
| task_create | 任务行 8 字段 | hub_note |
| task_prepare_start | 任务行（带 branch/head_sha）+ 分支上报（bind_type=task） | hub_note + hub_branch_note |
| task_transition | 任务行；submit 起带 reviewer 将看到的 review.commit | hub_note |
| task_create_batch | 每个任务各一条 | 每个 item 的 hub_note |

note 形如：

hub_task_sync_ok
hub_task_sync_skipped: no login token / business_code ← 没配置，什么都没发 hub_task_sync_disabled: HUB_SYNC/HUB_ENABLED off ← 被 kill switch 关掉 hub_task_sync_failed: status 401 forbidden ← 试过了，失败了；本地不受影响

怎么打开

// 1) 登录取 JWT（两段式设备码；JWT 落 ~/.agent-hub/config.json） // hub_login({}) // → code + verification_url // 浏览器打开 verification_url 并点 Approve // hub_login({ "code": "" }) // → status=pending_approval 就再调一次；ok 即落盘 // hub_list_teams({}) // → 发现你的 4 位 code（需 JWT；只有 API key 会 skipped）

// 2) 绑定团队（唯一产品真源：namespace metadata） // hub_bind_team({ "namespace_id": "insighttutor", "business_code": "z8gw" })

// 3) 提供凭据（env 优先；也可放 {workdir}/.mycompany/hub-client.json） // HUB_TOKEN= # 推荐；只有 API key 时部分能力不可用 // HUB_BASE_URL=https://hub.stifer.xyz

关闭方式（任一）：HUB_DISABLED=1、HUB_SYNC=0、HUB_ENABLED=false。kill switch 永远优先于凭据。

边界（照代码写实）

- ~/.agent-hub/config.json 是 JWT-only：它永远不提供 team code（否则同机两个 namespace 会争抢同一个团队）。team code 只可能来自 env / namespace metadata / workdir 文件。
- MCP 工具表里有四个 Hub 工具：hub_login（两段式设备码登录）、hub_list_teams（发现团队 code，需 JWT）、hub_status、hub_bind_team。登录成功后 JWT 落 ~/.agent-hub/config.json，且不会发明 team code。
- 没有重试队列、没有离线补发、没有顺序保证，也没有 H→L 对账。
- 完整字段白名单见 docs/SYNC_CONTRACT.md，逐面完成度矩阵见 docs/HUB_ALIGNMENT.md。

安装与快速开始 (Installation & Quick Start)

agentflow 提供多种宿主集成方案，推荐优先使用 DeepSeek Harness (DSH) 原生插件体验完整的多 Agent 协同与 4D 动态画布能力；同时也支持作为独立 MCP 服务接入 Claude Code、Codex 等终端工具，或连接 Agent Hub 进行多机分布式团队协同。

推荐方式一：DeepSeek Harness (DSH) 原生插件安装（首推）

通过 DSH 插件体系可实现核心状态机、技能与交互式拓扑画布的开箱即用：

1. 社区市场安装 (1024Store / dshfind)：
- 打开 DSH 插件市场 / 社区合作提供方（如 dshfind），搜索 @stifer/dsh-agentflow，点击一键安装；
2. CLI 命令行快速安装：
dsh plugin --profile web add @stifer/dsh-agentflow

3. 配置启用（在 /profiles/web/cordis.patch.yml 中追加）：
- insert:
- id: agentflow
name: '@stifer/dsh-agentflow'

4. 验证与体验：
- 启动 DSH 后在会话中输入 /agentflow 即可唤起引导；
- 自动挂载 mcp__agentflow__ (61+ 工具)；
- 原生集成 Live-Spec 4D 动态可视化拓扑画布（自动适配半宽与全宽视口），实时推演任务依赖与流转。

方式二：Claude Code / Codex 独立安装

适用于基于独立二进制或 CLI 终端的代码协作环境：

1. 一键安装脚本（自动下载二进制与技能包）：
- Windows (PowerShell)： irm https://raw.githubusercontent.com/toustifer/agentflow/master/scripts/install.ps1 | iex

- Linux / macOS (Bash)：
curl -fsSL https://raw.githubusercontent.com/toustifer/agentflow/master/scripts/install.sh | bash

2. 源码构建（可选）：
go build -o agentflow ./cmd/agentflow/

3. 手动配置 stdio 模式：
- Claude Code (.claude.json)： {
"mcpServers": {
"agentflow": {
"command": "agentflow",
"args": ["stdio"],
"type": "stdio"
}
}
}

- Codex (codex.json)： {
"mcpServers": {
"agentflow": {
"command": "agentflow",
"args": ["stdio"]
}
}
}

方式三：结合 Agent Hub 多机多用户协同

搭配 hub.stifer.xyz 控制平面，解锁跨机器、跨座席的多智能体团队协同能力：

- hub_login()：OAuth 浏览器一键授权，快速获取协同凭证；
- hub_bind_team(namespace_id, business_code)：将本地工作区 namespace 绑定至团队专属 4 位业务码；
- 核心协同特性：
- 分支占用防撞车：分布式租约与锁定机制，避免多端并行开发分支冲突；
- 全局任务大盘投影：实时向 Web 控制台软同步任务 DAG 状态与执行拓扑；
- 跨机 Playbook 避坑库共享：多 Agent 跨会话沉淀与检索团队避坑知识库。

项目快速启动 (Bootstrap a real project)

无论采用哪种安装方式，推荐的标准项目启动生命周期流（Happy Path）：

1. project_init：绑定代码仓库与 namespace
2. worker_register：登记参与团队的 Worker 角色
3. dag_create：基于需求分支创建 DAG 工作流
4. task_create / task_create_batch：拆解创建带依赖的任务
5. project_next_steps：评估阶段并获取行动建议
6. leader_tick：启动 Leader 行为树推进调度与审查

极简生命周期流图： project_init -> worker_register -> dag_create -> task_create_batch -> leader_tick -> worker-default -> reviewer-default -> leader_tick(done)

运行时说明

主运行时模式

主路径是 MCP stdio：

./agentflow stdio

其他模式

还支持：
- agentflow file ：读取单个 JSON-RPC 文件请求
- 默认 HTTP 启动：提供 127.0.0.1:9600 的健康接口和基础运行壳

但对 Claude Code / MCP 集成来说，stdio 才是核心运行方式。

Python BT sidecar

BT-backed lifecycle 依赖 Python sidecar。Go server 会在需要时拉起 python -m bt_service。

没有 Python 时：
- 基础 MCP / 状态存储仍可工作
- 但 leader / worker / reviewer 默认 BT 主链能力会退化或不可用

Git 前置条件

完整项目工作流强依赖 git：
- project_init 会处理 repo 绑定
- worktree / branch / review metadata 都依赖 git runtime
- 没有 git 时，无法使用完整的交付 / review 主链

数据库路径

可通过环境变量覆盖数据库位置：

AGENTFLOW_DB_PATH=/path/to/agentflow.db

如果未设置，默认会在系统临时目录下使用 agentflow.db。

验证

单元 / 集成测试

go test ./pkg/...
python -m pytest bt_service/tests/ -x -vv

端到端 smoke

go run ./smoke/mcp_comm_check.go

这个 smoke 会真实验证：
- namespace / worker / DAG / task 创建
- task transition 权限
- worktree 准备与 git commit
- worker diary 前置
- submit / review / rework / cancel
- backward compatibility

仓库布局

cmd/
agentflow/ Go entrypoint (stdio, file, HTTP)

pkg/
engine/ 状态机、DAG、Worker、SQLite、docs/diaries/handbooks server/ MCP handler、lifecycle、git/worktree、BT provider bridge

bt_service/
server/ Python BT action / transport / clients
tests/ Python BT sidecar tests

smoke/
mcp_comm_check.go 端到端协议 smoke

trees/
leader-default.json
worker-default.json
reviewer-default.json

skills/
agentflow/
agents/
agentflow-leader/ DSH preset：Leader（不代做，含 spawn_worker） agentflow-worker/ DSH preset：Worker（不 orchestrate，无 delegation） README.md DSH 预设发现页

深入了解

如果你想看更深一层的定义，不要把 README 当成唯一真相来源：

- SPEC.md
- worker handbook / diary / leader diary 的数据与存储模型
- REPORT_STUCK_SPEC.md
- report_stuck 行为设计与 blackboard 契约
- smoke/mcp_comm_check.go
- 端到端使用路径
- pkg/server/mcp.go
- 当前 MCP 工具面的权威来源
- pkg/server/project_init.go
- .claude/agentflow-git.md 规则模板来源
- trees/.json
- 默认 leader / worker / reviewer 行为树定义
- skills/agentflow/agents/
- DSH agent 预设：agentflow-leader / agentflow-worker（项目无关；Leader 不代做、Worker 不 orchestrate，含 spawn_worker）
- docs/dsh-setup.md
- DSH（DeepSeek Harness）宿主安装 / 差异 / MCP 门禁
- docs/github-committer-and-branch-protection.md
- 如何改提交归属（author/committer）与给分支加保护

注意事项

- agentflow 是本地优先系统，不是 SaaS 控制平面。
- README 负责解释系统心智模型，不会复刻全部 spec 细节。
- BT 默认流是 opinionated 的；如果你要自定义策略，应直接看 tree 定义和 BT 工具。
- review handoff 的完整体验依赖 git metadata，而不是仅靠 task state。

英文摘要

agentflow 是一个面向 AI agent 团队的本地优先 MCP 编排引擎。

它现在结合了：
- 通过 project_init 进行项目引导
- 阶段驱动的编排：setup -> shape -> plan -> execute -> stuck -> done
- Go MCP 服务器 + SQLite 作为事实来源
- 用于默认 leader / worker / reviewer 流程的 Python BT sidecar
- git 原生执行，每个 DAG 一个分支，每个任务一个 worktree
- 通过 review.commit 和 review.diff 进行显式 review handoff
- 通过 docs、worker handbooks 和 diaries 实现持久化项目记忆

安装与快速开始

选项 1：DeepSeek Harness（DSH）原生插件（推荐）
1. 市场（1024Store / dshfind）：
- 在 DSH Plugin Marketplace 或社区目录（dshfind）中搜索 @stifer/dsh-agentflow，点击安装。
2. CLI 快速安装：
dsh plugin --profile web add @stifer/dsh-agentflow

3. 在 profile 中启用（追加到 /profiles/web/cordis.patch.yml）：
- insert:
- id: agentflow
name: '@stifer/dsh-agentflow'

4. 验证与体验：
- 在对话中输入 /agentflow 以调出 orchestrator 指南。
- 自动挂载 61+ 个原子 MCP 工具（mcp__agentflow__）。
- 原生 Live-Spec 4D 动态可视化拓扑画布（自动响应半宽/全宽视口）。

选项 2：Claude Code / Codex 独立安装
- Windows（PowerShell）： irm https://raw.githubusercontent.com/toustifer/agentflow/master/scripts/install.ps1 | iex

- Linux / macOS（Bash）：
curl -fsSL https://raw.githubusercontent.com/toustifer/agentflow/master/scripts/install.sh | bash

- 在 .claude.json 或 codex.json 中配置 stdio 模式。或从源码构建：go build -o agentflow ./cmd/agentflow/ && ./agentflow stdio。

选项 3：Agent Hub 多宿主与多 agent 协作与 hub.stifer.xyz 控制平面连接以进行团队协调：
- hub_login()：两步浏览器设备码登录——不带 code 会返回 verification_url + code；再次带 code 调用会轮询直到批准，然后将 JWT 保存到 ~/.agent-hub/config.json（仅 JWT；不会写入团队代码）。
- hub_list_teams()：发现你的团队代码。需要来自 hub_login 的 JWT；仅凭 API key 会返回 skipped，而不是 failed。
- hub_bind_team(namespace_id, business_code)：用 4 位团队业务代码绑定本地工作区。
- 自动分支锁预防、全局任务板投影和跨机器 playbook 共享。

推荐的引导路径 project_init -> worker_register -> dag_create -> task_create_batch -> project_next_steps -> leader_tick

默认角色流程

Leader: refresh phase -> dispatch / monitor / stuck / done
Worker: confirm -> worktree -> implement -> commit -> doc -> diary -> submit
Reviewer: fetch diff -> decide -> pass / rework

深入参考

- SPEC.md 用于手册 / 日记数据模型
- REPORT_STUCK_SPEC.md 用于卡住路径契约
- smoke/mcp_comm_check.go 用于端到端冒烟测试
- pkg/server/mcp.go 用于权威 MCP 工具接口
- trees/*.json 用于随附的行为树

许可证

MIT