# midoo AI Learn Studio

> 用对话创建语言学习计划的平台。Agent 可以用开放的计划格式为用户创建计划、保存到 midoo 账号，或搜索和收藏社区计划。

## 接入
- MCP 服务（推荐）：https://test-studio.midooai.cn/api/mcp（Streamable HTTP，Authorization: Bearer mdo_...）
  工具：whoami、get_plan_format、validate_plan、create_plan、list_my_plans、get_plan、add_plan_to_midoo、publish_plan、search_community、get_community_plan、bookmark_community_plan、add_community_plan_to_midoo
- 文档页面：https://test-studio.midooai.cn/developers
- 接口根地址：https://test-studio.midooai.cn/api/agent/v1
- 认证：Authorization: Bearer mdo_...（用户在 https://test-studio.midooai.cn/developers 创建的个人访问令牌）

## 接口
- GET /api/agent/v1/schema：计划格式 JSON Schema 与完整示例（无需令牌）
- POST /api/agent/v1/plans/validate：校验计划，返回错误、提示和统计（无需令牌）
- GET /api/agent/v1/me：当前令牌对应的账号
- POST /api/agent/v1/plans：导入计划到 Studio；加 ?add_to_midoo=true 同时保存到 midoo
- GET /api/agent/v1/plans：列出我的计划
- GET /api/agent/v1/plans/{id}：读取计划当前版本（原生格式）
- POST /api/agent/v1/plans/{id}/add-to-midoo：把计划保存到 midoo 账号
- POST /api/agent/v1/plans/{id}/publish：分享到社区
- GET /api/agent/v1/community?q=&language=&sort=：搜索社区计划
- GET /api/agent/v1/community/{id}：社区计划详情
- POST /api/agent/v1/community/{id}/bookmark：收藏（DELETE 取消）
- POST /api/agent/v1/community/{id}/add-to-midoo：把社区计划保存到 midoo 账号

## 给 Agent 的说明
你可以帮我在 midoo AI Learn Studio 创建语言学习计划，并保存到我的 midoo 账号。

接口地址：https://test-studio.midooai.cn/api/agent/v1
认证：请求头 Authorization: Bearer <我的访问令牌>
格式说明：GET https://test-studio.midooai.cn/api/agent/v1/schema（JSON Schema 和完整示例，无需令牌）

步骤：
1. 先问清我的学习语言、当前水平（CEFR A0–C2）、目标场景、周期和每天可学时间。
2. 按 schema 写出计划 JSON：require_profile 描述学习者，plan.stages[].day_lessons[].lessons[] 是课时。
   每节课的 lesson_desc 写清学习步骤，并在末尾附 ```yaml 代码块列出 topic_kps 知识点
   （knowledge_id、pattern、pattern_trans 中文翻译、level、function、chunks、examples）。
3. POST https://test-studio.midooai.cn/api/agent/v1/plans/validate 校验，按返回的 errors 修正，warnings 尽量处理。
4. POST https://test-studio.midooai.cn/api/agent/v1/plans 导入；如果我同意，加 ?add_to_midoo=true 直接保存到 midoo。
5. 把返回的 studioUrl 发给我，我可以在 Studio 里预览和继续修改。
也可以：GET /community?q= 搜索社区计划，POST /community/{id}/add-to-midoo 添加，POST /community/{id}/bookmark 收藏。

## 计划示例
```json
{
  "require_profile": {
    "learn_lan": "ja",
    "teaching_lan": "zh-Hans",
    "background_goal": "下个月去大阪旅行，想自己点餐和问路",
    "current_level": "A0",
    "other": ""
  },
  "plan": {
    "name": "大阪旅行日语：点餐与问路",
    "analyst": "零基础，两周内掌握旅行中最常用的点餐和问路表达。",
    "stages": [
      {
        "stage_title": "在餐厅点餐",
        "stage_desc": "能看懂菜单、点餐并结账。",
        "stage_time": "第1周",
        "day_lessons": [
          {
            "day_lesson_title": "进店与点餐",
            "lessons": [
              {
                "lesson_title": "说出想要的菜",
                "lesson_desc": "1. 作为顾客告诉店员想要哪道菜。2. 说明数量。\n知识点：\n```yaml\ntopic_kps:\n  - topic_id: 1\n    topic_key: ordering\n    knowledge_points:\n      - knowledge_id: kp-1\n        pattern: これを ___ ください。\n        pattern_trans: 请给我___这个。\n        level: A0\n        function: speaking\n        chunks: [一つ, 二つ]\n        examples:\n          - これを一つください。\n```"
              }
            ]
          }
        ]
      }
    ]
  }
}
```