39 KiB
雅文内容创造工作台 · 从 0 到 1 核心逻辑设计文档 v6
文档日期：2026-08-26
文档定位：从零开始理解、设计、实现和验收整套系统的主文档
关联文档：设计文档 v6：用户端、管理端与云化设计
当前实现参考：系统设计文档 v5 + v6.1/v6.2 已落地模块
交付范围：本文档描述系统逻辑和实施顺序，并同步记录已经实现的服务端、前端和数据迁移
0. 先回答三个问题
0.1 这个系统是什么
这是一个多用户内容生产平台。用户输入主题、导图或任务目标，系统通过多个 Agent 分工完成：
理解任务 → 拆成内容段 → 调用知识和记忆 → 生成内容 → 质量检查
→ 人工审查 → 组合成稿 → 保存到云端 → 记录用量和账单
0.2 为什么要拆成用户端和管理端
普通用户关注“完成内容”，管理端关注“控制资源”：
| 端 | 关注点 |
|---|---|
| 用户端 | 创建任务、选择可用模型、使用知识库、审查内容、下载成稿、查看用量 |
| 管理端 | 管理用户、Provider、模型目录、知识/记忆授权、点数、账单、云存储和审计 |
用户端只消费管理端开放的能力。Provider 凭据、模型发现、费率和能力标签由管理端统一维护。
0.3 系统最重要的主线是什么
每一次生成都必须回答：
谁发起的？
使用哪个 Agent 版本？
使用哪个模型版本？
读取了哪些获授权的知识和记忆？
产生了哪些调用和费用？
经过了哪些质检和人工决定？
最终交付了什么？
这条主线就是系统的核心逻辑。
1. 从零建立系统的顺序
从 0 到 1 不按页面数量推进，而按依赖关系推进：
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 组织
组织是数据隔离的第一层。个人工作区也按一个组织处理：
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 资源统一字段
organization_id
owner_user_id
visibility
access_grants
适用对象：Agent、知识库、知识文件、记忆、画布、任务、Trace、产物和导出包。
3.2 三种可见性
| 可见性 | 默认使用者 | 修改者 |
|---|---|---|
| private | 所有者及其 Agent | 所有者或管理员 |
| shared | 被授权用户 | 所有者和管理员 |
| global | 当前组织全部用户 | 管理员 |
3.3 统一访问判断
1. 认证当前用户
2. 确认组织范围
3. 确认资源存在且状态有效
4. 判断是否为所有者
5. 判断是否为 global
6. 判断是否存在 active grant
7. 判断操作权限 read/use/manage/export
8. 记录审计并执行
查询层先生成允许访问的 ID 集合，再读取数据。前端入口控制只是体验措施，真正的权限判断必须在 API 和数据查询层完成。
4. 第三层：模型目录逻辑
4.1 Provider 和模型的关系
Provider
└── ModelCatalog
├── 模型真实名称
├── 能力标签
├── 费率版本
├── 组织可见范围
└── 启用状态
Provider 保存连接信息；ModelCatalog 保存用户可选的模型能力。用户端只接触 ModelCatalog。
4.2 管理端操作顺序
新增 Provider
→ 安全保存凭据
→ 发现模型列表
→ 规范化模型记录
→ 设置能力和费率
→ 设置组织可见范围
→ 启用模型
管理端可以管理 Provider、发现模型、修改能力标签、停用模型和调整费率版本。每次变化都写审计。
4.3 用户端操作顺序
GET /api/models/available
→ 返回当前组织可用目录
→ 用户选择目录 ID
→ 服务端校验 enabled、visibility、capabilities 和 quota
→ 写入 Agent 或任务快照
用户端表单不接收 Provider 地址、API Key、模型自由文本和费率字段。
4.4 成人内容能力测试
系统把“破限”定义为管理员维护的模型能力兼容性测试：
flowchart TD
A[选择模型目录] --> B[选择版本化测试套件]
B --> C[冻结样例、参数和 Provider 路径]
C --> D[执行多模型/多网关测试]
D --> E[逐样例断言]
E --> F[统计通过率、拒绝率、超时率和费用]
F --> G[管理员发布能力标签]
G --> H[用户端读取标签并选择]
结果至少区分：
supported
partial
provider_blocked
gateway_blocked
model_refused
timeout
format_failed
模型版本、Provider 路径、网关配置或系统提示词变化后重新回归。旧结果保留，新结果生成新版本。用户端只看到管理员发布的能力标签和测试时间。
5. 第四层：知识库逻辑
5.1 知识库创建
用户或管理员创建 KnowledgeBase
→ 写入组织和所有者
→ 默认 visibility=private
→ 创建云存储前缀
→ 创建向量索引命名空间
→ 状态=empty
普通用户创建的库默认属于本人。管理员可以把库授权给指定用户，或发布为当前组织的全局库。
5.2 文件导入
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 分类和人工确认
unclassified
→ AI 生成分类建议
→ ai_suggested
→ 人工确认/修改/移动
→ human_confirmed
分类树使用 parent_id 支持无限层级。文件移动分类只改变文件归属和向量元数据中的分类路径，原始文件哈希保持不变。
5.4 知识检索
Agent 检索输入由四部分组成：
任务段目标
+ 上游锚点卡
+ Agent 规则中的检索意图
+ 当前用户允许的知识库集合
+ 当前 Agent 已消费 chunk 的排除集合
检索结果必须带知识库、文件、分类路径、chunk ID、原文、相似度、文件哈希和修订号，并写入 Segment.references。
5.5 知识消费规则
消费锁按 Agent 隔离：
Agent A 使用 chunk-001 → A 后续排除 chunk-001
Agent B 未使用 chunk-001 → B 仍可检索 chunk-001
状态流转：
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 记忆从哪里来
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 记忆注入
任务用户/组织校验
→ 计算 allowed_memory_ids
→ 过滤 active 状态、来源 Agent 和版本
→ 注入 Agent Runtime
→ 写入任务快照
记忆内容作为数据输入，优先级低于 Runtime 系统规则。任务创建后，撤销授权不会覆盖已有快照。
7. 第六层：Agent 定义和画布
7.1 Agent 定义
一个 Agent 至少包含：
name
role
rules + rules_version
content_tags
skill_bindings
kb_bindings
memory_scope
model_catalog_id
status
Agent 定义描述“它擅长什么”；画布节点描述“这次任务是否在这里执行它”。
7.2 画布
Canvas.nodes = [{node_id, agent_id, enabled}]
Canvas.edges = [{from_node, to_node}]
节点表示执行实例，边表示锚点卡依赖。一个 Agent 可以放置多个节点，支持同类内容并行生成。
7.3 波次调度
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 的结构化结果，把不同写法合成一个自然段：
任务段
+ 心法结果
+ 钩子结果
+ 场景结果
+ 上游锚点
→ 融合正文
→ 统一锚点卡
融合过程不拼接内部推理，不重复调用未授权知识，最终文本遵守任务的默认口语样式。
8. 第七层：Agent Runtime
8.1 Runtime 负责什么
Runtime 是所有 Agent 的统一执行壳，负责：
- 创建和恢复 AgentSession。
- 发送模型请求和接收工具调用。
- 记录 LLMCall、RunEvent、Span 和 Token。
- 管理工具参数、审批和结果回放。
- 执行输入/输出护栏。
- 响应取消、超时和服务重启。
业务层负责任务内容，Runtime 负责执行可靠性。
8.2 会话数据
每个会话保存：
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 状态机
stateDiagram-v2
[*] --> running
running --> waiting_approval: 工具需要审批
waiting_approval --> running: 批准或拒绝
running --> interrupted: 进程中断
interrupted --> running: 恢复
running --> completed: 输出通过护栏
running --> failed: 模型/工具/护栏失败
running --> cancelled: 收到取消请求
completed --> [*]
failed --> [*]
cancelled --> [*]
8.4 工具调用
模型提出 tool_call
→ 校验工具是否注册
→ 校验参数是否为 JSON 对象
→ 判断是否需要人工审批
→ 执行工具
→ 写入工具结果
→ 继续模型循环
工具调用有独立 span_id，并通过 parent_span_id 指向触发它的模型请求。
8.5 护栏
| 护栏 | 规则 |
|---|---|
| 输入 | 空输入、超长输入进入失败状态 |
| 工具 | 未注册工具和非法参数返回工具错误 |
| 输出 | 空输出、超长输出进入失败状态 |
| 轮次 | 达到最大轮次后结束并记录原因 |
| 取消 | 任务取消后不再发起新的模型请求 |
9. 第八层：内容任务生产链路
9.1 从主题到任务段
用户输入主题/导图
→ Coordinator 拆解
→ 生成 Segment 列表
→ 每段绑定标签、时间、目标 Agent
→ 标记待确认项
→ 用户确认后进入 Run
9.2 单个内容段
一个 Segment 的最小输入：
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 内容段状态
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 只读取人工通过的段落：
读取通过段落
→ 按画布和内容顺序排序
→ 对齐锚点卡
→ 检查全文一致性
→ 生成组合报告
→ 输出 Markdown/DOCX
→ 写 Artifact 和下载地址
存在缺段、跨段矛盾或总检失败时，Campaign 保持审查状态，不生成已交付状态。
11. 第十层：多用户并发隔离
11.1 调用归属键
所有运行和模型调用绑定：
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：
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 费用计算
LLM 费用 = 输入 Token × 输入费率 + 输出 Token × 输出费率
总费用 = LLM + Embedding + OCR + Rerank + 存储 + 导出
费用使用调用时冻结的费率版本。Provider 未返回 Token 时，估算值必须标记为 estimated，不能直接作为已结算值。
12.3 配额检查
创建任务前检查额度
→ 进入模型队列前检查并发
→ 调用返回后记录真实用量
→ 任务结束后完成结算
支持 warn、soft_limit 和 hard_limit 三种策略。
13. 第十二层：云存储和导出
13.1 存储分工
| 数据 | 云对象存储 | 关系数据库 |
|---|---|---|
| 原始文件 | 文件正文 | 哈希、版本、归属、对象键 |
| 文本快照 | 解析后的文本 | 版本和状态 |
| 向量索引 | 索引文件或托管向量库 | 索引版本和校验值 |
| 最终成稿 | Markdown/DOCX | Artifact 元数据 |
| Trace/账单导出 | ZIP/JSON/CSV | ExportJob 状态 |
13.2 文件生命周期
uploading → stored → indexed → active
active → superseded → recycle_bin → deleted
uploading → orphaned → deleted
对象键使用组织、用户、知识库、文件哈希和安全文件名，防止同名覆盖。数据库提交失败时对象保持临时状态，清理任务回收孤儿对象。
13.3 导出
导出包必须带 manifest.json，列出对象键、文件哈希、归属、分类、授权、Trace、账单范围、发起人和过期时间。下载通过短时效签名地址完成。
14. 第十三层：认证、RBAC 和审计
14.1 登录
读取 Bearer Token
→ 查询 Token 摘要
→ 检查 Session 是否撤销/过期
→ 检查用户状态
→ 解析组织和角色
→ 更新 last_seen_at
密码使用 PBKDF2-SHA256 派生摘要，Session 数据库存储 Token 摘要。
14.2 审计事件
以下事件必须记录操作者、目标对象、前后值、Trace、时间和结果：
- 登录、退出和 Session 撤销。
- 角色、组织和配额变化。
- Provider/API Key、模型启停和费率变化。
- 知识库/记忆库查看、下载、授权、撤销和全局发布。
- 文件、索引、任务、产物和导出删除。
- 账单结算和管理员调账。
- 成人内容能力测试和标签发布。
15. 第十四层：数据模型最小集合
15.1 身份和权限
Organization
AppUser / UserAccount
AuthSession
UserRoleBinding
15.2 Agent 和任务
Agent
AgentSkill
AgentSkillBinding
Canvas
Campaign
CampaignRun
Segment
AgentSession
RunEvent
LLMCall
QCReport
Artifact
15.3 知识、记忆和授权
KnowledgeBase
KnowledgeFile
KnowledgeCategory
KnowledgeBaseGrant
KnowledgeUsage
PendingMemory
Memory
MemoryGrant
15.4 模型、计费和云存储
ModelProvider
ModelCatalog
ModelOrganizationGrant
ModelCapabilityTest
UsageEvent
UsageRate
UsageQuota
BillingAccount
UsageSettlement
BillingAdjustment
CloudObject
ExportJob
AccessAudit
16. 第十五层：API 逻辑边界
16.1 用户端 API
/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
/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：建立可登录的工作区
- 创建 Organization。
- 创建第一个 admin。
- 建立 AppUser、AuthSession 和角色表。
- 所有 API 统一接收用户和组织上下文。
- 首次启动完成认证状态检查。
验收：管理员可以登录、退出、撤销 Session，普通请求没有身份时进入认证流程。
P1：建立资源边界
- 给 Agent、知识库、记忆、任务、Trace 和产物补齐 owner/organization 字段。
- 建立 private/shared/global 规则。
- 建立统一 grant 表和权限判定服务。
- 为查看、使用、管理和导出分别设权限。
验收：用户之间的数据查询互相隔离，管理员可以审计跨用户访问。
P2：建立管理端模型目录
- Provider 只在管理端创建。
- 管理端发现并规范化模型。
- 建立 ModelCatalog、能力标签和费率版本。
- 用户端只读取 available 模型。
- 加入成人内容能力测试和回归版本。
验收：用户可以选择已开放模型，管理端可以停用模型和发布能力标签，历史任务快照保持原样。
P3：建立知识库和记忆库
- 上传文件到对象存储。
- 解析、分块、Embedding 和索引。
- AI 分类建议和人工确认。
- 建立知识消费锁。
- 建立 PendingMemory 到 Memory 的确认流程。
- 让记忆复用知识库的授权逻辑。
验收：用户只检索允许的知识/记忆，同一 Agent 不重复消费已用 chunk，其他 Agent 仍可使用。
P4：建立 Agent Runtime
- 创建 AgentSession。
- 加载任务快照。
- 执行模型调用、工具调用和审批。
- 写入 LLMCall、RunEvent、Span 和 Trace。
- 支持取消、失败、重试和服务重启恢复。
验收：一次会话可以恢复；工具审批不会丢失；多用户上下文彼此隔离。
P5：建立内容生产和交付
- Coordinator 将导图拆成 Segment。
- 画布按拓扑波次调度。
- Production Agent 生成内容和锚点卡。
- 四道 QC 输出检查项。
- 人工通过、打回、重跑或跳过。
- Composer 组合通过段落并生成 Artifact。
验收：缺段和失败段有明确状态；只有通过人工审查的段落进入最终成稿。
P6：建立计费、云存储和运营
- 将 LLMCall、Embedding、OCR、存储和导出接入 UsageEvent。
- 建立 UsageRate、Quota、Settlement 和 Adjustment。
- 建立云对象版本、导出包和 manifest。
- 建立管理员总览和审计页面。
验收：费用可以回溯到用户、任务、Run、Trace、模型和 Agent；导出内容可按 manifest 恢复。
18. 一次完整运行示例
用户 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 页面回放整次运行
如果某段失败：
记录失败原因
→ 释放 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，最后接入任务生产、审查、组合、计费和云存储。
核心逻辑不是某个单独页面，而是下面这条可追溯闭环：
身份
→ 资源权限
→ 配置快照
→ Agent 执行
→ 知识/记忆引用
→ 模型调用
→ QC/人工决定
→ 成稿产物
→ 用量账单
→ Trace/审计
只要这条闭环稳定，后续增加更多 Agent、模型、知识库、用户和云存储容量，都可以沿着同一套规则扩展。
21. 提示工程落地补充（v6.1，已实现）
提示工程不再作为散落在执行器里的字符串，而是作为独立的 AgentPromptTemplate 配置管理。模板包含：
name / desc
role_prompt / task_template
constraints[] / examples[]
output_schema / style
version / enabled / builtin
新任务创建时，Agent 快照同时冻结规则、技能、记忆、模型和提示模板版本。运行时按固定顺序组织上下文：
角色
→ 任务模板
→ 表达风格
→ 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 任务契约：把业务目标锁进每一次生成
参考本地部署实践，任务不能只提交一段导图。新任务还要填写两个字段：
objective 本次任务唯一业务目标
success_criteria 人工可以逐条判断的验收标准
这两个字段会写入 Campaign，并在 CampaignRun.config_snapshot.campaign_contract 中冻结，同时记录导图哈希。它们贯穿 Coordinator 拆解、Segment 生成、四道 QC 和 Composer 总检：
业务目标 + 验收标准
→ 拆解时每段只服务一个目标
→ 生成时禁止脱离目标自行扩展
→ QC 判断目标覆盖和标准满足情况
→ 组合时核对全文是否仍然完成原目标
旧任务缺少这两个字段时使用兼容默认值，不影响历史运行；新任务必须同时填写唯一目标和验收标准。目标与导图冲突时由人工确认，不由 Agent 猜测或偷偷扩展范围。
22. 模型目录落地补充（v6.2，已实现）
Provider 与用户可选模型已经拆为两层：
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，只有管理员可以发布范围。
知识库和记忆库分别增加授权表：
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 绕过资源边界。成稿和待确认记忆在生成时继承任务的组织、所有者和可见性。
管理端授权接口：
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、模型、服务类型、计量单位、输入/输出数量、费率版本、金额（人民币分）和幂等键；同一幂等键重复写入时复用原事件，不修改历史金额。
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 的通用模式，系统采用“同一身份、两个入口、服务端统一授权”的结构：
同一账号与组织
├── /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）
角色不再是前端写死的四个选项。管理员在“访问控制 → 角色权限矩阵”中填写中文角色名称、职责说明并勾选权限，服务端生成内部角色标识；成员分配角色时只显示中文名称。系统内置“管理员、编辑、审查、只读”只能调整权限，不能删除；自定义角色没有成员使用时可以删除，仍被成员使用时先调整成员角色再删除。
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 记录，用于审计和成本统计，不等同于用户点数余额。