aps-agent/docs/development/pi-fallback-runbook.md

# Pi Agent 兜底能力发布与现场运行手册

> 角色：Agent-D（P5 发布实现）· 成文日期：2026-09-04
> 依据：`poc/pi-fallback/P4-P5-DESIGN.md` §5、`poc/pi-fallback/P4-P5-AUDIT.md`、`docs/architecture/fallback.md` 与当前代码。
> 本文只写运行与发布准备边界，不替代 `CHANGELOG.md`/`fallback.md`；那两份由主管统一更新。

## 1. 启用前提与 fail-closed 开关

当前兜底形态是**本地 spawn runner**：Python 编排器在应用进程内拉起 Node + Pi CLI 子进程；没有已交付的独立 pi-runtime service。仓库 `poc/pi-fallback/runtime` 只是开发用安装，**不是发布产物**。启用前必须满足：

- 应用容器或部署机具备 Node（建议 22）与 Pi 制品，或显式配置 `APS_FALLBACK_PI_CLI`/`APS_FALLBACK_NODE`；
- 模型网关可由服务端访问，并配置 `LLM_BASE_URL`/`LLM_API_KEY`；
- 持久化目录可写且可长期保留 run/审计证据；
- P3 高风险场景使用前准备好 `fallback-highrisk.json` 与审批角色策略。

### 1.1 默认关

`server/agent_core/feature_flags.py` 的 `_DEFAULT_OFF_KEYS = {"fallback"}`。文件缺失、JSON 损坏、结构非法、取值非 bool、加载异常，全部回退 `fallback=False`。因此**未显式开启时不拉起 Pi 子进程**，聊天链路逐字节走原话术。

显式开启：

```json
{"version": 1, "features": {"fallback": true}}
```

配置路径默认 `APS_FEATURES_PATH`，未设置时为 `path_under_data("features.json")`（Web 通常 `server/data/features.json`，桌面 `~/.aps/data/features.json`）。可用 `GET /api/features` 的 `defaultOff` 核对语义。

### 1.2 环境变量

| 变量 | 作用 | 默认 |
|---|---|---|
| `APS_FALLBACK_DIR` | run 根目录 | `path_under_data("fallback")`（Web=`server/data/fallback`，桌面=`~/.aps/data/fallback`） |
| `APS_FALLBACK_PI_CLI` | Pi CLI 路径 | **代码默认回仓库 poc 路径，发布必须显式覆盖** |
| `APS_FALLBACK_PI_HOME` | Pi 配置目录 | `<fallback_root>/pi-home` |
| `APS_FALLBACK_NODE` | Node 可执行文件路径 | `node`（Windows 优先 `node.exe`；建议显式给绝对路径） |
| `APS_FALLBACK_MODEL` | 显式模型 | 空则 `GET {LLM_BASE_URL}/models` 协商，缓存 300s |
| `APS_FALLBACK_TIMEOUT_SEC` | 单次运行超时 | 90 |
| `APS_FALLBACK_MAX_STEPS` | 工具步数上限 | 30 |
| `APS_FALLBACK_MAX_OUTPUT_BYTES` | 输出体量上限 | 2 MiB |
| `APS_FALLBACK_EXEC_TIMEOUT_SEC` | 执行段预算 | 120 |
| `APS_FALLBACK_EXEC_MAX_STEPS` | 执行段步数 | 40 |
| `APS_FALLBACK_MAX_PLAN_STEPS` | 计划步骤上限 | 10 |
| `APS_FALLBACK_OPS_LOG_LINES` | S7 日志尾部行数 | 300 |
| `APS_FALLBACK_S6_MAX_CARDS` | S6 出卡全局封顶 | 20（白名单 `maxItemsPerRun` 优先） |
| `APS_FALLBACK_HIGHRISK_PATH` | P3 白名单路径 | `path_under_data("fallback-highrisk.json")` |
| `LLM_BASE_URL` | 模型网关地址 | 无默认，缺失即不可用 |
| `LLM_API_KEY` | 模型网关密钥 | 无默认，缺失即不可用；只进子进程环境，不打印不落盘 |
| `LLM_MODEL` | 期望模型 | 可选；不在清单时取第一项并记录协商说明 |

即使设置 `APS_FALLBACK_MODEL`，仍需 `LLM_BASE_URL`/`LLM_API_KEY`，因为 Pi 侧需要网关地址与密钥引用。P3 审批可能还涉及 `APS_APPROVAL_ROLE_POLICIES`（例如 `{"approval.approve":{"P3":["ops","admin"]}}`）。

## 2. Web/Docker 部署与 Pi 制品路径

### 2.1 现状

- Web/服务端部署当前是本地 spawn：Python 服务在本容器内启动 `node cli.js`；
- 现有 Dockerfile 只含 Python 与 `apps/web/dist`，**没有 Node/pi**；
- `packaging/k8s/deployment.yaml` 没有 `APS_FALLBACK_*`、Node/pi 相关配置；
- 因此镜像/Deployment 当前**不具备启用兜底的运行时**，只改环境变量无效。

### 2.2 Web/Docker 两态

主管裁决前，只记录两种可验收形态：

1. **Node + Pi 制品打进应用镜像或部署目录**：镜像/挂载卷提供固定版本 Node 与 Pi 制品，Python 通过 `APS_FALLBACK_PI_CLI`/`APS_FALLBACK_NODE` 指向；run 目录挂持久卷。这是“本地 spawn runner + 制品”形态。
2. **独立 pi-runtime service**：未来新增运行器协议与边界；**本轮不承诺已可用**，不得写入部署文档作为已完成能力。

镜像内建议 `APS_FALLBACK_DIR=/app/server/data/fallback`（或对应持久卷路径）；容器临时层不适合保留审计/回放证据。缺少 Node/pi/模型时，功能保持显式失败，服务不得崩溃。

### 2.3 现场核对

```powershell
Get-ChildItem -Recurse -LiteralPath "<镜像或部署目录>" -Filter cli.js |
  Where-Object { $_.FullName -match 'pi-coding-agent' } |
  Select-Object -First 10 FullName
```

发布清单必须能看到明确 Pi 制品；只看到仓库 poc 路径不能算“镜像已含 runtime”。

## 3. 桌面可选组件与 sidecar env 边界

当前桌面默认包不含 Node/pi：

- `apps/desktop/package.json` 的 `extraResources` 只含 `web/dist` 与 PyInstaller sidecar；
- `packaging/aps-sidecar.spec` 只收 Python 模块，未收 Node/pi；
- `sidecar.cjs` 的 `CHILD_ENV_ALLOWLIST` 不含 `LLM_*`/`APS_FALLBACK_*`，因此当前 Electron sidecar 不能把模型/兜底环境传给 Python。

文档边界：**不声称桌面已内置启用 Pi 兜底**。未来若要桌面启用，至少需由主管拍板：

1. 是否把 Node + Pi 作为安装包内可选组件，或首次使用下载；
2. sidecar 环境 allowlist 是否扩展 `LLM_*`/`APS_FALLBACK_*`；
3. 组件签名、体积、无网络安装、升级/回滚验收（参照 `docs/development/packaging-smoke.md`）；
4. 若迁 Tauri，Node runtime 方案与 Tauri 决策串行重设计。

本轮只给出可选组件边界与可复跑清单，不做“桌面默认可用”表述。

## 4. 无模型、断网与 MES 断连处置

### 4.1 无模型/模型网关不可达

当前行为是**逐次显式失败**：

- 缺少 `LLM_BASE_URL`/`LLM_API_KEY`、Node/pi 不可解析、`GET /models` 超时/异常/空清单 → 回原话术并附 `unavailable:<原因>`；
- 写 FAILED 审计；不会自动把 `fallback` 置 false；
- 当前没有专门 UI 状态位“模型不可用已强制关闭”。

这与详细方案 F5 的“无模型 force-off + UI 明示”**不一致**，已在缺口表中列为待主管裁决项。运维处置：看失败原因，检查 Node/Pi/网关配置后重试；不打算启用时把 `features.json` 显式写回 false。

### 4.2 断网/超时

propose 默认 90s/30 步/2MiB，执行段默认 120s/40 步；任一超限即杀进程树、显式判败。成败只看事件流 `stopReason=stop` 且报告非空，不看进程退出码。网络不可达不阻塞聊天主链路。

### 4.3 MES 断连（S6）

- 在线路径不变：未声明 `offlineBooking` 时先推 MES 后落账，断连即显式失败并回滚；
- 离线落账必须双成立：计划 params 显式 `offlineBooking:true` **且** 出卡/执行端实时探测 MES `failed`；
- 双成立才本地落账并打 `syncStatus=PENDING_SYNC`，确认卡明示“本地落账待同步”；
- 审批窗口内 MES 已恢复 → 执行端拒绝/回滚；offlineBooking 不能用来绕过 MES 在线校验；
- 恢复后由人重新发起“对一下账”；探测仍失败则回复“尚未恢复”，不轮询、不猜；
- 对账为纯读：MATCH/DRIFT/MISSING，外部原文与 `reconcile-manifest.json` sha256 冻结，报告不写世界；
- PENDING_SYNC 自动补推属后续轮次，当前未实现。

## 5. run 目录、审计回放、checkpoint/回滚

根：`APS_FALLBACK_DIR` 或 `path_under_data("fallback")`。单个 run 目录形态：

```text
<fallback_root>/fb-YYYYMMDD-HHMMSS-xxxxxx/
├── inbox/                  # snapshot.md / orders.csv / 集成状态 / ops 诊断 / external
├── work/                   # Pi 子进程工作目录
├── outbox/                 # report.md / plan.json / sandbox 产物 / reconcile 产物
├── events.jsonl
├── orchestrator.log
├── result.json
├── calls.jsonl
├── guard-<runId>.ts
├── execution.jsonl / execution.events.jsonl
└── outbox/reconcile-manifest.json   # S6 对账证据冻结文件
```

审计关联：完成审计 rationale 含 `runId`；工具事件 actor=`pi-fallback:<runId>`；`evidence_refs=["fallback-run:<runId>"]`；S6 对账另含 `manifestSha256`。

回放现状：`GET /api/gov/audit` 只返回最近 `limit` 条，**没有服务端 runId 过滤参数**；GovConsole 无 runId 搜索/一键回放视图。当前可靠回放是“runId + run 目录文件 + sha256 + 客户端筛选审计”，不能写成系统现成 runId 回放功能。

P3-DESIGN 曾要求 S7 每 run 追加通用 `manifest.json`；当前源码只找到 S6 `reconcile-manifest.json` 写路径，**未发现通用 S7 manifest 写路径**，作为发布前缺口处理。

回滚/收尾：

- S6 逐笔独立确认卡/checkpoint，单笔拒绝不影响其他；
- S7 配置为整文档替换：tmp + 原子 replace + `.bak` + 回读校验；
- S4 沙盒不改主世界，校验前后世界指纹 + 零 `WORLD_WRITE`；
- 失败后不得残留 `_saga_cp.json` 或 Pi 进程。

## 6. 回归与验收命令（.venv\Scripts\python.exe）

Python 一律使用仓库 `.venv\Scripts\python.exe`；命令只验证，不 commit/push、不跑真实打包。

### 6.1 定向确定性 golden

```powershell
.venv\Scripts\python.exe -m pytest `
  tests/golden/test_fallback_lane.py `
  tests/golden/test_fallback_execute.py `
  tests/golden/test_fallback_highrisk.py `
  tests/golden/test_fallback_offline_booking.py `
  tests/golden/test_fallback_p3_attack.py `
  tests/golden/test_feature_flags.py `
  -q
```

P4 质量专项已交付并经主管复核（2026-09-04），命令：

```powershell
.venv\Scripts\python.exe -m pytest tests/golden/test_fallback_p4_quality.py -q
```

主管复核结果：

- P4 质量：44 passed，结论与场景映射见 `poc/pi-fallback/P4-QUALITY-NOTES.md`；
- P4 注入：57 passed / 1 skipped，见 `poc/pi-fallback/P4-SECURITY-NOTES.md`；
- P4 离线：24 passed，见同一 security notes；
- 主管 8 文件联合（lane / execute / highrisk / p3_attack / offline_booking +
  P4 quality / injection / offline）：197 passed / 1 skipped in 51.87s；
- ruff：All checks passed；
- 汇总复核记录见 `poc/pi-fallback/P4-P5-VALIDATION.md`。

确定性门禁现可按上述结果勾选；真实 runtime/Docker/桌面打包、真实 smoke 与
发布批准仍以本手册其余边界与 `poc/pi-fallback/P5-RELEASE-NOTES.md` 为准。

### 6.2 S6/S7 真实冒烟（需真实 Node/Pi/LLM key）

```powershell
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s6_reconcile.py setup
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s6_reconcile.py outage
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s6_reconcile.py recovery
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s6_reconcile.py control
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s6_reconcile.py finalize
```

```powershell
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s7_ops.py setup
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s7_ops.py ops
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s7_ops.py control
.venv\Scripts\python.exe poc/pi-fallback/smoke/smoke_s7_ops.py finalize
```

冒烟收尾核对：无 `_saga_cp.json`、无 `server/data` 非预期残留、无残留 pi 进程。冒烟脚本会构造临时现场/CSV/假 MES，属验证设施，不是产品文件摄入能力。

### 6.3 已知未实现项与待裁决

1. P3 产品代码未提交；P3-VALIDATION 存在 GO/NO-GO 文档矛盾；
2. Pi runtime 未进 Docker/K8s/桌面发布包；仓库 poc 路径不是发布产物；
3. 桌面 sidecar 不允许 `LLM_*`/`APS_FALLBACK_*` 透传；
4. P4 注入/离线专项、P4 notes、P4-P5-VALIDATION 已交付并复核（注入 57 passed / 1 skipped、
   离线 24 passed），不再作为“未交付/无结论”缺口；
5. P4-QUALITY-NOTES 已提供确定性集成功率/误写率/确认轮次/耗时与 cost_points 近似聚合，
   产品层仍无统一指标导出、真实 token/cost 与 per-step 耗时；
6. 无 Pi usage/token/cost 解析、日预算/告警、触发率周报；
7. F5 无模型 force-off + UI 明示与现状不一致；
8. `/api/gov/audit` 无 runId 服务端过滤，GovConsole 无 runId 回放视图；
9. S4 真实冒烟未做；S6 超上限真实冒烟未做；S7 通用 manifest 写路径未见；
10. 全量 golden 基线数字口径过期（1071+ 等），需主管统一；
11. WMS 侧补录不在 P3 范围。