@dai_ming/plugin-deliverables 1.0.21 → 1.1.0

package/INSTALL.md

@@ -1,216 +1,28 @@
 # plugin-deliverables 安装文档
 
-本文档描述 `@dai_ming/plugin-deliverables@1.0.21` 的安装、升级与验证方式。
+本文档描述 `@dai_ming/plugin-deliverables@1.1.0` 的安装、升级与验证方式。
 
-## 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.21 --pin
+openclaw plugins install @dai_ming/plugin-deliverables@1.1.0 --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 的插件列表中加入：
+gateway 部署配置：
 
 ```yaml
 installPlugins:
-  - "@dai_ming/plugin-deliverables@1.0.21"
+  - "@dai_ming/plugin-deliverables@1.1.0"
 ```
 
-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.21 --registry https://registry.npmjs.org
-tar xzf dai_ming-plugin-deliverables-1.0.21.tgz \
-  -C /home/node/.openclaw/extensions-extra/plugin-deliverables \
-  --strip-components=1
-```
+1. `openclaw plugins info plugin-deliverables` 能看到插件已启用。
+2. Agent 工具列表里存在 `deliverables__upload_deliverable`。
+3. Pod 内不再出现 `node ...mcp-servers/deliverables.js` 进程。
+4. 生成交付物时，工具返回 `reply_markdown`、`preview_url`、`download_url`。
 
-### 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` 的旁路发送
-4. pod stdout 中会多出 `palz summary request/response` 与 `palz links request/response` 四条插件日志
-
-## 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.21" }
-```
+该版本为 OpenClaw Native plugin，不再安装或配置 stdio MCP server。历史 Pod 中残留的 `mcp.servers.deliverables` 会由 gateway 部署逻辑在下一次升级时清理。

package/README.md

@@ -1,253 +1,48 @@
 # @dai_ming/plugin-deliverables
 
-OpenClaw 交付物插件 — 让 AI Agent 将生成的文件（文章、HTML 页面、多文件游戏/网站、图片等）自动上传到 OSS，并在会话消息中回显可点击的预览/下载链接。
+OpenClaw Native 插件：注册 `deliverables__upload_deliverable` 原生 agent tool，把 AI 生成的文件上传到 claw-gateway 交付物系统，并返回可分享的预览/下载链接。
 
----
+## 包含内容
 
-## 插件包含什么
+| 路径 | 说明 |
+| --- | --- |
+| `index.js` | OpenClaw native extension：注册上传工具、注入运行时规则、拦截直接附件旁路 |
+| `openclaw.plugin.json` | OpenClaw 原生插件清单 |
+| `openclaw-plugin.json` | gateway 兼容清单：声明 skill、AGENTS 规则和插件 entry |
+| `skills/deliverables/SKILL.md` | Agent 使用交付物工具的技能说明 |
+| `agents-rules/deliverables.md` | 注入到 workspace `AGENTS.md` 的硬规则 |
 
-| 文件 | 作用 |
-|------|------|
-| `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.21 --pin
+openclaw plugins install @dai_ming/plugin-deliverables@1.1.0 --pin
 openclaw plugins enable plugin-deliverables
 ```
 
-这一步启用后，插件会额外提供三层兜底：
-
-1. `before_prompt_build`：把“交付物必须 upload-first”的硬规则注入到主 agent 和子 agent 的系统上下文
-2. `before_tool_call`：记录 `write` 生成的工作区文件，并阻止通过 `message` 附件字段直接发文件
-3. Palz 出站补丁：最终消息发送前扫描内部工作区路径/近期写入文件，自动上传为交付物并改写成 gateway 链接
-4. `message_sending`：如果仍然有媒体/文件旁路发送，最终发送前直接取消
-
-> 注意：非 Palz 渠道仍以 `before_prompt_build` + `before_tool_call` + `message_sending` 兜底为主；Palz 渠道具备自动上传和文本改写能力。
-
-### 方式一：通过 claw-gateway Helm 部署（推荐）
-
-只需在 Helm values 里把插件加入 `installPlugins` 列表，gateway 和 Helm initContainer 会自动完成所有配置：
+通过 gateway 部署时加入 `installPlugins`：
 
 ```yaml
-# values.yaml（或 claw-gateway 管理界面的 Helm 参数）
 installPlugins:
-  - "@dai_ming/plugin-deliverables@1.0.21"
-```
-
-initContainer 执行顺序：
-1. **Phase 3**：`npm pack @dai_ming/plugin-deliverables@1.0.21` 下载 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` |
-
-### 方式二：手动安装（不使用 claw-gateway 自动部署）
-
-适用于自行管理 OpenClaw 容器的场景。
-
-**Step 1 — 下载并解压插件**
-
-```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
+  - "@dai_ming/plugin-deliverables@1.1.0"
 ```
 
-**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"
-```
-
-**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**
+这个版本不再通过 `mcp.servers` 注入 stdio MCP 进程。OpenClaw 会读取 `package.json` 里的 `openclaw.extensions`，加载 `index.js` 并注册 native tool：
 
-在 `~/.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 }
-    }
-  }
-}
+```text
+deliverables__upload_deliverable
 ```
 
----
-
-## AGENTS.md 规则说明
-
-插件向每个 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/` 目录 |
+上传工具通过以下环境变量调用 claw-gateway：
 
-规则使用 HTML 注释 Marker 包裹，initContainer 和 Guardian 进程每次同步时都会幂等替换，不会产生重复块。
+- `CLAW_GATEWAY_URL`
+- `CLAW_GATEWAY_PUBLIC_URL`
+- `CLAW_GATEWAY_API_KEY` 或 `OPENCLAW_GATEWAY_API_KEY`
 
----
-
-## Skill 说明
-
-`skills/deliverables/SKILL.md` 是 OpenClaw Skill，被注入到 workspace 后由 Agent 在工具调用前读取。它规定：
-
-- 始终使用会话中实际暴露的工具名（`deliverables__upload_deliverable`）
-- 生成文件统一写入 `output/` 子目录
-- 多文件（游戏/网站）优先用 `type=game` + `files[]`，不要提前打 zip
-- 上传成功后回复必须附带 Markdown 格式的预览/下载链接
-
----
-
-## MCP Server 说明
-
-`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 编码的二进制内容（单文件场景）；工具会清理空白并校验格式 |
-| `file_path` | string | — | 本地文件路径，推荐用于 PDF/PPT/图片/zip 等二进制文件，工具会读取并自动编码 |
-| `files` | array | — | 多文件列表（游戏/站点场景，优先使用），每项可传 `content_text`、`content_base64` 或 `file_path` |
-
-返回值包含 `preview_url`、`download_url`、`reply_markdown`（可直接附在回复消息中）。
-
----
-
-## Runtime Hook 说明
-
-`index.js` 会在 OpenClaw runtime 中注册三个 hook：
-
-| Hook | 作用 |
-|------|------|
-| `before_prompt_build` | 把“生成文件必须走交付物上传”的硬规则注入系统上下文，覆盖主 agent 和子 agent |
-| `before_tool_call` | 记录 `write` 生成的工作区文件；阻止通过 `message` 工具的 `media/path/filePath/buffer` 等字段直接发送文件 |
-| Palz 出站补丁 | 扫描最终消息中的 `/data/workspace-*`、`output/*.ext`、反引号文件名等工作区文件引用，自动上传后替换为交付物链接 |
-| `message_sending` | 如果上游仍然产生了媒体/文件旁路发送，在最终出站前直接取消 |
-
-这些兜底一起工作的目标是：即使 prompt 漂移，也尽量把“工作区路径 / message + file/media”这类旁路堵住，统一收敛到 gateway 交付物链接。
-
-另外，Palz 渠道下如果交付物回复包含可信 gateway 交付物链接，会被拆成“内容简介 + 最终链接”两条消息；任意外部 URL 或非 gateway OSS URL 不会被包装成 `file_url` 文件消息。runtime plugin 还会分别打印这两次真实 HTTP 发送的 request/response 日志，便于直接从 pod stdout 排查。
-
----
-
-## 版本与发布
-
-### 在 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
 ```
-
-### 版本对齐建议
-
-| claw-gateway 版本 | plugin 版本 |
-|-------------------|-------------|
-| 当前              | 1.0.21      |
-
----
-
-## 常见问题
-
-**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`
-
-**Q: 上传后没有返回链接怎么办？**
-
-确认 `CLAW_GATEWAY_URL` 和 `CLAW_GATEWAY_API_KEY` 注入正确，可在容器内测试：
-
-```bash
-curl -H "X-API-Key: $CLAW_GATEWAY_API_KEY" $CLAW_GATEWAY_URL/healthz
-```
-
-**Q: claw-gateway 已经内置了 deliverables，会和插件冲突吗？**
-
-不会冲突。claw-gateway 通过 ConfigMap 注入的 MCP 脚本、skill、AGENTS 规则与插件内容完全一致。
-Phase 3e（插件注入）在前，ConfigMap 阶段（Phase 4/4c/4d）在后；ConfigMap 的内容会覆盖插件安装的内容，两者互为备份。