@mickorz/opencode-agentic-workflow 0.8.2 → 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +2 -1
  2. package/dist/plugin/progress-board.d.ts +7 -1
  3. package/dist/plugin/progress-board.js +10 -2
  4. package/dist/plugin/progress-board.js.map +1 -1
  5. package/package.json +1 -1
  6. package/skills/workflow-authoring/SKILL.md +112 -173
package/README.md CHANGED
@@ -476,7 +476,8 @@ pipeline 步的第几个会话，缺省最后一个；消息取 user/assistant
476
476
  自动选择的那一个。
477
477
 
478
478
  数据链路：RunJournal 状态转换 → `run.progress` 事件总线 → ProgressBoard（容量 20，
479
- journalDir 配置时用历史 run 做种子）→ `agentic-workflow-progress` RPC。headless
479
+ journalDir 配置时用**非终态**历史 run 做种子——只浮现上次被中断的，终态 run
480
+ 不占启动面板）→ `agentic-workflow-progress` RPC。headless
480
481
  （`opencode run`）下没有 TUI 监听，转发零成本；同一份事件流也会写进 traceDir
481
482
  （`events.jsonl`），可作为无头观测替代。
482
483
 
package/dist/plugin/progress-board.d.ts CHANGED
@@ -59,6 +59,12 @@ export declare function bindProgressBoard(deps: {
59
59
  fetchSessionMessages?: (sessionID: string) => Promise<SessionReplayMessage[]>;
60
60
  options?: ProgressBoardOptions;
61
61
  }): Promise<ProgressBoard>;
62
- /** store 里的近期 run -> 快照种子（newest first，容量截断） */
62
+ /** store 里的近期 run -> 快照种子（newest first，容量截断）
63
+ *
64
+ * v0.8.4 起只播种**非终态** run（进程退出时卡在 running 的被中断 run）：
65
+ * 启动面板保持干净，只浮现「上次没跑完、值得处理」的；completed /
66
+ * failed / aborted 不再上启动面板（failed 仍可用 resumeRunId 续跑，
67
+ * 只是不占版面——见 recorder.reopen 的可续跑状态集）。
68
+ */
63
69
  export declare function seedFromStore(store: ExecutionStore, capacity?: number): Promise<RunProgressSnapshot[]>;
64
70
  export {};
package/dist/plugin/progress-board.js CHANGED
@@ -125,7 +125,8 @@ export async function bindProgressBoard(deps) {
125
125
  };
126
126
  },
127
127
  });
128
- // store 种子：面板打开时能立即看到近期历史 run（不只是本次会话的）
128
+ // store 种子（v0.8.4）：只播种非终态 run——上次被中断的才值得在启动时
129
+ // 浮现（可续跑）；终态 run 不再占版面（面板历史残留的治理）
129
130
  let seed;
130
131
  if (deps.store) {
131
132
  seed = await seedFromStore(deps.store, deps.options?.capacity ?? 20);
@@ -139,10 +140,17 @@ export async function bindProgressBoard(deps) {
139
140
  }, { ...deps.options, ...(seed ? { seed } : {}) });
140
141
  return board;
141
142
  }
142
- /** store 里的近期 run -> 快照种子（newest first，容量截断） */
143
+ /** store 里的近期 run -> 快照种子（newest first，容量截断）
144
+ *
145
+ * v0.8.4 起只播种**非终态** run（进程退出时卡在 running 的被中断 run）：
146
+ * 启动面板保持干净，只浮现「上次没跑完、值得处理」的；completed /
147
+ * failed / aborted 不再上启动面板（failed 仍可用 resumeRunId 续跑，
148
+ * 只是不占版面——见 recorder.reopen 的可续跑状态集）。
149
+ */
143
150
  export async function seedFromStore(store, capacity = 20) {
144
151
  const runs = await store.listRuns();
145
152
  return runs
153
+ .filter((run) => run.status === "running")
146
154
  .sort((a, b) => b.startedAt - a.startedAt)
147
155
  .slice(0, capacity)
148
156
  .map(toProgressSnapshot);
package/dist/plugin/progress-board.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"progress-board.js","sourceRoot":"","sources":["../../src/plugin/progress-board.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"progress-board.js","sourceRoot":"","sources":["../../src/plugin/progress-board.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EACL,WAAW,GAIZ,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,yBAAyB,GAE1B,MAAM,mBAAmB,CAAA;AAI1B,iCAAiC;AACjC,MAAM,oBAAoB,GAAG,EAAE,CAAA;AAC/B,iBAAiB;AACjB,MAAM,iBAAiB,GAAG,GAAG,CAAA;AAkB7B,MAAM,OAAO,aAAa;IAOL,IAAI;IANN,IAAI,GAAG,IAAI,GAAG,EAA+B,CAAA;IAC7C,KAAK,GAAa,EAAE,CAAA;IACpB,QAAQ,CAAQ;IACzB,WAAW,CAA0B;IAE7C,YACmB,IAAwC,EACzD,OAA8B;oBADb,IAAI;QAGrB,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAA;QACvC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;QACrC,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YACrE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,+BAA+B;IAC/B,OAAO,CAAC,KAAoB;QAC1B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc;YAAE,OAAM;QACzC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAwB,EAAE,OAA+B;QAC7D,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAA;QACxC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC/B,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QAC7B,iCAAiC;QACjC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACvB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAC3B,MAAM,EAAE,GAAG,EAAE,EAAE,SAAS,IAAI,CAAC,CAAA;YAC7B,MAAM,EAAE,GAAG,EAAE,EAAE,SAAS,IAAI,CAAC,CAAA;YAC7B,OAAO,EAAE,GAAG,EAAE,CAAA;QAChB,CAAC,CAAC,CAAA;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;YAChC,IAAI,OAAO,KAAK,SAAS;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QACtD,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAChB,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,IAAI;QACF,MAAM,GAAG,GAA0B,EAAE,CAAA;QACrC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YAChC,IAAI,GAAG;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACxB,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,OAAO;QACL,IAAI,CAAC,WAAW,EAAE,EAAE,CAAA;QACpB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;IAC9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IASvC;IACC,IAAI,KAAgC,CAAA;IACpC,MAAM,YAAY,GAAyB,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE;QAC9E,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACnE,2DAA2D;QAC3D,MAAM,EAAE,KAAK,EAAE,KAAc,EAAE,EAAE;YAC/B,MAAM,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;YAC1C,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;YAC5D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAC1C,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC/C,CAAC;QACD,iDAAiD;QACjD,OAAO,EAAE,KAAK,EAAE,KAAc,EAAE,EAAE;YAChC,MAAM,OAAO,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAA;YAChD,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,oBAAoB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBACvE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;YAC1B,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YAClD,MAAM,IAAI,GAAG,GAAG,EAAE,KAAK,CAAC,IAAI,CAC1B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CACxF,CAAA;YACD,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,CAAA;YACnC,IAAI,CAAC,UAAU;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;YACzC,MAAM,SAAS,GACb,OAAO,CAAC,KAAK,KAAK,SAAS;gBACzB,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;gBACnE,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAE,CAAA;YACxC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAA;YAC3D,OAAO;gBACL,OAAO,EAAE;oBACP,SAAS;oBACT,IAAI,EAAE,OAAO,CAAC,IAAI;oBAClB,QAAQ,EAAE,QAAQ;yBACf,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC;yBAC9B,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC;iBACtF;aACF,CAAA;QACH,CAAC;KACF,CAAC,CAAA;IACF,6CAA6C;IAC7C,kCAAkC;IAClC,IAAI,IAAuC,CAAA;IAC3C,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,IAAI,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAA;IACtE,CAAC;IACD,KAAK,GAAG,IAAI,aAAa,CACvB,CAAC,GAAG,EAAE,EAAE;QACN,KAAK,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,GAAyC,CAAC,CAAC,KAAK,CACxF,CAAC,KAAK,EAAE,EAAE;YACR,mCAAmC;YACnC,OAAO,CAAC,GAAG,CACT,kDAAkD,GAAG,CAAC,KAAK,KAAK;gBAC9D,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9D,CAAA;QACH,CAAC,CACF,CAAA;IACH,CAAC,EACD,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAC/C,CAAA;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAqB,EACrB,QAAQ,GAAG,EAAE;IAEb,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAA;IACnC,OAAO,IAAI;SACR,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC;SACzC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;SACzC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;SAClB,GAAG,CAAC,kBAAkB,CAAC,CAAA;AAC5B,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mickorz/opencode-agentic-workflow",
3
- "version": "0.8.2",
3
+ "version": "0.8.4",
4
4
  "description": "Durable Agentic Workflow Runtime for OpenCode V2: journal & resume, version registry, tracing, token/cost metrics, git worktree isolation",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/skills/workflow-authoring/SKILL.md CHANGED
@@ -1,37 +1,38 @@
1
1
  ---
2
2
  name: workflow-authoring
3
3
  description: >
4
- 编写与自定义 opencode-agentic-workflow 代码流程（JS 模块）时加载。当用户想
5
- 定义/创建一个 workflow、把某个重复流程自动化、给现有流程加步骤或参数、
6
- 放入 v1（opencode-dynamic-workflows）时代的 .js 脚本、或遇到流程装载报错
7
- 与版本冲突时使用。覆盖：需求澄清、flows 目录 JS 模块编写（含 v1 脚本
8
- legacy 直接装载）、装载注册、workflow 工具试跑验证的完整链路。
4
+ 编写与自定义 opencode-agentic-workflow 流程时加载。当用户想定义/创建一个
5
+ workflow、把某个重复流程自动化、给现有流程改逻辑或加参数、放入 .js 脚本、
6
+ 或遇到流程装载报错与版本冲突时使用。覆盖：需求澄清、flows 目录 .js 脚本
7
+ 编写、装载注册、workflow 工具试跑验证的完整链路。唯一流程形态：js 脚本
8
+ （export const meta + 魔法全局 + 顶层 return）；不创建 .mjs。
9
9
  ---
10
10
 
11
- # workflow-authoring（代码流程编写）
11
+ # workflow-authoring（流程编写 · 唯一形态：js 脚本）
12
12
 
13
- 把用户的流程需求变成可复用的代码 workflow：**对话澄清 → 写 flows 目录
14
- JS 模块 → 保存即用（未知 id 自动重扫注册）→ 自己调 `workflow` 工具试跑
15
- → 汇报结果**。
13
+ 把用户的流程需求变成可复用的 workflow：**对话澄清 → 写 flows 目录 .js
14
+ 脚本 → 保存即用（未知 id 自动重扫注册）→ 自己调 `workflow` 工具试跑 →
15
+ 汇报结果**。
16
+
17
+ > **唯一流程形态 = js 脚本**（用户产品决策，2026-10-10）：文件开头
18
+ > `export const meta = {...}`，正文用注入的魔法全局（`agent` / `parallel` /
19
+ > `phase` / `verify` / `checkpoint` / `workflow` …），结尾顶层 `return`。
20
+ > **零 import。不创建 `.mjs` / `.cjs`，不写 defineWorkflow ESM 模块**；
21
+ > 遇到旧 `.mjs` 流程：删除或改写成 js 形态。
16
22
 
17
23
  ## 零语法契约（本 skill 的服务边界）
18
24
 
19
25
  **用户永远只说需求，不说工具语法。** `flow=` / `topic=` /
20
26
  `checkpointMode=` 这些参数全部由你（agent）组织：
21
27
 
22
- - 用户说「创建一个 workflow js：需求是 xxx」→ 你走完澄清、写文件、
28
+ - 用户说「创建一个 workflow：需求是 xxx」→ 你走完澄清、写文件、
23
29
  **立即自己调用 workflow 工具试跑**（topic 从需求里取一个小而真实的
24
30
  样例，checkpointMode 用 auto-approve）、把运行结果汇报给用户——
25
31
  一口气做完，中途不要把工具参数丢回给用户
26
- - 用户以后想再跑：说人话即可（「用拼音口诀流程，词：知识库」/
32
+ - 用户以后想再跑：说人话即可（「用五句话流程，主题：晨跑」/
27
33
  「再跑一次发布说明，主题换成 y」）——由你翻译成工具参数
28
34
  - 需求已明确就别问；有真歧义才问，且一次问全
29
35
 
30
- > v0.6.0 起声明式 JSON 流程已移除（`workflow_define` 工具同步下线），
31
- > 自定义流程只有代码形态。历史 JSON 用 `@mickorz/opencode-agentic-workflow/core`
32
- > API 改写（文末有映射表）。**v0.8.0 起 v1 脚本（魔法全局 + 顶层 return）
33
- > 原生装载，不改写**（见「v1 脚本（legacy）直接装载」节）。
34
-
35
36
  ## 第一步：澄清需求（缺什么问什么，别猜）
36
37
 
37
38
  1. **目的**：这个流程产出什么？（文档/代码/评审结论/检查报告）
@@ -39,103 +40,100 @@ JS 模块 → 保存即用（未知 id 自动重扫注册）→ 自己调 `workf
39
40
  3. **参数**：除了主题 topic，还要哪些输入？（受众、语言、深度、评审标准…）
40
41
  4. **完成标准**：最后一步之后怎么判断成功？
41
42
 
42
- ## 第二步：写 JS 模块（flows 目录）
43
+ ## 第二步：写 .js 脚本（flows 目录）
43
44
 
44
45
  **动笔要快**：位置就是项目根下 `flows/`（缺省自动装载），或
45
46
  `opencode.json` 插件 options 里 `workflows: ["<路径>"]` 显式指定的位置——
46
47
  **不需要探测插件装在哪、npm 全局有什么**（探索超过两步还没开始写文件，
47
- 路线就错了）。扩展名 `.mjs` 推荐（`.js`/`.cjs` 也支持；引用核心 API 的
48
- `.cjs` 会明确报错）。
48
+ 路线就错了）。文件名 kebab-case（`five-sentences.js`）；`meta.name` 即
49
+ flow id，**必须 snake_case**（`five_sentences`）。
49
50
 
50
51
  ```js
51
- // flows/release-notes.mjs
52
- import {
53
- defineWorkflow, agent, checkpoint, verify, assert, fileExists,
54
- } from "@mickorz/opencode-agentic-workflow/core"
55
-
56
- export default defineWorkflow({
57
- id: "release-notes",
58
- version: "1.0.0",
59
- description: "一句话说明（进工具清单，给未来的你/agent 看）",
60
- argsSchema: {
61
- type: "object",
62
- properties: {
63
- topic: { type: "string", description: "主题" },
64
- audience: { type: "string", description: "受众" },
65
- },
66
- required: ["topic"],
67
- },
68
- stepNames: ["draft", "review", "gate"], // 静态声明：journal/resume 依赖步骤序号稳定
69
- async run(args, ctx) {
70
- const state = await ctx.runSteps([ // runSteps = journal 记录 + resume 前缀跳过的统一入口
71
- async () => ({
72
- draft: (await agent(
73
- `针对 ${args.topic} 为 ${args.audience ?? "团队"} 写初稿…` +
74
- "。禁止调用 workflow / workflow_metrics 工具。完成后只回复 done。",
75
- { model: "glm/glm-5.3-flash", timeoutMs: 300000, retries: 1 },
76
- )).output,
77
- }),
78
- async () => ({ review: (await verify(args.topic, { criteria: "要点完整且有结论", reviewers: 2 })).passed ? "ok" : "ng" }),
79
- async () => { await checkpoint(`「${args.topic}」初稿已生成，批准？`) },
80
- ])
81
- return { output: `定稿：${state.draft}` }
82
- },
83
- })
52
+ // flows/release-notes.js —— js 脚本完整示例
53
+ export const meta = { name: 'release_notes', description: '为主题生成一段发布说明' }
54
+
55
+ phase('起草')
56
+ let draft = await agent(
57
+ `针对「${args.topic}」写 5 句以内的发布说明，只输出正文。禁止调用 workflow / workflow_metrics 工具。`,
58
+ { label: '起草', timeoutMs: 300000, retries: 1 },
59
+ )
60
+
61
+ phase('评审')
62
+ const verdict = await verify(draft, { reviewers: 2, threshold: 0.5, lens: ['要点完整', '有明确结论'] })
63
+ if (verdict.real === false) {
64
+ phase('修订')
65
+ draft = await agent(
66
+ `修订以下发布说明，补齐结论：\n${draft}\n禁止调用 workflow / workflow_metrics 工具。`,
67
+ { label: '修订' },
68
+ )
69
+ }
70
+
71
+ const approved = await checkpoint('发布说明已就绪，批准定稿？', { label: 'gate', default: true })
72
+ return { output: approved ? draft : `${draft}（未经人工批准）` }
84
73
  ```
85
74
 
86
- **核心 API**（全部从 `@mickorz/opencode-agentic-workflow/core` 导入；
87
- 装载器会自动把该裸说明符重写为本插件实例——用户目录无需 npm 安装本包）：
88
-
89
- - `agent(prompt, opts?)` → `{ output, structured? }`；opts：`model`
90
- （"providerID/modelId"）/ `timeoutMs` / `retries` / `retryDelayMs` /
91
- `schema`（JSON-Schema 结构化输出）
92
- - `checkpoint(message)`：人工审批门——拒绝即抛错中断；headless 传
93
- `checkpointMode: "auto-approve"`
94
- - `verify(artifact, { criteria?, reviewers?, passThreshold?, lenses? })` →
95
- `{ passed, verdicts }`：语义评审；lenses = 多视角各一票
96
- - `assert(() => fileExists("out.md"), "out.md")`：确定性断言（另有
97
- `commandSuccess` / `isFile` / `isDirectory`）
98
- - 组合子：`pipeline`（条目并发 fan-out）/ `race`（竞速首胜）/ `parallel` /
99
- `sequence` / `fallback` / `retry` / `phase`
100
- - `ctx.runSteps([...])`：编排入口——每个元素一个步骤函数，返回的部分
101
- state 会累积合并；journal 记录 + resume 跳过已完成前缀都由它管
75
+ **可用全局（19 个，无需导入、直接用）**：
76
+
77
+ - `agent(prompt, opts?)` → 返回字符串；`schema` 时返回解析对象。
78
+ opts：`label` / `timeoutMs` / `retries` / `retryDelayMs` / `schema` /
79
+ `model`（"providerID/modelId"）/ `isolation: 'worktree'`（per-call 独立
80
+ worktree，结束自动拆除）；未知键 fail-loud
81
+ - 组合子：`parallel(thunks)` / `pipeline(items, stages)` /
82
+ `sequence(nodes)` / `fallback(candidates)` / `race(branches)` /
83
+ `retry(thunk, { attempts, until })`
84
+ - 质量与断言：`verify(item, { reviewers, threshold, lens })` →
85
+ `{ real, realCount, total, votes }`；`judgePanel(attempts, { judges,
86
+ rubric })` → 最高分候选；`check(cond, msg)`（通过 true；未通过按可恢复
87
+ 失败处理）；`fileExists(p)`（同步布尔）/ `commandSuccess(cmd)`（异步布尔）
88
+ - `checkpoint(msg, { label, default })` → **boolean**（批准 true / 拒绝
89
+ false，不抛错；无交互 gate 时回落 `default`，没配 default 才报错）
90
+ - `workflow(ref, subArgs?)`：子流程。ref 三形态：注册名 `'five_sentences'` /
91
+ 脚本路径 `'./x.js'` / 对象 `{ scriptPath, label }`；返回子流返回值本体
92
+ （对象可直取字段）
93
+ - 其他：`phase(name)`（阶段标记，进日志与事件）/ `log(...)` / `args` /
94
+ `console`（shim）/ `setConcurrency(n)`（警告后忽略——并发由 executor
95
+ 统一管理）
96
+
97
+ **失败语义**：一切未知错误默认**可恢复**——parallel/pipeline 槽位塌缩
98
+ `null`、sequence 停止返 `null`、fallback/race 换候选；顶层 `agent()` 失败
99
+ （超时/schema 耗尽等）也塌缩 `null` 继续跑（登记「阶段失败闸门」——下一
100
+ `phase()` 边界或 run 终检触发终止报告；fallback/race 成功吸收清空闸门）。
101
+ 只有装载期契约错误与 abort 是结构性（立即上抛）。**parallel 出 null 槽位
102
+ 要自己兜底**（见示例外的 `sentences.map(s => s ?? '兜底')` 写法）。
102
103
 
103
104
  **必守纪律（违反 = 事故）**：
104
105
 
105
- 1. 每个 `agent` prompt **必须以「禁止调用 workflow / workflow_metrics 工具」
106
- 收尾**——子 agent 递归调工作流会自饿死并发信号量
107
- 2. `args` 里用到的参数都要在 `argsSchema.properties` 声明；`topic` 恒有
108
- （工具自动传）
109
- 3. 改动已注册流程的步骤结构（stepNames 数量/顺序/语义）= **必须升
110
- version**（1.0.0 → 1.1.0）；旧 journal 的 resume 依赖精确版本解析
111
- 4. `id` 不得用内置名：smoke / reliable / artifact / feature-development
112
- 5. 模块只能用 ESM 语法导出（`export default` 或 `export const definition`）；
113
- `.mjs` 里**不能有 TypeScript 注解**
114
- 6. **模块顶层只放 import / 常量 / 函数 / 导出**——不要在顶层跑数据处理
115
- （建索引、初始化表等）。顶层的立即执行代码在文件后部常量初始化之前
116
- 运行会触发 TDZ 报错（`Cannot access 'X' before initialization`）；
117
- 索引/缓存一律放函数里惰性构建
118
- 7. **不要探索插件安装位置 / npm 全局目录**——flows 模块运行在插件进程
119
- 内：Node 内置模块（node:fs 等）可用，**用户目录与全局的 npm 包
120
- require/import 不到**（解析链上没有）。本地确定性计算需要数据
121
- （拼音表/映射表/词表）时，**把数据直接内嵌进 .mjs 文件**（大表放
122
- 文件底部，配惰性索引）；库能力做不到的部分交给 `agent` 步
106
+ 1. 每个 `agent` prompt **必须以「禁止调用 workflow / workflow_metrics
107
+ 工具」收尾**——子 agent 递归调工作流会自饿死并发信号量
108
+ 2. **脚本内禁止 static `import`、禁止除 meta 外的任何 `export`**（装载期
109
+ 明确报错）。数据需求（拼音表/词表/映射表）**直接内嵌进 .js 文件**（大表
110
+ 放文件底部）；库能力做不到的部分交给 `agent` 步
111
+ 3. `meta.name`（snake_case）即 flow id，不得撞内置名：`smoke` /
112
+ `reliable` / `artifact` / `feature-development`；version 固定 `1.0.0`，
113
+ 无需声明
114
+ 4. `.js` 里**不能有 TypeScript 注解**（纯 JavaScript）
115
+ 5. 嵌套子流程只用 `workflow()` 全局；**绝不让子 agent 去调 workflow 工具**
116
+ 6. `args` 恒有 `topic`（工具自动传）；其他参数直接 `args.xxx` 读，由你
117
+ 调用时组织进 args
118
+ 7. **不要探索插件安装位置 / npm 全局目录**——脚本运行在插件进程内，
119
+ 用户目录与全局的 npm 包一概 import 不到（反正也不许 import）
120
+ 8. journal 动态记叶子步骤（每个 agent / checkpoint / subflow 各一步）；
121
+ resume = 整体重跑（无前缀跳过）
123
122
 
124
123
  ## 第三步：立即试跑 + 汇报（无需重启，你自己跑，不是让用户跑）
125
124
 
126
125
  保存文件后**你直接调用 `workflow` 工具**——未知 flow id 会触发一次 flows
127
- 目录增量重扫，刚写的模块当场注册运行（v0.6.1 起；v1「定义即注册」的
128
- 代码形态对位）。参数自己组织：`flow=<id>, topic=<从需求取的小而真实样例>,
129
- checkpointMode=auto-approve`（headless 必传）。关注：
126
+ 目录增量重扫，刚写的脚本当场注册运行。参数自己组织：`flow=<meta.name>,
127
+ topic=<从需求取的小而真实样例>, checkpointMode=auto-approve`（headless
128
+ 必传）。关注：
130
129
 
131
130
  - 步骤是否全 completed；失败步的报错（参数缺失/文件路径/评审否决）
132
131
  - 产物是否落盘、内容是否符合预期
133
132
  - `workflow not found` 且附 `flows load errors` 清单：文件写了但没注册
134
133
  上——按指名的错误修文件再试
135
134
  - 有 `background: true` 需求时用 `workflow_control status` 轮询
136
- - **边界（如实）**：只有**新文件**能被重扫拾取；**改动已装载文件**
137
- （含升 version）需重启生效（Node ESM 缓存按路径，重导返回旧模块）。
138
- 编辑既有流程后用 resumeRunId 前先重启
135
+ - **边界（如实）**：只有**新文件**能被重扫拾取；**改动已装载文件**需重启
136
+ 生效（Node ESM 缓存按路径，重导返回旧模块）
139
137
  - **新开聊天 ≠ 重启进程**：skill 每次会话从磁盘重读，**插件随 opencode
140
138
  进程加载一次就冻结**。重扫没拾取、available 里连老文件都缺 = 宿主
141
139
  进程是老的：看报错里的 `plugin v…`，与安装版本不符就提示用户
@@ -144,94 +142,35 @@ checkpointMode=auto-approve`（headless 必传）。关注：
144
142
  试跑通过后**用自然语言向用户汇报**（不要贴工具语法）：
145
143
 
146
144
  ```
147
- 流程已创建并试跑通过：pinyin-mnemonic（中文词 -> 拼音首字母 -> 记忆口诀）
148
- 试跑：知识库 -> ZSK，口诀「知识三点连成库」
149
- 以后想用，直接说：「用拼音口诀流程，词：xxx」
145
+ 流程已创建并试跑通过：release_notes（为主题生成一段发布说明）
146
+ 试跑：主题「v0.8.3」→ 5 句发布说明 + 双人评审通过 + 人工批准
147
+ 以后想用，直接说：「用发布说明流程，主题：xxx」
150
148
  ```
151
149
 
152
- ## v1 脚本（legacy）直接装载
153
-
154
- **用户给了 opencode-dynamic-workflows（v1）时代的 .js 脚本？原样放进
155
- flows/ 目录即可，绝不改写。** 识别条件：文件含 `export const meta = {...}`
156
- 且不含 `defineWorkflow`。装载后与 v2 流程同权（同一 workflow 工具调用、
157
- journal、TUI 面板、metrics）。
158
-
159
- ```js
160
- // flows/smoke-test.js —— v1 脚本原样
161
- export const meta = { name: 'smoke_test', description: '最小冒烟' }
162
-
163
- phase('Scan')
164
- const info = await agent('列出当前目录下的文件')
165
-
166
- phase('Echo')
167
- const results = await parallel([
168
- () => agent('说明工作流编排'),
169
- () => agent('说明确定性重放'),
170
- ])
171
- return { info, results }
172
- ```
150
+ ## 旧 JSON → js 迁移映射
173
151
 
174
- 可用全局（19 个，v1 全集）：`agent(prompt, {label, timeoutMs, retries,
175
- retryDelayMs, schema, model, isolation, agentType, tier})`（返回字符串；
176
- schema 时返回解析对象）、`parallel` / `pipeline` / `sequence` / `fallback` /
177
- `race`、`check(cond, msg)`、`fileExists(p)`（同步）/ `commandSuccess(cmd)`、
178
- `phase` / `log` / `args` / `setConcurrency` / `verify` / `judgePanel` /
179
- `retry` / `checkpoint(msg, {label, default})`（返回 boolean）/
180
- `workflow(ref, args)`（子流程，ref 三形态：注册名 / 脚本路径
181
- `'./x.js'` / 对象 `{scriptPath, label}`；返回子流返回值本体——对象可直取
182
- 字段）/ `console`。
183
-
184
- **失败语义（v1 对位）**：v1 默认**一切未知错误可恢复**（AGENT_FAILED）——
185
- parallel/pipeline 塌缩 `null`、sequence 停止返 `null`、fallback/race 换
186
- 候选；顶层 `agent()` 失败（超时/schema 耗尽等）也塌缩 `null` 继续跑
187
- （登记「阶段失败闸门」——下一 `phase()` 边界或 run 终检触发终止报告；
188
- fallback/race 成功吸收清空闸门）。只有适配层契约错误与 abort 是结构性
189
- （立即上抛，不塌缩）。
190
-
191
- **agent 选项**：`isolation: 'worktree'` per-call 独立 worktree（结束自动
192
- 拆除，非 git 目录响亮降级共享目录）；`agentType` / `tier` 响亮警告后降级
193
- （v2 无调用级对位）；未知选项键 fail-loud。
194
-
195
- 与 v1 的已知差异（fail-loud，不静默）：
196
- - `setConcurrency(n)`：v2 并发由 executor 统一管理——警告后忽略
197
- - `phase()` 只进日志与事件（v2 TUI 无阶段分组；步骤行 = 叶子调用）
198
- - resume = 整体重跑（v1 脚本无静态步骤序，无前缀跳过）
199
- - **chain 式工具嵌套**（子 agent 调 workflow 工具的 scriptPath）不被
200
- 支持——v2 工具拒绝 run 内调用（防信号量自饿死）；嵌套用 `workflow()`
201
- - meta.name（snake_case）即 flow id；固定 version 1.0.0
202
- - 脚本内不能有 static `import` / 除 meta 外的 `export`（装载期明确报错）
203
-
204
- **选型**：新流程默认写 v2 `.mjs`（类型清晰、argsSchema 进工具 hint、
205
- resume 支持步骤跳过）；v1 脚本直接放进来跑，或用户明确要 v1 风格时才写
206
- v1 形态。
207
-
208
- ## JSON → JS 迁移映射
209
-
210
- | 旧 JSON 步骤 | 代码写法 |
152
+ | 旧 JSON 步骤 | js 脚本写法 |
211
153
  |------|------|
212
154
  | `{ agent: "提示 {{topic}}" }` | `agent(\`提示 ${args.topic}\`)` |
213
- | `{ checkpoint: "批准？" }` | `await checkpoint("批准？")` |
214
- | `{ verify: { artifact, criteria } }` | `await verify(artifact, { criteria })` |
215
- | `{ fileExists: "out.md" }` | `await assert(() => fileExists("out.md"), "out.md")` |
216
- | `{ pipeline: "模板 {{item}}", items }` | `await pipeline(items, [async (item) => (await agent(\`模板 ${item}\`)).output])` |
217
- | `{ race: ["A", "B"] }` | `race([() => agent("A"), () => agent("B")])` |
218
- | `"output": "{{steps.draft}}"` | run 末尾 `return { output: state.draft }` |
155
+ | `{ checkpoint: "批准？" }` | `await checkpoint("批准？")`（返回 boolean，拒绝不抛错） |
156
+ | `{ verify: { artifact, criteria } }` | `await verify(artifact, { lens: criteria })`，看 `verdict.real` |
157
+ | `{ fileExists: "out.md" }` | `if (!fileExists("out.md")) …`（同步布尔） |
158
+ | `{ pipeline: "模板 {{item}}", items }` | `await pipeline(items, [async (item) => agent(\`模板 ${item}\`)])` |
159
+ | `{ race: ["A", "B"] }` | `await race([() => agent("A"), () => agent("B")])` |
160
+ | `"output": "{{steps.draft}}"` | 末尾 `return { output: draft }` |
219
161
 
220
162
  ## 常见报错速查
221
163
 
222
164
  | 报错 | 原因与修法 |
223
165
  |------|-----------|
224
- | `failed to import (...Cannot find package...)` | 模块导入了用户目录解析不到的包；只用 `@mickorz/opencode-agentic-workflow/core` 与 Node 内置模块，数据需求内嵌文件 |
225
- | `Cannot access 'X' before initialization` | 顶层立即执行代码跑在文件后部常量之前（TDZ）——索引/初始化移进函数惰性构建 |
226
- | `imports ".../core" but .cjs cannot be specifier-rewritten` | `.cjs` 引用核心 API——改名 `.mjs` |
227
- | `module must export a workflow` | 缺 `export default defineWorkflow({...})` |
228
- | `workflow.run must be a function` | 定义缺 `async run(args, ctx)` |
229
- | `JSON workflows were removed in v0.6.0` | flows 目录里还有 .json——按上面映射表改写成 JS |
230
- | `legacy script ... cannot use static import` | v1 脚本里写了 import——全局是注入的；需要导入就转 v2 .mjs |
231
- | `legacy scripts may only contain export const meta` | v1 脚本多余的 export——去掉或转 v2 .mjs |
232
- | `meta.name must be a non-empty snake_case string` | v1 meta.name 形状不对（如含 `-`）——改成 snake_case |
233
- | `workflow not found` + `flows load errors` 清单 | 文件没注册上：按指名错误修文件（语法/形状/保留 id/解析失败）直接重试，无需重启 |
234
- | 改了已注册流程但不生效 | 已装载文件的修改（含升 version）需重启；新文件才能被重扫即时拾取 |
235
- | `id "..." is reserved by a built-in` | 换个 id |
236
- | `duplicate <id>@<version>` | 同版本已从别的文件装载——删一处或升 version |
237
- | verify 返回 `passed: false` | 评审语义否决——改产物质量或放宽 criteria，不是 bug |
166
+ | `legacy script ... cannot use static import` | 脚本里写了 import——19 个全局是注入的；数据需求内嵌文件 |
167
+ | `legacy scripts may only contain export const meta` | 多余的 export——去掉（唯一导出就是 meta） |
168
+ | `meta.name must be a non-empty snake_case string` | id 形状不对（如 `five-sentences`）——改 `five_sentences` |
169
+ | `JSON workflows were removed in a v0.6.0` | flows 目录里还有 .json——按上面映射表改写成 js 脚本 |
170
+ | 手滑写成了 `.mjs` / defineWorkflow 模块 | 唯一形态是 js 脚本：删除重写（用户产品决策 2026-10-10） |
171
+ | `workflow not found` + `flows load errors` 清单 | 文件没注册上：按指名错误修文件（语法/形状/保留 id）直接重试，无需重启 |
172
+ | 改了已注册流程但不生效 | 已装载文件的修改需重启；新文件才能被重扫即时拾取 |
173
+ | `id "..." is reserved by a built-in` | 换个 id（内置：smoke / reliable / artifact / feature-development） |
174
+ | `duplicate <id>@1.0.0` | 同名 id 已从别的文件装载——删一处或改名 |
175
+ | verify 返回 `real: false` / parallel 出现 `null` 槽位 | 语义否决 / 可恢复失败塌缩（设计行为）——改质量、放宽标准，或代码里对 null 兜底 |
176
+ | 新开聊天后 skill 是新的但流程列表是旧的 | 插件随宿主进程加载一次就冻结——完全退出 opencode 再启动 |