用 OpenCode 构建文档处理管线

记得我早上徒步时用语音指令创建Claude Code代理吗？（文章1：起源故事; 文章2：深入探讨）。这个管道仍然运行得非常完美！但作为一名科技爱好者，我无法抗拒尝试OpenCode；这是一个开源终端工具，提供类似的代理功能，并有一些有趣的变体。

我是通过朋友Chris Mathias了解到OpenCode的，他告诉我关于Grok-Code-Fast-1的事情。我最初以为这是Claude Code的竞争对手，但它实际上是一个专门用于编码任务的模型。在研究过程中，我看到一篇文章提到OpenCode作为一个支持Grok-Code-Fast-1的平台。经过实验，我对它的能力印象深刻。尽管我已经投入了大量时间学习Claude Code中的代理和工作流程，但我想知道是否可以用OpenCode实现类似解决方案，而事实上确实可以。OpenCode平台甚至可能在某些应用中提供更多的力量和直观的设计。

我发现的东西让我感到惊讶：我在Claude Code中喜爱的相同代理模式，但带有用于状态跟踪和验证门的JSON清单，可以在错误扩散之前捕获它们。当我的OpenCode管道在没有干预的情况下处理一个大型手册时，我知道我必须分享这段并行旅程。请查看OpenCode和Claude Code示例的GitHub仓库，您可以进行比较和对比：GitHub: 完整代理示例以及 Claude Code 和 OpenCode。

1、文档挑战：同样的问题，新的工具

如果你读过我的Claude Code系列，你就会知道挑战：Markdown中的Mermaid图表需要PDF供利益相关者使用。我的Claude Code代理（GitHub仓库在这里）优雅地处理了这个问题。

OpenCode以不同的理念解决了同样的挑战；它是开源的，支持75多个模型，并在自然语言之外添加了结构化配置：

特性	OpenCode	Claude Code
环境	终端 TUI	终端/CLI
模型支持	75+ 提供商	Claude 模型
配置	JSON/Markdown	Markdown
错误恢复	清单/自我修复	错误处理
成本	免费（支付API密钥）	订阅

两种方法都很好。关键是选择适合你需求的工具。

你可以使用OpenCode与BedRock、你的Claude Max订阅以及Github co-pilot订阅。

2、OpenCode项目结构

这里是一个OpenCode代理项目的外观：

doc-pipeline/
├── .opencode/
│   ├── agents/
│   │   └── workflow-orchestrator.md      # 主协调器
│   ├── subagents/
│   │   ├── mermaid-extractor.prompt      # 提取图表
│   │   ├── image-generator.prompt        # 生成PNG
│   │   ├── markdown-rebuilder.prompt     # 重新构建带图片的Markdown
│   │   ├── pandoc-converter.prompt       # 创建PDF/Word
│   │   ├── pipeline-validator.prompt     # 验证所有内容
│   │   └── utf-sanitizer.prompt          # 修复编码
│   └── config.yml                        # 管道配置
├── docs/
│   ├── markdown/          # 源文件
│   ├── markdown_mermaid/  # 处理后的文件
│   └── pdf/              # 输出文档
└── logs/                 # 清单和日志

美丽之处在于，每个代理只是一个带有超能力的Markdown文件。

3、理解OpenCode：结构化的灵活性

OpenCode在你的终端中运行，具有精美的TUI。TUI是终端用户界面。魔法来自于将自然语言与结构相结合：

这些JSON清单是游戏规则改变者。它们跟踪每项操作，使从失败处恢复和调试成为可能。

4、认识OpenCode代理

让我们深入了解构成我们OpenCode文档管道的专用代理。每个代理都在将带有Mermaid图的Markdown转换为精美的PDF文档中发挥关键作用。其强大之处在于它们的专业化重点与智能协调相结合。

4.1 工作流协调器

让我们首先介绍工作流协调器，它负责高层次的协调。这个代理使用JSON清单来跟踪管道状态，如果发生故障，允许从失败点恢复。结构化的方法确保每个阶段在进入下一步之前得到适当的验证，从而创建一个能够处理复杂文档处理的稳健工作流。

位置：.opencode/agents/workflow-orchestrator.md

---
name: workflow-orchestrator
description: Orchestrates document conversion pipeline
mode: primary
tools: [Read, Write, Bash, Task]
---

# Workflow Orchestrator

You coordinate the documentation pipeline with intelligence.

## Core Responsibilities:
1. Execute phases in order
2. Create/update manifests for each phase
3. Validate outputs before proceeding
4. Enable resume from any failure point

## Workflow Phases:
```bash
# Phase 1: Pre-flight checks
which mmdc && which pandoc || exit 1
mkdir -p docs/markdown_mermaid/{images,mermaid} docs/{pdf,word} logs

# Phase 2: Extract diagrams (delegate to subagent)
Task "Extract all mermaid diagrams" -> mermaid-extractor

# Phase 3: Generate images (delegate to subagent)
Task "Convert diagrams to PNG" -> image-generator

# Phase 4: Rebuild markdown (delegate to subagent)
Task "Replace mermaid blocks with images" -> markdown-rebuilder

# Phase 5: Generate documents (delegate to subagent)
Task "Create PDF and Word docs" -> pandoc-converter

# Phase 6: Validate everything
Task "Validate all outputs" -> pipeline-validator
```

## Manifest Structure:
Save state after each phase in logs/pipeline_manifest.json:
```json
{
  "run_id": "2025-01-10-143022",
  "phases": {
    "extraction": {"status": "complete", "files": 14},
    "generation": {"status": "complete", "images": 14},
    "current": "document-conversion"
  }
}
```

## On Failure:
- Log exact error with context
- Save state for resume
- Suggest fixes based on error type

上面的代码列表显示了OpenCode的“工作流协调器”代理配置。这是协调整个文档管道的主要代理。以下是它所做的：

a) 它定义了一个名为“workflow-orchestrator”的主要代理，拥有读取、写入、运行shell命令和创建任务的工具。

b) 该代理协调多阶段的文档管道，包括：

执行飞行前检查以确保安装了所需的工具（mmdc和pandoc）
创建管道所需目录结构
将专门的任务委托给子代理，如mermaid-extractor、image-generator等
以顺序、有组织的方式管理工作流

c) 它维护一个JSON清单系统，跟踪管道的状态，包括：

当前运行的阶段
完成阶段的状态
文件计数和其他指标

d) 它包括错误处理，记录失败，保存状态以便从失败处恢复，并建议潜在的修复方案。

这个代理基本上充当了文档管道的“大脑”，在保持通过JSON清单的状态的同时协调其他专业代理，以确保可靠性和可恢复性。

4.2 Mermaid 提取器

位置：.opencode/subagents/mermaid-extractor.prompt

接下来我们介绍mermaid-extractor，这是一个专门用于从Markdown文件中提取和隔离Mermaid图表代码块的子代理。它智能分析每个图表的内容，根据图表类型和上下文生成有意义的文件名。这个代理将每个图表保存为单独的.mmd文件，并创建详细的清单，跟踪所有提取的图表，供后续管道代理处理。

---
name: mermaid-extractor
description: Extract mermaid diagrams with intelligent naming.
tools: [Read, Write, Glob]
---

# Mermaid Extractor Subagent

Extract mermaid diagrams with intelligent naming.

## Process:
1. Read markdown files from docs/markdown/
2. Find all ```mermaid blocks
3. Analyze content for descriptive naming
4. Save as .mmd files with pattern: {source}_{index}_{type}.mmd

## Intelligent Naming:
```python
# Analyze diagram content
if 'flowchart' in content: type = 'flowchart'
elif 'classDiagram' in content: type = 'class'
elif 'auth' in content and 'login' in content: type = 'auth_flow'
# etc...
```

## Create Manifest:
```json
{
  "source_file": "architecture.md",
  "extracted": [
    {
      "filename": "architecture_01_system_overview.mmd",
      "type": "flowchart",
      "line_count": 45,
      "complexity": "high"
    }
  ]
}
```

## Example Output:
- architecture_01_system_overview.mmd
- architecture_02_auth_flow.mmd  
- architecture_03_database_schema.mmd

Mermaid 提取器子代理负责识别和提取Markdown文件中的Mermaid图表代码块。以下是其功能的详细分解：

智能扫描：它读取docs/markdown/目录中的所有Markdown文件，识别任何标记为```mermaid语法的代码块。
智能命名系统：而不是使用通用名称，它分析每个图表的内容以生成基于以下因素的有意义文件名：
源文档名称
序列索引号
图表类型（流程图、类图等）
图表内容中的上下文信息
模式识别：它使用模式匹配来确定图表类型，检查关键词如“flowchart”、“classDiagram”，或上下文线索如“auth”和“login”以创建更具描述性的文件名。
文件提取：每个识别到的图表被保存为单独的.mmd文件，按照命名约定：{source}{index}{type}.mmd
清单创建：它生成一个详细的JSON清单，跟踪：
源Markdown文件
所有提取的图表文件
每个图表的元数据（类型、行数、复杂度）

这个清单对后续的管道阶段至关重要，因为它提供了所有需要由后续代理（如图像生成器）处理的图表的结构化库存。

提取的.mmd文件作为下一阶段的输入，其中它们将被转换为PNG图像。智能命名有助于在整个过程中保持可追溯性，使调试问题和将生成的图像与原始源图表关联变得更加容易。

4.3 带有自我修复功能的图像生成器

位置：.opencode/subagents/image-generator.prompt

现在我们介绍image-generator子代理，它专门用于将Mermaid图表文件（.mmd）转换为PNG图像。这个代理特别令人印象深刻，因为它结合了并行处理以提高效率和自动修复功能，以自动处理常见的图表渲染错误。

 ---
tools: [Bash, Read, Write]
---

# Image Generator Subagent

Generate PNG images with parallel processing and self-healing.

## Parallel Processing:
```bash
# Process 4 images simultaneously
find *.mmd | parallel -j 4 'mmdc -i {} -o ../images/{.}.png'
```

## Self-Healing on Errors:
When mmdc fails:
1. Parse error message
2. Common fixes:
   - "Expected ';'" → Add missing semicolon
   - "Invalid syntax" → Try simpler theme
   - "Out of memory" → Process individually
3. Retry with fix
4. If still fails → Generate placeholder

## Update Manifest:
```json
{
  "generated": [
    {
      "source": "diagram_01.mmd",
      "output": "diagram_01.png",
      "size": 125632,
      "attempts": 2,
      "self_healed": true,
      "fix_applied": "added_missing_semicolon"
    }
  ]
}
```

NEVER let one failure stop the pipeline!

图像生成器子代理展示了几个高级功能：

a) 并行处理：而不是一次转换一个图表，它使用GNU parallel工具同时处理最多4个图表，显著加快了包含许多图表的文档的管道速度。

b) 自愈错误处理：当mmdc（Mermaid CLI）工具在渲染图表时遇到错误时，代理：

分析特定的错误消息以确定可能的原因
自动应用适当的修复（添加缺失的分号、简化主题等）
使用修复重新尝试转换
如果修复失败，则创建占位符图像

c) 详细的清单更新：它维护转换过程的全面记录，跟踪：

每个源文件及其对应的输出
文件大小以供验证
转换尝试次数
是否应用了自愈以及哪个特定修复有效

这个子代理体现了OpenCode管道的以弹性设计为中心的特点。通过引入自动错误检测和恢复，它确保即使遇到有问题的图表，管道也能继续处理，而不是像传统脚本那样完全失败。

它生成的详细清单有两个关键用途：提供转换过程的透明度（哪些图表需要修复）以及在必要时让整个管道从确切的故障点恢复。

4.4 管道验证器

位置：.opencode/subagents/pipeline-validator.prompt

这个代理确保交付前的质量：

 ---
tools: [Read, Bash]
---

# Pipeline Validator Subagent

Validate every aspect of pipeline output.

## Validation Checks:

### 1. File Integrity
```bash
# All expected files exist
test -f docs/pdf/*.pdf || fail "Missing PDFs"

# Files have content  
find docs/pdf -size 0 | fail_if_any "Empty files"
```

### 2. Image Embedding
```bash
# PDF must be larger than sum of images
pdf_size=$(stat -f%z docs/pdf/output.pdf)
img_total=$(stat -f%z docs/markdown_mermaid/images/*.png | sum)
[[ $pdf_size -gt $img_total ]] || fail "Images not embedded"
```

### 3. Quality Score
Calculate score (0-100):
- All files present: +40
- Images embedded: +30  
- Searchable text: +20
- No errors in log: +10

## Final Report:
```json
{
  "score": 95,
  "status": "PASS",
  "issues": ["Minor: 1 image slightly low res"],
  "recommendation": "Safe to deliver"
}
```

Score < 70 = FAIL - Do not deliver!

管道验证器子代理作为文档管道的最终质量保证检查点。它进行全面的验证检查，以确保所有输出符合质量标准，然后再进行交付。以下是它所做的：

文件完整性验证：它验证所有预期的输出文件是否存在并且包含实际内容（不是空文件）。这包括检查预期目录中的PDF文件。
图像嵌入验证：它通过比较文件大小确认图像已正确嵌入最终PDF文档——PDF应该大于所有源图像的总和。

质量评分系统：它根据多个质量标准计算一个数值评分（0–100）：

文件存在和完整性的分数（+40分）
正确嵌入图像的分数（+30分）
PDF中的可搜索文本（+20分）
无错误的日志（+10分）

通过/失败决定：根据计算出的质量评分，它明确判断文档是否准备好交付（通过）或需要进一步改进（失败）。任何低于70的评分都会导致失败状态。

详细报告：它生成一个全面的JSON报告，包括：

总体质量评分
通过/失败状态
在验证期间发现的具体问题
下一步的建议

这个验证器确保没有任何不合格的文档通过管道，保持所有输出的一致质量标准。它起到了关键的“门”作用，要么批准文档进行交付，要么将其标记为需要进一步改进。

5、秘诀：清单和验证门

这就是OpenCode特别之处——清单模式。在提取器运行之后：

{
  "pipeline_id": "run_20250110_143022",
  "phase": "extraction",
  "status": "complete",
  "timestamp": "2025-01-10T14:31:45Z",
  "results": {
    "source_files": ["architecture.md", "api-docs.md"],
    "total_diagrams": 23,
    "extracted_files": [
      "architecture_01_system_flow.mmd",
      "architecture_02_auth_sequence.mmd",
      "api-docs_01_endpoint_map.mmd"
    ]
  },
  "ready_for_next": true
}

如果管道崩溃，只需运行：opencode resume — from run_20250110_143022.

6、构建你自己的OpenCode管道

准备试验了吗？这里是你的快速入门：

我在同一份47图文档上运行了两个管道：

成功率：Claude Code和OpenCode都非常优秀
设置时间：Claude Code需要5分钟，而OpenCode需要8分钟
错误恢复：Claude Code需要手动修复，而OpenCode提供自动恢复功能
并行处理：Claude Code按顺序处理，而OpenCode并行处理4倍
调试信息：Claude Code提供良好的信息，而OpenCode提供广泛的清单

两者都很好！当需要详细的跟踪和并行处理时，OpenCode表现突出。

我在使用OpenCode时学到了一些东西，我可以带回Claude Code的工作中。

准备试验了吗？这里是你的快速入门：

6.1 安装OpenCode

brew install opencode  # macOS
# 或
curl -sSL <https://opencode.dev/install.sh> | sh

6.2 创建你的结构

mkdir -p myproject/.opencode/{agents,subagents}
cd myproject

6.3 创建你的第一个代理

保存为 .opencode/agents/file-organizer.md:

---
name: file-organizer
tools: [Read, Write, Bash]
---

# File Organizer AgentYou organize project files intelligently.## Rules:
- Python files → src/
- Tests → tests/  
- Docs → docs/
- Configs → config/## Process:
1. Scan current directory
2. Identify file types
3. Create directories if needed
4. Move files to correct locations
5. Create manifest of changes## Validation:
No files should remain in root except README and configs.

6.4 运行它

opencode chat @agents/file-organizer.md "整理这个项目"

查看OpenCode和Claude Code中的完整示例：GitHub: 完整代理示例.

7、为什么这很重要：AI开发中的选择

Claude Code向我们展示了代理开发不需要数月的编程。OpenCode证明了通往同一目标有多条路径。这两种工具各自以自己的方式使AI开发民主化。

我在Claude Code中发现的模式——委派、专业化、验证——在OpenCode中也表现得很好。这不是关于哪个更好；而是关于拥有选择。

8、结束语

无论你选择Claude Code还是OpenCode（或两者），代理开发的未来都很光明。我的文档管道无论使用哪种工具都能完美运行。真正的胜利是，我们从脆弱的脚本转向了智能、自我修复的系统。

你会建造什么？那个需要坚固清单的数据管道？必须跟踪每次更改的部署系统？选择——以及工具——都是你的。

原文链接：OpenCode Agents: Another Path to Self-Healing Documentation Pipelines

汇智网翻译整理，转载请标明出处