@mickorz/opencode-agentic-workflow 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mickorz/opencode-agentic-workflow",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Durable Agentic Workflow Runtime for OpenCode V2: journal & resume, version registry, tracing, token/cost metrics, git worktree isolation",
   "type": "module",
   "license": "MIT",

package/skills/workflow-authoring/SKILL.md

@@ -10,7 +10,21 @@ description: >
 # workflow-authoring（代码流程编写）
 
 把用户的流程需求变成可复用的代码 workflow：**对话澄清 → 写 flows 目录
-JS 模块 → 保存即用（未知 id 自动重扫注册）→ `workflow` 工具试跑**。
+JS 模块 → 保存即用（未知 id 自动重扫注册）→ 自己调 `workflow` 工具试跑
+→ 汇报结果**。
+
+## 零语法契约（本 skill 的服务边界）
+
+**用户永远只说需求，不说工具语法。** `flow=` / `topic=` /
+`checkpointMode=` 这些参数全部由你（agent）组织：
+
+- 用户说「创建一个 workflow js：需求是 xxx」→ 你走完澄清、写文件、
+  **立即自己调用 workflow 工具试跑**（topic 从需求里取一个小而真实的
+  样例，checkpointMode 用 auto-approve）、把运行结果汇报给用户——
+  一口气做完，中途不要把工具参数丢回给用户
+- 用户以后想再跑：说人话即可（「用拼音口诀流程，词：知识库」/
+  「再跑一次发布说明，主题换成 y」）——由你翻译成工具参数
+- 需求已明确就别问；有真歧义才问，且一次问全
 
 > v0.6.0 起声明式 JSON 流程已移除（`workflow_define` 工具同步下线），
 > 自定义流程只有代码形态。历史 JSON 用 `@mickorz/opencode-agentic-workflow/core`
@@ -25,9 +39,11 @@ JS 模块 → 保存即用（未知 id 自动重扫注册）→ `workflow` 工
 
 ## 第二步：写 JS 模块（flows 目录）
 
-位置：项目 `flows/` 目录（缺省自动装载，零配置）；或 `opencode.json` 插件
-options 里 `workflows: ["<路径>"]` 显式指定（文件或目录，相对项目根）。
-扩展名 `.mjs` 推荐（`.js`/`.cjs` 也支持；引用核心 API 的 `.cjs` 会明确报错）。
+**动笔要快**：位置就是项目根下 `flows/`（缺省自动装载），或
+`opencode.json` 插件 options 里 `workflows: ["<路径>"]` 显式指定的位置——
+**不需要探测插件装在哪、npm 全局有什么**（探索超过两步还没开始写文件，
+路线就错了）。扩展名 `.mjs` 推荐（`.js`/`.cjs` 也支持；引用核心 API 的
+`.cjs` 会明确报错）。
 
 ```js
 // flows/release-notes.mjs
@@ -91,31 +107,41 @@ export default defineWorkflow({
 3. 改动已注册流程的步骤结构（stepNames 数量/顺序/语义）= **必须升
    version**（1.0.0 → 1.1.0）；旧 journal 的 resume 依赖精确版本解析
 4. `id` 不得用内置名：smoke / reliable / artifact / feature-development
-5. 模块只能用 ESM 语法导出（`export default` 或 `export const definition`）
-
-## 第三步：即时试跑（无需重启）
-
-保存文件后**直接调用 `workflow` 工具**——未知 flow id 会触发一次 flows
+5. 模块只能用 ESM 语法导出（`export default` 或 `export const definition`）；
+   `.mjs` 里**不能有 TypeScript 注解**
+6. **模块顶层只放 import / 常量 / 函数 / 导出**——不要在顶层跑数据处理
+   （建索引、初始化表等）。顶层的立即执行代码在文件后部常量初始化之前
+   运行会触发 TDZ 报错（`Cannot access 'X' before initialization`）；
+   索引/缓存一律放函数里惰性构建
+7. **不要探索插件安装位置 / npm 全局目录**——flows 模块运行在插件进程
+   内：Node 内置模块（node:fs 等）可用，**用户目录与全局的 npm 包
+   require/import 不到**（解析链上没有）。本地确定性计算需要数据
+   （拼音表/映射表/词表）时，**把数据直接内嵌进 .mjs 文件**（大表放
+   文件底部，配惰性索引）；库能力做不到的部分交给 `agent` 步
+
+## 第三步：立即试跑 + 汇报（无需重启，你自己跑，不是让用户跑）
+
+保存文件后**你直接调用 `workflow` 工具**——未知 flow id 会触发一次 flows
 目录增量重扫，刚写的模块当场注册运行（v0.6.1 起；v1「定义即注册」的
-代码形态对位）：
+代码形态对位）。参数自己组织：`flow=<id>, topic=<从需求取的小而真实样例>,
+checkpointMode=auto-approve`（headless 必传）。关注：
 
-- 成功：工具正常执行，输出带 `[<id>@<version> runId=…]`
+- 步骤是否全 completed；失败步的报错（参数缺失/文件路径/评审否决）
+- 产物是否落盘、内容是否符合预期
 - `workflow not found` 且附 `flows load errors` 清单：文件写了但没注册
   上——按指名的错误修文件再试
+- 有 `background: true` 需求时用 `workflow_control status` 轮询
 - **边界（如实）**：只有**新文件**能被重扫拾取；**改动已装载文件**
   （含升 version）需重启生效（Node ESM 缓存按路径，重导返回旧模块）。
   编辑既有流程后用 resumeRunId 前先重启
 
-## 第四步：试跑验证
+试跑通过后**用自然语言向用户汇报**（不要贴工具语法）：
 
-调用 `workflow` 工具：`flow=<id>, topic=<真实小主题>, checkpointMode=auto-approve`
-（headless 必传）。关注：
-
-- 步骤是否全 completed；失败步的报错（参数缺失/文件路径/评审否决）
-- 产物是否落盘、内容是否符合预期
-- 有 `background: true` 需求时用 `workflow_control status` 轮询
-
-试跑通过后向用户报告：流程 id、参数用法（含 args 清单）、一句话示例。
+```
+流程已创建并试跑通过：pinyin-mnemonic（中文词 -> 拼音首字母 -> 记忆口诀）
+试跑：知识库 -> ZSK，口诀「知识三点连成库」
+以后想用，直接说：「用拼音口诀流程，词：xxx」
+```
 
 ## JSON → JS 迁移映射
 
@@ -133,7 +159,8 @@ export default defineWorkflow({
 
 | 报错 | 原因与修法 |
 |------|-----------|
-| `failed to import (...Cannot find package...)` | 模块导入了用户目录解析不到的包；只用 `@mickorz/opencode-agentic-workflow/core` 与 Node 内置模块 |
+| `failed to import (...Cannot find package...)` | 模块导入了用户目录解析不到的包；只用 `@mickorz/opencode-agentic-workflow/core` 与 Node 内置模块，数据需求内嵌文件 |
+| `Cannot access 'X' before initialization` | 顶层立即执行代码跑在文件后部常量之前（TDZ）——索引/初始化移进函数惰性构建 |
 | `imports ".../core" but .cjs cannot be specifier-rewritten` | `.cjs` 引用核心 API——改名 `.mjs` |
 | `module must export a workflow` | 缺 `export default defineWorkflow({...})` |
 | `workflow.run must be a function` | 定义缺 `async run(args, ctx)` |