233 lines
20 KiB
HTML
233 lines
20 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||
<title>私域Agent · 系统功能逻辑全览</title>
|
||
<style>
|
||
:root { --page:#f7f8fa; --card:#fff; --ink:#18181a; --ink2:#55585f; --ink3:#8a8f98;
|
||
--jade:#1F6B52; --jade2:#2E8B6A; --jade-soft:rgba(31,107,82,.10);
|
||
--gold:#C4A962; --line:#e3e7f1; --r:10px; }
|
||
* { margin:0; padding:0; box-sizing:border-box; }
|
||
body { background:var(--page); color:var(--ink); font:14px/1.7 "Inter","Noto Sans SC",-apple-system,"PingFang SC",sans-serif; }
|
||
.wrap { max-width:1080px; margin:0 auto; padding:40px 32px 80px; }
|
||
h1 { font-size:26px; font-weight:700; letter-spacing:-.02em; }
|
||
.sub { color:var(--ink2); margin:6px 0 28px; font-size:13px; }
|
||
h2 { font-size:18px; font-weight:650; margin:36px 0 14px; padding-left:12px; border-left:4px solid var(--jade); }
|
||
h3 { font-size:14px; font-weight:650; margin:20px 0 8px; color:var(--jade); }
|
||
p { margin:8px 0; color:var(--ink2); }
|
||
.card { background:var(--card); border:1px solid var(--line); border-radius:var(--r); padding:18px 20px; margin:10px 0; }
|
||
table { width:100%; border-collapse:collapse; font-size:12.5px; margin:10px 0; background:#fff; border-radius:var(--r); overflow:hidden; }
|
||
th { background:#f0f3f0; text-align:left; padding:9px 12px; font-weight:650; border-bottom:2px solid var(--line); white-space:nowrap; }
|
||
td { padding:8px 12px; border-bottom:1px solid var(--line); vertical-align:top; }
|
||
tr:last-child td { border-bottom:0; }
|
||
code { background:var(--jade-soft); color:var(--jade); padding:1px 6px; border-radius:5px; font-size:12px; font-family:ui-monospace,Menlo,monospace; }
|
||
.flow { display:flex; flex-wrap:wrap; gap:8px; align-items:center; margin:12px 0; }
|
||
.flow .step { background:#fff; border:1.5px solid var(--jade); color:var(--jade); border-radius:9px; padding:7px 13px; font-size:12.5px; font-weight:600; }
|
||
.flow .step small { display:block; font-weight:400; color:var(--ink3); font-size:10.5px; }
|
||
.flow .arr { color:var(--gold); font-weight:700; }
|
||
.tag { display:inline-block; padding:2px 9px; border-radius:20px; font-size:11px; font-weight:600; margin:2px; }
|
||
.tag.g { background:var(--jade-soft); color:var(--jade); }
|
||
.tag.y { background:rgba(196,169,98,.15); color:#8a7433; }
|
||
.tag.r { background:rgba(215,85,85,.12); color:#b04a4a; }
|
||
.tag.b { background:rgba(69,104,207,.12); color:#4568cf; }
|
||
.two { display:grid; grid-template-columns:1fr 1fr; gap:12px; }
|
||
@media (max-width:760px){ .two{grid-template-columns:1fr} }
|
||
.note { background:#fffbe9; border:1px solid #efe3b0; border-radius:var(--r); padding:12px 16px; font-size:12.5px; color:#7a6a2f; margin:10px 0; }
|
||
.toc { columns:2; column-gap:28px; font-size:13px; }
|
||
.toc a { color:var(--jade); text-decoration:none; display:block; padding:3px 0; break-inside:avoid; }
|
||
.toc a:hover { text-decoration:underline; }
|
||
kbd { background:#eef1ee; border:1px solid var(--line); border-bottom-width:2px; border-radius:5px; padding:1px 6px; font-size:11px; }
|
||
</style>
|
||
</head>
|
||
<body><div class="wrap">
|
||
<h1>私域Agent · 系统功能逻辑全览</h1>
|
||
<p class="sub">版本 2026-09-01 · 对应源码 ~/Desktop/yawan-workbench（135 文件）· 访问地址 https://agent.pducv.cn</p>
|
||
|
||
<div class="card"><b style="font-size:13px">目录</b><div class="toc">
|
||
<a href="#s1">1. 系统一句话总览</a>
|
||
<a href="#s2">2. 角色与权限体系</a>
|
||
<a href="#s3">3. 核心工作流：从导图到成稿</a>
|
||
<a href="#s4">4. 内容生产流水线（Agent 体系）</a>
|
||
<a href="#s5">5. 知识库与向量检索（RAG）</a>
|
||
<a href="#s6">6. AI 辅助创建</a>
|
||
<a href="#s7">7. 质检体系</a>
|
||
<a href="#s8">8. 审查与打回循环</a>
|
||
<a href="#s9">9. 点数与成本控制</a>
|
||
<a href="#s10">10. 模型管理</a>
|
||
<a href="#s11">11. 数据隔离与安全</a>
|
||
<a href="#s12">12. 运维与守护</a>
|
||
<a href="#s13">13. 关键表与端点速查</a>
|
||
<a href="#s14">14. 已知边界与注意事项</a>
|
||
</div></div>
|
||
|
||
<h2 id="s1">1. 系统一句话总览</h2>
|
||
<div class="card">
|
||
<p><b>私域Agent</b> 是一个<b>多 Agent 协作的内容生产工作台</b>：雅文老师粘贴一节课的导图/框架，系统自动把它拆解成带时间轴的内容段任务单，派发给不同职能的 Agent（开场/心法/技法/销售/收尾…）逐段生成直播口播稿，每段经过 4 道独立质检和人工确认，最终组合成一份六色标注的 Word 成稿。</p>
|
||
<p style="margin-top:10px"><span class="tag g">FastAPI 后端</span><span class="tag g">React 前端</span><span class="tag g">Chroma 向量库</span><span class="tag y">DeepSeek 等模型</span><span class="tag y">本地 Whisper 转写</span><span class="tag b">Cloudflare 隧道</span></p>
|
||
</div>
|
||
|
||
<h2 id="s2">2. 角色与权限体系</h2>
|
||
<table>
|
||
<tr><th>角色</th><th>能力</th><th>典型用途</th></tr>
|
||
<tr><td><b>admin</b> 管理员</td><td>全部功能 + 用户管理 + 点数发放 + 运营看板</td><td>系统所有者（雅文管理员）</td></tr>
|
||
<tr><td><b>editor</b> 编辑</td><td>建任务/生成/审查/知识库管理</td><td>内容生产主力</td></tr>
|
||
<tr><td><b>reviewer</b> 审校</td><td>只读 + 审查通过/打回</td><td>质检把关人</td></tr>
|
||
<tr><td><b>viewer</b> 访客</td><td>仅被授权的资源只读</td><td>外部查看</td></tr>
|
||
</table>
|
||
<p><b>双层隔离</b>：①资源层——每条数据带 <code>organization_id / owner_user_id / visibility(private|shared|global)</code>，任何读写都过 <code>can_access()</code> 判定；②权限层——16 项权限按角色矩阵控制端点访问。实测：普通用户看不到他人的任务/私有知识库/私有 Agent，越权读直接 403/404。</p>
|
||
|
||
<h2 id="s3">3. 核心工作流：从导图到成稿</h2>
|
||
<div class="flow">
|
||
<div class="step">① 新建任务<small>目标+导图+选时长</small></div><div class="arr">→</div>
|
||
<div class="step">② AI 拆解<small>后台执行，1-2 分钟</small></div><div class="arr">→</div>
|
||
<div class="step">③ 清单增删改<small>不满意可提意见重拆</small></div><div class="arr">→</div>
|
||
<div class="step">④ 逐段生成<small>每段一个 Agent</small></div><div class="arr">→</div>
|
||
<div class="step">⑤ 4 道质检<small>自动</small></div><div class="arr">→</div>
|
||
<div class="step">⑥ 人工确认<small>通过/打回/跳过</small></div><div class="arr">→</div>
|
||
<div class="step">⑦ 组合成稿<small>六色 docx</small></div>
|
||
</div>
|
||
<div class="card">
|
||
<h3>① 新建任务（TasksPage）</h3>
|
||
<p>填写任务目标（必填）、验收标准（可 ✦AI 建议）、粘贴导图文本（或 📷 图片 OCR / 📄 导入文档）、选画布、<b>选直播总时长</b>（30分钟~4小时，AI 拆解会强制各段时间总和=所选时长）、可选关联上一天任务（跨稿对账）。</p>
|
||
<h3>② AI 拆解（后台异步）</h3>
|
||
<p>点「创建并拆解」立即返回，页面显示「⏳ 拆解中…」。主控 Agent 把导图逐节点编译成内容段任务单：每段带标题/内容标签/时间范围/产品引用；读不准的地方进「待确认清单」，压缩决策写进 notes。拆解产出为空或失败时明确报原因，不产生空任务。</p>
|
||
<h3>③ 清单增删改查</h3>
|
||
<p>拆出的每段可<b>直接编辑</b>（标题/标签/时长/产品，失焦自动保存，标签变了自动重新匹配 Agent）；可<b>删除</b>（生成过的也能删，删光回可拆解态）；可<b>新增段落</b>；整体不满意可<b>「✦ 对清单提意见，AI 重新拆解」</b>——意见最高优先级注入，AI 重出整份任务单。</p>
|
||
<h3>④⑤⑥ 逐段生成 + 质检 + 人工确认</h3>
|
||
<p>点「▶ 开始生成（第 1 段）」只派发第一个 Agent；生成+质检完自动停在「待审查」，人工通过后按钮变「▶ 生成下一段」继续派发。打回 = 自动按意见重新生成（见 §8）。也有传统「一键跑完全部」模式（暂停/继续/停止/删除齐全）。</p>
|
||
<h3>⑦ 组合成稿</h3>
|
||
<p>全部段通过后「📄 组合成稿」：跨段一致性检查 → 拼接 → 生成六色标注 docx（可下载/在线预览）。</p>
|
||
</div>
|
||
|
||
<h2 id="s4">4. 内容生产流水线（Agent 体系）</h2>
|
||
<table>
|
||
<tr><th>Agent（内置 14 个）</th><th>角色</th><th>职责</th></tr>
|
||
<tr><td>主控 Agent</td><td>coordinator</td><td>导图 → 任务单拆解（支持用户修改意见注入）</td></tr>
|
||
<tr><td>开场段 / 心法段 / 技法段 / 收尾段 / 钩子段 Agent</td><td>production</td><td>按内容标签生产对应段落正文（挂知识库检索生成）</td></tr>
|
||
<tr><td>产品销售 Agent</td><td>production</td><td>产品植入段（挂产品信息+销售逻辑库）</td></tr>
|
||
<tr><td>结构 / 内容 / 风格尺度 / 跨稿 质检</td><td>qc ×4</td><td>四门独立质检（见 §7）</td></tr>
|
||
<tr><td>组合 Agent</td><td>composer</td><td>跨段衔接检查 + 成稿组合</td></tr>
|
||
<tr><td>风格顾问 / 产品顾问</td><td>adviser</td><td>辅助咨询</td></tr>
|
||
</table>
|
||
<p><b>Agent 三要素</b>：规则（rules，可版本化）、提示模板（可挂 PromptTemplate）、知识库（kb_ids，检索素材来源）。<b>画布（Canvas）</b>把 Agent 编排成节点图，任务可绑定画布；画布可设<b>全局总监 Agent</b>（on_drift 疑似跑偏才审 / always 每段必审 / monitor 只记录）——跑偏的段自动重做 1 次，仍偏转人工。<b>融合生成</b>：一段可挂多个融合 Agent 共同产出。<b>Agent 三件套支持「✦ AI 帮我创建」</b>（见 §6）。</p>
|
||
|
||
<h2 id="s5">5. 知识库与向量检索（RAG）</h2>
|
||
<div class="two">
|
||
<div class="card">
|
||
<h3>六库定稿（v5 来源级清洗）</h3>
|
||
<table>
|
||
<tr><th>库</th><th>块数</th><th>内容</th></tr>
|
||
<tr><td>心法</td><td>8,912</td><td>性观念/性心理/亲密关系</td></tr>
|
||
<tr><td>技法</td><td>3,565</td><td>手法/前戏/高潮教学</td></tr>
|
||
<tr><td>功法</td><td>5,941</td><td>凯格尔/盆底肌/控精训练</td></tr>
|
||
<tr><td>情欲内容</td><td>727</td><td>角色扮演/SM/性幻想</td></tr>
|
||
<tr><td>产品信息</td><td>49</td><td>产品成分/用法</td></tr>
|
||
<tr><td>销售逻辑</td><td>2,438</td><td>98 场真实直播稿全链路</td></tr>
|
||
</table>
|
||
</div>
|
||
<div class="card">
|
||
<h3>上传与建索引</h3>
|
||
<p><b>三种方式</b>：📁整个文件夹（含多层子文件夹，拖拽或选择，自动打 zip）、📤单/多文件、API。</p>
|
||
<p><b>支持格式</b>：md/txt/docx/srt/json/jsonl/pdf + <b>音视频</b>（mp4/mov/mp3/wav 等 12 种 → ffmpeg 抽音轨 → 本地 Whisper 中文转写 → 语义分段）。</p>
|
||
<p><b>处理链</b>：清洗（去时间轴/乱码/去重）→ 分块（口播稿 2200 字聚合）→ bge-small-zh 向量化 → Chroma HNSW 索引（独立 rag_worker 子进程执行，规避主进程性能塌陷，8 秒级检索）。</p>
|
||
<p><b>多级分类</b>：手动分类 + ✦AI 自动分类（建议→确认制）+ 跨库移动文件。</p>
|
||
</div>
|
||
</div>
|
||
<div class="card">
|
||
<h3>检索逻辑（生成时自动发生）</h3>
|
||
<p><code>search_kbs</code>：向量 top-k 候选 → 剔除该 Agent 已消费片段（防重复引用）→ 关键词重排（命中 +0.15）→ 取 top-k。每段生成<b>预留（reserve）知识片段</b>：正文+锚点落盘才标记 consumed；失败/打回自动释放（available）可再次被检索。所有引用带 <code>文件名/标题/原文摘录</code> 写入 <code>references</code>，前端可逐条溯源核对。</p>
|
||
</div>
|
||
|
||
<h2 id="s6">6. AI 辅助创建</h2>
|
||
<div class="card">
|
||
<p>Agent / 技能 / 提示模板 三个页面都有「✦ AI 帮我创建」：用户一句大白话描述 → 系统先<b>检索知识库</b>（6 库全查，取最相关的 8 块注入 prompt）→ 模型输出受控 JSON 草稿（名称/规则/指令/建议）→ 用户在表单确认修改后才正式创建。草稿带 <code>_meta</code>：所用模型、Token 消耗、耗时、<b>引用了哪 8 条知识</b>（库名+文件+摘录）。</p>
|
||
<p>另有 <b>冲突检测</b>：创建/修改时扫描 15 组互斥词对（口语↔书面、简短↔详细…），重名/高相似名称、跨资源单侧冲突，以 warning 展示不阻断。</p>
|
||
</div>
|
||
|
||
<h2 id="s7">7. 质检体系（4 门全开）</h2>
|
||
<table>
|
||
<tr><th>门</th><th>检查什么</th><th>典型 FAIL</th></tr>
|
||
<tr><td>structure 结构</td><td>锚点卡 7 字段完整（核心概念/技法/产品引用/金句/情绪基调/结尾钩子/时长）</td><td>锚点缺失字段</td></tr>
|
||
<tr><td>content 内容</td><td>是否扣题、知识引用是否真实、有没有编造</td><td>内容与导图节点脱节</td></tr>
|
||
<tr><td>style 风格尺度</td><td>雅文口播风（大白话/单段流）、内容尺度</td><td>书面腔、结构模板化</td></tr>
|
||
<tr><td>cross 跨稿</td><td>与上一天任务的衔接、重复度</td><td>与昨日金句重复</td></tr>
|
||
</table>
|
||
<p>质检不过 → 自动重试最多 2 轮（失败意见注入下轮 prompt「本轮必须修复」）→ 仍不过转 <code>rework</code> 等人工。产物三件套：<b>正文（口语单段流）+ 锚点卡（结构化 JSON）+ 引用来源</b>。</p>
|
||
</div>
|
||
|
||
<h2 id="s8">8. 审查与打回循环</h2>
|
||
<div class="card">
|
||
<table>
|
||
<tr><th>操作</th><th>发生什么</th></tr>
|
||
<tr><td>✅ 通过</td><td>段 → approved；全部通过后任务变「可合成」</td></tr>
|
||
<tr><td>🔁 打回 + 意见</td><td><b>立即自动重做</b>：意见写入段落并以「用户打回意见（最高优先级，必须逐条落实）」注入新 prompt → 重新生成+质检 → 回到待审查；意见同时沉淀为该 Agent 的 L3 待确认记忆</td></tr>
|
||
<tr><td>⏭️ 跳过</td><td>段 → skipped，不参与合成</td></tr>
|
||
<tr><td>🔁 重试 / 重试+记原因</td><td>失败段重跑；原因沉淀为 L2 待确认记忆</td></tr>
|
||
<tr><td>🗑 删除段落</td><td>任何状态可删（已交付除外），生成派发自动跳过</td></tr>
|
||
</table>
|
||
<p>所有打回/修复原因都会进入「记忆库」的<b>待确认池</b>（L2 修复经验 / L3 偏好），管理员确认后写入 Agent 长期记忆——<b>系统会越用越懂雅文的要求</b>。运行轨迹页可看每个会话的轮次/工具调用/错误，工具调用支持人工批准/拒绝（human-in-the-loop）。</p>
|
||
</div>
|
||
|
||
<h2 id="s9">9. 点数与成本控制</h2>
|
||
<div class="card">
|
||
<p><b>计量</b>：1 点数 = 10 Token。点数余额本身不设上限；<b>发放三档</b>：一档 1,000 万 / 二档 1 亿 / 三档 10 亿（管理员在用量与账单页一键发放，也可手动输入）。</p>
|
||
<p><b>启动预检（硬性）</b>：开始生成前估算本次成本（按本组织近 200 次真实 LLM 用量外推，无历史用保守常量），余额须覆盖「预估 + 20% 缓冲」，不足直接 409 拦截并中文提示。任务页展示预估 Token/点数/耗时和估算来源。</p>
|
||
<p><b>运行中熔断</b>：点数耗尽、鉴权失败、区域限制类错误 → 立即停止整个任务（继续跑只是白烧）；瞬时错误（网络抖动）继续跑。</p>
|
||
<p><b>API 限流四层防护</b>：429 自动退避重试（读 Retry-After + 抖动，最多 2 次）→ 自动 failover 换 Provider → 单任务 240 轮调用预算熔断 → 中文错误提示（建议换模型）。<b>看板隔离</b>：运营看板不显示点数余额，普通用户只看自己的任务/用量。</p>
|
||
</div>
|
||
|
||
<h2 id="s10">10. 模型管理</h2>
|
||
<div class="card">
|
||
<p>多 Provider 多模型：<b>API Key 存 macOS 钥匙串</b>（<code>secret_store</code>，库文件里只有密文引用）；连通性测试一键验证；<b>全局默认模型</b>设置；每个 Agent 可单独指定 Provider/模型（不指定则用全局默认）；<b>故障自动转移</b>：主模型连续失败自动切到备选 Provider。当前主力：DeepSeek（v4-flash / v4-pro）。</p>
|
||
</div>
|
||
|
||
<h2 id="s11">11. 数据隔离与安全</h2>
|
||
<div class="card">
|
||
<p><b>认证</b>：用户名密码登录，Token 会话 12 小时；<b>防爆破</b>：(IP,用户名) 5 次失败锁 15 分钟，单 IP 30 次锁 15 分钟。</p>
|
||
<p><b>授权</b>：资源级 can_access（组织+归属+可见性+分级授权 use/manage/export）+ 角色权限矩阵双保险；<b>已实测</b>：跨用户任务/库/Agent 均不可见，越权 403/404。</p>
|
||
<p><b>备份</b>：每 6 小时自动备份，保留 14 份；密钥类一律不入库（钥匙串）；上传有类型白名单 + 路径穿越防护 + zip 炸弹防护。</p>
|
||
</div>
|
||
|
||
<h2 id="s12">12. 运维与守护</h2>
|
||
<div class="card">
|
||
<table>
|
||
<tr><th>组件</th><th>机制</th></tr>
|
||
<tr><td>公网入口</td><td><b>https://agent.pducv.cn</b>（域名→Cloudflare→命名隧道 yawan-workbench，地址永久固定）</td></tr>
|
||
<tr><td>隧道常驻</td><td>launchd 服务 <code>com.yawan.cloudflared</code>：崩溃自动重启 + 开机自启 + 4 条冗余连接</td></tr>
|
||
<tr><td>后端守护</td><td><code>~/bin/yawan-guard.sh</code> 每 60 秒巡检，挂了自动拉起</td></tr>
|
||
<tr><td>任务队列</td><td>持久化队列：租约 5 分钟 / 重试 3 次 / 死信队列可重放</td></tr>
|
||
<tr><td>巡检告警</td><td>5 分钟巡检：磁盘 <2GB、失败段超 30 分钟、点数 <1000 告警；告警去重 10 分钟</td></tr>
|
||
<tr><td>审计</td><td>LLMCall（每次模型调用：模型/耗时/Token/状态）、UsageEvent（计费事件）、RunEvent（运行轨迹）、Trace 全链路追踪</td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<h2 id="s13">13. 关键表与端点速查</h2>
|
||
<div class="two">
|
||
<div class="card">
|
||
<h3>核心数据表</h3>
|
||
<p><code>appuser</code> 用户 · <code>campaign</code> 任务（含 duration_minutes）· <code>segment</code> 内容段（状态机：pending→running→qc→human_review→approved/rework/failed/skipped）· <code>campaignrun</code> 运行（支持暂停/断点/取消）· <code>agent / agentskill / prompttemplate</code> · <code>knowledgebase / knowledgefile / knowledgecategory</code> · <code>knowledgeusage</code> 知识消费 · <code>canvas</code> 画布 · <code>llmcall / usageevent / runevent</code> 审计 · <code>memory / pendingmemory</code> 记忆 · <code>artifact</code> 成稿 · <code>notification</code> 通知</p>
|
||
</div>
|
||
<div class="card">
|
||
<h3>主要端点（158 个中的关键）</h3>
|
||
<p><code>POST /campaigns</code> 建任务（带时长）<br/>
|
||
<code>POST /campaigns/{id}/parse</code> 后台拆解（可带 advice 重拆）<br/>
|
||
<code>PUT/DELETE /campaigns/{id}/segments/{sid}</code> 改/删段<br/>
|
||
<code>POST /campaigns/{id}/segments</code> 新增段<br/>
|
||
<code>POST /campaigns/{id}/run</code> 全量生成 · <code>/run-step</code> 逐段生成<br/>
|
||
<code>POST /campaigns/{id}/pause|resume</code> 暂停/断点续跑<br/>
|
||
<code>POST /segments/{sid}/review</code> 审查（reject 即自动重做）<br/>
|
||
<code>POST /segments/{sid}/fix</code> 重试/换模型/改规则<br/>
|
||
<code>POST /campaigns/{id}/compose</code> 合成<br/>
|
||
<code>GET/POST /kbs...</code> 知识库/导入/文件夹导入/检索<br/>
|
||
<code>POST /ai-assist/draft</code> AI 辅助创建（KB 检索注入）</p>
|
||
</div>
|
||
</div>
|
||
|
||
<h2 id="s14">14. 已知边界与注意事项</h2>
|
||
<div class="note">
|
||
<p><b>① 电脑需开机</b>——系统跑在本机 Mac 上，关机即公网不可达（长期方案可迁轻量云服务器）。<b>② 音视频转写耗时</b>——1 小时视频约 20-40 分钟本地转写，属正常。<b>③ 每段生成 3-5 分钟</b>——生成+4 道质检是真实 LLM 调用，页面自动刷新无需盯着。<b>④ 质检多轮 rework</b>——质检判定未达标会自动重试 2 轮再转人工，属设计行为，人工再打回会带意见重做。<b>⑤ ngrok 已退役</b>——如遇旧地址打不开，一律用 agent.pducv.cn。<b>⑥ 测试知识库</b>——「检测用知识库」已删除，Agent 已重新挂载正式六库。</p>
|
||
</div>
|
||
<p style="margin-top:24px;color:var(--ink3);font-size:11px">私域Agent · 雅文老师内容生产中枢 · 内部文档</p>
|
||
</div></body></html>
|