什么是 do 工作流

do 工作流是 PinableAgents 中最核心也是最推荐的工作流。它的名字来源于"Do it right"的理念：与其快速写出代码再反复修补，不如在动手实现之前充分理解需求、探索代码库、明确架构方案，然后一次性高质量地交付。

do 工作流将一个功能开发任务分解为 7 个有序阶段，每个阶段由专门的智能体负责。这种分阶段的设计有几个核心优势：

  • 降低风险：在实现之前充分理解需求和代码库，避免返工
  • 质量保证：每个阶段都有明确的交付物，可以在早期发现问题
  • 可追溯性：完整的执行日志让你可以回顾每个决策的依据
  • 一致性：标准化的流程确保每次交付的质量基线

do 工作流适用于以下场景：

  • 新功能开发（小到一个 API 端点，大到一个完整模块）
  • 现有功能的增强或修改
  • 需要理解现有代码库后再修改的场景
  • 任何需要"做对"而非"做快"的任务

如果你不确定应该用哪个工作流，就用 do。它是最通用、最安全的选择。

准备工作

在运行第一个 do 工作流之前，请确认以下准备工作已完成：

确认模块已启用

do 工作流依赖 do 和 essentials 两个模块。运行以下命令检查模块状态：

# 查看已安装的模块
pinable-agents modules list

# 如果模块未安装，执行安装
pinable-agents modules install do essentials

# 确认工作流可用
pinable-agents workflows list
# 应该能看到 "do" 出现在列表中

确认 AI 后端可用

do 工作流需要一个可用的 AI 后端来驱动智能体。运行诊断命令确认后端状态：

# 检查后端状态
pinable-agents backend status

# 如果使用 Claude 后端，确认 CLI 工具可用
claude --version

# 如果使用 Codex 后端
codex --version

准备一个 Git 项目

do 工作流需要在一个 Git 仓库中运行。如果你还没有测试项目，可以快速创建一个：

mkdir ~/my-first-workflow && cd ~/my-first-workflow
git init
cat > main.go << 'EOF'
package main

import "fmt"

func main() {
    fmt.Println("Hello, PinableAgents!")
}
EOF
git add . && git commit -m "initial commit"

实际操作演示

现在让我们用 do 工作流完成一个简单但完整的功能开发任务。我们的目标是：为上面创建的 Go 项目添加一个 HTTP 服务器，提供一个 /health 健康检查端点。

启动工作流

在项目目录中运行以下命令：

pinable-agents run do \
  --task "添加一个 HTTP 健康检查端点 /health，返回 JSON 格式的服务状态" \
  --backend claude \
  --work-dir ~/my-first-workflow

或者通过桌面端操作：打开 PinableAgents 桌面端，进入 Workflows 页面，选择"do"工作流，在任务描述框中输入需求，选择工作目录，然后点击"运行"。

观察执行过程

工作流启动后，你会看到控制台输出各阶段的执行状态。每个阶段开始时会显示阶段名称和负责的智能体，完成时会显示交付物摘要。整个过程通常需要 3-8 分钟，具体取决于任务复杂度和网络速度。

[do] Starting workflow...
[do] Stage 1/7: Discovery
  Agent: code-explorer
  Scanning project structure...
  Found: 1 Go file, 1 commit
  ✓ Discovery complete (12s)

[do] Stage 2/7: Exploration
  Agent: code-explorer
  Analyzing main.go...
  Mapping dependencies...
  ✓ Exploration complete (8s)

[do] Stage 3/7: Clarification
  Agent: code-architect
  Generating clarifying questions...
  Auto-resolving based on context...
  ✓ Clarification complete (6s)
...

7 个阶段详细说明

阶段一：Discovery（发现）

由 code-explorer 智能体执行。这个阶段的目标是快速了解项目的整体结构和技术栈。智能体会扫描目录结构、识别编程语言和框架、查看关键配置文件（如 go.mod、package.json 等），并生成一份项目概览报告。

这个阶段不会深入阅读代码逻辑，而是建立一个"地图"，让后续阶段知道代码库的布局。对于大型项目，Discovery 阶段还会识别代码库的模块划分和入口点。

阶段二：Exploration（探索）

同样由 code-explorer 智能体执行。在 Discovery 建立整体地图后，Exploration 会深入到与当前任务相关的代码区域。智能体会阅读相关文件的具体实现，理解数据流和调用关系，标注可能受影响的代码路径。

这个阶段的产出是一份详细的代码分析报告，包括：现有代码的关键逻辑、与新功能相关的接口和数据结构、潜在的冲突点。

阶段三：Clarification（澄清）

由 code-architect 智能体执行。基于前两个阶段的发现，这个阶段会识别需求中的模糊点和隐含假设，生成一组澄清问题。在自动模式下，智能体会根据代码上下文和最佳实践自动回答这些问题；在交互模式下，这些问题会呈现给用户。

常见的澄清问题包括：错误处理策略、日志级别、是否需要认证、响应格式细节、性能要求等。

阶段四：Architecture（架构）

由 code-architect 智能体执行。这是整个工作流中最关键的阶段之一。智能体会根据需求理解和代码分析，设计实现方案。产出包括：需要修改的文件列表、新增的文件和接口、数据流设计、依赖变更。

架构方案遵循"最小变更原则"，即在满足需求的前提下，尽量减少对现有代码的改动。这个原则有助于降低引入缺陷的风险。

阶段五：Implementation（实现）

由 develop 智能体执行。这是实际编写代码的阶段。智能体会严格按照 Architecture 阶段的方案编写代码，包括新增文件、修改现有文件、更新依赖配置等。实现过程中会自动处理代码格式化、import 管理等细节。

Implementation 阶段会使用 Git worktree 在独立的工作目录中进行，确保主分支不受影响。所有变更在最终确认前都是隔离的。

阶段六：Review（审查）

由 code-reviewer 智能体执行。这个阶段对 Implementation 产生的所有代码变更进行审查。审查维度包括：代码正确性、风格一致性、错误处理完整性、安全隐患、性能影响、测试覆盖。

如果审查发现需要修改的问题，工作流会自动回到 Implementation 阶段进行修复，然后再次审查，直到所有问题都解决。

阶段七：Summary（总结）

由编排引擎自动生成。这个阶段汇总整个工作流的执行结果，包括：所有文件变更的 diff、架构决策的记录、审查通过的确认、建议的后续步骤（如是否需要手动测试特定场景）。

每个阶段的输入输出

阶段 智能体 输入 输出
Discovery code-explorer 项目目录路径 项目结构概览、技术栈识别
Exploration code-explorer 项目概览 + 任务描述 相关代码分析报告
Clarification code-architect 代码分析 + 任务描述 澄清问题及其答案
Architecture code-architect 完整上下文 + 澄清结果 实现方案文档
Implementation develop 实现方案 + 代码库访问 代码变更（在 worktree 中）
Review code-reviewer 代码变更 diff 审查报告 + 修复建议
Summary 编排引擎 所有阶段的产出 完整交付报告

查看执行日志与结果

每次工作流执行都会生成详细的日志，存储在工作目录下的 .pinable-agents/logs/ 目录中。你可以通过以下方式查看：

命令行查看

# 查看最近一次执行的日志
pinable-agents logs latest

# 查看特定阶段的详细日志
pinable-agents logs latest --stage discovery

# 查看所有历史执行记录
pinable-agents logs list

# 以 JSON 格式导出日志（便于分析）
pinable-agents logs export --format json --output report.json

桌面端查看

在 PinableAgents 桌面端的 Workflows 页面，每次执行完成后会自动显示结果摘要。点击"查看详情"可以展开每个阶段的完整日志，包括智能体的思考过程和中间产物。

日志文件结构

.pinable-agents/logs/
├── 2026-02-25T10-30-00/
│   ├── workflow.json       # 工作流元数据
│   ├── discovery.md        # Discovery 阶段产出
│   ├── exploration.md      # Exploration 阶段产出
│   ├── clarification.md    # Clarification 阶段产出
│   ├── architecture.md     # Architecture 阶段方案
│   ├── implementation.diff # Implementation 阶段代码变更
│   ├── review.md           # Review 阶段审查报告
│   └── summary.md          # 完整交付总结
└── latest -> 2026-02-25T10-30-00/

常见新手疑问

工作流执行中断了怎么办？

PinableAgents 支持断点续传。如果工作流因网络问题或其他原因中断，你可以使用 pinable-agents resume 命令从中断的阶段继续执行。所有已完成阶段的产出都会保留。

我可以跳过某个阶段吗？

在标准模式下不建议跳过任何阶段，因为每个阶段的产出是下一个阶段的输入。但如果你非常确定不需要某个阶段，可以使用 --skip 参数：

# 跳过 Clarification 阶段（不推荐）
pinable-agents run do --task "..." --skip clarification

工作流修改的代码在哪里？

do 工作流使用 Git worktree 在独立分支中进行代码修改。工作流完成后，你可以查看变更并决定是否合并到主分支：

# 查看工作流创建的分支
git branch -a

# 查看变更
git diff main..pinable/do-latest

# 合并变更
git merge pinable/do-latest

一次只能运行一个工作流吗？

是的，在同一个项目目录中，同一时间只能运行一个工作流实例。这是为了避免并发修改导致的代码冲突。如果你需要同时进行多个任务，建议在不同的项目目录或分支中分别运行。

如何选择 AI 后端？

不同后端各有优势。Claude 在代码理解和架构设计方面表现出色，适合 Discovery 到 Architecture 阶段；Codex 在代码生成方面效率高，适合 Implementation 阶段。你可以在 config.json 中为不同的智能体角色配置不同的后端。