finch-remote-host 0.0.0-stage → 1.0.0

package/finch.json

@@ -0,0 +1,39 @@
+{
+    "manifestVersion": 1,
+    "name": "远程主机",
+    "miniToolType": "local",
+    "main": "dist/index.js",
+    "activationEvents": ["onStartup"],
+    "systemPrompt": "在用户配置的远程服务器上跑命令、查日志、看服务状态时用 remote_host。",
+    "contributes": {
+        "tools": true,
+        "skills": true,
+        "settingsMenu": {
+            "icon": "square-terminal",
+            "tooltip": "远程主机与策略"
+        },
+        "composerActions": [
+            {
+                "id": "host",
+                "icon": "square-terminal",
+                "tooltip": "远程主机"
+            }
+        ],
+        "appPanel": {
+            "icon": "square-terminal",
+            "viewType": "remote-host.manager",
+            "instanceMode": "single",
+            "showInLauncher": true,
+            "source": {
+                "type": "local",
+                "path": "ui/panel.html"
+            }
+        }
+    },
+    "permissions": {
+        "filesystem": "readwrite",
+        "network": false,
+        "shell": true,
+        "secrets": ["host.*"]
+    }
+}

package/i18n/zh-CN.json

@@ -0,0 +1,34 @@
+{
+    "name": "远程主机",
+    "description": "在 Finch 里管理远程主机，让 Agent 通过 SSH 执行命令，危险操作先经用户确认，全部动作留审计。",
+    "systemPrompt": "在用户配置的远程服务器上跑命令、查日志、看服务状态时用 remote_host。",
+    "menu": {
+        "count": "{count} 台主机",
+        "empty": "还没有配置主机",
+        "ok": "上次成功",
+        "failed": "上次退出码 {code}",
+        "panel": "打开主机面板",
+        "noHosts": "还没配置主机",
+        "clear": "清除本会话的选择"
+    },
+    "badge": {
+        "pick": "选主机"
+    },
+    "confirm": {
+        "title": "在 {host} 上执行？",
+        "description": "目标：{target}\n判定：{hits}\n\n{command}",
+        "submit": "确认执行",
+        "cancel": "取消",
+        "tick": "我已看清命令与目标机"
+    },
+    "progress": {
+        "running": "正在 {host} 上执行…",
+        "streaming": "{host} · {seconds}s · {lines} 行 · {last}",
+        "waiting": "还没输出"
+    },
+    "panel": {
+        "needPassword": "密码认证需要先填密码",
+        "testOk": "连上了",
+        "testFail": "连不上，看下面的输出"
+    }
+}

package/package.json

@@ -1,6 +1,25 @@
 {
-  "name": "finch-remote-host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "finch-remote-host",
+    "version": "1.0.0",
+    "description": "在 Finch 里管理远程主机，让 Agent 通过 SSH 执行命令，危险操作先经用户确认，全部动作留审计。",
+    "keywords": [
+        "devops",
+        "finch",
+        "finch-minitool",
+        "remote-host",
+        "server",
+        "ssh"
+    ],
+    "license": "MIT",
+    "files": [
+        "finch.json",
+        "dist/",
+        "i18n/",
+        "skills/",
+        "ui/",
+        "icon.png",
+        "README.md"
+    ],
+    "type": "module",
+    "main": "dist/index.js"
+}

package/skills/remote-host/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: remote-host
+description: 远程主机的操作手册。用 remote_host 在用户已配置的服务器上读文件、查状态、跑命令之前先读它，尤其是四种策略模式的差别、只读判定的边界、规则写 glob 时的匹配方式，以及命令被拒绝或需要确认时怎么处理。
+---
+
+# 远程主机
+
+`remote_host` 操作的是用户在面板里手工添加过的主机：认证用磁盘上的私钥或系统安全存储里的密码，Agent 既不接触凭据，也不能新增或修改主机。
+
+## 心智模型
+
+- **主机是用户给的权限，不是 Agent 的资源。** 没有 `hosts` 里出现的主机，就是不存在。
+- **认证方式不用关心。** 密钥机与密码机对你完全一样；密码机若没存密码，`exec` 会直接报错，让用户去面板补。
+- **每条命令都过一次分类器。** 结论只有三种：直接跑、等用户确认、拒绝。
+- **一切留痕。** 每次执行都写审计，包括被拒绝和用户取消的那些。
+
+## 四种策略
+
+| 模式       | 只读命令 | 写操作 | 读凭据文件 | 典型场景                 |
+| ---------- | -------- | ------ | ---------- | ------------------------ |
+| `query`    | 直接跑   | 拒绝   | 拒绝       | 只要看得出状态的监控机   |
+| `readonly` | 直接跑   | 拒绝   | 确认       | 生产库、核心网关，只许看 |
+| `confirm`  | 直接跑   | 确认   | 确认       | 默认值，日常运维         |
+| `trusted`  | 直接跑   | 直接跑 | 直接跑     | 自己的跳板机、一次性环境 |
+
+硬拒清单不看模式，也不给确认按钮：删根目录、删任何一级目录（含 `rm -rf /var/*` 这种清空）、不带路径的通配删除（`rm -rf *`）、`mkfs`、`dd` 写裸盘、重定向写块设备、fork 炸弹、关机重启、`chmod 777 /`。
+
+判硬拒时先去掉引号再按段扫，`sudo rm -rf /var`、`sh -c "rm -rf /var"` 同样拦下；二级以下路径（`rm -rf /var/log/nginx`）归模式管。
+
+### 保护路径
+
+这些位置被删除、清空、截断、重定向写入时直接拒绝，不看模式：
+
+- 整棵子树：`/etc`、`/boot`、`/bin`、`/sbin`、`/lib*`、`/usr`、`/root`、`/var/www`、`/var/spool`、任何位置的 `.ssh`
+- 只到直属子目录：`/home`、`/opt`、`/srv`、`/var/lib`（`/var/lib/mysql` 拒，`/var/lib/apt/lists/*` 只要求确认）
+- 名单只收 Linux 通用路径：业务目录（如 `/wwwroot`）删里面只确认，但目录本身是一级目录，`rm -rf /wwwroot` 仍硬拒
+
+拦截的命令：`rm`、`rmdir`、`unlink`、`shred`、`truncate`、`dd of=`、`>`/`>>`、`find -delete`。
+
+`cp`、`mv`、`sed -i`、`tee` 不拦，它们改配置与部署照常走模式。
+
+## 标准节奏
+
+1. `hosts` —— 先看有哪些主机、什么模式、上次结果。标着「当前会话」的那台就是用户已经选好的。
+2. 用户在输入框下方选过主机时，`exec` 可以不传 `hostId`，直接落到那台；没选又没传就会报错，让用户去选。
+3. 第一次连某台机器，先跑 `whoami` 或 `uname -a` 验证连通性（只读，不会弹确认）。
+4. 摸清目录结构再动手：`ls`、`df -h`、`systemctl status <服务>`。
+5. 需要写入的命令一次说清楚：确认卡片显示的就是最终要执行的那一条，所以别把多条命令拼成一个字符串去"试探"，用户看到的越长越容易点取消。
+6. 长任务给 `timeoutSeconds`（默认 120，最大 600），执行期间进度会自己刷秒数、行数与最新一行，不用中途打断去问。输出正文仍是一次性返回，会被截断到头 6 KB + 尾 3 KB。
+7. 预计超过 10 分钟的任务（大构建、全量备份）用 `start` 起后台任务，别硬跑 `exec`：拿到 taskId 后用 `status` 轮询，别再起第二遍。
+8. 后台任务结束前不要凭空猜测进度，`status` 会给行数、日志尾巴和退出码；用户说要停就 `stop`，需要清远端日志再加 `clean`。裸 `nohup` 会让进程失控，不要用。
+
+## 命令怎么写
+
+- 判定按命令拆开后的每一段做：`ls -l` 直跑；`ls && rm -rf x` 里的 `rm` 那段不在白名单，整条走确认；`df -h > /tmp/a` 因为重定向不算只读。
+- 管道会逐段判定，任何一段不过就升级为确认。
+- 读 `.env`、`id_rsa`、`*.pem`、`/etc/shadow` 这类文件，即使只读也要确认——那是凭据。
+- 用户配了放行规则时，规则是 glob，整段匹配：`systemctl restart nginx` 不会放过 `systemctl restart nginx-backup`；`*` 不跨 `/`，跨层级用 `**`。
+- 不要用交互式命令（`vim`、`top`、`less`、`sudo -S`）：没有终端，它们会卡住直到超时。
+- 需要 root 就写 `sudo -n <命令>`，准备好免密；`-n` 让它在没权限时立刻失败而不是等密码。
+
+## 被拒绝或取消时
+
+- 「策略拒绝执行」：这条命令在当前模式下不允许。不要改写绕过（换写法、拆开、编码），直接告诉用户当前模式是什么、要做什么，让用户决定是否调策略。
+- 「用户没有确认」：就是不执行。不要重复发起同一条命令；确有必要，先说清楚为什么要这条命令。
+- 「后台会话没人确认」：任务跑在后台或远程通道上，危险命令必须放弃，改让用户在前台会话里操作。