w_tools_figma 1.0.0
w_tools_figma: ^1.0.0 copied to clipboard
只读的 Figma 取数与规格导出 CLI(读取本地缓存,不额外消耗额度)。
1.0.0 #
Added #
tokens --json --map的colors[]增加name(未命中映射时为null)。cache stats --files:逐文件列出大小、legacy/nodes/index分类和indexed状态。cache clean --legacy:只删旧file-*缓存,保留有效的nodes-*。cache clean --file=<path>:只删显式点名的缓存文件(修复 Windows 路径判断)。spec --with-id:markdown 规格表增加 nodeId 列(默认不加,保持表格宽度)。spec --with-layout:markdown 规格表增加布局列(layoutMode / itemSpacing / padding / 轴对齐),并在画板摘要后显示根节点布局。diff的layout比较加入layoutMode/ 主轴、交叉轴对齐。FetchResult.missingNodeIds:fetch nodes部分节点返回 null 时列出缺失 id;fetch/1JSON 也输出该数组。FetchCommand.imageUrls:直接返回nodeId → 签名 URL,不写缓存。TokensCommand.run增加可选includeMarkdown;CLI 增加--skip-markdown(tokens)与--skip-name-prefix(spec)。
Breaking #
fetch nodes显式传入--scale(包括--scale=2)一律 exit 2;之前只拒绝非默认值。fetch nodes全部节点返回 null 时 exit 1 且不写缓存;部分 null 会过滤后写入并报告缺失。spec --node-only必须配合--json,否则 exit 2;文本模式不再静默忽略该开关。cache clean无论是否--all都必须带--yes;--yes不再要求同时给--all。spec --json固定返回w_tools_figma.specs/1(items数组);删除w_tools_figma.spec/1与schema/spec.v1.json。tokens --json删除source(只保留sources);markdown变可选(--skip-markdown),TokensReport.markdown改为String?(TokensReport.new同步)。FigmaSpecRenderer.new的skipNamePrefixes默认值由内置 iOS 名单改为空; 需要跳过时用--skip-name-prefix。me/usage不再接受--root(这两个命令不用项目缓存)。- 参数解析改为每命令独立 parser:不支持的选项现在报“未知选项:--x” (以前是“不支持的选项:--x”),退出码仍是 2。
- 删除
CacheStore.homeOverride静态测试钩子:测试改用CacheStore(root, home: ...)构造注入;runSpec/runUsage/runDiff接受可选store。 diff的position改为相对父节点坐标;fills/strokes/effects的before/after改为结构 key(区分图片 / 渐变的具体内容),不再只是IMG/GRAD。- 删除
InitCommand/InitResult/UrlCommand/FigmaUrlTarget/UsageCommand/UsageResult: 这些薄包装已并入init/url/usageCLI handler。 - 删除
FetchCommand.file/FetchCommand.images:fetch file子命令与图片缓存已移除; 节点树用FetchCommand.nodes/fetch nodes,图片地址用FetchCommand.imageUrls。 - 删除
FetchCommand.ignoreBudget/DiffCommand.ignoreBudget字段与FetchCommand.new/DiffCommand.new的对应参数:本地额度护栏整块删除,额度由 Figma 服务端限制。 - 删除本地额度护栏:不再在额度用尽时 exit 3;
--ignore-budget命令选项删除。 收到 Figma 429 仍返回退出码 3。 - 删除
CacheStore.migrateLegacy/CacheStore.legacyDir/CacheStore.legacyTokenFile: CLI 不再自动迁移旧路径,1.0.0 把库级迁移也删掉。 - 删除
CacheStore.usageCountThisMonth:用CacheStore.usageEntries()自行统计。 - 删除
InitResult.gitignoreAdded(InitResult.new同步变化):init不再改.gitignore。 fetch images不再缓存:直接输出id<TAB>url;--json改为w_tools_figma.images/1(fileKey/tierCalls/urls,不再有cacheFile/fromCache)。fetch images不接受--depth/--refresh/--check-stale;fetch nodes不接受--scale(以前会被静默忽略)。- 移除
fetch file子命令:它写出的file-*.json没有任何命令会读 (spec --file=<file 缓存>也会报“不是 nodes 缓存”)。需要节点树时用fetch nodes。 url只接受 Figma 链接:不再把1862:9222之类的裸 nodeId 或任意含:的字符串 (如https://example.com/a:b、C:/tmp/x)当 nodeId。url/get不再接受--root(0.13.1 已标remove-in: 0.14.0):这两个命令本来就不用它, 现在会按“不支持的选项”返回退出码 2。- 移除
budget命令:改用usage --set=<n>;--json仍是w_tools_figma.usage/1,w_tools_figma.budget/1schema 删除。 - CLI 不再自动迁移旧
.figma-cache/.figma-token(0.8.0 的一次性迁移结束)。 init不再改.gitignore。
Changed #
CacheStore的路径 / 用量拆成内部CachePaths/UsageLog(公开 API 不变)。DiffCommand复用FetchCommand的取数 / 缓存 / 日志,不再单独实现_fetchFresh。help的命令签名 / 选项由parserFor生成,不再在usageText/commandUsage手写两份。- 删除
docs_contract_test/docs_drift_test的 README 字面量断言(事实由scripts/check_docs.sh覆盖)。 - 颜色语义映射的 key 归一化收敛到
colorKey。 - stdout / stderr 的 broken pipe 改为
stdout.done/stderr.done兜底。 CacheStore.homeOverride删除;runSpec/runUsage/runDiff支持传入store。init/url/usage命令逻辑并入 CLI handler;spec/tokens/frames/cache也去掉 command 包装,纯逻辑直接在 handler 里。- 参数层改为
parserFor(command)+CommandArgs,删除 24 字段CliOptions与全局 parser。 - 参数校验收进
parseCommand,删除内部rejectUnsupported/seen/seenText。 frames使用_nodes-index.json的 FRAME 摘要(version 5,旧索引自动重建);spec/tokens只读索引,不再写盘。usage支持--set=<n>设置月度预算(只改limit,保留其它字段)。fetch --check-stale/diff --if-stale共用同一份/meta读取;meta 文件统一写version/lastTouchedAt/checkedAt。- spec 规格表不再静默截断名称 / 文本 / 富文本 runs。
tokens --json的markdown只在需要时输出;--skip-markdown可只取结构化数组。_budget.json的limit只用于usage的提示(超 80% 打警告),不再拦截请求; 真正的额度限制由 Figma 服务端 429 决定。init --force不再覆盖真实 token:已存在非模板 token 时返回退出码 1 并保留原文件;--force只重建模板。init不再往_budget.json写从不读取的month字段。
0.13.3 #
Fixed #
fetch nodes/fetch images的 ids 去重后按字符串排序:缓存 key 与请求顺序无关,2:3,1:2与1:2,2:3不再产生两份缓存、重复消耗 Tier 1。
Changed #
--refresh文档改为「跳过缓存读取并重拉;成功后才覆盖,失败保留旧缓存」,与实现一致。fetch --check-stale命中缓存时输出cache hit (checked /meta),明确仍访问了 Tier 3。spec/tokens找不到缓存节点时,错误提示补fetch nodes <fileKey> <nodeId>和url <链接> --json的下一步。
0.13.2 #
Fixed #
spec/tokens同 id 命中多份 nodes 缓存时优先未--depth裁剪的完整树; 只剩裁剪缓存时在 stderr 提示子节点可能缺失(此前会静默输出空表 / 缺 token)。
0.13.1 #
Deprecated #
url --root/get --root标弃用:这两个命令本来就不用--root,现在使用会在 stderr 提示,--help已标注(remove-in: 0.14.0)。行为不变,仍接受该参数。
0.13.0 #
Breaking #
- 删除
UsageSummary(0.12.0 的兼容别名)。改用UsageResult:类型成员不变, 按 API 快照这是删除UsageSummary.new/UsageSummary.month/UsageSummary.used/UsageSummary.limit/UsageSummary.recent/UsageSummary.remaining/UsageSummary.isNearLimit。 - 删除
FigmaSpecRenderer.renderMarkdown:它只是renderMarkdownFromRoot的转发,改用后者。 按 API 快照这是删除FigmaSpecRenderer.renderMarkdown。 - 删除
spec --no-markdown旗标:改用--node-only(语义完全一致,只影响--json)。
Changed #
- 版本 0.12.0 → 0.13.0(0.x 预发布语义,minor 可破坏)。JSON 契约与其它命令行为不变。
0.12.0 #
Changed #
tokens --json增加结构化数组colors/texts/radii/spacings(含出现次数与示例), 脚本 / AI 不必再解析markdown;counts与markdown保留,v1 schema 只增字段。url --json/me --json补schema字段(w_tools_figma.url/1/w_tools_figma.me/1), 与其它--json输出一致;me保留/v1/me的原始字段,不做删减。frames复用_nodes-index.json里的 FRAME 摘要,不再每次解析全部缓存;spec --node-only不再先渲染一遍 markdown。缓存文件名格式不变。frames排序在同名画板时按 id 兜底,脚本拿到的顺序稳定。- 取值型选项支持空格写法(
--depth 3/--root /tmp/x),与--depth=3等价; 以前只有--set 20是特例。 - 参数解析改用
package:args(新增args: ^2.6.0依赖):flag / 选项语义、中文报错与退出码不变, 手写分派链换成声明式配置。唯一可见差异是边界报错文案:--node-depth -1现在报 "未知选项:-1"(以前报"需要非负整数",退出码都是 2)。
Breaking #
UsageSummary重命名为UsageResult。按 API 快照这是"删旧名 + 加新名":UsageSummary.month/UsageSummary.used/UsageSummary.limit/UsageSummary.recent/UsageSummary.remaining/UsageSummary.isNearLimit都迁到UsageResult.*。 旧名保留为@Deprecated的typedef(remove-in: 0.13.0),源码兼容, 但显式写UsageSummary类型的代码会收到弃用提示。- 构造器与返回类型同步改名:
UsageSummary.new→UsageResult.new,UsageCommand.run的返回类型从UsageSummary变成UsageResult(签名行为不变)。
Deprecated #
FigmaSpecRenderer.renderMarkdown标废弃,改用renderMarkdownFromRoot(remove-in: 0.13.0)。spec --no-markdown标弃用,改用--node-only(remove-in: 0.13.0);行为不变, 使用时 stderr 提示一行,--help已标注。
Fixed #
diff/diff --if-stale不再写死节点缓存的文件名:fetch nodes --depth=<n>或批量 ids 产生的缓存也能当基线(之前会误报"没有变化",并照扣 1 次 Tier 1)。没有旧缓存时提示 "首次 diff",基线来自--depth时给警告;--json输出不变。spec/tokens读到损坏的 nodes 缓存(如--file=指向被截断的缓存)时返回退出码 1 并提示清理 / 重拉,不再落到"参数错误"(退出码 2)。budget --set改为读-改-写,不再抹掉_budget.json里的其它字段(存量month/used)。- 不带
--file时,损坏的 nodes 缓存现在报"解析失败"并给出文件路径 +cache clean建议, 不再只报"找不到节点";frames走索引跳过坏文件时也会在 stderr 提示。 - 多余的位置参数(
spec 1:2 9:9、url a b、fetch nodes K 1:2 extra等)返回退出码 2, 不再静默忽略多出来的参数。 spec规格表的描边列不再出现 Python 字面量:缺strokeWeight时省略宽度,不打印None px。- 顶层
--help与help <command>合并到同一份来源,help fetch不再漏掉fetch nodes --depth。 help init点明这是 Figma 取数的 init,与w_tools_cli的 init(生成 AGENTS / doctor 配置)不是一回事。
0.11.5 #
Fixed #
--help/ 契约文案指向packages/figma/README.md,不再引用已删除的docs/figma-cli.md;相关缓存 / fetch 注释同步。
0.11.4 #
0.10.0 #
新增 #
fetch nodes --depth=<n>:限制节点树层数。深页面(如整页 27 个容器)原本一次拉 129 MB, 现在可以只拉需要的层;不同 depth 用不同缓存文件,互不覆盖。不传--depth行为不变。
0.9.0 #
新增 #
figma cache stats:当前项目缓存目录 / 文件数 / 大小(--json给脚本)。figma cache clean [--all]:清理当前项目缓存;--all清所有项目缓存(保留账号级用量/预算)。- Windows 路径:缓存用
%LOCALAPPDATA%\w_tools\figma、令牌用%APPDATA%\w_tools\figma-token, 环境变量缺失时回落到~/.cache/~/.config。
0.8.0 #
Changed(破坏性:路径) #
- 缓存 / 令牌 / 额度记录移出项目仓库:
- 缓存:
~/.cache/w_tools/figma/<项目标识>/(原<project>/.figma-cache/) - 令牌:
~/.config/w_tools/figma-token(原<project>/.figma-token,权限 600) - 额度/预算:
~/.cache/w_tools/figma/_usage.log/_budget.json(按账号,跨项目共用)
- 缓存:
- 旧路径首次运行时自动迁移(缓存移动、令牌移动),之后旧文件删除。
init不再往.gitignore加.figma-cache//.figma-token(新路径在仓库外); 只有老项目还留着旧文件时才补,防止误提交。spec/tokens/frames的缓存定位改用项目缓存目录(不再硬编码.figma-cache)。
Changelog #
0.11.0 #
0.9.2 #
Fixed #
- 新增
cache.v1.jsonschema。 tokens --json与--out改为互斥。cache stats不再接受--all/--yes;cache clean --yes必须搭配--all。- 文档移除过时的 usage
seat字段。
0.7.0 #
Fixed #
version从包版本读取,不再写死 0.1.0。fetch --refresh请求失败时保留旧缓存。diff遵守--no-log。tokens跳过隐藏节点及其子树。- 命令级选项校验:spec 不再静默接受 tokens/fetch 专属参数。
0.6.0 #
Changed #
spec/tokens默认扫描所有缓存,选择包含目标 nodeId 的文件;不再只取最大文件。- 找不到节点时给出候选缓存文件。
- 新增
.figma-cache/_nodes-index.json缓存索引。 spec a,b/tokens a,b支持跨缓存。tokens --json增加sources数组。
0.5.0 #
Added #
spec输出 strokeAlign、节点 opacity、阴影 spread。tokens --map语义名合并进颜色主表;frames人类输出显示 page 列。
0.4.0 #
Added #
frames --all/--name/--page/--verbose;默认只列顶层 FRAME,cacheFile 改为相对路径。spec a,b,c多画板 Markdown;JSON 使用w_tools_figma.specs/1。tokens --map缺少colors:时明确报错。
0.3.0 #
0.2.0 #
Added #
url --json。spec --json --node-depth=<n>,限制原始节点层级。get下载改为临时文件 + rename,并给 body 读取加超时。
0.1.0 #
- 初始内部版本:
init/fetch/spec/tokens/url/diff/usage/budget。 - 本地缓存、用量日志、预算、Tier 3 stale 检查与 token 保护。
get下载图片地址;me校验 token。- CLI 拆分、单命令帮助、AI 使用说明与 JSON schema。