@visualization-hub/dev-mcp 1.0.8 → 1.0.10

package/README.md

@@ -91,3 +91,327 @@
 }
 ```
 
+---
+
+## 🛠️ 命令行工具使用
+
+### 安装与别名
+
+安装后，您可以使用以下两个命令之一启动开发者 MCP 服务器：
+
+- **`viz-dev-mcp`**：原始命令名
+- **`dkhub`**：简短别名（推荐）
+
+```bash
+# 通过 npx 直接使用
+npx -y @visualization-hub/dev-mcp
+
+# 或使用 dkhub 别名
+npx -y @visualization-hub/dev-mcp dkhub
+```
+
+### 本地开发使用
+
+在本地开发环境中，可以直接使用以下命令：
+
+```bash
+# 使用原始命令
+./bin/viz-dev-mcp.js
+
+# 或使用 dkhub 别名（需在 package.json 中配置）
+dkhub
+```
+
+### 配置示例
+
+在 AI Agent 客户端配置中，您可以使用 `dkhub` 作为命令名：
+
+```json
+{
+  "mcpServers": {
+    "visualization-dev-mcp": {
+      "command": "dkhub",
+      "env": {
+        "VIZ_BASE_URL": "http://localhost:3000",
+        "VIZ_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+> **注意**：`dkhub` 别名需要在全局安装或使用 npx 时才可用。本地开发时，建议使用 `./bin/viz-dev-mcp.js` 直接启动。
+
+### 🔀 两种运行模式
+
+| 模式 | 触发方式 | 说明 |
+| :--- | :--- | :--- |
+| **CLI 命令模式** | `dkhub <命令> [参数]` | 在终端直接传参执行，立即返回 JSON 结果（本文后续示例均为此模式） |
+| **MCP 服务器模式** | `dkhub`（不带参数） | 以 stdio 启动 MCP 服务器，供 Cursor / Claude 等 AI Agent 连接调用 |
+
+```bash
+# CLI 命令模式：终端直接传参，立即执行
+dkhub create_component_project --projectName my-comp --pageType cesium --title "我的组件"
+
+# MCP 服务器模式：不带任何参数，常驻进程供 AI Agent 调用
+dkhub
+```
+
+### ✍️ 参数传递语法（怎么传参）
+
+在 CLI 命令模式下，参数以 `--参数名 值` 的形式传递，支持三种写法：
+
+```bash
+# 写法 1：空格分隔（推荐）
+dkhub build_component_project --projectDir ./my-comp
+
+# 写法 2：等号分隔
+dkhub build_component_project --projectDir=./my-comp
+
+# 写法 3：布尔开关（省略值，写上即为 true）
+dkhub upload_component_project --projectDir ./my-comp --skipPreflight
+```
+
+**参数对照示例**（以 `create_component_project` 为例）：
+
+```bash
+dkhub create_component_project --projectName my-cesium-component --pageType cesium --title "三维量测组件"
+        │                          │                                  │                    │
+        │                          │                                  │                    └─ 值：中文标题（含空格需加引号）
+        │                          │                                  └─ 参数名 --pageType，值 cesium
+        │                          └─ 参数名 --projectName，值 my-cesium-component
+        └─ 命令名
+```
+
+**数组参数**（`keywords` / `libraries` / `tags`）支持逗号或空格分隔：
+
+```bash
+dkhub create_component_project --libraries turf,tween.js ...
+dkhub search_projects --keywords 无人机,三维
+```
+
+> **Shell 提示**：部分 Shell（如 PowerShell）在未加引号时会将逗号转为空格。`dkhub` 已同时兼容逗号与空格分隔，两种写法均可正确解析为数组。含空格或中文的参数值建议用双引号包裹。
+
+---
+
+### 📋 dkhub 命令全清单
+
+`dkhub` 提供以下 **18 个命令**，支持在终端直接传参调用（CLI 模式），也可由 AI Agent 通过 MCP 协议调用（服务器模式）。命令名可省略 `dkhub_` 前缀。
+
+#### 1. 引导与规范类命令
+
+| 命令 | 说明 | 关键参数 |
+| :--- | :--- | :--- |
+| `dkhub get_developer_guide` | 获取全生命周期研发阶段指引（各阶段前置依赖、必调工具、红线禁忌与准出检查项） | `stage`：`init` / `scaffold` / `coding` / `build` / `compliance` / `upload` / `all`（默认 `all`） |
+| `dkhub get_project_rule` | 获取组件开发规范、13 项沙箱约束与 4 大红线禁忌 | `section`（可选，指定章节） |
+| `dkhub get_development_workflow` | 获取 10 步标准化研发流程 | 无 |
+| `dkhub get_global_packages` | 查询平台预置引擎版本（Cesium / Three / ECharts 等）及可选扩展库清单（`/static/libs`） | `page_type`（可选） |
+| `dkhub get_project_url` | 获取指定组件版本在平台沙箱中的真实在线预览 URL | `project_name`（必需）、`version`（可选） |
+
+#### 2. 资产检索与源码查阅类命令
+
+| 命令 | 说明 | 关键参数 |
+| :--- | :--- | :--- |
+| `dkhub search_projects` | 多关键词全文检索知识库平台已有组件资产 | `keywords`（数组）、`page_type`、`page`、`page_size` |
+| `dkhub list_categories` | 获取所有技术栈分类列表及组件数量统计 | 无 |
+| `dkhub get_project_detail` | 获取单个组件项目完整详情、依赖清单与版本历史记录 | `project_name`（必需） |
+| `dkhub list_my_projects` | 获取当前 API Key 对应用户创建上传的所有项目列表及分页信息 | `page`、`page_size` |
+| `dkhub get_project_files` | 查看指定组件版本的文件结构树（含相对路径与尺寸） | `project_name`（必需）、`version`（可选） |
+| `dkhub get_file_content` | 读取组件源码文件内容（如 `index.vue`、`util.ts`） | `project_name`（必需）、`file_path`（必需）、`version`（可选） |
+| `dkhub grep_source_code` | 在指定组件或全部组件中执行关键字 / 正则 Grep 检索 | `query`（必需）、`project_name`（可选）、`file_pattern`（可选） |
+
+#### 3. 本地工程化研发与发布类命令
+
+| 命令 | 说明 | 关键参数 |
+| :--- | :--- | :--- |
+| `dkhub create_component_project` | 一键创建标准 Vue 3 + TypeScript + Vite 组件工程脚手架（开箱满足 13 项沙箱合规） | `projectName`（必需）、`pageType`（必需）、`title`（必需）、`description`、`libraries`、`targetDir`、`overwrite` |
+| `dkhub build_component_project` | 本地调用内置 Vite 引擎编译打包，输出沙箱专属 `dist/index.js` 与 `dist/index.css` | `projectDir`（必需） |
+| `dkhub check_sandbox_compliance` | 执行 13 项沙箱合规静态扫描，输出得分、违规文件与修复建议 | `projectDir`（必需） |
+| **`dkhub upload_component_project`** | **【组件发布命令】** 本地打包 ZIP 并通过底层 HTTP 物理流秒级直传平台（耗时 < 0.1s，0 Token）。上传前强制执行 Pre-Flight 合规扫描 | `projectDir`（必需）、`uploadType`：`test` / `final`（默认 `test`）、`changelog`、`skipPreflight` |
+| `dkhub download_component_project` | 从知识库拉取组件 ZIP 包并就地解压为可二次开发的标准工程 | `projectName`（必需）、`version`（可选）、`targetDir`（可选） |
+| `dkhub delete_version` | 调用云端鉴权接口删除指定组件的指定版本 | `projectName`（必需）、`version`（必需）、`isBak`（默认 `false`） |
+
+---
+
+#### 🚀 工程创建命令详解：`dkhub create_component_project`
+
+组件研发的第一步，一键生成符合平台 13 项沙箱合规规范的 Vue 3 + TypeScript + Vite 标准工程脚手架。
+
+**终端命令（直接复制执行）**：
+
+```bash
+dkhub create_component_project --projectName my-cesium-component --pageType cesium --title "三维量测组件" --description "基于 Cesium 的三维空间量测 HUD 组件" --libraries turf,tween.js --targetDir D:/projects
+```
+
+**参数逐项对照**：
+
+| 命令行写法 | 参数名 | 实际传入的值 |
+| :--- | :--- | :--- |
+| `--projectName my-cesium-component` | `projectName` | `my-cesium-component` |
+| `--pageType cesium` | `pageType` | `cesium` |
+| `--title "三维量测组件"` | `title` | `三维量测组件`（含中文/空格需加引号） |
+| `--description "基于 Cesium 的..."` | `description` | 组件描述（可省略） |
+| `--libraries turf,tween.js` | `libraries` | `["turf", "tween.js"]`（数组，逗号分隔） |
+| `--targetDir D:/projects` | `targetDir` | `D:/projects`（可省略，默认当前目录） |
+| `--overwrite` | `overwrite` | `true`（布尔开关，写上即生效，可省略） |
+
+**等价的 MCP 调用参数**（仅 AI Agent 在服务器模式下使用，终端用户无需关心）：
+
+```json
+{
+  "projectName": "my-cesium-component",
+  "pageType": "cesium",
+  "title": "三维量测组件",
+  "description": "基于 Cesium 的三维空间量测 HUD 组件",
+  "libraries": ["turf", "tween.js"],
+  "targetDir": "D:/projects",
+  "overwrite": false
+}
+```
+
+**参数说明**：
+
+| 参数 | 类型 | 必需 | 默认值 | 详细说明 |
+| :--- | :--- | :---: | :--- | :--- |
+| `projectName` | `string` | 是 | — | 组件英文标识，需符合 npm 命名规范（`^[a-z0-9-_]+$`）：仅允许小写字母、数字、中划线和下划线 |
+| `pageType` | `string` | 是 | — | 技术栈类型：`cesium` / `three` / `openlayers` / `echarts` / `mapbox` / `maplibre` / `webgl` / `canvas` / `common` |
+| `title` | `string` | 是 | — | 组件中文显示标题 |
+| `description` | `string` | 否 | `${title} 可视化组件` | 组件功能描述 |
+| `libraries` | `string[]` | 否 | `[]` | 引用的扩展库声明（如 `["tween.js", "turf", "proj4"]`），将写入 `project.json` 的 `libraries` 字段 |
+| `targetDir` | `string` | 否 | 当前工作区 (`process.cwd()`) | 目标存放目录。若为父目录，会自动在其下创建以 `projectName` 命名的子目录；若目录名已与 `projectName` 相同则直接使用 |
+| `overwrite` | `boolean` | 否 | `false` | 若目标工程目录已存在且非空，是否强制覆盖 |
+
+**生成的标准工程结构**：
+
+命令执行成功后，将在目标目录生成以下开箱即满足 13 项沙箱合规骨架的工程：
+
+```
+my-cesium-component/
+├── project.json            # 组件元数据清单 (name, title, pageType, entry, libraries, tags)
+├── package.json            # 依赖与构建脚本 (vue, element-plus, @element-plus/icons-vue, pinia)
+├── tsconfig.json           # TypeScript 编译配置
+├── vite.config.ts          # Vite 构建配置 (external 排除 vue / element-plus / cesium 等全局库)
+└── src/
+    ├── index.vue           # 主视图 SFC (使用 Element Plus 组件，无底图容器、无 Emoji)
+    ├── index.ts            # 核心逻辑 Composable (useComponentLogic) 与 onUnmounted 资源销毁
+    ├── index.less          # 独立样式 (pointer-events: auto !important + 左上角定位)
+    ├── util.ts             # localStorage 持久化工具纯函数
+    ├── type.ts             # TypeScript 接口契约定义
+    ├── env.d.ts            # 全局变量类型声明 (window.viewer / Cesium / THREE 等)
+    └── components/
+        └── StatusPanel.vue # 私有子组件示例 (引导多组件拆分)
+```
+
+**返回值示例**：
+
+```json
+{
+  "success": true,
+  "message": "组件工程 [my-cesium-component] 成功生成在 D:/projects/my-cesium-component",
+  "project_dir": "D:/projects/my-cesium-component",
+  "project_name": "my-cesium-component",
+  "page_type": "cesium",
+  "created_files": [
+    "project.json",
+    "package.json",
+    "tsconfig.json",
+    "vite.config.ts",
+    "src/env.d.ts",
+    "src/type.ts",
+    "src/util.ts",
+    "src/components/StatusPanel.vue",
+    "src/index.less",
+    "src/index.ts",
+    "src/index.vue"
+  ],
+  "next_steps": [
+    "1. 进入工程目录: cd \"D:/projects/my-cesium-component\"",
+    "2. (可选) 安装依赖: npm install",
+    "3. 编写业务逻辑: 修改 src/index.vue, src/index.ts, src/index.less",
+    "4. 本地编译打包: 调用 build_component_project(projectDir: \"D:/projects/my-cesium-component\")",
+    "5. 沙箱合规自检: 调用 check_sandbox_compliance(projectDir: \"D:/projects/my-cesium-component\")",
+    "6. 极速发布平台: 调用 upload_component_project(projectDir: \"D:/projects/my-cesium-component\")"
+  ]
+}
+```
+
+**后续研发流程**（由 AI Agent 按序调用）：
+
+1. `dkhub create_component_project` — 生成标准工程脚手架（或 `dkhub download_component_project` 拉取已有组件二次开发）
+2. 编码实现业务逻辑（按功能拆分私有子组件至 `src/components/`，单文件控制在 400 行内）
+3. `dkhub build_component_project` — 本地编译打包，输出 `dist/index.js` 与 `dist/index.css`
+4. `dkhub check_sandbox_compliance` — 13 项合规自检（需 ≥ 75 分且无阻断项）
+5. `dkhub upload_component_project`（`uploadType: "test"`）— 测试版发布
+6. `dkhub get_project_url` — 获取沙箱预览 URL 验证
+7. `dkhub upload_component_project`（`uploadType: "final"`）— 正式定版发布
+
+> **命名提示**：`projectName` 必须使用小写字母、数字、中划线或下划线（如 `my-cesium-component`、`drone_route_plan`），不可包含大写字母或中文，否则将触发参数校验错误。
+
+---
+
+#### 🎯 组件发布命令详解：`dkhub upload_component_project`
+
+组件发布是研发闭环的最后一步，将本地工程以物理流方式直传至知识库平台。
+
+**终端命令（直接复制执行）**：
+
+```bash
+dkhub upload_component_project --projectDir D:/projects/my-cesium-component --uploadType test --changelog "新增三维量测功能"
+```
+
+**参数逐项对照**：
+
+| 命令行写法 | 参数名 | 实际传入的值 |
+| :--- | :--- | :--- |
+| `--projectDir D:/projects/my-cesium-component` | `projectDir` | 本地工程根目录（**必填**） |
+| `--uploadType test` | `uploadType` | `test`（测试版，默认）或 `final`（正式版） |
+| `--changelog "新增三维量测功能"` | `changelog` | 版本更新说明（可省略） |
+| `--skipPreflight` | `skipPreflight` | `true`（布尔开关，跳过合规预检，**不建议**） |
+
+**等价的 MCP 调用参数**（仅 AI Agent 在服务器模式下使用，终端用户无需关心）：
+
+```json
+{
+  "projectDir": "D:/projects/my-cesium-component",
+  "uploadType": "test",
+  "changelog": "新增三维量测功能",
+  "skipPreflight": false
+}
+```
+
+**参数说明**：
+
+| 参数 | 类型 | 必需 | 默认值 | 详细说明 |
+| :--- | :--- | :---: | :--- | :--- |
+| `projectDir` | `string` | 是 | — | 本地组件工程根目录路径 |
+| `uploadType` | `string` | 否 | `test` | 发布模式：`test`（测试覆盖，快速迭代调试）或 `final`（正式定版发布，自动归档并触发封面快照） |
+| `changelog` | `string` | 否 | — | 版本更新说明 |
+| `skipPreflight` | `boolean` | 否 | `false` | 是否跳过上传前的 Pre-Flight 自动化合规前置检查。**建议保持 `false`**，若工程未达标将阻断上传并返回完整的标准工程结构与修复指引 |
+
+**完整发布流程（终端依次执行，可直接复制）**：
+
+```bash
+# 1. 创建工程脚手架
+dkhub create_component_project --projectName my-cesium-component --pageType cesium --title "三维量测组件" --targetDir D:/projects
+
+# 2. 编写业务代码后，本地编译打包
+dkhub build_component_project --projectDir D:/projects/my-cesium-component
+
+# 3. 13 项沙箱合规自检（需 ≥ 75 分且无阻断项）
+dkhub check_sandbox_compliance --projectDir D:/projects/my-cesium-component
+
+# 4. 测试版发布
+dkhub upload_component_project --projectDir D:/projects/my-cesium-component --uploadType test
+
+# 5. 获取预览链接，在浏览器验证渲染与交互
+dkhub get_project_url --project_name my-cesium-component
+
+# 6. 验证无误后，正式定版发布并归档
+dkhub upload_component_project --projectDir D:/projects/my-cesium-component --uploadType final
+```
+
+> **调用方式总结**：
+> - **终端用户 / CI**：使用 **CLI 命令模式**，通过 `--参数名 值` 在命令行传参（如 `dkhub build_component_project --projectDir ./my-comp`），立即得到 JSON 结果。
+> - **AI Agent（Cursor / Claude / VS Code 等）**：使用 **MCP 服务器模式**，运行 `dkhub`（不带参数），由 Agent 通过 MCP 协议调用，工具全名为 `dkhub_xxx`，参数以 JSON 对象传入。
+> - 两种模式**能力完全等价**，共用同一套业务逻辑；命令名在 CLI 模式下可省略 `dkhub_` 前缀。
+

package/bin/viz-dev-mcp.js

@@ -1,2 +1,21 @@
 #!/usr/bin/env node
-require('../dist/index.js');
+/**
+ * dkhub / viz-dev-mcp 启动入口
+ *
+ * 两种运行模式：
+ *   1. CLI 模式：dkhub <command> [参数]  —— 在终端直接传参调用工具命令
+ *   2. MCP 模式：dkhub                  —— 不带参数运行，作为 MCP 服务器（stdio）供 AI Agent 调用
+ */
+const args = process.argv.slice(2);
+
+// 判断是否为 CLI 模式：首个参数是命令名（不以 - 开头），或使用了帮助参数
+const isCliMode =
+  (args.length > 0 && !args[0].startsWith('-')) ||
+  args[0] === '--help' ||
+  args[0] === '-h';
+
+if (isCliMode) {
+  require('../dist/cli.js');
+} else {
+  require('../dist/index.js');
+}

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * dkhub CLI 命令行入口
+ *
+ * 支持在终端直接传参调用各工具命令，例如：
+ *   dkhub create_component_project --projectName my-comp --pageType cesium --title "我的组件"
+ *   dkhub upload_component_project --projectDir ./my-comp --uploadType test
+ *
+ * 参数传递支持三种写法：
+ *   --key value      空格分隔
+ *   --key=value      等号分隔
+ *   --flag           布尔开关（如 --overwrite 等价于 --overwrite=true）
+ *
+ * 数组参数（keywords / libraries / tags）支持逗号分隔或 JSON 数组：
+ *   --libraries tween.js,turf
+ *   --libraries '["tween.js","turf"]'
+ *
+ * 不带任何参数运行 dkhub 时，将作为 MCP 服务器启动（由 bin 脚本分发）。
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}