1125 lines
39 KiB
Markdown
1125 lines
39 KiB
Markdown
# 雅文内容创造工作台 · 从 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` 记录，用于审计和成本统计，不等同于用户点数余额。
|