Proposal: Per-Agent Teaching Skills / 为课堂智能体配置教学法 Skill 的方案

[cosarah]

为课堂智能体配置教学法 Skill / Per-Agent Teaching Skills Configuration

中文版在前，English version below.

---

背景与动机

当前每个课堂智能体（agent）的行为通过 persona（系统提示词）和 allowedActions（白板等动作权限）配置。但教学法层面的规则（例如苏格拉底式提问、建构主义、先承接再引导、支架式教学等）目前只能写死在 persona 里，复用性差，也无法在多个 agent 之间共享或在课堂中临时切换。

本提案引入 Teaching Skill：一段纯文本的教学法规则，可以挂载到任意 agent 上，与 persona、actions 正交。

非目标 (Non-goals)

• 不引入工具调用 / function calling：会显著增加响应时延，与真实课堂对话节奏不符
• 不做 RAG / 外部检索
• 不做按学生画像动态切换：本期只做静态绑定 + 课堂内手动 hot-swap

数据模型

interface TeachingSkill {
  id: string;
  isBuiltin: boolean;

  // 内置 skill 走 i18n key；fork 后或导入的 skill 用纯文本
  nameKey?: string;
  descriptionKey?: string;
  name?: string;
  description?: string;

  // 永远纯文本，注入到 system prompt
  promptFragment: string;

  sourceLanguage?: string;   // 导入分享时的提示，仅 hint
  forkedFrom?: string;       // 内置 id，用于"恢复默认"
  createdAt: number;
  updatedAt: number;
}

// AgentConfig 增加
interface AgentConfig {
  // ... existing fields
  skillIds?: string[];   // 顺序即拼接顺序
}

UI 渲染：const displayName = skill.nameKey ? t(skill.nameKey) : skill.name;

内置 skill 的语言策略

经过权衡，采用 canonical English prompt + i18n meta 方案：

字段	存储方式	理由
name / description	i18n key	UI 展示，5-8 个 skill × N 语言成本可控
promptFragment	单一英文版本	见下

为什么 prompt 用英文够用：

1. LLM 跨语言指令对齐能力强，prompt 用英文写、学生用中文发言，LLM 仍按主 prompt "回复学生语言" 用中文输出
2. 教学法术语（Socratic, Scaffolding, Constructivism）源自英文教育学，LLM 训练语料里英文版语义最准
3. 英文 token 数约为中文 60%，多 skill 叠加时差距显著
4. 维护成本低：一份 prompt 永远一致，避免多语种漂移

Fork 编辑摩擦的解法（讨论点 ①，见下）：

• 方案 A：Fork 后弹提示，引导用户自行翻译或直接编辑英文版（零 LLM 调用）
• 方案 B：提供 "fork 并翻译" 一键按钮，单次轻量 LLM 调用翻译为当前界面语言后存为 fork

倾向先做 A，B 作为 Phase 2 增强。

CRUD 入口

主入口：Settings Dialog 新增 tab teaching-skills，位置在 web-search 和 general 之间。理由：

• 与 voice / image / TTS provider 等课堂资源配置同级，IA 一致
• 复用已有的 left-sidebar 导航 + 三栏布局
• lib/types/settings.ts:12 已留位

次入口（可选）：在 agent-config-panel 编辑 agent 时，skill 多选旁加 "管理 skill" 链接，跳转到 settings tab。

交互设计

两栏 list-detail：

┌─────────────────────────────────────────────────────┐
│ Teaching Skills           [+ 新建] [⬆ 导入] [⬇ 导出]│
├──────────────┬──────────────────────────────────────┤
│ □ 苏格拉底式  │  名称: [_______________]              │
│ ■ 建构主义    │  ID: constructivism (内置只读)        │
│ □ 支架式      │  描述: [_______________]              │
│ □ 先承接后引导│  Prompt 片段:                         │
│ □ PBL         │  ┌─────────────────────────────────┐ │
│ ─────内置──  │  │ <textarea>                      │ │
│ □ 我的 skill A│  │                                 │ │
│   (custom)    │  └─────────────────────────────────┘ │
│               │  Token 预估: ~120                    │
│               │  [恢复默认] [删除] [保存]            │
└──────────────┴──────────────────────────────────────┘

关键交互：

• Fork 内置：编辑内置 skill 自动 fork 为副本，显示 "已修改，来自: X [恢复默认]"
• 删除内置：仅能 toggle 隐藏，无法彻底删除
• 拖拽排序：skill 在 agent 上的拼接顺序影响效果，list 支持拖拽
• Token 预估：客户端 tiktoken 估算
• 冲突警告：agent 编辑面板里同时勾选互斥 skill（如 "直接讲授" + "苏格拉底"）时给非阻塞 warning

课堂内 Hot-swap（替代独立"试用"功能）

放弃 settings 内的独立试用沙盒。理由：单独跑无 slide / whiteboard / 历史对话上下文，效果与真实课堂严重不一致。

改为：

• agent-bar 加 skill pill：仿 voice pill 模式，当场切换某 agent 启用的 skill
• "重跑当前轮 with new skill" 按钮：复用 director graph，不消耗新 turn，直接 re-generate 当前 turn 并标注 (skill: socratic)
• 兼容真实教师场景：上课中临时换教学法

导入导出

JSON 文件，无 ZIP。

// .maic-skill.json
{
  "$schema": "openmaic.skill.v1",
  "exportedAt": "2026-05-10T...",
  "skills": [{
    "id": "socratic",
    "name": "Socratic",
    "description": "...",
    "promptFragment": "...",
    "sourceLanguage": "en"
  }]
}

导入入口：

1. Settings tab 顶部 ⬇ 导入 按钮（主入口）
2. 拖拽 .json 到 settings dialog
3. 粘贴 JSON 文本框（社区分享场景）

导出入口：

• 批量：tab 顶部 ⬆ 导出，全选/多选
• 单个：卡片 ⋯ 菜单含 "导出此 skill" / "复制为 JSON"（推荐，最轻量分享）

冲突处理：ID 撞车给三选一（覆盖 / 保留两份带后缀 / 跳过），批量时支持 "应用到全部"。

安全：

• prompt 是纯文本，不解析任何代码
• 单文件 < 1MB，单 prompt < 10k 字符
• 渲染时 escape，不解析 markdown / HTML

PR 拆分建议

#	PR	内容	依赖
1	Skill schema + registry + prompt 注入	types.ts、skills/store.ts、builtin.ts（5-8 个内置）、prompt-builder 拼接、AgentConfig.skillIds、zustand persist migration、director-graph override 透传	-
2	Settings tab CRUD UI	teaching-skills.tsx、list-detail、fork/恢复默认/删除、agent-config-panel skill 多选	1
3	课堂内 hot-swap	agent-bar skill pill、重跑当前轮	1
4	导入导出 + 复制 JSON	JSON schema、file-saver/upload、冲突处理 dialog	2
5 (Phase 2)	Fork-translate 增强	内置 LLM 翻译按钮	2

总工作量预估 ~2.5-3 天（不含 Phase 2）。

讨论点

希望社区在以下问题上给反馈：

1. 内置 skill 语言策略：方案 A（用户自翻译）vs 方案 B（内置 fork-translate）。是否值得为体验糖增加 LLM 依赖？
2. 内置 skill 的种类：第一批应包含哪些教学法？目前候选：苏格拉底式、建构主义、支架式、先承接再引导、PBL（基于问题的学习）。是否还有遗漏？是否应该按学科 / 学段分组？
3. 互斥/分组：是否需要 "教学法风格" 分组（如直接讲授 / 引导发现 / 探究式），同组内单选？还是完全自由组合？
4. Hot-swap 的回放语义：重跑当前轮时，原回复是替换还是保留对比？
5. 分享生态：是否需要内置 "skill 市场" 页面，从 GitHub Gist / 远程 URL 直接导入？还是仅靠 JSON 文件流转？

---

Background and Motivation

Each classroom agent currently behaves according to its persona (system prompt) and allowedActions (whiteboard etc.). Pedagogical rules — Socratic questioning, constructivism, scaffolding, "acknowledge then redirect" — can only be hardcoded into the persona. They are not reusable across agents and cannot be swapped on the fly during class.

This proposal introduces Teaching Skill: a plain-text pedagogy fragment that can be attached to any agent, orthogonal to persona and actions.

Non-goals

• No tool / function calling — increases latency, breaks classroom dialogue rhythm
• No RAG / external retrieval
• No dynamic per-student switching — this iteration covers static binding + manual hot-swap only

Data Model

interface TeachingSkill {
  id: string;
  isBuiltin: boolean;

  // Builtin skills use i18n keys; forked or imported skills use plain text
  nameKey?: string;
  descriptionKey?: string;
  name?: string;
  description?: string;

  // Always plain text; injected into system prompt
  promptFragment: string;

  sourceLanguage?: string;
  forkedFrom?: string;       // builtin id, used for "restore default"
  createdAt: number;
  updatedAt: number;
}

interface AgentConfig {
  // ... existing fields
  skillIds?: string[];   // order = concatenation order
}

UI rendering: const displayName = skill.nameKey ? t(skill.nameKey) : skill.name;

Language Strategy for Builtin Skills

Trade-off resolution: canonical English prompt + i18n meta.

Field	Storage	Reason
name / description	i18n key	UI-facing, 5-8 skills × N locales is manageable
promptFragment	Single English version	See below

Why English-only prompt is sufficient:

1. LLMs handle cross-language instructions well — English prompt + Chinese student input still yields Chinese output (controlled by main system prompt directive)
2. Pedagogy terms (Socratic, Scaffolding, Constructivism) originate in English literature; LLM training data is densest there
3. English token count is ~60% of Chinese for equivalent semantics — savings compound with multiple skills
4. One source of truth, no multi-locale drift

Fork friction handling (Discussion item ① below):

• Option A: After fork, prompt user to either translate manually or edit the English version directly (no LLM call)
• Option B: Provide "fork and translate" one-click button — single lightweight LLM call to translate into UI language, stored as the fork's text

Lean toward A for v1, B as Phase 2.

CRUD Entry Point

Primary: New teaching-skills tab in Settings Dialog, between web-search and general. Reasons:

• Same level as voice / image / TTS provider — consistent IA
• Reuses existing left-sidebar nav + three-column layout
• lib/types/settings.ts:12 already reserved

Secondary (optional): "Manage skills" link inside agent-config-panel skill multi-select, navigates to settings tab.

Interaction Design

Two-column list-detail (see Chinese version above for ASCII mockup).

Key behaviors:

• Fork builtin: editing a builtin auto-forks; shows "Modified, from: X [Restore default]"
• Delete builtin: only toggle-hide, no permanent delete
• Drag reorder: concatenation order matters, list supports drag
• Token estimate: client-side tiktoken
• Conflict warning: non-blocking warning when mutually exclusive skills selected on the same agent

In-Class Hot-swap (replaces standalone "Try-it" sandbox)

Drop the standalone sandbox. Reason: without slide / whiteboard / conversation context, results diverge sharply from real classroom.

Replace with:

• Skill pill in agent-bar: mirrors voice pill, switch active skills on the fly
• "Rerun current turn with new skill" button: reuses director graph, no new turn consumed, regenerates current turn tagged (skill: socratic)
• Aligns with real teacher use-case: pedagogy switch mid-class

Import / Export

JSON files, no ZIP.

// .maic-skill.json
{
  "$schema": "openmaic.skill.v1",
  "exportedAt": "2026-05-10T...",
  "skills": [{
    "id": "socratic",
    "name": "Socratic",
    "description": "...",
    "promptFragment": "...",
    "sourceLanguage": "en"
  }]
}

Import entries:

1. ⬇ Import button at the top of the tab (primary)
2. Drag .json onto settings dialog
3. Paste JSON text box (community share)

Export entries:

• Bulk: ⬆ Export at tab top, multi-select
• Single: card ⋯ menu with "Export this skill" / "Copy as JSON" (recommended, lightest sharing path)

Conflict handling: on ID collision, three options (Overwrite / Keep both with suffix / Skip), with "Apply to all" for bulk.

Safety:

• Prompt is plain text, no code execution
• Single file < 1MB, single prompt < 10k chars
• Render with escaping, no markdown / HTML

PR Breakdown

#	PR	Contents	Depends
1	Skill schema + registry + prompt injection	types.ts, skills/store.ts, builtin.ts (5-8 builtins), prompt-builder concat, AgentConfig.skillIds, zustand persist migration, director-graph override passthrough	-
2	Settings tab CRUD UI	teaching-skills.tsx, list-detail, fork / restore / delete, agent-config-panel multi-select	1
3	In-class hot-swap	agent-bar skill pill, rerun-current-turn	1
4	Import / export + Copy as JSON	JSON schema, file-saver/upload, conflict dialog	2
5 (Phase 2)	Fork-translate enhancement	Builtin LLM translation button	2

Total estimate: ~2.5-3 days excluding Phase 2.

Discussion Points

Feedback wanted on:

1. Builtin skill language strategy: Option A (user self-translates) vs Option B (builtin fork-translate). Is the LLM dependency worth the UX gain?
2. Initial builtin set: Which pedagogies should ship first? Current candidates: Socratic, Constructivism, Scaffolding, Acknowledge-then-Redirect, PBL. Anything missing? Should they be grouped by subject / age?
3. Mutual exclusion / grouping: Need "teaching style" groups (Direct Instruction / Guided Discovery / Inquiry-based) with single-select per group? Or fully free combination?
4. Hot-swap replay semantics: When rerunning current turn, replace original reply or keep both for comparison?
5. Sharing ecosystem: Need a builtin "skill marketplace" page importing from GitHub Gist / remote URL? Or stick to JSON file exchange only?

---

Looking forward to community feedback. / 期待社区反馈。