docs: add code mode design draft (TODO)

Author: guo-yu

docs/plans/2026-03-25-code-mode.md

@@ -0,0 +1,75 @@
+# Code Mode — 在 Sandbox 中执行代码片段
+
+**状态：** TODO
+**日期：** 2026-03-25
+**背景：** 受 Cloudflare Dynamic Workers 启发，结合 db9 HTTP API 的纯 fetch 可操作性
+
+---
+
+## 动机
+
+当前 `exec()` 执行的是 shell 命令，agent 需要反复来回调用。Code mode 让 agent 生成一段完整的逻辑代码一次性执行，减少 round-trip。
+
+典型场景：agent 生成一段 JS 代码，通过 db9 HTTP API 做复杂查询和数据处理，一次返回结构化结果。
+
+## 接口设计（草案）
+
+```typescript
+export interface CodeRunnerSandbox extends Sandbox {
+  runCode(code: string, options?: RunCodeOptions): Promise<RunCodeResult>
+}
+
+export interface RunCodeOptions {
+  language?: 'javascript' | 'typescript' | 'python'
+  timeout?: number
+  env?: Record<string, string>  // 注入为代码中可访问的 env 对象
+}
+
+export interface RunCodeResult {
+  output: unknown   // 代码 return 的值（JSON-serializable）
+  stdout: string
+  stderr: string
+}
+```
+
+`code` 是 async function body，可以用 `fetch()` 和 `return`：
+
+```typescript
+const result = await sandbox.runCode(`
+  const res = await fetch("https://api.db9.ai/customer/databases/mydb/sql", {
+    method: "POST",
+    headers: { "Authorization": "Bearer " + env.DB9_TOKEN, "Content-Type": "application/json" },
+    body: JSON.stringify({ query: "SELECT count(*) FROM users" })
+  })
+  return await res.json()
+`, { env: { DB9_TOKEN: 'xxx' } })
+```
+
+## Provider 实现差异
+
+| | cloud / boxlite (VM) | cloudflare (isolate) |
+|--|---------------------|---------------------|
+| 实现 | 包装成 Node.js 脚本，通过 exec 执行 | 包装成 Dynamic Worker module |
+| 启动 | ~50ms | ~5ms |
+| `fetch()` | ✅ | ✅ |
+| `fs` | ✅ | ❌ |
+| `child_process` | ✅ | ❌ |
+| npm 依赖 | require() 可用 | 需预 bundle |
+
+跨 provider 可移植的代码限于：纯计算 + `fetch()` + `return`。
+
+## Capability
+
+```typescript
+'code.run'          // 基础 code mode（fetch + return）
+'code.run.fs'       // code 中可用 fs（VM only）
+'code.run.process'  // code 中可用 child_process（VM only）
+```
+
+## 待决策
+
+1. `code` 参数是 function body 还是完整 ES module？
+2. env 注入方式：全局 `env` 对象 vs `process.env`
+3. 是否需要 `sandbank run` CLI 命令
+4. 依赖处理：Cloudflare 需要预 bundle，VM 不需要
+5. 错误处理：代码抛异常时的返回格式