chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
new
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

12 KiB
Raw Permalink Blame History

Hunjing Native API

1. 设计总览

Native API 是角色、对话、Agent、媒体、插件、社区、协作和交易的唯一公共业务 API。模型直接调用使用独立 Gateway 兼容入口。

聊天采用消息与 Run 原子创建；任务工作台采用显式 Run 创建：

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. 身份、数据域和服务账号

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. 角色与发布版本

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. 对话、消息与分支

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 原子发送消息

POST /v1/conversations/{conversation_id}/messages
Idempotency-Key: msg-...

{
  "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"
  }
}

{
  "message": {"id": "message_01...", "status": "accepted"},
  "run": {"id": "run_01...", "status": "queued"}
}

start_run=false 只保存消息草稿/人工消息。事务失败时两个资源都不创建。client_message_id 用于乐观 UI 对账，不承担服务端幂等。

5. Agent 定义、Run 与审批

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

{
  "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. 记忆与知识

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 语义见记忆与知识架构。

7. 文件、媒体、语音、Live2D 与 3D

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. 设备与权限

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

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 与协作

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. 社区与服务端治理私信

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. 市场、订单、支付与结算

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 和导出删除

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. 受保护诊断

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}

诊断查询同时要求普通认证和：

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