rainskills 0.1.29 → 0.1.33

package/README.md

@@ -1,6 +1,6 @@
 # Rainskills
 
-Rainskills 是一组面向应用识别、部署、排障和交付的 AI Skills，支持 Codex、Claude Code、Pi Agent、DeepSeek Harness 和 WorkBuddy。用户在市场中只会看到一个 `Rainskills` 产品，安装后 11 个 `rainbond-*` Skill 仍会独立触发。
+Rainskills 是一组面向应用识别、部署、排障和交付的 AI Skills，支持 Codex、Claude Code、Pi Agent、DeepSeek Harness、WorkBuddy 和 Hermes Agent。用户在市场中只会看到一个 `Rainskills` 产品，安装后 11 个 `rainbond-*` Skill 仍会独立触发。
 
 ## 安装
 
@@ -57,7 +57,15 @@ npx --yes rainskills workbuddy
 
 默认安装到 `${WORKBUDDY_CONFIG_DIR:-~/.workbuddy-ai}/skills`。如果安装发生在一个已经打开的 WorkBuddy 任务中，先刷新 Skill 列表或新建任务；部署时明确指定 Rainbond/Rainskills，或让项目保留 `rainbond.app.json`、`.rainbond/local.json` 标记，以避免被内置 Sites 路由抢占。
 
-安装流程支持 Codex、Claude Code、Pi Agent、DeepSeek Harness 和 WorkBuddy；所有 Agent 共用同一组 Skills 和本地 Rainskills CLI，不提供单独的客户端 MCP adapter。macOS、Linux 和 WSL 不支持 OpenClaw 安装。不要手工复制 Skill、拼接凭据或修改 Agent 配置。
+Hermes Agent：
+
+```bash
+npx --yes rainskills hermes
+```
+
+默认安装到 `${HERMES_HOME:-~/.hermes}/skills`，与其他宿主共用同一 CLI profile 和本地 Rainskills CLI，不配置客户端 MCP。如果安装发生在一个已经打开的 Hermes 会话中，执行 `/reset` 或新建会话后再使用新安装的 Skills。
+
+安装流程支持 Codex、Claude Code、Pi Agent、DeepSeek Harness、WorkBuddy 和 Hermes Agent；所有 Agent 共用同一组 Skills、CLI profile 和本地 Rainskills CLI，不提供单独的客户端 MCP adapter。macOS、Linux 和 WSL 不支持 OpenClaw 安装。不要手工复制 Skill、拼接凭据或修改 Agent 配置。
 
 ## 安装完成时用户会看到什么
 
@@ -239,7 +247,7 @@ node ~/.rainbond/lib/rainskills/bin/rainskills.js platform install --onboarding-
 
 Rainskills 会在用户下一次发起业务动作时，由本地运行时立即返回环境查询结果，并另行启动后台任务静默检查更新。更新只跟随 npm `latest` 指向的正式版。当前版本是 RC 或其他预发布版本时不会查询、不会自动升级；npm 上的新 RC 版本也不参与正式版自动升级。
 
-发现更高的正式版后，后台任务只委托到经过校验的精确版本，例如 `rainskills@0.1.29`，不会执行浮动的 `@latest` 业务代码。新版本原子刷新已经安装的 Rainskills Skills；当前业务继续使用启动时已经加载的版本，最迟从下一条新任务开始使用新版。npm 超时、版本检查失败、安装位置不安全或文件迁移失败时会保留旧版本，且不会阻塞或改变当前操作。
+发现更高的正式版后，后台任务只委托到经过校验的精确版本，例如 `rainskills@0.1.33`，不会执行浮动的 `@latest` 业务代码。新版本原子刷新已经安装的 Rainskills Skills；当前业务继续使用启动时已经加载的版本，最迟从下一条新任务开始使用新版。npm 超时、版本检查失败、安装位置不安全或文件迁移失败时会保留旧版本，且不会阻塞或改变当前操作。
 
 升级只更新 Rainskills 自身，不触发 Rainbond 安装、运行环境选择、登录授权或重新对接，也不会新增 Agent MCP 配置。更新内容仅包括 Skills 和本地 CLI。原始业务操作会继续执行；只有该业务操作本身需要运行环境时，才按既有门禁检查当前连接。可用连接直接复用，401 只重新授权一次，403 立即停止，从未连接过运行环境时才进入环境选择。
 

package/SKILL.md

@@ -9,7 +9,7 @@ This is the single marketplace entry for the complete Rainskills product. The in
 
 ## Initialize
 
-1. Detect the current host client and map it to exactly one supported installer target: Codex=`codex`, Claude Code=`claude`, Pi Agent=`pi`, DeepSeek Harness=`dsh`, or WorkBuddy=`workbuddy`. All five use the same installed Skills and protected local Rainskills CLI; Pi and DeepSeek Harness have no separate MCP adapter or generated extension. DeepSeek Harness installs to `$DSH_HOME/skills` (default `~/.dsh/skills`). WorkBuddy installs to `$WORKBUDDY_CONFIG_DIR/skills` (default `~/.workbuddy-ai/skills`). The macOS, Linux, and WSL installer intentionally does not support OpenClaw; report that limitation instead of invoking an unsupported target. Do not ask the user which supported client they are currently using. If the host cannot be determined reliably, omit the target and let the installer ask.
+1. Detect the current host client and map it to exactly one supported installer target: Codex=`codex`, Claude Code=`claude`, Pi Agent=`pi`, DeepSeek Harness=`dsh`, WorkBuddy=`workbuddy`, or Hermes Agent=`hermes`. All six use the same CLI profile, installed Skills, and protected local Rainskills CLI; none requires a separate client MCP adapter. DeepSeek Harness installs to `$DSH_HOME/skills` (default `~/.dsh/skills`). WorkBuddy installs to `$WORKBUDDY_CONFIG_DIR/skills` (default `~/.workbuddy-ai/skills`). Hermes Agent installs to `$HERMES_HOME/skills` (default `~/.hermes/skills`); `AI_AGENT=hermes-agent` or `HERMES_AGENT=true` is a reliable fallback when the host must be detected from a terminal subprocess. The macOS, Linux, and WSL installer intentionally does not support OpenClaw; report that limitation instead of invoking an unsupported target. Do not ask the user which supported client they are currently using. If the host cannot be determined reliably, omit the target and let the installer ask.
 2. Resolve the directory containing this `SKILL.md`. On native Windows, if the adjacent `bin/rainskills.js` exists, run it by absolute path with the detected target in an attached interactive terminal: `node <skill-directory>/bin/rainskills.js <target>`. On macOS, Linux, or WSL, if the adjacent `install.sh` exists, run `bash <skill-directory>/install.sh <target>` the same way. Do not replace the installer with manual file copies.
 3. Keep stdin, stdout, and stderr attached. When `RAINSKILLS_USER_INPUT_REQUIRED` appears, pause for that installer choice. If the installer emits `rainskills.next-action.v1`, execute only its fixed `argv` through the same launcher; never evaluate output as a shell command. If the adjacent `bin/rainskills.js` exists, use it for fixed next actions; otherwise use the same versioned npm package fallback described below.
 4. Stay attached until every independent Skill is installed. Do not select, connect, or configure an application runtime during installation. In the user-facing response, output only the fixed completion message below.
@@ -24,6 +24,8 @@ Skills-only 安装不需要 Node.js；CDN fallback 只负责安装 Skill 文件
 
 The installer emits this text inside `RAINSKILLS_USER_MESSAGE_BEGIN:install.completed` and the matching END marker, followed by `RAINSKILLS_AGENT_SUMMARY_REQUIRED:include-next-actions`. Relay only the body exactly and print nothing else; do not expose the markers, summarize, reformat, add a source link, or add verification details. If the host still summarizes instead of relaying, its installation summary must retain at least one example from “下一步可以直接说”.
 
+For `target=hermes`, the emitted body additionally tells an already-open Hermes session to run `/reset` or start a new session so its cached Skill catalog includes every newly installed `rainbond-*` Skill. Relay that emitted Hermes body exactly; do not replace it with the generic example below.
+
 ```text
 Rainskills 安装完成，下一条消息即可直接使用。
 
@@ -48,9 +50,11 @@ Rainskills 安装完成，下一条消息即可直接使用。
 
 Codex 中命令工具一旦返回 `session_id`，必须立即对该 `session_id` 反复调用 `write_stdin`（空输入轮询），直到工具返回 `exit_code`。连接器输出 `[RAINSKILLS_AGENT_WAIT_REQUIRED:runtime-connect]` 后进入上述轮询；看到 `[RAINSKILLS_AGENT_WAIT_COMPLETE:runtime-connect]` 后仍须继续轮询，直到取得退出码和最终 JSON。
 
+Hermes Agent 中必须使用 `terminal` 以 `background=true` 启动授权命令；取得 `session_id` 后，只对同一会话按需调用 `process(action="poll")` 获取授权地址，再调用 `process(action="wait")` 等待退出。`wait` 超时时只能继续等待同一 `session_id`；不得把后台启动或浏览器成功页面当作授权完成，也不得另起 `runtime status`。
+
 DeepSeek Harness 和 WorkBuddy 也必须保持原命令附着直到退出；如果宿主把长命令转成持久终端或后台任务，只能轮询该原始命令句柄，不得另起 `runtime status` 推测授权结果。WorkBuddy 安装后若当前任务的 Skill 清单尚未刷新，在下一条业务动作前先刷新 Skill 列表或新建任务，不得退回内置 Sites 代替 Rainbond 部署。
 
-Rainskills 只保存一个全局运行环境，不维护环境列表、名称、默认值或环境 ID。使用固定 launcher `node <home>/.rainbond/lib/rainskills/bin/rainskills.js`（运行包版本 `rainskills@0.1.29`）：
+Rainskills 只保存一个全局运行环境，不维护环境列表、名称、默认值或环境 ID。使用固定 launcher `node <home>/.rainbond/lib/rainskills/bin/rainskills.js`（运行包版本 `rainskills@0.1.33`）：
 
 - 状态：执行 `runtime status --json`。
 - 首次连接：执行 `runtime connect <target> --saas` 或 `runtime connect <target> --rainbond-url <Console origin>`。
@@ -58,6 +62,8 @@ Rainskills 只保存一个全局运行环境，不维护环境列表、名称、
 - 重新授权：执行 `runtime reconnect <target>`；必须进入浏览器 Device Flow，不复用 Shell 中缓存的 JWT。
 - 更换环境：明确告知用户会替换当前唯一环境；新授权和 live probe 成功后再覆盖凭据。
 
+固定 contract 中的 `<target>` 必须替换为当前宿主：Codex=`codex`、Claude Code=`claude`、Pi Agent=`pi`、DeepSeek Harness=`dsh`、WorkBuddy=`workbuddy`、Hermes Agent=`hermes`。
+
 所有 Rainbond 查询和变更继续通过 `~/.rainbond/bin/rainskills-tools.js`。不得配置客户端 MCP，也不得恢复环境枚举、业务 operation 生命周期、环境 ID 或 intent 恢复协议。
 
 业务 CLI 默认只读取受保护的唯一运行环境文件，忽略 Shell 中遗留的 `RAINBOND_URL` / `RAINBOND_JWT`。CI 若要显式使用环境变量凭据，必须同时设置 `RAINSKILLS_CREDENTIAL_SOURCE=environment`。

package/bin/rainskills-tools.js

@@ -449,6 +449,56 @@ function skillManifestPath(config) {
   return path.join(config.homeDir || os.homedir(), CONFIG_DIRECTORY, "bin", SKILL_MANIFEST_FILENAME);
 }
 
+function loadTelemetryPackageVersion(config) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(skillManifestPath(config), "utf8"));
+    return typeof manifest.package_version === "string" && manifest.package_version
+      ? manifest.package_version
+      : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function createBridgeTelemetry(config) {
+  try {
+    const directory = path.join(config.homeDir || os.homedir(), CONFIG_DIRECTORY, "rainskills", "telemetry");
+    const { createResultTelemetry } = requireRuntimeModule("result-telemetry.js");
+    return createResultTelemetry({
+      directory,
+      packageVersion: loadTelemetryPackageVersion(config),
+    });
+  } catch {
+    return null;
+  }
+}
+
+async function executeWithUsageTelemetry(command, config) {
+  const tracksUsage = command.command === "read" || command.command === "call";
+  const telemetry = tracksUsage ? createBridgeTelemetry(config) : null;
+  if (telemetry) await telemetry.flushPending(3).catch(() => {});
+  try {
+    const output = await execute(command, config);
+    if (telemetry) {
+      const firstUse = telemetry.recordFirstUse("success");
+      const active = telemetry.recordActiveDaily();
+      await Promise.allSettled([firstUse.delivery, active.delivery]);
+    }
+    return output;
+  } catch (error) {
+    if (telemetry) {
+      const firstUse = telemetry.recordFirstUse("failed", {
+        error_stage: "first_use",
+        error_code: error instanceof BridgeError && error.exitCode === EXIT.TRANSPORT
+          ? "transport_failed"
+          : "tool_call_failed",
+      });
+      await firstUse.delivery.catch(() => false);
+    }
+    throw error;
+  }
+}
+
 function loadSkillBinding(config, skillId, rootSkillId) {
   const target = skillManifestPath(config);
   let manifest;
@@ -1370,7 +1420,7 @@ async function main(args = process.argv.slice(2)) {
       if (config.isInsecureHttp) {
         process.stderr.write('{"warning":"using insecure HTTP transport"}\n');
       }
-      const output = await execute(command, config);
+      const output = await executeWithUsageTelemetry(command, config);
       process.stdout.write(`${JSON.stringify(fitOutput(output))}\n`);
       return;
     }
@@ -1380,7 +1430,7 @@ async function main(args = process.argv.slice(2)) {
     if (config.isInsecureHttp) {
       process.stderr.write('{"warning":"using insecure HTTP transport"}\n');
     }
-    const output = await execute(command, config);
+    const output = await executeWithUsageTelemetry(command, config);
     process.stdout.write(`${JSON.stringify(fitOutput(output))}\n`);
   } catch (error) {
     const bridgeError = error instanceof BridgeError