用途:管理 Open edX Studio 课程大纲的顶层结构。课程大纲是一棵树:课程 → 章节(section/chapter)→ 小节(sequential)→ 单元(vertical)→ 组件;本技能只覆盖章节及大纲读取,小节与单元另有同名 /xblock/ 机制的技能。
前置条件:先运行 node .claude/skills/iblai-api-studio-auth/scripts/studio-login.mjs --check,需打印两个 ok,否则先执行 /iblai-api-studio-auth,不要直接调用接口。需要来自 /iblai-api-studio-course-create 的课程 key(即 ROOT),以及按 /iblai-api-studio 规划的大纲。若要一次性创建整套大纲,用 /iblai-api-studio-outline;本技能用于编辑与追加。
认证与约定:Base URL 为 $STUDIO_URL,会话 cookie 来自 studio.env(其值为单引号包裹,解析时须去引号,否则 Studio 返回 500)。加载方式:set -a; . ./studio.env; set +a。请求需带 studio_session_id、csrftoken、X-CSRFToken、Origin、Referer、Accept、Content-Type 等头。ROOT 形如 block-v1:<org>+<number>+<run>+type@course+block@course;章节形如 block-v1:…+type@chapter+block@<hex>。编辑进入草稿,需经 /iblai-api-studio-publish 才对用户可见。DELETE 会连带删除内部所有小节与单元,属破坏性操作,须先与用户确认。
读取:GET /xblock/outline/{ROOT} 返回完整大纲(不含组件),节点含 id、display_name、category、has_children、published、published_on、has_changes、visibility_state、released_to_students、release_date、start、due、format、graded、has_explicit_staff_lock、studio_url、lms_url、actions、child_info 等;visibility_state 取值 live、ready、unscheduled、needs_attention、staff_only、gated。根节点还带 course_graders 与 start。GET /xblock/outline/{section} 返回单个章节及其后代;GET /xblock/{section} 只返回该章节自身字段。
写入:POST /xblock/ 创建章节,传 parent_locator、category: chapter、display_name,返回 locator 与 courseKey,新章节追加在末尾。POST /xblock/{section} 更新字段,只传变更项,如 metadata 中的 display_name、start(发布日期,ISO 8601 UTC)、visible_to_staff_only(true 时即使已发布也对用户隐藏,清除用 false 或 "nullout": ["visible_to_staff_only"]),可选 highlights 用于每周亮点邮件。POST /xblock/{ROOT} 传 children 数组重排章节,列表须包含当前全部章节 id;章节不能用 move_source_locator 移动(会返回 400)。POST /xblock/ 传 duplicate_source_locator 与 parent_locator 可连同内容复制章节。DELETE /xblock/{section} 返回 204。POST /xblock/{section} 传 {"publish": "make_public"} 发布该章节及其全部后代。
限制与注意:创建章节本身不发布任何内容;新章节显示 published: true、has_changes: false 仅因其为空,内容仍需发布。大纲接口是获取全部 id 最省的方式,建议缓存创建返回的 id。日期为 UTC ISO 字符串,Studio 会规范化回显。课程级 start(见 /iblai-api-studio-settings)是总开关,章节发布日期早于课程开始仍不可见。