docs: session-environment-guide 更新为分层CI/CD流程(NAS自动+VPS dispatch+agent PAT)

Step2 改 promote --target nas(CI自动为主,手动应急);§8 改已建成分层(双workflow隔离+两种approve+PAT osxkeychain sanguo-gitea-ci)。原写同时推NAS+VPS/审批gate过时。

docs/session-environment-guide.md

@@ -47,13 +47,17 @@ pytest tests/<你的模块>/ -q
 ```
 **预期**：全绿。Mac 用 fixture，不需要真实数据。
 
-### Step 2 — 部署 NAS test + VPS prod（一条命令同时推）
+### Step 2 — 部署 NAS test（CI/CD 自动 / 手动应急）
 
+> **默认走 CI/CD 自动**：`git push origin master` → 自动 `test → nas-deploy(推 NAS 后端+前端 dist) → nas-verify(秒级 gate)`。nas-verify 绿 = NAS test 已部署验证。**VPS 不在这里推**（见 Step 4）。详见 §8。
+
+手动（应急 / CI 没跑 / Mac 睡眠）：
 ```bash
-bash scripts/nas_sync/promote.sh --module sanguo_<你的模块>
+bash scripts/nas_sync/promote.sh --target nas --module sanguo_<你的模块>   # 单模块只推 NAS
+bash scripts/nas_sync/promote.sh --target nas                             # 全量只推 NAS
 ```
-- 单模块补推用 `--module`；**改了多个模块或根文件**（pyproject/pytest.ini/requirements/run_web.py）用全量 `bash scripts/nas_sync/promote.sh`。
-- promote.sh 内部：Mac→NAS(rsync，LAN 快) + Mac→VPS(scp)。**数据铁律双防护**，绝不会推 `data/`。
+- promote.sh 支持 `--target nas|vps|all`（默认 all）。NAS 走 rsync（LAN 快），VPS 走 scp。**数据铁律双防护**，绝不推 `data/`。
+- 前端 dist 不在 promote.sh（gitignore）；CI 自动 `npm build` + rsync dist。手动推前端见运维。
 
 ### Step 3 — NAS 冒烟（数据层/读取层改动必跑）
 
@@ -129,17 +133,23 @@ VPS 是**一次性任务**模型（回测 runner + 采集 schtask），**没有
 
 ---
 
-## 8. CI/CD（自动化，建设中）
+## 8. CI/CD（已建成，分层：NAS 自动 + VPS dispatch）
 
-目标形态（Gitea Actions，NAS 1.26.2 已支持）：
+Gitea 不支持 environment approval gate，故用**双 workflow** 隔离 NAS test / VPS prod：
 ```
-push master → 自动 NAS 单测+冒烟(job_nas_test) → 通过 → 审批后推 VPS+冒烟(job_vps)
+push master → ci-cd.yml 自动: test(pytest) → nas-deploy(推NAS后端+前端dist+restart容器) → nas-verify(login+strategy/list+dbbardata 秒级 gate)
+          ↓ nas-verify 全绿 = NAS test 已部署+验证
+          ⏸️  VPS 不自动推，停下等触发
+推 VPS(nas-verify 绿后，触发 vps-deploy.yml，两种 approve):
+   人工 = Gitea UI → Actions → vps-deploy.yml → Run workflow(填 sha)
+   agent = curl -H "Authorization: token $PAT" POST .../dispatches  body {"ref":"master","inputs":{"sha":"<full-sha>"}}
+          ↓ checkout 你传的 SHA(= NAS 验证过的) → promote --target vps → verify_unified_e2e
 ```
-- **P2（NAS CI）**：push 自动跑 pytest + smoke_e2e.py。
-- **P3（VPS CD）**：NAS 通过 → 人工审批 gate（prod 安全）→ 自动 scp 推 VPS + verify_unified_e2e.py。
-- **建成前**：按本手册 §3 手动走（5 步）。
-
-建成状态见运维 session 更新。
+- **NAS 自动**：push 即触发 ci-cd.yml；nas-verify 是秒级 gate（API 健康 + 数据可读）。runner 是 Mac（睡眠时 CI 不跑，手动 `promote --target nas` 应急）。
+- **VPS 严格版本**：vps-deploy.yml 接收 `sha` input，checkout 该 commit（= nas-verify 验证过的），绝不部署未验证代码。
+- **agent approve 的 PAT**：osxkeychain 存了 `sanguo-gitea-ci`（scoped `write:repository`）。取用：`token=$(security find-generic-password -s sanguo-gitea-ci -a agent -w)`，再 `curl -H "Authorization: token $token" ...`。⚠️ MCP claude_dev token 无 write 权限（dispatch 会 403）。
+- **前端 dist**：ci-cd.yml 的 nas-deploy 自动 `npm ci + build + rsync dist`（不 commit dist、不进 promote.sh）。
+- workflow 文件：`.gitea/workflows/ci-cd.yml`(push→NAS) + `vps-deploy.yml`(dispatch→VPS)。
 
 ---