@zicolasjac-ai/remote-readonly-ssh 1.1.0 → 1.1.2

package/README.md

@@ -1,14 +1,15 @@
 # rrs
 
-只读 SSH 运维 CLI —— 通过堡垒机（JumpServer 式菜单）在服务器上执行**白名单强制的只读查询**。设计上零写能力。
+**CLI and Agent Skill for safe read-only SSH inspection via JumpServer.**
 
-把"只读"从行为自律变成**技术强制**，适合 AI 助手、脚本、团队成员以最小权限做服务器排查。
+让 AI 助手（opencode / Claude Code / Cursor / Windsurf / Codex 等）通过堡垒机白名单强制地在服务器上做只读查询——技术上零写能力，每次调用（含被拒绝的）写入本地审计日志。
 
 ## 为什么需要它
 
 - **技术强制只读**：命令前缀白名单 + 禁止模式 + 参数防注入 + 目标主机白名单，多层校验。
 - **审计留痕**：每次调用（含被拒绝的记录）写入本地审计日志，可随时审查。
 - **零依赖**：只依赖系统自带 `ssh` 客户端，无 npm 依赖树。
+- **AI Agent 友好**：附带 SKILL.md 可一键安装到 opencode / Claude / Cursor / Windsurf / Codex / OpenHands 等 AI 助手的 skills 目录。
 
 ## 安装
 
@@ -18,17 +19,28 @@ npm install -g @zicolasjac-ai/remote-readonly-ssh
 
 要求 Node.js >= 18，系统已装 OpenSSH 客户端（Windows 10+ / Linux / macOS 自带）。
 
+> **npx 一行命令**：`npx -y @zicolasjac-ai/remote-readonly-ssh init` 也可直接启动初始化向导（无需先 `npm install`）。
+>
 > 从旧包名 `remote-readonly-ssh`（v1.0.0）升级的用户，请先 `npm uninstall -g remote-readonly-ssh` 再安装，否则会报 `EEXIST: file already exists`。
 
+> **postinstall 自动引导**：全局安装完成后，TTY 环境下会自动进入初始化向导；非交互式安装（如 CI）会打印三行下一步提示，不会阻塞安装。
+
 ## 快速开始
 
 ```bash
-rrs init          # 生成配置模板 ~/.rrs/config.json
-# 编辑配置: 填 jump_server / private_key_path / target_hosts
-rrs list-tools    # 查看白名单
-rrs sys-info
+npm install -g @zicolasjac-ai/remote-readonly-ssh   # 装完自动进向导
+# 或 npx -y @zicolasjac-ai/remote-readonly-ssh init
 ```
 
+向导会依次询问：
+
+1. 是否覆盖已有 `~/.rrs/config.json`（首次安装跳过此步）
+2. 堡垒机主机 / 端口 / 用户名 / SSH 私钥路径
+3. 目标主机白名单（每行 `ip=堡垒机搜索关键字`）
+4. 是否把 SKILL.md 安装到 opencode / Claude / Cursor 等 AI 助手
+
+向导非交互式环境（CI、管道）会静默生成配置模板，不阻塞安装。
+
 ## 用法
 
 ```
@@ -67,6 +79,26 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 
 审计日志：`~/.rrs/audit.log`
 
+## Agent Skills
+
+本工具附带一份 `SKILL.md`，教 AI 助手何时用、怎么用 `rrs`。安装后用 `rrs setup skills` 一键分发到各 agent 的 skills 目录：
+
+| `--agent` | 写入路径 |
+|-----------|----------|
+| `opencode` | `~/.config/opencode/skills/rrs/SKILL.md` |
+| `claude` / `cursor` / `windsurf` / `codex` | `~/.claude/skills/rrs/SKILL.md`（Claude skills 兼容） |
+| `agents` / `openhands` | `~/.agents/skills/rrs/SKILL.md` |
+| `all`（默认） | 上述三类目录都写 |
+
+```bash
+rrs setup skills                            # 安装到全部三类目录
+rrs setup skills --agent opencode           # 只写 opencode
+rrs setup skills --dry-run                  # 仅预览目标路径
+rrs setup uninstall skills                  # 从全部目录移除
+```
+
+卸载 npm 包时会自动尝试清理这些 skill 文件（`preuninstall` 钩子，失败不影响卸载）。
+
 ## 开发
 
 ```bash

package/bin/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+
+const initWizard = require("../src/init");
+const setupSkill = require("../src/setup");
+const path = require("path");
+
+const PACKAGE_ROOT = path.join(__dirname, "..");
+
+(async () => {
+  const tty = process.stdin.isTTY && process.stdout.isTTY;
+  if (tty) {
+    try {
+      await initWizard.runInteractive({ packageRoot: PACKAGE_ROOT });
+    } catch (e) {
+      console.error(`[rrs postinstall] 向导失败: ${e.message}`);
+      console.error("可稍后手动执行: rrs init");
+    }
+  } else {
+    console.log("");
+    console.log("rrs 安装完成。下一步:");
+    console.log("  rrs init                # 交互式初始化 + 安装 AI skill（推荐）");
+    console.log("  rrs setup skills        # 仅安装 AI skill 到 opencode / claude 等");
+    console.log("  rrs list-tools          # 查看白名单与配置");
+    console.log("");
+  }
+})();

package/bin/rrs.js

@@ -8,12 +8,14 @@ const { JumpShell, cleanAnsi } = require("../src/jumpshell");
 const {
   validateCmd, validatePath, validateHost, validateArg, validateBin,
 } = require("../src/whitelist");
+const setupSkill = require("../src/setup");
+const initWizard = require("../src/init");
 
 const PACKAGE_ROOT = path.join(__dirname, "..");
 
 function printUsage() {
   const cmds = [
-    ["init", "生成配置模板到 ~/.rrs/config.json"],
+    ["init", "交互式初始化向导（TTY 下）或生成配置模板"],
     ["list-tools", "查看工具、白名单、配置"],
     ["sys-info", "主机名/OS/内核/uptime"],
     ["proc <pattern>", "进程查询（防注入参数校验）"],
@@ -22,35 +24,88 @@ function printUsage() {
     ["dir <path>", "列目录（路径白名单）"],
     ["bin-version <bin>", "查二进制版本（二进制白名单）"],
     ["exec-only <cmd>", "通用只读命令（前缀白名单+禁止模式）"],
+    ["setup skills [--agent <n>]", "把 SKILL.md 安装到 opencode/claude/agents 等目录"],
+    ["setup uninstall skills [--agent <n>]", "从上述目录移除 skill"],
   ];
-  console.log("rrs — 只读 SSH 运维 CLI（白名单强制，零写能力）\n");
-  console.log("用法: rrs <工具> [参数] [--host <ip>] [--config <file>] [--json]\n");
+  console.log("rrs — CLI and Agent Skill for safe read-only SSH inspection\n");
+  console.log("用法: rrs <工具> [参数] [--host <ip>] [--config <file>] [--json]");
+  console.log("      rrs setup skills [--agent opencode|claude|cursor|windsurf|codex|openhands|agents|all] [--dry-run]\n");
   console.log("选项: --json 以 JSON 输出结果（便于脚本/AI 调用）; -v/--version 查看版本\n");
   for (const [k, v] of cmds) {
-    console.log(`  ${k.padEnd(22)} ${v}`);
+    console.log(`  ${k.padEnd(40)} ${v}`);
   }
 }
 
 function parseArgs(argv) {
-  const opts = { tool: null, arg: null, host: null, config: null, version: false, json: false };
+  const opts = {
+    mode: "tool",
+    tool: null,
+    arg: null,
+    setupCmd: null,
+    agent: "all",
+    dryRun: false,
+    host: null,
+    config: null,
+    version: false,
+    json: false,
+  };
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--host") opts.host = argv[++i];
     else if (a === "--config") opts.config = argv[++i];
-    else if (a === "-h" || a === "--help") { opts.tool = "help"; }
+    else if (a === "--agent") opts.agent = argv[++i];
+    else if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "-h" || a === "--help") { opts.mode = "tool"; opts.tool = "help"; }
     else if (a === "-v" || a === "--version") opts.version = true;
     else if (a === "--json") opts.json = true;
     else rest.push(a);
   }
+  if (rest[0] === "setup") {
+    opts.mode = "setup";
+    if (rest[1] === "uninstall") {
+      opts.setupCmd = "uninstall";
+      if (rest[2] === "skills") opts.setupTarget = "skills";
+    } else if (rest[1] === "skills") {
+      opts.setupCmd = "install";
+      opts.setupTarget = "skills";
+    }
+    return opts;
+  }
   opts.tool = opts.tool || rest[0] || "help";
   opts.arg = rest[1] || null;
   return opts;
 }
 
+function runSetup(opts) {
+  const agent = opts.agent || "all";
+  if (!opts.setupTarget || opts.setupTarget !== "skills") {
+    console.error("用法: rrs setup skills [--agent all|opencode|claude|cursor|windsurf|codex|openhands|agents] [--dry-run]");
+    console.error("      rrs setup uninstall skills [--agent ...] [--dry-run]");
+    process.exit(1);
+  }
+  let results;
+  try {
+    results = opts.setupCmd === "uninstall"
+      ? setupSkill.uninstall({ agent, dryRun: opts.dryRun })
+      : setupSkill.install(PACKAGE_ROOT, { agent, dryRun: opts.dryRun });
+  } catch (e) {
+    console.error(`[setup] 错误: ${e.message}`);
+    process.exit(1);
+  }
+  const verb = opts.setupCmd === "uninstall" ? "卸载" : "安装";
+  console.log(`${verb} skill (agent=${agent}):`);
+  for (const r of results) {
+    const status = r.action.startsWith("would-") ? "将" : "已";
+    console.log(`  [${r.agent}] ${status}${r.action.replace("would-", "")} ${r.dir}`);
+  }
+}
+
 function initConfig() {
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    return initWizard.runInteractive();
+  }
   const dir = configDir();
-  fs.mkdirSync(dir, { recursive: true });
   const dest = path.join(dir, "config.json");
   if (fs.existsSync(dest)) {
     console.log(`配置已存在: ${dest}（未覆盖，如需重置请手动删除）`);
@@ -121,6 +176,7 @@ async function main() {
     console.log(require(path.join(PACKAGE_ROOT, "package.json")).version);
     return;
   }
+  if (opts.mode === "setup") { runSetup(opts); return; }
   if (opts.tool === "help") { printUsage(); return; }
   if (opts.tool === "init") { initConfig(); return; }
 
@@ -165,4 +221,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { parseArgs, buildCmds, printUsage };
+module.exports = { parseArgs, buildCmds, printUsage, runSetup, initConfig };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.1.0",
-  "description": "只读 SSH 运维 CLI：基于白名单强制校验，通过堡垒机对服务器执行只读查询，设计上零写权限。",
+  "version": "1.1.2",
+  "description": "只读 SSH 运维 CLI 与 Agent Skill：通过 JumpServer 堡垒机白名单强制执行只读查询；附 SKILL.md 让 opencode / Claude Code / Cursor 等 AI 助手自动发现并正确调用。",
   "license": "MIT",
   "bin": {
     "rrs": "bin/rrs.js"
@@ -10,6 +10,7 @@
   "files": [
     "bin/",
     "src/",
+    "skills/",
     "config.example.json",
     "README.md",
     "LICENSE"
@@ -26,10 +27,16 @@
     "whitelist",
     "audit",
     "security",
-    "cli"
+    "cli",
+    "agent-skill",
+    "opencode",
+    "claude",
+    "ai"
   ],
   "dependencies": {},
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "postinstall": "node bin/postinstall.js",
+    "preuninstall": "node -e \"try { require('./src/setup').uninstall({agent:'all'}) } catch(_) {}\""
   }
 }

package/skills/rrs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: rrs
+description: 通过 JumpServer 堡垒机对服务器做白名单强制的只读运维查询（sys-info / proc / ports / dir / read-file / bin-version / exec-only）。技术强制只读、命令前缀白名单 + 禁止模式 + 路径白名单 + 主机白名单多层校验，每次调用（含被拒绝的）都写入本地审计日志。AI Agent 需要做"查看服务器现状"这类操作时调用此 skill；它不会写入任何远程状态。
+license: MIT
+compatibility: opencode, claude-code, cursor, windsurf, openhands, codex
+metadata:
+  audience: ai-agents
+  category: ops
+  safe: read-only
+---
+
+# rrs — Read-Only SSH Inspection Skill
+
+`rrs`（remote-read-only-ssh）是一个面向 AI Agent 的只读 SSH 运维工具。它通过 JumpServer 风格的堡垒机在白名单目标主机上执行**白名单强制**的只读查询。每次调用（含被拒绝的）都写入本地审计日志。
+
+## When to use me
+
+当你需要从服务器**获取信息**而不是**修改状态**时调用。典型场景：
+
+- 排查时拉主机名 / OS / 内核 / uptime
+- 查某个进程是否在跑（`proc nginx`）
+- 看监听端口（`ports 8080`）
+- 读配置文件（`read-file /etc/nginx/nginx.conf`）
+- 列目录结构（`dir /var/log`）
+- 查二进制版本（`bin-version nginx`）
+- 跑一段自定义只读命令（`exec-only "df -h | head"`）
+
+**不要**用它做任何写操作——rm / mv / cp / vi / sed -i / systemctl / 重定向到文件 等一律被拒绝。
+
+## Setup（用户一次性）
+
+```bash
+npm install -g @zicolasjac-ai/remote-readonly-ssh
+rrs init          # 生成配置模板 ~/.rrs/config.json
+# 编辑配置: jump_server / private_key_path / target_hosts
+rrs setup skills  # 把本 skill 安装到 opencode / claude / agents 等目录
+```
+
+## Usage
+
+```bash
+rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
+```
+
+**始终加 `--json`**，便于解析。
+
+### Tools
+
+| 工具 | 用途 | 示例 |
+|------|------|------|
+| `sys-info` | 主机名 / OS / 内核 / uptime | `rrs sys-info --json` |
+| `proc <pattern>` | 进程查询（参数严格校验） | `rrs proc nginx --json` |
+| `ports [filter]` | 监听端口 | `rrs ports 80 --json` |
+| `read-file <path>` | 读文件（路径白名单） | `rrs read-file /etc/nginx/nginx.conf --json` |
+| `dir <path>` | 列目录 | `rrs dir /var/log --json` |
+| `bin-version <bin>` | 查二进制版本/编译参数 | `rrs bin-version nginx --json` |
+| `exec-only <cmd>` | 通用只读命令（白名单校验） | `rrs exec-only "df -h" --json` |
+| `list-tools` | 查看白名单 / 配置 | `rrs list-tools --json` |
+| `init` | 生成配置模板 | `rrs init` |
+
+### Options
+
+- `--host <ip>`：指定目标主机（必须存在于 `target_hosts` 白名单）
+- `--config <file>`：使用自定义配置文件
+- `--json`：以 JSON 输出
+- `-v` / `--version`：查看版本
+- `-h` / `--help`：查看用法
+
+### Return shape
+
+成功：
+
+```json
+{"ok":true,"tool":"sys-info","host":"10.0.0.1","output":"..."}
+```
+
+拒绝（参数非法 / 敏感路径 / 命令不在白名单）：
+
+```json
+{"ok":false,"tool":"proc","host":"","error":"拒绝: 进程名 含非法字符 [a;b]","kind":"拒绝"}
+```
+
+错误（连接 / 鉴权 / 超时）：
+
+```json
+{"ok":false,"tool":"sys-info","host":"10.0.0.1","error":"等待命令执行完成超时: ...","kind":"错误"}
+```
+
+退出码：`0`=成功 / `2`=拒绝 / `3`=配置错误 / `1`=其他错误。
+
+## Hard rules（不要试图绕过）
+
+1. **永远不要**用 `exec-only` 跑写命令（`rm`、`mv`、`sed -i`、`>`、`tee` 等都被白名单拒绝）
+2. **永远不要**用 `read-file` 读 `blocked_paths`（`/etc/passwd`、`/etc/shadow`、`~/.ssh/id_*` 等）
+3. **永远不要**指定未在 `target_hosts` 注册的 IP
+4. **不要**试图把 `;` `&&` `|` `>` `$()` 拼到参数里——所有路径和参数都做严格字符集校验
+
+被拒绝的尝试一样会进审计日志。
+
+## Audit
+
+每次调用（含拒绝）追加写入 `~/.rrs/audit.log`：
+
+```
+[巡检记录] 2026-08-18 10:30:00
+  主机: 10.0.0.1
+  巡检项: sys-info
+  结果: 成功
+  命令明细:
+    1. echo ===HOST===; hostname; whoami; id
+       读取主机标识与权限
+    ...
+```
+
+如需让审计同时记录命令输出摘要，在 `~/.rrs/config.json` 设置 `"audit": { "include_output": true }`。

package/src/init.js

@@ -0,0 +1,142 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const readline = require("node:readline/promises");
+const setupSkill = require("./setup");
+
+const PACKAGE_ROOT = path.join(__dirname, "..");
+
+function templatePath() {
+  return path.join(PACKAGE_ROOT, "config.example.json");
+}
+
+function readTemplate() {
+  return JSON.parse(fs.readFileSync(templatePath(), "utf8"));
+}
+
+function writeTemplate(destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, "config.json");
+  if (fs.existsSync(dest)) return { dest, existed: true };
+  fs.writeFileSync(dest, JSON.stringify(readTemplate(), null, 2), "utf8");
+  return { dest, existed: false };
+}
+
+function parseTargets(text) {
+  const out = {};
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    if (eq <= 0) continue;
+    const ip = t.slice(0, eq).trim();
+    const kw = t.slice(eq + 1).trim();
+    if (ip && kw) out[ip] = kw;
+  }
+  return out;
+}
+
+function applyAnswers(cfg, answers) {
+  const a = answers || {};
+  if (a.jumpHost) cfg.jump_server.host = a.jumpHost;
+  if (a.jumpPort) cfg.jump_server.port = Number(a.jumpPort) || cfg.jump_server.port;
+  if (a.jumpUser) cfg.jump_server.username = a.jumpUser;
+  if (a.privateKeyPath) cfg.private_key_path = a.privateKeyPath;
+  if (a.targetHosts && Object.keys(a.targetHosts).length) cfg.target_hosts = a.targetHosts;
+  return cfg;
+}
+
+function defaultAnswersFor(cfg) {
+  return {
+    jumpHost: cfg.jump_server && cfg.jump_server.host ? "" : "",
+    jumpPort: cfg.jump_server && cfg.jump_server.port ? String(cfg.jump_server.port) : "22",
+    jumpUser: cfg.jump_server && cfg.jump_server.username ? cfg.jump_server.username : "",
+    privateKeyPath: cfg.private_key_path && !cfg.private_key_path.includes("YOURNAME") ? cfg.private_key_path : "",
+    targetHosts: cfg.target_hosts || {},
+  };
+}
+
+async function collectAnswers(rl, cfg, prompt) {
+  const ask = async (q, def) => {
+    const label = def ? `${q} [${def}]` : q;
+    const ans = (await rl.question(`${label}: `)).trim();
+    return ans || def || "";
+  };
+  const usePrompt = prompt && typeof prompt === "object";
+  const ans = {};
+  ans.jumpHost = usePrompt && prompt.jumpHost
+    ? await prompt.jumpHost(ask, cfg)
+    : await ask("堡垒机主机 IP / 域名", "");
+  if (!ans.jumpHost) {
+    throw new Error("跳过：未填写堡垒机主机。请稍后编辑 " + path.join(os.homedir(), ".rrs", "config.json"));
+  }
+  ans.jumpPort = usePrompt && prompt.jumpPort
+    ? await prompt.jumpPort(ask, cfg)
+    : await ask("堡垒机端口", "22");
+  ans.jumpUser = usePrompt && prompt.jumpUser
+    ? await prompt.jumpUser(ask, cfg)
+    : await ask("堡垒机用户名", "");
+  ans.privateKeyPath = usePrompt && prompt.privateKeyPath
+    ? await prompt.privateKeyPath(ask, cfg)
+    : await ask("SSH 私钥绝对路径", path.join(os.homedir(), ".ssh", "id_rsa"));
+  const targetText = usePrompt && prompt.targetHosts
+    ? await prompt.targetHosts(ask, cfg)
+    : await ask("目标主机（每行 ip=堡垒机搜索关键字，空行结束）", "");
+  ans.targetHosts = parseTargets(targetText);
+  return ans;
+}
+
+async function runInteractive({ input = process.stdin, output = process.stdout, packageRoot = PACKAGE_ROOT, prompt, installSkills = true, rlFactory } = {}) {
+  const destDir = path.join(os.homedir(), ".rrs");
+  const dest = path.join(destDir, "config.json");
+  const existed = fs.existsSync(dest);
+
+  const rl = rlFactory
+    ? rlFactory()
+    : readline.createInterface({ input, output });
+  try {
+    let overwrite = "n";
+    if (existed) {
+      const ans = (await rl.question(`检测到已存在配置 ${dest}\n  (n) 跳过配置，仅安装 skill  (b) 备份后重写  (y) 直接覆盖 [n]: `)).trim().toLowerCase();
+      overwrite = ans || "n";
+    }
+
+    if (!existed || overwrite === "y" || overwrite === "b") {
+      if (existed && overwrite === "b") {
+        fs.copyFileSync(dest, dest + ".bak");
+      }
+      fs.mkdirSync(destDir, { recursive: true });
+      const cfg = readTemplate();
+      const answers = await collectAnswers(rl, defaultAnswersFor(cfg), prompt);
+      const filled = applyAnswers(cfg, answers);
+      fs.writeFileSync(dest, JSON.stringify(filled, null, 2), "utf8");
+      output.write(`已写入配置: ${dest}\n`);
+    } else {
+      output.write(`保留现有配置: ${dest}\n`);
+    }
+
+    let installedSkills = false;
+    if (installSkills) {
+      const ans = (await rl.question("安装 AI skill 到 opencode / claude / agents 目录? [Y/n]: ")).trim().toLowerCase();
+      const install = ans || "y";
+      if (install !== "n") {
+        const results = setupSkill.install(packageRoot, { agent: "all" });
+        for (const r of results) {
+          output.write(`  [${r.agent}] ${r.action === "written" ? "已安装" : r.action} ${r.dir}\n`);
+        }
+        installedSkills = true;
+      }
+    }
+
+    output.write("\n下一步:\n");
+    output.write("  rrs list-tools           # 查看白名单与配置\n");
+    output.write("  rrs sys-info --json      # 试跑一次只读巡检\n");
+    return { dest, overwrite, installedSkills };
+  } finally {
+    if (!rlFactory) rl.close();
+  }
+}
+
+module.exports = { runInteractive, writeTemplate, readTemplate, parseTargets, applyAnswers, defaultAnswersFor, templatePath };

package/src/setup.js

@@ -0,0 +1,88 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const SKILL_NAME = "rrs";
+
+const ALIAS_TO_GROUP = {
+  opencode:  ["opencode"],
+  claude:    ["claude"],
+  agents:    ["agents"],
+  codex:     ["claude"],
+  cursor:    ["claude"],
+  windsurf:  ["claude"],
+  openhands: ["agents"],
+};
+
+const RELATIVE_DIRS = {
+  opencode:  [".config", "opencode", "skills"],
+  claude:    [".claude",   "skills"],
+  agents:    [".agents",   "skills"],
+};
+
+function listTargets(agent) {
+  const a = (agent || "all").toLowerCase();
+  if (a === "all") return ["opencode", "claude", "agents"];
+  const groups = ALIAS_TO_GROUP[a];
+  if (!groups) throw new Error(`未知 --agent [${agent}]，支持: all / opencode / claude / cursor / windsurf / codex / openhands / agents`);
+  return groups;
+}
+
+function targetFile(agent, home) {
+  const segs = RELATIVE_DIRS[agent];
+  if (!segs) throw new Error(`内部错误: 未知 agent ${agent}`);
+  return path.join(home, ...segs, SKILL_NAME, "SKILL.md");
+}
+
+function skillSrc(packageRoot) {
+  return path.join(packageRoot, "skills", SKILL_NAME, "SKILL.md");
+}
+
+function install(packageRoot, opts = {}) {
+  const agent = opts.agent || "all";
+  const dryRun = !!opts.dryRun;
+  const home = opts.home || os.homedir();
+  const src = skillSrc(packageRoot);
+  if (!fs.existsSync(src)) throw new Error(`缺少 skill 资源: ${src}`);
+  const targets = listTargets(agent);
+  const results = [];
+  for (const t of targets) {
+    const dest = targetFile(t, home);
+    if (dryRun) {
+      results.push({ agent: t, dir: dest, action: "would-write", exists: fs.existsSync(dest) });
+      continue;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, fs.readFileSync(src, "utf8"), "utf8");
+    results.push({ agent: t, dir: dest, action: "written", exists: true });
+  }
+  return results;
+}
+
+function uninstall(opts = {}) {
+  const agent = opts.agent || "all";
+  const dryRun = !!opts.dryRun;
+  const home = opts.home || os.homedir();
+  const targets = listTargets(agent);
+  const results = [];
+  for (const t of targets) {
+    const dest = targetFile(t, home);
+    const dir = path.dirname(dest);
+    if (!fs.existsSync(dest)) {
+      results.push({ agent: t, dir: dest, action: "missing", exists: false });
+      continue;
+    }
+    if (dryRun) {
+      results.push({ agent: t, dir: dest, action: "would-delete", exists: true });
+      continue;
+    }
+    fs.unlinkSync(dest);
+    try { fs.rmdirSync(dir); } catch (_) {}
+    results.push({ agent: t, dir: dest, action: "deleted", exists: false });
+  }
+  return results;
+}
+
+module.exports = { install, uninstall, listTargets, targetFile, skillSrc, ALIAS_TO_GROUP, SKILL_NAME };