w_tools_cli 1.7.4
w_tools_cli: ^1.7.4 copied to clipboard
w_tools 的接入工具:init 生成聚合入口 / 暂存层 / AGENTS 片段,doctor 检查消费方是否遵守接入约定。
w_tools_cli #
w_tools 的接入工具(纯 Dart,不依赖 Flutter)。
它解决三类问题:
接入:init 把约定装进项目
检查:doctor 扫出不合规的依赖 / import / 配置
学习:context list explain
5 分钟上手 #
安装到消费方项目:
dev_dependencies:
w_tools_cli: ^1.7.4
dart run w_tools_cli:init # 1. 生成 toolkit / UI 规范 / AGENTS / doctor 配置
dart run w_tools_cli:doctor # 2. 检查是否遵守接入约定
dart run w_tools_cli:list 表单 # 3. 找现成组件
dart run w_tools_cli:context --format=prompt # 4. 给 AI 项目事实
典型结果:
init → 生成 lib/app/w/toolkit.dart、AGENTS.md、.w_tools_doctor.yaml
doctor → 0 error / 0 warning 才算通过
命令怎么选 #
| 场景 | 命令 |
|---|---|
| 第一次接入 | init |
| 接入后检查 / CI | doctor |
| 找现成组件 | list |
| 看某个组件怎么用 | explain |
| 给 AI 项目上下文 | context --format=prompt |
| 只检查不写文件 | init --check |
| 检查模板是否过期 | init --check-drift |
| 升级 CLI 后刷新生成物 | init --force |
命令入口都是:
dart run w_tools_cli:<command> --help
init #
dart run w_tools_cli:init
生成:
lib/app/w/toolkit.dart 本项目能力清单(聚合入口)
.w_tools_doctor.yaml doctor 配置(默认值与内置一致)
AGENTS.md / CLAUDE.md / ... w_tools 指令片段(标记块)
lib/app/ui/ 页面规范(AppBars / AppBoxes / AppButtons / AppCard / AppScaffold)
lib/app/design_system/README.md 暂存层规则
init 不会修改 pubspec.yaml,只打印需要加入的依赖片段。
Profile #
| 参数 | 能力 |
|---|---|
--profile=minimal |
core |
--profile=ui |
core + ui + toast |
--profile=api |
core + api |
--profile=full |
core + app + form + ui + api + toast + qr + async(默认) |
单项覆盖:
dart run w_tools_cli:init --profile=ui
dart run w_tools_cli:init --no-ui
dart run w_tools_cli:init --no-async
dart run w_tools_cli:init --no-form
dart run w_tools_cli:init --no-app
dart run w_tools_cli:init --no-api
dart run w_tools_cli:init --no-toast
dart run w_tools_cli:init --no-qr
dart run w_tools_cli:init --map # 会引入 google_maps_flutter
dart run w_tools_cli:init --no-map # 显式关闭(默认关)
# --with-map 仍可用,等同 --map
Figma 片段 #
dart run w_tools_cli:init --figma
只在 AGENTS 中追加 Figma → Flutter 说明,不会修改 toolkit 或 pubspec。
是否生成按以下优先级:
--figma / --no-figma
> .w_tools_doctor.yaml 的 ai.figma
> pubspec 是否依赖 w_tools_figma
> false
ai.figma:
ai:
figma: auto # auto | true | false
如果 pubspec 已有 w_tools_figma,生成的安装命令沿用该约束;path/git 依赖时
不生成错误的 pub 版本命令。
指令文件目标 #
dart run w_tools_cli:init --targets=agents,claude --lang=en
支持:
agents AGENTS.md
claude CLAUDE.md
cursor .cursor/rules/w_tools.mdc
copilot .github/copilot-instructions.md
默认值可以写在 .w_tools_doctor.yaml 的 ai.targets / ai.language。
--no-instructions 优先于 --targets;--no-ui 只关闭页面 UI 与 w_tools_ui,不会自动移除 w_tools_toast。
切换 profile / targets 后,不再生成的旧文件会在 stale 中提示,但不会自动删除。
检查模式 #
dart run w_tools_cli:init --check # 只报告缺失;内容不同提示但不失败
dart run w_tools_cli:init --check-drift # 模板过期也失败
CI 想追踪模板更新时用 --check-drift。
doctor #
dart run w_tools_cli:doctor
常见格式:
dart run w_tools_cli:doctor --format=markdown # 贴 PR / AI
dart run w_tools_cli:doctor --json # CI
dart run w_tools_cli:doctor --strict # warning 也失败
规则:
| id | 级别 | 内容 |
|---|---|---|
| R1 | error | dependencies 里出现聚合包 w_tools |
| R2 | error | 业务代码直接 import / export package:w_tools_*(聚合入口、lib/app/ui/、暂存层除外) |
| R3 | warn | 业务层硬编码语义色(colors.palette 为空时跳过) |
| R4 | error | 设计系统 import 了 data/ / modules/ / routes/ / services/ |
| R5 | warn | 暂存层文件缺 // STAGED: 标记 |
| R6 | warn | 禁用单位 .h / .r(项目专用,默认关,rules.R6: true 打开) |
| R7 | error | toolkit 的 export 与 pubspec 依赖不一致 |
| R8 | warn | 生成物由旧版 w_tools_cli 生成 |
| R9 | 配置 | 项目禁用 API(banned;默认空) |
doctor 规则是文本级检查:整行注释和行尾
//注释会跳过,但字符串内容仍可能命中。
只跑部分规则:
dart run w_tools_cli:doctor --only=R1,R2,R9
dart run w_tools_cli:doctor --include-tests
无 CLI 时的手动兜底映射 #
消费方 AGENTS 里的 grep 只作为无 CLI 环境兜底,对应关系:
| 手动检查 | CLI | 说明 |
|---|---|---|
| ① design_system / ui 不依赖业务 | R4 | 只覆盖 data/ / modules/ / routes/ / services/;严格 import 白名单是项目特有,不在 CLI |
② 业务代码不直接 import w_tools_* |
R2 | 默认扫 lib/,要覆盖 test/ / tool/ 加 --include-tests |
| ③ pubspec 不依赖聚合包 | R1 | 区分 dependencies、dev_dependencies、dependency_overrides |
④ 图片只走 WImage |
R9 | 用 banned 配置,不新增默认 R10;路径白名单按项目配置 |
不要把这四条 grep 直接搬进 CLI:① 含项目特有 import 例外,④ 的允许路径也因项目而异。
项目禁用 API(R9) #
banned:
- id: no-raw-image
pattern: 'Image\.asset\('
mode: regex
use: 'WImage.asset'
reason: '项目要求统一图片入口'
level: warn
paths: ['lib/app/modules/**']
ignore: ['lib/app/ui/**']
mode 支持 literal / regex,默认 literal。
paths / ignore 支持 * / **。
行级豁免:
// w_tools:ignore R9 reason: design-system fallback
Image.asset('logo.png');
文件级:
// w_tools:ignore-file R9 reason: generated UI
没有 reason: 的豁免不生效。
R9 是文本级检查:整行注释和行尾
//注释会跳过,但字符串仍可能命中; 需要精确排除时用paths/ignore/ inline ignore。
配置 #
dart run w_tools_cli:doctor --print-config # 打印默认配置
dart run w_tools_cli:doctor --write-config # 写入 .w_tools_doctor.yaml
--json 的 issue 带可选 fix:
{"kind": "run", "command": "dart run w_tools_cli:init --force"}
{"kind": "edit", "file": "pubspec.yaml", "path": "dependencies.w_tools_core", "value": "any"}
context / list / explain #
context #
dart run w_tools_cli:context
dart run w_tools_cli:context --format=prompt --max-tokens=1500
dart run w_tools_cli:context --format=json
输出项目事实:依赖、toolkit 导出、暂存层、规则与检查结果。
JSON 顶层包含:
{
"schema": "w_tools.context",
"schemaVersion": 1
}
契约策略:
- 新增字段属于兼容变更,不 bump
schemaVersion。 - 消费方必须忽略未知字段。
- 删除 / 重命名 / 改类型 / 改语义才 bump。
- v1 结构见
schema/context.v1.json。
list #
dart run w_tools_cli:list # 列出全部组件
dart run w_tools_cli:list 下拉 # 按关键词搜索
dart run w_tools_cli:list --format=json
explain #
dart run w_tools_cli:explain WImage
dart run w_tools_cli:explain WFormDropdown
输出用途、反例、import、文档;项目配置了 banned 时会提示禁用项和替代方案。
banned 读取 --root 或当前工作目录的 .w_tools_doctor.yaml。
给 AI 的工作流 #
dart run w_tools_cli:context --format=prompt # 先拿事实
dart run w_tools_cli:list <关键词> # 找组件
dart run w_tools_cli:explain <组件名> # 看用法 / 反例
dart run w_tools_cli:doctor --json # 写完自检
init 生成的 AGENTS.md 已包含这条闭环。生成物头部带
generated by w_tools_cli x.y.z,R8 会检查是否过期。
升级与重新生成 #
CLI 模板会随版本变化。升级后执行:
flutter pub upgrade w_tools_cli
dart run w_tools_cli:init --check-drift
# 有 drift 时再覆盖生成物
dart run w_tools_cli:init --force
dart run w_tools_cli:doctor
注意:
--force 会覆盖生成的 AGENTS / toolkit / UI starter
不会删除当前 profile 不再生成的文件
退出码 #
| 命令 | 0 | 1 | 2 |
|---|---|---|---|
init --check |
没有缺失 / drift | 有缺失或 drift | 参数错误 |
doctor |
无 error(--strict 时也无 warning) |
有失败 | 参数 / 项目错误 |
list / explain |
找到 | 未找到 | 参数错误 |
context |
成功 | — | 参数 / 项目错误 |
示例 #
命令演示与可复现的最小消费方项目见 example/:
cd packages/cli
bash example/run_demo.sh
维护者 #
模板唯一来源是 templates/,目录唯一来源是 catalog/components.yaml:
cd packages/cli
dart run tool/gen_templates.dart
dart run tool/gen_catalog.dart
dart run tool/gen_templates.dart --check
dart run tool/gen_catalog.dart --check
dart test
改 CLI 版本号时同步
lib/src/common/version.dart的cliVersion;test/version_test.dart会拦住漂移。
设计依据与接入约定见仓库 docs/conventions.md
与 ADR-0002。