英语口语辅导师 — 技能设计

一个完整、可移植的长期运行英语口语练习辅导代理（agent）设计方案，基于 OpenClaw 构建。以北京一名七年级学生为原型设计，但所有规则与文件均配有详尽说明，便于适配任意 B1 水平学习者。

本文档是可共享的设计文档。OpenClaw 实际注入运行时的运行提示（runtime prompt）位于工作区（workspace）中的 .md 文件内，并在下方第 4 节中详细说明——该代理在运行时**从不读取**本 SKILL.md 文件。

1. 设计目标

非目标

• 多学生管理（仅支持单一 Frank，单一 workspace）
• 实时翻译（英语唯一性铁律）
• 代理输出音频（由浏览器用户脚本处理，非代理职责）
• 学科知识辅导（学生已在其他渠道获得足够此类支持）

2. OpenClaw 如何加载本技能

OpenClaw 不会将本 SKILL.md 的正文内容注入系统提示（system prompt）。实际流程如下：

1. YAML 前置元数据（name、description）→ 作为单行技能条目注入系统提示中的 skills 区块，约 250 字符。
2. 工作区文件（SOUL.md、AGENTS.md、USER.md、IDENTITY.md、TOOLS.md、HEARTBEAT.md）→ 每次请求时自动注入，约 12.8K 字符。
3. [System Context] 区块 → 由 tutor-timing 插件在每次请求时注入，约 6 行。

代理每轮可见约 13K 字符的相关上下文。本 SKILL.md 仅在人类（你、协作者或代码审查员）需要理解整体设计时才被加载。

对共享的意义：本文档是供阅读与适配的核心材料；而工作区文件才是代理实际遵循的权威规范。

3. 30 分钟状态机

START → WARM_UP（0–5 分钟） → MAIN_ACTIVITY（5–25 分钟） → WRAP_UP（25–30 分钟） → END（30+ 分钟）

为何需插件强制执行：代理无法在长时间会话及空闲间隔中可靠地自主追踪时间。tutor-timing 插件读取 lastMessageTime，计算已过分钟数，并在每次请求中注入当前所处阶段。插件源码详见 references/companion-files.md。

4. 运行时提示 — 工作区文件（权威运行规范）

工作区中六个文件会被自动注入，它们是权威的运行时规范。本节说明各文件内容；若你 fork 此技能，请将这些文件复制至你的 workspace 并按需调整。

4.1 SOUL.md — 权威来源

用途：定义身份、核心准则、状态机、响应规则、主题规则、交互日志记录。行为变更时应编辑此文件。

关键章节：

• 学生档案 — 姓名、年龄、水平、需求
• 核心准则（7 条铁律）：
  1. 仅使用英语。绝不翻译为中文。
  2. 禁用 emoji、图标或符号。
  3. 最低 30 分钟时长。由插件强制执行阶段控制。
  4. 默认使用开放式问题。
  5. 禁止讲授式教学，禁止引用教科书。
  6. 禁止输出任何音频/语音指令。
  7. 每次最多提出 1 个问题，单轮上限 2 个；严禁堆叠多个问题。
• 会话状态机 — 阶段图示及各阶段操作指引
• 响应规则 — 8 种跟进提问模板（轮换使用，禁止重复）、语法纠错表达方式、“连续 3 次简短回答 → 切换主题”规则
• 主题规则 — 禁止从 conversation-history.md 中重复选取已有主题，除非用于深入追问；提供“错误 vs 正确”类提问范例
• 交互日志 — 每次回复均追加至 teaching-transcript.md
• 会话摘要 — 在告别前撰写，格式有明确规范
• 语气风格 — 温暖、耐心、支持性强、略带趣味性

4.2 AGENTS.md — 运营索引（51 行，约 3K 字符）

用途：为代理提供的快速参考索引。始终以 SOUL.md 为准。

关键章节：

• 首行声明：“如有疑问，以 SOUL.md 为准”
• 教学操作（4 项要点）
• 主题与对话规则（路径说明 + 去重指引）
• 会话计时（5 个阶段触发条件）
• 主动引导讨论（4 项要点，全部引用 SOUL.md）
• 会话归档（2 个文件名及其用途）

4.3 USER.md — 学生档案

Frank，13–14 岁，北京七年级，B1 水平。备注：“他遇到困难时可能切换为中文——请温和引导回英语；简短回答表明兴趣减弱——应及时切换主题。”

4.4 IDENTITY.md — 代理身份卡

代理名称、角色、主要使用场景。

4.5 TOOLS.md — 本地环境配置

Windows 路径、语音脚本位置等主机特有信息。

4.6 HEARTBEAT.md — 定时任务

周期性检查（本代理默认无激活任务）。

4.7 工作区中的内容

• BOOTSTRAP.md — 曾为向导的一次性初始化文件，现已归档
• MEMORY.md / memory/*.md — 未使用；代理依赖工作区文件 + conversation-history.md 维持连续性
• AGENT-SPEC.md — 面向人类的设计文档，存放于 ~/.openclaw/skills/english-oral-tutor/（不在工作区），确保其绝不会泄露至运行时提示中。plugin-skills/ 目录专供 OpenClaw 的 npm registry 镜像使用，Windows 下会清除非符号链接条目——请勿将其用于用户自定义技能。

5. 辅助文件与插件

详见 references/companion-files.md：

• 插件源码与注册方式
• openclaw.json 中的代理配置区块
• 可选的语音 I/O Tampermonkey 脚本
• 主题库结构

6. 安装

**官方共享包位于 D:English-trainingskill**（含本设计文档 + 工作区模板 + 插件 + 主题库 + 可选语音脚本）。将该目录打包为 ZIP 后发送给其他 OpenClaw 用户，接收方按其中 README.md 执行安装。

以下为标准安装步骤；共享包内的 README.md 将完整复现这些说明。

6.1 包内容结构

skill/                                    ← 整个共享包
├── README.md                             ← 接收方从此开始
├── plugin-design/                        ← 设计文档（即本文档）
├── workspace/                            ← 代理工作区模板
│   ├── SOUL.md
│   ├── AGENTS.md
│   ├── USER.md.template                  ← 接收方填写
│   ├── IDENTITY.md.template              ← 接收方填写
│   ├── TOOLS.md
│   └── HEARTBEAT.md
├── plugin/tutor-timing/                  ← 会话阶段注入插件
├── topic-library/topic-library.md
└── voice/openclaw-voice-userscript.js     ← 可选

6.2 包中的内容（接收方自行创建）

• conversation-history.md 和 teaching-transcript.md 属于原始学生的个人数据。接收方在使用辅导师过程中将自行累积其专属版本。
• BOOTSTRAP.archive.md 是原始开发者搭建环境时使用的单次向导文件，新安装无需此文件。

6.3 接收方安装步骤

1. 将 workspace/ 复制至 ~/.openclaw/workspace/english-oral-teacher/。 将 USER.md.template 重命名为 USER.md，IDENTITY.md.template 重命名为 IDENTITY.md，并填写其中的 [PLACEHOLDERS]。

2. 将 plugin/tutor-timing/ 复制至 ~/.openclaw/extensions/。

3. 将 topic-library/topic-library.md 复制至 ~/.openclaw/agents/english-oral-teacher/english-oral-tutor/references/。

4. 编辑 ~/.openclaw/openclaw.json — 添加两个条目：

{
  "plugins": {
    "entries": { "tutor-timing": { "enabled": true } }
  },
  "agents": {
    "list": [
      {
        "id": "english-oral-teacher",
        "workspace": "C:\Users\\.openclaw\workspace\english-oral-teacher",
        "agentDir": "C:\Users\\.openclaw\agents\english-oral-teacher",
        "tts": { "auto": "off" }
      }
    ]
  }
}

5. 重启服务：执行 openclaw gateway restart。验证方式：打开 http://127.0.0.1:18789/，选择该代理，确认提示顶部出现 [System Context] 区块。

6. （可选）语音支持：安装 Tampermonkey，加载 voice/openclaw-voice-userscript.js，访问控制 UI。

7. 自定义配置

8. 已知问题与注意事项

• openclaw configure 和 openclaw doctor --fix 将静默覆盖工作区文件（问题 #27919）。执行任一命令前，请务必备份 workspace/english-oral-teacher/。
• 部分钩子（hook）中插件上下文为空（event.context.agentId 为 {}）。tutor-timing 插件采用模块级状态与无条件注入方式规避此问题。若你 fork 该插件，请保持此设计。
• 尽管存在铁律，代理仍可能偶尔输出 [[audio_as_voice]]。 若发生，请在 SOUL.md 的 Core Truth #6 中强化约束。
• MEMORY.md 与 memory/*.md 未被使用。 请勿惊讶于它们未出现在提示中——本技能依赖工作区文件与 conversation-history.md 维持连续性。
• BOOTSTRAP.md 已在 v1.0 版本中删除。 它曾作为一次性初始化脚手架存在；向导完成即归档。请勿重新添加。

9. 版本历史

• v1.0 — 初始设计。含 30 分钟插件、SOUL/AGENTS 分离架构、开放式问题、主题去重。

10. 致谢与出处

• 基于 OpenClaw 2026.5.x 构建
• 学生：Frank（私教场景）
• 语音脚本：D:English-trainingopenclaw-voice-userscript.js
• 插件：tutor-timing（仓库内实现，约 85 行）