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 还是更多渠道接入，都应继续守住三条底线： + +> **内容有证据、执行有边界、过程可审计。**