chenxin
42513d13c6
- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标 - 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处） - 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识 - 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测 - 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等） - 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档 - 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore
5.7 KiB
5.7 KiB
数据架构
1. 事实源
关系数据库保存角色、社区、协作、交易、插件和运行的权威状态；对象存储保存媒体与交付物；全文、向量、图投影、推荐特征和缓存都是派生数据。
flowchart LR
DB[(Relational Source of Truth)] --> FTS[Full-text Index]
DB --> V[Vector Index]
DB --> G[Graph Projection]
DB --> C[Cache]
FS[(Object Storage)] --> DB
FTS & V & G & C --> Q[Query and Retrieval]
任何索引可从数据库和对象存储重建，不能反向覆盖角色、记忆、社区来源、许可或交易账。
2. 核心关系
erDiagram
PERSONAL_DOMAIN ||--o{ CHARACTER : owns
CHARACTER ||--o{ CHARACTER_VERSION : versions
CHARACTER ||--o{ CHARACTER_ASSET : presents
CHARACTER ||--o{ MEMORY : remembers
CONVERSATION ||--o{ BRANCH : contains
BRANCH ||--o{ MESSAGE : orders
CONVERSATION ||--o{ RUN : triggers
RUN ||--o{ TURN : contains
TURN ||--o{ MODEL_CALL : attempts
TURN ||--o{ TOOL_CALL : invokes
RUN }o--|| PLUGIN_SNAPSHOT : pins
WORKSPACE ||--o{ WORKSPACE_MEMBER : authorizes
WORKSPACE ||--o{ PROJECT_ASSET : contains
USER ||--o{ COMMUNITY_CONTENT : publishes
COMMUNITY_CONTENT ||--o{ INTERACTION : receives
PUBLISHER ||--o{ PLUGIN_VERSION : releases
MARKETPLACE_LISTING }o--|| RELEASE_VERSION : sells
ORDER ||--o{ ORDER_ITEM : contains
ORDER ||--o{ LEDGER_ENTRY : posts
ORDER_ITEM ||--|| ENTITLEMENT : grants
SETTLEMENT_BATCH ||--o{ LEDGER_ENTRY : settles
3. 数据分区
| 范围 | 典型数据 | 默认可见性 |
|---|---|---|
| Personal Domain | 私密角色、记忆、对话、设备授权 | owner only |
| Workspace | 协作角色、世界、资产、评审 | member RBAC |
| Community | 已发布内容、互动、公开版本 | visibility policy |
| Marketplace | 商品、许可和公开交付摘要 | regional catalog |
| Finance | 订单、支付、退款、账务、结算 | buyer/seller/finance roles |
| Diagnostics | Run、工具、上下文和敏感支持包 | scoped grant |
公开角色 Release 不包含 Personal Domain 中的私密记忆、关系、对话和密钥。
4. 角色、记忆与资产
- CharacterVersion：不可变角色设定版本。
- CharacterAsset：图像、声音、Live2D、3D、动作和场景版本，引用对象与许可。
- Memory/MemoryVersion：长期状态、来源、敏感度、置信度、有效期、审批和纠正链；所有权、写入、版本、检索与装配见记忆与知识架构。
- KnowledgeDocument：外部资料、世界设定和共享知识，不等于人物经历。
- ReleaseVersion：面向社区/市场发布的不可变物料清单与内容哈希。
5. 社区与协作
- CommunityContent 使用统一发布对象加类型化 payload；互动独立记录并支持软删除与治理状态。
- Follow、Block、Report 和 ModerationCase 为一等对象。
- WorkspaceMember 和资源 ACL 双重约束；关键权限变更写审计。
- 协同编辑使用版本号/乐观锁；高频富文本或场景编辑确有需要时采用 CRDT，快照仍落关系事实源。
- 推荐特征保存来源和版本，允许用户清除；Restricted 数据不得进入。
6. 插件 Registry
Plugin、PluginVersion、PackageBlob、Signature、PermissionManifest、Compatibility、Review、Installation 和 PluginSnapshot 分开保存。PluginVersion 不可变；下架修改可分发状态，不改历史包摘要和 Run 快照。
7. 订单与账务
- Listing 可变；OrderItem 固定购买时的版本、价格、税、许可和卖家快照。
- PaymentAttempt、Refund、Dispute、Entitlement 与 Order 分离。
- LedgerEntry 不可变，使用平衡分录或等价会计模型；修正写反向分录。
- CreatorBalance 是 Ledger 聚合，不是独立可编辑事实。
- SettlementBatch 固定结算项；PayoutAttempt 记录 Provider 结果和幂等键。
- 金额使用整数最小单位或 Decimal，记录币种、汇率来源和价格版本。
8. Run 与诊断
Run 只保存聚合状态。Turn、ModelCall、ToolCall、ContextSnapshot、PluginSnapshot 和 AuditEvent 独立查询。Provider 原始正文默认不保存；支持需要时进入加密、限期对象并受 Sensitive DiagnosticGrant 控制。
9. 删除与许可传播
flowchart TD
D[Delete or revoke request] --> A[Authorize and audit]
A --> P[Update authoritative source]
P --> I[Remove indexes and caches]
P --> O[Delete or redact derived objects]
P --> R[Evaluate releases and entitlements]
R --> N[Stop new distribution or updates]
O --> B[Apply backup retention]
B --> T[Keep minimal tombstone]
删除私密源数据不等于撤销所有已合法发布许可；撤架、许可撤销、安全强制停用和用户删除分别建模。墓碑不保存被删原文。
10. 一致性与事件
- 权威状态和 Outbox 在同一事务写入；完整 1.0 的媒体、索引、通知、支付、社区和插件消费者需要 Outbox。
- Webhook/ToolCall 在副作用前写 pending 与幂等键，完成后写结果。
- 支付事件不依赖到达顺序；重复事件返回已有处理结果。
- 搜索、推荐、媒体和向量失败可重建，不影响权威状态。
11. 存储选择
- SQLite：本地开发与个人轻量自托管。
- PostgreSQL：正式部署的关系事实源和全文检索。
- Redis：队列、限流、实时会话和短期状态。
- S3-compatible：媒体、插件包、交付物和加密支持包。
- pgvector：默认语义检索起点；规模或评测需要时替换为专用向量库。
- 图关系先使用 PostgreSQL；多跳规模证明需要时启用 Neo4j/NebulaGraph 投影。
- 分析/搜索引擎按社区规模引入，不成为交易或身份事实源。