kui-vue 6.2.0 → 6.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AI.en-US.md +72 -4
- package/AI.md +70 -4
- package/ai/behaviors.json +23 -1
- package/ai/cli.mjs +180 -17
- package/ai/descriptions.json +28 -0
- package/ai/kui-components.json +1460 -1426
- package/ai/mcp.mjs +2 -188
- package/ai/query.mjs +192 -0
- package/ai/skills/kui-vue/SKILL.md +39 -18
- package/ai/skills/kui-vue/references/mcp.md +11 -1
- package/ai/skills/kui-vue/references/react-to-vue.md +110 -0
- package/ai/skills/kui-vue/references/vue-to-react.md +86 -0
- package/dist/index.js +2 -2
- package/es/index.js +549 -107
- package/es/locale/de.js +1 -1
- package/es/locale/el.js +1 -1
- package/es/locale/en.js +1 -1
- package/es/locale/fr.js +1 -1
- package/es/locale/it.js +1 -1
- package/es/locale/ja.js +1 -1
- package/es/locale/ko.js +1 -1
- package/es/locale/ru.js +1 -1
- package/es/locale/th.js +1 -1
- package/es/locale/uk.js +1 -1
- package/es/locale/vi.js +1 -1
- package/es/locale/zh-CN.js +1 -1
- package/es/locale/zh-TW.js +1 -1
- package/lib/index.cjs +2 -2
- package/lib/locale/de.cjs +1 -1
- package/lib/locale/el.cjs +1 -1
- package/lib/locale/en.cjs +1 -1
- package/lib/locale/fr.cjs +1 -1
- package/lib/locale/it.cjs +1 -1
- package/lib/locale/ja.cjs +1 -1
- package/lib/locale/ko.cjs +1 -1
- package/lib/locale/ru.cjs +1 -1
- package/lib/locale/th.cjs +1 -1
- package/lib/locale/uk.cjs +1 -1
- package/lib/locale/vi.cjs +1 -1
- package/lib/locale/zh-CN.cjs +1 -1
- package/lib/locale/zh-TW.cjs +1 -1
- package/package.json +6 -3
- package/style/base.css +1 -1
- package/style/components.css +2 -2
- package/style/index.css +2 -2
- package/style/motion.css +1 -1
- package/style/theme.css +1 -1
- package/types/carousel/carousel.d.ts +13 -0
- package/types/carousel/drag.d.ts +19 -0
- package/types/input/input-base.d.ts +186 -0
- package/types/input/input.d.ts +36 -107
- package/types/page/index.d.ts +13 -0
- package/types/page/responsive.d.ts +1 -0
- package/vetur/attributes.json +746 -722
- package/vetur/tags.json +96 -94
- package/vetur/web-types.json +687 -671
package/AI.en-US.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Kui Vue AI integration
|
|
2
2
|
|
|
3
|
+
Icon prop contract: Button.icon takes IconType[] data imported from kui-icons: import { Search } from 'kui-icons'; use <Button :icon="Search" /> in Vue templates or <Button icon={Search} /> in TSX. Never pass h(Icon, ...), a VNode, a component function, or an icon-name string to icon. Custom rendered content belongs in the default slot. Input prefix/suffix slots are not the Button.icon API.
|
|
4
|
+
|
|
3
5
|
Each Kui Vue npm release includes version-matched component metadata, a JSON Schema, an Agent Skill, an MCP server, and evaluation cases. This lets AI clients query the installed public API instead of guessing props.
|
|
4
6
|
|
|
5
7
|
## Initialize a project
|
|
@@ -13,20 +15,52 @@ The command adds Kui Vue guidance to `AGENTS.md` and is safe to run repeatedly.
|
|
|
13
15
|
|
|
14
16
|
## MCP server
|
|
15
17
|
|
|
16
|
-
|
|
18
|
+
Install `kui-vue` and its dependencies in the consuming project first.
|
|
19
|
+
Confirm that the installed version includes `node_modules/kui-vue/ai/mcp.mjs`.
|
|
20
|
+
Do not copy the script alone: it needs the package's metadata and dependencies.
|
|
21
|
+
|
|
22
|
+
Run `node -p "process.execPath"` in the project terminal to obtain the Node
|
|
23
|
+
executable's absolute path. For clients using the mcpServers JSON format:
|
|
17
24
|
|
|
18
25
|
```json
|
|
19
26
|
{
|
|
20
27
|
"mcpServers": {
|
|
21
28
|
"kui-vue": {
|
|
22
|
-
"command": "
|
|
23
|
-
"args": ["
|
|
29
|
+
"command": "/absolute/path/to/node",
|
|
30
|
+
"args": ["/absolute/path/to/project/node_modules/kui-vue/ai/mcp.mjs"]
|
|
24
31
|
}
|
|
25
32
|
}
|
|
26
33
|
}
|
|
27
34
|
```
|
|
28
35
|
|
|
29
|
-
|
|
36
|
+
Replace both placeholders with real absolute paths. A path containing spaces
|
|
37
|
+
remains one string argument. On Windows use forward slashes or escaped
|
|
38
|
+
backslashes in JSON, for example `C:/Program Files/nodejs/node.exe`.
|
|
39
|
+
Other clients may use another configuration format; enter the same command and
|
|
40
|
+
args through their MCP settings instead of copying this JSON unchanged.
|
|
41
|
+
|
|
42
|
+
This configuration does not depend on the client's working directory or pnpm.
|
|
43
|
+
Use `"command": "node"` only if the client can find Node.
|
|
44
|
+
The alternative command `pnpm` with args `["exec", "kui-vue-mcp"]` requires
|
|
45
|
+
pnpm on the client's PATH and an explicit working directory pointing to the
|
|
46
|
+
consuming project with the package installed.
|
|
47
|
+
|
|
48
|
+
### Verify and troubleshoot
|
|
49
|
+
|
|
50
|
+
1. Launch the absolute Node/script paths in a terminal first. This is a stdio
|
|
51
|
+
service, not a web server. It normally waits silently for input; press Ctrl+C
|
|
52
|
+
to stop. Silence alone does not prove a successful MCP connection.
|
|
53
|
+
2. Save the client configuration and reconnect. Check successful initialization
|
|
54
|
+
and a tool list containing search_components and get_component_api.
|
|
55
|
+
3. Call `get_component_api({ "name": "Button" })` and confirm an API response.
|
|
56
|
+
This tests connectivity and resources, not all component interactions.
|
|
57
|
+
|
|
58
|
+
If Node/pnpm cannot be found, check the executable path and client environment.
|
|
59
|
+
If the script cannot be found, check the project path, installation and package
|
|
60
|
+
version. Missing dependencies/metadata require restoring the complete package
|
|
61
|
+
installation with the project's package manager, not copying individual files.
|
|
62
|
+
If terminal startup works but the client fails, inspect client startup and
|
|
63
|
+
handshake logs. Update configuration after moving the project or Node installation.
|
|
30
64
|
|
|
31
65
|
## Client guidance
|
|
32
66
|
|
|
@@ -71,3 +105,37 @@ Run `pnpm check:ai-templates` for template type checks and interaction tests.
|
|
|
71
105
|
`pnpm build` still produces all release artifacts. Each build stage runs in a separate sequential Node process with a default 2048 MB old-space limit. Terser uses one worker; Less runs on the main thread. Type generation no longer runs inside the ESM bundler.
|
|
72
106
|
|
|
73
107
|
For development, use `pnpm dev`. `pnpm build:local` generates CSS, ESM, declarations and editor metadata only; it is not a release build. `pnpm build:es` now emits JavaScript only; use `pnpm build:types` for declarations. Individual CSS/CJS/UMD stages remain available. Set `KUI_BUILD_HEAP_MB=2560` only when a stage needs a larger heap. A heap limit is not a total process/system memory limit; avoid simultaneous builds and large test runs on 8 GB machines.
|
|
108
|
+
|
|
109
|
+
## Installed resources and command-line queries (without MCP)
|
|
110
|
+
|
|
111
|
+
`kui-vue/metadata` and `kui-vue/skill` are package export specifiers, not
|
|
112
|
+
directories. Resolve them with `node -p "require.resolve('kui-vue/metadata')"`
|
|
113
|
+
or run `pnpm exec kui-vue-ai paths`. Read the Skill at the returned path before
|
|
114
|
+
implementing unfamiliar APIs.
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
pnpm exec kui-vue-ai paths
|
|
118
|
+
pnpm exec kui-vue-ai search Input --limit 5
|
|
119
|
+
pnpm exec kui-vue-ai api Input --section props
|
|
120
|
+
pnpm exec kui-vue-ai api Input --section behavior
|
|
121
|
+
pnpm exec kui-vue-ai examples Input
|
|
122
|
+
pnpm exec kui-vue-ai templates
|
|
123
|
+
pnpm exec kui-vue-ai migration vue-to-react
|
|
124
|
+
pnpm exec kui-vue-ai migration react-to-vue
|
|
125
|
+
pnpm exec kui-vue-ai validate src/App.vue
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Use `example Input <id>` with an ID from examples; use `template <id>` to read
|
|
129
|
+
one business template. `query <tool-name> '<JSON>'` uses the same engine and
|
|
130
|
+
argument validation as MCP. Results are JSON; invalid usage and errors exit
|
|
131
|
+
nonzero. Source can be piped into `validate -`. Validation remains partial.
|
|
132
|
+
|
|
133
|
+
Run `init` again after upgrading. It refreshes a marked managed block and
|
|
134
|
+
preserves text outside it. For pre-marker guidance, only exact known generated
|
|
135
|
+
lines are migrated; customized wording remains for review. Put project-specific
|
|
136
|
+
rules outside managed markers. Malformed markers cause an error without writes.
|
|
137
|
+
|
|
138
|
+
Metadata describes components, not every package export. For utilities such as
|
|
139
|
+
theme, inspect the installed declarations too. Before migrating, read
|
|
140
|
+
`migration vue-to-react` or `migration react-to-vue`, then compare callbacks, state synchronization,
|
|
141
|
+
slots/render props and interaction behavior—not just typecheck results.
|
package/AI.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Kui Vue AI 开发接入
|
|
2
2
|
|
|
3
|
+
图标属性注意:`Button.icon` 接收从 `kui-icons` 导入的 `IconType[]` 图标数据。例如 `import { Search } from 'kui-icons'` 后,在模板中使用 `<Button :icon="Search" />`,在 TSX 中使用 `<Button icon={Search} />`。不要传 `h(Icon, ...)`、VNode、组件函数或图标名称字符串;自定义内容使用默认插槽。Input 的 prefix/suffix 插槽与 Button.icon 不是同一种接口。
|
|
4
|
+
|
|
3
5
|
Kui Vue 随 npm 版本一起发布组件元数据、JSON Schema、Agent Skill、MCP Server 和评测用例。AI 工具因此可以查询当前安装版本的真实 API,而不是猜测属性。
|
|
4
6
|
|
|
5
7
|
## 项目初始化
|
|
@@ -13,20 +15,53 @@ pnpm exec kui-vue-ai init
|
|
|
13
15
|
|
|
14
16
|
## MCP Server
|
|
15
17
|
|
|
16
|
-
|
|
18
|
+
先在应用项目中安装 `kui-vue` 及其依赖(见上面的安装命令),并确认安装版本包含
|
|
19
|
+
`node_modules/kui-vue/ai/mcp.mjs`。不要只复制这个脚本,它还需要同包的元数据和依赖。
|
|
20
|
+
|
|
21
|
+
在项目终端中运行以下命令,取得 Node 的绝对路径:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
node -p "process.execPath"
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
在支持 stdio MCP 的客户端中配置服务。下面是支持 `mcpServers` 格式的客户端示例;
|
|
28
|
+
其他客户端请通过 MCP 设置填写相同的 command 和 args,不要直接照搬整个 JSON:
|
|
17
29
|
|
|
18
30
|
```json
|
|
19
31
|
{
|
|
20
32
|
"mcpServers": {
|
|
21
33
|
"kui-vue": {
|
|
22
|
-
"command": "
|
|
23
|
-
"args": ["
|
|
34
|
+
"command": "/absolute/path/to/node",
|
|
35
|
+
"args": ["/absolute/path/to/project/node_modules/kui-vue/ai/mcp.mjs"]
|
|
24
36
|
}
|
|
25
37
|
}
|
|
26
38
|
}
|
|
27
39
|
```
|
|
28
40
|
|
|
29
|
-
|
|
41
|
+
将 command 替换为上面输出的 Node 路径,将 args 替换为你项目中脚本的绝对路径。
|
|
42
|
+
路径含空格也仍是一个字符串参数。Windows JSON 路径使用正斜杠或转义反斜杠,例如
|
|
43
|
+
`C:/Program Files/nodejs/node.exe`。该方式不依赖客户端的启动工作目录,也不要求使用 pnpm。
|
|
44
|
+
|
|
45
|
+
如果客户端能找到 Node,也可以使用 `"command": "node"`。
|
|
46
|
+
只有在客户端能找到 pnpm、且明确将工作目录设为已安装该包的项目目录时,
|
|
47
|
+
才使用 `"command": "pnpm"` 和 `"args": ["exec", "kui-vue-mcp"]`。
|
|
48
|
+
|
|
49
|
+
### 验证与排错
|
|
50
|
+
|
|
51
|
+
1. 先在终端用上述 Node 和脚本路径启动服务。它通过标准输入/输出通信,
|
|
52
|
+
不会打开网页,也不会主动打印“启动成功”;等待输入是正常状态,按 Ctrl+C 退出。
|
|
53
|
+
2. 保存客户端配置并重新连接服务。确认初始化成功、工具列表包含
|
|
54
|
+
`search_components` 和 `get_component_api`。
|
|
55
|
+
3. 查询 `get_component_api({ "name": "Button" })`,确认能返回组件 API。
|
|
56
|
+
这验证连接和资源读取,不代表所有组件交互都已验证。
|
|
57
|
+
|
|
58
|
+
若提示找不到 node/pnpm,请检查 command 的绝对路径及客户端环境;
|
|
59
|
+
找不到脚本,请检查项目路径、依赖安装和包版本;
|
|
60
|
+
脚本缺少依赖或元数据,请用项目的包管理器恢复完整安装,不要单独搬运脚本。
|
|
61
|
+
终端可运行但客户端失败时,查看客户端日志中的启动命令和握手错误。
|
|
62
|
+
项目路径或 Node 安装路径变更后也需要更新配置。
|
|
63
|
+
|
|
64
|
+
服务提供:
|
|
30
65
|
|
|
31
66
|
- 组件搜索和完整 API 查询
|
|
32
67
|
- 根据需求推荐组件
|
|
@@ -93,3 +128,34 @@ pnpm check:ai-evals
|
|
|
93
128
|
- 单阶段排查:`pnpm build:css`、`pnpm build:es`、`pnpm build:types`、`pnpm build:lib`、`pnpm build:umd`。
|
|
94
129
|
|
|
95
130
|
ES 构建不再同时生成类型,需要类型时使用 `build:types` 或 `build:local`。确需提高堆上限,可设置 `KUI_BUILD_HEAP_MB=2560 pnpm build`。堆上限不是整个进程或整台机器的内存上限;在 8 GB 机器上避免同时运行构建、全量测试和多个开发服务器。
|
|
131
|
+
|
|
132
|
+
## 不配置 MCP 也可以查询
|
|
133
|
+
|
|
134
|
+
`kui-vue/metadata` 和 `kui-vue/skill` 是 npm 包的导出路径,**不是目录**。
|
|
135
|
+
可以运行 `node -p "require.resolve('kui-vue/metadata')"` 定位文件,也可以使用
|
|
136
|
+
下面的 `paths` 命令。开始实现前先阅读返回路径中的 Skill。
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
pnpm exec kui-vue-ai paths
|
|
140
|
+
pnpm exec kui-vue-ai search Input --limit 5
|
|
141
|
+
pnpm exec kui-vue-ai api Input --section props
|
|
142
|
+
pnpm exec kui-vue-ai api Input --section behavior
|
|
143
|
+
pnpm exec kui-vue-ai examples Input
|
|
144
|
+
pnpm exec kui-vue-ai templates
|
|
145
|
+
pnpm exec kui-vue-ai migration vue-to-react
|
|
146
|
+
pnpm exec kui-vue-ai migration react-to-vue
|
|
147
|
+
pnpm exec kui-vue-ai validate src/App.vue
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
从 examples 结果取得 ID 后,用 `example Input <id>` 读取单个示例;
|
|
151
|
+
用 `template <id>` 读取业务模板。`query <工具名> '<JSON>'` 与 MCP 共用查询逻辑
|
|
152
|
+
和参数校验,无需启动 MCP。结果为 JSON;参数错误或校验不通过返回非零退出码。
|
|
153
|
+
`validate -` 可以读取标准输入,仍不能替代类型检查和交互测试。
|
|
154
|
+
|
|
155
|
+
升级依赖后重新执行 `init`,会更新 AGENTS.md 中带标记的托管区域,保留区域外的
|
|
156
|
+
项目规则。旧版没有标记的段落仅迁移能精确识别的生成行;修改过的自定义文本保留,
|
|
157
|
+
需要自行检查是否过时。项目规则应放在托管区域外,标记损坏时命令报错且不写入。
|
|
158
|
+
|
|
159
|
+
组件元数据不覆盖所有工具导出,例如 theme 还需查安装版本的声明。
|
|
160
|
+
迁移前按方向运行 `migration vue-to-react` 或 `migration react-to-vue` 阅读差异指南,核对绑定、回调、插槽与交互,
|
|
161
|
+
不要把类型检查通过当作迁移验收。
|
package/ai/behaviors.json
CHANGED
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"Button": {
|
|
25
25
|
"rules": [
|
|
26
26
|
"type controls semantic appearance; htmlType controls native submit/reset/button behavior. Do not use type=submit.",
|
|
27
|
-
"icon takes
|
|
27
|
+
"Button.icon takes IconType[] data imported from kui-icons: import { Search } from 'kui-icons'; use <Button :icon=\"Search\" /> in Vue templates or <Button icon={Search} /> in TSX. Never pass h(Icon, ...), a VNode, a component function, or an icon-name string to icon. Custom rendered content belongs in the default slot. Input prefix/suffix slots are not the Button.icon API."
|
|
28
28
|
]
|
|
29
29
|
},
|
|
30
30
|
"Modal": {
|
|
@@ -78,5 +78,27 @@
|
|
|
78
78
|
"rules": [
|
|
79
79
|
"compact joins adjacent controls. Vertical compact layout supports Button groups; it is not a general-purpose vertical form layout."
|
|
80
80
|
]
|
|
81
|
+
},
|
|
82
|
+
"Dropdown": {
|
|
83
|
+
"rules": [
|
|
84
|
+
"The default slot contains the trigger; the overlay slot contains popup content. React uses children and the overlay prop for these roles."
|
|
85
|
+
]
|
|
86
|
+
},
|
|
87
|
+
"DatePicker": {
|
|
88
|
+
"rules": [
|
|
89
|
+
"Default v-model binds the selected value; range modes support a range array. startDate/endDate bindings are an alternative. Do not assume one generic binding shape across all modes.",
|
|
90
|
+
"The change event reports the selected date value and formatted text. Check valueType and mode and handle clearing explicitly."
|
|
91
|
+
]
|
|
92
|
+
},
|
|
93
|
+
"Checkbox": {
|
|
94
|
+
"rules": [
|
|
95
|
+
"checked controls check state and value identifies a grouped item; do not conflate value, label and checked. Read the emitted event type before migrating to React."
|
|
96
|
+
]
|
|
97
|
+
},
|
|
98
|
+
"Popup": {
|
|
99
|
+
"rules": [
|
|
100
|
+
"The default slot provides the trigger and overlay provides popup content. Use v-model:open when two-way visibility synchronization is desired.",
|
|
101
|
+
"The shared Popup manages nested layers; avoid a second document-click closer around nested selector popups."
|
|
102
|
+
]
|
|
81
103
|
}
|
|
82
104
|
}
|
package/ai/cli.mjs
CHANGED
|
@@ -2,26 +2,189 @@
|
|
|
2
2
|
import fs from "node:fs";
|
|
3
3
|
import path from "node:path";
|
|
4
4
|
import process from "node:process";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
import { executeTool, metadata } from "./query.mjs";
|
|
5
7
|
|
|
6
|
-
const
|
|
7
|
-
const
|
|
8
|
-
const
|
|
9
|
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
|
|
8
|
+
const packageName = "kui-vue";
|
|
9
|
+
const heading = "## Kui Vue";
|
|
10
|
+
const legacyLines = [
|
|
11
|
+
"- This project uses Vue 3 and Kui Vue. Prefer components and public APIs documented at https://k-ui.cn.",
|
|
12
|
+
"- Import components from `kui-vue` and icons from `kui-icons`; import `kui-vue/style/index.css` once.",
|
|
13
|
+
"- Read the installed `kui-vue/metadata` before using unfamiliar props, events, or slots. Do not invent component APIs.",
|
|
14
|
+
"- Keep `theme`, `size`, and `shape` consistent and run typecheck/lint after edits.",
|
|
15
|
+
"- Button.icon takes IconType[] data imported from kui-icons: import { Search } from 'kui-icons'; use <Button :icon=\"Search\" /> in Vue templates or <Button icon={Search} /> in TSX. Never pass h(Icon, ...), a VNode, a component function, or an icon-name string to icon. Custom rendered content belongs in the default slot. Input prefix/suffix slots are not the Button.icon API.",
|
|
16
|
+
];
|
|
17
|
+
const begin = `<!-- ${packageName}:start -->`;
|
|
18
|
+
const end = `<!-- ${packageName}:end -->`;
|
|
19
|
+
const bin = `${packageName}-ai`;
|
|
20
|
+
const root = fileURLToPath(new URL("../", import.meta.url));
|
|
21
|
+
const help = `Usage: ${bin} <command>
|
|
22
|
+
init Update managed guidance in ./AGENTS.md
|
|
23
|
+
paths Show installed version and resource paths
|
|
24
|
+
search <query> [--offset N] [--limit N]
|
|
25
|
+
api <component> [--section NAME] API without example source
|
|
26
|
+
examples <component> [--offset N] [--limit N]
|
|
27
|
+
example <component> <id> Read one example from examples output
|
|
28
|
+
templates [query]
|
|
29
|
+
template <id>
|
|
30
|
+
validate <file|-> Check a source file or stdin; exit 1 if invalid
|
|
31
|
+
migration [vue-to-react|react-to-vue] Read migration guidance (default: vue-to-react)
|
|
32
|
+
query <MCP-tool-name> '<JSON>' Same query engine, no MCP setup required
|
|
33
|
+
help
|
|
34
|
+
All queries return JSON. Limits: 1–20, default 10. Errors exit nonzero.
|
|
35
|
+
Package export specifiers (e.g. ${packageName}/metadata) are not directories.`;
|
|
15
36
|
|
|
16
|
-
|
|
17
|
-
|
|
37
|
+
function guidance() {
|
|
38
|
+
return `${begin}
|
|
39
|
+
Installed ${packageName} guidance (version ${metadata.version}; managed by ${bin} init).
|
|
40
|
+
- Read the installed Skill before implementation: node_modules/${packageName}/ai/skills/${packageName}/SKILL.md. If this path is unavailable, run pnpm exec ${bin} paths to resolve it.
|
|
41
|
+
- ${packageName}/metadata and ${packageName}/skill are package export specifiers, NOT directories. Resolve them with node -p "require.resolve('${packageName}/metadata')" or use pnpm exec ${bin} paths.
|
|
42
|
+
- Without MCP, use pnpm exec ${bin} search Input, api Input --section props, api Input --section behavior, examples Input, and example Input <id>. Run help for arguments. Do not read the entire metadata JSON at once.
|
|
43
|
+
- For migration, read pnpm exec ${bin} migration vue-to-react or migration react-to-vue and query both installed libraries. Confirm both versions; declarations verify types, examples and behavior contracts verify usage.
|
|
44
|
+
- Import components from ${packageName}, icons from kui-icons, and ${packageName}/style/index.css once. Button.icon accepts imported icon data, not a rendered Icon element.
|
|
45
|
+
- Run pnpm exec ${bin} validate <file>, then application typecheck and interaction tests. Validation is partial; inspect skipped/complete and do not equate typecheck success with behavioral parity.
|
|
46
|
+
- Prefer installed-version resources over online docs. Do not invent APIs. Project-specific instructions outside this managed block are preserved.
|
|
47
|
+
${end}`;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function init() {
|
|
51
|
+
const target = path.resolve("AGENTS.md");
|
|
18
52
|
const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
53
|
+
const start = current.indexOf(begin);
|
|
54
|
+
const finish = current.indexOf(end);
|
|
55
|
+
let next;
|
|
56
|
+
if (start >= 0 || finish >= 0) {
|
|
57
|
+
if (
|
|
58
|
+
start < 0 ||
|
|
59
|
+
finish < start ||
|
|
60
|
+
current.indexOf(begin, start + begin.length) >= 0 ||
|
|
61
|
+
current.indexOf(end, finish + end.length) >= 0
|
|
62
|
+
) {
|
|
63
|
+
throw new Error("Malformed or duplicate managed markers in AGENTS.md; no changes made.");
|
|
64
|
+
}
|
|
65
|
+
next = current.slice(0, start) + guidance() + current.slice(finish + end.length);
|
|
66
|
+
} else {
|
|
67
|
+
// Upgrade only exact lines emitted by the previous initializer in its own
|
|
68
|
+
// section. Never replace an entire user-maintained heading or paragraph.
|
|
69
|
+
const lines = current.split(/(?<=\n)/);
|
|
70
|
+
let inSection = false;
|
|
71
|
+
next = lines
|
|
72
|
+
.filter((line) => {
|
|
73
|
+
const trimmed = line.trim();
|
|
74
|
+
if (/^##\s/.test(trimmed)) inSection = trimmed === heading;
|
|
75
|
+
return !(inSection && legacyLines.includes(trimmed));
|
|
76
|
+
})
|
|
77
|
+
.join("");
|
|
78
|
+
const headingMatch = new RegExp("^" + heading + "\\r?$", "m").exec(next);
|
|
79
|
+
if (headingMatch) {
|
|
80
|
+
const position = headingMatch.index + headingMatch[0].length;
|
|
81
|
+
next = next.slice(0, position) + "\n\n" + guidance() + next.slice(position);
|
|
82
|
+
} else {
|
|
83
|
+
next +=
|
|
84
|
+
(next ? (next.endsWith("\n") ? "\n" : "\n\n") : "") + heading + "\n\n" + guidance() + "\n";
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
if (next !== current) fs.writeFileSync(target, next);
|
|
88
|
+
console.log(
|
|
89
|
+
JSON.stringify({ file: target, updated: next !== current, version: metadata.version }, null, 2),
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function parseOptions(tokens) {
|
|
94
|
+
const args = [];
|
|
95
|
+
const options = {};
|
|
96
|
+
for (let i = 0; i < tokens.length; i++) {
|
|
97
|
+
const token = tokens[i];
|
|
98
|
+
if (!token.startsWith("--")) {
|
|
99
|
+
args.push(token);
|
|
100
|
+
continue;
|
|
101
|
+
}
|
|
102
|
+
const key = token.slice(2);
|
|
103
|
+
if (
|
|
104
|
+
!["offset", "limit", "section"].includes(key) ||
|
|
105
|
+
key in options ||
|
|
106
|
+
tokens[i + 1] === undefined
|
|
107
|
+
)
|
|
108
|
+
throw new Error(`Invalid option: ${token}`);
|
|
109
|
+
const value = tokens[++i];
|
|
110
|
+
options[key] = key === "section" ? value : Number(value);
|
|
111
|
+
}
|
|
112
|
+
return { args, options };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
try {
|
|
116
|
+
const [command = "help", ...tokens] = process.argv.slice(2);
|
|
117
|
+
if (["help", "--help", "-h"].includes(command)) {
|
|
118
|
+
console.log(help);
|
|
119
|
+
} else if (command === "init") {
|
|
120
|
+
if (tokens.length) throw new Error("init takes no arguments");
|
|
121
|
+
init();
|
|
122
|
+
} else if (command === "paths") {
|
|
123
|
+
if (tokens.length) throw new Error("paths takes no arguments");
|
|
124
|
+
console.log(
|
|
125
|
+
JSON.stringify(
|
|
126
|
+
{
|
|
127
|
+
library: packageName,
|
|
128
|
+
version: metadata.version,
|
|
129
|
+
metadata: path.join(root, "ai/kui-components.json"),
|
|
130
|
+
skill: path.join(root, `ai/skills/${packageName}/SKILL.md`),
|
|
131
|
+
migration: path.join(root, `ai/skills/${packageName}/references/vue-to-react.md`),
|
|
132
|
+
reverseMigration: path.join(root, `ai/skills/${packageName}/references/react-to-vue.md`),
|
|
133
|
+
},
|
|
134
|
+
null,
|
|
135
|
+
2,
|
|
136
|
+
),
|
|
137
|
+
);
|
|
138
|
+
} else if (command === "migration") {
|
|
139
|
+
const direction = tokens[0] || "vue-to-react";
|
|
140
|
+
if (tokens.length > 1 || !["vue-to-react", "react-to-vue"].includes(direction))
|
|
141
|
+
throw new Error("migration expects vue-to-react or react-to-vue");
|
|
142
|
+
const guide = direction === "react-to-vue" ? "react-to-vue.md" : "vue-to-react.md";
|
|
143
|
+
console.log(
|
|
144
|
+
JSON.stringify(
|
|
145
|
+
{
|
|
146
|
+
version: metadata.version,
|
|
147
|
+
source: fs.readFileSync(
|
|
148
|
+
path.join(root, `ai/skills/${packageName}/references/${guide}`),
|
|
149
|
+
"utf8",
|
|
150
|
+
),
|
|
151
|
+
},
|
|
152
|
+
null,
|
|
153
|
+
2,
|
|
154
|
+
),
|
|
155
|
+
);
|
|
156
|
+
} else if (command === "query") {
|
|
157
|
+
if (tokens.length !== 2) throw new Error("query requires a tool name and JSON arguments");
|
|
158
|
+
const result = executeTool(tokens[0], JSON.parse(tokens[1]));
|
|
159
|
+
console.log(JSON.stringify(result, null, 2));
|
|
160
|
+
if (tokens[0] === "validate_kui_usage" && !result.valid) process.exitCode = 1;
|
|
22
161
|
} else {
|
|
23
|
-
|
|
162
|
+
const { args, options } = parseOptions(tokens);
|
|
163
|
+
const commands = {
|
|
164
|
+
search: ["search_components", ["query"]],
|
|
165
|
+
api: ["get_component_api", ["name"]],
|
|
166
|
+
examples: ["list_component_examples", ["name"]],
|
|
167
|
+
example: ["get_component_example", ["name", "id"]],
|
|
168
|
+
templates: ["list_templates", ["query"]],
|
|
169
|
+
template: ["get_template", ["id"]],
|
|
170
|
+
validate: ["validate_kui_usage", ["source"]],
|
|
171
|
+
};
|
|
172
|
+
const entry = commands[command];
|
|
173
|
+
if (!entry) throw new Error(`Unknown command: ${command}. Run ${bin} help.`);
|
|
174
|
+
const [tool, keys] = entry;
|
|
175
|
+
if (args.length !== keys.length && !(command === "templates" && !args.length))
|
|
176
|
+
throw new Error(`${command} expects ${keys.join(", ")}; quote arguments containing spaces.`);
|
|
177
|
+
const params = { ...options };
|
|
178
|
+
args.forEach((value, i) => {
|
|
179
|
+
params[keys[i]] = value;
|
|
180
|
+
});
|
|
181
|
+
if (command === "validate")
|
|
182
|
+
params.source = fs.readFileSync(args[0] === "-" ? 0 : args[0], "utf8");
|
|
183
|
+
const result = executeTool(tool, params);
|
|
184
|
+
console.log(JSON.stringify(result, null, 2));
|
|
185
|
+
if (command === "validate" && !result.valid) process.exitCode = 1;
|
|
24
186
|
}
|
|
25
|
-
}
|
|
26
|
-
console.
|
|
187
|
+
} catch (error) {
|
|
188
|
+
console.error(JSON.stringify({ error: error.message }));
|
|
189
|
+
process.exitCode = 1;
|
|
27
190
|
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"Input": {
|
|
3
|
+
"onFocus": {
|
|
4
|
+
"zh": "输入元素获得焦点时触发,接收原生 FocusEvent。",
|
|
5
|
+
"en": "Emitted with the native FocusEvent when the input element receives focus."
|
|
6
|
+
},
|
|
7
|
+
"onBlur": {
|
|
8
|
+
"zh": "输入元素失去焦点时触发,接收原生 FocusEvent;表单上下文同时处理失焦校验。",
|
|
9
|
+
"en": "Emitted with the native FocusEvent when the input loses focus; the form context also processes blur validation."
|
|
10
|
+
}
|
|
11
|
+
},
|
|
12
|
+
"TextArea": {
|
|
13
|
+
"onInput": {
|
|
14
|
+
"zh": "原生文本输入时触发,接收 Event;新字符串值由 change 和 v-model 更新事件提供。",
|
|
15
|
+
"en": "Emitted with the native Event on text input; change and the v-model update event provide the new string value."
|
|
16
|
+
}
|
|
17
|
+
},
|
|
18
|
+
"Option": {
|
|
19
|
+
"onClick": {
|
|
20
|
+
"zh": "可用选项被点击并发出 select 后触发,接收原生 MouseEvent;禁用项不触发。",
|
|
21
|
+
"en": "Emitted with the native MouseEvent after select on an enabled option click; disabled options do not trigger it."
|
|
22
|
+
},
|
|
23
|
+
"onMouseenter": {
|
|
24
|
+
"zh": "鼠标进入可用选项时触发,接收原生 MouseEvent;禁用项不触发。",
|
|
25
|
+
"en": "Emitted with the native MouseEvent when the pointer enters an enabled option; disabled options do not trigger it."
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
}
|