@zicolasjac-ai/remote-readonly-ssh 1.1.5 → 1.1.7

package/README.md

@@ -90,19 +90,29 @@ rrs <tool> [arg] [--host <ip>] [--config <file>] [--json]
 
 本工具附带一份 `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`（默认） | 上述三类目录都写 |
+| `--agent` | 写入方式 | 路径 |
+|-----------|----------|------|
+| `agents`（canonical） | **实体文件** | `~/.agents/skills/remote-readonly-ssh/SKILL.md` |
+| `opencode` | 软链接 → agents | `~/.config/opencode/skills/remote-readonly-ssh/SKILL.md` |
+| `claude` / `claudecode` / `cursor` / `windsurf` / `codex` | 软链接 → agents | `~/.claude/skills/remote-readonly-ssh/SKILL.md` |
+| `qoder` | 软链接 → agents | `~/.qoder/skills/remote-readonly-ssh/SKILL.md` |
+| `all`（默认） | 实体 + 上述 3 个软链接 | 一行命令装齐 |
+
+`rrs setup skills` 默认 `agent=all`（不询问，直接装），输出一行简明提示：
+
+```
+rrs skill 已安装: agents (实体), opencode/claude/qoder (软链接)
+```
+
+> **Windows 注意**：普通用户缺少 `SeCreateSymbolicLinkPrivilege`，软链接创建会被 OS 拒绝；rrs 会自动 fallback 为复制，并提示"Windows 已 fallback 为复制（请开启开发者模式以启用真软链接）"。开启开发者模式后重新跑 `rrs setup skills` 即可使用真软链接。
 
 ```bash
-rrs setup skills                            # 安装到全部三类目录
+rrs setup skills                            # 一行命令装齐（实体 + 3 个软链接）
 npx -y @zicolasjac-ai/remote-readonly-ssh@latest setup skills   # 全局未装时用 npx
-rrs setup skills --agent opencode           # 只写 opencode
-rrs setup skills --dry-run                  # 仅预览目标路径
-rrs setup uninstall skills                  # 从全部目录移除
+rrs setup skills --agent opencode           # 只装 opencode 链接（agents 实体也自动建）
+rrs setup skills --agent qoder              # 只装 qoder 链接
+rrs setup skills --dry-run                  # 仅预览将要创建的目标
+rrs setup uninstall skills                    # 全部移除（实体 + 软链接）
 ```
 
 卸载 npm 包时会自动尝试清理这些 skill 文件（`preuninstall` 钩子，失败不影响卸载）。

package/bin/rrs.js

@@ -24,8 +24,8 @@ 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"],
+    ["setup skills [--agent <n>]", "把 SKILL.md 装到 agents(实体) + opencode/claude/qoder(软链接)"],
+    ["setup uninstall skills [--agent <n>]", "移除上述目录的 skill"],
   ];
   console.log("rrs — CLI and Agent Skill for safe read-only SSH inspection\n");
   console.log("用法: rrs <工具> [参数] [--host <ip>] [--config <file>] [--json]");
@@ -80,7 +80,7 @@ function parseArgs(argv) {
 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 skills [--agent all|opencode|claude|claudecode|cursor|windsurf|codex|qoder|agents|openhands] [--dry-run]");
     console.error("      rrs setup uninstall skills [--agent ...] [--dry-run]");
     process.exit(1);
   }
@@ -93,11 +93,34 @@ function runSetup(opts) {
     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}`);
+
+  if (opts.dryRun) {
+    console.log(opts.setupCmd === "uninstall" ? "将卸载:" : "将安装:");
+    for (const r of results) {
+      console.log(`  ${r.action.replace("would-", "将")} ${r.dir}`);
+    }
+    return;
+  }
+
+  // 默认输出：一行简明
+  const canonical = results.find((r) => r.agent === "agents");
+  const links = results.filter((r) => r.agent !== "agents");
+  const linkNames = links.map((r) => r.agent).join("/");
+  const anyFallback = links.some((r) => r.fallback);
+  const verb = opts.setupCmd === "uninstall" ? "已卸载" : "已安装";
+
+  if (opts.setupCmd === "install") {
+    if (canonical && links.length > 0) {
+      console.log(`rrs skill ${verb}: agents (实体), ${linkNames} (软链接)${anyFallback ? " — Windows 已自动 fallback 为复制（请开启开发者模式以启用真软链接）" : ""}`);
+    } else if (canonical) {
+      console.log(`rrs skill ${verb}: agents (实体)`);
+    } else if (links.length > 0) {
+      console.log(`rrs skill ${verb}: ${linkNames} (软链接)${anyFallback ? " — Windows 已自动 fallback 为复制" : ""}`);
+    }
+  } else {
+    const removed = results.filter((r) => r.action !== "missing").map((r) => r.agent).join("/");
+    if (removed) console.log(`rrs skill ${verb}: ${removed}`);
+    else console.log(`rrs skill 未找到任何已安装项`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "只读 SSH 运维 CLI 与 Agent Skill：通过 JumpServer 堡垒机白名单强制执行只读查询；附 SKILL.md 让 opencode / Claude Code / Cursor 等 AI 助手自动发现并正确调用。",
   "license": "MIT",
   "bin": {

package/skills/{rrs → remote-readonly-ssh}/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: rrs
+name: remote-readonly-ssh
 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
+compatibility: opencode, claude-code, cursor, windsurf, openhands, qoder, codex
 metadata:
   audience: ai-agents
   category: ops

package/src/init.js

@@ -119,13 +119,13 @@ async function runInteractive({ input = process.stdin, output = process.stdout,
 
     let installedSkills = false;
     if (installSkills) {
-      const ans = (await rl.question("安装 AI skill 到 opencode / claude / agents 目录? [Y/n]: ")).trim().toLowerCase();
+      const ans = (await rl.question("安装 AI skill 到 agents/opencode/claude/qoder? [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`);
-        }
+        const links = results.filter((r) => r.agent !== "agents");
+        const fallback = links.some((r) => r.fallback);
+        output.write(`rrs skill 已安装: agents (实体), ${links.map((r) => r.agent).join("/")} (软链接)${fallback ? " — Windows 已 fallback 为复制（请开开发者模式启用真软链接）" : ""}\n`);
         installedSkills = true;
       }
     }

package/src/setup.js

@@ -4,29 +4,35 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 
-const SKILL_NAME = "rrs";
+const SKILL_NAME = "remote-readonly-ssh";
+const CANONICAL = "agents";  // 唯一的物理文件位置；其他目标都是软链接
 
 const ALIAS_TO_GROUP = {
-  opencode:  ["opencode"],
-  claude:    ["claude"],
-  agents:    ["agents"],
-  codex:     ["claude"],
-  cursor:    ["claude"],
-  windsurf:  ["claude"],
-  openhands: ["agents"],
+  opencode:    ["opencode"],
+  claude:      ["claude"],
+  claudecode:  ["claude"],
+  agents:      ["agents"],
+  openhands:   ["agents"],
+  qoder:       ["qoder"],
+  cursor:      ["claude"],
+  windsurf:    ["claude"],
+  codex:       ["claude"],
 };
 
 const RELATIVE_DIRS = {
   opencode:  [".config", "opencode", "skills"],
   claude:    [".claude",   "skills"],
   agents:    [".agents",   "skills"],
+  qoder:     [".qoder",    "skills"],
 };
 
+const LINK_TARGETS = ["opencode", "claude", "qoder"];  // 除了 agents 之外要建软链接的目录
+
 function listTargets(agent) {
   const a = (agent || "all").toLowerCase();
-  if (a === "all") return ["opencode", "claude", "agents"];
+  if (a === "all") return [CANONICAL, ...LINK_TARGETS];
   const groups = ALIAS_TO_GROUP[a];
-  if (!groups) throw new Error(`未知 --agent [${agent}]，支持: all / opencode / claude / cursor / windsurf / codex / openhands / agents`);
+  if (!groups) throw new Error(`未知 --agent [${agent}]，支持: all / opencode / claude / claudecode / cursor / windsurf / codex / qoder / agents / openhands`);
   return groups;
 }
 
@@ -40,23 +46,80 @@ function skillSrc(packageRoot) {
   return path.join(packageRoot, "skills", SKILL_NAME, "SKILL.md");
 }
 
+// 实体文件必须先存在；其他目录作为软链接指向它
+function ensureCanonical(packageRoot, home) {
+  const dest = targetFile(CANONICAL, home);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, fs.readFileSync(skillSrc(packageRoot), "utf8"), "utf8");
+  return dest;
+}
+
 function install(packageRoot, opts = {}) {
   const agent = opts.agent || "all";
   const dryRun = !!opts.dryRun;
   const home = opts.home || os.homedir();
+  // 默认尝试软链接；可在测试中置 false 强制复制（避免 Windows 权限要求）
+  const useSymlink = opts.useSymlink !== false;
   const src = skillSrc(packageRoot);
   if (!fs.existsSync(src)) throw new Error(`缺少 skill 资源: ${src}`);
-  const targets = listTargets(agent);
+
+  const requested = listTargets(agent);
+  const wantsLinks = requested.some((t) => t !== CANONICAL);
   const results = [];
-  for (const t of targets) {
+
+  // 物理文件：若请求包含 agents 或任何链接目标，都必须确保 agents 实体存在
+  const needCanonical = requested.includes(CANONICAL) || wantsLinks;
+  if (needCanonical && !dryRun) {
+    ensureCanonical(packageRoot, home);
+  }
+
+  const canonicalPath = targetFile(CANONICAL, home);
+
+  for (const t of requested) {
     const dest = targetFile(t, home);
+    if (t === CANONICAL) {
+      if (dryRun) {
+        results.push({ agent: t, dir: dest, action: "would-write", exists: fs.existsSync(dest) });
+      } else {
+        results.push({ agent: t, dir: dest, action: "written", exists: true });
+      }
+      continue;
+    }
+    // 软链接：agents 实体 → 该目录的 SKILL.md
     if (dryRun) {
-      results.push({ agent: t, dir: dest, action: "would-write", exists: fs.existsSync(dest) });
+      results.push({
+        agent: t,
+        dir: dest,
+        action: fs.existsSync(dest) ? "would-relink" : "would-link",
+        target: canonicalPath,
+      });
       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 });
+    // 清理旧文件/链接
+    if (fs.existsSync(dest) || fs.lstatSync(dest, { throwIfNoEntry: false })) {
+      try { fs.unlinkSync(dest); } catch (_) {}
+    }
+    if (useSymlink) {
+      try {
+        fs.symlinkSync(canonicalPath, dest, "file");
+        results.push({ agent: t, dir: dest, action: "linked", exists: true, target: canonicalPath });
+        continue;
+      } catch (e) {
+        // Windows 普通用户缺少 SeCreateSymbolicLinkPrivilege；降级为复制
+        if (e.code !== "EPERM" && e.code !== "EACCES" && e.code !== "ENOTSUP") throw e;
+        // 继续走复制
+      }
+    }
+    fs.copyFileSync(canonicalPath, dest);
+    results.push({
+      agent: t,
+      dir: dest,
+      action: "copied",
+      exists: true,
+      target: canonicalPath,
+      fallback: true,
+    });
   }
   return results;
 }
@@ -65,24 +128,36 @@ function uninstall(opts = {}) {
   const agent = opts.agent || "all";
   const dryRun = !!opts.dryRun;
   const home = opts.home || os.homedir();
-  const targets = listTargets(agent);
+  const requested = listTargets(agent);
   const results = [];
-  for (const t of targets) {
+
+  for (const t of requested) {
     const dest = targetFile(t, home);
-    const dir = path.dirname(dest);
-    if (!fs.existsSync(dest)) {
+    const lstat = fs.lstatSync(dest, { throwIfNoEntry: false });
+    if (!lstat) {
       results.push({ agent: t, dir: dest, action: "missing", exists: false });
       continue;
     }
     if (dryRun) {
-      results.push({ agent: t, dir: dest, action: "would-delete", exists: true });
+      results.push({
+        agent: t,
+        dir: dest,
+        action: lstat.isSymbolicLink() ? "would-unlink" : "would-delete",
+        exists: true,
+      });
       continue;
     }
     fs.unlinkSync(dest);
-    try { fs.rmdirSync(dir); } catch (_) {}
-    results.push({ agent: t, dir: dest, action: "deleted", exists: false });
+    const parent = path.dirname(dest);
+    try { fs.rmdirSync(parent); } catch (_) {}
+    results.push({
+      agent: t,
+      dir: dest,
+      action: lstat.isSymbolicLink() ? "unlinked" : "deleted",
+      exists: false,
+    });
   }
   return results;
 }
 
-module.exports = { install, uninstall, listTargets, targetFile, skillSrc, ALIAS_TO_GROUP, SKILL_NAME };
+module.exports = { install, uninstall, listTargets, targetFile, skillSrc, ALIAS_TO_GROUP, RELATIVE_DIRS, SKILL_NAME, CANONICAL, LINK_TARGETS };