agentflow

AI Agent 团队的软件项目生命周期编排引擎
A local lifecycle orchestrator for AI agent teams

中文 · English

中文概览

agentflow 是一个本地优先、MCP 原生、git/worktree-aware 的 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 控制平面，让多机团队看到同一张任务大盘。三条铁律：

单向 L→H：只从 agentflow 推送到 Hub，从不把 Hub 状态读回本地。agentflow 的 SQLite 永远是唯一真源。
soft-fail：Hub 的任何故障（连接拒绝 / 超时 / 401 / 500）都不会让 MCP 工具调用失败，也不会回滚本地状态。发生了什么只体现在返回值里的一个 note 字符串。
默认关闭：没有绑定 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": "<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=<Hub JWT>        # 推荐；只有 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 插件体系可实现核心状态机、技能与交互式拓扑画布的开箱即用：

社区市场安装 (1024Store / dshfind)：
- 打开 DSH 插件市场 / 社区合作提供方（如 dshfind），搜索 @stifer/dsh-agentflow，点击一键安装；

CLI 命令行快速安装：

dsh plugin --profile web add @stifer/dsh-agentflow

配置启用（在 <dshHome>/profiles/web/cordis.patch.yml 中追加）：
```
- insert:
    - id: agentflow
      name: '@stifer/dsh-agentflow'
```
验证与体验：
- 启动 DSH 后在会话中输入 /agentflow 即可唤起引导；
- 自动挂载 mcp__agentflow__* (61+ 工具)；
- 原生集成 Live-Spec 4D 动态可视化拓扑画布（自动适配半宽与全宽视口），实时推演任务依赖与流转。

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

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

一键安装脚本（自动下载二进制与技能包）：

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

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

手动配置 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）：

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

极简生命周期流图：

project_init
-> worker_register
-> dag_create
-> task_create_batch
-> leader_tick
-> worker-default
-> reviewer-default
-> leader_tick(done)

Runtime Notes

Primary runtime mode

主路径是 MCP stdio：

./agentflow stdio

Other modes

还支持：

agentflow file <path>：读取单个 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 prerequisite

完整项目工作流强依赖 git：

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

Database path

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

AGENTFLOW_DB_PATH=/path/to/agentflow.db

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

Validation

Unit / integration tests

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

End-to-end 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

Repository Layout

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 预设发现页

Where To Go Deeper

如果你想看更深一层的定义，不要把 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）与给分支加保护

Caveats

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

English Summary

agentflow is a local-first MCP orchestration engine for AI agent teams.

It now combines:

project bootstrap with project_init
phase-driven orchestration: setup -> shape -> plan -> execute -> stuck -> done
Go MCP server + SQLite as the source of truth
Python BT sidecar for the default leader / worker / reviewer flows
git-native execution with one branch per DAG and one worktree per task
explicit review handoff through review.commit and review.diff
persistent project memory via docs, worker handbooks, and diaries

Installation & Quick Start

Option 1: DeepSeek Harness (DSH) Native Plugin (Recommended)

Marketplace (1024Store / dshfind):
- Search @stifer/dsh-agentflow in DSH Plugin Marketplace or community directory (dshfind), click install.

CLI Quick Install:

dsh plugin --profile web add @stifer/dsh-agentflow

Enable in profile (append to <dshHome>/profiles/web/cordis.patch.yml):
```
- insert:
    - id: agentflow
      name: '@stifer/dsh-agentflow'
```
Verify & Experience:
- Type /agentflow in conversation to bring up the orchestrator guide.
- Automatically mounts 61+ atomic MCP tools (mcp__agentflow__*).
- Native Live-Spec 4D dynamic visualization topology canvas (auto-responsive half/full-width viewport).

Option 2: Claude Code / Codex Standalone Install

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

Configure stdio mode in .claude.json or codex.json. Or build from source: go build -o agentflow ./cmd/agentflow/ && ./agentflow stdio.

Option 3: Agent Hub Multi-host & Multi-agent Collaboration

Connect with hub.stifer.xyz control plane for team coordination:

hub_login(): Two-step browser device-code login — no code returns a verification_url + code; calling again with code polls until approved, then saves the JWT to ~/.agent-hub/config.json (JWT-only; no team code is written).
hub_list_teams(): Discover your team codes. Needs the JWT from hub_login; an API key alone returns skipped, not failed.
hub_bind_team(namespace_id, business_code): Bind local workspace with 4-digit team business code.
Automatic branch lock prevention, global task board projection, and cross-machine playbook sharing.

Recommended bootstrap path

project_init
-> worker_register
-> dag_create
-> task_create_batch
-> project_next_steps
-> leader_tick

Default role flows

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

Deep references

SPEC.md for handbook / diary data model
REPORT_STUCK_SPEC.md for stuck-path contract
smoke/mcp_comm_check.go for end-to-end smoke
pkg/server/mcp.go for the authoritative MCP tool surface
trees/*.json for the shipped behavior trees

License

MIT

agentflow

项目标签

README

agentflow

中文概览

核心模型

生命周期总览

执行模型：Git / Branch / Worktree

1. project_init 是推荐入口

2. 一 DAG 一分支

3. 一 task 一 worktree

4. submit 是带交付契约的

默认 Behavior Tree 角色流

Leader

Worker

Reviewer

MCP 能力面

Bootstrap / Project Setup

DAG / Task / Worker State

Lifecycle / Behavior Trees

Git / Worktree / Review Handoff

Docs / Handbooks / Diaries

Reporting / Project Queries

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

接线了哪些时机

怎么打开

边界（照代码写实）

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

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

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

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

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

Runtime Notes

Primary runtime mode

Other modes

Python BT sidecar

Git prerequisite

Database path

Validation

Unit / integration tests

End-to-end smoke

Repository Layout

Where To Go Deeper

Caveats

English Summary

Installation & Quick Start

Option 1: DeepSeek Harness (DSH) Native Plugin (Recommended)

Option 2: Claude Code / Codex Standalone Install

Option 3: Agent Hub Multi-host & Multi-agent Collaboration

Recommended bootstrap path

Default role flows

Deep references

License

分类依据

同类项目

deepseek-harness

dsh-desktop

learn-harness-engineering

1. `project_init` 是推荐入口

4. `submit` 是带交付契约的