Mars3D开发者中心

外观

使用skill

2901字约10分钟

2026-05-28

什么是 mars3d-skill？

mars3d-skill是专门为Mars3D平台使用打造的 AI 辅助技能包，能帮你解决项目开发、集成、调试中的各类问题（比如地图空白、打包失败、API 使用错误等），尤其适配 Vue/ES5 技术栈和Vue通用项目模版(widget 机制)，让 AI 生成的代码更贴合 Mars3D 官方规范和工程最佳实践。

主要能力

  • 分析和修改 Mars3D 项目代码。
  • 排查 npm、静态文件、CDN 等 Mars3D 集成问题。
  • 处理 mars3d-cesium、Cesium 资源路径、地图空白、打包失败等常见问题。
  • 根据 mars3d.d.ts 和官方 API 页面确认 class、method、option 的正确用法。
  • 支持 Mars3D Vue widget 机制经验：widget-store.ts、index.vue、map.ts、useLifecycle(mapWork)。
  • 记录 Vue 工程实践：页面数据只保存业务状态和 graphic id，不把 Mars3D/Cesium 对象放进深度响应式状态。
  • 提供常用代码模式，例如 GraphicLayer、startDraw、centerPoint、layer cleanup 等。

主要文件及目录说明

  • ./SKILL.md 是 skill 入口，负责描述触发条件、工作流程和 reference 选择规则。
  • /references/ 中存放按需加载的经验文档。文档采用“中文经验说明 + 英文 API 术语”的形式，保留 Mars3D、GraphicLayer、startDraw、centerPoint、widget-store.ts 等关键术语，便于和代码、类型声明、官方 API 对齐。

一、准备工作及环境搭建

如果您电脑已有Claude Code或Codex等skill，请跳过此步骤。

下面讲解的是Claude Code中使用skill进行举例，Codex中使用差异请参看下面的第五节。

Claude Code 是 Anthropic 公司基于 Claude 大模型打造的 AI 编程智能体，主打深度理解项目、终端原生工作流。

1. 安装Claude Code

安装Claude Code，安装时无需注册Claude Code账号，而是在后续步骤中配置使用DeepSeek。

按 win+R 键，左下角输入cmd，点击回车，输入命令：

  npm install -g @anthropic-ai/claude-code@2.1.153

提示

截至2026-5-30，最新版本的2.1.156，有国产模型无法使用的问题,所以指定安装2.1.153版本。

claude-npm-install

claude-npm-install1

此时直接输入claude 会提示错误，直接关闭即可。

更多安装方式参考： https://code.claude.com/docs/zh-CN/quickstart#native-install-recommendedhttps://code.claude.com/docs/zh-CN/setup#windows-powershell

2. 安装CC Switch

安装CC Switch，我们通过CC Switch配置使用国产模型

首先到官方地址打开后找到下图，单击链接下载

cc-switch.jpg

安装完成后，双击桌面快捷方式图标启动

cc-switch1.jpg

点击箭头处按钮

cc-switch2.jpg

选择DeepSeek

cc-switch3.jpg

滑动到下方，点击获取API key，会跳转到deepseek官网，需要注册一个账号才能获取到key

cc-switch4.jpg

按照下面流程可以创建一个key，调用api会产生token费用（deepseek官方收取），建议按需充值。回到cc-switch 填写刚刚复制的key

cc-switch5.jpg

接着按需配置，建议勾选禁止自动升级，新版本可能会无法使用国内模型，点击确定

cc-switch6.jpg

点击启用

cc-switch7.jpg

3. 使用Cluade Code

重新打开Cluade Code终端，输入claude，直接点击回车，按照默认配置就能使用。

cc-switch8.jpg

输入你好，如果发现下面的错误，说明当前版本高了，选择退回版本即可。

cc-switch9.jpg

提示

截至2026-5-30，最新版本的2.1.156，有国产模型无法使用的问题,所以指定安装2.1.153版本。

到这一步，Claude Code的准备工作已经完成。

二、准备业务系统项目

下面我们以 mars3d-vue-project项目为例做讲解，实际项目开发中，请使用自己的项目即可。

请参考通用项目模版教程下载好项目并已成功运行。

三、集成mars3d-skill到项目

1.下载mars3d-skill

下载代码

git clone https://github.com/marsgis/mars3d-skill.git
  • Gitee：国内码云，下载速度快些。
git clone https://gitee.com/marsgis/mars3d-skill.git

2. 把mars3d-skill复制到项目指定目录

(1) 找到你的 Mars3D 项目根目录（比如 D:\mars3d-vue-project\）；

(2) 在项目根目录下，依次新建文件夹：.claude → skills（注意 .claude 前面有个点）,完成后目录为D:\mars3d-vue-project\.claude\skills\；

(3) 把下载好的 mars3d-skill 文件夹，完整复制到 .claude/skills 目录下。

最终你的项目结构应该是这样：

  • D:\mars3d-vue-project\
    • .claude
      • skills
        • mars3d-skill
          • SKILL.md
          • agents
            • openai.yaml
          • references
            • api-errors.md
            • integration.md
            • ...（其他参考文档）
    • src
      • …
    • package.json
    • ...（项目其他文件）

3.启动 Claude Code 并使用 skill

(1) 打开 Claude Code，并确保当前工作目录是你的 Mars3D 项目根目录；

(2) 在输入框中，以 /mars3d-skill 开头输入一个测试需求看看功能是否正常，比如：

/mars3d-skill 帮我分析这个 Mars3D Vue 项目是否使用 widget 机制

Claude Code 的调用名/mars3d-skill 来自skill目录名

(3) Claude Code 也会根据你的需求自动加载该 skill，无需手动选择。

claude使用skill流程

四、根据实际需求输入skill指令

后续更加您实际需求，按需输入skill指令，比如：

/mars3d-skill 帮我判断项目是否使用 Mars3D Vue widget 机制
/mars3d-skill 帮我写一个按钮，点击后在地图上标绘点，表格记录并支持删除

下面介绍一个开发需求，假设我们收到领导安排的一个开发任务需求：

任务需求

在工具栏加上一个“坐标定位”菜单按钮，点击该菜单之后会出现一个widget弹窗， 这个弹窗中上面是一个按钮，下面有一个表格，点击按钮之后可以在地图上标绘。

claude-code-project1.jpg

1.输入指令

分析需求，弄清楚需求的细节

帮我使用这个skill, 在D:\mars3d-vue-project\src\widgets\basic\toolbar\index.vue 在这个文件中的这段代码
    children: [
        { name: "坐标定位", icon: "local", widget: "location-point" }
    ]，加上一个按钮，点击之后会出现一个弹窗，这个弹窗中上面是一个按钮，下面是一个表格。点击按钮之后可以在地图上标绘
  点，每标绘一个点，就会在表格中增加这个点的记录，每个记录后面有一个删除按钮，点击删除，记录从表格中删除同时地图上的点
  也会被删除

输入/mars3d-skill 后面加上前面的提示词

claude-code-project2.jpg

2.按需调整细节代码

等待运行完成之后，可以看见有4个文件被修改了

claude-code-project3.jpg

红框上下两个文件修改的不多，简单看一下

claude-code-project4.jpg

claude-code-project5.jpg

红框中的index.vue文件有一个明显的bug, 手动修改一下

claude-code-project6.jpg

还有一个map.ts，代码基本符合需求，不用修改

claude-code-project7.jpg

完成代码如下

<template>
  <mars-dialog title="图上标绘" icon="hand-painted-plate" width="500" top="60">
    <div class="control-btn">
      <mars-button @click="drawPoint">点击标绘</mars-button>
    </div>

    <mars-table :data-source="tableData" :columns="columns" :pagination="false" size="small" row-key="id">
      <template #bodyCell="{ column, record }">
        <template v-if="column.dataIndex === 'index'">
          {{ tableData.indexOf(record) + 1 }}
        </template>
        <template v-if="column.dataIndex === 'action'">
          <a-popconfirm title="确定删除该点?" @confirm="deletePoint(record)">
            <a-button type="link" danger size="small">删除</a-button>
          </a-popconfirm>
        </template>
      </template>
    </mars-table>
  </mars-dialog>
</template>

<script setup lang="ts">
import { ref, onUnmounted } from "vue"
import useLifecycle from "@mars/common/uses/use-lifecycle"
import { useWidget } from "@mars/common/store/widget"
import * as mapWork from "./map"

// 取消工具栏高亮
import { onUnmounted } from "vue"

useLifecycle(mapWork)
const { updateWidget } = useWidget()
onUnmounted(() => {
  updateWidget("toolbar", "point-draw")
})

interface PointRow {
  id: string
  lng: string
  lat: string
  alt: string
}

const tableData = ref<PointRow[]>([])

const columns = [
  { title: "序号", dataIndex: "index", width: 60 },
  { title: "经度", dataIndex: "lng", ellipsis: true },
  { title: "纬度", dataIndex: "lat", ellipsis: true },
  { title: "高程", dataIndex: "alt", width: 80 },
  { title: "操作", dataIndex: "action", width: 80 }
]

async function drawPoint() {
  await mapWork.startDrawPoint()
}

// 监听绘制完成事件
mapWork.eventTarget.on("pointDrawn", (event: any) => {
  tableData.value.push(event.row)
})

function deletePoint(row: PointRow) {
  mapWork.removePoint(row.id)
  tableData.value = tableData.value.filter((item) => item.id !== row.id)
}
</script>

<style lang="less" scoped>
.control-btn {
  margin-bottom: 10px;
}
</style>
import * as mars3d from "mars3d"

let map: mars3d.Map
let graphicLayer: mars3d.layer.GraphicLayer

export const eventTarget = new mars3d.BaseClass()

export function onMounted(mapInstance: mars3d.Map): void {
  map = mapInstance
  graphicLayer = new mars3d.layer.GraphicLayer({ name: "标绘点" })
  map.addLayer(graphicLayer)
}

export function onUnmounted(): void {
  graphicLayer?.clear()
  if (graphicLayer && map) {
    map.removeLayer(graphicLayer, true)
  }
  graphicLayer = undefined as any
  map = undefined as any
}

export async function startDrawPoint() {
  const graphic = await graphicLayer.startDraw({
    type: "point",
    style: {
      color: "#ff4d4f",
      pixelSize: 10,
      outlineColor: "#ffffff",
      outlineWidth: 2
    }
  })

  const point = graphic.centerPoint
  point.format()

  const row = {
    id: String(graphic.id),
    lng: mars3d.Util.formatNum(point.lng, 6),
    lat: mars3d.Util.formatNum(point.lat, 6),
    alt: mars3d.Util.formatNum(point.alt, 2)
  }

  eventTarget.fire("pointDrawn", { row })
}

export function removePoint(id: string) {
  const graphic = graphicLayer.getGraphicById(id)

  if (graphic) {
    graphicLayer.removeGraphic(graphic, true)
  }
}

现在绘制已经实现了，但是删除还有问题，点击删除，发现没有反应，查看代码，a-popconfirm没有引入，我们可以手动修改，也可以让claude code帮我们修改

claude-code-project8.jpg

claude-code-project9.jpg

如果有其他修改，也可以像这样直接Claude Code进行修改

3.最终效果

这样我们就借助AI快速完成了一个开发需求，开发效率提升非常明显。

claude-code-project10.jpg

五、在 Codex 中使用 （可选）

如果您不用Claude Code，而是使用Codex时，也可以使用Codex进行开发，只是存放目录与调用命令不同。

对比项Codex（OpenAI）Claude Code（Anthropic）
skill 目录\.agents\skills\\.claude\skills\
调用命令$mars3d-skill/mars3d-skill
开发公司OpenAIAnthropic
核心模型GPT/o 系列代码专项版Claude Sonnet/Opus/Haiku
运行特点云端沙盒、并行多任务、安全严格本地终端优先、深度项目理解
适合人群全平台、多任务、注重安全习惯命令行、大型项目、复杂调试
token 消耗相对更低、更精简内容更详细，消耗偏高
生态侧重ChatGPT+云端工程终端+本地项目+Skill 扩展

1.存放目录目录名不同

在项目根目录下，依次新建文件夹：.agents → skills（注意 .agents 前面有个点）,完成后目录为D:\mars3d-vue-project\.agents\skills\；

最终你的项目结构应该是这样（对照看，确保没错）：

  • D:\mars3d-vue-project\
    • .agents
      • skills
        • mars3d-skill
          • SKILL.md
          • agents
            • openai.yaml
          • references
            • api-errors.md
            • integration.md
            • ...（其他参考文档）
    • src
      • …
    • package.json
    • ...（项目其他文件）

2. 调用命令不同

在 Codex 的输入框中，以 $mars3d-skill 开头输入skill指令，比如：

$mars3d-skill 帮我排查项目 npm run build 后地图空白的问题
$mars3d-skill 帮我新增一个 Mars3D 按钮，点击后在地图上标绘点并记录到表
$mars3d-skill 帮我新增一个 Mars3D widget，点击按钮后在地图上绘制点，并把点记录同步到表格

Codex的调用名$mars3d-skill来自 SKILL.md 里的 name: mars3d-skill

codex使用步骤

常见问题解答

Q1：复制文件夹后，AI 没识别到 skill 怎么办？

  • 检查文件夹路径是否正确（比如 Codex 是 .agents/skills/mars3d-skill，Claude 是 .claude/skills/mars3d-skill）；
  • 确保 mars3d-skill 文件夹里包含 SKILL.md 和 references 目录，不要只复制单个文件；
  • 重启 Codex/Claude Code，并重进项目目录。

Q2：使用 skill 会额外收费吗？

  • skill 本身免费，AI 平台（Codex/Claude Code）会按 token 消耗计费（比如 Claude Code 用 deepseek-v4-flash 模型，三次测试仅花费 0.22 元，费用受需求难度影响）。

价格

Q3：skill 能解决哪些问题？

  • 排查 npm 安装、CDN / 静态文件集成问题；
  • 解决地图空白、打包失败、API 调用报错；
  • 开发 Mars3D Vue widget、标绘点 / 线 / 面、图层管理等功能；
  • 规范 Vue 项目中 Mars3D 对象的使用方式（避免响应式坑）。