docs: add architecture, workflow and delivery documents
This commit is contained in:
yi
@@ -0,0 +1,35 @@
|
||||
# M1 验收报告 · 雅文内容创造工作台
|
||||
|
||||
> 日期：2026-08-25 ｜ 阶段：M1 骨架+核心链路 ｜ 结论：✅ 全部通过
|
||||
|
||||
## 验收项逐条结果
|
||||
|
||||
| # | 验收项 | 结果 | 证据 |
|
||||
|---|---|---|---|
|
||||
| 1 | 真实导图跑通全链路 | ✅ | 七天营「调情圣手」day2 导图 → 主控拆解 **18 段**（0-120 分钟时间轴对齐、产品节点识别、8 项待确认清单、压缩决策 notes）→ 4 段生成（开场1599字/心法904/痛点998/技法990）→ 结构+风格质检双 PASS → 人工通过 → 组合 → docx（43KB 可下载） |
|
||||
| 2 | 检索测试页验证命中质量 | ✅ | 产品库：缩阴液 0.79 / 催情油 0.71；风格库：开场话术 0.90 / 销售规则 0.95 |
|
||||
| 3 | 双模型对比文风 | ✅ | DeepSeek 生成开场段；技法段换 **MiMo mimo-v2.5-pro** 重跑成功（质检双 PASS） |
|
||||
| 4 | 新标签即加即用 | ✅ | 添加「验收测试标签」（id=30）→ 立即出现在标签列表 |
|
||||
| 5 | 失败注入：填错 key → 红标+通知 → 修复重跑 | ✅ | 改错 key → 段 failed（auth 401 捕获）→ 任务 has_failure=True → 通知中心 3 条失败提醒 → 恢复 key → fix 重试生成成功 → 修复原因进记忆待确认池 |
|
||||
|
||||
## 意外收获（闭环验证）
|
||||
|
||||
- **质检→打回→自动重跑**：fix 重试生成后质检抓到漏字（"有主、有担当"→应为"有主见"）→ 自动带意见重跑 → 二次未过转人工 rework
|
||||
- **失败分类**：401 auth 被正确分类为不可重试类 → 直接转人工（不瞎重试）
|
||||
|
||||
## 当前系统状态
|
||||
|
||||
- 后端 http://127.0.0.1:8000（FastAPI，SQLite 13 表）
|
||||
- 前端 http://127.0.0.1:5173（React 看板：任务/Agent/标签/模型/知识库/日志通知）
|
||||
- 知识库：产品 70 块 + 风格 39 块（BGE-small-zh 本地向量化，ModelScope 下载）
|
||||
- Provider：DeepSeek（默认）/ MiMo / AI聚合网
|
||||
- 启动：双击 `启动工作台.bat`
|
||||
|
||||
## 遗留/下一阶段（M2 画布）
|
||||
|
||||
1. React Flow 画布（拖节点/连线/启停/模板）—— M1 用列表编排
|
||||
2. 波次调度（依赖图拓扑）—— M1 顺序执行
|
||||
3. 锚点卡下游注入—— M1 已生成锚点卡但下游读取为顺序模式
|
||||
4. 内容/跨稿质检全开—— M1 只开 structure+style
|
||||
5. 六色 docx —— M1 简版（黑正文+加粗标题）
|
||||
6. SRT 原文库（73场）导入
|
||||
@@ -0,0 +1,41 @@
|
||||
# M3 验收报告 · 雅文内容创造工作台（记忆+引用+组合总检）
|
||||
|
||||
> 日期：2026-08-25 ｜ 阶段：M3 ｜ 结论：✅ 全部通过
|
||||
|
||||
## 验收项逐条结果
|
||||
|
||||
| # | 验收项 | 结果 | 证据 |
|
||||
|---|---|---|---|
|
||||
| 1 | **打回意见 → 记忆建议 → 人工确认 → 注入** | ✅ | 打回段带意见"开场降档：性感画面撤下换自嘲暖场" → 待确认池出现 1 条（L3）→ 确认 → 修复重跑生成正常（记忆注入不破坏生成） |
|
||||
| 2 | **引用溯源（防无来源事实）** | ✅ | 产品段引用 6 块（产品知识库"催情油198买一送一"+成分表 + 数字雅文档案销售规则）；开场段引用 3 块；质检 prompt 带引用核对 |
|
||||
| 3 | **组合一致性总检（5 项）** | ✅ | 4 段组合 → LLM 总检：跨段矛盾/回指断裂/时间线/情绪曲线/钩子兑现 全 PASS → done；有 FAIL 时返回 has_issues + 打回路由提示 |
|
||||
| 4 | **波次内并行** | ✅ | ThreadPoolExecutor（≤3 并发，独立 Session，SQLite busy_timeout 30s） |
|
||||
| 5 | **备稿库导入** | ✅ | 11 个 docx → 414 块 |
|
||||
| 6 | 训练营框架库 | ✅ | 七天导图 + 28天重排版 → 65 块 |
|
||||
| 7 | 质检规则库 | ✅ | 已建（质检 Agent 挂接） |
|
||||
|
||||
## 过程中发现并修复的问题
|
||||
|
||||
1. **Agent kb_ids 从未生效**：seed 时没传 kb_ids（全空）→ 引用溯源一直空。已修复数据 + 修正 seed.py（名字→id 转换）
|
||||
2. 缺"训练营框架库/质检规则库" → 已补建并挂接
|
||||
3. SQLite 并发写：busy_timeout 提到 30s
|
||||
4. `references` 是 SQLite 保留字 → 列名加引号
|
||||
|
||||
## 当前知识库全景
|
||||
|
||||
| 库 | 块数 | 用途 |
|
||||
|---|---|---|
|
||||
| 产品知识库 | 70 | 产品销售/产品体验 Agent + 内容质检 |
|
||||
| 风格档案库 | 39 | 全部生产 Agent（怎么讲） |
|
||||
| 直播原文库 | 0（已停，可随时导入） | 73 场 SRT |
|
||||
| 备稿库 | 414 | 跨稿质检 + 风格参考 |
|
||||
| 训练营框架库 | 65 | 心法/钩子/跨稿质检（次日真实框架） |
|
||||
| 质检规则库 | 0（规则内置于质检 Agent rules） | 质检 Agent |
|
||||
|
||||
## 遗留（M4）
|
||||
|
||||
- 导图图片 OCR（Windows OCR 替代路径）
|
||||
- 多天连续任务 + 跨稿对账自动化
|
||||
- rerank 开关、画布体验打磨、模板库
|
||||
- 六色 docx（黑/红/紫/绿/灰/蓝）
|
||||
- 前端：组合 has_issues 时一键打回对应段按钮
|
||||
@@ -0,0 +1,44 @@
|
||||
# M4 验收报告 · 雅文内容创造工作台（OCR + 六色 docx + 跨稿对账）
|
||||
|
||||
> 日期：2026-08-25 ｜ 阶段：M4（最后阶段）｜ 结论：✅ 全部通过
|
||||
|
||||
## 验收项逐条结果
|
||||
|
||||
| # | 验收项 | 结果 | 证据 |
|
||||
|---|---|---|---|
|
||||
| 1 | **导图图片 OCR** | ✅ | 真实导图识别：埃及艳后.png 63 行、凯格尔密码.png 19 行，内容可读（含坐标还原阅读顺序）；上传→OCR→填入导图框全链路通 |
|
||||
| 2 | **六色 docx** | ✅ | 【P】金句标记 → docx 紫色 run（7030A0）实测渲染成功；黑正文/紫金句/图例灰统计确认 |
|
||||
| 3 | **跨稿对账** | ✅ | 收尾段新规则钩子必填 → 锚点卡 hook 生成"明天解决他太快+八爪鱼缠法" → 关联任务开场段产物**自然兑现**："昨天我说过，今晚要解决他太快的问题…现场拆解八爪鱼缠法" |
|
||||
| 4 | **画布模板库 + 一键打回** | ✅ | 【模板】无产品场 / 【模板】纯心法场 已入库；组合总检 FAIL → 一键打回问题段按钮（带组合意见） |
|
||||
| 5 | 组合一致性总检 | ✅ | 实测抓到跨段矛盾 FAIL（5 项检查 1 项 FAIL），has_issues 流程完整 |
|
||||
|
||||
## OCR 排障记录（Windows 特有坑）
|
||||
|
||||
1. WinRT OCR 无法处理**中文路径**（UNABLE_TO_MASK_PATH）→ 中间文件存纯 ASCII 临时目录
|
||||
2. PowerShell 5.1 读无 BOM 的 UTF-8 脚本按 GBK 解析 → 路径乱码 → 脚本写 **utf-8-sig（带 BOM）**
|
||||
3. 大图（7.7MB 导图）OCR 引擎抛 AggregateException → Pillow 预处理（EXIF 转正 + 缩放到 2000px）
|
||||
4. PowerShell 输出 GBK 编码 → subprocess 用 encoding="gbk" 解码
|
||||
5. 单引号字符串不转义反斜杠 → 路径替换不要 replace("\\", "\\\\")
|
||||
|
||||
## 全阶段完成总结（M1-M4）
|
||||
|
||||
```
|
||||
M1 骨架+核心链路 ✅ 导图→拆解→生成→质检→审查→docx 全链路
|
||||
M2 画布 ✅ 节点/连线/启停/波次调度/近义标签/4质检全开
|
||||
M3 记忆+引用+总检 ✅ 记忆人工确认池/引用溯源/组合5项总检/并行
|
||||
M4 OCR+交付+对账 ✅ 导图OCR/六色docx/跨稿对账/模板库/一键打回
|
||||
```
|
||||
|
||||
## 当前系统全景
|
||||
|
||||
- 后端 FastAPI :8010 + 前端 React :5173（启动工作台.bat）
|
||||
- 6 个知识库（产品70/风格39/备稿414/训练营框架65/质检规则/直播原文库待导）
|
||||
- 14 个 Agent + 3 个模型 Provider（DeepSeek/MiMo/AI聚合网）+ 3 个画布模板
|
||||
- 29 个内容标签（可自加）｜ 4 道质检 ｜ 记忆待确认池 ｜ 失败转人工+通知
|
||||
|
||||
## 后续可打磨（非阻塞）
|
||||
|
||||
1. 特大导图（>5MB）分块 OCR
|
||||
2. 【S】表演标记强化（圆括号 → 标记包裹，让灰色更多）
|
||||
3. 前端组合报告展示（目前 alert 提示）
|
||||
4. 直播原文库导入（73 场 SRT 随时可导）
|
||||
@@ -0,0 +1,13 @@
|
||||
# Source delivery report
|
||||
|
||||
This file is the cross-platform entrypoint for the source delivery notes.
|
||||
|
||||
Please read the Chinese report in the same directory: 源码交付说明-2026-08-28.md.
|
||||
If a ZIP tool cannot display Chinese filenames correctly, the key delivery facts are:
|
||||
|
||||
- Package date: 2026-08-28.
|
||||
- Includes backend/frontend source, scripts, tests, dependency locks and design documents.
|
||||
- Excludes server/data, .venv, node_modules, dist, databases, knowledge content, vector indexes, logs, backups, credentials and previous ZIP archives.
|
||||
- Backend tests: 31 passed.
|
||||
- Frontend TypeScript check and Vite production build: passed.
|
||||
- Remaining issues and priorities are documented in the Chinese report beside this file.
|
||||
@@ -0,0 +1,85 @@
|
||||
# 雅文内容创造工作台：SaaS 与记忆库全面审查报告
|
||||
|
||||
审查日期：2026-08-27
|
||||
审查范围：`server/app`、`web/src`、`server/data/workspace.db`、用户端 `/app`、管理端 `/admin`
|
||||
审查基线：核心逻辑设计文档 v6、用户端/管理端云化与计费设计、记忆库原文《一文搞懂个人 AI 记忆系统构建全流程》
|
||||
|
||||
## 一、结论摘要
|
||||
|
||||
当前工作台已经具备“用户端与管理端分入口、登录会话、用户级用量账单、Agent 画布统一授权、知识库和记忆库基础 CRUD、运行追踪、模型目录同步”的本地可运行骨架。
|
||||
|
||||
本轮已修复三项高风险问题：
|
||||
|
||||
1. 角色从固定四个选项升级为可新建、可调整、可删除的自定义角色；界面权限名称全部改为中文。
|
||||
2. 管理端资源和账单查询增加租户范围，管理员只处理本租户和全局资源；跨租户成员、知识库、画布、记忆与用量不再通过管理接口直接返回。
|
||||
3. 记忆表补齐标题、描述、隐私范围、标签、沉淀日期、索引状态、使用次数和最近使用时间；运行时只加载“已生效且已建立索引”的记忆，并限制单个 Agent 最多加载 50 条高使用频次记忆。
|
||||
|
||||
仍需继续建设的企业级能力：云数据库/对象存储、密钥托管、组织与平台管理员分层、限流与审计留存、向量检索索引服务、记忆冲突检测和过期治理。这些属于部署架构升级，不应被本地 SQLite 演示版冒充为已完成。
|
||||
|
||||
## 二、文章要点与当前实现对照
|
||||
|
||||
参考原文：[一文搞懂个人 AI 记忆系统构建全流程](https://mp.weixin.qq.com/s/2Kz2JQK1r606S3quiCFUYg)
|
||||
|
||||
### 2.1 记忆组织
|
||||
|
||||
文章将记忆拆为五层：身份、原则、偏好、上下文、知识；每个一级目录最多两级子目录，二级目录直接放文件。当前数据库原有 `L1-L4` 层级保留兼容，本轮新增元数据后，建议在 UI 中把层级显示为“身份/原则/偏好/上下文/技能/经验/学习”，并在数据库中继续保留原始层级字段以兼容历史任务。
|
||||
|
||||
### 2.2 元数据
|
||||
|
||||
文章要求每条记忆具备类型、标题、描述、状态、隐私、标签和沉淀日期。当前 `Memory` 已增加对应字段，并新增 `index_status`、`usage_count`、`last_used_at` 作为运行治理字段。历史记录启动时会用 `created_at` 补齐沉淀日期。
|
||||
|
||||
### 2.3 调用与写入
|
||||
|
||||
文章强调“先看总索引，再按需加载”，写入前必须人工确认，并且保留来源和排除理由。当前待确认池仍是人工确认入口，批准后才创建 `Memory`；运行快照只读取已生效且已索引的记忆。下一阶段应增加每个 Agent 的索引文件/摘要接口、来源证据字段和冲突候选列表，避免把所有正文一次性塞进上下文。
|
||||
|
||||
### 2.4 文章明确的治理缺口
|
||||
|
||||
文章指出记忆升级、冲突检测和过期检测仍需要治理。当前系统已经有 `active/expired` 状态，但还缺自动过期策略、冲突检测、版本链和“经验升级为技能/原则”的人工工作流，列为 P1。
|
||||
|
||||
## 三、SaaS 审查结果
|
||||
|
||||
### P0：已修复
|
||||
|
||||
| 问题 | 修复结果 |
|
||||
| --- | --- |
|
||||
| 固定角色，无法按岗位新建 | 新增角色接口和管理端表单；内置角色不可删除，自定义角色可删除，仍被成员使用时删除会被拒绝 |
|
||||
| 权限码直接展示英文 | 权限矩阵和成员角色选择只展示中文名称；内部键仅用于接口与数据库 |
|
||||
| 管理员管理接口全表查询 | 知识库、画布、记忆、成员、用量、账单和配额查询按 `organization_id` 限制；全局资源以 `organization_id=0` 作为共享基线 |
|
||||
| 管理员跨租户直接访问资源 | 资源访问函数统一校验租户；管理员不再天然拥有其他租户资源权限 |
|
||||
| 通知列表可能暴露未知来源 | 普通成员只读取自己任务产生的通知；没有资源关联的历史通知交给租户管理员处理 |
|
||||
|
||||
### P1：当前仍需建设
|
||||
|
||||
| 领域 | 当前状态 | 建议 |
|
||||
| --- | --- | --- |
|
||||
| 组织管理 | 有 `Organization` 表，默认单组织，缺少组织创建、成员邀请和组织管理员边界 | 增加组织生命周期、邀请、离职回收和平台超级管理员能力 |
|
||||
| 数据存储 | SQLite、文件目录和本地向量回退存储 | 生产环境切换云数据库、对象存储和托管向量库；文件访问使用签名 URL |
|
||||
| 凭据安全 | Provider API Key 仍在本地表中保存 | 接入密钥托管服务，数据库只保存引用和轮换版本 |
|
||||
| 模型目录 | Provider/ModelCatalog 当前偏全局 | 增加租户可见范围、默认模型策略、可用性探测和费率版本审批 |
|
||||
| 计费 | 用户账单、追加式用量事件和配额已经存在 | 增加支付/充值、退款、月结单、发票、账单导出和异常对账 |
|
||||
| 运行治理 | 有 trace、span、调用日志和快照 | 增加租户级保留周期、脱敏、检索权限和审计导出 |
|
||||
| 并发与限流 | 有配额检查，缺少接口/模型/租户级限流和队列配额 | 增加 Redis 限流、并发槽位、重试预算和熔断 |
|
||||
|
||||
### P2：体验与维护
|
||||
|
||||
- 统一全部页面的状态词、可见性词和授权词，避免同时出现内部英文枚举。
|
||||
- 为角色、Agent、画布、知识库和记忆补充操作日志和变更前后快照。
|
||||
- 将资源授权和画布授权合并展示为一条“使用范围”，降低管理员理解成本。
|
||||
- 增加租户级健康检查、索引积压、账单积压和失败运行的运维面板。
|
||||
|
||||
## 四、验收证据
|
||||
|
||||
- 后端 `compileall`：通过。
|
||||
- 后端回归：24 项测试通过。
|
||||
- 前端 `npm run build`：通过，Vite 生产构建成功。
|
||||
- 真实数据库迁移：`Memory` 元数据列已存在，历史记忆沉淀日期已回填。
|
||||
- 角色接口实测：创建“内容主编”自定义角色，确认返回 `builtin=false`，随后删除成功。
|
||||
- 服务地址：前端 `http://127.0.0.1:5173`，后端 `http://127.0.0.1:8010`。
|
||||
|
||||
## 五、下一阶段实施顺序
|
||||
|
||||
1. 完成组织管理和平台管理员分层，冻结租户边界。
|
||||
2. 接入云数据库、对象存储、向量索引与密钥托管。
|
||||
3. 为记忆增加索引摘要、来源证据、版本链、冲突候选和过期任务。
|
||||
4. 增加租户限流、运行审计、账单对账与导出留痕。
|
||||
5. 用 Playwright 做 `/app`、`/admin`、角色创建、授权、记忆确认和账单隔离的端到端验收。
|
||||
@@ -0,0 +1,48 @@
|
||||
# DSH 内容生产执行器架构（2026-09-15）
|
||||
|
||||
## 1. 职责边界
|
||||
|
||||
工作台（FastAPI）保留管理职责：任务创建、导图录入、任务单确认、Agent/知识分类配置、启动/暂停/停止、人工审查、重试/跳过、成稿下载、运行事件与审计展示。
|
||||
|
||||
DSH（独立 Worker）负责执行核心内容生产流水线：导图拆解、全量生成、逐段生成、人工打回重做、失败修复重试、最终一致性总检与 docx 组合。
|
||||
|
||||
## 2. 后端开关
|
||||
|
||||
- 默认 `YAWAN_EXECUTION_BACKEND=inline`：保持原行为，由 API 后台线程执行。
|
||||
- 设置 `YAWAN_EXECUTION_BACKEND=dsh`：API 只写入 `CampaignRun`/业务状态和 `TaskQueueItem`，不启动内容生产线程。
|
||||
|
||||
启动 DSH：
|
||||
|
||||
```bash
|
||||
bash scripts/start_dsh.sh
|
||||
# 或
|
||||
cd server && YAWAN_EXECUTION_BACKEND=dsh python -m app.dsh_worker
|
||||
```
|
||||
|
||||
当前版本要求 API 和 DSH 共享同一个 `YAWAN_DATA_DIR`（SQLite、`data/kb`、`data/chroma`、`data/artifacts`、模型缓存）。
|
||||
|
||||
## 3. 队列任务
|
||||
|
||||
DSH 只领取 `campaign-%` 前缀，避免领取 `training-map:*` 等其他后台任务：
|
||||
|
||||
- `campaign-run:{run_id}`：全量/逐段生成，payload 中用 `mode=full|step` 区分。
|
||||
- `campaign-segment-redo:{segment_id}`：人工打回重做。
|
||||
- `campaign-segment-fix:{segment_id}`：工作台先应用修复配置，DSH 再执行 pending 段。
|
||||
- `campaign-parse:{campaign_id}`：导图拆解和任务单生成。
|
||||
- `campaign-compose:{campaign_id}`：五项跨段一致性总检和六色 docx 成稿。
|
||||
|
||||
队列表具备租约、心跳、退避重试、死信和幂等键。DSH 心跳定期续租；崩溃后的过期租约会被重新领取，并把孤儿 `running` 内容段恢复成可执行状态。
|
||||
|
||||
## 4. 进度与状态
|
||||
|
||||
- DSH 的进度事件写入 `ProgressEvent`，同时保留内存事件通道。
|
||||
- SSE `/api/events/progress` 和轮询接口统一通过 `progress.snapshot()` 读取内存 + SQLite 事件。
|
||||
- 前端新增 `composing` 状态，成稿组合期间自动轮询，完成后展示最终文稿或一致性问题。
|
||||
|
||||
## 5. 运维注意
|
||||
|
||||
1. 生产环境先启动工作台，再启动至少一个 DSH Worker。
|
||||
2. 不要让 `inline` API 和 DSH 同时执行同一套生产数据；同一环境应统一配置后端模式。
|
||||
3. DSH 需要与 API 使用相同 Python 依赖、模型密钥、Provider 配置、知识库和数据目录。
|
||||
4. 死信任务可在工作台运维页面重放；死信会同步补偿 Run/Campaign/Segment 状态并发送通知。
|
||||
5. 未来跨机器部署时，需要把队列升级为 HTTP Job API，并共享或同步 artifacts/向量索引。
|
||||
@@ -0,0 +1,52 @@
|
||||
# Coze Studio 借鉴分析 → 私域Agent 落地清单
|
||||
|
||||
分析对象：github.com/coze-dev/coze-studio（字节跳动开源 AI Agent 开发平台，21.5k star，Apache-2.0）
|
||||
技术栈：Go 后端（DDD 微服务 + Eino 运行时）+ React18/TS 前端（Rush monorepo + FlowGram 画布引擎）
|
||||
|
||||
## 一、值得借鉴的 6 个设计（按投入产出排序）
|
||||
|
||||
### 1. 工作流画布：节点注册表 + 表单元数据 ⭐ 最值得抄
|
||||
Coze：每种节点类型一个"注册表"（type 唯一、与后端约定 schema）+ "表单元数据"（FormMeta），
|
||||
画布上的节点卡只显示关键信息摘要，点击后在**侧边抽屉**里出完整配置表单；支持动态端口
|
||||
（如意图识别节点按分支数动态生成输出口）。
|
||||
→ 我们已有 @xyflow/react 画布。落地：
|
||||
- CanvasPage 抽 `nodeRegistry.ts`：每种 Agent 角色（生产/质检/主控/组合）一份 FormMeta，
|
||||
节点卡只显示「名称+标签+启停」，配置全部进右侧检查器（对齐已完成的"属性检查器"规划）
|
||||
- 节点 schema 与后端 canvas_snapshot 字段一一对应（现在已是 {node_id, agent_id, enabled, x, y}，加 role 即可）
|
||||
|
||||
### 2. 节点/工作流「试运行」(Test Run)
|
||||
Coze：每个节点支持单节点调试，试运行结果条直接显示在节点卡下方。
|
||||
→ 我们已有 run-step 逐段生成。落地：画布页加「▶ 试运行此节点」按钮——
|
||||
选中单个 Agent 节点，用一段测试导图文本走一次该 Agent 的生成，结果展示在节点卡下（复用 SSE 进度）。
|
||||
|
||||
### 3. 知识库：分段策略可配置 + 命中测试分 tab
|
||||
Coze：知识库建库时可选分段方式（自动/自定义分隔符/最大长度），且"命中测试"是一级入口。
|
||||
→ 我们的 KB 检索测试已在详情页签里 ✓。补：建库弹窗加"分段设置"（当前固定 2200 字聚合，
|
||||
放开为：自动/自定义长度/按标题切），后端 chunk.chunk_texts 已支持 target 参数，只差暴露。
|
||||
|
||||
### 4. 发布流：草稿 ↔ 发布版本分离
|
||||
Coze：Agent/工作流有"草稿"与"发布"两态，发布时冻结配置快照，回滚=切回历史发布版本。
|
||||
→ 我们有 canvas_snapshot 和 prompt_template_version 雏形。落地：Agent 加「发布」按钮，
|
||||
发布时把当前配置写进 agent.runtime_snapshot 冻结；任务生成优先用快照（已有此逻辑），未发布的改动不影响在跑任务。
|
||||
|
||||
### 5. Chat SDK / OpenAPI
|
||||
Coze：提供对话 OpenAPI 和可嵌入的 Chat SDK。
|
||||
→ 远期：给吴总团队做移动端轻入口或小程序时再考虑；当前 SaaS 页面已够用。
|
||||
|
||||
### 6. 功能开关（Feature Flags）
|
||||
Coze：bot-flags 统一管理功能灰度。
|
||||
→ 我们的 qc_mode 已是任务级开关。可以再收一个全局开关面板（系统管理→功能开关）：
|
||||
如"允许编辑内置资源""启用跨稿质检""启用总监审核"，避免改代码发版。
|
||||
|
||||
## 二、不建议照搬的
|
||||
- Rush monorepo + 30+ packages：我们单应用 147 文件，monorepo 是过度工程
|
||||
- Go 微服务 + DDD 四层：当前规模 FastAPI 单体+常驻子进程是最优解，拆微服务只会增加运维负担
|
||||
- i18n：用户全是中文团队，不需要
|
||||
- 数据库表资源（Coze 的 database 表）：我们没有此需求
|
||||
|
||||
## 三、建议落地顺序（结合用户此前痛点）
|
||||
1. 节点注册表+侧抽屉配置（画布体验，1 次迭代）
|
||||
2. 发布/草稿版本分离（Agent 改配置不再影响在跑任务，解决真问题）
|
||||
3. 分段策略可配置（KB 清洗质量的延伸）
|
||||
4. 全局功能开关面板（qc_mode 之类收进去）
|
||||
5. 单节点试运行（锦上添花）
|
||||
@@ -0,0 +1,61 @@
|
||||
# 微信 Bot 接入系统 AI
|
||||
|
||||
系统提供 `POST /api/wechat/bot/reply` 作为统一桥接接口。微信侧只负责收发消息，Agent、数字人、技能和已绑定知识库由系统处理。
|
||||
|
||||
## 配置
|
||||
|
||||
在生产服务器的 `/Users/macclaw/Desktop/yawan-workbench/.env.production` 设置（项目提供了 `.env.production.example` 模板；启动脚本和守护脚本会自动读取）：
|
||||
|
||||
```bash
|
||||
YAWAN_WECHAT_ADAPTER_URL=http://127.0.0.1:8765
|
||||
```
|
||||
|
||||
现在使用多账号模式时不需要手动填写 Bot Secret、Agent ID 或用户 ID。创建数字人后系统会自动生成同名 Agent 并绑定；数字人审核生效后，在“数字人 → 微信 Bot 连接”中选择该 Agent 并扫码。系统会为每个账号自动生成独立密钥和凭据目录。一个数字人可以绑定多个 Agent。
|
||||
|
||||
接口支持时间戳 HMAC 请求头：
|
||||
|
||||
```text
|
||||
X-WeChat-Bot-Timestamp: 当前 Unix 秒
|
||||
X-WeChat-Bot-Signature: HMAC-SHA256(secret, timestamp.conversation_id.message_id.text)
|
||||
```
|
||||
|
||||
`message_id` 用于幂等。Bot 重试同一消息时，系统会直接返回上次回复，不重复扣费。旧适配器也可暂时使用 `X-WeChat-Bot-Secret`，但新接入应升级到 HMAC。
|
||||
|
||||
## Wechaty 开发验证
|
||||
|
||||
`scripts/wechat_bot_adapter.mjs` 是可运行示例：
|
||||
|
||||
```bash
|
||||
cd /Users/macclaw/Desktop/yawan-workbench
|
||||
npm i wechaty wechaty-puppet-wechat4u
|
||||
YAWAN_API_URL=https://agent.pducv.cn \
|
||||
YAWAN_WECHAT_BOT_SECRET="$YAWAN_WECHAT_BOT_SECRET" \
|
||||
YAWAN_WECHAT_AGENT_ID=3 \
|
||||
node scripts/wechat_bot_adapter.mjs
|
||||
```
|
||||
|
||||
个人微信的 Web/UOS 协议存在封号和兼容性风险，只建议开发测试。生产建议使用腾讯官方 [openclaw-weixin](https://github.com/Tencent/openclaw-weixin) 的 iLink Bot 通道，或企业微信/公众号官方回调；这些适配器只需把收到的文本按同样 JSON 调用本接口，再将 `reply` 发回微信。
|
||||
|
||||
## 官方 iLink 多账号 sidecar
|
||||
|
||||
项目还提供 `scripts/wechat_ilink_sidecar.mjs`，使用 CoreSpeed 的官方 iLink SDK 管理多个账号。启动：
|
||||
|
||||
```bash
|
||||
cd /Users/macclaw/Desktop/yawan-workbench
|
||||
npm i @wechatbot/wechatbot
|
||||
YAWAN_API_URL=https://agent.pducv.cn \
|
||||
YAWAN_WECHAT_SIDECAR_PORT=8765 \
|
||||
/opt/homebrew/opt/node@22/bin/node scripts/wechat_ilink_sidecar.mjs
|
||||
```
|
||||
|
||||
`@wechatbot/wechatbot` 要求 Node.js 22 或更高版本；macOS/Homebrew 环境请使用上面的 Node 22 路径，或将 Node 22 放在 `PATH` 首位。
|
||||
|
||||
然后在 API 服务环境设置 `YAWAN_WECHAT_ADAPTER_URL=http://127.0.0.1:8765`。数字人页面点击“微信 Bot 连接”即可生成官方二维码；每个账号使用独立密钥、独立凭证目录和独立会话，只能调用自己绑定且有权限的 Agent。
|
||||
|
||||
请求示例：
|
||||
|
||||
```json
|
||||
{"agent_id":3,"conversation_id":"wx-room-or-user-id","message_id":"msg-001","text":"你好，帮我介绍一下课程"}
|
||||
```
|
||||
|
||||
系统会保留会话上下文，并把 Agent 的数字人规则、已挂接技能和知识库相关片段用于本轮回答。知识库检索失败时会记录日志并继续普通对话，避免微信侧卡死。
|
||||
@@ -0,0 +1,183 @@
|
||||
# 知识图谱检索升级方案
|
||||
|
||||
## 目标
|
||||
|
||||
解决训练营导图和内容任务在大知识库下的三个问题：
|
||||
|
||||
1. 不把全库原文一次性放进模型上下文；
|
||||
2. 检索既快又能覆盖概念之间的关系；
|
||||
3. 图谱、向量库或模型异常时仍能稳定生成并保留原文证据。
|
||||
|
||||
目标指标：
|
||||
|
||||
- 热态知识检索 P95：250ms 以内；
|
||||
- 首次冷启动检索：2 秒以内；
|
||||
- 内容任务最终注入：按 4,000～8,000 token 预算动态决定，不固定条数；
|
||||
- 训练营标准深度规划：10～30 分钟，超过硬截止时间必须保存阶段性结果；
|
||||
- 每个结论都能回溯到原始 chunk、文件和版本；
|
||||
- 图谱服务异常时自动回退到现有向量 + 中文 FTS + RRF + Cross-Encoder 链路。
|
||||
|
||||
## 总体架构
|
||||
|
||||
```text
|
||||
上传与索引
|
||||
├─ 原始文件、chunk、哈希和版本
|
||||
├─ 向量索引
|
||||
├─ 中文 FTS 索引
|
||||
├─ 分层底稿（文件级、分类级、知识库级）
|
||||
└─ 知识图谱（实体、关系、证据、版本）
|
||||
|
||||
用户查询
|
||||
→ 权限和分类过滤
|
||||
→ 查询理解（实体、概念、约束、目标）
|
||||
→ 图谱 1～2 跳关系扩展
|
||||
→ 图谱证据指向的原文 + 向量/FTS 候选召回
|
||||
→ 去重与主题覆盖
|
||||
→ Cross-Encoder 精排
|
||||
→ 父级上下文扩展
|
||||
→ token 预算注入模型
|
||||
→ 生成、质检、引用回溯
|
||||
```
|
||||
|
||||
图谱是“导航和关系路由层”，原始 chunk 是“事实证据层”。任何图谱节点和关系都必须保存来源 chunk，不允许只凭图谱结论生成内容。
|
||||
|
||||
## 图谱数据设计
|
||||
|
||||
### 实体
|
||||
|
||||
实体至少包括：主题、概念、方法、步骤、人物、产品、风险、适用人群、工具、章节和课程天数。每个实体保存：
|
||||
|
||||
- `entity_id`、组织和知识库范围；
|
||||
- 规范名称、别名、类型；
|
||||
- `canonical_hash`、首次出现和最后更新时间；
|
||||
- 抽取模型、抽取版本和置信度；
|
||||
- 对应的来源 chunk 数量。
|
||||
|
||||
### 关系
|
||||
|
||||
关系采用有向边，例如：先决条件、组成、步骤先后、适用、反例、风险、冲突、相似、引用、属于分类。每条边保存：
|
||||
|
||||
- `from_entity_id`、`to_entity_id`、关系类型；
|
||||
- 权重和置信度；
|
||||
- `source_chunk_ids`、文件、版本；
|
||||
- 抽取版本、创建时间和失效时间。
|
||||
|
||||
### 版本与权限
|
||||
|
||||
图谱实体、关系和证据都必须带组织、知识库、文件版本和分类范围。查询先做权限过滤再做图扩展，不能先查全图再过滤，否则会有越权风险。
|
||||
|
||||
## 建图流程
|
||||
|
||||
### 上传时增量建图
|
||||
|
||||
1. 文件解析、清洗、去重和分块；
|
||||
2. 根据 `content_hash + chunking_version` 判断是否已有处理结果；
|
||||
3. 只对新增或发生变化的文件抽取实体和关系；
|
||||
4. 对别名和同义实体做规范化合并；
|
||||
5. 写入关系及来源 chunk；
|
||||
6. 让受影响的分类综述和知识库总览失效；
|
||||
7. 后台重新生成受影响的摘要和图谱局部；
|
||||
8. 发布新的图谱版本，旧版本仍可回溯。
|
||||
|
||||
图谱建立使用幂等任务、租约、断点游标和阶段性进度。单文件失败不会阻塞整库，也不会把未完成状态标成完成。
|
||||
|
||||
### 抽取策略
|
||||
|
||||
- 规则抽取：标题、列表、编号、术语表、明显步骤和引用关系优先用本地规则完成；
|
||||
- 模型抽取：只对规则无法判断的实体和关系做批量 AI 抽取；
|
||||
- 冲突处理：保留两条关系和各自来源，标记为冲突，交给查询阶段核验；
|
||||
- 低置信关系：只能用于召回扩展，不能单独作为最终证据；
|
||||
- 关系重复：按规范化实体、关系类型、来源版本去重。
|
||||
|
||||
## 训练营导图检索
|
||||
|
||||
### 快速模式
|
||||
|
||||
1. 解析主题和用户选择的知识库/分类；
|
||||
2. 图谱定位相关主题、先决条件、步骤链和冲突点；
|
||||
3. 以图谱命中的实体和来源 chunk 作为定向查询词；
|
||||
4. 并行执行向量和中文 FTS 召回；
|
||||
5. 按知识库、分类和主题做配额，避免大库占满结果；
|
||||
6. RRF 融合、去重和多样性筛选；
|
||||
7. Cross-Encoder 对最多 32～64 个候选精排；
|
||||
8. 回溯代表性原文，按 token 预算交给导图模型。
|
||||
|
||||
快速模式不再声称通读全库，返回检索范围、图谱覆盖主题和未覆盖主题。
|
||||
|
||||
### 标准/深度模式
|
||||
|
||||
1. 先读知识库级和分类级底稿；
|
||||
2. 从图谱确定相关主题簇、依赖链和冲突区域；
|
||||
3. 只对相关文件和代表性资料定点回查原文；
|
||||
4. 对关键缺口和冲突做二次检索；
|
||||
5. 生成导图和每日递进关系；
|
||||
6. 保存覆盖范围、引用、未完成主题和可续跑游标。
|
||||
|
||||
完整模式不再按 30 万段原文逐批重新交给模型。摘要和图谱按内容哈希增量复用，只有新增、变化或被主题路由命中的区域需要处理。
|
||||
|
||||
## 内容任务 Agent 检索
|
||||
|
||||
1. 由导图节点、标题、标签、产品和上一段锚点生成查询；
|
||||
2. 图谱扩展相关概念、步骤、风险和先决条件；
|
||||
3. 向量 + FTS 初召回 30～60 条；
|
||||
4. 权限、分类、禁用和消费状态过滤；
|
||||
5. RRF 融合和近重复去重；
|
||||
6. Cross-Encoder 精排 16～32 条；
|
||||
7. 命中 child chunk 后合并同一 parent 的相邻内容；
|
||||
8. 按 4,000～8,000 token 预算动态注入 6～12 条或更少/更多的来源；
|
||||
9. 只预留真正注入的片段，生成成功后再标记 consumed；
|
||||
10. 生成后记录引用、锚点和图谱关系，供下一段承接。
|
||||
|
||||
“已读/已摘要”和“已消费”必须保持独立状态。预读不会占用内容任务的消费额度。
|
||||
|
||||
## 存储选型
|
||||
|
||||
第一阶段保留现有本地向量和 FTS 架构，在业务数据库增加图谱索引或独立的图谱表，先验证质量和延迟。当前不建议为了图谱立即迁移 Qdrant 或 Neo4j，避免在检索质量尚未有评测数据时增加运维单点。
|
||||
|
||||
当图谱边和实体规模、并发写入或多租户查询超过本地数据库能力时，再将图谱迁移到 Neo4j/ Memgraph 或 PostgreSQL 图扩展；迁移必须保留 `source_chunk_ids`、版本和权限字段，并提供只读回退。
|
||||
|
||||
向量库迁移到 Qdrant只在以下条件满足时进行：现有向量召回 P95 持续超标、索引更新阻塞检索、或需要多副本高并发。迁移前先用同一批标注问题做 Recall@10、MRR、NDCG 和 P95 对比。
|
||||
|
||||
## 稳定性和降级
|
||||
|
||||
- 图谱不可用：回退向量 + FTS + RRF；
|
||||
- Cross-Encoder 未加载：回退 RRF；
|
||||
- FTS 索引预热中：先返回向量召回并标记状态；
|
||||
- AI 抽取超时：保留原文和已完成图谱，任务可续跑；
|
||||
- 生成超时：保存阶段结果、游标、费用和未完成主题；
|
||||
- 所有后台任务采用原子租约、唯一执行键和幂等写入；
|
||||
- 生产环境不把图谱构建放在 FastAPI 请求线程。
|
||||
|
||||
## 验收方法
|
||||
|
||||
建立 100～300 条人工标注问题，覆盖主题、步骤、先决条件、冲突和跨文件关系。比较改造前后：
|
||||
|
||||
- Recall@10、MRR、NDCG；
|
||||
- 内容段质检通过率、事实错误率、重复率；
|
||||
- 来源可追溯率；
|
||||
- 热态和冷态 P50/P95；
|
||||
- 图谱不可用时的回退成功率；
|
||||
- 增量上传后受影响范围是否正确；
|
||||
- 跨用户、跨组织和分类权限隔离。
|
||||
|
||||
## 实施顺序
|
||||
|
||||
### P0：观测和基准
|
||||
|
||||
保留当前稳定链路，记录候选数量、过滤数量、精排数量、注入 token、引用数量和各阶段耗时，建立标注集。
|
||||
|
||||
### P1：图谱增量底座
|
||||
|
||||
加入实体、关系、证据、版本和抽取任务；先从标题、术语、步骤和引用关系开始，建立局部图谱和来源回溯。
|
||||
|
||||
### P2：图谱路由接入
|
||||
|
||||
训练营导图先用图谱定位主题簇和依赖链，再定点回查；内容任务先用图谱补充查询，再走混合召回。
|
||||
|
||||
### P3：精排与上下文扩展
|
||||
|
||||
启用已部署的本地 Cross-Encoder，接入 parent-child 上下文和 token 预算，做 A/B 评测后调整候选数。
|
||||
|
||||
### P4：规模化
|
||||
|
||||
只有当指标证明当前本地架构成为瓶颈时，再迁移 Qdrant 或独立图数据库，并保留降级路径。
|
||||
@@ -0,0 +1,407 @@
|
||||
# 私域 Agent 内容生产工作台：系统整体架构与功能检查文档
|
||||
|
||||
> 文档用途：给产品、运营、测试和维护人员逐项核对当前系统。内容依据 `/server/app`、`/web/src` 和启动脚本整理，描述的是代码已经实现或明确配置的行为；“待确认”项需要在实际环境中验收。本文不包含管理员密码、API 密钥等敏感信息。
|
||||
>
|
||||
> 代码位置：`server/app/main.py`（FastAPI 路由）、`server/app/models.py`（SQLModel 数据模型）、`server/app/agents`（Agent Runtime）、`server/app/rag`（知识库检索）、`web/src`（React 前端）。
|
||||
|
||||
## 1. 系统边界和运行拓扑
|
||||
|
||||
系统是一个单组织、本地持久化、可通过公网隧道访问的内容生产工作台。浏览器只访问 React 单页应用；前端通过 `/api` 调用 FastAPI；FastAPI 使用 SQLite 保存业务状态，知识库源文件和产物保存在数据目录，向量索引由 RAG 子系统维护。微信 iLink 连接由独立 Node sidecar 持有账号凭据，主 API 只保存哈希和引用。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U[浏览器用户] -->|HTTPS / HashRouter| W[React 工作台]
|
||||
W -->|/api + 会话令牌| A[FastAPI main.py]
|
||||
A --> DB[(SQLite workspace.db)]
|
||||
A --> FS[(data/ kb artifacts ocr models)]
|
||||
A --> R[RAG pipeline]
|
||||
R --> V[(向量/全文索引)]
|
||||
A --> RT[Agent Runtime]
|
||||
RT --> LLM[Provider / 模型]
|
||||
A --> Q[持久任务队列]
|
||||
A --> I[进度 SSE / 轮询]
|
||||
I --> W
|
||||
S[wechat_ilink_sidecar.mjs] -->|本机 127.0.0.1:8765| A
|
||||
S --> WX[官方 iLink 微信协议]
|
||||
CF[cloudflared / ngrok] --> A
|
||||
```
|
||||
|
||||
### 1.1 进程与端口
|
||||
|
||||
| 进程 | 作用 | 默认地址/端口 | 主要数据/日志 |
|
||||
|---|---|---|---|
|
||||
| FastAPI + Uvicorn | 认证、业务 API、任务调度和后台线程 | 开发 `8011`；生产 `8010` | `/tmp/yawan-uvicorn.log`；生产 `server/data` |
|
||||
| React/Vite | 开发预览；生产构建后的静态文件由现有部署方式提供 | 开发通常 `5173` | `web/dist` |
|
||||
| 微信 iLink sidecar | 多账号扫码、收发微信消息、状态回调 | `127.0.0.1:8765` | `/tmp/yawan-wechat-sidecar.log`；按账号隔离的 storage |
|
||||
| cloudflared/ngrok | 把生产 API/前端暴露到公网 | 隧道地址 | `/tmp/yawan-cloudflared.log`、`/tmp/yawan-ngrok.log` |
|
||||
|
||||
### 1.2 环境与存储
|
||||
|
||||
- `YAWAN_ENV=dev` 使用 `server/data-dev`；默认或 `prod` 使用 `server/data`。
|
||||
- `YAWAN_DATA_DIR` 可指定绝对路径，把 `workspace.db`、`kb/`、`artifacts/`、`ocr/`、`models/`、`chroma/` 等整体迁移到外接硬盘。
|
||||
- `YAWAN_CORS_ORIGINS` 控制允许的前端来源；生产默认包含 `https://agent.pducv.cn`。
|
||||
- `DB_PATH`、`KB_DIR`、`ARTIFACTS_DIR`、`OCR_DIR`、`MODELS_DIR` 在 `server/app/config.py` 根据环境动态创建。
|
||||
- 启动时 `init_db()` 建表、执行兼容迁移、恢复未完成的知识片段预留、对账物理文件与索引，并将空质检报告标记为需复检。
|
||||
|
||||
## 2. 用户端功能地图
|
||||
|
||||
侧栏由 `web/src/shell.tsx` 的 `navFor()` 根据权限生成；隐藏侧栏只是第一层保护，`AppRouter.tsx` 的 `FeatureGate` 和后端中间件还会再次校验。训练营导图已经作为内容任务入口的兼容路由保留；技能库和记忆库作为 Agent 与技能页签；标签作为知识库页签。
|
||||
|
||||
| 功能栏 | 页面/路由 | 主要能力 | 主要权限 |
|
||||
|---|---|---|---|
|
||||
| 总览 | `/admin/overview` | 状态、自检、快捷入口、通知 | `read` |
|
||||
| 内容任务 | `/admin/tasks`、`/admin/tasks/:id` | 建任务、导图拆解、逐段生成、质检、组合和交付 | `feature:tasks`、`tasks:*` |
|
||||
| 运行记录 | `/admin/runs` | 运行状态、事件、工具审批、失败恢复 | `feature:runs`、`runs:read` |
|
||||
| 操作日志 | `/admin/audit-logs` | 用户动作审计 | `feature:audit`、`audit:read` |
|
||||
| Agent 与技能 | `/admin/agents`，`?tab=skills|memories` | Agent、技能、记忆、模型工具、数字人身份配置 | `feature:agents`、`agents:*` |
|
||||
| 数字人 | `/admin/digital-humans` | 文档蒸馏、测试、反馈、版本、授权、微信 Bot | `feature:digital-humans`、`digital_humans:read` |
|
||||
| 画布编排 | `/admin/flows` | 节点、边、波次、总监模式、授权 | `feature:flows`、`flows:read` |
|
||||
| 知识库 | `/admin/knowledge` | 建库、上传、去重、分类、预览、检索、消费记录 | `feature:knowledge`、`kb:*` |
|
||||
| 模型管理 | `/admin/settings/providers` | Provider、模型目录、默认模型、连接测试 | `feature:models`、`providers:*` |
|
||||
| 用量分析 | `/admin/settings/usage` | 用量事件、余额、点数发放、配额 | `feature:usage`、`usage:read`、`billing:manage` |
|
||||
| 系统日志 | `/admin/system-logs` | HTTP/应用/任务错误和 Trace | `feature:system-logs`、`system_logs:read` |
|
||||
| 访问控制 | `/admin/settings/access` | 成员、角色、资源授权、全局发布、版本审核 | `feature:access`、`roles/users/audit:manage` |
|
||||
| 功能开关 | `/admin/settings/flags` | 读取和修改应用功能开关 | `feature:flags`、`flags:read` |
|
||||
| 运营看板 | `/admin/ops` | 指标、告警、备份、死信队列 | `feature:ops`、`ops:*` |
|
||||
| 操作手册 | `/admin/manual` | 面向普通用户的使用说明 | 登录后可见 |
|
||||
|
||||
## 3. 认证、组织和权限模型
|
||||
|
||||
### 3.1 登录链路
|
||||
|
||||
1. `GET /api/auth/status` 检查是否需要首次初始化。
|
||||
2. 首次使用 `POST /api/auth/bootstrap` 创建管理员；之后使用 `POST /api/auth/login`。
|
||||
3. 服务端生成不透明会话令牌，数据库只保存 SHA-256 哈希（`AuthSession`），默认有效期 12 小时。
|
||||
4. 浏览器把令牌放入 API 请求的 `Authorization` 头；退出调用 `POST /api/auth/logout` 撤销会话。
|
||||
5. `GET /api/auth/me` 返回当前用户、角色、组织和权限，前端据此渲染页面。
|
||||
|
||||
### 3.2 内置角色
|
||||
|
||||
- **管理员 admin**：`*` 全部权限，仍受组织边界约束。
|
||||
- **编辑 editor**：内容任务、Agent/画布、知识库、数字人查看、运行和日志等日常生产权限。
|
||||
- **审查 reviewer**：查看和审查任务、知识库、记忆，不含配置和生产写入权限。
|
||||
- **只读 viewer**：只能查看被允许的知识库内容。
|
||||
|
||||
角色存储在 `AppUser.role`，可维护的角色集合存储在 `RoleDefinition.permissions`。权限目录按“内容生产、资产与知识、数据与洞察、系统管理”等抽屉分组，仅改变展示方式，不改变已保存 key。
|
||||
|
||||
### 3.3 访问判定顺序
|
||||
|
||||
1. HTTP 中间件确认 `/api` 请求已认证；微信回调为特例，必须在接口内用账号密钥校验。
|
||||
2. `required_permission()` 校验方法和路径所需操作权限。
|
||||
3. `feature_permissions()` 校验功能栏权限。
|
||||
4. 资源访问函数（`require_kb`、`require_skill`、`require_canvas`、`require_memory` 等）校验组织、所有者、可见性和成员授权。
|
||||
5. 组织 ID：`0` 表示全局资源；正整数表示租户。数据库迁移会添加索引和触发器，阻止非法组织值落库。
|
||||
|
||||
### 3.4 可见性和授权
|
||||
|
||||
资源具有 `private/shared/global` 三种可见性。所有者可以管理自己的资源；共享资源通过 `*Grant` 表按 `read/use/manage/export` 授权；全局资源对普通用户只允许查看和使用，不能导出或修改全局本体。普通用户对全局资源的修改/删除写入 `ResourceRevision`，管理员审核后才合并。`ResourceFork` 记录个人副本与全局源的版本基线。
|
||||
|
||||
## 4. 数据模型和绑定关系
|
||||
|
||||
### 4.1 核心实体
|
||||
|
||||
| 实体 | 表 | 关键字段/职责 |
|
||||
|---|---|---|
|
||||
| 组织 | `Organization` | 租户名称、slug、启用状态 |
|
||||
| 用户/角色/会话 | `AppUser`、`RoleDefinition`、`AuthSession` | 本地账号、PBKDF2 密码摘要、RBAC、可撤销登录 |
|
||||
| Agent | `Agent` | 角色类型、标签、知识库 ID/分类、融合 Agent、模型、工具、规则、数字人、发布快照 |
|
||||
| 技能 | `AgentSkill`、`AgentSkillBinding`、`AgentSkillGrant` | 技能指令、版本、挂载 Agent、成员授权 |
|
||||
| 数字人 | `DigitalHuman`、`DigitalHumanGrant` | 十一维人格档案、蒸馏元数据、版本、来源文件和授权 |
|
||||
| 微信账号 | `WeChatBotAccount` | 所有者、组织、Agent、状态、二维码、凭据哈希/引用 |
|
||||
| 画布 | `Canvas`、`CanvasGrant` | 节点 Agent、边、总监 Agent/模式、授权 |
|
||||
| 知识库 | `KnowledgeBase` | 源目录、索引状态、文件/片段计数、分段策略、所有权 |
|
||||
| 分类/文件 | `KnowledgeCategory`、`KnowledgeFile` | 无限层级分类、AI 推荐分类、文件哈希和 revision |
|
||||
| 消费记录 | `KnowledgeUsage` | Agent+知识库+片段唯一锁、引用、状态、禁用标记 |
|
||||
| 任务/内容段 | `Campaign`、`Segment` | 导图原文、画布快照、段级 Agent、状态、锚点、引用、历史版本 |
|
||||
| 质检/产物 | `QCReport`、`Artifact` | 结构/内容/风格/跨稿质检，组合成稿和下载预览 |
|
||||
| 运行 | `CampaignRun`、`RunEvent`、`AgentSession`、`TaskQueueItem` | 可恢复执行、进度事件、工具调用会话、租约/重试/死信 |
|
||||
| AI 用量 | `LLMCall`、`UsageEvent`、`PointAccount`、`PointTransaction`、`UsageQuota` | 调用追踪、不可变计量、余额流水和配额 |
|
||||
| 日志/通知/记忆 | `AuditLog`、`SystemLog`、`Notification`、`PendingMemory`、`Memory` | 用户动作、系统故障、待读提醒、Agent 长期记忆 |
|
||||
| 版本提案 | `ResourceRevision`、`ResourceFork` | 全局资源个人修改、删除提案及冲突基线 |
|
||||
|
||||
### 4.2 绑定关系（当前代码语义）
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
APP_USER ||--o{ AGENT : owns
|
||||
APP_USER ||--o{ KNOWLEDGE_BASE : owns
|
||||
APP_USER ||--o{ DIGITAL_HUMAN : owns
|
||||
AGENT }o--o{ AGENT_SKILL : mounts
|
||||
AGENT }o--o{ KNOWLEDGE_BASE : reads
|
||||
AGENT }o--o{ AGENT : fusion
|
||||
AGENT }o--|| DIGITAL_HUMAN : identity
|
||||
CANVAS }o--o{ AGENT : nodes
|
||||
CAMPAIGN }o--|| CANVAS : snapshot
|
||||
CAMPAIGN ||--o{ SEGMENT : contains
|
||||
SEGMENT }o--|| AGENT : assigned
|
||||
SEGMENT }o--o{ KNOWLEDGE_BASE : consumes
|
||||
AGENT ||--o{ MEMORY : accumulates
|
||||
CAMPAIGN_RUN ||--o{ RUN_EVENT : emits
|
||||
CAMPAIGN_RUN ||--o{ AGENT_SESSION : resumes
|
||||
LLM_CALL ||--o| USAGE_EVENT : measured
|
||||
```
|
||||
|
||||
- **Agent→知识库**：`Agent.kb_ids` 和 `kb_category_ids` 保存挂接及分类范围；任务创建时运行快照冻结，生成时不读取后来新增的未授权库。
|
||||
- **Agent→技能**：`AgentSkillBinding` 多对多；任务快照记录技能指令。
|
||||
- **Agent→数字人**：`Agent.digital_human_id` 绑定身份；运行时数字人人格优先于 Agent 的 `persona_json`。
|
||||
- **Agent→记忆**：`Memory.agent_id` 归属 Agent；记忆候选按用户、组织、画布范围过滤并冻结到运行快照。
|
||||
- **画布→Agent/知识/记忆**：画布节点保存 Agent；画布授权只连带允许依赖资源的读/用，不放大编辑、删除、导出权限。
|
||||
- **内容任务→画布**：`Campaign.canvas_snapshot` 是创建时快照，之后修改画布不会改变历史任务。
|
||||
- **知识库消费隔离**：`KnowledgeUsage` 唯一约束为 `(agent_id,kb_id,chunk_id)`，不同 Agent 的消费互不锁定；`banned=true` 的片段永久排除检索。
|
||||
- **微信账号→Agent**：一个 `WeChatBotAccount.agent_id` 绑定一个 Agent；sidecar 收到消息时把账号 ID、Agent ID、会话 ID 一并回传，后端再次校验所有权和授权。
|
||||
|
||||
## 5. Agent 与技能工作区
|
||||
|
||||
### 5.1 Agent 配置
|
||||
|
||||
可创建、编辑、停用、发布和删除非内置 Agent。职责类型代码为 `production`、`training_map`、`qc`、`service`、`coordinator`、`composer`。生产 Agent 可配置内容标签和融合 Agent；知识库可以限定到分类；模型可跟随全局默认或指定 Provider/目录模型；`allowed_tools` 控制 Runtime 工具。
|
||||
|
||||
发布接口 `POST /api/agents/{id}/publish` 调用快照冻结逻辑，将规则、模型、技能、知识边界和记忆候选固化到 `runtime_snapshot`。任务创建又会把该快照复制到 `Segment.runtime_snapshot`，保证生成中途修改配置不会改变本次任务。
|
||||
|
||||
### 5.2 技能和记忆
|
||||
|
||||
技能支持 Markdown 导入（`POST /api/skills/import`）、版本和 Agent 多选挂载；技能自身可以按成员授权。记忆分为 L1 规则、L2 纠错、L3 偏好、L4 成功等层级，先进入 `PendingMemory`，审批后写入 `Memory`。Runtime 在模型真正调用前记录注入记忆的次数，避免恢复会话重复计量。
|
||||
|
||||
### 5.3 删除与绑定检查（现状和验收点）
|
||||
|
||||
当前删除接口会先检查引用关系：被画布节点、融合 Agent、历史任务或其他资源引用的 Agent/技能/知识库/记忆/数字人可能被拒绝删除，前端会提示先解绑。产品要求“弹出一键解绑所有后再删除”时，验收应确保：
|
||||
|
||||
- 明确列出将解除的绑定（Agent、技能、画布节点、知识库分类、数字人、记忆、微信账号等）。
|
||||
- 一键操作在同一事务或可恢复事务中完成；失败不得留下半解绑状态。
|
||||
- 历史任务的快照、日志、质检和账单保留，不因删除配置而丢失。
|
||||
- 全局资源的普通用户操作仍只能建立个人 `ResourceRevision`，不能直接解绑全局本体。
|
||||
- 删除微信账号先停止 sidecar 实例、清理二维码和凭据引用，再删除数据库记录。
|
||||
|
||||
## 6. 数字人蒸馏和微信 iLink
|
||||
|
||||
### 6.1 蒸馏流程
|
||||
|
||||
1. `POST /api/digital-humans/distill` 上传或选择文档，服务端抽取代表性样本。
|
||||
2. `_dh_distill()` 生成 `persona` 与 `persona_meta`，记录来源文件、覆盖范围和不确定性，状态为 `testing` 或 `distilling`。
|
||||
3. `POST /api/digital-humans/{id}/test-write` 进行人工试写；`/redistill` 根据反馈提升版本号。
|
||||
4. 补充素材通过 `/redistill` 上传并生成待测试新版本；微信对话不会自动写入数字人人格。
|
||||
5. 创建数字人时自动生成同名默认 Agent 并绑定；后续可继续创建多个 Agent 绑定同一数字人，运行时把人格档案合并进系统提示。
|
||||
|
||||
### 6.2 iLink 账号流程
|
||||
|
||||
- 前端数字人页调用 `POST /api/wechat/bot/accounts/connect`，后端生成账号级密钥（只保存哈希）并转发到 `YAWAN_WECHAT_ADAPTER_URL`。
|
||||
- sidecar 使用 `@wechatbot/wechatbot`、Node 22 和每账号独立 storage 目录；登录回调把 `pending_qr`、`connected`、`error`、`disconnected` 和二维码状态回传 API。
|
||||
- 微信消息签名为 HMAC-SHA256，后端验证时间戳、账号密钥、账号状态、Agent 绑定、组织和所有者；会话按账号/用户/Agent 隔离。
|
||||
- 删除调用 `DELETE /api/wechat/bot/accounts/{id}`，sidecar 停止对应 Bot 并回调断开。
|
||||
- 生产环境需要 `.env.production` 中的 `YAWAN_WECHAT_ADAPTER_URL=http://127.0.0.1:8765`，并由 `守护隧道.sh` 检查 8765 端口自动拉起。
|
||||
|
||||
## 7. 知识库、索引和检索
|
||||
|
||||
### 7.1 导入链路
|
||||
|
||||
支持 `.doc/.docx/.srt/.md/.txt/.json/.jsonl/.pdf` 以及音视频转写后索引。大文件走 `uploads/init`、分片上传、`uploads/{id}/finish`；目录导入走 `import-folder`。文件落盘后计算 `content_hash`，同内容文件跳过，重复片段在索引阶段去重。`KnowledgeFile.revision` 在同名内容变化时递增。
|
||||
|
||||
```text
|
||||
上传/分片 → 文件哈希和去重 → 文本解析或媒体转写 → 分段
|
||||
→ Embedding → 向量/全文索引 → 后台预热 → ready
|
||||
```
|
||||
|
||||
`index_status`：`empty`、`indexing`、`ready`、`needs_reindex`、`error`。启动对账会比较磁盘文件、文件表和向量计数；不会因为对账自动重建大库。
|
||||
|
||||
### 7.2 分类和预览
|
||||
|
||||
`KnowledgeCategory` 为无限层级树；文件同时保存人工分类 `category_id` 和 AI 建议 `ai_category_id`、置信度、理由。`POST /api/kbs/{kid}/classify` 批量推荐，`.../classification/confirm` 人工确认。知识库页签提供文件、分类、检索测试、消费记录和设置；文件查看走预览接口，管理员可查看全部消费记录，普通用户只返回自己有权看到的记录。
|
||||
|
||||
### 7.3 检索模式
|
||||
|
||||
- **full**：选定知识库/分类的全部已索引资料分批阅读/检索，时间和用量较高。
|
||||
- **quick**：按查询相关性召回，适合快速生成。
|
||||
- **reuse**：复用已阅读缓存，减少重复解析和模型调用。
|
||||
|
||||
RAG 管道包含查询校验、Embedding、召回、去重、消费锁和后处理，并记录阶段耗时和缓存命中率；`/api/kbs/{kid}/search` 和 `/api/kbs/search` 提供检索测试。知识片段消费状态为 `reserved`、`consumed`、`available`，进程启动会归还中断留下的 `reserved`。
|
||||
|
||||
## 8. 内容任务和训练营导图
|
||||
|
||||
### 8.1 创建和拆解
|
||||
|
||||
`POST /api/campaigns` 创建任务并保存导图文本、所选画布快照、知识库范围和 Agent；`POST /api/campaigns/{cid}/parse` 调用 coordinator 将导图拆为 `Segment`。每段包含节点、标题、时间范围、标签、指定 Agent、知识分类限制和运行快照。拆解失败可由 `POST /api/campaigns/{cid}/reparse` 重新拆解。
|
||||
|
||||
训练营导图 API 位于 `server/app/training_map.py`，核心输入包括主题、至少一个知识库、可选分类、天数和 Agent。严格模型校验：天数连续、节点标题和叶子内容去重、每个叶子必须有证据来源；导图节点只保留框架短语，详细正文在内容任务生成。导图建议支持整套方案、单天、单日导图和全部导图修改，生成阶段支持进度事件。
|
||||
|
||||
全库评估采用分层摘要：原始片段按库分批阅读并递归归并；同一组织、用户、主题、知识库/分类范围及模型签名下，完全相同批次会写入 `training-corpus/summary-cache.sqlite`，后续草稿或重试可增量复用，缓存使用 WAL、忙等待和单批次文件锁避免并发重复调用。通用全文预读仍使用按知识库隔离的 `training-knowledge` 清单；两类缓存均不写入 `KnowledgeUsage` 消费账本。
|
||||
|
||||
### 8.2 连续生成和跳过
|
||||
|
||||
任务运行使用 `CampaignRun`、`Segment.status` 和锚点卡：上游段产出 `anchor_card`，下游只接收摘要和最后确认段结尾，避免重复全文。跳过段会被记录为 `skipped`，后续段不能假设用户已经学会该前置知识，需要补足最小前提。段状态包括 `pending/running/qc/human_review/approved/rework/failed/skipped`。
|
||||
|
||||
逐段操作接口：
|
||||
|
||||
- `POST /api/campaigns/{cid}/segments/{sid}`：新增段。
|
||||
- `PUT /api/campaigns/{cid}/segments/{sid}`：修改 Agent、分类或正文。
|
||||
- `DELETE /api/campaigns/{cid}/segments/{sid}`：删除段。
|
||||
- `POST /api/segments/{sid}/review`：通过、打回或跳过。
|
||||
- `POST /api/segments/{sid}/fix`：提交修改意见并重新生成。
|
||||
- `POST /api/campaigns/{cid}/run-step`：运行下一步。
|
||||
- `POST /api/campaigns/{cid}/run`：启动完整流水线；支持暂停、取消、恢复。
|
||||
|
||||
### 8.3 质检、组合和交付
|
||||
|
||||
质检门包括 `structure`、`content`、`style`、`cross`；报告存放在 `QCReport`，空检查列表在启动迁移时自动标记 FAIL。全部段通过后 `POST /api/campaigns/{cid}/compose` 生成 `Artifact`，支持预览和下载。运行期间每次模型调用都关联 `trace_id`、Agent、段、Provider、模型和用量事件。
|
||||
|
||||
## 9. Agent Runtime、工具和 AI 调用
|
||||
|
||||
Runtime 的系统工具：`knowledge_search`、`read_upstream_anchors`、`read_agent_memory`、`request_handoff`；联网工具 `web_search`、`web_collect` 默认关闭，启用后需人工审批。每个 `AgentSession` 保存消息、工具状态、轮次、阶段和结果，可从检查点恢复；每个运行共享 240 轮模型预算，耗尽即停止并写入事件。
|
||||
|
||||
每次调用的记录路径：
|
||||
|
||||
```text
|
||||
AgentSession → RuntimeContext → LLMCall → UsageEvent → PointTransaction（如结算）
|
||||
↘ RunEvent / Trace / SystemLog
|
||||
```
|
||||
|
||||
模型选择：Agent 可指定 `model_provider_id/model_catalog_id/model_name`，否则跟随 `/api/settings/model-default`。Provider 通过 `/api/providers` 管理，支持连接测试、发现模型、刷新目录和删除；密钥来自配置或本地密钥存储，错误响应经过脱敏处理。
|
||||
|
||||
## 10. 日志、追踪、通知和用量
|
||||
|
||||
### 10.1 日志
|
||||
|
||||
- **AuditLog 操作日志**：记录用户、动作、资源、结果；不记录请求正文、令牌和密钥。典型动作包括登录、建库、上传、建 Agent、改权限、生成任务等。
|
||||
- **SystemLog 系统日志**：记录 HTTP 失败、应用错误、任务失败、RAG/队列异常和 Trace；错误处理中间件会把具体 `detail` 写入日志。级别支持 `INFO/WARNING/ERROR`，前端可按来源、状态和时间查看。
|
||||
- **RunEvent/LLMCall**：运行级工具调用、Agent、模型、重试、耗时和失败原因；用于运行记录和 Trace 详情。
|
||||
|
||||
接口：`/api/audit-logs`、`/api/system-logs`、`/api/llm_calls`、`/api/traces`、`/api/traces/{trace_id}`。
|
||||
|
||||
### 10.2 通知和进度
|
||||
|
||||
`Notification` 记录失败、待审查、记忆待确认等提醒；`GET /api/notifications`、`POST /api/notifications/{id}/read`、`POST /api/notifications/read-all` 支持单条和一键已读。生成进度由 `/api/events/progress`（SSE）和 `/api/events/progress-poll`（轮询）提供，前端 `ProgressToast` 显示 AI 工作阶段。
|
||||
|
||||
### 10.3 用量和点数
|
||||
|
||||
`UsageEvent` 是追加式计量账本，服务类型包括 `llm/embedding/ocr/storage/export/rerank`，具备幂等键、价格版本、输入输出数量和金额分。`PointAccount` 保存余额，`PointTransaction` 保存充值/扣费/调整流水，`UsageQuota` 保存每日/月度 token、金额、存储和并发限制。用户端 `/api/me/usage`、`/api/points/me` 只返回本人；管理员端 `/api/admin/usage/*` 和 `/api/admin/points/*` 可按用户/组织汇总和发放。
|
||||
|
||||
## 11. 任务队列、可靠性和恢复
|
||||
|
||||
`TaskQueueItem` 提供幂等 `task_key`、租约、重试退避和死信状态。`CampaignRun` 的 `checkpoint`、`pause_requested`、`cancel_requested` 支持服务重启后恢复。后台线程负责运行任务、索引、预热和告警；进程启动会回收未完成的知识消费预留和历史异常质检。
|
||||
|
||||
运营接口包括：
|
||||
|
||||
- `GET /api/ops/dashboard`：健康指标。
|
||||
- `POST /api/ops/alerts/sweep`：扫描告警。
|
||||
- `POST /api/ops/dead-letter/{task_id}/requeue`：死信重放。
|
||||
- `GET/POST /api/ops/backup`、`POST /api/ops/backup/drill`：备份和恢复演练。
|
||||
- `GET /api/system/status`、`GET /api/health`：API、RAG、队列等状态检查。
|
||||
|
||||
## 12. 管理员资源发布和版本审核
|
||||
|
||||
管理员资源页按 Agent、技能、知识库、画布、数字人、记忆分别查看授权。对应接口提供成员 grant、撤销、发布全局和导出。普通用户编辑全局资源时，后端创建 `ResourceRevision(operation=update/delete)` 和必要的 `ResourceFork`；管理员通过 `/api/admin/resource-revisions/{id}/approve` 或 `reject` 审核。审核批准后才改变全局资源版本，个人删除只隐藏自己的视图，不影响其他用户。
|
||||
|
||||
## 13. API 分组速查
|
||||
|
||||
### 认证与管理
|
||||
|
||||
`/auth/status`、`/auth/bootstrap`、`/auth/login`、`/auth/logout`、`/auth/me`、`/auth/users`、`/auth/roles`；管理员资源授权集中在 `/admin/{agents,skills,knowledge-bases,canvases,digital-humans,memories}`。
|
||||
|
||||
### Agent、技能、数字人和画布
|
||||
|
||||
`/agents`、`/agents/{id}/publish`、`/agents/{id}/fork`、`/skills`、`/skills/import`、`/skills/{id}/agents`、`/digital-humans/*`、`/canvases`、`/canvases/{id}/fork`。
|
||||
|
||||
### 知识库和上传
|
||||
|
||||
`/kbs`、`/kbs/{id}`、`/kbs/{id}/categories`、`/kbs/{id}/files/*`、`/kbs/{id}/classify`、`/kbs/{id}/search`、`/kbs/search`、`/uploads/init`、`/uploads/{id}/chunk/{index}`、`/uploads/{id}/finish`、`/kbs/{id}/import`、`/kbs/{id}/rebuild`。
|
||||
|
||||
### 任务与运行
|
||||
|
||||
`/campaigns`、`/campaigns/{id}/parse`、`/campaigns/{id}/reparse`、`/campaigns/{id}/segments/*`、`/campaigns/{id}/run`、`/runs/{id}`、`/agent-sessions/{id}`、`/segments/{id}/review`、`/segments/{id}/fix`、`/campaigns/{id}/compose`、`/artifacts/{id}/preview`。
|
||||
|
||||
### 微信
|
||||
|
||||
`/wechat/bot/accounts`（列表、连接、更新、绑定 Agent、删除）、`/wechat/bot/accounts/{id}/callback`（sidecar 状态回调）、`/wechat/bot/reply`（签名消息转发）。
|
||||
|
||||
## 14. 从用户角度的标准操作链
|
||||
|
||||
1. 登录后在“模型管理”确认可用 Provider 和默认模型。
|
||||
2. 在“知识库”建库，上传文件/目录，等待索引状态为“就绪”；必要时执行去重、分类和预览。
|
||||
3. 在“Agent 与技能”创建 Agent，选择职责、挂接知识库/分类、技能、模型和数字人，保存并发布。
|
||||
4. 在“画布编排”用节点和连线编排 Agent；检查每个节点是否有唯一 Agent 和有效知识范围。
|
||||
5. 在“内容任务”粘贴训练营导图/框架，选择画布和知识范围，创建任务并拆解；若失败使用“重新拆解”。
|
||||
6. 查看每个内容段的 Agent、知识引用和锚点；可更换 Agent、修改分类、生成、质检、通过/打回/跳过。
|
||||
7. 全部段通过后组合成稿，在预览页面复核并下载交付。
|
||||
8. 需要微信服务时，在“数字人 → 微信 Bot 连接”选择已配置 Agent，生成二维码，扫码后确认状态为“已连接”。
|
||||
9. 在“运行记录、操作日志、系统日志、用量分析”核对执行、错误、模型调用和余额。
|
||||
|
||||
## 15. 逐项验收清单
|
||||
|
||||
### 账号与权限
|
||||
|
||||
- [ ] 非管理员直接访问无权限路由显示明确中文提示，API 返回 403/404 且不泄露资源存在性。
|
||||
- [ ] 普通用户看不到未授权 Agent、知识库、技能、数字人、记忆和画布。
|
||||
- [ ] 全局资源个人修改/删除生成个人版本提案，不影响其他用户。
|
||||
- [ ] 账号删除是永久删除；停用只改变 `enabled`，两者按钮和审计动作不同。
|
||||
- [ ] 删除有关联资源时可查看依赖，并验证一键解绑事务、历史快照和日志保留。
|
||||
|
||||
### 知识库
|
||||
|
||||
- [ ] 首次打开知识库不会显示旧库残留或短暂的“不存在”；详情加载有明确状态。
|
||||
- [ ] 同内容文件和完全重复片段被跳过，导入结果显示跳过数量。
|
||||
- [ ] 子分类有文件时父分类计数同步；分类树可展开/收起。
|
||||
- [ ] 普通用户消费记录只包含自己可用的 Agent/片段；管理员可按用户筛选。
|
||||
- [ ] 预览按钮返回正确文件标题和正文；大文件不阻塞列表首屏。
|
||||
- [ ] full/quick/reuse 三种检索模式显示估算耗时、进度和失败原因。
|
||||
|
||||
### AI 生成与任务
|
||||
|
||||
- [ ] 导图先输出框架文本，确认后才能进入内容任务；节点标题/叶子内容无重复。
|
||||
- [ ] 导图每天按前置关系递进；跳过内容段后，后续段能看到桥接提示。
|
||||
- [ ] 内容段显示当前 Agent、模型、知识分类和引用来源。
|
||||
- [ ] 拆解失败、生成失败、AI 修改、图片/OCR/预读均有进度条、重试入口和日志。
|
||||
- [ ] 质检四道门均产生可追踪报告；空报告自动判为需复检。
|
||||
- [ ] 运行暂停、取消、恢复后不会重复扣费或重复消费片段。
|
||||
|
||||
### 微信 iLink
|
||||
|
||||
- [ ] 选择 Agent 后二维码出现；扫码成功后二维码隐藏且列表显示“已连接”。
|
||||
- [ ] 已连接账号仍显示删除按钮；删除后 sidecar 实例停止、状态回调断开、刷新不复现。
|
||||
- [ ] 多账号使用不同 storage 目录和账号密钥；账号 A 无法调用账号 B 的 Agent/会话。
|
||||
- [ ] 绑定 Agent 变更实时同步 sidecar；失效/过期/错误状态能回传并允许重新扫码。
|
||||
|
||||
### 可靠性与部署
|
||||
|
||||
- [ ] 生产只使用 `data/`（或明确的 `YAWAN_DATA_DIR`），开发只使用 `data-dev/`。
|
||||
- [ ] 后端、sidecar、隧道守护进程均可单独重启；502/1033 时日志能定位是 API、隧道还是 sidecar。
|
||||
- [ ] 启动后未完成运行、片段预留和索引状态能正确恢复或标记。
|
||||
- [ ] 生产构建通过 `npm run build`，前端动态模块版本与静态资源缓存一致。
|
||||
|
||||
## 16. 当前限制和风险边界
|
||||
|
||||
- SQLite + NullPool 适合单机/中小规模；多实例横向扩展前需要共享数据库、对象存储和队列，不能直接把本地文件目录挂到多个实例。
|
||||
- iLink sidecar 依赖 Node.js 22 和 `@wechatbot/wechatbot`；官方适配器不可用时只会显示配置/连接错误，不能在浏览器端直接完成协议登录。
|
||||
- 本地向量和全文索引路径由 `server/app/rag` 管理；若切换 Qdrant 等外部服务，需要同步配置、迁移和故障回退策略，当前代码仍保留本地存储能力。
|
||||
- AI 输出受模型可用性、点数余额、Runtime 轮次预算和知识索引状态影响；任何“全库阅读”都可能显著增加时间和用量。
|
||||
- 日志会对密钥、令牌和请求正文脱敏；若需要排查具体模型错误，应使用 Trace ID、Provider 状态和服务端原始日志，而不是把密钥写入前端提示。
|
||||
|
||||
## 16.1 性能基线与运行维护
|
||||
|
||||
- SQLite 连接统一启用 WAL、`busy_timeout=30000`、`synchronous=NORMAL` 和外键约束，并建立日志、知识库文件/分类/消费、授权、运行事件、队列等复合索引。
|
||||
- 知识片段消费预留、确认和释放使用批量查询/`executemany`，减少逐片段 SQL 往返和写锁竞争。
|
||||
- RAG 检索记录校验、Embedding、召回、后处理和总耗时，并保留缓存命中率；缓存键包含知识库版本、范围、模型和检索参数。
|
||||
- 管理员可调用 `GET /api/ops/performance` 查看最近 512 次 API 的 P50/P95/P99、慢接口、状态分布及 RAG 阶段指标。该指标为进程内基线，重启后重新采样。
|
||||
- 启动阶段只做必要初始化；知识库文件对账和全文索引预热由后台维护线程执行，避免大库扫描阻塞首屏和健康检查。
|
||||
- 生产守护脚本使用单实例锁，避免重复守护进程同时启动后端，降低内存争抢和 SQLite 写锁风险。
|
||||
- 普通 INFO/DEBUG/WARNING 系统日志与 AI 观测日志进入有界批量队列（最多 1000 条、每批 100 条、最长 1 秒刷盘）；ERROR、关键审计、计量账本和任务状态仍同步写入。队列丢弃/失败计数可通过性能指标追踪，进程优雅退出会先刷盘。
|
||||
- 性能指标现在通过匿名指标信封从 RAG 子进程回传 API 进程，包含 SQL 次数、SQL 耗时、锁错误、RAG 各阶段耗时和错误样本，避免把查询正文、令牌或原始路径写入指标。
|
||||
- 当前任务队列仍是旁路记录，内容生成/导图/上传依赖进程内线程和内存进度总线；外部 Worker 尚未启用。直接启用会造成重复执行和 SSE 进度丢失，必须先完成原子租约认领、持久化进度游标及唯一执行模式切换。
|
||||
- 2026-09-13 基线（本机冷启动、37 段产品信息库）：首次检索约 3.37 秒，其中 Embedding 约 2.93 秒、召回约 0.41 秒；相同查询命中缓存约 6 毫秒。该样本不能代表 9.8 万段以上大库，需在空闲、内容生成和索引运行中分别采样 P50/P95/P99。
|
||||
- Worker 审计结论：`TaskQueueItem.lease_next` 当前不是原子认领，且内容任务入队后仍由内存线程直接执行；上传、拆解、导图和 SSE 也依赖进程内状态。因此暂不启用内容生成外部 Worker，下一安全阶段仅考虑可幂等的 FTS 预热；迁移前需先完成原子租约、唯一执行模式、持久化进度游标和幂等验收。
|
||||
- 2026-09-13 Embedding 诊断已细分为模型加载、Tokenizer、Encode 推理、向量后处理/序列化、进程启动和 IPC 残差，并记录来源、数量、模型版本、维度、PID、缓存命中及 Worker 是否复用。管理员性能接口会聚合这些阶段的 P50/P95；`embedding_count` 可识别 quick 检索误做批量向量化。
|
||||
- 查询向量 LRU 与检索候选池缓存已分离：向量缓存只依赖规范化 query、模型/版本和策略（模型版本代表向量维度契约）；候选池缓存包含知识库/分类文件范围、权限签名、索引版本、检索模式和 top-k。知识库版本变化只影响候选池，避免无关地清空查询向量。
|
||||
- 2026-09-13 热态未命中采样（单库产品信息，15 条不同 query）：首条冷启动约 4.17 秒，其中模型加载约 3.06 秒；模型常驻后总耗时 P50 约 15.93ms、P95 约 25.84ms，Embedding P95 约 16.70ms，Encode P95 约 16.59ms，召回 P95 约 4.30ms，`embedding_count=1` 且 15 条均未命中查询缓存。六库联合采样（约 15 万段）首条冷启动约 7.48 秒，热态未命中约 0.66～0.78 秒，主要耗时在多库召回而非 Embedding。
|
||||
- 查询缓存复测确认：同 query、同 top-k 第二次命中候选池约 17ms；改变 top-k 后候选池重新计算约 45ms，但查询向量缓存命中、Embedding 耗时约 0ms。缓存键已修复首次维度从未知切换到 512 导致的伪未命中问题。
|
||||
- 2026-09-13 六库召回稳定性优化：召回线程池改为进程内固定 4 个 Worker，避免每次请求创建线程并限制高并发时的磁盘争用；只读 FTS 索引使用带 inode/版本校验的共享连接、页缓存和 mmap，索引原子替换后自动重连。新增 `fts_connection_reused` 指标，用于区分连接复用与索引自身耗时。
|
||||
- 2026-09-13 六库热态未命中复测（生产 6 库）：Embedding 已常驻后约 14～129ms，召回约 0.64～0.91 秒；瓶颈集中在心法、情欲内容的大型 FTS 索引（约 461MB/862MB）和对应向量 I/O，模型加载不再是稳态瓶颈。后续优先做大库索引体积与查询词规模优化，暂不切换模型或向量数据库。
|
||||
- 2026-09-13 向量查询进一步优化：移除检索热路径上的 `collection.count()`。该调用在外置盘冷读时，108135 段库约 1.7 秒，而实际向量查询约 20ms；Chroma/Qdrant 对空集合均直接返回空结果，因此无需先 count。检索指标现在只记录 collection、filter、vector 三段真实 I/O。
|
||||
- 2026-09-13 空闲态 10 条不同 query 只读采样：P50 约 556ms，P95 约 1.25s；首条冷启动约 6.43s，后续 Embedding 约 6～345ms。4 路并发只读采样全部完成，未再出现 `database is locked`；高并发仍受单个常驻 RAG Worker 的队列容量限制，继续保持单 Worker 以控制内存峰值。
|
||||
- 2026-09-13 稳定性修复：Embedding 用量事件改为独立短事务提交，计量写入失败只记录告警，不再让知识库检索失败；避免内容任务并发时主业务事务与用量写入互相持有 SQLite 写锁。
|
||||
- 计量短事务设置 500ms 忙等待上限；数据库暂时繁忙时只丢弃本次非关键计量并保留检索结果，避免用户看到 30 秒级假性超时。
|
||||
|
||||
## 17. 检查记录模板
|
||||
|
||||
| 检查日期 | 环境（dev/prod） | 页面/API | 操作步骤 | 预期 | 实际 | Trace/截图 | 结论 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| | | | | | | | |
|
||||
|
||||
维护此文档时，应以代码中的模型字段、路由和权限 key 为准；新增功能同时补充“功能地图、数据模型、API、权限、验收清单”五个位置。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 前端重构迁移清单（阶段0盘点结论）
|
||||
|
||||
## 现状
|
||||
- React 18 + Vite 5 + TS 5.5；无路由库（手写 window.history + tab state）；图标全用字符/emoji
|
||||
- 已装：react-router-dom 7.18、lucide-react 1.39（6143 图标可用）
|
||||
- 14 个入口平铺侧栏；TasksPage 468 行单文件含列表+详情；KBsPage 370 行；CanvasPage 292 行
|
||||
- api.ts（151 行）封装 fetch + token；progress.tsx SSE 进度；dialog.tsx 对话框；ui.tsx Tag/边界
|
||||
- 登录入口 /admin /app 双门户；后端 API 契约 158 端点不动
|
||||
|
||||
## 新路由映射（旧 tab → 新路由）
|
||||
| 旧 | 新 |
|
||||
|---|---|
|
||||
| overview | /admin（工作台首页）|
|
||||
| tasks | /admin/tasks（内容任务列表）|
|
||||
| tasks 详情内联 | /admin/tasks/:id（页签：内容段/运行轨迹/最终成稿/配置快照）|
|
||||
| ops | /admin/ops（并入工作台二级）|
|
||||
| canvas | /admin/flows（画布）|
|
||||
| agents | /admin/agents（列表）+ /admin/agents/:id（详情五页签）|
|
||||
| skills | /admin/agents?tab=skills（智能体模块内页签）|
|
||||
| prompt-templates | /admin/agents?tab=prompt-templates |
|
||||
| kbs | /admin/knowledge（列表）+ /admin/knowledge/:id（页签：文件/分类/检索测试/消费记录/设置）|
|
||||
| tags | /admin/knowledge?tab=tags |
|
||||
| models | /admin/settings/providers |
|
||||
| access | /admin/settings/access（页签：成员/角色权限/资源授权/登录安全）|
|
||||
| logs | /admin/runs（页签：通知/待确认/运行记录）+ /admin/runs/:id（Trace 详情）|
|
||||
| memories | /admin/agents?tab=memories |
|
||||
| usage | /admin/settings/usage（用量）+ 点数发放并入 access 或独立 /admin/settings/billing |
|
||||
|
||||
## 一级导航（5 项）
|
||||
1. 工作台 LayoutDashboard → /admin（含运营数据）
|
||||
2. 内容任务 ListChecks → /admin/tasks
|
||||
3. 智能体 Bot → /admin/agents（页签：Agent/技能/提示模板/记忆）+ /admin/flows（画布）+ /admin/runs（运行）
|
||||
4. 知识资产 Database → /admin/knowledge（页签：知识库/标签）
|
||||
5. 系统管理 Settings → /admin/settings/providers|access|usage
|
||||
|
||||
## 分阶段实施
|
||||
- P1 路由骨架 + AppShell（240px 侧栏/56 顶栏/移动抽屉）+ 导航迁移：保持旧页面组件原样挂进新路由
|
||||
- P2 TasksPage 拆列表页+详情页（页签）；AgentsPage 拆 320px 列表+详情；LogsPage 拆页签+服务端分页
|
||||
- P3 KBsPage 详情页签+文件列表；CanvasPage 工具栏+节点库+属性检查器+修复 0 节点 bug；AccessPage 四页签
|
||||
- P4 Skills/Templates/Tags 抽屉化；Models/Usage 口径修复；lucide 图标替换；视觉统一（14px/12px/8px 圆角/单主按钮）
|
||||
- 每阶段保持旧功能可运行 + tsc/build 过 + 浏览器走查
|
||||
@@ -0,0 +1,12 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>私域Agent</title>
|
||||
</head>
|
||||
<body>
|
||||
<div id="root"></div>
|
||||
<script type="module" src="/src/main.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,85 @@
|
||||
# 修复融合版变更说明（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）
|
||||
|
||||
```bash
|
||||
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/`（数据库、知识库、向量索引）不包含在本包内，部署时需重新初始化或单独迁移。
|
||||
+1124
File diff suppressed because it is too large
Load Diff
+780
@@ -0,0 +1,780 @@
|
||||
# 雅文内容创造工作台 · 核心逻辑设计文档 v6
|
||||
|
||||
> 文档日期：2026-08-26
|
||||
> 关联文档：[设计文档 v5](./设计文档v5-系统设计.md)、[设计文档 v6：用户端、管理端与云化设计](./设计文档v6-用户端管理端云化与计费设计.md)
|
||||
> 从零落地：[核心逻辑设计文档 v6：从 0 到 1](./核心逻辑设计文档v6-从0到1.md)
|
||||
> 文档用途：说明系统如何运行、数据如何流转、权限如何隔离，以及 v6 多用户云化能力如何接入现有 Runtime
|
||||
> 说明：本文件是逻辑设计文档；其中“当前实现”对应现有源码，“v6 目标”对应 v6 设计，不能把规划功能当作已上线功能
|
||||
|
||||
## 0. 一句话理解系统
|
||||
|
||||
雅文内容创造工作台是一个以 **任务为中心、Agent 为执行单元、知识库为事实来源、记忆库为经验来源、模型目录为受控能力、Trace 为审计链路** 的内容生产系统。
|
||||
|
||||
完整逻辑可以概括为：
|
||||
|
||||
```text
|
||||
用户请求
|
||||
→ 权限和配额校验
|
||||
→ 冻结任务配置
|
||||
→ Agent 画布拓扑调度
|
||||
→ 只检索允许使用的知识与记忆
|
||||
→ Agent Runtime 生成内容
|
||||
→ QC 质检
|
||||
→ 人工审查
|
||||
→ 组合 Agent 统一成稿
|
||||
→ 云存储交付
|
||||
→ 用量计量、账单和 Trace 归档
|
||||
```
|
||||
|
||||
## 1. 核心原则
|
||||
|
||||
### 1.1 数据归属优先
|
||||
|
||||
任何资源都先确定归属，再决定谁能看、谁能用、谁能改：
|
||||
|
||||
```text
|
||||
organization_id
|
||||
→ owner_user_id
|
||||
→ resource_type + resource_id
|
||||
→ visibility / grant / permission
|
||||
```
|
||||
|
||||
用户、Agent、任务、知识库、记忆、模型选择、Trace、产物和账单都必须绑定组织与用户。没有归属键的数据不能进入生产链路。
|
||||
|
||||
### 1.2 配置先冻结，运行后复现
|
||||
|
||||
任务开始前冻结：
|
||||
|
||||
- 画布节点和连线。
|
||||
- Agent 规则、规则版本和规则哈希。
|
||||
- Agent 挂接的技能、知识库和记忆。
|
||||
- Provider、模型、模型能力标签和费率版本。
|
||||
- 内容段、上游锚点和任务参数。
|
||||
|
||||
任务运行过程中修改管理端配置，只影响后续新任务；当前任务始终使用自己的快照。
|
||||
|
||||
### 1.3 知识与记忆不能越权
|
||||
|
||||
检索服务必须先计算用户可访问的资源集合，再执行向量检索：
|
||||
|
||||
```text
|
||||
allowed_kb_ids
|
||||
= owned_kb_ids
|
||||
∪ granted_kb_ids
|
||||
∪ global_kb_ids
|
||||
|
||||
allowed_memory_ids
|
||||
= owned_memory_ids
|
||||
∪ granted_memory_ids
|
||||
∪ global_memory_ids
|
||||
```
|
||||
|
||||
不能先搜索全库再由前端过滤。Agent 只能使用任务快照中允许的知识库和记忆。
|
||||
|
||||
### 1.4 事实必须可追溯
|
||||
|
||||
每个知识片段、模型调用、工具调用、质检结果和最终产物，都要能回溯到：
|
||||
|
||||
```text
|
||||
组织 → 用户 → 任务 → Run → Trace → Segment / Agent → 资源或模型
|
||||
```
|
||||
|
||||
没有来源的事实不能标记为已验证内容；没有 Trace 的模型调用不能计入已完成任务。
|
||||
|
||||
### 1.5 失败必须显式化
|
||||
|
||||
失败不等于空结果，等待不等于成功，Provider 返回 200 也不等于内容有效。系统必须区分：
|
||||
|
||||
- Provider 错误、网关拦截、模型拒绝、超时、限流。
|
||||
- RAG 无命中、索引损坏、文件解析失败。
|
||||
- Agent 输出为空、格式错误、护栏失败。
|
||||
- QC FAIL、人工打回、组合总检失败。
|
||||
- 云对象上传失败、导出失败、账单计量失败。
|
||||
|
||||
## 2. 参与者和职责
|
||||
|
||||
| 参与者 | 核心职责 | 不负责的事情 |
|
||||
| --- | --- | --- |
|
||||
| 用户端 | 创建任务、选择已开放模型、使用自己的资源和获授权资源 | 不能接 Provider、不能改费率、不能越权读私有资源 |
|
||||
| 管理端 | 管理用户、Provider、模型目录、知识库授权、记忆授权、配额、计费和导出 | 不绕过审计直接改历史账单 |
|
||||
| Coordinator Agent | 把导图拆成可执行内容段、分配标签和时间范围 | 不直接生成最终长稿 |
|
||||
| Production Agent | 根据任务段、规则、技能、知识和记忆生成内容 | 不使用未挂接资源，不补写无来源事实 |
|
||||
| QC Agent | 按固定检查项审查结构、内容、风格和跨段一致性 | 不替用户默默修改并伪装为通过 |
|
||||
| Composer Agent | 组合已人工通过的段落，执行全文一致性检查 | 不组合未通过或被跳过的段落 |
|
||||
| Agent Runtime | 维护会话、工具、审批、护栏、恢复和 Trace | 不替业务层决定资源权限 |
|
||||
| RAG 服务 | 解析、分块、向量化、检索、引用和消费锁定 | 不决定用户是否有权访问库 |
|
||||
| 计量服务 | 记录 LLM、Embedding、OCR、存储和导出用量 | 不修改原始调用事实 |
|
||||
|
||||
## 3. 核心对象关系
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
ORGANIZATION ||--o{ USER_ACCOUNT : contains
|
||||
USER_ACCOUNT ||--o{ AGENT : owns
|
||||
USER_ACCOUNT ||--o{ KNOWLEDGE_BASE : owns
|
||||
USER_ACCOUNT ||--o{ MEMORY : owns
|
||||
KNOWLEDGE_BASE ||--o{ KNOWLEDGE_FILE : contains
|
||||
KNOWLEDGE_BASE ||--o{ KNOWLEDGE_BASE_GRANT : shares
|
||||
MEMORY ||--o{ MEMORY_GRANT : shares
|
||||
MODEL_PROVIDER ||--o{ MODEL_CATALOG : exposes
|
||||
MODEL_CATALOG ||--o{ MODEL_ORGANIZATION_GRANT : opens
|
||||
AGENT ||--o{ AGENT_SKILL_BINDING : uses
|
||||
AGENT ||--o{ AGENT_KB_BINDING : uses
|
||||
CAMPAIGN ||--o{ CAMPAIGN_RUN : executes
|
||||
CAMPAIGN ||--o{ SEGMENT : contains
|
||||
CAMPAIGN_RUN ||--o{ AGENT_SESSION : starts
|
||||
CAMPAIGN_RUN ||--o{ RUN_EVENT : emits
|
||||
CAMPAIGN_RUN ||--o{ LLM_CALL : records
|
||||
SEGMENT ||--o{ QC_REPORT : checks
|
||||
CAMPAIGN ||--o{ ARTIFACT : produces
|
||||
LLM_CALL ||--o{ USAGE_EVENT : meters
|
||||
```
|
||||
|
||||
## 4. 任务核心逻辑
|
||||
|
||||
### 4.1 任务创建
|
||||
|
||||
任务创建只保存输入和初始选择，不立即调用模型：
|
||||
|
||||
1. 用户填写任务名称、导图或主题。
|
||||
2. 服务端确认用户属于有效组织，且有创建任务权限。
|
||||
3. 用户选择画布；服务端读取画布节点、连线和启停状态。
|
||||
4. 服务端校验 Agent、技能、知识库和模型目录引用。
|
||||
5. 任务进入 `draft`。
|
||||
|
||||
如果用户选择的模型被停用、Provider 已失效、知识库授权已撤销或 Agent 缺少必需知识库，任务创建应返回明确错误，而不是等到模型调用时才失败。
|
||||
|
||||
### 4.2 导图解析
|
||||
|
||||
解析由 Coordinator Agent 完成：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[导图/主题输入] --> B[输入护栏]
|
||||
B --> C[Coordinator Runtime]
|
||||
C --> D[识别内容节点]
|
||||
D --> E[绑定内容标签]
|
||||
E --> F[生成时间范围和任务目标]
|
||||
F --> G[识别产品/下一段/钩子]
|
||||
G --> H[标记不确定项]
|
||||
H --> I[生成 Segment 任务单]
|
||||
```
|
||||
|
||||
Coordinator 必须遵守：
|
||||
|
||||
- 不补写导图没有提供的产品、日期、人物或事实。
|
||||
- 一个 Segment 只承担一个清楚的内容目标。
|
||||
- 每个 Segment 必须有标题、内容标签、时间范围、导图原文和目标 Agent。
|
||||
- 不确定信息写入 `pending_confirms`，不能猜测后直接进入生产。
|
||||
|
||||
### 4.3 运行快照
|
||||
|
||||
创建 Run 时冻结完整配置：
|
||||
|
||||
```text
|
||||
CampaignRun.config_snapshot
|
||||
├── organization / user
|
||||
├── canvas
|
||||
├── segments[]
|
||||
│ └── primary Agent snapshot
|
||||
├── stages
|
||||
│ ├── coordinator
|
||||
│ ├── qc.structure
|
||||
│ ├── qc.content
|
||||
│ ├── qc.style
|
||||
│ ├── qc.cross
|
||||
│ └── composer
|
||||
├── model catalog/version/price
|
||||
└── memory and knowledge access snapshot
|
||||
```
|
||||
|
||||
快照写入后，任务只引用快照，不重新读取用户当前编辑中的规则。这样可以保证审查结果和最终成稿对应同一组配置。
|
||||
|
||||
### 4.4 Run 状态机
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> queued
|
||||
queued --> running
|
||||
running --> awaiting_review
|
||||
running --> failed
|
||||
running --> cancelled
|
||||
awaiting_review --> running: 人工继续/打回重跑
|
||||
awaiting_review --> completed: 所有段已通过并完成组合
|
||||
failed --> queued: 修复后重试
|
||||
cancelled --> queued: 管理员重新排队
|
||||
completed --> [*]
|
||||
```
|
||||
|
||||
同一 Campaign 只能有一个 `queued` 或 `running` 的活跃 Run。Run 取消、失败和恢复都保留原 Trace，不覆盖历史记录。
|
||||
|
||||
## 5. Agent 画布与调度逻辑
|
||||
|
||||
### 5.1 图结构
|
||||
|
||||
- 节点是画布上的执行实例，不是 Agent 定义本身。
|
||||
- `node_id` 标识画布节点，`agent_id` 指向 Agent 定义。
|
||||
- 同一个 Agent 可以放在多个节点上，形成并行或串行的多个实例。
|
||||
- 边 `from_node → to_node` 表示下游读取上游锚点卡。
|
||||
- 未连线的节点不共享上下文。
|
||||
|
||||
### 5.2 波次调度
|
||||
|
||||
服务端对画布执行拓扑排序：
|
||||
|
||||
1. 找到入度为 0 的节点作为第一波。
|
||||
2. 第一波完成后，把其出边节点的入度减一。
|
||||
3. 入度归零的节点进入下一波。
|
||||
4. 同一波次节点并行执行。
|
||||
5. 检测到环时拒绝运行，并提示具体环路。
|
||||
|
||||
节点停用时不会调用模型，下游收到 `skipped` 锚点。停用产品销售节点时，组合器必须知道“本场无产品”，不能自动补一个产品段。
|
||||
|
||||
### 5.3 融合 Agent
|
||||
|
||||
融合 Agent 用于把多个写法合成为一个自然段：
|
||||
|
||||
```text
|
||||
主 Agent 任务
|
||||
├── 心法写法 Agent
|
||||
├── 钩子写法 Agent
|
||||
└── 场景表达 Agent
|
||||
↓
|
||||
融合结果：一个自然口语段 + 一个结构化锚点卡
|
||||
```
|
||||
|
||||
融合时只传递结构化任务、允许的知识引用和上游锚点，不把各 Agent 的内部推理互相暴露。最终文本遵守统一的“大白话、自然口语、默认一段到底”样式，避免拼贴感。
|
||||
|
||||
## 6. Agent Runtime 核心逻辑
|
||||
|
||||
### 6.1 会话循环
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant O as 业务编排器
|
||||
participant R as Agent Runtime
|
||||
participant S as AgentSession
|
||||
participant M as Model Provider
|
||||
participant T as Tool
|
||||
participant E as RunEvent/LLMCall
|
||||
|
||||
O->>R: run_agent(task, snapshot, tools)
|
||||
R->>S: 创建或恢复会话
|
||||
R->>E: runtime_started + input_guardrail
|
||||
R->>M: 发送当前消息和工具定义
|
||||
M-->>R: 文本或 tool_calls
|
||||
R->>E: model_started/model_finished
|
||||
alt 工具调用
|
||||
R->>T: 校验参数并执行
|
||||
T-->>R: 工具结果
|
||||
R->>E: tool_started/tool_finished
|
||||
R->>S: 写入 tool 消息
|
||||
R->>M: 继续下一轮
|
||||
else 最终文本
|
||||
R->>E: output_guardrail
|
||||
R->>S: 写入完成结果
|
||||
R-->>O: completed/failed
|
||||
end
|
||||
```
|
||||
|
||||
### 6.2 会话恢复
|
||||
|
||||
`AgentSession` 保存消息、轮次、工具状态、审批状态、结果和错误。恢复时：
|
||||
|
||||
- 复用 `running`、`interrupted` 或 `waiting_approval` 会话。
|
||||
- 不重复执行已完成工具调用。
|
||||
- `pending_tool` 有审批决定后，先回放批准/拒绝结果，再继续模型循环。
|
||||
- 服务启动时把中断会话标记为可恢复，并归还未完成的知识片段预留。
|
||||
|
||||
### 6.3 工具审批
|
||||
|
||||
需要人工确认的工具调用进入 `waiting_approval`，不会因为接口返回成功就直接执行。审批动作必须记录：
|
||||
|
||||
```text
|
||||
requester session → pending_tool → approver user → decision → tool result
|
||||
```
|
||||
|
||||
工具批准接口只允许具有审查或管理权限的角色调用；工具本身还要在当前阶段的注册表中存在。
|
||||
|
||||
### 6.4 护栏和输出契约
|
||||
|
||||
Runtime 负责通用护栏，业务 Agent 负责领域契约：
|
||||
|
||||
| 层级 | 检查内容 |
|
||||
| --- | --- |
|
||||
| Runtime 输入 | 非空、长度上限、系统规则优先 |
|
||||
| Runtime 工具 | 工具是否注册、参数是否为合法 JSON |
|
||||
| Runtime 输出 | 非空、长度上限、文本可保存 |
|
||||
| Coordinator | Segment 字段完整、未知信息待确认 |
|
||||
| Production | 正文、引用、锚点卡完整 |
|
||||
| QC | 检查项必须带状态和问题说明 |
|
||||
| Composer | 只组合人工通过内容段 |
|
||||
|
||||
## 7. 知识库核心逻辑
|
||||
|
||||
### 7.1 建库管道
|
||||
|
||||
```text
|
||||
上传文件
|
||||
→ 计算内容哈希
|
||||
→ 写入云对象/本地源目录
|
||||
→ 解析格式
|
||||
→ 清洗文本
|
||||
→ 语义分块
|
||||
→ Embedding
|
||||
→ 写入向量索引
|
||||
→ 写入文件分类和版本
|
||||
→ 标记 ready
|
||||
```
|
||||
|
||||
支持 `.docx`、`.srt`、`.md`、`.txt`、`.json`、`.jsonl`。文件更新时先删除同名文件旧向量，再写入新版本，避免重复命中。
|
||||
|
||||
### 7.2 分类逻辑
|
||||
|
||||
分类分为 AI 建议和人工确认：
|
||||
|
||||
```text
|
||||
unclassified
|
||||
→ AI 分类任务
|
||||
→ ai_suggested
|
||||
→ 人工确认/修改
|
||||
→ human_confirmed
|
||||
```
|
||||
|
||||
分类树使用 `parent_id` 支持无限层级。文件保存 `category_id`、AI 建议分类、置信度、原因、内容哈希和修订号。移动文件分类只修改归属元数据，并在下一次增量索引时更新向量元数据中的完整分类路径。
|
||||
|
||||
### 7.3 检索与引用
|
||||
|
||||
Agent 生成前构造检索请求：
|
||||
|
||||
```text
|
||||
任务段目标
|
||||
+ 上游锚点卡
|
||||
+ Agent 规则里的检索意图
|
||||
+ 当前用户允许的知识库 ID
|
||||
+ 当前 Agent 已消费 chunk 排除集合
|
||||
```
|
||||
|
||||
检索结果必须带：知识库、文件、分类路径、chunk ID、原文、相似度、文件哈希和修订号。引用写入 `Segment.references`，并进入 QC 对证。
|
||||
|
||||
### 7.4 知识消费锁定
|
||||
|
||||
消费锁是 Agent 级别，不是全局锁：
|
||||
|
||||
```text
|
||||
Agent A 消费 chunk-001 → A 后续不可重复使用
|
||||
Agent B 未消费 chunk-001 → B 仍可使用
|
||||
```
|
||||
|
||||
状态流转：
|
||||
|
||||
```text
|
||||
available → reserved → consumed
|
||||
reserved → available（任务中断/模型失败）
|
||||
consumed → available（管理员人工释放）
|
||||
```
|
||||
|
||||
数据库对 `(agent_id, kb_id, chunk_id)` 建唯一约束，防止同一个 Agent 并发重复认领同一片段。
|
||||
|
||||
### 7.5 重建和回滚
|
||||
|
||||
重建必须遵循：
|
||||
|
||||
1. 读取当前索引快照。
|
||||
2. 标记 `indexing`。
|
||||
3. 按文件处理并记录进度。
|
||||
4. 所有文件成功后写入 `ready`。
|
||||
5. 任意文件失败时恢复旧快照和旧计数。
|
||||
|
||||
Chroma 不稳定时使用本地原子 JSON 向量文件作为检索兜底。KB3 当前基线为 73 个文件、2,717 个分块、512 维向量，数据库和独立进程读取结果一致。
|
||||
|
||||
## 8. 记忆库核心逻辑
|
||||
|
||||
### 8.1 记忆来源
|
||||
|
||||
记忆不是模型自动写入的隐式状态，而是可审查资源：
|
||||
|
||||
```text
|
||||
任务失败/人工修改/QC意见
|
||||
→ PendingMemory
|
||||
→ 人工确认
|
||||
→ Memory
|
||||
→ 绑定来源 Agent 和版本
|
||||
```
|
||||
|
||||
未确认记忆不能进入生产 Agent 的有效记忆上下文。
|
||||
|
||||
### 8.2 记忆与知识库同构
|
||||
|
||||
记忆库完全复用知识库的资源模型：
|
||||
|
||||
| 范围 | 默认使用者 | 修改者 |
|
||||
| --- | --- | --- |
|
||||
| `private` | 所有者及其 Agent | 所有者 |
|
||||
| `shared` | 被授权用户 | 所有者和管理员 |
|
||||
| `global` | 当前组织全部用户 | 管理员 |
|
||||
|
||||
管理员可以查看、导出、授权、撤销、发布全局和恢复私有。用户只能看到自己的私有记忆、获授权记忆和全局记忆。
|
||||
|
||||
### 8.3 记忆注入
|
||||
|
||||
Agent Runtime 注入记忆前执行：
|
||||
|
||||
1. 校验任务用户和组织。
|
||||
2. 计算允许读取的记忆 ID。
|
||||
3. 按来源 Agent、版本和状态筛选。
|
||||
4. 将记忆作为“已授权数据”注入，不允许记忆内容覆盖 Runtime 系统规则。
|
||||
5. 将使用的记忆版本写入任务快照。
|
||||
|
||||
撤销授权只影响新任务；已创建任务仍使用创建时的记忆快照。
|
||||
|
||||
## 9. 模型核心逻辑
|
||||
|
||||
### 9.1 管理端模型目录
|
||||
|
||||
模型使用链路为：
|
||||
|
||||
```text
|
||||
管理端接入 Provider
|
||||
→ 发现模型
|
||||
→ 规范化为 ModelCatalog
|
||||
→ 设置能力、可见性、费率和启用状态
|
||||
→ 按组织开放
|
||||
→ 用户端只读选择
|
||||
```
|
||||
|
||||
用户端不能新增 Provider、查看 API Key、修改 Base URL、发现模型、修改费率或输入任意模型名称。
|
||||
|
||||
### 9.2 模型选择和快照
|
||||
|
||||
用户选择 `model_catalog_id`，服务端校验：
|
||||
|
||||
- 模型目录存在且启用。
|
||||
- Provider 存在且启用。
|
||||
- 模型对当前组织可见。
|
||||
- 模型能力满足任务要求。
|
||||
- 当前用户和组织未超出配额。
|
||||
|
||||
通过后把 Provider、真实模型名、能力标签和费率版本写入 Run 快照。模型目录停用不会改变历史任务。
|
||||
|
||||
### 9.3 成人内容能力测试
|
||||
|
||||
“破限”在系统中落地为管理端模型能力兼容性测试，而不是用户自行上传提示词：
|
||||
|
||||
```text
|
||||
ModelCatalog
|
||||
+ adult-content-compat-v1
|
||||
+ 固定样例集
|
||||
+ Provider/网关路径
|
||||
+ 输出断言
|
||||
+ 通过率/拒绝率/超时率/费用
|
||||
→ 发布能力标签
|
||||
```
|
||||
|
||||
结果必须区分 `provider_blocked`、`gateway_blocked`、`model_refused`、`timeout`、`format_failed`、`supported` 和 `partial`。模型更新、Provider 路由变化、系统提示词变化或审查配置变化时重新回归。
|
||||
|
||||
## 10. 用户端与管理端逻辑
|
||||
|
||||
### 10.1 用户端闭环
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
L[登录] --> H[读取组织/角色/配额]
|
||||
H --> R[读取可用资源]
|
||||
R --> M[选择模型目录]
|
||||
M --> C[创建任务]
|
||||
C --> P[解析导图]
|
||||
P --> G[运行 Agent]
|
||||
G --> Q[查看 QC]
|
||||
Q --> V[人工审查]
|
||||
V --> O[组合和下载]
|
||||
O --> U[查看用量/账单]
|
||||
```
|
||||
|
||||
用户端所有写操作都带当前用户身份，所有资源查询都经过归属过滤。模型选择器只显示管理端开放的模型；知识库和记忆库按“我的/已授权/全局”分组。
|
||||
|
||||
### 10.2 管理端闭环
|
||||
|
||||
```text
|
||||
用户管理
|
||||
→ 组织/角色/配额
|
||||
→ Provider 和模型目录
|
||||
→ 成人内容能力测试
|
||||
→ 知识库/记忆授权
|
||||
→ 用量和账单
|
||||
→ 云存储和导出
|
||||
→ 审计复盘
|
||||
```
|
||||
|
||||
管理端可以查看其他用户的私有知识库和记忆，但查看、下载、导出、授权、撤销和删除都必须写入审计。
|
||||
|
||||
## 11. 认证、RBAC 与授权判断
|
||||
|
||||
### 11.1 认证流程
|
||||
|
||||
```text
|
||||
请求
|
||||
→ 读取 Bearer Token
|
||||
→ SHA-256 查找 AuthSession
|
||||
→ 检查撤销/过期
|
||||
→ 检查 AppUser 启用状态
|
||||
→ 写入 last_seen_at
|
||||
→ 得到 user_id / organization_id / role
|
||||
```
|
||||
|
||||
密码使用 PBKDF2-SHA256 派生摘要；数据库不保存明文密码，也不保存明文 Session Token。
|
||||
|
||||
### 11.2 权限判定
|
||||
|
||||
权限不是前端隐藏按钮，而是后端每个请求的强制条件：
|
||||
|
||||
```text
|
||||
身份认证
|
||||
→ 路由所需权限
|
||||
→ 组织范围
|
||||
→ 资源所有权/授权记录
|
||||
→ 操作级权限 read/use/manage
|
||||
→ 执行并记录审计
|
||||
```
|
||||
|
||||
用户端和管理端 API 逻辑分开。新增未知写接口默认归入管理配置权限，避免新接口漏保护。
|
||||
|
||||
### 11.3 资源权限矩阵
|
||||
|
||||
| 操作 | 私有资源所有者 | 获授权用户 | 全局用户 | 管理员 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `read` | 是 | 视授权 | 是 | 是，需审计 |
|
||||
| `use` | 是 | 视授权 | 是 | 是，需审计 |
|
||||
| `manage` | 视资源类型 | 否 | 否 | 是 |
|
||||
| `export` | 自己范围 | 允许范围 | 允许范围 | 全量或指定范围 |
|
||||
| `publish_global` | 否 | 否 | 否 | 是 |
|
||||
|
||||
## 12. 多用户并发与隔离
|
||||
|
||||
### 12.1 上下文隔离
|
||||
|
||||
每次模型请求都绑定：
|
||||
|
||||
```text
|
||||
organization_id
|
||||
user_id
|
||||
campaign_id
|
||||
run_id
|
||||
trace_id
|
||||
span_id
|
||||
session_id
|
||||
```
|
||||
|
||||
消息历史保存在独立 `AgentSession`，不放在 Provider 全局状态、不放在前端共享变量、不通过模型名称作为上下文键。
|
||||
|
||||
### 12.2 四层并发限制
|
||||
|
||||
| 层级 | 限制 |
|
||||
| --- | --- |
|
||||
| 用户级 | 并发 Run、Token 日/月额度、存储和导出 |
|
||||
| 组织级 | 总并发、总预算、总 Token |
|
||||
| 模型级 | Provider QPS、并发连接、超时、重试 |
|
||||
| 任务级 | 同一 Campaign 一个活跃 Run |
|
||||
|
||||
队列等待、限流、重试和取消都写入 Trace。一个 Provider 故障时，不影响其他 Provider 队列。
|
||||
|
||||
## 13. 计费和用量核心逻辑
|
||||
|
||||
### 13.1 计量原则
|
||||
|
||||
计量记录必须追加写入，不按页面统计临时计算。每条 `UsageEvent` 绑定调用归属：
|
||||
|
||||
```text
|
||||
user_id + organization_id + run_id + trace_id + provider + model + idempotency_key
|
||||
```
|
||||
|
||||
计量对象包括 LLM 输入/输出 Token、Embedding、OCR、Rerank、云存储和导出。
|
||||
|
||||
### 13.2 费用计算
|
||||
|
||||
```text
|
||||
LLM 费用 = 输入 Token × 输入费率 + 输出 Token × 输出费率
|
||||
总费用 = LLM + Embedding + OCR + Rerank + 存储 + 导出
|
||||
```
|
||||
|
||||
费用使用调用时冻结的费率版本。Provider 未返回 Token 时，估算值必须标记为 `estimated`，不能直接作为已结算值。
|
||||
|
||||
### 13.3 配额检查时机
|
||||
|
||||
```text
|
||||
创建任务前：检查用户/组织配额
|
||||
进入模型队列前：再次检查并发和预算
|
||||
调用返回后：写 UsageEvent
|
||||
任务结束后：结算本次实际用量
|
||||
```
|
||||
|
||||
配额策略支持 `warn`、`soft_limit` 和 `hard_limit`。达到硬限制时禁止新调用，并把原因显示在任务和 Trace 中。
|
||||
|
||||
## 14. 云存储和导出逻辑
|
||||
|
||||
### 14.1 文件生命周期
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> uploading
|
||||
uploading --> stored
|
||||
stored --> indexed
|
||||
indexed --> active
|
||||
active --> superseded: 文件更新
|
||||
superseded --> recycle_bin
|
||||
recycle_bin --> deleted
|
||||
uploading --> orphaned: 数据库提交失败
|
||||
orphaned --> deleted: 清理任务
|
||||
```
|
||||
|
||||
对象键按组织、用户、知识库、哈希和安全文件名组成，不以原始文件名作为唯一键。数据库只把已经校验哈希的对象标记为当前版本。
|
||||
|
||||
### 14.2 导出内容
|
||||
|
||||
导出任务必须包含 `manifest.json`，记录：
|
||||
|
||||
- 对象键、大小、哈希和版本。
|
||||
- 组织、用户、知识库/记忆归属。
|
||||
- 分类和授权状态。
|
||||
- Trace、账单和审计范围。
|
||||
- 导出发起人、时间、保留期和过期时间。
|
||||
|
||||
下载使用短时效签名地址，浏览器不接触云存储长期密钥。
|
||||
|
||||
## 15. 失败恢复和一致性
|
||||
|
||||
### 15.1 模型调用失败
|
||||
|
||||
| 失败 | 处理 |
|
||||
| --- | --- |
|
||||
| 超时/连接中断 | 按策略重试，写入每次尝试和耗时 |
|
||||
| 429/配额 | 进入限流或转人工，不伪造成功 |
|
||||
| Provider/模型不存在 | 直接失败，提示管理员修复目录 |
|
||||
| Provider 拦截 | 标记 `provider_blocked`，按能力路由规则处理 |
|
||||
| 网关拦截 | 标记 `gateway_blocked`，区分模型本体和网关 |
|
||||
| 空输出/截断 | 触发格式重试，仍失败则进入人工处理 |
|
||||
|
||||
### 15.2 RAG 失败
|
||||
|
||||
- 索引为 `indexing` 时禁止新任务使用该库，除非管理员明确允许旧版本。
|
||||
- 无命中是低置信结果，不得自动补写事实。
|
||||
- 重建失败恢复旧索引和旧计数。
|
||||
- 进程中断时归还 `reserved` 知识片段。
|
||||
- 向量库损坏时切换本地兜底索引，并记录降级事件。
|
||||
|
||||
### 15.3 组合失败
|
||||
|
||||
组合器不能把缺失段落静默填充为新内容：
|
||||
|
||||
```text
|
||||
缺段 → compose_report 标记缺失
|
||||
→ Campaign 保持 human_review/failed
|
||||
→ 通知中心提醒
|
||||
→ 人工修复、跳过或重新运行
|
||||
```
|
||||
|
||||
## 16. 核心不变量
|
||||
|
||||
以下规则是系统必须长期保持的不变量：
|
||||
|
||||
1. 没有有效身份和组织归属的请求不能访问业务 API。
|
||||
2. 用户端不能创建 Provider、查看 API Key 或输入任意模型名称。
|
||||
3. 模型调用必须使用启用且对当前组织可见的模型目录记录。
|
||||
4. 任务开始后，规则、技能、模型、知识和记忆必须从快照读取。
|
||||
5. Agent 只能检索被挂接且当前用户有权限使用的知识库。
|
||||
6. 同一个 Agent 不能重复消费同一个知识片段，其他 Agent 不受影响。
|
||||
7. 未确认记忆不能进入有效记忆上下文。
|
||||
8. Composer 只能组合已人工通过的段落。
|
||||
9. 每次模型调用必须有 `LLMCall`、Trace 和用量归属。
|
||||
10. 任何删除、授权、发布全局、导出和计费调整都必须有审计记录。
|
||||
11. 失败、等待审批、限流和降级不能标记为成功。
|
||||
12. 历史任务、账单和引用不能被当前配置修改覆盖。
|
||||
|
||||
## 17. 关键 API 逻辑分组
|
||||
|
||||
### 17.1 用户端
|
||||
|
||||
```text
|
||||
认证：/api/auth/status、/api/auth/login、/api/auth/logout
|
||||
模型：/api/models/available
|
||||
知识：/api/kbs、/api/kbs/{id}/search、/api/kbs/{id}/files/{name}
|
||||
记忆：/api/memories
|
||||
任务：/api/campaigns、/api/campaigns/{id}/parse、/api/campaigns/{id}/run
|
||||
审查：/api/segments/{id}/review、/api/segments/{id}/fix
|
||||
Trace：/api/traces、/api/traces/{trace_id}
|
||||
用量：/api/me/usage、/api/me/billing
|
||||
```
|
||||
|
||||
### 17.2 管理端
|
||||
|
||||
```text
|
||||
用户：/api/admin/users、/api/admin/organizations
|
||||
模型：/api/admin/model-providers、/api/admin/models
|
||||
能力测试：/api/admin/models/{id}/capability-tests
|
||||
知识授权：/api/admin/knowledge-bases/{id}/grants
|
||||
记忆授权：/api/admin/memories/{id}/grants
|
||||
计费：/api/admin/usage、/api/admin/billing/settlements
|
||||
导出：/api/admin/knowledge-bases/{id}/export、/api/admin/memories/{id}/export
|
||||
审计：/api/admin/audit
|
||||
```
|
||||
|
||||
## 18. 当前实现与 v6 目标对照
|
||||
|
||||
| 领域 | 当前 v5 实现 | v6 目标 |
|
||||
| --- | --- | --- |
|
||||
| Runtime | 已实现会话、工具、审批、恢复、护栏和 Trace | 增加用户/组织归属和配额上下文 |
|
||||
| 画布 | 已实现节点、连线、波次和快照 | 按用户隔离画布和模板 |
|
||||
| 知识库 | 已实现 RAG、分类、消费锁和 KB3 回滚 | 增加云对象、全局/私有/共享和授权 |
|
||||
| 记忆库 | 已实现待确认池、Agent 记忆和筛选删除 | 增加与知识库同构的可见性和授权 |
|
||||
| 模型 | 已实现 Provider CRUD、发现、测试和 Agent 绑定 | 收敛为管理端 ModelCatalog，用户端只读选择 |
|
||||
| 成人内容能力 | 已设计管理端兼容性测试和能力标签 | 实现测试套件、回归、发布和路由 |
|
||||
| 认证 | 已实现本地用户、PBKDF2、Session、RBAC | 增加组织、多租户和管理端角色 |
|
||||
| Trace | 已实现 Run/Session/Event/LLMCall 聚合 | 增加用户、组织和账单关联 |
|
||||
| 计费 | 已有 Token/耗时调用字段 | 新增 UsageEvent、费率版本、配额和结算 |
|
||||
| 存储 | 当前以本地 SQLite、源文件和向量兜底为主 | 迁移云对象存储和异步导出 |
|
||||
|
||||
## 19. 核心验收标准
|
||||
|
||||
### 19.1 任务链路
|
||||
|
||||
- 用户登录后可以创建任务、解析导图、运行 Agent、审查段落和组合成稿。
|
||||
- 每个 Run 都有唯一 `trace_id`，能看到模型调用、工具事件、QC 和产物。
|
||||
- 修改 Agent 规则或模型目录后，已运行任务的快照不变。
|
||||
|
||||
### 19.2 资源隔离
|
||||
|
||||
- 用户看不到其他用户未授权的知识库、记忆、任务、Trace 和账单。
|
||||
- 管理员可以查看和导出全量资源，所有动作有审计。
|
||||
- 全局知识库和全局记忆只允许管理员修改原文。
|
||||
- 用户端模型列表只包含管理端已启用且对当前组织开放的目录。
|
||||
|
||||
### 19.3 稳定性
|
||||
|
||||
- 同一用户不能并发消费同一知识片段。
|
||||
- 同一 Campaign 不能产生两个活跃 Run。
|
||||
- Provider、网关和模型版本变化能在 Trace 中区分。
|
||||
- KB3 重启后仍为 `ready/2717`，向量检索可返回结果。
|
||||
- 索引、模型、云存储和导出失败均有明确状态并可恢复。
|
||||
|
||||
### 19.4 计费
|
||||
|
||||
- 每次 LLM、Embedding、OCR 和存储行为都有用户/组织归属。
|
||||
- 费率版本变化不回写历史账单。
|
||||
- 预估、已计量和已结算状态可区分。
|
||||
- 用量明细可以回溯到 LLMCall、Run、Trace、Agent 和任务。
|
||||
|
||||
## 20. 结论
|
||||
|
||||
系统的核心不是“接入更多模型”或“堆更多 Agent”，而是把每一次生成变成一条可控、可复现、可审查、可计费的数据链：
|
||||
|
||||
```text
|
||||
谁发起
|
||||
→ 用了哪个版本的 Agent/模型
|
||||
→ 读取了哪些被授权的知识和记忆
|
||||
→ 产生了哪些模型/工具调用
|
||||
→ 经过哪些质检和人工决定
|
||||
→ 最终交付了什么
|
||||
→ 消耗了多少 AI 和存储资源
|
||||
```
|
||||
|
||||
v6 的用户端、管理端、云存储、模型能力测试、知识/记忆共享和计费，全部围绕这条链扩展，不改变 v5 已有的 Agent Runtime、QC、组合和 Trace 基础。
|
||||
@@ -0,0 +1,94 @@
|
||||
# 雅文内容创造工作台 · 流程图
|
||||
|
||||
## 图1 · 主流程（一次完整生产）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
U["👩 你<br/>输入：主题 / 导图 / 框架 / 思维"] --> C["主控 Agent 主编"]
|
||||
C -->|"① 解析导图（读不准的词→列待确认清单问你）"| B["蓝图：生成任务单 TaskSpec<br/>段划分+时间轴+产品节点+质检项"]
|
||||
B -->|"② 按段派发（并行）"| S1["段Agent1 开场/心法"]
|
||||
B -->|"② 按段派发（并行）"| S2["段Agent2 技法/场景"]
|
||||
B -->|"② 按段派发（并行）"| S3["段Agent3 产品/销售"]
|
||||
B -->|"② 按段派发（并行）"| SN["段AgentN 收尾/钩子"]
|
||||
S1 -.->|只读| KB["📚 共享只读知识库<br/>风格档案/导图库/原文库/备稿库/产品库/质检规则库"]
|
||||
S2 -.->|只读| KB
|
||||
S3 -.->|只读| KB
|
||||
SN -.->|只读| KB
|
||||
S1 --> Q1["质检闸 ①结构 ②内容 ③风格尺度 ④跨稿<br/>（每件产物独立过4道，并行）"]
|
||||
S2 --> Q1
|
||||
S3 --> Q1
|
||||
SN --> Q1
|
||||
Q1 -->|"FAIL → 打回原段重跑（带质检意见）"| S1
|
||||
Q1 -->|"FAIL → 打回原段重跑"| S2
|
||||
Q1 -->|"FAIL → 打回原段重跑"| S3
|
||||
Q1 -->|"FAIL → 打回原段重跑"| SN
|
||||
Q1 -->|"✅ 4道全过"| H["👩 人工审查台（硬关卡）<br/>逐段：产物+质检报告+差异高亮"]
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S1
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S2
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S3
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| SN
|
||||
H -->|"✅ 全部确认"| CM["组合Agent 总编<br/>时间轴拼装→衔接/回指检查→生成说明"]
|
||||
CM -->|"📄"| OUT["直播文稿.docx<br/>六色标记 + clean.txt + 待确认清单"]
|
||||
```
|
||||
|
||||
## 图2 · 哪里不对改哪里（三种修改路径）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph 路径1["内容级打回（最常见）"]
|
||||
A1["人工/质检发现段3不对"] --> A2["打回段3 + 写意见"]
|
||||
A2 --> A3["段3 Agent：读取意见+自己记忆<br/>重新生成段3"]
|
||||
A3 --> A4["段3 重新质检 → 复审"]
|
||||
A1 -.-> A5["其他段 1/2/4 原封不动 ✅"]
|
||||
end
|
||||
subgraph 路径2["规则级修正"]
|
||||
B1["你改 rules.md（如：技法段要求改）"] --> B2["该Agent按新规则重跑"]
|
||||
B2 --> B3["质检 → 审查"]
|
||||
end
|
||||
subgraph 路径3["人工直接改"]
|
||||
C1["审查时直接在产物上改"] --> C2["改动记录沉淀进该Agent记忆"]
|
||||
C2 --> C3["改后照常质检/放行"]
|
||||
end
|
||||
```
|
||||
|
||||
## 图3 · 记忆闭环（越用越懂 · 隔离）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
R["打回意见 / 质检FAIL / 你改规则"] --> W{"写入触发"}
|
||||
W -->|"人工打回"| M1["该段Agent记忆 L3偏好<br/>（结构化：来源/内容/状态）"]
|
||||
W -->|"质检FAIL"| M2["质检Agent记忆 L2错误模式<br/>（同类错误下次直接查）"]
|
||||
W -->|"你改规则"| M3["规则记忆 L1<br/>（等同永久生效）"]
|
||||
W -->|"你确认复盘（可选）"| M4["成功记忆 L4<br/>（防噪音，不自动写）"]
|
||||
M1 --> NEXT["下次该Agent运行时注入记忆<br/>+ 规则文件 + 任务单切片"]
|
||||
M2 --> NEXT
|
||||
M3 --> NEXT
|
||||
M4 --> NEXT
|
||||
NEXT --> OUT2["产出质量随轮次提升<br/>同一错误二次打回率↓"]
|
||||
style M1 fill:#2d6a4f
|
||||
style M2 fill:#1d3557
|
||||
style M3 fill:#6d597a
|
||||
style M4 fill:#7f5539
|
||||
```
|
||||
|
||||
## 图4 · 记忆/上下文隔离边界
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph 隔离区["每个Agent的私有空间（互不可见）"]
|
||||
R1["rules.md 规则文件"]
|
||||
M1["记忆库（独立命名空间）"]
|
||||
CTX["会话上下文（只含自己的任务切片）"]
|
||||
end
|
||||
subgraph 共享区["全Agent共享（只读）"]
|
||||
KB["📚 共享知识库<br/>风格/框架/原文/备稿/产品/质检规则"]
|
||||
TS["任务单 TaskSpec（主控产出）"]
|
||||
end
|
||||
A["段Agent"] -->|"读"| R1
|
||||
A -->|"读写"| M1
|
||||
A -->|"只读"| KB
|
||||
A -->|"只读自己的切片"| TS
|
||||
B["质检Agent"] -->|"读写"| M2["自己的错误模式记忆"]
|
||||
B -->|"只读"| KB
|
||||
B -->|"只读被检段产物"| TS
|
||||
```
|
||||
@@ -0,0 +1,91 @@
|
||||
# 雅文内容创造工作台 · 流程图 v2
|
||||
|
||||
## 图1 · 主流程 v2（波次调度 + 锚点卡 + 组合总检 + 记忆确认）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
U["👩 你：输入主题/导图/框架"] --> C["主控Agent<br/>解析导图→任务单"]
|
||||
C -->|"读不准的词→待确认清单问你"| TS["任务单 TaskSpec<br/>段+时间轴+产品节点+质检项"]
|
||||
TS --> W1["波次1（并行）<br/>开场段Agent | 服务Agent预热"]
|
||||
W1 --> W2["波次2（并行，读开场锚点卡）<br/>心法段Agent | 技法段Agent"]
|
||||
W2 --> W3["波次3（并行，读心法/技法锚点卡）<br/>场景段Agent | 产品段Agent"]
|
||||
W3 --> W4["波次4（读全部锚点卡）<br/>收尾段Agent | 互动标记Agent"]
|
||||
W4 --> AQ["每段产物 + 锚点卡AnchorCard"]
|
||||
AQ --> QC["4道质检闸：结构/内容/风格尺度/跨稿<br/>（质检报告逐条对证正文+锚点卡）"]
|
||||
QC -->|"FAIL→打回原段"| AQ
|
||||
QC -->|"✅全过"| HR["人工审查台（硬关卡）<br/>逐段：产物+质检报告+锚点卡"]
|
||||
HR -->|"🔁打回→意见生成记忆建议"| PM["记忆待确认池"]
|
||||
HR -->|"✅全部确认"| CM["组合Agent<br/>时间轴拼装→一致性总检(5项)"]
|
||||
CM -->|"发现矛盾/回指断裂→打回对应段"| AQ
|
||||
CM -->|"微衔接→缝合编辑（必须标记）"| OUT["直播文稿.docx（六色）<br/>+组合报告+待确认清单"]
|
||||
PM -->|"你确认→写入"| MEM["对应Agent记忆库"]
|
||||
PM -->|"你拒绝/屏蔽→丢弃"| D["✖"]
|
||||
```
|
||||
|
||||
## 图2 · 上下文契约：锚点卡机制（为什么段间不会"互不懂"）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph 上游["段2 技法段Agent 产出"]
|
||||
A2["段2 全文产物"]
|
||||
AC2["锚点卡（一页摘要）<br/>技法名：八爪鱼收紧术<br/>痛点：干涩→油<br/>情绪：高·演示"]
|
||||
end
|
||||
A2 --> AC2
|
||||
subgraph 下游["段3 产品段Agent（隔离）"]
|
||||
B["只读：段2锚点卡<br/>❌不读段2全文<br/>❌不共享对话"]
|
||||
OUT3["段3 产物：<br/>'刚才教的八爪鱼收紧术，配这瓶油…'<br/>✅回指一致"]
|
||||
end
|
||||
AC2 -->|"主控转交"| B
|
||||
subgraph 组合["组合Agent 总检"]
|
||||
CHK["一致性总检<br/>回指断裂？矛盾？时间线？情绪曲线？钩子？"]
|
||||
CHK -->|"发现断裂→打回对应段"| A2
|
||||
CHK -->|"通过→拼装交付"| DOC["📄 docx"]
|
||||
end
|
||||
OUT3 --> CHK
|
||||
```
|
||||
|
||||
## 图3 · 哪里不对改哪里（三种路径 v2）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph P1["路径1 内容级打回"]
|
||||
A1["质检或审查发现段3不对"] --> A2["打回段3+意见"]
|
||||
A2 --> A3["段3Agent：读意见+自己记忆+上游锚点卡<br/>重新生成"]
|
||||
A3 --> A4["段3重新质检→复审"]
|
||||
A1 -.-> A5["段1/2/4原封不动✅"]
|
||||
end
|
||||
subgraph P2["路径2 规则级修正"]
|
||||
B1["工作台改该Agent rules.md（带版本）"] --> B2["按新规则重跑该环节"]
|
||||
end
|
||||
subgraph P3["路径3 人工直接改"]
|
||||
C1["审查时直接改产物（标记）"] --> C2["生成记忆建议→待确认池"]
|
||||
end
|
||||
```
|
||||
|
||||
## 图4 · 记忆闭环 v2（人工确认后才沉淀）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
SRC["沉淀来源<br/>打回意见 / 质检FAIL / 你改规则 / 复盘"] --> PM["📥 记忆待确认池<br/>（每条：目标Agent+类型+内容+来源）"]
|
||||
PM -->|"✅ 你确认"| W["写入对应Agent记忆库<br/>L1规则/L2纠错/L3偏好/L4成功"]
|
||||
PM -->|"❌ 拒绝"| DR["丢弃"]
|
||||
PM -->|"🚫 屏蔽同类"| BL["该来源类型不再建议"]
|
||||
W --> N["下次该Agent运行时注入<br/>+规则+任务切片+上游锚点卡"]
|
||||
N --> O["产出质量提升，同一错误二次打回率↓"]
|
||||
style PM fill:#6d597a
|
||||
style W fill:#2d6a4f
|
||||
```
|
||||
|
||||
## 图5 · Agent 注册中心（随便添加，数量不限）
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
MAN["👩 你：Agent管理页"] -->|"新建向导5步"| NEW["新Agent<br/>名称/职责/规则(rules.md模板+规则片段库)<br/>输入来源(读谁锚点卡)/知识库勾选"]
|
||||
MAN -->|"复制"| CP["复制现有Agent改名改规则<br/>（如：复制场景段→青蛇白蛇段）"]
|
||||
MAN -->|"停用"| DIS["停用（不派单，历史保留）"]
|
||||
NEW --> REG["Agent注册中心<br/>agent_id/类型/标签/版本历史"]
|
||||
CP --> REG
|
||||
REG -->|"拖进流水线"| PL["流水线编辑器<br/>节点=Agent 边=依赖<br/>质检挂载/执行顺序"]
|
||||
PL -->|"主控按依赖分波次调度"| RUN["执行 ✅"]
|
||||
style REG fill:#1d3557
|
||||
```
|
||||
@@ -0,0 +1,99 @@
|
||||
# 雅文内容创造工作台 · 流程图 v3（开放画布版）
|
||||
|
||||
## 图1 · Agent 关系画布（核心：顺序可改/启停/任意连线）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
M["主控Agent<br/>导图→任务单"] --> A["开场 ●"]
|
||||
A --> X1["心法Agent1 ●"]
|
||||
A -.->|"可选读取"| X2["心法Agent2 ○停用<br/>（不生成，跳过）"]
|
||||
X1 --> AL["案例 ●"]
|
||||
X1 --> J1["技法Agent1 ●"]
|
||||
X1 --> J2["技法Agent2 ●<br/>（同类可多个，并行）"]
|
||||
X1 --> G["功法 ●"]
|
||||
AL --> P["产品销售 ●<br/>（挂：产品知识库）"]
|
||||
J1 --> V["画面 ●"]
|
||||
J2 --> V
|
||||
G --> S["场景 ●"]
|
||||
V --> E["收尾 ●"]
|
||||
S --> E
|
||||
P --> E
|
||||
E --> H["钩子 ●"]
|
||||
H --> CM["组合Agent<br/>拼装+一致性总检"]
|
||||
style X2 fill:#444,color:#999,stroke-dasharray: 5 5
|
||||
style M fill:#1d3557
|
||||
style CM fill:#6d597a
|
||||
```
|
||||
|
||||
> 画布操作：拖节点改位置 ｜ 拉线改依赖 ｜ 节点开关启停 ｜ 模板保存复用 ｜ 任务开工时固化快照
|
||||
|
||||
## 图2 · 内容类型标签与派单（同类可多个）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
MG["导图节点们"] -->|"主控标标签"| SEG["内容段<br/>段1=心法·女人如水<br/>段2=技法·八爪鱼收紧术<br/>段3=技法·三指游龙<br/>段4=产品销售·油<br/>…（同类多段不合并）"]
|
||||
SEG --> MATCH{"按标签匹配<br/>启用中的Agent"}
|
||||
MATCH -->|"技法×2"| J1["技法Agent1 节点"]
|
||||
MATCH -->|"技法×2"| J2["技法Agent2 节点"]
|
||||
MATCH -->|"心法×1"| X1["心法Agent 节点"]
|
||||
MATCH -->|"产品销售×1"| P1["产品销售Agent 节点"]
|
||||
J1 --> QC["质检+审查+组合"]
|
||||
J2 --> QC
|
||||
X1 --> QC
|
||||
P1 --> QC
|
||||
```
|
||||
|
||||
## 图3 · 多知识库隔离挂接
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph 库区["📚 知识库（可建多个，互相隔离）"]
|
||||
KB1["风格档案库"]
|
||||
KB2["产品知识库"]
|
||||
KB3["直播原文库"]
|
||||
KB4["你建的库：青蛇白蛇素材库"]
|
||||
end
|
||||
subgraph Agent区["Agent 挂接配置（多选）"]
|
||||
PA["产品销售Agent<br/>☑风格档案 ☑产品知识库<br/>☐原文库 ☐青蛇库"]
|
||||
JA["技法Agent<br/>☑风格档案 ☑直播原文库<br/>☐产品库"]
|
||||
QA["跨稿质检<br/>☑备稿库 ☑框架库"]
|
||||
end
|
||||
KB1 --> PA
|
||||
KB2 --> PA
|
||||
KB1 --> JA
|
||||
KB3 --> JA
|
||||
PA -.->|"不可见"| X1["产品Agent查不到原文库/青蛇库"]
|
||||
JA -.->|"不可见"| X2["技法Agent查不到产品库"]
|
||||
```
|
||||
|
||||
## 图4 · 锚点卡契约 + 组合一致性总检（防"段间互不懂"）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph 上游["技法段Agent 产出"]
|
||||
A2["技法段全文"]
|
||||
AC["锚点卡（一页）<br/>技法名/痛点/情绪基调/钩子"]
|
||||
end
|
||||
A2 --> AC
|
||||
subgraph 下游["产品销售Agent（隔离）"]
|
||||
B["只读锚点卡<br/>❌不读全文 ❌不共享对话"]
|
||||
O3["'刚才教的八爪鱼收紧术配这瓶油…'✅"]
|
||||
end
|
||||
AC --> B
|
||||
O3 --> CHK["组合Agent 一致性总检<br/>矛盾/回指/时间线/情绪曲线/钩子"]
|
||||
CHK -->|"断裂→打回对应段"| A2
|
||||
CHK -->|"微衔接→缝合标记"| D["📄 docx+组合报告"]
|
||||
```
|
||||
|
||||
## 图5 · 记忆闭环（人工确认后才沉淀）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
SRC["打回意见/质检FAIL/复盘"] --> PM["记忆待确认池"]
|
||||
PM -->|"✅确认"| MEM["该Agent记忆库（隔离命名空间）"]
|
||||
PM -->|"❌拒绝/🚫屏蔽"| D["✖"]
|
||||
MEM --> INJ["下次运行时注入：规则+记忆+任务切片+上游锚点卡+挂接知识库"]
|
||||
INJ --> BETTER["质量提升，二次打回率↓"]
|
||||
style PM fill:#6d597a
|
||||
style MEM fill:#2d6a4f
|
||||
```
|
||||
@@ -0,0 +1,169 @@
|
||||
# 雅文内容创造工作台 · 流程图 v4（RAG 知识库版）
|
||||
|
||||
## 图1 · RAG 知识库建库管道（导入即建，全自动）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
F["素材文件<br/>docx / srt / md / txt / json / 导图"] --> P1["① 导入<br/>拖拽上传+进度条"]
|
||||
P1 --> P2["② 格式解析<br/>docx提取正文 / srt去时间戳 / json结构抽取"]
|
||||
P2 --> P3["③ 清洗<br/>去空行/提词备注/字幕断句合并"]
|
||||
P3 --> P4["④ 分块<br/>标题感知+语义边界 400-600字 重叠15%<br/>元数据：库/文件/章节/序号"]
|
||||
P4 --> P5["⑤ 向量化<br/>BGE-M3 本地Embedding（离线，数据不出本机）"]
|
||||
P5 --> P6["⑥ 入库<br/>ChromaDB collection=知识库（天然隔离）"]
|
||||
P6 --> P7["⑦ 检索测试页<br/>输入query验证命中质量"]
|
||||
style P6 fill:#1d3557
|
||||
```
|
||||
|
||||
## 图2 · Agent 取料（混合检索 + 引用溯源，只查挂接库）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["生产Agent 生成请求"] --> Q["query构造<br/>任务切片+上游锚点卡+检索意图"]
|
||||
Q --> H{"混合检索<br/>只在挂接的collection内"}
|
||||
H -->|"向量 top-k"| V["BGE-M3 语义相似度"]
|
||||
H -->|"关键词 top-k"| K["BM25 精确命中<br/>（技法名/产品名/暗语）"]
|
||||
V --> M["合并去重"]
|
||||
K --> M
|
||||
M --> R["可选：rerank重排"]
|
||||
R --> S["引用溯源<br/>每条带：库/文件/章节/原文块/相似度"]
|
||||
S --> INJ["注入Agent上下文<br/>（后台标注来源，正文不出现'知识库里说'）"]
|
||||
INJ --> OUT["段产物"]
|
||||
OUT --> QC["质检一键核对引用<br/>选中一句→看引用→对证原文"]
|
||||
QC -->|"查无来源=FAIL"| A
|
||||
style QC fill:#6d597a
|
||||
```
|
||||
|
||||
## 图3 · 知识库隔离与 Agent 挂接
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph KB["📚 知识库（ChromaDB collection 物理隔离）"]
|
||||
C1["风格档案库"]
|
||||
C2["产品知识库"]
|
||||
C3["直播原文库（73场SRT）"]
|
||||
C4["备稿库（99篇）"]
|
||||
C5["你建的库：青蛇白蛇素材库"]
|
||||
end
|
||||
subgraph AG["Agent 挂接（多选）"]
|
||||
PA["产品销售Agent<br/>☑风格档案 ☑产品知识库"]
|
||||
JA["技法Agent<br/>☑风格档案 ☑直播原文库"]
|
||||
end
|
||||
C1 --> PA
|
||||
C2 --> PA
|
||||
C1 --> JA
|
||||
C3 --> JA
|
||||
PA -.->|"查不到"| X["原文库/青蛇库"]
|
||||
JA -.->|"查不到"| Y["产品库"]
|
||||
```
|
||||
|
||||
## 图4 · Agent 关系画布（v3 核心不变）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
M["主控Agent"] --> A["开场 ●"]
|
||||
A --> X1["心法Agent1 ●"]
|
||||
A -.->|"可选"| X2["心法Agent2 ○停用"]
|
||||
X1 --> J1["技法Agent1 ●"]
|
||||
X1 --> J2["技法Agent2 ● 并行"]
|
||||
X1 --> G["功法 ●"]
|
||||
J1 --> P["产品销售 ●"]
|
||||
J2 --> V["画面 ●"]
|
||||
G --> S["场景 ●"]
|
||||
V --> E["收尾 ●"]
|
||||
S --> E
|
||||
P --> E
|
||||
E --> H["钩子 ●"]
|
||||
H --> CM["组合Agent"]
|
||||
style X2 fill:#444,color:#999,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
## 图5 · 内容标签体系（26 个，6 大类）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph 结构["结构类"]
|
||||
A1["开场★"]; A2["转场"]; A3["收尾★"]; A4["钩子★"]; A5["预告"]
|
||||
end
|
||||
subgraph 内容["内容类"]
|
||||
B1["心法★"]; B2["痛点★"]; B3["动机铺垫★"]; B4["案例★"]; B5["见证"]
|
||||
B6["冷知识"]; B7["金句★"]; B8["共鸣"]
|
||||
end
|
||||
subgraph 技法["技法类"]
|
||||
C1["技法★"]; C2["功法★"]; C3["跟练★"]; C4["安全提示"]
|
||||
end
|
||||
subgraph 产品["产品类"]
|
||||
D1["产品销售★"]; D2["产品体验★"]; D3["产品回指"]
|
||||
end
|
||||
subgraph 表现["表现类"]
|
||||
E1["画面★"]; E2["场景★"]; E3["情绪"]; E4["氛围"]; E5["互动"]
|
||||
end
|
||||
subgraph 辅助["辅助类"]
|
||||
F1["答疑"]; F2["双主播"]; F3["毛边"]; F4["仪式"]
|
||||
end
|
||||
```
|
||||
|
||||
## 图6 · 模型管理（每个 Agent 可选不同模型）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph 模型池["模型注册（OpenAI 兼容，可同时挂多个）"]
|
||||
M1["🟦 DeepSeek<br/>deepseek-chat / R1"]
|
||||
M2["🟩 硅基流动 / 智谱GLM"]
|
||||
M3["🟧 Kimi / 通义"]
|
||||
M4["⬜ 本地 Ollama"]
|
||||
end
|
||||
subgraph 画布["画布节点（每Agent独立选模型）"]
|
||||
A1["主控Agent 🟦DeepSeek-R1<br/>（强推理：拆解/调度）"]
|
||||
A2["心法Agent 🟩GLM<br/>（文风对比）"]
|
||||
A3["画面Agent 🟧Kimi<br/>（文风对比）"]
|
||||
A4["质检Agent 🟦DeepSeek-R1<br/>（严格规则执行）"]
|
||||
A5["组合Agent 🟦长上下文<br/>（拼装+总检读全稿）"]
|
||||
end
|
||||
M1 --> A1
|
||||
M1 --> A4
|
||||
M1 --> A5
|
||||
M2 --> A2
|
||||
M3 --> A3
|
||||
```
|
||||
|
||||
## 图7 · 节点状态机（每个 Agent 工作状态清晰可见）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P["待派发 🟦灰"] --> R["生成中 🟦蓝<br/>（显示模型+已耗时）"]
|
||||
R --> Q["质检中 🟡黄<br/>（显示第几道）"]
|
||||
Q --> H["待人工审查 🟣紫"]
|
||||
H -->|"✅通过"| A["已通过 🟢绿"]
|
||||
H -->|"🔁打回"| RW["打回重做 🟠橙<br/>（显示第几轮）"]
|
||||
RW --> R
|
||||
R -->|"生成失败"| F["⚠️失败 🔴红<br/>（点击看原因）"]
|
||||
Q -->|"质检FAIL"| RW
|
||||
F -->|"人工修复后重跑"| R
|
||||
F -->|"人工跳过"| SK["跳过 ⬜灰斜线"]
|
||||
F -->|"停用节点"| D["停用 ⬛暗"]
|
||||
P -->|"上游停用"| SK
|
||||
style F fill:#7f1d1d,color:#fff
|
||||
style A fill:#14532d,color:#fff
|
||||
```
|
||||
|
||||
## 图8 · 失败处理闭环（生成不出来 → 必提醒人工）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
FAIL["Agent 生成失败"] --> RETRY{"可自动重试？<br/>超时/限流/截断"}
|
||||
RETRY -->|"是（最多2次）"| R1["指数退避重试"]
|
||||
R1 -->|"成功"| OK["✅ 继续流程"]
|
||||
R1 -->|"仍失败"| MAN
|
||||
RETRY -->|"否（拒审/Key错误/余额不足）"| MAN["🔴 转人工<br/>节点红标+通知中心提醒<br/>（不静默、不假装成功）"]
|
||||
MAN --> PANEL["失败处理面板<br/>失败Agent/模型/错误原文/调用日志/输入上下文"]
|
||||
PANEL --> ACT["人工修复动作"]
|
||||
ACT -->|"🔁重试"| R1
|
||||
ACT -->|"🔄换模型"| M2["换模型重跑"]
|
||||
ACT -->|"📝改规则"| R2["改rules.md重跑"]
|
||||
ACT -->|"✂️调任务切片"| R3["改写段描述重跑"]
|
||||
ACT -->|"⏭️跳过"| SK["跳过（组合注明缺段）"]
|
||||
ACT -->|"⏸️停用"| D["停用节点"]
|
||||
ACT --> MEM["填修复原因 → 记忆建议<br/>→ 待确认池 → 沉淀防复发"]
|
||||
style MAN fill:#7f1d1d,color:#fff
|
||||
style MEM fill:#6d597a
|
||||
```
|
||||
+122
@@ -0,0 +1,122 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>雅文内容创造工作台 · 流程图</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
body { background:#0f1117; color:#e6e6e6; font-family:"Microsoft YaHei",system-ui,sans-serif; margin:0; padding:24px; }
|
||||
h1 { text-align:center; font-size:22px; color:#fff; margin-bottom:4px; }
|
||||
.sub { text-align:center; color:#888; font-size:13px; margin-bottom:28px; }
|
||||
.card { background:#1a1d27; border:1px solid #2a2e3d; border-radius:12px; padding:20px 16px; margin-bottom:28px; }
|
||||
.card h2 { font-size:16px; color:#ffd479; margin:0 0 14px 8px; }
|
||||
.mermaid { display:flex; justify-content:center; overflow-x:auto; }
|
||||
.tag { display:inline-block; background:#2a2e3d; color:#9aa4bf; font-size:12px; padding:2px 10px; border-radius:10px; margin-left:8px; font-weight:normal;}
|
||||
footer { text-align:center; color:#555; font-size:12px; margin-top:16px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>雅文内容创造工作台 · 流程图</h1>
|
||||
<div class="sub">多 Agent 内容工厂：主控派单 → 环节生产 → 质检 → 人工审查 → 组合交付｜v1 ｜ 2026-08-25</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图1 · 主流程（一次完整生产）<span class="tag">核心图</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
U["👩 你<br/>输入：主题 / 导图 / 框架 / 思维"] --> C["主控 Agent 主编"]
|
||||
C -->|"① 解析导图（读不准的词→列待确认清单问你）"| B["蓝图：生成任务单 TaskSpec<br/>段划分+时间轴+产品节点+质检项"]
|
||||
B -->|"② 按段派发（并行）"| S1["段Agent1 开场/心法"]
|
||||
B -->|"② 按段派发（并行）"| S2["段Agent2 技法/场景"]
|
||||
B -->|"② 按段派发（并行）"| S3["段Agent3 产品/销售"]
|
||||
B -->|"② 按段派发（并行）"| SN["段AgentN 收尾/钩子"]
|
||||
S1 -.->|"只读"| KB["📚 共享只读知识库<br/>风格档案/导图库/原文库/备稿库/产品库/质检规则库"]
|
||||
S2 -.->|"只读"| KB
|
||||
S3 -.->|"只读"| KB
|
||||
SN -.->|"只读"| KB
|
||||
S1 --> Q1["质检闸 ①结构 ②内容 ③风格尺度 ④跨稿<br/>（每件产物独立过4道，并行）"]
|
||||
S2 --> Q1
|
||||
S3 --> Q1
|
||||
SN --> Q1
|
||||
Q1 -->|"FAIL → 打回原段重跑（带质检意见）"| S1
|
||||
Q1 -->|"FAIL → 打回原段重跑"| S2
|
||||
Q1 -->|"FAIL → 打回原段重跑"| S3
|
||||
Q1 -->|"FAIL → 打回原段重跑"| SN
|
||||
Q1 -->|"✅ 4道全过"| H["👩 人工审查台（硬关卡）<br/>逐段：产物+质检报告+差异高亮"]
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S1
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S2
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S3
|
||||
H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| SN
|
||||
H -->|"✅ 全部确认"| CM["组合Agent 总编<br/>时间轴拼装→衔接/回指检查→生成说明"]
|
||||
CM -->|"📄"| OUT["直播文稿.docx<br/>六色标记 + clean.txt + 待确认清单"]
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图2 · 哪里不对改哪里（三种修改路径）<span class="tag">核心图</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
subgraph 路径1["路径1 · 内容级打回（最常见）"]
|
||||
A1["人工/质检发现段3不对"] --> A2["打回段3 + 写意见"]
|
||||
A2 --> A3["段3 Agent：读取意见+自己记忆<br/>重新生成段3"]
|
||||
A3 --> A4["段3 重新质检 → 复审"]
|
||||
A1 -.-> A5["其他段 1/2/4 原封不动 ✅"]
|
||||
end
|
||||
subgraph 路径2["路径2 · 规则级修正"]
|
||||
B1["你改 rules.md（如：技法段要求改）"] --> B2["该Agent按新规则重跑"]
|
||||
B2 --> B3["质检 → 审查"]
|
||||
end
|
||||
subgraph 路径3["路径3 · 人工直接改"]
|
||||
C1["审查时直接在产物上改"] --> C2["改动记录沉淀进该Agent记忆"]
|
||||
C2 --> C3["改后照常质检/放行"]
|
||||
end
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图3 · 记忆闭环（越用越懂 · 每Agent隔离）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
R["打回意见 / 质检FAIL / 你改规则"] --> W{"写入触发"}
|
||||
W -->|"人工打回"| M1["该段Agent记忆 L3偏好<br/>（结构化：来源/内容/状态）"]
|
||||
W -->|"质检FAIL"| M2["质检Agent记忆 L2错误模式<br/>（同类错误下次直接查）"]
|
||||
W -->|"你改规则"| M3["规则记忆 L1<br/>（等同永久生效）"]
|
||||
W -->|"你确认复盘（可选）"| M4["成功记忆 L4<br/>（防噪音，不自动写）"]
|
||||
M1 --> NEXT["下次该Agent运行时注入记忆<br/>+ 规则文件 + 任务单切片"]
|
||||
M2 --> NEXT
|
||||
M3 --> NEXT
|
||||
M4 --> NEXT
|
||||
NEXT --> OUT2["产出质量随轮次提升<br/>同一错误二次打回率↓"]
|
||||
style M1 fill:#2d6a4f
|
||||
style M2 fill:#1d3557
|
||||
style M3 fill:#6d597a
|
||||
style M4 fill:#7f5539
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图4 · 上下文/记忆隔离边界</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TB
|
||||
subgraph 隔离区["每个Agent的私有空间（互不可见）"]
|
||||
R1["rules.md 规则文件"]
|
||||
M1["记忆库（独立命名空间）"]
|
||||
CTX["会话上下文（只含自己的任务切片）"]
|
||||
end
|
||||
subgraph 共享区["全Agent共享（只读）"]
|
||||
KB["📚 共享知识库<br/>风格/框架/原文/备稿/产品/质检规则"]
|
||||
TS["任务单 TaskSpec（主控产出）"]
|
||||
end
|
||||
A["段Agent"] -->|"读"| R1
|
||||
A -->|"读写"| M1
|
||||
A -->|"只读"| KB
|
||||
A -->|"只读自己的切片"| TS
|
||||
B["质检Agent"] -->|"读写"| M2["自己的错误模式记忆"]
|
||||
B -->|"只读"| KB
|
||||
B -->|"只读被检段产物"| TS
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<footer>雅文内容创造工作台 v1 · 设计评审稿 · 生成于 2026-08-25</footer>
|
||||
</body>
|
||||
</html>
|
||||
+120
@@ -0,0 +1,120 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>雅文内容创造工作台 · 流程图 v2</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
body { background:#0f1117; color:#e6e6e6; font-family:"Microsoft YaHei",system-ui,sans-serif; margin:0; padding:24px; }
|
||||
h1 { text-align:center; font-size:22px; color:#fff; margin-bottom:4px; }
|
||||
.sub { text-align:center; color:#888; font-size:13px; margin-bottom:28px; }
|
||||
.card { background:#1a1d27; border:1px solid #2a2e3d; border-radius:12px; padding:20px 16px; margin-bottom:28px; }
|
||||
.card h2 { font-size:16px; color:#ffd479; margin:0 0 14px 8px; }
|
||||
.mermaid { display:flex; justify-content:center; overflow-x:auto; }
|
||||
.tag { display:inline-block; background:#2a2e3d; color:#9aa4bf; font-size:12px; padding:2px 10px; border-radius:10px; margin-left:8px; font-weight:normal;}
|
||||
footer { text-align:center; color:#555; font-size:12px; margin-top:16px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>雅文内容创造工作台 · 流程图 v2</h1>
|
||||
<div class="sub">Agent注册中心 · 波次调度 · 锚点卡契约 · 组合一致性总检 · 记忆人工确认｜B方案 ｜ 2026-08-25</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图1 · 主流程 v2 <span class="tag">核心图</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
U["👩 你：输入主题/导图/框架"] --> C["主控Agent<br/>解析导图→任务单"]
|
||||
C -->|"读不准的词→待确认清单问你"| TS["任务单 TaskSpec<br/>段+时间轴+产品节点+质检项"]
|
||||
TS --> W1["波次1（并行）<br/>开场段Agent | 服务Agent预热"]
|
||||
W1 --> W2["波次2（并行，读开场锚点卡）<br/>心法段Agent | 技法段Agent"]
|
||||
W2 --> W3["波次3（并行，读心法/技法锚点卡）<br/>场景段Agent | 产品段Agent"]
|
||||
W3 --> W4["波次4（读全部锚点卡）<br/>收尾段Agent | 互动标记Agent"]
|
||||
W4 --> AQ["每段产物 + 锚点卡AnchorCard"]
|
||||
AQ --> QC["4道质检闸：结构/内容/风格尺度/跨稿<br/>（质检报告逐条对证正文+锚点卡）"]
|
||||
QC -->|"FAIL→打回原段"| AQ
|
||||
QC -->|"✅全过"| HR["人工审查台（硬关卡）<br/>逐段：产物+质检报告+锚点卡"]
|
||||
HR -->|"🔁打回→意见生成记忆建议"| PM["记忆待确认池"]
|
||||
HR -->|"✅全部确认"| CM["组合Agent<br/>时间轴拼装→一致性总检(5项)"]
|
||||
CM -->|"发现矛盾/回指断裂→打回对应段"| AQ
|
||||
CM -->|"微衔接→缝合编辑（必须标记）"| OUT["直播文稿.docx（六色）<br/>+组合报告+待确认清单"]
|
||||
PM -->|"你确认→写入"| MEM["对应Agent记忆库"]
|
||||
PM -->|"你拒绝/屏蔽→丢弃"| D["✖"]
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图2 · 上下文契约：锚点卡机制 <span class="tag">为什么段间不会"互不懂"</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
subgraph 上游["段2 技法段Agent 产出"]
|
||||
A2["段2 全文产物"]
|
||||
AC2["锚点卡（一页摘要）<br/>技法名：八爪鱼收紧术<br/>痛点：干涩→油<br/>情绪：高·演示"]
|
||||
end
|
||||
A2 --> AC2
|
||||
subgraph 下游["段3 产品段Agent（隔离）"]
|
||||
B["只读：段2锚点卡<br/>❌不读段2全文<br/>❌不共享对话"]
|
||||
OUT3["段3 产物：<br/>'刚才教的八爪鱼收紧术，配这瓶油…'<br/>✅回指一致"]
|
||||
end
|
||||
AC2 -->|"主控转交"| B
|
||||
subgraph 组合["组合Agent 总检"]
|
||||
CHK["一致性总检<br/>回指断裂？矛盾？时间线？情绪曲线？钩子？"]
|
||||
CHK -->|"发现断裂→打回对应段"| A2
|
||||
CHK -->|"通过→拼装交付"| DOC["📄 docx"]
|
||||
end
|
||||
OUT3 --> CHK
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图3 · 哪里不对改哪里（三种路径）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
subgraph P1["路径1 内容级打回"]
|
||||
A1["质检或审查发现段3不对"] --> A2["打回段3+意见"]
|
||||
A2 --> A3["段3Agent：读意见+自己记忆+上游锚点卡<br/>重新生成"]
|
||||
A3 --> A4["段3重新质检→复审"]
|
||||
A1 -.-> A5["段1/2/4原封不动✅"]
|
||||
end
|
||||
subgraph P2["路径2 规则级修正"]
|
||||
B1["工作台改该Agent rules.md（带版本）"] --> B2["按新规则重跑该环节"]
|
||||
end
|
||||
subgraph P3["路径3 人工直接改"]
|
||||
C1["审查时直接改产物（标记）"] --> C2["生成记忆建议→待确认池"]
|
||||
end
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图4 · 记忆闭环 v2（人工确认后才沉淀）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
SRC["沉淀来源<br/>打回意见 / 质检FAIL / 你改规则 / 复盘"] --> PM["📥 记忆待确认池<br/>（每条：目标Agent+类型+内容+来源）"]
|
||||
PM -->|"✅ 你确认"| W["写入对应Agent记忆库<br/>L1规则/L2纠错/L3偏好/L4成功"]
|
||||
PM -->|"❌ 拒绝"| DR["丢弃"]
|
||||
PM -->|"🚫 屏蔽同类"| BL["该来源类型不再建议"]
|
||||
W --> N["下次该Agent运行时注入<br/>+规则+任务切片+上游锚点卡"]
|
||||
N --> O["产出质量提升，同一错误二次打回率↓"]
|
||||
style PM fill:#6d597a
|
||||
style W fill:#2d6a4f
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图5 · Agent 注册中心（随便添加，数量不限）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TB
|
||||
MAN["👩 你：Agent管理页"] -->|"新建向导5步"| NEW["新Agent<br/>名称/职责/规则(rules.md模板+规则片段库)<br/>输入来源(读谁锚点卡)/知识库勾选"]
|
||||
MAN -->|"复制"| CP["复制现有Agent改名改规则<br/>（如：复制场景段→青蛇白蛇段）"]
|
||||
MAN -->|"停用"| DIS["停用（不派单，历史保留）"]
|
||||
NEW --> REG["Agent注册中心<br/>agent_id/类型/标签/版本历史"]
|
||||
CP --> REG
|
||||
REG -->|"拖进流水线"| PL["流水线编辑器<br/>节点=Agent 边=依赖<br/>质检挂载/执行顺序"]
|
||||
PL -->|"主控按依赖分波次调度"| RUN["执行 ✅"]
|
||||
style REG fill:#1d3557
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<footer>雅文内容创造工作台 v2 · B方案 · 2026-08-25</footer>
|
||||
</body>
|
||||
</html>
|
||||
+126
@@ -0,0 +1,126 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>雅文内容创造工作台 · 流程图 v3</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
body { background:#0f1117; color:#e6e6e6; font-family:"Microsoft YaHei",system-ui,sans-serif; margin:0; padding:24px; }
|
||||
h1 { text-align:center; font-size:22px; color:#fff; margin-bottom:4px; }
|
||||
.sub { text-align:center; color:#888; font-size:13px; margin-bottom:28px; }
|
||||
.card { background:#1a1d27; border:1px solid #2a2e3d; border-radius:12px; padding:20px 16px; margin-bottom:28px; }
|
||||
.card h2 { font-size:16px; color:#ffd479; margin:0 0 14px 8px; }
|
||||
.mermaid { display:flex; justify-content:center; overflow-x:auto; }
|
||||
.tag { display:inline-block; background:#2a2e3d; color:#9aa4bf; font-size:12px; padding:2px 10px; border-radius:10px; margin-left:8px; font-weight:normal;}
|
||||
footer { text-align:center; color:#555; font-size:12px; margin-top:16px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>雅文内容创造工作台 · 流程图 v3</h1>
|
||||
<div class="sub">Agent关系画布 · 内容类型标签 · 多知识库隔离挂接 · 锚点卡契约 · 记忆人工确认｜2026-08-25</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图1 · Agent 关系画布 <span class="tag">核心：顺序可改/单独启停/任意连线</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
M["主控Agent<br/>导图→任务单"] --> A["开场 ●"]
|
||||
A --> X1["心法Agent1 ●"]
|
||||
A -.->|"可选读取"| X2["心法Agent2 ○停用<br/>（不生成，跳过）"]
|
||||
X1 --> AL["案例 ●"]
|
||||
X1 --> J1["技法Agent1 ●"]
|
||||
X1 --> J2["技法Agent2 ●<br/>（同类可多个，并行）"]
|
||||
X1 --> G["功法 ●"]
|
||||
AL --> P["产品销售 ●<br/>（挂：产品知识库）"]
|
||||
J1 --> V["画面 ●"]
|
||||
J2 --> V
|
||||
G --> S["场景 ●"]
|
||||
V --> E["收尾 ●"]
|
||||
S --> E
|
||||
P --> E
|
||||
E --> H["钩子 ●"]
|
||||
H --> CM["组合Agent<br/>拼装+一致性总检"]
|
||||
style X2 fill:#444,color:#999,stroke-dasharray: 5 5
|
||||
style M fill:#1d3557
|
||||
style CM fill:#6d597a
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图2 · 内容类型标签与派单（同类可多个）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
MG["导图节点们"] -->|"主控标标签"| SEG["内容段<br/>段1=心法·女人如水<br/>段2=技法·八爪鱼收紧术<br/>段3=技法·三指游龙<br/>段4=产品销售·油<br/>…（同类多段不合并）"]
|
||||
SEG --> MATCH{"按标签匹配<br/>启用中的Agent"}
|
||||
MATCH -->|"技法×2"| J1["技法Agent1 节点"]
|
||||
MATCH -->|"技法×2"| J2["技法Agent2 节点"]
|
||||
MATCH -->|"心法×1"| X1["心法Agent 节点"]
|
||||
MATCH -->|"产品销售×1"| P1["产品销售Agent 节点"]
|
||||
J1 --> QC["质检+审查+组合"]
|
||||
J2 --> QC
|
||||
X1 --> QC
|
||||
P1 --> QC
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图3 · 多知识库隔离挂接</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TB
|
||||
subgraph 库区["📚 知识库（可建多个，互相隔离）"]
|
||||
KB1["风格档案库"]
|
||||
KB2["产品知识库"]
|
||||
KB3["直播原文库"]
|
||||
KB4["你建的库：青蛇白蛇素材库"]
|
||||
end
|
||||
subgraph Agent区["Agent 挂接配置（多选）"]
|
||||
PA["产品销售Agent<br/>☑风格档案 ☑产品知识库<br/>☐原文库 ☐青蛇库"]
|
||||
JA["技法Agent<br/>☑风格档案 ☑直播原文库<br/>☐产品库"]
|
||||
QA["跨稿质检<br/>☑备稿库 ☑框架库"]
|
||||
end
|
||||
KB1 --> PA
|
||||
KB2 --> PA
|
||||
KB1 --> JA
|
||||
KB3 --> JA
|
||||
PA -.->|"不可见"| X1["产品Agent查不到原文库/青蛇库"]
|
||||
JA -.->|"不可见"| X2["技法Agent查不到产品库"]
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图4 · 锚点卡契约 + 组合一致性总检 <span class="tag">防段间互不懂</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
subgraph 上游["技法段Agent 产出"]
|
||||
A2["技法段全文"]
|
||||
AC["锚点卡（一页）<br/>技法名/痛点/情绪基调/钩子"]
|
||||
end
|
||||
A2 --> AC
|
||||
subgraph 下游["产品销售Agent（隔离）"]
|
||||
B["只读锚点卡<br/>❌不读全文 ❌不共享对话"]
|
||||
O3["'刚才教的八爪鱼收紧术配这瓶油…'✅"]
|
||||
end
|
||||
AC --> B
|
||||
O3 --> CHK["组合Agent 一致性总检<br/>矛盾/回指/时间线/情绪曲线/钩子"]
|
||||
CHK -->|"断裂→打回对应段"| A2
|
||||
CHK -->|"微衔接→缝合标记"| D["📄 docx+组合报告"]
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图5 · 记忆闭环（人工确认后才沉淀）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
SRC["打回意见/质检FAIL/复盘"] --> PM["记忆待确认池"]
|
||||
PM -->|"✅确认"| MEM["该Agent记忆库（隔离命名空间）"]
|
||||
PM -->|"❌拒绝/🚫屏蔽"| D["✖"]
|
||||
MEM --> INJ["下次运行时注入：规则+记忆+任务切片+上游锚点卡+挂接知识库"]
|
||||
INJ --> BETTER["质量提升，二次打回率↓"]
|
||||
style PM fill:#6d597a
|
||||
style MEM fill:#2d6a4f
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<footer>雅文内容创造工作台 v3 · 开放画布版 · 2026-08-25</footer>
|
||||
</body>
|
||||
</html>
|
||||
+201
@@ -0,0 +1,201 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>雅文内容创造工作台 · 流程图 v4</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
body { background:#0f1117; color:#e6e6e6; font-family:"Microsoft YaHei",system-ui,sans-serif; margin:0; padding:24px; }
|
||||
h1 { text-align:center; font-size:22px; color:#fff; margin-bottom:4px; }
|
||||
.sub { text-align:center; color:#888; font-size:13px; margin-bottom:28px; }
|
||||
.card { background:#1a1d27; border:1px solid #2a2e3d; border-radius:12px; padding:20px 16px; margin-bottom:28px; }
|
||||
.card h2 { font-size:16px; color:#ffd479; margin:0 0 14px 8px; }
|
||||
.mermaid { display:flex; justify-content:center; overflow-x:auto; }
|
||||
.tag { display:inline-block; background:#2a2e3d; color:#9aa4bf; font-size:12px; padding:2px 10px; border-radius:10px; margin-left:8px; font-weight:normal;}
|
||||
footer { text-align:center; color:#555; font-size:12px; margin-top:16px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>雅文内容创造工作台 · 流程图 v4</h1>
|
||||
<div class="sub">开放画布 + RAG知识库 + 26内容标签 + 锚点卡契约 + 记忆人工确认｜2026-08-25</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图1 · RAG 知识库建库管道 <span class="tag">导入即建，全自动</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
F["素材文件<br/>docx / srt / md / txt / json / 导图"] --> P1["① 导入<br/>拖拽上传+进度条"]
|
||||
P1 --> P2["② 格式解析<br/>docx提取正文 / srt去时间戳 / json结构抽取"]
|
||||
P2 --> P3["③ 清洗<br/>去空行/提词备注/字幕断句合并"]
|
||||
P3 --> P4["④ 分块<br/>标题感知+语义边界 400-600字 重叠15%<br/>元数据：库/文件/章节/序号"]
|
||||
P4 --> P5["⑤ 向量化<br/>BGE-M3 本地Embedding（离线，数据不出本机）"]
|
||||
P5 --> P6["⑥ 入库<br/>ChromaDB collection=知识库（天然隔离）"]
|
||||
P6 --> P7["⑦ 检索测试页<br/>输入query验证命中质量"]
|
||||
style P6 fill:#1d3557
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图2 · Agent 取料（混合检索+引用溯源）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
A["生产Agent 生成请求"] --> Q["query构造<br/>任务切片+上游锚点卡+检索意图"]
|
||||
Q --> H{"混合检索<br/>只在挂接的collection内"}
|
||||
H -->|"向量 top-k"| V["BGE-M3 语义相似度"]
|
||||
H -->|"关键词 top-k"| K["BM25 精确命中<br/>（技法名/产品名/暗语）"]
|
||||
V --> M["合并去重"]
|
||||
K --> M
|
||||
M --> R["可选：rerank重排"]
|
||||
R --> S["引用溯源<br/>每条带：库/文件/章节/原文块/相似度"]
|
||||
S --> INJ["注入Agent上下文<br/>（后台标注来源，正文不出现'知识库里说'）"]
|
||||
INJ --> OUT["段产物"]
|
||||
OUT --> QC["质检一键核对引用<br/>选中一句→看引用→对证原文"]
|
||||
QC -->|"查无来源=FAIL"| A
|
||||
style QC fill:#6d597a
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图3 · 知识库隔离与 Agent 挂接</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TB
|
||||
subgraph KB["📚 知识库（ChromaDB collection 物理隔离）"]
|
||||
C1["风格档案库"]
|
||||
C2["产品知识库"]
|
||||
C3["直播原文库（73场SRT）"]
|
||||
C4["备稿库（99篇）"]
|
||||
C5["你建的库：青蛇白蛇素材库"]
|
||||
end
|
||||
subgraph AG["Agent 挂接（多选）"]
|
||||
PA["产品销售Agent<br/>☑风格档案 ☑产品知识库"]
|
||||
JA["技法Agent<br/>☑风格档案 ☑直播原文库"]
|
||||
end
|
||||
C1 --> PA
|
||||
C2 --> PA
|
||||
C1 --> JA
|
||||
C3 --> JA
|
||||
PA -.->|"查不到"| X["原文库/青蛇库"]
|
||||
JA -.->|"查不到"| Y["产品库"]
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图4 · Agent 关系画布（顺序可改/单独启停/任意连线）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
M["主控Agent"] --> A["开场 ●"]
|
||||
A --> X1["心法Agent1 ●"]
|
||||
A -.->|"可选"| X2["心法Agent2 ○停用"]
|
||||
X1 --> J1["技法Agent1 ●"]
|
||||
X1 --> J2["技法Agent2 ● 并行"]
|
||||
X1 --> G["功法 ●"]
|
||||
J1 --> P["产品销售 ●"]
|
||||
J2 --> V["画面 ●"]
|
||||
G --> S["场景 ●"]
|
||||
V --> E["收尾 ●"]
|
||||
S --> E
|
||||
P --> E
|
||||
E --> H["钩子 ●"]
|
||||
H --> CM["组合Agent"]
|
||||
style X2 fill:#444,color:#999,stroke-dasharray: 5 5
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图5 · 内容标签体系（26个 / 6大类 / ★核心13个）</h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
subgraph 结构["结构类"]
|
||||
A1["开场★"]; A2["转场"]; A3["收尾★"]; A4["钩子★"]; A5["预告"]
|
||||
end
|
||||
subgraph 内容["内容类"]
|
||||
B1["心法★"]; B2["痛点★"]; B3["动机铺垫★"]; B4["案例★"]; B5["见证"]
|
||||
B6["冷知识"]; B7["金句★"]; B8["共鸣"]
|
||||
end
|
||||
subgraph 技法["技法类"]
|
||||
C1["技法★"]; C2["功法★"]; C3["跟练★"]; C4["安全提示"]
|
||||
end
|
||||
subgraph 产品["产品类"]
|
||||
D1["产品销售★"]; D2["产品体验★"]; D3["产品回指"]
|
||||
end
|
||||
subgraph 表现["表现类"]
|
||||
E1["画面★"]; E2["场景★"]; E3["情绪"]; E4["氛围"]; E5["互动"]
|
||||
end
|
||||
subgraph 辅助["辅助类"]
|
||||
F1["答疑"]; F2["双主播"]; F3["毛边"]; F4["仪式"]
|
||||
end
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图6 · 模型管理（每个 Agent 可选不同模型）<span class="tag">新增</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
subgraph 模型池["模型注册（OpenAI 兼容，可同时挂多个）"]
|
||||
M1["🟦 DeepSeek<br/>deepseek-chat / R1"]
|
||||
M2["🟩 硅基流动 / 智谱GLM"]
|
||||
M3["🟧 Kimi / 通义"]
|
||||
M4["⬜ 本地 Ollama"]
|
||||
end
|
||||
subgraph 画布["画布节点（每Agent独立选模型）"]
|
||||
A1["主控Agent 🟦DeepSeek-R1<br/>（强推理：拆解/调度）"]
|
||||
A2["心法Agent 🟩GLM<br/>（文风对比）"]
|
||||
A3["画面Agent 🟧Kimi<br/>（文风对比）"]
|
||||
A4["质检Agent 🟦DeepSeek-R1<br/>（严格规则执行）"]
|
||||
A5["组合Agent 🟦长上下文<br/>（拼装+总检读全稿）"]
|
||||
end
|
||||
M1 --> A1
|
||||
M1 --> A4
|
||||
M1 --> A5
|
||||
M2 --> A2
|
||||
M3 --> A3
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图7 · 节点状态机 <span class="tag">每个Agent工作状态清晰可见</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart LR
|
||||
P["待派发 🟦灰"] --> R["生成中 🟦蓝<br/>（显示模型+已耗时）"]
|
||||
R --> Q["质检中 🟡黄<br/>（显示第几道）"]
|
||||
Q --> H["待人工审查 🟣紫"]
|
||||
H -->|"✅通过"| A["已通过 🟢绿"]
|
||||
H -->|"🔁打回"| RW["打回重做 🟠橙<br/>（显示第几轮）"]
|
||||
RW --> R
|
||||
R -->|"生成失败"| F["⚠️失败 🔴红<br/>（点击看原因）"]
|
||||
Q -->|"质检FAIL"| RW
|
||||
F -->|"人工修复后重跑"| R
|
||||
F -->|"人工跳过"| SK["跳过 ⬜灰斜线"]
|
||||
F -->|"停用节点"| D["停用 ⬛暗"]
|
||||
P -->|"上游停用"| SK
|
||||
style F fill:#7f1d1d,color:#fff
|
||||
style A fill:#14532d,color:#fff
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<div class="card">
|
||||
<h2>图8 · 失败处理闭环 <span class="tag">生成不出来 → 必提醒人工</span></h2>
|
||||
<pre class="mermaid">
|
||||
flowchart TD
|
||||
FAIL["Agent 生成失败"] --> RETRY{"可自动重试？<br/>超时/限流/截断"}
|
||||
RETRY -->|"是（最多2次）"| R1["指数退避重试"]
|
||||
R1 -->|"成功"| OK["✅ 继续流程"]
|
||||
R1 -->|"仍失败"| MAN
|
||||
RETRY -->|"否（拒审/Key错误/余额不足）"| MAN["🔴 转人工<br/>节点红标+通知中心提醒<br/>（不静默、不假装成功）"]
|
||||
MAN --> PANEL["失败处理面板<br/>失败Agent/模型/错误原文/调用日志/输入上下文"]
|
||||
PANEL --> ACT["人工修复动作"]
|
||||
ACT -->|"🔁重试"| R1
|
||||
ACT -->|"🔄换模型"| M2["换模型重跑"]
|
||||
ACT -->|"📝改规则"| R2["改rules.md重跑"]
|
||||
ACT -->|"✂️调任务切片"| R3["改写段描述重跑"]
|
||||
ACT -->|"⏭️跳过"| SK["跳过（组合注明缺段）"]
|
||||
ACT -->|"⏸️停用"| D["停用节点"]
|
||||
ACT --> MEM["填修复原因 → 记忆建议<br/>→ 待确认池 → 沉淀防复发"]
|
||||
style MAN fill:#7f1d1d,color:#fff
|
||||
style MEM fill:#6d597a
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<footer>雅文内容创造工作台 v4 · RAG知识库版 · 2026-08-25</footer>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,103 @@
|
||||
# 雅文内容创造工作台源码交付说明
|
||||
|
||||
> 交付日期：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`。业务数据库和知识资料不包含在源码包内，需要在目标环境重新初始化或单独通过受控迁移交付。
|
||||
@@ -0,0 +1,14 @@
|
||||
# 源码包说明
|
||||
|
||||
文件：`yawan-workbench-source-20260914.tar.gz`
|
||||
|
||||
本包包含当前系统的服务端、前端、脚本、测试和设计文档源码。为避免泄露生产信息和生成超大压缩包，以下内容未包含：
|
||||
|
||||
- 生产数据库、知识库原文、向量索引和运行日志；
|
||||
- `.env.production` 生产配置和密钥；
|
||||
- Python 虚拟环境、Node 依赖、前端构建缓存；
|
||||
- 外接盘备份和 Python 缓存文件。
|
||||
|
||||
部署时请复制 `.env.production.example` 为 `.env.production`，再填写实际配置；运行数据目录需要由部署环境单独提供。
|
||||
|
||||
同目录的 `.sha256` 文件用于校验压缩包完整性。
|
||||
@@ -0,0 +1,26 @@
|
||||
# 雅文内容创造工作台 - 源码包说明
|
||||
|
||||
本源码包不包含本机运行数据、知识库原文件、向量索引、模型缓存、数据库和 API 密钥。
|
||||
|
||||
## 包含内容
|
||||
|
||||
- `server/app/`：FastAPI 后端、Agent 编排、知识库和数据模型源码。
|
||||
- `server/scripts/`：维护、导入和初始化脚本。
|
||||
- `server/requirements.txt`：后端依赖清单。
|
||||
- `web/src/`：React + Vite 前端源码。
|
||||
- `web/package.json`、`web/pnpm-lock.yaml`：前端依赖与锁文件。
|
||||
- 根目录的设计文档、流程图、验收报告与启动脚本。
|
||||
|
||||
## 首次安装
|
||||
|
||||
```powershell
|
||||
cd server
|
||||
py -3.11 -m venv .venv
|
||||
.\.venv\Scripts\pip install -r requirements.txt
|
||||
|
||||
cd ..\web
|
||||
corepack enable
|
||||
pnpm install
|
||||
```
|
||||
|
||||
完成后从项目根目录双击 `启动工作台.bat`，浏览器打开 `http://localhost:5173/`。
|
||||
+260
@@ -0,0 +1,260 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>私域Agent · 用户使用手册</title>
|
||||
<style>
|
||||
:root {
|
||||
--page: #f7f8fa; --bg: #ffffff; --panel: #f6f6f6;
|
||||
--border: #e3e7f1; --ink-1: #18181a; --ink-2: #3f4148; --ink-3: #8b8e98;
|
||||
--jade: #1f6b52; --jade-soft: rgba(31,107,82,.08); --gold: #c4a962;
|
||||
--warn: #c98a1b; --down: #d5484d;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
body { margin: 0; background: var(--page); color: var(--ink-2); font-family: Inter, "Noto Sans SC", "PingFang SC", "Microsoft YaHei UI", system-ui, sans-serif; font-size: 14px; line-height: 1.85; }
|
||||
.wrap { max-width: 960px; margin: 0 auto; padding: 40px 24px 80px; }
|
||||
|
||||
/* 封面 */
|
||||
.cover { text-align: center; padding: 56px 20px 44px; background: var(--bg); border: 1px solid var(--border); border-radius: 24px; margin-bottom: 28px; }
|
||||
.cover .logo { width: 56px; height: 56px; margin: 0 auto 18px; display: grid; place-items: center; border-radius: 14px; background: linear-gradient(135deg, #1f6b52, #2e8b6a); color: #fff8e7; font-size: 26px; font-weight: 700; border: .5px solid var(--gold); }
|
||||
.cover h1 { margin: 0 0 6px; color: var(--ink-1); font-size: 30px; font-weight: 650; letter-spacing: -.01em; }
|
||||
.cover p { margin: 0; color: var(--ink-3); font-size: 14px; }
|
||||
.cover .meta { margin-top: 16px; display: inline-flex; gap: 8px; flex-wrap: wrap; justify-content: center; }
|
||||
.cover .meta span { padding: 3px 12px; border-radius: 999px; background: var(--panel); color: var(--ink-3); font-size: 11.5px; }
|
||||
|
||||
/* 章节 */
|
||||
h2.sec { margin: 44px 0 6px; color: var(--ink-1); font-size: 21px; font-weight: 650; display: flex; align-items: center; gap: 10px; }
|
||||
h2.sec .no { flex: 0 0 30px; width: 30px; height: 30px; display: grid; place-items: center; border-radius: 9px; background: var(--jade); color: #fff; font-size: 14px; font-weight: 700; }
|
||||
.sec-sub { margin: 0 0 14px 40px; color: var(--ink-3); font-size: 12.5px; }
|
||||
|
||||
.card { background: var(--bg); border: 1px solid var(--border); border-radius: 14px; padding: 20px 22px; margin: 14px 0; }
|
||||
.card h3 { margin: 0 0 8px; color: var(--ink-1); font-size: 15px; font-weight: 600; }
|
||||
.card p { margin: 6px 0; }
|
||||
|
||||
/* 步骤 */
|
||||
.steps { counter-reset: step; margin: 10px 0; padding: 0; list-style: none; }
|
||||
.steps li { counter-increment: step; position: relative; padding: 0 0 14px 44px; }
|
||||
.steps li::before { content: counter(step); position: absolute; left: 0; top: 2px; width: 26px; height: 26px; display: grid; place-items: center; border-radius: 50%; background: var(--jade-soft); color: var(--jade); font-size: 13px; font-weight: 700; }
|
||||
.steps li::after { content: ""; position: absolute; left: 13px; top: 32px; bottom: 2px; width: 1px; background: var(--border); }
|
||||
.steps li:last-child::after { display: none; }
|
||||
.steps b { color: var(--ink-1); }
|
||||
|
||||
/* 提示条 */
|
||||
.tip, .warn, .danger { display: flex; gap: 10px; align-items: flex-start; padding: 12px 16px; border-radius: 10px; margin: 12px 0; font-size: 13px; }
|
||||
.tip { background: var(--jade-soft); border: 1px solid rgba(31,107,82,.18); }
|
||||
.warn { background: rgba(201,138,27,.08); border: 1px solid rgba(201,138,27,.25); }
|
||||
.danger { background: rgba(213,72,77,.07); border: 1px solid rgba(213,72,77,.25); }
|
||||
.tip::before { content: "💡"; }
|
||||
.warn::before { content: "⚠️"; }
|
||||
.danger::before { content: "🚫"; }
|
||||
|
||||
/* 表格 */
|
||||
table { width: 100%; border-collapse: collapse; margin: 12px 0; background: var(--bg); border: 1px solid var(--border); border-radius: 12px; overflow: hidden; font-size: 13px; }
|
||||
th { background: var(--panel); color: var(--ink-1); font-weight: 600; text-align: left; padding: 10px 14px; border-bottom: 1px solid var(--border); }
|
||||
td { padding: 10px 14px; border-bottom: 1px solid var(--border); vertical-align: top; }
|
||||
tr:last-child td { border-bottom: 0; }
|
||||
td b { color: var(--ink-1); }
|
||||
code { padding: 1px 7px; border-radius: 6px; background: var(--panel); color: var(--jade); font-size: 12.5px; font-family: "SF Mono", Menlo, Consolas, monospace; }
|
||||
kbd { padding: 2px 7px; border-radius: 6px; background: var(--ink-1); color: #fff; font-size: 11.5px; font-family: inherit; }
|
||||
|
||||
/* 流程图 */
|
||||
.flow { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin: 14px 0; }
|
||||
.flow .node { padding: 8px 16px; border-radius: 10px; background: var(--bg); border: 1px solid var(--border); font-size: 13px; font-weight: 600; color: var(--ink-1); }
|
||||
.flow .node.hot { background: var(--jade); border-color: var(--jade); color: #fff; }
|
||||
.flow .arr { color: var(--ink-3); }
|
||||
|
||||
/* FAQ */
|
||||
details { background: var(--bg); border: 1px solid var(--border); border-radius: 12px; padding: 0; margin: 10px 0; overflow: hidden; }
|
||||
summary { cursor: pointer; padding: 14px 18px; font-weight: 600; color: var(--ink-1); list-style: none; display: flex; align-items: center; gap: 10px; }
|
||||
summary::before { content: "?"; flex: 0 0 22px; width: 22px; height: 22px; display: grid; place-items: center; border-radius: 50%; background: var(--jade-soft); color: var(--jade); font-size: 13px; font-weight: 700; }
|
||||
details[open] summary { border-bottom: 1px solid var(--border); }
|
||||
details .ans { padding: 14px 18px 16px 50px; }
|
||||
|
||||
.toc { background: var(--bg); border: 1px solid var(--border); border-radius: 14px; padding: 18px 22px; }
|
||||
.toc b { color: var(--ink-1); }
|
||||
.toc ol { margin: 8px 0 0; padding-left: 22px; }
|
||||
.toc li { margin: 3px 0; }
|
||||
.toc a { color: var(--jade); text-decoration: none; }
|
||||
.toc a:hover { text-decoration: underline; }
|
||||
@media print { body { background: #fff; } .cover { border: none; } }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="wrap">
|
||||
|
||||
<div class="cover">
|
||||
<div class="logo">私</div>
|
||||
<h1>私域Agent · 用户使用手册</h1>
|
||||
<p>导图进，成稿出。多智能体协作的内容生产中枢。</p>
|
||||
<div class="meta"><span>适用版本 v0.1</span><span>2026 年 8 月</span><span>阅读时间约 10 分钟</span></div>
|
||||
</div>
|
||||
|
||||
<div class="toc">
|
||||
<b>目录</b>
|
||||
<ol>
|
||||
<li><a href="#s1">第一次使用：登录</a></li>
|
||||
<li><a href="#s2">核心流程：从一段导图到一份成稿</a></li>
|
||||
<li><a href="#s3">任务看板：生成、审查、暂停与删除</a></li>
|
||||
<li><a href="#s4">知识库：导入、分类、编辑与迁移</a></li>
|
||||
<li><a href="#s5">Agent 画布与全局总监</a></li>
|
||||
<li><a href="#s6">Agent / 技能库 / 提示模板</a></li>
|
||||
<li><a href="#s7">模型管理与点数</a></li>
|
||||
<li><a href="#s8">用量账单 / 运营看板 / 日志与记忆</a></li>
|
||||
<li><a href="#s9">访问控制：成员与权限</a></li>
|
||||
<li><a href="#s10">常见问题 FAQ</a></li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<!-- ============ 1 登录 ============ -->
|
||||
<h2 class="sec" id="s1"><span class="no">1</span>第一次使用：登录</h2>
|
||||
<p class="sec-sub">拿到账号后，两分钟内进入工作台。</p>
|
||||
<div class="card">
|
||||
<ol class="steps">
|
||||
<li><b>打开系统地址</b>（管理员提供），页面右侧是登录表单。</li>
|
||||
<li><b>输入用户名和密码</b> → 点「登录」。密码连续输错 5 次会锁定 15 分钟，这是防暴力破解保护。</li>
|
||||
<li><b>进入总览页</b>。左侧导航栏是你能用的全部功能；没有权限的菜单不会出现。</li>
|
||||
</ol>
|
||||
<div class="warn">登录状态 12 小时有效，超时后系统会提示重新登录，正在生成的任务<b>不会因此中断</b>。</div>
|
||||
</div>
|
||||
|
||||
<!-- ============ 2 核心流程 ============ -->
|
||||
<h2 class="sec" id="s2"><span class="no">2</span>核心流程：从一段导图到一份成稿</h2>
|
||||
<p class="sec-sub">整个系统就为这一条流水线服务，看懂它就学会了 80%。</p>
|
||||
<div class="flow">
|
||||
<span class="node">① 新建任务<br><small>贴导图 / 传文件</small></span><span class="arr">→</span>
|
||||
<span class="node">② AI 拆解<br><small>导图变内容段</small></span><span class="arr">→</span>
|
||||
<span class="node hot">③ 开始生成<br><small>Agent 流水线</small></span><span class="arr">→</span>
|
||||
<span class="node">④ 审查<br><small>通过 / 打回</small></span><span class="arr">→</span>
|
||||
<span class="node">⑤ 合稿交付<br><small>下载成稿</small></span>
|
||||
</div>
|
||||
<div class="card">
|
||||
<ol class="steps">
|
||||
<li><b>新建任务</b>：进「任务看板」→ 点「＋ 新建任务」。唯一必填的是<b>任务目标</b>；导图可以粘贴文字、上传图片（自动 OCR）或导入 txt/md 文档。<b>验收标准</b>留空系统会自动生成，也可以点「✦ AI 建议验收标准」再手动修改。</li>
|
||||
<li><b>拆解</b>：点「创建并拆解」，AI 把导图编译成一个个内容段（每段有主题、时间区间、负责的 Agent）。拆解是幂等的，重复点击不会产生两套段落。</li>
|
||||
<li><b>生成</b>：点「▶ 开始生成」。各 Agent 按画布流程依次生产每一段，全程自动质检；画布设置了「全局总监」时，每段完成后总监还会审核是否跑偏。</li>
|
||||
<li><b>审查</b>：生成完的段落转「人工审查」。你逐段看，<b>通过</b>或<b>打回</b>（打回时写意见，Agent 会按你的意见重新生成，并自动沉淀记忆建议）。</li>
|
||||
<li><b>交付</b>：全部段落通过后自动合稿，任务看板里可预览全文并下载。</li>
|
||||
</ol>
|
||||
<div class="tip">点「开始生成」前系统会<b>自动做点数预检</b>：预估本次成本并与余额比对（含 20% 缓冲），余额不够会直接告知差额，不会让你跑到一半失败。</div>
|
||||
</div>
|
||||
|
||||
<!-- ============ 3 任务看板 ============ -->
|
||||
<h2 class="sec" id="s3"><span class="no">3</span>任务看板：生成、审查、暂停与删除</h2>
|
||||
<p class="sec-sub">这里是日常主战场。</p>
|
||||
<div class="card">
|
||||
<h3>生成中你能做的事</h3>
|
||||
<table>
|
||||
<tr><th style="width:130px">操作</th><th>说明</th></tr>
|
||||
<tr><td><b>⏸ 暂停</b></td><td>当前这段<b>做完后</b>停下（不浪费已花的点数），已完成段落保留。</td></tr>
|
||||
<tr><td><b>▶ 继续</b></td><td>从暂停处恢复，只跑剩余段落。</td></tr>
|
||||
<tr><td><b>■ 停止</b></td><td>终止本次运行，已生成内容保留在各自段落里。</td></tr>
|
||||
</table>
|
||||
<h3 style="margin-top:16px">关于失败与重试</h3>
|
||||
<p>单段失败（如网络超时）会自动重试，<b>不会</b>影响其他段。点数不足、Key 失效这类"不会自愈"的错误会触发<b>熔断</b>：整个任务立即停止并明确告知原因——点数类会提示「请联系管理员增加点数」，限流类会建议「更换其他模型」。</p>
|
||||
<h3 style="margin-top:16px">删除任务</h3>
|
||||
<p>任务卡片上的「删除任务」按钮可删除任务及其全部段落记录（运行中/暂停中的任务需先停止）。删除需二次确认，成稿文件保留在服务器供审计。</p>
|
||||
</div>
|
||||
|
||||
<!-- ============ 4 知识库 ============ -->
|
||||
<h2 class="sec" id="s4"><span class="no">4</span>知识库：导入、分类、编辑与迁移</h2>
|
||||
<p class="sec-sub">Agent 写稿的"素材库"。检索是语义级的，不依赖关键词完全匹配。</p>
|
||||
<div class="card">
|
||||
<ol class="steps">
|
||||
<li><b>建库</b>：知识库页 → 新建知识库。你建的库默认<b>只有你自己和管理员可见</b>。</li>
|
||||
<li><b>导入</b>：选中新库 → 「📤 上传到当前分类」，支持 docx / srt / md / txt / json / jsonl，单文件 ≤ 50MB。</li>
|
||||
<li><b>分类</b>：可在库内建<b>多级分类树</b>（一级/二级/任意层级）；「✦ AI 自动分类」会让 AI 预分类，你点「确认 AI 分类」生效。</li>
|
||||
<li><b>文件级管理</b>：每个已导入文件支持 <b>✏️ 在线编辑</b>（txt/md，保存自动重建索引）、<b>移到其他知识库</b>、<b>删除</b>（向量索引同步清理）。</li>
|
||||
<li><b>挂给 Agent</b>：到「Agent 管理」编辑某个 Agent 的「挂接知识库」，它生产时只从挂接的库里检索素材。</li>
|
||||
</ol>
|
||||
<div class="tip">「Agent 已消费知识」列表里的<b>锁定</b>片段：同一 Agent 不会重复使用同一段素材（避免成稿重复）；点「重新开放」可让它再次可用。</div>
|
||||
</div>
|
||||
|
||||
<!-- ============ 5 画布 ============ -->
|
||||
<h2 class="sec" id="s5"><span class="no">5</span>Agent 画布与全局总监</h2>
|
||||
<p class="sec-sub">画布决定"谁先写、谁后写、谁质检、谁兜底"。</p>
|
||||
<div class="card">
|
||||
<ol class="steps">
|
||||
<li><b>编排</b>：从左侧 Agent 列表点击添加节点，拖动连线建立上下游（上游写完 → 下游开工）。节点可停用（跳过不执行）。</li>
|
||||
<li><b>保存</b>：任务创建时会冻结画布快照，之后改画布<b>不影响</b>已建任务。</li>
|
||||
<li><b>全局总监（防跑偏）</b>：工具栏选择一个 Agent 作为总监，三档模式任选——
|
||||
<table>
|
||||
<tr><th style="width:170px">模式</th><th>行为</th></tr>
|
||||
<tr><td><b>疑似跑偏才审</b>（默认）</td><td>质检发现问题或重做过一轮才送审，省点数。</td></tr>
|
||||
<tr><td><b>每段必审</b></td><td>每段生成完总监都过目，重要交付用。</td></tr>
|
||||
<tr><td><b>仅记录不拦截</b></td><td>总监意见只记录，不自动重做。</td></tr>
|
||||
</table>
|
||||
总监判定跑偏后会给出「原因 + 拉回指导」，该段<b>自动带指导重做一次</b>；重做仍跑偏则转人工，不会无限烧点数。</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<!-- ============ 6 Agent/技能/模板 ============ -->
|
||||
<h2 class="sec" id="s6"><span class="no">6</span>Agent / 技能库 / 提示模板</h2>
|
||||
<p class="sec-sub">三件套决定每段内容的生产方式。</p>
|
||||
<div class="card">
|
||||
<ul>
|
||||
<li><b>Agent 管理</b>：每个 Agent 可配 挂接知识库、绑定技能、提示模板、模型、写作规则、工具权限。内置 15 个 Agent 覆盖拆解/生产/质检/组合全流程，全部<b>可删除</b>（被引用时会拦截提醒）。</li>
|
||||
<li><b>技能库</b>：可复用的写作方法（如"钩子设计"）。Agent 绑定后生成时自动注入。</li>
|
||||
<li><b>提示模板</b>：角色提示 + 任务模板 + 约束 + 输出结构，创建任务时冻结快照。</li>
|
||||
</ul>
|
||||
<div class="tip">三者创建时都有「<b>✦ AI 帮我创建</b>」入口：用大白话描述需求（像跟同事交代），AI 产出结构化草稿并自动做<b>冲突检测</b>（口语↔书面、要求自相矛盾、跨资源冲突等），确认后入库。</div>
|
||||
</div>
|
||||
|
||||
<!-- ============ 7 模型与点数 ============ -->
|
||||
<h2 class="sec" id="s7"><span class="no">7</span>模型管理与点数</h2>
|
||||
<p class="sec-sub">模型是"发动机"，点数是"油钱"。</p>
|
||||
<div class="card">
|
||||
<h3>模型管理</h3>
|
||||
<p>每个 Provider（如 DeepSeek）配 API Key（存 macOS 钥匙串，不落库）+ 模型列表。可用「测试连通」验证；可指定全局默认模型。遇到「限流」提示时，来这里<b>切换其他模型</b>即可。</p>
|
||||
<h3 style="margin-top:14px">点数规则</h3>
|
||||
<table>
|
||||
<tr><th>项目</th><th>规则</th></tr>
|
||||
<tr><td><b>折算</b></td><td>10 点数 = 1 Token，按实际用量扣。</td></tr>
|
||||
<tr><td><b>余额</b></td><td>余额本身不设上限；低于 10 点数暂停 AI 调用。</td></tr>
|
||||
<tr><td><b>发放</b></td><td>管理员在「用量与账单 → 用户点数」发放，支持三档快捷按钮：<b>一档 1千万 / 二档 1亿 / 三档 10亿</b>，也可手动输入任意数额。</td></tr>
|
||||
<tr><td><b>预检</b></td><td>启动生成前自动预估成本，余额需覆盖预估 + 20% 缓冲，不足时明确告知差额。</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<!-- ============ 8 数据面板 ============ -->
|
||||
<h2 class="sec" id="s8"><span class="no">8</span>用量账单 / 运营看板 / 日志与记忆</h2>
|
||||
<div class="card">
|
||||
<ul>
|
||||
<li><b>用量与账单</b>：看自己的 Token 用量与费用明细；管理员额外可看用户归属汇总和点数发放。</li>
|
||||
<li><b>运营看板</b>：管理员视角=全组织队列/任务/告警/备份；<b>普通用户只看到自己的任务与用量</b>（数据隔离在服务端强制）。</li>
|
||||
<li><b>日志与通知</b>：运行追踪（Trace）与系统通知。通知支持<b>「✓ 全部已读」</b>一键清零。普通用户只能看到自己发起的运行。</li>
|
||||
<li><b>记忆库</b>：打回意见会自动生成「待确认记忆」→ 你确认后沉淀为长期记忆，后续生成自动引用（相当于教 Agent 记住你的偏好）。</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<!-- ============ 9 访问控制 ============ -->
|
||||
<h2 class="sec" id="s9"><span class="no">9</span>访问控制：成员与权限</h2>
|
||||
<div class="card">
|
||||
<h3>添加成员</h3>
|
||||
<ol class="steps">
|
||||
<li>用户名 ≥ 3 个字符（字母/数字/._-，不支持中文）；初始密码 ≥ 10 个字符。表单下方有实时提示，两项都 ✓ 时「添加成员」按钮才会亮。</li>
|
||||
<li>选角色：只读 / 审查 / 编辑 / 管理员，或自定义角色。</li>
|
||||
</ol>
|
||||
<h3 style="margin-top:14px">权限体系</h3>
|
||||
<p>16 项细分权限分 4 组（内容生产 / 资产与知识 / 数据与洞察 / 系统管理），在「角色权限矩阵」逐项勾选。<b>保存后立即生效</b>；编辑期间页面轮询不会覆盖你未保存的勾选。</p>
|
||||
<div class="tip">资源可见性：用户自建的知识库/技能/模板/任务默认<b>私有</b>（仅本人+管理员）；需要共享时在资源授权里给指定成员授权，或「发布全局」对全组织可见。</div>
|
||||
</div>
|
||||
|
||||
<!-- ============ 10 FAQ ============ -->
|
||||
<h2 class="sec" id="s10"><span class="no">10</span>常见问题 FAQ</h2>
|
||||
<details><summary>点「开始生成」提示"点数不足"怎么办？</summary><div class="ans">提示里会写明<b>预估需要多少、你还差多少</b>。联系管理员在「用量与账单」按档位发放点数后重试即可。</div></details>
|
||||
<details><summary>生成中报"模型服务商限流（429）"？</summary><div class="ans">系统已自动放慢重试并尝试切换备用 Provider。若持续失败，到「模型管理」<b>更换其他模型</b>再重新运行失败段。</div></details>
|
||||
<details><summary>拆解失败 / 一直提示"任务还没有内容段"？</summary><div class="ans">拆解依赖 AI 调用。先到「模型管理」点「测试连通」确认当前模型可用（API Key 失效或服务商地域限制都会导致失败），修正后回到任务页重新点拆解。导图<b>不需要上传文件</b>，粘贴文字大纲即可。</div></details>
|
||||
<details><summary>为什么我看不到某个知识库 / 任务？</summary><div class="ans">资源默认私有，只有创建者和管理员可见。需要协作请让管理员在「访问控制 → 资源授权」给你授权，或将资源发布为全局。</div></details>
|
||||
<details><summary>密码忘了 / 账号被锁？</summary><div class="ans">联系管理员在「访问控制」重置密码（≥10 位）。连续输错 5 次锁 15 分钟，等待即可自动解锁。</div></details>
|
||||
<details><summary>段落打回后 Agent 会按我的意见改吗？</summary><div class="ans">会。打回时填写的意见会<b>直接注入下一轮生成</b>；同时系统自动生成「记忆建议」，你在记忆库确认后，这类偏好以后所有任务都生效。</div></details>
|
||||
<details><summary>同一个错误反复出现，Agent 会不会一直烧点数？</summary><div class="ans">不会。点数/密钥类错误触发<b>熔断</b>停止整个任务；每次运行还有 240 轮模型调用总预算，总监重做也最多 1 次，多重防线防失控。</div></details>
|
||||
<details><summary>数据安全吗？</summary><div class="ans">API Key 存 macOS 钥匙串；密码加盐哈希；登录有防爆破锁定；每 6 小时自动备份且保留 14 份，管理员可一键「恢复演练」验证备份可用。</div></details>
|
||||
|
||||
<div class="card" style="margin-top:36px; text-align:center; color:var(--ink-3); font-size:12px;">
|
||||
私域Agent · 内容生产中枢 —— 遇到本手册未覆盖的问题，联系管理员或截图报错信息反馈。
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,54 @@
|
||||
# 私域 Agent 新用户操作手册
|
||||
|
||||
## 先记住 3 件事
|
||||
知识库是资料来源；Agent 与技能决定怎么做；内容任务负责把导图变成可审查的成稿。
|
||||
|
||||
## 1. 登录并认识页面
|
||||
打开系统网址，输入用户名和密码，点击“登录”。左侧是功能入口；没有显示的菜单代表当前账号暂时不能使用。右上角依次是“操作手册”、通知铃铛、余额和退出。
|
||||
|
||||
## 2. 准备知识库
|
||||
1. 左侧“知识库”→“新建”，填写名称和可选说明，点击创建。
|
||||
2. 进入知识库→“文件”→“上传文件”，选择 doc/docx/pdf/txt/md/srt 或表格，也可上传文件夹。
|
||||
3. 等状态从“处理中/索引中”变为“索引就绪”。重复文件会被跳过，重复片段会被合并。
|
||||
4. “分类”中新建分类、选择上级分类并整理文件；标签也在知识库内维护。
|
||||
5. “检索测试”输入具体问题并点击检索，查看命中片段和来源。
|
||||
6. “消费记录”按“已消费/已开放”查看自己的记录，选中片段后开放使用。
|
||||
|
||||
## 3. 选择 Agent、技能和记忆
|
||||
进入“Agent 与技能”，点击 Agent 名称。查看职责、知识库分类、技能、工具、模型和数字人身份。记忆已经并入 Agent 与技能，不需要寻找单独的记忆库。写标题选选题类 Agent，写正文选写作类 Agent，检查事实选审校类 Agent。
|
||||
|
||||
## 4. 创建训练营导图
|
||||
在“内容任务”的导图流程中填写主题、期望天数，选择知识库和分类范围。阅读模式有：复用已读资料（推荐）、重新阅读全文（更慢且用量高）、快速相关检索（更快但不读全库）。保存草稿后评估，查看推荐天数、每天标题、前置知识、当天目标、来源证据、预计时间和进度。可修改整套方案或某一天；确认文字导图后再生成图片。后一天会等前一天确认后解锁。
|
||||
|
||||
## 5. 创建内容任务
|
||||
1. “内容任务”→“新建任务”。
|
||||
2. 填写任务名。
|
||||
3. 选择已确认训练营导图和“对应天数（导图第几天）”。
|
||||
4. 选择“画布模板（必选）”；模板决定 Agent 的处理顺序。
|
||||
5. 选择直播时长和质检方式，确认导图文本后点击“创建并拆解”。
|
||||
任务名、导图文本或画布模板缺少时，创建按钮会置灰。
|
||||
|
||||
## 6. 逐段生成和审查
|
||||
任务详情点击“开始生成（第 1 段）”，以后点击“生成下一段”。展开内容段可看标题、正文、负责 Agent、引用来源和质检结果。满意点“通过”；不满意点“打回”，写清原因后点“打回并重做”；本段不要则点“跳过”。全部通过后点“组合成稿”，预览后交付或下载。
|
||||
|
||||
## 7. 数字人和画布
|
||||
“数字人”→“蒸馏新数字人”，填写名称，粘贴资料或上传文档，点击开始蒸馏。待人工测试后试写；不满意写建议重新蒸馏，满意后审核生效。只有生效版本会被 Agent 使用。“画布编排”用于查看节点顺序和每个节点的 Agent；画布模板决定生产流程，导图提供学习内容。
|
||||
|
||||
## 8. 进度、通知和错误
|
||||
右上角铃铛查看完成、失败和待审查通知，可一键已读。“运行记录”查看排队、运行、暂停、完成、失败以及 Trace。处理错误顺序：先读红色错误→回到对应知识库/导图/任务修正→再重试。
|
||||
|
||||
## 9. 常见提示
|
||||
- 没有可使用知识库：上传资料并等待索引就绪，确认 Agent 已绑定。
|
||||
- 导图尚未生成每日导图：按天生成并确认。
|
||||
- 请选择画布模板：回到创建任务面板选择模板。
|
||||
- 任务还没有内容段：确认导图文本不为空并重新拆解。
|
||||
- 检索无结果：等待索引、缩小分类范围、换具体问题。
|
||||
- 文档解析失败：扫描版 PDF 可能没有文字层，改用可复制文字版。
|
||||
- 页面版本可能过期：按 Cmd/Ctrl+Shift+R 强制刷新。
|
||||
- 暂无此功能权限：该入口暂未向账号开放，请联系系统负责人。
|
||||
|
||||
## 10. 完整示例
|
||||
知识库→新建“课程资料”→上传《课程.md》→等待索引就绪→检索测试“第 1 天要学会什么”→Agent 与技能选择写作 Agent→内容任务新建→选择已确认导图和第 1 天→选择画布模板→创建并拆解→逐段通过或打回→组合成稿→预览→交付。
|
||||
|
||||
## 创建 Agent
|
||||
如果列表里没有合适的 Agent，进入“Agent 与技能”后点击“新建”，或点击“AI 帮我创建”。在“基本信息”填写名称、职责类型、描述和内容标签；在“知识与技能”绑定知识库、分类和技能；在“工具与模型”选择模型；需要统一表达风格时在“数字人身份”绑定已生效的数字人。点击“保存草稿”，检查无误后点击“发布（冻结配置）”。回到列表看到状态为“启用”，即可在内容段中选择。修改配置后要重新保存并发布。
|
||||
+232
@@ -0,0 +1,232 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>私域Agent · 系统功能逻辑全览</title>
|
||||
<style>
|
||||
:root { --page:#f7f8fa; --card:#fff; --ink:#18181a; --ink2:#55585f; --ink3:#8a8f98;
|
||||
--jade:#1F6B52; --jade2:#2E8B6A; --jade-soft:rgba(31,107,82,.10);
|
||||
--gold:#C4A962; --line:#e3e7f1; --r:10px; }
|
||||
* { margin:0; padding:0; box-sizing:border-box; }
|
||||
body { background:var(--page); color:var(--ink); font:14px/1.7 "Inter","Noto Sans SC",-apple-system,"PingFang SC",sans-serif; }
|
||||
.wrap { max-width:1080px; margin:0 auto; padding:40px 32px 80px; }
|
||||
h1 { font-size:26px; font-weight:700; letter-spacing:-.02em; }
|
||||
.sub { color:var(--ink2); margin:6px 0 28px; font-size:13px; }
|
||||
h2 { font-size:18px; font-weight:650; margin:36px 0 14px; padding-left:12px; border-left:4px solid var(--jade); }
|
||||
h3 { font-size:14px; font-weight:650; margin:20px 0 8px; color:var(--jade); }
|
||||
p { margin:8px 0; color:var(--ink2); }
|
||||
.card { background:var(--card); border:1px solid var(--line); border-radius:var(--r); padding:18px 20px; margin:10px 0; }
|
||||
table { width:100%; border-collapse:collapse; font-size:12.5px; margin:10px 0; background:#fff; border-radius:var(--r); overflow:hidden; }
|
||||
th { background:#f0f3f0; text-align:left; padding:9px 12px; font-weight:650; border-bottom:2px solid var(--line); white-space:nowrap; }
|
||||
td { padding:8px 12px; border-bottom:1px solid var(--line); vertical-align:top; }
|
||||
tr:last-child td { border-bottom:0; }
|
||||
code { background:var(--jade-soft); color:var(--jade); padding:1px 6px; border-radius:5px; font-size:12px; font-family:ui-monospace,Menlo,monospace; }
|
||||
.flow { display:flex; flex-wrap:wrap; gap:8px; align-items:center; margin:12px 0; }
|
||||
.flow .step { background:#fff; border:1.5px solid var(--jade); color:var(--jade); border-radius:9px; padding:7px 13px; font-size:12.5px; font-weight:600; }
|
||||
.flow .step small { display:block; font-weight:400; color:var(--ink3); font-size:10.5px; }
|
||||
.flow .arr { color:var(--gold); font-weight:700; }
|
||||
.tag { display:inline-block; padding:2px 9px; border-radius:20px; font-size:11px; font-weight:600; margin:2px; }
|
||||
.tag.g { background:var(--jade-soft); color:var(--jade); }
|
||||
.tag.y { background:rgba(196,169,98,.15); color:#8a7433; }
|
||||
.tag.r { background:rgba(215,85,85,.12); color:#b04a4a; }
|
||||
.tag.b { background:rgba(69,104,207,.12); color:#4568cf; }
|
||||
.two { display:grid; grid-template-columns:1fr 1fr; gap:12px; }
|
||||
@media (max-width:760px){ .two{grid-template-columns:1fr} }
|
||||
.note { background:#fffbe9; border:1px solid #efe3b0; border-radius:var(--r); padding:12px 16px; font-size:12.5px; color:#7a6a2f; margin:10px 0; }
|
||||
.toc { columns:2; column-gap:28px; font-size:13px; }
|
||||
.toc a { color:var(--jade); text-decoration:none; display:block; padding:3px 0; break-inside:avoid; }
|
||||
.toc a:hover { text-decoration:underline; }
|
||||
kbd { background:#eef1ee; border:1px solid var(--line); border-bottom-width:2px; border-radius:5px; padding:1px 6px; font-size:11px; }
|
||||
</style>
|
||||
</head>
|
||||
<body><div class="wrap">
|
||||
<h1>私域Agent · 系统功能逻辑全览</h1>
|
||||
<p class="sub">版本 2026-09-01 · 对应源码 ~/Desktop/yawan-workbench（135 文件）· 访问地址 https://agent.pducv.cn</p>
|
||||
|
||||
<div class="card"><b style="font-size:13px">目录</b><div class="toc">
|
||||
<a href="#s1">1. 系统一句话总览</a>
|
||||
<a href="#s2">2. 角色与权限体系</a>
|
||||
<a href="#s3">3. 核心工作流：从导图到成稿</a>
|
||||
<a href="#s4">4. 内容生产流水线（Agent 体系）</a>
|
||||
<a href="#s5">5. 知识库与向量检索（RAG）</a>
|
||||
<a href="#s6">6. AI 辅助创建</a>
|
||||
<a href="#s7">7. 质检体系</a>
|
||||
<a href="#s8">8. 审查与打回循环</a>
|
||||
<a href="#s9">9. 点数与成本控制</a>
|
||||
<a href="#s10">10. 模型管理</a>
|
||||
<a href="#s11">11. 数据隔离与安全</a>
|
||||
<a href="#s12">12. 运维与守护</a>
|
||||
<a href="#s13">13. 关键表与端点速查</a>
|
||||
<a href="#s14">14. 已知边界与注意事项</a>
|
||||
</div></div>
|
||||
|
||||
<h2 id="s1">1. 系统一句话总览</h2>
|
||||
<div class="card">
|
||||
<p><b>私域Agent</b> 是一个<b>多 Agent 协作的内容生产工作台</b>：雅文老师粘贴一节课的导图/框架，系统自动把它拆解成带时间轴的内容段任务单，派发给不同职能的 Agent（开场/心法/技法/销售/收尾…）逐段生成直播口播稿，每段经过 4 道独立质检和人工确认，最终组合成一份六色标注的 Word 成稿。</p>
|
||||
<p style="margin-top:10px"><span class="tag g">FastAPI 后端</span><span class="tag g">React 前端</span><span class="tag g">Chroma 向量库</span><span class="tag y">DeepSeek 等模型</span><span class="tag y">本地 Whisper 转写</span><span class="tag b">Cloudflare 隧道</span></p>
|
||||
</div>
|
||||
|
||||
<h2 id="s2">2. 角色与权限体系</h2>
|
||||
<table>
|
||||
<tr><th>角色</th><th>能力</th><th>典型用途</th></tr>
|
||||
<tr><td><b>admin</b> 管理员</td><td>全部功能 + 用户管理 + 点数发放 + 运营看板</td><td>系统所有者（雅文管理员）</td></tr>
|
||||
<tr><td><b>editor</b> 编辑</td><td>建任务/生成/审查/知识库管理</td><td>内容生产主力</td></tr>
|
||||
<tr><td><b>reviewer</b> 审校</td><td>只读 + 审查通过/打回</td><td>质检把关人</td></tr>
|
||||
<tr><td><b>viewer</b> 访客</td><td>仅被授权的资源只读</td><td>外部查看</td></tr>
|
||||
</table>
|
||||
<p><b>双层隔离</b>：①资源层——每条数据带 <code>organization_id / owner_user_id / visibility(private|shared|global)</code>，任何读写都过 <code>can_access()</code> 判定；②权限层——16 项权限按角色矩阵控制端点访问。实测：普通用户看不到他人的任务/私有知识库/私有 Agent，越权读直接 403/404。</p>
|
||||
|
||||
<h2 id="s3">3. 核心工作流：从导图到成稿</h2>
|
||||
<div class="flow">
|
||||
<div class="step">① 新建任务<small>目标+导图+选时长</small></div><div class="arr">→</div>
|
||||
<div class="step">② AI 拆解<small>后台执行，1-2 分钟</small></div><div class="arr">→</div>
|
||||
<div class="step">③ 清单增删改<small>不满意可提意见重拆</small></div><div class="arr">→</div>
|
||||
<div class="step">④ 逐段生成<small>每段一个 Agent</small></div><div class="arr">→</div>
|
||||
<div class="step">⑤ 4 道质检<small>自动</small></div><div class="arr">→</div>
|
||||
<div class="step">⑥ 人工确认<small>通过/打回/跳过</small></div><div class="arr">→</div>
|
||||
<div class="step">⑦ 组合成稿<small>六色 docx</small></div>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>① 新建任务（TasksPage）</h3>
|
||||
<p>填写任务目标（必填）、验收标准（可 ✦AI 建议）、粘贴导图文本（或 📷 图片 OCR / 📄 导入文档）、选画布、<b>选直播总时长</b>（30分钟~4小时，AI 拆解会强制各段时间总和=所选时长）、可选关联上一天任务（跨稿对账）。</p>
|
||||
<h3>② AI 拆解（后台异步）</h3>
|
||||
<p>点「创建并拆解」立即返回，页面显示「⏳ 拆解中…」。主控 Agent 把导图逐节点编译成内容段任务单：每段带标题/内容标签/时间范围/产品引用；读不准的地方进「待确认清单」，压缩决策写进 notes。拆解产出为空或失败时明确报原因，不产生空任务。</p>
|
||||
<h3>③ 清单增删改查</h3>
|
||||
<p>拆出的每段可<b>直接编辑</b>（标题/标签/时长/产品，失焦自动保存，标签变了自动重新匹配 Agent）；可<b>删除</b>（生成过的也能删，删光回可拆解态）；可<b>新增段落</b>；整体不满意可<b>「✦ 对清单提意见，AI 重新拆解」</b>——意见最高优先级注入，AI 重出整份任务单。</p>
|
||||
<h3>④⑤⑥ 逐段生成 + 质检 + 人工确认</h3>
|
||||
<p>点「▶ 开始生成（第 1 段）」只派发第一个 Agent；生成+质检完自动停在「待审查」，人工通过后按钮变「▶ 生成下一段」继续派发。打回 = 自动按意见重新生成（见 §8）。也有传统「一键跑完全部」模式（暂停/继续/停止/删除齐全）。</p>
|
||||
<h3>⑦ 组合成稿</h3>
|
||||
<p>全部段通过后「📄 组合成稿」：跨段一致性检查 → 拼接 → 生成六色标注 docx（可下载/在线预览）。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s4">4. 内容生产流水线（Agent 体系）</h2>
|
||||
<table>
|
||||
<tr><th>Agent（内置 14 个）</th><th>角色</th><th>职责</th></tr>
|
||||
<tr><td>主控 Agent</td><td>coordinator</td><td>导图 → 任务单拆解（支持用户修改意见注入）</td></tr>
|
||||
<tr><td>开场段 / 心法段 / 技法段 / 收尾段 / 钩子段 Agent</td><td>production</td><td>按内容标签生产对应段落正文（挂知识库检索生成）</td></tr>
|
||||
<tr><td>产品销售 Agent</td><td>production</td><td>产品植入段（挂产品信息+销售逻辑库）</td></tr>
|
||||
<tr><td>结构 / 内容 / 风格尺度 / 跨稿 质检</td><td>qc ×4</td><td>四门独立质检（见 §7）</td></tr>
|
||||
<tr><td>组合 Agent</td><td>composer</td><td>跨段衔接检查 + 成稿组合</td></tr>
|
||||
<tr><td>风格顾问 / 产品顾问</td><td>adviser</td><td>辅助咨询</td></tr>
|
||||
</table>
|
||||
<p><b>Agent 三要素</b>：规则（rules，可版本化）、提示模板（可挂 PromptTemplate）、知识库（kb_ids，检索素材来源）。<b>画布（Canvas）</b>把 Agent 编排成节点图，任务可绑定画布；画布可设<b>全局总监 Agent</b>（on_drift 疑似跑偏才审 / always 每段必审 / monitor 只记录）——跑偏的段自动重做 1 次，仍偏转人工。<b>融合生成</b>：一段可挂多个融合 Agent 共同产出。<b>Agent 三件套支持「✦ AI 帮我创建」</b>（见 §6）。</p>
|
||||
|
||||
<h2 id="s5">5. 知识库与向量检索（RAG）</h2>
|
||||
<div class="two">
|
||||
<div class="card">
|
||||
<h3>六库定稿（v5 来源级清洗）</h3>
|
||||
<table>
|
||||
<tr><th>库</th><th>块数</th><th>内容</th></tr>
|
||||
<tr><td>心法</td><td>8,912</td><td>性观念/性心理/亲密关系</td></tr>
|
||||
<tr><td>技法</td><td>3,565</td><td>手法/前戏/高潮教学</td></tr>
|
||||
<tr><td>功法</td><td>5,941</td><td>凯格尔/盆底肌/控精训练</td></tr>
|
||||
<tr><td>情欲内容</td><td>727</td><td>角色扮演/SM/性幻想</td></tr>
|
||||
<tr><td>产品信息</td><td>49</td><td>产品成分/用法</td></tr>
|
||||
<tr><td>销售逻辑</td><td>2,438</td><td>98 场真实直播稿全链路</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>上传与建索引</h3>
|
||||
<p><b>三种方式</b>：📁整个文件夹（含多层子文件夹，拖拽或选择，自动打 zip）、📤单/多文件、API。</p>
|
||||
<p><b>支持格式</b>：md/txt/docx/srt/json/jsonl/pdf + <b>音视频</b>（mp4/mov/mp3/wav 等 12 种 → ffmpeg 抽音轨 → 本地 Whisper 中文转写 → 语义分段）。</p>
|
||||
<p><b>处理链</b>：清洗（去时间轴/乱码/去重）→ 分块（口播稿 2200 字聚合）→ bge-small-zh 向量化 → Chroma HNSW 索引（独立 rag_worker 子进程执行，规避主进程性能塌陷，8 秒级检索）。</p>
|
||||
<p><b>多级分类</b>：手动分类 + ✦AI 自动分类（建议→确认制）+ 跨库移动文件。</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>检索逻辑（生成时自动发生）</h3>
|
||||
<p><code>search_kbs</code>：向量 top-k 候选 → 剔除该 Agent 已消费片段（防重复引用）→ 关键词重排（命中 +0.15）→ 取 top-k。每段生成<b>预留（reserve）知识片段</b>：正文+锚点落盘才标记 consumed；失败/打回自动释放（available）可再次被检索。所有引用带 <code>文件名/标题/原文摘录</code> 写入 <code>references</code>，前端可逐条溯源核对。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s6">6. AI 辅助创建</h2>
|
||||
<div class="card">
|
||||
<p>Agent / 技能 / 提示模板 三个页面都有「✦ AI 帮我创建」：用户一句大白话描述 → 系统先<b>检索知识库</b>（6 库全查，取最相关的 8 块注入 prompt）→ 模型输出受控 JSON 草稿（名称/规则/指令/建议）→ 用户在表单确认修改后才正式创建。草稿带 <code>_meta</code>：所用模型、Token 消耗、耗时、<b>引用了哪 8 条知识</b>（库名+文件+摘录）。</p>
|
||||
<p>另有 <b>冲突检测</b>：创建/修改时扫描 15 组互斥词对（口语↔书面、简短↔详细…），重名/高相似名称、跨资源单侧冲突，以 warning 展示不阻断。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s7">7. 质检体系（4 门全开）</h2>
|
||||
<table>
|
||||
<tr><th>门</th><th>检查什么</th><th>典型 FAIL</th></tr>
|
||||
<tr><td>structure 结构</td><td>锚点卡 7 字段完整（核心概念/技法/产品引用/金句/情绪基调/结尾钩子/时长）</td><td>锚点缺失字段</td></tr>
|
||||
<tr><td>content 内容</td><td>是否扣题、知识引用是否真实、有没有编造</td><td>内容与导图节点脱节</td></tr>
|
||||
<tr><td>style 风格尺度</td><td>雅文口播风（大白话/单段流）、内容尺度</td><td>书面腔、结构模板化</td></tr>
|
||||
<tr><td>cross 跨稿</td><td>与上一天任务的衔接、重复度</td><td>与昨日金句重复</td></tr>
|
||||
</table>
|
||||
<p>质检不过 → 自动重试最多 2 轮（失败意见注入下轮 prompt「本轮必须修复」）→ 仍不过转 <code>rework</code> 等人工。产物三件套：<b>正文（口语单段流）+ 锚点卡（结构化 JSON）+ 引用来源</b>。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s8">8. 审查与打回循环</h2>
|
||||
<div class="card">
|
||||
<table>
|
||||
<tr><th>操作</th><th>发生什么</th></tr>
|
||||
<tr><td>✅ 通过</td><td>段 → approved；全部通过后任务变「可合成」</td></tr>
|
||||
<tr><td>🔁 打回 + 意见</td><td><b>立即自动重做</b>：意见写入段落并以「用户打回意见（最高优先级，必须逐条落实）」注入新 prompt → 重新生成+质检 → 回到待审查；意见同时沉淀为该 Agent 的 L3 待确认记忆</td></tr>
|
||||
<tr><td>⏭️ 跳过</td><td>段 → skipped，不参与合成</td></tr>
|
||||
<tr><td>🔁 重试 / 重试+记原因</td><td>失败段重跑；原因沉淀为 L2 待确认记忆</td></tr>
|
||||
<tr><td>🗑 删除段落</td><td>任何状态可删（已交付除外），生成派发自动跳过</td></tr>
|
||||
</table>
|
||||
<p>所有打回/修复原因都会进入「记忆库」的<b>待确认池</b>（L2 修复经验 / L3 偏好），管理员确认后写入 Agent 长期记忆——<b>系统会越用越懂雅文的要求</b>。运行轨迹页可看每个会话的轮次/工具调用/错误，工具调用支持人工批准/拒绝（human-in-the-loop）。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s9">9. 点数与成本控制</h2>
|
||||
<div class="card">
|
||||
<p><b>计量</b>：1 点数 = 10 Token。点数余额本身不设上限；<b>发放三档</b>：一档 1,000 万 / 二档 1 亿 / 三档 10 亿（管理员在用量与账单页一键发放，也可手动输入）。</p>
|
||||
<p><b>启动预检（硬性）</b>：开始生成前估算本次成本（按本组织近 200 次真实 LLM 用量外推，无历史用保守常量），余额须覆盖「预估 + 20% 缓冲」，不足直接 409 拦截并中文提示。任务页展示预估 Token/点数/耗时和估算来源。</p>
|
||||
<p><b>运行中熔断</b>：点数耗尽、鉴权失败、区域限制类错误 → 立即停止整个任务（继续跑只是白烧）；瞬时错误（网络抖动）继续跑。</p>
|
||||
<p><b>API 限流四层防护</b>：429 自动退避重试（读 Retry-After + 抖动，最多 2 次）→ 自动 failover 换 Provider → 单任务 240 轮调用预算熔断 → 中文错误提示（建议换模型）。<b>看板隔离</b>：运营看板不显示点数余额，普通用户只看自己的任务/用量。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s10">10. 模型管理</h2>
|
||||
<div class="card">
|
||||
<p>多 Provider 多模型：<b>API Key 存 macOS 钥匙串</b>（<code>secret_store</code>，库文件里只有密文引用）；连通性测试一键验证；<b>全局默认模型</b>设置；每个 Agent 可单独指定 Provider/模型（不指定则用全局默认）；<b>故障自动转移</b>：主模型连续失败自动切到备选 Provider。当前主力：DeepSeek（v4-flash / v4-pro）。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s11">11. 数据隔离与安全</h2>
|
||||
<div class="card">
|
||||
<p><b>认证</b>：用户名密码登录，Token 会话 12 小时；<b>防爆破</b>：(IP,用户名) 5 次失败锁 15 分钟，单 IP 30 次锁 15 分钟。</p>
|
||||
<p><b>授权</b>：资源级 can_access（组织+归属+可见性+分级授权 use/manage/export）+ 角色权限矩阵双保险；<b>已实测</b>：跨用户任务/库/Agent 均不可见，越权 403/404。</p>
|
||||
<p><b>备份</b>：每 6 小时自动备份，保留 14 份；密钥类一律不入库（钥匙串）；上传有类型白名单 + 路径穿越防护 + zip 炸弹防护。</p>
|
||||
</div>
|
||||
|
||||
<h2 id="s12">12. 运维与守护</h2>
|
||||
<div class="card">
|
||||
<table>
|
||||
<tr><th>组件</th><th>机制</th></tr>
|
||||
<tr><td>公网入口</td><td><b>https://agent.pducv.cn</b>（域名→Cloudflare→命名隧道 yawan-workbench，地址永久固定）</td></tr>
|
||||
<tr><td>隧道常驻</td><td>launchd 服务 <code>com.yawan.cloudflared</code>：崩溃自动重启 + 开机自启 + 4 条冗余连接</td></tr>
|
||||
<tr><td>后端守护</td><td><code>~/bin/yawan-guard.sh</code> 每 60 秒巡检，挂了自动拉起</td></tr>
|
||||
<tr><td>任务队列</td><td>持久化队列：租约 5 分钟 / 重试 3 次 / 死信队列可重放</td></tr>
|
||||
<tr><td>巡检告警</td><td>5 分钟巡检：磁盘 <2GB、失败段超 30 分钟、点数 <1000 告警；告警去重 10 分钟</td></tr>
|
||||
<tr><td>审计</td><td>LLMCall（每次模型调用：模型/耗时/Token/状态）、UsageEvent（计费事件）、RunEvent（运行轨迹）、Trace 全链路追踪</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h2 id="s13">13. 关键表与端点速查</h2>
|
||||
<div class="two">
|
||||
<div class="card">
|
||||
<h3>核心数据表</h3>
|
||||
<p><code>appuser</code> 用户 · <code>campaign</code> 任务（含 duration_minutes）· <code>segment</code> 内容段（状态机：pending→running→qc→human_review→approved/rework/failed/skipped）· <code>campaignrun</code> 运行（支持暂停/断点/取消）· <code>agent / agentskill / prompttemplate</code> · <code>knowledgebase / knowledgefile / knowledgecategory</code> · <code>knowledgeusage</code> 知识消费 · <code>canvas</code> 画布 · <code>llmcall / usageevent / runevent</code> 审计 · <code>memory / pendingmemory</code> 记忆 · <code>artifact</code> 成稿 · <code>notification</code> 通知</p>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>主要端点（158 个中的关键）</h3>
|
||||
<p><code>POST /campaigns</code> 建任务（带时长）<br/>
|
||||
<code>POST /campaigns/{id}/parse</code> 后台拆解（可带 advice 重拆）<br/>
|
||||
<code>PUT/DELETE /campaigns/{id}/segments/{sid}</code> 改/删段<br/>
|
||||
<code>POST /campaigns/{id}/segments</code> 新增段<br/>
|
||||
<code>POST /campaigns/{id}/run</code> 全量生成 · <code>/run-step</code> 逐段生成<br/>
|
||||
<code>POST /campaigns/{id}/pause|resume</code> 暂停/断点续跑<br/>
|
||||
<code>POST /segments/{sid}/review</code> 审查（reject 即自动重做）<br/>
|
||||
<code>POST /segments/{sid}/fix</code> 重试/换模型/改规则<br/>
|
||||
<code>POST /campaigns/{id}/compose</code> 合成<br/>
|
||||
<code>GET/POST /kbs...</code> 知识库/导入/文件夹导入/检索<br/>
|
||||
<code>POST /ai-assist/draft</code> AI 辅助创建（KB 检索注入）</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 id="s14">14. 已知边界与注意事项</h2>
|
||||
<div class="note">
|
||||
<p><b>① 电脑需开机</b>——系统跑在本机 Mac 上，关机即公网不可达（长期方案可迁轻量云服务器）。<b>② 音视频转写耗时</b>——1 小时视频约 20-40 分钟本地转写，属正常。<b>③ 每段生成 3-5 分钟</b>——生成+4 道质检是真实 LLM 调用，页面自动刷新无需盯着。<b>④ 质检多轮 rework</b>——质检判定未达标会自动重试 2 轮再转人工，属设计行为，人工再打回会带意见重做。<b>⑤ ngrok 已退役</b>——如遇旧地址打不开，一律用 agent.pducv.cn。<b>⑥ 测试知识库</b>——「检测用知识库」已删除，Agent 已重新挂载正式六库。</p>
|
||||
</div>
|
||||
<p style="margin-top:24px;color:var(--ink3);font-size:11px">私域Agent · 雅文老师内容生产中枢 · 内部文档</p>
|
||||
</div></body></html>
|
||||
@@ -0,0 +1,310 @@
|
||||
# 雅文内容创造工作台 · 设计文档 v1
|
||||
|
||||
> 日期：2026-08-25 ｜ 状态：设计评审稿 ｜ 目标：多 Agent 内容工厂，主控派单 → 环节 Agent 生产 → 质检 → 人工审查 → 组合成直播文稿，全程可改、越用越懂
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
一个**多 Agent 内容生产工作台**，专为雅文老师直播文稿生产打造：
|
||||
|
||||
- **你只输入**：当天要做的内容主题 + 导图/框架/思维（内容+时间的权威大纲）
|
||||
- **工作台自动完成**：主控 Agent 拆解任务 → 按环节派发给生产 Agent → 每个环节产物独立质检 → 质检通过后送人工审查 → 全部确认后组合成一篇完整直播文稿（含颜色标记 docx）
|
||||
- **你可以干预任何环节**：每个 Agent 的规则可改、每个环节的产物可打回重做、打回意见会沉淀成该 Agent 的记忆，越用越贴合你的标准
|
||||
|
||||
## 2. 需求 → 设计对策映射
|
||||
|
||||
| # | 你的要求 | 设计对策 |
|
||||
|---|---|---|
|
||||
| 1 | 很多个 Agent 组成 | 1 主控 + 4~N 生产 Agent + 4 质检 Agent + 1 组合 Agent + 2 服务型 Agent（产品顾问/风格顾问） |
|
||||
| 2 | 每个 Agent 可设置规则做对应的事 | 每个 Agent 一个 `rules.md`（规则文件），你直接编辑，随时生效 |
|
||||
| 3 | 上下文隔离 | Agent 间不共享对话历史，只传递**结构化任务单**；每 Agent 独立会话 |
|
||||
| 4 | 知识库共用 | 一个只读共享知识库，所有 Agent 可检索，任何 Agent 不可写 |
|
||||
| 5 | 哪里不对改哪里 | 打回粒度 = 环节产物：打回哪段只重跑哪段，其他不动；规则级修正 + 人工直接改三种路径 |
|
||||
| 6 | 给主 Agent 主题/导图即可 | 主控 Agent 解析导图 → 生成任务单 → 自动派发、跟踪、汇总 |
|
||||
| 7 | 每件产物都有质检 Agent | 每个环节产物生成后**立即**自动过 4 道质检闸，不过关打回原环节 |
|
||||
| 8 | 质检过还要人工审查 | 人工审查台是硬关卡：质检全过 ≠ 交付，人工确认后才放行 |
|
||||
| 9 | 组合成一篇直播文稿 | 组合 Agent 按任务单时间轴拼装 + 衔接检查 + 生成六色标记 docx |
|
||||
| 10 | Agent 自主学习、越用越懂 | 每 Agent 独立记忆库：纠错、偏好、成功案例沉淀，写入有触发机制 |
|
||||
| 11 | 记忆库隔离 | 记忆按 Agent 命名空间隔离，互不可见；只有共享知识库是共用的 |
|
||||
|
||||
## 3. 系统架构总览
|
||||
|
||||
```
|
||||
┌────────────────────────── 你（唯一入口） ──────────────────────────┐
|
||||
│ 输入：主题 / 导图 / 框架 / 思维（当天权威大纲） │
|
||||
│ 干预：改 Agent 规则 · 打回环节 · 直接改产物 · 审查确认 │
|
||||
└────────────────────────────────┬──────────────────────────────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 主控 Agent（主编） │
|
||||
│ ① 解析导图 → ② 生成任务单 TaskSpec → ③ 派发 → ④ 跟踪 → ⑤ 汇总 │
|
||||
│ 记忆：项目管理偏好（压缩决策、交付习惯） │
|
||||
└──────┬──────────┬──────────┬──────────┬──────────┬───────────────┘
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ 段Agent1 │ │ 段Agent2 │ │ 段Agent3 │ │ 段AgentN │ │ 服务型 │
|
||||
│ 开场/心法 │ │ 技法/场景 │ │ 产品/销售 │ │ 收尾/钩子 │ │ 产品顾问 │
|
||||
│ 独立上下文 │ │ 独立上下文 │ │ 独立上下文 │ │ 独立上下文 │ │ 风格顾问 │
|
||||
│ 独立记忆库 │ │ 独立记忆库 │ │ 独立记忆库 │ │ 独立记忆库 │ │(只读供给)│
|
||||
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 共享只读知识库（所有人可查，无人可写） │
|
||||
│ 数字雅文档案/范稿 | 训练营框架/导图库 | 直播原文库(73场) │
|
||||
│ 备稿库(99篇) | 产品知识库(观品) | 质检规则库 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 质检闸（每件产物独立过 4 道，并行） │
|
||||
│ ①结构质检 ②内容质检 ③风格尺度质检 ④跨稿质检 │
|
||||
│ 各质检 Agent 有独立记忆：常见错误模式库，越查越准 │
|
||||
└──────┬──────────────────────────────────────────────────────┘
|
||||
▼ 全部通过
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ ═══ 人工审查台（硬关卡）═══ │
|
||||
│ 逐段查看：产物 + 质检报告 + 高亮差异 │
|
||||
│ 操作：✅通过 / 🔁打回(附意见→进该Agent记忆) / ✏️直接改 │
|
||||
└──────┬──────────────────────────────────────────────────────┘
|
||||
▼ 全部确认
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 组合 Agent（总编）：时间轴拼装 → 衔接/回指检查 │
|
||||
│ → 生成说明 → 六色标记 docx（宋体10.5pt） │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
📄 最终交付：直播文稿.docx + clean.txt + 待确认清单
|
||||
```
|
||||
|
||||
## 4. Agent 拓扑与职责
|
||||
|
||||
### 4.1 主控 Agent（主编/Coordinator）— 唯一派单者
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 职责 | 解析导图/主题 → 生成任务单 → 派发 → 跟踪进度 → 汇总质检/审查结果 → 决定重跑/放行 |
|
||||
| 输入 | 你的原始输入（主题、导图 md/图片、框架文字） |
|
||||
| 输出 | **任务单 TaskSpec**（结构化 JSON/MD，是全局唯一任务契约） |
|
||||
| 规则文件 | `agents/coordinator/rules.md`（拆解原则：导图=内容+时间权威大纲、节点逐条对应、读不准的词列待确认清单、时间总和校验、压缩决策写进交付说明） |
|
||||
| 记忆库 | `agents/coordinator/memory/`（你的项目管理偏好：压缩习惯、交付格式、确认偏好） |
|
||||
| 关键动作 | 导图读不准的词（手写/OCR 常错）**必须先列出来问你再动稿**——这是全流程第一道防错闸 |
|
||||
|
||||
### 4.2 生产 Agent（环节 Agent）— 按段划分，默认模板如下，数量可增减
|
||||
|
||||
每个段 Agent 只生产任务单里分配给它的那一段，产出独立文件。
|
||||
|
||||
| Agent | 产出内容 | 该 Agent 规则要点（rules.md 示例） | 质检重点 |
|
||||
|---|---|---|---|
|
||||
| 开场段 Agent | 扎心开场+承诺钩子，开场 30 分钟内见主题、第一件产品尽量前置 | 开场降档（性感画面撤下换自嘲暖场）、案例/悬念 30 秒入题 | 结构/风格尺度 |
|
||||
| 心法段 Agent | 心法金句、认知颠覆、"为什么"铺垫 | 先讲"为什么要听"再进干货；金句只作点缀不作产品引入载体 | 内容/风格 |
|
||||
| 技法段 Agent | 痛点技法展示：步骤骨架+画面点+跟练互动 | 技法快准狠（第一步…第二步…第三步）；可跟练动作+互动指令；每个卖点前必有痛点技法展示 | 内容/结构 |
|
||||
| 场景段 Agent | 角色扮演/SM 场景/水元素段等（按导图） | 色情小说档画面感写法；SM 道具带安全提示；场景=环境/衣着/光线/气味/心理/动作过程 | 风格/合规 |
|
||||
| 产品段 Agent | 产品体验感写作+销售话术 | 一产品一概念不混谈；产品随动作进场（拿第一瓶）；卖货节点宁早勿晚；价格以当轮指令为准 | 内容/跨稿 |
|
||||
| 收尾段 Agent | 信念收尾（最后 30 秒纯信念不卖货）+次日钩子 | 钩子=导图次日真实框架，技法名与导图一致；不写死待确认道具 | 跨稿/风格 |
|
||||
| 互动标记 Agent | 全稿表演标记补全（灰字） | （停顿三秒）（压低声音）（等弹幕）（演示）（拿第一瓶）；禁止报幕式转场 | 结构 |
|
||||
|
||||
> 段划分原则：**与导图节点一一对应**（导图是权威大纲），默认 6-15 段随当天导图增减。段 Agent 之间互不读取对方产物——防止上下文串扰（隔离的核心）。
|
||||
|
||||
### 4.3 服务型 Agent（只读供给，不产稿）
|
||||
|
||||
| Agent | 职责 |
|
||||
|---|---|
|
||||
| 产品顾问 Agent | 查产品知识库（观品 chunks.jsonl），产出产品事实卡（功效/价格口径/概念边界），供产品段 Agent 使用；记忆沉淀"产品概念边界"（水润≠养护等） |
|
||||
| 风格顾问 Agent | 加载数字雅文人格档案/范稿/文本层铁律，产出"本场风格校准卡"（称呼、句式、金句密度、暗语表），供所有生产 Agent 使用 |
|
||||
|
||||
### 4.4 质检 Agent — 4 道闸并行
|
||||
|
||||
| 质检 Agent | 检查清单（来自实战沉淀的审查五类+铁律） | 打回依据 |
|
||||
|---|---|---|
|
||||
| ① 结构质检 | 逻辑硬伤（自相矛盾/段序错乱/数据不自洽/预告打架/语义反字/时序张力）、笔误错字（漏字/同音/人名混乱/括号配对）、结构残留（提词备注/上半场无下半场/他稿时间线）、时间轴核对（每段标题时间标注、总和=直播时长） | 任何 FAIL → 打回原段 Agent |
|
||||
| ② 内容质检 | 每个卖点前是否有痛点技法展示（不放心法带入）、一产品一概念（"养护"字样清零）、技法密度（可跟练清单存在）、讲解前有"为什么"、删讲解不删画面、产品数量=导图产品节点数 | 同上 |
|
||||
| ③ 风格尺度质检 | 色情小说档词清单（腿心/热意/颤/烫 ≥3）、禁词清零（妹妹/豆豆/龙根/蛋蛋/射/喷/缴械=0）、反问句归零（对不对/明白吗）、表演标记覆盖率、破折号清零、无教学框架外露、无知识库来源标注 | 同上 |
|
||||
| ④ 跨稿质检 | day N-1 结尾预告的技法逐条兑现、价格/术语跨稿一致（以当轮指令为准）、产品名与台账对齐、回指句一致性（产品退场后相关回指句清理） | 同上 |
|
||||
|
||||
**质检输出**：结构化报告 `qc_report.json`（每条问题带位置+描述+修改建议+严重级），**报告逐条对证正文**（质检报告≠事实——用户对"表面功夫"敏感，报告与正文脱节必须抓出来）。
|
||||
|
||||
### 4.5 组合 Agent（总编/Composer）
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 职责 | 全部通过后：按任务单时间轴拼装 → 段间衔接检查（话题自然滑入，禁报幕式转场）→ 产品回指一致性 → 生成六色标记 docx（黑/红/紫/绿/灰/蓝）→ 生成说明 + 待确认清单 + clean.txt |
|
||||
| 输入 | 所有通过审查的段产物 + 任务单 |
|
||||
| 输出 | `直播文稿.docx`（宋体 10.5pt，段落自然合并 85-110 段）+ `生成说明`（生成依据/时间压缩决策/跨稿对账/合规处理/占位符） |
|
||||
| 记忆 | 沉淀"通过稿的组合模式"（衔接句样板、图例规范） |
|
||||
|
||||
## 5. 上下文隔离机制（核心设计）
|
||||
|
||||
```
|
||||
隔离原则：Agent 之间只通过"文件系统 + 结构化契约"通信，绝不共享对话。
|
||||
|
||||
┌─ 任务单 TaskSpec（主控产出，全流程唯一契约）────────────────┐
|
||||
│ campaign_id / date_id / 导图源文件引用 │
|
||||
│ segments: [{ id, title, 时间范围, 类型(心法/技法/产品/场景), │
|
||||
│ 导图节点原文, 产品节点, 交付要求 }] │
|
||||
│ quality_gates: 本场启用的质检项 + 词清单 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
每个段 Agent 运行时只看到：
|
||||
✅ 任务单中属于自己的 segment 切片
|
||||
✅ 共享知识库（只读检索接口）
|
||||
✅ 自己的规则文件 + 自己的记忆库
|
||||
❌ 其他段的产物
|
||||
❌ 其他 Agent 的对话历史/记忆
|
||||
❌ 主控与用户的对话
|
||||
|
||||
质检 Agent 运行时只看到：
|
||||
✅ 被检段产物 + 任务单对应切片 + 知识库质检规则 + 自己的错误模式记忆
|
||||
❌ 其他段产物（除非打回时作为上下文补充，由主控显式授权）
|
||||
```
|
||||
|
||||
隔离的物理载体：`work/<campaign_id>/segments/<segment_id>/` 每个段一个目录，产物独立文件；Agent 会话按段独立起停。
|
||||
|
||||
## 6. 共享知识库（只读、共用）
|
||||
|
||||
| 库 | 内容 | 说明 |
|
||||
|---|---|---|
|
||||
| 风格档案库 | 数字雅文人格档案、day1 定稿基准、仿雅文范稿、文本层铁律 10 条 | "怎么讲"的最高权威 |
|
||||
| 框架导图库 | 七天营导图、28 天重排版总纲、历史任务单 | 生成新稿的权威大纲引用 |
|
||||
| 直播原文库 | 73 场 SRT 转录（573 万字，E:\03_直播素材\直播合集） | 素材/案例/原话检索 |
|
||||
| 备稿库 | 99 篇备稿（150 万字，Desktop\直播文稿） | 历史定稿/跨稿对账依据 |
|
||||
| 产品知识库 | 观品产品知识库 chunks.jsonl | 产品事实/功效/概念边界（价格口径以当轮指令为准） |
|
||||
| 质检规则库 | 五类审查清单、词清单、铁律 | 质检 Agent 的检查依据 |
|
||||
|
||||
写权限：**无**。所有 Agent 只读检索。产出和记忆一律写各自工作区/记忆库——知识库保持原始状态。
|
||||
|
||||
## 7. 记忆系统设计（自主学习 · 每 Agent 隔离）
|
||||
|
||||
### 7.1 记忆分层
|
||||
|
||||
| 层 | 类型 | 来源 | 示例 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| L1 | 规则记忆 | 用户显式纠正（你改规则/打回时说的"以后都…"） | "卖货节点宁早勿晚；产品前必须有痛点技法展示" | 最高，等同于改 rules |
|
||||
| L2 | 纠错记忆 | 质检 FAIL 自动沉淀 | "本段上次因'养护'字样残留被打回" | 高，重跑时必读 |
|
||||
| L3 | 偏好记忆 | 人工审查意见 | "你上次打回说：心法段金句太多太密" | 高 |
|
||||
| L4 | 成功记忆 | 通过稿复盘（可选） | "开场段上次通过时用了自嘲暖场模式" | 中，仅参考 |
|
||||
|
||||
### 7.2 沉淀红线（重要——来自你们实战的两轮纠正）
|
||||
|
||||
- ✅ **可沉淀**：怎么讲（打法、结构、风格、质检标准、转场手法）
|
||||
- ❌ **不可沉淀**：讲什么（价格、头衔、技法名、产品组合、场次性口径）——每篇独立，以当轮指令/导图为准
|
||||
- 记忆条目必须带来源标签（哪场/哪次打回），场次性数据只能进"参考池"且带过期标记，绝不升级为规则
|
||||
|
||||
### 7.3 记忆写入时机（自动 + 手动）
|
||||
|
||||
1. 人工打回时 → 打回意见自动结构化写入对应 Agent 的 L3
|
||||
2. 质检 FAIL → 错误模式自动写入质检 Agent 的 L2（同段重跑时注入）
|
||||
3. 你编辑 rules.md → 记为 L1
|
||||
4. 每轮跑完 → 主控询问是否复盘沉淀（不自动，避免噪音）
|
||||
|
||||
### 7.4 记忆库物理隔离
|
||||
|
||||
```
|
||||
memory/
|
||||
coordinator/ ← 主控记忆（项目管理偏好）
|
||||
segment_opening/ ← 开场段 Agent 记忆
|
||||
segment_xinfa/ ← 心法段 Agent 记忆
|
||||
segment_jifa/ ← 技法段 Agent 记忆
|
||||
qc_structure/ ← 结构质检记忆（错误模式）
|
||||
qc_content/ ← 内容质检记忆
|
||||
qc_style/ ← 风格尺度质检记忆
|
||||
qc_cross/ ← 跨稿质检记忆
|
||||
composer/ ← 组合 Agent 记忆
|
||||
```
|
||||
每个库独立命名空间，Agent 运行时只挂载自己的记忆文件。
|
||||
|
||||
## 8. 全流程时序（正常路径 + 打回路径）
|
||||
|
||||
```
|
||||
正常路径：
|
||||
你 ──主题/导图──▶ 主控 ──任务单──▶ [段Agent们 并行] ──每段产物──▶ [4道质检并行]
|
||||
▶ 质检报告 ──▶ 人工审查台 ──全部✅──▶ 组合Agent ──▶ 直播文稿.docx
|
||||
|
||||
打回路径（哪里不对改哪里）：
|
||||
人工审查 🔁打回段3 ──意见──▶ 段3 Agent（读取意见+自己记忆+任务单切片）
|
||||
──重新生成段3──▶ 质检(段3) ──▶ 人工复审 ──✅──▶ 继续
|
||||
（段1/2/4 产物原封不动，不重跑）
|
||||
|
||||
规则修改路径：
|
||||
你 ──改 rules.md──▶ 指定 Agent ──重跑该环节──▶ 质检 ──▶ 审查
|
||||
```
|
||||
|
||||
## 9. 数据模型（核心 Schema）
|
||||
|
||||
```json
|
||||
// 任务单 TaskSpec
|
||||
{
|
||||
"campaign_id": "2026-08-26-day5",
|
||||
"mindmap_source": "导图文件路径",
|
||||
"total_duration": 120,
|
||||
"segments": [
|
||||
{
|
||||
"id": "seg-01",
|
||||
"title": "开场·扎心+承诺",
|
||||
"time": "00:00-00:08",
|
||||
"type": "opening",
|
||||
"mindmap_node": "导图节点原文转录",
|
||||
"products": [],
|
||||
"requirements": ["开场降档", "30秒入题"]
|
||||
}
|
||||
],
|
||||
"quality_gates": ["structure", "content", "style", "cross"],
|
||||
"word_limits": {"min": 5000, "target": 6758}
|
||||
}
|
||||
|
||||
// 质检报告 QCReport
|
||||
{
|
||||
"segment_id": "seg-03",
|
||||
"checks": [
|
||||
{"id": "structure-04", "name": "时间轴核对", "status": "FAIL",
|
||||
"issues": [{"location": "段标题③", "desc": "时间标注 00:22-00:30 与导图 00:20-00:28 不符",
|
||||
"suggestion": "改回导图时间", "severity": "high"}]}
|
||||
],
|
||||
"verdict": "FAIL"
|
||||
}
|
||||
|
||||
// 记忆条目 MemoryEntry
|
||||
{
|
||||
"agent_id": "segment_jifa",
|
||||
"type": "L3_preference",
|
||||
"content": "技法段讲解前必须先给'为什么'铺垫1-2句再进干货",
|
||||
"source": "2026-08-day4打回#2",
|
||||
"created": "2026-08-25",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
## 10. 落地技术选型（三条路，先看后定）
|
||||
|
||||
| 方案 | 形态 | 优点 | 缺点 | 工期 |
|
||||
|---|---|---|---|---|
|
||||
| **A. 轻量版（推荐先跑）** | 基于现有 Hermes 体系：每 Agent = 一个 skill + 独立记忆目录 + 独立工作目录；主控用 delegate_task 派发；质检用脚本+LLM 双检；组合复用 make_color_docs.py 引擎 | 零新基建、直接复用全部现有技能/素材库/质检清单、今天就可用 | 无可视化界面（命令行/对话式操作）、并行度受 Hermes 限制 | 1-2 天 |
|
||||
| **B. 工作台版（正式目标）** | 独立 Web 应用：FastAPI + DeepSeek API + SQLite + 前端看板。可视化：任务单看板、每段产物卡片、质检报告红绿灯、打回/通过按钮、规则编辑器 | 符合"工作台"体验、人工审查台最顺、可多人协作 | 开发量中等（知识库检索/记忆库/编排层都要自建） | 1-2 周 |
|
||||
| C. dsh 编排版 | 用 dsh 多 Agent 拓扑 + 自定义 harness 脚本 | 复用你已有的 dsh | dsh 目前偏单 Agent CLI/Web UI，多 Agent 编排要自己写协调层，且无工作台 UI | 1 周 |
|
||||
|
||||
**建议路径**：先用 A 把流程跑通（生成一篇真实稿子验证全链路，同时把任务单/质检报告/记忆的 schema 在实际使用中敲定），再上 B 做可视化工作台——A 跑出来的数据模型直接成为 B 的数据库结构。
|
||||
|
||||
## 11. 里程碑
|
||||
|
||||
| 阶段 | 内容 | 验收标准 |
|
||||
|---|---|---|
|
||||
| M1 流程验证（A 方案） | 搭好目录骨架 + 主控拆解 + 3 个段 Agent + 2 道质检 + 人工审查 + 组合 | 用一天真实导图跑出完整直播文稿，打回重跑某段不影响其他段 |
|
||||
| M2 记忆闭环 | 记忆库全部 Agent 落地 + 打回意见自动沉淀 + 重跑注入 | 同一错误第二次打回率显著下降 |
|
||||
| M3 工作台 UI（B 方案） | 任务看板 + 产物卡片 + 质检红绿灯 + 审查操作 + 规则编辑器 | 全程可视化，不再依赖对话式操作 |
|
||||
| M4 增强 | 多天批量跑（跨稿质检自动对账 day N-1 预告）、知识库增量导入 | 连续生成多天稿，跨稿质检 0 漏项 |
|
||||
|
||||
## 12. 风险与红线（设计内嵌，来自实战教训）
|
||||
|
||||
1. **导图读取**：手写/OCR 导图读不准的词，主控必须先列待确认清单问你再动稿（"龙蛇混杂/跟班戏"教训）
|
||||
2. **口径不沉淀**：记忆库严禁把场次性口径（价格/头衔/技法名/产品组合）升级为跨稿规则（两轮纠正教训）；规则只沉淀"怎么讲"
|
||||
3. **质检报告≠事实**：质检 Agent 的每条断言必须能对证正文，报告与正文脱节=质检自身 FAIL（"表面功夫"红线）
|
||||
4. **产品概念边界**：一产品一概念（水润≠养护），全稿"养护"清零——写入内容质检固定检查项
|
||||
5. **上下文串扰**：段 Agent 只读自己的切片+知识库，任何"参考其他段"的需求必须经主控显式授权（防止隐含口径漂移）
|
||||
6. **记忆噪音**：L4 成功记忆不自动写入，只在你确认复盘时沉淀，避免"越用越偏"
|
||||
7. **合规底线**：质检保留合规闸（无证宣称/绝对化用语/编造解剖名词），生成机制沿用防拒审信封（授权上下文只进后台不进正文）
|
||||
|
||||
---
|
||||
|
||||
**待你确认的问题：**
|
||||
1. 段 Agent 的默认划分（开场/心法/技法/场景/产品/收尾/互动标记 7 个）是否符合你脑子里的环节？要增减哪些？
|
||||
2. 落地路径选 A（今天就能跑）还是直接上 B（工作台 UI）？还是 A 先验证再 B？
|
||||
3. 记忆沉淀时机：打回意见自动沉淀（推荐）vs 全部手动确认，你倾向哪种？
|
||||
@@ -0,0 +1,299 @@
|
||||
# 雅文内容创造工作台 · 设计文档 v2（B 方案·独立 Web 工作台）
|
||||
|
||||
> 日期：2026-08-25 ｜ 状态：方案确认稿 ｜ 技术路线：独立 Web 应用（FastAPI + SQLite + React）
|
||||
> v1 → v2 变更：① Agent 注册中心（可自建 Agent，数量不限）② 记忆沉淀需人工确认（待确认池）③ 锚点卡上下文契约（解决段间互不知情的连贯性问题）④ 组合 Agent 升级为"拼装+一致性总检+打回路由"
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
一个**独立运行的 Web 工作台**（浏览器访问，本地部署），核心是"多 Agent 内容工厂"：
|
||||
|
||||
- 你只需要：输入主题/导图/框架 → 主控 Agent 自动拆解派单 → 各环节 Agent 生产 → 4 道质检 → 人工审查 → 组合交付
|
||||
- **Agent 可以自己随便添加**：预置 7 个环节 Agent + 4 个质检 Agent + 2 个服务 Agent，任何时刻你都可以新建/复制/停用 Agent，把它编进流水线
|
||||
- **记忆沉淀必须你点头**：所有"AI 想记住的东西"先进待确认池，你确认了才写进对应 Agent 的记忆库
|
||||
- **连贯性有双保险**：生成时传锚点卡对齐 + 组合时一致性总检，发现问题打回原段，不糊弄
|
||||
|
||||
## 2. 需求 → 设计对策映射（v2 完整版）
|
||||
|
||||
| # | 你的要求 | 设计对策 | 状态 |
|
||||
|---|---|---|---|
|
||||
| 1 | 很多个 Agent 组成 | 预置 13 个 Agent，可自由添加 | v2 升级：注册中心 |
|
||||
| 2 | 每个 Agent 可设置规则 | 每个 Agent 一个 `rules.md`，工作台内可视化编辑，版本历史可回滚 | ✅ |
|
||||
| 3 | 上下文隔离 | Agent 间不共享对话，只传结构化契约：任务切片 + 上游锚点卡 | v2 升级：锚点卡 |
|
||||
| 4 | 知识库共用 | 只读共享知识库（6 库），所有 Agent 可检索、不可写 | ✅ |
|
||||
| 5 | 哪里不对改哪里 | 打回粒度=段产物；三种修改路径（打回/改规则/直接改） | ✅ |
|
||||
| 6 | 给主 Agent 主题/导图即可 | 主控解析→任务单→自动派发（按依赖分波次）→跟踪→汇总 | v2 升级：波次调度 |
|
||||
| 7 | 每件产物都有质检 Agent | 4 道质检闸（结构/内容/风格尺度/跨稿），产物生成即检 | ✅ |
|
||||
| 8 | 质检过还要人工审查 | 人工审查台=硬关卡，质检全过≠交付 | ✅ |
|
||||
| 9 | 组合成一篇直播文稿 | 组合 Agent：拼装+一致性总检+六色 docx | v2 升级：总检职责 |
|
||||
| 10 | Agent 自主学习、越用越懂 | 每 Agent 独立记忆库（L1-L4），**写入需人工确认** | v2 升级：待确认池 |
|
||||
| 11 | 记忆库隔离 | 记忆按 Agent 命名空间物理隔离 | ✅ |
|
||||
| 12 | **Agent 可自添加、数量不限** | Agent 注册中心：新建向导/复制/停用/版本管理；流水线自由编排 | 🆕 |
|
||||
| 13 | **沉淀先人工确认** | 所有沉淀建议→待确认池→人工确认→写入；拒绝可屏蔽 | 🆕 |
|
||||
| 14 | **段间连贯性** | 锚点卡（生成时对齐）+ 组合器一致性总检（兜底） | 🆕 |
|
||||
|
||||
## 3. 系统架构总览（v2）
|
||||
|
||||
```
|
||||
┌────────────────────────── 你（浏览器访问工作台） ──────────────────────────┐
|
||||
│ 输入：主题/导图/框架 · 管理：Agent注册中心/流水线编辑 · 审查：质检+记忆确认 │
|
||||
└───────┬──────────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ Agent 注册中心（可自建） │
|
||||
│ ├─ 预置生产Agent：开场/心法/技法/场景/产品/收尾/互动标记 │
|
||||
│ ├─ 预置质检Agent：结构/内容/风格尺度/跨稿 │
|
||||
│ ├─ 预置服务Agent：产品顾问/风格顾问 │
|
||||
│ └─ 你新建的任意 Agent（向导：名称/职责类型/规则/输入来源/记忆库自动开） │
|
||||
└──────────────────────────┬─────────────────────────────────────────────┘
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ 流水线编排器（Pipeline，DAG 依赖图） │
|
||||
│ 主控Agent：解析导图→任务单→按依赖分波次派发→跟踪→汇总 │
|
||||
│ 波次1：开场段、服务Agent预热 波次2：心法段、技法段（读开场锚点卡） │
|
||||
│ 波次3：场景段、产品段（读心法/技法锚点卡） 波次4：收尾段（读全部锚点卡） │
|
||||
└──────┬─────────────────────────────────────────────────────────────────┘
|
||||
▼ 每波次完成后
|
||||
┌────────────────────────────────────────────────────────────────────────┐
|
||||
│ [段Agent]（每段独立会话/独立记忆库）──产出──▶ 段产物 + 锚点卡AnchorCard │
|
||||
│ ▲ │ │ │
|
||||
│ │ ▼ ▼ │
|
||||
│ 打回重跑 ◀── 4道质检闸（结构/内容/风格尺度/跨稿）──▶ 质检报告 │
|
||||
│ ▲ │ │
|
||||
│ │ ▼ 全过 │
|
||||
│ ┌────┴──────┐ ┌──────────────┐ │
|
||||
│ │ 人工审查台 │◀── 逐段：产物+质检报告+锚点卡 ──────────│ 记忆待确认池 │ │
|
||||
│ │ ✅通过/🔁打回│（打回意见→记忆建议，等你确认） │ 沉淀建议→你确认│ │
|
||||
│ └────┬──────┘ └──────────────┘ │
|
||||
│ ▼ 全部通过 │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 组合Agent：时间轴拼装 → 一致性总检（矛盾/回指/时间线/情绪曲线/钩子） │ │
|
||||
│ │ → 不一致打回原段（带位置） → 微衔接缝合（必须标记） → 六色docx │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
└────────────────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
📄 直播文稿.docx（六色标记）+ 组合报告（衔接处理清单）+ 待确认清单
|
||||
```
|
||||
|
||||
## 4. Agent 注册中心（🆕 核心变更 1）
|
||||
|
||||
### 4.1 三种 Agent 类型
|
||||
|
||||
| 类型 | 干什么 | 例子 | 是否参与流水线 |
|
||||
|---|---|---|---|
|
||||
| 生产 Agent | 生成一段内容 | 开场段、心法段、你自己建的"弹幕互动段" | ✅ 是流水线节点 |
|
||||
| 质检 Agent | 检查某类质量 | 结构质检、合规质检 | ✅ 挂在每个段产物上 |
|
||||
| 服务 Agent | 只读供给素材/标准 | 产品顾问、风格顾问 | 后台被调用 |
|
||||
|
||||
### 4.2 新建 Agent（向导式，5 步，几分钟完成）
|
||||
|
||||
```
|
||||
1. 基本信息：名称 / 描述 / 图标 / 类型
|
||||
2. 职责定义：这个 Agent 负责生成/检查什么（一句话职责）
|
||||
3. 规则编辑：自动生成 rules.md 模板 → 你直接写规则（支持 Markdown）
|
||||
（预置常用规则片段库：开场降档/技法快准狠/一产品一概念/色情小说档…一键插入）
|
||||
4. 输入来源：从哪个上游读锚点卡（可多选）/ 需要哪些知识库（勾选）
|
||||
5. 确认创建：自动创建独立记忆库 + 工作目录 + 测试按钮（拿一段样稿试跑）
|
||||
```
|
||||
|
||||
- **复制**：右键现有 Agent → 复制 → 改名改规则（想做个"青蛇白蛇段Agent"就复制"场景段Agent"改规则）
|
||||
- **停用/启用**：停用的 Agent 不进派单池，历史产物保留
|
||||
- **版本管理**：规则每次保存记版本，可回滚，可对比 diff
|
||||
- **数量无上限**：Agent 表就是普通数据库表，加多少都行
|
||||
|
||||
### 4.3 Agent 的能力标签
|
||||
|
||||
每个 Agent 挂标签（心法/技法/产品/场景/收尾/质检-结构/…），主控派单时按"任务单段类型 → 匹配标签的 Agent"选择执行者。同一类型有多个 Agent 时可选（或轮流）。
|
||||
|
||||
## 5. 流水线编排（🆕 核心变更 2）
|
||||
|
||||
- **默认流水线**（预置）：开场 →(依赖) 心法/技法 →(依赖) 场景/产品 →(依赖) 收尾 → 组合
|
||||
- **你可以编辑**：流水线编辑器（拖拽/列表）里加节点、删节点、改依赖关系、改执行顺序
|
||||
- **调度逻辑**：主控把任务单段映射到流水线节点，按**依赖图分波次（wave）执行**——无依赖的段并行跑，有依赖的段等上游完成后跑
|
||||
- 每个节点配置：执行 Agent、输入来源（读哪些上游的锚点卡）、质检要求（挂哪几道质检）
|
||||
|
||||
## 6. 上下文契约机制（🆕 核心变更 3）—— 回答"段间互不知情"的问题
|
||||
|
||||
### 6.1 锚点卡 AnchorCard（每段产物自动附带）
|
||||
|
||||
```json
|
||||
{
|
||||
"segment_id": "seg-02",
|
||||
"agent": "segment_xinfa",
|
||||
"title": "心法·女人如水",
|
||||
"core_concepts": ["女人是水，男人是火", "先把自己叫湿了"],
|
||||
"techniques": [],
|
||||
"products_ref": [],
|
||||
"golden_lines": ["所有的性感都不是天生的"],
|
||||
"emotion_tone": "温柔引导型（低声区）",
|
||||
"ending_hook": "水要养，亲水先热",
|
||||
"key_facts": []
|
||||
}
|
||||
```
|
||||
|
||||
- 每段产物生成后，由产出 Agent 自动提炼锚点卡（或主控提炼）
|
||||
- **下游 Agent 只读上游锚点卡**（一页摘要），不读全文、不共享对话——隔离不破，连贯性有保障
|
||||
- 锚点卡同时是质检的"对照物"：质检核对产物与锚点卡是否一致（防锚点卡撒谎）
|
||||
|
||||
### 6.2 依赖规则（默认，可改）
|
||||
|
||||
| 下游段 | 必读锚点卡 | 为什么 |
|
||||
|---|---|---|
|
||||
| 心法段 | 开场段 | 心法要接住开场的情绪落差 |
|
||||
| 技法段 | 心法段 | 技法兑现心法埋的钩子 |
|
||||
| 场景段 | 心法段+技法段 | 场景要用已教的技法做戏 |
|
||||
| 产品段 | 技法段 | 产品挂靠已展示的痛点技法（卖点前必有痛点技法展示） |
|
||||
| 收尾段 | 全部 | 收尾钩子=次日真实框架+本场回指 |
|
||||
|
||||
## 7. 组合 Agent（升级：拼装 + 一致性总检 + 打回路由）
|
||||
|
||||
### 7.1 拼装
|
||||
按任务单时间轴把各段拼接（每段标题带时间标注、大块灰字分隔），复用六色标记 docx 引擎（宋体 10.5pt、段落自然合并 85-110 段）。
|
||||
|
||||
### 7.2 一致性总检（组合器新增核心职责，5 项）
|
||||
|
||||
| 检查项 | 查什么 | 不过怎么办 |
|
||||
|---|---|---|
|
||||
| 跨段矛盾 | 概念/数据/说法前后打架（阈值高 vs 低） | 打回对应段 |
|
||||
| 回指断裂 | 前面提到的技法/产品/金句，后面引用对得上 | 打回引用段或定义段 |
|
||||
| 时间线打架 | 段标题时间标注与任务单、与段内叙述一致 | 打回该段 |
|
||||
| 情绪曲线断裂 | 全稿情绪走势（低谷→峰值→信念收尾）连贯 | 打回问题段 |
|
||||
| 钩子兑现 | 段 N 结尾钩子 = 段 N+1 实际内容；收尾钩子=次日预告 | 打回 |
|
||||
|
||||
### 7.3 处理原则：打回 > 缝合
|
||||
|
||||
- 结构性不一致 → **打回原段重跑**（组合器永不擅自改内容）
|
||||
- 微小衔接（两段交界缺个过渡句）→ 组合器做"缝合编辑"，但**缝合处必须标记**（蓝色【B】+ 组合报告里列"衔接处理清单"给你看）
|
||||
|
||||
### 7.4 组合报告
|
||||
交付时附带：`衔接处理清单`（哪些原样拼接/哪些缝合/哪些打回过）、时间压缩决策、跨稿对账结果、待确认项。
|
||||
|
||||
## 8. 质检体系（4 道闸，不变，细节见 v1 第 4.4）
|
||||
|
||||
| 闸 | 检查 | 产物 |
|
||||
|---|---|---|
|
||||
| ① 结构质检 | 硬伤/笔误/结构残留/时间轴 | 质检报告（逐条对证正文） |
|
||||
| ② 内容质检 | 痛点技法展示/一产品一概念/技法密度/为什么铺垫 | 同上 |
|
||||
| ③ 风格尺度质检 | 色情小说档词清单/禁词清零/反问句归零/表演标记 | 同上 |
|
||||
| ④ 跨稿质检 | day N-1 预告兑现/价格术语/产品台账 | 同上 |
|
||||
|
||||
质检报告格式、打回路由与 v1 相同；新增：质检报告核对锚点卡一致性。
|
||||
|
||||
## 9. 人工审查台（硬关卡 + 记忆确认面板）
|
||||
|
||||
### 9.1 逐段审查视图
|
||||
- 左：段产物全文（表演标记灰色显示）
|
||||
- 右：该段质检报告（红绿灯）+ 锚点卡 + 时间轴位置
|
||||
- 操作：✅ 通过 / 🔁 打回（写意见，意见自动生成"记忆建议"进待确认池）/ ✏️ 直接改（改动标记）
|
||||
|
||||
### 9.2 记忆确认面板（🆕 核心变更 4）
|
||||
```
|
||||
┌─ 待确认池（记忆建议）─────────────────────────────┐
|
||||
│ #3 建议沉淀：技法段Agent ← 打回意见 │
|
||||
│ "技法讲解前必须先给'为什么'铺垫1-2句再进干货" │
|
||||
│ 来源：2026-08-day4 打回#2 ｜ 类型：L3偏好 │
|
||||
│ [✅ 确认沉淀] [❌ 拒绝] [🚫 拒绝且屏蔽同类] │
|
||||
│ #4 建议沉淀：质检Agent ← 质检FAIL │
|
||||
│ "本场高频错误：'养护'字样残留" │
|
||||
│ [✅ 确认沉淀] [❌ 拒绝] │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
- 任何沉淀（打回意见/质检模式/你的规则改动）**都先进池子**
|
||||
- 确认 → 写入对应 Agent 记忆库（独立命名空间）；拒绝 → 丢弃；"屏蔽同类" → 该来源类型不再建议
|
||||
- 池子可批量操作（连过 5 条）
|
||||
|
||||
### 9.3 组合终审
|
||||
组合完成后你还要过一遍全文（组合 Agent 的报告+全文），确认后才是最终交付。质检→人工→组合→人工终审，四道关卡。
|
||||
|
||||
## 10. 记忆系统（v2：人工确认版）
|
||||
|
||||
| 层 | 内容 | 来源 | 写入方式 |
|
||||
|---|---|---|---|
|
||||
| L1 规则 | 你显式改的规则 | 你编辑 rules.md | 直接写入（你改的就是规则） |
|
||||
| L2 纠错 | 质检错误模式 | 质检 FAIL 自动生成建议 | **待确认池→你确认** |
|
||||
| L3 偏好 | 打回意见/审查意见 | 打回时自动生成建议 | **待确认池→你确认** |
|
||||
| L4 成功 | 通过稿复盘 | 你主动触发 | 你触发才生成建议，再确认 |
|
||||
|
||||
红线不变：只沉淀"怎么讲"（打法/结构/风格/质检标准），不沉淀"讲什么"（价格/头衔/技法名/场次性口径）；记忆条目带来源标签可追溯。
|
||||
|
||||
## 11. 数据模型（v2 核心表）
|
||||
|
||||
```sql
|
||||
agents -- Agent 注册中心
|
||||
id, name, type(production|qc|service), status(active|disabled),
|
||||
tags, rules_version, memory_namespace, created_at, version_history(json)
|
||||
|
||||
pipelines -- 流水线定义
|
||||
id, name, nodes(json: [{agent_id, depends_on[], qc_gates[], kb_tags[]}])
|
||||
|
||||
campaigns -- 每次生产任务
|
||||
id, date_id, pipeline_id, mindmap_ref, task_spec(json), status, wave_state
|
||||
|
||||
segments -- 段产物
|
||||
id, campaign_id, agent_id, node_id, anchor_card(json),
|
||||
artifact_path, status(pending|qc|human_review|approved|rework), version
|
||||
|
||||
qc_reports -- 质检报告
|
||||
id, segment_id, gate(structure|content|style|cross), checks(json), verdict
|
||||
|
||||
pending_memories -- 记忆待确认池
|
||||
id, target_agent_id, type(L2|L3|L4), content, source_ref,
|
||||
status(pending|approved|rejected|blocked)
|
||||
|
||||
memories -- 已确认记忆（per-agent 命名空间）
|
||||
id, agent_id, layer(L1-L4), content, source_ref, created_at, status(active|expired)
|
||||
|
||||
artifacts -- 组合产物
|
||||
id, campaign_id, docx_path, compose_report(json), final_status
|
||||
```
|
||||
|
||||
## 12. 工作台页面规划（UI）
|
||||
|
||||
| 页面 | 功能 |
|
||||
|---|---|
|
||||
| 任务看板（首页） | 新建任务（传导图/主题）、任务列表、每任务进度（波次状态/各段红绿灯/当前卡在哪） |
|
||||
| Agent 管理 | Agent 列表/新建向导/规则编辑器（含版本历史）/复制/停用/试跑按钮 |
|
||||
| 流水线编辑 | 节点编排（加/删/依赖连线）、节点 Agent 指派、质检挂载 |
|
||||
| 导图解析 | 上传导图 → 主控解析预览 → 读不准的词列表 → 你确认/修正 → 生成任务单 |
|
||||
| 审查台 | 逐段审查（产物+质检报告+锚点卡）+ 打回/通过 + 直接改 |
|
||||
| 记忆确认 | 待确认池：确认/拒绝/屏蔽 + 各 Agent 记忆浏览（只读） |
|
||||
| 交付中心 | 组合报告 + docx 下载 + 历史版本 |
|
||||
|
||||
## 13. 技术选型（B 方案落地）
|
||||
|
||||
| 层 | 选型 | 理由 |
|
||||
|---|---|---|
|
||||
| 后端 | FastAPI (Python) | 你环境 Python 3.14 可用；FastAPI 开发快、异步适合并行调 Agent |
|
||||
| 数据库 | SQLite + SQLModel | 单机部署零运维；一张库文件可备份迁移 |
|
||||
| Agent 引擎 | DeepSeek API（可配置多 provider） | 你已有 DeepSeek 密钥；后续可换 |
|
||||
| 知识库 | 文件系统 + SQLite FTS5 全文检索 | 素材是本地文件（SRT/docx/md/chunks.jsonl），先做索引+BM25；后续可加向量 |
|
||||
| 前端 | React + Vite + 看板组件 | 交互密集（拖拽/红绿灯/编辑）；本地起 dev server |
|
||||
| 产物 | 文件系统 + 元数据入库 | docx 引擎复用 make_color_docs.py 逻辑（改为工作台内生成） |
|
||||
| 部署 | 本机 `uvicorn` 服务，浏览器访问 localhost | 单用户；后续可加登录 |
|
||||
|
||||
## 14. 里程碑（2 周，4 阶段，每阶段可验收）
|
||||
|
||||
| 阶段 | 内容 | 验收标准 |
|
||||
|---|---|---|
|
||||
| **M1（第1-2天）** 骨架+核心链路 | 后端骨架、SQLite 表、Agent 注册中心（新建/规则编辑）、任务创建（传导图/文字）、主控解析→任务单→顺序派发（先不做波次）、3 个预置段 Agent、结构质检 1 道、审查台（打回/通过）、组合（简单拼接+docx） | 用一天真实导图跑通：导图→任务单→3段→质检→审查→docx 全链路 |
|
||||
| **M2（第3-6天）** 隔离与连贯 | 锚点卡机制、依赖图波次调度、流水线编辑器（简单版）、全部 7 个预置段 Agent、4 道质检全开 | 段间互读锚点卡生效；打回段3 不影响段1/2/4；质检报告逐条可对证 |
|
||||
| **M3（第7-10天）** 记忆+组合升级 | 待确认池（记忆面板）、L1-L4 记忆库落库、组合器一致性总检（5项）+缝合标记+组合报告、知识库接入（原文库/备稿库/产品库 FTS5 检索+风格顾问/产品顾问） | 打回意见进池→确认→下次注入；组合器抓到一次真实矛盾并打回；六色 docx 规格达标（宋体10.5/段落合并/词清单验证） |
|
||||
| **M4（第11-14天）** 打磨+批量 | 导图图片 OCR 接入（Windows OCR 替代路径）、多天连续任务、跨稿对账自动化（day N-1 预告→day N 兑现）、UI 打磨 | 连续跑 3 天稿子，跨稿质检 0 漏项；全程不依赖对话式操作 |
|
||||
|
||||
## 15. 风险与红线（继承 v1 + 新增）
|
||||
|
||||
1. 导图读取：读不准的词必须列待确认清单问你（不变）
|
||||
2. 口径不沉淀：记忆系统只沉淀"怎么讲"（不变，且加人工确认双保险）
|
||||
3. 质检报告≠事实：报告逐条对证正文（不变）+ 新增核对锚点卡
|
||||
4. **锚点卡防撒谎**：锚点卡由质检核对与产物一致性，防"摘要和正文不符"导致下游被误导
|
||||
5. **组合器权限边界**：只拼装+总检+缝合标记，永不擅自改内容；结构性不一致一律打回
|
||||
6. 记忆噪音：待确认池挡住噪音；"屏蔽同类"防反复打扰
|
||||
7. 合规底线：质检保留合规闸；防拒审信封只进后台不进正文
|
||||
8. 并行与成本：波次调度天然限流（同波次并发数可配置），DeepSeek API 调用量在任务页可见
|
||||
|
||||
---
|
||||
|
||||
**待你确认（v2 只剩 2 个关键问题）：**
|
||||
1. 默认流水线依赖关系（第 6.2 表：心法读开场、技法读心法、产品读技法…）符合你的生产逻辑吗？要不要调整？
|
||||
2. M1 验收用哪一天的导图试跑？（建议最近一天的真实导图，边跑边把任务单/锚点卡 schema 敲实）
|
||||
@@ -0,0 +1,256 @@
|
||||
# 雅文内容创造工作台 · 设计文档 v3（开放画布版）
|
||||
|
||||
> 日期：2026-08-25 ｜ 状态：方案确认稿 ｜ 技术路线：FastAPI + SQLite + React（React Flow 画布）
|
||||
> v2 → v3 变更：① **Agent 关系画布**（可视化编排：改顺序/单独启停/任意连线，不再有固定流水线）② **内容类型标签体系**（心法/案例/技法/功法/产品销售/画面/场景/收尾/钩子…同类内容可生成多个）③ **多知识库隔离挂接**（知识库随便建、每个 Agent 自己配挂哪些库、库与库隔离）
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
一个**开放的多 Agent 内容工厂**（浏览器访问的独立 Web 工作台）：
|
||||
|
||||
- 你建 Agent（数量不限）→ 在**画布**上把 Agent 连成关系图 → 给每个 Agent 配规则、配知识库、随时启停
|
||||
- 每次生产：给主控主题/导图 → 主控拆解成"内容段"（每段一个内容类型）→ 按画布关系派发执行 → 每段过质检 → 人工审查 → 组合交付
|
||||
- **一切都是可改的**：画布关系可改、顺序可改、单个 Agent 可停用、规则可改、知识库挂接可改、内容数量（几个心法几个技法）由导图说了算
|
||||
- 记忆沉淀必须你确认；段间靠锚点卡对齐；组合 Agent 做一致性总检
|
||||
|
||||
## 2. 需求 → 设计对策（v3 完整版）
|
||||
|
||||
| # | 你的要求 | 设计对策 | 状态 |
|
||||
|---|---|---|---|
|
||||
| 1 | Agent 可随便添加、数量不限 | Agent 注册中心 + 画布拖入 | v3：画布化 |
|
||||
| 2 | 每个 Agent 可设置规则 | 每个 Agent 一个 rules.md，可视化编辑+版本回滚 | ✅ |
|
||||
| 3 | 上下文隔离 | 只传结构化契约：任务切片 + 上游锚点卡 | ✅ |
|
||||
| 4 | **知识库分开、可建多个** | 知识库管理页：随便建库、导素材、独立索引 | 🆕 |
|
||||
| 5 | **每个 Agent 设置获取哪个知识库** | Agent 配置里勾选挂接库（多选），只查挂接的库 | 🆕 |
|
||||
| 6 | **知识库也是隔离的** | 每库独立命名空间，Agent 只能检索被挂接的库 | 🆕 |
|
||||
| 7 | **Agent 关系画布** | React Flow 画布：节点=Agent、连线=依赖，拖拽编排 | 🆕 |
|
||||
| 8 | **可修改内容生成顺序** | 画布连线/节点顺序即生成顺序，随时改 | 🆕 |
|
||||
| 9 | **单独停用一个 Agent** | 节点上启停开关，停用则该节点不执行（下游读锚点卡时自动跳过） | 🆕 |
|
||||
| 10 | **生成多个心法、多个技法** | 内容类型标签体系：导图拆几个同类段就生成几个，画布可放多个同类 Agent 节点 | 🆕 |
|
||||
| 11 | Agent 内容基本类型 | 预置标签：心法/案例/技法/功法/产品销售/画面/场景/收尾/钩子（+开场/互动），可自定义新增 | 🆕 |
|
||||
| 12 | 哪里不对改哪里 | 打回粒度=段；三种修改路径 | ✅ |
|
||||
| 13 | 每件产物过质检 | 4 道质检闸（可配置挂哪些） | ✅ |
|
||||
| 14 | 质检过还要人工审查 | 审查台硬关卡 | ✅ |
|
||||
| 15 | 组合成直播文稿 | 组合 Agent：拼装+一致性总检+六色 docx | ✅ |
|
||||
| 16 | 自主学习、越用越懂 | 每 Agent 独立记忆库（L1-L4） | ✅ |
|
||||
| 17 | 沉淀先人工确认 | 记忆待确认池 | ✅ |
|
||||
|
||||
## 3. 核心概念（v3 三大件）
|
||||
|
||||
### 3.1 内容类型标签（Content Tags）
|
||||
|
||||
Agent 与任务段的共同语言。**预置 11 个标签**（你列的 9 个 + 开场 + 互动），可随时自定义新增：
|
||||
|
||||
```
|
||||
开场 · 心法 · 案例 · 技法 · 功法 · 产品销售 · 画面 · 场景 · 收尾 · 钩子 · 互动
|
||||
```
|
||||
|
||||
- **任务侧**：主控解析导图时，每个导图节点标一个内容类型 → 成为"内容段"。导图里有 3 个技法块就拆 3 个技法段（同类多个，天然支持）
|
||||
- **Agent 侧**：每个 Agent 声明自己擅长哪些标签（多选）。一个 Agent 可以"场景+画面+产品销售"多标签
|
||||
- **派单**：内容段 → 找"标签匹配 + 启用中"的 Agent 节点执行
|
||||
|
||||
### 3.2 Agent 关系画布（Canvas）
|
||||
|
||||
```
|
||||
┌─ 画布（浏览器，React Flow）──────────────────────────────────────┐
|
||||
│ │
|
||||
│ [主控Agent] │
|
||||
│ │ 派发任务单 │
|
||||
│ ▼ │
|
||||
│ [开场Agent ●]─────────▶[心法Agent ●]───▶[技法Agent1 ●]─┐ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ▼ ▼ ▼ │
|
||||
│ │ [案例Agent ●] [功法Agent ●] [技法Agent2]│
|
||||
│ │ │ │ │ │
|
||||
│ │ ▼ ▼ ▼ │
|
||||
│ │ [产品销售Agent ●]──[画面Agent ●]─[场景Agent●]│
|
||||
│ │ │ │
|
||||
│ │ ▼ │
|
||||
│ │ [收尾Agent ●] │
|
||||
│ │ │ │
|
||||
│ │ ▼ │
|
||||
│ │ [钩子Agent ●] │
|
||||
│ └────────────────────────────────────────────────────────────┘
|
||||
│ ●=启用 ○=停用（灰显，不执行） 箭头=锚点卡流向（下游读上游） │
|
||||
└───────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**画布能力**：
|
||||
| 操作 | 说明 |
|
||||
|---|---|
|
||||
| 拖入 Agent | 从注册中心拖任意 Agent 上画布（同一 Agent 可放多个节点=同类型并行/串行多段） |
|
||||
| 连线 | 从 A 拉到 B = B 读 A 的锚点卡；不连 = 完全隔离 |
|
||||
| 改顺序 | 拖节点、改连线，生成顺序即图顺序（拓扑排序） |
|
||||
| 单独停用 | 节点上开关：停用=该节点不执行，下游读锚点卡时自动跳过（如停用"产品销售"，全文就 0 产品） |
|
||||
| 分支并行 | 一个节点连多个下游 = 并行；串成链 = 串行 |
|
||||
| 模板保存 | 画布存成模板（如"完整场"、"纯心法场"、"无产品场"），一键复用 |
|
||||
| 版本快照 | 任务开工时固化画布快照，之后改画布不影响已跑任务 |
|
||||
|
||||
### 3.3 多知识库隔离挂接（Knowledge Bases）
|
||||
|
||||
```
|
||||
┌─ 知识库管理页 ──────────────────────────────────────────────┐
|
||||
│ [+ 新建知识库] 每个库=独立命名空间+独立索引 │
|
||||
│ ├─ 📚 风格档案库 （种子：数字雅文档案/范稿/定稿基准） │
|
||||
│ ├─ 📚 训练营框架库 （种子：七天导图/28天重排版） │
|
||||
│ ├─ 📚 直播原文库 （种子：73场SRT，可增量导入） │
|
||||
│ ├─ 📚 备稿库 （种子：99篇docx） │
|
||||
│ ├─ 📚 产品知识库 （种子：观品chunks.jsonl） │
|
||||
│ ├─ 📚 质检规则库 （种子：审查五类清单/词清单） │
|
||||
│ └─ 📚 你建的库：如"青蛇白蛇素材库"（拖文件进去自动索引） │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
每个 Agent 的配置里：
|
||||
[知识库挂接（多选）]
|
||||
☑ 风格档案库 ☑ 产品知识库
|
||||
☐ 直播原文库 ☐ 备稿库 …
|
||||
|
||||
隔离规则：
|
||||
· Agent 检索时只能命中被挂接的库，挂接外的一律不可见
|
||||
· 知识库之间互不可见（库A的内容不会出现在库B的检索结果）
|
||||
· 挂接可随时改，改完立即生效（不影响已跑任务）
|
||||
```
|
||||
|
||||
## 4. 系统架构总览（v3）
|
||||
|
||||
```
|
||||
┌─────────────────── 你（浏览器访问工作台） ─────────────────────┐
|
||||
│ 任务看板 · Agent注册中心 · 关系画布 · 知识库管理 · 审查台 · 记忆 │
|
||||
└──────┬───────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌───────────────────────────────────────────────────────────────┐
|
||||
│ Agent 注册中心（可自建，数量不限） │
|
||||
│ Agent = { 名称/描述/类型(生产|质检|服务) │
|
||||
│ ｜内容标签(心法|案例|技法|功法|产品销售|画面|场景|收尾|钩子…) │
|
||||
│ ｜知识库挂接(多选) ｜ rules.md(版本历史) ｜ 独立记忆库 } │
|
||||
└──────────────────────────┬────────────────────────────────────┘
|
||||
▼
|
||||
┌───────────────────────────────────────────────────────────────┐
|
||||
│ Agent 关系画布（编排层：顺序/依赖/启停，模板化，任务快照） │
|
||||
│ 主控Agent：导图→任务单(内容段+时间轴+产品节点) → 按画布派发 │
|
||||
└──────┬─────────────────────────────────────────────────────────┘
|
||||
▼ 按画布拓扑分波次执行（每段=一个内容类型，同类可多个）
|
||||
┌───────────────────────────────────────────────────────────────┐
|
||||
│ [生产Agent节点]（独立会话/记忆/只读挂接知识库） │
|
||||
│ │ 产出：段内容 + 锚点卡 │
|
||||
│ ▼ │
|
||||
│ 4道质检闸（挂哪些质检Agent可配）→ 报告逐条对证正文+锚点卡 │
|
||||
│ ▼ 全过 │
|
||||
│ 人工审查台（✅/🔁打回→记忆待确认池/✏️直接改） │
|
||||
│ ▼ 全部确认 │
|
||||
│ 组合Agent：拼装 → 一致性总检(5项) → 打回/缝合标记 → 六色docx │
|
||||
└───────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 5. 预置 Agent 清单（种子，全部可改可删可复制）
|
||||
|
||||
| Agent | 类型 | 内容标签 | 默认知识库挂接 |
|
||||
|---|---|---|---|
|
||||
| 主控 Agent | 编排 | — | 全部（解析导图） |
|
||||
| 开场段 Agent | 生产 | 开场 | 风格档案库 |
|
||||
| 心法段 Agent | 生产 | 心法 | 风格档案库+训练营框架库 |
|
||||
| 案例段 Agent | 生产 | 案例 | 直播原文库+备稿库 |
|
||||
| 技法段 Agent | 生产 | 技法 | 风格档案库+直播原文库 |
|
||||
| 功法段 Agent | 生产 | 功法 | 风格档案库 |
|
||||
| 产品销售 Agent | 生产 | 产品销售 | 产品知识库+备稿库 |
|
||||
| 画面段 Agent | 生产 | 画面 | 风格档案库 |
|
||||
| 场景段 Agent | 生产 | 场景 | 风格档案库+直播原文库 |
|
||||
| 收尾段 Agent | 生产 | 收尾 | 风格档案库 |
|
||||
| 钩子段 Agent | 生产 | 钩子 | 训练营框架库（次日真实框架） |
|
||||
| 互动标记 Agent | 生产 | 互动 | 质检规则库 |
|
||||
| 结构质检 | 质检 | — | 质检规则库 |
|
||||
| 内容质检 | 质检 | — | 质检规则库+产品知识库 |
|
||||
| 风格尺度质检 | 质检 | — | 质检规则库（词清单） |
|
||||
| 跨稿质检 | 质检 | — | 备稿库+训练营框架库 |
|
||||
| 产品顾问 | 服务 | — | 产品知识库 |
|
||||
| 风格顾问 | 服务 | — | 风格档案库 |
|
||||
|
||||
> 默认画布（完整场）：开场→心法→(案例∥技法∥功法)→(产品销售∥画面∥场景)→收尾→钩子。你可以改成任何形状。
|
||||
|
||||
## 6. 主控 Agent 拆解逻辑（v3）
|
||||
|
||||
1. 读导图/主题 → 逐节点转录（读不准的词 → 待确认清单问你）
|
||||
2. 每个导图节点 → 内容段：`{段id, 标题, 内容标签, 时间范围, 产品节点?, 导图原文}`
|
||||
3. 同类多段：导图几个技法块就几个技法段（不合并）
|
||||
4. 生成任务单 → 按画布匹配：每段找"标签匹配+启用"的节点 Agent
|
||||
5. 按画布拓扑分波次派发 → 跟踪每段状态（待派/生成中/质检中/待审查/通过/打回）
|
||||
6. 全段通过 → 交组合 Agent
|
||||
|
||||
## 7. 数据模型（v3 核心表）
|
||||
|
||||
```sql
|
||||
agents -- Agent 注册中心
|
||||
id, name, type(production|qc|service), status(active|disabled),
|
||||
content_tags(json:["心法","技法"]), -- 内容类型标签（生产Agent）
|
||||
rules_version, memory_namespace, version_history(json)
|
||||
|
||||
knowledge_bases -- 知识库（可建多个）
|
||||
id, name, desc, source_dir, index_status, created_at
|
||||
|
||||
agent_kb_bindings -- Agent↔知识库 多对多（挂接配置）
|
||||
agent_id, kb_id, enabled
|
||||
|
||||
canvases -- 关系画布（模板）
|
||||
id, name, nodes(json:[{node_id, agent_id, enabled, x, y}]),
|
||||
edges(json:[{from_node, to_node, type:required|optional}])
|
||||
|
||||
campaigns -- 生产任务
|
||||
id, date_id, canvas_snapshot(json), task_spec(json),
|
||||
mindmap_ref, status, wave_state
|
||||
|
||||
segments -- 内容段（每段一个内容类型，同类可多个）
|
||||
id, campaign_id, node_id, agent_id, content_tag,
|
||||
anchor_card(json), artifact_path,
|
||||
status(pending|running|qc|human_review|approved|rework), version
|
||||
|
||||
qc_reports -- 质检报告
|
||||
id, segment_id, gate, checks(json), verdict
|
||||
|
||||
pending_memories -- 记忆待确认池
|
||||
id, target_agent_id, type(L2|L3|L4), content, source_ref,
|
||||
status(pending|approved|rejected|blocked)
|
||||
|
||||
memories -- 已确认记忆（per-agent 命名空间）
|
||||
id, agent_id, layer, content, source_ref, created_at, status
|
||||
|
||||
artifacts -- 组合产物
|
||||
id, campaign_id, docx_path, compose_report(json), final_status
|
||||
```
|
||||
|
||||
## 8. 技术选型（v3）
|
||||
|
||||
| 层 | 选型 | 说明 |
|
||||
|---|---|---|
|
||||
| 后端 | FastAPI (Python 3.14) | 异步并行调 Agent |
|
||||
| 数据库 | SQLite + SQLModel | 单机零运维 |
|
||||
| **画布** | **React Flow（MIT 免费）** | 拖拽节点/连线/启停开关，业界标准画布库 |
|
||||
| 前端 | React + Vite + Tailwind | 看板/画布/编辑器 |
|
||||
| Agent 引擎 | DeepSeek API（可配多 provider） | 复用你的密钥 |
|
||||
| 知识库 | 每库一个 SQLite FTS5 索引 + 文件目录 | 导入 md/docx/srt/txt/json，增量重建索引 |
|
||||
| 产物 | 文件系统 + 元数据 | docx 引擎复用六色标记逻辑 |
|
||||
|
||||
## 9. 里程碑（2 周，画布是重点）
|
||||
|
||||
| 阶段 | 内容 | 验收 |
|
||||
|---|---|---|
|
||||
| **M1（1-2天）** 骨架 | 后端骨架+数据表、知识库管理（建库+导入+检索）、Agent 注册中心（新建/规则/标签/挂接）、任务创建、主控拆解→顺序派发、3 个种子 Agent、结构质检 1 道、审查台基础、组合（简单拼接+docx） | 真实导图跑通全链路 |
|
||||
| **M2（3-6天）** 画布 | React Flow 画布（拖节点/连线/启停/模板/快照）、波次调度（拓扑排序）、锚点卡机制、全部种子 Agent、4 道质检 | 画布改顺序/停用一个 Agent 后重跑生效；段间锚点卡对齐 |
|
||||
| **M3（7-10天）** 记忆+组合 | 待确认池、L1-L4 记忆、组合一致性总检+缝合标记+组合报告、知识库增量导入、多段同类（3 技法并行） | 打回意见进池确认后注入；组合器抓到真实矛盾并打回；同类多段并行跑通 |
|
||||
| **M4（11-14天）** 打磨 | 导图 OCR 接入、多天连续、跨稿对账自动化、画布体验打磨、模板库 | 连续 3 天稿、跨稿 0 漏项 |
|
||||
|
||||
## 10. 风险与红线
|
||||
|
||||
1. 导图读不准的词必须列待确认清单问你（不变）
|
||||
2. 记忆只沉淀"怎么讲"不沉淀"讲什么"；且写入需你确认（不变）
|
||||
3. 质检报告逐条对证正文+锚点卡（防表面功夫）
|
||||
4. 组合器只拼装+总检+缝合标记，永不擅自改内容
|
||||
5. **画布快照**：任务开工后画布改动不影响已跑任务（避免跑一半乱了）
|
||||
6. **停用下游的连锁**：停用"产品销售"节点时，产品顾问/质检的产品检查自动跳过，组合报告注明"本场 0 产品"
|
||||
7. 知识库导入规模：SRT/docx 批量导入做后台任务+进度条；单库索引重建可后台跑
|
||||
8. 合规底线与防拒审信封（只进后台不进正文）
|
||||
|
||||
---
|
||||
|
||||
**待你确认（1 个问题）**：
|
||||
- 预置 11 个内容标签（开场/心法/案例/技法/功法/产品销售/画面/场景/收尾/钩子/互动）够用吗？还要加哪些？（比如"答疑/弹幕互动"要不要独立标签？）
|
||||
@@ -0,0 +1,297 @@
|
||||
# 雅文内容创造工作台 · 设计文档 v4（开放画布 + RAG 知识库）
|
||||
|
||||
> 日期：2026-08-25 ｜ 状态：方案确认稿 ｜ 技术路线：FastAPI + SQLite + React(React Flow) + **RAG 知识库**
|
||||
> v3 → v4 变更：① **内容标签扩充至 26 个**（6 大类，可自定义）② **知识库升级为 RAG 架构**：导入→解析→分块→向量化→语义检索→引用溯源，不再用纯关键词检索
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
开放的多 Agent 内容工厂（浏览器访问的独立 Web 工作台）：
|
||||
|
||||
- 你建 Agent（不限数量）→ 画布连线编排（顺序/依赖/单独启停）→ 每个 Agent 配规则、配**RAG 知识库挂接**
|
||||
- 每次生产：给主控主题/导图 → 拆解成内容段（每段一个内容标签，同类可多个）→ 按画布派发 → 质检 → 人工审查 → 组合交付（六色 docx）
|
||||
- **知识库 = RAG 建库**：素材拖进去，系统自动解析、分块、向量化，Agent 用语义检索取料，答案带引用溯源
|
||||
- 记忆沉淀必须你确认；段间靠锚点卡对齐；组合 Agent 做一致性总检
|
||||
- **每个 Agent 可独立选择模型**：主控/生产/质检/组合各配各的模型，画布节点上可见可换，任务成本按 Agent 记账
|
||||
|
||||
## 2. 内容标签体系（扩充版：26 个预置，6 大类）
|
||||
|
||||
主控拆导图时给每个节点标一个标签；Agent 声明擅长标签；标签可自定义新增。★=高频核心。
|
||||
|
||||
### 结构类（5）
|
||||
| 标签 | 定义 | 典型用法 |
|
||||
|---|---|---|
|
||||
| ★ 开场 | 扎心暖场/承诺钩子/开场降档 | 案例/悬念 30 秒入题，第一件产品尽量前置 |
|
||||
| 转场 | 段间衔接（话题自然滑入，禁报幕） | 组合器优先处理；也可由互动标记 Agent 预埋 |
|
||||
| ★ 收尾 | 信念收尾：最后 30 秒纯信念不卖货 | "所有的性感都不是天生的…"三段式金句 |
|
||||
| ★ 钩子 | 收口钩子=导图次日真实框架 | 技法名与导图一致，不写死待确认道具 |
|
||||
| 预告 | 中途预告/下一场承诺 | 只留一个带日期的承诺，其余"回头安排" |
|
||||
|
||||
### 内容类（8）
|
||||
| 标签 | 定义 | 典型用法 |
|
||||
|---|---|---|
|
||||
| ★ 心法 | 认知/心态/信念升级 | 概念有画面、论证有对照；金句只点缀不作产品引入 |
|
||||
| ★ 痛点 | 焦虑唤醒/扎心一刀/痛点直击 | "你干开门，门都没上润滑你硬推，不哭才怪" |
|
||||
| ★ 动机铺垫 | 讲解前先讲"为什么要听"（1-2 句动机+原理） | 每个知识点/技法前的"为什么"铺垫，压缩时不删 |
|
||||
| ★ 案例 | 学员案例/姐妹故事 | 一人分饰两角、具体到细节 |
|
||||
| 见证 | 产品见证/逆袭故事 | 卖货时的真实感来源（与案例区分开） |
|
||||
| 冷知识 | 身体冷知识/科学证据 | 射精阈值/前列腺位置/括约肌无天然润滑…必须准确 |
|
||||
| ★ 金句 | 金句收口/三段式金句 | 扎心话术收口干脆 |
|
||||
| 共鸣 | 情感共鸣/温柔引导型低声区 | 全稿低谷段，气息写、放慢、压低声 |
|
||||
|
||||
### 技法类（4）
|
||||
| 标签 | 定义 | 典型用法 |
|
||||
|---|---|---|
|
||||
| ★ 技法 | 外显手法：手活/口活/体位/步骤骨架 | 第一步…第二步…第三步+画面点，不展开细节 |
|
||||
| ★ 功法 | 内功练习：凯格尔/缩阴功/八爪鱼收紧术类 | 可跟练、有作业（今晚洗澡从第一个摸到第五个） |
|
||||
| ★ 跟练 | 现场跟练口令+互动指令 | "吸气收紧、呼气放松→公屏打'咬'" |
|
||||
| 安全提示 | SM/技法安全提示 | 低温蜡烛、拍肉厚处、安全词定义（玫瑰） |
|
||||
|
||||
### 产品类（3）
|
||||
| 标签 | 定义 | 典型用法 |
|
||||
|---|---|---|
|
||||
| ★ 产品销售 | 完整销售话术（痛点→价值→价格锚定→限量） | 一产品一概念不混谈；产品随动作进场 |
|
||||
| ★ 产品体验 | 产品体验感写作（拿起→第一下→扩散→伴侣反应→欲望结果） | 掌心揉热粉嫩油贴锁骨窝停三秒… |
|
||||
| 产品回指 | 后段产品回指（"老师前面那瓶油"） | 不二次完整销售 |
|
||||
|
||||
### 表现类（5）
|
||||
| 标签 | 定义 | 典型用法 |
|
||||
|---|---|---|
|
||||
| ★ 画面 | 画面感描写（色情小说档画面链） | 动作/对话/快感写到底；腿心/热意/颤/烫 |
|
||||
| ★ 场景 | 场景演绎：角色扮演/SM红房/水元素 | 环境/衣着/光线/气味/心理/动作过程 |
|
||||
| 情绪 | 情绪低谷/峰值铺垫/三连跳板 | 拍桌→"我只说一遍"→停顿三秒→开讲 |
|
||||
| 氛围 | 仪式感氛围（音乐/灯光/道具/舞美） | 灰字表演标记落实，不进正文说教 |
|
||||
| 互动 | 公屏互动（扣字/选择题/等弹幕） | "选择题→等弹幕→统计转折"真互动 |
|
||||
|
||||
### 辅助类（4）
|
||||
| 标签 | 定义 | 典型用法 |
|
||||
|---|---|---|
|
||||
| 答疑 | 弹幕答疑/常见问题 | 从原文库检索真实答疑话术 |
|
||||
| 双主播 | 男女主播互动 | 一唱一和、插科打诨 |
|
||||
| 毛边 | 直播毛边（自嘲/断句/笑场/闲聊） | 真人感低谷 |
|
||||
| 仪式 | 开营仪式/七天巡礼（引流课） | 无产品节点=0产品0红色 |
|
||||
|
||||
> 标签是开放体系：新建 Agent 时可自定义新标签；主控拆导图时如遇未知类型，列出来让你定标签。
|
||||
|
||||
### 2.1 标签管理（开放：随时自己添加）
|
||||
|
||||
| 操作 | 说明 |
|
||||
|---|---|
|
||||
| 新建标签 | 工作台【标签管理】页一键添加：名称+所属大类+一句话定义+典型用法；立即出现在 Agent 配置和主控拆解的选项里 |
|
||||
| 编辑/停用 | 改名/改定义/停用（停用后不再出现在选项里，历史任务数据保留） |
|
||||
| 分组 | 预置 6 大类可调整，也可自建新大类 |
|
||||
| 未知标签兜底 | 主控拆导图遇到不认识的内容块 → 列入待确认清单让你定标签（定一个立即生效，或归入"待分类"） |
|
||||
| 数据一致性 | 标签改名/删除时，历史任务的段标签显示旧名（快照），不影响历史数据 |
|
||||
|
||||
## 3. Agent 关系画布（同 v3，不变）
|
||||
|
||||
节点=Agent（启停开关/知识库挂接显示/**模型标识**）、连线=锚点卡流向、顺序=图拓扑、模板保存、任务快照。同一 Agent 可放多个节点（同类多段并行）。
|
||||
|
||||
## 4. 模型管理（每个 Agent 可选不同模型）🆕
|
||||
|
||||
### 4.1 模型注册（工作台设置页）
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| Provider 管理 | 添加任意 OpenAI 兼容 API：DeepSeek / 硅基流动 / 智谱 / Kimi / 通义 / 本地 Ollama…各配 base_url + API key + 模型列表，可同时挂多个 |
|
||||
| 全局默认模型 | 未单独配置的 Agent 用全局默认（初始=DeepSeek deepseek-chat，你的密钥） |
|
||||
| 连通性测试 | 设置页一键测试每个 provider：延迟、速度、可用模型刷新 |
|
||||
|
||||
### 4.2 每个 Agent 一个模型选择
|
||||
|
||||
- Agent 配置里【模型】下拉：从已注册模型里选，或"跟随全局默认"
|
||||
- 画布节点显示模型标识（如 🟦DeepSeek / 🟩GLM / 🟧Kimi），点开可快速切换
|
||||
- 同类型多节点（两个技法 Agent）可各用不同模型并行 → 现场对比文风，选出最像的
|
||||
- 任务快照固化模型选择：任务开工后改模型不影响已跑任务
|
||||
|
||||
### 4.3 推荐分工（初始建议，全部可改）
|
||||
|
||||
| 角色 | 推荐模型倾向 | 理由 |
|
||||
|---|---|---|
|
||||
| 主控 Agent | 强推理（DeepSeek-R1 类） | 导图解析/任务拆解/波次调度要准 |
|
||||
| 生产 Agent | 文风强、上下文长 | 心法/画面/场景类吃文风，按实际试跑选 |
|
||||
| 质检 Agent | 强推理+规则执行 | 五类审查要严格逐条对证 |
|
||||
| 组合 Agent | 长上下文（128K+） | 拼装全文+一致性总检要读全稿 |
|
||||
|
||||
### 4.4 成本与日志
|
||||
|
||||
- 任务页按 Agent 记录每次调用的模型 / 输入输出 token / 费用
|
||||
- 同一内容段换模型重跑的成本和效果可对比（A/B 看板）
|
||||
|
||||
## 5. RAG 知识库子系统（🆕 v4 核心）
|
||||
|
||||
### 5.1 建库管道（导入即建，全自动）
|
||||
|
||||
```
|
||||
素材文件（docx/srt/md/txt/json/导图）
|
||||
│ ① 导入（拖拽上传，后台任务+进度条）
|
||||
▼
|
||||
② 格式解析：docx 提取正文｜srt 去时间戳合并字幕｜md/txt 直读｜json 按结构抽取
|
||||
▼
|
||||
③ 清洗：去 BOM/空行/提词备注/表演标记归一；SRT 断句合并成完整语段
|
||||
▼
|
||||
④ 分块 Chunking：标题感知 + 语义边界（按段落/章节切），块大小 400-600 字，
|
||||
相邻块重叠 15%（保上下文连续）；每块带元数据 {库id, 文件, 章节, 序号}
|
||||
▼
|
||||
⑤ 向量化 Embedding：本地 BGE-M3 模型（中文强/多语种，离线可用）
|
||||
▼
|
||||
⑥ 入库：ChromaDB（嵌入式向量库，collection=知识库，天然隔离）
|
||||
▼
|
||||
⑦ 索引完成 → 检索测试页可即时验证命中质量
|
||||
```
|
||||
|
||||
### 5.2 检索（Agent 取料时）
|
||||
|
||||
```
|
||||
Agent 生成请求
|
||||
│ query 构造：任务切片 + 上游锚点卡 + Agent 规则里的检索意图
|
||||
▼
|
||||
混合检索（只在挂接的 collection 内查）
|
||||
├─ 向量检索：语义相似度 top-k（k=8，默认可配）
|
||||
└─ 关键词检索：BM25 精确命中 top-k（补专有名词：技法名/产品名/暗语）
|
||||
▼
|
||||
合并去重 → 可选重排（cross-encoder 或 LLM rerank，v4 后置开关）
|
||||
▼
|
||||
引用溯源：每条命中带 {库, 文件, 章节, 原文块, 相似度}
|
||||
→ 注入 Agent 上下文（后台可见来源标注，正文永远不出现"知识库里说"）
|
||||
```
|
||||
|
||||
### 5.3 隔离与挂接
|
||||
|
||||
- **每库一个 ChromaDB collection + 独立元数据命名空间**：库与库物理隔离，检索互不可见
|
||||
- Agent 挂接（多选）决定它检索哪些 collection；挂接外的一律查不到
|
||||
- 删除/更新文件：增量重分块重向量化，不影响其他文件
|
||||
|
||||
### 5.4 引用溯源防"表面功夫"
|
||||
|
||||
- Agent 产出的每条事实/案例/产品说法，后台记录引用来源（哪个库哪个块）
|
||||
- **质检 Agent 可一键核对**：选中一句 → 看它的引用 → 与知识库原文对证（防编造、防"报告≠事实"）
|
||||
- 检索测试页：你输入一句 query，看命中的原文块质量，随时检验库建得好不好
|
||||
|
||||
### 5.5 预置种子库（6 个，可增）
|
||||
|
||||
| 库 | 素材来源 | 分块要点 |
|
||||
|---|---|---|
|
||||
| 风格档案库 | 数字雅文档案/范稿/day1定稿基准/文本层铁律 | 规则型文档按章节分块 |
|
||||
| 训练营框架库 | 七天导图/28天重排版/历史任务单 | 按天/按节点分块 |
|
||||
| 直播原文库 | 73 场 SRT（573 万字） | 按场次→段落分块 |
|
||||
| 备稿库 | 99 篇 docx（150 万字） | 按稿→标题分块 |
|
||||
| 产品知识库 | 观品 chunks.jsonl | 按产品分块（content 去空格） |
|
||||
| 质检规则库 | 五类审查清单/词清单/铁律 | 按检查项分块 |
|
||||
|
||||
### 5.6 技术选型（RAG 部分）
|
||||
|
||||
| 组件 | 选型 | 理由 |
|
||||
|---|---|---|
|
||||
| 向量库 | ChromaDB（嵌入式） | 零运维、Python 原生、collection 隔离、metadata 过滤、Windows 免编译 |
|
||||
| Embedding | 本地 BGE-M3（sentence-transformers） | 中文语义强、离线可用（素材涉敏不外发）、768 维 |
|
||||
| 备选 Embedding | 硅基流动/智谱 embedding API | 若嫌本地模型占内存（约 1-2GB） |
|
||||
| 分块 | 自研解析器（python-docx/正则）+ 标题感知切分 | SRT/docx 格式各有专门处理 |
|
||||
| 重排（可选） | cross-encoder 或 LLM rerank | 命中质量不足时开启 |
|
||||
| 模型管理 | OpenAI 兼容多 Provider 注册 + 每 Agent 选模型 | DeepSeek/硅基/智谱/Kimi/Ollama 并存，按 Agent 切换 |
|
||||
| 规模预估 | 700 万字 ≈ 1.4 万块 × 768 维 | ChromaDB 无压力 |
|
||||
|
||||
## 6. 失败处理与人工介入（生成不出来 → 必提醒人工）🆕
|
||||
|
||||
### 6.1 失败分类与自动重试策略
|
||||
|
||||
| 失败类型 | 例子 | 策略 |
|
||||
|---|---|---|
|
||||
| 瞬时错误 | API 超时 / 429 限流 / 连接中断 | 自动重试 2 次（指数退避），可配置 |
|
||||
| 内容拒绝 | 模型拒审："抱歉，我无法生成…"（检测拒绝特征词） | 自动换措辞重试 1 次；仍拒绝 → **转人工**（不无限自动折腾） |
|
||||
| 空输出/截断 | 输出为空 / 中途截断 / 结构解析失败 | 重试 1 次；仍失败 → 转人工 |
|
||||
| 模型/Key 错误 | key 失效 / 模型不存在 / 余额不足 | **直接转人工**（重试无意义） |
|
||||
| RAG 失败 | 检索接口报错 | 重试 1 次 → 转人工；无命中不算失败，但标"低置信"提示 |
|
||||
|
||||
**原则：重试只覆盖瞬时问题；凡是"重试解决不了"的失败，一律转人工，绝不静默跳过、绝不假装成功。**
|
||||
|
||||
### 6.2 失败提醒与人工介入台
|
||||
|
||||
- 节点状态变 **🔴 失败**，任务看板红标 + 通知中心提醒（待处理失败数）
|
||||
- 点击进入【失败处理面板】，能看到：
|
||||
- 哪个 Agent / 哪个节点 / 用的哪个模型 / 失败类型与错误原文
|
||||
- 重试次数与调用日志（时间/模型/token/耗时）
|
||||
- 失败时的输入上下文（任务切片 + 上游锚点卡 + 规则摘要）
|
||||
- 人工修复动作（按钮式）：
|
||||
- 🔁 重试
|
||||
- 🔄 换模型重跑（该 Agent 换另一个已注册模型）
|
||||
- 📝 改规则重跑（打开 rules.md 编辑 → 保存即重跑）
|
||||
- ✂️ 调整任务切片重跑（如导图段描述触发拒审，改写描述）
|
||||
- ⏭️ 跳过该段（组合时注明"本场缺段"）
|
||||
- ⏸️ 停用该节点
|
||||
- **修复后记录原因**：人工在面板填一句"为什么失败/怎么修好的" → 生成记忆建议 → 进待确认池 → 确认后沉淀进该 Agent 记忆（如"该模型对 XX 内容拒审，换 YY 模型可过"）
|
||||
- 失败不阻塞其他段：一段失败时其他段照常跑，但任务整体保持"⚠️ 有待处理失败"状态，直到人工处理完
|
||||
|
||||
## 7. 状态可视化（每个 Agent 工作状态清晰可见）🆕
|
||||
|
||||
### 7.1 节点状态机（画布/看板统一）
|
||||
|
||||
```
|
||||
待派发(灰) → 生成中(蓝，显示模型+已耗时) → 质检中(黄，显示第几道)
|
||||
→ 待人工审查(紫) → 已通过(绿)
|
||||
→ 打回重做(橙，显示第几轮)
|
||||
→ ⚠️ 失败(红，点击看原因)
|
||||
→ 停用(暗) / 跳过(灰斜线，上游停用导致)
|
||||
```
|
||||
|
||||
### 7.2 三处可见
|
||||
|
||||
| 位置 | 显示什么 |
|
||||
|---|---|
|
||||
| 画布节点 | 实时状态色 + 模型标识 + 当前轮次；点开=详情抽屉 |
|
||||
| 任务看板 | 每段一行：状态徽章/模型/耗时/轮次/成本；失败红标置顶 |
|
||||
| 详情抽屉 | 调用日志流（每次 LLM 调用：时间/模型/token/耗时/错误）、质检报告、锚点卡、产物全文、当前输入上下文 |
|
||||
|
||||
### 7.3 配套
|
||||
|
||||
- **运行日志流**：任务执行时实时滚动（谁在跑/谁在等/谁失败了），可暂停过滤
|
||||
- **通知中心**：失败提醒 / 待确认清单 / 记忆待确认 / 待分类标签，统一小红点
|
||||
- **成本面板**：按 Agent × 模型统计 token 与费用
|
||||
- 状态全部落库（llm_calls 调用日志表 + segments 状态字段），历史可回看
|
||||
|
||||
## 8. 系统架构总览（v4）
|
||||
|
||||
```
|
||||
┌─────────────── 你（浏览器） ───────────────────────────────┐
|
||||
│ 任务看板 · Agent注册中心 · 关系画布 · 知识库管理(RAG) · 审查台 · 记忆 │
|
||||
└──────┬─────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌───────────────────────────────────────────────────────────┐
|
||||
│ Agent 注册中心：{类型|内容标签(26选多)|知识库挂接(多选)| │
|
||||
│ 模型选择 | rules.md(版本) | 独立记忆库} │
|
||||
└──────────────┬────────────────────────────────────────────┘
|
||||
▼
|
||||
┌───────────────────────────────────────────────────────────┐
|
||||
│ Agent 关系画布：节点=Agent(启停) 边=锚点卡流向 模板/快照 │
|
||||
└──────────────┬────────────────────────────────────────────┘
|
||||
▼ 按拓扑分波次
|
||||
┌──────────────┴────────────────────────────────────────────┐
|
||||
│ [生产Agent] ⇄ RAG检索(只查挂接库,带引用溯源) │
|
||||
│ 产出：段内容+锚点卡 │
|
||||
│ → 4道质检(报告对证正文+锚点卡+引用) → 人工审查(硬关卡) │
|
||||
│ → 组合Agent(拼装+一致性总检+缝合标记) → 六色docx │
|
||||
└───────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 9. 里程碑（v4 更新）
|
||||
|
||||
| 阶段 | 内容 | 验收 |
|
||||
|---|---|---|
|
||||
| **M1（1-3天）** 骨架+知识库管道 | 后端骨架+数据表、Agent 注册中心、**标签管理页**（新建/停用/分组，随时自加）、**模型管理（多 Provider 注册+每 Agent 选模型）**、**状态与失败机制**（节点状态机+调用日志表+失败转人工+通知中心）、**RAG 管道（导入→解析→分块→BGE-M3 向量化→ChromaDB 入库→检索测试页）**、种子库导入（产品库 chunks.jsonl + 风格档案先行）、主控拆解→顺序派发、3 个种子 Agent、结构质检、审查台基础、组合（拼接+docx） | 导图跑通全链路；检索测试页验证产品库/风格库命中质量；两个生产 Agent 用不同模型各跑一段对比文风；你亲手加一个新标签并立刻能用；**故意填错 key 制造一次失败 → 看板红标+通知提醒 → 修复重跑成功** |
|
||||
| **M2（4-7天）** 画布 | React Flow 画布（拖节点/连线/启停/模板/快照）、波次调度、锚点卡机制、全部种子 Agent、4 道质检 | 画布改序/停用生效；锚点卡对齐；SRT 原文库导入完成 |
|
||||
| **M3（8-11天）** 记忆+引用 | 待确认池、L1-L4 记忆、组合一致性总检+组合报告、**引用溯源核对（质检一键对证）**、备稿库导入、同类多段并行 | 打回意见确认后注入；组合器抓真实矛盾；引用核对 1 次实操 |
|
||||
| **M4（12-14天）** 打磨 | 导图 OCR、多天连续、跨稿对账自动化、rerank 开关、画布体验、模板库 | 连续 3 天稿、跨稿 0 漏项 |
|
||||
|
||||
## 10. 风险与红线（v4 增量）
|
||||
|
||||
1. **Embedding 隐私**：素材涉敏（成人内容），默认本地 BGE-M3 离线向量化，数据不出本机；用 API embedding 是显式可选
|
||||
2. **分块质量**：SRT 字幕断句合并是关键（按时间戳间隙+语义完整句切），分块错误会在检索测试页暴露，可手动调整块大小参数
|
||||
3. **引用防编造**：Agent 引用必须带来源块，质检核对；查无来源的"事实"= FAIL
|
||||
4. **失败不静默**：任何"重试解决不了"的失败必须转人工提醒，绝不自动跳过/假装成功；人工修复原因沉淀进记忆（防同类失败反复）
|
||||
5. 其余红线不变：导图待确认清单、口径不沉淀、质检报告对证正文、组合器不擅改内容、画布快照、停用连锁
|
||||
|
||||
---
|
||||
|
||||
**待确认（1 个问题）**：
|
||||
- 26 个预置标签里，★核心 13 个之外的可选标签（转场/预告/见证/冷知识/共鸣/安全提示/产品回指/情绪/氛围/答疑/双主播/毛边/仪式）需要保留哪些？还是全部预置（可以停用不显示）？
|
||||
+559
@@ -0,0 +1,559 @@
|
||||
# 雅文内容创造工作台 · 系统设计文档 v5
|
||||
|
||||
> 文档日期：2026-08-26
|
||||
> 文档状态：当前实现说明与运行设计
|
||||
> 项目定位：企业级多 Agent 内容生产、知识检索、质量审查与成稿交付工作台
|
||||
> 技术栈：FastAPI + SQLModel + SQLite + ChromaDB/本地向量兜底 + React + Vite + React Flow
|
||||
> 云化扩展：[v6 用户端、管理端与云化设计](./设计文档v6-用户端管理端云化与计费设计.md)
|
||||
|
||||
## 0. 文档范围
|
||||
|
||||
本文件描述当前工作台的实际架构和已落地行为，包含：
|
||||
|
||||
- Agent Runtime：会话、工具调用、审批、恢复、护栏和事件追踪。
|
||||
- Agent 画布：多节点、连线、拓扑调度、融合 Agent 和运行快照。
|
||||
- 内容生产链路：导图解析、内容段生成、四道质检、人工审查和组合成稿。
|
||||
- 知识库：文件导入、分类树、AI 分类建议、人工确认、RAG 检索、消费锁定和可回滚重建。
|
||||
- 模型管理：Provider、模型发现、连通性测试、Agent 独立模型和配置快照。
|
||||
- 认证与 RBAC：本地用户、PBKDF2 密码摘要、可撤销 Bearer Session 和角色权限。
|
||||
- LLM Trace：调用、Span、Agent 会话、工具事件、QC 报告和成稿产物的统一关联。
|
||||
- 前端信息架构、运维启动、备份恢复、测试和当前验收证据。
|
||||
|
||||
文中“已实现”表示源码已经存在并通过本地验证；“后续增强”只表示可选演进方向，不作为当前功能承诺。
|
||||
|
||||
## 1. 设计目标与边界
|
||||
|
||||
### 1.1 设计目标
|
||||
|
||||
1. 让内容生产从“手工复制粘贴”变成可追踪的 Agent 协作流程。
|
||||
2. 让每个 Agent 的规则、技能、知识库、记忆和模型选择可配置，同时在任务开始时冻结，保证任务可复现。
|
||||
3. 让知识引用可回溯，禁止生产 Agent 在没有知识材料时把推测写成事实。
|
||||
4. 让失败、人工审查、工具审批和服务重启都能恢复，不产生静默成功。
|
||||
5. 让管理员可以控制成员访问范围，并能从 Trace 还原一次任务的完整运行过程。
|
||||
|
||||
### 1.2 系统边界
|
||||
|
||||
- 当前部署是本地或内网单工作区服务，不依赖独立微服务集群。
|
||||
- API 服务监听 `127.0.0.1:8010`，React 开发服务器监听 `127.0.0.1:5173`。
|
||||
- SQLite 保存业务数据、账号和运行状态；源文件保存在知识库目录；向量保存于 ChromaDB 和本地兜底文件。
|
||||
- 模型调用使用已配置的 OpenAI 兼容 Provider；API Key 不写入运行快照，也不出现在前端日志中。
|
||||
|
||||
## 2. 总体架构
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U[工作台用户] --> WEB[React + Vite 前端]
|
||||
WEB --> API[FastAPI API]
|
||||
API --> AUTH[认证与 RBAC]
|
||||
API --> ORCH[任务编排器]
|
||||
ORCH --> RUN[CampaignRun 检查点]
|
||||
ORCH --> RT[Agent Runtime]
|
||||
RT --> LLM[Provider / LLM]
|
||||
RT --> EVT[RunEvent + LLMCall]
|
||||
ORCH --> QC[QC 四道质检]
|
||||
ORCH --> COMP[Composer 组合器]
|
||||
API --> RAG[RAG 管道]
|
||||
RAG --> FILES[知识库源文件]
|
||||
RAG --> VEC[ChromaDB]
|
||||
RAG --> FALLBACK[本地原子 JSON 向量兜底]
|
||||
API --> DB[(SQLite / SQLModel)]
|
||||
QC --> DB
|
||||
COMP --> ART[Markdown / DOCX 产物]
|
||||
RT --> DB
|
||||
```
|
||||
|
||||
### 2.1 运行时分层
|
||||
|
||||
| 层 | 主要职责 | 代码位置 |
|
||||
| --- | --- | --- |
|
||||
| Web UI | 页面、表单、画布、任务审查、Trace 浏览 | `web/src/App.tsx`、`web/src/CanvasPage.tsx` |
|
||||
| API | 鉴权、资源 CRUD、任务控制、文件上传、下载预览 | `server/app/main.py` |
|
||||
| 编排层 | 画布拓扑、内容段派发、质检、组合、跨段锚点 | `server/app/agents/runner.py`、`coordinator.py` |
|
||||
| Runtime | LLM 多轮、工具协议、审批、恢复、输入输出护栏 | `server/app/agents/runtime.py` |
|
||||
| 知识层 | 解析、分块、Embedding、向量检索、引用、消费记录 | `server/app/rag/` |
|
||||
| 持久化层 | SQLite 表、幂等迁移、索引和启动恢复 | `server/app/models.py`、`db.py` |
|
||||
|
||||
## 3. 核心业务流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant UI as 前端
|
||||
participant API as FastAPI
|
||||
participant Run as CampaignRun
|
||||
participant Runtime as Agent Runtime
|
||||
participant KB as RAG 知识库
|
||||
participant QC as QC
|
||||
participant Composer as 组合 Agent
|
||||
|
||||
User->>UI: 创建内容任务并填写导图
|
||||
UI->>API: POST /api/campaigns
|
||||
API->>Run: 冻结画布、Agent、技能、模型和知识库配置
|
||||
User->>UI: 执行导图解析
|
||||
UI->>API: POST /api/campaigns/{id}/parse
|
||||
API->>Runtime: 启动 coordinator 会话
|
||||
Runtime->>KB: 读取任务所需资料和上游上下文
|
||||
Runtime-->>API: 生成内容段任务单与锚点约束
|
||||
User->>UI: 启动任务
|
||||
UI->>API: POST /api/campaigns/{id}/run
|
||||
API->>Run: 写入 queued/running 检查点
|
||||
API->>Runtime: 按画布波次并行派发
|
||||
Runtime->>KB: 只检索挂接库，预留并消费片段
|
||||
Runtime-->>API: 返回正文和锚点卡
|
||||
API->>QC: 执行结构、内容、风格、跨段质检
|
||||
QC-->>API: PASS/FAIL 与检查项
|
||||
User->>UI: 人工审查、通过或打回
|
||||
UI->>API: POST /api/segments/{id}/review
|
||||
User->>UI: 组合交付
|
||||
UI->>API: POST /api/campaigns/{id}/compose
|
||||
API->>Composer: 只读取已人工通过内容段
|
||||
Composer-->>API: 组合报告和 Markdown/DOCX 产物
|
||||
```
|
||||
|
||||
### 3.1 任务状态
|
||||
|
||||
`Campaign.status`：
|
||||
|
||||
| 状态 | 含义 |
|
||||
| --- | --- |
|
||||
| `draft` | 已创建，尚未解析 |
|
||||
| `parsing` | 正在将导图转为任务段 |
|
||||
| `parsed` | 已生成任务段，等待执行 |
|
||||
| `running` | Agent 正在生成 |
|
||||
| `qc` | 正在质检 |
|
||||
| `human_review` | 等待人工审查 |
|
||||
| `composing` | 正在组合最终稿 |
|
||||
| `done` | 组合完成并可预览/下载 |
|
||||
| `failed` | 存在未处理的失败 |
|
||||
|
||||
`CampaignRun.status` 负责一次具体执行：`queued`、`running`、`awaiting_review`、`completed`、`failed`、`cancelled`。任务重跑会创建新的 Run，旧 Run 的 Trace 和检查点仍保留。
|
||||
|
||||
## 4. Agent Runtime 设计
|
||||
|
||||
### 4.1 RuntimeContext
|
||||
|
||||
每个会话使用 `RuntimeContext`，包含数据库会话、Run/Campaign/Segment 标识、当前 Agent、Provider、模型、Trace ID 和取消检查器。模型、工具和事件都从该上下文取得，避免在业务代码中散落全局状态。
|
||||
|
||||
### 4.2 会话与恢复
|
||||
|
||||
`AgentSession` 持久化以下内容：
|
||||
|
||||
- `run_id`、`campaign_id`、`segment_id`、`agent_id`、`agent_name`。
|
||||
- `phase`：`coordinator`、`production`、`qc`、`composer`、`handoff`。
|
||||
- `status`：`running`、`waiting_approval`、`interrupted`、`completed`、`failed`、`cancelled`。
|
||||
- 当前轮次、最大轮次、消息上下文、工具状态、最终输出和错误。
|
||||
- `trace_id`、父会话 ID、时间戳。
|
||||
|
||||
服务启动时会把中断的运行标记为可恢复状态；`resume` 会复用未完成会话，而不会重复创建同一阶段的成功结果。消息会保留系统规则和最近上下文，超过上限时裁剪旧上下文。
|
||||
|
||||
### 4.3 工具协议与审批
|
||||
|
||||
工具通过 `RuntimeTool` 注册，包含名称、描述、JSON Schema、处理器和 `requires_approval` 标记。调用过程为：
|
||||
|
||||
1. Runtime 记录 `tool_started`。
|
||||
2. 解析 JSON 参数并执行授权处理器。
|
||||
3. 记录 `tool_finished`，把结果以 `tool` 消息回传给模型。
|
||||
4. 需要人工审批时保存 `pending_tool`，会话进入 `waiting_approval`。
|
||||
5. 管理员或审查者通过 `/api/agent-sessions/{session_id}/tool-approval` 批准/拒绝，随后调用 `/api/runs/{run_id}/resume` 继续。
|
||||
|
||||
Provider 不支持 tools 时，Runtime 自动退化为单轮最终输出；这只改变调用方式，不改变会话、Trace 和护栏记录。
|
||||
|
||||
### 4.4 护栏
|
||||
|
||||
- 输入护栏：拒绝空任务；用户输入超过 100,000 字时终止本会话。
|
||||
- 输出护栏：拒绝空输出；模型输出超过 120,000 字时标记失败。
|
||||
- 工具护栏：未注册工具直接返回“未授权工具”；参数必须是 JSON 对象。
|
||||
- 运行护栏：每个 Agent 默认最多 6 轮；收到取消请求后写入 `cancelled`。
|
||||
- 指令边界：知识库、工具和上游文本以数据注入，不得覆盖 Runtime 系统规则。
|
||||
|
||||
## 5. Agent 画布与组合配置
|
||||
|
||||
### 5.1 画布模型
|
||||
|
||||
`Canvas.nodes` 保存节点 ID、Agent ID 和启用状态；`Canvas.edges` 保存 `from_node` 到 `to_node` 的依赖关系。连线表示下游 Agent 可以读取上游锚点卡，画布不连线的节点保持上下文隔离。
|
||||
|
||||
支持：
|
||||
|
||||
- 同一个 Agent 放置多个节点，用于同类内容并行或串行。
|
||||
- 节点启用/停用；停用节点不会被派发，下游收到跳过状态。
|
||||
- 通过拓扑排序生成波次；同一波次可并行执行。
|
||||
- 在任务创建时冻结画布和 Agent 配置，后续改画布不会影响已创建任务。
|
||||
- Agent 可配置 `fusion_agent_ids`，由融合生产逻辑把多种写法合并成一个自然段。
|
||||
|
||||
### 5.2 组合约束
|
||||
|
||||
组合 Agent 只读取已通过人工审查的段落，并检查：
|
||||
|
||||
1. 结构是否完整。
|
||||
2. 时间线、概念和产品回指是否一致。
|
||||
3. 段间锚点是否兑现。
|
||||
4. 情绪曲线与语气是否连续。
|
||||
5. 成稿是否满足交付格式和文本样式规则。
|
||||
|
||||
生产 Agent 的默认正文规则是大白话、自然口语、正文一段到底；表演提示可以使用括号内联。锚点卡以结构化 JSON 保存，不直接暴露内部推理。
|
||||
|
||||
## 6. 配置快照与可复现运行
|
||||
|
||||
### 6.1 快照内容
|
||||
|
||||
`server/app/agents/snapshot.py` 负责冻结：
|
||||
|
||||
- Agent ID、名称、角色、规则内容、规则版本和规则哈希。
|
||||
- 已挂接知识库 ID、技能版本与技能指令。
|
||||
- Agent 使用的 Provider、模型名称和 Provider 指纹。
|
||||
- 记忆、融合 Agent 和阶段角色配置。
|
||||
|
||||
快照不包含 API Key。Provider 指纹包括名称、Base URL、模型和启用状态；运行期间指纹变化会被识别，防止“任务显示旧模型、实际调用新模型”。
|
||||
|
||||
### 6.2 写入位置
|
||||
|
||||
| 数据 | 快照字段 |
|
||||
| --- | --- |
|
||||
| 任务运行 | `CampaignRun.config_snapshot` |
|
||||
| 内容段 | `Segment.runtime_snapshot` |
|
||||
| 质检报告 | `QCReport.runtime_snapshot`、`run_id`、`trace_id` |
|
||||
| 最终产物 | `Artifact.runtime_snapshot`、`run_id`、`trace_id` |
|
||||
|
||||
## 7. 知识库与 RAG
|
||||
|
||||
### 7.1 数据结构
|
||||
|
||||
- `KnowledgeBase`：库名称、源目录、文件数量、分块数量和索引状态。
|
||||
- `KnowledgeFile`：文件名、内容哈希、修订号、分类、AI 分类建议、置信度、分类状态。
|
||||
- `KnowledgeCategory`：支持无限层级的 `parent_id` 分类树。
|
||||
- `KnowledgeUsage`：记录某个 Agent 是否已经预留/消费某个 chunk。
|
||||
|
||||
分类状态：`unclassified`、`ai_suggested`、`human_confirmed`。人工可以新建、修改、删除分类，也可以把文件移动到其他分类；向量元数据会写入完整分类路径。
|
||||
|
||||
### 7.2 导入与重建
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[docx/srt/md/txt/json/jsonl] --> B[复制到 KB 源目录]
|
||||
B --> C[格式解析]
|
||||
C --> D[清洗与语义分块]
|
||||
D --> E[Embedding]
|
||||
E --> F[写本地兜底向量文件]
|
||||
F --> G[尝试写 Chroma collection]
|
||||
G --> H[更新 chunk_count 与 ready]
|
||||
```
|
||||
|
||||
- 支持格式：`.docx`、`.srt`、`.md`、`.txt`、`.json`、`.jsonl`。
|
||||
- SRT 使用约 2,200 字目标窗口，避免把连续字幕拆成过多碎片；其他格式使用通用分块目标。
|
||||
- Embedding 使用本地模型，批量大小为 64。
|
||||
- 每个知识库拥有独立 collection，文件更新前先删除该文件的旧向量。
|
||||
- 重建按文件写入，每个文件都是一个可观察进度点。
|
||||
|
||||
### 7.3 只允许使用知识库内容
|
||||
|
||||
生产 Agent 的检索范围由 `Agent.kb_ids` 决定，只查询已挂接知识库。检索结果会写入引用列表和消费记录；同一个 Agent 对同一个 chunk 处于 `reserved` 或 `consumed` 时，后续检索会排除它。其他 Agent 的消费记录互不影响。
|
||||
|
||||
人工可以通过释放接口把某条使用记录恢复为可用状态。若进程在模型请求中断，启动恢复会把未完成的 `reserved` 记录归还为 `available`。
|
||||
|
||||
### 7.4 KB3 当前基线
|
||||
|
||||
截至 2026-08-26：
|
||||
|
||||
- 文件数：73。
|
||||
- 分块数：2,717。
|
||||
- 数据库状态：`ready`。
|
||||
- 本地兜底索引：2,717 条，向量维度 512。
|
||||
- 独立 Python 进程读取和相似度检索均通过。
|
||||
|
||||
ChromaDB 在 Windows 上可能出现只写入 HNSW 元数据的半成品索引，因此系统优先读取原子替换的 `server/data/vector_fallback/kb_3.json`。Chroma 写入失败不会阻断本地检索。
|
||||
|
||||
### 7.5 重建回滚
|
||||
|
||||
重建开始前导出当前向量快照；重建过程任一文件解析、Embedding 或写入失败时，恢复原向量和数据库计数。只有成功完成全部文件后才写 `ready`。KB3 重建使用的数据库备份为：
|
||||
|
||||
`server/data/backups/workspace-before-kb3-rebuild-20260826-193733.db`
|
||||
|
||||
SHA256：`D35F7F43B533E3DF0EC4F1EB6C659558CABEE36DDF6A3E48359329A31EAA0084`
|
||||
|
||||
## 8. 模型管理
|
||||
|
||||
### 8.1 Provider
|
||||
|
||||
`ModelProvider` 保存名称、Base URL、模型列表、默认模型、启用状态和本地 API Key。API 支持：
|
||||
|
||||
- 新增、修改、删除 Provider。
|
||||
- 调用 OpenAI 兼容的 `/models` 自动发现模型。
|
||||
- 测试 Provider 连通性。
|
||||
- 刷新 Provider 模型列表。
|
||||
- 设置全局默认模型。
|
||||
|
||||
### 8.2 Agent 模型选择
|
||||
|
||||
Agent 可以绑定独立的 `model_provider_id + model_name`；为空时跟随全局默认。任务创建时将实际 Provider 和模型写入快照，避免运行中途修改模型导致同一任务行为漂移。
|
||||
|
||||
## 9. 认证与 RBAC
|
||||
|
||||
### 9.1 首次启动
|
||||
|
||||
没有账号时，`GET /api/auth/status` 返回 `bootstrap_required=true`。前端显示“初始化管理员账号”，由用户自己创建第一个管理员账号；系统不内置默认密码。
|
||||
|
||||
### 9.2 安全实现
|
||||
|
||||
- 用户名限制为 3–48 个字符，只允许字母、数字、点、下划线和连字符。
|
||||
- 密码长度 10–256 个字符。
|
||||
- PBKDF2-SHA256，240,000 轮，随机 16 字节盐。
|
||||
- Session 使用随机不透明 Token；数据库只保存 Token SHA-256 摘要。
|
||||
- Session 默认 12 小时有效，可撤销；账号停用后立即失效。
|
||||
- CORS 允许 `Authorization` 请求头。
|
||||
|
||||
### 9.3 角色权限
|
||||
|
||||
| 角色 | 权限 |
|
||||
| --- | --- |
|
||||
| `admin` | 全部权限；成员、Provider、Agent、标签、技能、知识库、任务和审查管理 |
|
||||
| `editor` | 读取资源、修改内容配置、运行任务、处理审查和失败 |
|
||||
| `reviewer` | 读取资源、人工审查、读取审计 Trace |
|
||||
| `viewer` | 只读工作台和资源 |
|
||||
|
||||
未知写接口默认收敛到 `config:write`，防止新增 API 遗漏保护。系统始终保留至少一个启用中的管理员，当前登录管理员不能停用自己。
|
||||
|
||||
## 10. LLM Trace 与可观测性
|
||||
|
||||
### 10.1 Trace 关联
|
||||
|
||||
一次任务运行拥有一个 `trace_id`，关联：
|
||||
|
||||
- `CampaignRun`：运行状态、检查点和完整配置快照。
|
||||
- `LLMCall`：Provider、模型、尝试次数、Prompt/Output 哈希、Token、耗时、错误。
|
||||
- `AgentSession`：阶段、轮次、工具状态、会话结果。
|
||||
- `RunEvent`：模型、工具、护栏、审批、任务和段完成事件。
|
||||
- `QCReport`、`Artifact`：质检结果、组合产物和运行快照。
|
||||
|
||||
每个模型或工具事件拥有 `span_id`；工具事件可通过 `parent_span_id` 关联到触发它的模型请求。
|
||||
|
||||
### 10.2 API 与前端
|
||||
|
||||
| API | 用途 |
|
||||
| --- | --- |
|
||||
| `GET /api/llm_calls` | 按 Campaign、Trace、状态筛选模型调用 |
|
||||
| `GET /api/traces` | Trace 汇总：调用数、错误数、Token、耗时、Agent 数 |
|
||||
| `GET /api/traces/{trace_id}` | 查看运行快照、调用、会话、事件、QC 和产物 |
|
||||
| `GET /api/notifications` | 查看失败、待审查和待确认提醒 |
|
||||
|
||||
前端“日志与通知”页面提供 Trace 列表、状态筛选和详情回放。审查任务页面提供当前运行的会话、事件和工具审批状态。
|
||||
|
||||
## 11. 数据模型总览
|
||||
|
||||
| 表 | 作用 | 关键关联 |
|
||||
| --- | --- | --- |
|
||||
| `Agent` | Agent 规则、角色、标签、知识库、模型 | `AgentSkillBinding`、`Memory` |
|
||||
| `AgentSkill` | 可复用技能指令 | `AgentSkillBinding` |
|
||||
| `ContentTag` | 内容类型和分类 | Agent 与 Segment JSON 字段 |
|
||||
| `Canvas` | 画布节点和连线 | Agent |
|
||||
| `Campaign` | 内容任务和画布快照 | Segment、CampaignRun |
|
||||
| `Segment` | 单个内容段、锚点、引用、状态 | Campaign、Agent、QCReport |
|
||||
| `CampaignRun` | 一次可恢复运行 | Campaign、Trace |
|
||||
| `AgentSession` | Agent Runtime 会话 | Run、Segment、Agent |
|
||||
| `RunEvent` | Runtime、工具和任务事件 | Run、Trace |
|
||||
| `LLMCall` | 模型调用账本 | Run、Trace、Agent |
|
||||
| `KnowledgeBase` | 知识库索引状态 | KnowledgeFile、Category |
|
||||
| `KnowledgeFile` | 文件归属和分类审核 | KnowledgeBase、Category |
|
||||
| `KnowledgeUsage` | Agent 级 chunk 消费锁 | Agent、KnowledgeBase |
|
||||
| `PendingMemory` | 待人工确认记忆 | target Agent |
|
||||
| `Memory` | 已确认 Agent 记忆 | Agent |
|
||||
| `Artifact` | 组合报告和 DOCX 路径 | Campaign、Run、Trace |
|
||||
| `AppUser` | 本地账号和角色 | AuthSession |
|
||||
| `AuthSession` | 可撤销 Token 哈希 | AppUser |
|
||||
|
||||
数据库启动初始化会执行幂等迁移和索引创建，包括 Trace 索引、AgentSession 查询索引、同 Agent 同 chunk 唯一索引和同一 Campaign 活跃 Run 唯一索引。
|
||||
|
||||
## 12. API 资源分组
|
||||
|
||||
### 12.1 认证
|
||||
|
||||
```text
|
||||
GET /api/auth/status
|
||||
POST /api/auth/bootstrap
|
||||
POST /api/auth/login
|
||||
POST /api/auth/logout
|
||||
GET /api/auth/me
|
||||
GET /api/auth/users
|
||||
POST /api/auth/users
|
||||
PUT /api/auth/users/{user_id}
|
||||
POST /api/auth/users/{user_id}/reset-password
|
||||
```
|
||||
|
||||
### 12.2 配置资源
|
||||
|
||||
```text
|
||||
GET/POST/PUT/DELETE /api/tags
|
||||
GET/POST/PUT/DELETE /api/agents
|
||||
GET/POST/PUT/DELETE /api/skills
|
||||
GET/POST/PUT/DELETE /api/providers
|
||||
POST /api/providers/discover-models
|
||||
POST /api/providers/{id}/test
|
||||
POST /api/providers/{id}/refresh-models
|
||||
GET/PUT /api/settings/model-default
|
||||
GET/POST/PUT/DELETE /api/canvases
|
||||
```
|
||||
|
||||
### 12.3 知识库
|
||||
|
||||
```text
|
||||
GET/POST/PUT/DELETE /api/kbs
|
||||
POST /api/kbs/{id}/import
|
||||
POST /api/kbs/{id}/rebuild
|
||||
GET /api/kbs/{id}/search
|
||||
POST /api/kbs/search
|
||||
GET /api/kbs/{id}/files/{filename}
|
||||
POST/PUT/DELETE /api/kbs/{id}/categories
|
||||
PUT /api/kbs/{id}/files/{filename}/category
|
||||
POST /api/kbs/{id}/files/{filename}/classification/confirm
|
||||
POST /api/kbs/{id}/classify
|
||||
GET /api/kbs/{id}/usage
|
||||
POST /api/kb-usages/{usage_id}/release
|
||||
```
|
||||
|
||||
### 12.4 任务与交付
|
||||
|
||||
```text
|
||||
GET/POST /api/campaigns
|
||||
POST /api/campaigns/{id}/parse
|
||||
POST /api/campaigns/{id}/run
|
||||
GET /api/campaigns/{id}/runs
|
||||
GET /api/runs/{id}
|
||||
POST /api/runs/{id}/cancel
|
||||
POST /api/runs/{id}/resume
|
||||
GET /api/agent-sessions/{id}
|
||||
POST /api/agent-sessions/{id}/tool-approval
|
||||
POST /api/segments/{id}/review
|
||||
POST /api/segments/{id}/fix
|
||||
POST /api/campaigns/{id}/compose
|
||||
GET /api/artifacts/{id}/preview
|
||||
GET /api/artifacts/{id}/download
|
||||
```
|
||||
|
||||
### 12.5 常见错误
|
||||
|
||||
| 状态码 | 场景 |
|
||||
| --- | --- |
|
||||
| `400` | 参数不合法、状态不允许或分类/画布引用无效 |
|
||||
| `401` | 缺少、过期、撤销或无效 Token |
|
||||
| `403` | 角色没有对应权限 |
|
||||
| `404` | 资源或 Trace 不存在 |
|
||||
| `409` | 同一任务已有活跃 Run、用户名重复或并发消费冲突 |
|
||||
| `500` | Provider、解析器、向量库或文件系统异常；错误会记录到 Run/Trace |
|
||||
|
||||
## 13. 前端信息架构
|
||||
|
||||
当前工作台导航分为：
|
||||
|
||||
- 工作台：总览、任务看板。
|
||||
- 智能生产：Agent 画布、Agent 管理、技能库。
|
||||
- 资产中心：知识库、标签管理、模型管理。
|
||||
- 系统：日志与通知、记忆库、访问控制（仅管理员）。
|
||||
|
||||
关键用户路径：
|
||||
|
||||
1. 首次访问：初始化管理员或登录。
|
||||
2. Agent 管理：创建 Agent、填写规则、挂接技能、知识库和模型。
|
||||
3. Agent 画布：拖入多个 Agent 节点、连线、启停、保存模板。
|
||||
4. 知识库：上传文件、查看原文、分类、确认 AI 建议、检索测试、重建索引。
|
||||
5. 任务看板：创建任务、解析导图、观察运行状态、审查内容段、处理失败。
|
||||
6. 日志与通知：按状态筛选 Trace，查看模型调用和事件链。
|
||||
7. 组合交付：查看成稿预览、组合报告并下载产物。
|
||||
|
||||
前端 API 封装统一从 `localStorage` 读取 `yawan-workbench-access-token`，JSON 请求和文件上传都会自动添加 Bearer Header；401 后由认证入口重新登录。
|
||||
|
||||
## 14. 启动、部署与备份
|
||||
|
||||
### 14.1 启动后端
|
||||
|
||||
```powershell
|
||||
cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\server"
|
||||
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8010
|
||||
```
|
||||
|
||||
### 14.2 启动前端
|
||||
|
||||
```powershell
|
||||
cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\web"
|
||||
npm.cmd run dev -- --host 127.0.0.1 --port 5173
|
||||
```
|
||||
|
||||
也可以从项目根目录运行 `启动工作台.bat`。
|
||||
|
||||
### 14.3 生产构建
|
||||
|
||||
```powershell
|
||||
cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\web"
|
||||
npm.cmd run build
|
||||
```
|
||||
|
||||
### 14.4 备份建议
|
||||
|
||||
至少备份以下内容：
|
||||
|
||||
- `server/data/workspace.db`：业务数据库。
|
||||
- `server/data/kb/`：知识库原始文件。
|
||||
- `server/data/vector_fallback/`：稳定向量兜底文件。
|
||||
- `server/data/chroma/`：Chroma 数据目录，可作为加速层备份。
|
||||
- `server/data/artifacts/`：Markdown/DOCX 交付产物。
|
||||
|
||||
备份恢复后先启动 API，再检查 `/api/auth/status`、知识库 `index_status` 和 Trace 列表；不要只依据目录存在判断索引可用。
|
||||
|
||||
## 15. 测试与验收证据
|
||||
|
||||
当前已执行：
|
||||
|
||||
```powershell
|
||||
cd "C:\Users\xinmiclaw\Desktop\雅文内容创造工作台\server"
|
||||
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
|
||||
.\.venv\Scripts\python.exe -m compileall -q app scripts
|
||||
|
||||
cd ..\web
|
||||
npm.cmd run build
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- 后端测试 13 个全部通过。
|
||||
- Python 编译检查通过。
|
||||
- Vite 生产构建通过，生成 `web/dist/`。
|
||||
- `/api/auth/status` 返回 200。
|
||||
- 未登录访问受保护 Agent API 返回 401。
|
||||
- OpenAPI 文档包含 `/api/traces` 和 `/api/auth/users`。
|
||||
- 前端 5173 和后端 8010 均可访问。
|
||||
- KB3 独立进程读取为 `ready/2717`，相似度检索返回结果。
|
||||
|
||||
## 16. 当前已知约束与后续增强
|
||||
|
||||
### 16.1 已知约束
|
||||
|
||||
- SQLite 适合当前本地/内网工作区；大规模多人并发时应迁移到 PostgreSQL。
|
||||
- 本地向量兜底使用 JSON，优先保证稳定性；数据量继续扩大后可替换为独立向量服务。
|
||||
- Provider 的 API Key 仍由本地数据库保存，生产多租户部署应接入系统密钥管理服务。
|
||||
- Agent Runtime 当前以线程/后台任务调度为主，跨机器扩展需要引入任务队列和分布式锁。
|
||||
|
||||
### 16.2 后续增强方向
|
||||
|
||||
1. 增加 Trace 导出 JSON、运行对比和成本统计。
|
||||
2. 为知识库分类增加分类规则版本和批量人工确认。
|
||||
3. 增加 Agent 规则版本差异对比和一键回滚。
|
||||
4. 将通知中心扩展为可配置的本地/企业 IM 通知。
|
||||
5. 为生产段加入更细粒度的引用覆盖率和事实一致性指标。
|
||||
|
||||
## 17. 代码索引
|
||||
|
||||
| 文件 | 说明 |
|
||||
| --- | --- |
|
||||
| `server/app/main.py` | FastAPI 路由、启动恢复、资源 CRUD、任务控制 |
|
||||
| `server/app/models.py` | SQLModel 数据表定义 |
|
||||
| `server/app/db.py` | 数据库初始化、幂等迁移和索引 |
|
||||
| `server/app/auth.py` | 密码哈希、Session、角色权限映射 |
|
||||
| `server/app/agents/runtime.py` | Agent Runtime 主循环和工具协议 |
|
||||
| `server/app/agents/snapshot.py` | Agent/阶段运行配置快照 |
|
||||
| `server/app/agents/runner.py` | 内容段生成、引用消费、状态机和锚点 |
|
||||
| `server/app/agents/qc.py` | 四道质检和 QC 报告 |
|
||||
| `server/app/agents/composer.py` | 组合成稿、总检和交付产物 |
|
||||
| `server/app/rag/pipeline.py` | 导入、分类、重建、回滚和检索编排 |
|
||||
| `server/app/rag/store.py` | Chroma 与本地向量兜底存储 |
|
||||
| `server/scripts/rebuild_kb3.py` | KB3 可观察重建脚本 |
|
||||
| `web/src/App.tsx` | 工作台页面、认证入口、资源管理和 Trace 页面 |
|
||||
| `web/src/CanvasPage.tsx` | Agent 画布交互 |
|
||||
| `web/src/api.ts` | 前端 API 和 Token 注入 |
|
||||
@@ -0,0 +1,904 @@
|
||||
# 雅文内容创造工作台 · v6 用户端、管理端与云化设计
|
||||
|
||||
> 文档日期：2026-08-27
|
||||
> 文档状态：v6 设计 + v6.1 提示模板实现同步
|
||||
> 关联文档：[设计文档 v5](./设计文档v5-系统设计.md)
|
||||
> 核心逻辑：[核心逻辑设计文档 v6](./核心逻辑设计文档v6.md)
|
||||
> 从零落地：[核心逻辑设计文档 v6：从 0 到 1](./核心逻辑设计文档v6-从0到1.md)
|
||||
> 本文只修改设计文档，不代表本轮已经修改源码
|
||||
|
||||
## 0. 这次要解决什么
|
||||
|
||||
当前 v5 已经具备本地 Agent Runtime、知识库、任务编排、认证、Trace 和 KB3 稳定索引。本 v6 设计在此基础上增加六个企业化能力：
|
||||
|
||||
1. 面向普通用户的用户端，以及面向运营人员的管理端。
|
||||
2. 按用户统计 AI 调用量、Token、Embedding、OCR 和存储量，并形成可审计的计费账单。
|
||||
3. 所有源文件、向量快照、产物和导出包迁移到云对象存储。
|
||||
4. 增加全局知识库、私有知识库和管理员授权共享机制。
|
||||
5. 模型连接、模型发现和模型费率全部收敛到管理端，用户端只选择已开放模型。
|
||||
6. 记忆库复用知识库的私有、共享、全局、授权、撤销、导出和审计逻辑。
|
||||
|
||||
本版本的关键原则是：**所有权与使用权分离、全局资源与私有资源隔离、计费以真实调用账本为准、管理端可见但不能绕过审计**。
|
||||
|
||||
## 1. 产品形态
|
||||
|
||||
### 1.1 用户端
|
||||
|
||||
普通用户只看到自己的工作空间，以及管理员授权给他的资源：
|
||||
|
||||
- 我的任务：创建任务、运行 Agent、查看进度、审查内容和下载成稿。
|
||||
- 我的 Agent：创建和维护自己的生产 Agent、技能绑定和规则。
|
||||
- 我的知识库：上传、分类、预览、检索和删除自己的私有素材。
|
||||
- 全局知识库：读取管理员开放的公共资料；不能删除和修改原文。
|
||||
- 共享知识库：管理员明确授予当前用户后才显示。
|
||||
- 记忆库：管理自己的记忆，以及管理员授予的共享/全局记忆。
|
||||
- 模型选择：只能从管理端已接入并开放的模型目录中选择，不能添加 Provider、API Key 或模型。
|
||||
- 用量与账单：查看本月 AI 用量、余额/额度、调用明细和导出记录。
|
||||
- 我的记忆：只管理自己的私有记忆，不能读取其他用户未授权的记忆。
|
||||
|
||||
### 1.2 管理端
|
||||
|
||||
管理员使用独立的管理端导航，不与用户端混在同一组页面里：
|
||||
|
||||
- 用户与组织：账号、状态、角色、所属组织和配额。
|
||||
- 全局知识库：创建和维护所有用户可用的公共知识。
|
||||
- 知识库总览：查看全部用户私有知识库的元数据、容量、索引状态和归属。
|
||||
- 授权中心：把某个私有知识库授权给指定用户，或开放给全部用户。
|
||||
- 记忆库总览：查看全部用户记忆、来源 Agent、可见性、使用者和版本。
|
||||
- 模型目录：接入 Provider、维护模型列表、费率、能力、启用状态和用户可见范围。
|
||||
- AI 用量与计费：按用户、Provider、模型、时间和任务查看用量与费用。
|
||||
- 云存储与导出：导出数据库、知识库文件、向量索引、Trace 和账单。
|
||||
- 安全审计：查看登录、权限变更、知识库授权、导出和计费调整记录。
|
||||
|
||||
管理端可以“看见”用户私有知识库的元数据和内容预览，但所有查看、下载、导出行为都要写入审计日志；默认不改变文件归属和内容。
|
||||
|
||||
## 2. 总体架构变化
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U[普通用户端] --> G[统一 API 网关]
|
||||
A[管理端] --> G
|
||||
G --> IAM[身份、组织与 RBAC]
|
||||
G --> TENANT[租户与资源授权]
|
||||
G --> ORCH[Agent Runtime / 任务编排]
|
||||
G --> BILL[用量计量与计费]
|
||||
G --> KB[RAG 知识库服务]
|
||||
G --> EXP[导出任务服务]
|
||||
IAM --> DB[(关系数据库)]
|
||||
TENANT --> DB
|
||||
BILL --> DB
|
||||
ORCH --> DB
|
||||
KB --> META[知识库元数据]
|
||||
KB --> OBJ[云对象存储]
|
||||
KB --> VEC[云向量存储或本地加速索引]
|
||||
EXP --> OBJ
|
||||
ORCH --> LLM[模型 Provider]
|
||||
ORCH --> BILL
|
||||
A --> AUDIT[审计日志]
|
||||
U --> AUDIT
|
||||
```
|
||||
|
||||
### 2.1 资源边界
|
||||
|
||||
每个请求先解析出三个边界：
|
||||
|
||||
| 边界 | 作用 |
|
||||
| --- | --- |
|
||||
| `organization_id` | 组织或租户隔离，决定用户属于哪个企业空间 |
|
||||
| `owner_user_id` | 私有资源的所有者，决定默认可见范围 |
|
||||
| `visibility` | `private`、`shared`、`global` 三种知识库可见性 |
|
||||
|
||||
管理员权限是跨用户的管理权限，不会把私有知识库自动变成公共知识库。只有执行“授权共享”或“设为全局”操作后，资源的使用范围才改变。
|
||||
|
||||
## 3. 用户、组织与角色设计
|
||||
|
||||
### 3.1 账号层级
|
||||
|
||||
```text
|
||||
Organization
|
||||
└── UserAccount
|
||||
├── UserRoleBinding
|
||||
├── UsageQuota
|
||||
├── BillingAccount
|
||||
├── KnowledgeBase（私有）
|
||||
├── Agent
|
||||
└── Memory
|
||||
```
|
||||
|
||||
同一个用户只能在当前组织范围内使用组织资源。未来需要跨组织时，使用组织成员关系授权，不直接复用另一组织的用户 ID。
|
||||
|
||||
### 3.2 角色
|
||||
|
||||
| 角色 | 用户端能力 | 管理端能力 |
|
||||
| --- | --- | --- |
|
||||
| `user` | 使用自己的 Agent、私有库、获授权的共享库和全局库 | 无 |
|
||||
| `reviewer` | 额外执行内容审查、查看审查 Trace | 无用户管理能力 |
|
||||
| `operator` | 使用用户端全部功能 | 查看用户、处理导出、处理索引和授权申请 |
|
||||
| `admin` | 使用全部用户端功能 | 用户、知识库、权限、计费、云存储和审计全管理 |
|
||||
| `owner` | 组织内全部功能 | 当前组织最高权限，不跨组织 |
|
||||
|
||||
管理员接口和用户接口使用不同的权限前缀：
|
||||
|
||||
```text
|
||||
user:read 用户读取自己的资源
|
||||
user:write 用户修改自己的资源
|
||||
admin:users 管理用户与角色
|
||||
admin:kb 管理所有知识库和授权
|
||||
admin:memory 管理所有记忆和授权
|
||||
admin:models 管理 Provider、模型目录和模型授权
|
||||
admin:billing 查看和调整计费规则
|
||||
admin:export 创建和下载全量导出
|
||||
admin:audit 查看审计日志
|
||||
```
|
||||
|
||||
### 3.3 模型配置权限边界
|
||||
|
||||
模型连接属于管理端资源，用户端只消费“可用模型目录”，不接触 Provider 凭据：
|
||||
|
||||
| 操作 | 用户端 | 管理端 |
|
||||
| --- | --- | --- |
|
||||
| 新增/修改/删除 Provider | 禁止 | 允许 |
|
||||
| 填写或查看 API Key | 禁止 | 允许，界面只显示脱敏摘要 |
|
||||
| 从 Provider 发现模型 | 禁止 | 允许 |
|
||||
| 启用/停用模型 | 禁止 | 允许 |
|
||||
| 修改模型费率和能力标签 | 禁止 | 允许 |
|
||||
| 给 Agent 选择模型 | 允许，在可用目录内选择 | 允许全部模型 |
|
||||
| 直接输入任意模型名称 | 禁止 | 可作为受控维护动作 |
|
||||
|
||||
用户创建或编辑 Agent 时，模型字段只能引用 `ModelCatalog` 中状态为 `enabled` 且对当前组织可见的记录。用户端不显示 Provider 管理入口，也不接受 `base_url`、`api_key` 或任意自定义模型名。管理员停用模型后，历史任务继续使用已冻结的运行快照，新任务不能再选择该模型。
|
||||
|
||||
## 4. 知识库可见性与授权模型
|
||||
|
||||
### 4.1 三类知识库
|
||||
|
||||
| 类型 | 创建者 | 默认使用者 | 修改者 |
|
||||
| --- | --- | --- | --- |
|
||||
| 私有知识库 `private` | 普通用户或管理员代建 | 仅所有者 | 所有者；管理员可代维护 |
|
||||
| 共享知识库 `shared` | 普通用户或管理员 | 被授权用户列表 | 所有者和管理员 |
|
||||
| 全局知识库 `global` | 管理员 | 当前组织全部用户 | 管理员 |
|
||||
|
||||
用户自己上传的知识库默认是 `private`。管理员可以执行两种授权动作：
|
||||
|
||||
1. 授权给指定用户：保持私有归属不变，增加可使用者。
|
||||
2. 开放给全部用户：将可见性改为 `global`，所有用户可以检索，但只有管理员可以修改原文。
|
||||
|
||||
取消授权只影响后续检索，不删除原文件、不改变历史任务的引用快照。
|
||||
|
||||
### 4.2 访问判定顺序
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
R[收到知识库读取请求] --> S{账号已启用?}
|
||||
S -- 否 --> X[返回 401/403]
|
||||
S -- 是 --> M{管理员管理动作?}
|
||||
M -- 是 --> L[允许管理范围内读取并记录审计]
|
||||
M -- 否 --> O{当前用户是所有者?}
|
||||
O -- 是 --> L2[允许读写私有库]
|
||||
O -- 否 --> G{visibility = global?}
|
||||
G -- 是 --> L3[允许只读检索]
|
||||
G -- 否 --> P{存在有效授权记录?}
|
||||
P -- 是 --> L4[允许按授权范围读取]
|
||||
P -- 否 --> D[拒绝访问]
|
||||
```
|
||||
|
||||
检索服务必须在数据库层先得到“允许查询的知识库 ID 列表”，再调用向量搜索；不能先搜索全库后在结果层过滤。
|
||||
|
||||
### 4.3 授权记录
|
||||
|
||||
建议新增 `KnowledgeBaseGrant`：
|
||||
|
||||
| 字段 | 含义 |
|
||||
| --- | --- |
|
||||
| `id` | 授权记录 ID |
|
||||
| `kb_id` | 知识库 ID |
|
||||
| `grantee_user_id` | 被授权用户；全员开放时为空 |
|
||||
| `grantee_organization_id` | 被授权组织 |
|
||||
| `permission` | `read`、`use`、`manage` |
|
||||
| `status` | `active`、`revoked`、`expired` |
|
||||
| `granted_by` | 执行授权的管理员 |
|
||||
| `expires_at` | 可选到期时间 |
|
||||
| `created_at`、`revoked_at` | 生命周期时间 |
|
||||
|
||||
`use` 允许 Agent 检索并消费 chunk，`read` 只允许人工浏览，`manage` 允许分类、重建和文件维护。普通用户不能给自己追加授权，也不能把私有库开放给全部用户。
|
||||
|
||||
### 4.4 记忆库与画布组合授权
|
||||
|
||||
记忆库保留知识库的所有权和可见性字段，但运行时授权根改为 Agent 画布。用户创建的 Agent 记忆默认是 `private`；管理员授权某个画布后，画布节点 Agent 的知识库和确认记忆一起获得查看/运行范围，不再要求为同一流程重复授权记忆。
|
||||
|
||||
| 记忆范围 | 默认可见者 | 用户端行为 | 管理端行为 |
|
||||
| --- | --- | --- | --- |
|
||||
| 私有记忆 `private` | 所有者及其 Agent | 查看、编辑、删除、绑定自己的 Agent | 可查看、导出、代维护，所有行为审计 |
|
||||
| 共享记忆 `shared` | 画布授权用户 | 读取并在授权画布中使用 | 通过画布授权、撤销、修改可使用者 |
|
||||
| 全局记忆 `global` | 当前组织全部用户 | 只读使用，不修改原文 | 创建、编辑、版本管理和下架 |
|
||||
|
||||
记忆的访问判定顺序为：管理员管理动作 → 所有者 → 全局 → 有效画布授权 → 兼容的历史 `MemoryGrant` → 拒绝。用户端的记忆检索必须先得到允许访问的记忆 ID 集合，再注入 Agent Runtime，不能先读取全量记忆后在前端过滤。
|
||||
|
||||
画布授权使用 `read`、`use`、`manage`、`export` 四种权限；画布对依赖知识和记忆的继承只覆盖查看和使用，不放大编辑、删除、导出权限。旧 `MemoryGrant` 仅用于迁移兼容，管理端新界面不再创建单独记忆授权。撤销画布授权只影响后续运行；已经创建的任务仍保留其运行快照和引用来源。
|
||||
|
||||
建议新增 `MemoryGrant`，字段结构与 `KnowledgeBaseGrant` 一致，并在 `Memory` 增加：
|
||||
|
||||
```text
|
||||
owner_user_id
|
||||
organization_id
|
||||
visibility: private | shared | global
|
||||
source_agent_id
|
||||
version
|
||||
```
|
||||
|
||||
管理员查看或导出其他用户记忆时必须写入 `AccessAudit`，用户不能通过修改 Agent ID 绕过记忆归属校验。
|
||||
|
||||
## 5. 模型目录与选择
|
||||
|
||||
### 5.1 管理端模型目录
|
||||
|
||||
Provider 的 API Key、Base URL 和模型发现全部由管理端维护。管理端将发现结果规范化为 `ModelCatalog`，用户只看到安全的展示字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `id` | 稳定的模型目录 ID |
|
||||
| `provider_id` | 所属 Provider |
|
||||
| `model_name` | Provider 上的真实模型名 |
|
||||
| `display_name` | 用户端展示名 |
|
||||
| `capabilities` | 文本、工具调用、视觉、长上下文等能力 |
|
||||
| `enabled` | 是否允许新任务选择 |
|
||||
| `visibility` | `global`、组织范围或管理员专用 |
|
||||
| `pricing_version` | 当前计费费率版本 |
|
||||
|
||||
管理员添加 Provider 后，可以点击“发现模型”获取列表，再逐个启用或停用。发现失败只影响目录刷新，不暴露 API Key 和 Provider 错误细节给普通用户。
|
||||
|
||||
### 5.2 用户端模型选择
|
||||
|
||||
用户端 Agent 表单只请求：
|
||||
|
||||
```text
|
||||
GET /api/models/available
|
||||
```
|
||||
|
||||
返回当前用户所在组织可用的模型目录。用户选择的是目录 ID，不是 Provider 地址或自由文本；保存 Agent 时服务端再次校验目录状态和组织可见性。
|
||||
|
||||
模型目录变更不覆盖历史任务快照：
|
||||
|
||||
1. 任务创建时保存 Provider、模型名、能力和费率版本。
|
||||
2. 管理员停用模型后，旧 Run 可以继续恢复或审计。
|
||||
3. 新建任务和重跑任务只能选择当前启用模型。
|
||||
4. 账单使用快照中的费率版本，不按当前目录价格回算历史费用。
|
||||
|
||||
### 5.3 模型相关审计
|
||||
|
||||
以下管理动作写入审计：Provider 新增/删除、API Key 替换、模型启停、费率变更、组织可见范围变更。用户只能看到自己的模型选择记录和调用账单，不能看到其他 Provider 的密钥、内部地址和组织费率策略。
|
||||
|
||||
### 5.4 多用户并发治理
|
||||
|
||||
多个用户同时使用同一个模型不会共享错上下文，原因是每次调用都绑定完整的归属键：
|
||||
|
||||
```text
|
||||
organization_id + user_id + campaign_id + run_id + trace_id + span_id
|
||||
```
|
||||
|
||||
运行时不把消息历史放在 Provider 或全局内存中；每个 Agent Session 独立保存自己的消息、工具状态和配置快照。模型请求发送前由服务端按当前 Session 组装消息，返回后再按同一 `run_id/trace_id` 写入调用账本。
|
||||
|
||||
并发控制分为四层：
|
||||
|
||||
| 层级 | 控制内容 | 目的 |
|
||||
| --- | --- | --- |
|
||||
| 用户级 | 并发 Run 数、Token 日/月额度 | 防止单个用户占满资源 |
|
||||
| 组织级 | 总并发、总 Token、预算上限 | 防止一个组织影响其他组织 |
|
||||
| 模型级 | Provider QPS、并发连接、超时和重试 | 遵守模型服务限制 |
|
||||
| 任务级 | 同一 Campaign 只允许一个活跃 Run | 防止重复计费和结果覆盖 |
|
||||
|
||||
请求进入后先经过配额检查，再进入带组织和模型键的队列。队列状态、限流等待、重试和失败都会写入 Trace；因此“等待”不会被误认为“模型混乱”。
|
||||
|
||||
模型目录必须使用版本化和软停用：
|
||||
|
||||
1. 同一个 Provider 的模型名称变化时创建新的目录版本，不覆盖旧记录。
|
||||
2. 管理员停用只禁止新任务，不删除历史目录和账单费率。
|
||||
3. Provider 临时故障时只影响绑定该 Provider 的队列，其他模型继续运行。
|
||||
4. 用量账本使用调用发起用户归属，不使用最后一个修改 Agent 的用户归属。
|
||||
|
||||
因此，多个用户可以同时选择同一模型；他们的上下文、权限、配额、Trace 和账单分别隔离。真正需要避免的是“共享消息历史、按名称动态解析模型、无用户归属的用量记录”，这些在本设计中全部禁止。
|
||||
|
||||
### 5.5 成人内容能力兼容性测试
|
||||
|
||||
用户所说的“破限”在系统中落地为**管理员可执行、可回归、可审计的成人内容能力兼容性测试**。测试记录模型在指定内容类型上的真实表现，不把测试结果伪装成模型能力，也不把某个 Provider 的策略状态传播给其他 Provider。
|
||||
|
||||
测试分为四个维度：
|
||||
|
||||
| 维度 | 测试内容 | 结果示例 |
|
||||
| --- | --- | --- |
|
||||
| 成人内容生成 | 合规的成人向文本、角色设定和情节续写样例 | `supported`、`provider_blocked`、`partial` |
|
||||
| 中文表达 | 大白话、段落样式、连续口语和上下文衔接 | `pass`、`format_mismatch` |
|
||||
| Agent 结构 | 锚点卡、工具调用、JSON 结构和多轮恢复 | `pass`、`schema_failed` |
|
||||
| 稳定性 | 超时、限流、空输出、长度和重复调用 | `stable`、`timeout`、`rate_limited` |
|
||||
|
||||
测试套件使用版本号和固定样例集，例如 `adult-content-compat-v1`。样例内容存放在管理员控制的测试集内，测试结果只保存哈希、分类、状态、模型版本、Provider、Token、耗时和 Trace，不把测试样例全文写入普通用户日志。
|
||||
|
||||
管理端可以单个测试、批量测试或按计划回归：
|
||||
|
||||
1. 选择一个或多个已接入模型。
|
||||
2. 选择测试套件和生成参数，冻结测试输入、温度、最大输出长度和超时。
|
||||
3. 并行调用模型，记录每个样例的状态、输出哈希和断言结果。
|
||||
4. 计算通过率、成人内容兼容等级、稳定性和平均费用。
|
||||
5. 更新 `ModelCatalog` 的能力状态；只有达到管理员设定阈值的模型才显示为“可用于成人内容”。
|
||||
6. 测试结束后生成 Trace 和报告，支持与上一个模型版本做回归对比。
|
||||
|
||||
Provider 侧的内容策略仍然会影响结果；出现 `provider_blocked` 时，目录应标记为“该 Provider 当前不支持此能力”，而不是把模型标记为已兼容。系统通过管理员选择其他已接入模型或调整路由来满足业务要求，测试结果不覆盖 Provider 的服务策略。
|
||||
|
||||
模型目录增加以下字段：
|
||||
|
||||
```text
|
||||
content_capability: general | adult_supported | adult_partial | adult_unavailable
|
||||
capability_test_version
|
||||
capability_tested_at
|
||||
capability_score
|
||||
capability_status
|
||||
```
|
||||
|
||||
生产任务在创建时声明内容能力需求。运行时只从满足需求且对当前组织可见的目录中选择；任务开始后把能力结果和费率一起写入快照。管理员更新测试结果不会改变已运行任务，后续新任务和重跑任务使用最新目录状态。
|
||||
|
||||
这种设计避免了多用户场景下的三个混乱来源：用户自己上传“解除限制”提示词、模型名称相同但 Provider 不同、模型更新后旧任务被新能力覆盖。
|
||||
|
||||
### 5.6 公开资料检索结论与采用方式
|
||||
|
||||
2026-08-26 对 Linux.do `/latest` 及其公开主题进行检索。`/latest` 本身只是主题索引页，没有一套可直接复现的模型能力规范；相关主题中的用户反馈显示，同一个模型在不同 Provider、中转层、账号和版本下表现可能不同，外置审查和版本更新也会让之前的测试结果失效。这些属于社区观察，作为线索而不是生产结论：
|
||||
|
||||
- [关于破限/破甲的疑问](https://linux.do/t/topic/2512323)：讨论了模型本体偏好与模型前置拦截层的差异。
|
||||
- [破限词仓库没了，谁还有备份的](https://linux.do/t/topic/2504365)：反映提示词仓库和测试结果存在时效性，且不同接入方式结果不同。
|
||||
- [更新了破限工具的 ZCode 版本](https://linux.do/t/topic/2524019)：提到成人向创作在不同模型上的结果差异，并指出本地部署模型更容易保持可控测试环境。
|
||||
- [关于成人内容模型的公开讨论](https://linux.do/t/topic/1680571)：显示社区通常按模型和接入渠道分别试用，而不是假设存在一个适用于全部 Provider 的固定方案。
|
||||
|
||||
系统据此采用以下工程结论：
|
||||
|
||||
1. 不把“破限成功”作为永久能力，而是把它记录为“某 Provider + 某模型版本 + 某测试套件”的一次测试结果。
|
||||
2. 同一个目录模型至少测试直连 Provider 和实际中转/网关两条路径，区分模型行为与前置审查层行为。
|
||||
3. 每次模型版本、Provider 路由、系统提示词或外置审查配置变化，都触发 `adult-content-compat` 回归；旧结果保留，新结果生成新版本。
|
||||
4. 失败结果必须区分 `provider_blocked`、`gateway_blocked`、`model_refused`、`timeout`、`format_failed`，不能用一个“破限失败”状态掩盖根因。
|
||||
5. 只有管理员可以查看原始测试输出和发布能力标签；用户端只看到已发布的能力等级和最后测试时间。
|
||||
|
||||
测试实现可采用 Promptfoo 的 Provider × Test Case × Assertion 矩阵，也可用 Garak 的 Probe/Detector 机制做回归探测；两者都应在工作台内部保存输入哈希、断言、通过率和 Trace，而不是直接把第三方工具输出当作生产路由结论。
|
||||
|
||||
## 6. 云存储设计
|
||||
|
||||
### 6.1 存储职责
|
||||
|
||||
云对象存储保存大文件和可导出产物，关系数据库只保存元数据、权限、哈希和生命周期状态。
|
||||
|
||||
| 数据 | 存储位置 | 数据库记录 |
|
||||
| --- | --- | --- |
|
||||
| 原始上传文件 | 对象存储 | `CloudObject` + `KnowledgeFile` |
|
||||
| 解析后的文本快照 | 对象存储 | 文件哈希和版本 |
|
||||
| 向量索引快照 | 对象存储或托管向量库 | 索引版本和校验值 |
|
||||
| Markdown/DOCX 成稿 | 对象存储 | `Artifact` 的对象键和哈希 |
|
||||
| Trace 导出包 | 对象存储 | `ExportJob` |
|
||||
| 账单导出 | 对象存储 | `BillingExport` |
|
||||
|
||||
### 6.2 对象键规范
|
||||
|
||||
对象键不使用用户原始文件名作为唯一标识，避免重名覆盖：
|
||||
|
||||
```text
|
||||
org/{organization_id}/users/{user_id}/kb/{kb_id}/files/{sha256}-{safe_name}
|
||||
org/{organization_id}/users/{user_id}/kb/{kb_id}/index/{index_version}.json
|
||||
org/{organization_id}/campaigns/{campaign_id}/artifacts/{artifact_id}.docx
|
||||
org/{organization_id}/exports/{export_job_id}/{part_name}
|
||||
```
|
||||
|
||||
写入流程：上传临时对象 → 计算 SHA-256 → 写入数据库元数据 → 原子切换当前版本 → 删除过期临时对象。数据库提交失败时不把对象标记为当前版本；对象清理任务按状态和保留期回收孤儿文件。
|
||||
|
||||
### 6.3 下载与导出
|
||||
|
||||
- 用户下载自己的文件或有权访问的全局/共享文件。
|
||||
- 管理员导出全部或指定用户数据，但必须选择范围、原因和保留期。
|
||||
- API 返回短时效签名地址，不把云存储长期密钥下发到浏览器。
|
||||
- 导出任务异步执行，页面显示排队、打包、上传、完成和失败状态。
|
||||
- 导出包包含 `manifest.json`，列出文件、哈希、归属、分类、权限和创建时间。
|
||||
|
||||
## 7. AI 使用量计费
|
||||
|
||||
### 7.1 计量对象
|
||||
|
||||
每一次 AI 行为都生成一条不可变用量事件：
|
||||
|
||||
| 计量项 | 来源 | 计费单位 |
|
||||
| --- | --- | --- |
|
||||
| LLM 输入 | `LLMCall.prompt_tokens` | 百万 Token |
|
||||
| LLM 输出 | `LLMCall.completion_tokens` | 百万 Token |
|
||||
| Embedding | RAG 导入和查询 | 千 Token 或向量次数 |
|
||||
| OCR | 导图图片 OCR | 页数/图片数 |
|
||||
| 重排 | 可选 Rerank Provider | 次数或 Token |
|
||||
| 云存储 | 对象存储统计 | GB·月 |
|
||||
| 导出 | 导出任务 | GB 或次数 |
|
||||
|
||||
每条计量事件携带 `user_id`、`organization_id`、`campaign_id`、`run_id`、`trace_id`、Provider、模型、数量、费率版本和幂等键。管理员修改费率不会回写历史事件。
|
||||
|
||||
### 7.2 费用公式
|
||||
|
||||
```text
|
||||
llm_fee = prompt_tokens / 1,000,000 * prompt_rate
|
||||
+ completion_tokens / 1,000,000 * completion_rate
|
||||
|
||||
embedding_fee = embedding_tokens / 1,000 * embedding_rate
|
||||
ocr_fee = image_count * ocr_rate
|
||||
storage_fee = gb_month * storage_rate
|
||||
total_fee = llm_fee + embedding_fee + ocr_fee + storage_fee + export_fee
|
||||
```
|
||||
|
||||
最终金额按费率版本保存，不从当前 Provider 配置实时反算。内部计费精度使用整数最小货币单位，界面再格式化为元。
|
||||
|
||||
### 7.3 用量账本
|
||||
|
||||
建议新增：
|
||||
|
||||
- `UsageEvent`：单次 AI 行为原始计量，追加写入，不允许普通用户修改。
|
||||
- `UsageRate`：Provider/模型/服务类型的费率和生效时间。
|
||||
- `BillingAccount`：用户或组织余额、额度、冻结和状态。
|
||||
- `UsageSettlement`：按日/月汇总的结算结果。
|
||||
- `BillingAdjustment`：管理员手工调账，必须填写原因并关联审计事件。
|
||||
- `UsageQuota`：日/月 Token、存储、并发和导出限制。
|
||||
|
||||
### 7.4 计费时序
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant Runtime as Agent Runtime
|
||||
participant LLM as Provider
|
||||
participant Meter as 用量计量
|
||||
participant Bill as 账单服务
|
||||
participant Admin as 管理端
|
||||
|
||||
User->>Runtime: 发起任务
|
||||
Runtime->>LLM: 模型请求
|
||||
LLM-->>Runtime: 输出与 Token 统计
|
||||
Runtime->>Meter: 写入不可变 UsageEvent
|
||||
Meter->>Bill: 按费率计算预估费用
|
||||
Bill-->>User: 更新用量与额度
|
||||
Admin->>Bill: 查询、导出或调整账单
|
||||
Bill-->>Admin: 汇总、明细和审计记录
|
||||
```
|
||||
|
||||
在 Provider 没有返回 Token 时，系统可以使用本地 tokenizer 做“估算”标记，但不能把估算值伪装成计费确认值。账单中区分 `measured`、`estimated`、`settled` 三种状态。
|
||||
|
||||
### 7.5 超额策略
|
||||
|
||||
用户达到配额后按组织策略处理：
|
||||
|
||||
- `warn`：继续执行，仅提示超额。
|
||||
- `soft_limit`：允许当前任务完成，禁止新任务排队。
|
||||
- `hard_limit`：暂停新的 LLM、Embedding 和 OCR 请求。
|
||||
|
||||
已经进入运行中的任务根据 Run 策略完成或取消，取消动作必须写入 Trace 和账单状态。
|
||||
|
||||
## 8. 数据模型扩展
|
||||
|
||||
### 8.1 账号与组织
|
||||
|
||||
建议在现有 `AppUser` 之上增加：
|
||||
|
||||
| 表 | 关键字段 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `Organization` | `id`、`name`、`status`、`plan_id` | 企业或个人工作区 |
|
||||
| `UserAccount` | `user_id`、`organization_id`、`status` | 用户与组织关系 |
|
||||
| `UserRoleBinding` | `user_id`、`role`、`scope` | 角色和作用域 |
|
||||
| `BillingPlan` | `id`、`name`、`quota`、`rates` | 套餐和配额 |
|
||||
| `UsageQuota` | `user_id`、`period`、`limits`、`used` | 用户用量限制 |
|
||||
|
||||
### 8.2 知识库与云对象
|
||||
|
||||
建议扩展现有 `KnowledgeBase`：
|
||||
|
||||
```text
|
||||
owner_user_id
|
||||
organization_id
|
||||
visibility: private | shared | global
|
||||
storage_provider
|
||||
storage_prefix
|
||||
index_version
|
||||
source_bytes
|
||||
retention_policy
|
||||
```
|
||||
|
||||
新增：
|
||||
|
||||
| 表 | 作用 |
|
||||
| --- | --- |
|
||||
| `KnowledgeBaseGrant` | 用户/组织授权关系 |
|
||||
| `CloudObject` | 对象键、版本、哈希、大小、存储类和删除状态 |
|
||||
| `ExportJob` | 导出范围、发起人、进度、对象键和过期时间 |
|
||||
| `AccessAudit` | 查看、下载、授权、撤销和导出行为 |
|
||||
|
||||
### 8.3 模型目录与记忆库
|
||||
|
||||
新增模型目录表 `ModelCatalog`，由管理端维护，用户端只引用目录 ID：
|
||||
|
||||
| 表 | 关键字段 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `ModelCatalog` | `provider_id`、`model_name`、`capabilities`、`enabled`、`visibility`、`pricing_version` | 管理端接入并开放给用户选择的模型 |
|
||||
| `ModelOrganizationGrant` | `model_id`、`organization_id`、`status` | 可选的组织级模型授权 |
|
||||
| `ModelCapabilityTest` | `model_id`、`suite_version`、`status`、`score`、`trace_id` | 管理端模型能力兼容性测试结果 |
|
||||
| `ModelCapabilityCase` | `test_id`、`case_hash`、`dimension`、`assertions`、`result` | 单个测试样例的可审计断言结果 |
|
||||
| `MemoryGrant` | `memory_id`、`grantee_user_id`、`permission`、`status` | 记忆库共享/全局授权 |
|
||||
|
||||
现有 `Memory` 增加 `owner_user_id`、`organization_id`、`visibility`、`source_agent_id` 和 `version`。用户端只能维护自己的私有记忆；共享和全局记忆由授权判定服务控制，规则与 `KnowledgeBaseGrant` 相同。
|
||||
|
||||
### 8.4 任务与账单关联
|
||||
|
||||
现有 `LLMCall` 已经有 `run_id`、`campaign_id`、`agent_id`、`trace_id`、Token 和耗时字段。v6 只需补充：
|
||||
|
||||
```text
|
||||
organization_id
|
||||
user_id
|
||||
usage_event_id
|
||||
billing_status
|
||||
```
|
||||
|
||||
这样一次账单可以回溯到模型调用、Agent、内容段、任务和最终产物。
|
||||
|
||||
## 9. 用户端页面设计
|
||||
|
||||
### 9.1 首页总览
|
||||
|
||||
首屏显示四个指标：
|
||||
|
||||
- 本月已用 Token / 剩余额度。
|
||||
- 本月预估费用 / 已结算费用。
|
||||
- 私有知识库数量和存储占用。
|
||||
- 当前运行任务和待审查数量。
|
||||
|
||||
顶部显示当前组织和账号，不显示其他用户的名称、用量或私有资源。
|
||||
|
||||
### 9.2 知识库页面
|
||||
|
||||
页面分为三个 Tab：
|
||||
|
||||
1. 我的知识库：上传、分类、预览、重建、删除。
|
||||
2. 已授权知识库：只显示管理员授予当前用户的库。
|
||||
3. 全局知识库：只读浏览和检索，显示来源与版本。
|
||||
|
||||
每个知识库卡片显示：可见性、所有者、授权状态、文件数、分块数、索引状态、容量和最近更新时间。用户不能在列表中看到未授权私有库。
|
||||
|
||||
### 9.3 用量与账单页面
|
||||
|
||||
提供时间筛选、任务筛选、模型筛选和导出按钮：
|
||||
|
||||
- 用量趋势：输入 Token、输出 Token、Embedding、OCR、存储。
|
||||
- 调用明细：时间、Agent、模型、Trace、数量、状态、费用。
|
||||
- 配额状态：当前值、上限、预警线。
|
||||
- 账单导出：生成当前用户可见范围的 CSV/JSON 包。
|
||||
|
||||
### 9.4 模型与记忆页面
|
||||
|
||||
- 模型选择器只展示 `/api/models/available` 返回的启用模型；不显示 Provider API Key、Base URL 和发现按钮。
|
||||
- 用户不能新增、编辑或删除模型，也不能输入任意模型名称；表单保存时服务端再次校验目录 ID。
|
||||
- 用户在模型卡片上只看到管理员确认的能力标签，例如“支持成人内容”“部分支持”或“当前不可用”，不能自行修改该标签。
|
||||
- 记忆库页面分为“我的记忆”“已授权记忆”“全局记忆”三个范围，支持查看、确认、停用和删除当前用户有权限管理的条目。
|
||||
- 共享/全局记忆显示所有者、版本、来源 Agent 和授权状态，但用户不能修改原文。
|
||||
|
||||
## 10. 管理端页面设计
|
||||
|
||||
### 10.1 用户与组织
|
||||
|
||||
管理员可以：
|
||||
|
||||
- 创建、停用、重置和删除用户。
|
||||
- 设置角色、组织、套餐、配额和并发限制。
|
||||
- 查看用户最近登录、任务数、知识库数量和本月用量摘要。
|
||||
- 强制撤销用户全部 Session。
|
||||
|
||||
### 10.2 知识库总览与授权中心
|
||||
|
||||
管理端表格显示：
|
||||
|
||||
```text
|
||||
知识库名称 | 所有者 | 类型 | 文件数 | 容量 | 索引状态 | 使用者数 | 最近访问 | 操作
|
||||
```
|
||||
|
||||
操作包括：查看、导出、分类维护、重建索引、授权指定用户、开放全局、撤销授权。任何“开放全局”操作都要二次确认，并记录变更前后的可见性。
|
||||
|
||||
### 10.3 记忆库总览与授权中心
|
||||
|
||||
管理员可以按用户、Agent、组织、可见性和状态查看全部记忆，并执行：
|
||||
|
||||
- 查看、预览和导出用户私有记忆。
|
||||
- 授权指定用户使用某条记忆或某组记忆。
|
||||
- 将记忆发布为组织全局记忆，或恢复为私有/共享状态。
|
||||
- 修改版本、停用过期记忆、撤销授权和恢复授权。
|
||||
|
||||
管理员的查看、下载、导出和授权动作都写入 `AccessAudit`；撤销授权只影响新建任务，历史任务继续保留运行快照。
|
||||
|
||||
### 10.4 模型目录管理
|
||||
|
||||
管理员在模型目录页面完成 Provider 和模型生命周期管理：
|
||||
|
||||
1. 新增 Provider 并安全保存 API Key。
|
||||
2. 调用 Provider 的模型发现接口。
|
||||
3. 逐个启用/停用模型，设置能力标签和费率版本。
|
||||
4. 按组织开放模型；用户端只读显示可用目录。
|
||||
5. 查看模型调用量、错误率、Token 和费用。
|
||||
6. 运行成人内容能力兼容性测试，查看版本间的通过率、拒绝率、超时率和成本变化。
|
||||
7. 仅在测试结果达到阈值后，发布或下架模型的“支持成人内容”能力标签。
|
||||
|
||||
### 10.5 计费管理
|
||||
|
||||
管理员可以设置 Provider/模型费率、套餐配额、预警阈值和超额策略；可以按用户、组织、任务和 Trace 查询费用，并对异常账单执行带原因的调账。
|
||||
|
||||
计费页面区分：
|
||||
|
||||
- 原始用量。
|
||||
- 费率版本。
|
||||
- 预估金额。
|
||||
- 已结算金额。
|
||||
- 管理员调整金额。
|
||||
|
||||
## 11. API 设计
|
||||
|
||||
### 11.1 用户端 API
|
||||
|
||||
```text
|
||||
GET /api/me/usage
|
||||
GET /api/me/billing
|
||||
GET /api/me/exports
|
||||
POST /api/me/exports
|
||||
GET /api/models/available
|
||||
|
||||
GET /api/kbs?scope=mine|granted|global
|
||||
GET /api/kbs/{id}/access
|
||||
POST /api/kbs/{id}/import
|
||||
GET /api/kbs/{id}/search
|
||||
GET /api/kbs/{id}/files/{filename}
|
||||
|
||||
GET /api/memories?scope=mine|granted|global
|
||||
POST /api/memories/{id}/decide
|
||||
PUT /api/memories/{id}
|
||||
DELETE /api/memories/{id}
|
||||
```
|
||||
|
||||
接口返回结果必须经过当前用户可见范围过滤；`scope=mine` 不能返回管理员代建但归属其他用户的私有库。
|
||||
|
||||
`GET /api/models/available` 是用户端唯一的模型目录入口，只返回管理员已启用且当前组织可见的模型。用户端不开放 Provider CRUD、模型发现、费率修改和 API Key 相关接口。
|
||||
|
||||
### 11.2 管理端 API
|
||||
|
||||
```text
|
||||
GET /api/admin/organizations
|
||||
GET /api/admin/users
|
||||
POST /api/admin/users/{id}/revoke-sessions
|
||||
PUT /api/admin/users/{id}/quota
|
||||
|
||||
GET /api/admin/knowledge-bases
|
||||
POST /api/admin/knowledge-bases/{id}/grants
|
||||
DELETE /api/admin/knowledge-bases/{id}/grants/{grant_id}
|
||||
POST /api/admin/knowledge-bases/{id}/publish-global
|
||||
POST /api/admin/knowledge-bases/{id}/export
|
||||
|
||||
GET /api/admin/memories
|
||||
POST /api/admin/memories/{id}/publish-global
|
||||
GET /api/admin/canvases
|
||||
POST /api/admin/canvases/{id}/grants
|
||||
DELETE /api/admin/canvases/{id}/grants/{grant_id}
|
||||
POST /api/admin/canvases/{id}/publish-global
|
||||
GET /api/admin/knowledge-bases/{id}/export
|
||||
GET /api/admin/canvases/{id}/export
|
||||
GET /api/admin/memories/{id}/export
|
||||
|
||||
GET /api/admin/model-providers
|
||||
POST /api/admin/model-providers
|
||||
PUT /api/admin/model-providers/{id}
|
||||
DELETE /api/admin/model-providers/{id}
|
||||
POST /api/admin/model-providers/{id}/discover
|
||||
GET /api/admin/models
|
||||
PUT /api/admin/models/{id}
|
||||
POST /api/admin/models/{id}/organization-grants
|
||||
POST /api/admin/models/{id}/capability-tests
|
||||
GET /api/admin/models/{id}/capability-tests
|
||||
POST /api/admin/models/{id}/capability-tests/{test_id}/publish
|
||||
|
||||
GET /api/admin/usage
|
||||
GET /api/admin/billing/settlements
|
||||
POST /api/admin/billing/adjustments
|
||||
GET /api/admin/audit
|
||||
```
|
||||
|
||||
管理端模型接口和画布授权接口只允许管理员权限；记忆的用户使用范围由 `CanvasGrant` 继承计算。普通用户即使知道管理端路径，也只能得到 `403`，不会得到 Provider 配置或其他用户的管理数据。
|
||||
|
||||
能力测试接口只接受管理端预置的测试套件 ID，拒绝由普通用户或前端传入任意“破限提示词”。测试执行和发布结果写入 Trace、`ModelCapabilityTest` 与审计日志。
|
||||
|
||||
### 11.3 响应和错误
|
||||
|
||||
| 状态码 | 场景 |
|
||||
| --- | --- |
|
||||
| `401` | 未登录或 Session 过期 |
|
||||
| `403` | 已登录但没有用户/管理端权限，或没有知识库授权 |
|
||||
| `404` | 资源不存在，或为了防止枚举而隐藏未授权资源 |
|
||||
| `409` | 重复授权、重复结算或并发修改冲突 |
|
||||
| `422` | 计费、导出或存储参数不合法 |
|
||||
| `429` | 用户或组织达到并发/调用限额 |
|
||||
| `503` | 云存储、Embedding 或 Provider 暂时不可用 |
|
||||
|
||||
## 12. 数据安全与审计
|
||||
|
||||
### 12.1 最小权限
|
||||
|
||||
- 用户检索只在“所有者 + 有效授权 + 全局库”集合中执行。
|
||||
- 管理员查看私有库内容需要 `admin:kb`，下载/导出还需要 `admin:export`。
|
||||
- 用户端只能读取自己可用的 `ModelCatalog`，模型 Provider 和费率只对 `admin:models` 开放。
|
||||
- 用户记忆只在“所有者 + 有效画布授权 + 全局记忆”集合中注入 Agent Runtime；旧 `MemoryGrant` 仅作为迁移兼容。
|
||||
- 计费明细按用户和组织隔离；普通用户不能查看其他用户 Token 或费用。
|
||||
- 记忆、任务、Trace 和产物沿用同一所有者/组织边界。
|
||||
|
||||
### 12.2 审计事件
|
||||
|
||||
以下操作必须记录操作者、目标对象、前后值、IP/客户端、Trace 和结果：
|
||||
|
||||
- 登录、退出、Session 撤销和角色变更。
|
||||
- 查看、下载、导出用户私有知识库。
|
||||
- 查看、下载、导出用户私有记忆。
|
||||
- 授权、撤销授权、开放全局和恢复私有。
|
||||
- Provider/API Key 替换、模型启停、模型组织授权和费率版本变更。
|
||||
- 成人内容能力测试的发起、样例套件版本、结果发布、能力标签变更和回归差异。
|
||||
- 修改 Provider 费率、配额、套餐和手工调账。
|
||||
- 删除文件、删除知识库和索引回滚。
|
||||
|
||||
### 12.3 删除与保留
|
||||
|
||||
用户删除私有知识库时进入回收站，不立即物理删除；默认保留 30 天，管理员可以在审计确认后提前清理。全局知识库删除需要管理员二次确认，并保留历史任务引用的内容哈希和快照。
|
||||
|
||||
## 13. 从 v5 迁移到 v6
|
||||
|
||||
### 13.1 兼容策略
|
||||
|
||||
1. 现有 `AppUser` 迁移为第一个 `Organization` 下的管理员账号。
|
||||
2. 现有 `KnowledgeBase` 默认归属该组织和管理员，历史库先标记为 `private`。
|
||||
3. 现有 `Memory`、Agent、Campaign、Segment、Trace 和 Artifact 追加 `organization_id/user_id`，历史数据使用迁移时的拥有者补齐；历史记忆默认为 `private`。
|
||||
4. 现有 Provider 和模型列表迁移为管理端 `ModelCatalog`，历史 Agent 的模型引用转换为目录 ID；用户端不继承 Provider 写入权限。
|
||||
5. 本地源文件先上传到对象存储，校验哈希一致后再切换读取路径。
|
||||
6. KB3 的 2,717 个分块和 512 维向量先作为一个 index version 上传，不重新计算 Embedding。
|
||||
7. 迁移完成前保留本地 SQLite、原始文件和 `vector_fallback` 目录，验证通过后再进入清理周期。
|
||||
|
||||
### 13.2 迁移验收
|
||||
|
||||
迁移必须逐项验证：
|
||||
|
||||
- 用户只能看到自己的私有库和已授权库。
|
||||
- 用户只能选择管理端已开放的模型，不能创建 Provider、修改 API Key 或输入任意模型名。
|
||||
- 用户只能看到自己的私有记忆和已授权/全局记忆，记忆授权撤销后新任务立即失效。
|
||||
- 管理员可以查看和导出所有库，但操作有审计记录。
|
||||
- KB3 重启后仍为 `ready/2717`，引用和 chunk ID 不变化。
|
||||
- 一次 LLM 调用可以从账单回溯到 `LLMCall`、Run、Trace 和用户。
|
||||
- 对象哈希、数据库哈希和导出 manifest 一致。
|
||||
- 撤销授权后，新任务检索不到该库，历史任务仍能查看已有引用快照。
|
||||
|
||||
## 14. 实施阶段建议
|
||||
|
||||
### 阶段 P1：边界和云对象
|
||||
|
||||
- 新增组织、用户归属、资源所有者和可见性字段。
|
||||
- 将现有 Provider/模型整理成管理端 `ModelCatalog`，先确定用户端只读选择边界。
|
||||
- 建立 `adult-content-compat-v1` 等版本化能力测试套件，先校验模型目录再向用户端发布能力标签。
|
||||
- 建立对象存储适配层、对象键规范和上传/下载生命周期。
|
||||
- 先迁移原始文件和最终产物，不改变 Agent 业务流程。
|
||||
|
||||
### 阶段 P2：全局库与授权
|
||||
|
||||
- 增加 `KnowledgeBaseGrant` 和授权判定服务。
|
||||
- 增加 `MemoryGrant`，让记忆库和知识库使用同一套私有/共享/全局判定。
|
||||
- 用户端拆分“我的/已授权/全局”三个知识库范围。
|
||||
- 用户端拆分“我的/已授权/全局”三个记忆范围。
|
||||
- 管理端增加知识库和记忆库总览、授权和导出入口。
|
||||
|
||||
### 阶段 P3：用量计量与账单
|
||||
|
||||
- 将 `LLMCall`、Embedding、OCR 和存储事件统一写入 `UsageEvent`。
|
||||
- 增加费率版本、配额、预警、结算和调账。
|
||||
- 管理端完成按用户、组织、模型和 Trace 的账单查询。
|
||||
|
||||
### 阶段 P4：迁移与压测
|
||||
|
||||
- 迁移当前数据并执行权限矩阵测试。
|
||||
- 测试对象存储断点续传、重复上传、孤儿文件清理和导出恢复。
|
||||
- 测试并发 Agent、额度耗尽、授权撤销和管理员审计。
|
||||
|
||||
## 15. 设计完成标准
|
||||
|
||||
当以下条件全部满足，v6 设计可以进入实现验收：
|
||||
|
||||
- 用户端和管理端导航、权限和 API 边界清晰分离。
|
||||
- 用户端没有 Provider CRUD、模型发现、API Key 和费率修改入口，只能选择管理员开放的模型目录。
|
||||
- 成人内容模型能力由管理端版本化测试结果发布；用户端只读查看能力标签，不能自行“破限”或改写测试结论。
|
||||
- 私有、共享、全局三种知识库访问规则可以通过数据库授权记录解释。
|
||||
- 记忆库沿用同样的私有、共享、全局、授权、撤销和审计规则。
|
||||
- 管理员能查看、预览、导出每个用户私有知识库，同时所有行为可审计。
|
||||
- 管理员能查看、预览、导出每个用户私有记忆，并能授权给指定用户或全部用户。
|
||||
- AI 用量可以按用户和组织精确归集到 Trace，费率变更不影响历史账单。
|
||||
- 云存储对象有哈希、版本、生命周期和导出 manifest。
|
||||
- 重启、索引失败、云存储暂时不可用和配额超限都有明确状态，不产生假成功。
|
||||
- v5 的 Agent Runtime、QC、组合、记忆和 KB3 既有行为保持兼容。
|
||||
|
||||
## 16. v6.1 提示模板与结构化输出（已实现）
|
||||
|
||||
根据《提示工程实战指南》的工程化原则，Agent 配置增加独立的 `AgentPromptTemplate`。模板字段为角色提示、任务模板、约束列表、上下文示例、输出 Schema、表达风格和版本状态。它与 Agent 规则分离，避免规则、任务数据和示例互相污染。
|
||||
|
||||
运行时固定使用“角色 → 任务 → 风格 → Agent 规则 → 约束 → 示例 → 技能/记忆/锚点/知识 → Runtime 硬规则 → 输出协议”的分层提示。用户模板只负责组织输入，知识来源边界、Agent 级消费锁、工具审批、取消、QC 和人工审查由 Runtime 保持最高优先级。
|
||||
|
||||
新建任务时保存模板完整快照并记录版本。模板更新自动递增版本；历史任务继续使用旧快照。输出协议以锚点卡 JSON 为当前生产 Schema，运行器在产物写入前执行 `required` 和字段类型校验，失败结果释放知识片段并进入重做或人工处理。
|
||||
|
||||
管理端入口：`GET/POST /api/prompt-templates`、`GET/PUT/DELETE /api/prompt-templates/{id}`；Agent 管理中的 `prompt_template_id` 只允许引用启用模板。内置模板允许停用，已绑定模板需要解除关系后再删除。
|
||||
|
||||
## 17. v6.2 模型目录边界（已实现）
|
||||
|
||||
Provider 仅负责连接信息和模型发现，用户可选项由独立 `ModelCatalog` 管理。Provider 模型清单发生变化时，系统自动同步目录并停用消失的历史项；目录项保留能力状态、费率版本和启用状态，供管理员后续测试发布。
|
||||
|
||||
用户端只能调用 `GET /api/models/available` 获取启用目录，Agent 保存目录 ID 并由服务端再次校验 Provider、模型名称和启用状态。Provider 列表、模型发现、模型连通性测试、目录能力和费率修改均收敛到管理权限，历史任务仍使用其冻结的 Provider/模型快照。
|
||||
|
||||
## 18. v6.3 资源边界与授权实现（P1，已完成）
|
||||
|
||||
服务端已新增 `Organization` 和统一资源范围字段 `organization_id / owner_user_id / visibility`，覆盖 Agent、画布、任务、知识库、待确认记忆、记忆和成稿。普通用户创建的资源自动绑定当前用户并默认为私有；全局发布与共享范围由管理员控制。
|
||||
|
||||
知识库和记忆库分别使用 `KnowledgeBaseGrant`、`MemoryGrant` 保存用户授权，权限分为 `read / use / manage / export`。`use` 自动包含读取，`manage` 包含全部操作，`export` 只用于导出与读取。用户列表、详情、上传、分类、索引、检索、记忆确认/删除、任务运行、Trace 和成稿下载均在服务端检查组织、所有者、可见性和有效授权；撤销授权只影响后续请求，不破坏历史任务快照。
|
||||
|
||||
管理端已提供知识库和记忆库的总览、指定用户授权、撤销授权和发布全局接口。Provider、模型目录、知识/记忆授权均由 `/api/admin/*` RBAC 保护，用户端不获得配置写权限。成稿、待确认记忆和运行链路创建时继承所属任务的范围字段，避免关联资源出现跨用户泄漏。
|
||||
|
||||
本阶段迁移是幂等的：已有 SQLite、原始文件、向量索引和成稿保留，新增列与授权表在启动时补齐。资源隔离、授权分级、模型目录、Agent Runtime 和前端构建均已完成自动化回归验证。
|
||||
|
||||
## 19. 用量计量与账单实现（v6.4，已完成）
|
||||
|
||||
系统已使用追加式 `UsageEvent` 作为唯一用量账本，覆盖 LLM、Embedding 和 OCR。每条事件包含 `user_id`、`organization_id`、`campaign_id`、`run_id`、`segment_id`、`trace_id`、Agent、Provider、模型、服务类型、单位、数量、输入/输出 Token、费率、费率版本、金额（人民币分）、状态和唯一幂等键。`LLMCall` 通过 `usage_event_id` 回链事件，并记录 `billing_status`。
|
||||
|
||||
计费流程为：
|
||||
|
||||
```text
|
||||
请求进入
|
||||
→ 解析发起用户和组织
|
||||
→ 读取 ModelCatalog 当前费率快照
|
||||
→ Provider 返回真实 Token（或本地估算）
|
||||
→ 追加 UsageEvent
|
||||
→ LLMCall/Trace 回链
|
||||
→ 周期汇总与配额检查
|
||||
```
|
||||
|
||||
建库、重建索引和知识检索都记录 Embedding 事件，导图 OCR 记录一次图像事件。Provider 未提供 Token 时标记 `estimated`；`measured`、`estimated`、`settled`、`void` 在界面和汇总中分开统计。费率后续调整只影响新事件，历史金额保持费率版本快照。
|
||||
|
||||
用户端新增 `/api/usage/summary`、`/api/usage/events` 和“用量与账单”入口；管理员新增 `/api/admin/usage/summary`、`/api/admin/usage/events`、`/api/admin/quotas` 及配额新增/删除接口，可按用户、模型、服务类型和日/月周期筛选。管理员代运行任务时，`CampaignRun.user_id` 保存实际发起账号，LLM 账单优先继承该字段，防止多人共用模型造成串账。
|
||||
|
||||
`UsageQuota` 支持 Token、金额、存储、并发限制与 `warn / soft_limit / hard_limit` 策略。任务启动前做配额预检；未配置配额时不改变原有行为，达到软/硬限制时返回 429。事件幂等唯一索引、配额唯一索引及用户/组织/时间索引均通过启动迁移补齐，重复启动不会重复建表或重复计费。
|
||||
|
||||
## 20. 企业级双入口与 RBAC 收口（v6.5，已实现）
|
||||
|
||||
企业产品通常采用同一身份体系下的独立用户门户和管理控制台：用户进入 `/app`，管理员进入 `/admin`。两者共享登录会话、组织和审计链，但拥有不同的导航、页面职责和 API 权限。门户入口是账号角色的固定边界，管理员和普通用户都没有跳转到另一门户的入口。
|
||||
|
||||
本项目的入口职责如下：
|
||||
|
||||
| 入口 | 可见范围 | 典型动作 |
|
||||
| --- | --- | --- |
|
||||
| 用户工作台 `/app` | 全部业务页面，但数据限定为本人、已授权和全局资源 | 新建任务、管理自己的 Agent/画布/标签/技能/模板/知识库/记忆、选择已发布模型、查看账单 |
|
||||
| 管理控制台 `/admin` | 全部业务页面 + 全组织资源与配置 | 成员/RBAC、Provider、模型目录、Agent、技能、标签、模板、授权、配额、审计 |
|
||||
|
||||
服务端中间件对 `/api/admin/*`、Provider、模型默认配置、模型发现和模型目录治理接口要求 `admin:manage` 或管理员配置权限；普通用户可以读取 `/api/models/available` 的已发布模型目录，但不接触连接凭据、费率治理、配额配置和能力发布。标签、技能、提示模板、Agent、画布、知识库和记忆库在用户端保留完整业务操作，并通过组织、所有者、可见性和 Grant 做行级过滤。用户用量接口只按当前会话用户查询，管理端账单接口只由管理员访问。前端路由守卫和服务端资源判定共同抵抗跨门户与越权请求。
|
||||
|
||||
账号响应新增 `portal` 和 `permissions` 字段。登录后服务端返回的 `portal` 决定唯一入口，前端将管理员定向 `/admin`、普通用户定向 `/app`；访问不匹配的入口只显示入口阻断页。该设计便于未来将 `/app` 与 `/admin` 拆为独立前端或独立域名，同时保留当前单体部署的平滑迁移路径。
|
||||
|
||||
### 20.1 画布作为组合授权根
|
||||
|
||||
`CanvasGrant` 授权对象是一个可运行 Agent 流程的组合边界。管理员给用户授予画布的 `read / use / manage / export` 权限后，画布中的 Agent、Agent 关联知识库以及该 Agent 的已确认记忆按同一范围参与查看和运行；系统不再要求为同一画布重复配置记忆授权。该继承仅允许查看和使用，不把知识库或记忆的编辑、删除、导出能力传递给用户。用户运行后产生的新记忆使用当前用户作为 owner，默认保存为私有；管理员可查看、导出并发布到全局。记忆库页面继续提供个人记忆管理，管理端保留全组织审计和全局发布能力。
|
||||
|
||||
### 20.2 角色管理补充（v6.6）
|
||||
|
||||
角色属于租户级 RBAC 配置。管理员可以在管理控制台创建中文角色、填写职责说明、选择权限、修改权限并删除自定义角色。内置角色仅允许调整权限；自定义角色仍被成员使用时，删除请求返回业务冲突，避免成员瞬间失去权限。服务端为自定义角色生成内部标识，前端和导出报告只展示中文角色名称与中文权限名称。
|
||||
|
||||
权限目录：查看内容、内容编辑、内容审查、运行追踪、配置查看、系统配置、成员管理、管理控制台。角色接口为 `GET/POST/PUT/DELETE /api/auth/roles`，成员创建和修改会校验角色是否存在，并继承当前管理员所属组织。
|
||||
|
||||
### 20.3 记忆库治理补充（v6.6）
|
||||
|
||||
记忆记录采用“待确认 → 已生效 → 可索引调用”的状态链。除原有 Agent、层级、正文、来源和可见性外，记录还保存标题、描述、隐私范围、标签、沉淀日期、索引状态、使用次数和最近使用时间。人工编辑后进入 `needs_reindex`，索引完成后才可进入 Agent 快照；运行时优先加载高使用频次且已建立索引的记忆，单 Agent 加载上限为 50 条。
|
||||
|
||||
该设计对齐记忆库文章的五层记忆、两级分类、元数据、总索引/子索引和人工确认原则。生产云化阶段还需增加对象存储中的索引文件、来源证据、版本链、冲突检测和过期任务，且所有读写均按租户和画布授权范围执行。
|
||||
|
||||
### 20.4 SaaS 生产门槛
|
||||
|
||||
当前本地版已具备租户字段、用户级账单、资源行级授权和独立 `/app`、`/admin` 入口；上线 SaaS 前必须将 SQLite、本地文件和本地向量回退替换为云数据库、对象存储和托管向量索引，并接入密钥托管、限流、组织邀请、平台管理员分层、审计留存和账单结算。详见《SaaS与记忆库全面审查报告》。
|
||||
## 20.5 点数余额规则（v6.7）
|
||||
|
||||
用户 AI 使用额度改为点数余额，统一换算为 `10 点数 = 1 Token`。用户端只能查看自己的点数和用量账单；管理端可以按组织成员增加点数并查看余额。余额低于 10 点数时，服务端在模型请求前返回“点数余额不足”，不向 Provider 发起请求。
|
||||
|
||||
每次模型调用成功后，根据实际输入与输出 Token 扣除 `Token × 10` 点数；Provider 未提供 Token 时按 1 Token 最低计量，并在 `UsageEvent` 中保留估算状态。充值与扣点均写入不可变 `PointTransaction` 流水，充值使用管理员操作幂等键，扣点使用模型用量事件幂等键。余额、流水和账单都按用户与组织隔离，多用户同时调用同一个模型时互不串账。
|
||||
|
||||
`UsageQuota` 及其管理接口仅保留为旧版本数据兼容，不再作为页面入口和运行时限制。管理端页面不再提供“成员配额”编辑器，平台的 AI 可用性只由点数余额控制；`UsageEvent` 仍用于成本、费率快照、Trace 和审计，不用于给用户充值。
|
||||
@@ -0,0 +1,893 @@
|
||||
# 雅文内容创造工作台：核心逻辑、功能与业务总结
|
||||
|
||||
> 生成日期：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 还是更多渠道接入，都应继续守住三条底线：
|
||||
|
||||
> **内容有证据、执行有边界、过程可审计。**
|
||||
Reference in New Issue
Block a user