用OpenCode构建规划管道提效实战

你是否也和我一样，一直在寻找优化 OpenCode 等工具使用方式的方法？或许这篇文章能给你带来一些新思路，也能帮助你理解这类工具及其他工具的部分工作流。

在研究 OpenCode 文档时，我发现了社区插件页面。在那里，我找到了三个在我看来能够很好互补的插件。准确地说，其中一个我已经在使用了：Plannotator。

于是，我开始研究命令、Agent 的工作原理，以及如何设计一套既合理、最重要的是确实能够运行的工作流。别急，接下来我会解释每个插件的作用，以及最终想通过集成实现什么。

我之前如何使用 OpenCode

集成目标

Plannotator：可视化审查

Octto：结构化收集上下文

Subtask2：Pipeline 编排

开始使用 OpenCode 后，我意识到规划模块非常重要。更重要的是，不只是规划本身，规划过程中提出的问题也同样关键。

规划和提问这两种新方式结合起来，不仅显著提升了生成代码的质量，也加深了我对业务规则、系统行为和工作流的理解。

即便这些发现已经优化了整个过程，我仍然觉得还有进一步改进的空间。

我原本使用 OpenCode 的流程基本如下：先发送 prompt，工具扫描代码以获取上下文；接着提出一些问题；然后进入 build 阶段，也就是把规划好的内容真正实现出来。

我的设想是：通过 Octto 尽可能多地提取上下文，使用 Subtask2 编排各个命令，最后通过 Plannotator 可视化查看完整计划。

+---------------------------------------------------------------+
|                                                               |
|  IDEIA -> CONTEXTO -> PLANO -> REFINAMENTO -> REVISAO -> OK   |
|                                                               |
+---------------------------------------------------------------+

最终，只需要一个命令就能编排整个流程：

/generate-plan "descrição do objetivo"

第一个插件是社区（He4rtDevs）里的一位朋友 Cherry 推荐给我的，它就是 Plannotator。

这个插件的作用很直接：规划结束后，它会在浏览器中打开一个页面，展示生成的完整计划。相比终端，这种方式更便于查看。

在浏览器界面中，你可以选择计划里的部分内容并给出反馈，这些反馈会被送回规划流程。你也可以批准计划，直接进入 build 阶段，也就是执行规划好的内容。

当你向 Octto 发送第一个 prompt 时，它会在浏览器中打开一个页面，展示与初始需求相关的问题。这个页面相当于一个交互式 brainstorming 界面。

随着你逐一回答问题，系统会根据这些答案，在同一次会话中继续生成新的问题，从而加深对问题的理解，并在进入后续阶段前更好地构建上下文。最后，它会在项目的 /docs/plans 目录中生成一个 .md 文件。

我只为它增加了一项配置：将第一个问题设置为自由文本输入框，让用户能够更自由地描述上下文，例如直接粘贴一项完整的 task。

工作流程

+----------------------+
|       ask_text       |  <-- Primeira ação obrigatória
+----------+-----------+
           |
           | Campo de texto no browser:
           | "Descreva com detalhes o que
           | você quer planejar..."
           v
+----------------------+
|   create_brainstorm  |  <-- Agente inicia sessão
+----------+-----------+      com contexto coletado
           |
           | Define branches de exploração
           v
+--------------------------------------------------------------+
|                    BRANCHES DE EXPLORAÇÃO                    |
|                                                              |
|  +----------------+  +-------------------+  +---------------+|
|  | Motivação &    |  | Requisitos &      |  | Riscos &      ||
|  | Objetivos      |  | Restrições        |  | Dependências  ||
|  +--------+-------+  +---------+---------+  +-------+-------+|
|           |                    |                    |        |
+-----------+--------------------+--------------------+--------+
            |
            v
+----------------------+
|      BROWSER UI      |
|                      |
|  [ Pergunta 1 ]      |
|  [ Pergunta 2 ]      |
|  [ Pergunta N ]      |
|                      |
|      [Responder]     |
+----------+-----------+
           |
           | Usuário responde
           v
+----------------------+
| await_brainstorm_    |
| complete             |  <-- Agente aguarda respostas
+----------+-----------+
           |
           | Sintetiza respostas
           v
+----------------------+
|      docs/plans/     |
| 2026-03-08-objetivo  |  <-- Arquivo gerado
|        .md           |
+----------------------+

通过 Fragments 配置

Octto 的行为可以通过 fragments 定制。Fragments 是添加到内部 Agent prompt 中的指令：

{
    "fragments": {
        "octto": [
            "Sempre pergunte a motivação e o 'porquê' das mudanças",
            "Gere nomes de arquivo no formato: YYYY-MM-DD-slug.md",
            "Salve os planos em docs/plans/"
        ],
        "probe": [
            "Priorize perguntas sobre motivações e restrições",
            "Inclua perguntas sobre requisitos não-funcionais"
        ],
        "bootstrapper": [
            "Crie branches focados em: requisitos, arquitetura, riscos"
        ]
    }
}

各个内部 Agent 的作用：

• bootstrapper：创建初始 branches 结构
• probe：生成用于深入探索的问题
• octto：定义上下文收集的整体行为

Subtask2 支持按顺序串联多个命令。一个命令执行结束后，链中的下一个命令会自动开始执行。

在我的场景中，我只会使用它的 return 功能，但这个插件还有许多其他有趣的功能，例如：

• 循环执行 subtasks，直到满足用户指定的条件
• 并行执行多个 subtasks——相关 PR 尚未合并
• $TURN[n] 用来传递会话轮次，即用户与 Assistant 的消息
• {as:name} 与 $RESULT[name] 用来捕获和引用 subtasks 的输出

Return Chain 语法

---
subtask: true
return:
- /comando-1
- /comando-2
- /comando-3
---

借助 Subtask2，我可以向工作流中添加命令，这带来了许多可能性。不过目前我还是打算脚踏实地，先通过几个新命令实现一套简单的流程。

我创建这些命令的唯一目的，就是在这条 pipeline 中使用它们。

启动整个流程的命令是 /generate-plan。执行它之后，规划 pipeline 就会开始运行。

你可以自由选择任何命令名称。我之所以选了这个名字，只是听从了脑海里的声音。

如果你想进一步了解如何在 OpenCode 中创建和配置命令，可以看看它的文档，写得还不错。

/generate-plan refatorar sistema de autenticação
/generate-plan "adicionar suporte a múltiplos gateways de pagamento"

引号并非必需：命令之后的所有内容都会作为 $ARGUMENTS 传入。

---
description: Pipeline completo de planejamento 
agent: octto
subtask: true
return:
- /refine-plan
- /review-plan
---

prompt aqui, e lembre de usar o $ARGUMENTS

如果你想看看我在 generate-plan 命令中使用的 prompt，可以去 gist 查看。

所有命令都可以在 OpenCode 中单独使用。使用带有 subtask 的命令时，唯一的区别是：它会在另一个上下文中执行。

/refine-plan 的目标，是为已有计划补充架构方面的细节。

/refine-plan # usa plano mais recente
/refine-plan docs/plans/meu-plano.md # plano específico

---
description: Expande e refina tecnicamente um plano existente com arquitetura e diagramas
subtask: true
---

Mesma coisa que o anterior, aqui você consegue adicionar a instrução que você quiser.

在我的例子中，所使用的 prompt 放在 gist 的 refine-plan.md 中。

最后是 /review-plan 命令，它的目标是通过 Plannotator 对计划进行交互式审查。

/review-plan # usa plano mais recente
/review-plan docs/plans/meu-plano.md # plano específico

需要特别注意：这个命令没有使用 subtask: true。它会在主会话中运行，以便 submit_plan 工具能够正确地在浏览器里打开 Plannotator 界面。作为 subtask 运行的命令无法初始化浏览器 UI。

完整执行流程

最重要的问题是：它成功了吗？成功了。

这是门大炮吗？也是，哈哈哈哈。

之所以会做出这个项目，是因为当我问自己“这东西真的能跑起来吗？”时，陷入了高度专注的状态。最终，我得到了答案。

从日常使用体验来看，我认为最适合使用这套流程的场景包括开发新 feature、重构项目，甚至也可以用它来组织学习计划。

不过，千万别把它用在“我想改一下按钮颜色”这种需求上，否则只会把事情复杂化。

我最喜欢的是 Octto，以及它动态生成问题的能力。在我看来，这对补充上下文有非常大的帮助。

除此之外，你还可以为它的 branches 添加指令，指定希望或不希望使用的 input 类型，等等。它的文档值得一读。

Subtask2 则打开了更多可能性。正如我之前所说，我最终选择了比较简单的用法，但思路更开阔的人，很可能可以从这个工具中挖掘出更多价值。

我计划继续创建新的命令、进一步优化 prompts，然后看看会发生什么。

就是这些。感谢你读到这里，也请尝试自己动手玩玩。

正如我的 Tech Lead 常说的：

写点没用的代码，再弄坏点什么。

有些评论可能只有登录后的访客才能看到。登录后即可查看全部评论。

如果需要采取进一步措施，你可以考虑屏蔽此人和／或举报滥用行为。