cloudcc-cli 2.2.5 → 2.2.7

package/src/plugin/doc.js

@@ -0,0 +1,801 @@
+/**
+ * plugin 文档统一入口（全量一次性输出）
+ */
+const fs = require("fs");
+const path = require("path");
+
+function generateFullMarkdownDoc() {
+    const lines = [
+        "# CloudCC 自定义组件开发指南",
+        "",
+        "> 本文档参考官方「自定义组件」说明与示例整理而成：[自定义组件](https://help.cloudcc.cn/product03/zi-ding-yi-zu-jian/)。  ",
+        "> 目标：指导开发者从 0 到 1 创建、调试、发布组件，并掌握常用能力（启动型组件、防止样式污染、ECharts、调用自定义类、引入第三方库/图片、日志上报、扩展属性与事件等）。",
+        "",
+        "---",
+        "",
+        "## 1. 快速上手：发布第一个组件",
+        "",
+        "### 1.1 启动项目",
+        "",
+        "在已完成环境搭建与模板项目创建后（见 `env-setup.md`），启动本地项目：",
+        "",
+        "```bash",
+        "npm run serve",
+        "```",
+        "",
+        "浏览器访问 `http://localhost:8080/`，确认模板项目能正常运行。",
+        "",
+        "### 1.2 创建组件",
+        "",
+        "- 新建一个组件文件，**组件名称必须满足 DOM 命名规则**，例如：`cc-com-demo.vue`  ",
+        "  - 推荐遵循：以 `cc-` 开头，后续使用小写单词和 `-` 连接。",
+        "",
+        "### 1.3 在 `App` 中引入组件",
+        "",
+        "在模板项目的入口（通常是 `App.vue` 或特定页面组件）中，引入你创建的组件并挂载到页面。",
+        "",
+        "### 1.4 本地预览",
+        "",
+        "保持 `npm run serve` 运行，在浏览器中访问 `http://localhost:8080/`，确认组件渲染正常。",
+        "",
+        "### 1.5 发布组件",
+        "",
+        "在 VS Code 中：",
+        "- 右键点击组件的入口文件（你的自定义组件文件）  ",
+        "- 选择「发布组件」（CloudCC 插件菜单）  ",
+        "- 控制台提示发布成功信息，表示组件已经上传至 CloudCC 平台，可在页面编辑器中使用。",
+        "",
+        "---",
+        "",
+        "## 2. 启动型组件（loadModel=start）",
+        "",
+        "> 通过设置 `loadModel: \"start\"`，可以让组件在应用启动时加载，而不是等页面渲染时再加载，适合做布局调整、全局样式/脚本注入、全局监听等。",
+        "",
+        "### 2.1 场景示例",
+        "",
+        "示例：使用启动型组件隐藏详情页右侧区域（如联系人详情页右侧活动动态 Card）。",
+        "",
+        "### 2.2 代码示例",
+        "",
+        "```vue",
+        "<template>",
+        "  <div></div>",
+        "</template>",
+        "",
+        "<script>",
+        "console.log(\"JS 脚本可以写在这里，会在组件加载时自动执行\");",
+        "",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        // 组件唯一标识，全局唯一",
+        "        component: \"cloudcc-demo-a\",",
+        "        // 组件名称，在页面编辑器显示的名字",
+        "        compName: \"cloudcc-demo-a\",",
+        "        // 组件描述信息",
+        "        compDesc: \"组件描述信息\",",
+        "        // 设置组件在应用启动的时候加载",
+        "        loadModel: \"start\"",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  }",
+        "};",
+        "</script>",
+        "",
+        "<style lang=\"scss\">",
+        "// 下方样式选择器仅作示例，具体 DOM 结构请以实际页面为准",
+        ".detail001 {",
+        "  .main.left.scrollBoxUnique {",
+        "    width: 100% !important;",
+        "  }",
+        "  .layoutSwitchBox {",
+        "    display: none !important;",
+        "  }",
+        "  .right.scrollBoxUnique {",
+        "    display: none !important;",
+        "  }",
+        "}",
+        "</style>",
+        "```",
+        "",
+        "说明：",
+        "- 示例中通过类名（如 `.detail001`）与子选择器控制布局与显示/隐藏。  ",
+        "- DOM 结构可能随版本调整，**不要依赖不稳定选择器**，必要时配合「正确查找页面元素」最佳实践。",
+        "",
+        "---",
+        "",
+        "## 3. 避免样式污染（scoped）",
+        "",
+        "> Vue 组件中不加 `scoped` 的 `style` 会导致全局样式污染。平台推荐所有组件样式默认使用 `scoped`。",
+        "",
+        "### 3.1 最小示例",
+        "",
+        "```vue",
+        "<template>",
+        "  <div></div>",
+        "</template>",
+        "",
+        "<script>",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\"",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  }",
+        "};",
+        "</script>",
+        "",
+        "<style lang=\"scss\" scoped>",
+        "// 因为设置了 scoped，此标签下的样式仅作用于当前组件",
+        "</style>",
+        "```",
+        "",
+        "要点：",
+        "- `lang=\"scss\"`：推荐统一使用 SCSS",
+        "- `scoped`：保证样式只作用在当前组件，避免影响宿主页面与其他组件",
+        "",
+        "---",
+        "",
+        "## 4. 使用 ECharts 绘制图表",
+        "",
+        "> 平台已集成 `echarts@5.3.2`，组件打包时会排除该库，发布到平台后会自动引用平台 ECharts 资源。",
+        "",
+        "### 4.1 代码示例（区域图）",
+        "",
+        "```vue",
+        "<template>",
+        "  <div id=\"chartId\" :style=\"{ width: '100%', height: '400px' }\"></div>",
+        "</template>",
+        "",
+        "<script>",
+        "import * as echarts from \"echarts\";",
+        "",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\"",
+        "      },",
+        "      isLock: false,",
+        "      myChart: null",
+        "    };",
+        "  },",
+        "  mounted() {",
+        "    this.myChart = echarts.init(document.getElementById(\"chartId\"));",
+        "    this.myChart.setOption({",
+        "      // 此处为官方示例配置，可按需裁剪和修改",
+        "      color: [\"#80FFA5\", \"#00DDFF\", \"#37A2FF\", \"#FF0087\", \"#FFBF00\"],",
+        "      title: { text: \"Gradient Stacked Area Chart\" },",
+        "      tooltip: {",
+        "        trigger: \"axis\",",
+        "        axisPointer: {",
+        "          type: \"cross\",",
+        "          label: { backgroundColor: \"#6a7985\" }",
+        "        }",
+        "      },",
+        "      legend: { data: [\"Line 1\", \"Line 2\", \"Line 3\", \"Line 4\", \"Line 5\"] },",
+        "      toolbox: { feature: { saveAsImage: {} } },",
+        "      grid: {",
+        "        left: \"3%\",",
+        "        right: \"4%\",",
+        "        bottom: \"3%\",",
+        "        containLabel: true",
+        "      },",
+        "      xAxis: [{ type: \"category\", boundaryGap: false, data: [\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\",\"Sat\",\"Sun\"] }],",
+        "      yAxis: [{ type: \"value\" }],",
+        "      series: [",
+        "        // 省略部分 series 配置，可按官方示例使用",
+        "      ]",
+        "    });",
+        "  }",
+        "};",
+        "</script>",
+        "",
+        "<style lang=\"scss\" scoped>",
+        ".cc-container {",
+        "  text-align: center;",
+        "  padding: 8px;",
+        "  background: goldenrod;",
+        "}",
+        "</style>",
+        "```",
+        "",
+        "建议：",
+        "- 在 `beforeDestroy`/`unmounted` 生命周期中调用 `this.myChart.dispose()` 释放资源，避免内存泄露。",
+        "",
+        "---",
+        "",
+        "## 5. 在组件中调用自定义类（后端接口）",
+        "",
+        "> 自定义组件调用后台自定义类已封装在 `CCDK` 中，**不要自己拼接 HTTP 地址**，统一使用 `$CCDK.CCCommon.post`。",
+        "",
+        "### 5.1 代码示例",
+        "",
+        "```vue",
+        "<template>",
+        "  <div class=\"cc-container\" @click=\"getInfo\">Hello World</div>",
+        "</template>",
+        "",
+        "<script>",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\"",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  },",
+        "  methods: {",
+        "    getInfo() {",
+        "      const className = \"AccountClass\";",
+        "      const methodName = \"selectAccount\";",
+        "      const params = [",
+        "        { argType: \"java.lang.String\", argValue: \"hello\" },",
+        "        { argType: \"java.lang.String\", argValue: \"world\" }",
+        "      ];",
+        "",
+        "      window.$CCDK.CCCommon.post(className, methodName, params)",
+        "        .then(res => {",
+        "          console.log(res);",
+        "        })",
+        "        .catch(error => {",
+        "          console.error(error);",
+        "        });",
+        "    }",
+        "  }",
+        "};",
+        "</script>",
+        "",
+        "<style lang=\"scss\" scoped>",
+        ".cc-container {",
+        "  text-align: center;",
+        "  padding: 8px;",
+        "  background: goldenrod;",
+        "}",
+        "</style>",
+        "```",
+        "",
+        "要点：",
+        "- `className`、`methodName` 必须与 CloudCC 后端自定义类和方法保持一致",
+        "- `params` 为按顺序传入的参数数组，每项包括 `argType`（Java 类型）与 `argValue`",
+        "",
+        "---",
+        "",
+        "## 6. 引入第三方库与静态资源",
+        "",
+        "### 6.1 通过 CCDK 注入第三方 JS（示例：jQuery）",
+        "",
+        "> 平台提供统一 JS 注入能力 `CCDK.CCLoad.loadJs`，无需将第三方库打包进组件。",
+        "",
+        "```vue",
+        "<template>",
+        "  <div></div>",
+        "</template>",
+        "",
+        "<script>",
+        "// 在组件加载前引入 jQuery",
+        "window.$CCDK.CCLoad.loadJs(",
+        "  \"https://cdn.bootcdn.net/ajax/libs/jquery/3.6.4/jquery.js\"",
+        ");",
+        "",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\",",
+        "        // 启动加载，确保第三方库在应用启动时就注入",
+        "        loadModel: \"start\"",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  }",
+        "};",
+        "</script>",
+        "```",
+        "",
+        "注意：",
+        "- 建议优先使用平台已集成的库；如需外部 CDN，要考虑可用性与合规性。",
+        "",
+        "### 6.2 使用静态资源图片",
+        "",
+        "1. 在「开发者控制台 → 静态资源」中新建并上传图片  ",
+        "2. 在列表中复制该资源的访问地址  ",
+        "3. 在组件中直接使用该 URL：",
+        "",
+        "```vue",
+        "<template>",
+        "  <div>",
+        "    <img",
+        "      style=\"width: 800px; height: 800px\"",
+        "      src=\"https://res.lightning.cloudcc.cn/staticResource/org08f84e9c0566eaf0c/202309/16945042351857583.png\"",
+        "    />",
+        "  </div>",
+        "</template>",
+        "",
+        "<script>",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\",",
+        "        loadModel: \"start\"",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  }",
+        "};",
+        "</script>",
+        "```",
+        "",
+        "---",
+        "",
+        "## 7. 日志上报：CCLog（Info / Error）",
+        "",
+        "> 为方便排查线上问题，平台提供 `CCDK.CCLog` 上报日志到监控平台，支持 Info 和 Error 等级。",
+        "",
+        "### 7.1 上报 Info 日志",
+        "",
+        "```vue",
+        "<template>",
+        "  <div>",
+        "    <el-button @click=\"reportInfo\">上报 Info 日志</el-button>",
+        "  </div>",
+        "</template>",
+        "",
+        "<script>",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\",",
+        "        loadModel: \"start\"",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  },",
+        "  methods: {",
+        "    reportInfo() {",
+        "      const logInfo = {",
+        "        infoType: \"debug\",     // 日志级别，如 debug/info 等",
+        "        serviceName: \"my app\", // 服务/组件名称",
+        "        infoMessage: \"描述信息\" // 描述内容",
+        "      };",
+        "      window.$CCDK.CCLog.reportInfoLog(logInfo);",
+        "    }",
+        "  }",
+        "};",
+        "</script>",
+        "```",
+        "",
+        "### 7.2 上报 Error 日志",
+        "",
+        "```vue",
+        "<template>",
+        "  <div>",
+        "    <el-button @click=\"reportError\">上报 Error 日志</el-button>",
+        "  </div>",
+        "</template>",
+        "",
+        "<script>",
+        "export default {",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\",",
+        "        loadModel: \"start\"",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  },",
+        "  methods: {",
+        "    reportError() {",
+        "      const logInfo = {",
+        "        serviceName: \"my app\",",
+        "        errorMessage: \"错误描述信息\",",
+        "        printStackTraceInfo: \"堆栈信息或补充说明\"",
+        "      };",
+        "      window.$CCDK.CCLog.reportErrorLog(logInfo);",
+        "    }",
+        "  }",
+        "};",
+        "</script>",
+        "```",
+        "",
+        "### 7.3 查看上报日志",
+        "",
+        "1. 登录 CloudCC 系统  ",
+        "2. 点击右上角头像 → 进入「开发者平台」  ",
+        "3. 进入对应日志菜单查看上报记录",
+        "",
+        "---",
+        "",
+        "## 8. 组件销毁逻辑与性能",
+        "",
+        "> 由于自定义组件的特殊渲染逻辑，**必须控制组件销毁时机**，避免长时间使用导致内存不断上涨（OOM）。",
+        "",
+        "### 8.1 默认销毁策略",
+        "",
+        "- 组件进入后台（用户不可见）时开始倒计时  ",
+        "- 倒计时结束后组件被销毁，默认销毁时间约为 20 分钟（具体以平台当前版本为准）",
+        "",
+        "### 8.2 自定义销毁时间",
+        "",
+        "在安全信息的高级配置中设置 `destroyTimeout`，所有打包组件共享该配置（单位：毫秒）：",
+        "",
+        "```json",
+        "\"devConsoleConfig\": {",
+        "  \"destroyTimeout\": 1200000",
+        "}",
+        "```",
+        "",
+        "建议：",
+        "- 对于占用资源较高的组件（如大量 ECharts 实例、轮询等），适当缩短销毁时间，并在组件卸载前主动释放资源。",
+        "",
+        "---",
+        "",
+        "## 9. 扩展属性（propObj / propOption）与动态配置",
+        "",
+        "> 通过扩展属性，组件可以变成「可配置组件」，由页面编辑器在属性面板中采集配置数据，再由组件使用这些配置渲染不同效果。",
+        "",
+        "### 9.1 基本结构",
+        "",
+        "```js",
+        "data() {",
+        "  return {",
+        "    componentInfo: {",
+        "      component: \"cloudcc-demo-a\",",
+        "      compName: \"cloudcc-demo-a\",",
+        "      compDesc: \"组件描述信息\",",
+        "      loadModel: \"start\"",
+        "    },",
+        "    // 扩展属性对象：存放实际属性值",
+        "    propObj: {",
+        "      // 自定义属性时，必须写入 id",
+        "      id: \"\",",
+        "      src: \"\"",
+        "    },",
+        "    // 扩展属性配置：定义属性在页面编辑器中的展示形式",
+        "    propOption: {",
+        "      src: {",
+        "        lable: \"请输入图片地址\",",
+        "        type: \"input\"",
+        "      }",
+        "    },",
+        "    isLock: false",
+        "  };",
+        "}",
+        "```",
+        "",
+        "### 9.2 在组件中接收扩展属性（elePropObj）",
+        "",
+        "页面编辑器会将配置好的属性通过 `props.elePropObj` 传入组件：",
+        "",
+        "```vue",
+        "<template>",
+        "  <div>",
+        "    <img style=\"width: 800px; height: 800px\" :src=\"elePropObj.src\" />",
+        "  </div>",
+        "</template>",
+        "",
+        "<script>",
+        "export default {",
+        "  props: {",
+        "    // 自定义属性对象",
+        "    elePropObj: {",
+        "      type: Object,",
+        "      default: () => ({})",
+        "    }",
+        "  },",
+        "  data() {",
+        "    return {",
+        "      componentInfo: {",
+        "        component: \"cloudcc-demo-a\",",
+        "        compName: \"cloudcc-demo-a\",",
+        "        compDesc: \"组件描述信息\",",
+        "        loadModel: \"start\"",
+        "      },",
+        "      propObj: {",
+        "        id: \"\",",
+        "        src: \"\"",
+        "      },",
+        "      propOption: {",
+        "        src: {",
+        "          lable: \"请输入图片地址\",",
+        "          type: \"input\"",
+        "        }",
+        "      },",
+        "      isLock: false",
+        "    };",
+        "  }",
+        "};",
+        "</script>",
+        "```",
+        "",
+        "### 9.3 `propOption` 常用类型一览",
+        "",
+        "> 所有配置写在 `data` 的 `propOption` 中，平台会根据 `type` 决定渲染何种采集控件。",
+        "",
+        "- **输入框**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"请输入图片地址\",",
+        "    type: \"input\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **日期选择器**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"日期选择器\",",
+        "    type: \"date\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **时间选择器**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"时间选择器\",",
+        "    type: \"time\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **图标选择器**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"图标\",",
+        "    type: \"icon\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **颜色选择器**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"颜色\",",
+        "    type: \"color\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **下拉框**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"下拉框\",",
+        "    type: \"option\",",
+        "    options: [",
+        "      { value: \"fill\", label: \"fill\" },",
+        "      { value: \"contain\", label: \"contain\" }",
+        "    ]",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **切换器（单选按钮组）**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"切换器\",",
+        "    type: \"radioButton\",",
+        "    options: [",
+        "      { label: \"default\", value: \"default\" },",
+        "      { label: \"button\", value: \"button\" }",
+        "    ]",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **开关**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"开关\",",
+        "    type: \"switch\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **代码编辑框**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"代码编辑框\",",
+        "    type: \"code\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "- **提示信息（带链接）**：",
+        "",
+        "```js",
+        "propOption: {",
+        "  src: {",
+        "    lable: \"提示信息\",",
+        "    type: \"word\",",
+        "    link: \"https://www.baidu.com\"",
+        "  }",
+        "}",
+        "```",
+        "",
+        "---",
+        "",
+        "## 10. 自定义事件（events / eventsOption）",
+        "",
+        "> 通过扩展事件属性，可以让页面配置层注入一段可执行代码，在组件生命周期中回调，适用于少量灵活逻辑（需非常注意安全性与维护成本）。",
+        "",
+        "### 10.1 数据结构示例",
+        "",
+        "```js",
+        "data() {",
+        "  return {",
+        "    componentInfo: {",
+        "      component: \"test-plugin\",",
+        "      compName: \"test-plugin\",",
+        "      compDesc: \"Component description information\"",
+        "    },",
+        "    events: {",
+        "      // 自定义事件：在 created 生命周期执行",
+        "      myCreated: `function created(self) {",
+        "        // self 即 this，为当前组件的 Vue 实例",
+        "      }`",
+        "    },",
+        "    eventsOption: {",
+        "      myCreated: {",
+        "        lable: \"label.dev.created\",",
+        "        type: \"code\"",
+        "      }",
+        "    },",
+        "    isLock: false",
+        "  };",
+        "}",
+        "```",
+        "",
+        "### 10.2 在生命周期中执行自定义事件",
+        "",
+        "```js",
+        "created() {",
+        "  // 将字符串转为函数（eval 需谨慎使用，仅在可信环境启用）",
+        "  const myCreated = eval(\"(false || \" + this.eleEventObj.myCreated + \")\");",
+        "  myCreated(this);",
+        "}",
+        "```",
+        "",
+        "注意：",
+        "- 此模式依赖 `eval`，有潜在安全风险，仅适用于内部受控场景",
+        "- 强烈建议对传入的代码做严格访问控制与审计",
+        "",
+        "---",
+        "",
+        "## 11. componentInfo 配置说明",
+        "",
+        "### 11.1 标准配置",
+        "",
+        "```js",
+        "componentInfo: {",
+        "  // 组件唯一标识，全局唯一：",
+        "  // 1. 必须使用小写英文",
+        "  // 2. 由两个及以上单词组成",
+        "  // 3. 使用 \"-\" 分隔",
+        "  component: \"cloudcc-demo-01\",",
+        "",
+        "  // 组件名称，在页面编辑器中显示",
+        "  compName: \"演示使用组件\",",
+        "",
+        "  // 组件描述信息",
+        "  compDesc: \"组件描述信息\"",
+        "}",
+        "```",
+        "",
+        "### 11.2 高级配置：loadModel",
+        "",
+        "```js",
+        "componentInfo: {",
+        "  // 加载模式，不写时默认 \"lazy\"",
+        "  // lazy：懒加载，仅在自定义页面实际加载组件时才加载",
+        "  // start：启动加载，在应用启动时即加载组件",
+        "  loadModel: \"lazy\"",
+        "}",
+        "```",
+        "",
+        "推荐：",
+        "- 布局、全局脚本、埋点类组件可使用 `start`",
+        "- 普通展示组件默认使用 `lazy`",
+        "",
+        "---",
+        "",
+        "## 12. 进阶说明与架构提示",
+        "",
+        "- 自定义组件的底层实现基于 Web Components，以支持跨框架组件开发与复用。",
+        "- 组件编译时，以组件入口文件作为构建入口，而非整个模板项目的 `main.js`：",
+        "  - `main.js` 作为本地运行模板项目的入口，可按需调整",
+        "  - 组件发布时，仅与组件入口及其依赖相关",
+        "- 引入第三方库时：",
+        "  - 优先使用平台统一注入方式（如 `CCDK.CCLoad.loadJs`）",
+        "  - 避免把大体积库直接打包进组件，减小发布包体积，提高加载性能",
+        "",
+        "---",
+        "",
+        "## 13. 自定义组件开发 Checklist",
+        "",
+        "- [ ] 组件文件名与 `componentInfo.component` 命名符合规范（小写 + `-` 分隔，全局唯一）",
+        "- [ ] 样式默认使用 `lang=\"scss\" scoped`，避免样式污染",
+        "- [ ] 使用平台提供的 `CCDK` 能力调用后端、自定义类、日志上报等，不手写接口 URL",
+        "- [ ] 如需第三方库，优先使用 `CCLoad.loadJs` 或平台已集成的库",
+        "- [ ] 合理设置 `loadModel`（`lazy`/`start`），避免不必要的启动时加载",
+        "- [ ] 如使用 ECharts/定时器/监听等，注意在组件销毁时释放资源",
+        "- [ ] 合理使用 `propObj` / `propOption` / `elePropObj` 提升组件可配置性",
+        "- [ ] 如启用 `events` 动态代码，确保仅在可信场景使用，并有审计与限制",
+        "- [ ] 发布前在本地 `npm run serve` 完整验证主要功能与交互",
+        "",
+    ];
+
+    const base = lines.join("\n");
+    const ccdkPath = path.join(__dirname, "..", "api", "ccdk-sdk.md");
+    let ccdkContent = "";
+    try {
+        ccdkContent = fs.readFileSync(ccdkPath, "utf8");
+    } catch (e) {
+        ccdkContent = `# CloudCC 前端 SDK（cloudcc-ccdk）使用指南\n\n（未找到文件：${ccdkPath}）\n`;
+    }
+
+    return [
+        base,
+        "",
+        "---",
+        "",
+        "## 附录：CCDK SDK 速查",
+        "",
+        "> 来源：`src/api/ccdk-sdk.md`",
+        "",
+        ccdkContent.trim(),
+        "",
+    ].join("\n");
+}
+
+function doc() {
+    const content = generateFullMarkdownDoc();
+    console.log(content);
+    return content;
+}
+
+// 兼容旧调用方：仍提供同名入口（但都返回全量文档）
+doc.getEditGuide = doc;
+
+module.exports = doc;