API 概览

当前 API 使用 REST JSON 风格，鉴权为 Authorization: Bearer <token>。

平台

• POST /auth/register
• POST /auth/login
• GET /auth/registration-policy
• GET /charter/current
• POST /charter/accept
• GET /me
• GET /invites
• POST /invites
• DELETE /me

注册请求必须携带 charter_version 与值为 true 的 charter_accepted。登录响应会返回 requires_charter_acceptance 和 current_charter_version。

尚未确认当前必确认版本的会员可以登录、读取当前共识并提交确认，但核心业务接口会返回 428 CHARTER_ACCEPTANCE_REQUIRED。

GET /auth/registration-policy 返回当前注册模式。部署方通过 REGISTRATION_INVITE_REQUIRED 控制邀请制：为 true 时邀请码必填且由 API 强制校验；为 false 时开放无邀请码注册。

个人数据

• POST /personal/{kind}
• GET /personal/{kind}
• GET /personal/schema
• GET /personal/field-config/all
• PUT /personal/field-config/all
• GET /personal/dashboard/summary
• GET /personal/life-profile
• PUT /personal/life-profile
• POST /personal/export
• POST /personal/delete

kind 可选：body、diet、exercise、energy、sleep、reflection。

成员经济与订阅

• GET /member/assets
• GET /member/ledger
• PUT /member/vacation
• GET /member/subscription
• GET /subscription
• POST /maintenance/daily
• GET /billing/catalog
• GET /billing/overview
• GET /billing/entitlements
• POST /billing/checkouts
• POST /billing/webhooks/stripe

维护接口需要独立密钥。套餐变更必须通过托管结账和验签 Webhook，旧写接口仅返回 CHECKOUT_REQUIRED；支付事件以提供方事件编号幂等处理。

AI 助理

• GET /ai/weekly-reports
• POST /ai/weekly-report
• GET /ai/capabilities
• GET /ai/monthly-reports
• POST /ai/monthly-report
• GET /ai/correlations
• POST /ai/correlations
• GET /ai/coach/conversations
• GET /ai/coach/conversations/{id}
• POST /ai/coach/messages

所有生成能力执行 Credit 预留；成功后确认实际成本，模型调用失败时退款。服务端同时校验订阅、记录日与等级。RAG、数字分身和 Agent 尚无公开接口。

导入与工具

• GET /imports
• POST /imports/excel
• POST /imports/sleep-cycle
• GET /tools
• GET /tools/{slug}
• POST /tools/{slug}/install
• PUT /tools/{slug}/state
• POST /tools/{slug}/upgrade
• POST /tools/{slug}/rollback
• DELETE /tools/{slug}/install

删除安装接口保持兼容但执行软停用，不删除数据或版本历史。退役工具禁止新安装和升级，已有数据仍可读取和导出。

建造者生命周期接口：

• GET /tool-admin/candidates
• POST /tool-admin/candidates/{candidate_key}/adopt
• GET /tool-admin/tools/{slug}/versions
• GET /tool-admin/tools
• POST /tool-admin/tools/{slug}/versions
• PUT /tool-admin/tools/{slug}/versions/{version}/checks
• POST /tool-admin/tools/{slug}/versions/{version}/publish
• GET /tool-admin/tools/{slug}/rollouts
• POST /tool-admin/tools/{slug}/rollouts
• POST /tool-admin/tools/{slug}/rollouts/{rollout_id}/run
• POST /tool-admin/tools/{slug}/rollouts/{rollout_id}/pause
• POST /tool-admin/tools/{slug}/rollouts/{rollout_id}/resume
• POST /tool-admin/tools/{slug}/retire

版本必须通过安全、隐私、性能和可维护性四项检查才能发布。迁移 key 必须绑定平台代码处理器；升级事务失败不切换版本，回滚遇到不可逆步骤或数据损失风险会拒绝。批量灰度按稳定样本和固定批大小逐成员执行，支持手动暂停/恢复及失败阈值自动暂停。平台不接受成员提交任意 SQL 或代码。

Words to me 成员接口：

• GET/POST /words-to-me/sentences
• PUT/DELETE /words-to-me/sentences/{sentence_id}
• POST /words-to-me/draw
• PUT /words-to-me/feedback
• GET /words-to-me/stats
• GET/PUT /words-to-me/settings

以上接口只对已安装并启用该工具的成员开放。展示调用会写入私域展示历史，反馈按展示记录幂等更新。

工具提案 Pipeline

• GET /tool-proposals
• POST /tool-proposals
• GET /tool-proposals/{id}
• PUT /tool-proposals/{id}
• POST /tool-proposals/{id}/submit
• POST /tool-proposals/{id}/revise
• POST /tool-proposals/{id}/comments
• PUT /tool-proposals/{id}/support
• POST /tool-proposals/{id}/decision
• PUT /tool-proposals/{id}/development-status

Lv.3 共建者可以创建提案，社区成员参与评估，只有建造者可以作公开决策并推进研发/试用/发布状态。提案采纳不会直接创建可安装工具。

个人工作台

• GET /workspace/widgets
• GET /workspace/layout
• PUT /workspace/layout
• POST /workspace/layout/reset

组件只能来自平台注册表。保存接口拒绝未知、重复、停用或不支持尺寸的组件；角色预设只负责首次初始化和主动恢复，不覆盖成员已保存的布局。