Astryx CLI build 命令组合套件与--skeleton推荐机制一次让 JSON 载荷与人类可读输出对齐的修复【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxastryx build是 Astryx 设计系统 CLI 的页面装配入口给它一句自然语言描述它会返回一份分组好的组合套件composition kit——最接近的页面模板、可覆盖局部的 block、用于补齐缺口的组件以及始终在线的 frame foundation。本文围绕astryxdesign/cli的一次 patch.changeset/build-kit-skeleton-command.md对应 CHANGELOG 中build相关记录展开当最接近的页面模板不是直接命中direct match时套件载荷中每个 page 的command都会被追加--skeleton与渲染器对人类展示的建议保持一致。读完本文你将理解build命令的分组与打分机制、directMatch语义、--skeleton的实现原理以及如何用测试与命令行验证这一行为。先理解astryx buildplaybook 与 composition kit 两种形态build命令有两种运行形态核心逻辑全部收敛在packages/cli/api/build目录下CLI 层只负责解析参数与渲染无查询参数返回 playbook 信号build.help信封data.playbook恒为true由命令行渲染器展开成如何用 Astryx 构建页面的完整工作流文字见 build.mjs 中的printPlaybook。带查询参数执行统一搜索并把结果分组成composition kitbuild.kit信封包含最接近的页面模板、覆盖局部的 block、补齐缺口的领域组件/钩子以及始终在线的 frame foundation见 kit.mjs 的buildKit函数。两种形态的文档化签名与参数说明位于 build.doc.mjsbuild(query?: string, options?: BuildOptions)其中options.cwd指定从哪个目录解析astryxdesign/core与模板options.type可将底层搜索限定到单一领域component | hook | doc | templateoptions.limit控制分组前从搜索拉取的最大结果数默认 60。组合套件的分组结构阈值、覆盖度门槛与恒在线组件buildKit(query, options)的实现kit.mjs先把查询交给统一搜索再按领域与类型过滤、排序、截断最终得到四组推荐 两组恒在线名单分组来源过滤条件数量上限pagesdomain template且kind ! block得分 ≥PAGE_FLOOR50且通过覆盖度门槛≤ 3blocksdomain template且kind block得分 ≥DOMAIN_FLOOR55≤ 5domaindomain component \|\| hook得分 ≥DOMAIN_FLOOR55且排除 frame/foundation 名字≤ 6frame/foundation静态名单每次套件都出现—四个阈值常量在 kit.mjs 中集中定义PAGE_DIRECT 95、PAGE_FLOOR 50、DOMAIN_FLOOR 55、PAGE_COVERAGE 0.5、THIN_KIT 3。值得注意的两个设计细节覆盖度是门槛而非加分项。covers(r)使用getResultCoverage计算多词查询下只有命中概念数占总数 ≥ 50%PAGE_COVERAGE的结果才有资格作为页面推荐。注释里给出了反例——build actionable warning banner曾让login、contact-form、documentation-design三个恰好渲染了 Banner 的模板都拿到 95 分并被当成直接命中覆盖度门槛正是为了防止匹配了三个概念中的一个被包装成匹配了三个。frame/foundation 永不参与关键词匹配。AppShell、TopNav、SideNav、Layout以及VStack、HStack、Grid、Card、Text、Heading、Button等是每个页面都需要的基础件但dashboard这样的想法不会命中Stack。它们被固定放在FRAME与FOUNDATION数组里同时用来在domain组中剔除同名项ALWAYS集合。当pages blocks domain的总数小于THIN_KIT3时套件会携带hint字段明确告诉调用方这是关键词搜索而非语义搜索并给出裸子命令[component --list, template --list]供其自行拼接调用前缀避免把astryx component --list这类写死的前缀交给 pnpm workspace 用户。问题所在人类看到--skeleton程序却读到脚手架命令套件的核心字段之一是directMatchpages.length 0 pages[0].score PAGE_DIRECT即排名第一的页面模板得分达到 95 才算直接命中。而每个 page 条目上的command字段是调用方接下来该运行什么。修复前的缺陷见 kit.mjs 的注释与build.test.mjs中的回归用例描述即使套件内部刚刚判定顶部页面不是直接命中page 条目的command依然是脚手架命令template name。结果就是同一个套件向两类受众给出了相反的建议——对人类RECOMMENDED START区打印template name --skeletonPAGE TEMPLATES标题也写着作为布局参考使用use as a layout reference见 build.mjs对程序JSON 调用方读取command字段拿到的却是脚手架命令。为什么这值得一次专项修复注释点明了后果template name会输出整个页面源码而 Agent 拿到一份它并没有完全要求的完整模板时倾向于照单全收再改编——这正是请求 A 却得到 B 的体面变体的典型来源。--skeleton给出的只是布局骨架不附带完整实现从而避免诱导 Agent 把近似的模板当作精确答案直接落地。修复还强调最需要这项保护的是最不擅长察觉问题的调用方即自动化 Agent 而非人类读者。修复本身复制后追加--skeleton而非原地修改修复位于 kit.mjsconst recommendedPages directMatch ? pages : pages.map(page ({...page, command: ${page.command} --skeleton}));要点有三仅当非直接命中时追加。直接命中时command保持脚手架形式template name调用方应当 scaffold 后改编复制而非修改。这些条目来自search()的返回结果不属于buildKit所有因此用展开运算符创建新对象只改写command字段只追加标志不拼接前缀。载荷中不出现npx、pnpm等调用前缀——命令渲染由 CLI 层的formatCliCommand/getCliInvocation负责见 build.mjs 的文件头注释API 层保持包管理器无关JSON 形状跨环境稳定。这一约束同样体现在hint.commands只给裸子命令的设计上。对应的类型契约同步更新在 build.type.mjspages的每个条目当directMatch为 false 时command携带--skeleton以便推荐阅读布局而非脚手架化它。测试如何锁住这一行为修复的正确性由 build.test.mjs 中的四组断言守护分别覆盖行为正确与边界不被破坏两个维度非直接命中 → 追加--skeleton对应build(notifications)断言directMatch为 false、pages.length 0且每个page 的command都以--skeleton结尾直接命中 → 不追加对应build(contact form)断言directMatch为 true且每个 page 的command都不含--skeleton追加标志不等于拼接前缀对build(notifications)的每个 pagecommand不得以pnpm|npm|yarn|bun|npx开头保证 API 载荷始终包管理器无关恢复命令保持裸子命令build(quantum flux capacitor telemetry)这类无命中查询返回的hint.commands既不以astryx开头也不含任何包管理器前缀留给调用方用自有调用方式渲染。同一份测试文件还覆盖了匹配后被过滤的边界build(blockchain)的hasResults为 true搜索确实有命中但三个分组总和为 0全被分数门槛滤掉此时必须给出hint避免调用方把用词不对误读成这个包没有东西。--skeleton背后template.skeleton leaf 的骨架提取器被推荐的命令最终落到template命令族的--skeleton标志上。template()分发器template.mjs在options.skeleton为 true 时路由到 skeleton.mjs 的templateSkeleton返回template.skeleton信封模板名、描述、组合的组件列表以及紧凑的布局骨架文本。骨架提取extractSkeleton的实现思路值得展开只关注默认导出的return (...)区块最多提取 35 行MAX_LINES超出部分以...截断结构组件保留开闭标签其余组件压成自闭合单行STRUCTURAL白名单包含AppShell、Layout、Card、Section、Grid、SideNav、TopNav、Dialog、FormLayout等 20 个组件VStack/HStack只有携带空间属性时才保留嵌套结构否则整行跳过避免纯排版噪音空间属性按白名单原样拷贝SPATIAL_PROPS包括padding、contentPadding、gap、rowGap、columnGap、columns、hasDivider、variant、density、role、height、width、maxWidth等extractSpatialAttrs用引号/花括号配对解析值保证字符串与对象字面量不被截断槽位与遗留 div 转注释header/content/footer/sideNav等 JSX 槽位参数被提取为/* header: */注释带padding/maxWidth/gap等样式的裸div被转成/* div: padding ..., maxWidth ... */形式的空间注释方便阅读者定位布局意图。组件名提取兼容裸名与历史XDS前缀两种写法XDS?([A-Z]\w)正则template.test.mjs 中的回归用例验证了template(contact-form, {skeleton: true})能同时返回非空组件列表含Card、TextInput与非空骨架体且骨架体不包含XDS前缀、保留columns{{minWidth: 200}}这类关键空间属性。实战验证如何在你的项目里复现这套行为以下命令基于当前仓库实际命令形态可用于本地验证假设调用前缀为npx astryx实际前缀由getCliInvocation依据你的包管理器自动决定# 1. 查看 build 的 playbook无查询 npx astryx build # 2. 用非直接命中的想法生成组合套件 npx astryx build notifications # 3. 用直接命中的想法生成组合套件 npx astryx build contact form # 4. 查看套件的 JSON 载荷观察 command 字段 npx astryx --json build notifications # 5. 按套件建议打印最接近页面的布局骨架 npx astryx template name --skeleton验证要点对notifications这类模糊查询套件中directMatch应为 false每个 page 的command都会携带--skeleton对contact form这类被模板精确覆盖的查询directMatch应为 truecommand保持脚手架形式。--json输出的command永远不应包含npx/pnpm等前缀。template命令的完整标志位template.doc.mjs包括--list列出可用模板、--type page|block按类型过滤、--package pkg按包缩小范围用于消歧义同名模板、--skeleton打印带空间注释的布局骨架、--cdn [path]写出无需构建步骤的 CDN 起始页、-f, --overwrite覆盖已存在文件。总结这次 patch 的本质是一次双受众一致性修复同一个 composition kit人类读者从渲染器散文里读到当作布局参考而 JSON 调用方尤其是 Agent却从command字段读到脚手架化它。通过在非直接命中时给每个 page 的command追加--skeleton套件让程序与人类收到同一条建议也让请求 A 却得到 B 的体面变体这类 Agent 常见失败少了一个触发源。修复遵循的三条纪律——只追加标志不拼接前缀、复制条目而非原地修改、用测试同时锁住追加与不追加两种分支——是理解 Astryx CLI API 层设计包管理器无关、载荷稳定、契约先行的绝佳样例。如果希望继续深入推荐阅读 kit.mjs分组与打分、skeleton.mjs骨架提取、build.test.mjs 与 template.test.mjs行为契约以及 packages/cli/README.md 中关于template.skeleton的条目说明。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考