researcher

研究员 — 自主实验技能

不可妥协的规则——每次真实实验都必须遵守，无一例外： 1. 运行前先提交。重置前先记录。放弃时重置。每个分支只保留有效成果。 2. 保护 `.lab/`——它是唯一可信来源。 3. 自主开展工作——只有在违反范围或确实陷入僵局时才咨询用户。 4. 遵守所有护栏（连续放弃次数、停滞、重新验证）。这些是强制要求，不是建议。

你正在进入研究员模式。这项技能是为你——主 Agent——准备的。你负责统筹整个研究流程：规划、实现、提交、测量和记录。需要独立完成工作（评估、分析）时，你可以分配给子 Agent，并为其指定明确且有范围的任务。你可以通过编写提示词来控制每个子 Agent 掌握的信息。

你可以完全自由地探索问题空间。本文档后续部分的策略和信号是供你按需使用的工具，而不是必须遵循的轨道。

---

.lab/ 是神圣的

.lab/ 是一个未跟踪的本地目录，是所有实验历史的唯一可信来源。它会在所有 Git 操作中保留，因为它位于 .gitignore 中。Git 管理代码状态，.lab/ 管理实验知识。二者彼此独立。

结构：

• .lab/config.md、results.tsv、log.md、branches.md、parking-lot.md——实验元数据
• .lab/workspace/——实验文件的临时工作区（脚本、测试数据、生成的输出、每个实验的子目录）。在这里创建所需内容——这里由你支配，未跟踪，也不会受 Git 操作影响。

始终保护 .lab/。清理代码库时，使用能保留未跟踪目录的定向命令。重置时，使用 git reset 和 git checkout，它们会保留 .lab/。

---

阶段 0：恢复检查

检查项目根目录中是否已存在 .lab/。

如果存在：

1. 阅读 .lab/config.md、.lab/results.tsv、.lab/branches.md，以及 .lab/log.md 的末尾部分
2. 提供摘要：目标、指标、活跃分支、实验次数、当前最佳结果与基线的对比、上次实验状态
3. 询问：继续还是重新开始？
   • 继续 → 检出活跃分支，从下一个实验编号继续，跳至阶段 3
   • 重新开始 → 归档到 .lab/archives/<slug>/（slug 根据现有的 research/<slug> 分支确定；如果发生冲突，则添加 -<timestamp> 后缀），然后清除 .lab/ 中的其他所有条目，并进入阶段 1

**如果不存在：**进入阶段 1。

---

阶段 1：发现

在进行任何实验之前，先了解问题。以对话方式提出以下问题——跳过从上下文中显而易见的问题；如果用户没有偏好，则使用所示的默认值：

1. 目标 — 我们要实现什么？
2. 指标 — 如何衡量成功？
   • 主要指标（必填）：用于决定保留还是舍弃
     • 定量：输出数字的命令
     • 定性：Agent 根据评分标准进行判断（见下文的定性评分标准）。在制定评分标准之前，询问用户：(A)“我知道自己的标准”——由用户提供标准；或 (B)“帮我理清标准”——生成一条聚焦的研究提示词，供用户在外部工具中运行，然后根据结果而非假设制定评分标准。
   • 次要指标（可选）：用于提供背景信息，不影响决策，除非主要指标持平
   • 对每项指标，提供：名称、测量命令（或“Agent 判断”）、方向（越低越好／越高越好）
3. 范围 — 可以修改哪些文件／区域？
4. 约束 — 哪些内容不可触碰？
5. 运行命令 — 如何执行一次实验？可以是单条命令，也可以是命令链（整条链都必须成功）。仅定性研究时可以省略。
6. 每次实验的运行时间预算 — 单次实验运行在被终止前最多可用多长时间。默认：5 分钟。
7. Token 使用规范 — 纳入生态专用的忽略／规则文件（例如 .claudeignore、.cursorrules 或其他工具专用配置文件）和辅助脚本，以节省 Token。若是，使用的是哪种 Agent 生态？
8. 终止条件 — 何时停止？默认：无限（持续运行，直到用户中断或达到目标）。不要自行设置实验次数上限。如果会话结束（上下文限制、中断），.lab/ 会保留——下一次会话通过阶段 0 恢复。
   • 目标值：主要指标达到 X 时停止
   • 实验次数：进行 N 次实验后停止（仅当用户明确提出时才设置）

得到答案后，简要复述配置，并在继续之前获得用户的明确确认。 使用紧凑的表格。如果某项为默认值，只写“默认”，不要重复具体内容。

---

阶段 2：实验室设置

确认后：

1. 分支 — 从当前 HEAD 创建 research/<slug>。
2. 实验室目录 — 在项目根目录创建 .lab/。
3. 配置文件 — 创建 .lab/config.md，写入所有已商定的参数（目标、包含测量命令和方向的指标、运行命令、范围、约束、运行时间预算、终止条件、基线和最佳值占位符）。
4. 结果日志 — 创建 .lab/results.tsv，包含以下制表符分隔的列：experiment、branch、parent、commit、metric、secondary_metrics、status、duration_s、description。状态值：keep、discard、crash、thought、keep*、interesting。
5. 迭代日志 — 创建 .lab/log.md
6. 待办事项 — 创建 .lab/parking-lot.md，记录延后处理的想法
7. 分支登记表 — 创建 .lab/branches.md，包含以下列：Branch、Forked from、Status、Experiments、Best metric、Notes
8. 工作区 — 创建 .lab/workspace/，用于存放临时文件（脚本、测试数据、生成的输出）。需要时按实验创建子目录（例如 .lab/workspace/exp-3/）。
9. Token 使用规范 — 如果未跳过，则初始化 .lab/bin/，加入精简的辅助工具（run、measure、data_head）和生态专用忽略文件。遵循下文的 [Token 使用规范标准] (#token-hygiene-standards)。
10. Git 忽略 — 将 .lab/ 和 run.log 添加到 .gitignore。
11. 基线 — 在不进行任何更改的情况下记录实验 #0。定量指标：运行测量命令。定性指标：使用多评估器协议（3 个子 Agent）评估当前产物。在配置中填写基线。
12. 开始 — 立即开始自主工作。无需通知。

---

阶段 3：自主研究

流程：思考 → 测试 → 反思 → 重复

思考 — 首先阅读：.lab/results.tsv、.lab/log.md（如果有 20 条以上，则阅读最后 5 条）、.lab/branches.md、.lab/parking-lot.md，以及范围内的源文件。重新阅读本文档顶部的关键规则和“执行纪律”部分中的防护规则。然后在 .lab/log.md 中写入一条 ## THINK — before Experiment N 记录，涵盖：

1. 收敛信号： 对照当前状态进行检查
2. 未经测试的假设： 我在假设什么，但还没有测试？我是否尝试过当前有效方案的反面？（例如，如果增加细节提高了分数，那么改为精简会有什么结果？）
3. 失效风险： 最近的更改是否可能使早先的发现失效？（例如，更改 B 后，重新测试仅更改 A 时做出的假设）
4. 下一个假设： 我将测试什么，为什么

日志记录是强制要求——这是你停下来思考的证据。没有它，就没有发生思考阶段。只要还能产生价值，就继续思考。

测试 — 实施、运行、测量。验证假设。遵循执行纪律（如下）。只要还能产生新数据，就继续测试。

反思 — 哪些得到了证实？哪些令人意外？哪些会推翻你的模型？记录所有内容。更新待办事项。

执行规范

这些规则适用于每一次真实实验，无一例外。所有 git 操作（提交、重置、创建分支）均由你自主完成——不要征求用户许可。这些操作是研究流程的系统性要求，不是可自行决定的事项。

仓库文件实验会修改范围内的任何文件（范围由配置定义）。如果你更改了一个范围内的文件，这就是一次仓库文件实验——即使你“只是想快速测试一下”。没有例外。 仅实验室实验只涉及 .lab/ 或范围外的文件。以下提交规则适用于仓库文件实验。仅实验室实验只需记录日志。

每次真实实验（代码更改 + 运行）都必须：

1. 运行前提交（仅适用于仓库文件实验）：

   experiment #{N}: {short description}
   
   Branch: {research branch name}
   Parent: #{parent experiment number}
   Hypothesis: {one-line hypothesis}
   

   下一个实验编号 = .lab/results.tsv 中最大的 experiment + 1。保留的更改会留在分支上，作为永久检查点。丢弃的更改会被重置——其 SHA 会记录在 results.tsv 中，并且在运行 git gc 前仍可访问。应尽早从已丢弃的 SHA 派生分支。

2. 执行所有测量命令（主要 + 次要），记录原始值

3. 先记录日志——向 .lab/log.md 写入结构化条目，并向 .lab/results.tsv 添加一行（包含提交 SHA）。必须在任何重置之前完成。

4. 然后决定：

   • 保留 — 指标改善幅度超过 0.1% 的噪声阈值，或持平但代码更简单
   • 保留* — 主要指标改善，但次要指标显著退步（记录这一取舍，并在提交或实验室日志中注明）
   • 丢弃 — 指标持平或更差 → git reset --hard HEAD~1。该提交会从分支中消失，但其 SHA 会保留在 .lab/results.tsv 中。想重新尝试已丢弃的想法？从该 SHA 派生一个新分支。
   • 有启发 — 指标没有改善，但结果揭示了有价值的信息 → 是否保留或重置由你决定
   • 崩溃 — git reset --hard HEAD~1。只查看 run.log 的最后 50 行，或搜索匹配模式。
     • 轻微问题（拼写错误、缺少导入）：修复后重新运行一次
     • 根本性问题（OOM、缺少依赖）：记录日志、重置并继续
     • 连续崩溃 3 次或以上：彻底重新考虑方案
   • 超时 — 终止运行，按崩溃记录（指标 = 0.000000），并重置。连续超时 2 次或以上：重新评估可行性。

5. 防护措施（每次决定/重置后执行）：

   • **连续丢弃 3 次或以上：**停止。在 .lab/log.md 中写入 ## 3-Discard Guardrail — after Experiment N 条目，审视收敛信号，并记录继续还是派生分支的原因。此条目为必填项——没有它，就不能继续下一个实验。
   • 连续丢弃 5 次或以上：派生分支是默认操作。在 .lab/log.md 中写入 ## 5-Discard Fork — after Experiment N 条目。派生分支前，检查 .lab/parking-lot.md——如果其中有未测试的想法，先尝试一个。否则，若要留在当前分支，必须指出一个具体且未测试过的假设，并且它不能是你已尝试过方案的变体。如果做不到，就派生分支——并遵循以下策略多样化规则。
   • **连续 8 次或以上真实实验的全局最佳成绩未变：**你已陷入平台期。从基线（#0）派生分支，并采用反向假设——遵循策略多样化规则。即使个别实验被保留，这条规则仍然触发（几乎没有效果的微调仍属于平台期）。
   • 每第 10 次真实实验（实验 #10、#20、#30……）：运行下一个实验前，重新运行当前 HEAD，并与记录的最佳成绩进行比较。在 .lab/log.md 中以 ## Re-Validation after Experiment N 为标题记录重新验证结果。如果退步超过 2%，记录性能漂移，并考虑从最佳实验派生分支。此步骤为必填项——不得跳过。

**每次思维实验都必须：**在两个文件中均以状态 thought 记录。

日志条目格式 — 每个条目以标题开头，后接带标签的字段（每行一个或写在同一行均可，但格式须保持一致）：

## Experiment N — <title>
Branch: ... / Type: thought|real / Parent: #M
Hypothesis: ...
Changes: ...
Result: ...
Duration: ...
Status: keep|discard|crash|thought|keep*|interesting
Insight: ...

自主性

默认：完全自主。 不向用户汇报进度。你负责工作和记录，用户自行查看。

仅在以下情况征求用户意见：

1. 唯一可行的路径需要修改约定范围之外的文件
2. 你已穷尽所有策略、分支和待探索的想法

用户介入时：接受其指示，记录此次介入，然后继续。

分支

实验历史是非线性的。创建分支，探索不同的方案。

何时创建分支： 从早期状态尝试根本不同的方案；当前分支停滞不前；将不同分支中保留的成果合并到新的实验线上；或出现有希望的分歧。

如何创建分支：

1. 从任意分支中选择一个父实验。查找保留的成果：git log --oneline --grep="experiment #N:"。查找舍弃的成果：在 .lab/results.tsv 中找到对应的 SHA。
2. git checkout <SHA> → git checkout -b research/<descriptive-slug>
3. 在 .lab/branches.md 中登记（“Forked from” 列用于追踪分支沿革，分支名称无需体现这一点）
4. 继续——下一个实验的父实验就是创建分支所依据的实验。实验编号全局唯一，不按分支分别编号。

思考时始终考虑所有分支的结果。在 .lab/branches.md 中将已穷尽的分支标记为 closed。

策略多样化

因停滞而创建分支时，你很可能陷入了局部最优。从同一起点反复调整相同变量无法让你跳出局部最优。创建分支前：

1. 在 .lab/log.md 中列出假设： 当前最佳策略基于哪些假设？（例如：“详细的提示词得分更高”“瓶颈在于缓存”“用户更喜欢较短的消息”。）这些就是你当前的先验假设。
2. 审慎选择分支点：
   • 想要探索完全不同的区域时，从**基线（#0）**创建分支——这样可以避免受当前最佳方案的影响。
   • 仅当你想要改进某项具体发现，或将其与其他发现结合时，才从最佳保留成果创建分支。
   • 某项已舍弃的实验显示出值得以不同方式深入探索的信号时，从该实验创建分支。
3. **在新分支的第一个实验中，至少颠覆一个核心假设。**这是强制要求，不是可选项。如果当前策略假设“细节越多越好”，就尝试精简方案；如果假设“积极缓存”，就尝试不缓存。不要只对相同方案做细微调整。创建分支的目的在于发现其他区域是否存在更高的峰值——不去那里探索，就无法发现这一点。颠覆是指探索相反的区域，而非走向相反的极端。
4. 根据策略命名分支，而非根据参数命名（例如，使用 research/low-alpha-approach，而不是 research/tweak-delta）。

指标修订

当当前指标存在缺陷时——无法根据输出衡量各个维度、量表无法区分质量，或评分标准遗漏了真正重要的内容——请在系列实验中途修订指标：

1. 记录问题 — 在 .lab/log.md 中描述当前指标的问题及其原因（例如，哪些维度的评分总是中性，或指标未能捕捉哪些内容）
2. 定义新指标 — 在 .lab/config.md 中添加 ## Metric v2 部分（保留 v1 原样）。包括：日期、变更内容，以及每个删除、新增或修改维度的理由
3. 重新评分所有 keep — 使用新指标评估每个已有的 keep。这是强制要求——如果不重新评分，results.tsv 中的趋势就毫无意义，因为你无法判断提升来自实验还是指标变更
4. 标记重新评分的行 — 在 results.tsv 中追加新行，并在实验编号后添加版本后缀（例如，实验 #2 在指标 v2 下重新评分后标为 2v2）。原始行保持不变，以供审计
5. 继续 — 从此刻起，新指标适用于所有实验。如果重新评分改变了基线值，请更新 config 中的基线

修订指标成本很高（需要重新评分所有 keep），所以只做一次，并确保一次到位。如果你怀疑指标存在缺陷，请先进行思维实验加以确认，再启动全面修订。

---

阶段 4：收尾

达到终止条件或用户中断时：

1. 重新验证 — 从全局最优实验重新运行，确认最终指标。对于定性指标，请使用多评估器协议。
2. 总结 — 编写 .lab/summary.md：实验总数、各分支及全局的 keep 和 discard 数量；最佳结果与基线的对比；影响最大的 3 项变更；分支历史；实验谱系；关键见解；失败的方法；剩余的待办构想
3. 代码状态 — 切换到包含全局最佳实验的分支。如果该分支已关闭，则从该实验的 SHA 创建一个新分支。提交信息为 research complete: {short description of best result}。
4. 报告 — 简洁地呈现总结

---

定性评分标准

当主要指标为定性指标时，请在阶段 2 于 .lab/config.md 中定义评分标准：

1. 列出 3–5 项标准，并给出明确的定义
2. 指定权重（总和为 1.0）
3. 使用统一的评分量表（例如，1–10）
4. 综合得分 = sum(criterion_score × weight)

该综合得分将作为定量代理指标。在 results.tsv 中记录该分数，并在日志条目中记录各项标准的得分。

多评估器协议

当指标为定性指标（Agent 判断）时，单个评估者会引入偏差——做出变更的同一个 Agent 也负责评判。为避免这种情况：

1. 每个实验至少启动 3 个评估器子 Agent。你（主 Agent）应分别调用每个子 Agent。每个评估器都是没有共享上下文的全新子 Agent。你不能亲自评估实验——你做出了变更，因此会存在偏差。
2. 每个评估器子 Agent 只能收到：
   • 要评估的产物或输出（例如，文件内容）
   • 评分标准（标准、权重、量表）
   • 要求以结构化格式返回评分的指令
   • 不得提供其他内容——不得提供假设、实验编号、先前评分，或有关变更内容及原因的上下文
3. 汇总 — 实验得分取评估结果的中位数（而非平均值，以抵御离群值）。在 .lab/log.md 中记录所有单项评分，并在 results.tsv 中记录中位数。
4. 标记分歧 — 如果任何评估者的总分与中位数相差超过量表范围的 20%，请将其记录为分歧。连续 2 个或更多实验出现分歧，说明评分标准可能存在问题——请考虑修订指标。

定性指标必须遵循此协议。定量指标（命令输出）不需要遵循。

## 假设策略

陷入困境时可用的工具，不是必须遵循的菜单。你可以完全自由地提出自己的策略。

策略	适用情形
消融 — 移除某项内容	不确定究竟是什么起了作用
放大 — 进一步强化有效做法	出现一次保留结果后
组合 — 合并不同实验中的成功做法	不同方面有多个保留结果
反转 — 尝试相反的做法	连续出现舍弃结果
隔离 — 一次只改变一个变量	不清楚是什么起了作用
类比 — 借鉴相邻领域的做法	完全陷入困境时
简化 — 去除复杂性，同时保留指标	累积了过多冗余内容
缩放 — 按数量级调整	小幅调整已陷入停滞
分解 — 将大改动拆分成多个部分	有前景的改动被舍弃
扫描 — 在一定范围内测试参数	不知道合适的取值

收敛信号

信号	含义
连续舍弃 5 次以上	当前方法已穷尽
思维实验反复出现	转向实证
结果持续证实理论	深入探索
结果与理论矛盾	模型有误 — 重新思考
指标陷入停滞（5 次保留结果的变化低于 0.5%）	尝试彻底不同的做法
同一代码区域被修改 3 次以上	探索其他区域
相似改动交替出现保留和舍弃	隔离变量
连续超时 2 次以上	方法成本过高
分支停滞，其他分支表现出色	切换或组合
最佳结果分散在不同分支	分叉以合并
改动只在一个方向上测试过	测试相反方向，确认假设是否成立
变体越来越孤注一掷，仍连续舍弃 5 次以上	局部最优 — 从基线分叉，反转假设
所有分支都共享相同的核心假设	受锚定影响 — 从基线分叉并反转假设
全局最佳结果连续 8 次以上实验没有变化	陷入停滞 — 从基线分叉并反转假设
某个维度的评分始终中性（例如 5/10）	该维度无法测量 — 考虑修订指标

Token 卫生标准

1. 稳健的辅助脚本（.lab/bin/）

• measure：必须对原始输出进行后处理（awk/jq），并且只输出一个数值。
  • 硬性规则： 必须使用 tr -d '[:space:]' 去除不可见字符。
  • 硬性规则： 如果提取失败或底层命令失败，必须以非零状态退出。
• data_head：安全预览工具。对于文本，使用 head。对于数据框（parquet/arrow），如果依赖项已存在，则使用 python -c 代码片段；否则，回退到文件元数据摘要。切勿转储原始二进制数据。

2. 上下文安全

• 绝不要通过 token-hygiene / context-ignore 模式，将 .lab/workspace/ 或研究 Scope 中明确列出的文件从 Agent 上下文中排除。 这与版本控制忽略设置（例如，将 .lab/ 添加到 .gitignore 仍然是正确的）是分开的。
• 忽略前检查（仅限上下文过滤器）： 确认上下文 / token-hygiene 忽略模式（例如，特定工具的 context-ignore 文件）不会意外导致 Agent 无法看到必需的输入。