# 认证与 API 用户（JSON 手动维护）

本项目的 API v1 使用 **Bearer Token** 鉴权，且 **API 用户与网页用户完全隔离**。

## 1. 鉴权方式（每个请求都要带）

请求头：

```
Authorization: Bearer <TOKEN>
```

服务端会对 `<TOKEN>` 做 `SHA256`，与 `data/api_users.json` 中保存的 `token_sha256` 进行匹配。

## 2. API 用户配置文件

路径：

- `data/api_users.json`

格式（示例）：

```json
{
  "users": {
    "api_jojo": {
      "token_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "created_at": "2026-01-23",
      "note": "for flutter app"
    }
  }
}
```

字段说明：

- `users`：对象，key 是 API 用户名（建议全小写、只包含字母数字下划线/连字符）。
- `token_sha256`：必填，token 的 SHA256 十六进制字符串。
- `created_at` / `note`：可选，仅用于记录与审计。

注意：

- 当前实现为**启动时加载**该 JSON；如果你修改了 `data/api_users.json`，请**重启服务**使其生效。

## 3. 生成 token_sha256 的方法

### 3.1 用 Python 生成

```bash
python3 - <<'PY'
import hashlib
token = "YOUR_TOKEN"
print(hashlib.sha256(token.encode("utf-8")).hexdigest())
PY
```

把输出粘到 `token_sha256`。

### 3.2 token 建议

- 长度建议：>= 32 字符（越长越好）
- 生成建议：使用密码管理器或安全随机源生成
- 存储建议：客户端侧使用系统安全存储（Keychain/Keystore），不要写死在前端代码里

## 4. API 用户的独立落盘目录

每个 API 用户会创建独立工作区，默认根目录：

- `api/users/<api_username>/`

典型结构：

```
api/users/<api_username>/
  project/
    user_upload/              # API 上传文件只能落在这里（以及其子目录）
    ...                       # 智能体运行产生的项目文件也在 project 下
  data/
    conversations/            # 对话 JSON 落盘目录
    memory.md
    task_memory.md
    ...
  logs/
```

对话文件示例路径：

- `api/users/api_jojo/data/conversations/conv_20260123_234245_036.json`

对话 JSON 结构（简化示例）：

```json
{
  "id": "conv_20260123_234245_036",
  "title": "新对话",
  "created_at": "2026-01-23T23:42:45.036Z",
  "updated_at": "...",
  "messages": [
    { "role": "user", "content": "你好", "timestamp": "..." },
    { "role": "assistant", "content": "…", "reasoning_content": "", "timestamp": "..." },
    { "role": "tool", "name": "web_search", "content": "{...}", "timestamp": "..." }
  ],
  "metadata": { "run_mode": "fast", "model_key": "kimi", "...": "..." }
}
```

说明：

- API v1 **没有提供“读取历史对话”的 HTTP 接口**；如确实需要历史，请直接读落盘文件或后续再加只读接口。

## 5. 安全注意事项

- Bearer Token 等同密码：不要放到 Git、不要发到日志、不要在网页端暴露。
- 如果怀疑泄露：替换 token（更新 JSON），重启服务；旧 token 会立即失效。
- 生产环境建议：
  - 通过反向代理限制来源 IP；
  - 记录 API 调用审计日志（至少记录 user、endpoint、时间、返回码）；
  - 加入速率限制（避免被刷）。