智能体与技能的数据模型
本课有两个由教师维护的配置制品：智能体把角色提示词与「能用的技能」「能查的材料」绑在一起；技能以单一文本文件定义，空行以上是元数据，空行以下是引导规程。两者都按班级切分，一次回答只用会话选定的那一个智能体所绑定的部分。文末对照主流的 SKILL.md 格式，说明本课为什么这样选。
1智能体：提示词与两份绑定
智能体是本班的一个配置单位。它不复制技能与材料的正文，只保存绑定关系；技能与材料各自仍是班级级的行。
| 字段 / 关系 | 含义 | 约束 |
|---|---|---|
id | 主键 | 自增 |
class_id | 所属班级 | 跨班不可见；按编号直取他班智能体返回 404 |
name | 名称 | 班内唯一，不超过 64 字 |
prompt | 角色提示词 | 不超过 2000 字；为空时回退到默认角色设定，不因此拒绝请求 |
enabled | 启用状态 | 为否时学生列不到、也选不了；已存在的会话不受影响 |
tutor_agent_skills | 绑定的技能 | 只能绑本班技能，跨班或不存在按 404 处理；未绑定或已停用的技能不参与路由 |
tutor_agent_materials | 绑定的材料 | 只能绑本班材料；空绑定是合法状态，此时检索为空 |
2技能的字段与来源
技能以单一文本文件定义：空行以上是元数据，空行以下是引导规程。服务端解析后写入 skills 表；一条技能要参与路由，还须被某个智能体绑定且处于启用状态。
| 字段 | 含义 | 约束 |
|---|---|---|
id | 主键 | 自增 |
class_id | 所属班级 | 跨班不可见，按编号直取他班技能返回 404 |
name | 名称 | 班内唯一，不超过 32 字；含「解题引导」时触发不给最终答案的硬性要求 |
trigger_text | 适用条件 | 不超过 120 字；按中英文逗号、顿号、分号或竖线切词，再逐词与提问比对 |
description | 说明 | 空行以下的正文，不超过 2000 字，整段进入系统消息 |
tools_json | 工具列表 | 本课只接受 knowledge_search，其他值在解析阶段即被拒绝 |
source_text | 文件原文 | 保留教师写的整份文件，便于取回再编辑 |
subject_text | 资料范围 | 不超过 32 字；非空时只保留标题含该词的材料 |
enabled | 启用状态 | 为否时不参与路由，即使仍被智能体绑定着 |
seed_key | 种子幂等键 | 预置技能专用；教师自建的技能为 NULL |
3两份样板
下面是 A 班预置的两份技能文件。空行之前是元数据，空行之后是引导规程；# 开头的行与空行在元数据区被忽略。
名称：数学解题引导
适用条件：方程,去括号,分数,通分,面积,应用题,未知数,行程
资料：数学
工具：knowledge_search
启用：是
学生正在自己做数学作业，往往已经写了一步。先看懂他卡在哪一步，只指出下一步该检查什么，例如去括号有没有乘到每一项、分母不同要不要先通分、该设哪个未知数。不要算出最终得数，不要把整道题做完。依据只用数学自学笔记，并标出材料标题和位置。名称：语文解题引导
适用条件：春晓,默写,阅读,中心,作文,开头,古诗,词语
资料：语文
工具：knowledge_search
启用：是
学生正在自己背诵、做阅读或改作文，卡在某一句。先接住他已经写出的那一句，告诉他往前看哪一句、找哪类句子。不要把诗的下一句、中心句或改好的段落直接写出来。依据只用语文自学笔记，并标出材料标题和位置。解析规则：文件不超过 8000 字；名称、适用条件与启用三项必填；同一字段重复出现、出现未定义字段、或空行以下缺少正文，均在提交时被拒绝，并返回面向教师的可读错误信息。
4本课格式与主流 SKILL.md 的差异
本课的技能文件是项目自定义格式，不是 Agent Skills 规范的 SKILL.md。两者的差别不在写法，而在于由谁决定「这次提问该用哪个技能」。
先交代对方的形态：规范要求一个技能是一个目录，目录中的 SKILL.md 以 YAML frontmatter 开头——即由两行 --- 夹住的一段键值元数据，其后才是正文；正文之外还可放脚本与参考文件，按需载入。
| 维度 | SKILL.md（Agent Skills 规范） | 本课实现 |
|---|---|---|
| 形态 | 目录 skill-name/ 内含 SKILL.md，可再带脚本与参考文件 | 单个纯文本文件，解析后写成 skills 表的一行 |
| 元数据 | YAML frontmatter，name 与 description 必填 | 中文键行：名称、适用条件、资料、工具、启用 |
| 正文 | frontmatter 之后的 Markdown，写法不限 | 空行以下的说明，不超过 2000 字 |
| 激活主体 | 模型读 description，自行判断该不该用 | 服务端按适用条件切词计分，至多选一个 |
| 加载方式 | 渐进式披露：元数据常驻，正文与资源按需载入 | 全量入库；命中后整段说明进入系统消息 |
| 执行参数 | 只有 allowed-tools，且是实验性字段 | 资料即检索范围，工具限定为 knowledge_search |
| 可移植性 | 跨产品通用，可拿到别的 Harness 里直接跑 | 绑定本项目的表结构与路由实现 |
这是一次有取舍的选型，不是格式写错了。把选择权交给代码，换来的是确定性：同一次提问路由到哪个技能可以单测、可以在验证记录里复现、出错能定位到是哪个词没匹配上。代价是技能读不懂超出「适用条件」词表的意图。Agent Skills 规范反过来，覆盖面更宽，但同一次提问的结果不易复现——两种做法服务于不同的目标。
5写权限与生效时机
| 操作 | 接口与角色 | 生效时机 |
|---|---|---|
| 列出本班智能体 | 已登录即可；学生只得到已启用的 | 即时 |
| 创建、修改、启停智能体 | 仅教师；同时提交绑定的技能与材料编号 | 下一次提问即按新关系作答；已有会话立即改用它 |
| 列出本班技能 | 已登录即可 | 即时 |
| 新建、修改、删除技能 | 仅教师 | 下一次提问即按新配置路由；删除会同时清掉绑定 |
| 把技能从智能体解绑（或停用技能） | 仅教师 | 该技能下一次提问起不再参与这个智能体的路由 |
配置不随会话创建时的快照（snapshot）固化：会话锁定的只是「用哪个智能体」，而该智能体当前绑了哪些技能与材料，每次提问重新读取。教师中途解绑某技能后，已存在的会话下一次提问即按新关系路由——验收时可解绑后重放同一提问，对比回答行为的差异。