2.0 对接面 API 清单（代码生成·勿手改）
与全量清单
REF-api-inventory.md同一次内省产出。 两条判据都取自代码：鉴权面不含verify_admin_key（不是运营面）、 包归属不是 1.0（不是遗留对话面）。上手看API-v2-integration.md。共 20 条（全量 195 条里的一小块 —— 其余是运营面，外部用不到也打不进）。
⚠ 其中 7 条完全无鉴权：/api/v1/auth/login、/api/v1/platform/login、/api/v1/tools、/api/v1/tools/health、/health、/healthz、/readyz。
登录那两条是设计如此（登录前没有身份）；/api/v1/tools* 与探针是已知口径差异
（docs/ARCHITECTURE.md §6.1 D6/D7·未修复）—— 别把后者当公开接口来依赖，口径一修你的依赖就断。
登录与账户（6 条）
| 方法 | 路径 | 职责 | 包 | 鉴权 | 消费方 |
|---|---|---|---|---|---|
| POST | /api/v1/auth/login | 统一登录（运营与商家账号）：→ {access_token, token_type, expires_in, username, role, | 共用底层 | 无 | SDK-ts · SDK-dart |
| POST | /api/v1/auth/logout | 登出：令牌版本 +1，该账号所有设备的令牌立即失效。 | 共用底层 | require_ctx | ops-web |
| GET | /api/v1/me | 当前登录账号：从 ctx 派生 + users 表富集（display_name / 权威 role）。 | 共用底层 | require_ctx | ops-web |
| POST | /api/v1/me/change-password | 改密：body {old_password?, new_password}。老用户无 hash 时 old_password 可空。 | 共用底层 | require_ctx | ops-web |
| GET | /api/v1/memory/recall | — | 共用底层 | require_ctx | SDK-ts · SDK-dart |
| POST | /api/v1/platform/login | 平台用户登录（ops-web）：只收平台账号，商家账号当作密码错误处理。返回同 /auth/login。 | 共用底层 | 无 | ops-web |
对话 · 写确认 · 过程（2 条）
| 方法 | 路径 | 职责 | 包 | 鉴权 | 消费方 |
|---|---|---|---|---|---|
| POST | /api/v1/writes/commit | 统一写确认入口。body.kind ∈ {commit, campaign_action}，缺省 commit（向后兼容）。 | 共用底层 | require_ctx | SDK-dart · SDK-flutter |
| POST | /api/v2/mind/turns | 开启/继续一轮 —— 新包的路径。 | v2 | require_ctx | ops-web · eval |
会话 · 记忆 · 任务 · 反馈（6 条）
| 方法 | 路径 | 职责 | 包 | 鉴权 | 消费方 |
|---|---|---|---|---|---|
| GET | /api/v1/conversations | 我的会话列表（按最近活跃排序，租户隔离）。 | 共用底层 | require_ctx | SDK-ts · SDK-dart |
| POST | /api/v1/conversations/{conversation_id}/archive | 归档会话。 | 共用底层 | require_ctx | SDK-dart |
| GET | /api/v1/conversations/{conversation_id}/messages | 会话消息分页（游标式 before_seq 向上翻历史，按 seq 升序）。 | 共用底层 | require_ctx | SDK-ts · SDK-dart |
| POST | /api/v1/feedback/error | 商家对 agent 回答举报错误（App 端「报告问题」按钮）。 | 共用底层 | require_ctx | SDK-dart |
| GET | /api/v1/tasks | — | 共用底层 | require_ctx | SDK-ts |
| PATCH | /api/v1/tasks/{task_id} | — | 共用底层 | require_ctx | SDK-ts |
探针与工具池（6 条）
| 方法 | 路径 | 职责 | 包 | 鉴权 | 消费方 |
|---|---|---|---|---|---|
| GET | /api/v1/tools | 列出通用工具，支持多维过滤。运营端工具管理页与 Agent 决策层均可调用。 | 共用底层 | 无 | ops-web |
| GET | /api/v1/tools/health | 返回所有已注册 Provider 的健康状态快照。运营端监控面板使用。 | 共用底层 | 无 | ops-web |
| GET | /health | — | 共用底层 | 无 | ops-web · eval |
| GET | /healthz | — | 共用底层 | 无 | — |
| GET | /readyz | 就绪探针：DB 不可用即 503，供负载均衡摘流（与 /healthz 的存活语义分开）。 | 共用底层 | 无 | — |
| GET | /whoami | 受保护：回显已解析的租户上下文（验证治理链）。 | 共用底层 | require_ctx | — |