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

> 交付日期：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. 启动方式

首次部署先安装依赖：

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

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

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

```powershell
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`。业务数据库和知识资料不包含在源码包内，需要在目标环境重新初始化或单独通过受控迁移交付。