chenxin
5da1efe921
- 新增 ADR-024：服务端关系主库统一 PostgreSQL，不设 SQLite 档（pgvector 与中文全文无法在 SQLite 承载，双档必然残缺或第二实现）；端侧离线缓存不受约束 - AGENTS.md：权威事实源与部署句更新；8.6 固化 pk_/uk_/idx_/fk_ 索引命名约定 - system-architecture、data-architecture、memory-and-knowledge、roadmap WP-01、handoff（决策 29）同步清理 SQLite 引用
262 lines
18 KiB
Markdown
262 lines
18 KiB
Markdown
# Hunjing 设计阶段交接文档
|
||
|
||
> 交接基线：完整 1.0 产品、架构、API、富内容、文化语言和工程规则已经定义；仓库当前仍处于设计阶段，不能把任何 TODO 表述为已实现。
|
||
|
||
## 1. 当前状态
|
||
|
||
本轮完成了文档体系重建和完整 1.0 设计收敛：
|
||
|
||
- 根 `README.md`、`AGENTS.md` 与 `docs/` 已按当前目标重写；
|
||
- 文档数量、行数和图表数会随设计变更增长，不作为交接完成证据；以 `docs/README.md` 索引和当前检查结果为准；
|
||
- 完整 1.0 实施清单中的所有未勾选项都是真实待办；不得依赖本文件的历史计数判断完成度；
|
||
- 尚未开始正式代码实现，文档中的端点、表、事件和组件均是目标契约；
|
||
- 当前工作区文件均处于新增/修改状态，尚未提交；不要假定 Git 历史已保存本轮成果。
|
||
|
||
## 2. 不要重新讨论的已确认决策
|
||
|
||
除非用户明确改变决定，后续实现必须以这些结论为前提：
|
||
|
||
1. **1.0 是一次完整整体交付**：内部工作包可以并行和独立验收，但任何缺项都不能称为正式 1.0。
|
||
2. **1.0 全量范围**：角色、记忆、分支多模态对话、多 Agent、插件生态、实时语音、多语言、图像、Live2D、3D 运行编辑、Web/Tauri 桌面和移动、设备感知、完整社区、角色社区、协作、真实支付退款分成结算、运营和自托管全部进入 1.0。
|
||
3. **2.0 边界**：Blender 级完整 3D 建模器、LLM 直接修改完整 3D 几何/绑定、IoT/机器人/物理动作控制。
|
||
4. **能力皆插件，治理内核不插件化**：认证、授权、数据隔离、审批、Ledger、审计、事务和 Sandbox fail-closed 属于 Core。
|
||
5. **插件双轨**：声明式/远程插件默认受限；第三方本地代码插件即使受信也运行在独立进程/容器；只有 bundled Core plugin 可进主进程。
|
||
6. **技术按需**：能力和安全边界强制；语言、数据库、专用向量/图存储和服务拆分按 ADR、官方资料及实测决定。
|
||
7. **3D 1.0 深度**：VRM/glTF 导入、材质/骨骼/表情/动作/场景编辑、运行和导出；不自研完整建模器。
|
||
8. **客户端**：Next.js Web + Tauri v2 Desktop + Tauri v2 iOS/Android。
|
||
9. **社区私信**：服务端治理的一对一和小群聊，服务端加密存储，可举报/屏蔽/审核/多端同步；1.0 不做 E2EE。
|
||
10. **真实市场闭环**：支付、退款、争议、平台费、创作者分成、余额、结算和对账进入 1.0，Ledger 不可变。
|
||
11. **API 开放面**：公开 Native API，同时提供 OpenAI-compatible 和 Anthropic Messages-compatible 网关。
|
||
12. **API 域名**：Native 为 `api.<domain>/v1`；兼容入口为 `gateway.<domain>/openai/v1` 与 `gateway.<domain>/anthropic/v1`。
|
||
13. **认证**：1.0 使用 OAuth 2.1；Web 为安全 Session Cookie，Tauri 为 Authorization Code + PKCE，第三方为 OAuth Bearer，自动化为限 scope Service Account API key；凭据只经 Header 传递。2.0 再设计自研加密认证系统。
|
||
14. **消息与 Run**：聊天消息和可选 Run 在一个事务原子创建；任务工作台可以显式创建无 Conversation Run。
|
||
15. **富内容**：Native API 使用类型化 ContentBlock；用户编辑可使用 Markdown 内嵌 Mermaid、代码和数学公式，服务端规范化为 canonical Block。
|
||
16. **实时渲染**：Markdown/代码增量；数学按完整定界符或完成后；Mermaid 和媒体在 Block 完成/资源 ready 后；最终 Block/Message 与流累积状态对账。
|
||
17. **文化体系**：产品采用完整“中国古代神话/道家文化名 · 直白解释”双层语言；API、数据库、事件、权限和日志只用中性英文稳定值。
|
||
18. **隐藏推理**：不采集、不持久化、不通过诊断接口返回 chain-of-thought；仅保存可见内容、可读摘要、工具轨迹和计数。
|
||
19. **权威记忆**：自动提取先产生 MemoryCandidate；批准、纠正、取代和恢复创建不可变 MemoryVersion。Personal Domain/Workspace 是所有权边界，全文、向量和图只是投影；KV cache、隐藏状态和权重适配不是 1.0 权威记忆。
|
||
20. **ID 生成**：持久化平台资源统一 UUIDv7；服务端 Request 与 Trace record 使用 UUIDv4；`traceparent` 遵循 W3C；秘密、Token、Ticket 和 capability 使用 CSPRNG opaque value，不使用 UUID。
|
||
21. **灵台引擎双形态**：性能与安全敏感的确定性核心以 C++ 实现为灵台引擎（太一/小周天/洛书/河图/陶钧/烛照六模块，承接旧版"灵台/九枢"血脉），同一核心可经稳定 C ABI 进程内嵌入 Python/Rust/Go 宿主，也可作为部署内部 gRPC 独立服务运行；引擎无权威状态、最小 I/O、fail closed，任何能力在两种形态语义一致。
|
||
22. **内驱力与大周天演化（1.0）**：角色具有用户可审阅的内驱力维度；大周天是交互事件触发的自我评估 Run，预算受控、产出候选、经确认演化并留版本谱系；不做后台自主运行、不伪造离线意识（守一不变）；引擎流式模块文化名"小周天"，与角色"大周天"构成大小周天体系。
|
||
23. **产品宪章与永久禁域（ADR-019）**：宪章是产品定义上位约束，九条永久禁域不可被 Prompt、插件、管理员或自托管配置关闭；决策优先序为安全合规 > 用户数据权 > 角色连续性 > 生态健康 > 商业目标。
|
||
24. **三界归真作用域（ADR-020）**：对话分真界/境界/幻境，归真携带 `canonical_scope`；境界只成世界知识候选、幻境不自动入忆；言可入幻、行必归真。
|
||
25. **私箧、保全态与计费伦理（ADR-021）**：私箧用户独立持钥、平台不可恢复；欠费/封禁只读保全不删数据；不按记忆、感情或亲密计费。
|
||
26. **叩心进入 1.0（ADR-022）**：角色主动联系先成叩心候选，受静默、频率、渠道与预算控制；不回应不降关系；不以追逐式消息换回流。
|
||
27. **周天体系统一（ADR-023）**：小周天=Run 可追踪认知闭环（完成信号为大周天唯一输入面），大周天=`cycle_` 聚合根 + 四阶段评估（回顾/对照/提议/提交）+ 阶段记忆；吸收旧版契约骨架并补全其缺失的架构设计。
|
||
28. **数据权与开放核心**：PersonalDomain 数据默认不用于模型训练（自愿贡献需独立、明确、可撤销同意）；前台化名与法定身份分离核验；高敏数据可完全禁止跨区模型处理；核心 Apache-2.0 开放、品牌与官方资产单独保护、DCO 贡献、自托管遥测默认关闭；模型配置按"平台硬边界→目录→用户 BYOK→角色覆写→会话临时"继承。
|
||
29. **统一 PostgreSQL（ADR-024）**：服务端关系主库在开发、测试、自托管与正式部署统一 PostgreSQL，不设 SQLite 主库档（pgvector/中文全文无法在 SQLite 承载，双档必然残缺）；索引命名 `pk_/uk_/idx_/fk_` 前缀。
|
||
|
||
正式 ADR 见[架构决策记录](../decisions/README.md)。
|
||
|
||
## 3. 事实源与阅读路径
|
||
|
||
新接手者先读：
|
||
|
||
1. [项目工程规则](../../AGENTS.md)
|
||
2. [产品定义与边界](../product/product-definition.md)
|
||
3. [完整 1.0 范围与发布门](../product/complete-1.0-scope.md)
|
||
4. [架构决策记录](../decisions/README.md)
|
||
5. [系统架构](../architecture/system-architecture.md)
|
||
6. 当前工作包对应的专项架构；记忆实现必须先读[记忆与知识架构](../architecture/memory-and-knowledge.md)
|
||
7. [协议与稳定标识](../contracts/README.md)及当前工作包对应契约
|
||
8. [安全与诊断访问](../security/security-and-diagnostics.md)
|
||
9. [完整 1.0 实施 TODO](implementation-roadmap.md)
|
||
10. [文化语言体系](../product/cultural-language.md)
|
||
|
||
事实层级：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
P[产品范围] --> A[ADR 与架构]
|
||
A --> C[契约与 OpenAPI]
|
||
C --> I[实现]
|
||
I --> T[测试与运行证据]
|
||
```
|
||
|
||
稳定 ID、枚举、Header、事件、错误码和 ContentBlock 必须先进入契约/OpenAPI，再进入实现。文化名只进入品牌/本地化层。
|
||
|
||
## 4. 文档地图
|
||
|
||
### 产品
|
||
|
||
- `docs/product/product-definition.md`：1.0 产品域和 2.0 边界。
|
||
- `docs/product/complete-1.0-scope.md`：发布口径、必须交付和发布门。
|
||
- `docs/product/cultural-language.md`：镜庭、镜生、镜树、息壤、形仪、天工阁、百工坊、雅集、同契台、云市、司命台等文化名与工程映射。
|
||
|
||
### 架构
|
||
|
||
- `docs/architecture/system-architecture.md`：逻辑模块、物理边界和客户端。
|
||
- `docs/architecture/agent-runtime.md`：Run/Turn/ModelCall/ToolCall、多 Agent、取消与恢复。
|
||
- `docs/architecture/plugin-system.md`：双轨插件、Manifest、生命周期、SDK 与 Registry。
|
||
- `docs/architecture/data-architecture.md`：角色、运行、社区、插件、媒体、订单与 Ledger 数据关系。
|
||
- `docs/architecture/memory-and-knowledge.md`：记忆所有权、类型、Candidate/Version、纠正、召回、ContextSnapshot 和评测。
|
||
- `docs/architecture/media-and-device-architecture.md`：语音、图像、Live2D、3D 和 DeviceGrant。
|
||
- `docs/architecture/community-and-marketplace.md`：社区、私信、协作、市场、支付与结算。
|
||
- `docs/architecture/frontend-content-rendering.md`：Markdown/Shiki/KaTeX/Mermaid/媒体的实时解析、安全、性能和可访问性。
|
||
|
||
### 契约
|
||
|
||
- `docs/contracts/api-conventions.md`：认证、Header、版本、分页、ETag、幂等、错误、上传。
|
||
- `docs/contracts/native-api.md`：Native 资源端点。
|
||
- `docs/contracts/gateway-compatible-api.md`：OpenAI/Anthropic 兼容入口和路由/usage 规则。
|
||
- `docs/contracts/realtime-and-webhooks.md`：Run/通知 SSE、语音/协作/设备 WebSocket、入站/出站 Webhook。
|
||
- `docs/contracts/internal-api.md`：Application Command/Query、Outbox、Model/Tool/Plugin/Sandbox/Payment Port。
|
||
- `docs/contracts/content-blocks-and-streaming.md`：统一 ContentBlock 和 Block 级流事件。
|
||
- `docs/contracts/run-observability.md`：每轮模型、工具、token、cache、费用和诊断字段。
|
||
- `docs/contracts/http-and-events.md`：通用 Header、错误和稳定事件。
|
||
|
||
### 安全、研究与交付
|
||
|
||
- `docs/security/security-and-diagnostics.md`：威胁、插件、设备、社区、支付和诊断双重授权。
|
||
- `docs/research/reference-projects.md`：deepseek-harness、pi、MemOS、其他角色记忆项目和模型网关证据。
|
||
- `docs/delivery/implementation-roadmap.md`：14 个完整 1.0 工作包。
|
||
|
||
## 5. API 实现要点
|
||
|
||
### 5.1 分面
|
||
|
||
```text
|
||
Native: https://api.<domain>/v1
|
||
OpenAI: https://gateway.<domain>/openai/v1
|
||
Anthropic: https://gateway.<domain>/anthropic/v1
|
||
Webhook: https://api.<domain>/webhooks/v1
|
||
```
|
||
|
||
兼容 Gateway 只提供模型推理，不读写 Character、Memory、Community、Device、Order 或 PluginInstallation。需要自动 Tool Loop、多 Agent、审批和持久化时调用 Native Run API。
|
||
|
||
### 5.2 核心消息请求
|
||
|
||
```http
|
||
POST /v1/conversations/{conversation_id}/messages
|
||
Idempotency-Key: <opaque>
|
||
```
|
||
|
||
请求可同时包含 ContentBlock 和 `start_run=true`。服务端在一个事务创建 Message、Run、Audit 与 Outbox；失败时不能只留下 Message 或 Run。
|
||
|
||
### 5.3 实时协议
|
||
|
||
- Run 和通知：SSE；
|
||
- 实时语音、协同、设备：WebSocket；
|
||
- Event 有 Run `sequence`，Block delta 有 `delta_index`；
|
||
- 客户端按 event ID 和 `(block_id, delta_index)` 去重；
|
||
- 流缺口通过重放或最终 Message 对账；
|
||
- `content.block.completed` 和 `message.completed` 是权威快照；
|
||
- 首个可见 delta 后禁止切换 Provider 重新生成另一份内容。
|
||
|
||
### 5.4 诊断
|
||
|
||
普通 Run API 不返回 ModelCall、Tool 参数或 ContextSnapshot 详情。诊断读取同时要求普通认证和：
|
||
|
||
```http
|
||
Hunjing-Diagnostic-Token: hjd_...
|
||
Hunjing-Diagnostic-Purpose: user_inspection
|
||
```
|
||
|
||
Grant 默认 15 分钟、单次、绑定 Run。隐藏推理、密钥、Authorization、签名 URL 永不返回。
|
||
|
||
## 6. 统一富内容实现要点
|
||
|
||
ContentBlock 类型包括：
|
||
|
||
```text
|
||
text markdown code quote table callout math mermaid
|
||
image video audio file gallery avatar
|
||
tool_call tool_result agent_status approval_request artifact citation error
|
||
```
|
||
|
||
前端分级实时策略：
|
||
|
||
| 类型 | 策略 |
|
||
| --- | --- |
|
||
| Text/Markdown | 增量显示、节流解析，未闭合结构保持源码态 |
|
||
| Code | 纯文本优先，按行/时间片使用 Shiki |
|
||
| Math | 定界符闭合或 Block 完成后用 KaTeX，保留 MathML/fallback |
|
||
| Mermaid | Block 完成后 strict mode 隔离渲染并净化 SVG |
|
||
| Image/Video/Audio/File | progress 占位，resource ready 后加载 |
|
||
| Tool/Agent/Approval | 类型化状态替换，不模拟为自由文本 |
|
||
|
||
不要把所有内容压回一个 Markdown 字符串。不要在每个 token 上重跑 Shiki、KaTeX 或 Mermaid。失败降级必须保留源码/内容，而不是空白。
|
||
|
||
## 7. 数据与安全不变量
|
||
|
||
- 关系数据库是权威事实源；对象存储保存媒体；全文/向量/图/推荐/缓存均可重建。
|
||
- 所有 Query 在数据库层带 PersonalDomain/Workspace/Finance scope，不能先全表读后应用层过滤。
|
||
- CharacterVersion、Message Revision、MemoryVersion、ReleaseVersion、PluginVersion 和 LedgerEntry 都是可追溯版本/事实。
|
||
- Ledger 不可变；退款和纠错写反向分录。
|
||
- 购买不等于安装插件；安装不等于启用；启用不等于批准新增权限。
|
||
- 未信任插件不能进主进程；Python import、Node VM 和 WebView 都不是安全 Sandbox。
|
||
- Tool input、Markdown、Mermaid、公式、SVG、文件路径、URL、媒体和 Webhook 全部是边界输入。
|
||
- 没有符合策略的隔离后端时拒绝危险执行，不能回退宿主执行。
|
||
- 删除传播到主存储、索引、缓存和派生数据；墓碑不保留原文。
|
||
|
||
## 8. 下一步建议
|
||
|
||
从 `WP-01 工程、契约与身份` 开始，但不要直接实现业务页面。建议顺序：
|
||
|
||
1. 建立仓库目录、Makefile、Python/Next.js/Tauri 最小可运行工程；
|
||
2. 把当前 Markdown 契约转换为 OpenAPI 3.1 和 JSON Schema；
|
||
3. 先定义并生成通用 ID、错误、分页、Money、ContentBlock、Event 和认证 DTO；
|
||
4. 建立 PostgreSQL 基线（统一引擎，ADR-024）、Alembic、User/PersonalDomain/Session/ServiceAccount；
|
||
5. 实现 OAuth 2.1 边界和 Header/CSRF/Origin/Scope 校验；
|
||
6. 实现一个不调用模型的 Conversation→Message→Run 事务和 SSE 空状态闭环；
|
||
7. 再进入 `WP-02` 与 `WP-03`，不要先实现插件市场、支付或 3D 页面。
|
||
|
||
第一条垂直切片的完成证据至少包括：`make` 中可发现的启动/迁移/生成/检查命令；OpenAPI 生成客户端无 drift；一次请求原子写入 Message、Run、Audit 与 Outbox；失败注入不留下孤儿资源；SSE 可返回快照和终止状态；跨 Personal Domain 请求失败关闭；自动化测试命令可重复通过。
|
||
|
||
这是实现顺序，不是缩减 1.0 范围。每完成一个 TODO，必须补实现位置、调用点、测试和运行证据。具体文件布局和依赖版本应在建立工程时形成 ADR/机器配置，不在交接摘要中维护第二份易漂移清单。
|
||
|
||
## 9. 尚未确定的发布与契约配置
|
||
|
||
以下保持 TODO，不要替用户虚构：
|
||
|
||
- 运营主体、首发地区、隐私角色和数据保留期限；
|
||
- 支付、退款、KYC、税务、发票和创作者结算 Provider；
|
||
- 首批模型、ASR、TTS、图像、对象存储和媒体处理 Provider；
|
||
- 费率、分成、结算周期、退款窗口、准备金和拒付规则；
|
||
- 上传大小、Run/Agent 并发、RPM/TPM、媒体与流重放保留上限；默认分页已由 `contracts/api-conventions.md` 固定；
|
||
- 社区规范、年龄分级、审核标准、申诉和版权投诉时限；
|
||
- 正式域名、首发币种和地区可售策略；
|
||
- 兼容 Gateway 首发支持的 Provider beta 功能清单。
|
||
|
||
Provider 选择和纯内部容量数值可在 Port/配置边界建立后延后；运营主体、地区、保留期限、币种/税务/退款、年龄分级、社区治理和兼容 beta 承诺会影响用户权利或公开语义，阻塞相关契约冻结及正式 1.0。任一项开始影响开发期数据模型时先询问用户并新增 ADR，不把它们笼统视为普通配置。
|
||
|
||
## 10. 验证证据
|
||
|
||
本文件不保存会迅速陈旧的文件数、行数和 Mermaid 数。每次交接或提交都应针对当前工作区重新生成带日期、Git commit/dirty 状态、命令和工具版本的结果；未保存命令或产物的“检查通过”不能作为发布证据。
|
||
|
||
当前仍是纯文档设计阶段：没有代码测试、OpenAPI drift、迁移或运行证据。复核应优先通过项目 Makefile；Makefile 尚未建立时至少执行：
|
||
|
||
- `git diff --check`；
|
||
- 内部 Markdown 链接检查；
|
||
- 重复标题检查；
|
||
- 所有 Mermaid 图实际渲染；
|
||
- 关键稳定值只在 `docs/contracts/` 定义的映射检查。
|
||
|
||
开始实现后，验证证据必须进入工作包的验收记录，而不是回填一段无法复现的摘要。
|
||
|
||
## 11. 工作区注意事项
|
||
|
||
- 当前文件尚未提交。不要执行 `git reset --hard`、`git clean` 或覆盖式重建。
|
||
- Git 状态中的修改均应视为用户当前工作成果；提交前先检查完整 diff。
|
||
- IDE 资源列表可能仍显示已经被重建删除的旧路径，这是编辑器缓存，不代表磁盘文件存在。
|
||
- `CLAUDE.md` 仍通过 `@AGENTS.md` 加载项目规则；后续不要在两处复制规则。
|
||
- 任何新文档都要加入 `docs/README.md`；任何新稳定值先进入 `docs/contracts/README.md` 和机器 Schema。
|
||
|
||
## 12. 交接完成条件
|
||
|
||
接手者先完成以下知识核对；这只证明理解设计，不代表工作包验收：
|
||
|
||
- 1.0 与 2.0 的唯一边界是什么？
|
||
- Native API 与两类兼容 Gateway 为什么分域？
|
||
- Message 和 Run 为什么原子创建？
|
||
- ContentBlock 为什么不能退回单一 Markdown？
|
||
- 什么内容可以增量渲染，什么必须完成后渲染？
|
||
- 文化名和稳定工程值如何分层？
|
||
- 哪些能力可插件化，哪些必须留在治理内核？
|
||
- Provider usage、Prompt Cache、ModelCall attempt 如何记录？
|
||
- 为什么普通 Run API 不能返回详细诊断？
|
||
- MemoryCandidate、Memory 和 MemoryVersion 为什么分离，记忆所有权由什么边界决定？
|
||
- 为什么购买插件、安装插件、启用插件和授予权限必须分离？
|
||
|
||
无法回答时回到本文第 3–7 节和对应事实源，不要凭印象编码。能够回答后，仍须为当前工作包补齐机器契约、可运行命令和需求→实现→调用点→测试→证据矩阵，才可开始相应实现。
|