版本 2026-09-01 · 对应源码 ~/Desktop/yawan-workbench（135 文件）· 访问地址 https://agent.pducv.cn
私域Agent 是一个多 Agent 协作的内容生产工作台：雅文老师粘贴一节课的导图/框架，系统自动把它拆解成带时间轴的内容段任务单，派发给不同职能的 Agent（开场/心法/技法/销售/收尾…）逐段生成直播口播稿，每段经过 4 道独立质检和人工确认，最终组合成一份六色标注的 Word 成稿。
FastAPI 后端React 前端Chroma 向量库DeepSeek 等模型本地 Whisper 转写Cloudflare 隧道
| 角色 | 能力 | 典型用途 |
|---|---|---|
| admin 管理员 | 全部功能 + 用户管理 + 点数发放 + 运营看板 | 系统所有者（雅文管理员） |
| editor 编辑 | 建任务/生成/审查/知识库管理 | 内容生产主力 |
| reviewer 审校 | 只读 + 审查通过/打回 | 质检把关人 |
| viewer 访客 | 仅被授权的资源只读 | 外部查看 |
双层隔离：①资源层——每条数据带 organization_id / owner_user_id / visibility(private|shared|global)，任何读写都过 can_access() 判定；②权限层——16 项权限按角色矩阵控制端点访问。实测：普通用户看不到他人的任务/私有知识库/私有 Agent，越权读直接 403/404。
填写任务目标（必填）、验收标准（可 ✦AI 建议）、粘贴导图文本（或 📷 图片 OCR / 📄 导入文档）、选画布、选直播总时长（30分钟~4小时，AI 拆解会强制各段时间总和=所选时长）、可选关联上一天任务（跨稿对账）。
点「创建并拆解」立即返回，页面显示「⏳ 拆解中…」。主控 Agent 把导图逐节点编译成内容段任务单：每段带标题/内容标签/时间范围/产品引用；读不准的地方进「待确认清单」，压缩决策写进 notes。拆解产出为空或失败时明确报原因，不产生空任务。
拆出的每段可直接编辑（标题/标签/时长/产品，失焦自动保存，标签变了自动重新匹配 Agent）；可删除（生成过的也能删，删光回可拆解态）；可新增段落；整体不满意可「✦ 对清单提意见，AI 重新拆解」——意见最高优先级注入，AI 重出整份任务单。
点「▶ 开始生成（第 1 段）」只派发第一个 Agent；生成+质检完自动停在「待审查」，人工通过后按钮变「▶ 生成下一段」继续派发。打回 = 自动按意见重新生成（见 §8）。也有传统「一键跑完全部」模式（暂停/继续/停止/删除齐全）。
全部段通过后「📄 组合成稿」：跨段一致性检查 → 拼接 → 生成六色标注 docx（可下载/在线预览）。
| Agent（内置 14 个） | 角色 | 职责 |
|---|---|---|
| 主控 Agent | coordinator | 导图 → 任务单拆解（支持用户修改意见注入） |
| 开场段 / 心法段 / 技法段 / 收尾段 / 钩子段 Agent | production | 按内容标签生产对应段落正文（挂知识库检索生成） |
| 产品销售 Agent | production | 产品植入段（挂产品信息+销售逻辑库） |
| 结构 / 内容 / 风格尺度 / 跨稿 质检 | qc ×4 | 四门独立质检（见 §7） |
| 组合 Agent | composer | 跨段衔接检查 + 成稿组合 |
| 风格顾问 / 产品顾问 | adviser | 辅助咨询 |
Agent 三要素：规则（rules，可版本化）、提示模板（可挂 PromptTemplate）、知识库（kb_ids，检索素材来源）。画布（Canvas）把 Agent 编排成节点图，任务可绑定画布；画布可设全局总监 Agent（on_drift 疑似跑偏才审 / always 每段必审 / monitor 只记录）——跑偏的段自动重做 1 次，仍偏转人工。融合生成：一段可挂多个融合 Agent 共同产出。Agent 三件套支持「✦ AI 帮我创建」（见 §6）。
| 库 | 块数 | 内容 |
|---|---|---|
| 心法 | 8,912 | 性观念/性心理/亲密关系 |
| 技法 | 3,565 | 手法/前戏/高潮教学 |
| 功法 | 5,941 | 凯格尔/盆底肌/控精训练 |
| 情欲内容 | 727 | 角色扮演/SM/性幻想 |
| 产品信息 | 49 | 产品成分/用法 |
| 销售逻辑 | 2,438 | 98 场真实直播稿全链路 |
三种方式：📁整个文件夹（含多层子文件夹，拖拽或选择，自动打 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，前端可逐条溯源核对。
Agent / 技能 / 提示模板 三个页面都有「✦ AI 帮我创建」：用户一句大白话描述 → 系统先检索知识库（6 库全查，取最相关的 8 块注入 prompt）→ 模型输出受控 JSON 草稿（名称/规则/指令/建议）→ 用户在表单确认修改后才正式创建。草稿带 _meta：所用模型、Token 消耗、耗时、引用了哪 8 条知识（库名+文件+摘录）。
另有 冲突检测：创建/修改时扫描 15 组互斥词对（口语↔书面、简短↔详细…），重名/高相似名称、跨资源单侧冲突，以 warning 展示不阻断。
| 门 | 检查什么 | 典型 FAIL |
|---|---|---|
| structure 结构 | 锚点卡 7 字段完整（核心概念/技法/产品引用/金句/情绪基调/结尾钩子/时长） | 锚点缺失字段 |
| content 内容 | 是否扣题、知识引用是否真实、有没有编造 | 内容与导图节点脱节 |
| style 风格尺度 | 雅文口播风（大白话/单段流）、内容尺度 | 书面腔、结构模板化 |
| cross 跨稿 | 与上一天任务的衔接、重复度 | 与昨日金句重复 |
质检不过 → 自动重试最多 2 轮（失败意见注入下轮 prompt「本轮必须修复」）→ 仍不过转 rework 等人工。产物三件套：正文（口语单段流）+ 锚点卡（结构化 JSON）+ 引用来源。
| 操作 | 发生什么 |
|---|---|
| ✅ 通过 | 段 → approved；全部通过后任务变「可合成」 |
| 🔁 打回 + 意见 | 立即自动重做：意见写入段落并以「用户打回意见（最高优先级，必须逐条落实）」注入新 prompt → 重新生成+质检 → 回到待审查；意见同时沉淀为该 Agent 的 L3 待确认记忆 |
| ⏭️ 跳过 | 段 → skipped，不参与合成 |
| 🔁 重试 / 重试+记原因 | 失败段重跑；原因沉淀为 L2 待确认记忆 |
| 🗑 删除段落 | 任何状态可删（已交付除外），生成派发自动跳过 |
所有打回/修复原因都会进入「记忆库」的待确认池（L2 修复经验 / L3 偏好），管理员确认后写入 Agent 长期记忆——系统会越用越懂雅文的要求。运行轨迹页可看每个会话的轮次/工具调用/错误，工具调用支持人工批准/拒绝（human-in-the-loop）。
计量：1 点数 = 10 Token。点数余额本身不设上限；发放三档：一档 1,000 万 / 二档 1 亿 / 三档 10 亿（管理员在用量与账单页一键发放，也可手动输入）。
启动预检（硬性）：开始生成前估算本次成本（按本组织近 200 次真实 LLM 用量外推，无历史用保守常量），余额须覆盖「预估 + 20% 缓冲」，不足直接 409 拦截并中文提示。任务页展示预估 Token/点数/耗时和估算来源。
运行中熔断：点数耗尽、鉴权失败、区域限制类错误 → 立即停止整个任务（继续跑只是白烧）；瞬时错误（网络抖动）继续跑。
API 限流四层防护：429 自动退避重试（读 Retry-After + 抖动，最多 2 次）→ 自动 failover 换 Provider → 单任务 240 轮调用预算熔断 → 中文错误提示（建议换模型）。看板隔离：运营看板不显示点数余额，普通用户只看自己的任务/用量。
多 Provider 多模型：API Key 存 macOS 钥匙串（secret_store，库文件里只有密文引用）；连通性测试一键验证；全局默认模型设置；每个 Agent 可单独指定 Provider/模型（不指定则用全局默认）；故障自动转移：主模型连续失败自动切到备选 Provider。当前主力：DeepSeek（v4-flash / v4-pro）。
认证：用户名密码登录，Token 会话 12 小时；防爆破：(IP,用户名) 5 次失败锁 15 分钟，单 IP 30 次锁 15 分钟。
授权：资源级 can_access（组织+归属+可见性+分级授权 use/manage/export）+ 角色权限矩阵双保险；已实测：跨用户任务/库/Agent 均不可见，越权 403/404。
备份：每 6 小时自动备份，保留 14 份；密钥类一律不入库（钥匙串）；上传有类型白名单 + 路径穿越防护 + zip 炸弹防护。
| 组件 | 机制 |
|---|---|
| 公网入口 | 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 全链路追踪 |
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 通知
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 检索注入）
① 电脑需开机——系统跑在本机 Mac 上，关机即公网不可达（长期方案可迁轻量云服务器）。② 音视频转写耗时——1 小时视频约 20-40 分钟本地转写，属正常。③ 每段生成 3-5 分钟——生成+4 道质检是真实 LLM 调用，页面自动刷新无需盯着。④ 质检多轮 rework——质检判定未达标会自动重试 2 轮再转人工，属设计行为，人工再打回会带意见重做。⑤ ngrok 已退役——如遇旧地址打不开，一律用 agent.pducv.cn。⑥ 测试知识库——「检测用知识库」已删除，Agent 已重新挂载正式六库。
私域Agent · 雅文老师内容生产中枢 · 内部文档