toustifer/agentflow

agentflow

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

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

中文 ·
English

中文概览

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

安装与快速开始 (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

端到端冒烟测试

go run ./smoke/mcp_comm_check.go

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

仓库布局

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 预设：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 server + 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. Marketplace（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()：一键式 OAuth 浏览器授权。
- 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