@dai_ming/plugin-deliverables 1.0.19 → 1.0.21

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 (11) hide show
  1. package/INSTALL.md +6 -6
  2. package/README.md +15 -12
  3. package/agents-rules/deliverables.md +16 -14
  4. package/index.js +840 -8
  5. package/mcp-servers/deliverables.js +130 -32
  6. package/openclaw-plugin.json +1 -1
  7. package/openclaw.plugin.json +1 -1
  8. package/package.json +6 -2
  9. package/skills/deliverables/SKILL.md +7 -0
  10. package/test/index.test.js +100 -0
  11. package/test/mcp-server.test.js +44 -0
package/INSTALL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # plugin-deliverables 安装文档
2
2
 
3
- 本文档描述 `@dai_ming/plugin-deliverables@1.0.16` 的安装、升级与验证方式。
3
+ 本文档描述 `@dai_ming/plugin-deliverables@1.0.21` 的安装、升级与验证方式。
4
4
 
5
5
  ## 1. 目标
6
6
 
@@ -22,7 +22,7 @@
22
22
  适用于已经支持 `openclaw plugins install` 的运行环境。
23
23
 
24
24
  ```bash
25
- openclaw plugins install @dai_ming/plugin-deliverables@1.0.16 --pin
25
+ openclaw plugins install @dai_ming/plugin-deliverables@1.0.21 --pin
26
26
  openclaw plugins enable plugin-deliverables
27
27
  ```
28
28
 
@@ -47,7 +47,7 @@ openclaw plugins list
47
47
 
48
48
  ```yaml
49
49
  installPlugins:
50
- - "@dai_ming/plugin-deliverables@1.0.16"
50
+ - "@dai_ming/plugin-deliverables@1.0.21"
51
51
  ```
52
52
 
53
53
  Helm 初始化时会自动完成：
@@ -66,8 +66,8 @@ Helm 初始化时会自动完成：
66
66
  ```bash
67
67
  mkdir -p /home/node/.openclaw/extensions-extra/plugin-deliverables
68
68
  cd /tmp
69
- npm pack @dai_ming/plugin-deliverables@1.0.16 --registry https://registry.npmjs.org
70
- tar xzf dai_ming-plugin-deliverables-1.0.16.tgz \
69
+ npm pack @dai_ming/plugin-deliverables@1.0.21 --registry https://registry.npmjs.org
70
+ tar xzf dai_ming-plugin-deliverables-1.0.21.tgz \
71
71
  -C /home/node/.openclaw/extensions-extra/plugin-deliverables \
72
72
  --strip-components=1
73
73
  ```
@@ -212,5 +212,5 @@ cat /home/node/.openclaw/extensions-extra/plugin-deliverables/package.json
212
212
  必须是：
213
213
 
214
214
  ```json
215
- { "version": "1.0.16" }
215
+ { "version": "1.0.21" }
216
216
  ```
package/README.md CHANGED
@@ -24,17 +24,18 @@ OpenClaw 交付物插件 — 让 AI Agent 将生成的文件（文章、HTML 页
24
24
  现在这个包同时支持 OpenClaw 原生插件加载。也就是说，除了网关侧用 `openclaw-plugin.json` 注入 MCP/skill/AGENTS 规则外，OpenClaw 还会读取 `openclaw.plugin.json` + `index.js`，把运行时 hook 也一并启用。
25
25
 
26
26
  ```bash
27
- openclaw plugins install @dai_ming/plugin-deliverables@1.0.16 --pin
27
+ openclaw plugins install @dai_ming/plugin-deliverables@1.0.21 --pin
28
28
  openclaw plugins enable plugin-deliverables
29
29
  ```
30
30
 
31
31
  这一步启用后，插件会额外提供三层兜底：
32
32
 
33
33
  1. `before_prompt_build`：把“交付物必须 upload-first”的硬规则注入到主 agent 和子 agent 的系统上下文
34
- 2. `before_tool_call`：阻止通过 `message` 附件字段直接发文件
35
- 3. `message_sending`：如果仍然有媒体/文件旁路发送，最终发送前直接取消
34
+ 2. `before_tool_call`：记录 `write` 生成的工作区文件，并阻止通过 `message` 附件字段直接发文件
35
+ 3. Palz 出站补丁：最终消息发送前扫描内部工作区路径/近期写入文件，自动上传为交付物并改写成 gateway 链接
36
+ 4. `message_sending`：如果仍然有媒体/文件旁路发送，最终发送前直接取消
36
37
 
37
- > 注意：`message_sending` 只能改文本或取消发送，不能自动把错误发送重写成 `upload_deliverable`。所以它的职责是“兜底阻断”，不是“自动修正”。
38
+ > 注意：非 Palz 渠道仍以 `before_prompt_build` + `before_tool_call` + `message_sending` 兜底为主；Palz 渠道具备自动上传和文本改写能力。
38
39
 
39
40
  ### 方式一：通过 claw-gateway Helm 部署（推荐）
40
41
 
@@ -43,11 +44,11 @@ openclaw plugins enable plugin-deliverables
43
44
  ```yaml
44
45
  # values.yaml（或 claw-gateway 管理界面的 Helm 参数）
45
46
  installPlugins:
46
- - "@dai_ming/plugin-deliverables@1.0.16"
47
+ - "@dai_ming/plugin-deliverables@1.0.21"
47
48
  ```
48
49
 
49
50
  initContainer 执行顺序：
50
- 1. **Phase 3**：`npm pack @dai_ming/plugin-deliverables@1.0.16` 下载 tarball → 解压到 `/data/extensions-extra/plugin-deliverables/`
51
+ 1. **Phase 3**：`npm pack @dai_ming/plugin-deliverables@1.0.21` 下载 tarball → 解压到 `/data/extensions-extra/plugin-deliverables/`
51
52
  2. **Phase 3b**：在插件目录执行 `npm install --omit=dev`（本插件无运行时依赖，此步骤跳过）
52
53
  3. **Phase 3e**：读取 `openclaw-plugin.json` 清单，自动：
53
54
  - 复制 `mcp-servers/deliverables.js` → `/data/mcp-servers/deliverables.js`
@@ -182,8 +183,9 @@ fi
182
183
  | `group_id` | string | — | 群聊 ID |
183
184
  | `user_id` | string | — | 用户 ID |
184
185
  | `content_text` | string | — | 文本内容（单文件场景） |
185
- | `content_base64` | string | — | Base64 编码的二进制内容（单文件场景） |
186
- | `files` | array | — | 多文件列表（游戏/站点场景，优先使用） |
186
+ | `content_base64` | string | — | Base64 编码的二进制内容（单文件场景）；工具会清理空白并校验格式 |
187
+ | `file_path` | string | — | 本地文件路径，推荐用于 PDF/PPT/图片/zip 等二进制文件，工具会读取并自动编码 |
188
+ | `files` | array | — | 多文件列表（游戏/站点场景，优先使用），每项可传 `content_text`、`content_base64` 或 `file_path` |
187
189
 
188
190
  返回值包含 `preview_url`、`download_url`、`reply_markdown`（可直接附在回复消息中）。
189
191
 
@@ -196,12 +198,13 @@ fi
196
198
  | Hook | 作用 |
197
199
  |------|------|
198
200
  | `before_prompt_build` | 把“生成文件必须走交付物上传”的硬规则注入系统上下文，覆盖主 agent 和子 agent |
199
- | `before_tool_call` | 阻止通过 `message` 工具的 `media/path/filePath/buffer` 等字段直接发送文件 |
201
+ | `before_tool_call` | 记录 `write` 生成的工作区文件；阻止通过 `message` 工具的 `media/path/filePath/buffer` 等字段直接发送文件 |
202
+ | Palz 出站补丁 | 扫描最终消息中的 `/data/workspace-*`、`output/*.ext`、反引号文件名等工作区文件引用，自动上传后替换为交付物链接 |
200
203
  | `message_sending` | 如果上游仍然产生了媒体/文件旁路发送，在最终出站前直接取消 |
201
204
 
202
- 这三层一起工作的目标是：即使 prompt 漂移，也尽量把“message + file/media”这条旁路堵住，统一收敛到 `deliverables__upload_deliverable`。
205
+ 这些兜底一起工作的目标是：即使 prompt 漂移，也尽量把“工作区路径 / message + file/media”这类旁路堵住，统一收敛到 gateway 交付物链接。
203
206
 
204
- 另外，Palz 渠道下如果交付物回复会被拆成“内容简介 + 最终链接”两条消息，runtime plugin 还会分别打印这两次真实 HTTP 发送的 request/response 日志，便于直接从 pod stdout 排查。
207
+ 另外，Palz 渠道下如果交付物回复包含可信 gateway 交付物链接，会被拆成“内容简介 + 最终链接”两条消息；任意外部 URL 或非 gateway OSS URL 不会被包装成 `file_url` 文件消息。runtime plugin 还会分别打印这两次真实 HTTP 发送的 request/response 日志，便于直接从 pod stdout 排查。
205
208
 
206
209
  ---
207
210
 
@@ -223,7 +226,7 @@ npm publish --registry https://registry.npmjs.org --access public
223
226
 
224
227
  | claw-gateway 版本 | plugin 版本 |
225
228
  |-------------------|-------------|
226
- | 当前 | 1.0.16 |
229
+ | 当前 | 1.0.21 |
227
230
 
228
231
  ---
229
232
 
package/agents-rules/deliverables.md CHANGED
@@ -54,24 +54,26 @@ Tool name note:
54
54
  1. Create content under current agent workspace `output/` directory first (for example `output/report.md`), then call the deliverables upload tool exposed in this session.
55
55
  2. If you need to use the `write` tool, the target path MUST be inside `output/`. Never write deliverable files to the workspace root.
56
56
  3. If you already wrote the file to the wrong place, move/copy it into `output/` before finalizing the task and before describing the saved path to the user.
57
- 4. If format is HTML, prefer `type=article` and file name ends with `.html`.
58
- 5. Every single-file deliverable MUST use a file name with an explicit extension.
59
- 6. If format is markdown/text, use `type=article` and `.md`/`.txt`.
60
- 7. If the user did not specify a document/text format, default to Markdown and use a `.md` file name.
61
- 8. For multi-file deliverables (game/site), you MUST prefer `type=game` with `files[]`, keep files as a folder structure, and do NOT zip before upload unless the user explicitly asks for a zip package.
62
- 9. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
63
- 10. If a generated project requires starting a separate backend service, custom port, database, or long-running process to work, do NOT pretend the deliverables preview can run it. Tell the user that deliverables preview only supports static output, and that runtime projects need deployment/ingress instead.
64
- 11. After successful upload, the final assistant message MUST start with 1-2 short sentences in your own words, briefly describing what you generated for the user.
65
- 12. The intro must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
66
- 13. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines.
67
- 14. Otherwise final reply MUST include Markdown links (short label + full URL target):
57
+ 4. For binary deliverables such as PDF, PPT, images, video, or zip files, pass `file_path` pointing at the file under `output/`; do not paste shell output or partial base64 into `content_base64`.
58
+ 5. If the upload tool returns an error, retry with a valid `file_path` or report the upload failure. Never invent OSS, preview, or download URLs.
59
+ 6. If format is HTML, prefer `type=article` and file name ends with `.html`.
60
+ 7. Every single-file deliverable MUST use a file name with an explicit extension.
61
+ 8. If format is markdown/text, use `type=article` and `.md`/`.txt`.
62
+ 9. If the user did not specify a document/text format, default to Markdown and use a `.md` file name.
63
+ 10. For multi-file deliverables (game/site), you MUST prefer `type=game` with `files[]`, keep files as a folder structure, and do NOT zip before upload unless the user explicitly asks for a zip package.
64
+ 11. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
65
+ 12. If a generated project requires starting a separate backend service, custom port, database, or long-running process to work, do NOT pretend the deliverables preview can run it. Tell the user that deliverables preview only supports static output, and that runtime projects need deployment/ingress instead.
66
+ 13. After successful upload, the final assistant message MUST start with 1-2 short sentences in your own words, briefly describing what you generated for the user.
67
+ 14. The intro must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
68
+ 15. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines.
69
+ 16. Otherwise final reply MUST include Markdown links (short label + full URL target):
68
70
  `预览链接：[点击预览](<full_url>)`
69
71
  `下载链接：[点击下载](<full_url>)`
70
- 15. For multi-file/game deliverables, if the tool gives directory-style output, the second line may be:
72
+ 17. For multi-file/game deliverables, if the tool gives directory-style output, the second line may be:
71
73
  `文件列表：[查看目录](<full_url>)`
72
74
  Keep that format instead of forcing a zip link.
73
- 16. Do NOT only say "已保存到工作空间".
74
- 17. Do NOT append workspace path or a raw URL block after the Markdown links.
75
+ 18. Do NOT only say "已保存到工作空间".
76
+ 19. Do NOT append workspace path or a raw URL block after the Markdown links.
75
77
 
76
78
  ### Exception
77
79