chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
603a683c1453d7e746988271e35b23d9c3946178
hunjing/docs/contracts/native-api.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

379 lines
12 KiB
Markdown
Raw Blame History

# Hunjing Native API
## 1. 设计总览
Native API 是角色、对话、Agent、媒体、插件、社区、协作和交易的唯一公共业务 API。模型直接调用使用独立 Gateway 兼容入口。
聊天采用**消息与 Run 原子创建**；任务工作台采用**显式 Run 创建**：
```mermaid
sequenceDiagram
participant C as Client
participant A as Native API
participant D as Database
participant R as Agent Runtime
C->>A: POST conversation message, start_run=true
A->>D: transaction create Message and Run
D-->>A: committed resources
A-->>C: 201 message and run
A->>R: outbox run.queued
C->>A: GET run event stream
R-->>C: SSE events
```
## 2. 身份、数据域和服务账号
```text
GET /v1/me
GET /v1/personal-domains
GET /v1/personal-domains/{domain_id}
PATCH /v1/personal-domains/{domain_id}
GET /v1/service-accounts
POST /v1/service-accounts
GET /v1/service-accounts/{service_account_id}
PATCH /v1/service-accounts/{service_account_id}
DELETE /v1/service-accounts/{service_account_id}
POST /v1/service-accounts/{service_account_id}/keys
GET /v1/service-accounts/{service_account_id}/keys
DELETE /v1/service-accounts/{service_account_id}/keys/{key_id}
```
Service Account scope 显式列出资源和动作，不允许隐式继承用户全部权限。API key 明文只在创建响应出现一次。
## 3. 角色与发布版本
```text
GET /v1/characters
POST /v1/characters
GET /v1/characters/{character_id}
PATCH /v1/characters/{character_id}
DELETE /v1/characters/{character_id}
GET /v1/characters/{character_id}/versions
POST /v1/characters/{character_id}/versions
GET /v1/characters/{character_id}/versions/{version_id}
POST /v1/character-imports
GET /v1/character-imports/{import_id}
POST /v1/characters/{character_id}/exports
GET /v1/exports/{export_id}
POST /v1/character-forks
GET /v1/characters/{character_id}/assets
POST /v1/characters/{character_id}/assets
```
创建 CharacterVersion 必须带 `If-Match` 当前 Character ETag。Import 只创建待审查候选，不执行脚本、插件或宏。
## 4. 对话、消息与分支
```text
GET /v1/conversations
POST /v1/conversations
GET /v1/conversations/{conversation_id}
PATCH /v1/conversations/{conversation_id}
DELETE /v1/conversations/{conversation_id}
GET /v1/conversations/{conversation_id}/branches
POST /v1/conversations/{conversation_id}/branches
GET /v1/conversations/{conversation_id}/messages
POST /v1/conversations/{conversation_id}/messages
GET /v1/messages/{message_id}
POST /v1/messages/{message_id}/revisions
POST /v1/messages/{message_id}/regenerations
POST /v1/branches/{branch_id}/selections
POST /v1/branches/{branch_id}/transplants
```
### 4.1 原子发送消息
```http
POST /v1/conversations/{conversation_id}/messages
Idempotency-Key: msg-...
```
```json
{
"branch_id": "branch_01...",
"content": [
{"type": "text", "text": "分析这张图"},
{"type": "file", "file_id": "file_01..."}
],
"client_message_id": "client-local-id",
"start_run": true,
"run": {
"agent_id": "agent_01...",
"budget": {"max_cost_minor": 100, "currency": "USD"},
"response_mode": "stream"
}
}
```
```json
{
"message": {"id": "message_01...", "status": "accepted"},
"run": {"id": "run_01...", "status": "queued"}
}
```
`start_run=false` 只保存消息草稿/人工消息。事务失败时两个资源都不创建。`client_message_id` 用于乐观 UI 对账，不承担服务端幂等。
## 5. Agent 定义、Run 与审批
```text
GET /v1/agents
POST /v1/agents
GET /v1/agents/{agent_id}
PATCH /v1/agents/{agent_id}
GET /v1/agents/{agent_id}/versions
POST /v1/agents/{agent_id}/versions
GET /v1/runs
POST /v1/runs
GET /v1/runs/{run_id}
GET /v1/runs/{run_id}/turns
GET /v1/runs/{run_id}/children
GET /v1/runs/{run_id}/events
POST /v1/runs/{run_id}/steering-messages
POST /v1/runs/{run_id}/cancellations
POST /v1/runs/{run_id}/resumptions
GET /v1/approvals/{approval_id}
POST /v1/approvals/{approval_id}/decisions
```
### 5.1 显式任务 Run
```json
{
"agent_id": "agent_01...",
"input": [{"type": "text", "text": "整理这些资料并生成报告"}],
"resources": [
{"type": "file", "file_id": "file_01...", "access": "read_only"}
],
"budget": {
"max_cost_minor": 500,
"currency": "USD",
"max_children": 3,
"max_duration_ms": 1800000
},
"output_contract": {
"type": "artifact",
"accepted_media_types": ["text/markdown", "application/pdf"]
}
}
```
Run 创建、取消、恢复和 ApprovalDecision 都要求 `Idempotency-Key`。ApprovalDecision 值为 `allow` 或 `deny`，拒绝可带用户可见原因；审批过期后不能复用。
## 6. 记忆与知识
```text
GET /v1/characters/{character_id}/memory-candidates
POST /v1/characters/{character_id}/memory-candidates
GET /v1/memory-candidates/{candidate_id}
POST /v1/memory-candidates/{candidate_id}/decisions
GET /v1/memories
POST /v1/memories
GET /v1/memories/{memory_id}
PATCH /v1/memories/{memory_id}
DELETE /v1/memories/{memory_id}
GET /v1/memories/{memory_id}/versions
POST /v1/memory-searches
GET /v1/knowledge-documents
POST /v1/knowledge-documents
GET /v1/knowledge-documents/{document_id}
PATCH /v1/knowledge-documents/{document_id}
DELETE /v1/knowledge-documents/{document_id}
```
Memory Search 使用 POST，因为过滤、scope、rerank 和预算是结构化请求；它只读，不要求幂等键。响应必须包含命中版本、来源、各检索通道分数、重排结果、召回原因和是否进入上下文。`POST /v1/memories` 与 Candidate decision 是幂等命令；`PATCH /v1/memories/{memory_id}` 必须带 `If-Match`，纠正创建新 MemoryVersion，不原地覆盖。所有权、状态过滤、删除和 ContextSnapshot 语义见[记忆与知识架构](../architecture/memory-and-knowledge.md)。
## 7. 文件、媒体、语音、Live2D 与 3D
```text
POST /v1/uploads
GET /v1/uploads/{upload_id}
POST /v1/uploads/{upload_id}/completions
GET /v1/files/{file_id}
DELETE /v1/files/{file_id}
GET /v1/files/{file_id}/content
GET /v1/media-assets
POST /v1/media-assets
GET /v1/media-assets/{media_id}
DELETE /v1/media-assets/{media_id}
POST /v1/media-jobs
GET /v1/media-jobs/{job_id}
POST /v1/media-jobs/{job_id}/cancellations
GET /v1/voices
POST /v1/voices
POST /v1/voice-consents
DELETE /v1/voice-consents/{consent_id}
POST /v1/realtime-voice-sessions
GET /v1/avatar-models/{avatar_id}
POST /v1/avatar-models
POST /v1/avatar-models/{avatar_id}/revisions
POST /v1/avatar-models/{avatar_id}/exports
```
`media_jobs` 的 `operation` 覆盖 ASR、TTS、image generation/edit、Live2D layer/validation、VRM/glTF validation/normalization 等；参数由 operation-specific JSON Schema 校验。
## 8. 设备与权限
```text
GET /v1/devices
POST /v1/devices/registrations
GET /v1/devices/{device_id}
PATCH /v1/devices/{device_id}
DELETE /v1/devices/{device_id}
GET /v1/device-grants
POST /v1/device-grants
GET /v1/device-grants/{grant_id}
DELETE /v1/device-grants/{grant_id}
POST /v1/device-sessions
GET /v1/device-sessions/{session_id}
POST /v1/device-sessions/{session_id}/terminations
```
DeviceGrant 创建 body 显式给出 capability、character、purpose、scope、precision、foreground/background、expiry 和 retention。OS 拒绝权限时不能在服务端伪装已授权。
## 9. 插件、MCP 与 Skill
```text
GET /v1/plugins
POST /v1/plugins
GET /v1/plugins/{plugin_id}
GET /v1/plugins/{plugin_id}/versions
POST /v1/plugins/{plugin_id}/versions
GET /v1/plugin-versions/{version_id}
POST /v1/plugin-versions/{version_id}/submissions
GET /v1/plugin-installations
POST /v1/plugin-installations
GET /v1/plugin-installations/{installation_id}
PATCH /v1/plugin-installations/{installation_id}
DELETE /v1/plugin-installations/{installation_id}
POST /v1/plugin-installations/{installation_id}/permission-decisions
GET /v1/mcp-servers
POST /v1/mcp-servers
PATCH /v1/mcp-servers/{server_id}
DELETE /v1/mcp-servers/{server_id}
GET /v1/skills
POST /v1/skills
```
上传 PluginVersion 不等于发布；购买不等于安装；安装不等于启用；升级新增权限必须重新创建 PermissionDecision。
## 10. Workspace 与协作
```text
GET /v1/workspaces
POST /v1/workspaces
GET /v1/workspaces/{workspace_id}
PATCH /v1/workspaces/{workspace_id}
GET /v1/workspaces/{workspace_id}/members
POST /v1/workspaces/{workspace_id}/invitations
DELETE /v1/workspaces/{workspace_id}/members/{user_id}
PATCH /v1/workspaces/{workspace_id}/members/{user_id}
GET /v1/projects
POST /v1/projects
GET /v1/projects/{project_id}
PATCH /v1/projects/{project_id}
GET /v1/projects/{project_id}/revisions
POST /v1/projects/{project_id}/revisions
POST /v1/projects/{project_id}/reviews
POST /v1/reviews/{review_id}/decisions
POST /v1/collaboration-sessions
```
成员编辑、评审、发布、市场上架和财务权限分离。权限变更、合并和发布要求 ETag/If-Match。
## 11. 社区与服务端治理私信
```text
GET /v1/profiles/{user_id}
PUT /v1/me/following/{user_id}
DELETE /v1/me/following/{user_id}
PUT /v1/me/blocks/{user_id}
DELETE /v1/me/blocks/{user_id}
GET /v1/community-content
POST /v1/community-content
GET /v1/community-content/{content_id}
PATCH /v1/community-content/{content_id}
DELETE /v1/community-content/{content_id}
GET /v1/community-content/{content_id}/comments
POST /v1/community-content/{content_id}/comments
PUT /v1/community-content/{content_id}/reactions/{reaction}
DELETE /v1/community-content/{content_id}/reactions/{reaction}
GET /v1/feeds/home
POST /v1/community-searches
POST /v1/reports
GET /v1/moderation-cases/{case_id}
POST /v1/moderation-cases/{case_id}/appeals
GET /v1/inbox/threads
POST /v1/inbox/threads
GET /v1/inbox/threads/{thread_id}/messages
POST /v1/inbox/threads/{thread_id}/messages
PATCH /v1/inbox/threads/{thread_id}/members/{user_id}
DELETE /v1/inbox/threads/{thread_id}/members/{user_id}
```
私信和小群聊使用服务端加密存储、多端同步、举报、屏蔽和审核，不承诺端到端加密。私信与角色 Conversation 使用不同资源类型和权限，避免混淆。
## 12. 市场、订单、支付与结算
```text
GET /v1/marketplace-listings
POST /v1/marketplace-listings
GET /v1/marketplace-listings/{listing_id}
PATCH /v1/marketplace-listings/{listing_id}
POST /v1/marketplace-listings/{listing_id}/publications
GET /v1/orders
POST /v1/orders
GET /v1/orders/{order_id}
POST /v1/orders/{order_id}/payment-sessions
POST /v1/orders/{order_id}/refunds
GET /v1/refunds/{refund_id}
GET /v1/entitlements
GET /v1/entitlements/{entitlement_id}
GET /v1/creator-accounts/{creator_id}
PATCH /v1/creator-accounts/{creator_id}
GET /v1/creator-accounts/{creator_id}/balances
GET /v1/creator-accounts/{creator_id}/settlements
GET /v1/settlements/{settlement_id}
GET /v1/creator-accounts/{creator_id}/statements
```
客户端不能提交权威金额。创建 Order 只接受 listing/version/quantity/coupon 等业务输入，服务端计算价格、税、许可和卖家快照。Payment/Refund/Payout 结果以验签 Webhook 和 Ledger 为准。
## 13. 通知、Webhook 和导出删除
```text
GET /v1/notifications
POST /v1/notifications/{notification_id}/reads
GET /v1/webhook-endpoints
POST /v1/webhook-endpoints
PATCH /v1/webhook-endpoints/{endpoint_id}
DELETE /v1/webhook-endpoints/{endpoint_id}
POST /v1/webhook-endpoints/{endpoint_id}/secret-rotations
POST /v1/data-exports
GET /v1/data-exports/{export_id}
POST /v1/deletion-requests
GET /v1/deletion-requests/{deletion_id}
```
Webhook secret 明文只在创建/轮换响应出现一次。导出和删除是异步资源，具有 scope、状态、进度、失败和审计，不使用一个全能同步端点。
## 14. 受保护诊断
```text
POST /v1/diagnostic-grants
GET /v1/diagnostic-grants/{grant_id}
DELETE /v1/diagnostic-grants/{grant_id}
GET /v1/runs/{run_id}/diagnostics
GET /v1/runs/{run_id}/diagnostics/turns/{turn_id}
```
诊断查询同时要求普通认证和：
```http
Hunjing-Diagnostic-Token: hjd_...
Hunjing-Diagnostic-Purpose: user_inspection
```
Grant 绑定 subject、domain、run/turn、scope、level、purpose、expiry 和 uses。普通 Run API 不返回模型 attempt、脱敏工具参数或 Context Manifest 明细。
Reference in new issue View Git Blame Copy Permalink