From bbebb7072e7b6586251254755f22bf2a53aa19d2 Mon Sep 17 00:00:00 2001
From: HIsheR <shawn1440982358@163.com>
Date: Mon, 26 Oct 2026 15:55:37 +0800
Subject: [PATCH] =?UTF-8?q?iter(g156):=20ua=20tokens=20=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=E6=8C=89=E5=90=8D=E8=BF=87=E6=BB=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

传子串只列匹配令牌并在末尾标注匹配词，--json 同步过滤。
无匹配时报总数并以 1 退出，替代「全表打印后再肉眼找」。
---
 .ua/backlog.json             |  8 ++++++++
 packages/tools/cli/bin/ua.js | 12 +++++++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/.ua/backlog.json b/.ua/backlog.json
index 9d3497f..5e3a44b 100644
--- a/.ua/backlog.json
+++ b/.ua/backlog.json
@@ -1604,6 +1604,14 @@
       "acceptance": "ua index 在 llms.txt 末尾输出配方目录（id / 标题 / 要点数）并指明三种取法；cli 清单的 mcp 导出描述与 MCP_TOOL_NAMES 一致。",
       "notes": "",
       "status": "done"
+    },
+    {
+      "id": "g156",
+      "title": "ua tokens 支持按名字过滤",
+      "motivation": "21 个令牌全表打印后再肉眼找某一个，写样式时反复查多行；缺令牌名拼错也不报错。",
+      "acceptance": "ua tokens <子串> 只列匹配项并在末尾标注匹配词，--json 同步过滤；无匹配时给出总数并以 1 退出。",
+      "notes": "",
+      "status": "open"
     }
   ]
 }
diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js
index 771a9e7..aaed144 100644
--- a/packages/tools/cli/bin/ua.js
+++ b/packages/tools/cli/bin/ua.js
@@ -541,12 +541,18 @@ function cmdTokens(args) {
     console.error('未找到 packages/design/tokens/tokens.json');
     process.exit(1);
   }
+  const keyword = args.find((a) => !a.startsWith('--'))?.toLowerCase(); // 带名字参数时按子串过滤，写样式时不必翻全表
+  const picked = keyword ? list.filter((t) => t.cssVar.toLowerCase().includes(keyword)) : list;
+  if (keyword && !picked.length) {
+    console.error(`no token match: ${keyword}（共 ${list.length} 个令牌，ua tokens 看全表）`);
+    process.exit(1);
+  }
   if (args.includes('--json')) {
-    console.log(JSON.stringify(list, null, 2));
+    console.log(JSON.stringify(picked, null, 2));
     return;
   }
-  for (const t of list) console.log(`${t.cssVar.padEnd(26)} ${t.value}${t.dark && t.dark !== t.value ? '  / 暗色 ' + t.dark : ''}`);
-  console.log(`共 ${list.length} 个令牌`);
+  for (const t of picked) console.log(`${t.cssVar.padEnd(26)} ${t.value}${t.dark && t.dark !== t.value ? '  / 暗色 ' + t.dark : ''}`);
+  console.log(`共 ${picked.length} 个令牌${keyword ? `（匹配 ${keyword}）` : ''}`);
 }
 
 // ---- 内置 stdio MCP server（JSON-RPC 2.0，按行分帧） ----