爱生活

Appearance

API 接口文档 ​

爱生活 采用本地优先 (Local-First) 架构，绝大多数数据操作通过本地数据库完成。外部 API 仅用于 AI 对话、位置服务和云端同步等少数场景。

1. 接口总览 ​

#接口方法用途环境
1{baseUrl}/chat/completionsPOSTAI 对话（兼容 OpenAI）生产
2/api/ai/proxyPOSTAI 对话代理开发(H5)
3https://restapi.amap.com/v3/geocode/regeoGET逆地理编码生产
4/api/packageGET快递查询代理开发(H5)
5WebDAV (PROPFIND/PUT/GET)—云端同步生产
6https://api.github.com/gists/{id}PATCH/GETGist 同步生产
7https://hf-mirror.com/*GETGGUF 模型下载生产(App)

2. AI 对话接口 ​

爱生活 支持云端 AI（OpenAI 兼容接口）和端侧 AI（本地推理）双模式。本节仅覆盖云端接口。

2.1 接口信息 ​

POST {baseUrl}/chat/completions
Content-Type: application/json
Authorization: Bearer {apiKey}
参数说明
baseUrl默认 https://api.openai.com/v1，可通过 AI 配置自定义
apiKeyAPI 密钥，通过 AI 配置页面设置，AES-256-GCM 加密存储于 aiConfig 表

2.2 请求格式（非流式） ​

H5 和小程序环境使用非流式请求：

json
{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "system",
      "content": "你是一个 AI 生活助理，当前时间是 2026-08-11。可用操作：[ACTION]...[/ACTION]"
    },
    {
      "role": "user",
      "content": "帮我记一个任务，明天提交周报"
    }
  ],
  "max_tokens": 800,
  "temperature": 0.7
}
字段类型必填说明
modelstring是模型名称，如 deepseek-chat、gpt-4o
messagesarray是对话消息列表
messages[].roleenum是system / user / assistant
messages[].contentstring是消息内容
max_tokensnumber否最大生成 token 数，默认 800
temperaturenumber否采样温度，默认 0.7

2.3 请求格式（SSE 流式） ​

App 环境使用 SSE 流式请求（需要 OpenAI 兼容的流式支持）：

json
{
  "model": "deepseek-chat",
  "messages": [...],
  "max_tokens": 800,
  "temperature": 0.7,
  "stream": true
}

2.4 响应格式（非流式） ​

json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "好的，我来帮你记录这个任务。\n\n[ACTION]\n{\"name\":\"create_task\",\"content\":\"提交周报\",\"dueDate\":\"2026-08-12\"}\n[/ACTION]"
      }
    }
  ]
}

2.5 响应格式（SSE 流式） ​

data: {"choices":[{"delta":{"content":"好的"}}]}

data: {"choices":[{"delta":{"content":"，"}}]}

data: {"choices":[{"delta":{"content":"我来"}}]}

...

data: [DONE]

流式解析规则：

  • 每行以 data: 开头
  • 提取 choices[0].delta.content 作为增量文本
  • 遇到 data: [DONE] 表示流结束
  • 超时时间：600 秒

2.6 Agent Action 格式 ​

AI 回复中的 [ACTION]...[/ACTION] 块会被 Agent 解析并执行：

[ACTION]
{"name":"create_task","content":"提交周报","dueDate":"2026-08-12"}
[/ACTION]
字段说明
nameAction 名称，对应 actions.ts 中注册的操作
其他字段根据 Action 的 Zod Schema 动态变化

支持的 Action 清单详见 AI 子系统设计。

2.7 H5 开发代理 ​

H5 开发模式下，请求通过 Vite 代理转发以绕过 CORS：

POST /api/ai/proxy
X-Target-Url: {目标 API 地址}
X-API-Key: {API 密钥}
Content-Type: application/json

请求体原样转发到 X-Target-Url 指向的 OpenAI 兼容接口。

3. 高德地图接口 ​

3.1 逆地理编码 ​

将经纬度坐标转换为结构化地址信息。

GET https://restapi.amap.com/v3/geocode/regeo?location={lng},{lat}&extensions=base&output=JSON&key={apiKey}
参数类型必填说明
locationstring是经纬度，格式 lng,lat
extensionsstring否返回扩展信息，默认 base
outputstring否输出格式，固定 JSON
keystring是高德 Web 服务 API Key

响应示例：

json
{
  "status": "1",
  "regeocode": {
    "formatted_address": "北京市朝阳区阜通东大街6号",
    "addressComponent": {
      "province": "北京市",
      "city": "北京市",
      "district": "朝阳区",
      "township": "望京街道",
      "streetNumber": { "street": "阜通东大街", "number": "6号" }
    }
  }
}
字段说明
status1 成功，0 失败
regeocode.formatted_address格式化地址
regeocode.addressComponent.province省
regeocode.addressComponent.city市
regeocode.addressComponent.district区

使用场景：轨迹记录（record_trajectory）时自动获取当前位置的地址描述。

4. WebDAV 同步接口 ​

4.1 概述 ​

支持通过 WebDAV 协议将加密数据同步到个人网盘（如坚果云）。

平台连接方式
App直连 WebDAV 服务器
H5 (开发)通过 localhost:9399 代理转发
H5 (生产)需服务端配置 CORS 或将代理合并部署

4.2 代理转发（H5 开发模式） ​

ALL localhost:9399/{path}
X-Dav-Url: {目标 WebDAV 服务器 URL}
X-Dav-Auth: {Basic Auth 头值（可选）}
X-Dav-Ct: {Content-Type（可选）}

代理自动处理：

  • PUT 409 DuplicateName：自动删除冲突目录后重试
  • PUT 409 AncestorsNotFound：自动逐级创建父目录后重试

4.3 上传 ​

PUT {webdavUrl}/lifeos-backup.json
Authorization: Basic {base64(user:pass)}
Content-Type: application/json

{加密的 JSON 数据}

4.4 下载 ​

GET {webdavUrl}/lifeos-backup.json
Authorization: Basic {base64(user:pass)}

响应为完整加密的 JSON 数据文件。

4.5 目录操作 ​

方法用途
PROPFIND列出目录内容
MKCOL创建目录
DELETE删除文件/目录
OPTIONS检查服务器能力

4.6 支持的 WebDAV 服务 ​

服务默认地址说明
坚果云https://dav.jianguoyun.com/dav/推荐，国内访问稳定
Nextcloudhttps://{your-server}/remote.php/dav/自建方案
ownCloudhttps://{your-server}/remote.php/dav/自建方案

5. GitHub Gist 同步接口 ​

5.1 上传 ​

PATCH https://api.github.com/gists/{gistId}
Authorization: token {githubToken}
Content-Type: application/json

{
  "files": {
    "lifeos-backup.json": {
      "content": "{加密的 JSON 数据}"
    }
  }
}

5.2 下载 ​

GET https://api.github.com/gists/{gistId}
Authorization: token {githubToken}

响应中包含 files["lifeos-backup.json"].content，即加密的 JSON 数据。

5.3 配置要求 ​

配置项说明
GitHub TokenPersonal Access Token，需 gist 权限
Gist ID目标 Gist 的 32 位哈希 ID

安全说明：Gist 内容为 AES-256-GCM 加密密文，即使 Gist 被公开或 GitHub 被入侵，没有用户密码无法解密。

6. 快递查询代理 ​

H5 开发模式下的快递查询代理。

GET /api/package?postid={快递单号}

由 Vite 代理转发到 https://m.kuaidi100.com/index_all.html，返回 HTML 片段。仅在开发环境可用。

7. 模型下载接口 ​

7.1 GGUF 模型（App 端） ​

App 端通过 uni.downloadFile 下载量化模型：

GET https://hf-mirror.com/{user}/{repo}/resolve/main/{filename}.gguf
模型下载地址（hf-mirror.com 镜像）
Qwen2.5-0.5BQwen/Qwen2.5-0.5B-Instruct-GGUF/qwen2.5-0.5b-instruct-q4_k_m.gguf
Qwen3-0.6BQwen/Qwen3-0.6B-GGUF/qwen3-0.6b-q4_k_m.gguf
TinyLlama 1.1BTheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf
Qwen2.5-1.5BQwen/Qwen2.5-1.5B-Instruct-GGUF/qwen2.5-1.5b-instruct-q4_k_m.gguf
Phi-3 Minimicrosoft/Phi-3-mini-4k-instruct-gguf/Phi-3-mini-4k-instruct-q4.gguf
Gemma 2Bgoogle/gemma-2-2b-it-GGUF/gemma-2-2b-it-Q4_K_M.gguf

下载完成后存储到 _doc/models/{modelId}.gguf，并进行 MD5 完整性校验。

7.2 Transformers.js 模型（H5 端） ​

H5 端通过 @huggingface/transformers 库从 HuggingFace Hub 下载 ONNX 格式模型，自动缓存到浏览器 IndexedDB（transformers-cache 数据库）。无需手动管理。

8. 通用约定 ​

8.1 错误处理 ​

所有 HTTP 错误的处理策略：

场景处理方式
网络不可用自动降级到端侧 AI / 本地模式
401/403 认证失败提示检查 API Key / Token 配置
429 请求限流等待后重试（最多 3 次）
5xx 服务端错误重试 1 次后提示稍后再试
SSE 连接中断自动重连（最多 3 次）
请求超时600 秒超时后终止

8.2 数据安全 ​

  • 传输加密：所有外部 API 请求使用 HTTPS
  • 数据加密：同步数据在上传前已完成 AES-256-GCM 加密
  • 密钥保护：API Key 通过 EncryptedStore 加密存储
  • 零知识：服务端无法解密用户数据

8.3 环境区分 ​

环境AI 接口WebDAV快递
开发 (H5)/api/ai/proxy 代理localhost:9399 代理/api/package 代理
生产 (H5)直连需 CORS 配置不可用
生产 (App)直连直连不可用