csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

♻️ refactor(test): rebuild agent runtime test flow

Browse Source
This commit is contained in:
csh
2026-06-24 11:22:09 +08:00
parent a34c6444a5
commit 0f59543409
9 changed files with 1158 additions and 5601 deletions
Download Patch File Download Diff File Expand all files Collapse all files
test/agent/README.md
+249 -245
View File
@@ -1,300 +1,304 @@
# TSL Agent 测试定义
这个目录包含 TSL 语法的 agent 测试用例定义，**支持测试任何 agent**。
你是 TSL agent 测试执行方。
---
阅读本 README 后，先向用户询问本机 `tsl` 可执行文件路径。
用户提供路径后，优先自动识别被测 agent 名称；无法可靠识别时，向用户确认一次
agent 短名。随后严格按本文的标准测试流程执行。
## 🎯 多 Agent 支持
轮次边界必须严格执行：
### 测试定义（通用）
- 第一轮只允许生成首答、落盘、运行验证和记录评分；禁止修复，禁止把运行错误回传给被测 agent，禁止修改第一轮结果文件，也禁止测试执行方在命令失败后自动编辑文件。
- 本轮计划测试的所有 case 完成第一轮评分后，才允许进入第二轮修复。
- 第二轮只修复第一轮已经记录为 `fail` 的 case；每修复某个 case 一次，只增加该 case 的 `repair_count`。
- **`test_cases.md`** - 100+ 测试用例定义（英文完整版）
这个目录包含 TSL 语法的 agent 测试用例定义。当前评分以运行时验证为准：
生成的 `.tsl` 或 `.tsf` 能按标准流程执行通过即为通过，执行报错、超时或文件类型错误即为失败。
- 适用于所有 agent（Claude, GPT-4, Gemini, 等）
- 包含提示词、评分标准、预期代码
- 与具体 agent 无关
## 测试定义
- **`test_cases_zh.md`** - 100+ 测试用例定义（中文完整版）
- 完整翻译版本，包含所有测试用例
- 适合中文环境下的 agent 评估
- `prompts_zh.md`：给被测 agent 的题面文件。
- 包含 100 个唯一测试用例。
- 只包含题面，不包含答案、评分细则或 source docs 映射。
- 除非题面明确要求 `.tsf`，默认都要求生成 `.tsl`。
### 测试结果（按 Agent 分类）
不再维护单独的 rubric 文件。不要用人工答案表给被测 agent 提供额外线索。
- **`result/results_<agent>_<date>.md`** - 特定 agent 的测试结果
- 存放目录：`test/agent/result/`（已加入 `.gitignore`）
- 命名格式：`results_{agent}_{YYYYMMDD}.md`
- 示例：
- `result/results_claude_20260610.md` - Claude 的测试结果
- `result/results_gpt4_20240617.md` - GPT-4 的测试结果
- `result/results_gemini_20240617.md` - Gemini 的测试结果
## 测试产物
---
所有测试结果都落盘为 `.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 # 本文件
├── test_cases.md # 通用测试定义（英文完整版）⭐
├── test_cases_zh.md # 通用测试定义（中文完整版）⭐
└── result/ # 测试结果目录（gitignore）
├── results_claude_20260610.md
├── results_gpt4_20240617.md
└── results_gemini_20240617.md
```
### 添加新 Agent 的测试结果
```text
test/agent/
├── test_cases.md # 通用（不变）
├── test_cases_zh.md # 中文版（不变）
├── README.md
├── prompts_zh.md
└── result/
├── results_claude_20260610.md # Claude
├── results_gpt4_20240617.md # GPT-4（新增）
└── results_gemini_20240617.md # Gemini（新增）
└── claude/
└── 20260610/
├── tsl-001.tsl
├── tsl-037/
│ ├── <TopLevelName>.tsf
│ └── verify.tsl
└── repair-1/
├── tsl-001.tsl
└── tsl-037/
├── <TopLevelName>.tsf
└── verify.tsl
```
---
## 🎯 使用方式
### 测试不同的 Agent
1. **使用相同的测试定义**
```bash
# 所有 agent 都使用 test_cases.md 中的测试用例
cat test_cases.md
```
2. **为每个 Agent 记录结果**
```bash
# 创建结果目录
mkdir -p test/agent/result
# 测试 GPT-4
# 结果保存为：test/agent/result/results_gpt4_20240617.md
# 测试 Gemini
# 结果保存为：test/agent/result/results_gemini_20240617.md
# 测试 Claude
# 结果保存为：test/agent/result/results_claude_20240617.md
```
3. **对比不同 Agent 的表现**
```bash
# 对比通过率、得分、常见错误等
diff test/agent/result/results_claude_20240617.md \
test/agent/result/results_gpt4_20240617.md
```
---
## 📊 测试流程
## 标准测试流程
### 1. 准备测试
```bash
# 查看测试用例
cat test_cases.md
阅读本 README 后，测试执行方必须在开始执行用例前询问并记录本机 `tsl`
可执行文件路径。该路径不写入配置文件，只在本轮运行时验证中使用。
# 选择要测试的 agent
AGENT="gpt4" # 或 claude, gemini, 等
DATE=$(date +%Y%m%d)
将 `TSL_HOME` 记为 `tsl` 可执行文件所在目录；如果用户提供的是 TSL 根目录，
则以用户提供的目录作为 `TSL_HOME`。
```text
TSL executable path: /path/to/tsl
```
### 2. 执行测试
优先自动识别被测 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. 复制提示词（Prompt）
2. 发送给目标 agent
3. 记录生成的代码
4. 根据评分标准打分（0/1/2）
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 不得主动读取、请求、搜索或引用任何评分材料。
### 3. 保存结果
Codex 作为被测 agent 时：
```bash
# 创建结果目录
mkdir -p test/agent/result
- 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。
# 创建结果文件
# 格式：result/results_{agent}_{YYYYMMDD}.md
任何被测 agent 都一样：第一轮运行时验证输出不能回传给被测 agent。第一轮发现错误时，
只记录 `fail`，不得修复当前文件，不得让被测 agent 重新回答，不得把修改后的文件计入
第一轮成绩。测试执行方自己的自动修复/纠错行为在第一轮也必须关闭。如果工具在看到
第一轮运行错误后自动修改结果文件，必须按首次落盘文件评分；无法恢复首次落盘文件时，
该 case 标记为 `invalid`。第二轮修复阶段是例外，见“自动修复轮次”。
test/agent/result/results_gpt4_20240617.md
test/agent/result/results_claude_20240617.md
test/agent/result/results_gemini_20240617.md
评分材料包括：
- `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.
```
### 4. 对比分析
文件落盘规则：
- 默认每个 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 | 测试日期 | 通过率 | 平均分 | 常见错误 |
|-------|---------|-------|--------|---------|
| Claude | 2026-06-10 | 100% (10/10) | 2.0 | 无 |
| GPT-4 | 2024-06-17 | 90% (9/10) | 1.8 | 赋值语法 |
| Gemini | 2024-06-17 | 85% (8.5/10) | 1.7 | 类定义 |
| 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/result/results_{agent}_{YYYYMMDD}.md
test/agent/README.md
test/agent/prompts_zh.md
```
**说明**：
- `result/`: 测试结果统一存放目录（已加入 `.gitignore`）
- `{agent}`: agent 名称（小写，如 claude, gpt4, gemini）
- `{YYYYMMDD}`: 测试日期（如 20240617）
### 示例
不提交：
```text
test/agent/result/results_claude_20260610.md # Claude 在 2026-06-10 的测试
test/agent/result/results_claude_20240617.md # Claude 在 2024-06-17 的测试
test/agent/result/results_gpt4_20240617.md # GPT-4 在 2024-06-17 的测试
test/agent/result/results_gpt4o_20240617.md # GPT-4o 在 2024-06-17 的测试
test/agent/result/results_gemini_20240617.md # Gemini 在 2024-06-17 的测试
test/agent/result/results_gemini15_20240617.md # Gemini 1.5 在 2024-06-17 的测试
test/agent/result/
```
---
## 测试用例覆盖
## 🎯 .gitignore 配置
`prompts_zh.md` 包含 100 个测试用例，覆盖：
### 版本控制策略
| 语法点 | 测试用例数 |
| ----------- | ---------- |
| 基础脚本 | 10+ |
| 控制流 | 10+ |
| 函数调用 | 10+ |
| `.tsf`/Unit | 4+ |
| 集合与查询 | 10+ |
| 表达式 | 10+ |
| 类与对象 | 15+ |
| 运行时特性 | 10+ |
| 高级边界 | 10+ |
**提交到 git**：
## 相关文档
```text
✅ test/agent/test_cases.md # 测试定义（英文完整版）
✅ test/agent/test_cases_zh.md # 测试定义（中文完整版）
✅ test/agent/README.md # 说明文档
```
- 文档总入口：`docs/index.md`
**不提交**（已加入 `.gitignore`）：
## 最佳实践
```text
❌ test/agent/result/ # 测试结果目录
```
- 测试用例应该对所有 agent 都适用。
- 不要添加特定 agent 的专属测试。
- 关注 TSL 语法本身，而非 agent 特性。
- 每轮测试使用独立日期目录。
- 保留第一次输出作为基线，不根据运行反馈让同一个 agent 修订答案。
- 定期对比不同 agent 的通过率和常见运行错误。
---
## 📊 测试用例覆盖
`test_cases.md` 包含 100+ 测试用例，覆盖：
| 语法点 | 测试用例数 |
| ---------- | ---------- |
| 函数定义 | 15+ |
| 类与对象 | 10+ |
| 控制流 | 10+ |
| 变量与赋值 | 8+ |
| Unit 模块 | 5+ |
| 参数传递 | 8+ |
| 类型系统 | 6+ |
| 错误边界 | 10+ |
| 其他 | 30+ |
**总计**：100+ 测试用例
---
## 🔗 相关文档
### TSL 文档
- TSL 语法文档：`docs/tsl/syntax/`
- TSL 快速索引：`docs/tsl/syntax/00_agent_index.json`
- TSL 语法入口：`docs/tsl/syntax/index.md`
### Agent 优化
- Agent 快速索引：`docs/tsl/syntax/00_agent_index.json`
- 为 agent 优化，减少 75% token 消耗
- 包含精确行号和示例代码
---
## 💡 最佳实践
### 1. 保持测试定义的通用性
- ✅ 测试用例应该对所有 agent 都适用
- ✅ 不要添加特定 agent 的专属测试
- ✅ 关注 TSL 语法本身，而非 agent 特性
### 2. 结果命名规范
- ✅ 使用统一的命名格式
- ✅ 包含 agent 名称和日期
- ✅ 便于排序和查找
### 3. 定期对比
- 建议每季度测试一次所有 agent
- 追踪 agent 的改进趋势
- 发现不同 agent 的优势和劣势
### 4. 基线管理
- 保留第一次测试结果作为基线
- 新结果与基线对比
- 追踪质量变化
---
## 🎉 示例：测试新 Agent
### 步骤
```bash
# 1. 选择测试用例
cat test_cases.md | grep "### TSL-001"
# 2. 复制提示词发送给新 agent（如 GPT-4）
# 3. 记录结果
cat > results_gpt4_20240617.md << 'EOF'
# TSL Codegen Test Results - GPT-4
Date: 2024-06-17
Agent: GPT-4 (gpt-4-turbo)
## Summary
- Cases run: 10
- Cases passed: 9
- First-pass score: 18 / 20
- Pass rate: 90%
## Results
| Case | Score | Notes |
|------|-------|-------|
| TSL-001 | 2 | Correct |
| TSL-002 | 2 | Correct |
| TSL-003 | 1 | Minor issue |
...
EOF
# 4. 对比 Claude 和 GPT-4
diff results_claude_20260610.md results_gpt4_20240617.md
```
---
**维护者**：TSL Team
**最后更新**：2024-06-17
**维护者**：TSL Team
**支持的 Agent**：所有支持 TSL 的 agent