sky-ui-kit 0.1.11 → 0.1.12

package/README.md

@@ -1,8 +1,8 @@
 # sky-ui-kit 组件与样式库
 
-## AI 接入入口：先选择使用方式
+## AI 接入入口：先询问用户
 
-当用户要求引入 sky-ui-kit 时，先读取当前安装包的 llms.txt 和 [原生 HTML 接入与迁移](docs/HTML-INTEGRATION.md)，检查项目和真实 exports。原生 HTML 路线统一库支持的控件样式，保留原 DOM、事件和表单行为，无需 Vue。仅在用户明确需要真实 Vue 组件时，才选择 Vue 直接接入或局部挂载。目标不明确时询问；接入后合并项目 AGENTS.md 规则，按实际视觉状态和业务行为验收，不能只以安装成功或 CSS 已加载作为完成依据。
+当用户要求引入 sky-ui-kit 时，必须先读取[引导式接入流程](docs/START-HERE.md)，先询问用户接入 HTML/JavaScript 还是 Vue，再询问页面范围及接入目标，等待回答后配置。不得仅根据项目文件猜测路线；用户在当前对话已经明确的答案不重复询问。HTML 换肤保留原 DOM、业务事件和表单，不要求 Vue。按所选路线读取后续指南并合并项目 AGENTS.md；不能以安装成功或 CSS 已加载代替视觉及行为验收。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -91,7 +91,7 @@ npm pack --dry-run
 
 ## 当前发布状态与维护发布流程
 
-当前发布版本为 0.1.11，package.json 未设置 private 限制。HTML 按需样式和数字增强入口从 0.1.10 提供；0.1.11 包含相对链接修复、透明地图覆盖层及旧页面迁移文档和示例。已安装的 0.1.10 需升级后获得修订。
+当前发布版本为 0.1.12，package.json 未设置 private 限制。HTML 按需样式和数字增强入口从 0.1.10 提供；0.1.12 增加先询问 HTML/Vue 的引导式接入流程；0.1.11 包含相对链接修复、透明地图覆盖层及旧页面迁移文档和示例。已安装的 0.1.10 需升级后获得修订。
 
 消费项目无需执行库构建或发布操作。维护者仅在明确获得发布授权后，更新版本、运行 npm run docs:ai、类型检查和构建，核对包内文件后再发布。prepack 会生成文档并构建，不应把它当成纯检查命令。早期未发布状态见 [开发历史归档](docs/RELEASE-HISTORY.md)。
 

package/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "sky-ui-kit",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "elementPlusVersion": "2.14.7",
   "setup": {
     "cssOnce": [

package/docs/AI-CHANGELOG.md

@@ -527,3 +527,7 @@ HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue
 ## 0.1.11 发布内容
 
 修正 AI 指南及合并文档相对链接，更新 README 当前发布状态并归档历史说明。原生 HTML 路线明确保留 DOM/事件/表单且无需 Vue；新增透明地图覆盖层、独立浮层主题、旧皮肤移除及前后迁移示例。发布检查包括生成文档、相对链接/包内路径、类型和库构建；未进行浏览器视觉或真实地图验收。
+
+## 0.1.12 引导式接入
+
+新增唯一 START-HERE.md 入口，要求先询问 HTML/JavaScript 或 Vue 并等待用户回答，再确认目标与范围；明确回答不重复问，不确定时只读检查后请用户确认。README、llms 生成源、AI/HTML/迁移/主题/按需指南及网站快速开始共用此规则。HTML 保留已有交互，Vue 为用户明确选择的路线。包不会自行弹出问答，需 AI 阅读文档后执行。

package/docs/AI-GUIDE.md

@@ -1,8 +1,8 @@
 # sky-ui-kit：AI 使用指南
 
-## AI 接入入口：先选择使用方式
+## AI 接入入口：先询问用户
 
-当用户要求引入 sky-ui-kit 时，先读取当前安装包的 llms.txt 和 [原生 HTML 接入与迁移](HTML-INTEGRATION.md)，检查项目和真实 exports。原生 HTML 路线统一库支持的控件样式，保留原 DOM、事件和表单行为，无需 Vue。仅在用户明确需要真实 Vue 组件时，才选择 Vue 直接接入或局部挂载。目标不明确时询问；接入后合并项目 AGENTS.md 规则，按实际视觉状态和业务行为验收，不能只以安装成功或 CSS 已加载作为完成依据。
+当用户要求引入 sky-ui-kit 时，必须先读取[引导式接入流程](START-HERE.md)，先询问用户接入 HTML/JavaScript 还是 Vue，再询问页面范围及接入目标，等待回答后配置。不得仅根据项目文件猜测路线；用户在当前对话已经明确的答案不重复询问。HTML 换肤保留原 DOM、业务事件和表单，不要求 Vue。按所选路线读取后续指南并合并项目 AGENTS.md；不能以安装成功或 CSS 已加载代替视觉及行为验收。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -319,23 +319,13 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 ### 快速开始：团队 AI 读取提示
 
 ```text
-请先读取 node_modules/sky-ui-kit/llms.txt，确认当前项目目标：
-- 原生 HTML：先读 docs/HTML-INTEGRATION.md，保留现有 DOM、业务事件和表单，仅接入支持的控件样式；不要求 Vue。
-- 地图悬浮面板：透明覆盖层保留布局，主题放在实际面板及独立浮层；清理旧控件皮肤并按状态验收。
-- 明确需要真实 Vue 组件时，才按以下 Vue 索引读取：
-- components.json：当前已安装版本的公开组件与 API 清单
-- docs/AI-GUIDE.md：使用规则和完整示例
-- docs/AI-CHANGELOG.md：模块变更及接入影响
-- docs/COMPONENT-API.md：属性、事件、插槽与类型
-- docs/CSS-THEME.md：主题变量、样式隔离与浮层限制
-- docs/INTEGRATION.md：原项目替换和业务接线
-- docs/COMPONENT-USAGE.md：原项目实际使用的组件与调用位置
-- docs/ADAPTATION.md：逐模块替换、Vite 图标配置、主题及业务适配方案
-
-请依据当前已安装包的版本与文档生成代码，不要虚构组件名称或 API。
-CSS 在当前项目公共入口只引入一次（HTML 可使用 link；Vue 使用 main.ts）。
-不能只以安装成功或 CSS 已加载作为视觉接入完成依据；按默认/悬停/聚焦/禁用/选中和原业务行为核对。
-业务请求、路由、权限由应用接入。
+请读取 node_modules/sky-ui-kit/llms.txt 和 docs/START-HERE.md。
+请先问我这次接入 HTML/JavaScript 还是 Vue，等待我的回答，不要根据项目文件直接猜测。
+然后按我的选择询问页面范围和目标：HTML 保留现有 DOM/事件/表单，仅统一支持的控件样式；
+Vue 询问是使用真实组件还是仅给原生控件换肤。已经明确提供的信息不重复询问。
+我选择“不确定”时再检查项目并请我确认。回答前只做文档读取和只读检查，不执行路线相关配置。
+按所选路线查阅包内指南及真实 exports，保留已有项目规则并合并到 AGENTS.md。
+完成后报告状态外观、原有业务行为的验证结果与剩余限制，不把安装成功视为接入完成。
 ```
 
 ### 图标安装：内置与自有资源

package/docs/CSS-THEME.md

@@ -1,4 +1,6 @@
 # CSS 变量主题与样式隔离
+
+接入前必须先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 MapPageLayout 使用 --map-layout-layer-content/panel/legend/toolbar/focus/hover 统一区域层级。与原平台一致：content=1、panel=2、legend=3、toolbar=4、focus=5、hover=6，时间轴和右栏同样参与；hover 高于 focus；content 内部即使使用较大 z-index 也不跨越区域堆叠上下文。图例和底部外层允许内容溢出，避免浮层被父区域裁剪；内部滚动由业务组件负责。
 

package/docs/HTML-INTEGRATION.md

@@ -1,5 +1,9 @@
 # 原生 HTML 样式接入与旧页面迁移
 
+## 开始前先完成接入问答
+
+先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案再配置。本文是用户选择原生控件换肤后的实施指南，不用于 AI 自行选择技术路线。
+
 ## 目标、版本与路线
 
 本路线适用于已有 HTML/JavaScript 页面、服务端模板以及 Vue 页面中的原生元素：统一库支持的控件表面样式，保留原 DOM、id/name/data 属性、监听器、表单提交和业务行为。不要求迁移 Vue，也不因页面包含查询、校验、弹窗等交互而切换技术栈。
@@ -104,7 +108,7 @@ data-sky-native="off" 使节点及其后代退出控件皮肤；内层 sky-html
 
 合并以下规则并保留原有内容；文档路径相对安装包根目录：
 
-> 本项目采用 sky-ui-kit 原生 HTML 样式路线。先读当前安装包 llms.txt、docs/HTML-INTEGRATION.md、docs/HTML-FORM-CATALOG.md 并核对 exports。保留原 DOM、监听器、表单与地图行为；使用受支持的库控件皮肤，删除冲突的旧默认及状态皮肤声明，保留布局。透明地图覆盖层不得因主题变为实底；浮层主题边界明确设置。不得通过叠加仿写皮肤补丁实现一致性。只有明确需要真实 Vue 组件才选择可选 Vue 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
+> 本项目经用户确认采用 sky-ui-kit 原生 HTML 样式路线，接入范围按本项目记录。后续新增接入先按 docs/START-HERE.md 确认未明确的路线及范围，不从项目结构自行猜测。先读当前安装包 llms.txt、docs/HTML-INTEGRATION.md、docs/HTML-FORM-CATALOG.md 并核对 exports。保留原 DOM、监听器、表单与地图行为；使用受支持的库控件皮肤，删除冲突的旧默认及状态皮肤声明，保留布局。透明地图覆盖层不得因主题变为实底；浮层主题边界明确设置。不得通过叠加仿写皮肤补丁实现一致性。只有明确需要真实 Vue 组件才选择可选 Vue 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
 
 ## 验收：视觉和业务均通过才完成
 

package/docs/INTEGRATION.md

@@ -1,4 +1,6 @@
 # 主题接入规则更新
+
+接入前必须先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 ## 新布局接入（源码尚未发布）
 

package/docs/ON-DEMAND.md

@@ -1,4 +1,6 @@
 # 按需引入
+
+接入前必须先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 下一次发布后支持独立组件路径：
 

package/docs/START-HERE.md

@@ -0,0 +1,55 @@
+# 引导式接入：先问用户，再配置
+
+这是 README、llms.txt 和各接入指南共用的唯一流程入口。规则从 0.1.12 提供。安装包不会自动向用户弹出问答，也不会自动进入所有 AI 上下文；AI 阅读此入口后应主动执行下面的问答。
+
+## 第一步：确认用户使用 HTML 还是 Vue
+
+当用户说“帮我引入 sky-ui-kit”或安装后要求接入时，先问：
+
+> 这次要接入的是哪一种页面？
+> 1. 原生 HTML / JavaScript 页面
+> 2. Vue 3 页面
+> 3. 我不确定，请帮我检查后说明
+
+等待用户回答，再执行路线相关的文件修改、样式加载或框架依赖安装。不要根据 package.json、扩展名或当前目录擅自替用户选择。可以先阅读包内文档、核对已安装版本和只读检查项目。
+用户在本次对话已明确回答 HTML/Vue 时，直接采用该答案，不重复询问；该答案来自用户，不是 AI 猜测。用户选择“不确定”时才检查项目，说明发现并请用户确认接入的具体页面类型；混合项目需确认目标页面。
+
+## 第二步：按答案询问接入目标
+
+HTML 用户：
+
+> 你希望在哪些地方使用统一样式？
+> 1. 先改一个现有页面或面板，保留原来的操作逻辑
+> 2. 整个现有站点换肤，保留原来的操作逻辑
+> 3. 创建一个新的原生 HTML 示例页面
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+HTML 的查询、表单校验、分页、弹窗等现有交互继续使用原业务 JS，不把“需要交互”解释为“必须迁移 Vue”。只有用户主动要求真实 Vue 组件能力时，才说明可选局部挂载及成本，并等待其选择。
+
+Vue 用户：
+
+> 你希望怎样使用这个包？
+> 1. 使用库实际导出的 Vue 组件开发或替换页面
+> 2. 仅给现有原生 HTML 控件统一样式，保留现有逻辑
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+答案已明确时不重复问；缺失答案不能通过等待超时自动补成默认选择。用户暂未回答时只做不依赖答案的读取工作。
+
+## 第三步：实施所选路线
+
+| 用户选择 | 阅读资料 | 实施要求 |
+|---|---|---|
+| HTML 或 Vue 中原生元素换肤 | [HTML 迁移](HTML-INTEGRATION.md)、[控件验收](HTML-FORM-CATALOG.md) | 保留 DOM/id/name/监听器/表单，按需 CSS，删除冲突旧皮肤、保留布局 |
+| Vue 真实组件 | [AI 指南](AI-GUIDE.md)、[真实出口](../components.json)、[API](COMPONENT-API.md)、[主题](CSS-THEME.md) | 核对 Vue/peerDependencies，按实际导出使用组件 |
+
+记录用户确认的页面、路线与范围，简要说明将引入的资源，再实施；不额外要求用户确认每个常规修改。遇到地图透明覆盖层、浮层、旧 CSS 冲突时按 HTML 指南处理，不改成不透明整页工作区，也不通过仿写控件皮肤覆盖。
+需要本地源码路径才能完成的指引应作为文档缺口报告；消费者只依赖当前安装包。
+
+## 第四步：记录项目规则并逐状态验收
+
+将用户选择、接入范围、包内入口、主题位置及验收规则合并到消费项目 AGENTS.md，保留已有规则，不重复追加。不自动创建消费项目不存在的 Vue 依赖或迁移技术栈。
+核对默认、悬停、聚焦、错误、只读、禁用、选中及浮层，检查查询/提交/重置/地图操作等原行为。区分已做的静态检查和用户/浏览器实际验证，列出系统 select/日期等浏览器差异；安装成功或 CSS 已加载不等于完成视觉接入。
+
+## 新聊天测试
+
+用户只说“帮我引入 sky-ui-kit”。期望 AI 先询问 HTML/Vue，等待回答；随后按所选路线询问范围并执行。不得直接注册 Vue、套上全页背景或把页面改成库组件。已明确的答案不再重复询问。

package/llms-full.txt

@@ -1,6 +1,10 @@
 # sky-ui-kit
 
-> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.11. AI tools must explicitly load these files.
+> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.12. AI tools must explicitly load these files.
+
+## Mandatory onboarding
+
+Read [Start here](docs/START-HERE.md). Ask the user HTML/JavaScript or Vue FIRST and wait for their answer before route-specific edits or dependency configuration. Then ask scope and intended usage. Do not infer the route from project files. Reuse answers explicitly provided by the user; inspect only when they choose unsure, then ask them to confirm. HTML keeps existing DOM/events/forms and does not require Vue.
 
 ## Documentation
 
@@ -25,13 +29,13 @@
 
 ## Setup
 
-Native HTML: read docs/HTML-INTEGRATION.md first, retain DOM/events/forms, load supported html/*.css once, preserve transparent map overlays and remove conflicting legacy control skins. Vue is optional only when real Vue components are requested. Vue component route: import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts, and check components.json before using exports. Verify visual states and existing behavior; installing or loading CSS alone is not completion.
+After the required user Q&A in docs/START-HERE.md, native HTML: read docs/HTML-INTEGRATION.md, retain DOM/events/forms, load supported html/*.css once, preserve transparent map overlays and remove conflicting legacy control skins. Vue is optional only when real Vue components are requested. Vue component route: import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts, and check components.json before using exports. Verify visual states and existing behavior; installing or loading CSS alone is not completion.
 
 # sky-ui-kit：AI 使用指南
 
-## AI 接入入口：先选择使用方式
+## AI 接入入口：先询问用户
 
-当用户要求引入 sky-ui-kit 时，先读取当前安装包的 llms.txt 和 [原生 HTML 接入与迁移](docs/HTML-INTEGRATION.md)，检查项目和真实 exports。原生 HTML 路线统一库支持的控件样式，保留原 DOM、事件和表单行为，无需 Vue。仅在用户明确需要真实 Vue 组件时，才选择 Vue 直接接入或局部挂载。目标不明确时询问；接入后合并项目 AGENTS.md 规则，按实际视觉状态和业务行为验收，不能只以安装成功或 CSS 已加载作为完成依据。
+当用户要求引入 sky-ui-kit 时，必须先读取[引导式接入流程](docs/START-HERE.md)，先询问用户接入 HTML/JavaScript 还是 Vue，再询问页面范围及接入目标，等待回答后配置。不得仅根据项目文件猜测路线；用户在当前对话已经明确的答案不重复询问。HTML 换肤保留原 DOM、业务事件和表单，不要求 Vue。按所选路线读取后续指南并合并项目 AGENTS.md；不能以安装成功或 CSS 已加载代替视觉及行为验收。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -348,23 +352,13 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 ### 快速开始：团队 AI 读取提示
 
 ```text
-请先读取 node_modules/sky-ui-kit/llms.txt，确认当前项目目标：
-- 原生 HTML：先读 docs/HTML-INTEGRATION.md，保留现有 DOM、业务事件和表单，仅接入支持的控件样式；不要求 Vue。
-- 地图悬浮面板：透明覆盖层保留布局，主题放在实际面板及独立浮层；清理旧控件皮肤并按状态验收。
-- 明确需要真实 Vue 组件时，才按以下 Vue 索引读取：
-- components.json：当前已安装版本的公开组件与 API 清单
-- docs/AI-GUIDE.md：使用规则和完整示例
-- docs/AI-CHANGELOG.md：模块变更及接入影响
-- docs/COMPONENT-API.md：属性、事件、插槽与类型
-- docs/CSS-THEME.md：主题变量、样式隔离与浮层限制
-- docs/INTEGRATION.md：原项目替换和业务接线
-- docs/COMPONENT-USAGE.md：原项目实际使用的组件与调用位置
-- docs/ADAPTATION.md：逐模块替换、Vite 图标配置、主题及业务适配方案
-
-请依据当前已安装包的版本与文档生成代码，不要虚构组件名称或 API。
-CSS 在当前项目公共入口只引入一次（HTML 可使用 link；Vue 使用 main.ts）。
-不能只以安装成功或 CSS 已加载作为视觉接入完成依据；按默认/悬停/聚焦/禁用/选中和原业务行为核对。
-业务请求、路由、权限由应用接入。
+请读取 node_modules/sky-ui-kit/llms.txt 和 docs/START-HERE.md。
+请先问我这次接入 HTML/JavaScript 还是 Vue，等待我的回答，不要根据项目文件直接猜测。
+然后按我的选择询问页面范围和目标：HTML 保留现有 DOM/事件/表单，仅统一支持的控件样式；
+Vue 询问是使用真实组件还是仅给原生控件换肤。已经明确提供的信息不重复询问。
+我选择“不确定”时再检查项目并请我确认。回答前只做文档读取和只读检查，不执行路线相关配置。
+按所选路线查阅包内指南及真实 exports，保留已有项目规则并合并到 AGENTS.md。
+完成后报告状态外观、原有业务行为的验证结果与剩余限制，不把安装成功视为接入完成。
 ```
 
 ### 图标安装：内置与自有资源
@@ -3624,6 +3618,10 @@ HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue
 
 修正 AI 指南及合并文档相对链接，更新 README 当前发布状态并归档历史说明。原生 HTML 路线明确保留 DOM/事件/表单且无需 Vue；新增透明地图覆盖层、独立浮层主题、旧皮肤移除及前后迁移示例。发布检查包括生成文档、相对链接/包内路径、类型和库构建；未进行浏览器视觉或真实地图验收。
 
+## 0.1.12 引导式接入
+
+新增唯一 START-HERE.md 入口，要求先询问 HTML/JavaScript 或 Vue 并等待用户回答，再确认目标与范围；明确回答不重复问，不确定时只读检查后请用户确认。README、llms 生成源、AI/HTML/迁移/主题/按需指南及网站快速开始共用此规则。HTML 保留已有交互，Vue 为用户明确选择的路线。包不会自行弹出问答，需 AI 阅读文档后执行。
+
 # Component API reference
 
 Generated from Vue/TypeScript source; defaultExpression is source text, not evaluated JSON. Types refer to declarations below. Unlisted props must not be invented. For Element Plus components use upstream documentation and shipped typings.
@@ -5896,6 +5894,8 @@ UiContainer 展示系统顶部/侧栏/内容和地图浮动区域示例。原 Ma
 | src/components/widgets/Legend.vue | 0 | 未发现直接引用，需检查间接 / 动态使用 | vue<br>vue-router |
 
 # CSS 变量主题与样式隔离
+
+接入前必须先按 [引导式接入流程](docs/START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 MapPageLayout 使用 --map-layout-layer-content/panel/legend/toolbar/focus/hover 统一区域层级。与原平台一致：content=1、panel=2、legend=3、toolbar=4、focus=5、hover=6，时间轴和右栏同样参与；hover 高于 focus；content 内部即使使用较大 z-index 也不跨越区域堆叠上下文。图例和底部外层允许内容溢出，避免浮层被父区域裁剪；内部滚动由业务组件负责。
 
@@ -6213,6 +6213,8 @@ HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue
 修正 AI 指南相对链接及 README 发布状态；新增透明地图覆盖层/主题面板/body 浮层示例，补齐旧页面 CSS 皮肤移除、布局保留和逐状态验收。迁移前后共用布局及业务脚本，不要求 Vue、不增加业务项目专用全局覆盖。详见 [HTML 迁移](docs/HTML-INTEGRATION.md)和[迁移后示例](examples/html/migration/after.html)。本轮仅文档、示例及生成器修订，未构建、发布或浏览器验证。
 
 # 按需引入
+
+接入前必须先按 [引导式接入流程](docs/START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 下一次发布后支持独立组件路径：
 
@@ -6621,6 +6623,10 @@ metricslab降水播放轴使用TemplateLayout.timeline插槽；timelineLeft/time
 
 # 原生 HTML 样式接入与旧页面迁移
 
+## 开始前先完成接入问答
+
+先按 [引导式接入流程](docs/START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案再配置。本文是用户选择原生控件换肤后的实施指南，不用于 AI 自行选择技术路线。
+
 ## 目标、版本与路线
 
 本路线适用于已有 HTML/JavaScript 页面、服务端模板以及 Vue 页面中的原生元素：统一库支持的控件表面样式，保留原 DOM、id/name/data 属性、监听器、表单提交和业务行为。不要求迁移 Vue，也不因页面包含查询、校验、弹窗等交互而切换技术栈。
@@ -6725,7 +6731,7 @@ data-sky-native="off" 使节点及其后代退出控件皮肤；内层 sky-html
 
 合并以下规则并保留原有内容；文档路径相对安装包根目录：
 
-> 本项目采用 sky-ui-kit 原生 HTML 样式路线。先读当前安装包 llms.txt、docs/HTML-INTEGRATION.md、docs/HTML-FORM-CATALOG.md 并核对 exports。保留原 DOM、监听器、表单与地图行为；使用受支持的库控件皮肤，删除冲突的旧默认及状态皮肤声明，保留布局。透明地图覆盖层不得因主题变为实底；浮层主题边界明确设置。不得通过叠加仿写皮肤补丁实现一致性。只有明确需要真实 Vue 组件才选择可选 Vue 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
+> 本项目经用户确认采用 sky-ui-kit 原生 HTML 样式路线，接入范围按本项目记录。后续新增接入先按 docs/START-HERE.md 确认未明确的路线及范围，不从项目结构自行猜测。先读当前安装包 llms.txt、docs/HTML-INTEGRATION.md、docs/HTML-FORM-CATALOG.md 并核对 exports。保留原 DOM、监听器、表单与地图行为；使用受支持的库控件皮肤，删除冲突的旧默认及状态皮肤声明，保留布局。透明地图覆盖层不得因主题变为实底；浮层主题边界明确设置。不得通过叠加仿写皮肤补丁实现一致性。只有明确需要真实 Vue 组件才选择可选 Vue 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
 
 ## 验收：视觉和业务均通过才完成
 
@@ -7150,3 +7156,59 @@ document.getElementById('theme').addEventListener('click', () => {
 });
 
 ~~~
+
+# 引导式接入：先问用户，再配置
+
+这是 README、llms.txt 和各接入指南共用的唯一流程入口。规则从 0.1.12 提供。安装包不会自动向用户弹出问答，也不会自动进入所有 AI 上下文；AI 阅读此入口后应主动执行下面的问答。
+
+## 第一步：确认用户使用 HTML 还是 Vue
+
+当用户说“帮我引入 sky-ui-kit”或安装后要求接入时，先问：
+
+> 这次要接入的是哪一种页面？
+> 1. 原生 HTML / JavaScript 页面
+> 2. Vue 3 页面
+> 3. 我不确定，请帮我检查后说明
+
+等待用户回答，再执行路线相关的文件修改、样式加载或框架依赖安装。不要根据 package.json、扩展名或当前目录擅自替用户选择。可以先阅读包内文档、核对已安装版本和只读检查项目。
+用户在本次对话已明确回答 HTML/Vue 时，直接采用该答案，不重复询问；该答案来自用户，不是 AI 猜测。用户选择“不确定”时才检查项目，说明发现并请用户确认接入的具体页面类型；混合项目需确认目标页面。
+
+## 第二步：按答案询问接入目标
+
+HTML 用户：
+
+> 你希望在哪些地方使用统一样式？
+> 1. 先改一个现有页面或面板，保留原来的操作逻辑
+> 2. 整个现有站点换肤，保留原来的操作逻辑
+> 3. 创建一个新的原生 HTML 示例页面
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+HTML 的查询、表单校验、分页、弹窗等现有交互继续使用原业务 JS，不把“需要交互”解释为“必须迁移 Vue”。只有用户主动要求真实 Vue 组件能力时，才说明可选局部挂载及成本，并等待其选择。
+
+Vue 用户：
+
+> 你希望怎样使用这个包？
+> 1. 使用库实际导出的 Vue 组件开发或替换页面
+> 2. 仅给现有原生 HTML 控件统一样式，保留现有逻辑
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+答案已明确时不重复问；缺失答案不能通过等待超时自动补成默认选择。用户暂未回答时只做不依赖答案的读取工作。
+
+## 第三步：实施所选路线
+
+| 用户选择 | 阅读资料 | 实施要求 |
+|---|---|---|
+| HTML 或 Vue 中原生元素换肤 | [HTML 迁移](docs/HTML-INTEGRATION.md)、[控件验收](docs/HTML-FORM-CATALOG.md) | 保留 DOM/id/name/监听器/表单，按需 CSS，删除冲突旧皮肤、保留布局 |
+| Vue 真实组件 | [AI 指南](docs/AI-GUIDE.md)、[真实出口](components.json)、[API](docs/COMPONENT-API.md)、[主题](docs/CSS-THEME.md) | 核对 Vue/peerDependencies，按实际导出使用组件 |
+
+记录用户确认的页面、路线与范围，简要说明将引入的资源，再实施；不额外要求用户确认每个常规修改。遇到地图透明覆盖层、浮层、旧 CSS 冲突时按 HTML 指南处理，不改成不透明整页工作区，也不通过仿写控件皮肤覆盖。
+需要本地源码路径才能完成的指引应作为文档缺口报告；消费者只依赖当前安装包。
+
+## 第四步：记录项目规则并逐状态验收
+
+将用户选择、接入范围、包内入口、主题位置及验收规则合并到消费项目 AGENTS.md，保留已有规则，不重复追加。不自动创建消费项目不存在的 Vue 依赖或迁移技术栈。
+核对默认、悬停、聚焦、错误、只读、禁用、选中及浮层，检查查询/提交/重置/地图操作等原行为。区分已做的静态检查和用户/浏览器实际验证，列出系统 select/日期等浏览器差异；安装成功或 CSS 已加载不等于完成视觉接入。
+
+## 新聊天测试
+
+用户只说“帮我引入 sky-ui-kit”。期望 AI 先询问 HTML/Vue，等待回答；随后按所选路线询问范围并执行。不得直接注册 Vue、套上全页背景或把页面改成库组件。已明确的答案不再重复询问。

package/llms.txt

@@ -1,6 +1,10 @@
 # sky-ui-kit
 
-> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.11. AI tools must explicitly load these files.
+> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.12. AI tools must explicitly load these files.
+
+## Mandatory onboarding
+
+Read [Start here](docs/START-HERE.md). Ask the user HTML/JavaScript or Vue FIRST and wait for their answer before route-specific edits or dependency configuration. Then ask scope and intended usage. Do not infer the route from project files. Reuse answers explicitly provided by the user; inspect only when they choose unsure, then ask them to confirm. HTML keeps existing DOM/events/forms and does not require Vue.
 
 ## Documentation
 
@@ -25,6 +29,6 @@
 
 ## Setup
 
-Native HTML: read docs/HTML-INTEGRATION.md first, retain DOM/events/forms, load supported html/*.css once, preserve transparent map overlays and remove conflicting legacy control skins. Vue is optional only when real Vue components are requested. Vue component route: import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts, and check components.json before using exports. Verify visual states and existing behavior; installing or loading CSS alone is not completion.
+After the required user Q&A in docs/START-HERE.md, native HTML: read docs/HTML-INTEGRATION.md, retain DOM/events/forms, load supported html/*.css once, preserve transparent map overlays and remove conflicting legacy control skins. Vue is optional only when real Vue components are requested. Vue component route: import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts, and check components.json before using exports. Verify visual states and existing behavior; installing or loading CSS alone is not completion.
 
 - [HTML form checklist](docs/HTML-FORM-CATALOG.md): individual native control examples and verification limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sky-ui-kit",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Vue UI components compatible with Element Plus and the project theme",
   "type": "module",
   "files": [
@@ -29,7 +29,8 @@
     "docs/HTML-INTEGRATION.md",
     "examples/html",
     "docs/HTML-FORM-CATALOG.md",
-    "docs/RELEASE-HISTORY.md"
+    "docs/RELEASE-HISTORY.md",
+    "docs/START-HERE.md"
   ],
   "exports": {
     ".": {