workflow —— 创作流程与纪律

读者:做工具的用户,和替他干活的 AI。两者读同一份。 先读这章,它定义「做一个工具的顺序」与「不能越的线」;能不能做某件事见 numable docs capabilities,具体文件格式见 layout / xwidget / df / rcn 各章。

一个工具是什么

一个工具就是一个目录,里面全是明文 JSON / HTML,没有构建产物、没有编译步骤。App 把工作区目录当根:文件写进去,包就在 App 里可见;改一个字,重渲就生效。

最小的包长这样(numable init 生成的起步包):

my-source/
  manifest.json                # 身份与元数据:id(ULID)/ version / title / category / network / i18n
  xWidget/
    clock.xwidget              # 一个组件的声明:尺寸档、实例参数、取数绑定、刷新节奏、点击行为
    rc/clock.rcn               # 这个组件的画法(几何 + 颜色 + 文本,渲成一张位图)
    flow/clock.df              # 这个组件的取数流(请求 + 加工,产出给 .rcn 用的键)
  page/
    router.json                # 页面路由表(可选:没有页面就不要 page/)
    html/home/index.html       # 点组件进入的详情页
  .numable/                    # 本机夹具与产出,永不进包(numable init 已写进 .gitignore)

四类文件各管一件事,互不越界:

多出来的两类是可选的:page/ 下的详情页(html / xpage / form 三种页型,见 numable docs page),和 .af 交互流(点击、参数写回、刷新,见 numable docs af)。

创作顺序

七步。每一步都有命令能验,不要跳步——跳过第 2 步直接画组件,是返工最常见的原因(组件画完了才发现字段路径不对,几何和判空全得重写)。

1. 克隆起步

numable init my-source
numable init my-source --from ../已有的包目录

从模板或一个已有的包克隆,不要手搓目录:身份 id(26 位 ULID)由命令行生成并写进 manifest.id / manifest.domain,目录布局与文件后缀现成正确。看到 ✓ 新包 … id=… 即成功。

2. 先取数,后画组件

先写 .df,把数据跑通:

numable run my-source --flow clock --full

--full 打印完整输出。取到的键,就是组件上能用的全部变量——包括你要用来判空的旗标、要显示的时间锚、要驱动折线的定长数组。这一步产出的键名清单,是第 3 步的输入。

看到 ✓ clock {...} 且键名与你预期一致算对;看到 ✗ 就先修流,不要往下走。run 会强制网络白名单,打印 · 网络白名单已强制: [...]——这里少一个 host,真机上就是同一处被拦。

3. 画组件

写 .rcn,渲出来看:

numable render my-source --widget clock

产出在 my-source/.numable/render/ 下:每个组件 × 浅色 / 暗色 / 空态 × 语言各一张 PNG,外加一张 index.html 拼图。render 会先跑一遍 run,取数失败的组件会用空数据渲——所以空态那张不是摆设,它就是「源挂了那天用户看到的东西」。只调版式、不想每次都打一轮网络(有日限额的源尤其要省)时加 --no-run,复用上一次取到的数据。同目录下 <组件>.json 记着每张图的尺寸与可点区域(hits:点哪块会触发哪个事件;为空说明组件里没有单独可点的格子,点整张组件走 .xwidget 的 onClick),核对点击范围时用得上。

包里有页面(page/,点组件打开的那一层)时,页面也渲出来看:

numable render my-source --page

router.json 里每条路由按手机宽出浅色、暗色两张整页截图,落在同一目录的 page*.png。页面里的取数与 run 走同一套白名单和夹具,被拦下的请求、页面脚本报错、没模拟的桥方法都会打印出来。form 页和远程页暂不支持,要在 App 里点进去看。细节见 numable docs page。

4. 声明

写 .xwidget,把 rc / df / 尺寸档 / 刷新节奏 / 点击行为绑起来。两处最容易错:

• canvas.depends 必须写成 {"flow": "@[file://flow/clock.df]", "params": {...}},裸字符串会把入参吞成空(G12c);
• 组件上要显示但不参与取数的键,也得经 .df 透出——.xwidget.params 不在渲染域(G28)。

5. 静态闸

numable check my-source

默认 personal 档,要求零 error。它抓的是「不检查就没人发现」的那一类:白名单不闭合、cell 缺 type、op:if 条件键写错、并发结果晚一拍、取数失败没有 error 出口。错误码全表见 numable docs lint-codes。

6. 贴图确认

把 .numable/render/ 下的浅色 / 暗色 / 空态三张图给用户看。用户点头才算做完——check 与 run 证明不了「好不好看」和「这是不是他想要的那个组件」。

7. 持续优化

用户在 App 编辑器里手改、或再让 AI 改,改的都是同一份源文件。每次改完只需重跑受影响的那一层:改 .df 跑 run,改 .rcn 跑 render,改 .xwidget / manifest.json 跑 check。

命令速查

上面七步用到的就是这些,外加几个不常用但省事的开关:

三个通用开关与三个环境变量:

• --json:所有命令都能加,输出改成机器可读的 JSON。给脚本或 AI 消费时用它,别去解析给人看的那份彩色输出。
• --lang zh|en:界面语言(numable docs 也跟着换语言)。
• --fixtures <目录>:run 换一套夹具跑。默认读 <包>/.numable/params/,想同时留一套「空数据」夹具验空态时,把它放别处再用这个开关指过去。
• NUMABLE_PROFILE / NUMABLE_LANG / NUMABLE_CHROME:分别免去每次打 --profile、--lang,以及指定渲染用的浏览器可执行文件。

三层验证各管什么

三层不可互替。任何一层绿了都不代表另一层绿。

手机上独有的差异(字形宽度、数字格式化、日期方法)只能装到手机上看。

红线

违反下面任何一条,包不算做完。「检查方式」一栏说明它在哪一层能被抓到。

个人自用 vs 发布

check 有两档,默认 personal:

numable check my-source --profile publish

自用包不必现在就满足发布向的要求;想上架时再跑一次 publish 档,缺什么补什么,流程见 numable docs publish。两者是同一个包、同一个 ULID:自用包发布后,用户手上那个组件长按就能升到已发布的版本,数据保留。

接下来读哪章