w_tools_cli 1.1.0
w_tools_cli: ^1.1.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片段 和.w_tools_doctor.yaml(全注释,不改变行为)。 - doctor:扫描项目,检查是否遵守「只依赖子包、业务代码只 import 聚合入口、 暂存层不依赖业务」等约定(R1~R8)。
安装 #
dev_dependencies:
w_tools_cli: ^1.1.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 # 检查约定
# 多目标 / 英文
dart run w_tools_cli:init --targets=agents,claude --lang=en
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_*(聚合入口、暂存层除外) |
| R3 | warn | 硬编码语义色(默认关;需在 .w_tools_doctor.yaml 声明 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 生成(只检查带 <!-- w_tools:begin --> 的 target 文件与 toolkit) |
--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会拦住漂移。