Files

T

yi 72fc5b47c7 docs: add architecture, workflow and delivery documents

2026-09-16 19:06:19 +08:00

35 KiB

Raw Blame History

雅文内容创造工作台：核心逻辑、功能与业务总结

生成日期：2026-09-15
依据源码：server/app、web/src、scripts、docs 及 2026-09-14 源码包说明整理。
文档定位：面向产品、运营、测试、运维和二次开发人员，快速理解系统“解决什么业务问题、有哪些核心功能、数据如何流转、关键规则在哪里实现”。

1. 一句话定位

这是一套面向私域训练营 / 直播内容生产 / 数字人 IP 运营的 AI 内容工作台。系统把“资料库、Agent 方法论、数字人表达风格、内容任务流水线、人工审查、用量计费和微信触达”整合在一起，目标是让内容生产从“单次问 AI”变成：

有资料依据、有角色分工、有过程审查、有版本沉淀、有成本控制、可通过微信持续服务用户的工业化生产线。

核心业务链路可以概括为：

知识素材入库
  → 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 进程拓扑

浏览器
  → 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 入库流程

上传文件 / 文件夹
  → 病毒/异常文件隔离（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 混合检索流程

用户/Agent 查询
  → 权限与组织校验
  → 知识库、分类、文件白名单、隔离文件过滤
  → 查询 Embedding（有查询缓存）
  → 向量召回
  → 中文 FTS 关键词召回
  → RRF 融合
  → 去重、多样性和主题覆盖
  → Cross-Encoder 精排
  → 父级上下文扩展
  → 按 Token 预算返回带来源的证据片段

关键设计：

权限签名参与缓存键：授权变化后不会复用旧候选池；
索引版本参与缓存键：知识更新后自动失效；
查询向量与候选池缓存分离：改变 top-k 或分类不必总是重算向量；
FTS 未就绪时先向量降级，索引预热后自动切换 hybrid；
RAG 运行在独立 worker pool，避免 Embedding 大模型占满 API 进程；
检索结果带文件、chunk、分类等元数据，供正文引用和溯源；
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 从具体生产中获得的经验”。

记忆分待确认和已生效两层：

自动生成或人工录入的建议先进入 PendingMemory；
审核通过后进入 Memory 并可索引；
生成时按 Agent、任务、段落、查询召回相关记忆；
用户打回段落时，可自动生成 L3 偏好类待确认记忆；
记忆不会未经确认直接影响生产；
画布授权只传递配置者自己的 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 画布分波次执行

普通模式按段落顺序执行；画布模式根据节点依赖边计算拓扑波次：

第一波无上游节点
  → 生成并提交锚点卡
第二波读取上游锚点卡
  → 生成、质检、审查
后续波次继续承接
  → 画布外兜底段最后执行
  → 全部人工通过后组合

实现位于 agents/runner.py 的 run_campaign()。每个波次内部串行，原因是：

下游需要上游锚点卡；
SQLite 单写入者不适合大量并发写；
这样能降低知识片段预留、产物写入和计费事务冲突。

8.4 单段生成逻辑

execute_segment() 是段落生产核心，主要步骤：

校验 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 负责最终文稿。

核心规则：

只组合人工通过的内容段；
跳过段、待重做段和失败段不能进入正式交付；
读取任务待确认项和说明；
做跨段一致性总检：
- 跨段矛盾；
- 回指断裂；
- 时间线一致性；
- 情绪曲线；
- 钩子兑现；
若总检失败，在成稿说明中列出具体段落和建议，要求回到对应段处理；
生成 DOCX，支持彩色标记：
- 黑色：正文；
- 红色：产品；
- 紫色：金句；
- 绿色：运营；
- 灰色：表演提示；
- 蓝色：修改建议；
Artifact 保存 DOCX 路径、组合报告、Trace、运行快照和可见性；
前端可预览和下载。

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 通过回调同步二维码、扫码、连接、断开和错误状态。

连接要求：

选择当前账号有权使用的 production 或 service Agent；
Agent 必须绑定已审核生效的数字人；
后端创建账号和独立 secret；
sidecar 使用 secret 发起扫码连接；
页面展示二维码并轮询连接状态。

11.2 消息处理

微信收到文本
  → 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、导出、存储等服务类型；
支持用户日 / 月配额、金额上限、存储和并发限制；
超限策略包括提醒、软限制、硬限制。

任务启动前：

根据历史均值或保守默认值估算 Token、金额、点数和耗时；
点数余额必须覆盖预估成本加 20% 缓冲；
不足时阻断启动并提示充值。

任务运行中：

每次模型调用消耗点数；
Provider 返回余额、鉴权等不可自愈错误时立即熔断；
避免“已经没点数还继续跑”的浪费。

管理员可按快捷档位发放点数：1 千万、1 亿、10 亿，也可手工调整。

13. 权限、租户隔离与资源治理

13.1 登录和角色

认证位于 auth.py：

首次使用支持 bootstrap 管理员；
密码使用 PBKDF2-SHA256，随机 salt，高迭代次数；
登录后发放不透明会话 Token；
数据库保存 Token 哈希；
支持会话过期、撤销和最近访问时间；
内置角色包括 admin、editor、reviewer、viewer；
支持自定义角色和细粒度权限；
旧权限名会自动扩展为新权限集合，避免升级丢权限。

13.2 三层权限控制

前端菜单隐藏
  → 前端路由 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 天直播稿”为例：

准备资料：管理员新建知识库，上传课程稿、产品资料、历史直播稿、聊天反馈，等待索引就绪。
整理分类：把文件分为产品、心法、技法、案例、禁忌，检索测试确认命中正确。
配置 Agent：
- 主控 Agent 负责拆解；
- 写作 Agent 绑定知识库分类和写作技能；
- 质检 Agent 绑定审校规则；
- 组合 Agent 负责全文；
- 数字人控制统一表达风格。
生成训练营导图：输入主题和天数，复用已读资料，检查每日目标、证据和缺口，确认方案。
创建内容任务：选择第 5 天导图、直播时长和画布模板，输入目标与验收标准。
导图拆解：系统生成多个内容段、时间范围、标签、待确认项。
逐段生产：写作 Agent 基于 RAG 证据和数字人人格生成口播稿。
自动质检：结构、风格、事实和风险门禁给出 PASS / FAIL。
人工处理：用户通过、打回或跳过；打回意见可沉淀为待确认记忆。
总监纠偏：发现段落偏离主题时，注入指导重做一次。
组合成稿：系统只拼接已通过段落，做跨段一致性检查，输出彩色 DOCX。
交付复用：最终稿下载交付，优质规则、技能和记忆持续沉淀。
微信服务：同一个已审核数字人绑定微信账号，对私域用户提出的课程 / 产品问题进行带知识依据的回答。

16. 关键业务不变量

这些规则是理解系统代码和后续改造时最不能破坏的约束：

生产 Agent 没有可用知识库时不能生成内容；
任务运行优先使用创建时冻结的 Agent / 模型 / 规则快照；
数字人必须审核生效后才能被正式 Agent 和微信使用；
待确认记忆不能未经人工审核直接影响生产；
最终成稿只能组合人工通过的内容段；
知识检索必须先做组织、用户、分类和资源授权过滤；
RAG 返回的是证据，不允许把无来源信息包装成事实；
用户打回意见必须能影响下一轮生成；
微信消息必须验签并按 message_id 幂等；
点数不足应在启动前阻断，余额 / 鉴权类错误应在运行中熔断；
用量、点数流水和审计日志应追加记录，不做无痕覆盖；
共享资源的修改、删除、全局发布要经过授权或审核机制；
长任务必须有阶段状态、可取消 / 暂停标记和重启恢复策略；
训练营导图的课程节点必须有证据，不为凑天数扩展题外内容。

17. 当前代码形态和维护建议

17.1 代码形态

server/app/main.py 体量很大（约 400KB+），集中了大量路由和业务逻辑；
RAG、Agent Runtime、训练营、计费、权限等已拆出独立模块；
源码中保留了多个 .pre-* 备份文件，正式交付或长期维护时建议移出主代码目录；
前端页面较多，但统一通过 api.ts 调用后端，并有懒加载和路由预取；
现有设计文档丰富，但部分文档描述的是规划或阶段状态，二次开发时应以当前模型、路由和测试为准。

17.2 建议的模块化拆分

后续可优先把 main.py 拆分为：

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. 新成员快速阅读顺序

建议按以下顺序看源码：

server/app/models.py：先理解所有业务对象；
server/app/config.py：环境、数据目录和默认模型；
web/src/AppRouter.tsx、web/src/shell.tsx：理解页面和权限入口；
server/app/auth.py、access.py：理解认证和资源授权；
server/app/rag/pipeline.py、hybrid.py：理解知识入库与检索；
server/app/agents/coordinator.py：理解导图如何拆段；
server/app/agents/runner.py：理解内容任务主流水线；
server/app/agents/qc.py、supervisor.py、composer.py：理解质检、纠偏和成稿；
server/app/digital_persona.py：理解数字人协议；
server/app/training_map.py 和 training_corpus.py：理解训练营导图；
server/app/billing.py、llm.py、points_guard.py：理解模型、成本和熔断；
scripts/wechat_ilink_sidecar.mjs 与微信相关 API：理解私域触达；
ops.py、backup.py、task_queue.py、perf_metrics.py：理解运维闭环。

19. 总结

雅文工作台不是简单的“聊天机器人后台”，而是一个围绕真实内容团队设计的 AI 内容生产操作系统：

前端提供面向运营人员的低门槛工作台；
后端用任务、段落、质检和成稿把生产过程结构化；
RAG 保证内容尽量来自可追溯资料；
Agent、技能、记忆和数字人把生产方法和表达风格资产化；
画布和运行时把多角色协作编排成可重复流水线；
训练营导图把“长期课程设计”纳入证据化规划；
微信 Bot 把数字人从内容生产工具延伸为私域服务入口；
权限、审核、版本、日志、备份、计费和配额让系统具备团队使用和商业化运营基础。

后续增强无论是知识图谱、外部 Worker、多组织 SaaS 还是更多渠道接入，都应继续守住三条底线：

内容有证据、执行有边界、过程可审计。

35 KiB Raw Blame History Unescape Escape