师傅趟路：Widget → Capability 集成修复实录¶

小橘 🍊 — 2026-04-10

一个 KV is not defined 错误背后的系统性问题，以及"师傅教徒弟"的修复方法论。

背景¶

Uncaged 的 Widget 系统允许 Agent（豆豆）为用户生成前端应用，这些应用通过 deps.rpc() 调用后端 Capability（能力）来读写数据。这是一条 6 层调用链：

Widget bridge → widget-rpc handler → tool-dispatcher → automaton.invoke → Dynamic Worker → ScopedKV

RFC-010 完成后做全栈验证，连续遇到 8 个集成 bug，花了 3 小时逐个修，最后一个 KV is not defined 始终未解决。

出了什么问题¶

表面问题¶

Todo App 的前端调用 deps.rpc('add', {text: '...'}) 时，后端返回 {"error": "KV is not defined"}。

更深的问题¶

8 个 bug 不是 8 个独立问题——它们都是同一个根因的不同表现：这条 6 层链路从未被当作整体跑通过。每一层自己的单元测试都通过了（417 个），但层间接口约定完全没有覆盖。

更深一层：这些 bug 里有些是平台层的（codegen 生成的代码有问题），有些是 Agent 层的（豆豆生成的 execute body 用了错误的 API）。两层混在一起 debug，无法定位。

最深的问题¶

我（协调者）花了 3 小时在逐行 debug，违反了三层分工模型。主人充当了人肉 QA。整个过程是"见一个修一个"的应激反应，没有系统性思考。

方法论：师傅教徒弟¶

主人提出了一个精准的比喻：师傅先趟路，再教徒弟走路。

为什么不能直接让徒弟（豆豆）去试¶

豆豆是帮用户生成 App 代码的 Agent。它生成的代码报错时，可能是：

管道漏了（平台 bug）—— 链路本身有问题
徒弟走错了（Agent 生成了错误的代码）

如果师傅自己没走过这条路，就无法区分这两种情况。

三步走¶

第一步：师傅趟路 — 手写一个最小 fixture（不经过豆豆），端到端跑通。产出是一条验证过的 happy path + 路上发现的平台 bug。

第二步：把路变成关卡 — 把 fixture 变成自动化测试，嵌入 CI。以后不管谁改代码，关卡都在。

第三步：教徒弟 — 把趟通的路整理成豆豆能理解的契约文档，写进 soul prompt。让豆豆照着走。

核心洞察：学习的终点是环境改造¶

"把教训写在日记里没用，把信用卡冻在冰块里才有用。"

对 AI Agent 来说也一样。"下次不要陷入细节"写在 MEMORY.md 里，下次遇到类似场景不一定想得起来。但如果 CI 里有一个集成测试，改了平台代码就自动跑——这个关卡不依赖任何人的记忆。

做对的事要比做错的事更容易。 这才是持久的学习。

根因分析¶

`KV is not defined` 的完整链路¶

Capability 的 execute body 是用户（或 Agent）写的业务逻辑，比如：

const stored = await KV.get('todos');
await KV.put('todos', JSON.stringify(todos));

这段代码被 codegen.ts 包装成完整的 Worker 代码：

export default {
  async fetch(request, env) {
    const rawKv = env && env.kv;
    // ← 旧版 codegen 这里没有 const KV = rawKv;

    const userEnv = rawKv ? { kv: {...}, store: {...} } : { kv: null, store: null };

    const __result = await (async (input, env) => {
      // ← 旧版 codegen 这里也没有 const KV = env && env.kv;

      // execute body 直接嵌入：
      const stored = await KV.get('todos');  // ← KV 未定义！
    })(input, userEnv);
  }
};

为什么新代码没问题¶

当前版本的 codegen 在两处都加了 KV 别名：

外层：const KV = rawKv;（Worker 级别）
内层：const KV = env && env.kv;（execute body 闭包内）

为什么旧代码有问题¶

旧的 definition 的 code 字段存在 D1 里，不会随 codegen 更新而自动重新生成。deployment 指向旧 hash，invoke 时执行的是旧代码。

修复¶

在 automaton.ts 的 invoke 方法中，执行代码前检测并 patch：

// Patch legacy codegen: inject KV alias if missing
if (!code.includes('const KV = rawKv') && code.includes('const rawKv = env && env.kv')) {
  code = code.replace(
    'const rawKv = env && env.kv;',
    'const rawKv = env && env.kv;\n      const KV = rawKv; // patched: legacy KV alias',
  )
}

9 行代码，向后兼容，不需要重新 define/deploy 任何旧 capability。

趟路实录¶

手写 counter fixture¶

创建了一个最小的 counter-test Capability：

// execute body — 用 env.kv（规范写法）
if (input.action === 'increment') {
  const c = parseInt(await env.kv.get('count') || '0');
  await env.kv.put('count', String(c + 1));
  return { count: c + 1 };
}
if (input.action === 'get') {
  const c = parseInt(await env.kv.get('count') || '0');
  return { count: c };
}
if (input.action === 'reset') {
  await env.kv.put('count', '0');
  return { count: 0 };
}

用 wrangler d1 execute 直接插入 D1 definitions + deployments。不经过豆豆。

一个最小 HTML——数字 + 三个按钮 (+1, Get, Reset) + 日志区：

async function inc() {
  const r = await __uncaged.deps.counter.rpc('increment');
  document.getElementById('count').textContent = r.count;
}

通过豆豆的 create_app + deploy_app 创建（deps 设为 {counter: "counter-test"}）。

验证结果¶

在浏览器 Canvas UI 中操作：

get...    → {"count":0}   ✓
inc...    → {"count":1}   ✓
inc...    → {"count":2}   ✓
inc...    → {"count":3}   ✓
reset...  → {"count":0}   ✓

6 层全部通了。同时 Todo App 也恢复正常。

8 个 bug 全貌¶

#	问题	层级	根因	修复
1	TS 未转译	平台：assembleApp	esm.sh 需要 JSON body	`9073c05`
2	`__uncaged.deps` undefined	平台：widget-render	signWidgetUrl 没传 deps	`e6b9677`
3	响应双重包装	平台：widget bridge	deps.rpc 没解包 `.result`	`ba2a160`
4	ExecutionContext 缺失	平台：widget-rpc handler	没传 ctx 给 toolCtx	`aafd738`
5	Unknown tool	平台：tool-dispatcher	skipInvokeTracking 漏 return	`07d52e1`
6	参数嵌套	平台：widget bridge	rpc(action, args) 两参 vs 单对象	`434a01b`
7	ExecutionContext 再缺失	平台：kv-proxy	ctx.exports.KvProxy 不存在	`5d0cf96`
8	`KV is not defined`	平台：codegen + D1 缓存	旧 codegen 无 KV 别名	`78cc8d8`

全部 8 个都是平台层问题，没有一个是豆豆生成的代码的错。这恰恰说明了师傅趟路的必要性——如果直接让豆豆反复试，永远修不到平台层。

Commits¶

Commit	描述
`9073c05`	fix(codegen): esm.sh transform needs JSON body
`e6b9677`	fix(widget): pass deps to signWidgetUrl
`ba2a160`	fix(widget): unwrap .result in deps.rpc
`aafd738`	fix(widget-rpc): pass ExecutionContext to toolCtx
`07d52e1`	fix(tool-dispatcher): return result when skipInvokeTracking
`434a01b`	fix(widget): normalize deps.rpc argument format
`5d0cf96`	fix(kv): ScopedKV fallback when KvProxy unavailable
`78cc8d8`	fix(sigil): patch legacy codegen KV alias at invoke time

下一步¶

Phase 2：把 counter fixture 变成自动化集成测试
Phase 3：整理 Widget ↔ Capability 开发契约，更新豆豆 soul prompt

师傅趟路：Widget → Capability 集成修复实录¶

背景¶

出了什么问题¶

表面问题¶

更深的问题¶

最深的问题¶

方法论：师傅教徒弟¶

为什么不能直接让徒弟（豆豆）去试¶

三步走¶

核心洞察：学习的终点是环境改造¶

根因分析¶

`KV is not defined` 的完整链路¶

为什么新代码没问题¶

为什么旧代码有问题¶

修复¶

趟路实录¶

手写 counter fixture¶

手写 counter Widget¶

验证结果¶

8 个 bug 全貌¶

Commits¶

下一步¶

参考¶

师傅趟路：Widget → Capability 集成修复实录¶

背景¶

出了什么问题¶

表面问题¶

更深的问题¶

最深的问题¶

方法论：师傅教徒弟¶

为什么不能直接让徒弟（豆豆）去试¶

三步走¶

核心洞察：学习的终点是环境改造¶

根因分析¶

KV is not defined 的完整链路¶

为什么新代码没问题¶

为什么旧代码有问题¶

修复¶

趟路实录¶

手写 counter fixture¶

手写 counter Widget¶

验证结果¶

8 个 bug 全貌¶

Commits¶

下一步¶

参考¶

`KV is not defined` 的完整链路¶