@dai_ming/plugin-deliverables 1.0.3 → 1.0.5

package/README.md

@@ -1,215 +1,141 @@
 # @dai_ming/plugin-deliverables
 
-OpenClaw 交付物插件 — 让 AI Agent 将生成的文件（文章、HTML 页面、多文件游戏/网站、图片等）自动上传到 OSS，并在会话消息中回显可点击的预览/下载链接。
+OpenClaw 交付物插件。安装后会把交付物 MCP、skill、AGENTS 规则和 `openclaw.json` 配置一次性落到运行目录里，让 Agent 默认把生成文件上传成可访问的交付物链接。
 
----
-
-## 插件包含什么
+## 包内文件
 
 | 文件 | 作用 |
 |------|------|
-| `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` | 插件清单：官方文件名 |
-| `openclaw-plugin.json` | 插件清单：声明 MCP server、skill、AGENTS 规则、openclaw.json 配置段 |
-
----
+| `install.js` | 安装器：负责复制插件、注册 MCP、安装 skill、注入 AGENTS 规则、补齐 `plugins.allow`、清 session |
+| `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 和运行时配置 |
 
-## 安装方式
+## 推荐安装方式
 
-### 方式一：通过 claw-gateway Helm 部署（推荐）
+### 方式一：claw-gateway Helm 部署
 
-只需在 Helm values 里把插件加入 `installPlugins` 列表，gateway 和 Helm initContainer 会自动完成所有配置：
+把插件加入 `installPlugins`：
 
 ```yaml
-# values.yaml（或 claw-gateway 管理界面的 Helm 参数）
 installPlugins:
-  - "@dai_ming/plugin-deliverables@1.0.3"
+  - "@dai_ming/plugin-deliverables@1.0.5"
 ```
 
-initContainer 执行顺序：
-1. **Phase 3**：`npm pack @dai_ming/plugin-deliverables@1.0.3` 下载 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 替换）
-
-> **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` |
+现有 chart 会在 init 阶段完成安装。
 
-### 方式二：手动安装（不使用 claw-gateway 自动部署）
+### 方式二：npm 安装后执行安装脚本
 
-适用于自行管理 OpenClaw 容器的场景。
-
-**Step 1 — 下载并解压插件**
+这就是给运行中 pod / 自定义镜像准备的最小落地方式。
 
 ```bash
 npm config set registry https://registry.npmmirror.com
-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
+npm install @dai_ming/plugin-deliverables@1.0.5
+node node_modules/@dai_ming/plugin-deliverables/install.js
 ```
 
-**Step 2 — 复制 MCP Server 脚本**
+也可以直接用 bin：
 
 ```bash
-mkdir -p ~/.openclaw/mcp-servers
-cp ~/.openclaw/extensions-extra/plugin-deliverables/mcp-servers/deliverables.js \
-   ~/.openclaw/mcp-servers/deliverables.js
+npx openclaw-deliverables-install
 ```
 
-**Step 3 — 安装 Skill**
+如果 OpenClaw home 不在默认位置，可以显式传入：
 
 ```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"
+node node_modules/@dai_ming/plugin-deliverables/install.js \
+  --home /home/node/.openclaw
 ```
 
-**Step 4 — 注入 AGENTS.md 规则**
-
-```bash
-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
-```
-
-**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": {
-      "deliverables": { "enabled": true }
-    }
-  }
-}
-```
-
----
-
-## AGENTS.md 规则说明
+## `install.js` 会做什么
 
-插件向每个 workspace 的 `AGENTS.md` 注入两段硬约束规则：
+执行一次脚本后，会自动完成这些动作：
 
-| 规则段 | Marker | 作用 |
-|--------|--------|------|
-| URL 回显规则 | `DELIVERABLE_LINK_RULES_START` … `DELIVERABLE_LINK_RULES_END` | 强制 Agent 上传后在消息中输出可点击的 Markdown 链接 |
-| 自动上传规则 | `DELIVERABLE_AUTO_UPLOAD_RULES_START` … `DELIVERABLE_AUTO_UPLOAD_RULES_END` | 当用户要求生成文件时默认自动上传，写入 `output/` 目录 |
+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`
+   - 把 `plugin-deliverables` 加入 `plugins.allow`
+7. 清理 session，让下一条消息重新读取 prompt / skill / tool 配置
+8. 如果 agent 或全局存在 `tools.allow` 白名单，自动补上 `deliverables__upload_deliverable`
 
-规则使用 HTML 注释 Marker 包裹，initContainer 和 Guardian 进程每次同步时都会幂等替换，不会产生重复块。
+## 是否需要重启 Pod
 
----
+不需要重启 Pod。
 
-## Skill 说明
+原因：
+- 安装脚本会直接改 `~/.openclaw/openclaw.json`
+- `plugins.allow` 变化会触发 OpenClaw 的 watcher，进程级重载大约 15 秒
+- session 也会被清掉，所以下一条消息会重新读取最新的 `AGENTS.md` / skill
 
-`skills/deliverables/SKILL.md` 是 OpenClaw Skill，被注入到 workspace 后由 Agent 在工具调用前读取。它规定：
+建议做法：
 
-- 始终使用会话中实际暴露的工具名（`deliverables__upload_deliverable`）
-- 生成文件统一写入 `output/` 子目录
-- 多文件（游戏/网站）优先用 `type=game` + `files[]`，不要提前打 zip
-- 上传成功后回复必须附带 Markdown 格式的预览/下载链接
-
----
-
-## MCP Server 说明
+```bash
+node node_modules/@dai_ming/plugin-deliverables/install.js
+sleep 20
+```
 
-`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 | — | 多文件列表（游戏/站点场景，优先使用） |
+```bash
+node install.js --help
+```
 
-返回值包含 `preview_url`、`download_url`、`reply_markdown`（可直接附在回复消息中）。
+| 参数 | 说明 |
+|------|------|
+| `--home <dir>` | 指定 OpenClaw home，默认 `~/.openclaw` |
+| `--plugin-root <dir>` | 指定插件源码目录，默认当前包目录 |
+| `--no-clear-sessions` | 不清 session |
+| `--dry-run` | 只打印计划，不落盘 |
 
----
+## 返回结果
 
-## 版本与发布
+安装脚本成功后会输出一段 JSON 摘要，包含：
 
-### 在 claw-gateway 仓库内发布
+- 目标 OpenClaw home
+- 写入的 extension 目录
+- 写入的 MCP 文件
+- 修改的 `AGENTS.md`
+- 清理的 session 数量
 
-插件源码位于 `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
 ```
 
-### 版本对齐建议
-
-| claw-gateway 版本 | plugin 版本 |
-|-------------------|-------------|
-| 当前              | 1.0.3       |
-
----
+## 排障
 
-## 常见问题
+### Agent 没看到工具
 
-**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`
+1. `~/.openclaw/openclaw.json` 里是否有 `mcp.servers.deliverables`
+2. `plugins.allow` 是否含 `plugin-deliverables`
+3. `~/.openclaw/mcp-servers/deliverables.js` 是否存在
+4. 当前 workspace 的 `AGENTS.md` 是否已经注入 deliverables 规则
 
-**Q: 上传后没有返回链接怎么办？**
+### 上传返回 401 / 404
 
-确认 `CLAW_GATEWAY_URL` 和 `CLAW_GATEWAY_API_KEY` 注入正确，可在容器内测试：
+优先检查容器环境变量：
 
 ```bash
-curl -H "X-API-Key: $CLAW_GATEWAY_API_KEY" $CLAW_GATEWAY_URL/healthz
+env | grep -E 'CLAW_GATEWAY|OPENCLAW_GATEWAY|botID'
 ```
 
-**Q: claw-gateway 已经内置了 deliverables，会和插件冲突吗？**
+以及直接请求 gateway：
 
-不会冲突。claw-gateway 通过 ConfigMap 注入的 MCP 脚本、skill、AGENTS 规则与插件内容完全一致。
-Phase 3e（插件注入）在前，ConfigMap 阶段（Phase 4/4c/4d）在后；ConfigMap 的内容会覆盖插件安装的内容，两者互为备份。
+```bash
+curl -H "X-API-Key: $CLAW_GATEWAY_API_KEY" "$CLAW_GATEWAY_URL/healthz"
+```

package/install.js

@@ -0,0 +1,463 @@
+#!/usr/bin/env node
+"use strict";
+
+var fs = require("fs");
+var os = require("os");
+var path = require("path");
+
+var LEGACY_DELIVERABLE_TOOL_NAMES = {
+  "upload_deliverable": true,
+  "list_deliverables": true,
+  "renew_deliverable": true,
+  "deliverables__upload_deliverable": true,
+  "deliverables__list_deliverables": true,
+  "deliverables__renew_deliverable": true
+};
+var DELIVERABLES_UPLOAD_TOOL = "deliverables__upload_deliverable";
+
+function usage() {
+  console.log([
+    "Usage:",
+    "  node install.js [--home <openclaw-home>] [--plugin-root <dir>] [--no-clear-sessions] [--dry-run]",
+    "",
+    "Defaults:",
+    "  --home        " + path.join(os.homedir(), ".openclaw"),
+    "  --plugin-root current package directory"
+  ].join("\n"));
+}
+
+function parseArgs(argv) {
+  var args = {
+    home: path.join(os.homedir(), ".openclaw"),
+    pluginRoot: __dirname,
+    clearSessions: true,
+    dryRun: false
+  };
+  for (var i = 0; i < argv.length; i++) {
+    var cur = argv[i];
+    if (cur === "--home") {
+      i += 1;
+      if (i >= argv.length) throw new Error("--home requires a value");
+      args.home = path.resolve(argv[i]);
+      continue;
+    }
+    if (cur === "--plugin-root") {
+      i += 1;
+      if (i >= argv.length) throw new Error("--plugin-root requires a value");
+      args.pluginRoot = path.resolve(argv[i]);
+      continue;
+    }
+    if (cur === "--no-clear-sessions") {
+      args.clearSessions = false;
+      continue;
+    }
+    if (cur === "--dry-run") {
+      args.dryRun = true;
+      continue;
+    }
+    if (cur === "--help" || cur === "-h") {
+      usage();
+      process.exit(0);
+    }
+    throw new Error("unknown argument: " + cur);
+  }
+  return args;
+}
+
+function isPlainObject(val) {
+  return !!val && typeof val === "object" && !Array.isArray(val);
+}
+
+function deepCopy(val) {
+  if (val === undefined) return undefined;
+  return JSON.parse(JSON.stringify(val));
+}
+
+function resolveEnv(val) {
+  if (typeof val !== "string") return val;
+  return val.replace(/\$\{([^}]+)\}/g, function(_, key) {
+    return process.env[key] || "";
+  });
+}
+
+function resolveEnvDeep(val) {
+  if (Array.isArray(val)) return val.map(resolveEnvDeep);
+  if (isPlainObject(val)) {
+    var out = {};
+    Object.keys(val).forEach(function(key) {
+      out[key] = resolveEnvDeep(val[key]);
+    });
+    return out;
+  }
+  return resolveEnv(val);
+}
+
+function normalizeRuntimeName(name) {
+  if (typeof name !== "string") return "";
+  var out = name.trim();
+  if (!out) return "";
+  if (out.charAt(0) === "@") {
+    var slash = out.indexOf("/");
+    out = slash >= 0 ? out.slice(slash + 1) : out.slice(1);
+  }
+  var at = out.indexOf("@");
+  if (at >= 0) out = out.slice(0, at);
+  return out.trim();
+}
+
+function ensureDir(dir, dryRun) {
+  if (dryRun) return;
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readJSON(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (err) {
+    return deepCopy(fallback);
+  }
+}
+
+function writeJSON(filePath, value, dryRun) {
+  if (dryRun) return;
+  ensureDir(path.dirname(filePath), dryRun);
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n");
+}
+
+function samePath(a, b) {
+  try {
+    return fs.realpathSync(a) === fs.realpathSync(b);
+  } catch (err) {
+    return false;
+  }
+}
+
+function copyRecursive(src, dst, dryRun) {
+  var stat = fs.lstatSync(src);
+  if (stat.isSymbolicLink()) {
+    var target = fs.realpathSync(src);
+    copyRecursive(target, dst, dryRun);
+    return;
+  }
+  if (stat.isDirectory()) {
+    ensureDir(dst, dryRun);
+    fs.readdirSync(src).forEach(function(entry) {
+      if (entry === "node_modules" || entry === ".git") return;
+      copyRecursive(path.join(src, entry), path.join(dst, entry), dryRun);
+    });
+    return;
+  }
+  ensureDir(path.dirname(dst), dryRun);
+  if (!dryRun) {
+    fs.copyFileSync(src, dst);
+    if (path.extname(dst) === ".js") {
+      fs.chmodSync(dst, 0o755);
+    }
+  }
+}
+
+function replaceDirectory(src, dst, dryRun) {
+  if (samePath(src, dst)) return false;
+  if (!dryRun) fs.rmSync(dst, { recursive: true, force: true });
+  copyRecursive(src, dst, dryRun);
+  return true;
+}
+
+function normalizePluginEntryMap(entriesCfg, pluginId) {
+  if (!isPlainObject(entriesCfg)) return {};
+  var merged = {};
+  Object.keys(entriesCfg).forEach(function(name) {
+    var item = entriesCfg[name];
+    if (!isPlainObject(item)) return;
+    Object.keys(item).forEach(function(key) {
+      merged[key] = deepCopy(item[key]);
+    });
+  });
+  if (merged.enabled === undefined) merged.enabled = true;
+  var out = {};
+  out[pluginId] = merged;
+  return out;
+}
+
+function collectWorkspaceRoots(home, cfg) {
+  var roots = {};
+  function add(dir) {
+    if (!dir || typeof dir !== "string") return;
+    roots[path.resolve(dir)] = true;
+  }
+  add(path.join(home, "workspace"));
+  try {
+    fs.readdirSync(home).forEach(function(entry) {
+      if (entry === "workspace" || entry.indexOf("workspace-") === 0) {
+        add(path.join(home, entry));
+      }
+    });
+  } catch (err) {}
+  if (cfg && cfg.agents && Array.isArray(cfg.agents.list)) {
+    cfg.agents.list.forEach(function(agent) {
+      if (agent && typeof agent.workspace === "string" && agent.workspace.trim()) {
+        add(agent.workspace.trim());
+      }
+    });
+  }
+  return Object.keys(roots);
+}
+
+function collectAgentIDs(home, cfg) {
+  var ids = {};
+  function add(id) {
+    if (!id || typeof id !== "string") return;
+    ids[id.trim()] = true;
+  }
+  add("main");
+  try {
+    fs.readdirSync(path.join(home, "agents")).forEach(function(entry) {
+      if (entry && entry !== "." && entry !== "..") add(entry);
+    });
+  } catch (err) {}
+  if (cfg && cfg.agents && Array.isArray(cfg.agents.list)) {
+    cfg.agents.list.forEach(function(agent) {
+      if (agent && agent.id) add(String(agent.id));
+    });
+  }
+  return Object.keys(ids);
+}
+
+function writeText(filePath, content, dryRun) {
+  if (dryRun) return;
+  ensureDir(path.dirname(filePath), dryRun);
+  fs.writeFileSync(filePath, content);
+}
+
+function installSkills(pluginRoot, manifest, home, workspaceRoots, agentIDs, dryRun) {
+  var installed = [];
+  if (!isPlainObject(manifest.skills)) return installed;
+  Object.keys(manifest.skills).forEach(function(skillName) {
+    var relFile = manifest.skills[skillName];
+    var src = path.join(pluginRoot, relFile);
+    var content = fs.readFileSync(src, "utf8");
+    workspaceRoots.forEach(function(wsRoot) {
+      var skillFile = path.join(wsRoot, "skills", skillName, "SKILL.md");
+      writeText(skillFile, content, dryRun);
+      ensureDir(path.join(wsRoot, "output"), dryRun);
+      installed.push(skillFile);
+    });
+    agentIDs.forEach(function(agentID) {
+      var skillFile = path.join(home, "agents", agentID, "skills", skillName, "SKILL.md");
+      writeText(skillFile, content, dryRun);
+      installed.push(skillFile);
+    });
+  });
+  return installed;
+}
+
+function injectRules(pluginRoot, manifest, workspaceRoots, dryRun) {
+  if (!manifest.agents_rules || !manifest.agents_rules.file) return [];
+  var startMarker = manifest.agents_rules.start_marker || "";
+  var endMarker = manifest.agents_rules.end_marker || "";
+  var rules = fs.readFileSync(path.join(pluginRoot, manifest.agents_rules.file), "utf8").trim() + "\n";
+  var changed = [];
+  workspaceRoots.forEach(function(wsRoot) {
+    var agentsFile = path.join(wsRoot, "AGENTS.md");
+    var existing = "";
+    try {
+      existing = fs.readFileSync(agentsFile, "utf8");
+    } catch (err) {}
+    var next = existing;
+    if (startMarker && endMarker && existing.indexOf(startMarker) >= 0) {
+      var re = new RegExp("<!--\\s*" + escapeRegExp(startMarker) + "\\s*-->[\\s\\S]*?<!--\\s*" + escapeRegExp(endMarker) + "\\s*-->", "g");
+      next = existing.replace(re, rules.trim());
+      if (next !== "" && next.charAt(next.length - 1) !== "\n") next += "\n";
+    } else if (existing) {
+      next = existing.replace(/\s*$/, "") + "\n\n" + rules;
+    } else {
+      next = rules;
+    }
+    ensureDir(path.join(wsRoot, "output"), dryRun);
+    if (next !== existing) {
+      writeText(agentsFile, next, dryRun);
+      changed.push(agentsFile);
+    }
+  });
+  return changed;
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function sanitizeToolList(items, isAllow) {
+  if (!Array.isArray(items)) return items;
+  var out = [];
+  var seen = {};
+  var hasWildcard = false;
+  items.forEach(function(raw) {
+    var item = String(raw || "").trim();
+    if (!item) return;
+    if (item === "*") hasWildcard = true;
+    if (LEGACY_DELIVERABLE_TOOL_NAMES[item]) return;
+    if (!seen[item]) {
+      out.push(item);
+      seen[item] = true;
+    }
+  });
+  if (isAllow && !hasWildcard && !seen[DELIVERABLES_UPLOAD_TOOL]) {
+    out.push(DELIVERABLES_UPLOAD_TOOL);
+  }
+  return out;
+}
+
+function sanitizeToolConfig(toolsCfg) {
+  if (!isPlainObject(toolsCfg)) return;
+  if (Array.isArray(toolsCfg.allow)) toolsCfg.allow = sanitizeToolList(toolsCfg.allow, true);
+  if (Array.isArray(toolsCfg.deny)) toolsCfg.deny = sanitizeToolList(toolsCfg.deny, false);
+}
+
+function applyPluginConfig(cfg, manifest, home) {
+  if (!isPlainObject(cfg)) cfg = {};
+  var pluginId = normalizeRuntimeName(manifest.name || "plugin-deliverables");
+  var mcpRoot = path.join(home, "mcp-servers");
+
+  cfg.plugins = isPlainObject(cfg.plugins) ? cfg.plugins : {};
+  cfg.plugins.allow = Array.isArray(cfg.plugins.allow) ? cfg.plugins.allow.slice() : [];
+  if (cfg.plugins.allow.indexOf(pluginId) === -1) cfg.plugins.allow.push(pluginId);
+  cfg.plugins.entries = isPlainObject(cfg.plugins.entries) ? cfg.plugins.entries : {};
+
+  var manifestPluginCfg = isPlainObject(manifest.openclaw_config) ? resolveEnvDeep(manifest.openclaw_config) : {};
+  var desiredEntries = {};
+  if (isPlainObject(manifestPluginCfg.plugins) && isPlainObject(manifestPluginCfg.plugins.entries)) {
+    desiredEntries = normalizePluginEntryMap(manifestPluginCfg.plugins.entries, pluginId);
+  }
+  var desiredPluginEntry = desiredEntries[pluginId] || { enabled: true };
+  if (desiredPluginEntry.enabled === undefined) desiredPluginEntry.enabled = true;
+  var currentEntry = isPlainObject(cfg.plugins.entries[pluginId]) ? cfg.plugins.entries[pluginId] : {};
+  cfg.plugins.entries[pluginId] = Object.assign({}, currentEntry, desiredPluginEntry);
+
+  cfg.skills = isPlainObject(cfg.skills) ? cfg.skills : {};
+  cfg.skills.entries = isPlainObject(cfg.skills.entries) ? cfg.skills.entries : {};
+  if (isPlainObject(manifest.skills)) {
+    Object.keys(manifest.skills).forEach(function(skillName) {
+      var currentSkill = isPlainObject(cfg.skills.entries[skillName]) ? cfg.skills.entries[skillName] : {};
+      cfg.skills.entries[skillName] = Object.assign({}, currentSkill, { enabled: true });
+    });
+  }
+
+  cfg.mcp = isPlainObject(cfg.mcp) ? cfg.mcp : {};
+  cfg.mcp.servers = isPlainObject(cfg.mcp.servers) ? cfg.mcp.servers : {};
+  if (isPlainObject(manifest.mcp_servers)) {
+    Object.keys(manifest.mcp_servers).forEach(function(serverName) {
+      var server = manifest.mcp_servers[serverName];
+      if (!isPlainObject(server)) return;
+      var generated = {
+        command: typeof server.command === "string" && server.command.trim() ? resolveEnv(server.command) : "node"
+      };
+      if (Array.isArray(server.args) && server.args.length) {
+        generated.args = resolveEnvDeep(server.args);
+      } else if (typeof server.script === "string" && server.script.trim()) {
+        generated.args = [path.join(mcpRoot, path.basename(server.script))];
+      }
+      if (isPlainObject(server.env)) generated.env = resolveEnvDeep(server.env);
+      if (typeof server.cwd === "string" && server.cwd.trim()) generated.cwd = resolveEnv(server.cwd);
+      if (typeof server.transport === "string" && server.transport.trim()) generated.transport = resolveEnv(server.transport);
+      var currentServer = isPlainObject(cfg.mcp.servers[serverName]) ? cfg.mcp.servers[serverName] : {};
+      cfg.mcp.servers[serverName] = Object.assign({}, currentServer, generated);
+    });
+  }
+
+  sanitizeToolConfig(cfg.tools);
+  if (cfg.agents && Array.isArray(cfg.agents.list)) {
+    cfg.agents.list.forEach(function(agent) {
+      if (isPlainObject(agent)) sanitizeToolConfig(agent.tools);
+    });
+  }
+
+  return cfg;
+}
+
+function installMcpServers(pluginRoot, manifest, home, dryRun) {
+  var copied = [];
+  if (!isPlainObject(manifest.mcp_servers)) return copied;
+  Object.keys(manifest.mcp_servers).forEach(function(serverName) {
+    var server = manifest.mcp_servers[serverName];
+    if (!isPlainObject(server) || typeof server.script !== "string" || !server.script.trim()) return;
+    var src = path.join(pluginRoot, server.script);
+    var dst = path.join(home, "mcp-servers", path.basename(server.script));
+    ensureDir(path.dirname(dst), dryRun);
+    if (!dryRun) {
+      fs.copyFileSync(src, dst);
+      fs.chmodSync(dst, 0o755);
+    }
+    copied.push(dst);
+  });
+  return copied;
+}
+
+function clearSessions(home, dryRun) {
+  var cleared = [];
+  var agentsRoot = path.join(home, "agents");
+  try {
+    fs.readdirSync(agentsRoot).forEach(function(agentID) {
+      var sessionDir = path.join(agentsRoot, agentID, "sessions");
+      if (!fs.existsSync(sessionDir)) return;
+      fs.readdirSync(sessionDir).forEach(function(entry) {
+        if (!/\.jsonl$/.test(entry) && entry !== "sessions.json") return;
+        var full = path.join(sessionDir, entry);
+        if (!dryRun) fs.rmSync(full, { force: true });
+        cleared.push(full);
+      });
+    });
+  } catch (err) {}
+  return cleared;
+}
+
+function main() {
+  var args = parseArgs(process.argv.slice(2));
+  var pluginRoot = path.resolve(args.pluginRoot);
+  var home = path.resolve(args.home);
+  var manifestPath = path.join(pluginRoot, "openclaw-plugin.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error("missing openclaw-plugin.json at " + manifestPath);
+  }
+  var manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  var pluginName = normalizeRuntimeName(manifest.name || "plugin-deliverables");
+  var openclawPath = path.join(home, "openclaw.json");
+  var currentConfig = readJSON(openclawPath, {});
+  var workspaceRoots = collectWorkspaceRoots(home, currentConfig);
+  var agentIDs = collectAgentIDs(home, currentConfig);
+  var extensionsDir = path.join(home, "extensions", pluginName);
+  var extensionsExtraDir = path.join(home, "extensions-extra", pluginName);
+
+  ensureDir(home, args.dryRun);
+  replaceDirectory(pluginRoot, extensionsDir, args.dryRun);
+  replaceDirectory(pluginRoot, extensionsExtraDir, args.dryRun);
+  var mcpFiles = installMcpServers(pluginRoot, manifest, home, args.dryRun);
+  var skillFiles = installSkills(pluginRoot, manifest, home, workspaceRoots, agentIDs, args.dryRun);
+  var agentFiles = injectRules(pluginRoot, manifest, workspaceRoots, args.dryRun);
+  var nextConfig = applyPluginConfig(currentConfig, manifest, home);
+  writeJSON(openclawPath, nextConfig, args.dryRun);
+  var clearedSessions = args.clearSessions ? clearSessions(home, args.dryRun) : [];
+
+  var summary = {
+    plugin: pluginName,
+    version: manifest.version || "",
+    openclaw_home: home,
+    dry_run: args.dryRun,
+    copied_extensions: [extensionsDir, extensionsExtraDir],
+    mcp_servers: mcpFiles,
+    skill_files: skillFiles.length,
+    agents_files: agentFiles,
+    cleared_sessions: clearedSessions.length,
+    openclaw_json: openclawPath
+  };
+  console.log(JSON.stringify(summary, null, 2));
+  if (!args.dryRun) {
+    console.log("Install complete. Wait about 15s for OpenClaw to reload plugins.allow, then send a new message to verify.");
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error("[plugin-deliverables] install failed:", err && err.stack ? err.stack : err);
+  process.exit(1);
+}

package/openclaw-plugin.json

@@ -1,7 +1,6 @@
 {
-  "id": "plugin-deliverables",
   "name": "plugin-deliverables",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "npm_package": "@dai_ming/plugin-deliverables",
   "description": "Deliverables plugin: MCP server + skill + AGENTS rules for AI-generated file uploads",
   "mcp_servers": {
@@ -27,7 +26,9 @@
   "openclaw_config": {
     "plugins": {
       "entries": {
-        "plugin-deliverables": { "enabled": true }
+        "plugin-deliverables": {
+          "enabled": true
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dai_ming/plugin-deliverables",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "OpenClaw deliverables plugin — upload AI-generated files to OSS and return shareable preview/download links",
   "keywords": [
     "openclaw",
@@ -8,9 +8,12 @@
     "deliverables",
     "mcp"
   ],
+  "bin": {
+    "openclaw-deliverables-install": "./install.js"
+  },
   "license": "MIT",
   "files": [
-    "openclaw.plugin.json",
+    "install.js",
     "openclaw-plugin.json",
     "mcp-servers/",
     "skills/",

package/openclaw.plugin.json

@@ -1,34 +0,0 @@
-{
-  "id": "plugin-deliverables",
-  "name": "plugin-deliverables",
-  "version": "1.0.3",
-  "npm_package": "@dai_ming/plugin-deliverables",
-  "description": "Deliverables plugin: MCP server + skill + AGENTS rules for AI-generated file uploads",
-  "mcp_servers": {
-    "deliverables": {
-      "script": "mcp-servers/deliverables.js",
-      "command": "node",
-      "env": {
-        "CLAW_GATEWAY_URL": "${CLAW_GATEWAY_URL}",
-        "CLAW_GATEWAY_PUBLIC_URL": "${CLAW_GATEWAY_PUBLIC_URL}",
-        "CLAW_GATEWAY_API_KEY": "${CLAW_GATEWAY_API_KEY}",
-        "OPENCLAW_GATEWAY_API_KEY": "${OPENCLAW_GATEWAY_API_KEY}"
-      }
-    }
-  },
-  "skills": {
-    "deliverables": "skills/deliverables/SKILL.md"
-  },
-  "agents_rules": {
-    "file": "agents-rules/deliverables.md",
-    "start_marker": "DELIVERABLE_LINK_RULES_START",
-    "end_marker": "DELIVERABLE_AUTO_UPLOAD_RULES_END"
-  },
-  "openclaw_config": {
-    "plugins": {
-      "entries": {
-        "plugin-deliverables": { "enabled": true }
-      }
-    }
-  }
-}