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）

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/（数据库、知识库、向量索引）不包含在本包内，部署时需重新初始化或单独迁移。