@@ -0,0 +1,407 @@
# 私域 Agent 内容生产工作台：系统整体架构与功能检查文档
> 文档用途：给产品、运营、测试和维护人员逐项核对当前系统。内容依据 `/server/app`、`/web/src` 和启动脚本整理，描述的是代码已经实现或明确配置的行为；“待确认”项需要在实际环境中验收。本文不包含管理员密码、API 密钥等敏感信息。
>
> 代码位置：`server/app/main.py`（ （ （ （
## 1. 系统边界和运行拓扑
系统是一个单组织、本地持久化、可通过公网隧道访问的内容生产工作台。浏览器只访问 React 单页应用；前端通过 `/api` 调用 FastAPI；
``` 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；
## 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}` ，
- 生产环境需要 `.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` （ `/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` ：
## 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` （ `/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_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～
- 2026-09-13 向量查询进一步优化：移除检索热路径上的 `collection.count()` 。该调用在外置盘冷读时，108135 段库约 1.7 秒，而实际向量查询约 20ms；
- 2026-09-13 空闲态 10 条不同 query 只读采样：P50 约 556ms， ～ `database is locked` ；高并发仍受单个常驻 RAG Worker 的队列容量限制，继续保持单 Worker 以控制内存峰值。
- 2026-09-13 稳定性修复：Embedding 用量事件改为独立短事务提交，计量写入失败只记录告警，不再让知识库检索失败；避免内容任务并发时主业务事务与用量写入互相持有 SQLite 写锁。
- 计量短事务设置 500ms 忙等待上限；数据库暂时繁忙时只丢弃本次非关键计量并保留检索结果，避免用户看到 30 秒级假性超时。
## 17. 检查记录模板
| 检查日期 | 环境（dev/prod）
|---|---|---|---|---|---|---|---|
| | | | | | | | |
维护此文档时，应以代码中的模型字段、路由和权限 key 为准；新增功能同时补充“功能地图、数据模型、API、权限、验收清单”五个位置。
yi