API 设计

HnsX 服务端对外提供两套接口：REST API 供 Console 和 SDK 使用，gRPC API 供 CLI 和内部服务使用。底层共享同一份 Protobuf 协议定义。

1. 设计原则

协议优先：proto/hnsx/v1/ 是 API 的唯一真相源。
REST 对外：Console / SDK 通过 HTTP/REST + JSON 调用。
gRPC 对内：CLI / Runtime Worker 通过 gRPC 调用。
实时推送：Session Observation 通过 SSE 推送。
资源命名：使用名词复数，路径语义清晰。
版本化：API 路径前缀 /api/v1/。
分页：列表接口统一 limit / offset。
错误统一：HTTP status + code + message 的 JSON 错误体。

2. 错误响应

{
  "code": "DOMAIN_NOT_FOUND",
  "message": "Domain 'customer-service' not found",
  "details": {
    "domain_id": "customer-service"
  }
}

HTTP Status	场景
200	成功
201	创建成功
204	删除成功，无返回体
400	请求参数错误
401	未认证
403	无权限
404	资源不存在
409	资源冲突（如重复 ID）
422	业务校验失败
500	服务端错误

3. Domain API

3.1 列出 Domain

GET /api/v1/domains?limit=20&offset=0

响应：

{
  "items": [
    {
      "id": "customer-service",
      "version": "0.1.0",
      "description": "Routes customer questions.",
      "status": "active",
      "created_at": "2026-07-08T12:00:00Z",
      "updated_at": "2026-07-08T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

3.2 获取 Domain

GET /api/v1/domains/:id

响应：

{
  "id": "customer-service",
  "version": "0.1.0",
  "description": "...",
  "harness": { ... },
  "eval": { ... },
  "status": "active",
  "created_at": "2026-07-08T12:00:00Z",
  "updated_at": "2026-07-08T12:00:00Z"
}

3.3 注册 Domain

POST /api/v1/domains
Content-Type: application/json

{
  "id": "customer-service",
  "version": "0.1.0",
  "description": "...",
  "harness": { ... },
  "eval": { ... }
}

3.4 更新 Domain

PUT /api/v1/domains/:id
Content-Type: application/json

{
  "version": "0.2.0",
  "description": "...",
  "harness": { ... }
}

3.5 删除 Domain

DELETE /api/v1/domains/:id

3.6 获取 Domain 版本列表

GET /api/v1/domains/:id/versions

3.7 获取 Domain 指定版本

GET /api/v1/domains/:id/versions/:version

3.8 验证 Domain

POST /api/v1/domains/:id/validate
Content-Type: application/json

{
  "harness": { ... }
}

4. Session API

4.1 列出 Session

GET /api/v1/sessions?domain=customer-service&state=running&limit=20&offset=0

4.2 获取 Session

GET /api/v1/sessions/:id

响应：

{
  "id": "sess-001",
  "domain_id": "customer-service",
  "domain_version": "0.1.0",
  "orchestration": "supervisor",
  "state": "completed",
  "trigger": { "question": "Why was I charged twice?" },
  "result": { "response": "..." },
  "trace_id": "trace-001",
  "started_at": "2026-07-08T12:00:00Z",
  "completed_at": "2026-07-08T12:00:05Z",
  "summary": {
    "total_cost_usd": 0.05,
    "duration_ms": 5000,
    "agent_invocations": 2,
    "tool_invocations": 1
  }
}

4.3 触发 Session

POST /api/v1/sessions
Content-Type: application/json

{
  "domain_id": "customer-service",
  "domain_version": "0.1.0",
  "trigger": { "question": "Why was I charged twice?" }
}

响应：

{
  "id": "sess-001",
  "state": "running"
}

4.4 重跑 Session

POST /api/v1/sessions/:id/rerun

4.5 取消 Session

POST /api/v1/sessions/:id/cancel

4.6 获取 Session Trace

GET /api/v1/sessions/:id/trace

响应：

{
  "trace_id": "trace-001",
  "session_id": "sess-001",
  "observations": [ ... ]
}

4.7 实时订阅 Session 事件

GET /api/v1/sessions/:id/events
Accept: text/event-stream

SSE 事件：

event: observation
data: {"kind":"text","agent_id":"billing","payload":{"content":"..."}}

event: state
data: {"state":"completed"}

event: done
data: {}

5. Trace API

5.1 查询 Trace

GET /api/v1/traces?domain=customer-service&session=sess-001&from=2026-07-01&to=2026-07-08&limit=20

响应：

{
  "items": [
    {
      "trace_id": "trace-001",
      "session_id": "sess-001",
      "domain_id": "customer-service",
      "status": "completed",
      "started_at": "2026-07-08T12:00:00Z",
      "duration_ms": 5000
    }
  ],
  "total": 1
}

5.2 获取 Trace 详情

GET /api/v1/traces/:traceId

6. Eval API

Eval sets are globally scoped under /api/v1/evals. The domain_id field inside each set ties it to a domain.

6.1 列出 EvalSet

GET /api/v1/evals?limit=20&offset=0

6.2 获取 EvalSet

GET /api/v1/evals/:setId

6.3 创建 EvalSet

POST /api/v1/evals
Content-Type: application/json

{
  "set_id": "routing-accuracy",
  "domain_id": "customer-service",
  "description": "...",
  "cases": [ ... ]
}

6.4 更新 EvalSet

PUT /api/v1/evals/:setId
Content-Type: application/json

{
  "description": "...",
  "cases": [ ... ]
}

6.5 删除 EvalSet

DELETE /api/v1/evals/:setId

6.6 运行 Eval

POST /api/v1/evals/:setId/run
Content-Type: application/json

{
  "orchestration": "supervisor",
  "baseline_run_id": "eval-run-001"
}

响应：

{
  "eval_run_id": "eval-run-002",
  "state": "running"
}

6.7 获取 EvalRun

GET /api/v1/evals/:setId/runs/:runId

响应：

{
  "id": "eval-run-002",
  "set_id": "routing-accuracy",
  "domain_id": "customer-service",
  "state": "completed",
  "score": 0.92,
  "total_cases": 50,
  "passed_cases": 46,
  "total_cost_usd": 1.5,
  "duration_ms": 120000,
  "baseline_run_id": "eval-run-001",
  "cases": [ ... ],
  "created_at": "2026-07-08T12:00:00Z"
}

6.8 列出 EvalRun

GET /api/v1/evals/:setId/runs?limit=20&offset=0

7. Metric API

7.1 获取 Domain 指标

GET /api/v1/metrics?domain=customer-service&from=2026-07-01&to=2026-07-08

响应：

{
  "domain_id": "customer-service",
  "total_sessions": 150,
  "completed_sessions": 140,
  "failed_sessions": 10,
  "total_cost_usd": 12.5,
  "avg_duration_ms": 2500,
  "agent_invocations": 300,
  "tool_invocations": 120
}

7.2 获取 Agent 指标

GET /api/v1/metrics/agents?domain=customer-service

8. Audit API

8.1 查询 AuditLog

GET /api/v1/audit?action=tool_call&decision=deny&limit=100

响应：

{
  "items": [
    {
      "id": "audit-001",
      "timestamp": "2026-07-08T12:00:00Z",
      "session_id": "sess-001",
      "domain_id": "customer-service",
      "action": "tool_call",
      "actor": "agent:billing",
      "resource": "tool:shell",
      "decision": "deny",
      "reason": "shell is in denied_tools list"
    }
  ],
  "total": 1
}

9. Approval API

9.1 列出待审批

GET /api/v1/approvals?status=pending&limit=20

9.2 审批通过

POST /api/v1/approvals/:id/approve
Content-Type: application/json

{
  "comment": "Approved by operator"
}

9.3 审批拒绝

POST /api/v1/approvals/:id/reject
Content-Type: application/json

{
  "comment": "Too risky"
}

10. Runtime API

10.1 列出 Runtime Worker

GET /api/v1/runtimes

10.2 获取 Runtime

GET /api/v1/runtimes/:id

11. Secret API

11.1 列出 Secret

GET /api/v1/secrets

11.2 创建 Secret

POST /api/v1/secrets
Content-Type: application/json

{
  "id": "openai_api_key",
  "value": "sk-..."
}

11.3 更新 Secret

PUT /api/v1/secrets/:id

11.4 删除 Secret

DELETE /api/v1/secrets/:id

12. Policy API

12.1 列出 Policy

GET /api/v1/policies

12.2 创建 Policy

POST /api/v1/policies
Content-Type: application/json

{
  "id": "no-shell",
  "name": "Deny Shell Tool",
  "rules": {
    "denied_tools": ["shell"]
  }
}

12.3 绑定 Policy 到 Domain

POST /api/v1/domains/:id/policies
Content-Type: application/json

{
  "policy_id": "no-shell"
}

13. gRPC 服务

CLI 和 Runtime Worker 使用 gRPC：

服务	说明
`Registry`	Domain 注册/发现
`Scheduler`	Session 调度
`Discovery`	Runtime 发现
`TelemetryService`	Trace / Metric 上报
`EvalService`	Eval 触发/查询
`Runtime`	触发 Session 流式执行

定义见 proto/hnsx/v1/control_plane.proto 和 proto/hnsx/v1/runtime.proto。

14. 认证

当前阶段使用 API Key：

Authorization: Bearer hnsx-api-key-xxx

未来支持：

OAuth 2.0 / OIDC
JWT
mTLS（Runtime Worker 之间）

15. API 实现阶段

Phase 1

Domain CRUD
Session trigger + SSE
Trace query

Phase 2

Eval API
Metric API
Audit API

Phase 3

Approval API
Runtime API
Secret / Policy API

Phase 4

gRPC 服务完整实现
认证与权限

16. 与 Web Console 的对应

Console 页面	主要 API
Dashboard	`GET /api/v1/metrics`, `GET /api/v1/sessions`
Domain 列表	`GET /api/v1/domains`
Domain 详情	`GET/PUT /api/v1/domains/:id`, `POST /api/v1/domains/:id/validate`
Session 列表	`GET /api/v1/sessions`
Session 详情	`GET /api/v1/sessions/:id`, `GET /api/v1/sessions/:id/events`
Trace 查询	`GET /api/v1/traces`
Eval	`GET/POST/PUT/DELETE /api/v1/evals/...`
Observability	Grafana 嵌入
AuditLog	`GET /api/v1/audit`
Approvals	`GET/POST /api/v1/approvals`
Settings	Secret / Policy / Runtime API

API 设计#

1. 设计原则#

2. 错误响应#

3. Domain API#

3.1 列出 Domain#

3.2 获取 Domain#

3.3 注册 Domain#

3.4 更新 Domain#

3.5 删除 Domain#

3.6 获取 Domain 版本列表#

3.7 获取 Domain 指定版本#

3.8 验证 Domain#

4. Session API#

4.1 列出 Session#

4.2 获取 Session#

4.3 触发 Session#

4.4 重跑 Session#

4.5 取消 Session#

4.6 获取 Session Trace#

4.7 实时订阅 Session 事件#

5. Trace API#

5.1 查询 Trace#

5.2 获取 Trace 详情#

6. Eval API#

6.1 列出 EvalSet#

6.2 获取 EvalSet#

6.3 创建 EvalSet#

6.4 更新 EvalSet#

6.5 删除 EvalSet#

6.6 运行 Eval#

6.7 获取 EvalRun#

6.8 列出 EvalRun#

7. Metric API#

7.1 获取 Domain 指标#

7.2 获取 Agent 指标#

8. Audit API#

8.1 查询 AuditLog#

9. Approval API#

9.1 列出待审批#

9.2 审批通过#

9.3 审批拒绝#

10. Runtime API#

10.1 列出 Runtime Worker#

10.2 获取 Runtime#

11. Secret API#

11.1 列出 Secret#

11.2 创建 Secret#

11.3 更新 Secret#

11.4 删除 Secret#

12. Policy API#

12.1 列出 Policy#

12.2 创建 Policy#

12.3 绑定 Policy 到 Domain#

13. gRPC 服务#

14. 认证#

15. API 实现阶段#

Phase 1#

Phase 2#

Phase 3#

Phase 4#

16. 与 Web Console 的对应#