文档即状态机：Agentic Souls 如何用 Markdown 驱动 AI 软件开发工作流

🇬🇧 English Version

一、引言

Agentic Souls 是一个基于文档驱动的 AI 软件开发工作流系统，它通过定义 Planner（规划者）、Evaluator（评审官）和 Specialist（实施者）三个核心角色，利用结构化的 Markdown 文件作为状态机和控制流，实现高质量的软件交付。

二、核心设计

2.1 设计决策 1：Markdown 作为状态机与控制流

直觉会怎么做：使用数据库或复杂的 JSON 结构来管理任务状态，在代码中硬编码流程逻辑。

实际怎么做的：Agentic Souls 使用一系列结构化的 Markdown 文件（task.md, plan.md, execution.md, evidence.md, verdict.md）作为唯一的真相来源。每个文件代表工作流的一个阶段，文件的创建和更新即为状态迁移。

根据 docs/campaign.md 的定义，一个完整的 Campaign 包含以下结构：

campaign:
  id: CAMP-XXX
  name: [Campaign 名称]
  status: pending | in_progress | completed | failed

  task:           # 任务定义
    ...

  plan:           # 执行计划
    ...

  execution:      # 执行记录
    ...

  evidence:       # 验证证据
    ...

  verdict:        # 最终判决
    ...

文件按阶段逐步创建，而不是一次性生成：

文档	创建者	创建时机	内容
task.md	Planner	Campaign 开始时	任务定义
plan.md	Planner	task.md 完成后	执行计划
execution.md	Specialist	每个 Phase 执行时	执行日志（逐步追加）
evidence.md	Evaluator	每个 Phase 验证时	验证证据（逐步追加）
verdict.md	Evaluator	所有 Phase 完成后	最终判决

为什么更好：

1. 人类可读性：开发者可以直接阅读和理解任务进展，无需解析代码逻辑。
2. 版本控制友好：Git 天然支持 Markdown 的差异对比，便于审计和回溯。
3. 解耦：AI Agent 只是文件的消费者和生产者，流程逻辑完全由文件结构定义，易于扩展新的工作流。

2.2 设计决策 2：基于证据的独立评估（Evaluator）

直觉会怎么做：Planner 声称任务完成，直接标记为通过；或者 Evaluator 依赖 Specialist 的自述。

实际怎么做的：Evaluator 被设计为一个独立的 sub_agent，它不信任任何陈述。它必须通过读取文件、运行命令（如 pytest, ruff）来获取"一手证据"，并将这些证据映射到具体的 Acceptance Criteria (AC)。

从 souls/evaluator.md 中可以看到 Evaluator 的核心约束：

规则_1:
  描述: 不信任 Planner 的陈述，自己动手验证
  原因: 独立验证，确保客观公正

规则_2:
  描述: 不发现证据不给 PASS，去读文件、跑命令
  原因: 证据驱动，避免主观判断

规则_3:
  描述: 不在职责范围内给建议，只输出判决
  原因: 保持角色边界，避免越权

实际的 evidence.md 展示了这种证据驱动的验证方式。以 campaigns/<your-campaign>/evidence.md 为例：

## Phase 1 (P0)

| AC | Status | Verification | Proof |
|----|--------|-------------|-------|
| AC-1 | PASS | 代码审查 | `SimilarityDetector(min_block_size=min_lines)` + `add_code_block` |
| AC-2 | PASS | 读取 pyproject.toml | `ai-analyze = "src.cli:main"` |
| AC-3 | PASS | grep 搜索 | `grep -r "from src\." src/` 返回 0 结果 |
| AC-4 | PASS | 代码审查 | serena_stdio_client.py 无局部 Path 导入 |
| AC-5 | PASS | 测试通过 | `assert len(h) == 64` |

Evaluator 的判决结果只能是以下四种之一：

• PASS：所有 AC 达成
• PARTIAL：核心 AC 达成，但存在非阻塞问题
• FAIL：核心 AC 未达成
• BLOCKED：存在阻塞，需要外部干预

为什么更好：

1. 客观性：消除了主观判断和"幻觉"，所有判决都基于可验证的证据。
2. 可追溯性：evidence.md 提供了完整的审计轨迹，方便排查问题。
3. 角色边界：Evaluator 被严格限制只输出判决（PASS/FAIL），不提供建议，确保了制衡。

2.3 设计决策 3：通过约束性 Soul 文档实现角色隔离

直觉会怎么做：在代码中定义不同的 Agent 类，通过参数传递角色信息。

实际怎么做的：每个角色（Planner, Specialist, Evaluator）对应一个 Markdown 文件（位于 souls/ 目录）。这些文件不仅定义了职责，更包含了严格的"行为准则"和"禁止行为"。

以 souls/planner.md 为例，Planner 的核心约束是：

规则_1:
  描述: 永远不自己写超过20行的实现代码
  原因: 保持角色边界，避免越权

规则_2:
  描述: 所有实现通过 Task 工具委托给 Specialist
  原因: 职责分离，确保执行质量

规则_3:
  描述: 完成前必须调用 Evaluator，不允许自我评判
  原因: 独立验证，确保交付质量

souls/specialist.md 定义了 Specialist 的执行规范：

规则_1:
  描述: 只做 Planner 分配的子任务，不自行扩大范围
  原因: 保持职责边界，避免越权

规则_2:
  描述: 不做整体规划，不判断整体是否完成
  原因: 这是 Planner 的职责，不是 Specialist 的职责

规则_3:
  描述: 完成后立即汇报，说清楚做了什么、产物在哪、是否需要 Planner 关注
  原因: 及时反馈，便于 Planner 决策

souls/evaluator.md 则强调了 Evaluator 的独立性：

隔离机制:
  - Evaluator 是独立的 sub_agent
  - 不继承 Planner 的判断
  - 不接受 Planner 的建议
  - 只基于自己的验证输出判决

为什么更好：

1. 灵活性：可以轻松创建新角色或修改现有角色的行为，只需编辑 Markdown 文件。
2. 显式约束：将业务逻辑中的约束（如代码行数限制、角色边界）显式化，防止 AI 越权。
3. 可组合性：不同的工作流（Workflow）可以引用不同的 Soul 组合，适应不同场景。

三、源码导航

模块	文件	说明
核心定义	docs/campaign.md	Campaign 的完整结构和状态机定义
角色定义	souls/planner.md	Planner 的职责、约束和工作流程
角色定义	souls/evaluator.md	Evaluator 的独立验证机制和判决标准
角色定义	souls/specialist.md	Specialist 的执行规范和汇报格式
实战案例	campaigns/	完整的 Campaign 实例目录，包含各阶段文件
记忆系统	memories/	历史问题和解决方案的知识库

四、与 PSE 框架的关系

Agentic Souls 与 autogen-pse、crewai-pse 共享 Planner / Specialist / Evaluator 三角色协作的设计理念，但侧重不同：

项目	协作模式	编排方式	特点
agentic-souls	文档驱动	Markdown 状态机	人类可读、Git 友好、无需代码框架
autogen-pse	讨论型	AutoGen RoundRobinGroupChat	多轮对话协商、自动重试、SSE 实时流
crewai-pse	流水线型	CrewAI Sequential	严格顺序执行、任务驱动、结构化输出

Agentic Souls 可视为 PSE 模式的"文档层抽象"——用 Markdown 文件替代代码编排，适合需要强审计、人类可读流程的场景。

五、快速开始

git clone https://github.com/erishen/agentic-souls.git
cd agentic-souls

Agentic Souls 是一个文档驱动的系统，不需要安装依赖即可使用。你可以将其集成到任何支持 Markdown 上下文加载的 Agent 框架中（如 AutoGen、CrewAI、Claude Code 等）：

1. 克隆仓库：获取 Soul 文档、工作流定义和 Campaign 示例
2. 选择工作流：从 workflows/ 目录选取适合的工作流（如 feature-development.md）
3. 加载角色：将对应的 souls/planner.md、souls/specialist.md、souls/evaluator.md 作为 Agent 的系统提示
4. 执行 Campaign：Planner 创建 task.md → Specialist 执行并追加 execution.md → Evaluator 验证并写入 evidence.md / verdict.md

典型流程：

1. 加载 Planner Soul: "请读取 souls/planner.md"
2. 选择工作流: "请按照 workflows/feature-development.md 执行"
3. 切换到 Specialist: "请读取 souls/specialist.md"
4. 切换到 Evaluator: "请读取 souls/evaluator.md"