headless-ui-cli 0.10.0

核心是帮助宿主 AI 根据需求/截图，正确选择、理解、组合与改造 shadcn/Headless 组件，并验证页面效果和交互。默认用于用户指定的独立 React 项目，E9 是可选适配器。

Headless 指组件行为与外观可分离：shadcn 带默认样式且源码可改造，交互控件依托 Radix；自有 Browser、富文本、上传、只读流程图和只读甘特提供默认成品及独立行为 Hook。通常用默认成品并定制外观，深度定制才复用 Hook 组合视图，不重新实现重型引擎。整个清单不是纯无样式库；无界面浏览器验收是另一项验证动作。

输入：需求文档/原型/截图 + 目标目录。调用方 Agent 使用自身模型生成代码；CLI 提供真实源码事实、分阶段指引、组件安装和类型检查，不调用 LLM 或启动其他 Agent。最终项目源码留在目录，提供运行和构建方法；编译、打包、部署由外部软件开发 Agent 完成，不交付 dist 或部署归档。

0.10.0 已移除 WorkBuddy 适配和 generate 入口，包无生产运行依赖；原 generate 调用明确返回迁移错误，guide 只返回指引。0.9.0 的历史行为保留在对应版本。Windows 修订及未测范围见 Windows 审计。

安装到调用方工具目录（公共 npm，固定版本）：

npm install --save-exact [email protected] --registry=https://registry.npmjs.org/
npx --no-install headless-ui-cli --help --json

Agent 首次读取 --help --json 的 tool/commands，了解工具定位、能力、Headless 特点与责任边界；随后从以下入口取得指引，再用自身模型开发页面并按需调用组件命令。guide 也返回 tool，catalog 返回组件使用原则 componentModel：

npx --no-install headless-ui-cli guide --requirements /path/to/requirements/README.md --dir /path/to/app --json

安装、调用顺序和成功/失败结果见 Agent 接入文档。不要求模型/宿主配置；业务和视觉使用调用方自己的浏览器能力。

组件源码、目录、关联、shadcn 文档与固定 CLI 运行包按 CLI 内置配置获取，调用方无需配置组件服务。工具内新增组件及后续维护见 自有组件源。

确定性命令（由调用方 Agent 使用）

新目录可以只有需求文件。CLI 不请求模型、不自建第二套 agent loop；CLI init 提供固定最小模板，宿主安装依赖、选组件并实现应用。

node /path/to/headless-ui-cli/dist/index.js guide --dir /path/to/app --requirements requirements/README.md --json
node /path/to/headless-ui-cli/dist/index.js components --dir /path/to/app --names button,dialog --json
node /path/to/headless-ui-cli/dist/index.js components --dir /path/to/app --source registry --names dialog,select --json
node /path/to/headless-ui-cli/dist/index.js components --dir /path/to/app --add dialog,select --json
node /path/to/headless-ui-cli/dist/index.js check --dir /path/to/app --json
node /path/to/headless-ui-cli/dist/index.js guide --dir /path/to/app --stage verify --json

guide --requirements 可省略，自动发现项目内 requirements/README.md 等入口；显式输入可为工程内外的本地文件/目录，相对路径以 --dir 为基准。工程外材料只读，无需复制；返回真实入口和 baseDirectory，图片/附件按材料位置解析，代码仍只写目标工程。components 返回实际源码、摘要、使用位置和按需实践；缺组件明确返回未安装。check 使用项目 typecheck；可选 build 显式构建静态归档，不属于页面任务默认流程，不上传部署。

AI 使用与改造组件

1. 根据参考拆解布局、行为和业务状态，用 guide 清单发现已有组件。
2. catalog 先返回全量轻量候选，包含功能/来源/完整性；复杂能力用 --related 查询依赖、反向示例/block 与关联方案。宿主基于需求选型，不再以记忆作为名字入口。
3. catalog --resolve <id,id> 批量确定本地/远程。本地直接读源码；缺失先 components --source registry --names <id,id>，判断后 --add 并自动回读。来源快照及安装日志位于 .headless-ui/。真实 API 来自源码和类型，不维护第二份 Props 库。
4. 视觉用 token、variant、局部 className、业务组合及必要结构改造；保留Radix的键盘/焦点/ARIA等协议。不要默认套Card，不把antd属性用于shadcn，不把多选浏览器硬塞进Select。
5. 在真实服务上用headless截图比较与交互断言验证；check/build通过不等于高还原。COMPONENTS.md说明改造与行为证据，ACCEPTANCE.md说明已测/未测。

常规控件和复杂交互优先复用组件；需要业务能力时组合已有组件，避免每页重复实现。布局和业务计算由宿主按需求编写，组件覆盖率不代替效果。业务目录默认发现 src/business、src/components/business、business 和原有 components/business；非约定目录可通过项目 headless-ui.config.json 的 businessDirectories 相对路径数组补充。多个同名导出明确返回歧义，可按具体项目内文件路径查询。

guide/inspect/catalog 保持轻量；components 才按需加载解析器与 CLI。CLI 运行包首次从自有服务器取得，校验 SHA-256 后缓存在 ~/.cache/headless-ui，之后直接使用 Node 运行。React、Radix 等第三方公开 npm 依赖使用淘宝镜像 https://registry.npmmirror.com，项目 scope 私有源保留，这不是整个 npm 生态的离线镜像。

维护与可选 Skill 分发

npm ci
npm test
npm run test:package
npm run pack:skill

同版 Skill 目录为 artifacts/skill/headless-ui-cli，包含 SKILL.md、CLI、指南、组件实践及 BUILD 摘要，无 node_modules，不需要浏览器运行依赖。不自动写用户全局 Skill 配置。调用方也可直接使用 npm 包或工作区 dist/index.js。

任务示例：“使用headless-ui-cli，在当前目录根据requirements/README.md生成独立应用。改造shadcn/Headless组件来满足参考效果，通过headless验证，交付工程源码、验证报告与启动/构建方法，由调用方构建部署。”

可选 E9 与边界

E9 已配置模块自动识别，保留 --ecology/--module 和只写模块的边界。E9检查委托标准预设，发布沿用标准工程，工具不改公共脚手架。独立项目不需要E9配置、私有React或宿主Portal。

本版默认 React/TypeScript；不宣称支持 Vue/纯 HTML 的组件适配。轻型组件复用 shadcn；重型组件优先安装我们维护的成品。table 继续使用 @shadcn/table，实验 @weaver/table 暂停收录。富文本、上传、流程图、甘特图有独立 Headless 入口。调用方负责业务和视觉判断，目录约定不是操作系统沙箱。静态 build 要求输出 index.html；SSR 服务包不能直接当静态包。解压/归档依赖系统 tar；Windows 原生执行尚未验收。

当前契约见 CONTRACTS，0.4 的真实 WorkBuddy 执行属于历史验收；0.5 结果见 0.5 验收，不同版本不互相替代。

PC Browser 系统组件（0.7）

工具内置 @weaver/browser 候选，和 shadcn 组件一起出现在全量目录中。先 catalog --refresh，选型后 catalog --resolve @weaver/browser，本地已有复用，缺失才 components --source registry --names @weaver/browser 和 components --add @weaver/browser。

它是参考 weapp-ui Browser 的系统组合源码，复用 Radix Dialog/Checkbox/RadioGroup/Tabs，提供单选/多选、分类树、列表/表格、搜索/分页、已选区、锁定/禁用、异步状态；不包含 weapp 业务接口。API 与边界见 组件说明，源码维护在 registry/weaver，演示在 examples/browser。不需要把新业务组件加入 Radix。

帮助与正式组件维护源（0.9）

--help / -h 列出所有能力，guide --help / help components 查看单命令输入输出和示例；加 --json 获得结构化帮助，不联网、不启动其他 Agent。

四项新维护源已加入 registry/weaver/catalog.json，说明与代码一同维护：rich-text-editor、file-upload、process-diagram、gantt，均提供默认视图和独立 Headless Hook。流程图和甘特目前只读。实验 Table 源码和历史证据保留，当前新任务使用 shadcn Table。组件源已发布到 weaver-20261013-1，线上 @weaver 清单包含 Browser 与四项新增；已完成真实远程安装、严格类型和本地浏览器验收。