yawan-workbench/修复融合版变更说明-2026-08-29.md

# 修复融合版变更说明（2026-08-29）

> 基于源码包 2026-08-28 的全部改动清单。当前版本：后端 101 项测试全部通过，前端 TypeScript 0 错误、Vite 构建通过，真机全链路检测通过。

## 0b. 第三轮：P0 收尾（2026-08-29 晚）

### P0-4 租户边界数据库级强制
- `init_db` 自动创建 9 张业务表的租户触发器（`trg_*_tenant_ins`）：`organization_id < 0` 或 NULL 的数据直接被数据库 ABORT，越权数据无法落库。
- 修复引擎绑定：`main.py` / `db.get_session` 改为动态取引擎（`_engine()` / `_current_engine()`），测试可整体替换数据库。
- 3 项越权集成测试（真实登录流程）：触发器拒绝负 org、跨租户任务列表不可见/详情 404、全局资源跨租户可见。

### P0-5 自动备份与恢复演练
- 新增 `server/app/backup.py`：
  - SQLite 在线备份 API 一致性快照 + 知识库原文打包 zip（跳过可重建的向量索引）；
  - 启动时备份一次 + 每 6 小时周期备份；保留最近 14 份自动清理；
  - 完整性校验（zip 逐条 CRC + 内存库 deserialize 打开 + 关键表检查）；
  - **恢复演练**：每次备份后对最新备份做真实解压 + SQLite 打开验证，结果落盘 `restore-drill.json`。
- API：`GET /api/ops/backup`（状态）、`POST /api/ops/backup`（立即备份）、`POST /api/ops/backup/drill`（手动演练）；运营看板新增「备份与恢复」面板（份数/最近时间/大小/演练结果 + 一键备份/演练）。
- 7 项测试。

## 0. 第二轮：P0 企业级 + P2 运营（2026-08-29 晚）

### P0-1 Provider 密钥进 macOS 钥匙串
- 新增 `server/app/secret_store.py`：优先用 `security` 命令写入登录钥匙串；DB 的 `api_key` 字段只存 `keychain:服务:键名` 引用；钥匙串不可用时自动降级回明文（旧行为，跨平台可用）。
- Provider 创建/更新时密钥自动入串；`llm.py` 与模型发现按引用取回真实密钥；API 只返回掩码（`•••• 钥匙串保管` / `***后四位`）并标注 `secret_backend`。
- 6 项测试。

### P0-2 对象存储适配器
- 新增 `server/app/storage.py`：统一 `save/read/delete/exists` 接口；`local`（默认，磁盘）与 `s3`（MinIO/COS/S3，环境变量 `YAWEN_STORAGE_BACKEND=s3` + `YAWEN_S3_*` 启用，懒加载 boto3）双实现。
- 存库引用格式 `local://key` / `s3://bucket/key`，`..` 路径穿越净化，原子写（tmp+rename）。
- 6 项测试。

### P0-3 持久任务队列
- 新增 `server/app/task_queue.py` + `TaskQueueItem` 表：租约（5 分钟心跳，超时视为 worker 死亡可被抢占）、抖动退避重试（最多 3 次）、死信队列（可手动重放）、`task_key` 幂等入队。
- `_schedule_run` 已接入：任务同步入持久队列，运行结束同步完成状态；服务崩溃后孤儿任务凭租约超时自动回收。
- 7 项测试。

### P2 告警引擎 + 运营看板
- 新增 `server/app/ops.py`：四类巡检（死信积压 / 磁盘 < 2GB / 全局点数 < 1000 / 任务失败超 30 分钟未处理），写入 Notification，10 分钟窗口按 `dedup_key` 去重；启动后每 5 分钟自动巡检。
- 新增 `/api/ops/dashboard` 一屏看板 + `/api/ops/alerts/sweep` 手动巡检 + `/api/ops/dead-letter/{id}/requeue` 死信重放。
- 前端新增「运营看板」页（`pages/OpsPage.tsx`）：队列四卡、任务与质量（含知识库消费进度条）、Provider 健康（标注密钥后端）、最近告警、死信列表一键重放；15 秒自动刷新。
- 6 项测试。

## 1. 错误修复

1. `web/pnpm-workspace.yaml` 配置无效（缺 packages 字段）导致 `pnpm install` 报错，已删除。
2. 交付报告 P1-5：QC / Composer 读取产物失败时静默 `except: pass`，空正文会流入质检和成稿。已改为显式失败：
   - QC：写入 `qc-artifact-read` FAIL 报告并注明原因；
   - Composer：停止组合并返回逐段失败明细；docx 写入失败会在稿内标注系统提示。
3. 交付报告 P1-6：Chroma 向量写入降级不可观测。已改为：fallback 文件写入失败直接抛错；Chroma 失败记录 WARNING 日志（fallback 兜底检索不受影响）。
4. 新增 SPA 静态托管：后端直接托管 `web/dist`，单端口 8010 同时提供 API 与页面（`/admin`、`/app` 前端路由自动回退 index.html）。修复过程中规避了 FastAPI `HTTPException` 与 Starlette 基类不匹配的异常捕获坑。

## 2. UI 重构（墨韵金设计系统）

1. `App.tsx` 拆分：`types.ts`（共享类型）、`constants.ts`（状态表/运行时标签/页面元数据/规则模板）、`ui.tsx`（Tag、错误边界）。
2. 全新深色主题：墨蓝分层表面 × 香槟金品牌色，覆盖全部 211 个样式类；卡片 hover 浮起、侧栏金色选中态、状态灯呼吸动效、弹窗入场动画，完整响应式断点与 `prefers-reduced-motion` 支持。
3. 登录页重设计：分屏沉浸式布局（左侧品牌区 + 右侧表单），窄屏自动降级为单栏。

## 3. Hermes Agent 优点融合（以雅文为主体）

1. **运行级轮次预算**（源自 `iteration_budget.py`）：新增 `server/app/hermes_core.py`。每次任务运行 240 轮共享预算池，覆盖拆解/生产/质检/组合全部会话；耗尽自动熔断并写入 `run_budget_exhausted` 事件，运行结束释放预算池。
2. **抖动退避 + Retry-After**（源自 `retry_utils.py`）：`llm.py` 的固定 `2^n` 退避替换为全抖动退避，优先尊重服务端 Retry-After，防止并发限流踩踏。
3. **工具停滞护栏**（源自 `tool_guardrails.py`）：同一工具 + 相同参数连续调用 3 次注入换参数提示，5 次熔断会话并写明原因，保护点数余额。
4. **真实系统自检**：新增 `/api/system/status`，侧栏状态灯实时反映数据库/向量库/磁盘/调度队列健康度（15 秒刷新），异常时变橙色警告。
5. **任务启动前准备度检查**（交付报告 P1-1）：新增 `server/app/readiness.py` 与 `/api/campaigns/{cid}/readiness`。启动前一次性检查：内容段、生产 Agent 状态、模型链路、知识库挂接与索引、QC/Composer、点数余额；未就绪直接 409 阻断并逐条返回原因，任务页「生产进度」卡片同步显示黄色阻断/提示块。

## 4. 测试

- 原有 31 项全部保留并通过。
- 新增 `tests/test_hermes_core.py`（10 项）：预算并发安全、退避区间、Retry-After 解析、停滞护栏状态机。
- 新增 `tests/test_readiness.py`（7 项）：无段阻断、停用 Agent、缺知识库、点数不足/偏低、缺 QC/Composer。
- 合计 48 项，`python -m pytest tests/ -q` 全部通过。

## 5. 运行方式（macOS）

```bash
cd server
python3.11 -m venv .venv          # 需要 Python 3.10+（代码使用 3.10+ 类型语法）
.venv/bin/pip install -r requirements.txt pytest httpx
.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8010
```

打开 `http://127.0.0.1:8010/admin`（后端已直接托管前端构建产物，无需单独启动前端；开发调试仍可用 `web/` 下 `pnpm dev`，代理 8010）。

> 注意：`server/data/`（数据库、知识库、向量索引）不包含在本包内，部署时需重新初始化或单独迁移。