Skip to main content

w_tools_cli 1.4.0 copy "w_tools_cli: ^1.4.0" to clipboard
w_tools_cli: ^1.4.0 copied to clipboard

w_tools 的接入工具:init 生成聚合入口 / 暂存层 / AGENTS 片段,doctor 检查消费方是否遵守接入约定。

w_tools_cli #

w_tools 的接入工具(纯 Dart,不依赖 Flutter):

  • context:输出项目事实(版本、toolkit 导出、暂存层、规则、检查结果), 支持 json / markdown / prompt 三种格式,给 AI 和 CI 读。
  • list / explain:查内置组件目录(list <关键词>、explain <组件名>), 避免凭记忆造组件名。
  • init:把接入约定装进当前项目,生成聚合入口、暂存层 README、AGENTS.md 片段、 lib/app/ui/ 页面规范(AppBars / AppBoxes / AppButtons / AppCard / AppScaffold) 和 .w_tools_doctor.yaml(默认值与内置一致)。init 只生成 AGENTS 摘要,不会复制 w_tools 仓库的 docs/agents/*.md 深度文档。
  • doctor:扫描项目,检查是否遵守「只依赖子包、业务代码只 import 聚合入口、 暂存层不依赖业务」等约定(R1~R8)。

示例 #

命令演示与可复现的最小消费方项目见 example/:

cd packages/cli
bash example/run_demo.sh

安装 #

dev_dependencies:
  w_tools_cli: ^1.4.0
dart run w_tools_cli:init      # 生成到当前项目
dart run w_tools_cli:context   # 看项目事实
dart run w_tools_cli:list 下拉 # 查组件
dart run w_tools_cli:doctor    # 检查约定

# profile 组合
# minimal: core
# ui:      core + ui + toast
# api:     core + api
# full:    core + app + form + ui + api + toast + qr + async(默认)
dart run w_tools_cli:init --profile=ui

# 多目标 / 英文
dart run w_tools_cli:init --targets=agents,claude --lang=en

# 按能力组合生成(默认 full)
dart run w_tools_cli:init --profile=minimal   # core
dart run w_tools_cli:init --profile=ui        # core + ui + toast
dart run w_tools_cli:init --profile=api       # core + api
dart run w_tools_cli:init --profile=full      # 当前默认

# 不生成 lib/app/ui / design_system 规范,也不导出 w_tools_ui
dart run w_tools_cli:init --no-ui

# 不导出 w_tools_async
dart run w_tools_cli:init --no-async

# 不生成 / 不检查 AGENTS 等 AI 指令文件
dart run w_tools_cli:init --no-instructions

--profile 决定基础能力,--ui / --no-ui / --no-qr / --no-async / --with-map 覆盖单项; --no-instructions 优先于 --targets。

Profile 能力:

参数 能力
--profile=minimal core
--profile=ui core + ui + toast
--profile=api core + api
--profile=full core + app + form + ui + api + toast + qr + async

--no-ui / --no-instructions 只停止生成,不删除已有文件。
切换 profile 或 targets 后,当前配置不再生成的旧 UI / 指令文件会在 stale 中提示, 但不会自动删除。
--no-ui 只关闭页面 UI 与 w_tools_ui,不会自动移除 w_tools_toast。

init --targets 支持 agents(AGENTS.md)/ claude(CLAUDE.md)/ cursor(.cursor/rules/w_tools.mdc,新文件会带 Cursor 需要的 frontmatter)/ copilot(.github/copilot-instructions.md); 默认值可以写在 .w_tools_doctor.yaml 的 ai.targets / ai.language 里。 生成的指令里会写入真实项目名(package:<你的包名>/app/w/toolkit.dart)。

通过 dart run 使用;这个包不声明全局可执行文件,避免把 init / doctor 这么泛的名字装进用户 PATH。

init 不会改 pubspec.yaml:它只打印需要加入的依赖片段。

给 AI 的工作流 #

dart run w_tools_cli:context --format=prompt   # 先拿事实(可加 --max-tokens=1500)
dart run w_tools_cli:list <关键词>              # 找现成组件
dart run w_tools_cli:explain <组件名>           # 看用途 / 反例 / import
dart run w_tools_cli:doctor --json             # 写完自检(0 error 才算过)

init 生成的 AGENTS.md 片段已经把这条闭环写进去了。生成物头部带 generated by w_tools_cli x.y.z,doctor 的 R8 会检查它是否过期。

规则 #

id 级别 内容
R1 error dependencies 里出现聚合包 w_tools
R2 error 业务代码直接 import package:w_tools_*(聚合入口、lib/app/ui/、暂存层除外)
R3 warn 业务层硬编码语义色(默认关;需声明 colors.palette;项目 UI / 暂存层豁免)
R4 error 设计系统(lib/app/ui/、暂存层)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 生成(只检查带 <!-- w_tools:begin --> 的 target 文件与 toolkit;UI starter 不检查)

--json 的每条 issue 带可选的 fix(run 执行命令 / edit 改 YAML 字段), AI 可以直接执行;没有 fix 时用 hint:

{"kind": "run",  "command": "dart run w_tools_cli:init --force"}
{"kind": "edit", "file": "pubspec.yaml", "path": "dependencies.w_tools_core", "value": "any"}

--strict 让 warning 也失败;--json / --format=markdown 给 CI / AI 解析; list / explain 也支持 --format=json; --only=R1,R2 只跑指定规则;--include-tests 同时扫 test/ 与 tool/。

dart run w_tools_cli:doctor --print-config   # 打印带注释的默认配置
dart run w_tools_cli:doctor --write-config   # 写到 .w_tools_doctor.yaml
dart run w_tools_cli:doctor --format=markdown # 可直接粘给 AI / PR 评论

设计依据与接入约定见仓库 docs/conventions.md 与 ADR-0002。

开发 #

模板唯一来源是 templates/,目录唯一来源是 catalog/components.yaml:

cd packages/cli
dart run tool/gen_templates.dart         # 生成 lib/src/init/templates.g.dart
dart run tool/gen_catalog.dart           # 生成 lib/src/catalog/catalog.g.dart
dart run tool/gen_templates.dart --check # CI 校验
dart run tool/gen_catalog.dart --check
dart test --coverage=coverage            # 覆盖率
dart run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info --report-on=lib --package=.

改了 CLI 版本号,必须同步 lib/src/common/version.dart 的 cliVersion; test/version_test.dart 会拦住漂移。

0
likes
0
points
4.08k
downloads

Publisher

unverified uploader

Weekly Downloads

w_tools 的接入工具:init 生成聚合入口 / 暂存层 / AGENTS 片段,doctor 检查消费方是否遵守接入约定。

Homepage
Repository (GitHub)
View/report issues

Topics

#dart #tooling #cli

License

unknown (license)

Dependencies

args, path, yaml

More

Packages that depend on w_tools_cli