@mickorz/opencode-agentic-workflow 0.4.0 → 0.5.0

package/skills/workflow-authoring/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: workflow-authoring
+description: >
+  编写与自定义 opencode-agentic-workflow 声明式流程时加载。当用户想定义/创建一个
+  workflow、把某个重复流程自动化、给现有流程加步骤或参数、或遇到 workflow_define
+  版本冲突与校验报错时使用。覆盖：需求澄清、声明式 JSON 构造、workflow_define
+  落盘注册、workflow 工具试跑验证的完整链路。
+---
+
+# workflow-authoring（声明式流程编写）
+
+把用户的流程需求变成可复用的声明式 workflow：**对话澄清 → 构造 JSON →
+`workflow_define` 落盘注册 → `workflow` 工具试跑**。全程无需人工编辑文件。
+
+## 第一步：澄清需求（缺什么问什么，别猜）
+
+1. **目的**：这个流程产出什么？（文档/代码/评审结论/检查报告）
+2. **步骤**：大致几步、每步谁做（子 agent / 人工审批 / 语义评审 / 文件断言）
+3. **参数**：除了主题 topic，还要哪些输入？（受众、语言、深度、评审标准…）
+4. **完成标准**：最后一步之后怎么判断成功？
+
+## 第二步：构造声明式 JSON
+
+```json
+{
+  "id": "kebab-case-短名",
+  "version": "1.0.0",
+  "description": "一句话说明（进工具清单，给未来的你/agent 看）",
+  "args": {
+    "type": "object",
+    "properties": {
+      "topic": { "type": "string", "description": "主题" },
+      "audience": { "type": "string", "description": "受众" }
+    },
+    "required": ["topic"]
+  },
+  "steps": [
+    {
+      "name": "draft",
+      "agent": "针对 {{topic}} 为 {{args.audience}} 写初稿…。禁止调用 workflow / workflow_metrics 工具。完成后只回复 done。",
+      "model": "glm/glm-5.3-flash",
+      "timeoutMs": 300000,
+      "retries": 1
+    },
+    { "name": "review", "verify": { "artifact": "{{steps.draft}}", "criteria": "要点完整且有结论" } },
+    { "name": "gate", "checkpoint": "「{{topic}}」初稿已生成，批准？" },
+    { "name": "file", "fileExists": "out.md" }
+  ],
+  "output": "定稿：{{steps.draft}}"
+}
+```
+
+**步骤七类**（每步恰好一个步骤键）：`agent`（子 agent）、`checkpoint`（人工
+审批门）、`verify`（语义评审；可加 `threshold` 投票与 `lenses` 多视角）、
+`fileExists`（文件存在断言，相对项目根）、`subflow`（嵌套另一个已注册
+workflow；`"subflow": "flow-id"` + 可选 `args` 对象（原始值或模板）；需要
+journalDir；嵌套深度上限 3；子 run 的输出进 `{{steps.<名>}}`，子 run 失败按
+普通步骤失败处理）、`pipeline`（条目并发 fan-out：`"pipeline": "提示模板"`
+（`{{item}}` 引用条目）+ `items` 非空模板数组 + 可选 `outputAs`/`onFailure`/
+`model`/`timeoutMs`/`retries`；结果数组与 items 对齐，`{{steps.<名>}}` 得
+JSON 串）、`race`（多提示竞速：`"race": ["模板A", "模板B"]` ≥2 并发起跑
+首个成功者胜出 + 可选 `outputAs`；全败报错）。pipeline/race 各占一个
+resume 单元：中断重跑整步（条目级断点不支持，需要就拆 subflow 步）。
+
+**必守纪律（违反 = 事故）**：
+
+1. 每个 `agent` prompt **必须以「禁止调用 workflow / workflow_metrics 工具」
+   收尾**——子 agent 递归调工作流会自饿死并发信号量
+2. 模板变量只有 `{{topic}}`、`{{args.x}}`、`{{steps.<前步名>}}`（pipeline
+   提示内另有 `{{item}}`）；未知变量 = 该步失败（fail-loud，绝不静默空串）
+3. `args` 里声明过的参数才能在 prompt 里引用；`topic` 恒有（工具自动传）
+4. `agent` 步可选 `model`（"providerID/modelId"）/ `timeoutMs`（正数毫秒）/
+   `retries`（非负整数）——只在 agent 与 pipeline 步合法（race 仅 outputAs）
+5. 改动已注册流程的步骤内容 = **必须升 version**（1.0.0 → 1.1.0）；旧版本
+   journal 的 resume 依赖精确版本解析
+6. `id` 不得用内置名：smoke / reliable / artifact / feature-development
+
+## 第三步：workflow_define 落盘注册
+
+调用 `workflow_define` 工具，输入刚构造的 `workflow` 对象。结果语义：
+
+- 成功：返回 `defined <id>@<version>` 与落盘路径，**立即可用**（无需重启）
+- 「already defined (identical)」：内容相同，幂等成功，直接用
+- 「already registered with DIFFERENT content」：同版本不同内容——升 version
+  再 define
+- 校验报错：逐字段指名，按报错修 JSON 再试
+
+## 第四步：试跑验证
+
+调用 `workflow` 工具：`flow=<id>, topic=<真实小主题>, checkpointMode=auto-approve`
+（headless 必传）。关注：
+
+- 步骤是否全 completed；失败步的报错（模板变量/文件路径/评审否决）
+- 产物是否落盘、内容是否符合预期
+- 有 `background: true` 需求时用 `workflow_control status` 轮询
+
+试跑通过后向用户报告：流程 id、参数用法（含 args 清单）、一句话示例。
+
+## 常见报错速查
+
+| 报错 | 原因与修法 |
+|------|-----------|
+| `must have exactly one of agent/checkpoint/verify/fileExists/subflow/pipeline/race` | 一步给了两个步骤键，或忘了给 |
+| `items must be a non-empty array of non-empty string templates` | pipeline 步缺 items 或混入非字符串/空串 |
+| `race must be an array of at least 2 non-empty prompt templates` | race 步分支少于 2 或有空提示（单分支无竞速意义） |
+| `subflow step "..." requires the journalDir` | subflow 需要插件配置 journalDir（lineage 落盘）；配置后重试 |
+| `subflow nesting too deep` | 嵌套超 3 层；拍平组合方式 |
+| `template variable {{...}} is not provided` | 调用没传该参数，或 args 没声明 |
+| `already registered with DIFFERENT content` | 升 version 再 workflow_define |
+| `id "..." is reserved by a built-in` | 换个 id |
+| verify 步 `fail` | 评审语义否决——改产物质量或放宽 criteria，不是 bug |

package/skills/workflow-optimize/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: workflow-optimize
+description: >
+  opencode-agentic-workflow 流程的迭代优化闭环。当用户说某个 workflow 跑得慢/
+  贵/老失败、要优化或迭代一个流程、要对比改动前后效果、或想基于 journal 与
+  metrics 复盘执行质量时使用。覆盖：metrics/journal 诊断 → 单主题改动 →
+  升版重定义 → 同参重跑 → 前后对比报告。
+---
+
+# workflow-optimize（流程迭代优化）
+
+一次完整迭代 = **诊断 → 单主题改动 → 升版 → 同参重跑 → 对比报告**。
+每次迭代只验证一个假设；收敛或收益递减即停。
+
+## 第一步：诊断（先看数据，别急着改）
+
+1. `workflow_metrics` 工具（format=json）：看累计 token/成本/时长——
+   哪个流程贵、哪个模型贵
+2. `workflow_control` 工具（action=status）：看 run 列表与单 run 详情——
+   失败在哪一步、失败原因（模板变量/评审否决/超时/文件断言）、
+   aborted/failed 占比
+3. 打开流程 JSON（`workflow_define` 返回的落盘路径）：定位可疑步骤
+   （prompt 模糊、timeout 过小、无 retries、verify criteria 过严/过松）
+
+产出一句诊断结论：「X 流程的 Y 步因为 Z 原因导致 W 症状」。
+
+## 第二步：单主题改动（一次只改一个变量）
+
+常见主题（择一）：
+
+- **步骤结构**：拆一步为两步 / 合并冗余步 / 加 fileExists 兜底断言
+- **prompt 质量**：明确输出格式、加「只回复 done」收敛输出、消除歧义词
+- **调用级选项**：给易超时步加 `timeoutMs`/`retries`；简单步用小 `model`
+- **评审校准**：verify 的 `criteria` 写实；多维度用 `lenses`；容错用
+  `threshold` 投票（全票制太严时）
+- **参数化**：把硬编码值提升为 `args` 参数（提高复用/对比可控性）
+
+## 第三步：升版重定义（版本契约）
+
+改动步骤内容/prompts/args 结构 = **必须升 version**（1.0.0 → 1.1.0）。
+调用 `workflow_define` 传入完整新 JSON；registry 同 id 多版本共存、
+新 run 自动取最新。**绝不覆写旧版文件**——对比与回滚都靠旧版还在。
+
+只改 description/output 模板等非结构内容？仍建议升版（版本即审计线）。
+
+## 第四步：同参重跑（控制变量）
+
+用与基线**相同的 topic 与 args** 跑新版：`workflow` 工具
+`flow=<id>, topic=<基线同款>, checkpointMode=auto-approve`。
+复杂流程可加 `background: true` + `workflow_control status` 轮询。
+
+## 第五步：对比报告（向用户交代）
+
+从两版 run 的 journal（workflow_control status 详情）+ metrics 提取：
+
+| 维度 | 旧版 | 新版 | 变化 |
+|------|------|------|------|
+| 状态/失败步 | … | … | |
+| token / 成本 | … | … | |
+| 时长 | … | … | |
+| verify 结论 | … | … | |
+
+结论必须含：**改了什么、为什么有效/无效、下一步建议或「已收敛」**。
+收益递减（<10% 且无质量提升）就停，别为迭代而迭代。
+
+## 边界
+
+- 负责：流程 JSON 的优化迭代与效果对比方法论
+- 不负责：插件引擎开发（src/ 的活）、OpenCode 本身配置问题
+- 回滚 = 用旧版 JSON 再 `workflow_define` 一个更高版本（内容抄旧版）

package/dist/workflows/index.d.ts

@@ -1,19 +0,0 @@
-/**
- * 内置 workflow 定义（P2.5）
- *
- * workflows/ 目录 = workflow 资产（id/version/description/args/entry），
- * 与 workflow/ 目录（组合子引擎）分离。新增 workflow = 新增一个定义文件 +
- * 在插件入口注册，插件工具与路由零改动。
- */
-import type { WorkflowDefinition } from "../registry/registry.js";
-/** smoke：3 路并行分析 + 汇总（P0 冒烟链） */
-export declare function smokeWorkflow(): WorkflowDefinition<{
-    topic: string;
-}>;
-/** reliable：执行 -> check -> verify -> checkpoint 可靠链（P1 验收链） */
-export declare function reliableWorkflow(options?: {
-    checkCommand?: string;
-    reviewers?: number;
-}): WorkflowDefinition<{
-    topic: string;
-}>;

package/dist/workflows/index.js

@@ -1,40 +0,0 @@
-/**
- * 内置 workflow 定义（P2.5）
- *
- * workflows/ 目录 = workflow 资产（id/version/description/args/entry），
- * 与 workflow/ 目录（组合子引擎）分离。新增 workflow = 新增一个定义文件 +
- * 在插件入口注册，插件工具与路由零改动。
- */
-import { runSmokeWorkflow } from "../workflow/smoke.js";
-import { runReliableWorkflow } from "../workflow/reliable.js";
-const TOPIC_SCHEMA = {
-    type: "object",
-    properties: {
-        topic: { type: "string", description: "分析主题" },
-    },
-    required: ["topic"],
-};
-/** smoke：3 路并行分析 + 汇总（P0 冒烟链） */
-export function smokeWorkflow() {
-    return {
-        id: "smoke",
-        version: "1.0.0",
-        description: "3 路并行分析 agent + 1 个汇总 agent（冒烟演示）",
-        args: TOPIC_SCHEMA,
-        entry: async ({ topic }) => runSmokeWorkflow(topic),
-    };
-}
-/** reliable：执行 -> check -> verify -> checkpoint 可靠链（P1 验收链） */
-export function reliableWorkflow(options) {
-    return {
-        id: "reliable",
-        version: "1.0.0",
-        description: "agent -> 确定性检查 -> 多 reviewer 语义验证 -> 人工审批 的可靠链",
-        args: TOPIC_SCHEMA,
-        entry: async ({ topic }) => runReliableWorkflow(topic, {
-            checkCommand: options?.checkCommand,
-            reviewers: options?.reviewers,
-        }),
-    };
-}
-//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAE7D,MAAM,YAAY,GAAe;IAC/B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE;KAC/C;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;CACpB,CAAA;AAED,iCAAiC;AACjC,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,EAAE,EAAE,OAAO;QACX,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,mCAAmC;QAChD,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC;KACpD,CAAA;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,gBAAgB,CAAC,OAGhC;IACC,OAAO;QACL,EAAE,EAAE,UAAU;QACd,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,gDAAgD;QAC7D,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CACzB,mBAAmB,CAAC,KAAK,EAAE;YACzB,YAAY,EAAE,OAAO,EAAE,YAAY;YACnC,SAAS,EAAE,OAAO,EAAE,SAAS;SAC9B,CAAC;KACL,CAAA;AACH,CAAC"}