# 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。
历史报告只追加新的后续报告，不覆盖原始证据。