# 协议与稳定标识

本目录是稳定工程契约的单一事实源。代码实现前应生成 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)