agent-Specialization/api_doc/auth.md

鉴权与目录结构（API v1）

本项目的 API v1 使用 Bearer Token 鉴权，并且与网页端账号体系隔离。

---

1) 鉴权方式

所有需要鉴权的 API 请求都必须带 Header：

Authorization: Bearer <TOKEN>

• <TOKEN> 是你分配给 API 调用方的明文 token
• 服务端不会保存明文 token，只保存其 SHA256

---

2) API 用户与 token 的配置文件

文件：data/api_users.json

结构示例：

{
  "users": {
    "api_demo": {
      "token_sha256": "9d2f30ce92cee1301dbbdc990aed245a781c34717a1bf51a7a368b6f4ae28f50",
      "created_at": "2026-01-23",
      "note": "dev generated"
    }
  }
}

说明：

• users 的 key 是 API 用户名（仅用于区分与落盘路径）
• 调用时只需要 token（用户名不会作为参数传入）

修改 data/api_users.json 后通常需要重启服务以生效（取决于当前是否支持热加载）。

---

3) 目录结构（多工作区）

API 用户根目录（默认）：api/users/<api_user>/

在该目录下包含：

3.1 用户级共享目录（prompts / personalization）

api/users/<api_user>/shared/
  prompts/
    <name>.txt
  personalization/
    personalization.json        # 默认个性化（主文件）
    <name>.json                 # 命名个性化

说明：

• prompts 与 personalization 是用户级共享：不同 workspace 共用同一份配置；
• /api/v1/prompts 与 /api/v1/personalizations 操作的就是这里的文件。

3.2 工作区目录（每个 workspace 独立）

api/users/<api_user>/workspaces/<workspace_id>/
  project/                      # 工具读写根目录（容器挂载目录）
    user_upload/                # 上传目录（API 只允许在这里上传/下载）
  data/                         # 对话/备份等数据落盘（工作区独立）
    conversations/
      conv_*.json
    backups/
    prompts -> ../../shared/prompts               # 软链（可能不存在）
    personalization -> ../../shared/personalization  # 软链（可能不存在）
  logs/

说明：

• 每个 workspace 都会启动独立容器（隔离执行环境）；
• project/ 与 data/ 都是 workspace 级：对话文件不会跨 workspace 混用；
• user_upload/ 也是 workspace 级：不同 workspace 互相不可见。

---

4) 并发规则

• 并发限制以 workspace 为粒度：同一 API 用户的同一 workspace_id 同时只允许一个任务运行。
• 不同 workspace 可以同时运行多个任务。