chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9dafb8fe72a42a72a6f821ee88cfaaa2d32e77f7
hunjing/docs/contracts/README.md
T
chenxin 42513d13c6 📝 docs: 建立魂镜完整 1.0 设计文档体系 
- 产品层：产品宪章与永久禁域、产品定义、完整 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
2026-09-09 21:07:14 +08:00

188 lines
7.0 KiB
Markdown
Raw Blame History

# 协议与稳定标识
本目录是稳定工程契约的单一事实源。代码实现前应生成 OpenAPI 3.1 / JSON Schema；本文件定义尚未机器化前的命名基线。
## 命名
| 对象 | 规则 | 示例 |
| --- | --- | --- |
| JSON / SQL | `snake_case` | `personal_domain_id` |
| HTTP path 参数 | `snake_case` | `{run_id}` |
| 事件 | `domain.action` | `model.request.completed` |
| 插件稳定名 | reverse-domain 或点分稳定名 | `example.web-fetch` |
| 逻辑模型 | `kebab-case` | `default-chat` |
| 时间 | UTC RFC 3339 | `2026-09-02T08:00:00Z` |
## ID 前缀
| 对象 | 前缀 | 生成版本 |
| --- | --- | --- |
| User | `user_` | UUIDv7 |
| PersonalDomain | `domain_` | UUIDv7 |
| Character | `character_` | UUIDv7 |
| CharacterVersion | `character_version_` | UUIDv7 |
| CharacterAsset | `character_asset_` | UUIDv7 |
| CharacterImport | `import_` | UUIDv7 |
| Export | `export_` | UUIDv7 |
| Agent | `agent_` | UUIDv7 |
| Conversation | `conversation_` | UUIDv7 |
| Branch | `branch_` | UUIDv7 |
| Message | `message_` | UUIDv7 |
| ContentBlock | `block_` | UUIDv7 |
| File | `file_` | UUIDv7 |
| Upload | `upload_` | UUIDv7 |
| Run | `run_` | UUIDv7 |
| BigCycle | `cycle_` | UUIDv7 |
| Turn | `turn_` | UUIDv7 |
| ModelCall | `model_call_` | UUIDv7 |
| ToolCall | `tool_call_` | UUIDv7 |
| Approval | `approval_` | UUIDv7 |
| Job | `job_` | UUIDv7 |
| MemoryCandidate | `memory_candidate_` | UUIDv7 |
| Memory | `memory_` | UUIDv7 |
| MemoryVersion | `memory_version_` | UUIDv7 |
| KnowledgeDocument | `knowledge_document_` | UUIDv7 |
| KnowledgeChunk | `knowledge_chunk_` | UUIDv7 |
| ContextSnapshot | `context_snapshot_` | UUIDv7 |
| PluginSnapshot | `plugin_snapshot_` | UUIDv7 |
| DiagnosticGrant | `diagnostic_grant_` | UUIDv7 |
| Workspace | `workspace_` | UUIDv7 |
| WorkspaceInvitation | `invitation_` | UUIDv7 |
| Project | `project_` | UUIDv7 |
| Review | `review_` | UUIDv7 |
| CollaborationSession | `collab_session_` | UUIDv7 |
| CommunityContent | `content_` | UUIDv7 |
| InboxThread | `inbox_thread_` | UUIDv7 |
| Report | `report_` | UUIDv7 |
| ModerationCase | `moderation_` | UUIDv7 |
| Plugin | `plugin_` | UUIDv7 |
| PluginVersion | `plugin_version_` | UUIDv7 |
| PluginInstallation | `plugin_installation_` | UUIDv7 |
| MCPServer | `mcp_` | UUIDv7 |
| Skill | `skill_` | UUIDv7 |
| ReleaseVersion | `release_` | UUIDv7 |
| MarketplaceListing | `listing_` | UUIDv7 |
| Order | `order_` | UUIDv7 |
| PaymentAttempt | `payment_` | UUIDv7 |
| Refund | `refund_` | UUIDv7 |
| Entitlement | `entitlement_` | UUIDv7 |
| LedgerEntry | `ledger_` | UUIDv7 |
| SettlementBatch | `settlement_` | UUIDv7 |
| Device | `device_` | UUIDv7 |
| DeviceGrant | `device_grant_` | UUIDv7 |
| DeviceSession | `device_session_` | UUIDv7 |
| MediaAsset | `media_` | UUIDv7 |
| MediaJob | `media_job_` | UUIDv7 |
| Voice | `voice_` | UUIDv7 |
| AvatarModel | `avatar_` | UUIDv7 |
| RealtimeVoiceSession | `voice_session_` | UUIDv7 |
| ServiceAccount | `service_account_` | UUIDv7 |
| APIKey record | `key_` | UUIDv7 |
| WebhookEndpoint | `webhook_endpoint_` | UUIDv7 |
| WebhookEvent | `webhook_event_` | UUIDv7 |
| AuditEvent | `audit_` | UUIDv7 |
| Event | `event_` | UUIDv7 |
| Request | `request_` | UUIDv4（仅服务端生成） |
| Trace record | `trace_` | UUIDv4 |
### 生成规则
- UUIDv4/UUIDv7 的位布局、variant 和文本格式遵循 RFC 9562；各语言使用经过测试的标准库或成熟实现，不自行拼位。
- 持久化业务资源、版本、事件、账务、审计和异步任务统一使用 UUIDv7，获得数据库索引局部性和大致创建顺序。
- 请求关联与 Trace record 不需要按创建时间排序，使用 UUIDv4。调用方提供的合法 `Hunjing-Request-ID` 原样保留；只有服务端补发时使用 `request_<uuidv4>`。
- 格式固定为 `<prefix><lowercase-canonical-uuid>`，例如 `memory_01941f29-7c00-7cc8-9c2a-6f4f0f2de512`；解析时必须校验前缀和 UUID version，不能只校验 UUID 文本。
- UUIDv7 内含近似生成时间，但 `created_at`、`occurred_at` 和数据库提交顺序才是权威时间；不得从 ID 推导业务时间、权限、分页结果或事件顺序。
- W3C `traceparent` 中的 `trace-id` 仍按 W3C Trace Context 生成 16 字节非零随机值并编码为 32 位小写十六进制，不添加 `trace_` 前缀，也不与 Trace record ID 混用。
- API key 明文、Diagnostic Token、CSRF token、OAuth token、Webhook secret、实时恢复 token、ExecutionTicket 和预签名 URL capability 使用 CSPRNG/对应标准生成的 opaque value，不使用 UUIDv4 或 UUIDv7。
- `Idempotency-Key`、`client_message_id`、Provider request ID 和 Provider event ID 属外部或调用方标识，按各自契约验证并原样保存，不改写成平台 UUID。
- 前缀属于公开字符串的一部分；未经本文件登记，不新增公开前缀。
## 通用枚举
### `run_status`
`queued`、`running`、`waiting_approval`、`completed`、`failed`、`cancelled`
### `memory_candidate_status`
`pending_review`、`approved`、`rejected`、`expired`
### `memory_status`
`active`、`superseded`、`archived`、`deleted`
### `memory_kind`
`fact`、`preference`、`event`、`relationship`
### `sensitivity`
`none`、`low`、`medium`、`high`
### `permission_decision`
`allow`、`ask`、`deny`
### `usage_source`
`provider`、`gateway_estimate`、`unavailable`
### `diagnostic_level`
`summary`、`detailed`、`sensitive`
### `publication_status`
`draft`、`submitted`、`published`、`limited`、`suspended`、`removed`
### `order_status`
`pending_payment`、`paid`、`partially_refunded`、`refunded`、`disputed`、`cancelled`
### `ledger_entry_type`
`charge`、`refund`、`platform_fee`、`creator_payable`、`tax`、`reserve`、`payout`、`reversal`
### `device_capability`
`file`、`camera`、`microphone`、`screen`、`location`、`notification`
### `plugin_runtime`
`bundled`、`declarative`、`remote`、`isolated_process`、`container`
### `canonical_scope`
`reality`、`world`、`simulation`
### `big_cycle_status`
`pending`、`running`、`completed`、`failed`
### `autonomy_level`
`introspective`、`rule_bound`、`approval_required`、`forbidden`
## 约束
- 未知值用 `null`，真实零值用 `0`；不能混淆。
- 金额为 `cost_minor: integer` + `currency: string`。
- 时长统一 `_ms` 非负整数。
- 哈希字段必须在 Schema 说明算法和编码。
- API 不暴露数据库实现后缀，如 `_json`。
- 客户端对新增枚举值必须走 unknown 分支，不能崩溃。
## 子文档
1. [API 总体约定](api-conventions.md)
2. [Hunjing Native API](native-api.md)
3. [模型网关兼容 API](gateway-compatible-api.md)
4. [实时 API 与 Webhook](realtime-and-webhooks.md)
5. [内部端口、事件与插件协议](internal-api.md)
6. [统一富内容与流式协议](content-blocks-and-streaming.md)
7. [1.0 API 表面总表](api-surface.md)
8. [HTTP 与事件契约](http-and-events.md)
9. [运行观测契约](run-observability.md)
10. [Lingtai C ABI](lingtai-ffi.md)
11. [Lingtai Service](lingtai-service.md)
Reference in new issue View Git Blame Copy Permalink