# 生活工作台 AI 操作手册

## 1. 正式入口

- 工作台：`https://www.researchlife.top`
- AI 操作手册：`/ai-guide.txt`
- OpenAPI 3.1 定义：`/ai-openapi.json`
- 数据 API：`https://raaxisgewmzcxdpuhosj.supabase.co/rest/v1`

`/api/ai/v1` 已取消。当前工作台由 GitHub `main` 自动部署到 Cloudflare Pages，正式入口为 `https://www.researchlife.top`，备用入口为 `https://daily-life-5i8.pages.dev`。AI 直接通过 Supabase PostgREST 操作真实云端数据，或在不能配置外部 API 时使用工作台可见表单。

## 2. 接口认证

AI 使用工作台正式 HTML 当前提供的 Supabase 公开 publishable key。每个新会话首次操作前必须重新读取正式网站 `/ai-guide.txt`、`/ai-openapi.json` 和正式 HTML 中的当前公开客户端配置；不得复用对话历史、摘要、长期记忆或旧标签页里的密钥。密钥值只在业务 HTML 的 `SUPA_KEY` 常量中维护，本文档和 OpenAPI 文件不重复保存。

遇到 `401 Invalid API key` 时，立即停止使用旧密钥，重新加载正式 HTML 并读取当前公开客户端配置，先执行一次只读查询；只读查询成功后再继续原操作，不得盲目循环重试。不得在回复、摘要、记忆、文档或日志中展示完整密钥。

每个请求至少携带：

```http
apikey: <SUPABASE_PUBLISHABLE_KEY>
Content-Type: application/json
```

为与网页请求保持一致，也可同时携带：

```http
Authorization: Bearer <SUPABASE_PUBLISHABLE_KEY>
```

写入请求添加以下请求头，以便返回实际保存的 UUID 和字段：

```http
Prefer: return=representation
```

不得使用、索取或写入 `service_role`、数据库密码或管理密钥。

## 3. 通用增查改删

当前业务表是 `finance`、`habits`、`fitness`、`schedule`、`media`。原 `shopping` 表已从生产库删除，不得通过本手册继续操作。

查询：

```http
GET /<table>?select=*&order=created_at.desc&limit=100
```

新增：

```http
POST /<table>
Prefer: return=representation

{ ...record fields... }
```

按 UUID 修改：

```http
PATCH /<table>?id=eq.<uuid>
Prefer: return=representation

{ ...fields to change... }
```

按 UUID 删除：

```http
DELETE /<table>?id=eq.<uuid>
Prefer: return=representation
```

修改和删除前必须先查询并取得真实 UUID；禁止按不精确条件批量修改或删除。删除只能在用户明确指定具体记录后执行。

## 4. 业务操作映射

### 4.1 记账、收入和预算

表：`finance`

| 字段 | 含义 |
|---|---|
| `record_type` | `收入`、`支出` 或 `预算` |
| `name` | 记录名称 |
| `category` | 分类 |
| `amount` | 非负金额 |
| `date` | `YYYY-MM-DD` |
| `account` | 账户或支付方式 |
| `note` | 备注 |

记一笔支出：

```json
{
  "record_type": "支出",
  "name": "午餐",
  "category": "餐饮",
  "amount": 28,
  "date": "2026-08-13",
  "account": "微信",
  "note": ""
}
```

金额、收支方向或日期不明确时必须询问；分类、账户和备注未提供时可以留空。

### 4.2 写日记

日记复用 `habits` 表，不创建新表。字段映射必须是：

| 日记含义 | `habits` 字段 | 写入规则 |
|---|---|---|
| 类型 | `data_type` | 固定为 `日记` |
| 标题 | `habit_name` | 日记标题 |
| 心情 | `method` | 用户给出的心情；未给可留空 |
| 日期 | `date` | `YYYY-MM-DD` |
| 正文与图片元数据 | `note` | `journal:v2:` 后接单行 JSON；字段为 `content` 和 `images` |
| 其余数值 | `target`、`value` | 写 `0` |
| 单位 | `unit` | 空字符串 |
| 颜色 | `color` | `#4d3045` |

```json
{
  "data_type": "日记",
  "habit_name": "今天重新整理了工作台",
  "method": "平静",
  "date": "2026-08-13",
  "target": 0,
  "value": 0,
  "unit": "",
  "color": "#4d3045",
  "note": "journal:v2:{\"content\":\"今天完成了工作台整理，也明确了接下来让 AI 参与记录的方式。\",\"images\":[]}"
}
```

`images` 每项固定为 `{"path":"...","name":"...","type":"image/jpeg","size":12345}`。AI 通过 PostgREST 新建纯文字日记时写空数组；修改已有日记前必须先读取 `note`，若已有图片则原样保留未被用户明确移除的图片元数据。不得编造 Storage 路径，也不得把图片 base64 写进 `note`。历史纯文本 `note` 仍兼容读取。

用户给出一段完整日记时可直接保存；只有日期、标题或正文存在实质歧义时才询问。

### 4.3 任务、待办和行程

表：`schedule`

- `title`：标题。
- `date`：行程为出发日期；普通任务为开始日期，未填开始日期时为截止日期；无截止且没有日期时可为 `null`。
- `start_time`、`end_time`：行程为出发和到达时间；普通任务为开始和截止时间，均可为空。
- `priority`：`高`、`中`、`低`，默认 `中`。
- `status`：`待处理`、`进行中`、`已完成`，默认 `待处理`。
- 普通任务或待办：`category` 使用 `每日任务`、`待办事项`、`工作`、`生活` 或 `其他`。`note` 以 `task:v2:` 开头，后接单行 JSON：`startDate`、`startTime`、`endDate`、`endTime`、`noDeadline`、`note`。
- 行程：`category` 固定为 `行程`，`title` 保存行程名称，`date` 保存出发日期，`start_time` 和 `end_time` 保存出发、到达时间。
- 行程的交通方式、航班/车次、起终点、时长、座位号、备注和图片元数据放在 `note`：以 `trip:v1:` 开头，后接一行 JSON，字段固定为 `mode`、`number`、`from`、`to`、`duration`、`seat`、`note`、`images`。

行程示例：

```json
{
  "title": "G1 北京南到上海虹桥",
  "date": "2026-08-20",
  "start_time": "07:00",
  "end_time": "11:28",
  "priority": "中",
  "status": "待处理",
  "category": "行程",
  "note": "trip:v1:{\"mode\":\"高铁\",\"number\":\"G1\",\"from\":\"北京南站\",\"to\":\"上海虹桥站\",\"duration\":\"4 小时 28 分\",\"seat\":\"05车 12A\",\"note\":\"提前 30 分钟到站\",\"images\":[]}"
}
```

修改已有行程前必须读取并保留未被用户明确移除的 `images`。PostgREST 合同只管理记录元数据，不负责上传图片二进制；没有已经成功上传的 Storage 对象路径时不得自行填写 `images`。

跨天任务示例：

```json
{
  "title": "准备会议材料",
  "date": "2026-08-15",
  "start_time": "09:00",
  "end_time": "18:00",
  "priority": "高",
  "status": "进行中",
  "category": "工作",
  "note": "task:v2:{\"startDate\":\"2026-08-15\",\"startTime\":\"09:00\",\"endDate\":\"2026-08-18\",\"endTime\":\"18:00\",\"noDeadline\":false,\"note\":\"每天检查一次进度\"}"
}
```

无截止日期任务使用 `noDeadline=true`，四个起止日期时间可为空，物理 `date` 可写 `null`。它在未完成前持续显示，不判定逾期；完成后才从当前任务区移出。旧任务若没有 `task:v2:`，原 `date` 作为旧版单日任务日期兼容读取。任务修改前必须解析并合并 `task:v2:`，不得覆盖用户没有要求改变的起止信息。

行程默认按完整出发时间排序：先按 `date` 升序，再按 `start_time` 升序；同日缺少出发时间的记录排在有时间的记录之后，最后使用稳定的记录标识排序。

### 4.4 习惯、打卡和历史目标

表：`habits`

- 习惯：`data_type='习惯'`。
- 打卡：`data_type='打卡'`，`note` 使用 `habit:<习惯 UUID>` 关联。
- 历史长期目标：`data_type='目标'`。
- 历史目标进度：`data_type='目标记录'`，`note` 使用 `goal:<目标 UUID>|<备注>` 关联。
- 日记：`data_type='日记'`，按 4.2 的映射写入。

关联记录必须先查询父记录 UUID，不得猜测或使用页面本地 ID。

当前页面已经删除“目标”独立模块和新增入口。旧目标、目标进度仍保存在 `habits` 中，可按用户明确要求查询或精确修改；不得因页面改版删除这些历史记录，也不得把它们描述为当前可见模块。

### 4.5 健康记录与旧体测兼容

表：`fitness`

- 当前页面新增记录统一使用 `data_type='健康记录'`。
- `体测`、`目标`、`周计划`、`热量` 仅作为历史类型继续查询和兼容，不再有“运动”独立模块或新增入口。
- 日期使用 `date`。
- 体重、体脂、身高使用 `weight`、`body_fat`、`height`。
- 旧摄入和消耗记录使用 `intake`、`burn`；旧周计划使用 `weekday`、`plan`，不得因页面改版删除。

健康记录固定使用 `data_type='健康记录'`、`title='健康记录 · <身体状况>'` 和记录日期 `date`。网页表单所有用户字段均可选，日期未填写时由全站当前选定日期补齐；不得把未知值伪装成 `0` 或“正常”。体重、体脂同时写入顶层 `weight`、`body_fat`，也保存在 `plan` JSON 中；旧 `data_type='体测'` 的有效非零体重继续进入健康趋势。`status` 镜像保存体温状态（空字符串、`正常` 或 `异常`）；顶层 `note` 与 `plan.note` 始终写入相同补充文本，读取时优先 `plan.note`，旧记录缺失 `plan.note` 时才回退到顶层 `note`。`plan` 保存单行 JSON：

```json
{
  "sleepDuration": 7.5,
  "sleepAt": "23:30",
  "wakeAt": "07:00",
  "sleepQuality": 80,
  "weight": 68.4,
  "bodyFat": 18.2,
  "restingHeartRate": 58,
  "temperatureStatus": "正常",
  "temperatureValue": null,
  "bodyStatus": "良好",
  "medication": "",
  "note": ""
}
```

可选字段规则：

- 未提供 `sleepDuration` 时写 `null` 或省略，不得写 `0` 代替未知；有值时使用小时数。
- 未提供 `sleepAt`、`wakeAt`、`medication` 或健康备注时可写空字符串或省略。
- 未提供 `sleepQuality` 时写 `null` 或省略，不得写 `0` 代替未知；`0` 是用户明确给出时的合法评分，非 null 时必须是 `0` 到 `100` 的整数，不得使用文字等级或字符串数字。
- 未提供 `weight`、`bodyFat` 或 `restingHeartRate` 时写 `null` 或省略，不得写 `0`；有值时分别校验为有效体重、0–100 体脂率和 20–240 次/分静息心率。
- 未提供体温状态时 `temperatureStatus` 与顶层 `status` 写空字符串或省略，`temperatureValue` 写 `null`；只有用户明确说正常时才写“正常”。
- `temperatureStatus='正常'` 时 `temperatureValue` 必须为 `null`；`temperatureStatus='异常'` 时可填写 34–45℃ 数值，也允许在具体数值未知时写 `null`。
- 不得推断用户未明确提供的发热、疼痛、疾病等症状。身体状况只有用户明确描述或语义高度确定时才可做保守归纳。

### 4.6 书影音

表：`media`

- 名称：`name`。
- 类型：`书`、`电影`、`剧集`、`播客`、`音乐`、`游戏`。
- 状态：`想看`、`在看`、`已完成`、`搁置`。
- 评分：`rating`，0–5；未知时为 `null`。
- 完成日期：`finish_date`，未完成可为 `null`。
- 感想和标签：`review`、`tags`。

## 5. AI 执行规则

1. 用户给出的任务和字段已经清楚时，直接执行，不重复索要确认。
2. 只询问会改变记录含义的缺失字段，例如记账金额、收支方向、日期或日记正文。
3. 新增和修改使用 `Prefer: return=representation`；返回数组必须恰好一条并包含真实 UUID。随后按该 UUID 再查询一次，核对关键字段后才能声称成功。
4. 修改前先读取目标记录，使用 `id=eq.<uuid>` 精确更新；不得覆盖用户没有要求改变的字段。
5. 新增健康记录前按 `data_type=eq.健康记录` 与 `date=eq.YYYY-MM-DD` 查询同日记录。用户说“更新今天健康状态”时先取得 UUID 后 PATCH；用户明确要求另一条时可 POST；同日已有记录但新增或更新意图不清时询问一次。
6. 删除必须由用户明确指定具体记录；删除前报告表名、UUID 和记录摘要。
7. 操作失败时报告 HTTP 状态和非敏感错误摘要，不得盲目循环重试。401 按第 2 节重新读取正式 HTML 配置并先做只读验证。
8. 不得创建测试记录验证写入，也不得擅自修改或删除生产记录。

## 6. 浏览器操作备用路径

无法配置 OpenAPI 或外部 HTTP 工具的 AI，可以打开正式工作台：

| 任务 | 页面入口 |
|---|---|
| 记账 | `#finance` → “记一笔” |
| 写日记 | `#journal` → “写日记” |
| 添加任务或待办 | `#planner` → “添加任务” |
| 添加行程 | `#planner` → “添加行程” |
| 新增习惯 | `#habits` → “新增习惯” |
| 记录健康 | `#health` → “记录健康” |
| 添加收藏 | `#media` → “添加收藏” |

默认入口是 `#overview` 总览月历。用户在月历或页面标题右侧日期控件选择的日期，是账本、习惯、健康、日程和日记的统一查看日期；新增记录默认沿用该日期。点击健康页按钮后，必须确认页面出现 `role=dialog`、`data-form-type=health`，且存在健康日期、体重、体脂和静息心率字段。若未出现，先检查页面可见错误和控制台，再在新标签页尝试一次；仍失败且正式 API 可用时切换 API，不得反复盲点，也不得声称成功。

保存后确认页面显示“最近修改已写入在线表”。

AI 通过 API 写入后，已打开的页面会在重新获得焦点或下一次 60 秒后台刷新时读取云端数据；如果用户需要立即看到结果，引导其点击当前页面标题右侧的“同步”。记账流水、习惯、任务、行程和健康记录均提供“编辑”，保存时更新原 UUID。

## 7. 推荐给 AI 的任务说明

```text
你可以操作我的生活工作台。优先读取 /ai-guide.txt 和 /ai-openapi.json，并通过 Supabase REST 完成查询、新增和修改；不能配置外部 API 时再使用网页可见表单。任务字段清楚时直接执行，只询问会改变记录含义的关键缺失字段。每次写入使用 Prefer: return=representation 并核对返回记录。修改必须按真实 UUID 精确定位且只改指定字段。删除必须等我明确指定具体记录后才能执行。不要创建测试数据，不要使用管理密钥。
```

## 8. 安全现状

- 网站和数据库客户端权限公开免登录。
- 当前页面和 AI 使用的五张表允许 anon 角色增查改删；原 `shopping` 表已删除。
- 任何获得正式网址和公开客户端配置的人都可能操作数据。
- 日记和其他模块不要保存密码、证件号码、详细住址、病历等敏感信息。
- 当前正式页面已实现日记与行程图片上传，生产 `life-images` 也已创建并完成上传、公开/认证读取、精确删除、无残留、MIME 与 8 MB 限制验收。该 bucket 是公开匿名模型，不提供用户隔离。
- 这是现行设计事实；如以后需要用户隔离，应单独引入登录和更严格的 RLS。

## 9. MCP / OpenAPI 对接说明

当前正式托管是纯静态站点，没有持续运行的 MCP 服务端点。其他 AI 应优先使用 `/ai-openapi.json` 作为机器可读合同，使用 `/ai-guide.txt` 理解业务语义；这两份文件由根目录 `AI_OPENAPI.json` 和本手册同步生成。

最短接入流程：

1. 每个新会话重新读取正式 `/ai-guide.txt`、`/ai-openapi.json` 和正式 HTML 当前公开客户端配置，确认五张当前业务表、字段映射和操作边界；不得沿用历史会话或旧标签页密钥。
2. 导入 `/ai-openapi.json`，把刚从正式 HTML 读取的 publishable key 配置到 `apikey` 请求头；不得使用管理密钥。401 时立即停用旧密钥，重新加载正式 HTML，并在继续写入前先完成一次只读查询。
3. 查询后按真实 UUID 新增或修改，写入时使用 `Prefer: return=representation` 并核对恰好一条返回记录，再按返回 UUID 查询一次核验关键字段。
4. 修改任务、行程、日记、习惯或健康记录时，只提交用户要求改变的字段；对 `task:v2:`、`journal:v2:`、`trip:v1:` 和健康 `plan` JSON 必须先解析、合并再写回，禁止覆盖未修改的嵌套字段。
5. 图片二进制由网页和 Supabase Storage 处理；PostgREST AI 只能保留已有 `{path,name,type,size}` 元数据，不得编造路径或把 base64 写入业务表。
6. 删除只能在用户明确指定具体记录后按 UUID 执行；原 `shopping` 表已经删除，不存在可调用路径。

如果某个 AI 平台只接受 MCP，不接受 OpenAPI，应由该平台把同一 OpenAPI 合同包装为 MCP 工具；工具权限、五表范围、UUID 精确修改和删除确认规则必须保持不变。当前项目不把不存在的 MCP 服务写成已部署能力。