# Agent 课程创作

教员和管理员登录[课程创作台](../index.html)后，可以用自然语言生成课程，也可以导入 Coding Agent 编写的计划 JSON。学员通过[课程列表](../courses.html)进入已发布的课程。所有网页链接和服务请求都在当前站点下解析，部署在子目录时保留同一应用前缀。

## 在网页中创作

1. 管理员在[设置](../settings.html)中选择 OpenAI 兼容协议或 Anthropic 协议，配置服务地址、模型及 API key，并测试连接。在线生成需要后端能访问所选模型服务。接口只返回 key 的配置状态，改变服务地址或协议时需显式更新或清除旧 key。
2. 教员在 Agent 面板选择从零创作或修改当前草稿，描述设备、教学目标和评分要求。修改时保留未要求变更的设备、版本及布局。
3. 查看返回候选的变更、说明、校验及预演结果，再选择 **应用到 Myth 预览** 或 **应用并试运行（学习）**。应用前保留原场景。试运行时使用真实三维标记检查视角、选取和动作，发布前由教员核对专业内容。

## 在线工具

| 工具 | 用途 |
| --- | --- |
| `asset_search(query)` | 搜索目录中可用的设备及教学能力。 |
| `asset_inspect(asset_id)` | 读取精确版本、部件、状态、动作及前置条件。 |
| `get_plan_schema()` | 读取计划结构，以及基于已有计划修改时的范围。 |
| `validate_plan(plan)` | 调用原生 Rust 校验器，保存不可变候选并返回具体错误。 |
| `rehearse_plan(candidate_id)` | 对已通过校验的候选执行预期操作路径的规则预演。 |
| `finish_plan(candidate_id, summary)` | 完成同一个已通过校验和预演的候选，交由教员确认。 |

模型可以依据结构化报错进行有限次修正，缺少资产或行为时应指出能力缺口。计划只引用可信库中声明的版本和动作。模型无权定义新行为效果、执行任意 shell、读取任意文件或上传 GLB。上游 key 仅由后端用于请求头，不进入模型提示或浏览器。

在线调用从创作台页面按相对地址 `./api/agent/` 发往同源服务。持有项目源码时可在 `server/agent.py` 的 `TOOL_SPECS` 和 `server/tools.py` 中检查工具实现。[工具说明](./tools.json)记录本地 CLI 契约和在线实现索引，不启动或注册 MCP 服务。

## Coding Agent 与本地 CLI

- 读取[设备及行为目录](../content/library.json)确定设备 ID、版本、部件与受信动作。当前有 16 个设备模板，使用 15 个 GLB。蓄电池更换和诊断模板共用同一模型，动作集分别维护。
- 按[计划 Schema](../schema/plan.schema.json)编写独立 JSON。为每个场景实例指定唯一 ID 和固定的 `asset_version`。位置单位为米，地面为 Y=0，`rotation_y` 单位为度。
- 在 `scene.instances` 布置设备，在 `course.initial` 设置已声明的初态。每个 `course.steps` 步骤引用确切的 `instance` 和 `action`。GLB URL、节点变换和行为效果由可信库维护。
- 查阅[示例索引](../content/plans/index.json)。可以从[整流模块更换](../content/plans/pbr-replace-module-a.json)、[户外一次设备认知](../content/plans/hd-substation-recognition.json)或[三相刀闸外观演示](../content/plans/hd-disconnector-visual-demo.json)开始。已有配电、整流和蓄电池模型沿用原模板及 URL，并已原位更新材质。课程文件名中的 `pbr-` 是示例名称，不是资产 ID。

在带有 Rust 工具链的项目源码根目录运行以下命令。校验反馈包含 `path`、`code`、`message`，修正后重新校验和预演，再把 JSON 导入网页。

```powershell
cargo run --no-default-features --bin course_tool -- search 蓄电池
cargo run --no-default-features --bin course_tool -- inspect rectifier_cabinet
cargo run --no-default-features --bin course_tool -- validate content/plans/pbr-replace-module-a.json
cargo run --no-default-features --bin course_tool -- replay content/plans/hd-disconnector-visual-demo.json --exam
```

高保真开关柜门和隔离开关刀闸的动作供离线三维观察。课程中的确认、开合或间隙观察只记录教学步骤，不判定现场停电、回路隔离、安全距离或作业许可。其余高保真设备的教学能力以各自可信目录为准。

## 蓄电池诊断

`battery_diagnostic_station@1.0.0` 支持[单体故障](../content/plans/battery-diagnosis-cell.json)和[连接故障](../content/plans/battery-diagnosis-connection.json)两个教学情境。先观察外观、测量单体电压与连接压降，再根据证据选择原因与处置，完成隔离和检修步骤后复测。学员标题使用“情境一／二”，避免预先透露正确选项。

- 用 `inspect` 查阅 `battery_diagnostic_v1`。可信库的 `kind` 可声明 `diagnosis` 或 `treatment`，`choice_group` 定义同组动作。每个选择步骤在 `choices` 列出同组全部选项，并在 `action` 中引用本情境正确项。步骤说明要求学员比较证据。不要把 `correct_when`、`effects`、`evidence_actions` 写入课程计划。
- 同一实例需完成观察与两项测量，初态中的记录标记不能代替操作。校验器检查证据、选项完整性和正确项唯一性。`private_state` 隐藏学员视图和事件中的故障真相。浏览器本地解释执行不提供防作弊保证。
- 观察和读数进入复盘证据。错误诊断、错误处置分别记为 `diagnosis_error`、`treatment_error` 并扣分，设备状态保持原值。缺少证据时返回 `evidence_required`。
- 两个预设情境的单体电压／连接压降分别为 1.75 V／0.02 V 和 2.25 V／0.30 V。更换路线包含备件核对、拆装、复测，连接路线包含隔离核对、紧固、复测。这些数值只用于课程情境。电池隔离后仍储能，实际作业和验收按现场专业规程执行。