894 lines
35 KiB
Markdown
894 lines
35 KiB
Markdown
|
# 雅文内容创造工作台：核心逻辑、功能与业务总结
|
|||
|
|
|
|||
|
|
> 生成日期：2026-09-15
|
|||
|
|
> 依据源码：`server/app`、`web/src`、`scripts`、`docs` 及 2026-09-14 源码包说明整理。
|
|||
|
|
> 文档定位：面向产品、运营、测试、运维和二次开发人员，快速理解系统“解决什么业务问题、有哪些核心功能、数据如何流转、关键规则在哪里实现”。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 一句话定位
|
|||
|
|
|
|||
|
|
这是一套面向**私域训练营 / 直播内容生产 / 数字人 IP 运营**的 AI 内容工作台。系统把“资料库、Agent 方法论、数字人表达风格、内容任务流水线、人工审查、用量计费和微信触达”整合在一起，目标是让内容生产从“单次问 AI”变成：
|
|||
|
|
|
|||
|
|
> **有资料依据、有角色分工、有过程审查、有版本沉淀、有成本控制、可通过微信持续服务用户的工业化生产线。**
|
|||
|
|
|
|||
|
|
核心业务链路可以概括为：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
知识素材入库
|
|||
|
|
→ Agent / 技能 / 数字人配置
|
|||
|
|
→ 训练营导图或直播大纲拆解
|
|||
|
|
→ 多 Agent 分波次逐段生成
|
|||
|
|
→ 自动质检 + 人工审查 + 打回重做
|
|||
|
|
→ 成稿组合与 DOCX 交付
|
|||
|
|
→ 有效经验沉淀为记忆 / 技能 / 数字人规则
|
|||
|
|
→ 同一数字人通过微信 Bot 对外问答和私域服务
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 技术与运行架构
|
|||
|
|
|
|||
|
|
### 2.1 技术栈
|
|||
|
|
|
|||
|
|
| 层级 | 技术 | 主要文件 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 前端 | React 18、TypeScript、Vite、React Router、`@xyflow/react` | `web/src` |
|
|||
|
|
| 后端 API | FastAPI、SQLModel、Pydantic | `server/app/main.py`、`server/app/api` |
|
|||
|
|
| 数据库 | SQLite，业务元数据和状态全部落库 | `server/data/workspace.db` 或自定义数据目录 |
|
|||
|
|
| 向量检索 | Chroma / Qdrant 适配、Sentence-Transformers、BGE 中文向量 | `server/app/rag` |
|
|||
|
|
| 全文检索 | SQLite 中文 FTS 索引，向量 + FTS + RRF 融合 | `server/app/rag/hybrid.py` |
|
|||
|
|
| 精排 | Cross-Encoder Rerank，可选本地模型 | `server/app/rag/rerank.py` |
|
|||
|
|
| 大模型 | OpenAI 兼容接口：DeepSeek、MiMo、AI 聚合网等可配置 Provider | `server/app/llm.py` |
|
|||
|
|
| 微信接入 | Node.js 22 + `@wechatbot/wechatbot` iLink sidecar | `scripts/wechat_ilink_sidecar.mjs` |
|
|||
|
|
| 文档处理 | `python-docx`、自研解析、OCR 辅助 | `server/app/rag/parse.py`、`ocr.py`、`agents/composer.py` |
|
|||
|
|
|
|||
|
|
### 2.2 进程拓扑
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
浏览器
|
|||
|
|
→ React SPA（Vite 开发服务或 web/dist 静态文件）
|
|||
|
|
→ FastAPI /api
|
|||
|
|
├─ SQLite：用户、权限、知识库元数据、Agent、任务、运行、计费、日志
|
|||
|
|
├─ 文件系统：原始素材、产物、OCR、模型缓存、训练导图阅读缓存
|
|||
|
|
├─ RAG Worker：Embedding、向量检索、FTS、Rerank
|
|||
|
|
├─ LLM Provider：OpenAI 兼容大模型服务
|
|||
|
|
├─ 后台线程：任务执行、索引维护、告警、备份、进度事件
|
|||
|
|
└─ Node iLink Sidecar（127.0.0.1:8765）
|
|||
|
|
└─ 微信多账号扫码、消息收发、状态回调
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.3 环境和数据目录
|
|||
|
|
|
|||
|
|
配置位于 `server/app/config.py`：
|
|||
|
|
|
|||
|
|
- `YAWAN_ENV=dev`：使用 `server/data-dev`，开发环境不启动后台恢复和生产维护任务；
|
|||
|
|
- 默认或 `prod`：使用 `server/data`；
|
|||
|
|
- `YAWAN_DATA_DIR`：可把数据目录整体切到外接盘或持久化卷，必须是绝对路径；
|
|||
|
|
- 关键目录：
|
|||
|
|
- `kb/`：知识库源文件；
|
|||
|
|
- `chroma/`：向量索引；
|
|||
|
|
- `artifacts/`：段落产物、最终文稿；
|
|||
|
|
- `ocr/`：OCR 输出；
|
|||
|
|
- `models/`：本地模型；
|
|||
|
|
- `training-knowledge/`：训练营导图复用的资料阅读记录。
|
|||
|
|
|
|||
|
|
生产密钥不放在源码中。`.env.production.example` 只提供微信 sidecar 地址和兼容密钥模板。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 核心业务对象
|
|||
|
|
|
|||
|
|
主要数据表在 `server/app/models.py`。
|
|||
|
|
|
|||
|
|
### 3.1 资产配置类
|
|||
|
|
|
|||
|
|
| 对象 | 表 / 模型 | 业务含义 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 知识库 | `KnowledgeBase` | 内容生产的事实来源，包含索引状态、分段策略、可见性 |
|
|||
|
|
| 知识文件 | `KnowledgeFile` | 库内文件、分类、哈希、AI 分类状态、版本 |
|
|||
|
|
| 知识使用记录 | `KnowledgeUsage` | 某条知识片段被哪个 Agent、任务、段落消费或释放 |
|
|||
|
|
| 内容标签 | `ContentTag` | 心法、技法、产品、结构、表现等内容类型 |
|
|||
|
|
| Agent | `Agent` | 承担拆解、生产、质检、组合、客服等职责的智能体 |
|
|||
|
|
| 技能 | `AgentSkill` | 可复用的方法论 / 指令 / 操作步骤，可挂接到多个 Agent |
|
|||
|
|
| Prompt 模板 | `AgentPromptTemplate` | 角色、任务、约束、示例、输出格式的版本化模板 |
|
|||
|
|
| 数字人 | `DigitalHuman` | 从真实材料蒸馏出的人格、语气、销售逻辑和表达规则 |
|
|||
|
|
| 画布 | `Canvas` | Agent 节点、依赖边、波次、总监模式的编排模板 |
|
|||
|
|
| 记忆 | `Memory` / `PendingMemory` | Agent 的长期经验；待确认记忆必须人工审核后生效 |
|
|||
|
|
|
|||
|
|
### 3.2 任务生产类
|
|||
|
|
|
|||
|
|
| 对象 | 表 / 模型 | 业务含义 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 内容任务 | `Campaign` | 一次直播稿 / 训练营内容生产任务，保存导图、目标、画布快照、任务单和状态 |
|
|||
|
|
| 内容段 | `Segment` | 导图拆解后的最小生产单元，绑定 Agent、标签、时间范围、产物、质检和引用 |
|
|||
|
|
| 质检报告 | `QCReport` | 结构、内容、风格、跨段一致性等门禁结果 |
|
|||
|
|
| 成稿产物 | `Artifact` | 最终 DOCX、组合报告、运行快照和溯源信息 |
|
|||
|
|
| 任务运行 | `CampaignRun` | 一次任务执行实例，支持排队、运行、暂停、恢复、取消、失败恢复 |
|
|||
|
|
| 运行事件 | `RunEvent` | 任务运行过程中的 trace、span、工具调用、状态变化 |
|
|||
|
|
| Agent 会话 | `AgentSession` | 工具调用型 Agent 的多轮会话、工具状态、人工审批和恢复点 |
|
|||
|
|
| 任务队列 | `TaskQueueItem` | 幂等键、租约、重试、退避和死信状态 |
|
|||
|
|
|
|||
|
|
### 3.3 治理和运营类
|
|||
|
|
|
|||
|
|
| 对象 | 业务含义 |
|
|||
|
|
|---|---|
|
|||
|
|
| `AppUser` / `RoleDefinition` / `AuthSession` | 用户、自定义角色、登录会话 |
|
|||
|
|
| 各类 `*Grant` | Agent、技能、知识库、画布、数字人、记忆等资源授权 |
|
|||
|
|
| `ResourceRevision` / `ResourceFork` | 全局资源修改审核、删除审核、派生复制 |
|
|||
|
|
| `ModelProvider` / `ModelCatalog` | 模型服务商、模型能力、费率、启用状态 |
|
|||
|
|
| `LLMCall` | 每次大模型调用的耗时、Token、错误、哈希和计费状态 |
|
|||
|
|
| `UsageEvent` | LLM、Embedding、OCR、Rerank、导出等追加式用量事件 |
|
|||
|
|
| `PointAccount` / `PointTransaction` | 点数余额和不可变流水 |
|
|||
|
|
| `UsageQuota` | 用户周期配额、并发、存储和超限策略 |
|
|||
|
|
| `AuditLog` / `SystemLog` | 用户操作审计和系统运行日志 |
|
|||
|
|
| `Notification` | 失败、待审查、记忆建议、完成等通知 |
|
|||
|
|
| `WeChatBotAccount` | 微信账号、绑定 Agent、二维码、密钥哈希和连接状态 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 功能版图
|
|||
|
|
|
|||
|
|
前端路由和菜单由权限动态生成，主要页面如下。
|
|||
|
|
|
|||
|
|
| 模块 | 前端页面 | 核心能力 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 总览 | `OverviewPage` | 系统状态、待处理事项、快捷入口 |
|
|||
|
|
| 内容任务 | `TaskListPage`、`TaskDetailPage`、`TasksPage` | 导图拆解、逐段生成、审查、打回、组合、交付 |
|
|||
|
|
| 训练营导图 | `TrainingMapPage`、Coverage、Timing、Categories | 主题规划、资料阅读、天数评估、每日导图、证据和覆盖率 |
|
|||
|
|
| 运行记录 | `RunsPage` | 查看运行状态、Trace、工具审批、暂停、恢复和失败 |
|
|||
|
|
| Agent 与技能 | `AgentWorkbench`、`AgentsPage`、`SkillsPage`、`MemoriesPage` | Agent、技能、记忆、工具、模型配置 |
|
|||
|
|
| 数字人 | `DigitalHumansPage`、`PersonaProfile` | 材料蒸馏、测试写作、反馈、再蒸馏、审核和微信绑定 |
|
|||
|
|
| 画布编排 | `CanvasPage` | 用 XYFlow 配置 Agent 节点、依赖边、波次和总监 |
|
|||
|
|
| 知识库 | `KnowledgePage`、`KBsPage`、TagsPage | 上传、分类、索引、检索测试、消费记录、文件夹导入 |
|
|||
|
|
| 模型管理 | `ModelsPage` | Provider、模型目录、默认模型、连通性测试、模型发现 |
|
|||
|
|
| 用量分析 | `UsagePage` | 用量、费用、点数、配额、结算和调整 |
|
|||
|
|
| 运营看板 | `OpsPage` | 队列、死信、备份、性能、告警和系统健康 |
|
|||
|
|
| 访问控制 | `AccessPage` | 用户、角色、资源授权、全局发布和版本审核 |
|
|||
|
|
| 日志 | `AuditLogsPage`、`SystemLogsPage` | 操作审计、系统错误、HTTP 和 Trace 查询 |
|
|||
|
|
| 功能开关 | `FeatureFlagsPage` | 控制部分功能入口和实验能力 |
|
|||
|
|
| 用户手册 | `UserManualPage` | 系统内置操作说明 |
|
|||
|
|
|
|||
|
|
后端 `main.py` 当前约有 227 个 API 路由，覆盖认证、资源管理、知识库、Agent、任务、训练营、计费、微信、日志、通知和运维。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 核心业务流程一：知识库建设与证据化检索
|
|||
|
|
|
|||
|
|
知识库是全系统的事实边界。生产 Agent 没有知识库时不允许生成内容，目的是防止凭空编造。
|
|||
|
|
|
|||
|
|
### 5.1 入库流程
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
上传文件 / 文件夹
|
|||
|
|
→ 病毒/异常文件隔离（quarantine）
|
|||
|
|
→ 文件哈希与重复文件判断
|
|||
|
|
→ 解析 doc/docx/pdf/txt/md/srt/表格等素材
|
|||
|
|
→ 文本清洗和分块
|
|||
|
|
→ Embedding 向量化
|
|||
|
|
→ 写入向量库
|
|||
|
|
→ 建立 / 更新中文 FTS 索引
|
|||
|
|
→ 同步文件数、chunk 数、索引版本和业务状态
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
关键实现：
|
|||
|
|
|
|||
|
|
- 解析：`server/app/rag/parse.py`；
|
|||
|
|
- 分块：`server/app/rag/chunk.py`；
|
|||
|
|
- 向量化：`server/app/rag/embed.py`；
|
|||
|
|
- 向量存储：`store.py`、`qdrant_store.py`；
|
|||
|
|
- 索引管道：`pipeline.py`；
|
|||
|
|
- FTS 和融合：`hybrid.py`；
|
|||
|
|
- 大文件支持分块上传：`/api/uploads/init`、`/chunk/{index}`、`/finish`；
|
|||
|
|
- 文件夹导入支持进度查询和断点恢复。
|
|||
|
|
|
|||
|
|
知识库支持：
|
|||
|
|
|
|||
|
|
- 自动分段和按标题分段；
|
|||
|
|
- 文件级 / 分类级范围过滤；
|
|||
|
|
- AI 分类建议，人工确认后生效；
|
|||
|
|
- 内容哈希和文件版本；
|
|||
|
|
- 文件删除、重建索引、分类隔离；
|
|||
|
|
- 知识片段消费、释放和复用记录。
|
|||
|
|
|
|||
|
|
### 5.2 混合检索流程
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
用户/Agent 查询
|
|||
|
|
→ 权限与组织校验
|
|||
|
|
→ 知识库、分类、文件白名单、隔离文件过滤
|
|||
|
|
→ 查询 Embedding（有查询缓存）
|
|||
|
|
→ 向量召回
|
|||
|
|
→ 中文 FTS 关键词召回
|
|||
|
|
→ RRF 融合
|
|||
|
|
→ 去重、多样性和主题覆盖
|
|||
|
|
→ Cross-Encoder 精排
|
|||
|
|
→ 父级上下文扩展
|
|||
|
|
→ 按 Token 预算返回带来源的证据片段
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
关键设计：
|
|||
|
|
|
|||
|
|
1. **权限签名参与缓存键**：授权变化后不会复用旧候选池；
|
|||
|
|
2. **索引版本参与缓存键**：知识更新后自动失效；
|
|||
|
|
3. **查询向量与候选池缓存分离**：改变 top-k 或分类不必总是重算向量；
|
|||
|
|
4. **FTS 未就绪时先向量降级**，索引预热后自动切换 hybrid；
|
|||
|
|
5. **RAG 运行在独立 worker pool**，避免 Embedding 大模型占满 API 进程；
|
|||
|
|
6. **检索结果带文件、chunk、分类等元数据**，供正文引用和溯源；
|
|||
|
|
7. **Embedding 用量用独立短事务记录**，计量失败不阻断检索。
|
|||
|
|
|
|||
|
|
`docs/知识图谱检索升级方案-20260914.md` 是下一阶段升级方案。当前代码的主线仍是“向量 + 中文 FTS + RRF + Cross-Encoder”，不是已经完整落地的知识图谱系统。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 核心业务流程二：Agent、技能、记忆与数字人
|
|||
|
|
|
|||
|
|
### 6.1 Agent 分工
|
|||
|
|
|
|||
|
|
系统预置和支持的角色包括：
|
|||
|
|
|
|||
|
|
| 角色 | 职责 |
|
|||
|
|
|---|---|
|
|||
|
|
| `coordinator` 任务拆解 | 将导图 / 大纲编译为可执行内容段任务单 |
|
|||
|
|
| `production` 内容生产 | 绑定知识和数字人，生成可直接口播的正文 |
|
|||
|
|
| `qc` 质量检查 | 检查结构、事实、风格、口播感、规则符合度 |
|
|||
|
|
| `composer` 成稿组合 | 只组合人工通过的段落，并做全文一致性检查 |
|
|||
|
|
| `service` 服务 / 客服 | 用于微信等外部会话入口，回答用户问题 |
|
|||
|
|
|
|||
|
|
Agent 可配置：
|
|||
|
|
|
|||
|
|
- 角色、描述、内容标签；
|
|||
|
|
- 知识库和知识库分类；
|
|||
|
|
- 技能和融合 Agent；
|
|||
|
|
- 可用工具；
|
|||
|
|
- Provider、模型和 Prompt 模板；
|
|||
|
|
- 自定义规则和规则版本；
|
|||
|
|
- 数字人身份；
|
|||
|
|
- 发布状态、可见性和资源授权；
|
|||
|
|
- 发布时生成运行快照。
|
|||
|
|
|
|||
|
|
### 6.2 运行快照与可复现性
|
|||
|
|
|
|||
|
|
任务拆解时，系统会冻结参与 Agent 的：
|
|||
|
|
|
|||
|
|
- 规则；
|
|||
|
|
- 技能；
|
|||
|
|
- 知识库范围；
|
|||
|
|
- 模型 Provider 和模型名；
|
|||
|
|
- Provider 指纹；
|
|||
|
|
- 数字人 / 人格配置；
|
|||
|
|
- 融合 Agent 配置。
|
|||
|
|
|
|||
|
|
后续即使管理员修改 Agent，旧任务仍优先使用任务创建时的快照。若快照中的 Provider 被删除、停用、模型变化或配置指纹漂移，相关段落会停止并给出可操作错误，避免同一任务前后用不同规则生成。
|
|||
|
|
|
|||
|
|
### 6.3 技能和记忆
|
|||
|
|
|
|||
|
|
- **技能**偏“可复用方法”：例如某类内容如何开场、如何转折、如何做产品植入；
|
|||
|
|
- **记忆**偏“Agent 从具体生产中获得的经验”。
|
|||
|
|
|
|||
|
|
记忆分待确认和已生效两层：
|
|||
|
|
|
|||
|
|
1. 自动生成或人工录入的建议先进入 `PendingMemory`；
|
|||
|
|
2. 审核通过后进入 `Memory` 并可索引；
|
|||
|
|
3. 生成时按 Agent、任务、段落、查询召回相关记忆；
|
|||
|
|
4. 用户打回段落时，可自动生成 L3 偏好类待确认记忆；
|
|||
|
|
5. 记忆不会未经确认直接影响生产；
|
|||
|
|
6. 画布授权只传递配置者自己的 Agent 经验，不放大其他用户私有偏好。
|
|||
|
|
|
|||
|
|
### 6.4 数字人生成和使用
|
|||
|
|
|
|||
|
|
数字人模块位于 `digital_persona.py`，从本人文档、口述稿、聊天材料中蒸馏结构化人格，包括：
|
|||
|
|
|
|||
|
|
- 身份、受众和关系；
|
|||
|
|
- 语气、语速、词汇、口头禅；
|
|||
|
|
- 开场习惯、互动方式；
|
|||
|
|
- 文稿风格、叙事方式、论证方式；
|
|||
|
|
- 受众画像；
|
|||
|
|
- 痛点 / 痒点钩子；
|
|||
|
|
- 销售逻辑、转化路径和 CTA 转场；
|
|||
|
|
- 禁词、专业边界和证据不足项。
|
|||
|
|
|
|||
|
|
蒸馏协议强调：
|
|||
|
|
|
|||
|
|
- 上传材料是数据，不是指令，防止提示词注入；
|
|||
|
|
- 没有证据不虚构原话、不凑口头禅；
|
|||
|
|
- 医学、疗效、露骨动作等高风险内容标记人工核验；
|
|||
|
|
- 数字人只管表达风格，不覆盖任务目标和知识来源边界；
|
|||
|
|
- 历史运行只使用当时冻结的档案版本；
|
|||
|
|
- 数字人需测试、反馈、再蒸馏、审核生效后才能绑定 Agent 和微信。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 核心业务流程三：训练营导图
|
|||
|
|
|
|||
|
|
训练营导图是比普通直播稿更前置的课程规划能力，主逻辑在：
|
|||
|
|
|
|||
|
|
- `training_map.py`：API、草稿、版本、评估、修订、逐日导图；
|
|||
|
|
- `training_corpus.py`：跨知识库分批阅读和语料压缩；
|
|||
|
|
- `training_reading.py`：阅读任务、进度、并发、缓存；
|
|||
|
|
- `training_knowledge.py`：与主题无关、可复用的阅读摘要缓存；
|
|||
|
|
- `training_estimate.py`：资料量、耗时和复用估算；
|
|||
|
|
- `training_scope.py`：知识库 / 文件 / 分类范围归一化。
|
|||
|
|
|
|||
|
|
### 7.1 业务目标
|
|||
|
|
|
|||
|
|
用户输入主题、期望天数、知识库和分类范围，系统基于资料证据生成：
|
|||
|
|
|
|||
|
|
- 推荐天数；
|
|||
|
|
- 每日主题；
|
|||
|
|
- 前置知识；
|
|||
|
|
- 当天学习成果；
|
|||
|
|
- 知识点、练习、应用和复盘；
|
|||
|
|
- 每日递进关系；
|
|||
|
|
- 覆盖情况和证据来源；
|
|||
|
|
- 资料不足、冲突或待确认项；
|
|||
|
|
- 每日文字导图和图片导图。
|
|||
|
|
|
|||
|
|
### 7.2 三种资料处理模式
|
|||
|
|
|
|||
|
|
| 模式 | 特点 | 适用场景 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 复用已读资料 | 按输入内容哈希复用已有高质量摘要，成本低、速度快 | 日常迭代，推荐 |
|
|||
|
|
| 重新阅读全文 | 重新分批阅读所选资料，更慢、更贵 | 资料变化大或需要刷新结论 |
|
|||
|
|
| 快速相关检索 | 不通读全库，只按主题检索相关片段 | 快速出初稿或主题明确时 |
|
|||
|
|
|
|||
|
|
### 7.3 关键约束
|
|||
|
|
|
|||
|
|
- 所有保留节点必须能追溯到知识库证据；
|
|||
|
|
- 资料里“提到”某个议题，不代表必须升级成必修课；
|
|||
|
|
- 不因凑天数增加题外节点；
|
|||
|
|
- 每天的 outcome 必须能成为后一天真正依赖的输入；
|
|||
|
|
- 评估、重评和细化共用课程范围，防止主题漂移；
|
|||
|
|
- 方案和每日导图都有版本号，更新需带版本，防止并发覆盖；
|
|||
|
|
- 长任务使用后台运行、队列记录、取消标记和阶段性结果；
|
|||
|
|
- 阅读缓存按组织、知识库、原始 chunk 指纹和策略版本隔离。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 核心业务流程四：内容任务流水线
|
|||
|
|
|
|||
|
|
内容任务是系统最核心的生产线。
|
|||
|
|
|
|||
|
|
### 8.1 创建任务
|
|||
|
|
|
|||
|
|
输入包括：
|
|||
|
|
|
|||
|
|
- 任务名称；
|
|||
|
|
- 导图 / 大纲文本；
|
|||
|
|
- 业务目标和验收标准；
|
|||
|
|
- 直播总时长；
|
|||
|
|
- 画布模板；
|
|||
|
|
- 质检模式；
|
|||
|
|
- 可选的上一任务；
|
|||
|
|
- 已确认训练营导图及对应天数。
|
|||
|
|
|
|||
|
|
系统要求任务名、导图文本和画布模板齐备后才能创建并拆解。
|
|||
|
|
|
|||
|
|
### 8.2 主控拆解
|
|||
|
|
|
|||
|
|
`agents/coordinator.py` 调用 `coordinator` Agent，把导图编译成结构化 `Segment` 列表。拆解规则包括：
|
|||
|
|
|
|||
|
|
- 忠实转录导图节点，不补写不存在的主题、产品或日期；
|
|||
|
|
- 读不准的内容进入 `pending_confirms`，不猜测；
|
|||
|
|
- 每段绑定内容标签、标题、时间范围、导图原文和产品引用；
|
|||
|
|
- 所有时间段总和必须等于直播总时长；
|
|||
|
|
- 保留节点顺序和多同类节点，不随意合并近似主题；
|
|||
|
|
- 形成“基础 → 练习 → 应用 → 复盘 / 收束”的递进；
|
|||
|
|
- 输出任务单、待确认项和说明。
|
|||
|
|
|
|||
|
|
用户可以带修改意见重新拆解。
|
|||
|
|
|
|||
|
|
### 8.3 画布分波次执行
|
|||
|
|
|
|||
|
|
普通模式按段落顺序执行；画布模式根据节点依赖边计算拓扑波次：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
第一波无上游节点
|
|||
|
|
→ 生成并提交锚点卡
|
|||
|
|
第二波读取上游锚点卡
|
|||
|
|
→ 生成、质检、审查
|
|||
|
|
后续波次继续承接
|
|||
|
|
→ 画布外兜底段最后执行
|
|||
|
|
→ 全部人工通过后组合
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
实现位于 `agents/runner.py` 的 `run_campaign()`。每个波次内部串行，原因是：
|
|||
|
|
|
|||
|
|
- 下游需要上游锚点卡；
|
|||
|
|
- SQLite 单写入者不适合大量并发写；
|
|||
|
|
- 这样能降低知识片段预留、产物写入和计费事务冲突。
|
|||
|
|
|
|||
|
|
### 8.4 单段生成逻辑
|
|||
|
|
|
|||
|
|
`execute_segment()` 是段落生产核心，主要步骤：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
校验 Agent / 模型 / 快照 / 知识库
|
|||
|
|
→ 召回可用记忆
|
|||
|
|
→ 注入数字人人格
|
|||
|
|
→ 组装融合 Agent 指导
|
|||
|
|
→ 读取上一段结尾和上游锚点卡
|
|||
|
|
→ 根据标题、标签、产品和上下文构造 RAG 查询
|
|||
|
|
→ 检索并预留知识片段
|
|||
|
|
→ 调用生产 LLM
|
|||
|
|
→ 规范化口播正文
|
|||
|
|
→ 生成锚点卡
|
|||
|
|
→ 写段落产物文件
|
|||
|
|
→ 自动质检
|
|||
|
|
→ 必要时全局总监审核
|
|||
|
|
→ 成功后消费知识片段；失败则释放预留
|
|||
|
|
→ 写运行事件、通知、用量和段落状态
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
锚点卡承担跨段衔接作用，通常包含标题、正文摘要、结尾钩子、产品 / 话题承诺、下一段需要承接的信息。
|
|||
|
|
|
|||
|
|
### 8.5 质检与人工门禁
|
|||
|
|
|
|||
|
|
质检能力在 `agents/qc.py`，常见门禁包括：
|
|||
|
|
|
|||
|
|
- 是否围绕本段主题；
|
|||
|
|
- 是否完成任务目标和验收标准；
|
|||
|
|
- 是否有提纲残留、结构残留或机器腔；
|
|||
|
|
- 时间范围、标题和正文是否一致；
|
|||
|
|
- 口播语言是否自然；
|
|||
|
|
- 是否与数字人语气一致；
|
|||
|
|
- 是否编造知识库没有的事实；
|
|||
|
|
- 产品、价格、疗效、承诺等高风险表述是否越界；
|
|||
|
|
- 段落钩子是否被下一段兑现。
|
|||
|
|
|
|||
|
|
人工审查动作：
|
|||
|
|
|
|||
|
|
- **通过**：段落进入 `approved`，允许组合；
|
|||
|
|
- **打回**：进入 `rework`，用户意见注入下一轮 Prompt，并可能生成记忆建议；
|
|||
|
|
- **跳过**：进入 `skipped`，不参与最终成稿。
|
|||
|
|
|
|||
|
|
失败修复支持重试、换模型、改规则、改任务描述、跳过、停用 Agent 等。
|
|||
|
|
|
|||
|
|
### 8.6 全局总监
|
|||
|
|
|
|||
|
|
画布可配置总监 Agent 和模式：
|
|||
|
|
|
|||
|
|
| 模式 | 行为 |
|
|||
|
|
|---|---|
|
|||
|
|
| `always` | 每段生成后都审 |
|
|||
|
|
| `on_drift` | 默认模式，仅在质检失败、多轮重做等可疑场景审，节省点数 |
|
|||
|
|
| `off` | 关闭 |
|
|||
|
|
|
|||
|
|
总监不写正文，只判断是否跑偏并给出拉回指导。为避免无限烧点数，跑偏后最多引导重做一次；总监服务异常不阻断主流程。
|
|||
|
|
|
|||
|
|
### 8.7 暂停、恢复、取消和重启恢复
|
|||
|
|
|
|||
|
|
- 用户可取消、暂停、恢复运行；
|
|||
|
|
- 执行器在段落和波次边界检查标记；
|
|||
|
|
- 暂停会保留 checkpoint；
|
|||
|
|
- 服务重启时，`running/queued` 的任务会恢复为可调度状态；
|
|||
|
|
- 中断的 AgentSession 标为 `interrupted`；
|
|||
|
|
- 已写好的正文不会因重启被盲目覆盖；
|
|||
|
|
- 启动后自动重新调度可恢复任务。
|
|||
|
|
|
|||
|
|
进度同时通过：
|
|||
|
|
|
|||
|
|
- SSE：`/api/events/progress`；
|
|||
|
|
- 轮询备用：`/api/events/progress-poll`。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 成稿组合与交付
|
|||
|
|
|
|||
|
|
`agents/composer.py` 负责最终文稿。
|
|||
|
|
|
|||
|
|
核心规则：
|
|||
|
|
|
|||
|
|
1. **只组合人工通过的内容段**；
|
|||
|
|
2. 跳过段、待重做段和失败段不能进入正式交付；
|
|||
|
|
3. 读取任务待确认项和说明；
|
|||
|
|
4. 做跨段一致性总检：
|
|||
|
|
- 跨段矛盾；
|
|||
|
|
- 回指断裂；
|
|||
|
|
- 时间线一致性；
|
|||
|
|
- 情绪曲线；
|
|||
|
|
- 钩子兑现；
|
|||
|
|
5. 若总检失败，在成稿说明中列出具体段落和建议，要求回到对应段处理；
|
|||
|
|
6. 生成 DOCX，支持彩色标记：
|
|||
|
|
- 黑色：正文；
|
|||
|
|
- 红色：产品；
|
|||
|
|
- 紫色：金句；
|
|||
|
|
- 绿色：运营；
|
|||
|
|
- 灰色：表演提示；
|
|||
|
|
- 蓝色：修改建议；
|
|||
|
|
7. Artifact 保存 DOCX 路径、组合报告、Trace、运行快照和可见性；
|
|||
|
|
8. 前端可预览和下载。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. Agent Runtime 与工具体系
|
|||
|
|
|
|||
|
|
`agents/runtime.py` 提供通用工具调用循环，`runner.py` 则承载内容任务的强约束流水线。
|
|||
|
|
|
|||
|
|
Runtime 特性：
|
|||
|
|
|
|||
|
|
- 每个会话有 `turn` 和 `max_turns`，防止无限循环；
|
|||
|
|
- 消息超长时裁剪，保留必要上下文；
|
|||
|
|
- 支持工具 JSON Schema 定义、参数解析和工具结果回传；
|
|||
|
|
- 工具执行前后有输入 / 输出护栏；
|
|||
|
|
- 需要人工批准的工具会让会话进入 `waiting_approval`；
|
|||
|
|
- 可从可恢复会话继续，而不是重新开新会话；
|
|||
|
|
- 记录 trace、span、工具名、状态和错误；
|
|||
|
|
- 支持预算闸门和运行级并发控制。
|
|||
|
|
|
|||
|
|
典型工具包括：
|
|||
|
|
|
|||
|
|
- 知识库检索；
|
|||
|
|
- 读取上游锚点；
|
|||
|
|
- 读取已通过段落；
|
|||
|
|
- 读取 Agent 记忆；
|
|||
|
|
- 融合 Agent 协作；
|
|||
|
|
- Web 搜索 / 网页采集等扩展工具。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11. 微信私域 Bot 闭环
|
|||
|
|
|
|||
|
|
微信侧只负责消息通道，业务推理在主系统内完成。
|
|||
|
|
|
|||
|
|
### 11.1 多账号连接
|
|||
|
|
|
|||
|
|
生产推荐使用官方 / CoreSpeed iLink sidecar：
|
|||
|
|
|
|||
|
|
- 文件：`scripts/wechat_ilink_sidecar.mjs`；
|
|||
|
|
- 默认监听：`127.0.0.1:8765`；
|
|||
|
|
- 每个微信账号独立密钥；
|
|||
|
|
- 每个账号独立本地凭据目录；
|
|||
|
|
- 后端保存密钥哈希和提示，不向前端返回明文密钥；
|
|||
|
|
- sidecar 通过回调同步二维码、扫码、连接、断开和错误状态。
|
|||
|
|
|
|||
|
|
连接要求：
|
|||
|
|
|
|||
|
|
1. 选择当前账号有权使用的 `production` 或 `service` Agent；
|
|||
|
|
2. Agent 必须绑定已审核生效的数字人；
|
|||
|
|
3. 后端创建账号和独立 secret；
|
|||
|
|
4. sidecar 使用 secret 发起扫码连接；
|
|||
|
|
5. 页面展示二维码并轮询连接状态。
|
|||
|
|
|
|||
|
|
### 11.2 消息处理
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
微信收到文本
|
|||
|
|
→ sidecar 生成 timestamp + HMAC-SHA256 签名
|
|||
|
|
→ POST /api/wechat/bot/reply
|
|||
|
|
→ 后端验签、检查账号和 Agent 权限
|
|||
|
|
→ 按 conversation_id/message_id 幂等处理
|
|||
|
|
→ 读取历史会话
|
|||
|
|
→ 注入数字人规则和技能
|
|||
|
|
→ 检索 Agent 绑定知识库 / 分类的相关片段
|
|||
|
|
→ 调用 LLM
|
|||
|
|
→ 保存会话和 trace
|
|||
|
|
→ 返回 reply 给 sidecar
|
|||
|
|
→ sidecar 发回微信
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
重要规则：
|
|||
|
|
|
|||
|
|
- 同一 `message_id` 重试直接返回上次回复，不重复扣费；
|
|||
|
|
- 会话只保留系统提示和最近对话，防止无限增长；
|
|||
|
|
- 每轮最多注入限定长度的知识片段；
|
|||
|
|
- 知识库检索失败时记录日志，但继续普通对话，避免微信卡死；
|
|||
|
|
- Bot 调用同样计入用量和点数；
|
|||
|
|
- 旧版 `X-WeChat-Bot-Secret` 兼容，新接入使用 HMAC。
|
|||
|
|
|
|||
|
|
`scripts/wechat_bot_adapter.mjs` 是旧 Wechaty / Web 协议开发示例，只适合测试，不作为生产首选。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12. 模型、容错、计费与配额
|
|||
|
|
|
|||
|
|
### 12.1 多模型 Provider
|
|||
|
|
|
|||
|
|
模型配置支持：
|
|||
|
|
|
|||
|
|
- 多个 OpenAI 兼容 Provider；
|
|||
|
|
- 模型列表发现和手工配置；
|
|||
|
|
- 默认模型；
|
|||
|
|
- 模型能力目录；
|
|||
|
|
- 输入 / 输出费率；
|
|||
|
|
- 启停、连通性测试；
|
|||
|
|
- Agent 级独立模型选择。
|
|||
|
|
|
|||
|
|
`llm.py` 对错误进行中文可读化分类：
|
|||
|
|
|
|||
|
|
- 限流；
|
|||
|
|
- 认证失败；
|
|||
|
|
- 模型不存在；
|
|||
|
|
- 超时；
|
|||
|
|
- 连接失败；
|
|||
|
|
- 余额不足；
|
|||
|
|
- 其他错误。
|
|||
|
|
|
|||
|
|
可重试错误会自动退避重试；认证、限流、连接、超时、模型不存在、余额不足等可尝试切换到其他启用 Provider。模型不存在时可改用目标 Provider 的默认模型。
|
|||
|
|
|
|||
|
|
### 12.2 调用记录
|
|||
|
|
|
|||
|
|
每次 LLM 调用记录：
|
|||
|
|
|
|||
|
|
- Provider、模型；
|
|||
|
|
- Trace / Span；
|
|||
|
|
- 任务、段落、Agent；
|
|||
|
|
- 尝试次数；
|
|||
|
|
- Prompt / 输出哈希；
|
|||
|
|
- 输入输出 Token；
|
|||
|
|
- 耗时；
|
|||
|
|
- 错误和拒答；
|
|||
|
|
- 计费状态。
|
|||
|
|
|
|||
|
|
系统保存哈希而非完整 Prompt，便于排查同时降低敏感内容泄漏风险。
|
|||
|
|
|
|||
|
|
### 12.3 点数和配额
|
|||
|
|
|
|||
|
|
计费代码在 `billing.py`、`points_guard.py`、`cost_estimate.py`。
|
|||
|
|
|
|||
|
|
- 换算：`10 点数 = 1 Token`；
|
|||
|
|
- 每次调用产生不可变 `UsageEvent`；
|
|||
|
|
- 点数流水 `PointTransaction` 只追加，不直接覆盖历史；
|
|||
|
|
- 支持 LLM、Embedding、OCR、Rerank、导出、存储等服务类型；
|
|||
|
|
- 支持用户日 / 月配额、金额上限、存储和并发限制；
|
|||
|
|
- 超限策略包括提醒、软限制、硬限制。
|
|||
|
|
|
|||
|
|
任务启动前：
|
|||
|
|
|
|||
|
|
1. 根据历史均值或保守默认值估算 Token、金额、点数和耗时；
|
|||
|
|
2. 点数余额必须覆盖预估成本加 20% 缓冲；
|
|||
|
|
3. 不足时阻断启动并提示充值。
|
|||
|
|
|
|||
|
|
任务运行中：
|
|||
|
|
|
|||
|
|
- 每次模型调用消耗点数；
|
|||
|
|
- Provider 返回余额、鉴权等不可自愈错误时立即熔断；
|
|||
|
|
- 避免“已经没点数还继续跑”的浪费。
|
|||
|
|
|
|||
|
|
管理员可按快捷档位发放点数：1 千万、1 亿、10 亿，也可手工调整。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 13. 权限、租户隔离与资源治理
|
|||
|
|
|
|||
|
|
### 13.1 登录和角色
|
|||
|
|
|
|||
|
|
认证位于 `auth.py`：
|
|||
|
|
|
|||
|
|
- 首次使用支持 bootstrap 管理员；
|
|||
|
|
- 密码使用 PBKDF2-SHA256，随机 salt，高迭代次数；
|
|||
|
|
- 登录后发放不透明会话 Token；
|
|||
|
|
- 数据库保存 Token 哈希；
|
|||
|
|
- 支持会话过期、撤销和最近访问时间；
|
|||
|
|
- 内置角色包括 admin、editor、reviewer、viewer；
|
|||
|
|
- 支持自定义角色和细粒度权限；
|
|||
|
|
- 旧权限名会自动扩展为新权限集合，避免升级丢权限。
|
|||
|
|
|
|||
|
|
### 13.2 三层权限控制
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
前端菜单隐藏
|
|||
|
|
→ 前端路由 FeatureGate 拦截
|
|||
|
|
→ 后端中间件和每个资源操作再次校验
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
仅隐藏菜单不等于安全，后端会根据 Method + Path 推导所需权限。
|
|||
|
|
|
|||
|
|
### 13.3 资源可见性
|
|||
|
|
|
|||
|
|
资源支持：
|
|||
|
|
|
|||
|
|
- `private`：私有；
|
|||
|
|
- `shared`：按用户 / 权限授权共享；
|
|||
|
|
- `global`：全局可用，通常需管理员审核发布。
|
|||
|
|
|
|||
|
|
资源类型包括：
|
|||
|
|
|
|||
|
|
- Agent；
|
|||
|
|
- 技能；
|
|||
|
|
- 知识库；
|
|||
|
|
- 数字人；
|
|||
|
|
- 画布；
|
|||
|
|
- 记忆；
|
|||
|
|
- Prompt 模板等。
|
|||
|
|
|
|||
|
|
授权权限通常区分：read、use、manage、export。画布可以连带授权节点 Agent 所需的知识库和记忆，但只开放读取 / 使用，不放大编辑、删除、导出权限。
|
|||
|
|
|
|||
|
|
### 13.4 全局发布、Fork 和修订审核
|
|||
|
|
|
|||
|
|
普通用户修改或删除全局资源时，不一定直接覆盖原资源，而是生成 `ResourceRevision`：
|
|||
|
|
|
|||
|
|
- 编辑可走审核；
|
|||
|
|
- 删除可走审核；
|
|||
|
|
- 管理员可批准或拒绝；
|
|||
|
|
- 用户可从共享资源 Fork 出私有副本；
|
|||
|
|
- `ResourceFork` 保存来源版本和指纹。
|
|||
|
|
|
|||
|
|
这使系统既能沉淀公共资产，又能避免用户误改影响所有任务。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 14. 运营、可靠性与可观测性
|
|||
|
|
|
|||
|
|
### 14.1 健康检查和看板
|
|||
|
|
|
|||
|
|
主要接口：
|
|||
|
|
|
|||
|
|
- `/api/health`：基础健康；
|
|||
|
|
- `/api/system/status`：系统状态和环境；
|
|||
|
|
- `/api/ops/dashboard`：队列、备份、告警、资源状态；
|
|||
|
|
- `/api/ops/performance`：HTTP、RAG、Embedding 等性能指标。
|
|||
|
|
|
|||
|
|
### 14.2 持久任务队列
|
|||
|
|
|
|||
|
|
`task_queue.py` 提供：
|
|||
|
|
|
|||
|
|
- 幂等 `task_key`；
|
|||
|
|
- pending / running / done / dead / cancelled；
|
|||
|
|
- 租约和心跳；
|
|||
|
|
- worker 死亡后孤儿任务回收；
|
|||
|
|
- 最大尝试次数；
|
|||
|
|
- 指数抖动退避；
|
|||
|
|
- 死信手动重放。
|
|||
|
|
|
|||
|
|
需要注意：内容生成、上传和部分训练营任务仍大量依赖当前进程内线程与进度总线。队列已经具备可靠任务表能力，但外部 Worker 完全接管前，还需要确保唯一执行模式、持久进度游标和所有操作幂等。
|
|||
|
|
|
|||
|
|
### 14.3 备份
|
|||
|
|
|
|||
|
|
`backup.py` 在生产启动时备份一次，之后每 6 小时自动备份，并做恢复演练检查。运营接口支持：
|
|||
|
|
|
|||
|
|
- 查看备份状态；
|
|||
|
|
- 立即备份；
|
|||
|
|
- 校验最近备份；
|
|||
|
|
- 恢复演练报告；
|
|||
|
|
- 自动清理旧备份。
|
|||
|
|
|
|||
|
|
### 14.4 日志和 Trace
|
|||
|
|
|
|||
|
|
- `AuditLog`：用户行为审计；
|
|||
|
|
- `SystemLog`：系统、任务、RAG、模型、HTTP 错误；
|
|||
|
|
- `RunEvent`：任务内过程事件；
|
|||
|
|
- `LLMCall`：模型调用详情；
|
|||
|
|
- Trace 可串联一次任务中的多个 Agent、工具和模型调用；
|
|||
|
|
- 前端运行记录页可按任务、状态和 Trace 查询。
|
|||
|
|
|
|||
|
|
### 14.5 RAG 性能治理
|
|||
|
|
|
|||
|
|
系统已实现或记录了以下优化：
|
|||
|
|
|
|||
|
|
- Embedding 模型预热和常驻；
|
|||
|
|
- 查询向量 LRU 缓存；
|
|||
|
|
- 候选池缓存；
|
|||
|
|
- FTS mmap / 共享连接 / 页缓存；
|
|||
|
|
- 固定 4 个召回 Worker，避免高并发磁盘争用；
|
|||
|
|
- RAG worker IPC 指标回传；
|
|||
|
|
- P50 / P95 延迟分位；
|
|||
|
|
- 避免热路径 `collection.count()` 等慢操作；
|
|||
|
|
- 大 FTS 索引预热和原子替换；
|
|||
|
|
- 非关键计量写失败不阻断检索。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 15. 端到端业务示例
|
|||
|
|
|
|||
|
|
以“训练营第 5 天直播稿”为例：
|
|||
|
|
|
|||
|
|
1. **准备资料**：管理员新建知识库，上传课程稿、产品资料、历史直播稿、聊天反馈，等待索引就绪。
|
|||
|
|
2. **整理分类**：把文件分为产品、心法、技法、案例、禁忌，检索测试确认命中正确。
|
|||
|
|
3. **配置 Agent**：
|
|||
|
|
- 主控 Agent 负责拆解；
|
|||
|
|
- 写作 Agent 绑定知识库分类和写作技能；
|
|||
|
|
- 质检 Agent 绑定审校规则；
|
|||
|
|
- 组合 Agent 负责全文；
|
|||
|
|
- 数字人控制统一表达风格。
|
|||
|
|
4. **生成训练营导图**：输入主题和天数，复用已读资料，检查每日目标、证据和缺口，确认方案。
|
|||
|
|
5. **创建内容任务**：选择第 5 天导图、直播时长和画布模板，输入目标与验收标准。
|
|||
|
|
6. **导图拆解**：系统生成多个内容段、时间范围、标签、待确认项。
|
|||
|
|
7. **逐段生产**：写作 Agent 基于 RAG 证据和数字人人格生成口播稿。
|
|||
|
|
8. **自动质检**：结构、风格、事实和风险门禁给出 PASS / FAIL。
|
|||
|
|
9. **人工处理**：用户通过、打回或跳过；打回意见可沉淀为待确认记忆。
|
|||
|
|
10. **总监纠偏**：发现段落偏离主题时，注入指导重做一次。
|
|||
|
|
11. **组合成稿**：系统只拼接已通过段落，做跨段一致性检查，输出彩色 DOCX。
|
|||
|
|
12. **交付复用**：最终稿下载交付，优质规则、技能和记忆持续沉淀。
|
|||
|
|
13. **微信服务**：同一个已审核数字人绑定微信账号，对私域用户提出的课程 / 产品问题进行带知识依据的回答。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 16. 关键业务不变量
|
|||
|
|
|
|||
|
|
这些规则是理解系统代码和后续改造时最不能破坏的约束：
|
|||
|
|
|
|||
|
|
1. **生产 Agent 没有可用知识库时不能生成内容**；
|
|||
|
|
2. **任务运行优先使用创建时冻结的 Agent / 模型 / 规则快照**；
|
|||
|
|
3. **数字人必须审核生效后才能被正式 Agent 和微信使用**；
|
|||
|
|
4. **待确认记忆不能未经人工审核直接影响生产**；
|
|||
|
|
5. **最终成稿只能组合人工通过的内容段**；
|
|||
|
|
6. **知识检索必须先做组织、用户、分类和资源授权过滤**；
|
|||
|
|
7. **RAG 返回的是证据，不允许把无来源信息包装成事实**；
|
|||
|
|
8. **用户打回意见必须能影响下一轮生成**；
|
|||
|
|
9. **微信消息必须验签并按 message_id 幂等**；
|
|||
|
|
10. **点数不足应在启动前阻断，余额 / 鉴权类错误应在运行中熔断**；
|
|||
|
|
11. **用量、点数流水和审计日志应追加记录，不做无痕覆盖**；
|
|||
|
|
12. **共享资源的修改、删除、全局发布要经过授权或审核机制**；
|
|||
|
|
13. **长任务必须有阶段状态、可取消 / 暂停标记和重启恢复策略**；
|
|||
|
|
14. **训练营导图的课程节点必须有证据，不为凑天数扩展题外内容**。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 17. 当前代码形态和维护建议
|
|||
|
|
|
|||
|
|
### 17.1 代码形态
|
|||
|
|
|
|||
|
|
- `server/app/main.py` 体量很大（约 400KB+），集中了大量路由和业务逻辑；
|
|||
|
|
- RAG、Agent Runtime、训练营、计费、权限等已拆出独立模块；
|
|||
|
|
- 源码中保留了多个 `.pre-*` 备份文件，正式交付或长期维护时建议移出主代码目录；
|
|||
|
|
- 前端页面较多，但统一通过 `api.ts` 调用后端，并有懒加载和路由预取；
|
|||
|
|
- 现有设计文档丰富，但部分文档描述的是规划或阶段状态，二次开发时应以当前模型、路由和测试为准。
|
|||
|
|
|
|||
|
|
### 17.2 建议的模块化拆分
|
|||
|
|
|
|||
|
|
后续可优先把 `main.py` 拆分为：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
api/auth.py
|
|||
|
|
api/knowledge.py
|
|||
|
|
api/agents.py
|
|||
|
|
api/digital_humans.py
|
|||
|
|
api/campaigns.py
|
|||
|
|
api/training_maps.py
|
|||
|
|
api/billing.py
|
|||
|
|
api/wechat.py
|
|||
|
|
api/ops.py
|
|||
|
|
services/...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`training_map.py` 已经使用 APIRouter，是较好的拆分参考。
|
|||
|
|
|
|||
|
|
### 17.3 部署注意
|
|||
|
|
|
|||
|
|
- 生产环境不要提交真实 `.env.production`；
|
|||
|
|
- 数据目录、知识库原文、向量索引和产物目录要纳入备份与挂载卷；
|
|||
|
|
- Node iLink sidecar 需要 Node.js 22+；
|
|||
|
|
- 部分训练营缓存锁使用 `fcntl`，更适合 macOS / Linux 生产环境；Windows 一键启动主要适合开发预览；
|
|||
|
|
- 大知识库场景应持续监控 SQLite 写锁、FTS 索引体积、RAG P95 和模型 Provider 限流；
|
|||
|
|
- 知识图谱升级应保持“图谱只做导航，原文 chunk 才是证据”的边界。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 18. 新成员快速阅读顺序
|
|||
|
|
|
|||
|
|
建议按以下顺序看源码：
|
|||
|
|
|
|||
|
|
1. `server/app/models.py`：先理解所有业务对象；
|
|||
|
|
2. `server/app/config.py`：环境、数据目录和默认模型；
|
|||
|
|
3. `web/src/AppRouter.tsx`、`web/src/shell.tsx`：理解页面和权限入口；
|
|||
|
|
4. `server/app/auth.py`、`access.py`：理解认证和资源授权；
|
|||
|
|
5. `server/app/rag/pipeline.py`、`hybrid.py`：理解知识入库与检索；
|
|||
|
|
6. `server/app/agents/coordinator.py`：理解导图如何拆段；
|
|||
|
|
7. `server/app/agents/runner.py`：理解内容任务主流水线；
|
|||
|
|
8. `server/app/agents/qc.py`、`supervisor.py`、`composer.py`：理解质检、纠偏和成稿；
|
|||
|
|
9. `server/app/digital_persona.py`：理解数字人协议；
|
|||
|
|
10. `server/app/training_map.py` 和 `training_corpus.py`：理解训练营导图；
|
|||
|
|
11. `server/app/billing.py`、`llm.py`、`points_guard.py`：理解模型、成本和熔断；
|
|||
|
|
12. `scripts/wechat_ilink_sidecar.mjs` 与微信相关 API：理解私域触达；
|
|||
|
|
13. `ops.py`、`backup.py`、`task_queue.py`、`perf_metrics.py`：理解运维闭环。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 19. 总结
|
|||
|
|
|
|||
|
|
雅文工作台不是简单的“聊天机器人后台”，而是一个围绕真实内容团队设计的 **AI 内容生产操作系统**：
|
|||
|
|
|
|||
|
|
- 前端提供面向运营人员的低门槛工作台；
|
|||
|
|
- 后端用任务、段落、质检和成稿把生产过程结构化；
|
|||
|
|
- RAG 保证内容尽量来自可追溯资料；
|
|||
|
|
- Agent、技能、记忆和数字人把生产方法和表达风格资产化；
|
|||
|
|
- 画布和运行时把多角色协作编排成可重复流水线；
|
|||
|
|
- 训练营导图把“长期课程设计”纳入证据化规划；
|
|||
|
|
- 微信 Bot 把数字人从内容生产工具延伸为私域服务入口；
|
|||
|
|
- 权限、审核、版本、日志、备份、计费和配额让系统具备团队使用和商业化运营基础。
|
|||
|
|
|
|||
|
|
后续增强无论是知识图谱、外部 Worker、多组织 SaaS 还是更多渠道接入，都应继续守住三条底线：
|
|||
|
|
|
|||
|
|
> **内容有证据、执行有边界、过程可审计。**
|