@zicolasjac-ai/remote-readonly-ssh 1.0.4 → 1.1.1

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 目录。
 
 ## 安装
 
@@ -23,10 +24,12 @@ npm install -g @zicolasjac-ai/remote-readonly-ssh
 ## 快速开始
 
 ```bash
-rrs init          # 生成配置模板 ~/.rrs/config.json
+npm install -g @zicolasjac-ai/remote-readonly-ssh
+rrs init                 # 生成配置模板 ~/.rrs/config.json
+rrs setup skills         # 把 SKILL.md 安装到 opencode / claude / agents 等目录
 # 编辑配置: 填 jump_server / private_key_path / target_hosts
-rrs list-tools    # 查看白名单
-rrs sys-info
+rrs list-tools
+rrs sys-info --json
 ```
 
 ## 用法
@@ -67,6 +70,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/rrs.js

@@ -8,6 +8,7 @@ const { JumpShell, cleanAnsi } = require("../src/jumpshell");
 const {
   validateCmd, validatePath, validateHost, validateArg, validateBin,
 } = require("../src/whitelist");
+const setupSkill = require("../src/setup");
 
 const PACKAGE_ROOT = path.join(__dirname, "..");
 
@@ -22,32 +23,83 @@ 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() {
   const dir = configDir();
   fs.mkdirSync(dir, { recursive: true });
@@ -121,6 +173,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 +218,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { parseArgs, buildCmds, printUsage };
+module.exports = { parseArgs, buildCmds, printUsage, runSetup };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zicolasjac-ai/remote-readonly-ssh",
-  "version": "1.0.4",
-  "description": "只读 SSH 运维 CLI：基于白名单强制校验，通过堡垒机对服务器执行只读查询，设计上零写权限。",
+  "version": "1.1.1",
+  "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,15 @@
     "whitelist",
     "audit",
     "security",
-    "cli"
+    "cli",
+    "agent-skill",
+    "opencode",
+    "claude",
+    "ai"
   ],
   "dependencies": {},
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "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/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 };