📝 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
This commit is contained in:
chenxin committed
commit
42513d13c6
37 files changed
+5795
No files matched your search
@@ -0,0 +1,378 @@
|
||||
# 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
Block a user