@mickorz/opencode-agentic-workflow 0.8.2 → 0.8.3
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.
- package/package.json +1 -1
- package/skills/workflow-authoring/SKILL.md +112 -173
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mickorz/opencode-agentic-workflow",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.3",
|
|
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",
|
|
@@ -1,37 +1,38 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: workflow-authoring
|
|
3
3
|
description: >
|
|
4
|
-
编写与自定义 opencode-agentic-workflow
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
14
|
-
|
|
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
|
|
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
|
-
## 第二步：写
|
|
43
|
+
## 第二步：写 .js 脚本（flows 目录）
|
|
43
44
|
|
|
44
45
|
**动笔要快**：位置就是项目根下 `flows/`（缺省自动装载），或
|
|
45
46
|
`opencode.json` 插件 options 里 `workflows: ["<路径>"]` 显式指定的位置——
|
|
46
47
|
**不需要探测插件装在哪、npm 全局有什么**（探索超过两步还没开始写文件，
|
|
47
|
-
|
|
48
|
-
|
|
48
|
+
路线就错了）。文件名 kebab-case（`five-sentences.js`）；`meta.name` 即
|
|
49
|
+
flow id，**必须 snake_case**（`five_sentences`）。
|
|
49
50
|
|
|
50
51
|
```js
|
|
51
|
-
// flows/release-notes.
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
- `
|
|
93
|
-
`
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
`
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
|
|
107
|
-
2.
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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
|
-
|
|
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
|
-
流程已创建并试跑通过：
|
|
148
|
-
|
|
149
|
-
|
|
145
|
+
流程已创建并试跑通过：release_notes（为主题生成一段发布说明）
|
|
146
|
+
试跑：主题「v0.8.3」→ 5 句发布说明 + 双人评审通过 + 人工批准
|
|
147
|
+
以后想用，直接说：「用发布说明流程，主题：xxx」
|
|
150
148
|
```
|
|
151
149
|
|
|
152
|
-
##
|
|
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
|
-
|
|
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" }` | `
|
|
216
|
-
| `{ pipeline: "模板 {{item}}", items }` | `await pipeline(items, [async (item) =>
|
|
217
|
-
| `{ race: ["A", "B"] }` | `race([() => agent("A"), () => agent("B")])` |
|
|
218
|
-
| `"output": "{{steps.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
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
|
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
|
|
|
234
|
-
|
|
|
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 再启动 |
|