AI 深度技能之-解读Hermes Agent（六）- Kanban + Markdown 混合编排Kanban 管调度

Kanban 管调度和状态，Markdown 管角色行为和交接协议。这不是二选一，是合体。把 AGENTS.md 和 TEAMAGENTS.md 放进 Hermes Profile 的 workspace/ 下，让每个 Worker 在执行时同时读四个信源：kanban 任务卡片、全局约束、编排契约、角色定义。调度交给 Dispatcher，行为交给 Markdown——各管各的，互不干扰。

为什么需要混合方案

先看纯 Kanban 和纯 Markdown 各自的短板：

纯 Kanban 的问题：任务卡片 body 里塞满指令——"你是 coder，用 JWT 实现登录，跑 pnpm test，产出 changed_files……"。这些指令随任务走，换个 Profile 要重写一遍，角色行为无法跨任务积累。task body 越长，Worker 上下文窗口越紧。

纯 Markdown 的问题：没有自动调度，状态靠解析文件，容错靠人工。Git Hook 能做触发，但 Worker 崩了没人管，超时了没 reclaim，Dashboard 不存在。

混合方案做的事情：

层面	由谁管	做什么
任务状态	Kanban (SQLite)	triage → todo → ready → running → done/blocked
调度	Dispatcher	60s 轮询，自动拉起 Worker
角色行为	`agents/@role.md`	技能、产出格式、角色专属指令
全局约束	`AGENTS.md`	构建/测试命令、代码规范、安全边界
交接协议	`TEAMAGENTS.md`	阶段路由表、metadata schema、状态规则
容错	Kanban	自动重试、熔断、TTL 锁、reclaim
可视化	Dashboard	GUI + WebSocket 实时刷新

混合架构总览：

混合架构总览

上图核心：Dispatcher 拉起 Worker 后，Worker 先并行读取四个信源——kanban_show() 拿任务上下文、AGENTS.md 拿全局约束、TEAMAGENTS.md 拿交接协议、agents/@role.md 拿角色行为——合并后执行，最后 kanban_complete() 写回结构化 metadata。

结合点的关键设计：kanban task body 只写"做什么"（任务描述），"怎么做"全部交给 Markdown 文件。这样同一个 @coder.md 可以服务 100 个不同的编码任务，角色行为随项目积累，task body 保持精简。

目录结构：Markdown 文件放哪里

Hermes 的每个 Profile 有两个关键目录：

Profile Home（~/.hermes/ 或 ~/.hermes/profiles/<name>/）：存放全局配置（config.yaml、.env、SOUL.md、memories/）和共享的 kanban.db
Workspace（workspace/ 或通过 --workspace 指定的路径）：工作目录，存放项目代码和 Markdown 契约文件

Markdown 文件放在 Workspace 根目录下，因为它们是项目级别的约束，不是 Profile 级别的——不同项目可以有不同的 AGENTS.md 和 TEAMAGENTS.md。

目录结构

上图展示了完整的目录布局：

~/.hermes/                          # Profile Home
├── config.yaml                     # 模型、Provider、工具配置
├── .env                            # API Keys
├── SOUL.md                         # Agent 人格设定
├── memories/                       # 长期记忆
└── kanban.db                       # 共享看板 (所有 Profile 读写)

workspace/                          # 每个 Profile 独立的工作目录
├── AGENTS.md                       # 全局约束 (构建/测试/规范)
├── TEAMAGENTS.md                   # 编排契约 (阶段/路由/协议)
├── agents/                         # 角色定义目录
│   ├── @pm.md                      # 需求分析师
│   ├── @designer.md                # 技术设计师
│   ├── @coder.md                  # 编码工程师
│   └── @reviewer.md               # 代码审查员
├── src/                            # 项目源码
├── tests/                          # 测试
└── .handoffs/                      # JSON 交接包 (可选双保险)

为什么 kanban.db 在 Profile Home 而 AGENTS.md 在 workspace？

因为 kanban.db 是跨 Profile 共享的调度基础设施（一个看板多个 Profile 读写），而 AGENTS.md 是项目级别的约束（不同项目的代码规范、构建命令不同）。Dispatcher spawn Worker 时会通过 --workspace 参数指向项目目录，Worker 在该目录下自然能读到 Markdown 文件。

AGENTS.md：全局约束模板

这个文件所有 Worker 都会读，只写共性约束，不写角色专属内容：

# AGENTS.md — 项目全局约束

## Setup Commands
- Install dependencies: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`
- Run linter: `pnpm lint`
- Build: `pnpm build`

## Code Style
- TypeScript strict mode, no implicit any
- Single quotes, no semicolons (except ASI hazard cases)
- Functional patterns preferred; avoid class hierarchies
- All public functions must have JSDoc comments
- File naming: kebab-case for modules, PascalCase for components

## Testing Convention
- Test files colocated: `foo.ts` → `foo.test.ts`
- Use vitest, not jest
- Minimum coverage: 80% for modified files
- E2E tests in `tests/e2e/`, use playwright

## Git Convention
- Commit message format: `type(scope): description`
- Types: feat, fix, refactor, test, docs, chore
- Always run `pnpm test` before committing

## Security Boundaries
- NEVER modify `.github/workflows/` without explicit approval
- NEVER commit `.env` or secrets
- NEVER disable linting rules globally; use inline overrides
- All API endpoints must have rate limiting
- Auth required for all non-public endpoints

## Directory Convention
- `src/` — application source
- `src/modules/` — feature modules
- `tests/` — test files
- `docs/` — documentation
- `.handoffs/` — inter-agent handoff packages

Worker 读取逻辑：Dispatcher 拉起 Worker 时会设置 HERMES_KANBAN_WORKSPACE 环境变量，Worker 的 System Prompt 中注入 AGENTS.md 内容（大部分支持 AGENTS.md 标准的 Agent 工具会自动读取工作目录根下的 AGENTS.md）。对于 Hermes 来说，Worker 本身就是一个 Hermes Agent 实例，会自动加载 workspace 下的 AGENTS.md。

TEAMAGENTS.md：编排契约模板

这个文件是混合方案的核心——它定义了 Kanban 的 metadata schema 和阶段路由逻辑，让 Worker 知道上下游怎么交接：

# TEAMAGENTS.md — 团队编排契约

## 流水线阶段定义

| 阶段 ID | 名称 | Assignee | 上游 | 下游 |
|---------|------|----------|------|------|
| 1 | 需求分析 | @pm | — | 2 |
| 2 | 方案设计 | @designer | 1 | 3 |
| 3 | 编码实现 | @coder | 2 | 4 |
| 4 | 代码审查 | @reviewer | 3 | — (或退回 3) |

## 角色路由表

当 Worker 被 Dispatcher 拉起时，根据 `kanban_show()` 返回的 task assignee
匹配 `agents/` 目录下的角色文件：

| Assignee | 角色文件 | 职责 |
|----------|----------|------|
| @pm | agents/@pm.md | 需求拆解、用户故事、验收标准 |
| @designer | agents/@designer.md | 技术方案、API 契约、数据模型 |
| @coder | agents/@coder.md | 编码实现、单元测试、集成测试 |
| @reviewer | agents/@reviewer.md | 代码审查、安全审计、验收检查 |

## 交接协议 (Handoff Protocol)

每个 Worker 完成任务时，`kanban_complete()` 的 metadata
必须包含以下字段（JSON 格式）：

### 通用字段（所有阶段必含）
```json
{
  "phase": "1|2|3|4",
  "assignee": "@pm|@designer|@coder|@reviewer",
  "summary": "一句话总结",
  "changed_files": ["path/to/file1", "path/to/file2"],
  "decisions": ["决定A: 理由...", "决定B: 理由..."],
  "next_hint": "给下游 Agent 的提示，例如'关注认证模块的错误处理'"
}

阶段专属字段

阶段 1 → 2（@pm → @designer）额外字段：

{
  "spec_path": "docs/specs/user-auth.md",
  "user_stories": ["作为用户，我可以用邮箱注册", ...],
  "acceptance_criteria": ["注册成功后跳转首页", ...],
  "constraints": ["不支持第三方登录（一期）", ...]
}

阶段 2 → 3（@designer → @coder）额外字段：

{
  "design_doc": "docs/designs/auth-design.md",
  "tech_stack": ["JWT", "bcrypt", "rate-limiter"],
  "api_contracts": [
    {"method": "POST", "path": "/auth/register", "body": "..."},
    {"method": "POST", "path": "/auth/login", "body": "..."}
  ],
  "data_models": ["User", "Session"],
  "test_requirements": "单元测试覆盖率 ≥ 80%"
}

阶段 3 → 4（@coder → @reviewer）额外字段：

{
  "diff_path": "patches/feature-auth.patch",
  "tests_run": "pnpm test",
  "test_result": "pass (42 passed, 0 failed)",
  "coverage": "87.3%",
  "known_issues": ["refresh token 轮换未实现，二期补", ...]
}

阶段 4 审查结果（@reviewer）额外字段：

{
  "verdict": "pass|needs_changes|reject",
  "review_comments": [
    {"file": "src/auth.ts", "line": 42, "severity": "warning", "comment": "..."},
    ...
  ],
  "security_notes": "未发现 SQL 注入风险，bcrypt 强度 12 足够"
}

状态规则

审查通过 (verdict=pass): @reviewer 调用 kanban_complete()，流水线结束
审查退回 (verdict=needs_changes): @reviewer 调用 kanban_block(reason="needs_changes") 并在 comment 中写明退回原因，人工或 Orchestrator 调用 kanban_unblock(t_coder)
审查拒绝 (verdict=reject): 同 block，但 kind=critical，需人工介入

并行模式 (可选)

当 TEAMAGENTS.md 定义了 depends_on 数组时，Orchestrator 可以用 kind=dependency 创建并行任务：

parallel_phase:
  tasks:
    - id: t_research_a
      assignee: @researcher
      topic: "方案A调研"
    - id: t_research_b
      assignee: @researcher
      topic: "方案B调研"
  gate: all             # all=全部完成才推进 / any=任一完成
  downstream: t_synthesize

Orchestrator 创建时用 kanban_create 的 parent_id 和 kind=dependency 参数实现自动等待。

---

## 角色定义文件：agents/ 目录

每个角色一个 Markdown 文件，定义该角色的行为、技能、产出格式：

### agents/@pm.md

```markdown
# @pm — 需求分析师

## Role
你是需求分析师。你的工作是将模糊的产品需求拆解为
结构化的技术规格说明，供下游的 @designer 使用。

## Skills
- spec-decompose: 将用户故事拆解为前后端任务
- acceptance-criteria: 定义可测试的验收标准

## Input
读取上游交接包（如有）和 kanban task body 中的需求描述。

## Output
1. 技术规格文档: `docs/specs/{feature-name}.md`
2. kanban_complete metadata 必须包含 TEAMAGENTS.md
   中定义的"阶段 1 → 2 专属字段"

## Constraints
- 不要做技术选型（交给 @designer）
- 不要写实现细节（交给 @coder）
- 验收标准必须可测试（"API 返回 200" 而非"API 正常工作"）
- 用户故事格式: "作为<角色>，我可以<动作>，以便<目的>"

## Output Format
```markdown
# 技术规格: {feature-name}

## 背景
{为什么需要这个功能}

## 用户故事
1. 作为用户，我可以...
2. ...

## 验收标准
- [ ] AC1: ...
- [ ] AC2: ...

## 约束
- {constraint}

### agents/@designer.md

```markdown
# @designer — 技术设计师

## Role
你是技术设计师。基于 @pm 产出的规格文档，
设计技术方案、API 契约和数据模型。

## Skills
- design-doc: 技术方案文档
- api-contract: API 契约定义
- data-model: 数据模型设计

## Input
读取 kanban_show() 返回的 parent handoff 中的
spec_path、user_stories、acceptance_criteria。

## Output
1. 技术设计文档: `docs/designs/{feature-name}-design.md`
2. kanban_complete metadata 必须包含 TEAMAGENTS.md
   中定义的"阶段 2 → 3 专属字段"

## Constraints
- 技术选型需给出理由（不写"用 JWT"，写"用 JWT 因为无状态、横向扩展友好"）
- API 契约必须含错误码定义
- 数据模型必须含索引设计
- 安全相关决策必须标注（密码哈希算法、限流策略等）

## Output Format
```markdown
# 技术设计: {feature-name}

## 技术选型
| 决策 | 选择 | 理由 |
|------|------|------|
| 认证 | JWT | 无状态，横向扩展友好 |
| 密码哈希 | bcrypt(12) | OWASP 推荐 |
| 限流 | sliding window | 比 fixed window 更平滑 |

## API 契约
### POST /auth/register
Request: { email: string, password: string }
Response 200: { userId: string, token: string }
Response 409: { error: "email_exists" }

## 数据模型
User { id: UUID, email: string, pw_hash: string, created_at: timestamp }
Index: email (unique)

## 安全设计
- 密码: bcrypt cost=12
- JWT: 24h expiry, refresh token 7d
- 限流: 5 req/min per IP

### agents/@coder.md

```markdown
# @coder — 编码工程师

## Role
你是编码工程师。基于 @designer 的技术方案，
实现代码和测试。

## Skills
- coding: 代码实现
- testing: 单元测试 + 集成测试
- git-ops: 分支管理、diff 生成

## Input
读取 kanban_show() 返回的 parent handoff 中的
design_doc、tech_stack、api_contracts、test_requirements。

## Workflow
1. 读取 AGENTS.md 获取构建和测试命令
2. 读取 @designer 的 design_doc
3. 按方案实现代码，遵循 AGENTS.md 的代码规范
4. 编写单元测试（覆盖率满足 design_doc 的 test_requirements）
5. 运行 `pnpm test` 确认通过
6. 生成 diff patch: `git diff > patches/{feature-name}.patch`
7. 组装 metadata 调用 kanban_complete()

## Output
1. 代码变更（直接修改 src/ 下的文件）
2. 测试文件（colocated 规则）
3. diff patch: `patches/{feature-name}.patch`
4. kanban_complete metadata 必须包含 TEAMAGENTS.md
   中定义的"阶段 3 → 4 专属字段"

## Constraints
- 严格遵循 @designer 的技术方案，不擅自改技术选型
- 如遇方案不可行，kanban_block 并说明原因
- 遵守 AGENTS.md 的安全边界（不碰 CI 配置、不提交 secrets）
- 测试必须通过才能 complete

agents/@reviewer.md

# @reviewer — 代码审查员

## Role
你是代码审查员。审查 @coder 的实现是否符合
@designer 的方案和 @pm 的验收标准。

## Skills
- code-review: 代码审查
- security-audit: 安全审计
- acceptance-check: 验收检查

## Input
读取 kanban_show() 返回的 parent handoff 中的
diff_path、tests_run、test_result、coverage、known_issues。

## Review Checklist
1. 代码是否符合 AGENTS.md 的代码规范
2. 是否实现了 @designer 的 API 契约（方法、路径、请求/响应）
3. 是否满足 @pm 的验收标准（逐条检查）
4. 安全审计：注入风险、认证绕过、敏感数据泄露
5. 测试覆盖是否达标
6. known_issues 是否可接受（不阻塞一期交付）

## Output
- 通过: kanban_complete(metadata: {verdict: "pass", ...})
- 退回: kanban_block(reason: "needs_changes")
  + kanban_comment(t_coder, "具体修改建议")
- 拒绝: kanban_block(reason: "critical", kind: critical)
  + kanban_comment

## Constraints
- 审查结论必须基于事实（引用具体文件和行号）
- 不做代码风格偏好性批评（那是 linter 的活）
- security_notes 即使通过也要写（"未发现风险"或"发现低危风险可接受"）

Worker 执行流程：四源合并

这是混合方案最核心的设计——Worker 被拉起后，并行读取四个信源，合并成完整上下文再执行：

Worker 执行流程

上图展示了三个阶段：

读取阶段（4 源并行） ：

kanban_show() — 拿任务标题、描述、上游 handoff、历史尝试
workspace/AGENTS.md — 拿构建命令、代码规范、安全边界
workspace/TEAMAGENTS.md — 拿当前阶段路由、交接协议、metadata schema
workspace/agents/@role.md — 拿角色专属指令、技能、产出格式

执行阶段：

按 AGENTS.md 约束编码（遵循代码规范）
按 @role.md 指令使用指定技能
长任务每 30s 调 kanban_heartbeat() 告活

交接阶段：

按 TEAMAGENTS.md 定义的 schema 组装 metadata
调 kanban_complete(summary, metadata) 写回
Dispatcher 检测完成，推进下游任务
下游 Worker 的 kanban_show() 自动读到本次 metadata

合并后的上下文示例：

=== kanban task (kanban_show) ===
title: "实现用户认证 API"
body: "需要注册、登录、token 刷新三个接口"
parent handoff (from @designer):
  design_doc: "docs/designs/auth-design.md"
  tech_stack: ["JWT", "bcrypt", "rate-limiter"]
  api_contracts: [{method: "POST", path: "/auth/register", ...}]
  test_requirements: "覆盖率 ≥ 80%"

=== AGENTS.md ===
test command: pnpm test
code style: TS strict, single quotes, no semicolons

=== TEAMAGENTS.md ===
阶段 3 → 4 交接 metadata 必含:
  changed_files, tests_run, test_result, coverage, known_issues

=== agents/@coder.md ===
role: 编码工程师
skills: coding, testing, git-ops
workflow: 读方案 → 编码 → 测试 → diff → complete

Worker 看到这四块信息后，完全清楚该做什么、怎么做、产出什么格式、交给谁。

完整流水线运行示例

下图展示了一个需求从创建到审查完成的全流程时序：

完整流水线时序图

上图关键节点：

Human 创建四张任务卡并建立依赖链：

# 创建四个阶段的任务
T1=$(hermes kanban create "需求分析: 用户认证模块" \
--assignee pm --triage | jq -r .task_id)

T2=$(hermes kanban create "技术设计: 用户认证模块"
--assignee designer --triage | jq -r .task_id)

T3=$(hermes kanban create "编码实现: 用户认证 API"
--assignee coder --triage | jq -r .task_id)

T4=$(hermes kanban create "代码审查: 用户认证实现"
--assignee reviewer --triage | jq -r .task_id)

建立依赖链: T1 → T2 → T3 → T4

hermes kanban link --parent T1 --child T2 hermes kanban link --parent T2 --child T3 hermes kanban link --parent T3 --child T4

启动流水线: 将 T1 从 triage 提升到 ready

hermes kanban promote $T1

2. **Dispatcher 自动接力**：每 60s 扫描 `ready` 状态任务，找到对应 Profile 拉起 Worker。Worker 完成后调 `kanban_complete()`，Dispatcher 检测到完成自动推进下游任务（`todo → ready`）。

3. **Worker 读四源**：每个 Worker 被 spawn 后，先调 `kanban_show()` 读任务上下文，再读 workspace 下的三个 Markdown 文件，合并后执行。

4. **审查退回路径**：@reviewer 审查不通过时，调 `kanban_block(reason="needs_changes")` 阻塞自己的任务，同时在 @coder 的任务上写 comment。Orchestrator 或人工调 `kanban_unblock(t_coder)` 将 @coder 的任务重新推回 `ready`，Dispatcher 重新拉起 @coder Worker，它读 `kanban_show()` 时会看到退回原因和历史尝试记录。

---

## 启动流水线：完整操作步骤

### 第一步：初始化 Kanban 和 Profile

```bash
# 初始化 Kanban 看板
hermes kanban init

# 创建四个流水线 Profile
hermes profile create pm --description "需求分析师"
hermes profile create designer --description "技术设计师"
hermes profile create coder --description "编码工程师"
hermes profile create reviewer --description "代码审查员"

# 指定每个 Profile 的 workspace（共享同一个项目仓库）
hermes profile config pm --workspace ~/projects/my-app
hermes profile config designer --workspace ~/projects/my-app
hermes profile config coder --workspace ~/projects/my-app
hermes profile config reviewer --workspace ~/projects/my-app

# 启动 Dashboard
hermes dashboard &
# 打开 http://127.0.0.1:9100

第二步：在 workspace 下创建 Markdown 文件

cd ~/projects/my-app

# 创建 AGENTS.md（全局约束）
cat > AGENTS.md << 'EOF'
## Setup Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Build: `pnpm build`

## Code Style
- TypeScript strict mode
- Single quotes, no semicolons
- Functional patterns preferred

## Security
- Never modify .github/workflows/
- Never commit .env
- Auth required for all non-public endpoints
EOF

# 创建 TEAMAGENTS.md（编排契约）
# （使用上文提供的完整模板）

# 创建角色文件
mkdir -p agents
cat > agents/@pm.md << 'EOF'
# @pm — 需求分析师
（使用上文提供的模板）
EOF

cat > agents/@designer.md << 'EOF'
# @designer — 技术设计师
（使用上文提供的模板）
EOF

cat > agents/@coder.md << 'EOF'
# @coder — 编码工程师
（使用上文提供的模板）
EOF

cat > agents/@reviewer.md << 'EOF'
# @reviewer — 代码审查员
（使用上文提供的模板）
EOF

# 提交到 Git（版本管理 Markdown 契约）
git add AGENTS.md TEAMAGENTS.md agents/
git commit -m "docs: add multi-agent pipeline markdown contracts"

第三步：创建任务并启动流水线

# 创建四个阶段的任务
T1=$(hermes kanban create "需求分析: 用户认证模块" \
  --assignee pm --triage | jq -r .task_id)

T2=$(hermes kanban create "技术设计: 用户认证模块" \
  --assignee designer --triage | jq -r .task_id)

T3=$(hermes kanban create "编码实现: 用户认证 API" \
  --assignee coder --triage | jq -r .task_id)

T4=$(hermes kanban create "代码审查: 用户认证实现" \
  --assignee reviewer --triage | jq -r .task_id)

# 建立依赖链
hermes kanban link --parent $T1 --child $T2
hermes kanban link --parent $T2 --child $T3
hermes kanban link --parent $T3 --child $T4

# 启动流水线
hermes kanban promote $T1

# 启动 Gateway（内含 Dispatcher）
hermes gateway start

第四步：监控和干预

# 查看看板概览
hermes kanban list
# ID     TITLE                    ASSIGNEE   STATUS
# t_001  需求分析: 用户认证模块    @pm        running
# t_002  技术设计: 用户认证模块    @designer  todo
# t_003  编码实现: 用户认证 API    @coder     todo
# t_004  代码审查: 用户认证实现    @reviewer  todo

# 查看某个任务的执行历史
hermes kanban runs t_001
# #  OUTCOME    PROFILE  ELAPSED  STARTED
# 1  completed  pm       45s      2026-07-12 15:10

# 查看某个任务的详情（含 metadata）
hermes kanban show t_001
# title: 需求分析: 用户认证模块
# status: done
# metadata:
#   spec_path: docs/specs/user-auth.md
#   user_stories: [...]
#   acceptance_criteria: [...]

# 实时跟踪日志
tail -f ~/.hermes/logs/t_001.log

Orchestrator 模式：自动创建任务链

上面的手动创建方式适合理解流程。生产环境通常用 Orchestrator Profile 自动创建任务链：

Orchestrator Profile 配置

# ~/.hermes/profiles/orchestrator/config.yaml
model: claude-sonnet-4-20250514
tools:
  - kanban           # 启用 kanban 工具集
  - terminal         # 基础终端操作
  - file             # 文件读写
workspace: ~/projects/my-app

Orchestrator 的 System Prompt（SOUL.md）

# Orchestrator SOUL.md

你是流水线编排者。你的职责：

1. 读取 workspace/TEAMAGENTS.md 获取流水线阶段定义
2. 接收用户的需求描述
3. 用 kanban_create 为每个阶段创建任务卡
4. 用 kanban_link 建立依赖链
5. 用 kanban_promote 启动第一个任务
6. 监控执行进度，在任务失败时干预

## 决策规则
- 需求明确 → 直接创建 4 阶段任务链
- 需求模糊 → 先创建一个 @pm 的 triage 任务，
  让 @pm 拆解后再由 @pm 或 Orchestrator 创建后续任务
- 审查退回 → kanban_unblock 上游任务，附 comment 说明
- 连续 2 次退回 → 人工介入，不自动重试

## 禁止
- 不要自己执行编码、设计、审查（你有 orchestrator 工具，没有这些技能）
- 不要修改 agents/*.md（那是人类的工作）
- 不要绕过 TEAMAGENTS.md 定义的协议

用 Orchestrator 启动流水线

# 与 Orchestrator 对话
hermes -p orchestrator

> 用户认证模块需要支持邮箱注册、登录、token 刷新

# Orchestrator 会：
# 1. 读 TEAMAGENTS.md 确认 4 阶段路由
# 2. kanban_create × 4 创建任务
# 3. kanban_link × 3 建立依赖
# 4. kanban_promote 启动第一阶段
# 5. 回复："已创建 4 个任务，流水线已启动，
#        预计 @pm 45s, @designer 60s, @coder 5min, @reviewer 2min"

容错与退回：Kanban + Markdown 协同

混合方案的容错能力来自两层协同：

场景	Kanban 层	Markdown 层
Worker 崩溃	Dispatcher 检测 dead pid → reclaim → 重拉	Worker 读 `kanban_show()` 看到 prior attempts，不重复犯错
Spawn 失败	2 次失败后 gave_up + 通知	@role.md 说明该 Profile 需要的 env 变量
审查退回	@reviewer block + comment on @coder	@coder 重读 review_feedback，知道改什么
方案不可行	@coder block(reason="design_infeasible")	@designer 重读 prior attempts，调整方案
连续退回	failure_limit 触发 auto-block	人工介入，检查 agents/*.md 是否定义清楚

退回操作示例：

# @reviewer 审查后发现 3 个问题，退回给 @coder

# Worker 内部（@reviewer 的 tool calls）：
kanban_block(
  reason="needs_changes: 1) 缺少 refresh token 轮换 2) 错误处理不完整 3) 缺少限流"
)

kanban_comment(
  task_id="t_coder",   # 在 @coder 的任务上写 comment
  body="""
审查退回，需修改：

1. **refresh token 轮换** (src/auth.ts:78)
   当前实现只签发 refresh token 但不轮换，
   需在每次 refresh 时生成新 token 并失效旧 token。

2. **错误处理** (src/auth.ts:102-115)
   login 失败时只返回 500，需区分：
   - 401: 密码错误
   - 404: 用户不存在
   - 429: 限流触发

3. **限流** (src/auth.ts:130)
   设计文档要求 5 req/min per IP，
   当前实现缺少 rate limiter 中间件。

详见 review_comments 中的逐条审查意见。
"""
)

# 人工或 Orchestrator 将 @coder 任务推回 ready
hermes kanban unblock t_coder
# Dispatcher 下一个 tick 重新拉起 @coder Worker
# @coder 的 kanban_show() 会看到：
#   - prior attempts: 1 (上次执行)
#   - comments: @reviewer 的退回原因
#   - 它根据退回意见修改代码，重新 complete

并行模式：Fan-out + Gate

TEAMAGENTS.md 可以定义并行阶段。Orchestrator 用 kanban_create 的 parent_id 和 kind=dependency 实现：

# 创建根任务
T_ROOT=$(hermes kanban create "技术调研: 微服务框架选型" \
  --assignee orchestrator | jq -r .task_id)

# 创建 3 个并行调研任务（都依赖 T_ROOT）
for topic in "grpc" "graphql" "rest"; do
  hermes kanban create "调研: $topic 方案" \
    --assignee researcher \
    --parent $T_ROOT \
    --kind dependency
done

# 创建汇总任务（依赖所有调研完成）
T_SYNTH=$(hermes kanban create "汇总分析: 框架选型建议" \
  --assignee writer \
  --parent $T_ROOT \
  --kind dependency | jq -r .task_id)

# 启动
hermes kanban promote $T_ROOT

Dispatcher 会：

拉起 3 个 @researcher Worker 并行执行
每个 Worker complete 后检查 sibling 是否都完成
全部完成 → 自动 promote T_SYNTH 到 ready
@writer Worker 读 kanban_show()，看到三个调研的 metadata

TEAMAGENTS.md 中的并行定义：

## 并行阶段定义

### 技术调研流水线
| 任务 | Assignee | 依赖 |
|------|----------|------|
| 调研 gRPC | @researcher | T_ROOT |
| 调研 GraphQL | @researcher | T_ROOT |
| 调研 REST | @researcher | T_ROOT |
| 汇总分析 | @writer | 以上全部 (gate: all) |

### Gate 规则
- `gate: all` — 所有 sibling 完成才推进下游（默认）
- `gate: any` — 任一 sibling 完成即推进（用于竞速模式）
- `gate: majority` — 多数完成即推进（2/3 通过模式）

三种方案对比

维度	纯 Kanban	纯 Markdown	混合方案
状态存储	SQLite DB	Markdown + JSON 文件	SQLite DB
调度	Dispatcher 自动 (60s)	Git Hook / Cron	Dispatcher 自动
角色行为	写在 task body 里	agents/*.md	agents/*.md
全局约束	每次重复写	AGENTS.md	AGENTS.md
交接协议	隐式 (metadata ad hoc)	TEAMAGENTS.md	TEAMAGENTS.md
容错	自动重试 + 熔断	人工	自动重试 + 熔断
Dashboard	GUI + WebSocket	无	GUI + WebSocket
框架依赖	Hermes Agent	零依赖	Hermes Agent
人机通用	否 (Hermes 专有)	是 (任何 Agent 工具)	部分 (Markdown 层通用)

选择建议：

纯 Kanban：已经在用 Hermes，团队内部统一，不需要跟外部工具协作。适合快速跑起来。
纯 Markdown：多工具混用（Claude Code + Codex + Cursor），不想被框架锁定，愿意手动管理调度。适合开源协作。
混合方案：已经在用 Hermes，但想让角色行为可积累、交接协议可版本管理、Markdown 契约对人和 Agent 都可读。适合长期运营的 Agent 团队。

最佳实践

1. Markdown 文件版本管理

# AGENTS.md 和 TEAMAGENTS.md 应该提交到 Git
git add AGENTS.md TEAMAGENTS.md agents/
git commit -m "docs: update handoff protocol schema"

# 角色行为变更是可审计的
git log --oneline -- agents/@coder.md
# a3f2d1c docs: @coder 加 git-ops 技能
# 7b1e9f0 docs: @coder 明确测试覆盖率要求

2. task body 保持精简

# ✅ 好的做法：task body 只写"做什么"
hermes kanban create "实现用户认证 API" --assignee coder
# "怎么做"由 @coder.md 定义，"约束"由 AGENTS.md 定义，
# "交接格式"由 TEAMAGENTS.md 定义

# ❌ 不好的做法：task body 写满指令
hermes kanban create "实现用户认证 API。
你是编码工程师。用 JWT 实现注册登录刷新三个接口。
密码用 bcrypt cost=12。跑 pnpm test 确认通过。
产出 changed_files 和 test_result。不要碰 CI 配置。
..." --assignee coder
# 问题：指令不可复用、不可积累、不可审计

3. metadata schema 用 TEAMAGENTS.md 约束

TEAMAGENTS.md 定义了 metadata schema 后，Orchestrator 在创建任务时可以在 task body 中提示：

hermes kanban create "实现用户认证 API" \
  --assignee coder \
  --body "按 TEAMAGENTS.md 阶段 3 → 4 协议产出 metadata"

Worker 读到后会去 TEAMAGENTS.md 查 schema，确保 metadata 字段完整。

4. workspace 隔离

# 不同项目用不同 workspace
hermes profile config coder --workspace ~/projects/app-a
hermes profile config coder-2 --workspace ~/projects/app-b
# 同一个 @coder.md 角色可以服务多个项目
# 但 kanban.db 是共享的，看板会显示两个项目的任务
# 用 board 隔离:
hermes kanban boards create app-a
hermes kanban boards create app-b

5. Profile Distribution 同步 Markdown

# 用 Profile Distribution (Git) 同步 Markdown 契约到多台机器
cd ~/.hermes/profile-distributions/coder/
git add workspace/AGENTS.md workspace/TEAMAGENTS.md workspace/agents/
git commit -m "sync: markdown contracts"
git push origin main

# 其他机器
hermes profile pull coder
# 自动同步 Markdown 文件

踩坑记录

1. AGENTS.md 和 SOUL.md 不要冲突

SOUL.md 是 Profile 人格设定（幽默/严肃/话痨/精简），AGENTS.md 是项目约束（构建命令/代码规范）。如果 SOUL.md 说"回答要详细解释"，AGENTS.md 说"简洁直接"，Worker 会精神分裂。

解法：SOUL.md 管人格和语气，AGENTS.md 管工程约束，两者职责正交。

2. TEAMAGENTS.md 中的 metadata schema 要版本化

当你改了 metadata schema（比如给 @coder 的产出加了一个 coverage 字段），正在运行的任务可能还在用旧 schema。下游 @reviewer 读不到 coverage 就会困惑。

解法：

## Schema Version
current: 2
history:
  - v1 (2026-06-01): 初始版本
  - v2 (2026-07-12): 加入 coverage 和 known_issues 字段

Orchestrator 创建任务时在 body 中标注 schema 版本，Worker 读取对应版本。

3. workspace 路径一致性

# ❌ Profile A 的 workspace 是相对路径
hermes profile config pm --workspace ./my-app

# ❌ Profile B 的 workspace 是绝对路径
hermes profile config coder --workspace /home/user/projects/my-app

# 结果：@pm 写了 docs/specs/user-auth.md（相对路径）
# @coder 读不到，因为它的 workspace 是绝对路径

解法：所有 Profile 用相同的绝对路径指向同一个 workspace。

4. kanban task body 和 agents/*.md 不要重复

如果 task body 写了"用 JWT 实现"，@coder.md 也写了"用 JWT"，这是冗余但无害。但如果 task body 写"用 Session 实现"，@coder.md 写"用 JWT"，Worker 会困惑。

解法：task body 写特定需求（"实现用户认证"），@role.md 写通用行为（"按 @designer 的方案选型"）。特定覆盖通用，不要在同一层写两份。

5. Dispatcher 轮询间隔与心跳的关系

Dispatcher 每 60s 轮询一次。Worker 的 kanban_heartbeat() 默认 TTL 也是 60s。如果 Worker 在 60s 内没有调 heartbeat（比如卡在一个长编译任务上），Dispatcher 可能误判为超时并 reclaim。

解法：长任务中每 30s 调一次 heartbeat，确保 TTL 不过期：

# Worker 内部伪代码
while (compiling):
    kanban_heartbeat(note="compiling... 4/8 files done")
    sleep(30)

总结

混合方案的核心设计原则是关注点分离：

关注点	归属	原因
"做什么"	Kanban task body	每个任务不同，需要状态管理
"怎么做"	agents/@role.md	角色行为可跨任务复用，可积累
"全局约束"	AGENTS.md	所有 Agent 共享，项目级别
"交接格式"	TEAMAGENTS.md	协议层，定义 metadata schema
"调度和容错"	Kanban Dispatcher	自动化，不需要人管
"可视化"	Dashboard	GUI + WebSocket

这种分离带来的好处：

task body 精简——只写特定需求，不重复角色指令
角色行为可积累——@coder.md 随项目迭代越来越完善
交接协议可审计——TEAMAGENTS.md 的每次变更都是 Git commit
调度自动化——Dispatcher 管容错，不需要人盯
人机通用——Markdown 文件人和 Agent 都能读，理解同一套协议

如果你已经在用 Hermes Kanban，把 AGENTS.md 和 TEAMAGENTS.md 放进 workspace 是几乎零成本升级——不需要改 kanban.db schema，不需要改 Dispatcher 逻辑，只需要在工作目录加几个 Markdown 文件，Worker 就会自动读取。

参考文档：

Hermes Kanban 官方文档：hermes-agent.nousresearch.com/docs/user-g…
AGENTS.md 开放标准：agents.md
Kanban Tutorial（四个实战故事）：kanban-tutorial
Worker Lanes 契约：kanban-worker-lanes
Profile Distribution（Git 同步）：profile-distributions