Nexus/docs/project/AI-HANDOFF-2026-05-23.md

# Nexus 6.0 — AI 接续工作交接（SSOT）

> **生成日期**: 2026-05-23  
> **用途**: 切换 AI / 新会话时**唯一接续入口**；下文汇总本会话决策、代码状态、待办与验证清单。  
> **工作区**: `C:\Users\uzuma\Desktop\svn\Nexus\.claude\worktrees\suspicious-williams-fe9492`  
> **部署状态**: ❌ **尚未部署**（无生产环境、无需「重启服务」；首次部署后再跑 E2E）

---

## 0. 给下一任 AI 的复制提示词

```
【严谨性】与 Nexus 团队同等严谨，不得降低标准。全量标准索引：
  docs/project/standards-transfer-package.md

【必读 · 按序】
1. docs/project/AI-HANDOFF-2026-05-23.md
1b. docs/project/2026-06-01-master-backlog-plan.md（文件管理/POSIX/部署/审计 长计划任务）
2. docs/project/nexus-full-site-features.md
3. docs/project/development-acceptance-standard.md
4. docs/project/standards-transfer-package.md

【规范 · 全文内化（开发 + 审计同等强制）】
- .cursor/rules/perfect-implementation.mdc
- .cursor/rules/nexus-tech-stack.mdc + nexus-python-backend.mdc + nexus-frontend.mdc + nexus-security.mdc
- .cursor/rules/audit-line-review.mdc（走读/Phase2 触发）
- standards/system-development-standard.md
- standards/line-walk-audit-standard-v2.md
- standards/audit-core-principles.md

【逐行审查】8步/文件、全文Read至EOF、Closure全表(含SAFE)、FINDING必须文件:行号、单回复≤5文件；
  禁止grep/Top15冒充审计；P0/P1当场修+changelog+矩阵。提示词见 v2 §十四.1。

【验收】完成前：pytest tests/test_security_unit.py + wsl_integration_smoke.sh + changelog；
  上线前：production-verification-checklist.md；宣称完成前读 verification-before-completion SKILL。

项目未部署。端口：子机出站443心跳；中心→子机SSH22；8601仅本机。
P1待办：WebSSH断线重连、CSV批量导入。首次部署E2E见本文§6。
已否决见§7。
```

---

## 1. 项目一句话

Nexus 6.0：2000+ 台服务器运维平台；FastAPI 四层架构 + Redis 实时心跳 + WebSocket/Telegram 告警 + asyncssh 推送/WebSSH/脚本；前端 Tailwind v4 + Alpine.js 静态页。

---

## 2. 端口与通道模型（2026-05-23 最终决策）

| 方向 | 端口 | 用途 | 是否必须 |
|------|------|------|----------|
| 子机 → 中心 | **443 出站** | Agent 心跳、长任务 `curl` 回调 | ✅ 必须 |
| 中心 → 子机 | **22 入站** | rsync 推送、文件浏览/操作、**脚本执行**、**手动健康检查**、Agent 安装/升级 | ✅ 必须 |
| 子机本机 | **127.0.0.1:8601** | Agent uvicorn（仅本机） | 可选进程；**不要求公网 8601** |

**已否定/不推荐**

- 为脚本/健康检查强制公网开放 8601  
- 用宝塔「Python 项目管理器」托管 Agent（与面板生命周期耦合）  
- 用 btpanel-skills 安装 Agent（skills 仅适合读面板监控 API，见 [btpanel-skills](https://github.com/aaPanel/btpanel-skills)）

**Go 单二进制 Agent**：长期可选；当前子机均有 Python 3.12，优先 venv 方案。

---

## 3. 本会话及近期已完成（代码）

### 3.1 架构 / 运维向

| 项 | 说明 | 关键文件 |
|----|------|----------|
| 脚本执行改 SSH | 不再依赖中心访问子机 8601；结果含 `channel: ssh` | `server/application/services/script_service.py` |
| 手动健康检查改 SSH | `check_all_servers` 经 SSH 探测指标 | `server_service.py`, `server/infrastructure/ssh/remote_probe.py` |
| Agent 安装脚本 | python3.12+ venv、`127.0.0.1` 监听、不自动放行公网 8601 | `web/agent/install.sh` |
| 安装说明文案 | 心跳 443 / 脚本 SSH / 无需公网 8601 | `web/app/servers.html` |
| Changelog | | `docs/changelog/2026-05-23-ssh-exec-no-8601.md` |

### 3.2 功能向（会话前后期，代码已在仓库）

| 项 | 说明 |
|----|------|
| 推送 dry-run 预览 | `push.html` + `SyncEngineV2.preview_sync()`，方案 D 智能提示 |
| 推送日志视图 | `commands.html` 推送日志 Tab |
| 脚本快捷执行 | `scripts.html` 直接执行面板 |
| 定时脚本执行 | `schedule_runner.py` + `schedules.html`，`schedule_type=script` |
| 审计时间/用户过滤 | `audit.html` + `settings.py` API |
| 告警中心页 | `alerts.html` + `/api/alert-history` + `AlertLog` 表 |
| Telegram 测试 / Chat ID | `settings.html` + settings API |
| 告警分项 Telegram 开关 | `settings.html` + `NOTIFY_*` 配置 |
| 登录 IP 白名单 + 订阅解析 | `subscription_parser.py` + `ip_allowlist_refresh.py`（2h） |
| Agent 远程安装 / 安装命令 | `servers.html` + `install-agent` API |
| Agent 升级（SSH） | `POST /servers/{id}/upgrade-agent`（**未**随新 venv install.sh 对齐，见待办） |
| Agent IP 白名单 | `agent.py` + `install.sh` 写入 `allowed_ips` |
| 时钟漂移检测 | 心跳 `agent_time` + UI 徽章 + Telegram |
| TOTP 重绑 UX | `settings.html` |
| 远程文件删/改名/建目录 | `sync_v2.py` |
| Phase 2 审计 63 项 | 矩阵 `docs/reports/audit-phase-2-findings-matrix.md` |
| WSL 联调脚本/venv | `scripts/wsl_*.sh`, `docs/project/wsl-integration-test.md` |
| 标准文档目录 | `standards/` + `docs/project/*-standard*.md` |

### 3.3 代码完成度（主观）

- **核心业务代码**: ~95%～98%  
- **首次部署 E2E**: 0%（未部署）  
- **用户要求的增强功能**: 仍有 **5～7 项未写代码**（见 §4）

---

## 4. 待实现功能（下一任 AI 工作 backlog）

按用户确认优先级排序。

### P1 — 建议先做

| ID | 功能 | 说明 | 建议触及文件 |
|----|------|------|--------------|
| F-01 | **WebSSH 断线重连** | 方案 C：断线自动重试 1 次 + 手动重连按钮 | `web/app/terminal.html`, `server/api/webssh.py` |
| F-02 | **服务器批量导入 CSV** | 上传 CSV → 校验 → 批量 `POST /api/servers/` | 新 API + `servers.html` |
| F-03 | **Agent 升级与 install.sh 对齐** | `upgrade-agent` 应使用 `/opt/nexus-agent/.venv` + 127.0.0.1 | `server/api/servers.py` |

### P2 — 迭代

| ID | 功能 | 说明 |
|----|------|------|
| F-04 | **仪表盘历史趋势图** | CPU/内存时序；需 Redis/MySQL 历史或新聚合 |
| F-05 | 远程文件上传 UI | 可用 WebSSH/scp/推送代替；非阻塞上线 |
| F-06 | 远程文件内容预览 | 可用 WebSSH cat 代替 |

### 可选 / 讨论项（未承诺实现）

| ID | 功能 | 说明 |
|----|------|------|
| F-07 | 宝塔面板 API 监控增强 | 参考 aaPanel/btpanel-skills，补站点/服务状态（**不**替代 Agent） |
| F-08 | Agent ↔ 中心 mTLS | 安全增强，工作量大 |
| F-09 | Docker Compose 部署 | 用户称暂不需要 |
| F-10 | Go 单二进制 Agent | 2000+ 台 Python 3.12 齐全时可暂缓 |

### SSH 回退（已采用主路径，非待办）

用户曾问「SSH 回退」：已实现为**默认 SSH**，非「Agent 失败再回退」。无需再做了 Agent 优先逻辑，除非用户改口。

---

## 5. 标准转接（与团队同等严谨 · 下一任 AI 必读）

| 文档 | 路径 |
|------|------|
| **标准转接包（全量索引）** | [`standards-transfer-package.md`](standards-transfer-package.md) |
| 开发验收 L0～L5 | [`development-acceptance-standard.md`](development-acceptance-standard.md) |
| 标准目录 | [`standards/README.md`](../../standards/README.md) |

**逐行审查**：与开发规范**同等强制** — 全文见 `standards/line-walk-audit-standard-v2.md` + `standards/audit-core-principles.md`；Cursor 触发器 `audit-line-review.mdc`。

**开发规范**：`standards/system-development-standard.md` 全文 + 档 B 全部 `.cursor/rules/nexus-*.mdc`。

---

## 5b. 开发验收标准（L0～L5 速查）

**SSOT**：[`development-acceptance-standard.md`](development-acceptance-standard.md)

| 层级 | 何时用 | 关键文档 |
|------|--------|----------|
| L0 | 始终 | `perfect-implementation.mdc`、`standards/system-development-standard.md` |
| L1 | 新功能/大改 | `docs/design/specs/`、`docs/design/plans/` 内验收标准 |
| L2 | 每次改代码合并前 | `pytest tests/test_security_unit.py`、`scripts/wsl_integration_smoke.sh` |
| L3 | 安全路径改动 | `standards/line-walk-audit-standard-v2.md`、`audit-core-principles.md` |
| L4 | 模块 E2E | `script-execution.md` §11、`alert-push-policy.md`、T1～T5 |
| L5 | 首次部署/上线 | `production-verification-checklist.md`（逐项勾选） |

**禁止**：未跑 L2 命令就声称「已完成」；未勾 L5 就声称「可上线」。

---

## 6. 待验证（非「未实现」，但上线前必做）

**项目未部署时不要写「请重启生产」**；以下在 **first deploy** 后执行。

### 6.1 基础（`CLAUDE.md` / `AGENTS.md`）

- [ ] T1 心跳 Redis 写入  
- [ ] T2 WebSocket  
- [ ] T3 三层守护（杀 Python → Supervisor 拉起）  
- [ ] T4 Telegram  
- [ ] T5 install.html 五步  

### 6.2 脚本平台（`docs/project/script-execution.md` §11）

- [ ] T-SE1～T-SE8（分批、长任务回调、停止、Redis 刷盘等）  
- **注意**: 文档仍写 Agent `:8601` 执行，**实际已改 SSH** — 验证时按 SSH 测，并更新文档。

### 6.3 首次生产清单

完整表：`docs/project/production-verification-checklist.md`

### 6.4 WSL 代码向（无密钥核对）

`docs/project/wsl-integration-test.md` + `scripts/wsl_integration_smoke.sh --code-only`

### 6.5 建议「最小首次部署 10 条」

1. install 向导生成 `.env` + 管理员  
2. 登录 + TOTP  
3. 添加 1 台子机（SSH 凭据）  
4. 子机安装 Agent（新 `install.sh`），确认 **无需公网 8601** 仍有心跳  
5. 仪表盘看到 Redis 在线/指标  
6. SSH 推送 1 个目录（dry-run + 正式）  
7. SSH 执行短脚本（`channel: ssh`）  
8. WebSSH 连接 + 命令审计  
9. Telegram 测试发送  
10. `alerts.html` 有告警历史记录  

---

## 7. 已否决（永久不做，除非用户书面改口）

| 功能 | 原因 |
|------|------|
| 文件编辑器（Monaco/ACE） | 2026-05-23 用户明确抛弃；WebSSH + vim |
| RBAC / 多管理员 | 鉴权即信任 |
| 审计日志导出 CSV/JSON | 用户不需要 |
| 移动端适配 | 用户否决 |
| 会话录像 asciicast | 不需要 |
| Redis Sentinel/Cluster | 用户不需要 |
| Docker 部署（当前阶段） | 用户暂不需要 |
| 推送结果邮件报告 | 不需要 |

记录：`docs/Nexus-功能说明书.html` §15（部分条目已过期，见 §8）

---

## 8. 文档债务（下一任 AI 应同步）

| 文档 | 问题 | 动作 |
|------|------|------|
| `docs/Nexus-功能说明书.html` | §15 仍写审计过滤/定时脚本「未实现」 | 更新为已实现 |
| `docs/project/script-execution.md` | 仍写 Agent HTTP 执行、:8800/:8601 | 改为 SSH 22 + 443 心跳 |
| `docs/design/specs/2026-05-19-sprint-planning.md` | WebSSH/ install 仍标待做 | 标为已完成或归档 |
| `PROJECT_HANDOVER.md` | 日期与端口模型旧 | 顶部链到本文 |
| `CLAUDE.md` / `AGENTS.md` | 待测试列表仍有效 | 部署后勾选 |

**新变更务必**: `docs/changelog/YYYY-MM-DD-*.md`（`perfect-implementation.mdc`）

---

## 9. 环境与约束（用户确认）

- **子机**: 宝塔面板；Python **3.7.16**（面板 pyenv）+ 系统 **3.12.3**  
- **Agent 安装**: 固定 **3.12 venv**，隔离于宝塔 pyenv 3.7  
- **防火墙**: 多数子机**未开公网 8601**；推送/脚本依赖 **22**；心跳依赖 **出站 443**  
- **WSL 联调**: 只验证代码路径，不纠结部署密钥是否入 git（install 生成）  
- **仓库**: 唯一 Nexus 仓库；worktree 开发  

---

## 10. 关键路径索引

| 类别 | 路径 |
|------|------|
| 接续 SSOT | **本文** |
| **全站功能清单** | `docs/project/nexus-full-site-features.md` |
| **标准转接包** | `docs/project/standards-transfer-package.md` |
| **开发验收标准** | `docs/project/development-acceptance-standard.md` |
| **系统开发标准** | `standards/system-development-standard.md` |
| **逐行审计 v2** | `standards/line-walk-audit-standard-v2.md` |
| **审计原则** | `standards/audit-core-principles.md` |
| **功能说明书 HTML** | `docs/Nexus-功能说明书.html` |
| 项目记忆 | `CLAUDE.md`, `AGENTS.md` |
| 进度 | `docs/project/status.md`, `docs/project/roadmap.md` |
| 部署 | `docs/project/deploy.md` |
| 审计矩阵 | `docs/reports/audit-phase-2-findings-matrix.md` |
| 脚本 SSOT | `docs/project/script-execution.md` |
| 标准 | `standards/README.md`, `docs/project/line-walk-audit-standard-v2.md` |
| Agent | `web/agent/agent.py`, `web/agent/install.sh` |
| 脚本 SSH | `server/application/services/script_service.py` |
| 健康 SSH | `server/infrastructure/ssh/remote_probe.py` |
| 告警历史 | `web/app/alerts.html`, `server/api/settings.py`（alert_history_router） |
| Changelog 示例 | `docs/changelog/2026-05-23-ssh-exec-no-8601.md` |

---

## 11. 架构分层（禁止违反）

```
web/app/*.html → server/api/*.py → application/services → infrastructure/* → domain/models
```

- API 层：JWT + Pydantic；不写 SQL  
- 无 `.env` → 安装模式（仅 `/api/install/` + 静态）  
- 不可从 DB 覆盖：`SECRET_KEY`, `API_KEY`, `ENCRYPTION_KEY`, `DATABASE_URL`  

---

## 12. Git / 提交说明

- 用户**未要求 commit** 时勿主动提交  
- 当前 worktree 含大量未跟踪 `.cursor/`、修改的 `server/**`、`web/**`、`docs/**`  
- 合并前建议：按逻辑拆分 commit（SSH 通道 / 功能增强 / 文档）

---

## 13. 会话决策时间线（摘要）

1. WSL 全链路联调 → Redis pool、SQLAlchemy aiomysql patch、venv  
2. Phase 2/3/4 逐行审计 → 63+ 项修复  
3. 标准文档 → `standards/`  
4. 功能 gap 讨论 → dry-run、告警中心、白名单、定时脚本等 **已实现**  
5. 文件编辑器 → **否决**  
6. Agent 8601 vs SSH → **脚本+健康检查走 22；心跳走 443；弱化 8601**  
7. 宝塔 Python 管理 → **不用**；venv + 3.12  
8. 项目未部署 → **无需重启**  

---

**文档维护**: 下一任 AI 完成待办或验证后，更新本文 §4 §5 §7 的勾选状态，并写 changelog。