yawan-workbench/源码交付说明-2026-08-28.md

雅文内容创造工作台源码交付说明

交付日期：2026-08-28
交付类型：当前磁盘源码快照
代码仓库状态：当前目录不是 Git 仓库，因此本包不包含提交历史与分支信息。

1. 打包范围

压缩包包含：

• server/app/：FastAPI、SQLModel、Agent Runtime、RAG、QC、计费和权限源码。
• server/scripts/：知识导入与维护脚本。
• server/tests/：31 项后端单元测试。
• server/requirements.txt：后端依赖声明。
• web/src/：React + TypeScript 前端源码。
• web/package.json、锁文件及 Vite/TypeScript 配置。
• 当前根目录设计文档、流程图、验收报告和启动脚本。
• 本交付说明。压缩包外随附同名 .sha256 文件，用于核对 ZIP 完整性。

压缩包明确排除：

• server/.venv/、web/node_modules/、web/dist/。
• server/data/ 下的数据库、知识库原文、向量索引、日志、备份与生成内容。
• .env、密钥、证书、Token 和 Provider 真实凭据。
• 旧版源码压缩包、缓存、__pycache__ 和测试临时文件。

2. 本轮已经修改

1. 为内容任务新增 objective 和 success_criteria，新任务必须同时填写唯一业务目标与验收标准。
2. SQLite 幂等迁移新增对应字段，历史任务保留并使用兼容默认值。
3. 任务契约贯穿 Coordinator 拆解、生产 Agent、四道 QC 和 Composer 总检。
4. CampaignRun.config_snapshot 冻结目标、验收标准和导图 SHA-256，减少配置漂移。
5. 任务页新增目标与验收标准输入和详情展示。
6. 增加 /api/health 公共健康探针，只返回服务状态与版本，不暴露业务数据。
7. 增加任务契约回归测试，后端测试从 30 项增至 31 项。
8. 更新《从 0 到 1 核心逻辑设计文档 v6》，补充任务契约章节。

3. 验证结果

检查	结果
后端 Python 编译	通过
后端单元测试	31 项全部通过
前端 TypeScript 检查	通过
前端 Vite 生产构建	通过，196 个模块
SQLite 迁移	通过，已确认 objective、success_criteria 两列存在
后端健康探针	GET /api/health 返回 status=ok
服务监听	前端 127.0.0.1:5173，后端 127.0.0.1:8010
页面级检查	管理端登录页可加载；当前浏览器没有有效登录会话，未继续提交业务表单

4. 仍未修改的问题

P0：正式企业部署前必须完成

1. Provider 密钥仍保存在本地 SQLite 字段中。 应改为 KMS、系统密钥环或独立 Secret Manager，数据库只保存密钥引用和掩码。
2. 业务文件仍是本地磁盘存储。 当前没有 COS/S3/MinIO 对象存储适配器、临时签名下载、生命周期、跨节点共享和灾备恢复实现。
3. 后台任务仍由进程内线程执行。 服务重启或多实例部署时缺少可靠队列、租约、重试退避、死信队列和 worker 心跳；应迁移到持久任务队列。
4. 租户边界尚未做数据库级强制。 当前主要依赖应用层过滤；正式多租户需要数据库约束、服务层统一策略与越权集成测试。
5. 备份恢复没有达到生产标准。 现有本地数据库和向量文件没有自动备份、恢复演练、RPO/RTO 指标和对象存储版本控制。

P1：影响稳定性和运营质量

1. 任务启动前准备度检查未完成。 仍需在运行前一次性检查模型、Provider、Agent、知识库索引、可用知识片段、QC/Composer 和点数余额，并在 UI 显示阻断原因。
2. 模型能力验证还不够强。 已有模型目录和能力状态，但仍需结构化输出、工具调用、上下文长度、超时与速率限制的自动化探测和定期复测。
3. 前端主要逻辑集中在 App.tsx。 文件体量较大，任务、Agent、知识库、记忆、访问控制、计费和 Trace 应拆成独立路由、页面模块、数据 hooks 与错误边界。
4. 后端路由主要集中在 main.py。 应按认证、任务、Agent、知识、计费、审计拆分 router/service/repository，降低单文件修改风险。
5. 部分读取异常被静默忽略。 QC/Composer 读取产物失败时存在 except Exception: pass，应写 Trace 并把段落标为明确失败，避免空内容进入下游。
6. 向量存储降级不可观测。 Chroma 写入失败会使用本地 fallback，但没有告警、健康状态和修复任务，运营人员难以发现降级。
7. 集成和端到端测试覆盖不足。 当前 31 项以单元测试为主，还需要认证、RBAC、任务完整生成、知识消费锁、计费扣点、服务重启恢复和浏览器流程测试。
8. 接口文档和版本管理不足。 服务仍标记 0.1.0-M1，需要正式 API 版本、迁移版本、变更日志和兼容策略。

P2：体验与长期演进

1. 增加任务级成本预算、预计 Token、预计耗时和知识可用量预估。
2. 增加人工确认项的逐条确认、修改和审计记录。
3. 增加知识库命中率、重复消费率、引用覆盖率和无依据内容率指标。
4. 增加 Trace 跨服务关联、指标看板、告警和审计导出。
5. 增加正式部署配置、容器镜像、反向代理、HTTPS、日志轮转和升级回滚流程。

5. 启动方式

首次部署先安装依赖：

cd server
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

cd ..\web
pnpm install --frozen-lockfile

本地开发可运行根目录的 启动工作台.bat，也可分别启动：

cd server
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8010

cd ..\web
pnpm dev --host 127.0.0.1 --port 5173

打开 http://127.0.0.1:5173/admin。业务数据库和知识资料不包含在源码包内，需要在目标环境重新初始化或单独通过受控迁移交付。