# TSL Agent 测试定义

你是 TSL agent 测试执行方。

阅读本 README 后，先向用户询问本机 `tsl` 可执行文件路径。
用户提供路径后，优先自动识别被测 agent 名称；无法可靠识别时，向用户确认一次
agent 短名。随后严格按本文的标准测试流程执行。

轮次边界必须严格执行：

- 第一轮只允许生成首答、落盘、运行验证和记录评分；禁止修复，禁止把运行错误回传给被测 agent，禁止修改第一轮结果文件，也禁止测试执行方在命令失败后自动编辑文件。
- 本轮计划测试的所有 case 完成第一轮评分后，才允许进入第二轮修复。
- 第二轮只修复第一轮已经记录为 `fail` 的 case；每修复某个 case 一次，只增加该 case 的 `repair_count`。

这个目录包含 TSL 语法的 agent 测试用例定义。当前评分以运行时验证为准：
生成的 `.tsl` 或 `.tsf` 能按标准流程执行通过即为通过，执行报错、超时或文件类型错误即为失败。

## 测试定义

- `prompts_zh.md`：给被测 agent 的题面文件。
  - 包含 100 个唯一测试用例。
  - 只包含题面，不包含答案、评分细则或 source docs 映射。
  - 除非题面明确要求 `.tsf`，默认都要求生成 `.tsl`。

不再维护单独的 rubric 文件。不要用人工答案表给被测 agent 提供额外线索。

## 测试产物

所有测试结果都落盘为 `.tsl` 或 `.tsf` 文件，不保存 agent 回答 markdown。

- 存放目录：`test/agent/result/<agent>/<YYYYMMDD>/`
  - `<agent>` 由测试执行方优先自动识别。
  - 识别来源优先使用被测 agent 的产品名、命令名、SDK provider 名或当前运行器已知的 agent 身份。
  - 无法从运行器上下文、命令名或已知 provider 可靠识别时，向用户确认一次 agent 短名；不要猜测。
  - 目录名统一转成小写短名，只使用 ASCII 字母、数字、短横线、下划线或点。
- 命名格式：
  - `.tsl`：`tsl-001.tsl`
  - `.tsf`：`tsl-037/<TopLevelName>.tsf`
  - `.tsf` 调用验证脚本：`tsl-037/verify.tsl`
- 修复轮次按 case 计数：`repair-1/tsl-001.tsl`、`repair-1/tsl-037/<TopLevelName>.tsf`
- 示例：
  - `result/claude/20260610/tsl-001.tsl`
  - `result/claude/20260610/tsl-037/<TopLevelName>.tsf`
  - `result/claude/20260610/tsl-037/verify.tsl`

被测 agent 禁止读取、请求、搜索或引用 `result/`。

## 目录结构

```text
test/agent/
├── README.md
├── prompts_zh.md
└── result/
    └── claude/
        └── 20260610/
            ├── tsl-001.tsl
            ├── tsl-037/
            │   ├── <TopLevelName>.tsf
            │   └── verify.tsl
            └── repair-1/
                ├── tsl-001.tsl
                └── tsl-037/
                    ├── <TopLevelName>.tsf
                    └── verify.tsl
```

## 标准测试流程

### 1. 准备测试

阅读本 README 后，测试执行方必须在开始执行用例前询问并记录本机 `tsl`
可执行文件路径。该路径不写入配置文件，只在本轮运行时验证中使用。

将 `TSL_HOME` 记为 `tsl` 可执行文件所在目录；如果用户提供的是 TSL 根目录，
则以用户提供的目录作为 `TSL_HOME`。

```text
TSL executable path: /path/to/tsl
```

优先自动识别被测 agent 名称并记为 `AGENT`。`AGENT` 不是普通配置项；如果无法从
当前运行器上下文、命令名或已知 provider 可靠识别，则在开始执行用例前向用户确认一次
agent 短名；不要猜测。

```bash
AGENT="<auto-detected-agent>"
DATE=$(date +%Y%m%d)
mkdir -p "test/agent/result/$AGENT/$DATE"
```

### 2. 逐题生成文件

阅读 `prompts_zh.md`，然后按 case 逐题执行测试。

对于每个测试用例：

1. 为当前 case 启动全新的被测 agent 会话。测试执行方可以保持同一个会话，
   但被测 agent 不能在同一个会话里连续回答多个 case。
2. 只发送 `prompts_zh.md` 中的 `Runner Setup`、`Answer Rules` 加单个题面，
   或只暴露 `prompts_zh.md` 加 `docs/index.md` 及其路由到的 `docs/` 子页。
3. 允许 agent 从 `docs/index.md` 自动路由并阅读相关文档。
4. 记录 agent 生成的第一次完整代码并立即落盘。
5. 落盘后冻结该 case 的第一轮结果文件；第一轮不允许 agent 根据运行结果或评分反馈修订答案。
6. 被测 agent 不得主动读取、请求、搜索或引用任何评分材料。

Codex 作为被测 agent 时：

- CLI 自动化：每个 case 单独执行一次 `codex exec`，不要使用 `codex exec resume`。
- CLI 自动化如果不想保留会话记录，可使用 `codex exec --ephemeral`。
- Codex App 或 IDE：每个 case 新建一个 thread，不要在同一个 thread 里继续下一个 case。
- Codex SDK/MCP：每个 case 调用一次新的 thread/start；不要用同一个 thread 连续 run 多个 case。

任何被测 agent 都一样：第一轮运行时验证输出不能回传给被测 agent。第一轮发现错误时，
只记录 `fail`，不得修复当前文件，不得让被测 agent 重新回答，不得把修改后的文件计入
第一轮成绩。测试执行方自己的自动修复/纠错行为在第一轮也必须关闭。如果工具在看到
第一轮运行错误后自动修改结果文件，必须按首次落盘文件评分；无法恢复首次落盘文件时，
该 case 标记为 `invalid`。第二轮修复阶段是例外，见“自动修复轮次”。

评分材料包括：

- `result/`
- 运行时验证日志
- 其他 agent 的输出文件
- 对比报告或人工备注

若被测 agent 主动接触评分材料，该 case 或本轮测试应标记为 `invalid`，
不计入有效成绩。

推荐的运行器设置：

```text
You are in this repository. The documentation entry point is docs/index.md.
When asked to write TSL, start from docs/index.md and follow its routing to the
relevant TSL pages. Do not infer syntax from Pascal, TypeScript, JavaScript,
Python, or SQL.
```

文件落盘规则：

- 默认每个 case 保存为 `.tsl`，例如 `test/agent/result/<agent>/<YYYYMMDD>/tsl-001.tsl`。
- 只有题面明确要求输出 `.tsf` 时，才保存为 `.tsf`，并放入对应 case 目录，
  例如 `test/agent/result/<agent>/<YYYYMMDD>/tsl-037/<TopLevelName>.tsf`。
- `.tsf` 文件名不能使用 case 编号；文件基名必须与第一个顶层声明同名。
  测试执行方应按被测 agent 代码中的第一个顶层声明命名文件，不为了凑文件名改写代码。
- 任何 `unit ... end.` 文件只能保存为 `.tsf`，不能保存为 `.tsl`。
- 如果 agent 输出 markdown code fence，测试执行方只提取代码内容保存到文件，不保存回答 markdown。

### 3. 运行时验证

运行时验证是标准测试流程的一部分。保存 `.tsl` 和 `.tsf` 文件后，由测试执行方
逐个验证。第一轮验证必须在被测 agent 会话之外执行，不要把 stdout/stderr 或错误日志
发送回被测 agent；即使第一轮发现错误，也只记录评分，不修复文件。第二轮自动修复阶段
按“自动修复轮次”规则处理。

`.tsl` 验证规则：

```bash
cd test/agent/result/<agent>/<YYYYMMDD>
tsl tsl-001.tsl
tsl tsl-002.tsl
```

`.tsf` 验证规则：

1. 将 case 目录中的 `.tsf` 文件复制到 `TSL_HOME/funcext/tmp/`。
2. 在同一个 case 目录中编写 `verify.tsl` 调用脚本。
   调用脚本应按被测 agent 实际生成的函数名、unit 名或类型名来调用。
   验证脚本必须实际调用 `.tsf` 暴露的功能，不能只输出成功标记。
3. 调用脚本在所有验证调用成功后，用 TSL 输出语句最后输出一行 `__TSL__AGENT__OK__`。
4. 执行 `tsl verify.tsl`。
5. 验证完成后删除 `TSL_HOME/funcext/tmp/`。

```bash
cd test/agent/result/<agent>/<YYYYMMDD>/tsl-037
mkdir -p "$TSL_HOME/funcext/tmp"
cp ./*.tsf "$TSL_HOME/funcext/tmp/"
tsl verify.tsl
rm -rf "$TSL_HOME/funcext/tmp"
```

`funcext/tmp` 由本流程独占。开始验证前不要在该目录保留人工文件；结束后必须清理。

### 4. 第一轮评分规则

- `pass`：按标准流程执行，最后一个非空输出行是 `__TSL__AGENT__OK__`。
- `fail`：超时、缺少文件、文件类型错误、`.tsf` 调用脚本失败，
  `.tsf` 文件名与第一个顶层声明不一致，`.tsf` 无法被 TSL 加载/编译，
  或最后一个非空输出行不是 `__TSL__AGENT__OK__`。
- `invalid`：被测 agent 主动读取、请求、搜索或引用评分材料。

TSL 可能在打印错误后仍返回退出码 0，因此不能只看 `$LASTEXITCODE`。
运行时评分以成功标记为准：脚本没有正常执行到最后，就不会输出最后的
`__TSL__AGENT__OK__`。

最终成绩只统计有效 case：

```text
pass_rate = pass / (pass + fail)
```

不由被测 agent 自评。

### 5. 自动修复轮次

本轮计划测试的所有 case 完成第一轮评分后，可以对 `fail` 的 case 启动第二轮自动修复。

修复规则：

1. 第一轮期间禁止修复；只有进入第二轮后，第一轮已经记录为 `fail` 的 case 才可以修复。
2. 修复阶段可以把当前文件内容和运行时验证输出发给被测 agent。
3. 每次 agent 产出修复版本，都保存到新的修复目录，不覆盖第一轮文件。
4. 第一次修复保存到 `repair-1/`，第二次修复保存到 `repair-2/`，依此类推。
5. `repair_count` 按 case/file 单独记录；修复 `tsl-019.tsl` 只增加 `tsl-019` 的次数，
   不影响其他失败 case。
6. 修复版本仍按同样的运行时验证规则执行，最后一个非空输出行必须是 `__TSL__AGENT__OK__`。

示例：

```text
test/agent/result/opencode/20260623/
├── tsl-019.tsl              # 第一轮原始输出
├── repair-1/
│   └── tsl-019.tsl          # 第 1 次修复
└── repair-2/
    └── tsl-019.tsl          # 第 2 次修复
```

修复统计：

```text
case_id = tsl-019
first_pass = 第一轮是否 pass
repair_pass = 修复后是否 pass
repair_count = 该 case 的修复版本数量
```

如果第一轮已经 `pass`，`repair_count = 0`。如果多次修复仍失败，
该 case 的 `repair_count` 记录实际修复次数，`repair_pass = false`。

### 6. 对比分析

不同 agent 的输出直接按目录对比：

```bash
diff -r test/agent/result/claude/20260617 \
        test/agent/result/gpt4/20260617
```

建议人工记录汇总表，但不要把汇总表放入被测 agent 可读上下文。

```markdown
| Agent | 测试日期 | 有效用例 | Pass | Fail | Invalid | Pass rate |
|-------|---------|---------:|-----:|-----:|--------:|----------:|
| Claude | 2026-06-17 | 100 | 96 | 4 | 0 | 96% |
| GPT-4 | 2026-06-17 | 100 | 88 | 12 | 0 | 88% |
```

## 版本控制策略

提交到 git：

```text
test/agent/README.md
test/agent/prompts_zh.md
```

不提交：

```text
test/agent/result/
```

## 测试用例覆盖

`prompts_zh.md` 包含 100 个测试用例，覆盖：

| 语法点      | 测试用例数 |
| ----------- | ---------- |
| 基础脚本    | 10+        |
| 控制流      | 10+        |
| 函数调用    | 10+        |
| `.tsf`/Unit | 4+         |
| 集合与查询  | 10+        |
| 表达式      | 10+        |
| 类与对象    | 15+        |
| 运行时特性  | 10+        |
| 高级边界    | 10+        |

## 相关文档

- 文档总入口：`docs/index.md`

## 最佳实践

- 测试用例应该对所有 agent 都适用。
- 不要添加特定 agent 的专属测试。
- 关注 TSL 语法本身，而非 agent 特性。
- 每轮测试使用独立日期目录。
- 保留第一次输出作为基线，不根据运行反馈让同一个 agent 修订答案。
- 定期对比不同 agent 的通过率和常见运行错误。

**维护者**：TSL Team
**支持的 Agent**：所有支持 TSL 的 agent