数据截至 (上游 commit 7830cc746c11)
GenBI:仪表盘生成与一键部署
30 秒导读: 这一章讲 WrenAI 三个节拍里的第二拍 —— Deploy。当 agent 已经把一个业务问题变成一条受治理的 SQL 答案后,怎么把这个"答案"变成一个可分享、能在浏览器里跑、无需后端的仪表盘应用?核心答案是:
wren genbi这套 CLI 自己不写前端代码,它把"用本项目的上下文层构建一个 GenBI app"合成为一份指令,交给外面的编码 agent 去实现;然后负责登记、部署前防泄密校验、一键部署到用户自己的 Vercel / Cloudflare Pages 账号。跑起来的应用由wren-core-wasm(语义引擎的 WebAssembly 版)驱动,在浏览器里按 MDL 语义直接查询数据。
本章只覆盖 core/wren/src/wren/genbi/ 这一个子系统。上下文层(MDL、项目文件)怎么来,见 上下文层:MDL 语义模型与项目文件;模型名 SQL 如何被翻译成受治理的物理 SQL,见 语义引擎:模型名 SQL → 受治理物理 SQL。
1. 这是什么(零基础也能懂)
一句话定义: wren genbi 是一套把"一次数据分析答案"变成"一个静态仪表盘网站"并帮你部署上线的命令行工具链。
它和你想象的"AI 生成前端"不一样。 最容易误解的一点:Wren 不自己生成前端代码。它扮演的是"包工头 + 质检 + 物流",不是"泥瓦匠"。真正动手写 HTML/JS 的是外部的编码 agent(比如 Claude Code、Cursor 这类)。Wren 做三件事:
- 合成一份施工图纸 —— 把静态模板、本项目的实时事实(有哪些模型、哪些列、数据源是什么)、用户的原始需求拼成一份权威的"构建指令",打印到 stdout,交给 agent。
- 登记与质检 —— agent 把应用写进
apps/<name>/后,Wren 把它登记进项目清单,并在部署前做一次结构校验 + 防泄密扫描。 - 一键物流 —— 校验通过后,把这个静态文件夹上传到用户自己的 Vercel 或 Cloudflare Pages 账号。
给谁用、解决什么问题: 假设你是一个数据 agent 的搭建者。agent 已经能回答"上季度各区域营收是多少"。现在你想让这个答案变成一个同事点开链接就能看、还能自己改筛选条件的看板 —— 而且你不想为它运维一个后端服务。wren genbi 就是把这最后一公里(从答案到可分享的应用)标准化、并守住"公开站点绝不能泄露数据库密码"这条红线。
为什么能没有后端? 因为语义引擎被编译成了 WebAssembly(wren-core-wasm)。浏览器直接加载这个 wasm 引擎 + 项目的 MDL,就能在客户端按语义模型跑查询 —— 数据要么打包进应用一起发(快照模式),要么由应用连回用户自己的数据源(实时模式)。
用起来什么样: 一条端到端的命令序列大致长这样:
# 1. 让 Wren 吐出一份"构建指令",喂给你的编码 agent
wren genbi build sales-dash --prompt "各区域季度营收看板" --data-mode snapshot
# 2. (agent 按指令把应用写进 apps/sales-dash/ 后)登记进项目清单
wren genbi register sales-dash --data-mode snapshot
# 3. 部署前质检:文件齐不齐、MDL 能不能解析、有没有把密码写进代码
wren genbi verify sales-dash
# 4. 本地预览
wren genbi open sales-dash
# 5. 一键部署到你自己的 Vercel 账号
wren genbi deploy sales-dash --provider vercel
一句话直觉: 把 wren genbi 当成一个发布流水线:build(出图纸)→ agent 施工 → register(入册)→ verify(质检卡口)→ deploy(上线)。Wren 掌管的是"图纸、册子、质检、物流",施工交给 agent,运行时交给浏览器里的 wasm 引擎。
2. 顶层全景(它大概怎么转)
这节讲什么: 把 genbi 子系统的部件、它们的职责、以及一条完整的"从需求到上线"数据流串一遍。
2.1 一张流水线图
下面这张图从左到右就是一次完整的生命周期。关键:Wren(CLI)和 agent 是两个不同的执行者 —— 虚线框内是 Wren 管的,[AGENT] 那一步是外部 agent 干的。
用户需求 + --data-mode
│
▼
┌─────────────────────────────────────────────────────────┐
│ wren genbi build │
│ ├─ 隐式编译 MDL(若 target/mdl.json 缺失) │
│ ├─ 读项目事实:模型清单 + 数据源 │
│ └─ compose_build_instruction() → 打印"构建指令"到 stdout │
└─────────────────────────────────────────────────────────┘
│ 指令(markdown 纯文本)
▼
[AGENT] 按指令把静态应用写进 apps/<name>/
│ (index.html + mdl.json + 数据资产/连接配置)
▼
┌──────────────────┐ ┌──────────────────────────────┐
│ wren genbi │ │ wren genbi verify │
│ register │─────▶│ ① 必需文件在? │
│ 写 .wren/apps.yml│ │ ② mdl.json 能解析? │
│ status=scaffolded│ │ ③ snapshot 有数据资产? │
└──────────────────┘ │ ④ _scan_for_secrets 防泄密 │
└──────────────────────────────┘
│ 通过 → status=built
▼
┌──────────────────────────────┐
│ wren genbi deploy │
│ ├─ 再跑一遍 verify(卡口) │
│ ├─ resolve_token(Vercel/CF) │
│ └─ provider.deploy() 上传 │
└──────────────────────────────┘
│ 成功 → status=deployed
▼
公开 URL(*.vercel.app / *.pages.dev)
│
▼
浏览器加载 wren-core-wasm + MDL,
客户端按 MDL 语义查询(无后端)
2.2 部件一句话职责
| 部件 | 干什么 | 文件 |
|---|---|---|
composer | 把模板 + 项目事实 + 用户需求合成为"构建指令" | genbi/composer.py |
index | 维护项目内的 GenBI app 清单(.wren/apps.yml) | genbi/index.py |
verify | 部署前结构校验 + 防泄密扫描 | genbi/verify.py |
tokens | 三级查找 Vercel/Cloudflare 部署令牌 | genbi/tokens.py |
cli | Typer 子命令,把 compose→verify→deploy 串起来 | genbi/cli.py |
providers | 可互换的部署适配器(Vercel REST / Cloudflare wrangler) | genbi/providers/ |
wren-core-wasm | 浏览器端的语义引擎,让部署产物无需后端 | core/wren-core-wasm/(外部) |
2.3 主线走一遍(高层)
一条最短路径:需求进来 → build 出图纸 → agent 施工 → register 入册 → verify/deploy 质检并上线 → 浏览器里 wasm 跑起来。
贯穿全程有一条暗线:Wren 反复强调"这是个公开静态站点,任何人打开 URL 都能读到每一个文件"。这条暗线塑造了几乎所有关键设计 —— --data-mode 的两种取舍、verify 的默认拒绝式防泄密扫描、令牌绝不走命令行参数。理解了"产物是公开的",就理解了这个子系统一半的设计动机。
3. 核心原理(逐个机制,由浅入深)
3.1 构建指令合成:Wren 不写前端,而是"发图纸"
它要解决的小问题: 怎么让一个通 用编码 agent,构建出一个正确挂载了本项目上下文层的 GenBI 应用?
思路: agent 很会写前端,但它不知道"你这个项目有哪些模型、哪些列、数据源是什么、wasm 引擎该怎么接线"。Wren 的价值就是把这些项目专属的事实注入进一份指令里,让 agent 拿到的不是空白提示,而是一份填好了项目上下文的施工图纸。
这个设计和 Wren 别处的 wren context instructions 是同一个模式:CLI 不执行动作,只产出一份权威的、纯 markdown 的指令交给 agent(见 composer.py 模块 docstring)。
指令里有什么: compose_build_instruction 把五类东西拼进一份 markdown(composer.py:72 compose_build_instruction):
| 区块 | 内容 | 来源 |
|---|---|---|
| wasm 接线 | 从 CDN 加载 wren-core-wasm、loadMDL、query 的样板 | 静态模板 + 版本常量 |
| 项目上下文 | 编译好的 MDL 路径、目标文件夹、数据源、数据模式 | CLI 传入 |
| 可用模型 | 每个模型及其列名的清单 | load_models()(见 02) |
| 数据处理指引 | 按 data_mode 二选一的具体步骤 | _data_mode_guidance |
| 用户需求 | 用户原始 prompt,逐字附在末尾 | CLI 传入 |
版本钉死。 wasm 引擎的版本用一个常量钉住,并要求和 wasm 包的 package.json 保持同步(composer.py:15 WREN_CORE_WASM_VERSION = "0.4.1")。指令里明确让 agent 从共享 CDN 加载,不要把 ~68MB 的 wasm 二进制打进应用文件夹(composer.py:90-103)。
模型清单怎么格式化。 一个小而实用的函数,把模型列表变成每行一个 bullet、附上列名;模型为空时给出可执行的补救提示(composer.py:54 _format_model_inventory):
# 真实源码 composer.py:54-62 _format_model_inventory
def _format_model_inventory(models: list[dict]) -> str:
if not models:
return "- (no models found — run `wren context build` first)"
lines = []
for model in models:
cols = ", ".join(c.get("name", "?") for c in model.get("columns", []))
lines.append(f"- **{model.get('name', '?')}**: {cols}")
return "\n".join(lines)
这段做的事:把每个模型渲染成 - **模型名**: 列1, 列2, ...;找不到模型时不是报错,而是给 agent 一句可照做的提示。
数据模式:嵌入数据 vs 实时查询
这是 build 阶段最重要的一个决策。 --data-mode 决定了部署产物如何拿到数据,只有两个合法值(composer.py:17 DATA_MODES = ("snapshot", "live")),_data_mode_guidance 按它派发不同的施工指引(composer.py:46)。
| 维度 | snapshot(快照 / 嵌入数据) | live(实时查询) |
|---|---|---|
| 数据来源 | 打包进应用的静态资产(*.parquet / *.duckdb) | 部署后连回用户自己的数据仓库/API |
| 后端 | 完全无后端,纯静态 | 应用里写一个"端点 URL"连接配置 |
| 引擎怎么查 | 浏览器里 wasm 直接查静态资产 | wasm 通过端点查实时数据 |
| 关键红线 | —— | 数据库凭证绝不能内联进应用 |
| 额外要求 | 把数据导出为 parquet 放进 data/ | 端点须对部署域名开放 CORS |
live 模式的指引里有一条硬规则,值得原文体会(composer.py:24-30):
"HARD RULE: warehouse credentials MUST NEVER be inlined into the app. The app is a public static site..."
指引明确说:wren genbi verify 的密钥扫描只是"尽力而为的纵深防御",不是保证 —— 真正守住秘密的是"凭证绝不内联"这条硬规则本身(composer.py:26-30)。用代理/带鉴权的 API,或浏览器端鉴权,而不是把密码写进公开文件。
未知模式直接抛错。 _data_mode_guidance 对不认识的模式 raise ValueError(composer.py:51),配合 CLI 层的前置校验(cli.py:113),让一个拼错的 --data-mode(比如 snapsho)在早期就失败,而不是默默产出错误指引。
3.2 应用登记与生命周期:项目内的 app 清单
它要解决的小问题: 一个项目里可能有多个 GenBI app,Wren 怎么知道有哪些、各自什么状态、部署到哪了?
思路: 用一个机器写、机器读的清单文件当唯一事实源 —— <project>/.wren/apps.yml(index.py:18 _INDEX_RELPATH,index.py:24 index_path)。它刻意模仿了 ~/.wren/profiles.yml 的注册表模式,并且只存非机密的链接状态,秘密永远不进这里(见 index.py 模块 docstring)。
生命周期是个三态状态机(index.py:21 STATUSES):
register verify 通过 deploy 成功
scaffolded ─────────▶ (built) ─────────▶ deployed
刚登记 质检过关 已 上线
register_app首次登记时置为scaffolded(index.py:80)。verify通过后,若还停在scaffolded才推进到built(cli.py:266-267)。deploy成功后置为deployed,并把部署链接状态一起写回(cli.py:373)。
清单的 CRUD 由五个纯函数承担:
| 函数 | 作用 | 位置 |
|---|---|---|
load_index | 读清单,不存在则返回空骨架 | index.py:32 |
save_index | 写回 YAML(不排序键,保持人可读顺序) | index.py:74 |
register_app | 新建或更新某 app 的条目 | index.py:80 |
remove_app | 删条目(返回 False 表示本就没登记) | index.py:100 |
get_app | 取单个条目或 None | index.py:110 |
update_app | 把若干字段合并进条目并持久化 | index.py:126 |
防御式读取是这里的精华。 load_index 花了很大篇幅处理"文件存在但坏了"的情况,因为一个坏清单如果不早点报错,会在某个命令深处炸出一个看不懂的 AttributeError。它的处理分层很清楚:
# 真实源码 index.py:42-52(节选)load_index
try:
data = yaml.safe_load(path.read_text())
except yaml.YAMLError as e:
raise MalformedIndexError(f"{path} is not valid YAML: {e}") from e
if data is None:
data = {}
if not isinstance(data, dict):
raise MalformedIndexError(
f"{path} is malformed — expected a mapping at the top level, "
f"got {type(data).__name__}."
)
三层校验依次是:能不能解析成 YAML → 是不是 mapping → apps 键是不是 mapping。任何一层不过都抛 MalformedIndexError 并带上出问题的路径(index.py:28 MalformedIndexError)。
一个真实踩过的坑藏在注释里(index.py:53-59):早先用 setdefault 规整 apps: 这种"键在但值为 null"的情况 —— 但 setdefault 对已存在的键是 no-op,于是 apps: None 被原样留下,让后面每个访问器都崩。修法是显式判 is None(而不是判真假),这样一个合法的 falsy 值仍会被保留、交给校验去暴露,而不是被悄悄改成默认值(index.py:60-69)。
3.3 交付前校验:结构检查 + 防泄密扫描
它要解决的小问题: 怎么保证一个 agent 写出来的应用"能跑"、并且"不会把公司数据库密码发到公网上"?
思路: 在产物走向公开 URL 之前,设一道确定性的、无浏览器的卡口(verify.py 模块 docstring)。它只做静态结构检查,不真的启动浏览器跑 wasm(那是未来可能的加固)。
verify_app 的检查项依次是(verify.py:111):
- 数据模式合法 —— 未知模式直接 fail closed,避免拼错的模式绕过后续检查(
verify.py:119-126)。 - 应用文件夹存在 且有
index.html入口(verify.py:128-132)。 mdl.json存在、非空、是合法 JSON(verify.py:134-143)。- 快照模式必须有数据资产(
*.parquet/*.duckdb),否则应用没数据可查(verify.py:145-155,verify.py:15_DATA_ASSET_SUFFIXES)。 - 每种模式都跑防泄密扫描(
verify.py:158)。
结果用一个小 dataclass 承载(verify.py:105 VerifyResult):passed 布尔 + failures 消息列表。
_scan_for_secrets:默认拒绝式的密钥扫描
这是本子系统最能体现"公开产物"暗线的地方(verify.py:68 _scan_for_secrets)。它的核心设计决策是 默认扫描一切,只跳过明确的二进制/数据格式,而不是"只扫某几类文本文件":
为什么是默认拒绝(default-deny)? 注释讲得很直白(
verify.py:17-22):如果用"允许名单"(只扫.html/.js…),你永远追不上 agent 下一次会用什么扩展名(.env、.ts、.vue…)—— 而 这些恰恰是最可能藏着凭证、又都会被发到公开站点的文件。
所以它反过来:遍历每个普通文件,只跳过已知的二进制/数据后缀(verify.py:23 _UNSCANNABLE_SUFFIXES,含 .parquet/.wasm/.png/.woff2/.zip 等),其余一律读文本、跑正则。
扫描有两条独立的防线:
防线一:.env* 文件仅凭存在就判失败。 不管里面内容能不能被下面的正则识别 —— 一个 .env 文件出现在公开静态应用里几乎必然是错误,而 wrangler pages deploy . 会把它整个发出去,所以这道门是唯一能拦住它的(verify.py:82-88)。
防线二:窄正则匹配内联凭证(verify.py:48 _SECRET_PATTERNS),模式刻意保持窄以避免误报:
| 模式 | 抓什么 |
|---|---|
| connection string with password | scheme://user:pass@host 这种带密码的连接串 |
| AWS access key id | AKIA 开头的 AWS key |
| password/secret/token assignment | password = "..." / api_key: "..." 这类赋值(值 ≥8 字符) |
# 真实源码 verify.py:76-88(节选)_scan_for_secrets
for path in sorted(app_dir.rglob("*")):
if not path.is_file() or path.is_symlink():
continue
if path.name.startswith(".env"): # 防线一:.env 仅凭存在即失败
failures.append(...)
continue
if path.suffix.lower() in _UNSCANNABLE_SUFFIXES: # 跳过二进制/数据
continue
这段重点看两点:符号链接被直接跳过(providers 也不发它们),以及 .env 的处理排在后缀过滤之前 —— 保证它绝不会因为"后缀可疑"之类理由被漏掉。
3.4 令牌解析:密钥绝不走命令行
它要解决的小问题: 部署要用 Vercel / Cloudflare 的 API 令牌,怎么拿到它、又不让它泄露?
思路: 令牌是秘密,而命令行参数会漏进 shell 历史和进程列表(ps 能看到)。所以 Wren 抄了 Vercel agent-skill 的模式:令牌永远不接受 --token 这种 CLI flag,而是从环境里发现(tokens.py 模块 docstring)。
resolve_token 做三级查找(tokens.py:14):
① 进程环境变量(shell export 的最优先)
│ 命中即返回
▼
② 标准 .env 发现(cwd → 向上走到项目根 → ~/.wren/.env)
│ 命中即返回
▼
③ 显式 --path 项目目录下的 .env(覆盖 cwd 之外的项目)
│
▼
都没有 → 返回 None(由调用方决定是否提示)
三级依次是:shell 环境 > 通用 .env 发现 > 指定项目的 .env。找不到不报错,而是返回 None,把"要不要提示用户"的决定权留给调用方(tokens.py:41)—— deploy 命令拿到 None 时会打印一条可操作的提示,并再次强调"绝不要用 CLI flag 传令牌"(cli.py:342-350)。
每个 provider 声明自己要读哪个环境变量:Vercel 读 VERCEL_TOKEN(vercel.py:65),Cloudflare 读 CLOUDFLARE_API_TOKEN(cloudflare.py:47)。
3.5 CLI 编排:把 compose → verify → deploy 串起 来
这节讲什么: genbi/cli.py 是把前面所有部件粘起来的 Typer 子应用(cli.py:10 genbi_app)。这里讲两个最值得看的点:路径安全 和 deploy 的完整编排。
应用名即路径:一道防目录穿越的关卡
app 名字会变成 <project>/apps/ 下的一段路径。一个精心构造的名字(比如 ../../etc)如果不拦,就能逃出 apps/。_resolve_app_dir 用一条 slug 正则堵死这个口子(cli.py:18 _APP_NAME_RE,cli.py:21 _resolve_app_dir):
# 真实源码 cli.py:18 _APP_NAME_RE
_APP_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
它要求名字以字母数字开头,只含字母数字、_、- —— 于是路径分隔符、..、以点开头的名字全被拒,返回的路径永远被关在 <project>/apps/ 里面。build/register/verify/open/deploy 全走这个函数。
deploy:一次完整编排
deploy 命令(cli.py:298)是整条流水线的收口,步骤环环相扣:
deploy <name> --provider vercel [--prod]
│
├─ 1. _require_registered:没登记就报错退出 (cli.py:321)
├─ 2. get_provider(provider):取适配器,未知 provider 报错 (cli.py:325)
├─ 3. verify_app:再跑一遍质检 —— "坏应用永不落到公开 URL" (cli.py:331)
├─ 4. resolve_token:三级找令牌,找不到给可操作提示 (cli.py:341)
├─ 5. adapter.deploy(...):真正上传,失败抛 DeployError (cli.py:352)
└─ 6. update_app:status=deployed + 写回 deploy 链接状态 (cli.py:373)
注意第 3 步:部署前会再独立跑一次 verify(不是复用 verify 命令的结果),注释点明动机是"a broken app never reaches a public URL"(cli.py:330)。这是"公开产物"暗线的又一次体现 —— 质检是部署自己的一部分,不能靠用户记得先跑 verify。
其余命令各司其职:
| 命令 | 作用 | 位置 |
|---|---|---|
build | 打印构建指令(必要时先隐式编译 MDL) | cli.py:63 |
register | 登记 agent 写好的应用 | cli.py:159 |
list | 列出已登记的应用及状态、部署 URL | cli.py:195 |
remove | 从清单删除(保留 apps/<name>/ 文件) | cli.py:215 |
verify | 单独跑质检 | cli.py:244 |
open | 本地起 HTTP server 预览 | cli.py:271 |
deploy | 质检 → 部署 | cli.py:298 |
build 的一个体贴细节: 如果 target/mdl.json 还没编译,build 会隐式先编译一次(cli.py:123-134),这样喂给 agent 的指令里永远是最新的上下文层,而不是过期或缺失的 MDL。
3.6 部署适配器:Vercel 走 REST,Cloudflare 走 wrangler
它要解决的小问题: 把一个静态文件夹上传到不同的托管商,它们的上传方式差别很大,怎么用统一接口包住?
思路: 定义一个 DeployProvider 协议(providers/base.py:25),每个托管商写一个适配器实现它;get_provider(name) 按名字返回适配器,未知名字抛 KeyError 并列出已知集合(providers/__init__.py:8)。返回值统一是一个 Deployment dataclass —— 只含非机密的链接状态(URL、环境、项目/账号 id)(providers/base.py:10 Deployment)。
两个适配器走了截然不同的路,原因很实际:
| 维度 | Vercel(vercel.py) | Cloudflare Pages(cloudflare.py) |
|---|---|---|
| 上传方式 | v13 REST API,文件 base64 内联,一次调用搞定 | shell out 到 wrangler pages deploy |
| 为什么 | 有单次内联上传端点,无需 CLI | Pages 没有单次内联 REST 端点;官方建议就是用 wrangler(cloudflare.py:1-12) |
| 令牌怎么传 | 只在 Authorization header 里,绝不进 argv | 只经子进程环境变量,绝不进 argv |
| 额外要求 | —— | 需要 wrangler(或 npx wrangler)+ CLOUDFLARE_ACCOUNT_ID |
| URL 怎么拿 | 从 API 响应读 | 用正则从 wrangler 输出里抓 *.pages.dev(cloudflare.py:22) |
两处共同的安全细节都围着"公开产物"暗线转:
- Vercel 收集文件时跳过符号链接、跳过解析后落在 build_dir 之外的路径、跳过
.env*(vercel.py:38-60_collect_files)—— 哪怕 verify 漏了,这里再拦一道,防止一个野生 symlink 把磁盘上别处的文件也发出去。 - Cloudflare 部署时用
cwd=build_dir跑deploy .,这样 wrangler 不会误捡项目根里某个无关的wrangler.toml(cloudflare.py:100-117)。
令牌传递方式再强调一遍(两个适配器 docstring 都写了):Vercel 令牌只走 Authorization header(vercel.py:5-6),Cloudflare 令牌只走子进程环境(cloudflare.py:79-84)—— 都绝不进命令行参数。
4. 浏览器端的运行时:wren-core-wasm 让产物无需后端
这节讲什么: 前面都在讲"怎么造和发",这节讲"发出去的东西靠什么跑"。
部署产物是纯静态站点,却能按语义模型查询数据 —— 秘密在于语义引擎被编译成了 WebAssembly。README 把这一拍描述为(README:56):
"Deploy. Turn any answer into a shareable, browser-side dashboard powered by
wren-core-wasm..."
wren-core-wasm 是 Rust 语义引擎 wren-core 的浏览器构建,以 npm 包分发,产物约 68MB(见根 CLAUDE.md 的 wasm 段)。构建指令让 agent 从 CDN(unpkg)加载它、而不是打包进应用(composer.py:90-103),典型接线是:
// 示意,非源码 —— 摘自 composer.py 生成的指令模板
import { WrenEngine } from
const engine = await WrenEngine.init();
await engine.loadMDL(mdl, profile); // profile: { source: "<url前缀或空>" }
const result = await engine.query(sql); // 按 MDL 语义查询
这就是"无后端"的关键闭环: 浏览器加载 wasm 引擎 + 项目的 mdl.json,profile.source 指向静态数据资产(快照模式)或实时端点(实时模式)。查询在客户端按 MDL 语义解析、执行 —— 和服务端语义引擎走的是同一套 MDL 治理(见 03),只是搬进了浏览器。所以一次 wren genbi deploy 之后,分享出去的就是一个自带语义引擎、任何人打开即用、不需要你运维任何服务的仪表盘。
5. 巧妙之处(可借鉴的技术)
"CLI 不做,只发指令"这个反直觉的分工。 Wren 明明是做数据的,却坚决不生成前端,而是把项目事实注入一份指令交给通用 agent(composer.py:72)。妙在分离了"项目专属知识"和"通用编码能力" —— Wren 只负责它独有的部分(上下文层),把它不擅长也没必要做的前端施工外包出去。
"公开产物"作为贯穿全局的第一性原理。 从 --data-mode 的硬规则(composer.py:24),到 default-deny 的密钥扫描(verify.py:17-22),到 deploy 内置的强制质检(cli.py:330),到 provider 里跳过 symlink/.env(vercel.py:38-60)—— 同一条"任何人能读到每个文件"的暗线,推导出了一整套一致的防御。值得学的是从一个物理事实反复推导设计,而不是零散打补丁。
纵深防御,且诚实标注每层的能力边界。 密钥防护有三层:硬规则(靠人)、verify 扫描(尽力而为)、provider 再过滤。而且代码明确写出扫描"不是保证"(composer.py:26-30)—— 不夸大自动化能力,把最终责任说清楚。
default-deny 胜过 allowlist。 密钥扫描默认扫一切、只跳过二进制(verify.py:17-22),背后的洞察是"你追不上 agent 下一个会用的扩展名"。这个"面对不可预测的输入,反过来枚举安全的例外"的思路,在安全设计里很通用。
令牌永不进 argv。 三级环境查找(tokens.py:14)+ header/子进程环境传递(vercel.py:84、cloudflare.py:79-84),系统性地把秘密挡在 shell 历史和进程列表之外。
防御式读清单 + 注释留证。 load_index 分层校验坏文件(index.py:42-69),并把"setdefault 曾导致 apps: None 崩溃"这个真实踩坑写进注释(index.py:53-59)—— 让后人知道"为什么这里不能图省事"。
6. 边界与局限
verify 不是真的把应用跑起来。 它只做静态结构检查,不启动浏览器跑 wasm 冒烟查询;模块 docstring 自己承认"真正的 headless wasm 冒烟查询是未来可能的加固"(verify.py:1-6)。所以"文件齐、MDL 能解析"不等于"查询真能出结果"。
密钥扫描按设计会漏。 正则刻意保持窄以免误报(verify.py:47),default-deny 也只是缩小而非消灭风险面。代码反复强调它是纵深防御、不是保证(composer.py:26-30)—— 真正的保障是"凭证绝不内联"的人为纪律。
只支持两种数据模式、两个部署商。 DATA_MODES 只有 snapshot/live(composer.py:17);provider 注册表只有 vercel/cloudflare(providers/__init__.py:13-16),base 里提到"wren SaaS later"是未来项(providers/base.py:1)。
Cloudflare 部署依赖外部 wrangler CLI。 没有 wrangler 也没有 npx 就直接失败并提示安装(cloudflare.py:71-77);URL 是从 wrangler 文本输出里正则抓的(cloudflare.py:125),若上游改了输出格式可能抓不到。
live 模式的 CORS 要用户自己配。 端点必须对部署域名开放 CORS,这条 Wren 只能提醒、无法代办(composer.py:31-32)。
清单只记链接状态,不备份应用。 remove 只删清单条目,apps/<name>/ 的文件原样保留(cli.py:227);清单本身不做版本或并发保护。
7. 横向对比(同组其它章)
genbi 是 WrenAI 这个数据 agent 货架上"最后一公里"的部件,它站在前几章的产出之上:
| 关切 | 本章(genbi) | 相邻章 |
|---|---|---|
| 上下文从哪来 | 消费编译好的 MDL + 模型清单 | 02 上下文层:MDL 语义模型与项目文件 |
| 查询语义如何治理 | 部署产物在浏览器里用同一套 MDL 语义 | 03 语义引擎:模型名 SQL → 受治理物理 SQL |
| CLI/skills 如何下发 | genbi 是 wren CLI 的一个子命令组 | 01 Agent 驱动的 CLI 与 skills 下发 |
| 过往查询如何召回 | (不直接相关;答案可来自召回) | 04 记忆与检索 |
| 全景与阅读顺序 | —— | index |
一句话定位:02/03 把"正确的答案"造出来,genbi 把这个答案"打包上线成可分享的应用"。
8. 代码地图(导航索引)
用符号名 grep 比行号更抗漂移。下面每行指向一个该打开的真实符号。
| 主题 | 文件路径 | 符号名 |
|---|---|---|
| 合成构建指令(总入口) | core/wren/src/wren/genbi/composer.py | compose_build_instruction |
| 数据模式派发指引 | core/wren/src/wren/genbi/composer.py | _data_mode_guidance / _LIVE_GUIDANCE / _SNAPSHOT_GUIDANCE |
| 模型清单格式化 | core/wren/src/wren/genbi/composer.py | _format_model_inventory |
| wasm 版本 / 数据模式常量 | core/wren/src/wren/genbi/composer.py | WREN_CORE_WASM_VERSION / DATA_MODES |
| 清单路径 / schema 版本 / 状态机 | core/wren/src/wren/genbi/index.py | index_path / INDEX_SCHEMA_VERSION / STATUSES |
| 防御式读清单 | core/wren/src/wren/genbi/index.py | load_index / MalformedIndexError |
| 清单 CRUD | core/wren/src/wren/genbi/index.py | register_app / remove_app / get_app / update_app / save_index |
| 结构校验(总入口) | core/wren/src/wren/genbi/verify.py | verify_app / VerifyResult |
| 防泄密扫描 | core/wren/src/wren/genbi/verify.py | _scan_for_secrets / _SECRET_PATTERNS / _UNSCANNABLE_SUFFIXES |
| 令牌三级解析 | core/wren/src/wren/genbi/tokens.py | resolve_token |
| CLI 子命令 | core/wren/src/wren/genbi/cli.py | build / register / list_apps / remove / verify / open_app / deploy |
| 应用名 slug 防穿越 | core/wren/src/wren/genbi/cli.py | _APP_NAME_RE / _resolve_app_dir |
| 部署适配器协议 | core/wren/src/wren/genbi/providers/base.py | DeployProvider / Deployment / DeployError |
| 适配器注册表 | core/wren/src/wren/genbi/providers/__init__.py | get_provider |
| Vercel 适配器(REST) | core/wren/src/wren/genbi/providers/vercel.py | VercelProvider / _collect_files |
| Cloudflare 适配器(wrangler) | core/wren/src/wren/genbi/providers/cloudflare.py | CloudflareProvider / _wrangler_cmd |
| 浏览器端语义引擎(外部) | core/wren-core-wasm/ | WrenEngine(npm wren-core-wasm) |