@dai_ming/plugin-deliverables 1.0.14 → 1.0.15

package/INSTALL.md

@@ -0,0 +1,215 @@
+# plugin-deliverables 安装文档
+
+本文档描述 `@dai_ming/plugin-deliverables@1.0.15` 的安装、升级与验证方式。
+
+## 1. 目标
+
+安装完成后，插件应同时提供三类能力：
+
+1. MCP 工具：`deliverables__upload_deliverable`
+2. Prompt/Skill 注入：自动把文档类产物收敛到交付物上传流程
+3. Runtime Hook 兜底：
+   - `before_prompt_build`
+   - `before_tool_call`
+   - `message_sending`
+
+也就是说，这个版本不只是“把上传工具装进去”，还会阻止 `message + file/media` 这种旁路发送。
+
+## 2. 推荐安装方式
+
+### 2.1 通过 OpenClaw 原生插件安装
+
+适用于已经支持 `openclaw plugins install` 的运行环境。
+
+```bash
+openclaw plugins install @dai_ming/plugin-deliverables@1.0.15 --pin
+openclaw plugins enable plugin-deliverables
+```
+
+安装后建议检查：
+
+```bash
+openclaw plugins info plugin-deliverables
+openclaw plugins list
+```
+
+确认点：
+
+- 插件 id 为 `plugin-deliverables`
+- 入口文件为 `index.js`
+- 插件状态为 `enabled`
+
+### 2.2 通过 claw-gateway Helm 参数安装
+
+适用于当前我们这套 pod 生成链路。
+
+在 release 的插件列表中加入：
+
+```yaml
+installPlugins:
+  - "@dai_ming/plugin-deliverables@1.0.15"
+```
+
+Helm 初始化时会自动完成：
+
+1. `npm pack` 下载插件
+2. 解压到扩展目录
+3. 读取 `openclaw-plugin.json` 注入 MCP / skills / AGENTS 规则
+4. 由 OpenClaw 读取 `openclaw.plugin.json` + `index.js` 激活 runtime hooks
+
+## 3. 手动安装方式
+
+适用于需要在单个 pod 内热修验证的场景。
+
+### 3.1 下载与解压
+
+```bash
+mkdir -p /home/node/.openclaw/extensions-extra/plugin-deliverables
+cd /tmp
+npm pack @dai_ming/plugin-deliverables@1.0.15 --registry https://registry.npmjs.org
+tar xzf dai_ming-plugin-deliverables-1.0.15.tgz \
+  -C /home/node/.openclaw/extensions-extra/plugin-deliverables \
+  --strip-components=1
+```
+
+### 3.2 安装 MCP 脚本
+
+```bash
+mkdir -p /home/node/.openclaw/mcp-servers
+cp /home/node/.openclaw/extensions-extra/plugin-deliverables/mcp-servers/deliverables.js \
+   /home/node/.openclaw/mcp-servers/deliverables.js
+```
+
+### 3.3 安装 Skill
+
+```bash
+mkdir -p /home/node/.openclaw/workspace/skills/deliverables
+cp /home/node/.openclaw/extensions-extra/plugin-deliverables/skills/deliverables/SKILL.md \
+   /home/node/.openclaw/workspace/skills/deliverables/SKILL.md
+```
+
+### 3.4 注入 AGENTS 规则
+
+```bash
+AGENTS=/home/node/.openclaw/workspace/AGENTS.md
+RULES=/home/node/.openclaw/extensions-extra/plugin-deliverables/agents-rules/deliverables.md
+
+node - <<'NODE'
+const fs = require("fs");
+const agents = process.env.AGENTS;
+const rules = process.env.RULES;
+const block = fs.readFileSync(rules, "utf8").trim();
+let body = "";
+try {
+  body = fs.readFileSync(agents, "utf8");
+} catch {
+  body = "";
+}
+const re = /<!--\s*DELIVERABLE_LINK_RULES_START\s*-->[\s\S]*?<!--\s*DELIVERABLE_AUTO_UPLOAD_RULES_END\s*-->/g;
+const next = re.test(body) ? body.replace(re, block) : `${body.trim()}\n\n${block}\n`.trimStart();
+fs.writeFileSync(agents, `${next.replace(/\s*$/, "")}\n`);
+NODE
+```
+
+执行前先导出环境变量：
+
+```bash
+export AGENTS=/home/node/.openclaw/workspace/AGENTS.md
+export RULES=/home/node/.openclaw/extensions-extra/plugin-deliverables/agents-rules/deliverables.md
+```
+
+### 3.5 启用 runtime plugin
+
+确保 OpenClaw 配置里存在：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "plugin-deliverables": {}
+    }
+  }
+}
+```
+
+如果运行环境支持 `openclaw plugins install/enable`，优先使用原生命令；否则要确保插件目录在 OpenClaw 可扫描的 extensions 路径下。
+
+## 4. 升级后的验证清单
+
+### 4.1 文件级验证
+
+确认插件目录内存在：
+
+```bash
+ls -la /home/node/.openclaw/extensions-extra/plugin-deliverables
+```
+
+必须看到：
+
+- `index.js`
+- `openclaw.plugin.json`
+- `openclaw-plugin.json`
+- `mcp-servers/deliverables.js`
+
+### 4.2 Prompt/Skill 验证
+
+确认：
+
+```bash
+rg -n "DELIVERABLE_LINK_RULES_START|DELIVERABLE_AUTO_UPLOAD_RULES_START" /home/node/.openclaw/workspace/AGENTS.md
+ls -la /home/node/.openclaw/workspace/skills/deliverables
+```
+
+### 4.3 行为验证
+
+建议发两类请求：
+
+1. 文档类
+   - `帮我写一篇关于卡卡的介绍，生成 Markdown 并保存为交付物`
+2. 多文件类
+   - `做一个简单静态网页小游戏，并保存为交付物`
+
+预期结果：
+
+1. 第一条回复：模型自己的简短内容介绍
+2. 第二条回复：纯一个 https 链接
+3. 不再出现 `message + file_url/media` 的旁路发送
+
+## 5. 常见问题
+
+### 5.1 安装后工具没出来
+
+检查：
+
+```bash
+ls /home/node/.openclaw/mcp-servers
+cat /home/node/.openclaw/openclaw.json
+```
+
+确认：
+
+- `deliverables.js` 已复制
+- `mcp.servers.deliverables` 已存在
+- `tools.allow` 未把 `deliverables__upload_deliverable` 拦掉
+
+### 5.2 文档还是只保存工作区，不上传
+
+优先检查：
+
+1. `AGENTS.md` 是否有 deliverables 规则块
+2. `skills/deliverables/SKILL.md` 是否存在
+3. runtime plugin 是否被实际加载
+
+### 5.3 第二条消息不是纯链接
+
+这是上层 prompt 或插件旧版本未生效的典型现象。先确认实际安装版本：
+
+```bash
+cat /home/node/.openclaw/extensions-extra/plugin-deliverables/package.json
+```
+
+必须是：
+
+```json
+{ "version": "1.0.15" }
+```

package/README.md

@@ -1,152 +1,248 @@
 # @dai_ming/plugin-deliverables
 
-OpenClaw 交付物插件。安装后会把交付物 MCP、skill、AGENTS 规则和 `openclaw.json` 配置一次性落到运行目录里，让 Agent 默认把生成文件上传成可访问的交付物链接。
+OpenClaw 交付物插件 — 让 AI Agent 将生成的文件（文章、HTML 页面、多文件游戏/网站、图片等）自动上传到 OSS，并在会话消息中回显可点击的预览/下载链接。
 
-当前版本增强点：
+---
 
-- 上传成功后返回标准 Markdown 链接块；同时通过运行时补丁把 palz-connector 中的“简介 + 链接”交付物回复拆成两条独立消息
-- 单文件交付物会尽量保留原始文件后缀；如果模型漏掉后缀，插件会按内容类型自动补齐（如 `.md` / `.html`）
-
-## 包内文件
+## 插件包含什么
 
 | 文件 | 作用 |
 |------|------|
-| `install.js` | 安装器：负责复制插件、注册 MCP、安装 skill、注入 AGENTS 规则、补齐 `plugins.allow`、清 session，并刷新旧的 deliverables MCP 进程 |
-| `mcp-servers/deliverables.js` | MCP Server，暴露 `upload_deliverable` |
-| `skills/deliverables/SKILL.md` | 约束模型优先走交付物上传，并统一写到 `output/` |
-| `agents-rules/deliverables.md` | 注入到 `AGENTS.md` 的强约束规则 |
-| `openclaw-plugin.json` | 兼容当前安装脚本的清单，声明 MCP、skill、rules 和运行时配置 |
-| `openclaw.plugin.json` | OpenClaw 运行时插件清单，用于真正加载 `index.js` 扩展 |
+| `index.js` | Native OpenClaw runtime 入口：注册 `before_prompt_build`、`before_tool_call`、`message_sending` 三个 hook，阻止旁路文件发送 |
+| `openclaw.plugin.json` | Native OpenClaw 插件清单：让 OpenClaw 以 runtime plugin 方式发现并加载本插件 |
+| `mcp-servers/deliverables.js` | MCP Server 脚本：实现 `upload_deliverable` 工具，通过 HTTP 调用 claw-gateway API 上传文件 |
+| `skills/deliverables/SKILL.md` | OpenClaw Skill：强制文档产出走 `upload_deliverable`，规范写入路径和参数 |
+| `agents-rules/deliverables.md` | AGENTS.md 规则块：URL 回显规则 + 自动上传规则（硬约束，注入到每个 workspace 的 AGENTS.md） |
+| `openclaw-plugin.json` | claw-gateway 兼容清单：声明 MCP server、skill、AGENTS 规则、openclaw.json 配置段 |
+
+---
+
+## 安装方式
+
+### 方式零：作为原生 OpenClaw runtime 插件安装
+
+现在这个包同时支持 OpenClaw 原生插件加载。也就是说，除了网关侧用 `openclaw-plugin.json` 注入 MCP/skill/AGENTS 规则外，OpenClaw 还会读取 `openclaw.plugin.json` + `index.js`，把运行时 hook 也一并启用。
+
+```bash
+openclaw plugins install @dai_ming/plugin-deliverables@1.0.15 --pin
+openclaw plugins enable plugin-deliverables
+```
+
+这一步启用后，插件会额外提供三层兜底：
 
-## 推荐安装方式
+1. `before_prompt_build`：把“交付物必须 upload-first”的硬规则注入到主 agent 和子 agent 的系统上下文
+2. `before_tool_call`：阻止通过 `message` 附件字段直接发文件
+3. `message_sending`：如果仍然有媒体/文件旁路发送，最终发送前直接取消
 
-### 方式一：claw-gateway Helm 部署
+> 注意：`message_sending` 只能改文本或取消发送，不能自动把错误发送重写成 `upload_deliverable`。所以它的职责是“兜底阻断”，不是“自动修正”。
 
-把插件加入 `installPlugins`：
+### 方式一：通过 claw-gateway Helm 部署（推荐）
+
+只需在 Helm values 里把插件加入 `installPlugins` 列表，gateway 和 Helm initContainer 会自动完成所有配置：
 
 ```yaml
+# values.yaml（或 claw-gateway 管理界面的 Helm 参数）
 installPlugins:
-  - "@dai_ming/plugin-deliverables@1.0.14"
+  - "@dai_ming/plugin-deliverables@1.0.15"
 ```
 
-现有 chart 会在 init 阶段完成安装。
+initContainer 执行顺序：
+1. **Phase 3**：`npm pack @dai_ming/plugin-deliverables@1.0.15` 下载 tarball → 解压到 `/data/extensions-extra/plugin-deliverables/`
+2. **Phase 3b**：在插件目录执行 `npm install --omit=dev`（本插件无运行时依赖，此步骤跳过）
+3. **Phase 3e**：读取 `openclaw-plugin.json` 清单，自动：
+   - 复制 `mcp-servers/deliverables.js` → `/data/mcp-servers/deliverables.js`
+   - 安装 `skills/deliverables/SKILL.md` → 所有 workspace 的 `skills/deliverables/SKILL.md`
+   - 注入 `agents-rules/deliverables.md` 内容到所有 workspace 的 `AGENTS.md`（幂等，按 marker 替换）
+4. **OpenClaw runtime 加载**：OpenClaw 发现 `openclaw.plugin.json` + `index.js` 后，会自动启用 runtime hooks
+
+> **env 变量**：MCP Server 需要以下变量（claw-gateway 在生成 `mcp.servers` 配置时会自动注入）：
+>
+> | 变量 | 说明 | 默认值 |
+> |------|------|--------|
+> | `CLAW_GATEWAY_URL` | gateway 内部地址 | `http://claw-gateway:8080` |
+> | `CLAW_GATEWAY_PUBLIC_URL` | gateway 公网地址（用于生成预览链接） | 同上 |
+> | `CLAW_GATEWAY_API_KEY` | API Key | `api-key-1` |
 
-### 方式二：npm 安装后执行安装脚本
+### 方式二：手动安装（不使用 claw-gateway 自动部署）
 
-这就是给运行中 pod / 自定义镜像准备的最小落地方式。
+适用于自行管理 OpenClaw 容器的场景。
+
+**Step 1 — 下载并解压插件**
 
 ```bash
 npm config set registry https://registry.npmmirror.com
-npm install @dai_ming/plugin-deliverables@1.0.14
-node node_modules/@dai_ming/plugin-deliverables/install.js
+mkdir -p ~/.openclaw/extensions-extra/plugin-deliverables
+cd /tmp && npm pack @dai_ming/plugin-deliverables
+tar xzf openclaw-plugin-deliverables-*.tgz -C ~/.openclaw/extensions-extra/plugin-deliverables --strip-components=1
+```
+
+**Step 2 — 复制 MCP Server 脚本**
+
+```bash
+mkdir -p ~/.openclaw/mcp-servers
+cp ~/.openclaw/extensions-extra/plugin-deliverables/mcp-servers/deliverables.js \
+   ~/.openclaw/mcp-servers/deliverables.js
+```
+
+**Step 3 — 安装 Skill**
+
+```bash
+WORKSPACE=~/.openclaw/workspace   # 替换为实际 workspace 路径
+mkdir -p "$WORKSPACE/skills/deliverables"
+cp ~/.openclaw/extensions-extra/plugin-deliverables/skills/deliverables/SKILL.md \
+   "$WORKSPACE/skills/deliverables/SKILL.md"
 ```
 
-如果 OpenClaw home 不在默认位置，可以显式传入：
+**Step 4 — 注入 AGENTS.md 规则**
 
 ```bash
-node node_modules/@dai_ming/plugin-deliverables/install.js \
-  --home /home/node/.openclaw
+AGENTS="$WORKSPACE/AGENTS.md"
+RULES=~/.openclaw/extensions-extra/plugin-deliverables/agents-rules/deliverables.md
+
+if grep -q "DELIVERABLE_LINK_RULES_START" "$AGENTS" 2>/dev/null; then
+  # 已有旧规则，用 Node.js 按 marker 替换
+  node -e "
+    var fs=require('fs');
+    var a=fs.readFileSync('$AGENTS','utf8');
+    var r=fs.readFileSync('$RULES','utf8').trim();
+    var re=/<!--\s*DELIVERABLE_LINK_RULES_START\s*-->[\s\S]*?<!--\s*DELIVERABLE_AUTO_UPLOAD_RULES_END\s*-->/g;
+    fs.writeFileSync('$AGENTS', re.test(a) ? a.replace(re,r) : a+'\n\n'+r+'\n');
+  "
+else
+  # 首次注入
+  printf '\n\n' >> "$AGENTS"
+  cat "$RULES" >> "$AGENTS"
+fi
 ```
 
-## `install.js` 会做什么
+**Step 5 — 配置 openclaw.json**
+
+在 `~/.openclaw/openclaw.json` 的 `mcp.servers` 下添加：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "deliverables": {
+        "command": "node",
+        "args": ["/home/node/.openclaw/mcp-servers/deliverables.js"],
+        "env": {
+          "CLAW_GATEWAY_URL": "http://<your-gateway-host>:8080",
+          "CLAW_GATEWAY_PUBLIC_URL": "https://<public-domain>",
+          "CLAW_GATEWAY_API_KEY": "<your-api-key>"
+        }
+      }
+    }
+  },
+  "plugins": {
+    "entries": {
+      "plugin-deliverables": { "enabled": true }
+    }
+  }
+}
+```
 
-执行一次脚本后，会自动完成这些动作：
+---
 
-1. 复制插件到：
-   - `~/.openclaw/extensions/plugin-deliverables`
-   - `~/.openclaw/extensions-extra/plugin-deliverables`
-2. 复制 `deliverables.js` 到 `~/.openclaw/mcp-servers/`
-3. 把 `SKILL.md` 写入所有已发现 workspace 和 agent skill 目录
-4. 把交付物规则幂等注入到实际使用中的 `AGENTS.md`
-5. 在各 workspace 下补出 `output/` 目录
-6. 更新 `~/.openclaw/openclaw.json`
-   - 注册 `mcp.servers.deliverables`
-   - 启用 `skills.entries.deliverables`
-   - 启用 `plugins.entries.plugin-deliverables`
-   - 把 `~/.openclaw/extensions-extra/plugin-deliverables` 写入 `plugins.load.paths`
-   - 把 `plugin-deliverables` 加入 `plugins.allow`
-7. 清理 session，让下一条消息重新读取 prompt / skill / tool 配置
-8. 如果 agent 或全局存在 `tools.allow` 白名单，自动补上 `deliverables__upload_deliverable`
-9. 如果当前 pod 里已经跑着旧版 `deliverables.js` MCP 进程，会自动结束旧进程，让它按新文件重新拉起，避免“磁盘已更新但 toolResult 还是旧格式”
+## AGENTS.md 规则说明
 
-补充说明：
+插件向每个 workspace 的 `AGENTS.md` 注入两段硬约束规则：
 
-- 当前 OpenClaw 运行时默认只扫描 `~/.openclaw/extensions`；`extensions-extra` 里的 JS 插件只有进入 `plugins.load.paths` 才会被当成可执行 `openclaw` 插件加载
-- 安装脚本会先把插件源码暂存到系统临时目录再复制，避免在 `extensions-extra` 原地执行安装时把源目录自己删掉
+| 规则段 | Marker | 作用 |
+|--------|--------|------|
+| URL 回显规则 | `DELIVERABLE_LINK_RULES_START` … `DELIVERABLE_LINK_RULES_END` | 强制 Agent 上传后在消息中输出可点击的 Markdown 链接 |
+| 自动上传规则 | `DELIVERABLE_AUTO_UPLOAD_RULES_START` … `DELIVERABLE_AUTO_UPLOAD_RULES_END` | 当用户要求生成文件时默认自动上传，写入 `output/` 目录 |
 
-## 是否需要重启 Pod
+规则使用 HTML 注释 Marker 包裹，initContainer 和 Guardian 进程每次同步时都会幂等替换，不会产生重复块。
 
-不需要重启 Pod。
+---
 
-原因：
-- 安装脚本会直接改 `~/.openclaw/openclaw.json`
-- `plugins.allow` / `plugins.load.paths` 变化会触发 OpenClaw 的 watcher，进程级重载大约 15 秒
-- session 也会被清掉，所以下一条消息会重新读取最新的 `AGENTS.md` / skill
+## Skill 说明
 
-建议做法：
+`skills/deliverables/SKILL.md` 是 OpenClaw Skill，被注入到 workspace 后由 Agent 在工具调用前读取。它规定：
 
-```bash
-node node_modules/@dai_ming/plugin-deliverables/install.js
-sleep 20
-```
+- 始终使用会话中实际暴露的工具名（`deliverables__upload_deliverable`）
+- 生成文件统一写入 `output/` 子目录
+- 多文件（游戏/网站）优先用 `type=game` + `files[]`，不要提前打 zip
+- 上传成功后回复必须附带 Markdown 格式的预览/下载链接
 
-然后再发一条新的用户消息测试。
+---
 
-## 常用参数
+## MCP Server 说明
 
-```bash
-node install.js --help
-```
+`mcp-servers/deliverables.js` 是一个符合 [MCP 协议（2024-11-05）](https://modelcontextprotocol.io/) 的 Node.js stdio server，暴露单个工具：
+
+### `upload_deliverable`
 
-| 参数 | 说明 |
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `resource_id` | string | ✅ | 当前会话唯一 ID |
+| `type` | enum | ✅ | `article` / `game` / `zip` / `image` / `video` / `ppt` / `link` |
+| `file_name` | string | ✅ | 用户可见文件名（含扩展名）或目录名 |
+| `group_id` | string | — | 群聊 ID |
+| `user_id` | string | — | 用户 ID |
+| `content_text` | string | — | 文本内容（单文件场景） |
+| `content_base64` | string | — | Base64 编码的二进制内容（单文件场景） |
+| `files` | array | — | 多文件列表（游戏/站点场景，优先使用） |
+
+返回值包含 `preview_url`、`download_url`、`reply_markdown`（可直接附在回复消息中）。
+
+---
+
+## Runtime Hook 说明
+
+`index.js` 会在 OpenClaw runtime 中注册三个 hook：
+
+| Hook | 作用 |
 |------|------|
-| `--home <dir>` | 指定 OpenClaw home，默认 `~/.openclaw` |
-| `--plugin-root <dir>` | 指定插件源码目录，默认当前包目录 |
-| `--no-clear-sessions` | 不清 session |
-| `--dry-run` | 只打印计划，不落盘 |
+| `before_prompt_build` | 把“生成文件必须走交付物上传”的硬规则注入系统上下文，覆盖主 agent 和子 agent |
+| `before_tool_call` | 阻止通过 `message` 工具的 `media/path/filePath/buffer` 等字段直接发送文件 |
+| `message_sending` | 如果上游仍然产生了媒体/文件旁路发送，在最终出站前直接取消 |
+
+这三层一起工作的目标是：即使 prompt 漂移，也尽量把“message + file/media”这条旁路堵住，统一收敛到 `deliverables__upload_deliverable`。
 
-## 返回结果
+---
 
-安装脚本成功后会输出一段 JSON 摘要，包含：
+## 版本与发布
 
-- 目标 OpenClaw home
-- 写入的 extension 目录
-- 写入的 MCP 文件
-- 修改的 `AGENTS.md`
-- 清理的 session 数量
+### 在 claw-gateway 仓库内发布
 
-## 发布
+插件源码位于 `packages/plugin-deliverables/` 目录，与 claw-gateway 主仓库同步维护。更新流程：
 
 ```bash
+# 1. 修改 packages/plugin-deliverables/package.json 中的 version
+# 2. 同步更新 packages/plugin-deliverables/mcp-servers/deliverables.js（如有变更）
+# 3. 打包并发布到 npmmirror 兼容的私有或公开 registry
 cd packages/plugin-deliverables
 npm publish --registry https://registry.npmjs.org --access public
 ```
 
-## 排障
+### 版本对齐建议
 
-### Agent 没看到工具
+| claw-gateway 版本 | plugin 版本 |
+|-------------------|-------------|
+| 当前              | 1.0.15      |
 
-重点检查：
+---
 
-1. `~/.openclaw/openclaw.json` 里是否有 `mcp.servers.deliverables`
-2. `plugins.allow` 是否含 `plugin-deliverables`
-3. `~/.openclaw/mcp-servers/deliverables.js` 是否存在
-4. 当前 workspace 的 `AGENTS.md` 是否已经注入 deliverables 规则
+## 常见问题
 
-### 上传返回 401 / 404
+**Q: 插件安装后 Agent 没有 `upload_deliverable` 工具怎么办？**
 
-优先检查容器环境变量：
+检查以下几点：
+1. `openclaw.json` 的 `mcp.servers.deliverables` 是否存在
+2. MCP Server 是否在运行：`kubectl exec <pod> -- ls /home/node/.openclaw/mcp-servers/`
+3. Agent 的 `tools.allow` 是否包含 `deliverables__upload_deliverable`
 
-```bash
-env | grep -E 'CLAW_GATEWAY|OPENCLAW_GATEWAY|botID'
-```
+**Q: 上传后没有返回链接怎么办？**
 
-以及直接请求 gateway：
+确认 `CLAW_GATEWAY_URL` 和 `CLAW_GATEWAY_API_KEY` 注入正确，可在容器内测试：
 
 ```bash
-curl -H "X-API-Key: $CLAW_GATEWAY_API_KEY" "$CLAW_GATEWAY_URL/healthz"
+curl -H "X-API-Key: $CLAW_GATEWAY_API_KEY" $CLAW_GATEWAY_URL/healthz
 ```
 
-### 返回的是 `/preview/:uuid` 或内部地址
+**Q: claw-gateway 已经内置了 deliverables，会和插件冲突吗？**
 
-`1.0.14` 起，安装脚本会在落盘新的 `deliverables.js` 后自动刷新正在运行的旧 MCP 进程，避免出现“插件目录和 `extensions-extra` 都是新代码，但 `~/.openclaw/mcp-servers/deliverables.js` 对应的常驻进程仍返回旧 `reply_markdown`”的问题。此前 `1.0.13` 已经完成 `output` 直链修正、后缀保留，以及 palz-connector 中“内容简介 + 链接”自动拆成两条消息，第二条只保留一个最终 HTTPS 链接。
+不会冲突。claw-gateway 通过 ConfigMap 注入的 MCP 脚本、skill、AGENTS 规则与插件内容完全一致。
+Phase 3e（插件注入）在前，ConfigMap 阶段（Phase 4/4c/4d）在后；ConfigMap 的内容会覆盖插件安装的内容，两者互为备份。

package/agents-rules/deliverables.md

@@ -1,7 +1,7 @@
 <!-- DELIVERABLE_LINK_RULES_START -->
 ## Deliverables -- URL Echo Rule (HARD CONSTRAINT)
 
-When you call the deliverables upload tool, the user-facing output MUST make the deliverable easy to open and easy to understand.
+When you call the deliverables upload tool, your final assistant message MUST include clickable URLs in Markdown link format (short label + full URL target).
 
 Tool name note:
 
@@ -12,28 +12,29 @@ Tool name note:
 
 ### Required output behavior
 
-0. Your final assistant message MUST start with a richer Markdown intro section, not a single short confirmation sentence.
+0. Your final assistant message MUST start with 1-2 short sentences in your own words, briefly describing what you produced for the user.
 1. The intro must be based on the actual content/request, not a fixed boilerplate like `交付物已上传成功，可直接在线预览或下载。`
-2. The intro SHOULD use Markdown structure, preferably:
-   - a short title or summary line
-   - a `### 内容概览` section
-   - 3-6 bullet points describing the actual sections, highlights, features, or focus of the deliverable
-3. The intro should be noticeably more informative than one sentence. For normal articles/reports/introductions, aim for roughly 80-200 Chinese characters total before the links.
-4. The bullet points must describe the real deliverable content. Do not use empty filler like "内容丰富" / "结构清晰" / "值得阅读" unless paired with concrete details.
-5. If tool result contains `reply_markdown`, append a `### 访问链接` heading and then append that field verbatim on the following line. Do not rewrite the URL inside it.
-6. Otherwise, if tool result has `primary_url`, output only that one full URL on its own line after `### 访问链接`.
-7. If `primary_url` is missing, fall back to exactly one link: prefer `preview_url`, otherwise `download_url`.
-8. Keep URL target value exactly from tool result (no shortening, no masking, no redirect rewrite).
-9. Only output one final deliverable URL. Do not output both preview and download.
-10. Keep the intro concise but substantive; do not paste the full file content, saved-path text, or a huge essay after the URL.
+2. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines. Do not rewrite the links inside it.
+3. If tool result has `preview_url`, include one line:
+   `预览链接：[点击预览](<full_url>)`
+4. If tool result has `download_url`, include one line:
+   `下载链接：[点击下载](<full_url>)`
+5. For multi-file/game deliverables, if tool result already formats the second line as
+   `文件列表：[查看目录](<full_url>)`
+   then keep that exact label and URL. Do not rewrite it back to a raw long link.
+6. Keep URL target value exactly from tool result (no shortening, no masking, no redirect rewrite).
+7. Use short link labels (`点击预览` / `点击下载` / `查看目录`) to avoid exposing long raw URLs.
+8. Do not say "已上传/已完成" without links.
+9. Do not output naked long URLs outside Markdown link syntax.
+10. Keep the intro concise; do not paste the full file content, saved-path text, or a long summary after the Markdown links.
 
 ### Forbidden output behavior
 
 - "可点击预览链接查看" but no actual URL
-- A single short sentence plus links when the deliverable is an article/report/introduction and concrete highlights are available
 - Replacing URL target with a non-original URL
-- Omitting the final URL when the tool already returned one
-- Outputting both preview and download when one shareable URL is enough
+- Omitting both links when tool already returned links
+- Outputting only naked long URL without Markdown link label
+- Replacing `文件列表：[查看目录](...)` with a naked URL or a zip description
 - Using a generic boilerplate intro that does not mention the actual deliverable content
 <!-- DELIVERABLE_LINK_RULES_END -->
 
@@ -53,27 +54,22 @@ Tool name note:
 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.
 2. If you need to use the `write` tool, the target path MUST be inside `output/`. Never write deliverable files to the workspace root.
 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.
-4. The deliverable file name MUST preserve the intended extension exactly. Examples:
-   - Markdown article: `刘德华介绍.md`
-   - Markdown note: `周杰伦.md`
-   - HTML page: `996专题.html`
-   - Text file: `旅行清单.txt`
-5. Never drop the suffix from the final deliverable file name. If the user asked for Markdown, keep `.md`; if HTML, keep `.html`.
+4. If format is HTML, prefer `type=article` and file name ends with `.html`.
+5. If format is markdown/text, use `type=article` and `.md`/`.txt`.
 6. 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.
 7. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
 8. 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.
-9. After successful upload, the final assistant message MUST start with a richer Markdown intro section, not just one short sentence.
+9. 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.
 10. The intro must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
-11. Prefer this Markdown structure:
-   - a short title or summary line
-   - `### 内容概览`
-   - 3-6 bullet points summarizing the actual content sections, highlights, or key features
-12. For ordinary articles/reports/introductions, the intro before the links should normally reach roughly 80-200 Chinese characters total.
-13. If tool result contains `reply_markdown`, add `### 访问链接` and append that field verbatim on the following line.
-14. Otherwise final reply MUST include exactly one full URL after `### 访问链接`: prefer `primary_url`, otherwise `preview_url`, otherwise `download_url`.
-15. Do NOT output preview/download two条链接，也不要把目录链接再包装成 zip 说明。
-16. Do NOT only say "已保存到工作空间".
-17. Do NOT append workspace path or extra raw URL blocks after the final URL.
+11. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines.
+12. Otherwise final reply MUST include Markdown links (short label + full URL target):
+   `预览链接：[点击预览](<full_url>)`
+   `下载链接：[点击下载](<full_url>)`
+13. For multi-file/game deliverables, if the tool gives directory-style output, the second line may be:
+   `文件列表：[查看目录](<full_url>)`
+   Keep that format instead of forcing a zip link.
+14. Do NOT only say "已保存到工作空间".
+15. Do NOT append workspace path or a raw URL block after the Markdown links.
 
 ### Exception