认证与 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

格式（示例）：

{
  "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 生成

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 结构（简化示例）：

{
  "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、时间、返回码）；
- 加入速率限制（避免被刷）。

3.2 KiB Raw Blame History Unescape Escape