HTTP API v1（JSON）
Base URL 为部署站点根路径 + /api/v1。面向 CLI、脚本与 Agent；浏览器内 Inertia 页面不依赖本 API。
基础约定
- Content-Type：请求体一般为
application/json（DELETE可无 body）。 - 鉴权：请求头
Authorization: Bearer <api_access_token_plaintext>。令牌在 Web 端创建；服务端仅存 SHA256 摘要，撤销后立即失效。 - 成功响应：
{ "data": … , "meta"?: … }。 - 错误响应：
{ "data": null, "error": { "code", "message", "fields"? } }，HTTP 状态码与语义一致。 - 业务资源时间戳：字段名多为 camelCase 的
createdAt/updatedAt；列表meta中分页字段为 snake_case（如per_page）。
鉴权与 401
| 场景 | error.message（示例） |
|---|---|
| 未带 Authorization 或非 Bearer | 未提供 API Key |
| 摘要不匹配或记录不存在 | API Key 无效 |
| Token 已撤销 | API Key 已撤销 |
成功鉴权会更新该令牌的 last_used_at。当前实现无 OAuth 式 scope：令牌等价于对应登录用户对其名下资源的访问。
端点一览
以下路径均相对于 /api/v1。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /auth/me | 当前用户 JSON |
| POST | /auth/refresh | 占位刷新（仍需 Bearer） |
| GET | /intakes | 分页列出本人收录 |
| POST | /intakes | 创建收录 |
| GET | /intakes/:id | 详情 |
| PATCH | /intakes/:id | 更新 |
| DELETE | /intakes/:id | 删除 |
| POST | /intakes/:id/refinements | 信号漏斗派生子项 |
| POST | /intakes/:id/promote_to_playbook | 精选信号晋升为独立 Playbook |
| POST | /intakes/ai | AI 自动识别创建（异步） |
| GET | /intakes/ai/status/:job_token | 查询 AI 任务状态 |
| POST | /fetches | 解析 URL 返回资料段（不落库） |
| GET | /search/intakes | 搜索收录 |
| GET | /search/playbooks | 搜索打法 |
| GET | /dictionary/items | 词典项列表 |
| — | /playbooks | 打法资源：列表 GET、创建 POST、详情 GET、更新 PATCH、删除 DELETE |
| — | /walkthroughs | 讲解资源：同上；创建/更新可 multipart |
规范主本：docs/20-engineering/specs/api-v1.md（与代码冲突时以代码为准并回写文档）。
分页 meta
total：总条数page：当前页（从 1 起）per_page：每页条数（客户端勿假设固定值）
profile 与 multipart
- Intake 创建时 URL 解析：
kind=tool|channel且带url时，默认不会自动解析；需显式传auto_resolve_url: true（或等价字符串）。 - profile_data：须符合服务端注册表校验；可与
profile_data_json二选一形式提交（详见 api-v1 规格）。 - 讲解上传：创建 / 更新讲解可使用
multipart/form-data携带视频文件或.cast终端录屏，也支持 asciinema 外链或第三方视频链接（具体字段以接口实现为准）。