Nexus/docs/project/AI-HANDOFF-2026-06-08.md

Nexus — AI 接续（2026-06-08 · Linux）

新会话请复制下方「复制提示词」整段。
SSOT：docs/project/nexus-functional-development-guide.md · 门控 bash deploy/pre_deploy_check.sh
完整待办 132 条见本文 §「Master Backlog 索引」。

---

复制提示词（整段给新会话）

【Nexus 6.0 接续 · Linux · 2026-06-08】

工作区：$NEXUS_ROOT（本机 ~/桌面/Nexus 或 /opt/nexus）
仓库：http://66.154.115.8:3000/admin/Nexus.git · 分支 main @ a401ea5
生产：https://api.synaglobal.vip · Docker @ /opt/nexus · 端口 8600
SSH：export NEXUS_SSH="azureuser@20.24.218.235"
     export NEXUS_SSH_KEY="/home/r/下载/Telegram Desktop/nz-admin.pem"  # 路径含空格须引号
push：bash scripts/git-push.sh（凭据 deploy/nexus-1panel.secrets.sh，gitignore）
部署：bash deploy/pre_deploy_check.sh && bash deploy/deploy-production.sh

【栈】FastAPI + Async SQLAlchemy + Redis · Vue 3 + Vuetify 4 SPA（15 页）· Vite → web/app/
【铁律】单 Agent · 完美实现 perfect-implementation.mdc · 改代码必 changelog + 部署前 audit · 测试 Agent 做、用户终验

【生产已部署（a401ea5）】
- server_ids 批量上限 2000 + 列表 422 中文完整（a401ea5）
- 设置页 v-form 校验 + 422 中文 + 数值字段 String 保存（632891e / ff143c2）
- 未设路径服务器区：独立面板、行内详情、批量操作与主表齐平、sort-by 排序（85ecd1f）
- 未设路径批量检测选中数修复（05c7aeb）
- 展开详情对比度 + 同步日志仅 1 条（d0526c0）
- 资源恢复 Telegram 联动 CPU/内存/磁盘开关；仪表盘移除服务器列表（fe8b24c/cb49fd9）
- 登录门控/壁纸/IP 校验、页面缓存刷新、server_batch 后台任务、WebSSH ANSI、终端快捷栏等（见 git log 2026-06-08）

【本会话运维记录】
- 批量任务 #20（install-agent）因部署重启僵尸 running；已通过任务 #26 对 #290/#346 重装 Agent 成功
- 用户报「server_ids 最多 50 项s after validation, not 101」→ 已修并部署 a401ea5
- 设置页连接池保存 422「Input should be a valid string」→ 已修并部署 ff143c2/632891e

【本地未提交 · 下一会话优先】
☐ server_batch 僵尸回收 + stuck 扫描（代码已在工作区，未 commit/部署）
  - server/background/server_batch_reconcile.py（新）
  - server/application/services/server_batch_service.py（改）
  - server/infrastructure/database/server_batch_job_repo.py（改）
  - server/infrastructure/redis/server_batch_store.py（改）
  - server/main.py（改：启动 recover + 60s reconcile loop）
  - tests/test_server_batch_reconcile.py（新）
  - docs/changelog/2026-06-08-server-batch-reconcile.md（新）
  - docs/design/plans/2026-06-08-server-batch-reconcile.md（新）
  → 流程：补 audit → pytest → commit → push → deploy

【用户终验待确认】
- 全选 101 台批量操作（install-agent / detect-path）不再 422
- 设置页连接池等数值字段保存
- 未设路径区排序、批量检测选中数、展开对比度、关 CPU 告警无恢复 Telegram
- WebSSH 实连 pwd、Telegram 测试发送、推送预览（勿误推生产）

【优先待办 TOP 10】
1. server_batch 僵尸回收 — **本地已实现，待 commit + 部署**（见上）
2. sync_logs 30 天自动清理 ☑（本地实现，待部署）
3. Agent 401 后停循环（A-05 / web/agent/agent.py）
4. Agent upgrade 与 install.sh venv 对齐（D-01）
5. ~75 条后端 API 英文 detail 改中文（Pydantic 422 已部分中文化）
6. 更新 AI-HANDOFF + alignment-plan 勾选状态（文档 SSOT）
7. L4 Playwright 全绿 + L5 production-verification-checklist
8. Dashboard 24h 历史趋势图（B-02）
9. 资产管理页 / Sync 配置 UI（C-01/C-02）
10. POSIX-14～18 + 文件管理 FM-L* 生产浏览器验收

【完整 132 条待办】docs/project/AI-HANDOFF-2026-06-08.md §Master Backlog 索引
【对齐计划 31 项】docs/design/plans/2026-06-07-missing-features-alignment-plan.md
【Master 长计划】docs/project/2026-06-01-master-backlog-plan.md

【勿重复做 / 已否决】RBAC、移动端、会话录像、审计 CSV 导出、邮件报告、Redis Cluster、独立文件编辑器
【已风险接受】WebSocket JWT query（ADR-011）、Agent global API_KEY legacy — risk-acceptance-single-operator.md

【工作区】a401ea5 已 push/deploy；本地勿提交 web/app/assets/* 构建残留、gate_log.jsonl、.cursor/settings.json
【文档】Handoff 本文 · 功能指南 nexus-functional-development-guide.md · 验收 development-acceptance-standard.md

---

生产状态

项	值
分支	main @ a401ea5
生产 URL	https://api.synaglobal.vip
运行时	Docker Compose @ /opt/nexus（1panel-network）
SSH	azureuser@20.24.218.235（本机 Host nexus 常不可用，用 IP + pem）
最近部署	2026-06-08 — server_ids 2000 + 422 中文（a401ea5）· /health ok · /app/ 200

---

2026-06-08 已推送主要变更（摘要）

Commit	主题
a401ea5	server_ids 批量上限 2000；列表 too_long 422 纯中文
632891e	设置页 v-form 校验；422 中文；SettingUpdatePayload 数字 coerce
ff143c2	设置保存数值字段 String(value) 修 422
85ecd1f	未设路径区表格 sort-by 服务端排序
05c7aeb	未设路径批量检测对话框选中数
d0526c0	展开详情对比度；同步日志 limit=1
fe8b24c	资源恢复 Telegram 联动 CPU/内存/磁盘开关
更早	登录门控、pages 自动刷新、server_batch 后台、WebSSH ANSI 等（见 docs/changelog/2026-06-08-*.md）

---

本会话未完成（写入日志 · 2026-06-08 对话框结束）

A. 代码已写未提交

模块	状态	说明
server_batch 僵尸回收	☐ 未 commit	recover_orphaned_batch_jobs + server_batch_reconcile_loop 60s；changelog/plan 已有
若干 verification 报告	☐ 未提交	docs/reports/2026-06-08-*-verification.md 多份

B. 已识别待做（未开始或部分）

#	项	状态
3	sync_logs 30 天自动 purge	☑
4	Agent 401 停循环（A-05）	☐
5	upgrade-agent 与 install.sh 对齐（D-01）	☐
—	~75 条后端 API 英文 detail 改中文	☐
—	~25 前端英/混排标签	☐
29–31	L4 Playwright + L5 验收清单	☐
87–95	用户浏览器终验（WebSSH/Telegram/推送等）	~

C. 工作区卫生

• 勿提交：web/app/assets/*、deploy/gate_log.jsonl、.cursor/settings.json
• Handoff 本文已更新至 a401ea5；server_batch reconcile 待下一会话收尾

---

关键路径

用途	路径
后端入口	server/main.py
服务器 API/批量	server/api/servers.py · server/application/services/server_batch_service.py
批量回收（未提交）	server/background/server_batch_reconcile.py
422 中文	server/utils/validation_errors_zh.py
未设路径前端	frontend/src/components/servers/ServerUnsetPathPanel.vue · ServersPage.vue
Agent 安装	web/agent/install.sh
门控	deploy/pre_deploy_check.sh（7/7）
部署	deploy/deploy-production.sh

---

Master Backlog 索引（132 条 · 2026-06-08 盘点）

新会话接某编号时说「做 #N」即可。

一、运维可靠性（1–7）

1. server_batch 僵尸任务回收（例 #20） ☑~ （本地已实现，待部署）
2. server_batch 启动 stuck 扫描 ☑~ （同上）
3. sync_logs 30 天自动 purge ☑
4. Agent 401 停循环（A-05） ☐
5. upgrade-agent 与 install.sh 对齐（D-01） ☐
6. 生产复核 push_schedules.target_path 列（A-02） ~
7. 各子机同步 agent.py（A-05 依赖） ☐

二、对齐计划 A 部署点验（8–12）

8. A-01 持续部署 ☑ · 9. A-02 ~ · 10. A-03 脚本库点验 ~ · 11. A-04 调度点验 ~ · 12. A-05 同 #4

三、14 页缺口 B（13–19）

13. B-01 Commands 推送日志 Tab ☑~ · 14. B-02 Dashboard 24h 趋势 ☐ · 15. B-03 Files 树形侧栏 ☐
14. B-04 CSV 模板 ☑~ · 17. B-05 SSOT 扩写 ☑ · 18. B-06 Settings Agent 指引 ☐ · 19. WebSSH 重连生产验证 ~

四、API 无 UI C（20–23）

20. C-01 资产管理页 ☐ · 21. C-02 Sync 配置 UI ☐ · 22. C-03 Sync 批量命令 ☐ · 23. C-04 Sync SFTP ☐

五、产品 D（24–28）

24. D-01 同 #5 · 25. D-02 宝塔监控 ☐ · 26. D-03 mTLS ☐ · 27. D-04 搜索增强 ☐ · 28. D-05 凭据轮询 E2E ☐

六、验收 E（29–50）

29. E-01 local_verify 401 ☐ · 30. E-02 Playwright 15 绿 ☐ · 31. E-03 L5 清单 ☐
    32–35. E-04～E-07 心跳/WS/守护/install E2E ☐ · 36. E-08 ☑ · 37–41. POSIX-14～18 ☐
    42–46. ENH-01～04/08 ☐ · 47–50. 文档 SSOT E-19～22（#47/#50 部分 ☑）

七、Master FM/T（51–81）

51. A-09 local_integration_smoke ☐ · 52. Phase C 浏览器 L1–L4 ☐ · 53–74. FM-L1～L4 文件管理生产验收 ☐
    75–77. ENH-05～07 文档回写 ☐ · 78. T-04 Telegram ☐ · 79. T-06 同 #31 · 80. T-07 WebSSH ~ · 81. T-08 CSV ☑

八、Handoff 可选（82–86）

82. 全选筛选结果 ☑ · 83. 失败分组 ☑ · 84. 失败导出 CSV ☐ · 85. 归档旧 handoff ☐ · 86. 其它表 sort 扫尾 ☐

九、用户终验（87–95）

87–90. WebSSH/推送/Telegram/kill 自愈 ☐ · 91–95. 近期功能浏览器终验 ~

十、L5 清单（96–125）

96–125. production-verification-checklist.md 逐项 ☐（#122 /health ☑）

十一、仓库卫生（126–132）

126–132. handoff/alignment 过期、verification 未提交、assets 残留、gate_log、.cursor ☐

十二、不做 / 风险接受（133–137）

133–135. 已否决功能 · 136–137. ADR-011 / global API_KEY 风险接受

---

常用命令

cd ~/桌面/Nexus   # 或 $NEXUS_ROOT
docker compose up -d mysql redis
bash scripts/start-dev.sh          # API :8600
bash scripts/local_verify.sh
cd frontend && npm run dev         # :3000/app/

bash deploy/pre_deploy_check.sh
bash scripts/git-push.sh
export NEXUS_SSH="azureuser@20.24.218.235"
export NEXUS_SSH_KEY="/home/r/下载/Telegram Desktop/nz-admin.pem"
bash deploy/deploy-production.sh

---

铁律

• 单 Agent；禁止虚拟部门
• 完美实现：设计→技术文档→代码→测试→changelog→（批准）部署
• 测试 Agent 执行；用户只做终验（docs/reports/2026-06-01-final-acceptance-checklist.md）

---

变更记录

日期	变更
2026-06-08 初版	3f995a7 摘要
2026-06-08 中	更新至 85ecd1f；132 条 Master Backlog
2026-06-08 末	更新至 a401ea5；记录 server_ids/设置 422 修复；server_batch reconcile 未提交待办