用 AI Agent 开发 oTree：打造专属 MCP 工具与 Copilot Skill

用 AI Agent 开发 oTree：打造专属 MCP 工具与 Copilot Skill

分类： OTree 工具与动态
标签： OTreeAIMCPCopilot工具

发表于 [oTree Study] • 2026年5月 • 阅读时间约 12 分钟

背景：让 AI 真正懂 oTree

用 AI 写代码已经不新鲜了。但如果你让 GPT 或 Claude 帮你写 oTree 实验，你大概率会遇到这些问题：

  • 把 participant.vars 当数据字段用，结果 CSV 里什么都没有
  • WaitPage 的 is_displayed 写错，导致所有人永远卡在等待页
  • 用了 oTree 3 的 self.player 写法，但你的项目是 oTree 5
  • payoff 用了普通 float 做运算，Currency 类型炸了

这些问题的根源不是 AI 不够聪明，而是它不知道 oTree 的那些隐藏规则。

于是我们决定做两件事：

  1. 写一个 Copilot Skill，把 oTree 的核心知识、工作流和常见坑打包给 AI 用
  2. 写一个 MCP Server，让 AI 有能力直接读取你的 oTree 项目结构并生成代码

什么是 Copilot Skill？

Copilot Skill 是 VS Code GitHub Copilot 的一种知识包，放在 .github/skills/<名称>/SKILL.md 目录下。当你问 Copilot 一个 oTree 相关的问题时，它会自动加载这个 Skill 里的内容，获得专领域的背景知识再回答你。

简单理解：Skill = 给 AI 的上岗培训材料，里面有标准流程、参考文档、代码模板。

什么是 MCP Server？

MCP（Model Context Protocol）是 Anthropic 提出的一个开放协议，让 AI 可以调用外部工具——类似于给 AI 配了一套”函数库”。

MCP Server 通过 stdio 与 VS Code Copilot 通信，AI 可以在对话中直接调用你写的 Python 函数来做事情，比如读取你的 oTree 项目文件、分析页面流程、生成脚手架代码。

简单理解：MCP = AI 的工具箱，里面有它可以调用的函数。

我们做了什么

Skill：.github/skills/otree-dev/

.github/skills/otree-dev/
├── SKILL.md                          # 主入口：7步工作流 + 触发关键词
├── references/
│   ├── models-and-data.md            # 数据模型：字段类型、对象层次、participant.vars
│   ├── pages-and-flow.md             # 页面机制：Page lifecycle、WaitPage、live_method
│   ├── bots-and-testing.md           # 自动测试：PlayerBot、expect()、SubmissionMustFail
│   └── gotchas.md                    # 12个常见坑（附说明和正确写法）
└── assets/
    └── app-scaffold.md               # 3种完整脚手架模板

MCP Server：mcp-servers/otree-inspector/

mcp-servers/otree-inspector/
├── server.py          # FastMCP 服务，4个工具
├── requirements.txt
└── README.md

Skill 详解：oTree 知识怎么组织的

SKILL.md：触发和工作流

SKILL.md 的 description 字段决定了 AI 什么时候会加载这个 Skill：

---
name: otree-dev
description: "Use when building, debugging, or scaffolding oTree experiments.
  Triggers on: creating oTree apps, models.py Player/Group/Subsession fields,
  pages.py WaitPage live_method page_sequence, session configs SESSION_CONFIGS,
  bots tests PlayerBot, payoff logic, participant.vars..."
---

描述里密集地包含了 oTree 的核心关键词——只要你的问题涉及这些词，Skill 就会自动被加载。

主体内容是一个 7 步标准工作流：

  1. 了解 App 结构（读 __init__.py 或 MCP inspect_otree_app）
  2. 追踪页面流程（page_sequence、WaitPage、is_displayed）
  3. 复查数据模型（字段类型、participant.vars vs 字段）
  4. 应用代码修改（oTree 5 no-self 格式、payoff 用 cu()）
  5. 写或修复 Bots
  6. 检查常见坑
  7. 生成脚手架

references/gotchas.md：12 个必知的坑

这是整个 Skill 里含金量最高的一份文件，列举了 AI 最容易写错的场景：

坑 1：WaitPage 死锁

# 危险：如果某个玩家的 is_displayed=False 跳过了 WaitPage 前的页面，
# 而 after_all_players_arrive 依赖那个玩家的数据，可能出问题。
# 解决：给 WaitPage 本身也加 is_displayed，或重新安排页面顺序。

坑 2：participant.vars 不进数据导出

# 错误写法 — CSV 里看不到
participant.vars['my_answer'] = 42

# 正确写法 — 定义 Player 字段
class Player(BasePlayer):
    my_answer = models.IntegerField()
player.my_answer = 42

坑 3：Currency 运算

# 错误
player.payoff = player.contribution * 1.5

# 正确
player.payoff = cu(player.contribution) * 1.5

坑 4：oTree 5 no-self 格式

# oTree 3/4 旧写法（已过时）
def vars_for_template(self):
    return dict(x=self.player.x)

# oTree 5 正确写法
@staticmethod
def vars_for_template(player):
    return dict(x=player.x)

其余 8 个坑涵盖：before_next_page 被跳过的条件、form_fields 未声明字段、live_method 返回格式错误、session.vars 竞态条件等。

MCP Server 详解：4 个工具

MCP Server 基于 fastmcp 编写，提供 4 个工具函数，AI 可以在对话中直接调用。

工具 1：inspect_otree_app(app_path)

读取一个 oTree app 的 __init__.py（oTree 5）或 models.py（旧版），返回结构摘要。

示例输出：

## oTree App: public_goods  (otree5 format)
File: public_goods/__init__.py

### C (Constants)
  - NAME_IN_URL
  - PLAYERS_PER_GROUP
  - NUM_ROUNDS
  - ENDOWMENT

### Group
  - total_contribution

### Player
  - contribution

### page_sequence (4 pages)
  Introduction
  Contribute
  ResultsWaitPage
  Results

### Bots: defined

这让 AI 不需要逐行读你的代码，就能快速掌握 app 的整体结构。

工具 2：trace_page_flow(app_path)

深度解析每一个页面的行为细节。

示例输出：

## Page Flow: public_goods

### 1. Introduction  [Page]
  ✓ is_displayed (conditional)

### 2. Contribute  [Page]
  form_model = 'player'
  form_fields = ['contribution']

### 3. ResultsWaitPage  [WaitPage]
  ✓ after_all_players_arrive

### 4. Results  [Page]
  ✓ vars_for_template

帮助 AI（和你自己）快速看清楚页面的条件、表单、WaitPage 钩子、是否有超时等。

工具 3：check_session_configs(settings_path)

解析 settings.py 中的 SESSION_CONFIGS，让 AI 了解实验的整体配置。

示例输出：

## SESSION_CONFIGS

### full_experiment
  display_name: 完整实验
  app_sequence: instructions → public_goods → survey → payment
  num_demo_participants: 6
  custom config keys: multiplier, treatment
    multiplier = 2
    treatment = 'high'

## SESSION_CONFIG_DEFAULTS
  real_world_currency_per_point = 0.01
  participation_fee = 5.0

工具 4：scaffold_otree_app(name, ...)

根据参数生成完整的 oTree 5 __init__.py 脚手架代码。

参数：

参数说明
app_nameApp 名称（同时作为 NAME_IN_URL）
players_per_group每组人数，None 表示个人游戏
num_rounds轮数，默认 1
description文件头注释
use_live_page是否包含 live_method 实时页面

示例调用：

生成一个 3 人组、3 轮的公共品博弈脚手架——会自动包含 Group.total_contribution、ResultsWaitPage、after_all_players_arrive、PlayerBot 等完整结构，语法验证无误，可以直接使用。

如何使用

第一步：安装 MCP Server 依赖

pip install "mcp[cli]"

第二步：VS Code 配置已自动完成

项目中已经有 .vscode/mcp.json，内容如下：

{
  "servers": {
    "otree-inspector": {
      "type": "stdio",
      "command": "python",
      "args": ["${workspaceFolder}/mcp-servers/otree-inspector/server.py"]
    }
  }
}

重启 VS Code 后，MCP Server 会自动启动，在 Copilot 聊天中即可使用。

第三步：直接开聊

打开 VS Code 的 Copilot Chat（Ctrl+Shift+I 或侧边栏），直接描述你的需求：

示例提问：

“帮我看一下 trust_game 这个 app 的页面流程，有没有 WaitPage 问题？“

Copilot 会自动调用 trace_page_flow('trust_game')，返回结构化分析，并结合 gotchas.md 中的规则给出建议。

“帮我新建一个 2 人信任博弈 app，需要 3 轮，Trustor 先决策，Trustee 后响应”

Copilot 会调用 scaffold_otree_app('trust_game', players_per_group=2, num_rounds=3) 生成基础结构，再根据你的描述补充逻辑。

“我的 participant.vars['decision'] 为什么在 CSV 里看不到？“

Copilot 会加载 gotchas.md 第 2 条并给出详细解释和修复方案。

技术说明

Skill 的加载机制

Skill 采用渐进式加载：

  1. 发现阶段（约 100 tokens）：只读 name 和 description，判断是否相关
  2. 指令阶段（< 5000 tokens）：加载 SKILL.md 主体
  3. 按需加载：references/ 和 assets/ 下的文件仅在被引用时才加载

这意味着 Skill 几乎不消耗 context 窗口，只有真正需要时才展开。

MCP Server 的工作原理

MCP Server 通过 Python 的 ast 模块静态解析 oTree 代码，不需要运行 oTree，也不需要 Django 环境。只要有 __init__.py 文件，就能分析。

这意味着：

  • 无论你的 oTree 项目有没有安装依赖，都能分析
  • 不会有副作用（不会修改文件、不会运行代码）
  • 支持 oTree 5（__init__.py）和旧版（models.py + pages.py）

未来计划

目前这套工具还在早期阶段，计划后续补充：

  • explain_otree_error：把报错信息 + app 结构一起发给 AI，给出针对性修复建议
  • search_otree_docs：接入 oTree 官方文档的语义搜索
  • validate_page_flow：自动检测 WaitPage 死锁风险
  • 更多 Skill 场景：otree-debug（专门排错）、otree-live（实时页面专项）

总结

组件解决的问题
SKILL.md + 工作流AI 有标准流程可以遵循，不会乱来
gotchas.mdAI 不再踩那 12 个经典坑
inspect_otree_appAI 能快速掌握你的 app 结构
trace_page_flowAI 能准确分析页面行为
check_session_configsAI 了解你的实验配置
scaffold_otree_app语法正确的脚手架，直接可用

这套工具的核心思路是：不是让 AI 更聪明，而是给 AI 提供它真正需要的上下文。oTree 有很多约定俗成的规则，散落在文档各处，这些规则打包进 Skill 和 MCP 之后，AI 就能更准确、更高效地帮你开发。

相关资源：

评论