0 Fork 0

Files

T

chenxin 5da1efe921 📝 docs: 统一 PostgreSQL 主库并固化索引命名约定

- 新增 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 引用

2026-09-09 21:14:10 +08:00

18 KiB

Raw Blame History

Hunjing 设计阶段交接文档

交接基线：完整 1.0 产品、架构、API、富内容、文化语言和工程规则已经定义；仓库当前仍处于设计阶段，不能把任何 TODO 表述为已实现。

1. 当前状态

本轮完成了文档体系重建和完整 1.0 设计收敛：

根 README.md、AGENTS.md 与 docs/ 已按当前目标重写；
文档数量、行数和图表数会随设计变更增长，不作为交接完成证据；以 docs/README.md 索引和当前检查结果为准；
完整 1.0 实施清单中的所有未勾选项都是真实待办；不得依赖本文件的历史计数判断完成度；
尚未开始正式代码实现，文档中的端点、表、事件和组件均是目标契约；
当前工作区文件均处于新增/修改状态，尚未提交；不要假定 Git 历史已保存本轮成果。

2. 不要重新讨论的已确认决策

除非用户明确改变决定，后续实现必须以这些结论为前提：

1.0 是一次完整整体交付：内部工作包可以并行和独立验收，但任何缺项都不能称为正式 1.0。
1.0 全量范围：角色、记忆、分支多模态对话、多 Agent、插件生态、实时语音、多语言、图像、Live2D、3D 运行编辑、Web/Tauri 桌面和移动、设备感知、完整社区、角色社区、协作、真实支付退款分成结算、运营和自托管全部进入 1.0。
2.0 边界：Blender 级完整 3D 建模器、LLM 直接修改完整 3D 几何/绑定、IoT/机器人/物理动作控制。
能力皆插件，治理内核不插件化：认证、授权、数据隔离、审批、Ledger、审计、事务和 Sandbox fail-closed 属于 Core。
插件双轨：声明式/远程插件默认受限；第三方本地代码插件即使受信也运行在独立进程/容器；只有 bundled Core plugin 可进主进程。
技术按需：能力和安全边界强制；语言、数据库、专用向量/图存储和服务拆分按 ADR、官方资料及实测决定。
3D 1.0 深度：VRM/glTF 导入、材质/骨骼/表情/动作/场景编辑、运行和导出；不自研完整建模器。
客户端：Next.js Web + Tauri v2 Desktop + Tauri v2 iOS/Android。
社区私信：服务端治理的一对一和小群聊，服务端加密存储，可举报/屏蔽/审核/多端同步；1.0 不做 E2EE。
真实市场闭环：支付、退款、争议、平台费、创作者分成、余额、结算和对账进入 1.0，Ledger 不可变。
API 开放面：公开 Native API，同时提供 OpenAI-compatible 和 Anthropic Messages-compatible 网关。
API 域名：Native 为 api.<domain>/v1；兼容入口为 gateway.<domain>/openai/v1 与 gateway.<domain>/anthropic/v1。
认证：1.0 使用 OAuth 2.1；Web 为安全 Session Cookie，Tauri 为 Authorization Code + PKCE，第三方为 OAuth Bearer，自动化为限 scope Service Account API key；凭据只经 Header 传递。2.0 再设计自研加密认证系统。
消息与 Run：聊天消息和可选 Run 在一个事务原子创建；任务工作台可以显式创建无 Conversation Run。
富内容：Native API 使用类型化 ContentBlock；用户编辑可使用 Markdown 内嵌 Mermaid、代码和数学公式，服务端规范化为 canonical Block。
实时渲染：Markdown/代码增量；数学按完整定界符或完成后；Mermaid 和媒体在 Block 完成/资源 ready 后；最终 Block/Message 与流累积状态对账。
文化体系：产品采用完整“中国古代神话/道家文化名 · 直白解释”双层语言；API、数据库、事件、权限和日志只用中性英文稳定值。
隐藏推理：不采集、不持久化、不通过诊断接口返回 chain-of-thought；仅保存可见内容、可读摘要、工具轨迹和计数。
权威记忆：自动提取先产生 MemoryCandidate；批准、纠正、取代和恢复创建不可变 MemoryVersion。Personal Domain/Workspace 是所有权边界，全文、向量和图只是投影；KV cache、隐藏状态和权重适配不是 1.0 权威记忆。
ID 生成：持久化平台资源统一 UUIDv7；服务端 Request 与 Trace record 使用 UUIDv4；traceparent 遵循 W3C；秘密、Token、Ticket 和 capability 使用 CSPRNG opaque value，不使用 UUID。
灵台引擎双形态：性能与安全敏感的确定性核心以 C++ 实现为灵台引擎（太一/小周天/洛书/河图/陶钧/烛照六模块，承接旧版"灵台/九枢"血脉），同一核心可经稳定 C ABI 进程内嵌入 Python/Rust/Go 宿主，也可作为部署内部 gRPC 独立服务运行；引擎无权威状态、最小 I/O、fail closed，任何能力在两种形态语义一致。
内驱力与大周天演化（1.0）：角色具有用户可审阅的内驱力维度；大周天是交互事件触发的自我评估 Run，预算受控、产出候选、经确认演化并留版本谱系；不做后台自主运行、不伪造离线意识（守一不变）；引擎流式模块文化名"小周天"，与角色"大周天"构成大小周天体系。
产品宪章与永久禁域（ADR-019）：宪章是产品定义上位约束，九条永久禁域不可被 Prompt、插件、管理员或自托管配置关闭；决策优先序为安全合规 > 用户数据权 > 角色连续性 > 生态健康 > 商业目标。
三界归真作用域（ADR-020）：对话分真界/境界/幻境，归真携带 canonical_scope；境界只成世界知识候选、幻境不自动入忆；言可入幻、行必归真。
私箧、保全态与计费伦理（ADR-021）：私箧用户独立持钥、平台不可恢复；欠费/封禁只读保全不删数据；不按记忆、感情或亲密计费。
叩心进入 1.0（ADR-022）：角色主动联系先成叩心候选，受静默、频率、渠道与预算控制；不回应不降关系；不以追逐式消息换回流。
周天体系统一（ADR-023）：小周天=Run 可追踪认知闭环（完成信号为大周天唯一输入面），大周天=cycle_ 聚合根 + 四阶段评估（回顾/对照/提议/提交）+ 阶段记忆；吸收旧版契约骨架并补全其缺失的架构设计。
数据权与开放核心：PersonalDomain 数据默认不用于模型训练（自愿贡献需独立、明确、可撤销同意）；前台化名与法定身份分离核验；高敏数据可完全禁止跨区模型处理；核心 Apache-2.0 开放、品牌与官方资产单独保护、DCO 贡献、自托管遥测默认关闭；模型配置按"平台硬边界→目录→用户 BYOK→角色覆写→会话临时"继承。
统一 PostgreSQL（ADR-024）：服务端关系主库在开发、测试、自托管与正式部署统一 PostgreSQL，不设 SQLite 主库档（pgvector/中文全文无法在 SQLite 承载，双档必然残缺）；索引命名 pk_/uk_/idx_/fk_ 前缀。

正式 ADR 见架构决策记录。

3. 事实源与阅读路径

新接手者先读：

事实层级：

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 分面

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 核心消息请求

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 详情。诊断读取同时要求普通认证和：

Hunjing-Diagnostic-Token: hjd_...
Hunjing-Diagnostic-Purpose: user_inspection

Grant 默认 15 分钟、单次、绑定 Run。隐藏推理、密钥、Authorization、签名 URL 永不返回。

6. 统一富内容实现要点

ContentBlock 类型包括：

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 工程、契约与身份 开始，但不要直接实现业务页面。建议顺序：

建立仓库目录、Makefile、Python/Next.js/Tauri 最小可运行工程；
把当前 Markdown 契约转换为 OpenAPI 3.1 和 JSON Schema；
先定义并生成通用 ID、错误、分页、Money、ContentBlock、Event 和认证 DTO；
建立 PostgreSQL 基线（统一引擎，ADR-024）、Alembic、User/PersonalDomain/Session/ServiceAccount；
实现 OAuth 2.1 边界和 Header/CSRF/Origin/Scope 校验；
实现一个不调用模型的 Conversation→Message→Run 事务和 SSE 空状态闭环；
再进入 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 节和对应事实源，不要凭印象编码。能够回答后，仍须为当前工作包补齐机器契约、可运行命令和需求→实现→调用点→测试→证据矩阵，才可开始相应实现。

18 KiB Raw Blame History Unescape Escape