# 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 明细。