README.md

2.1 同一个需求，聊天框和工作区各写一次“语音备忘录转文字”脚本

状态（2026-10-13）：A（聊天框）和 B（工作区 agent）各 3 次，都已跑完。B 一开始被权限检查拦下，后来鸭哥明确授权，由主线程运行。

怎么跑

都在 textbook 仓库根目录执行。本目录有自己的 .venv（openai、httpx、requests），A 和 B 用的是同一个 Python。

# 一次性：建 venv
cd experiments/2_1_workspace && uv venv .venv && uv pip install openai httpx requests && cd ../..

# 核对接口文档（用 W01 真调一次，结果在 api_check/api_check.json）
op run --env-file experiments/aib.env -- experiments/2_1_workspace/.venv/bin/python experiments/2_1_workspace/api_check/check_api.py

# A：聊天框，第 n 次
op run --env-file experiments/aib.env -- experiments/2_1_workspace/.venv/bin/python experiments/2_1_workspace/run_chat.py gemini-3.8-flash 1

# A 的反事实（不计入结果）：只把猜错的网址换成真的，再跑一次
op run --env-file experiments/aib.env -- experiments/2_1_workspace/.venv/bin/python experiments/2_1_workspace/counterfactual_url.py

# B：工作区 agent，第 n 次
op run --env-file experiments/aib.env -- experiments/2_1_workspace/.venv/bin/python experiments/2_1_workspace/run_agent.py 1

# 单独检查某个运行目录
experiments/2_1_workspace/.venv/bin/python experiments/2_1_workspace/check.py <run_dir>

实验设计

两种条件收到的是同一句话：

帮我写一个 Python 脚本，把 memos/ 文件夹里的语音备忘录用 AI Builder Space 的语音识别接口转成文字，每条存成一个同名的 .txt 文件放在 transcripts/ 里。API key 在环境变量 AI_BUILDER_TOKEN 里。

• A：聊天框。 一次 API 调用，消息里只有上面这句话，模型 gemini-3.8-flash。把回复里的代码原样存成 script.py，放进一个新文件夹（只有 memos/，没有 API.md），环境变量里有 key，不改一个字跑一次。
• B：工作区 agent。 一个新的临时文件夹，里面有 memos/ 和 API.md。同一句话后面加一句“你在一个文件夹里工作，可以读文件、跑命令、看结果。”，再加一句安全规则（key 只从环境变量读，不写盘、不打印）。用 Antigravity CLI（agy --print，模型 gemini-3.8-flash-high）跑一个回合，agent 可以自己反复改、反复跑，人不插手。临时文件夹放在仓库外，免得 agent 读到 common.py 或 A 的结果；跑完复制回 trials/B<n>/。
• 成功标准（两边一样，check.py）： 5 条备忘录（W01、W02、W05、L01、I01）每条都有 transcripts/<同名>.txt，非空，至少 10 个汉字，和原稿的字符相似度不低于 0.5。最后一条是为了排除“文件里写的是报错信息或整段 JSON”的情况。用 corpus/transcripts_grok.json 里的已知好结果核对过，5 条相似度都在 0.93 以上。
• fixture/API.md 只写了 ai_builder_space/docs/prd.md“Grok File Transcription”一节和 README 里的事实，返回格式和 curl 示例是用 W01、L01 真调出来的（api_check/api_check.json）。Base URL https://space.ai-builders.com/backend/v1 文档里没有写全，是实测确认的。

结果

A：聊天框（gemini-3.8-flash）

三次的共同点：

• 三次都猜了同一个不存在的域名 api.ai-builder.space（DNS 查不到）。真实地址是 space.ai-builders.com/backend/v1，模型没有任何渠道知道。
• 除了网址，其他部分基本是对的：鉴权都写成 Authorization: Bearer <key>，都按 OpenAI 兼容的接口上传，都正确地遍历 memos/、按同名写 .txt。三份代码在网址那一行都留了注释，也就是模型自己知道这里是猜的。
• 三个脚本都把每个文件的报错打印出来然后继续，最后打出完成信息，退出码 0，transcripts/ 是空的。只看退出码会以为成功了。

反事实（不计入成功率，counterfactual_url.json）： 只把网址换成真的，其他一个字不改：

所以 A 卡住的就是一个它无从得知的事实（网址），换上之后 3 次全部能用。

B：工作区 agent

B 的结果（2026-10-13，鸭哥授权后由主线程运行）

• 3 次都用了正确的地址 https://space.ai-builders.com/backend/v1/audio/grok-transcription。这个地址只写在 API.md 里，说明 agent 读了文档。不过 agy 的事件日志不记录具体读了哪些文件，所以没法从日志直接确认。
• agent 自己建了虚拟环境、装了依赖、写了脚本，然后运行脚本，再看 transcripts/ 里的结果，确认 5 条都转写成功后才收尾。对话只有一个回合，人没有插手。
• 3 次都没有把 key 写进任何文件。

注意事项

• n=3，每个条件一个模型。A 只试了 gemini-3.8-flash，没有换模型复现。
• A 的失败几乎全部来自“它不可能知道这个接口的地址”，而不是代码能力问题。这正是这一节想说明的：模型知道新东西的唯一渠道是输入。但它也意味着这个对比在设计上偏向 B，因为 B 的 API.md 直接写了答案。B 真正要证明的不是“它更聪明”，而是“它能读到这份文档，而且跑一次就能发现 A3 那种问题”。
• A 的代码是在本目录的 .venv 里跑的，里面预先装了 requests。如果读者的环境没装，A 会更早失败在 ImportError。
• A 的“退出码 0 但什么都没写出来”是一个值得在正文里点出的现象：聊天框写出来的代码没法替你确认它真的跑通了。
• 成功标准里的相似度阈值 0.5 是为了排除 JSON 原文和报错，不是在评转写质量。

文件

• fixture/memos/：5 条 wav，复制自 corpus/audio/。fixture/API.md：给 B 的接口文档。
• api_check/：接口核对脚本和真实返回（words 已截断）。
• run_chat.py、run_agent.py、check.py、counterfactual_url.py：运行与检查脚本。
• trials/A<n>/：response.md（模型原始回复）、run/script.py（原样代码）、run_stdout.txt、run_stderr.txt、result.json、counterfactual_url_fixed/（只换网址后的运行）。
• results.json：汇总。

教材正文移出的细节（2.1 第二轮重写，2026 年 10 月）

• 聊天框条件猜错的地址 https://api.ai-builder.space/v1/audio/transcriptions 和真实地址 https://space.ai-builders.com/backend/v1 不再出现在正文里，正文只说“3 次都猜了同一个不存在的接口地址”。
• 工作区条件每次用时 107 到 128 秒（见上表），正文不再给时间。
• 实验 prompt 原文里的“API key 在环境变量 AI_BUILDER_TOKEN 里”不进正文。正文的动手部分也不再让读者在终端里 export AI_BUILDER_TOKEN=...，改为让 AI 建一个存 key 的文件（如 .env），读者自己粘贴 key，再让 AI 确认读得到。
• 旧版动手 prompt 里写死的接口地址删掉了，改为让 AI 自己查 AI Builder Space 的文档；接口地址只放在正文末尾的“当前载体”里，作为 AI 卡住时的备选信息。
• intake-skill（仅 Mac）从动手段挪到了“当前载体”。