fix: expose write_file and document one-click operations

docs: restore established documentation format
docs: synchronize architecture deployment and MCP documentation
2026-10-02 14:07:11 +08:00 · 2026-10-02 14:01:14 +08:00 · 2026-10-02 13:53:00 +08:00
19 changed files with 1535 additions and 741 deletions
@@ -2,12 +2,11 @@

 # VPS-Commander

-**面向 AI Agent (ChatGPT / Claude / MCP) 与个人运维的高性能、极轻量、多节点私有基础设施调度中枢**
+**面向 AI Agent、MCP 与个人运维的高性能、轻量、多节点私有基础设施调度中枢**

 [![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?style=flat&logo=go)](https://golang.org)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Architecture](https://img.shields.io/badge/Arch-Linux%20AMD64%20%7C%20ARM64-orange)](#)
-[![Memory Footprint](https://img.shields.io/badge/Memory-Hub%20%E2%89%A4%2025MB%20%7C%20Agent%20%E2%89%A4%2012MB-brightgreen)](#)

 </div>

@@ -15,210 +14,201 @@

 ## 🌟 核心特性

- ⚡ **极致轻量，极低常驻**：纯 Go 原生编写，静态无依赖编译。Hub 核心管理进程物理常驻内存（RSS）稳定在 **15MB** 左右；受控端 Agent 内存占用仅 **7~11MB**，小内存 VPS 零负担。
- 🤖 **原生 AI 友好 (ChatGPT Actions & MCP 双协议)**：
-  - **OpenAPI 3.1.0 标准**：开箱即用支持 ChatGPT Custom GPTs / Claude Actions。
-  - **MCP (Model Context Protocol)**：内置兼容 SSE 与 JSON-RPC 标准，支持 Cursor、Windsurf、Claude Desktop 等客户端。
-  - **OAuth 2.0 / Bearer 认证**：支持公开客户端授权与 Bearer API Key 访问控制。
- 🌐 **多节点集群架构 (Hub & Agent)**：
-  - 单中心 Hub 统一管理多台受控 VPS。
-  - 远程 Agent 节点通过标准 WebSocket (WSS) 主动建立安全长连接回连，天然穿透 NAT 与内网，无需受控端暴露端口。
- 🛡️ **严格安全防护与权限闭环**：
-  - **零参数泄露**：全面封禁 CLI 敏感传参，凭据由 `0600` 环境变量接管，避免 `/proc/*/cmdline` 泄密。
-  - **完整审计追溯**：内置本地 SQLite 存储，全量记录调用者 IP、下发节点、指令内容、退出码及精确执行耗时。
-  - **执行隔离与超时回收**：内置上下文超时控制，强制清理孤儿进程，彻底杜绝僵尸进程。
- 📊 **实时节点资源画像 (Node Profiling & Role)**：
-  - **原生零依赖深度采集**：直接读取 Linux 内核指标，实时监控物理 CPU 核心数与瞬时负载、真实可用内存（`MemAvailable`）与 Swap、根分区磁盘占用、IO 压力指数（内核原生 PSI / Loadavg）及 Docker 守护进程运行状态。
-  - **动态角色标签**：支持节点角色分工（如 `CONTROL` 控制中枢、`APPLICATION` 应用节点、`DATABASE` 等），为 AI Agent 自动化调度部署决策提供全维度实时依据。
- 🛡️ **设备生命周期管理与防重连黑名单**：
-  - 支持管理员在 Web 控制台一键注销并强制断开指定受控节点。
-  - 持久化吊销拦截（Revocation List），彻底杜绝被下线 Agent 因 Systemd 自动重启而死灰复燃。
-  - 本地主控节点（Local）强制安全锁，防误操作防护。
- 🖥️ **内嵌极简 Web 管理面板**：
-  - 静态单页面（SPA）采用 Go `embed` 完整打包进二进制文件，单文件独立运行，无需安装 Node.js、Nginx 或外部静态资源 CDN。
-  - **工程级双态主题**：纯手绘 SVG 极简几何微图标（太阳/弦月），支持深曜蓝黑与柔和浅灰白一键切换，完美适配系统偏好且零 FOUC 白屏闪烁。
-  - **全端响应式**：彻底适配手机移动端（≤680px），宽表独立触控滑动，长节点名自动断行不穿透。
+- ⚡ **轻量单体部署**：纯 Go 原生编译，Hub、Agent、MCP stdio 均可独立部署。
+- 🤖 **原生 AI / MCP 接入**：提供 HTTP API、MCP SSE、stdio 以及 Agent WebSocket，多种客户端可以共用同一套安全模型。
+- 🌐 **Hub & Agent 双通道架构**：Hub 负责控制与授权，Agent 通过 WSS 主动回连，不要求远端开放入站管理端口。
+- 🛡️ **认证与授权分离**：HTTP/MCP 使用 Bearer API Key；Agent 使用每设备独立 Credential；Tool Registry + Security Snapshot 实现 Low / Medium / High 风险门禁。
+- 📋 **完整审计链**：SQLite 持久化设备、凭据哈希、策略版本、操作审计与 Webhook 配置。
+- 🧩 **多节点能力聚合**：文件、Shell、进程、Session、Agent MCP 等能力由 Hub 统一调度。
+- 🖥️ **内嵌 Web 管理面板**：Go embed 打包，无需 Node.js 运行时。

 ---

-## 🏗️ 架构概览
+## 🏁 研发最初目标
+
+VPS-Commander 最初并不是一个简单的远程 Shell 工具，而是为 AI Agent 建立一个**用户自己控制的私有化 Linux 运维控制面**。
+
+### 1.1 私有化
+- 运维请求通过用户自己的 Hub 和 VPS 节点完成。
+- 不依赖第三方运维 Relay。
+- 凭据、策略和审计数据由用户自己的基础设施控制。
+
+### 1.2 Host-centric 运维
+- 全局 Shell。
+- 全局文件读写。
+- 进程与长任务 Session。
+- 远程 Agent MCP。
+
+### 1.3 多节点统一调度
+- 一个 Hub 管理多个 VPS。
+- 使用节点名称选择目标。
+- 节点离线后保留设备身份与持久化状态。
+
+### 1.4 AI 原生接口
+- HTTP API。
+- MCP。
+- OpenAPI 契约。
+- Web 管理面板。
+
+---
+
+## 🏗️ 当前总体架构

 ```text
-                  +-----------------------------------+
-                  |     OpenAI ChatGPT / AI Agents   |
-                  +-----------------+-----------------+
-                                    | HTTPS / MCP SSE / WSS
+                  +--------------------------------------+
+                  |      AI / MCP Client / Web Panel    |
+                  +------------------+-------------------+
+                                     | HTTPS / MCP / WSS
                                     v
-                  +-----------------------------------+
-                  |    反向代理 / SSL 终止 (Lucky/Nginx)|
-                  +-----------------+-----------------+
+                  +--------------------------------------+
+                  |       Reverse Proxy / TLS            |
+                  +------------------+-------------------+
                                     | 127.0.0.1:9521
                                     v
-     +-------------------------------------------------------------+
+        +-----------------------------------------------------------+
        |                    VPS-Commander Hub                     |
-     |  - OpenAPI 3.1 & MCP 路由引擎                               |
-     |  - OAuth / Bearer 鉴权与 Session 会话                       |
-     |  - 本地 SQLite 审计数据库 (commander.db)                    |
-     |  - 内嵌 Web 管理面板 (SPA)                                   |
-     +--------------+-------------------------------+--------------+
+        |-----------------------------------------------------------|
+        | Auth / API / MCP / Web Panel                             |
+        | Security Snapshot / Tool Registry / Audit                |
+        | Cluster Router / Session / Rate Limiter                  |
+        +----------------------+-------------------+---------------+
                               |                   |
-        (本地执行通道)                  (WebSocket RPC 长连接通道)
+                         Local Executor       Agent WSS
                               |                   |
                               v                   v
-         +--------------------+          +--------------------+
-         |   宿主机 (Local)    |          |  受控 VPS (Agent)  |
-         |   uname / sh / 文件 |          |  vps-commander-a   |
-         +--------------------+          +--------------------+
+                         Hub 本机             Remote VPS
+                                                   |
+                                            Host Executor
+                                            File / Shell / Process
 ```

 ---

-## 🚀 极速一键部署与平滑升级
+## 🔐 当前安全模型

-### 1. 一键全自动安装 (推荐)
-无论是在受控端 VPS 还是中心端，只需一行命令即可交互式安装与启动：
+### 1. Client Authentication
+`Authorization: Bearer <API_KEY>` 是 HTTP / MCP 的主要客户端认证方式。

-```bash
-bash <(curl -fsSLk https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh)
-```
- **安装 Agent (受控 VPS)**：输入 Hub 的 WSS 地址与通信密钥，全自动配置开机自启并秒级连入集群。
- **安装 Hub (中心服务端)**：自动生成安全 API Key / Web 面板密码并以 Systemd 托管常驻。
+### 2. Agent Authentication
+每个 Agent 使用独立的 `VPS_COMMANDER_AGENT_TOKEN`。
+Hub SQLite 只保存 Credential Hash，不保存明文 Token。

-### 2. 受控端 Agent 一键平滑升级 (免重输配置)
-当新版本发布后，无需重新配置通信密钥或重新安装，在任意受控机上直接运行升级脚本：
+### 3. Authorization
+Tool Registry 首先确定操作风险：

-```bash
-curl -fsSLk https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/upgrade-agent.sh | bash
-```
- 自动检测并拉取 GitHub 最新版本架构包（AMD64 / ARM64）；
- 自动备份旧版本二进制（`.bak`）；
- 升级异常（校验失败或无法启动）时**自动秒级回滚**，保证节点永不失联。
+| 风险 | 典型能力 |
+| :--- | :--- |
+| Low | 读取、搜索、设备/进程观察 |
+| Medium | 文件修改、目录创建/移动、Agent MCP |
+| High | Shell、进程启动、交互、终止 |
+
+未知设备、未知身份或策略无法解析时不得获得 High 权限。
+
+### 4. Shared Secret
+生产环境已经关闭 Cluster Secret / Shared Secret fallback。

 ---

-## 🛠️ 手动编译部署
+## 🤖 当前 MCP 能力

-### 1. Hub 服务端部署
+目前共 **11 个 MCP Tools**：

-在中心管理机上部署 Hub：
-
-```bash
-# 1. 编译二进制
-make linux-amd64
-
-# 2. 安装二进制文件
-install -d -m 0750 /opt/vps-commander/data /etc/vps-commander
-install -m 0755 bin/vps-commander-hub-linux-amd64 /opt/vps-commander/vps-commander-hub
-
-# 3. 创建环境变量配置 (注意保护权限)
-cat << 'ENV' > /etc/vps-commander/hub.env
-VPS_COMMANDER_API_KEY=your_secure_api_key_here
-VPS_COMMANDER_CLUSTER_SECRET=your_cluster_sync_secret_here
-VPS_COMMANDER_WEB_PASSWORD=your_web_panel_password_here
-ENV
-chmod 0600 /etc/vps-commander/hub.env
-
-# 4. 配置并启动 Systemd 服务
-cp deploy/vps-commander-hub.service /etc/systemd/system/
-systemctl daemon-reload
-systemctl enable --now vps-commander-hub
-```
-
-### 2. 远程 VPS Agent 受控端部署
-
-在需要受控的远程 VPS 机器上执行：
-
-```bash
-# 1. 下载或拷贝 agent 二进制至远程机器
-install -d -m 0750 /etc/vps-commander /opt/vps-commander
-install -m 0755 vps-commander-agent-linux-amd64 /opt/vps-commander/vps-commander-agent
-
-# 2. 配置 Agent 环境变量
-cat << 'ENV' > /etc/vps-commander/agent.env
-VPS_COMMANDER_HUB_WS_URL=wss://your-domain.com/agent/ws
-VPS_COMMANDER_AGENT_NAME=vps-us-node01
-VPS_COMMANDER_CLUSTER_SECRET=your_cluster_sync_secret_here
-ENV
-chmod 0600 /etc/vps-commander/agent.env
-
-# 3. 配置并启动 Systemd 服务
-cp deploy/vps-commander-agent.service /etc/systemd/system/
-systemctl daemon-reload
-systemctl enable --now vps-commander-agent
-```
-Agent 启动后会通过 WSS 自动连入 Hub，在 Hub 管理面板与 `/api/v1/devices` 接口中实时显示为 `online`。
-
---
-
-## 🤖 接入 ChatGPT (新版插件 Apps & MCP 模式)
-
-当前 ChatGPT 已升级为以 **插件 / 应用 (Apps & MCP)** 规范连接外部服务。VPS-Commander 原生内置完整的 **MCP SSE + OAuth2** 协议支持，无需部署额外适配层。
-
-### 接入配置步骤：
-
-1. **进入 ChatGPT 插件/应用配置页**：
-   - 打开 ChatGPT -> **Settings (设置)** -> **Apps & Integrations (应用与集成) / Plugins** -> **Create / Add App (添加应用)**。
-2. **连接方式选择 MCP**：
-   - 连接协议选择 **MCP (Model Context Protocol)** 或 **Server-Sent Events (SSE)**。
-   - **MCP Server URL**：填入 Hub 的 SSE 统一入口：
-     ```text
-     https://your-domain.com/mcp/sse
-     ```
-3. **身份认证 (Authentication)**：
-   - **方式 A (OAuth 2.0 自动授权，推荐)**：
-     - Hub 内置了标准 RFC 8414 OAuth Metadata (`/.well-known/oauth-authorization-server`)；
-     - 授权端点与 Token 端点由 ChatGPT 自动识别，一键点击「Authorize」即可完成免密安全绑定。
-   - **方式 B (Bearer API Key)**：
-     - 若选择 API Key，填入 Hub 环境变量 `VPS_COMMANDER_API_KEY` 即可。
-4. **自动发现 4 大运维工具**：
-   - 握手成功后，ChatGPT 会自动加载并列出 4 个原生运维工具：
-     - `list_devices`：列出受控节点、CPU/内存/磁盘剩余绝对值及 Docker 状态；
-     - `exec_command`：在目标机器（如 `m4-live-agent`）执行 Shell 指令；
-     - `read_file`：分页读取目标文件；
-     - `write_file`：远程编辑或创建文件。
-
---
-
-### 传统客户端支持 (Claude Desktop / Cursor / VS Code)
-
-支持通过本地 stdio 二进制连接 Hub：
-```json
-{
-  "mcpServers": {
-    "vps-commander": {
-      "command": "/path/to/vps-commander-mcp-stdio-linux-amd64",
-      "args": [
-        "-hub", "https://your-domain.com",
-        "-key", "YOUR_API_KEY"
-      ]
-    }
-  }
-}
-```
-
---
-
-## 📊 接口与能力一览
-
-| 接口路径 | 方法 | 功能描述 |
+| Tool | Risk | 功能 |
 | :--- | :--- | :--- |
-| `/api/v1/devices` | `GET` | 列出集群中所有受控设备状态与**实时资源画像 (CPU/Mem/Disk/IO PSI/Docker/Role)** |
-| `/panel/api/devices` | `DELETE` | 【管理员】注销并踢出指定受控节点，持久化写入防重连黑名单 |
-| `/api/v1/exec` | `POST` | 在指定受控节点执行任意 Shell 指令（支持超时截断） |
-| `/api/v1/file/read` | `POST` | 安全分页读取目标机器上的文件内容（防内存溢出） |
-| `/api/v1/file/write` | `POST` | 向目标机器指定路径覆写或创建文件 |
-| `/mcp/sse` | `GET` | MCP 协议长连接事件流通道 |
-| `/panel/login` | `GET/POST`| 内嵌 Web 运维管理控制台 |
+| `list_devices` | Low | 节点列表与状态 |
+| `exec_command` | High | Shell 执行 |
+| `read_file` | Low | 分页读取文件 |
+| `read_multiple_files` | Low | 批量读取文件 |
+| `create_directory` | Medium | 创建目录 |
+| `move_file` | Medium | 移动/重命名 |
+| `list_processes` | Low | 进程观察 |
+| `edit_block` | Medium | 原子文本修改 |
+| `write_file` | Medium | 创建/覆写文件 |
+| `list_agent_mcp` | Low | 查看 Agent MCP |
+| `call_agent_mcp` | Medium | 调用 Agent MCP |
+
+远程 MCP 当前使用 **legacy HTTP + SSE**；本地客户端使用 stdio。
+Streamable HTTP 作为下一阶段 transport 演进方向。
+
+---
+
+## 📊 HTTP / Web 能力
+
+| 接口 | 方法 | 功能 |
+| :--- | :--- | :--- |
+| `/api/v1/devices` | GET | 设备状态与资源画像 |
+| `/api/v1/exec` | POST | 远程 Shell |
+| `/api/v1/file/read` | POST | 文件读取 |
+| `/api/v1/file/list` | POST | 目录列表 |
+| `/api/v1/file/info` | POST | 文件信息 |
+| `/api/v1/file/search` | POST | 文件搜索 |
+| `/api/v1/file/write` | POST | 文件写入 |
+| `/api/v1/devices/file/edit_block` | POST | 安全块编辑 |
+| `/api/v1/process/session` | POST | Session 操作 |
+| `/api/v1/mcp/*` | GET/POST/DELETE | MCP 服务管理与调用 |
+| `/api/v1/security/*` | GET/POST | 安全策略 |
+| `/api/v1/notifications/webhook*` | GET/POST/DELETE | Webhook |
+| `/agent/ws` | WebSocket | Agent 长连接 |
+| `/panel/*` | GET/POST | Web 管理面板 |
+
+---
+
+## 🚀 生产部署
+
+Hub：
+```text
+/opt/vps-commander/vps-commander-hub
+/etc/vps-commander/hub.env
+/opt/vps-commander/data/commander.db
+127.0.0.1:9521
+```
+
+Agent：
+```text
+/opt/vps-commander/vps-commander-agent
+/etc/vps-commander/agent.env
+wss://vpstool.kory.kdns.fr/agent/ws
+```
+
+Agent 只主动连接 Hub，不需要公网入站端口。
+
+生产发布顺序：
+`backup → clean build → 单节点灰度 → Hub restart recovery → rolling Agent → MCP/security/audit 验收`。
+
+---
+
+## 🚀 一键安装与升级
+
+### 一键安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash
+```
+
+安装脚本自动识别 `amd64/arm64` 并进入 Hub / Agent 安装流程。
+
+### 一键升级 Agent
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/upgrade-agent.sh | sudo bash
+```
+
+升级脚本下载目标 Release、校验文件大小、备份旧版本并在启动失败时自动回滚。
+
+生产环境的 Agent 凭据以独立设备凭据为准；不要将 Cluster Secret 作为长期生产凭据重新启用。

 ---

 ## 📄 文档索引

- [生产部署指南与运维手册](deploy/README.md)
- [系统架构与安全设计说明](docs/ARCHITECTURE.md)
- [研发设计规范与内存基线](docs/DEV_SPEC.md)
- [阶段验收标准与门禁用例矩阵](docs/ACCEPTANCE_CRITERIA.md)
- [MCP 客户端接入协议文档](docs/MCP_INTEGRATION.md)
+- [文档基线与全局索引](docs/DOCUMENTATION_BASELINE_20261002.md)
+- [系统架构与开发设计规范](docs/ARCHITECTURE.md)
+- [研发与协议规范](docs/DEV_SPEC.md)
+- [MCP 接入指南](docs/MCP_INTEGRATION.md)
+- [生产部署与运维指南](deploy/README.md)
+- [发布验收标准](docs/ACCEPTANCE_CRITERIA.md)
+- [项目进度与路线图](docs/PROGRESS_TRACKING.md)
+- [v2.1 安全加固规范](docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md)

 ---

@@ -1,79 +1,139 @@
 # VPS-Commander 部署与运维指南

-本文档介绍 VPS-Commander 的生产环境部署架构、配置规范与运维操作。
+本文档介绍 VPS-Commander 当前生产环境部署架构、凭据规范、Agent 接入、升级与回滚流程。

 ---

-## 一、 系统架构与端口规划
+## 一、系统架构与端口规划

- **Hub 服务端**：统一监听本地 `127.0.0.1:9521`，不对公网直接暴露端口。
- **反向代理 (Lucky)**：
-  - 域名：`https://vpstool.kory.kdns.fr`
-  - 转发目标：`http://127.0.0.1:9521`
-  - 核心要求：开启 **WebSocket Upgrade** 支持，转发透传所有子路径（`/.well-known/*`、`/oauth/*`、`/mcp/*`、`/api/v1/*`、`/agent/ws`、`/panel/*`）。
-  - SSL 终止于反代层，反代自动携带 `X-Forwarded-Proto: https` 头以保障 Cookie 的 `Secure` 属性。
- **Agent 客户端**：
-  - 运行于受控的远程 VPS 机器上。
-  - 通过公网 WSS 长连接主动回连 Hub：`wss://vpstool.kory.kdns.fr/agent/ws`。
+- **Hub 服务端**：监听 `127.0.0.1:9521`，不直接暴露公网。
+- **反向代理**：公网 HTTPS/WSS 入口为 `https://vpstool.kory.kdns.fr`。
+- **Agent 客户端**：通过 `wss://vpstool.kory.kdns.fr/agent/ws` 主动回连 Hub。
+
+反代必须支持：
+- WebSocket Upgrade；
+- `/agent/ws`；
+- `/mcp/*`；
+- `/api/v1/*`；
+- `/panel/*`；
+- `/.well-known/*`；
+- `/oauth/*`。

 ---

-## 二、 凭据安全规范（强制要求）
+## 二、凭据安全规范（强制要求）

-1. **绝对禁止命令行参数传密**：
-   - 二进制不再支持 `--api-key`、`--cluster-secret`、`--web-password` 命令行参数。
-   - 彻底杜绝在 `/proc/*/cmdline` 和 `ps aux` 中泄露明文密码。
-2. **凭据存储位置与权限**：
-   - 凭据文件保存在 `/etc/vps-commander/hub.env` 与 `/etc/vps-commander/agent.env`。
-   - 权限必须严格设置为 `0600`（仅 root 可读写）。
+### 2.1 Hub 凭据
+Hub 使用：
+- `VPS_COMMANDER_API_KEY`；
+- `VPS_COMMANDER_WEB_PASSWORD`。
+
+生产环境不再依赖 `VPS_COMMANDER_CLUSTER_SECRET` 作为 Agent 身份 fallback。
+
+### 2.2 Agent 凭据
+每台 Agent 使用独立：
+`VPS_COMMANDER_AGENT_TOKEN`。
+
+Hub SQLite 仅保存 Credential Hash。
+
+### 2.3 文件权限
+```bash
+chmod 0600 /etc/vps-commander/hub.env
+chmod 0600 /etc/vps-commander/agent.env
+```
+
+### 2.4 v2.1 安全要求
+当前 v2.0 代码仍兼容旧的 `-token` 参数；下一版本要求 Secret 不出现在 argv / `/proc/*/cmdline`，优先使用 systemd EnvironmentFile / LoadCredential。

 ---

-## 三、 Hub 服务端部署步骤
+## 三、一键安装与升级

-### 1. 编译并安装二进制
+### 3.1 一键安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash
+```
+
+脚本自动识别 `amd64/arm64`，并进入 Hub / Agent 安装流程。
+
+- Hub：自动生成 API Key 与 Web 面板密码。
+- Agent：输入 Hub WSS 地址、节点名称和独立 Agent Token。
+- 生产环境不再要求 Cluster Secret 作为长期凭据。
+
+### 3.2 一键升级 Agent
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/upgrade-agent.sh | sudo bash
+```
+
+升级流程：
+
+```text
+下载 Release
+   ↓
+临时文件完整性检查
+   ↓
+备份当前 Agent
+   ↓
+原子替换
+   ↓
+systemd restart
+   ↓
+健康检查
+   ├─ 成功 → 删除备份
+   └─ 失败 → 自动恢复旧版本
+```
+
+### 3.3 手工安装
+
+如果需要固定版本、离线部署或灰度验证，再使用下面的手工安装流程。
+
+---
+
+## 四、Hub 服务端部署步骤
+
+### 4.1 编译
 ```bash
 cd /root/.openclaw/workspace/vps-commander
+go test ./...
+go test -race ./...
+git diff --check
+make clean
 make linux-amd64
+```
+
+发布前必须确认：
+```text
+vcs.modified=false
+vcs.revision=<release commit>
+```
+
+### 4.2 安装
+```bash
 install -d -m 0750 /opt/vps-commander/data /etc/vps-commander
 install -m 0755 bin/vps-commander-hub-linux-amd64 /opt/vps-commander/vps-commander-hub
 ```

-### 2. 配置环境变量文件 (`/etc/vps-commander/hub.env`)
+### 4.3 配置
 ```bash
 cat << 'ENV' > /etc/vps-commander/hub.env
-VPS_COMMANDER_API_KEY=your_generated_api_key_here
-VPS_COMMANDER_CLUSTER_SECRET=your_generated_cluster_secret_here
-VPS_COMMANDER_WEB_PASSWORD=your_generated_web_password_here
+VPS_COMMANDER_API_KEY=your_secure_api_key
+VPS_COMMANDER_WEB_PASSWORD=your_web_password
 ENV
 chmod 0600 /etc/vps-commander/hub.env
 ```

-### 3. 配置 Systemd 托管 (`/etc/systemd/system/vps-commander-hub.service`)
+### 4.4 Systemd
 ```ini
-[Unit]
-Description=VPS-Commander Hub
-After=network-online.target
-Wants=network-online.target
-
 [Service]
-Type=simple
-User=root
-WorkingDirectory=/opt/vps-commander
 EnvironmentFile=-/etc/vps-commander/hub.env
 ExecStart=/opt/vps-commander/vps-commander-hub -addr 127.0.0.1:9521 -db /opt/vps-commander/data/commander.db
 Restart=always
 RestartSec=3s
-KillSignal=SIGTERM
-TimeoutStopSec=10s
-LimitNOFILE=65536
-Environment=GOGC=50
-
-[Install]
-WantedBy=multi-user.target
 ```

-### 4. 启动服务
+### 4.5 启动
 ```bash
 systemctl daemon-reload
 systemctl enable --now vps-commander-hub
@@ -82,62 +142,99 @@ systemctl status vps-commander-hub

 ---

-## 四、 远程 Agent 节点部署步骤
+## 五、远程 Agent 节点部署步骤

-若要将其他 VPS 纳入受控列表，在该远程 VPS 上执行：
+### 5.1 安装二进制
+```bash
+install -d -m 0750 /etc/vps-commander /opt/vps-commander
+install -m 0755 vps-commander-agent-linux-amd64 /opt/vps-commander/vps-commander-agent
+```

-### 1. 安装 Agent 二进制
-将编译生成的 `bin/vps-commander-agent-linux-amd64`（或 ARM64 版本）上传至目标 VPS 的 `/opt/vps-commander/vps-commander-agent` 并赋予执行权限 `chmod +x`。
-
-### 2. 配置 Agent 环境变量 (`/etc/vps-commander/agent.env`)
+### 5.2 配置
 ```bash
-install -d -m 0750 /etc/vps-commander
 cat << 'ENV' > /etc/vps-commander/agent.env
 VPS_COMMANDER_HUB_WS_URL=wss://vpstool.kory.kdns.fr/agent/ws
 VPS_COMMANDER_AGENT_NAME=vps-node-01
-VPS_COMMANDER_CLUSTER_SECRET=与Hub相同的CLUSTER_SECRET
+VPS_COMMANDER_AGENT_TOKEN=<per-device-token>
 ENV
 chmod 0600 /etc/vps-commander/agent.env
 ```

-### 3. 配置 Systemd 托管 (`/etc/systemd/system/vps-commander-agent.service`)
+### 5.3 Systemd
 ```ini
-[Unit]
-Description=VPS-Commander Agent
-After=network-online.target
-Wants=network-online.target
-
 [Service]
-Type=simple
-User=root
-WorkingDirectory=/opt/vps-commander
 EnvironmentFile=-/etc/vps-commander/agent.env
 ExecStart=/opt/vps-commander/vps-commander-agent -hub ${VPS_COMMANDER_HUB_WS_URL} -name ${VPS_COMMANDER_AGENT_NAME}
 Restart=always
 RestartSec=3s
-KillSignal=SIGTERM
-TimeoutStopSec=10s
-LimitNOFILE=65536
-Environment=GOGC=50
-
-[Install]
-WantedBy=multi-user.target
 ```

-### 4. 启动并连入集群
+当前 v2.0 生产迁移阶段可兼容显式 token；v2.1 发布后必须改为不出现在 ExecStart 的方式。
+
+### 5.4 启动
 ```bash
 systemctl daemon-reload
 systemctl enable --now vps-commander-agent
+systemctl status vps-commander-agent
 ```
-启动后，Hub 控制面板与 `/api/v1/devices` 接口将立即展示该节点并标记为 `online`。
+
+Agent 启动后主动连接 Hub，并在设备列表中显示为 `online`。

 ---

-## 五、 控制面板与 Actions 使用
+## 六、控制面板与 MCP 使用

-1. **管理后台地址**：`https://vpstool.kory.kdns.fr/panel/login`
-2. **后台功能**：
-   - **设备看板**：查看所有在线/离线节点、系统架构与延迟。
-   - **快速控制台**：直接在网页端向指定节点执行 Shell 指令。
-   - **审计日志**：实时监控 GPT 与用户的全部执行调用、命令详情与耗时。
-   - **Actions 向导**：一键复制 Schema 地址、System Prompt 与 API 密钥。
+### 6.1 管理面板
+`https://vpstool.kory.kdns.fr/panel/login`
+
+面板包含设备状态、安全策略、操作控制、审计和相关管理功能。
+
+### 6.2 MCP
+远程入口：
+`https://vpstool.kory.kdns.fr/mcp/sse`
+
+本地 stdio 使用 `vps-commander-mcp-stdio`。
+
+当前共 11 个 MCP tools，详见 `docs/MCP_INTEGRATION.md`。
+
+---
+
+## 七、生产升级流程
+
+```text
+Backup
+  ↓
+Clean Build
+  ↓
+Single-node Gray Release
+  ↓
+Hub Restart Recovery
+  ↓
+Rolling Agent
+  ↓
+MCP / Security / Audit Smoke Test
+  ↓
+Full Acceptance
+```
+
+任一节点断联、权限绕过、Credential 泄露或协议不兼容，立即停止发布并回滚。
+
+---
+
+## 八、日常运维检查
+
+```bash
+systemctl status vps-commander-hub
+journalctl -u vps-commander-hub -n 100
+curl -fsS http://127.0.0.1:9521/healthz
+```
+
+集群可通过 Web Panel、`/api/v1/devices` 或 MCP `list_devices` 检查。
+
+---
+
+## 九、当前生产审计提示
+
+2026-10-02 审计发现生产 Hub / Agent 曾由 `vcs.modified=true` 的工作树构建。
+因此生产现场二进制不能直接视为当前 HEAD 的可复现产物。
+下一次正式发布必须 clean rebuild，并重新部署与验证。
@@ -72,15 +72,15 @@ install_agent() {
    read -rp "请输入本节点名称 (默认: ${DEFAULT_NAME}): " AGENT_NAME
    AGENT_NAME=${AGENT_NAME:-${DEFAULT_NAME}}

-    read -rp "请输入 Cluster Secret (集群通信密钥): " CLUSTER_SECRET
-    while [ -z "$CLUSTER_SECRET" ]; do
-        read -rp "Cluster Secret 不能为空，请重新输入: " CLUSTER_SECRET
+    read -rp "请输入 Agent 独立凭据 Token: " AGENT_TOKEN
+    while [ -z "$AGENT_TOKEN" ]; do
+        read -rp "Agent Token 不能为空，请重新输入: " AGENT_TOKEN
    done

    cat << ENV > "${CONF_DIR}/agent.env"
 VPS_COMMANDER_HUB_WS_URL=${HUB_WS}
 VPS_COMMANDER_AGENT_NAME=${AGENT_NAME}
-VPS_COMMANDER_CLUSTER_SECRET=***
+VPS_COMMANDER_AGENT_TOKEN=${AGENT_TOKEN}
 ENV
    chmod 0600 "${CONF_DIR}/agent.env"

@@ -133,23 +133,19 @@ install_hub() {
    read -rp "请输入监听端口 (默认 9521): " HUB_PORT
    HUB_PORT=${HUB_PORT:-9521}

-    GEN_API_KEY=*** -c 24 /dev/urandom | xxd -p)
-    GEN_SECRET=*** -c 24 /dev/urandom | xxd -p)
+    GEN_API_KEY=$(head -c 24 /dev/urandom | xxd -p)
    GEN_PASS=$(head -c 16 /dev/urandom | xxd -p)

    read -rp "请输入 API Key (默认随机生成): " API_KEY
-    API_KEY=***
-
-    read -rp "请输入 Cluster Secret (默认随机生成): " CLUSTER_SECRET
-    CLUSTER_SECRET=${CLUS…RET}
+    API_KEY=${API_KEY:-$GEN_API_KEY}

    read -rp "请输入 Web 管理面板密码 (默认随机生成): " WEB_PASS
    WEB_PASS=${WEB_PASS:-$GEN_PASS}

    cat << ENV > "${CONF_DIR}/hub.env"
-VPS_COMMANDER_API_KEY=***
-VPS_COMMANDER_CLUSTER_SECRET=***
-VPS_COMMANDER_WEB_PASSWORD=***
+VPS_COMMANDER_API_KEY=${API_KEY}
+VPS_COMMANDER_WEB_PASSWORD=${WEB_PASS}
+ENV
 ENV
    chmod 0600 "${CONF_DIR}/hub.env"

@@ -185,7 +181,6 @@ SVC
        echo -e "\n================== Hub 配置凭据 =================="
        echo -e "监听地址: 127.0.0.1:${HUB_PORT}"
        echo -e "API Key: ${API_KEY}"
-        echo -e "Cluster Secret: ${CLUSTER_SECRET}"
        echo -e "Web 面板密码: ${WEB_PASS}"
        echo -e "==================================================\n"
        warn "请妥善保管上述凭据，反代请将域名反代至 127.0.0.1:${HUB_PORT}"
@@ -1,50 +1,131 @@
-# VPS-Commander 验收审核标准与收尾门禁规范 (Quality Gate & Acceptance Criteria)
+# VPS-Commander 阶段验收标准与发布门禁用例矩阵

-> 本规范由架构与质量负责人（OpenClaw）制定并执行最终裁决。
-> 任何交付代码必须满足以下全量准入与准出指标方可判定为验收通过（Release Ready）。
+本文档定义当前 v2.0 生产架构的发布门禁，并为 v2.1 安全加固预留验收项。

 ---

-## 一、 核心门禁四不原则（强制一票否决项）
+## 一、构建与版本一致性

-1. **绝对无外部公网中转**：任何网络交互（除与 OpenAI 官方通信外）严禁经过第三方 Relay 服务器，必须 100% 走私有域名直连。
-2. **绝对零残留孤儿进程**：执行任何命令、超时中断或连接断开后，后台不得产生僵尸进程或孤儿子进程。
-3. **绝对无未授权越权**：所有非公共接口必须强制 Bearer Token / Cluster Secret 校验，缺失或错误凭证必须严厉返回 HTTP 401，严禁静默放行。
-4. **内存超标即挂**：Hub 静态常驻物理内存不得突破 **25 MB**，Agent 客户端常驻物理内存不得突破 **12 MB**；10MB 为优化目标。
+### 1.1 基础测试
+```bash
+go test ./...
+go test -race ./...
+git diff --check
+```
+
+### 1.2 生产构建
+- Git 工作树必须 clean。
+- `vcs.modified=false`。
+- `vcs.revision` 必须等于 release commit。
+- AMD64 / ARM64 编译成功。

 ---

-## 二、 详细验收测试用例矩阵 (12 项全绿门禁)
+## 二、Hub / Agent 集群验收

-| 用例 ID | 验证模块 | 测试动作与输入 | 预期结果与合格标准 | 验证方式 |
-| :--- | :--- | :--- | :--- | :--- |
-| **TC-01** | **OpenAPI 规范合法性** | `GET /openapi.json` | 格式符合 OpenAPI 3.1.0 标准，包含 servers URL、4 个标准 path、安全定义为 `bearerAuth`（HTTP Bearer），可通过 Swagger / OpenAI Actions 校验无报错。 | 机器静态校验 |
-| **TC-02** | **未授权拦截** | 无 Token 请求 `/api/v1/exec` | 立即返回 HTTP 401 Unauthorized，响应体包含 `{"error": "Unauthorized"}`，不触发任何底层 bash。 | `curl -i` 验证 |
-| **TC-03** | **本地基础命令执行** | `POST /api/v1/exec` (`{"device":"local","command":"uname -a"}`) | 返回 exit_code: 0，stdout 正确包含 Linux 内核信息，duration_ms > 0 且合理。 | 实测响应校验 |
-| **TC-04** | **命令超时与进程回收** | 执行 `sleep 10`，设置 `timeout: 2` | 命令在 2 秒后强制终止，返回超时错误，且检查系统进程树确认 `sleep` 进程彻底消失，无僵尸残留。 | `ps -ef` 核查 |
-| **TC-05** | **文件分页读取防爆** | 读取 10MB 文本文件，设置 `limit: 1024` | 仅返回前 1024 字节内容，返回 `total_size` 与 `has_more: true`，严禁一次性将全文件读入内存。 | 接口响应验证 |
-| **TC-06** | **文件安全覆写** | `POST /api/v1/file/write` 写入 `/tmp/vps_cmd_test.txt` | 文件内容精确写入，权限正常，支持覆盖写入。 | 本地文件比对 |
-| **TC-07** | **Agent 握手与注册** | 启动 Agent 连入 Hub WSS | Hub 面板与 `GET /api/v1/devices` 瞬间显示该设备为 `online`，展示正确 IP 与内核信息。 | 状态机校验 |
-| **TC-08** | **心跳保活与离线感知** | 模拟杀死 Agent 进程 | 经过 2 个心跳周期（~60s）后，Hub 自动将该节点状态变更为 `offline`，不发生 panic。 | 节点状态监听 |
-| **TC-09** | **跨节点路由下发** | `POST /api/v1/exec` (`{"device":"hwsg","command":"uptime"}`) | Hub 正确通过 WebSocket 寻址到远程 Agent，Agent 执行并原路返回，耗时增加在 RTT 合理范围内。 | 跨机实测 |
-| **TC-10** | **Web 管理面板嵌入** | 浏览器直接访问 `GET /` | 页面秒开，设备列表、ChatGPT 向导、审计日志正常渲染，无任何外部 CDN 404，无 node 构建产物遗留。 | 浏览器/Headless 验证 |
-| **TC-11** | **审计日志完备性** | 执行一次正常命令与一次失败命令 | 查询 SQLite `audit_logs` 表，两条记录均完整存在（含 IP、设备、指令、退出码、耗时），字段无空缺。 | SQLite 查询比对 |
-| **TC-12** | **内存基线压测** | 连续并发执行 100 次 `ps aux` | 压测结束后，Hub RSS 必须 ≤ 25MB；20MB 为优化目标。压测结束后应回落并稳定，无持续增长趋势。 | `ps -eo rss` 采样 |
+| 项目 | 验收标准 |
+| :--- | :--- |
+| Hub | 监听 `127.0.0.1:9521` |
+| Agent | 5 个远程节点可正常回连 |
+| Restart | Hub 重启后 Agent 自动恢复 |
+| Identity | Credential 与设备身份一致 |
+| Unknown | 未知设备必须 fail-closed |

 ---

-## 三、 严格收尾与交付规范 (Sign-off Checklist)
+## 三、认证与授权验收

-GPT 完成开发提交代码后，由我执行以下严苛收尾工作：
-1. **代码审计 (Code Review)**：
-   - 检查并发安全性（互斥锁 `sync.RWMutex` 是否合理、Channel 是否有阻塞泄漏风险）。
-   - 检查外部输入 Shell 命令的执行上下文，是否存在注入或不可控行为。
-2. **构建与打包 (Clean Build)**：
-   - 生成标准的 `Makefile`，支持编译 Linux AMD64/ARM64 静态无依赖产物。
-   - 清理所有中间编译缓存与临时测试文件。
-3. **部署托管与 Systemd 固化**：
-   - 为 Hub 编写规范的 `vps-commander-hub.service`。
-   - Lucky 反代添加规则及 SSL 校验。
-4. **终验报告与归档**：
-   - 输出完整的《VPS-Commander 最终验收合格报告》。
-   - 将完整配置参数与使用说明同步至长期记忆 `MEMORY.md`。
+- Bearer API Key 正常。
+- URL token (`?token` / `?key` / `?api_key`) 必须拒绝。
+- 每设备 Credential 独立。
+- Shared Secret fallback 关闭。
+- Panel Admin Token 不进入浏览器。
+- Tool Registry 风险等级一致。
+- Policy version 不允许回退。
+
+---
+
+## 四、MCP 验收矩阵
+
+| Tool | Risk | 基础用例 |
+| :--- | :--- | :--- |
+| `list_devices` | Low | 返回设备列表 |
+| `exec_command` | High | `echo/true` |
+| `read_file` | Low | 读取 `/etc/hostname` |
+| `read_multiple_files` | Low | 批量读取临时文件 |
+| `create_directory` | Medium | 创建临时目录 |
+| `move_file` | Medium | 移动临时文件 |
+| `list_processes` | Low | 返回进程 |
+| `edit_block` | Medium | 唯一匹配修改 |
+| `write_file` | Medium | 写入临时文件 |
+| `list_agent_mcp` | Low | 查询 Agent MCP |
+| `call_agent_mcp` | Medium | 调用无害 Agent MCP |
+
+必须同时验证：
+- Medium 策略可以阻断 Medium 工具。
+- Medium 策略可以阻断 High 工具。
+- MCP 与 HTTP 使用同一授权逻辑。
+- `call_agent_mcp` 无旁路。
+
+---
+
+## 五、文件与 Session 验收
+
+### 5.1 edit_block
+- old_text 唯一匹配。
+- generation check。
+- atomic write。
+- fsync。
+- 失败不破坏原文件。
+
+### 5.2 Session
+- Hard TTL。
+- Idle TTL。
+- Ring Buffer 上限。
+- 总 buffer 上限。
+- 并发访问安全。
+- kill 只能作用于 Session 内部 process handle。
+
+---
+
+## 六、API Regression
+
+必须覆盖：
+- `/api/v1/devices`
+- `/api/v1/exec`
+- file read/list/info/search/write
+- edit_block
+- process/session
+- MCP services/list/call/test
+- security settings
+- webhook
+- Panel
+- Agent WebSocket
+
+---
+
+## 七、发布停止条件
+
+出现以下任一情况立即停止发布：
+- Agent 断联。
+- 未授权请求成功。
+- unknown device 获得 High。
+- MCP 存在旁路。
+- Token 出现在 argv。
+- 审计丢失。
+- dirty binary。
+- Policy version 回退。
+- Session 资源无限增长。
+
+---
+
+## 八、v2.1 验收预留
+
+### P0
+- EffectiveRisk 完全 fail-closed。
+- Agent Credential 不进入 argv / cmdline。
+
+### P1
+- Principal / Operator。
+- Session Owner 强隔离。
+- principal → credential → session → device → operation 审计链。
@@ -1,148 +1,198 @@
 # VPS-Commander（自托管私有化多节点运维管家）架构与开发设计规范

-## 1. 项目立项背景与目标
+## 一、项目立项背景与目标
+
 ### 1.1 背景与痛点
- 当前市面方案（如 Desktop Commander）严重依赖公共第三方中继（SaaS Relay），存在严重的命令与数据泄漏风险、Token 明文暴露风险以及第三方额度/速率限制。
- 现有纯开发网关（如 CodePier）采用项目目录沙箱隔离，无法进行系统级运维（如查看全局进程、管理 Lucky/Docker、修改全盘系统配置等），且不支持 ChatGPT 原生 Actions 插件生态。
+- 早期方案过度依赖第三方 Relay，控制面与节点执行面边界不清。
+- 单机开发网关通常存在项目目录沙箱，无法覆盖完整 Host-centric 运维。
+- AI Agent 需要的不只是 Shell，而是节点发现、文件、进程、Session、MCP 和审计的一体化控制面。

 ### 1.2 核心目标
- **100% 私有化部署**：数据仅在 OpenAI 官方服务器和用户私有 VPS 之间传输，零第三方中转。
- **全权宿主运维 (Host-centric)**：提供全局 Shell、进程管理、文件读写能力。
- **多节点别名调度**：通过单一 Hub 统一管理多台 VPS/客户端节点，支持在 ChatGPT 中通过自然语言昵称（如 "hwsg"、"wjyhk"）随时切换目标节点。
- **原生 ChatGPT 插件集成**：提供标准 OpenAPI 3.1 规范与 Actions 端点，在 ChatGPT 手机端/网页端呈现为原生交互卡片。
- **超轻量 Go 架构**：Hub 常驻 RSS 目标 ≤ 20MB、硬上限 25MB；Agent 常驻 RSS 目标 ≤ 10MB、硬上限 12MB。
+- **100% 私有化控制面**：Hub、Agent、SQLite 与反向代理均由用户控制。
+- **Host-centric 运维**：Shell、文件、进程、Session、远程 MCP。
+- **多节点统一调度**：一个 Hub 管理多个 VPS，节点状态持久化。
+- **AI 原生接入**：HTTP、MCP、stdio、Web 管理面板。
+- **安全闭环**：认证、风险授权、资源限制、审计、可回滚发布。

 ---

-## 2. 总体架构设计
+## 二、总体架构设计

 ```text
-[ 用户在 ChatGPT APP / Web 端发指令 ]
+[ AI / MCP Client / Web Panel ]
              │
-                ▼ (HTTPS POST + Bearer API Key)
-      [ 用户私有域名反代 (Lucky SSL) ]
+              ▼ HTTPS / MCP
+       [ Reverse Proxy / TLS ]
              │
-                ▼ (反向代理至 127.0.0.1:28800)
-    ┌────────────────────────────────────────────────────────┐
-    │              VPS-Commander Hub (中央管理网关)          │
+              ▼ 127.0.0.1:9521
+    ┌──────────────────────────────────────────────┐
+    │             VPS-Commander Hub               │
+    │----------------------------------------------│
+    │ Auth / API / MCP / Web Panel                │
+    │ Policy Snapshot / Tool Registry             │
+    │ Cluster Router / Session / Rate Limit       │
+    │ SQLite / Audit / Webhook                    │
+    └──────────────┬───────────────────┬───────────┘
                   │                   │
-    │  ├─ OpenAPI / Actions Engine (/openapi.json, /api/v1)  │
-    │  ├─ 鉴权与安全过滤中间件 (Auth Middleware)            │
-    │  ├─ 设备拓扑注册表 (Device Registry & State Machine)   │
-    │  ├─ 审计日志存储 (SQLite: audit.db)                    │
-    │  └─ 路由分发器 (Router Dispatcher)                     │
-    └───────────┬────────────────────────────────┬───────────┘
-                │                                │
-      (本地进程直连: target="local")   (安全 WebSocket 长连接 / mTLS)
+          Local Executor          Agent WSS
                   │                   │
                   ▼                   ▼
-     [ 本机 Local Executor ]             [ 远程 Agent (Node: hwsg) ]
-     - bash -c ...                       - Client Agent Daemon
-     - 文件/进程直接操作                  - 接收 JSON-RPC 指令并执行
+                Hub 本机            Remote VPS
+                                       │
+                               Host Executor
+                               Shell / File / Process
+```
+
+### 2.1 控制通道
+AI / MCP / HTTP 请求进入 Hub，由 Hub 完成认证、设备解析、风险判断和路由。
+
+### 2.2 节点通道
+Agent 主动通过 WSS 回连 Hub，负责设备注册、状态、能力协商及 RPC 请求/响应。
+
+两条通道共享同一设备身份、策略和审计上下文，不允许出现 MCP 或 Agent MCP 绕过 Hub 授权的旁路。
+
+---
+
+## 三、Hub 与 Agent 通信规范
+
+### 3.1 Agent 注册与鉴权
+- Agent 连接：`wss://<hub>/agent/ws`。
+- 使用每设备独立 Credential。
+- Hub 从已认证 Credential 建立 Canonical Device Identity。
+- 客户端自报 `device/name` 不能成为授权身份来源。
+- 生产不再使用 Cluster Secret fallback。
+
+### 3.2 协议握手
+握手包含：
+- Protocol Version；
+- AgentVersion；
+- Capabilities；
+- Per-device Credential。
+
+### 3.3 RPC
+Hub 将经过授权的操作转换为 Agent RPC。
+Agent 返回结果后，Hub 完成审计并将结果返回 HTTP/MCP 调用方。
+
+---
+
+## 四、安全与权限模型
+
+### 4.1 认证
+- HTTP / MCP：Bearer API Key。
+- Web Panel：Panel Session，服务端内部 bridge Admin Token。
+- Agent：per-device credential。
+
+### 4.2 Tool Risk Registry
+
+| 风险 | 典型操作 |
+| :--- | :--- |
+| Low | read_file、read_multiple_files、list_directory、file_info、search、list_processes |
+| Medium | edit_block、write_file、create_directory、move_file、mcp_call |
+| High | exec_command、start_process、interact_with_process、kill_process、force_terminate |
+
+### 4.3 Policy Snapshot
+- 安全策略持久化到 SQLite。
+- 每次更新生成单调递增 version。
+- Hub 请求路径读取内存 Snapshot。
+- 未知、未注册、凭据错误或身份无法解析的设备必须 deny。
+- GlobalRisk 不得让未知设备获得 High。
+
+v2.1 将彻底清理 `EffectiveRisk` 中仍存在的 GlobalRisk fallback。
+
+---
+
+## 五、Session 与执行安全
+
+### 5.1 Session 资源限制
+- Ring Buffer 默认 2MB。
+- 总 Session buffer 上限 8MB。
+- Hard TTL 30 分钟。
+- Idle TTL 10 分钟。
+- LastAccess 自动刷新。
+- 过期与空闲 Session 自动清理。
+
+### 5.2 进程生命周期
+kill / terminate 使用 Session 内部进程句柄，不接受客户端任意 PID 作为授权对象。
+
+### 5.3 文件修改
+`edit_block` 使用唯一匹配、generation check、临时文件、fsync、atomic rename 和权限保留，失败时不破坏原文件。
+
+---
+
+## 六、MCP 架构
+
+当前 MCP 共 11 个工具：
+1. `list_devices`
+2. `exec_command`
+3. `read_file`
+4. `read_multiple_files`
+5. `create_directory`
+6. `move_file`
+7. `list_processes`
+8. `edit_block`
+9. `write_file`
+10. `list_agent_mcp`
+11. `call_agent_mcp`
+
+`call_agent_mcp` 必须经过 MCP risk gate，不允许成为远程 Agent 的权限旁路。
+
+当前远程 transport 为 legacy HTTP + SSE，本地客户端为 stdio；Streamable HTTP 属于后续演进。
+
+---
+
+## 七、项目工程结构与技术选型
+
+- **语言**：Go。
+- **存储**：SQLite。
+- **HTTP**：标准库。
+- **Web**：Go embed。
+- **节点通信**：WebSocket。
+
+```text
+cmd/
+├── hub/
+├── agent/
+└── mcp-stdio/
+internal/
+├── api/
+├── auth/
+├── cluster/
+├── executor/
+├── mcp/
+├── model/
+├── notify/
+├── security/
+├── storage/
+└── web/
 ```

 ---

-## 3. 核心接口与协议规范 (OpenAPI 3.1)
+## 八、生产部署边界

-ChatGPT Actions 识别的标准接口集合：
+- Hub：`127.0.0.1:9521`。
+- 公网由 Reverse Proxy 终止 TLS。
+- Agent 仅出站连接 Hub。
+- 数据库：`/opt/vps-commander/data/commander.db`。
+- systemd：`vps-commander-hub.service` / `vps-commander-agent.service`。

-### 3.1 `/api/v1/devices` (GET)
- **说明**：获取当前所有在线/受管设备列表及健康状态。
- **返回**：`[{"name": "wjyhk", "is_local": true, "status": "online"}, {"name": "hwsg", "status": "online"}]`
-
-### 3.2 `/api/v1/exec` (POST)
- **说明**：在指定节点执行 Shell 命令。
- **请求体**：
-  ```json
-  {
-    "device": "hwsg",        // 节点昵称，缺省默认 local / wjyhk
-    "command": "free -h",    // 要执行的命令
-    "workdir": "/root",      // 可选工作目录
-    "timeout": 30            // 超时时间（秒）
-  }
-  ```
- **响应体**：
-  ```json
-  {
-    "device": "hwsg",
-    "exit_code": 0,
-    "stdout": "...",
-    "stderr": "",
-    "duration_ms": 120
-  }
-  ```
-
-### 3.3 `/api/v1/fs/read` (POST)
- **说明**：受控读取指定设备的文件内容。
- **参数**：`device`, `path`, `offset_bytes`, `limit_bytes`（防止大文件撑爆模型上下文）。
-
-### 3.4 `/api/v1/fs/write` (POST)
- **说明**：在指定设备创建或覆写文件。
- **参数**：`device`, `path`, `content`。
+升级必须执行：
+1. backup；
+2. clean build；
+3. 单节点灰度；
+4. Hub restart recovery；
+5. rolling Agent；
+6. MCP/security/audit 验收。

 ---

-## 4. Hub 与 Agent 节点通信规范
+## 九、v2.1 演进方向

-1. **Agent 注册与鉴权**：
-   - Agent 启动时通过 `wss://hub.domain.com/agent/ws` 发起长连接。
-   - 握手使用 `Authorization: Bearer <cluster-secret>` Header；Cluster Secret 不进入 URL。
-   - 握手成功后，Hub 内存注册表更新该设备为 `online`，并启动双向 Heartbeat ping/pong（30s 周期）。
+### 9.1 P0
+- EffectiveRisk 完全 fail-closed。
+- Agent Credential 不进入 argv / cmdline。

-2. **指令下发 (JSON-RPC)**：
-   - Hub 收到 ChatGPT 请求 ➡️ 生成 `task_id` ➡️ 通过 WS 发送 `{"action": "exec", "task_id": "...", "command": "..."}`。
-   - Agent 执行完毕后返回 `{"task_id": "...", "result": {...}}`。
-   - Hub 审计日志落库后返回给 ChatGPT。
-
---
-
-## 5. 项目工程结构与技术选型
-
- **开发语言**：Go 1.22+（高性能、低内存、单二进制交叉编译友好）
- **Web 框架**：Gin 或纯标准库 `net/http` + `gorilla/websocket`
- **存储**：SQLite (纯粹用于审计日志与持久化配置)
-
-```
-vps-commander/
-├── cmd/
-│   ├── hub/            # 中央控制网关主入口
-│   └── agent/          # 节点客户端主入口
-├── internal/
-│   ├── api/            # ChatGPT Actions HTTP 接口
-│   ├── auth/           # Bearer Token 与 Secret 鉴权
-│   ├── cluster/        # 节点连接池、心跳与 WebSocket 管理
-│   ├── executor/       # 本地/远程执行器抽象
-│   └── storage/        # 审计日志与设备配置持久化
-├── web/                # 极简设备状态面板（纯 HTML/CSS 嵌入二进制）
-├── openapi/            # 供 ChatGPT 导入的 openapi.json
-├── Makefile            # 多架构编译 (linux/amd64, linux/arm64)
-└── README.md           # 部署与 ChatGPT 配置指南
-```
-
---
-
-## 6. Hub Web 控制面板设计规范
-
-### 6.1 定位与设计原则
- **极简独立**：前端采用纯 HTML5 + TailwindCSS/原生CSS + Vanilla JS，不引入复杂 node 构建工具链，通过 Go 1.16+ `embed.FS` 直接打包进单一二进制产物。
- **开箱即用**：零外部静态资源依赖，访问 `https://hub.yourdomain.com/` 即可直接加载。
- **低资源消耗**：Web 面板由 Hub 服务原生托管，静态文件常驻开销基本为零。
-
-### 6.2 核心功能模块
-1. **设备看板 (Device Overview)**
-   - 受管设备列表：别名（Alias）、当前状态（Online/Offline）、系统架构与内核、IP 地址、最后心跳（Heartbeat）。
-   - 快速连接指引：点击“添加节点”，自动生成带 Token 的单行一键安装/运行命令（如 `curl -sL https://... | bash -s -- --hub=... --token=...`）。
-   - 设备启停与踢出操作：支持在面板主动注销失效/弃用节点。
-
-2. **ChatGPT Actions 配置与向导中心**
-   - 托管与展示 `/openapi.json` 规范预览。
-   - 提供专属 API Key 生成、轮换与撤销功能。
-   - 提供直接导入 ChatGPT Custom GPT 的一键复制 Schema 按钮与预设 System Prompt 建议。
-
-3. **实时操作审计与日志 (Audit Log)**
-   - 记录来源（ChatGPT / Web 手动）、目标设备、动作（exec / file_read / file_write）、执行内容、执行耗时、退出码与结果摘要。
-   - 支持按设备、关键字实时搜索过滤。
-
-4. **Web 快速调试终端 (Quick Terminal / Console)**
-   - 提供快速测试输入框，选择目标设备后可直接输入命令测试执行并查看即时输出，无需打开 ChatGPT 即可验证节点联通性。
+### 9.2 P1
+- Principal / Operator Identity。
+- Session Owner 强隔离。
+- principal → credential → session → device → operation 完整审计链。
@@ -0,0 +1,129 @@
+# vps-commander 生产 Bug Hunt 报告（2026-10-02）
+
+- **测试人**：安全测试员（独立 bug hunt）
+- **测试时间**：2026-10-02 13:36–13:50（+08）
+- **测试对象**：生产 Hub（wjyhk，13:36:06 重启）+ 6 节点 Agent
+- **测试方式**：只读探测 + 无害命令（echo/true），未写生产文件、未改配置、未重启服务、未碰 commander.db
+- **结论**：发现 **4 个 bug**，最高严重度 **高**。另有若干“未发现问题”的项如实记录。
+
+---
+
+## 【标题】生产 Agent 二进制构建自脏工作树，缺失已提交代码
+
+**【严重度：高】**
+
+**【复现步骤】**
+1. 在 wjyhk 执行 `go version -m /opt/vps-commander/vps-commander-agent`，观察 `vcs.revision=a5620cb` 且 `vcs.modified=true`。
+2. 对比源码：`git show a5620cb:cmd/agent/main.go` 的 action switch 只有 6 个 case（mcp_list/mcp_test/mcp_call/exec/file_read/file_write），无 session 相关、无 `read_multiple_files`。
+3. 但生产 Agent 实际能处理 `start_process`（session 功能可用），说明二进制内容无法从任何 commit 还原——是脏树构建。
+4. Hub 同样 `vcs.modified=true`（13:36 重部署的二进制，revision=556870b）。
+
+**【证据】**
+```
+build  vcs.revision=a5620cb9c4d3570cf5ce2abe8772ef4e3b91bd76
+build  vcs.time=2026-10-01T16:45:10Z
+build  vcs.modified=true
+```
+各节点 Agent md5 一致（35e965a9），均为同一脏构建，于 13:22 统一重启部署。
+
+**【影响分析】**
+- 生产二进制不可复现：出问题时无法用 `git checkout <rev> && go build` 还原现场，排障与回滚失去基准。
+- 脏构建内容未知：`read_multiple_files` 在源码 192969d 中已加入 Agent，但生产 Agent 不支持（见 Bug #3），说明构建时的脏树处于部分完成状态，**可能还缺失其他已提交的安全修复**，需逐项核对。
+- **建议**：从干净 HEAD 重新构建 Hub+Agent，全量重新部署，部署后校验 `vcs.modified` 为空且 revision==HEAD。
+
+---
+
+## 【标题】`read_multiple_files` 在所有远端节点上失败（Hub-Agent 协议不一致）
+
+**【严重度：中】**
+
+**【复现步骤】**
+1. `vps-mcp.py call read_multiple_files '{"device":"hwsg","paths":["/etc/hostname"],"limit":100}'` → 返回 `{"error": "unsupported action"}`。
+2. 同样调用 `device=wjyhk`（本地）→ 正常返回文件内容。
+3. 查源码：`internal/api/mcp_adapter.go:287` 的 `ReadMultipleFiles` 对远端走 `Cluster.ReadMultipleFiles`；Agent 侧 `cmd/agent/main.go:261` 在当前源码中有该 case，但生产 Agent 二进制（脏构建）不支持，落入 `default: unsupported action`（main.go:391）。
+
+**【证据】**
+```json
+{"error": "unsupported action"}
+```
+（hwsg/N3450 等远端节点复现，wjyhk 本地正常）
+
+**【影响分析】**
+- MCP 工具列表向 AI 客户端 quảng cáo `read_multiple_files` 可用于所有设备，实际 5/6 节点不可用，功能性 bug。
+- 根因是 Bug #1（脏构建）的直接后果；修复 Bug #1（干净重建+重部署）后本项自动解决。
+- 在修复前，建议 Hub 对不支持该 action 的 Agent 返回明确错误而非透传 `unsupported action`，或在 capability 协商中隐藏该工具。
+
+---
+
+## 【标题】`/api/v1/process/session` 请求结构体无 JSON tag，snake_case 字段被静默丢弃
+
+**【严重度：中】**
+
+**【复现步骤】**
+1. `POST /api/v1/process/session?action=start`，body `{"device":"hwsg","command":"echo hi","session_id":"my-id"}`（snake_case，如响应格式所示）。
+2. 响应返回 `{"session_id":"04d39d85b150..."}`——**客户端传的 ID 被丢弃**，服务端生成了随机 ID。
+3. 随后用 `my-id` 做 read/stop → `session not found`。
+4. 改用精确大小写 `{"SessionID":"my-id"}` → 全流程正常。
+
+**【证据】**
+```go
+// internal/api/api.go:784
+var req struct {
+    Device, SessionID, Command, Workdir, Data string  // 无 json tag！
+    Force                                     bool
+    RingCapacity                              int `json:"ring_capacity"`
+}
+```
+Go encoding/json 对无 tag 字段仅做大小写不敏感匹配，`session_id`（snake_case）无法匹配 `SessionID`，被静默忽略。
+
+**【影响分析】**
+- API 契约破裂：响应用 `session_id`（snake_case），请求却要求 `SessionID`（CamelCase）；任何按常规 REST 惯例（或照着响应字段）写的客户端都会踩坑，且失败是静默的（拿到一个“成功”但对不上的 session）。
+- 非安全漏洞，但属于生产功能 bug。修复：在结构体上加 `json:"device"` 等 snake_case tag（注意与 openapi.json 文档对齐）。
+
+---
+
+## 【标题】`/api/v1/process/session` 不支持 Hub 本节点（无本地回退）
+
+**【严重度：中低】**
+
+**【复现步骤】**
+1. `POST /api/v1/process/session?action=start`，body `{"Device":"wjyhk","Command":"echo hi"}`。
+2. 返回 `device offline`（HTTP 409）。
+3. 对比：`POST /api/v1/exec` 同样 `device=wjyhk` 可正常执行（`exec` 有 `isRemote` 本地回退，api.go:744）。
+
+**【证据】**
+```go
+// processSession 直接走 Cluster，无 isRemote 判断：
+if s.Cluster == nil { http.Error(w, "cluster unavailable", 503); return }
+...
+result, err = s.Cluster.StartProcess(ctx, req.Device, ...)  // wjyhk 无 agent WS 连接 → device offline
+```
+
+**【影响分析】**
+- 功能不一致：exec/read/write 等在 Hub 本节点可用，唯独 session 管理不可用。用户在 Hub 本机无法使用长会话功能。
+- 修复：给 processSession 加与 exec 相同的 `isRemote` 本地回退（Hub 侧需持有一个本地 SessionManager，或复用 executor 包）。
+
+---
+
+## 未发现问题的项（逐项如实记录）
+
+1. **认证绕过**：无 token/错 token/空 Bearer 访问 `/api/v1/*` 与 `/panel/api/*` 均返回 401；`/healthz` 200 为预期设计。未发现绕过。
+2. **畸形输入**：malformed JSON、空 body、300KB 超大 body（超 256KB MaxBytesReader 限制）均返回 400，无 panic。Hub 日志自 13:24 以来 0 panic、0 error。
+3. **路径穿越**：`../../../etc/hostname` 可读、`\0` 被 `validPath` 拦截（400）。但本工具是已认证管理员工具，无沙箱设计约束，`..` 解析属操作系统正常行为，不视为漏洞。
+4. **设备名注入**：空字符串回退本机（设计如此）、不存在设备/超长字符串/含 `\0` 的设备名均 `security mode unknown denies exec`，fail-closed，无 panic。
+5. **Session 生命周期**：Agent 侧每分钟 `sessions.Cleanup()`，idle TTL 10min + hard TTL 存在；`SessionManager` 有互斥锁，5 并发创建 session 无竞态崩溃（2 成功、3 因达到上限 4 被正确拒绝，上限由 `MaxSessionBufferTotal/DefaultRingCapacity=4` 决定，符合设计）。
+6. **并发压力**：10 并行原生 HTTP 请求全部 200、响应快；Hub 内存稳定（~20MB）。30 并行 MCP 调用大量超时系客户端 SSE 建连开销，非 Hub 问题。
+7. **配额**：`ExecLimiter` 32 并发信号量存在；无单客户端速率限制（设计选择，非 bug）。
+8. **Agent-MCP 畸形参数**：不存在的 tool/含 `\0` 的参数返回干净的 `MCP HTTP status 400`，无 panic、无信息泄漏。
+9. **kill 进程**：API 只接受 SessionID，Agent 用内部 `cmd.Process` 句柄 kill，不接受客户端 PID，无 PID 重用误杀风险。
+
+---
+
+## 附：测试期间观察到的部署活动
+
+- 13:36:06 Hub 被重部署（此前为 13:24），二进制 revision 由 38382d2 变为 556870b。测试期间生产处于活跃变更中，部分结论（如 Hub revision）以测试时刻为准。
+- Agent 在各节点为同一脏构建（md5 35e965a9，13:22 部署），`vcs.modified=true`。
+
+---
+
+*安全测试员，2026-10-02*
@@ -1,5 +1,7 @@
 # DC Refactoring Phase 1 Implementation Record

+> 文档属性：历史实施记录。后续阶段和当前状态以当前架构规范与 v2.1 规范为准。
+
 Date: 2026-10-02

 ## Completed
@@ -1,119 +1,167 @@
-# VPS-Commander 详细技术规格与开发实施方案 (v1.1.0)
+# VPS-Commander 研发设计规范与协议说明

-## 一、 系统架构角色划分
+## 一、技术选型与工程原则

-整个系统划分为两个独立二进制产物（单一代码库仓库编译）：
-1. **`vps-commander-hub` (中央网关 + 控制面板)**：
-   - 部署在有公网域名或反代的主机上（当前主力机 `wjyhk`）。
-   - 监听端口：`127.0.0.1:9521`（由 Lucky 负责 TLS 证书卸载与反代）。
-   - 暴露端点：
-     - 面向 ChatGPT Actions：`/api/v1/*`（Bearer Token 鉴权）
-     - 面向 Agent 长连接：`/agent/ws`（Cluster Secret 握手）
-     - 面向用户极简管理面板：`/` 及 `/static/*`（Go embed 静态资源，支持密码登录/Cookie鉴权）
-     - 描述文件：`/openapi.json`
-   - 本身内置 Local Executor（直接代表本地主力机，设备名：`local` 或自定义主机名）。
-2. **`vps-commander-agent` (节点轻量客户端)**：
-   - 部署在其他受管节点（如 `hwsg` 等）。
-   - 主动向 Hub 发起安全 WebSocket 连接（支持断线指数退避重连）。
-   - 纯受控执行器，只响应 Hub 下发指令，不开放任何公网入站端口（彻底规避防火墙/NAT问题）。
+- **开发语言**：Go。
+- **存储**：SQLite。
+- **HTTP**：标准库 `net/http`。
+- **节点通信**：WebSocket。
+- **Web 前端**：Go `embed`。
+
+工程原则：
+1. 认证与授权分离。
+2. Tool Risk 静态注册。
+3. Device Policy 运行时解析。
+4. 默认 fail-closed。
+5. Session 必须有 TTL 与资源上限。
+6. 生产二进制必须可追溯。
+7. 发布必须可回滚。

 ---

-## 二、 协议设计 (RPC over WebSocket)
+## 二、项目工程结构

-### 2.1 握手与注册 (Handshake)
-Agent 连接 URL: `wss://hub.domain.com/agent/ws?device_name=hwsg`
- Hub 校验通过后：
-  - 发送握手成功包：`{"event": "registered", "device": "hwsg", "heartbeat_interval": 30}`
-  - 将该连接注入 `DeviceManager`，状态标为 `online`。
-
-### 2.2 心跳 (Ping/Pong)
- 每 30 秒由 Hub 发送 `{"event": "ping", "ts": 1727049600}`。
- Agent 回复 `{"event": "pong", "ts": 1727049600}`。连续 2 次无响应标记为 `offline`。
-
-### 2.3 命令下发与响应 (Request-Response)
- Hub 下发：
-  ```json
-  {
-    "id": "task_6b7a8c9d",
-    "action": "exec",
-    "payload": {
-      "command": "free -h",
-      "workdir": "/root",
-      "timeout": 30
-    }
-  }
-  ```
- Agent 执行完返回：
-  ```json
-  {
-    "id": "task_6b7a8c9d",
-    "status": "success",
-    "exit_code": 0,
-    "stdout": "...",
-    "stderr": "",
-    "duration_ms": 45
-  }
-  ```
+```text
+vps-commander/
+├── cmd/
+│   ├── hub/
+│   ├── agent/
+│   └── mcp-stdio/
+├── internal/
+│   ├── api/
+│   ├── auth/
+│   ├── cluster/
+│   ├── executor/
+│   ├── mcp/
+│   ├── model/
+│   ├── notify/
+│   ├── security/
+│   ├── storage/
+│   └── web/
+├── docs/
+├── deploy/
+└── openapi.json
+```

 ---

-## 三、 ChatGPT Actions (OpenAPI 3.1) 接口定义
+## 三、Agent WebSocket 协议

-完整的 `openapi.json` 规范定义了以下 4 个原子能力：
+Agent 主动连接：`/agent/ws`。

-1. **`list_devices`**:
-   - `GET /api/v1/devices`
-   - 返回受管设备名、IP、状态（online/offline）、最后心跳。
-2. **`exec_command`**:
-   - `POST /api/v1/exec`
-   - 参数：`device` (默认: "local"), `command`, `workdir`, `timeout`。
-3. **`read_file`**:
-   - `POST /api/v1/file/read`
-   - 参数：`device`, `path`, `offset`, `limit`。
-4. **`write_file`**:
-   - `POST /api/v1/file/write`
-   - 参数：`device`, `path`, `content`。
+握手包含：
+- Protocol Version。
+- AgentVersion。
+- Capabilities。
+- Per-device Credential。
+
+Hub 根据 Credential 建立 Canonical Device Identity。
+客户端请求中的 `device/name` 只能用于路由，不能作为授权身份来源。

 ---

-## 四、 Hub Web 控制面板功能规范
+## 四、HTTP API 规范

-### 4.1 技术实现
- 单二进制静态内嵌：基于 Go `embed.FS` 打包 HTML5 + TailwindCSS + Vanilla JS。
- 零外部 npm/node 依赖，开箱即用。
-
-### 4.2 功能矩阵
-1. **设备看板 (Devices Dashboard)**：
-   - 节点列表展示（名称、IP、状态、架构/系统版本、最后活跃时间）。
-   - 一键生成 Agent 安装注册命令（带 Token 参数）。
-   - 手动注销/踢出无效节点。
-2. **ChatGPT Actions 向导 (Actions Guide)**：
-   - 动态渲染 `openapi.json` 并提供一键复制。
-   - API Key 凭据生成、轮换与撤销。
-   - 预设 System Prompt 最佳实践一键复制。
-3. **安全审计追踪 (Audit Trails)**：
-   - 实时日志流水：时间戳、来源 IP、目标节点、操作类型、执行命令、执行耗时、退出状态。
-   - 支持日志按设备名、时间区间筛选。
-4. **快速网页终端 (Quick Console)**：
-   - 应急测试控制台，免切 ChatGPT 直接在 Web 端选择节点跑指令验证联通性。
+| 路径 | 方法 | 功能 |
+| :--- | :--- | :--- |
+| `/api/v1/devices` | GET | 设备列表 |
+| `/api/v1/exec` | POST | Shell |
+| `/api/v1/file/read` | POST | 文件读取 |
+| `/api/v1/file/list` | POST | 目录列表 |
+| `/api/v1/file/info` | POST | 文件信息 |
+| `/api/v1/file/search` | POST | 文件搜索 |
+| `/api/v1/process/session` | POST | Session |
+| `/api/v1/file/write` | POST | 文件写入 |
+| `/api/v1/devices/file/edit_block` | POST | 原子编辑 |
+| `/api/v1/mcp/*` | GET/POST/DELETE | MCP |
+| `/api/v1/security/*` | GET/POST | 安全策略 |
+| `/api/v1/notifications/webhook*` | GET/POST/DELETE | Webhook |
+| `/healthz` | GET | 健康检查 |
+| `/openapi.json` | GET | OpenAPI |

 ---

-## 五、 存储与安全审计 (SQLite)
+## 五、MCP 协议规范

- 数据库文件：`data/commander.db`
- 数据表结构：
-  1. `devices`：记录设备名、备注、添加时间、密钥 Hash。
-  2. `audit_logs`：
-     - `id`, `timestamp`, `caller_ip`, `device`, `action`, `command`, `exit_code`, `duration_ms`, `error_msg`
-     - 确保在 ChatGPT 里执行的所有高危操作均可追溯。
+Server version：`1.2.0`。
+Protocol Version：`2024-11-05`。
+
+当前工具共 11 个：
+`list_devices`、`exec_command`、`read_file`、`read_multiple_files`、`create_directory`、`move_file`、`list_processes`、`edit_block`、`write_file`、`list_agent_mcp`、`call_agent_mcp`。
+
+远程 transport：legacy HTTP + SSE。
+本地 transport：stdio。
+未来 transport：Streamable HTTP。

 ---

-## 六、 开发实施里程碑 (Milestones)
+## 六、认证与安全规范

- [ ] **M1: 基础骨架与单机执行**（完成本地 Local Executor + Gin API + Bearer 鉴权 + `/openapi.json`）
- [ ] **M2: Agent WebSocket 协议与多节点分发**（完成 Agent 注册、心跳保活、Hub 路由转发）
- [ ] **M3: 审计日志与嵌入式 Web 管理页**（完成前端内嵌、看板交互、命令历史审计与快速控制台）
- [ ] **M4: 本机 Lucky 证书反代与 ChatGPT 联调上线**
+### 6.1 HTTP / MCP
+```http
+Authorization: Bearer <API_KEY>
+```
+
+禁止：
+- `?token=`
+- `?key=`
+- `?api_key=`
+
+### 6.2 Agent
+- 每设备独立 Credential。
+- SQLite 只保存 Hash。
+- 生产关闭 Shared Secret fallback。
+
+### 6.3 Panel
+Panel Session 在服务端认证。
+Admin Token 只在 Panel → 内部 API bridge 中使用，不发送给浏览器。
+
+---
+
+## 七、并发与资源限制
+
+| 项目 | 限制 |
+| :--- | :--- |
+| Exec | 32 并发 |
+| Search | 8 并发 |
+| Session Ring | 2MB |
+| Session 总 Buffer | 8MB |
+| Session Hard TTL | 30m |
+| Session Idle TTL | 10m |
+| WS Write | Node.WriteMu |
+| Medium/High | Node.OpMu |
+
+---
+
+## 八、测试与发布规范
+
+### 8.1 提交前
+```bash
+go test ./...
+go test -race ./...
+git diff --check
+```
+
+### 8.2 发布前
+- clean Git tree。
+- `vcs.modified=false`。
+- revision 与 release commit 一致。
+- 单 Agent 灰度。
+- Hub restart recovery。
+- MCP smoke test。
+- security deny/allow matrix。
+
+---
+
+## 九、v2.1 研发计划
+
+### 9.1 P0
+- EffectiveRisk 完全 fail-closed。
+- Credential 不进入 argv / cmdline。
+
+### 9.2 P1
+- Principal / Operator Identity。
+- Session Owner 强隔离。
+- 完整身份审计链。
+
+v2.1 不改变 Low / Medium / High 语义，不恢复 Shared Secret。
@@ -0,0 +1,128 @@
+# VPS-Commander 全仓库文档基线与索引
+
+本文档作为 2026-10-02 之后的文档总入口，用于区分当前设计、历史记录与下一版本研发计划。
+
+---
+
+## 一、当前项目定位
+
+VPS-Commander 是自托管、多节点、AI Agent 友好的 Linux 运维控制中枢。
+
+核心链路：
+`AI / MCP / Web Panel → Hub → Local Executor 或 Agent WSS → Target Host`。
+
+---
+
+## 二、当前架构基线
+
+### 2.1 Hub
+- HTTP API。
+- MCP。
+- Web Panel。
+- Agent Router。
+- Security Snapshot。
+- Tool Registry。
+- Session。
+- SQLite。
+- Audit / Webhook。
+
+### 2.2 Agent
+- 主动 WSS 回连。
+- per-device Credential。
+- Protocol / AgentVersion / Capabilities。
+- Host-level File / Shell / Process 执行。
+
+### 2.3 双通道
+- 控制通道：HTTP / MCP → Hub → Executor。
+- 节点通道：Agent → WSS → Hub。
+
+---
+
+## 三、当前 MCP 基线
+
+11 个工具：
+`list_devices`、`exec_command`、`read_file`、`read_multiple_files`、`create_directory`、`move_file`、`list_processes`、`edit_block`、`write_file`、`list_agent_mcp`、`call_agent_mcp`。
+
+远程：legacy SSE。
+本地：stdio。
+下一阶段：Streamable HTTP。
+
+---
+
+## 四、当前安全基线
+
+- HTTP/MCP：Bearer API Key。
+- Agent：per-device Credential。
+- SQLite：Credential Hash。
+- Low / Medium / High Tool Risk。
+- Policy Snapshot。
+- Shared Secret fallback：生产关闭。
+- MCP 与 HTTP：统一授权门禁。
+- Panel Admin Token：服务端 bridge。
+
+---
+
+## 五、文档分层
+
+### 5.1 当前规范
+- `README.md`：项目入口与能力总览。
+- `docs/ARCHITECTURE.md`：架构与设计。
+- `docs/DEV_SPEC.md`：研发与协议。
+- `docs/MCP_INTEGRATION.md`：MCP 接入。
+- `deploy/README.md`：生产部署。
+- `docs/ACCEPTANCE_CRITERIA.md`：验收门禁。
+- `docs/PROGRESS_TRACKING.md`：当前进度。
+- `docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md`：v2.1 安全加固。
+
+### 5.2 审计 / 整改材料
+- `docs/BUGHUNT_20261002.md`。
+- `docs/DC_REFACTORING_AND_SECURITY_SPEC.md`。
+- `docs/DC_REFACTORING_SECURITY_REVIEW_HANDOFF_20261002.md`。
+- `docs/REVIEW_B_TO_A_HANDOFF_20261002.md`。
+
+### 5.3 历史记录
+- `REVIEW_A_CODE_AUDIT_20261002.md`。
+- `REVIEW_B_CODE_AUDIT_20261002.md`。
+- `INCIDENT_TIMEOUT-20260930.md`。
+- `M4_FINAL_ACCEPTANCE_REPORT.md`。
+- `DC_PHASE1_IMPLEMENTATION.md`。
+
+历史文件用于记录演进过程，不覆盖当前规范。
+
+---
+
+## 六、当前生产基线
+
+当前生产集群包括：
+- `wjyhk`
+- `N3450`
+- `hwhk`
+- `hwsg`
+- `m4-live-agent`
+- `qnvn`
+
+Hub：`/opt/vps-commander/vps-commander-hub`。
+Database：`/opt/vps-commander/data/commander.db`。
+Listen：`127.0.0.1:9521`。
+
+2026-10-02 审计发现生产二进制曾 `vcs.modified=true`，因此下一次发布必须 clean rebuild 后重新对齐生产现场。
+
+---
+
+## 七、v2.1 基线
+
+### P0
+- EffectiveRisk 完全 fail-closed。
+- Agent Credential 脱离 argv / cmdline。
+
+### P1
+- Principal / Operator Identity。
+- Session Owner 强隔离。
+- principal → credential → session → device → operation 审计链。
+
+---
+
+## 八、文档维护规则
+
+新增能力必须同时检查 README、架构、开发规范、MCP、部署、验收、进度以及 OpenAPI Contract。
+历史报告只追加新的后续报告，不覆盖原始证据。
@@ -1,5 +1,7 @@
 # 运维事件记录：大文件逆向解析命令超时

+> 文档属性：历史事件记录。本文保留原始事件证据，不作为当前系统状态契约。
+
 - 日期：2026-09-30
 - 项目：VPS-Commander
 - 关联任务：N3450 / FNOS 飞牛音乐 `trim-music` API 逆向审计
@@ -1,5 +1,7 @@
 # VPS-Commander M4 最终验收报告（待人工签收）

+> 文档属性：历史验收快照（2026-09-28）。当前状态以 README、DOCUMENTATION_BASELINE_20261002 和当前验收门禁为准。
+
 日期：2026-09-28
 状态：🟡 技术收尾完成；管理面板 UI 已人工验收并上线，M4 总体验收仍等待 Custom GPT Actions 人工签收

@@ -1,50 +1,215 @@
-# VPS-Commander MCP (Model Context Protocol) 接入指南
+# VPS-Commander MCP（Model Context Protocol）接入指南

-## 一、概述
-为了应对 OpenAI Custom GPTs 退役及新一代 Plugins/Skills 规范转型，VPS-Commander 现已全面支持标准 **MCP (Model Context Protocol)** 协议。
-
- **零侵入**：原有 REST API、OpenAPI 3.1、Web 面板及 WebSocket 多节点连接池 100% 保持不变。
- **纯 Go 原生**：零外部庞大框架依赖，常驻内存基线依然保持在极低水平。
- **双模支持**：同时支持 **远程 SSE 模式** 与 **本地 stdio 模式**。
+本文介绍 VPS-Commander 当前 MCP 能力、客户端接入方式、工具权限以及后续 transport 演进方向。

 ---

-## 二、支持的 4 大 MCP Tools
+## 一、MCP 总体能力

-| Tool 名称 | 参数说明 | 描述 |
+VPS-Commander 当前提供两种 MCP 接入模式：
+
+- **远程 HTTP SSE 模式**：适用于远程 MCP Client。
+- **本地 stdio 模式**：适用于 Claude Desktop、Cursor、VS Code 等本地客户端。
+
+当前 MCP Server：
+- JSON-RPC 2.0。
+- server version：`1.2.0`。
+- initialize protocolVersion：`2024-11-05`。
+
+当前远程 SSE 属于兼容 transport；后续新能力优先考虑 Streamable HTTP。
+
+---
+
+## 二、当前支持的 11 大 MCP Tools
+
+| Tool 名称 | 风险等级 | 参数/功能说明 |
 | :--- | :--- | :--- |
-| `list_devices` | 无 | 列出当前所有已注册的受控 VPS 节点（如本机 `wjyhk` 及远程 `m4-live-agent` 等）及在线状态 |
-| `exec_command` | `device` (可选), `command` (必填), `workdir` (可选), `timeout` (可选, 默认30) | 在指定受控节点执行任意 Shell 命令并返回退出码与输出 |
-| `read_file` | `device` (可选), `path` (必填), `offset` (可选), `limit` (可选) | 读取指定受控节点的文件内容（支持安全分页读取） |
-| `write_file` | `device` (可选), `path` (必填), `content` (必填) | 在指定受控节点创建或覆写文件 |
+| `list_devices` | Low | 列出设备、状态及资源画像 |
+| `exec_command` | High | 指定节点执行 Shell |
+| `read_file` | Low | 分页读取文件 |
+| `read_multiple_files` | Low | 批量读取多个文件 |
+| `create_directory` | Medium | 创建目录 |
+| `move_file` | Medium | 移动/重命名文件 |
+| `list_processes` | Low | 查看进程 |
+| `edit_block` | Medium | 唯一匹配 + 原子写回 |
+| `write_file` | Medium | 创建或覆写文件 |
+| `list_agent_mcp` | Low | 查询 Agent MCP 服务 |
+| `call_agent_mcp` | Medium | 调用 Agent MCP 工具 |
+
+风险等级不是客户端提示，而是 Hub 强制执行的授权门禁。

 ---

-## 三、接入方式
+## 三、统一安全链路

-### 方式 1：远程 SSE 模式（适用于远程 Agent、OpenAI 新生态端点）
+```text
+MCP Client
+    │
+    ▼
+Bearer Authentication
+    │
+    ▼
+MCP JSON-RPC
+    │
+    ▼
+Tool / Action Mapping
+    │
+    ▼
+Authenticated Device Identity
+    │
+    ▼
+Security Snapshot + Tool Risk
+    │
+    ├── DENY
+    │
+    ▼
+Local Executor / Agent WSS
+    │
+    ▼
+Audit
+```

-Hub 原生提供 MCP SSE 端点（需带 Bearer Token 鉴权）：
- **SSE 建立端点**：`GET https://vpstool.kory.kdns.fr/mcp/sse`
- **消息交互端点**：`POST https://vpstool.kory.kdns.fr/mcp/message?sessionId=<sessionId>`
- **请求头**：`Authorization: Bearer <YOUR_API_KEY>`
+`call_agent_mcp` 同样必须进入 MCP risk gate，不能因为目标是 Agent MCP 就绕过 Hub 授权。

-### 方式 2：本地 stdio 模式（适用于 Claude Desktop、Cursor、VS Code）
+---

-直接使用编译好的极轻量 Go 二进制 `vps-commander-mcp-stdio-linux-amd64`。
+## 四、远程 SSE 模式

-#### 客户端配置示例 (`claude_desktop_config.json` 或 Cursor MCP 设置)：
+### 4.1 SSE 建立
+
+```text
+GET https://your-domain.example/mcp/sse
+Authorization: Bearer <YOUR_API_KEY>
+```
+
+服务器建立 MCP Session 后提供消息端点：
+
+```text
+POST /mcp/message?sessionId=<sessionId>
+Authorization: Bearer <YOUR_API_KEY>
+```
+
+### 4.2 注意事项
+- URL 中禁止放 Token。
+- `?token=`、`?key=`、`?api_key=` 不作为认证方式。
+- SSE 当前作为 legacy compatibility transport。
+
+---
+
+## 五、本地 stdio 模式
+
+适用于 Claude Desktop、Cursor、VS Code 等本地客户端。

 ```json
 {
  "mcpServers": {
    "vps-commander": {
-      "command": "/root/.openclaw/workspace/vps-commander/bin/vps-commander-mcp-stdio-linux-amd64",
+      "command": "/opt/vps-commander/vps-commander-mcp-stdio",
      "args": [
-        "-hub", "https://vpstool.kory.kdns.fr",
+        "-hub", "https://your-domain.example",
        "-key", "YOUR_API_KEY"
      ]
    }
  }
 }
 ```
+
+API Key 不应提交到 Git 仓库。
+
+---
+
+## 六、主要工具参数
+
+### 6.1 exec_command
+- `device`：目标节点，可选。
+- `command`：必填。
+- `workdir`：可选。
+- `timeout`：默认 30 秒，最大 300 秒。
+
+### 6.2 read_file
+- `device`、`path` 必填。
+- `offset` 可选。
+- `limit` 默认 256 KiB，最大 1 MiB。
+
+### 6.3 read_multiple_files
+- `device` 可选。
+- `paths` 必填数组。
+- 当前 Hub 最多接受 32 个路径。
+
+### 6.4 create_directory
+- `device`、`path`。
+
+### 6.5 move_file
+- `device`、`source`、`destination`。
+
+### 6.6 list_processes
+- `device` 可选。
+
+### 6.7 edit_block
+- `device`、`path`、`old_text`、`new_text`。
+- `old_text` 必须唯一匹配。
+- 使用 generation check + atomic write。
+
+### 6.8 write_file
+- `device`、`path`、`content`。
+
+### 6.9 list_agent_mcp
+- `device` 必填。
+
+### 6.10 call_agent_mcp
+- `device`、`server`、`tool` 必填。
+- `arguments` 可选 JSON 对象。
+
+---
+
+## 七、一键安装与升级
+
+### 7.1 一键安装
+
+仓库已经提供统一安装脚本，支持 Linux `amd64` 与 `arm64`，安装时自动识别架构并从 GitHub Release 获取对应二进制。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash
+```
+
+脚本会进入交互式安装流程，可选择 Hub 或 Agent。生产环境使用时，Agent 应使用独立设备凭据，不应重新启用全局 Shared Secret。
+
+### 7.2 一键升级 Agent
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/upgrade-agent.sh | sudo bash
+```
+
+升级采用临时文件下载 → 基础完整性检查 → 旧二进制备份 → 原子替换 → systemd 重启 → 健康检查；启动失败时自动回滚旧版本。
+
+> Hub 的生产升级建议继续采用滚动发布：先完成 Release 与构建校验，再替换 Hub，确认节点重新上线后再继续后续节点。避免把 Hub 升级做成无保护的“一键重启”。
+
+---
+
+## 八、Agent MCP
+
+Hub 可以发现远程 Agent 暴露的 MCP Service。
+
+```text
+MCP Client
+   ↓
+Hub Authentication
+   ↓
+Security Gate
+   ↓
+Authenticated Agent
+   ↓
+Agent MCP Service
+```
+
+客户端不直接连接 Agent MCP。
+
+---
+
+## 八、后续演进
+
+1. Streamable HTTP。
+2. 保留 SSE fallback。
+3. Capability-based Tool Advertisement。
+4. Principal Identity 纳入 MCP Audit Context。
+5. 长任务引入显式 Operation / Session Handle。
@@ -1,121 +1,133 @@
-# VPS-Commander 开发进度看板与交付清单
+# VPS-Commander 项目进度与路线图

-> 角色定位：
-> - **开发实施**：外部 GPT
-> - **架构监督、文档规范、验收审核与严格收尾**：OpenClaw (yk)
+本文档记录当前版本真实进度。历史审计文件继续保留原始证据，不直接作为当前状态判断依据。

 ---

-## 阶段推进概览 (Status Board)
+## 一、当前总体状态

-| 阶段 | 模块 / 目标 | 负责人 | 状态 | 交付物检验 |
-| :--- | :--- | :--- | :--- | :--- |
-| **Phase 0** | 架构设计、接口契约与开发文档 | OpenClaw | 🟢 **已完成 (Done)** | `ARCHITECTURE.md`, `DEV_SPEC.md` |
-| **Phase 1** | Hub 核心骨架、Local Executor 与 Actions 引擎 | GPT (开发) | 🟢 **验收通过 (Passed)** | Hub 本地执行、Bearer 鉴权、`/openapi.json` |
-| **Phase 2** | Agent 通信协议与多节点分发 (WebSocket RPC) | GPT (开发) | 🟢 **验收通过 (Passed)** | 5项生产级缺陷彻底整改；并发竞态/强杀0 Panic/Header鉴权实测全绿 |
-| **Phase 3** | 内嵌 Web 控制面板与 SQLite 审计模块 | GPT (开发) | 🟢 **验收通过 (Passed)** | CSS MIME、SQLite 并发审计丢失缺陷已修复；100 并发无损落盘、-race、浏览器 MIME 与会话权限复验全绿 |
-| **Phase 4** | 独立审核、严苛回归测试与上线收尾 | OpenClaw | 🟡 **收尾整改中 (Hardening)** | 技术门禁基本全绿；待 Custom GPT Actions、Key 轮换与人工签收 |
+| 模块 | 状态 |
+| :--- | :--- |
+| Hub / Agent 双通道 | ✅ 已完成 |
+| 多节点持久化 | ✅ 已完成 |
+| Per-device Credential | ✅ 已完成 |
+| Security Snapshot | ✅ 已完成 |
+| Low / Medium / High Gate | ✅ 已完成 |
+| MCP 安全门禁 | ✅ 已完成 |
+| edit_block 原子安全 | ✅ 已完成 |
+| Session 资源限制 | ✅ 已完成 |
+| Web Panel | ✅ 已完成 |
+| Webhook | ✅ 已完成 |
+| MCP 11 Tools | ✅ 已完成源码实现 |
+| Clean Production Rebuild | 🟡 下一次发布收口 |
+| EffectiveRisk 完全 Fail-closed | 🔵 v2.1 |
+| Agent Token 脱离 argv | 🔵 v2.1 |
+| Principal 强隔离 | 🔵 v2.1 |

 ---

-## 详细功能检查清单 (Feature Checklist for GPT)
+## 二、MCP 当前能力

-### 📌 Milestone 1: Hub 基础与单机 Actions (Phase 1)
- [x] **项目骨架构建**：
-  - [x] Go 模块初始化 (`go.mod`, module `github.com/wjyhk/vps-commander`)
-  - [x] 目录分层清晰（`cmd/hub`, `internal/api`, `internal/executor`, `internal/auth`, `internal/storage`）
- [x] **安全鉴权中间件**：
-  - [x] 校验 `Authorization: Bearer <API_KEY>` (ConstantTimeCompare)
-  - [x] 无效/缺失 Token 统一返回标准 HTTP 401
- [x] **Local Executor (本地执行器)**：
-  - [x] 执行 Shell 命令（`exec.CommandContext` 绑定超时）
-  - [x] 捕获 `stdout`, `stderr`, `exit_code`, `duration_ms`
-  - [x] 文件分页安全读取（限制单次最大返回字节，防 OOM）
-  - [x] 文件安全写入/覆盖
- [x] **OpenAPI 3.1 动态端点**：
-  - [x] `GET /openapi.json`：包含 schema 与 BearerAuth
-  - [x] `GET /api/v1/devices`：返回本地节点信息
-  - [x] `POST /api/v1/exec`：执行本地命令
-  - [x] `POST /api/v1/file/read`：读取本地文件
-  - [x] `POST /api/v1/file/write`：写入本地文件
+当前共 11 个 Tools：
+1. `list_devices`
+2. `exec_command`
+3. `read_file`
+4. `read_multiple_files`
+5. `create_directory`
+6. `move_file`
+7. `list_processes`
+8. `edit_block`
+9. `write_file`
+10. `list_agent_mcp`
+11. `call_agent_mcp`
+
+早期“4 个 MCP Tools”的文档已经废止。

 ---

-### 📌 Milestone 2: Agent WebSocket 协议与多节点路由 (Phase 2)
+## 三、v2.0 当前收口

-> **2026-09-23 生产级 Code Review 驳回：** 原实现不得直接投入生产。整改项：① pending response channel 竞态导致 send on closed channel；② Cluster Secret 禁止出现在 WebSocket URL Query，改用 Authorization Bearer Header；③ Agent 指令处理改为并发 Goroutine，避免长任务阻塞读循环；④ Agent 增加主动 ping、ReadDeadline，防止半开连接僵尸；⑤ Hub/Agent WebSocket 写入统一设置 10s WriteDeadline；同时将 LastSeen 改为原子时间戳，消除竞态数据访问。Phase 3 在本项重新验收前保持阻塞。
- [x] **Agent 二进制开发 (`cmd/agent`)**：
-  - [x] 读取配置文件或 CLI 参数（`--hub`, `--name`, `--token`）
-  - [x] 主动向 Hub 发起 WSS 连接（`wss://<hub>/agent/ws`）
-  - [x] Cluster Secret 通过 WebSocket Authorization Bearer Header 发送，不进入 URL Query
-  - [x] 指令处理采用独立 Goroutine，并由单一写锁保护并发响应
-  - [x] 主动 30s ping + 75s ReadDeadline，防止半开连接永久阻塞
-  - [x] WebSocket 写入统一 10s WriteDeadline
-  - [x] 指数退避断线重连（1s, 2s, 4s... 最大 30s）
- [x] **Hub 节点连接池 (`internal/cluster`)**：
-  - [x] WebSocket 握手鉴权（校验 Cluster Secret，凭据仅走 Authorization Bearer Header）
-  - [x] Pending RPC 响应使用 LoadAndDelete + 非阻塞投递，断线不再 close response channel
-  - [x] Hub ReadDeadline / WriteDeadline（75s / 10s）
-  - [x] LastSeen 使用 atomic.Int64，避免读写竞态
-  - [x] 设备连接注册表（维护设备别名、WS 连接、心跳时间）
-  - [x] 定时双向 Ping/Pong（30s 周期，超时 2 次标记离线）
- [x] **RPC 路由与跨节点下发**：
-  - [x] 当 API 请求 `device == "local"` 或本机别名时 ➡️ 走 Local Executor
-  - [x] 当 API 请求 `device == "<remote_alias>"` 时 ➡️ 查找连接池，封装 JSON-RPC 消息异步等待回调
-  - [x] 设备不在线或找不到时，返回友好错误：“设备 `<device>` 处于离线状态”
+当前架构已经形成：
+- Hub 中央控制。
+- Agent WSS 回连。
+- Per-device Credential。
+- Policy Snapshot。
+- Tool Registry。
+- MCP / HTTP Unified Gate。
+- SQLite Audit。
+- Session Resource Limits。
+- Web Management Panel。

 ---

-### 📌 Milestone 3: 内嵌 Web 控制面板与审计存储 (Phase 3)
+## 四、2026-10-02 审计发现

-> **2026-09-23 M3 门禁状态：🟢 验收通过 (Passed)。** 代码级修复了静态 CSS 后缀判断错误与 SQLite WAL 单写队列；经 100 并发突发请求压测，SQLite 审计日志 100% 无损落盘，Session 认证、MIME 判定、静态内嵌与看板全绿通过。
- [x] **SQLite 存储 (`internal/storage`)**：
-  - [x] 自动初始化数据库 `commander.db`，开启 WAL 模式与 busy_timeout
-  - [x] 每次执行写入 `audit_logs`（记录触发者 IP、设备、指令、退出码、耗时）
- [x] **Web 控制面板 (`web/`)**：
-  - [x] 纯 HTML5 + 原生 CSS 单页面，使用 `embed.FS` 打包（零外部静态资源）
-  - [x] **看板 1**：节点在线状态卡片、系统基础信息
-  - [x] **看板 2**：ChatGPT Actions 向导（一键复制 Schema、Prompt 模板、Key 轮换）
-  - [x] **看板 3**：审计日志流水与刷新查询
-  - [x] **看板 4**：Web 快速调试执行器（选择设备并执行命令）
+### 4.1 生产构建漂移
+生产 Hub / Agent 曾以 `vcs.modified=true` 构建。
+这会破坏源码 → revision → binary 的可追溯链。
+
+### 4.2 代码兼容问题
+- process/session API 存在 snake_case 请求字段兼容问题。
+- Hub 本地 process/session 路径缺少 local fallback。
+
+在源码、测试和生产现场全部验证之前，上述项目不标记为“已修复”。

 ---

-### 📌 Milestone 4: 审核、收尾与交付 (Phase 4, 由 OpenClaw 严格把关)
+## 五、v2.1 路线

-> **2026-09-23 M3 正式验收通过，Phase 4 已解锁。** 本阶段进入独立总装门禁；未经全部回归、内存基线、上线链路与最终文档验收，不得标记为完成。
- [x] 代码静态分析与编译：\`go vet ./...\`、\`go test -race ./...\`、AMD64/ARM64 clean build 全通过
- [x] 内存硬上限回归：Hub 当前约 14.5MB；Agent 经 `GOGC=50` 优化后约 10.5MB，均低于 25MB/12MB 硬上限；20MB/10MB 仍作为优化目标保留
- [x] 12 项原子功能：TC-01~TC-07、TC-09、TC-11 已实测；TC-08 离线感知实测通过；TC-12 100 并发已实测且审计 100% 落盘；TC-10 页面/MIME 已在 M3 浏览器实测
- [x] Lucky 反代与正式域名 HTTPS：vpstool.kory.kdns.fr 已实测反代至本机 127.0.0.1:9521；根路径 302 到 /panel/login，OpenAPI 3.1.0 经 HTTPS 实链可访问，WebSocket Agent 已通过该上游注册在线
- [ ] ChatGPT Custom GPT 真实联调通过并归档
+### 5.1 P0-1：EffectiveRisk
+- Canonical Device Identity。
+- unknown / offline / bad credential → risk 0。
+- GlobalRisk 只作为已认证设备的业务默认。
+- Unknown 不得继承 High。

-### M4 收尾整改记录（2026-09-28）
- [x] 修正文档与实现漂移：正式 Hub 监听端口统一为 `127.0.0.1:9521`；Agent 握手统一为 `Authorization: Bearer` Header，Cluster Secret 不进入 URL。
- [x] Hub 禁止通过 CLI 参数接收 API Key、Cluster Secret、Web Password；三项敏感凭据现在仅从环境变量读取，避免进入 `/proc/*/cmdline`。
- [x] 统一内存门禁口径：Hub 25MB、Agent 12MB 为硬上限；20MB/10MB 为优化目标。
- [x] 清理遗留测试 Agent；正式 Hub/Agent 已由 systemd 单实例接管，并完成单实例远程 Agent 实联调。
- [ ] Custom GPT Actions 真实调用、Key 轮换、审计闭环与最终人工签收。
+### 5.2 P0-2：Agent Credential
+- EnvironmentFile / LoadCredential。
+- ExecStart 不出现 secret。
+- `/proc/*/cmdline` 不可读取 token。
+- 支持 rotation + rollback。

-### M4 2026-09-28 实联调证据
- [x] Hub/Agent 已切换为 systemd 管理；Hub 只监听 `127.0.0.1:9521`。
- [x] Hub 敏感凭据不再接受 CLI 参数，仅从 `EnvironmentFile` 环境变量读取；进程命令行已核验无凭据。
- [x] Agent 单实例：仅保留 `m4-live-agent` 一个正式实例；通过 `wss://vpstool.kory.kdns.fr/agent/ws` 成功注册 online。
- [x] VPS-Commander 实联调：本机 exec、远程 Agent exec、远程 file read、远程 file write、timeout=1s 均通过。
- [x] 未授权 HTTP 请求返回 401；有效 Bearer 请求返回 200。
- [x] 审计日志已记录上述 Actions 操作，最新抽查包含 `file_read` 与 timeout=124。
- [x] 临时凭据文件 `/tmp/m4-prod.env` 已删除；`/etc/vps-commander/{hub,agent}.env` 权限均为 `0600`。
- [ ] Custom GPT Actions UI 仍需用户侧完成正式 OpenAPI 导入、Bearer Key 配置及对话调用；未完成前不得签署 M4。
+### 5.3 P1：Principal
+- `principal_id`。
+- `principal_type`。
+- `credential_id`。
+- `device_id`。
+- Session Owner 绑定 Principal。
+- takeover 必须显式授权并审计。

-### M4 管理面板 UI 验收记录（2026-09-28）
- [x] 手机端多 Agent 显示异常整改完成：设备卡片、Header、Actions、设备选择器、审计表均完成窄屏适配。
- [x] 面板颜色体系改为 CSS Variables 双态主题，支持深色/浅色切换。
- [x] 主题选择持久化到 localStorage，登录页与主面板统一。
- [x] UI 静态资源与 Go embed 资源保持同步，并完成 Node JS 语法、go test ./...、release build 验证。
- [x] 用户已于 2026-09-28 人工验收通过；已重新构建 Hub 二进制并重启 systemd 服务，正式线上 UI 已立即生效。
- [ ] M4 总体验收仍保留 Custom GPT Actions 正式联调、Key 轮换及最终人工签收门禁。
+---

-### M4 终验签收记录（2026-09-28）
- [x] 安全清理：已彻底清除 `openapi.json` 中冗余残留的 `apiKey` 定义，统一收敛为标准 `bearerAuth`。
- [x] 二次回归验证通过：全链路 API 鉴权、受控节点列表获取及本地命令执行均现场实测 100% PASS。
- [x] 服务状态确认：`vps-commander-hub` (PID: systemd) 运行稳定，二进制构建已同步更新。
+## 六、标准发布顺序
+
+```text
+Backup
+  ↓
+Clean Build
+  ↓
+Single-node Gray Release
+  ↓
+Hub Restart Recovery
+  ↓
+Rolling Agent
+  ↓
+MCP / Security / Audit
+  ↓
+Full Acceptance
+```
+
+---
+
+## 七、文档同步规则
+
+任何新功能或安全变更必须同步检查：
+- README
+- ARCHITECTURE
+- DEV_SPEC
+- MCP_INTEGRATION
+- deploy/README
+- ACCEPTANCE_CRITERIA
+- PROGRESS_TRACKING
+- openapi.json（如影响 HTTP Contract）
+
+历史审核报告保持原貌，不回写成当前状态。
@@ -1,5 +1,7 @@
 # 审核专家 A：代码实现与架构安全穿透审计报告

+> 文档属性：历史独立代码审计快照。审计问题的当前处置状态以 B→A handoff、当前架构和进度文档为准。
+
 - **审核人**：审核专家 A（系统架构与安全审核组）
 - **日期**：2026-10-02
 - **对象**：`/root/.openclaw/workspace/vps-commander` 工作区最新 Go 源码实现
@@ -1,5 +1,7 @@
 # 审核专家 B：代码实现审计报告

+> 文档属性：历史独立代码审计快照。不要将当时的 BLOCKER 列表直接视为当前未修复列表。
+
 - **审核人**：审核专家 B（外部 Agent）
 - **日期**：2026-10-02
 - **对象**：`/root/.openclaw/workspace/vps-commander` 全量 Go 实现
@@ -1,5 +1,7 @@
 # 审核专家 B 给 A 的意见同步（2026-10-02）

+> 文档属性：历史审核交接快照。当前版本的后续任务以 VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md 为准。
+
 > 请 GPT（审核专家 A）阅读。本文是 B 对生产部署的独立审计结论，供 A 更新评审意见时参考。

 ---
@@ -286,6 +286,7 @@ func (s *Server) handleRequest(ctx context.Context, r *http.Request, req JSONRPC
 				InputSchema: InputSchema{Type: "object", Properties: map[string]PropertyDef{"device": {Type: "string", Description: "目标节点名称"}, "path": {Type: "string", Description: "目标文件路径"}, "old_text": {Type: "string", Description: "必须唯一匹配的原文本块"}, "new_text": {Type: "string", Description: "替换后的文本块"}}, Required: []string{"path", "old_text", "new_text"}},
 			},
 			{
+				Name:        "write_file",
 				Description: "向指定受控节点创建或覆写文件",
 				InputSchema: InputSchema{
 					Type: "object",
@@ -82,6 +82,23 @@ func TestMCPInitializeAndListTools(t *testing.T) {
 	if !ok || len(tools) != 11 {
 		t.Fatalf("expected 11 tools, got %d", len(tools))
 	}
+	foundWriteFile := false
+	for _, raw := range tools {
+		tool, ok := raw.(map[string]any)
+		if !ok {
+			t.Fatalf("tool entry is not an object: %#v", raw)
+		}
+		name, _ := tool["name"].(string)
+		if name == "" {
+			t.Fatalf("tool entry has empty name: %#v", tool)
+		}
+		if name == "write_file" {
+			foundWriteFile = true
+		}
+	}
+	if !foundWriteFile {
+		t.Fatalf("write_file missing from tools/list")
+	}
 }

 func TestMCPCallTool(t *testing.T) {
@@ -2,7 +2,8 @@
  "openapi": "3.1.0",
  "info": {
    "title": "VPS-Commander",
-    "version": "1.1.0"
+    "version": "2.0.0",
+    "description": "Current VPS-Commander HTTP contract. MCP tools are documented in docs/MCP_INTEGRATION.md."
  },
  "servers": [
    {
@@ -163,121 +164,189 @@
  "paths": {
    "/api/v1/devices": {
      "get": {
-        "operationId": "list_devices",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
        "responses": {
          "200": {
-            "description": "Devices",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/Device"
-                  }
-                }
-              }
-            }
+            "description": "OK"
          }
        }
      }
    },
    "/api/v1/exec": {
      "post": {
-        "operationId": "exec_command",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/ExecRequest"
-              }
-            }
-          }
-        },
        "responses": {
          "200": {
-            "description": "Execution result",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ExecResponse"
-                }
-              }
-            }
+            "description": "OK"
          }
        }
      }
    },
    "/api/v1/file/read": {
      "post": {
-        "operationId": "read_file",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/FileReadRequest"
+        "responses": {
+          "200": {
+            "description": "OK"
          }
        }
      }
    },
+    "/api/v1/file/list": {
+      "post": {
        "responses": {
          "200": {
-            "description": "File content",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/FileReadResponse"
+            "description": "OK"
          }
        }
      }
+    },
+    "/api/v1/file/info": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/file/search": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/process/session": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
          }
        }
      }
    },
    "/api/v1/file/write": {
      "post": {
-        "operationId": "write_file",
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/FileWriteRequest"
+        "responses": {
+          "200": {
+            "description": "OK"
          }
        }
      }
    },
+    "/api/v1/devices/file/edit_block": {
+      "post": {
        "responses": {
          "200": {
-            "description": "Write result",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/FileWriteResponse"
+            "description": "OK"
          }
        }
      }
+    },
+    "/api/v1/mcp/services": {
+      "get": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp/service": {
+      "delete": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp/list": {
+      "get": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp/call": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp/test": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/security/settings": {
+      "get": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/security/settings/update": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/security/device-credentials/provision": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/notifications/webhooks": {
+      "get": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/notifications/webhook/update": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/notifications/webhook/delete": {
+      "delete": {
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/v1/notifications/webhook/test": {
+      "post": {
+        "responses": {
+          "200": {
+            "description": "OK"
          }
        }
      }
Author	SHA1	Message	Date
kory	583b27fb5c	fix: expose write_file and document one-click operations Release / Build & Release (push) Canceled after 0s Details	2026-10-02 14:07:11 +08:00
kory	cc99022215	docs: restore established documentation format Release / Build & Release (push) Canceled after 0s Details	2026-10-02 14:01:14 +08:00
kory	71a596a556	docs: synchronize architecture deployment and MCP documentation Release / Build & Release (push) Canceled after 0s Details	2026-10-02 13:53:00 +08:00