From 72fc5b47c73c4e5b52a678e324c9649b84c8d66f Mon Sep 17 00:00:00 2001 From: yi <100551693+yi1108@users.noreply.github.com> Date: Wed, 16 Sep 2026 19:06:19 +0800 Subject: [PATCH] docs: add architecture, workflow and delivery documents --- M1验收报告.md | 35 + M3验收报告.md | 41 + M4验收报告.md | 44 + SOURCE-DELIVERY-REPORT.md | 13 + SaaS与记忆库全面审查报告.md | 85 ++ docs/DSH内容生产执行器架构-20260915.md | 48 + docs/coze-studio-借鉴分析.md | 52 + docs/微信Bot接入.md | 61 ++ docs/知识图谱检索升级方案-20260914.md | 183 ++++ docs/系统整体架构与功能检查文档.md | 407 ++++++++ web/MIGRATION.md | 41 + web/index.html | 12 + 修复融合版变更说明-2026-08-29.md | 85 ++ 核心逻辑设计文档v6-从0到1.md | 1124 ++++++++++++++++++++++ 核心逻辑设计文档v6.md | 780 +++++++++++++++ 流程图.md | 94 ++ 流程图v2.md | 91 ++ 流程图v3.md | 99 ++ 流程图v4.md | 169 ++++ 流程图预览.html | 122 +++ 流程图预览v2.html | 120 +++ 流程图预览v3.html | 126 +++ 流程图预览v4.html | 201 ++++ 源码交付说明-2026-08-28.md | 103 ++ 源码包说明-20260914.md | 14 + 源码包说明.md | 26 + 用户使用手册.html | 260 +++++ 用户操作手册.md | 54 ++ 系统功能逻辑文档.html | 232 +++++ 设计文档v1.md | 310 ++++++ 设计文档v2.md | 299 ++++++ 设计文档v3.md | 256 +++++ 设计文档v4.md | 297 ++++++ 设计文档v5-系统设计.md | 559 +++++++++++ 设计文档v6-用户端管理端云化与计费设计.md | 904 +++++++++++++++++ 项目核心逻辑功能业务总结-20260915.md | 893 +++++++++++++++++ 36 files changed, 8240 insertions(+) create mode 100644 M1验收报告.md create mode 100644 M3验收报告.md create mode 100644 M4验收报告.md create mode 100644 SOURCE-DELIVERY-REPORT.md create mode 100644 SaaS与记忆库全面审查报告.md create mode 100644 docs/DSH内容生产执行器架构-20260915.md create mode 100644 docs/coze-studio-借鉴分析.md create mode 100644 docs/微信Bot接入.md create mode 100644 docs/知识图谱检索升级方案-20260914.md create mode 100644 docs/系统整体架构与功能检查文档.md create mode 100644 web/MIGRATION.md create mode 100644 web/index.html create mode 100644 修复融合版变更说明-2026-08-29.md create mode 100644 核心逻辑设计文档v6-从0到1.md create mode 100644 核心逻辑设计文档v6.md create mode 100644 流程图.md create mode 100644 流程图v2.md create mode 100644 流程图v3.md create mode 100644 流程图v4.md create mode 100644 流程图预览.html create mode 100644 流程图预览v2.html create mode 100644 流程图预览v3.html create mode 100644 流程图预览v4.html create mode 100644 源码交付说明-2026-08-28.md create mode 100644 源码包说明-20260914.md create mode 100644 源码包说明.md create mode 100644 用户使用手册.html create mode 100644 用户操作手册.md create mode 100644 系统功能逻辑文档.html create mode 100644 设计文档v1.md create mode 100644 设计文档v2.md create mode 100644 设计文档v3.md create mode 100644 设计文档v4.md create mode 100644 设计文档v5-系统设计.md create mode 100644 设计文档v6-用户端管理端云化与计费设计.md create mode 100644 项目核心逻辑功能业务总结-20260915.md diff --git a/M1验收报告.md b/M1验收报告.md new file mode 100644 index 0000000..1dd7ac2 --- /dev/null +++ b/M1验收报告.md @@ -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场）导入 diff --git a/M3验收报告.md b/M3验收报告.md new file mode 100644 index 0000000..562131e --- /dev/null +++ b/M3验收报告.md @@ -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 时一键打回对应段按钮 diff --git a/M4验收报告.md b/M4验收报告.md new file mode 100644 index 0000000..c3eac05 --- /dev/null +++ b/M4验收报告.md @@ -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 随时可导） diff --git a/SOURCE-DELIVERY-REPORT.md b/SOURCE-DELIVERY-REPORT.md new file mode 100644 index 0000000..4c77f37 --- /dev/null +++ b/SOURCE-DELIVERY-REPORT.md @@ -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. diff --git a/SaaS与记忆库全面审查报告.md b/SaaS与记忆库全面审查报告.md new file mode 100644 index 0000000..9c5315a --- /dev/null +++ b/SaaS与记忆库全面审查报告.md @@ -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`、角色创建、授权、记忆确认和账单隔离的端到端验收。 diff --git a/docs/DSH内容生产执行器架构-20260915.md b/docs/DSH内容生产执行器架构-20260915.md new file mode 100644 index 0000000..f33f10c --- /dev/null +++ b/docs/DSH内容生产执行器架构-20260915.md @@ -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/向量索引。 diff --git a/docs/coze-studio-借鉴分析.md b/docs/coze-studio-借鉴分析.md new file mode 100644 index 0000000..27c3525 --- /dev/null +++ b/docs/coze-studio-借鉴分析.md @@ -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. 单节点试运行（锦上添花） diff --git a/docs/微信Bot接入.md b/docs/微信Bot接入.md new file mode 100644 index 0000000..7897eb4 --- /dev/null +++ b/docs/微信Bot接入.md @@ -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 的数字人规则、已挂接技能和知识库相关片段用于本轮回答。知识库检索失败时会记录日志并继续普通对话，避免微信侧卡死。 diff --git a/docs/知识图谱检索升级方案-20260914.md b/docs/知识图谱检索升级方案-20260914.md new file mode 100644 index 0000000..b71213f --- /dev/null +++ b/docs/知识图谱检索升级方案-20260914.md @@ -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 或独立图数据库，并保留降级路径。 diff --git a/docs/系统整体架构与功能检查文档.md b/docs/系统整体架构与功能检查文档.md new file mode 100644 index 0000000..a492276 --- /dev/null +++ b/docs/系统整体架构与功能检查文档.md @@ -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、权限、验收清单”五个位置。 diff --git a/web/MIGRATION.md b/web/MIGRATION.md new file mode 100644 index 0000000..38043a8 --- /dev/null +++ b/web/MIGRATION.md @@ -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 过 + 浏览器走查 diff --git a/web/index.html b/web/index.html new file mode 100644 index 0000000..43672e8 --- /dev/null +++ b/web/index.html @@ -0,0 +1,12 @@ + + + + + + 私域Agent + + +
+ + + diff --git a/修复融合版变更说明-2026-08-29.md b/修复融合版变更说明-2026-08-29.md new file mode 100644 index 0000000..f07384d --- /dev/null +++ b/修复融合版变更说明-2026-08-29.md @@ -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/`（数据库、知识库、向量索引）不包含在本包内，部署时需重新初始化或单独迁移。 diff --git a/核心逻辑设计文档v6-从0到1.md b/核心逻辑设计文档v6-从0到1.md new file mode 100644 index 0000000..57fc423 --- /dev/null +++ b/核心逻辑设计文档v6-从0到1.md @@ -0,0 +1,1124 @@ +# 雅文内容创造工作台 · 从 0 到 1 核心逻辑设计文档 v6 + +> 文档日期：2026-08-26 +> 文档定位：从零开始理解、设计、实现和验收整套系统的主文档 +> 关联文档：设计文档 v6：用户端、管理端与云化设计 +> 当前实现参考：系统设计文档 v5 + v6.1/v6.2 已落地模块 +> 交付范围：本文档描述系统逻辑和实施顺序，并同步记录已经实现的服务端、前端和数据迁移 + +## 0. 先回答三个问题 + +### 0.1 这个系统是什么 + +这是一个多用户内容生产平台。用户输入主题、导图或任务目标，系统通过多个 Agent 分工完成： + +~~~text +理解任务 → 拆成内容段 → 调用知识和记忆 → 生成内容 → 质量检查 +→ 人工审查 → 组合成稿 → 保存到云端 → 记录用量和账单 +~~~ + +### 0.2 为什么要拆成用户端和管理端 + +普通用户关注“完成内容”，管理端关注“控制资源”： + +| 端 | 关注点 | +| --- | --- | +| 用户端 | 创建任务、选择可用模型、使用知识库、审查内容、下载成稿、查看用量 | +| 管理端 | 管理用户、Provider、模型目录、知识/记忆授权、点数、账单、云存储和审计 | + +用户端只消费管理端开放的能力。Provider 凭据、模型发现、费率和能力标签由管理端统一维护。 + +### 0.3 系统最重要的主线是什么 + +每一次生成都必须回答： + +~~~text +谁发起的？ +使用哪个 Agent 版本？ +使用哪个模型版本？ +读取了哪些获授权的知识和记忆？ +产生了哪些调用和费用？ +经过了哪些质检和人工决定？ +最终交付了什么？ +~~~ + +这条主线就是系统的核心逻辑。 + +## 1. 从零建立系统的顺序 + +从 0 到 1 不按页面数量推进，而按依赖关系推进： + +~~~mermaid +flowchart LR + P0[P0 身份和组织] --> P1[P1 资源归属和权限] + P1 --> P2[P2 模型目录] + P1 --> P3[P3 知识库和记忆库] + P2 --> P4[P4 Agent Runtime] + P3 --> P4 + P4 --> P5[P5 任务/QC/组合] + P5 --> P6[P6 计费/云存储/审计] + P6 --> P7[P7 验收和运营] +~~~ + +| 阶段 | 目标 | 产出 | +| --- | --- | --- | +| P0 | 让系统知道谁在使用 | Organization、User、Session | +| P1 | 让资源有边界 | owner、visibility、grant、RBAC | +| P2 | 让模型受控可选 | Provider、ModelCatalog、能力标签 | +| P3 | 让 Agent 有事实和经验 | KnowledgeBase、Memory、引用和消费状态 | +| P4 | 让 Agent 可稳定执行 | Runtime、工具、审批、恢复、Trace | +| P5 | 让内容可交付 | Campaign、Segment、QC、人工审查、Composer | +| P6 | 让平台可运营 | 云存储、计量、账单、导出和审计 | +| P7 | 让系统可上线 | 权限矩阵、故障演练、数据迁移和验收 | + +## 2. 第一层：身份、组织和角色 + +### 2.1 组织 + +组织是数据隔离的第一层。个人工作区也按一个组织处理： + +~~~text +Organization +└── UserAccount + ├── Agents + ├── KnowledgeBases + ├── Memories + ├── Campaigns + ├── UsageQuota + └── BillingAccount +~~~ + +所有业务对象都保存 organization_id。跨组织读取必须通过明确的组织授权关系。 + +### 2.2 用户 + +用户至少有以下属性： + +| 字段 | 作用 | +| --- | --- | +| user_id | 稳定的用户标识 | +| organization_id | 所属组织 | +| username | 登录名 | +| display_name | 工作台展示名称 | +| status | 启用、停用、锁定 | +| role | 用户、审查者、运营、管理员 | +| quota_id | 当前配额方案 | + +### 2.3 角色 + +| 角色 | 主要能力 | +| --- | --- | +| user | 使用自己的资源和已授权资源，运行任务和查看自己的账单 | +| reviewer | 额外执行人工审查、处理打回和工具审批 | +| operator | 处理用户、索引、导出和授权运营工作 | +| admin | 管理组织、Provider、模型、知识、记忆、计费和审计 | +| owner | 当前组织的最高管理权限 | + +角色只决定“能做什么”，资源授权决定“能对哪份数据做”。两者同时成立才允许执行。 + +## 3. 第二层：资源所有权和可见性 + +### 3.1 资源统一字段 + +~~~text +organization_id +owner_user_id +visibility +access_grants +~~~ + +适用对象：Agent、知识库、知识文件、记忆、画布、任务、Trace、产物和导出包。 + +### 3.2 三种可见性 + +| 可见性 | 默认使用者 | 修改者 | +| --- | --- | --- | +| private | 所有者及其 Agent | 所有者或管理员 | +| shared | 被授权用户 | 所有者和管理员 | +| global | 当前组织全部用户 | 管理员 | + +### 3.3 统一访问判断 + +~~~text +1. 认证当前用户 +2. 确认组织范围 +3. 确认资源存在且状态有效 +4. 判断是否为所有者 +5. 判断是否为 global +6. 判断是否存在 active grant +7. 判断操作权限 read/use/manage/export +8. 记录审计并执行 +~~~ + +查询层先生成允许访问的 ID 集合，再读取数据。前端入口控制只是体验措施，真正的权限判断必须在 API 和数据查询层完成。 + +## 4. 第三层：模型目录逻辑 + +### 4.1 Provider 和模型的关系 + +~~~text +Provider + └── ModelCatalog + ├── 模型真实名称 + ├── 能力标签 + ├── 费率版本 + ├── 组织可见范围 + └── 启用状态 +~~~ + +Provider 保存连接信息；ModelCatalog 保存用户可选的模型能力。用户端只接触 ModelCatalog。 + +### 4.2 管理端操作顺序 + +~~~text +新增 Provider + → 安全保存凭据 + → 发现模型列表 + → 规范化模型记录 + → 设置能力和费率 + → 设置组织可见范围 + → 启用模型 +~~~ + +管理端可以管理 Provider、发现模型、修改能力标签、停用模型和调整费率版本。每次变化都写审计。 + +### 4.3 用户端操作顺序 + +~~~text +GET /api/models/available + → 返回当前组织可用目录 + → 用户选择目录 ID + → 服务端校验 enabled、visibility、capabilities 和 quota + → 写入 Agent 或任务快照 +~~~ + +用户端表单不接收 Provider 地址、API Key、模型自由文本和费率字段。 + +### 4.4 成人内容能力测试 + +系统把“破限”定义为管理员维护的模型能力兼容性测试： + +~~~mermaid +flowchart TD + A[选择模型目录] --> B[选择版本化测试套件] + B --> C[冻结样例、参数和 Provider 路径] + C --> D[执行多模型/多网关测试] + D --> E[逐样例断言] + E --> F[统计通过率、拒绝率、超时率和费用] + F --> G[管理员发布能力标签] + G --> H[用户端读取标签并选择] +~~~ + +结果至少区分： + +~~~text +supported +partial +provider_blocked +gateway_blocked +model_refused +timeout +format_failed +~~~ + +模型版本、Provider 路径、网关配置或系统提示词变化后重新回归。旧结果保留，新结果生成新版本。用户端只看到管理员发布的能力标签和测试时间。 + +## 5. 第四层：知识库逻辑 + +### 5.1 知识库创建 + +~~~text +用户或管理员创建 KnowledgeBase + → 写入组织和所有者 + → 默认 visibility=private + → 创建云存储前缀 + → 创建向量索引命名空间 + → 状态=empty +~~~ + +普通用户创建的库默认属于本人。管理员可以把库授权给指定用户，或发布为当前组织的全局库。 + +### 5.2 文件导入 + +~~~mermaid +flowchart LR + U[上传文件] --> H[计算 SHA-256] + H --> O[写云对象临时版本] + O --> P[解析 docx/srt/md/txt/json/jsonl] + P --> C[清洗和语义分块] + C --> E[Embedding] + E --> V[写向量索引] + V --> M[写文件元数据和分类] + M --> R[状态=ready] +~~~ + +文件表保存：文件名、哈希、修订号、分类、AI 分类建议、置信度和状态。重复上传同名文件时，先替换旧向量，再增加修订号。 + +### 5.3 AI 分类和人工确认 + +~~~text +unclassified + → AI 生成分类建议 + → ai_suggested + → 人工确认/修改/移动 + → human_confirmed +~~~ + +分类树使用 parent_id 支持无限层级。文件移动分类只改变文件归属和向量元数据中的分类路径，原始文件哈希保持不变。 + +### 5.4 知识检索 + +Agent 检索输入由四部分组成： + +~~~text +任务段目标 ++ 上游锚点卡 ++ Agent 规则中的检索意图 ++ 当前用户允许的知识库集合 ++ 当前 Agent 已消费 chunk 的排除集合 +~~~ + +检索结果必须带知识库、文件、分类路径、chunk ID、原文、相似度、文件哈希和修订号，并写入 Segment.references。 + +### 5.5 知识消费规则 + +消费锁按 Agent 隔离： + +~~~text +Agent A 使用 chunk-001 → A 后续排除 chunk-001 +Agent B 未使用 chunk-001 → B 仍可检索 chunk-001 +~~~ + +状态流转： + +~~~text +available → reserved → consumed +reserved → available（任务中断或模型失败） +consumed → available（管理员人工释放） +~~~ + +数据库使用 agent_id、kb_id、chunk_id 的组合唯一约束，避免并发重复认领。 + +### 5.6 知识库共享 + +管理员通过 KnowledgeBaseGrant 授权： + +| 权限 | 能力 | +| --- | --- | +| read | 浏览和预览原文 | +| use | Agent 检索和消费 chunk | +| manage | 分类、重建、删除和文件维护 | +| export | 在范围内创建导出任务 | + +授权撤销后，新任务立即按新权限计算；已创建任务继续使用快照中的引用和版本。 + +## 6. 第五层：记忆库逻辑 + +### 6.1 记忆从哪里来 + +~~~mermaid +flowchart LR + A[QC 意见/人工修改/失败原因] --> B[PendingMemory] + B --> C[人工确认] + C --> D[Memory] + D --> E[绑定来源 Agent、版本和可见性] + E --> F[后续任务注入] +~~~ + +未确认记忆处于待处理状态，不进入有效 Agent 记忆上下文。 + +### 6.2 记忆与知识库同构 + +记忆同样拥有 owner_user_id、organization_id、visibility 和授权记录： + +| 范围 | 读取者 | 编辑者 | +| --- | --- | --- | +| private | 所有者及其 Agent | 所有者 | +| shared | 被授权用户 | 所有者和管理员 | +| global | 当前组织全部用户 | 管理员 | + +管理员可以查看、导出、授权、撤销、发布全局和恢复私有。用户只能读取自己的记忆、已授权记忆和全局记忆。 + +### 6.3 记忆注入 + +~~~text +任务用户/组织校验 + → 计算 allowed_memory_ids + → 过滤 active 状态、来源 Agent 和版本 + → 注入 Agent Runtime + → 写入任务快照 +~~~ + +记忆内容作为数据输入，优先级低于 Runtime 系统规则。任务创建后，撤销授权不会覆盖已有快照。 + +## 7. 第六层：Agent 定义和画布 + +### 7.1 Agent 定义 + +一个 Agent 至少包含： + +~~~text +name +role +rules + rules_version +content_tags +skill_bindings +kb_bindings +memory_scope +model_catalog_id +status +~~~ + +Agent 定义描述“它擅长什么”；画布节点描述“这次任务是否在这里执行它”。 + +### 7.2 画布 + +~~~text +Canvas.nodes = [{node_id, agent_id, enabled}] +Canvas.edges = [{from_node, to_node}] +~~~ + +节点表示执行实例，边表示锚点卡依赖。一个 Agent 可以放置多个节点，支持同类内容并行生成。 + +### 7.3 波次调度 + +~~~mermaid +flowchart TD + A[读取节点和边] --> B{存在环?} + B -- 是 --> X[拒绝运行并提示环路] + B -- 否 --> C[计算入度] + C --> D[找入度为0的节点] + D --> E[同一波次并行执行] + E --> F[完成后更新下游入度] + F --> G{还有节点?} + G -- 是 --> D + G -- 否 --> H[调度完成] +~~~ + +停用节点不进入执行波次，下游收到 skipped 状态。 + +### 7.4 融合 Agent + +融合 Agent 接收多个生产 Agent 的结构化结果，把不同写法合成一个自然段： + +~~~text +任务段 + + 心法结果 + + 钩子结果 + + 场景结果 + + 上游锚点 + → 融合正文 + → 统一锚点卡 +~~~ + +融合过程不拼接内部推理，不重复调用未授权知识，最终文本遵守任务的默认口语样式。 + +## 8. 第七层：Agent Runtime + +### 8.1 Runtime 负责什么 + +Runtime 是所有 Agent 的统一执行壳，负责： + +- 创建和恢复 AgentSession。 +- 发送模型请求和接收工具调用。 +- 记录 LLMCall、RunEvent、Span 和 Token。 +- 管理工具参数、审批和结果回放。 +- 执行输入/输出护栏。 +- 响应取消、超时和服务重启。 + +业务层负责任务内容，Runtime 负责执行可靠性。 + +### 8.2 会话数据 + +每个会话保存： + +~~~text +session_id +run_id / campaign_id / segment_id +agent_id / agent_name / phase +trace_id / parent_session_id +status / turn / max_turns +messages / tool_state +result_text / result_meta / error +~~~ + +消息历史属于当前 Session，不放在 Provider 全局上下文中。多个用户同时使用同一模型时，消息、权限和 Trace 仍然彼此分开。 + +### 8.3 Runtime 状态机 + +~~~mermaid +stateDiagram-v2 + [*] --> running + running --> waiting_approval: 工具需要审批 + waiting_approval --> running: 批准或拒绝 + running --> interrupted: 进程中断 + interrupted --> running: 恢复 + running --> completed: 输出通过护栏 + running --> failed: 模型/工具/护栏失败 + running --> cancelled: 收到取消请求 + completed --> [*] + failed --> [*] + cancelled --> [*] +~~~ + +### 8.4 工具调用 + +~~~text +模型提出 tool_call + → 校验工具是否注册 + → 校验参数是否为 JSON 对象 + → 判断是否需要人工审批 + → 执行工具 + → 写入工具结果 + → 继续模型循环 +~~~ + +工具调用有独立 span_id，并通过 parent_span_id 指向触发它的模型请求。 + +### 8.5 护栏 + +| 护栏 | 规则 | +| --- | --- | +| 输入 | 空输入、超长输入进入失败状态 | +| 工具 | 未注册工具和非法参数返回工具错误 | +| 输出 | 空输出、超长输出进入失败状态 | +| 轮次 | 达到最大轮次后结束并记录原因 | +| 取消 | 任务取消后不再发起新的模型请求 | + +## 9. 第八层：内容任务生产链路 + +### 9.1 从主题到任务段 + +~~~text +用户输入主题/导图 + → Coordinator 拆解 + → 生成 Segment 列表 + → 每段绑定标签、时间、目标 Agent + → 标记待确认项 + → 用户确认后进入 Run +~~~ + +### 9.2 单个内容段 + +一个 Segment 的最小输入： + +~~~text +content_tag +title +time_range +mindmap_node +product_ref +upstream_anchor_cards +agent_snapshot +allowed_kb_ids +allowed_memory_ids +model_snapshot +~~~ + +输出必须包含正文、引用列表、锚点卡、状态和运行 Trace。 + +### 9.3 内容段状态 + +~~~text +pending → running → qc → human_review → approved + ├→ rework → running + ├→ failed + └→ skipped +~~~ + +失败段不吞掉其他段；任务整体显示待处理失败，直到人工修复、重跑、跳过或停用。 + +## 10. 第九层：QC、人工审查和组合 + +### 10.1 四道 QC + +| 闸门 | 检查内容 | +| --- | --- | +| structure | 标题、时间、顺序、段落完整性 | +| content | 事实、引用、任务目标和内容覆盖 | +| style | 大白话、口播感、品牌语气和格式 | +| cross | 与上下游锚点、产品、概念和情绪曲线一致 | + +每道 QC 都要输出带状态的检查项。空检查列表不视为通过。 + +### 10.2 人工审查 + +QC PASS 只表示自动检查通过，内容仍进入人工审查。人工可以： + +- 通过。 +- 打回并填写意见。 +- 修改内容后重新质检。 +- 选择换模型重跑。 +- 选择调整任务切片重跑。 +- 跳过本段并让组合器显示缺段。 + +人工决定写入审查事件，并关联当前 Segment 和 Trace。 + +### 10.3 组合器 + +Composer 只读取人工通过的段落： + +~~~text +读取通过段落 + → 按画布和内容顺序排序 + → 对齐锚点卡 + → 检查全文一致性 + → 生成组合报告 + → 输出 Markdown/DOCX + → 写 Artifact 和下载地址 +~~~ + +存在缺段、跨段矛盾或总检失败时，Campaign 保持审查状态，不生成已交付状态。 + +## 11. 第十层：多用户并发隔离 + +### 11.1 调用归属键 + +所有运行和模型调用绑定： + +~~~text +organization_id +user_id +campaign_id +run_id +trace_id +span_id +session_id +~~~ + +同一模型被多个用户同时使用时，系统按 Session 组装消息，按用户和组织写入账单。 + +### 11.2 四层限制 + +| 层级 | 限制 | +| --- | --- | +| 用户 | 并发任务、Token、存储和导出额度 | +| 组织 | 总并发、总预算、总 Token | +| 模型 | Provider QPS、连接数、超时和重试 | +| 任务 | 同一 Campaign 一个活跃 Run | + +队列等待、限流、重试和取消写入 Trace。一个 Provider 的故障只影响绑定它的队列。 + +## 12. 第十一层：计费和用量 + +### 12.1 计量事件 + +每一次 AI 或存储行为追加一条 UsageEvent： + +~~~text +user_id +organization_id +run_id / trace_id +provider / model +service_type +quantity +pricing_version +status +idempotency_key +~~~ + +计量对象包括：LLM 输入/输出 Token、Embedding、OCR、Rerank、云存储和导出。 + +### 12.2 费用计算 + +~~~text +LLM 费用 = 输入 Token × 输入费率 + 输出 Token × 输出费率 +总费用 = LLM + Embedding + OCR + Rerank + 存储 + 导出 +~~~ + +费用使用调用时冻结的费率版本。Provider 未返回 Token 时，估算值必须标记为 estimated，不能直接作为已结算值。 + +### 12.3 配额检查 + +~~~text +创建任务前检查额度 + → 进入模型队列前检查并发 + → 调用返回后记录真实用量 + → 任务结束后完成结算 +~~~ + +支持 warn、soft_limit 和 hard_limit 三种策略。 + +## 13. 第十二层：云存储和导出 + +### 13.1 存储分工 + +| 数据 | 云对象存储 | 关系数据库 | +| --- | --- | --- | +| 原始文件 | 文件正文 | 哈希、版本、归属、对象键 | +| 文本快照 | 解析后的文本 | 版本和状态 | +| 向量索引 | 索引文件或托管向量库 | 索引版本和校验值 | +| 最终成稿 | Markdown/DOCX | Artifact 元数据 | +| Trace/账单导出 | ZIP/JSON/CSV | ExportJob 状态 | + +### 13.2 文件生命周期 + +~~~text +uploading → stored → indexed → active +active → superseded → recycle_bin → deleted +uploading → orphaned → deleted +~~~ + +对象键使用组织、用户、知识库、文件哈希和安全文件名，防止同名覆盖。数据库提交失败时对象保持临时状态，清理任务回收孤儿对象。 + +### 13.3 导出 + +导出包必须带 manifest.json，列出对象键、文件哈希、归属、分类、授权、Trace、账单范围、发起人和过期时间。下载通过短时效签名地址完成。 + +## 14. 第十三层：认证、RBAC 和审计 + +### 14.1 登录 + +~~~text +读取 Bearer Token + → 查询 Token 摘要 + → 检查 Session 是否撤销/过期 + → 检查用户状态 + → 解析组织和角色 + → 更新 last_seen_at +~~~ + +密码使用 PBKDF2-SHA256 派生摘要，Session 数据库存储 Token 摘要。 + +### 14.2 审计事件 + +以下事件必须记录操作者、目标对象、前后值、Trace、时间和结果： + +- 登录、退出和 Session 撤销。 +- 角色、组织和配额变化。 +- Provider/API Key、模型启停和费率变化。 +- 知识库/记忆库查看、下载、授权、撤销和全局发布。 +- 文件、索引、任务、产物和导出删除。 +- 账单结算和管理员调账。 +- 成人内容能力测试和标签发布。 + +## 15. 第十四层：数据模型最小集合 + +### 15.1 身份和权限 + +~~~text +Organization +AppUser / UserAccount +AuthSession +UserRoleBinding +~~~ + +### 15.2 Agent 和任务 + +~~~text +Agent +AgentSkill +AgentSkillBinding +Canvas +Campaign +CampaignRun +Segment +AgentSession +RunEvent +LLMCall +QCReport +Artifact +~~~ + +### 15.3 知识、记忆和授权 + +~~~text +KnowledgeBase +KnowledgeFile +KnowledgeCategory +KnowledgeBaseGrant +KnowledgeUsage +PendingMemory +Memory +MemoryGrant +~~~ + +### 15.4 模型、计费和云存储 + +~~~text +ModelProvider +ModelCatalog +ModelOrganizationGrant +ModelCapabilityTest +UsageEvent +UsageRate +UsageQuota +BillingAccount +UsageSettlement +BillingAdjustment +CloudObject +ExportJob +AccessAudit +~~~ + +## 16. 第十五层：API 逻辑边界 + +### 16.1 用户端 API + +~~~text +/api/auth/* +/api/models/available +/api/agents +/api/canvases +/api/kbs +/api/memories +/api/campaigns +/api/segments +/api/runs +/api/traces +/api/me/usage +/api/me/billing +~~~ + +每个接口都使用当前用户和组织上下文，资源查询按 owner、visibility 和 grant 过滤。 + +### 16.2 管理端 API + +~~~text +/api/admin/users +/api/admin/organizations +/api/admin/model-providers +/api/admin/models +/api/admin/models/{id}/capability-tests +/api/admin/knowledge-bases +/api/admin/memories +/api/admin/usage +/api/admin/billing +/api/admin/exports +/api/admin/audit +~~~ + +管理端接口要求管理权限；导出、密钥、计费调整和全局发布使用更细粒度权限。 + +## 17. 第十六层：从 0 到 1 的实施计划 + +### P0：建立可登录的工作区 + +1. 创建 Organization。 +2. 创建第一个 admin。 +3. 建立 AppUser、AuthSession 和角色表。 +4. 所有 API 统一接收用户和组织上下文。 +5. 首次启动完成认证状态检查。 + +验收：管理员可以登录、退出、撤销 Session，普通请求没有身份时进入认证流程。 + +### P1：建立资源边界 + +1. 给 Agent、知识库、记忆、任务、Trace 和产物补齐 owner/organization 字段。 +2. 建立 private/shared/global 规则。 +3. 建立统一 grant 表和权限判定服务。 +4. 为查看、使用、管理和导出分别设权限。 + +验收：用户之间的数据查询互相隔离，管理员可以审计跨用户访问。 + +### P2：建立管理端模型目录 + +1. Provider 只在管理端创建。 +2. 管理端发现并规范化模型。 +3. 建立 ModelCatalog、能力标签和费率版本。 +4. 用户端只读取 available 模型。 +5. 加入成人内容能力测试和回归版本。 + +验收：用户可以选择已开放模型，管理端可以停用模型和发布能力标签，历史任务快照保持原样。 + +### P3：建立知识库和记忆库 + +1. 上传文件到对象存储。 +2. 解析、分块、Embedding 和索引。 +3. AI 分类建议和人工确认。 +4. 建立知识消费锁。 +5. 建立 PendingMemory 到 Memory 的确认流程。 +6. 让记忆复用知识库的授权逻辑。 + +验收：用户只检索允许的知识/记忆，同一 Agent 不重复消费已用 chunk，其他 Agent 仍可使用。 + +### P4：建立 Agent Runtime + +1. 创建 AgentSession。 +2. 加载任务快照。 +3. 执行模型调用、工具调用和审批。 +4. 写入 LLMCall、RunEvent、Span 和 Trace。 +5. 支持取消、失败、重试和服务重启恢复。 + +验收：一次会话可以恢复；工具审批不会丢失；多用户上下文彼此隔离。 + +### P5：建立内容生产和交付 + +1. Coordinator 将导图拆成 Segment。 +2. 画布按拓扑波次调度。 +3. Production Agent 生成内容和锚点卡。 +4. 四道 QC 输出检查项。 +5. 人工通过、打回、重跑或跳过。 +6. Composer 组合通过段落并生成 Artifact。 + +验收：缺段和失败段有明确状态；只有通过人工审查的段落进入最终成稿。 + +### P6：建立计费、云存储和运营 + +1. 将 LLMCall、Embedding、OCR、存储和导出接入 UsageEvent。 +2. 建立 UsageRate、Quota、Settlement 和 Adjustment。 +3. 建立云对象版本、导出包和 manifest。 +4. 建立管理员总览和审计页面。 + +验收：费用可以回溯到用户、任务、Run、Trace、模型和 Agent；导出内容可按 manifest 恢复。 + +## 18. 一次完整运行示例 + +~~~text +用户 USER_A 登录 ORGANIZATION_X + → 选择管理员开放的 MODEL_CATALOG_01 + → 创建“今晚直播任务” + → 选择画布 CANVAS_01 + → Coordinator 拆出 8 个 Segment + → 任务快照冻结 Agent/规则/技能/知识/记忆/模型/费率 + → Runtime 为每段创建独立 Session + → 生产 Agent 检索允许的知识库 + → 当前 Agent 排除已经消费过的 chunk + → 输出正文、引用和锚点卡 + → 四道 QC 检查 + → 用户人工审查并通过 8 段 + → Composer 组合成 Markdown/DOCX + → Artifact 上传云存储 + → UsageEvent 记录 Token 和费用 + → Trace 页面回放整次运行 +~~~ + +如果某段失败： + +~~~text +记录失败原因 + → 释放 reserved chunk + → 其他段继续执行 + → 通知用户/管理员 + → 人工选择重试、换模型、改规则、调整切片或跳过 + → 重新质检并更新 Trace +~~~ + +## 19. 最终验收清单 + +### 19.1 身份和权限 + +- 首次启动可以创建管理员。 +- 用户端和管理端入口分离。 +- 用户只能读取自己的资源和有效授权资源。 +- 管理端跨用户操作都有审计。 + +### 19.2 模型 + +- Provider 只由管理端维护。 +- 用户只能选择开放模型目录。 +- 模型版本、能力标签和费率可追踪。 +- 成人内容能力测试有版本、断言、结果和回归记录。 + +### 19.3 知识和记忆 + +- 私有、共享、全局逻辑一致。 +- AI 分类建议可人工确认、修改和移动。 +- Agent 级消费锁生效。 +- 待确认记忆不会提前进入生产上下文。 + +### 19.4 运行和交付 + +- 任务快照保证运行可复现。 +- Agent Runtime 支持工具、审批、取消和恢复。 +- QC、人工审查和组合状态清晰。 +- 失败段不会伪装成成功成稿。 + +### 19.5 计费和云端 + +- 每次模型调用都有用户、组织、Run 和 Trace 归属。 +- 估算、计量和结算状态可区分。 +- 文件、向量、产物和导出包有哈希与版本。 +- 导出包带 manifest，可进行完整核对。 + +## 20. 结论 + +从 0 到 1 建设这套系统，先建立身份和数据边界，再接入受控模型，随后建设知识/记忆和 Runtime，最后接入任务生产、审查、组合、计费和云存储。 + +核心逻辑不是某个单独页面，而是下面这条可追溯闭环： + +~~~text +身份 +→ 资源权限 +→ 配置快照 +→ Agent 执行 +→ 知识/记忆引用 +→ 模型调用 +→ QC/人工决定 +→ 成稿产物 +→ 用量账单 +→ Trace/审计 +~~~ + +只要这条闭环稳定，后续增加更多 Agent、模型、知识库、用户和云存储容量，都可以沿着同一套规则扩展。 + +## 21. 提示工程落地补充（v6.1，已实现） + +提示工程不再作为散落在执行器里的字符串，而是作为独立的 `AgentPromptTemplate` 配置管理。模板包含： + +```text +name / desc +role_prompt / task_template +constraints[] / examples[] +output_schema / style +version / enabled / builtin +``` + +新任务创建时，Agent 快照同时冻结规则、技能、记忆、模型和提示模板版本。运行时按固定顺序组织上下文： + +```text +角色 +→ 任务模板 +→ 表达风格 +→ Agent 规则 +→ 模板约束 +→ Zero/One/Few-Shot 示例 +→ 技能、融合建议、记忆、上游锚点 +→ 知识库材料 +→ Runtime 硬规则 +→ 输出协议与 Schema +``` + +模板支持的变量包括 `{agent_name}`、`{agent_role}`、`{title}`、`{content_tag}`、`{time_range}`、`{mindmap_node}` 和 `{product_ref}`。未知变量保持原样，避免普通花括号被误替换。 + +输出协议当前用于锚点卡 JSON。运行器在正文落盘前执行轻量 Schema 校验，至少检查 JSON 对象、`required` 字段和字段类型；校验失败会释放本轮知识片段并进入重做/人工处理，不会把无效结果标记为已交付。 + +管理端新增 `/api/prompt-templates` CRUD 页面，Agent 管理页可以绑定启用模板。模板内容变化自动递增版本；被 Agent 使用的模板不能直接删除，内置模板只允许停用。旧任务使用冻结快照，不随模板后续修改漂移。 + +这部分把文章中的“角色 + 任务 + 约束 + 示例 + 结构化输出 + 测试闭环”映射到工作台，同时保留知识库来源边界、Agent 消费锁、锚点连续性、QC 和人工审查等既有硬规则。 + +### 21.1 任务契约：把业务目标锁进每一次生成 + +参考本地部署实践，任务不能只提交一段导图。新任务还要填写两个字段： + +```text +objective 本次任务唯一业务目标 +success_criteria 人工可以逐条判断的验收标准 +``` + +这两个字段会写入 `Campaign`，并在 `CampaignRun.config_snapshot.campaign_contract` 中冻结，同时记录导图哈希。它们贯穿 Coordinator 拆解、Segment 生成、四道 QC 和 Composer 总检： + +```text +业务目标 + 验收标准 + → 拆解时每段只服务一个目标 + → 生成时禁止脱离目标自行扩展 + → QC 判断目标覆盖和标准满足情况 + → 组合时核对全文是否仍然完成原目标 +``` + +旧任务缺少这两个字段时使用兼容默认值，不影响历史运行；新任务必须同时填写唯一目标和验收标准。目标与导图冲突时由人工确认，不由 Agent 猜测或偷偷扩展范围。 + +## 22. 模型目录落地补充（v6.2，已实现） + +Provider 与用户可选模型已经拆为两层： + +```text +ModelProvider（管理端连接信息、API Key、Base URL） + └── ModelCatalog（用户端可见模型、能力标签、费率版本、启用状态） +``` + +Provider 新增、编辑或同步模型清单时，系统会幂等写入 `ModelCatalog`；不再出现在 Provider 清单中的历史模型会被停用而不是物理删除，保证历史任务快照仍可追溯。用户端只访问 `GET /api/models/available`，返回模型目录 ID、显示名称、能力状态和费率版本，不返回 Provider 地址或密钥。 + +Agent 可以保存 `model_catalog_id`。服务端创建和更新 Agent 时会校验目录项、Provider 状态和真实模型名称，拒绝不存在、停用或不属于 Provider 清单的模型。任务快照同时记录目录项信息，Provider 配置变化不会覆盖历史运行。 + +管理端模型目录使用 `GET/PUT /api/admin/models`，Provider、模型发现、模型测试和默认模型配置统一收敛到管理权限；普通用户只能读取已启用目录。前端 Agent 管理页已从 Provider 列表切换为可用模型目录。 + +## 23. 资源边界与授权落地（v6.3 P1，已实现） + +本阶段把多用户隔离从设计约定落实为服务端统一判定。新增 `Organization`，并为 Agent、Canvas、Campaign、KnowledgeBase、PendingMemory、Memory、Artifact 和 AppUser 增加 `organization_id`、`owner_user_id`、`visibility`。新建资源默认绑定当前登录用户；普通用户提交的 `global/shared` 请求会被强制收敛为 `private`，只有管理员可以发布范围。 + +知识库和记忆库分别增加授权表： + +```text +KnowledgeBaseGrant(kb_id, user_id, permission) +MemoryGrant(memory_id, user_id, permission) +``` + +授权级别为 `read / use / manage / export`，其中 `use` 包含读取，`manage` 包含全部操作，`export` 只允许导出和读取。全局资源允许组织内用户读取和使用；共享资源必须命中有效授权；私有资源只对所有者和管理员可见。权限撤销后，新请求立即失效，历史任务仍由快照保留可追溯记录。 + +服务端所有知识库详情、上传、分类、索引、检索、消费释放和删除操作都经过统一访问辅助层；Agent 挂接知识库、融合 Agent、画布节点也会验证当前用户的使用权限。任务、Run、Agent Session、审查、组合和成稿下载/预览沿 Campaign 归属检查，避免通过关联 ID 绕过资源边界。成稿和待确认记忆在生成时继承任务的组织、所有者和可见性。 + +管理端授权接口： + +```text +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 +GET /api/admin/memories +POST /api/admin/memories/{id}/grants +DELETE /api/admin/memories/{id}/grants/{grant_id} +POST /api/admin/memories/{id}/publish-global +GET /api/auth/roles +PUT /api/auth/roles/{role} +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 +``` + +管理员可以查看所有知识库、记忆及授权对象；普通用户仍只调用用户端列表和检索接口。迁移采用幂等列补齐和 `create_all`，不删除原始文件、SQLite 数据、向量索引或历史成稿。当前已通过资源隔离、授权分级、旧功能回归和真实数据库启动验证。 + +## 24. 用量计量与账单落地（v6.4 P2/P3，已实现） + +本阶段把模型、向量和 OCR 的消耗统一纳入追加式 `UsageEvent` 账本。事件保存用户、组织、任务、Run、Segment、Trace、Agent、Provider、模型、服务类型、计量单位、输入/输出数量、费率版本、金额（人民币分）和幂等键；同一幂等键重复写入时复用原事件，不修改历史金额。 + +```text +LLMCall(user_id, organization_id, usage_event_id, billing_status) + └── UsageEvent(service_type=llm, unit=token) +Embedding 建库/重建/检索 ──> UsageEvent(service_type=embedding) +OCR 导图识别 ──> UsageEvent(service_type=ocr, unit=image) +``` + +模型目录中的 `input_rate / output_rate / rate_version` 在调用返回时复制到事件，费用使用整数分计算；Provider 未返回 Token 时保留 `estimated` 状态，不伪装成已测量值。运行记录保存 `user_id / organization_id`，管理员代运行时账单归属发起运行的账号，普通任务则继承任务所有者。 + +用户端接口为 `GET /api/usage/summary` 和 `GET /api/usage/events`，只返回当前账号在本组织内的事件；工作台新增“用量与账单”页面，支持日/月、服务类型筛选、Token/费用/事件统计和 Trace 明细。管理端接口为 `/api/admin/usage/summary`、`/api/admin/usage/events`、`/api/admin/quotas`，可按用户、模型、服务和周期审计，并通过配额接口配置 Token、金额、存储、并发上限及 `warn / soft_limit / hard_limit` 策略。 + +任务启动前执行配额检查；未配置配额时保持兼容，配置软/硬上限后达到 Token 或金额上限返回 429。`UsageQuota` 与事件账本使用唯一约束和索引，服务重启通过幂等迁移补齐，不影响既有任务、成稿、知识向量和 Trace。 + +## 25. 企业级双入口与权限边界（v6.5，已实现） + +参考 Microsoft 365/Entra 管理中心和 Keycloak 的通用模式，系统采用“同一身份、两个入口、服务端统一授权”的结构： + +```text +同一账号与组织 + ├── /app 用户工作台：全部业务能力，数据只显示本人/已授权/全局资源 + └── /admin 管理控制台：全部业务能力 + 全组织配置、授权、审计与访问控制 +``` + +管理员登录后默认进入 `/admin`，普通成员直接进入 `/app`。两个入口是严格隔离的路由：管理员访问 `/app`、普通成员访问 `/admin` 都会被入口守卫拦截，不显示另一门户内容，也没有门户切换或跳转按钮。两端共享认证会话和业务组件，但以账号角色决定唯一可进入的门户；服务端仍以 RBAC 和资源行级权限作为最终判定。 + +服务端权限按“入口 + 资源 + 操作”三层执行。用户端保留任务、Agent、画布、标签、技能、提示模板、知识库、记忆库、模型目录和用量账单等全部业务页面；其中 Agent、画布、标签、技能、模板、知识库、记忆和任务按本人/已授权/全局范围过滤，用户创建的资源默认为私有。Provider 连接、API Key、模型发现、模型目录费率与能力发布、全组织授权、配额和访问控制只在管理端执行。编辑角色可以管理自己的业务资源，审查角色执行审查动作，查看角色保持只读。前端入口隔离用于降低误操作，真实限制由中间件和资源访问层共同完成。 + +用户端与管理端共享登录会话和审计链，但使用不同导航、工作区标题、入口地址和 API 权限。用户端的“用量与账单”只查询当前用户事件，不展示配额编辑器；Token、金额、存储和并发配额只能由管理端配置。管理端可以查看全组织账单与资源，用户端只能查看本人、已授权和全局资源。两端后续可以拆成两个独立前端部署，不需要重写业务 API。 + +画布授权规则：`CanvasGrant` 是 Agent 流程的授权根。管理员向用户授予画布的 `read / use / manage / export` 权限后，画布节点中的 Agent 及其挂接知识库、确认记忆按同一流程范围提供查看或运行能力；该继承只覆盖查看和运行，不放大资源的编辑、删除或导出权限。用户在授权画布运行中产生的新记忆仍以当前用户为 owner、默认 private；管理员可以在管理端查看、导出并单独发布到全局。记忆库页面保留用于查看、确认和删除用户自己的记忆，但不再提供单独的用户授权入口。 + +### 25.1 自定义角色生命周期与中文权限目录（v6.6） + +角色不再是前端写死的四个选项。管理员在“访问控制 → 角色权限矩阵”中填写中文角色名称、职责说明并勾选权限，服务端生成内部角色标识；成员分配角色时只显示中文名称。系统内置“管理员、编辑、审查、只读”只能调整权限，不能删除；自定义角色没有成员使用时可以删除，仍被成员使用时先调整成员角色再删除。 + +```text +GET /api/auth/roles +POST /api/auth/roles +PUT /api/auth/roles/{role} +DELETE /api/auth/roles/{role} +``` + +权限目录的界面名称为“查看内容、内容编辑、内容审查、运行追踪、配置查看、系统配置、成员管理、管理控制台”。英文键只存在于服务端判定和数据库，不作为用户界面文案。每次请求都重新读取角色权限，角色调整不需要重启服务。 + +### 25.2 记忆元数据与索引加载规则（v6.6） + +记忆记录新增 `title`、`description`、`privacy`、`tags`、`timestamp`、`index_status`、`usage_count` 和 `last_used_at`。历史记录使用创建时间补齐沉淀日期。运行时只允许 `active + indexed` 的记忆进入 Agent 快照，并按使用次数和最近记录最多加载 50 条；人工修改记忆后标记 `needs_reindex`，重建索引完成后才重新参与生成。 + +记忆仍采用“待确认池 → 人工确认 → 已生效记忆 → Agent 画布运行”的闭环。下一阶段补充五层中文分类、总索引/子索引、来源证据、冲突候选、过期任务和经验升级技能的人工工作流。 +## 26. 点数余额替代成员 Token 配额（v6.7） + +平台统一使用点数作为 AI 使用余额，换算规则固定为 `10 点数 = 1 Token`。用户端只显示当前账号的点数余额、可折算 Token 数和自己的用量账单；点数余额低于 10 时，模型调用在进入 Provider 前直接停止。 + +管理端通过“用量与账单 → 用户点数”为本组织成员增加点数。充值动作写入 `PointTransaction(kind=credit)`，模型调用成功后按实际 Token（Provider 没有返回用量时按 1 Token 的最低计量）写入 `PointTransaction(kind=debit)`，使用幂等键避免重复扣点。点数账户和流水按 `user_id + organization_id` 隔离，管理员可以查看本组织余额和充值原因。 + +旧 `UsageQuota` 表与 `/api/admin/quotas` 接口仅为历史数据兼容保留，不再出现在页面，也不参与任务启动或模型调用的可用性判断。AI 是否可用只由点数余额决定；费用账单仍由 `UsageEvent` 记录，用于审计和成本统计，不等同于用户点数余额。 diff --git a/核心逻辑设计文档v6.md b/核心逻辑设计文档v6.md new file mode 100644 index 0000000..a508809 --- /dev/null +++ b/核心逻辑设计文档v6.md @@ -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 基础。 diff --git a/流程图.md b/流程图.md new file mode 100644 index 0000000..8e62c95 --- /dev/null +++ b/流程图.md @@ -0,0 +1,94 @@ +# 雅文内容创造工作台 · 流程图 + +## 图1 · 主流程（一次完整生产） + +```mermaid +flowchart TD + U["👩 你
输入：主题 / 导图 / 框架 / 思维"] --> C["主控 Agent 主编"] + C -->|"① 解析导图（读不准的词→列待确认清单问你）"| B["蓝图：生成任务单 TaskSpec
段划分+时间轴+产品节点+质检项"] + B -->|"② 按段派发（并行）"| S1["段Agent1 开场/心法"] + B -->|"② 按段派发（并行）"| S2["段Agent2 技法/场景"] + B -->|"② 按段派发（并行）"| S3["段Agent3 产品/销售"] + B -->|"② 按段派发（并行）"| SN["段AgentN 收尾/钩子"] + S1 -.->|只读| KB["📚 共享只读知识库
风格档案/导图库/原文库/备稿库/产品库/质检规则库"] + S2 -.->|只读| KB + S3 -.->|只读| KB + SN -.->|只读| KB + S1 --> Q1["质检闸 ①结构 ②内容 ③风格尺度 ④跨稿
（每件产物独立过4道，并行）"] + S2 --> Q1 + S3 --> Q1 + SN --> Q1 + Q1 -->|"FAIL → 打回原段重跑（带质检意见）"| S1 + Q1 -->|"FAIL → 打回原段重跑"| S2 + Q1 -->|"FAIL → 打回原段重跑"| S3 + Q1 -->|"FAIL → 打回原段重跑"| SN + Q1 -->|"✅ 4道全过"| H["👩 人工审查台（硬关卡）
逐段：产物+质检报告+差异高亮"] + H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S1 + H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S2 + H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S3 + H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| SN + H -->|"✅ 全部确认"| CM["组合Agent 总编
时间轴拼装→衔接/回指检查→生成说明"] + CM -->|"📄"| OUT["直播文稿.docx
六色标记 + clean.txt + 待确认清单"] +``` + +## 图2 · 哪里不对改哪里（三种修改路径） + +```mermaid +flowchart LR + subgraph 路径1["内容级打回（最常见）"] + A1["人工/质检发现段3不对"] --> A2["打回段3 + 写意见"] + A2 --> A3["段3 Agent：读取意见+自己记忆
重新生成段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偏好
（结构化：来源/内容/状态）"] + W -->|"质检FAIL"| M2["质检Agent记忆 L2错误模式
（同类错误下次直接查）"] + W -->|"你改规则"| M3["规则记忆 L1
（等同永久生效）"] + W -->|"你确认复盘（可选）"| M4["成功记忆 L4
（防噪音，不自动写）"] + M1 --> NEXT["下次该Agent运行时注入记忆
+ 规则文件 + 任务单切片"] + M2 --> NEXT + M3 --> NEXT + M4 --> NEXT + NEXT --> OUT2["产出质量随轮次提升
同一错误二次打回率↓"] + 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["📚 共享知识库
风格/框架/原文/备稿/产品/质检规则"] + TS["任务单 TaskSpec（主控产出）"] + end + A["段Agent"] -->|"读"| R1 + A -->|"读写"| M1 + A -->|"只读"| KB + A -->|"只读自己的切片"| TS + B["质检Agent"] -->|"读写"| M2["自己的错误模式记忆"] + B -->|"只读"| KB + B -->|"只读被检段产物"| TS +``` diff --git a/流程图v2.md b/流程图v2.md new file mode 100644 index 0000000..6983153 --- /dev/null +++ b/流程图v2.md @@ -0,0 +1,91 @@ +# 雅文内容创造工作台 · 流程图 v2 + +## 图1 · 主流程 v2（波次调度 + 锚点卡 + 组合总检 + 记忆确认） + +```mermaid +flowchart TD + U["👩 你：输入主题/导图/框架"] --> C["主控Agent
解析导图→任务单"] + C -->|"读不准的词→待确认清单问你"| TS["任务单 TaskSpec
段+时间轴+产品节点+质检项"] + TS --> W1["波次1（并行）
开场段Agent | 服务Agent预热"] + W1 --> W2["波次2（并行，读开场锚点卡）
心法段Agent | 技法段Agent"] + W2 --> W3["波次3（并行，读心法/技法锚点卡）
场景段Agent | 产品段Agent"] + W3 --> W4["波次4（读全部锚点卡）
收尾段Agent | 互动标记Agent"] + W4 --> AQ["每段产物 + 锚点卡AnchorCard"] + AQ --> QC["4道质检闸：结构/内容/风格尺度/跨稿
（质检报告逐条对证正文+锚点卡）"] + QC -->|"FAIL→打回原段"| AQ + QC -->|"✅全过"| HR["人工审查台（硬关卡）
逐段：产物+质检报告+锚点卡"] + HR -->|"🔁打回→意见生成记忆建议"| PM["记忆待确认池"] + HR -->|"✅全部确认"| CM["组合Agent
时间轴拼装→一致性总检(5项)"] + CM -->|"发现矛盾/回指断裂→打回对应段"| AQ + CM -->|"微衔接→缝合编辑（必须标记）"| OUT["直播文稿.docx（六色）
+组合报告+待确认清单"] + PM -->|"你确认→写入"| MEM["对应Agent记忆库"] + PM -->|"你拒绝/屏蔽→丢弃"| D["✖"] +``` + +## 图2 · 上下文契约：锚点卡机制（为什么段间不会"互不懂"） + +```mermaid +flowchart LR + subgraph 上游["段2 技法段Agent 产出"] + A2["段2 全文产物"] + AC2["锚点卡（一页摘要）
技法名：八爪鱼收紧术
痛点：干涩→油
情绪：高·演示"] + end + A2 --> AC2 + subgraph 下游["段3 产品段Agent（隔离）"] + B["只读：段2锚点卡
❌不读段2全文
❌不共享对话"] + OUT3["段3 产物：
'刚才教的八爪鱼收紧术，配这瓶油…'
✅回指一致"] + end + AC2 -->|"主控转交"| B + subgraph 组合["组合Agent 总检"] + CHK["一致性总检
回指断裂？矛盾？时间线？情绪曲线？钩子？"] + CHK -->|"发现断裂→打回对应段"| A2 + CHK -->|"通过→拼装交付"| DOC["📄 docx"] + end + OUT3 --> CHK +``` + +## 图3 · 哪里不对改哪里（三种路径 v2） + +```mermaid +flowchart LR + subgraph P1["路径1 内容级打回"] + A1["质检或审查发现段3不对"] --> A2["打回段3+意见"] + A2 --> A3["段3Agent：读意见+自己记忆+上游锚点卡
重新生成"] + 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["沉淀来源
打回意见 / 质检FAIL / 你改规则 / 复盘"] --> PM["📥 记忆待确认池
（每条：目标Agent+类型+内容+来源）"] + PM -->|"✅ 你确认"| W["写入对应Agent记忆库
L1规则/L2纠错/L3偏好/L4成功"] + PM -->|"❌ 拒绝"| DR["丢弃"] + PM -->|"🚫 屏蔽同类"| BL["该来源类型不再建议"] + W --> N["下次该Agent运行时注入
+规则+任务切片+上游锚点卡"] + N --> O["产出质量提升，同一错误二次打回率↓"] + style PM fill:#6d597a + style W fill:#2d6a4f +``` + +## 图5 · Agent 注册中心（随便添加，数量不限） + +```mermaid +flowchart TB + MAN["👩 你：Agent管理页"] -->|"新建向导5步"| NEW["新Agent
名称/职责/规则(rules.md模板+规则片段库)
输入来源(读谁锚点卡)/知识库勾选"] + MAN -->|"复制"| CP["复制现有Agent改名改规则
（如：复制场景段→青蛇白蛇段）"] + MAN -->|"停用"| DIS["停用（不派单，历史保留）"] + NEW --> REG["Agent注册中心
agent_id/类型/标签/版本历史"] + CP --> REG + REG -->|"拖进流水线"| PL["流水线编辑器
节点=Agent 边=依赖
质检挂载/执行顺序"] + PL -->|"主控按依赖分波次调度"| RUN["执行 ✅"] + style REG fill:#1d3557 +``` diff --git a/流程图v3.md b/流程图v3.md new file mode 100644 index 0000000..5168ee5 --- /dev/null +++ b/流程图v3.md @@ -0,0 +1,99 @@ +# 雅文内容创造工作台 · 流程图 v3（开放画布版） + +## 图1 · Agent 关系画布（核心：顺序可改/启停/任意连线） + +```mermaid +flowchart LR + M["主控Agent
导图→任务单"] --> A["开场 ●"] + A --> X1["心法Agent1 ●"] + A -.->|"可选读取"| X2["心法Agent2 ○停用
（不生成，跳过）"] + X1 --> AL["案例 ●"] + X1 --> J1["技法Agent1 ●"] + X1 --> J2["技法Agent2 ●
（同类可多个，并行）"] + X1 --> G["功法 ●"] + AL --> P["产品销售 ●
（挂：产品知识库）"] + J1 --> V["画面 ●"] + 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 + style M fill:#1d3557 + style CM fill:#6d597a +``` + +> 画布操作：拖节点改位置 ｜ 拉线改依赖 ｜ 节点开关启停 ｜ 模板保存复用 ｜ 任务开工时固化快照 + +## 图2 · 内容类型标签与派单（同类可多个） + +```mermaid +flowchart TD + MG["导图节点们"] -->|"主控标标签"| SEG["内容段
段1=心法·女人如水
段2=技法·八爪鱼收紧术
段3=技法·三指游龙
段4=产品销售·油
…（同类多段不合并）"] + SEG --> MATCH{"按标签匹配
启用中的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
☑风格档案 ☑产品知识库
☐原文库 ☐青蛇库"] + JA["技法Agent
☑风格档案 ☑直播原文库
☐产品库"] + QA["跨稿质检
☑备稿库 ☑框架库"] + end + KB1 --> PA + KB2 --> PA + KB1 --> JA + KB3 --> JA + PA -.->|"不可见"| X1["产品Agent查不到原文库/青蛇库"] + JA -.->|"不可见"| X2["技法Agent查不到产品库"] +``` + +## 图4 · 锚点卡契约 + 组合一致性总检（防"段间互不懂"） + +```mermaid +flowchart LR + subgraph 上游["技法段Agent 产出"] + A2["技法段全文"] + AC["锚点卡（一页）
技法名/痛点/情绪基调/钩子"] + end + A2 --> AC + subgraph 下游["产品销售Agent（隔离）"] + B["只读锚点卡
❌不读全文 ❌不共享对话"] + O3["'刚才教的八爪鱼收紧术配这瓶油…'✅"] + end + AC --> B + O3 --> CHK["组合Agent 一致性总检
矛盾/回指/时间线/情绪曲线/钩子"] + 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 +``` diff --git a/流程图v4.md b/流程图v4.md new file mode 100644 index 0000000..4972889 --- /dev/null +++ b/流程图v4.md @@ -0,0 +1,169 @@ +# 雅文内容创造工作台 · 流程图 v4（RAG 知识库版） + +## 图1 · RAG 知识库建库管道（导入即建，全自动） + +```mermaid +flowchart LR + F["素材文件
docx / srt / md / txt / json / 导图"] --> P1["① 导入
拖拽上传+进度条"] + P1 --> P2["② 格式解析
docx提取正文 / srt去时间戳 / json结构抽取"] + P2 --> P3["③ 清洗
去空行/提词备注/字幕断句合并"] + P3 --> P4["④ 分块
标题感知+语义边界 400-600字 重叠15%
元数据：库/文件/章节/序号"] + P4 --> P5["⑤ 向量化
BGE-M3 本地Embedding（离线，数据不出本机）"] + P5 --> P6["⑥ 入库
ChromaDB collection=知识库（天然隔离）"] + P6 --> P7["⑦ 检索测试页
输入query验证命中质量"] + style P6 fill:#1d3557 +``` + +## 图2 · Agent 取料（混合检索 + 引用溯源，只查挂接库） + +```mermaid +flowchart TD + A["生产Agent 生成请求"] --> Q["query构造
任务切片+上游锚点卡+检索意图"] + Q --> H{"混合检索
只在挂接的collection内"} + H -->|"向量 top-k"| V["BGE-M3 语义相似度"] + H -->|"关键词 top-k"| K["BM25 精确命中
（技法名/产品名/暗语）"] + V --> M["合并去重"] + K --> M + M --> R["可选：rerank重排"] + R --> S["引用溯源
每条带：库/文件/章节/原文块/相似度"] + S --> INJ["注入Agent上下文
（后台标注来源，正文不出现'知识库里说'）"] + INJ --> OUT["段产物"] + OUT --> QC["质检一键核对引用
选中一句→看引用→对证原文"] + 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
☑风格档案 ☑产品知识库"] + JA["技法Agent
☑风格档案 ☑直播原文库"] + 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
deepseek-chat / R1"] + M2["🟩 硅基流动 / 智谱GLM"] + M3["🟧 Kimi / 通义"] + M4["⬜ 本地 Ollama"] + end + subgraph 画布["画布节点（每Agent独立选模型）"] + A1["主控Agent 🟦DeepSeek-R1
（强推理：拆解/调度）"] + A2["心法Agent 🟩GLM
（文风对比）"] + A3["画面Agent 🟧Kimi
（文风对比）"] + A4["质检Agent 🟦DeepSeek-R1
（严格规则执行）"] + A5["组合Agent 🟦长上下文
（拼装+总检读全稿）"] + end + M1 --> A1 + M1 --> A4 + M1 --> A5 + M2 --> A2 + M3 --> A3 +``` + +## 图7 · 节点状态机（每个 Agent 工作状态清晰可见） + +```mermaid +flowchart LR + P["待派发 🟦灰"] --> R["生成中 🟦蓝
（显示模型+已耗时）"] + R --> Q["质检中 🟡黄
（显示第几道）"] + Q --> H["待人工审查 🟣紫"] + H -->|"✅通过"| A["已通过 🟢绿"] + H -->|"🔁打回"| RW["打回重做 🟠橙
（显示第几轮）"] + RW --> R + R -->|"生成失败"| F["⚠️失败 🔴红
（点击看原因）"] + 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{"可自动重试？
超时/限流/截断"} + RETRY -->|"是（最多2次）"| R1["指数退避重试"] + R1 -->|"成功"| OK["✅ 继续流程"] + R1 -->|"仍失败"| MAN + RETRY -->|"否（拒审/Key错误/余额不足）"| MAN["🔴 转人工
节点红标+通知中心提醒
（不静默、不假装成功）"] + MAN --> PANEL["失败处理面板
失败Agent/模型/错误原文/调用日志/输入上下文"] + PANEL --> ACT["人工修复动作"] + ACT -->|"🔁重试"| R1 + ACT -->|"🔄换模型"| M2["换模型重跑"] + ACT -->|"📝改规则"| R2["改rules.md重跑"] + ACT -->|"✂️调任务切片"| R3["改写段描述重跑"] + ACT -->|"⏭️跳过"| SK["跳过（组合注明缺段）"] + ACT -->|"⏸️停用"| D["停用节点"] + ACT --> MEM["填修复原因 → 记忆建议
→ 待确认池 → 沉淀防复发"] + style MAN fill:#7f1d1d,color:#fff + style MEM fill:#6d597a +``` diff --git a/流程图预览.html b/流程图预览.html new file mode 100644 index 0000000..9969644 --- /dev/null +++ b/流程图预览.html @@ -0,0 +1,122 @@ + + + + + +雅文内容创造工作台 · 流程图 + + + + +

雅文内容创造工作台 · 流程图

+
多 Agent 内容工厂：主控派单 → 环节生产 → 质检 → 人工审查 → 组合交付｜v1 ｜ 2026-08-25
+ +
+

图1 · 主流程（一次完整生产）核心图

+
+flowchart TD
+    U["👩 你
输入：主题 / 导图 / 框架 / 思维"] --> C["主控 Agent 主编"]
+    C -->|"① 解析导图（读不准的词→列待确认清单问你）"| B["蓝图：生成任务单 TaskSpec
段划分+时间轴+产品节点+质检项"]
+    B -->|"② 按段派发（并行）"| S1["段Agent1 开场/心法"]
+    B -->|"② 按段派发（并行）"| S2["段Agent2 技法/场景"]
+    B -->|"② 按段派发（并行）"| S3["段Agent3 产品/销售"]
+    B -->|"② 按段派发（并行）"| SN["段AgentN 收尾/钩子"]
+    S1 -.->|"只读"| KB["📚 共享只读知识库
风格档案/导图库/原文库/备稿库/产品库/质检规则库"]
+    S2 -.->|"只读"| KB
+    S3 -.->|"只读"| KB
+    SN -.->|"只读"| KB
+    S1 --> Q1["质检闸 ①结构 ②内容 ③风格尺度 ④跨稿
（每件产物独立过4道，并行）"]
+    S2 --> Q1
+    S3 --> Q1
+    SN --> Q1
+    Q1 -->|"FAIL → 打回原段重跑（带质检意见）"| S1
+    Q1 -->|"FAIL → 打回原段重跑"| S2
+    Q1 -->|"FAIL → 打回原段重跑"| S3
+    Q1 -->|"FAIL → 打回原段重跑"| SN
+    Q1 -->|"✅ 4道全过"| H["👩 人工审查台（硬关卡）
逐段：产物+质检报告+差异高亮"]
+    H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S1
+    H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S2
+    H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| S3
+    H -->|"🔁 打回（附意见→沉淀进该Agent记忆）"| SN
+    H -->|"✅ 全部确认"| CM["组合Agent 总编
时间轴拼装→衔接/回指检查→生成说明"]
+    CM -->|"📄"| OUT["直播文稿.docx
六色标记 + clean.txt + 待确认清单"]
+
+
+ +
+

图2 · 哪里不对改哪里（三种修改路径）核心图

+
+flowchart LR
+    subgraph 路径1["路径1 · 内容级打回（最常见）"]
+        A1["人工/质检发现段3不对"] --> A2["打回段3 + 写意见"]
+        A2 --> A3["段3 Agent：读取意见+自己记忆
重新生成段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
+
+
+ +
+

图3 · 记忆闭环（越用越懂 · 每Agent隔离）

+
+flowchart TD
+    R["打回意见 / 质检FAIL / 你改规则"] --> W{"写入触发"}
+    W -->|"人工打回"| M1["该段Agent记忆 L3偏好
（结构化：来源/内容/状态）"]
+    W -->|"质检FAIL"| M2["质检Agent记忆 L2错误模式
（同类错误下次直接查）"]
+    W -->|"你改规则"| M3["规则记忆 L1
（等同永久生效）"]
+    W -->|"你确认复盘（可选）"| M4["成功记忆 L4
（防噪音，不自动写）"]
+    M1 --> NEXT["下次该Agent运行时注入记忆
+ 规则文件 + 任务单切片"]
+    M2 --> NEXT
+    M3 --> NEXT
+    M4 --> NEXT
+    NEXT --> OUT2["产出质量随轮次提升
同一错误二次打回率↓"]
+    style M1 fill:#2d6a4f
+    style M2 fill:#1d3557
+    style M3 fill:#6d597a
+    style M4 fill:#7f5539
+
+
+ +
+

图4 · 上下文/记忆隔离边界

+
+flowchart TB
+    subgraph 隔离区["每个Agent的私有空间（互不可见）"]
+        R1["rules.md 规则文件"]
+        M1["记忆库（独立命名空间）"]
+        CTX["会话上下文（只含自己的任务切片）"]
+    end
+    subgraph 共享区["全Agent共享（只读）"]
+        KB["📚 共享知识库
风格/框架/原文/备稿/产品/质检规则"]
+        TS["任务单 TaskSpec（主控产出）"]
+    end
+    A["段Agent"] -->|"读"| R1
+    A -->|"读写"| M1
+    A -->|"只读"| KB
+    A -->|"只读自己的切片"| TS
+    B["质检Agent"] -->|"读写"| M2["自己的错误模式记忆"]
+    B -->|"只读"| KB
+    B -->|"只读被检段产物"| TS
+
+
+ + + + diff --git a/流程图预览v2.html b/流程图预览v2.html new file mode 100644 index 0000000..6c2c334 --- /dev/null +++ b/流程图预览v2.html @@ -0,0 +1,120 @@ + + + + + +雅文内容创造工作台 · 流程图 v2 + + + + +

雅文内容创造工作台 · 流程图 v2

+
Agent注册中心 · 波次调度 · 锚点卡契约 · 组合一致性总检 · 记忆人工确认｜B方案 ｜ 2026-08-25
+ +
+

图1 · 主流程 v2 核心图

+
+flowchart TD
+    U["👩 你：输入主题/导图/框架"] --> C["主控Agent
解析导图→任务单"]
+    C -->|"读不准的词→待确认清单问你"| TS["任务单 TaskSpec
段+时间轴+产品节点+质检项"]
+    TS --> W1["波次1（并行）
开场段Agent | 服务Agent预热"]
+    W1 --> W2["波次2（并行，读开场锚点卡）
心法段Agent | 技法段Agent"]
+    W2 --> W3["波次3（并行，读心法/技法锚点卡）
场景段Agent | 产品段Agent"]
+    W3 --> W4["波次4（读全部锚点卡）
收尾段Agent | 互动标记Agent"]
+    W4 --> AQ["每段产物 + 锚点卡AnchorCard"]
+    AQ --> QC["4道质检闸：结构/内容/风格尺度/跨稿
（质检报告逐条对证正文+锚点卡）"]
+    QC -->|"FAIL→打回原段"| AQ
+    QC -->|"✅全过"| HR["人工审查台（硬关卡）
逐段：产物+质检报告+锚点卡"]
+    HR -->|"🔁打回→意见生成记忆建议"| PM["记忆待确认池"]
+    HR -->|"✅全部确认"| CM["组合Agent
时间轴拼装→一致性总检(5项)"]
+    CM -->|"发现矛盾/回指断裂→打回对应段"| AQ
+    CM -->|"微衔接→缝合编辑（必须标记）"| OUT["直播文稿.docx（六色）
+组合报告+待确认清单"]
+    PM -->|"你确认→写入"| MEM["对应Agent记忆库"]
+    PM -->|"你拒绝/屏蔽→丢弃"| D["✖"]
+
+
+ +
+

图2 · 上下文契约：锚点卡机制 为什么段间不会"互不懂"

+
+flowchart LR
+    subgraph 上游["段2 技法段Agent 产出"]
+        A2["段2 全文产物"]
+        AC2["锚点卡（一页摘要）
技法名：八爪鱼收紧术
痛点：干涩→油
情绪：高·演示"]
+    end
+    A2 --> AC2
+    subgraph 下游["段3 产品段Agent（隔离）"]
+        B["只读：段2锚点卡
❌不读段2全文
❌不共享对话"]
+        OUT3["段3 产物：
'刚才教的八爪鱼收紧术，配这瓶油…'
✅回指一致"]
+    end
+    AC2 -->|"主控转交"| B
+    subgraph 组合["组合Agent 总检"]
+        CHK["一致性总检
回指断裂？矛盾？时间线？情绪曲线？钩子？"]
+        CHK -->|"发现断裂→打回对应段"| A2
+        CHK -->|"通过→拼装交付"| DOC["📄 docx"]
+    end
+    OUT3 --> CHK
+
+
+ +
+

图3 · 哪里不对改哪里（三种路径）

+
+flowchart LR
+    subgraph P1["路径1 内容级打回"]
+        A1["质检或审查发现段3不对"] --> A2["打回段3+意见"]
+        A2 --> A3["段3Agent：读意见+自己记忆+上游锚点卡
重新生成"]
+        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（人工确认后才沉淀）

+
+flowchart TD
+    SRC["沉淀来源
打回意见 / 质检FAIL / 你改规则 / 复盘"] --> PM["📥 记忆待确认池
（每条：目标Agent+类型+内容+来源）"]
+    PM -->|"✅ 你确认"| W["写入对应Agent记忆库
L1规则/L2纠错/L3偏好/L4成功"]
+    PM -->|"❌ 拒绝"| DR["丢弃"]
+    PM -->|"🚫 屏蔽同类"| BL["该来源类型不再建议"]
+    W --> N["下次该Agent运行时注入
+规则+任务切片+上游锚点卡"]
+    N --> O["产出质量提升，同一错误二次打回率↓"]
+    style PM fill:#6d597a
+    style W fill:#2d6a4f
+
+
+ +
+

图5 · Agent 注册中心（随便添加，数量不限）

+
+flowchart TB
+    MAN["👩 你：Agent管理页"] -->|"新建向导5步"| NEW["新Agent
名称/职责/规则(rules.md模板+规则片段库)
输入来源(读谁锚点卡)/知识库勾选"]
+    MAN -->|"复制"| CP["复制现有Agent改名改规则
（如：复制场景段→青蛇白蛇段）"]
+    MAN -->|"停用"| DIS["停用（不派单，历史保留）"]
+    NEW --> REG["Agent注册中心
agent_id/类型/标签/版本历史"]
+    CP --> REG
+    REG -->|"拖进流水线"| PL["流水线编辑器
节点=Agent 边=依赖
质检挂载/执行顺序"]
+    PL -->|"主控按依赖分波次调度"| RUN["执行 ✅"]
+    style REG fill:#1d3557
+
+
+ + + + diff --git a/流程图预览v3.html b/流程图预览v3.html new file mode 100644 index 0000000..b1fa111 --- /dev/null +++ b/流程图预览v3.html @@ -0,0 +1,126 @@ + + + + + +雅文内容创造工作台 · 流程图 v3 + + + + +

雅文内容创造工作台 · 流程图 v3

+
Agent关系画布 · 内容类型标签 · 多知识库隔离挂接 · 锚点卡契约 · 记忆人工确认｜2026-08-25
+ +
+

图1 · Agent 关系画布 核心：顺序可改/单独启停/任意连线

+
+flowchart LR
+    M["主控Agent
导图→任务单"] --> A["开场 ●"]
+    A --> X1["心法Agent1 ●"]
+    A -.->|"可选读取"| X2["心法Agent2 ○停用
（不生成，跳过）"]
+    X1 --> AL["案例 ●"]
+    X1 --> J1["技法Agent1 ●"]
+    X1 --> J2["技法Agent2 ●
（同类可多个，并行）"]
+    X1 --> G["功法 ●"]
+    AL --> P["产品销售 ●
（挂：产品知识库）"]
+    J1 --> V["画面 ●"]
+    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
+    style M fill:#1d3557
+    style CM fill:#6d597a
+
+
+ +
+

图2 · 内容类型标签与派单（同类可多个）

+
+flowchart TD
+    MG["导图节点们"] -->|"主控标标签"| SEG["内容段
段1=心法·女人如水
段2=技法·八爪鱼收紧术
段3=技法·三指游龙
段4=产品销售·油
…（同类多段不合并）"]
+    SEG --> MATCH{"按标签匹配
启用中的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 · 多知识库隔离挂接

+
+flowchart TB
+    subgraph 库区["📚 知识库（可建多个，互相隔离）"]
+        KB1["风格档案库"]
+        KB2["产品知识库"]
+        KB3["直播原文库"]
+        KB4["你建的库：青蛇白蛇素材库"]
+    end
+    subgraph Agent区["Agent 挂接配置（多选）"]
+        PA["产品销售Agent
☑风格档案 ☑产品知识库
☐原文库 ☐青蛇库"]
+        JA["技法Agent
☑风格档案 ☑直播原文库
☐产品库"]
+        QA["跨稿质检
☑备稿库 ☑框架库"]
+    end
+    KB1 --> PA
+    KB2 --> PA
+    KB1 --> JA
+    KB3 --> JA
+    PA -.->|"不可见"| X1["产品Agent查不到原文库/青蛇库"]
+    JA -.->|"不可见"| X2["技法Agent查不到产品库"]
+
+
+ +
+

图4 · 锚点卡契约 + 组合一致性总检 防段间互不懂

+
+flowchart LR
+    subgraph 上游["技法段Agent 产出"]
+        A2["技法段全文"]
+        AC["锚点卡（一页）
技法名/痛点/情绪基调/钩子"]
+    end
+    A2 --> AC
+    subgraph 下游["产品销售Agent（隔离）"]
+        B["只读锚点卡
❌不读全文 ❌不共享对话"]
+        O3["'刚才教的八爪鱼收紧术配这瓶油…'✅"]
+    end
+    AC --> B
+    O3 --> CHK["组合Agent 一致性总检
矛盾/回指/时间线/情绪曲线/钩子"]
+    CHK -->|"断裂→打回对应段"| A2
+    CHK -->|"微衔接→缝合标记"| D["📄 docx+组合报告"]
+
+
+ +
+

图5 · 记忆闭环（人工确认后才沉淀）

+
+flowchart TD
+    SRC["打回意见/质检FAIL/复盘"] --> PM["记忆待确认池"]
+    PM -->|"✅确认"| MEM["该Agent记忆库（隔离命名空间）"]
+    PM -->|"❌拒绝/🚫屏蔽"| D["✖"]
+    MEM --> INJ["下次运行时注入：规则+记忆+任务切片+上游锚点卡+挂接知识库"]
+    INJ --> BETTER["质量提升，二次打回率↓"]
+    style PM fill:#6d597a
+    style MEM fill:#2d6a4f
+
+
+ + + + diff --git a/流程图预览v4.html b/流程图预览v4.html new file mode 100644 index 0000000..9b175de --- /dev/null +++ b/流程图预览v4.html @@ -0,0 +1,201 @@ + + + + + +雅文内容创造工作台 · 流程图 v4 + + + + +

雅文内容创造工作台 · 流程图 v4

+
开放画布 + RAG知识库 + 26内容标签 + 锚点卡契约 + 记忆人工确认｜2026-08-25
+ +
+

图1 · RAG 知识库建库管道 导入即建，全自动

+
+flowchart LR
+    F["素材文件
docx / srt / md / txt / json / 导图"] --> P1["① 导入
拖拽上传+进度条"]
+    P1 --> P2["② 格式解析
docx提取正文 / srt去时间戳 / json结构抽取"]
+    P2 --> P3["③ 清洗
去空行/提词备注/字幕断句合并"]
+    P3 --> P4["④ 分块
标题感知+语义边界 400-600字 重叠15%
元数据：库/文件/章节/序号"]
+    P4 --> P5["⑤ 向量化
BGE-M3 本地Embedding（离线，数据不出本机）"]
+    P5 --> P6["⑥ 入库
ChromaDB collection=知识库（天然隔离）"]
+    P6 --> P7["⑦ 检索测试页
输入query验证命中质量"]
+    style P6 fill:#1d3557
+
+
+ +
+

图2 · Agent 取料（混合检索+引用溯源）

+
+flowchart TD
+    A["生产Agent 生成请求"] --> Q["query构造
任务切片+上游锚点卡+检索意图"]
+    Q --> H{"混合检索
只在挂接的collection内"}
+    H -->|"向量 top-k"| V["BGE-M3 语义相似度"]
+    H -->|"关键词 top-k"| K["BM25 精确命中
（技法名/产品名/暗语）"]
+    V --> M["合并去重"]
+    K --> M
+    M --> R["可选：rerank重排"]
+    R --> S["引用溯源
每条带：库/文件/章节/原文块/相似度"]
+    S --> INJ["注入Agent上下文
（后台标注来源，正文不出现'知识库里说'）"]
+    INJ --> OUT["段产物"]
+    OUT --> QC["质检一键核对引用
选中一句→看引用→对证原文"]
+    QC -->|"查无来源=FAIL"| A
+    style QC fill:#6d597a
+
+
+ +
+

图3 · 知识库隔离与 Agent 挂接

+
+flowchart TB
+    subgraph KB["📚 知识库（ChromaDB collection 物理隔离）"]
+        C1["风格档案库"]
+        C2["产品知识库"]
+        C3["直播原文库（73场SRT）"]
+        C4["备稿库（99篇）"]
+        C5["你建的库：青蛇白蛇素材库"]
+    end
+    subgraph AG["Agent 挂接（多选）"]
+        PA["产品销售Agent
☑风格档案 ☑产品知识库"]
+        JA["技法Agent
☑风格档案 ☑直播原文库"]
+    end
+    C1 --> PA
+    C2 --> PA
+    C1 --> JA
+    C3 --> JA
+    PA -.->|"查不到"| X["原文库/青蛇库"]
+    JA -.->|"查不到"| Y["产品库"]
+
+
+ +
+

图4 · Agent 关系画布（顺序可改/单独启停/任意连线）

+
+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大类 / ★核心13个）

+
+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 可选不同模型）新增

+
+flowchart LR
+    subgraph 模型池["模型注册（OpenAI 兼容，可同时挂多个）"]
+        M1["🟦 DeepSeek
deepseek-chat / R1"]
+        M2["🟩 硅基流动 / 智谱GLM"]
+        M3["🟧 Kimi / 通义"]
+        M4["⬜ 本地 Ollama"]
+    end
+    subgraph 画布["画布节点（每Agent独立选模型）"]
+        A1["主控Agent 🟦DeepSeek-R1
（强推理：拆解/调度）"]
+        A2["心法Agent 🟩GLM
（文风对比）"]
+        A3["画面Agent 🟧Kimi
（文风对比）"]
+        A4["质检Agent 🟦DeepSeek-R1
（严格规则执行）"]
+        A5["组合Agent 🟦长上下文
（拼装+总检读全稿）"]
+    end
+    M1 --> A1
+    M1 --> A4
+    M1 --> A5
+    M2 --> A2
+    M3 --> A3
+
+
+ +
+

图7 · 节点状态机 每个Agent工作状态清晰可见

+
+flowchart LR
+    P["待派发 🟦灰"] --> R["生成中 🟦蓝
（显示模型+已耗时）"]
+    R --> Q["质检中 🟡黄
（显示第几道）"]
+    Q --> H["待人工审查 🟣紫"]
+    H -->|"✅通过"| A["已通过 🟢绿"]
+    H -->|"🔁打回"| RW["打回重做 🟠橙
（显示第几轮）"]
+    RW --> R
+    R -->|"生成失败"| F["⚠️失败 🔴红
（点击看原因）"]
+    Q -->|"质检FAIL"| RW
+    F -->|"人工修复后重跑"| R
+    F -->|"人工跳过"| SK["跳过 ⬜灰斜线"]
+    F -->|"停用节点"| D["停用 ⬛暗"]
+    P -->|"上游停用"| SK
+    style F fill:#7f1d1d,color:#fff
+    style A fill:#14532d,color:#fff
+
+
+ +
+

图8 · 失败处理闭环 生成不出来 → 必提醒人工

+
+flowchart TD
+    FAIL["Agent 生成失败"] --> RETRY{"可自动重试？
超时/限流/截断"}
+    RETRY -->|"是（最多2次）"| R1["指数退避重试"]
+    R1 -->|"成功"| OK["✅ 继续流程"]
+    R1 -->|"仍失败"| MAN
+    RETRY -->|"否（拒审/Key错误/余额不足）"| MAN["🔴 转人工
节点红标+通知中心提醒
（不静默、不假装成功）"]
+    MAN --> PANEL["失败处理面板
失败Agent/模型/错误原文/调用日志/输入上下文"]
+    PANEL --> ACT["人工修复动作"]
+    ACT -->|"🔁重试"| R1
+    ACT -->|"🔄换模型"| M2["换模型重跑"]
+    ACT -->|"📝改规则"| R2["改rules.md重跑"]
+    ACT -->|"✂️调任务切片"| R3["改写段描述重跑"]
+    ACT -->|"⏭️跳过"| SK["跳过（组合注明缺段）"]
+    ACT -->|"⏸️停用"| D["停用节点"]
+    ACT --> MEM["填修复原因 → 记忆建议
→ 待确认池 → 沉淀防复发"]
+    style MAN fill:#7f1d1d,color:#fff
+    style MEM fill:#6d597a
+
+
+ + + + diff --git a/源码交付说明-2026-08-28.md b/源码交付说明-2026-08-28.md new file mode 100644 index 0000000..e69ee45 --- /dev/null +++ b/源码交付说明-2026-08-28.md @@ -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`。业务数据库和知识资料不包含在源码包内，需要在目标环境重新初始化或单独通过受控迁移交付。 diff --git a/源码包说明-20260914.md b/源码包说明-20260914.md new file mode 100644 index 0000000..c56fedd --- /dev/null +++ b/源码包说明-20260914.md @@ -0,0 +1,14 @@ +# 源码包说明 + +文件：`yawan-workbench-source-20260914.tar.gz` + +本包包含当前系统的服务端、前端、脚本、测试和设计文档源码。为避免泄露生产信息和生成超大压缩包，以下内容未包含： + +- 生产数据库、知识库原文、向量索引和运行日志； +- `.env.production` 生产配置和密钥； +- Python 虚拟环境、Node 依赖、前端构建缓存； +- 外接盘备份和 Python 缓存文件。 + +部署时请复制 `.env.production.example` 为 `.env.production`，再填写实际配置；运行数据目录需要由部署环境单独提供。 + +同目录的 `.sha256` 文件用于校验压缩包完整性。 diff --git a/源码包说明.md b/源码包说明.md new file mode 100644 index 0000000..d08a352 --- /dev/null +++ b/源码包说明.md @@ -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/`。 diff --git a/用户使用手册.html b/用户使用手册.html new file mode 100644 index 0000000..e8422dc --- /dev/null +++ b/用户使用手册.html @@ -0,0 +1,260 @@ + + + + + +私域Agent · 用户使用手册 + + + +
+ +
+ +

私域Agent · 用户使用手册

+

导图进，成稿出。多智能体协作的内容生产中枢。

+
适用版本 v0.12026 年 8 月阅读时间约 10 分钟
+
+ +
+ 目录 +
    +
  1. 第一次使用：登录
    2. +
  2. 核心流程：从一段导图到一份成稿
    3. +
  3. 任务看板：生成、审查、暂停与删除
    4. +
  4. 知识库：导入、分类、编辑与迁移
    5. +
  5. Agent 画布与全局总监
    6. +
  6. Agent / 技能库 / 提示模板
    7. +
  7. 模型管理与点数
    8. +
  8. 用量账单 / 运营看板 / 日志与记忆
    9. +
  9. 访问控制：成员与权限
    10. +
  10. 常见问题 FAQ
    11. +
+
+ + +

1第一次使用：登录

+

拿到账号后，两分钟内进入工作台。

+
+
    +
  1. 打开系统地址（管理员提供），页面右侧是登录表单。
    2. +
  2. 输入用户名和密码 → 点「登录」。密码连续输错 5 次会锁定 15 分钟，这是防暴力破解保护。
    3. +
  3. 进入总览页。左侧导航栏是你能用的全部功能；没有权限的菜单不会出现。
    4. +
+
登录状态 12 小时有效，超时后系统会提示重新登录，正在生成的任务不会因此中断。
+
+ + +

2核心流程：从一段导图到一份成稿

+

整个系统就为这一条流水线服务，看懂它就学会了 80%。

+
+ ① 新建任务
贴导图 / 传文件→ + ② AI 拆解
导图变内容段→ + ③ 开始生成
Agent 流水线→ + ④ 审查
通过 / 打回→ + ⑤ 合稿交付
下载成稿 +
+
+
    +
  1. 新建任务：进「任务看板」→ 点「＋ 新建任务」。唯一必填的是任务目标；导图可以粘贴文字、上传图片（自动 OCR）或导入 txt/md 文档。验收标准留空系统会自动生成，也可以点「✦ AI 建议验收标准」再手动修改。
    2. +
  2. 拆解：点「创建并拆解」，AI 把导图编译成一个个内容段（每段有主题、时间区间、负责的 Agent）。拆解是幂等的，重复点击不会产生两套段落。
    3. +
  3. 生成：点「▶ 开始生成」。各 Agent 按画布流程依次生产每一段，全程自动质检；画布设置了「全局总监」时，每段完成后总监还会审核是否跑偏。
    4. +
  4. 审查：生成完的段落转「人工审查」。你逐段看，通过或打回（打回时写意见，Agent 会按你的意见重新生成，并自动沉淀记忆建议）。
    5. +
  5. 交付：全部段落通过后自动合稿，任务看板里可预览全文并下载。
    6. +
+
点「开始生成」前系统会自动做点数预检：预估本次成本并与余额比对（含 20% 缓冲），余额不够会直接告知差额，不会让你跑到一半失败。
+
+ + +

3任务看板：生成、审查、暂停与删除

+

这里是日常主战场。

+
+

生成中你能做的事

+ + + + + +
操作说明
⏸ 暂停当前这段做完后停下（不浪费已花的点数），已完成段落保留。
▶ 继续从暂停处恢复，只跑剩余段落。
■ 停止终止本次运行，已生成内容保留在各自段落里。
+

关于失败与重试

+

单段失败（如网络超时）会自动重试，不会影响其他段。点数不足、Key 失效这类"不会自愈"的错误会触发熔断：整个任务立即停止并明确告知原因——点数类会提示「请联系管理员增加点数」，限流类会建议「更换其他模型」。

+

删除任务

+

任务卡片上的「删除任务」按钮可删除任务及其全部段落记录（运行中/暂停中的任务需先停止）。删除需二次确认，成稿文件保留在服务器供审计。

+
+ + +

4知识库：导入、分类、编辑与迁移

+

Agent 写稿的"素材库"。检索是语义级的，不依赖关键词完全匹配。

+
+
    +
  1. 建库：知识库页 → 新建知识库。你建的库默认只有你自己和管理员可见。
    2. +
  2. 导入：选中新库 → 「📤 上传到当前分类」，支持 docx / srt / md / txt / json / jsonl，单文件 ≤ 50MB。
    3. +
  3. 分类：可在库内建多级分类树（一级/二级/任意层级）；「✦ AI 自动分类」会让 AI 预分类，你点「确认 AI 分类」生效。
    4. +
  4. 文件级管理：每个已导入文件支持 ✏️ 在线编辑（txt/md，保存自动重建索引）、移到其他知识库、删除（向量索引同步清理）。
    5. +
  5. 挂给 Agent：到「Agent 管理」编辑某个 Agent 的「挂接知识库」，它生产时只从挂接的库里检索素材。
    6. +
+
「Agent 已消费知识」列表里的锁定片段：同一 Agent 不会重复使用同一段素材（避免成稿重复）；点「重新开放」可让它再次可用。
+
+ + +

5Agent 画布与全局总监

+

画布决定"谁先写、谁后写、谁质检、谁兜底"。

+
+
    +
  1. 编排：从左侧 Agent 列表点击添加节点，拖动连线建立上下游（上游写完 → 下游开工）。节点可停用（跳过不执行）。
    2. +
  2. 保存：任务创建时会冻结画布快照，之后改画布不影响已建任务。
    3. +
  3. 全局总监（防跑偏）：工具栏选择一个 Agent 作为总监，三档模式任选—— + + + + + +
    模式行为
    疑似跑偏才审（默认）质检发现问题或重做过一轮才送审，省点数。
    每段必审每段生成完总监都过目，重要交付用。
    仅记录不拦截总监意见只记录，不自动重做。
    + 总监判定跑偏后会给出「原因 + 拉回指导」，该段自动带指导重做一次；重做仍跑偏则转人工，不会无限烧点数。
    4. +
+
+ + +

6Agent / 技能库 / 提示模板

+

三件套决定每段内容的生产方式。

+
+ +
三者创建时都有「✦ AI 帮我创建」入口：用大白话描述需求（像跟同事交代），AI 产出结构化草稿并自动做冲突检测（口语↔书面、要求自相矛盾、跨资源冲突等），确认后入库。
+
+ + +

7模型管理与点数

+

模型是"发动机"，点数是"油钱"。

+
+

模型管理

+

每个 Provider（如 DeepSeek）配 API Key（存 macOS 钥匙串，不落库）+ 模型列表。可用「测试连通」验证；可指定全局默认模型。遇到「限流」提示时，来这里切换其他模型即可。

+

点数规则

+ + + + + + +
项目规则
折算10 点数 = 1 Token，按实际用量扣。
余额余额本身不设上限；低于 10 点数暂停 AI 调用。
发放管理员在「用量与账单 → 用户点数」发放，支持三档快捷按钮：一档 1千万 / 二档 1亿 / 三档 10亿，也可手动输入任意数额。
预检启动生成前自动预估成本，余额需覆盖预估 + 20% 缓冲，不足时明确告知差额。
+
+ + +

8用量账单 / 运营看板 / 日志与记忆

+
+ +
+ + +

9访问控制：成员与权限

+
+

添加成员

+
    +
  1. 用户名 ≥ 3 个字符（字母/数字/._-，不支持中文）；初始密码 ≥ 10 个字符。表单下方有实时提示，两项都 ✓ 时「添加成员」按钮才会亮。
    2. +
  2. 选角色：只读 / 审查 / 编辑 / 管理员，或自定义角色。
    3. +
+

权限体系

+

16 项细分权限分 4 组（内容生产 / 资产与知识 / 数据与洞察 / 系统管理），在「角色权限矩阵」逐项勾选。保存后立即生效；编辑期间页面轮询不会覆盖你未保存的勾选。

+
资源可见性：用户自建的知识库/技能/模板/任务默认私有（仅本人+管理员）；需要共享时在资源授权里给指定成员授权，或「发布全局」对全组织可见。
+
+ + +

10常见问题 FAQ

+
点「开始生成」提示"点数不足"怎么办？
提示里会写明预估需要多少、你还差多少。联系管理员在「用量与账单」按档位发放点数后重试即可。
+
生成中报"模型服务商限流（429）"？
系统已自动放慢重试并尝试切换备用 Provider。若持续失败，到「模型管理」更换其他模型再重新运行失败段。
+
拆解失败 / 一直提示"任务还没有内容段"？
拆解依赖 AI 调用。先到「模型管理」点「测试连通」确认当前模型可用（API Key 失效或服务商地域限制都会导致失败），修正后回到任务页重新点拆解。导图不需要上传文件，粘贴文字大纲即可。
+
为什么我看不到某个知识库 / 任务？
资源默认私有，只有创建者和管理员可见。需要协作请让管理员在「访问控制 → 资源授权」给你授权，或将资源发布为全局。
+
密码忘了 / 账号被锁？
联系管理员在「访问控制」重置密码（≥10 位）。连续输错 5 次锁 15 分钟，等待即可自动解锁。
+
段落打回后 Agent 会按我的意见改吗？
会。打回时填写的意见会直接注入下一轮生成；同时系统自动生成「记忆建议」，你在记忆库确认后，这类偏好以后所有任务都生效。
+
同一个错误反复出现，Agent 会不会一直烧点数？
不会。点数/密钥类错误触发熔断停止整个任务；每次运行还有 240 轮模型调用总预算，总监重做也最多 1 次，多重防线防失控。
+
数据安全吗？
API Key 存 macOS 钥匙串；密码加盐哈希；登录有防爆破锁定；每 6 小时自动备份且保留 14 份，管理员可一键「恢复演练」验证备份可用。
+ +
+ 私域Agent · 内容生产中枢 —— 遇到本手册未覆盖的问题，联系管理员或截图报错信息反馈。 +
+ +
+ + diff --git a/用户操作手册.md b/用户操作手册.md new file mode 100644 index 0000000..5598814 --- /dev/null +++ b/用户操作手册.md @@ -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 帮我创建”。在“基本信息”填写名称、职责类型、描述和内容标签；在“知识与技能”绑定知识库、分类和技能；在“工具与模型”选择模型；需要统一表达风格时在“数字人身份”绑定已生效的数字人。点击“保存草稿”，检查无误后点击“发布（冻结配置）”。回到列表看到状态为“启用”，即可在内容段中选择。修改配置后要重新保存并发布。 diff --git a/系统功能逻辑文档.html b/系统功能逻辑文档.html new file mode 100644 index 0000000..165552a --- /dev/null +++ b/系统功能逻辑文档.html @@ -0,0 +1,232 @@ + + + + + +私域Agent · 系统功能逻辑全览 + + +
+

私域Agent · 系统功能逻辑全览

+

版本 2026-09-01 · 对应源码 ~/Desktop/yawan-workbench（135 文件）· 访问地址 https://agent.pducv.cn

+ +
目录
+1. 系统一句话总览 +2. 角色与权限体系 +3. 核心工作流：从导图到成稿 +4. 内容生产流水线（Agent 体系） +5. 知识库与向量检索（RAG） +6. AI 辅助创建 +7. 质检体系 +8. 审查与打回循环 +9. 点数与成本控制 +10. 模型管理 +11. 数据隔离与安全 +12. 运维与守护 +13. 关键表与端点速查 +14. 已知边界与注意事项 +
+ +

1. 系统一句话总览

+
+

私域Agent 是一个多 Agent 协作的内容生产工作台：雅文老师粘贴一节课的导图/框架，系统自动把它拆解成带时间轴的内容段任务单，派发给不同职能的 Agent（开场/心法/技法/销售/收尾…）逐段生成直播口播稿，每段经过 4 道独立质检和人工确认，最终组合成一份六色标注的 Word 成稿。

+

FastAPI 后端React 前端Chroma 向量库DeepSeek 等模型本地 Whisper 转写Cloudflare 隧道

+
+ +

2. 角色与权限体系

+ + + + + + +
角色能力典型用途
admin 管理员全部功能 + 用户管理 + 点数发放 + 运营看板系统所有者（雅文管理员）
editor 编辑建任务/生成/审查/知识库管理内容生产主力
reviewer 审校只读 + 审查通过/打回质检把关人
viewer 访客仅被授权的资源只读外部查看
+

双层隔离：①资源层——每条数据带 organization_id / owner_user_id / visibility(private|shared|global)，任何读写都过 can_access() 判定；②权限层——16 项权限按角色矩阵控制端点访问。实测：普通用户看不到他人的任务/私有知识库/私有 Agent，越权读直接 403/404。

+ +

3. 核心工作流：从导图到成稿

+
+
① 新建任务目标+导图+选时长
→
+
② AI 拆解后台执行，1-2 分钟
→
+
③ 清单增删改不满意可提意见重拆
→
+
④ 逐段生成每段一个 Agent
→
+
⑤ 4 道质检自动
→
+
⑥ 人工确认通过/打回/跳过
→
+
⑦ 组合成稿六色 docx
+
+
+

① 新建任务（TasksPage）

+

填写任务目标（必填）、验收标准（可 ✦AI 建议）、粘贴导图文本（或 📷 图片 OCR / 📄 导入文档）、选画布、选直播总时长（30分钟~4小时，AI 拆解会强制各段时间总和=所选时长）、可选关联上一天任务（跨稿对账）。

+

② AI 拆解（后台异步）

+

点「创建并拆解」立即返回，页面显示「⏳ 拆解中…」。主控 Agent 把导图逐节点编译成内容段任务单：每段带标题/内容标签/时间范围/产品引用；读不准的地方进「待确认清单」，压缩决策写进 notes。拆解产出为空或失败时明确报原因，不产生空任务。

+

③ 清单增删改查

+

拆出的每段可直接编辑（标题/标签/时长/产品，失焦自动保存，标签变了自动重新匹配 Agent）；可删除（生成过的也能删，删光回可拆解态）；可新增段落；整体不满意可「✦ 对清单提意见，AI 重新拆解」——意见最高优先级注入，AI 重出整份任务单。

+

④⑤⑥ 逐段生成 + 质检 + 人工确认

+

点「▶ 开始生成（第 1 段）」只派发第一个 Agent；生成+质检完自动停在「待审查」，人工通过后按钮变「▶ 生成下一段」继续派发。打回 = 自动按意见重新生成（见 §8）。也有传统「一键跑完全部」模式（暂停/继续/停止/删除齐全）。

+

⑦ 组合成稿

+

全部段通过后「📄 组合成稿」：跨段一致性检查 → 拼接 → 生成六色标注 docx（可下载/在线预览）。

+
+ +

4. 内容生产流水线（Agent 体系）

+ + + + + + + + +
Agent（内置 14 个）角色职责
主控 Agentcoordinator导图 → 任务单拆解（支持用户修改意见注入）
开场段 / 心法段 / 技法段 / 收尾段 / 钩子段 Agentproduction按内容标签生产对应段落正文（挂知识库检索生成）
产品销售 Agentproduction产品植入段（挂产品信息+销售逻辑库）
结构 / 内容 / 风格尺度 / 跨稿 质检qc ×4四门独立质检（见 §7）
组合 Agentcomposer跨段衔接检查 + 成稿组合
风格顾问 / 产品顾问adviser辅助咨询
+

Agent 三要素：规则（rules，可版本化）、提示模板（可挂 PromptTemplate）、知识库（kb_ids，检索素材来源）。画布（Canvas）把 Agent 编排成节点图，任务可绑定画布；画布可设全局总监 Agent（on_drift 疑似跑偏才审 / always 每段必审 / monitor 只记录）——跑偏的段自动重做 1 次，仍偏转人工。融合生成：一段可挂多个融合 Agent 共同产出。Agent 三件套支持「✦ AI 帮我创建」（见 §6）。

+ +

5. 知识库与向量检索（RAG）

+
+
+

六库定稿（v5 来源级清洗）

+ + + + + + + + +
库块数内容
心法8,912性观念/性心理/亲密关系
技法3,565手法/前戏/高潮教学
功法5,941凯格尔/盆底肌/控精训练
情欲内容727角色扮演/SM/性幻想
产品信息49产品成分/用法
销售逻辑2,43898 场真实直播稿全链路
+
+
+

上传与建索引

+

三种方式：📁整个文件夹（含多层子文件夹，拖拽或选择，自动打 zip）、📤单/多文件、API。

+

支持格式：md/txt/docx/srt/json/jsonl/pdf + 音视频（mp4/mov/mp3/wav 等 12 种 → ffmpeg 抽音轨 → 本地 Whisper 中文转写 → 语义分段）。

+

处理链：清洗（去时间轴/乱码/去重）→ 分块（口播稿 2200 字聚合）→ bge-small-zh 向量化 → Chroma HNSW 索引（独立 rag_worker 子进程执行，规避主进程性能塌陷，8 秒级检索）。

+

多级分类：手动分类 + ✦AI 自动分类（建议→确认制）+ 跨库移动文件。

+
+
+
+

检索逻辑（生成时自动发生）

+

search_kbs：向量 top-k 候选 → 剔除该 Agent 已消费片段（防重复引用）→ 关键词重排（命中 +0.15）→ 取 top-k。每段生成预留（reserve）知识片段：正文+锚点落盘才标记 consumed；失败/打回自动释放（available）可再次被检索。所有引用带 文件名/标题/原文摘录 写入 references，前端可逐条溯源核对。

+
+ +

6. AI 辅助创建

+
+

Agent / 技能 / 提示模板 三个页面都有「✦ AI 帮我创建」：用户一句大白话描述 → 系统先检索知识库（6 库全查，取最相关的 8 块注入 prompt）→ 模型输出受控 JSON 草稿（名称/规则/指令/建议）→ 用户在表单确认修改后才正式创建。草稿带 _meta：所用模型、Token 消耗、耗时、引用了哪 8 条知识（库名+文件+摘录）。

+

另有 冲突检测：创建/修改时扫描 15 组互斥词对（口语↔书面、简短↔详细…），重名/高相似名称、跨资源单侧冲突，以 warning 展示不阻断。

+
+ +

7. 质检体系（4 门全开）

+ + + + + + +
门检查什么典型 FAIL
structure 结构锚点卡 7 字段完整（核心概念/技法/产品引用/金句/情绪基调/结尾钩子/时长）锚点缺失字段
content 内容是否扣题、知识引用是否真实、有没有编造内容与导图节点脱节
style 风格尺度雅文口播风（大白话/单段流）、内容尺度书面腔、结构模板化
cross 跨稿与上一天任务的衔接、重复度与昨日金句重复
+

质检不过 → 自动重试最多 2 轮（失败意见注入下轮 prompt「本轮必须修复」）→ 仍不过转 rework 等人工。产物三件套：正文（口语单段流）+ 锚点卡（结构化 JSON）+ 引用来源。

+
+ +

8. 审查与打回循环

+
+ + + + + + + +
操作发生什么
✅ 通过段 → approved；全部通过后任务变「可合成」
🔁 打回 + 意见立即自动重做：意见写入段落并以「用户打回意见（最高优先级，必须逐条落实）」注入新 prompt → 重新生成+质检 → 回到待审查；意见同时沉淀为该 Agent 的 L3 待确认记忆
⏭️ 跳过段 → skipped，不参与合成
🔁 重试 / 重试+记原因失败段重跑；原因沉淀为 L2 待确认记忆
🗑 删除段落任何状态可删（已交付除外），生成派发自动跳过
+

所有打回/修复原因都会进入「记忆库」的待确认池（L2 修复经验 / L3 偏好），管理员确认后写入 Agent 长期记忆——系统会越用越懂雅文的要求。运行轨迹页可看每个会话的轮次/工具调用/错误，工具调用支持人工批准/拒绝（human-in-the-loop）。

+
+ +

9. 点数与成本控制

+
+

计量：1 点数 = 10 Token。点数余额本身不设上限；发放三档：一档 1,000 万 / 二档 1 亿 / 三档 10 亿（管理员在用量与账单页一键发放，也可手动输入）。

+

启动预检（硬性）：开始生成前估算本次成本（按本组织近 200 次真实 LLM 用量外推，无历史用保守常量），余额须覆盖「预估 + 20% 缓冲」，不足直接 409 拦截并中文提示。任务页展示预估 Token/点数/耗时和估算来源。

+

运行中熔断：点数耗尽、鉴权失败、区域限制类错误 → 立即停止整个任务（继续跑只是白烧）；瞬时错误（网络抖动）继续跑。

+

API 限流四层防护：429 自动退避重试（读 Retry-After + 抖动，最多 2 次）→ 自动 failover 换 Provider → 单任务 240 轮调用预算熔断 → 中文错误提示（建议换模型）。看板隔离：运营看板不显示点数余额，普通用户只看自己的任务/用量。

+
+ +

10. 模型管理

+
+

多 Provider 多模型：API Key 存 macOS 钥匙串（secret_store，库文件里只有密文引用）；连通性测试一键验证；全局默认模型设置；每个 Agent 可单独指定 Provider/模型（不指定则用全局默认）；故障自动转移：主模型连续失败自动切到备选 Provider。当前主力：DeepSeek（v4-flash / v4-pro）。

+
+ +

11. 数据隔离与安全

+
+

认证：用户名密码登录，Token 会话 12 小时；防爆破：(IP,用户名) 5 次失败锁 15 分钟，单 IP 30 次锁 15 分钟。

+

授权：资源级 can_access（组织+归属+可见性+分级授权 use/manage/export）+ 角色权限矩阵双保险；已实测：跨用户任务/库/Agent 均不可见，越权 403/404。

+

备份：每 6 小时自动备份，保留 14 份；密钥类一律不入库（钥匙串）；上传有类型白名单 + 路径穿越防护 + zip 炸弹防护。

+
+ +

12. 运维与守护

+
+ + + + + + + + +
组件机制
公网入口https://agent.pducv.cn（域名→Cloudflare→命名隧道 yawan-workbench，地址永久固定）
隧道常驻launchd 服务 com.yawan.cloudflared：崩溃自动重启 + 开机自启 + 4 条冗余连接
后端守护~/bin/yawan-guard.sh 每 60 秒巡检，挂了自动拉起
任务队列持久化队列：租约 5 分钟 / 重试 3 次 / 死信队列可重放
巡检告警5 分钟巡检：磁盘 <2GB、失败段超 30 分钟、点数 <1000 告警；告警去重 10 分钟
审计LLMCall（每次模型调用：模型/耗时/Token/状态）、UsageEvent（计费事件）、RunEvent（运行轨迹）、Trace 全链路追踪
+
+ +

13. 关键表与端点速查

+
+
+

核心数据表

+

appuser 用户 · campaign 任务（含 duration_minutes）· segment 内容段（状态机：pending→running→qc→human_review→approved/rework/failed/skipped）· campaignrun 运行（支持暂停/断点/取消）· agent / agentskill / prompttemplate · knowledgebase / knowledgefile / knowledgecategory · knowledgeusage 知识消费 · canvas 画布 · llmcall / usageevent / runevent 审计 · memory / pendingmemory 记忆 · artifact 成稿 · notification 通知

+
+
+

主要端点（158 个中的关键）

+

POST /campaigns 建任务（带时长）
+POST /campaigns/{id}/parse 后台拆解（可带 advice 重拆）
+PUT/DELETE /campaigns/{id}/segments/{sid} 改/删段
+POST /campaigns/{id}/segments 新增段
+POST /campaigns/{id}/run 全量生成 · /run-step 逐段生成
+POST /campaigns/{id}/pause|resume 暂停/断点续跑
+POST /segments/{sid}/review 审查（reject 即自动重做）
+POST /segments/{sid}/fix 重试/换模型/改规则
+POST /campaigns/{id}/compose 合成
+GET/POST /kbs... 知识库/导入/文件夹导入/检索
+POST /ai-assist/draft AI 辅助创建（KB 检索注入）

+
+
+ +

14. 已知边界与注意事项

+
+

① 电脑需开机——系统跑在本机 Mac 上，关机即公网不可达（长期方案可迁轻量云服务器）。② 音视频转写耗时——1 小时视频约 20-40 分钟本地转写，属正常。③ 每段生成 3-5 分钟——生成+4 道质检是真实 LLM 调用，页面自动刷新无需盯着。④ 质检多轮 rework——质检判定未达标会自动重试 2 轮再转人工，属设计行为，人工再打回会带意见重做。⑤ ngrok 已退役——如遇旧地址打不开，一律用 agent.pducv.cn。⑥ 测试知识库——「检测用知识库」已删除，Agent 已重新挂载正式六库。

+
+

私域Agent · 雅文老师内容生产中枢 · 内部文档

+ diff --git a/设计文档v1.md b/设计文档v1.md new file mode 100644 index 0000000..c8a52ca --- /dev/null +++ b/设计文档v1.md @@ -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//segments//` 每个段一个目录，产物独立文件；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 全部手动确认，你倾向哪种？ diff --git a/设计文档v2.md b/设计文档v2.md new file mode 100644 index 0000000..22878db --- /dev/null +++ b/设计文档v2.md @@ -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 敲实） diff --git a/设计文档v3.md b/设计文档v3.md new file mode 100644 index 0000000..dcac8cf --- /dev/null +++ b/设计文档v3.md @@ -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 个内容标签（开场/心法/案例/技法/功法/产品销售/画面/场景/收尾/钩子/互动）够用吗？还要加哪些？（比如"答疑/弹幕互动"要不要独立标签？） diff --git a/设计文档v4.md b/设计文档v4.md new file mode 100644 index 0000000..7021336 --- /dev/null +++ b/设计文档v4.md @@ -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 个之外的可选标签（转场/预告/见证/冷知识/共鸣/安全提示/产品回指/情绪/氛围/答疑/双主播/毛边/仪式）需要保留哪些？还是全部预置（可以停用不显示）？ diff --git a/设计文档v5-系统设计.md b/设计文档v5-系统设计.md new file mode 100644 index 0000000..b98f7dc --- /dev/null +++ b/设计文档v5-系统设计.md @@ -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 注入 | diff --git a/设计文档v6-用户端管理端云化与计费设计.md b/设计文档v6-用户端管理端云化与计费设计.md new file mode 100644 index 0000000..67fbcd0 --- /dev/null +++ b/设计文档v6-用户端管理端云化与计费设计.md @@ -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 和审计，不用于给用户充值。 diff --git a/项目核心逻辑功能业务总结-20260915.md b/项目核心逻辑功能业务总结-20260915.md new file mode 100644 index 0000000..2e6b840 --- /dev/null +++ b/项目核心逻辑功能业务总结-20260915.md @@ -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 还是更多渠道接入，都应继续守住三条底线： + +> **内容有证据、执行有边界、过程可审计。**