hunjing/docs/contracts/README.md

协议与稳定标识

本目录是稳定工程契约的单一事实源。代码实现前应生成 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 总体约定
2. Hunjing Native API
3. 模型网关兼容 API
4. 实时 API 与 Webhook
5. 内部端口、事件与插件协议
6. 统一富内容与流式协议
7. 1.0 API 表面总表
8. HTTP 与事件契约
9. 运行观测契约
10. Lingtai C ABI
11. Lingtai Service