做鸿蒙开发这两年多我发现自己有一个很奇怪的习惯转换DevEco Studio 一直开着写代码的时候却越来越依赖终端里那个黑框框。起因很简单DevEco Code 作为 IDE 内置的 AI 辅助确实做到了开箱即用但一旦进入复杂点的页面重构、多文件联动修改它的表现就有点力不从心。后来我把 Claude Code 接进了鸿蒙工程通过 MCP、Skill、CLAUDE.md 三个层面的配置硬是把这条通用 AI 工具链变成了一个熟悉 ArkTS、懂 ArkUI、还会自己跑构建看日志的鸿蒙开发助手。这篇就是完整的实战记录。先说清楚这篇适合谁。如果你正在用 DevEco Studio 写鸿蒙应用每天的主要产出是entry/src/main/ets下面的页面代码同时对 DevEco Code 的生成质量有点不满想试试通用 AI 编程工具能不能做同样的活又或者你已经听说 Claude Code 很火但对 MCP、Skill、CLAUDE.md 这些名词还是一头雾水那么这篇文章正好对得上你的需求。我会从零开始把我验证过的配置方法、踩过的坑、最后的验证清单全部摊开讲你可以直接照着抄。1. 内容整体设计与思路拆解1.1 为什么要把 DevEco Code 换成 Claude Code先客观地说一句DevEco Code 并不是不能用。它对鸿蒙工程的上下文感知是天然的优势毕竟原生跑在 DevEco Studio 里SDK 路径、模块结构、资源目录这些信息都是现成的用来生成一个基础页面、补一个组件属性、改一段样式完全够用。它的定位更接近“IDE 内置助手”强调的是低摩擦你不需要额外维护任何配置文件打开就能用。但当你开始追求更高效率尤其是从“写单文件”变成“改整个功能模块”的时候差距就出来了。我举个自己的例子上个月要做一个多页签的个人中心页面涉及Index.ets、ProfilePage.ets、SettingsPage.ets三个文件之间的状态联动还有路由配置、oh-package.json5依赖变更。这种跨文件的改动DevEco Code 的生成结果经常是“局部正确、整体断裂”它给出的代码放在当前文件里没问题跟其他文件拼起来就缺东少西。Claude Code 的做法不一样它在生成之前会先批量读一遍相关文件自己梳理模块依赖关系再动手改的时候跨文件的一致性明显高出一个层级。当然这里说的“对等接入”不是要证明谁能彻底替代谁而是把 Claude Code 改造成一个能无缝参与鸿蒙开发的外挂 AI。DevEco Code 继续留在 IDE 里处理即时问答和轻量补全Claude Code 在终端里承担复杂任务和自动化流程两边各干各擅长的部分。比如 AI 写代码DevEco Code 负责“这一行怎么写”Claude Code 负责“这个模块怎么设计”两者并不冲突。1.2 整体架构MCP Skill CLAUDE.md 各管什么我第一次接触这三个名词的时候也绕了很久其实它们的职责非常清晰就是一个三层的配合关系。CLAUDE.md 管的是“认知层”。它放在项目根目录Claude Code 每次启动会话都会自动读取相当于一份给新成员看的项目入职手册。你在里面写清楚项目是干什么的、代码放哪里、有什么编码规范、常用命令是什么AI 在回答任何问题前就已经掌握了这些背景。这层不解决具体操作问题只解决“懂不懂行”的问题。Skill 管的是“方法层”。它是一套技能包每个 Skill 就是一个带说明文档的指令模板放在.claude/skills目录下。Skill 解决的是“会不会干活”的问题比如“生成符合团队规范的 ArkTS 页面”“根据崩溃日志定位状态管理问题”这些都是需要特定步骤的操作流你把它固化成一个 SkillAI 下次遇到同类任务就会按标准流程执行而不是天马行空自由发挥。MCP 管的是“行动层”。它是 Model Context Protocol 的缩写通俗讲就是把外部能力封装成标准接口让 AI 能在对话过程中直接调用真实工具。鸿蒙开发里最典型的用法是把构建命令、日志抓取、依赖查询这些操作封装成 MCP ServerAI 写完成代码后可以自己触发一次编译把报错拉回来分析再继续改。这层解决的是“能不能动手”的问题。一句话总结这套架构CLAUDE.md 让 AI 理解项目Skill 让 AI 掌握方法MCP 让 AI 调用工具。三层叠起来Claude Code 才从“一个会写代码的语言模型”变成“一个真正的鸿蒙开发助手”。1.3 方案选型为什么选用 CLI 接入而不是 IDE 插件我知道市面上也有各种把 Claude 能力搬进 IDE 的插件方案所以这里把选型逻辑讲清楚。首先Claude Code 本身就是以 CLI 工具的形式发布的跑在终端里天然适合作为自动化链路的一环。鸿蒙工程的构建、签名、日志抓取全部有对应的命令行工具比如hvigorw、hdcCLI 形态的 AI 助手可以直接在同一个终端环境里调用这些命令不需要考虑 IDE 插件和外部进程之间的通信障碍。其次CLI 形态更容易做版本隔离和团队统一。我可以在项目根目录用.mcp.json统一声明 MCP Server用.claude/skills统一维护团队技能库用根目录的CLAUDE.md统一注入项目规范整套配置都天然地跟代码仓库一起走。新人克隆仓库一键启动 Claude Code拿到的就是跟团队一致的 AI 开发环境。IDE 插件的配置很难做到这种程度的“配置即代码”。另外一个现实因素是迭代速度。Claude Code 本身的更新节奏很快新功能不断往上加CLI 版本跟进最及时。绑死在某个 IDE 插件上反而要等插件适配体验上总会慢半拍。2. 核心细节解析与实操要点2.1 先搞懂 MCP 在鸿蒙场景下的具体用法MCP 这个协议听起来很抽象拆开来看核心就三件事服务器、工具、资源。服务器是一个独立进程负责跟外部环境打交道工具是服务器暴露出来的可执行动作比如“触发一次 HAP 构建”“查询 SDK 路径”“拉取最新崩溃日志”资源是服务器暴露给 AI 的上下文数据比如“当前工程完整的模块依赖树”。Claude Code 作为客户端通过标准协议跟服务器通信需要的时候自动调用工具、读取资源不用我们手工在提示词里塞命令细节。我在鸿蒙工程里最常用的几个 MCP Server整理成表格供对照MCP Server暴露能力典型使用场景deveco-command封装 hvigorw 构建、签名、预览命令AI 改完代码后自动编译验证拉报错信息回来改oh-package-mcp读取和修改 oh-package.json5 依赖声明AI 识别到需要第三方库时自动补依赖hdc-logcat-mcp抓取模拟器或真机运行日志让 AI 根据异常堆栈反推问题点file-system-mcp限制范围内的文件读写保证 AI 只操作工作目录避免误伤系统文件配置 MCP Server 有两种方式用户级和项目级。用户级通过claude mcp add命令注册好处是全局可用适合配置通用工具项目级则在.mcp.json里声明随仓库走适合配置跟具体工程绑定的工具。我做鸿蒙开发时强烈建议用项目级配置因为hvigorw的路径、SDK 版本这些信息跟项目强相关换了工程配置大概率不能复用写进仓库反而更方便。2.2 Skill 的目录结构与触发逻辑Skill 本质上是一套“带说明书的指令包”它的目录结构并不复杂~/.claude/skills/ arkts-page-generator/ SKILL.md templates/ basic-page.ets list-page.etsSKILL.md是整个 Skill 的入口里面要写清楚这个技能的名称、描述、使用场景和执行步骤。Claude Code 会根据用户提问的内容结合SKILL.md里description字段的语义描述来决定是否触发这个 Skill。所以写描述是一件非常重要的事情要具体、贴近用户说法不适合用大而空的词。我的一个实操心得是description里最好包含两到三个高频触发词。比如一个生成 ArkTS 页面的 Skill描述里就要明确出现“新增页面”“创建页面”“ArkTS 页面”这类表达。否则 AI 匹配不到触发条件Skill 就形同虚设。另外关于模板的颗粒度我踩过很大的坑。一开始我试图把完整页面所有逻辑都塞进模板结果生成出来的代码特别僵化动不动就是模板里的硬编码改起来比从零写还麻烦。后面调整策略模板只提供“骨架 关键片段”业务逻辑让 AI 根据需求动态生成灵活性和准确度都提升了很多。一个好的模板是约束结构而不是约束内容这句话放在 Skill 设计里尤其正确。2.3 CLAUDE.md 的核心写法从项目信息到编码规范CLAUDE.md 很容易被误用成一个“资料大全”我在初版本里塞进去的接口文档堆起来比项目代码还长结果 AI 的表现反而变差。后来我意识到CLAUDE.md 的定位是“注意力手册”只承载那些 AI 每次干活都必须知道的高频关键信息其他内容放到专门的文档目录里按需读取。我现在的写法固定分四块项目概览、目录结构、编码规范、常用命令。项目概览用两三句话交代工程类型、Stage 模型、目标 API 版本避免 AI 对项目环境做出离谱假设。目录结构标注核心代码路径特别是entry/src/main/ets下的页面和组件目录。编码规范重点写强制规则比如禁用any类型、状态变量声明要求、装饰器使用约定等。常用命令则把构建、预览、签名、日志抓取都列出来让 AI 知道去哪执行命令。写编码规范这部分要特别注意一个度。不是把团队内部所有 lint 规则都抄进去而是精选那些“AI 最容易犯且后果严重”的规则。比如 ArkTS 里状态管理的处理方式、资源引用的路径规则、页面路由注册要求这些写进去最划算。我之前还试过把代码格式化细节写进 CLAUDE.md比如缩进用几个空格事实证明完全没有必要反而浪费上下文空间。2.4 对等接入的验证指标怎么定聊完三个工具的细节还需要解决一个问题怎么判断“对等接入”真的成功了我给自己定了一套验证指标分享出来供参考。能力对等不应该只看“能生成代码”还要看是否能覆盖 DevEco Code 日常承担的核心任务。我列了六项第一能根据一句话需求生成一个注册了路由的 ArkTS 页面第二能正确处理State、Prop、Link父子组件数据联动第三改完代码会主动调用构建类 MCP 工具进行编译验证第四能通过 hdc 日志定位崩溃问题并给出修复路径第五在 CLAUDE.md 明示禁止any的情况下生成的代码不会出现any第六能按 Skill 模板生成固定结构的列表页同时填充真实业务逻辑。这六项全过了才说明工具链切换基本合格。我自己在项目里把这六项做成了每次接入新成员 AI 工具链时都要跑的“上岗测试”。有标准就有抓手不然凭感觉判断很容易出现“看着能用一上线就崩”的问题。3. 实操过程与核心环节实现3.1 环境准备安装 Claude Code 与 Node 版本避坑安装步骤本身不复杂但是有几个前提条件需要提前处理好。首先是 Node.js 环境Claude Code 对 Node.js 版本有最低要求太老的版本装了也起不来。我是用 nvm 管理 Node 版本的切到最新的 LTS 版本再操作这一步能避免后续很多未知报错。# 切换到较新的 Node.js LTS 版本 node -v npm -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证是否安装成功 claude --version # 进入鸿蒙工程目录并启动 cd ~/workspace/harmony-app claude第一次启动需要完成账号登录流程按命令行提示操作即可。登录成功后建议先不急着干活随便跑一个对话确认交互没问题再往下配置。我在这一步就遇到过安装成功但启动后进程异常退出的情况直接重新执行安装命令覆盖安装一次就恢复了。另外一个小建议Claude Code 的体验受 shell 环境的影响比较大如果你平时用的是定制过的 zsh 或者 PowerShell注意看看启动时的环境变量是否正常。有些临时别名或者代理类环境变量配置可能会干扰到子进程调用这也是后面容易出现“工具调不通”的根源之一。3.2 编写 CLAUDE.md一份可以直接改用的模板下面这份模板是从我实际项目中删减出来的保留了最核心的结构可以直接铺到你的鸿蒙工程根目录# HarmonyOS APP - ArkTS Development ## 项目概览 本项目是一个面向 HarmonyOS 手机的日常工具类应用采用 Stage 模型 目标 API 版本为 12主模块为 entry核心代码位于 entry/src/main/ets。 ## 目录结构 - entry/src/main/ets/entryability/ - Ability 生命周期相关 - entry/src/main/ets/pages/ - 页面代码使用 ArkUI 声明式语法 - entry/src/main/ets/common/ - 公共组件与工具方法 - entry/src/main/resources/ - 字符串、颜色等资源文件 ## 编码规范 - 使用 TypeScript 严格模式禁止使用 any - 页面组件使用 Component 和 Entry 装饰器文件名与组件名保持一致 - 状态管理优先使用 State、Prop、Link避免直接修改全局变量 - 单位使用 vp涉及像素转换时用 vp2px() 方法不要硬编码具体像素值 ## 常用命令 - 构建hvigorw assembleHap - 预览hvigorw --mode module -p productdefault preview - 签名hvigorw signHap - 日志hdc log -a -x写完第一件事不是急着开发而是在 Claude Code 里做一次“上岗提问”。比如问“这个项目的主入口 Ability 在哪个文件”如果它能准确回答entry/src/main/ets/entryability/下的文件说明 CLAUDE.md 已经被正确识别并生效了。如果答非所问优先检查文件编码和位置CLAUDE.md 一定放在项目根目录且不要用 BOM 头的 UTF-8 编码。3.3 配置一个常用的 ArkTS 页面生成 Skill在 Claude Code 里配置 Skill 的收益比大多数人想象中来得更快。我的第一个 Skill 就是页面生成器用了几周后又陆续加了日志分析、依赖检查等技能现在日常工作中有一半以上的重复流程都走的是 Skill。3.3.1 创建 SKILL.md先创建目录~/.claude/skills/arkts-page-generator/在里面新建SKILL.md--- name: arkts-page-generator description: 根据用户需求生成完整的 ArkTS 页面代码包含 Component、Entry 装饰器以及对应的组件布局和状态管理逻辑。 --- ## 使用场景 当用户需要进入一个新页面或者要求“新增一个某某页面”时使用本 Skill。 ## 执行步骤 1. 确认页面对应的路由配置在 main_pages.json 中注册 2. 根据页面类型选择模板basic-page.ets 或 list-page.ets 3. 在模板基础上填充业务状态变量优先使用 State 管理 4. 输出完整代码并同时给出需要在 oh-package.json5 中补充的依赖如有 5. 建议在 build() 方法内按区块添加结构注释3.3.2 添加模板文件在templates/目录下放一个基础页面模板basic-page.ets内容不需要太完整保留骨架就好Entry Component struct PageName { State message: string Hello HarmonyOS; build() { Column({ space: 12 }) { Text(this.message) .fontSize(20) .fontWeight(FontWeight.Bold) } .width(100%) .padding(16) } }这个模板故意不写复杂的业务代码只提供一个“页面该长什么样”的基准。AI 生成具体页面时会在这个基准上填充实际业务字段和布局既保证了结构统一又不会因为模板过度约束导致生成结果生硬。Skill 写好后在用户级~/.claude/skills/和项目级.claude/skills/各放一份。用户级的适合个人常用技能项目级适合团队在仓库里维护统一模板项目级优先级更高能覆盖用户级同名配置。3.4 接入 DevEco 相关 MCP Server这是整个接入方案里最花时间也是收益最大的一环。鸿蒙开发不像 Web 前端那样可以随便在浏览器里即时预览代码能不能编译、运行是否正常很多时候必须真实跑一次才知道。把构建和日志能力通过 MCP 暴露给 AIClaude Code 就能在修改代码后自己触发构建把报错拉回来分析再修改、再验证形成一个完整闭环。3.4.1 MCP Server 的最小实现我这里用一个封装了hvigorw调用的 MCP Server 举例核心逻辑就是通过 MCP 标准接口把命令行工具包一层import { Server } from modelcontextprotocol/sdk/server/index.js; const server new Server({ name: deveco-command, version: 0.1.0 }, { capabilities: { tools: { buildHap: { description: 构建 HAP 包, inputSchema: { type: object, properties: { module: { type: string, description: 模块名默认 entry } } } }, signHap: { description: 对构建产物签名, inputSchema: { type: object, properties: { hapPath: { type: string, description: HAP 文件路径 } } } } } } });这段代码只是示意真正落地时还需要处理工具执行输出、超时控制、日志截断等细节。MCP SDK 提供了完善的基础设施照着官方示例扩展工具即可难度不大。3.4.2 配置 .mcp.json推荐用项目级配置在工程根目录创建一个.mcp.json{ mcpServers: { deveco-command: { command: npx, args: [tsx, config/mcp/deveco-command-mcp/index.ts] }, hdc-logcat: { command: npx, args: [tsx, config/mcp/hdc-logcat-mcp/index.ts] } } }配置完成后在 Claude Code 里启动会话输入claude mcp list查看已连接的服务器。如果列表里能看到deveco-command和hdc-logcat且状态为 connected说明 MCP 层已经打通。这里多说一句.mcp.json放进仓库里随代码走团队里其他人克隆下来就能直接用不需要各自再注册一遍。如果发现其他成员拉取后 MCP 不生效优先检查 Node 依赖是否装齐这类 npx 启动的 Server 经常因为tsx未安装而静默失败。3.5 能力对等验证清单所有配置完成后的最后一步是跑一遍完整的验证。我自己的建议是不要凭感觉判断直接按下面清单逐项打勾生成一个新的 ArkTS 页面确认Entry/Component装饰器、.build()结构、页面路由注册全部正确用State和Prop实现一个父子组件数据联动示例验证状态管理符合规范修改代码后主动询问“帮我构建一下”确认 Claude Code 能自动触发 deveco-command MCP 工具完成编译故意制造一个空指针异常让 AI 通过 hdc 日志定位问题并给出修复建议在需求里明确提出“页面使用列表展示”确认 AI 触发 list-page Skill 而不是临时自由发挥观察整个会话中是否出现被 CLAUDE.md 明令禁止的写法如any类型六项全部通过后再把 Claude Code 投入到日常开发中。如果哪一项卡住了回看对应环节列表页不触发 Skill 就检查描述不主动构建就检查 MCP 配置出现any就检查 CLAUDE.md 是否被正确加载。大部分问题都能在这三个环节里找到答案。4. 常见问题与排查技巧实录4.1 Skill 没被触发先从描述词查起Skill 没被触发是我在接入初期遇到最频繁的问题明明写好了技能包AI 却像没看见一样。排查分三步先确认SKILL.md头部的description是否足够贴近用户的自然表达比如用户说“我要加一个设置页”而描述里只有“生成 ArkTS 页面”这种抽象短语匹配度就可能不够其次用claude skill list查看 Skill 是否被正确扫描到最后如果前两步没问题那就是提示词和描述之间的语义距离太远解决办法是往描述里多塞几个同义触发词。这段经历给我的启发是写 Skill 描述的时候要站在“用户会怎么说”而不是“技能能做什么”的角度去措辞。你要让 AI 在做意图匹配的时候能第一时间命中而不是靠它自己理解发散。4.2 CLAUDE.md 写太长导致上下文被稀释有人可能觉得 CLAUDE.md 写得越全越好我最初也是这样做的结果适得其反。把整个项目需求文档、接口协议、第三方库说明都塞进去之后Claude Code 每次会话都要带着这些冗长的背景信息注意力被大量无关内容稀释处理核心任务时反而变笨了。我的调整方案是只保留高频且关键的信息把其余内容移到项目docs目录需要时通过“读取文件”的方式动态加载。比如接口文档不会在 CLAUDE.md 里罗列而是告诉 AI“接口定义在docs/api.md涉及网络层修改前先读这个文件”。这样既保证信息可达又不会长期占用上下文窗口。4.3 构建类 MCP 工具超时hvigorw 构建 HarmonyOS 应用尤其是首次构建耗时可能超过一两分钟。而 MCP 工具默认的会话超时通常是几十秒这就导致 AI 调用构建工具后迟迟等不到结果最终判定工具调用失败。我的处理办法是把耗时操作改造成异步任务模式MCP Server 收到构建请求后先返回一个任务 ID随后在后台执行构建AI 拿到任务 ID 后通过轮询接口查询构建状态。这样即便构建耗时五分钟整个过程也不会因为超时被中断。如果不想搞得这么复杂也可以直接调大 MCP 客户端的超时阈值只是这样遇到真正卡死的任务时排查起来会更困难。4.4 子进程执行环境不一致Claude Code 在终端里启动后它执行 MCP 工具和命令时依赖的是当前 shell 的环境变量。如果你在.zshrc或 PowerShell profile 里配置了自定义路径、别名但 Claude Code 启动时继承的环境不完整就会出现“手动在终端里跑命令没问题AI 调工具却报找不到命令”的情况。解决方案是让 MCP Server 自己负责环境准备在 server 启动脚本里显式设置PATH不要依赖外层 shell 的默认环境。或者在 Claude Code 的配置里指定一个统一的环境变量文件。这样团队成员的机器配置不一样也不会影响工具链稳定性。4.5 上下文窗口被工具返回结果刷屏MCP 工具返回结果如果太大比如一次完整构建日志有几千行AI 的上下文窗口很快就被这些中间信息塞满导致后续对话质量急剧下降。最直观的表现是 AI 变得“健忘”刚分析完的代码转个身就忘了。我给构建类 MCP Server 增加了maxLines参数默认只回传最后 200 行日志AI 如果觉得内容不够可以显式请求更多。日志抓取类工具类似默认截断到错误堆栈部分。这个优化做完之后会话的可用长度明显变长AI 的连续推理能力也稳了很多是投入产出比非常高的一个调整。这次从 DevEco Code 切换到 Claude Code 的实战我前前后后折腾了两周多踩过的坑比预想的多但最后跑通时收获也远超预期。以前写一个稍复杂的列表页从新建文件到确认能编译怎么也要一个多小时现在把需求描述清楚Claude Code 生成骨架再手动调整几处数据格式整个流程基本压缩到二十分钟以内。最有价值的倒不是生成速度而是 MCP 接通以后AI 能自己构建、自己看报错、自己改代码这个正循环一旦跑起来生产力提升相当明显。如果你也正在做鸿蒙开发手头又想尝试通用 AI 编程工具我的建议是别一上来就追求把所有能力一次接完。先配好 CLAUDE.md让 AI 理解项目再写一个高频用到的 Skill让 AI 会干活最后再考虑用 MCP 接通构建和日志链路让 AI 能验证自己的产出。每一步都有即时反馈信心攒够了再扩展其他场景会从容得多。
鸿蒙开发实战：用Claude Code+MCP+Skill打造AI编程助手
做鸿蒙开发这两年多我发现自己有一个很奇怪的习惯转换DevEco Studio 一直开着写代码的时候却越来越依赖终端里那个黑框框。起因很简单DevEco Code 作为 IDE 内置的 AI 辅助确实做到了开箱即用但一旦进入复杂点的页面重构、多文件联动修改它的表现就有点力不从心。后来我把 Claude Code 接进了鸿蒙工程通过 MCP、Skill、CLAUDE.md 三个层面的配置硬是把这条通用 AI 工具链变成了一个熟悉 ArkTS、懂 ArkUI、还会自己跑构建看日志的鸿蒙开发助手。这篇就是完整的实战记录。先说清楚这篇适合谁。如果你正在用 DevEco Studio 写鸿蒙应用每天的主要产出是entry/src/main/ets下面的页面代码同时对 DevEco Code 的生成质量有点不满想试试通用 AI 编程工具能不能做同样的活又或者你已经听说 Claude Code 很火但对 MCP、Skill、CLAUDE.md 这些名词还是一头雾水那么这篇文章正好对得上你的需求。我会从零开始把我验证过的配置方法、踩过的坑、最后的验证清单全部摊开讲你可以直接照着抄。1. 内容整体设计与思路拆解1.1 为什么要把 DevEco Code 换成 Claude Code先客观地说一句DevEco Code 并不是不能用。它对鸿蒙工程的上下文感知是天然的优势毕竟原生跑在 DevEco Studio 里SDK 路径、模块结构、资源目录这些信息都是现成的用来生成一个基础页面、补一个组件属性、改一段样式完全够用。它的定位更接近“IDE 内置助手”强调的是低摩擦你不需要额外维护任何配置文件打开就能用。但当你开始追求更高效率尤其是从“写单文件”变成“改整个功能模块”的时候差距就出来了。我举个自己的例子上个月要做一个多页签的个人中心页面涉及Index.ets、ProfilePage.ets、SettingsPage.ets三个文件之间的状态联动还有路由配置、oh-package.json5依赖变更。这种跨文件的改动DevEco Code 的生成结果经常是“局部正确、整体断裂”它给出的代码放在当前文件里没问题跟其他文件拼起来就缺东少西。Claude Code 的做法不一样它在生成之前会先批量读一遍相关文件自己梳理模块依赖关系再动手改的时候跨文件的一致性明显高出一个层级。当然这里说的“对等接入”不是要证明谁能彻底替代谁而是把 Claude Code 改造成一个能无缝参与鸿蒙开发的外挂 AI。DevEco Code 继续留在 IDE 里处理即时问答和轻量补全Claude Code 在终端里承担复杂任务和自动化流程两边各干各擅长的部分。比如 AI 写代码DevEco Code 负责“这一行怎么写”Claude Code 负责“这个模块怎么设计”两者并不冲突。1.2 整体架构MCP Skill CLAUDE.md 各管什么我第一次接触这三个名词的时候也绕了很久其实它们的职责非常清晰就是一个三层的配合关系。CLAUDE.md 管的是“认知层”。它放在项目根目录Claude Code 每次启动会话都会自动读取相当于一份给新成员看的项目入职手册。你在里面写清楚项目是干什么的、代码放哪里、有什么编码规范、常用命令是什么AI 在回答任何问题前就已经掌握了这些背景。这层不解决具体操作问题只解决“懂不懂行”的问题。Skill 管的是“方法层”。它是一套技能包每个 Skill 就是一个带说明文档的指令模板放在.claude/skills目录下。Skill 解决的是“会不会干活”的问题比如“生成符合团队规范的 ArkTS 页面”“根据崩溃日志定位状态管理问题”这些都是需要特定步骤的操作流你把它固化成一个 SkillAI 下次遇到同类任务就会按标准流程执行而不是天马行空自由发挥。MCP 管的是“行动层”。它是 Model Context Protocol 的缩写通俗讲就是把外部能力封装成标准接口让 AI 能在对话过程中直接调用真实工具。鸿蒙开发里最典型的用法是把构建命令、日志抓取、依赖查询这些操作封装成 MCP ServerAI 写完成代码后可以自己触发一次编译把报错拉回来分析再继续改。这层解决的是“能不能动手”的问题。一句话总结这套架构CLAUDE.md 让 AI 理解项目Skill 让 AI 掌握方法MCP 让 AI 调用工具。三层叠起来Claude Code 才从“一个会写代码的语言模型”变成“一个真正的鸿蒙开发助手”。1.3 方案选型为什么选用 CLI 接入而不是 IDE 插件我知道市面上也有各种把 Claude 能力搬进 IDE 的插件方案所以这里把选型逻辑讲清楚。首先Claude Code 本身就是以 CLI 工具的形式发布的跑在终端里天然适合作为自动化链路的一环。鸿蒙工程的构建、签名、日志抓取全部有对应的命令行工具比如hvigorw、hdcCLI 形态的 AI 助手可以直接在同一个终端环境里调用这些命令不需要考虑 IDE 插件和外部进程之间的通信障碍。其次CLI 形态更容易做版本隔离和团队统一。我可以在项目根目录用.mcp.json统一声明 MCP Server用.claude/skills统一维护团队技能库用根目录的CLAUDE.md统一注入项目规范整套配置都天然地跟代码仓库一起走。新人克隆仓库一键启动 Claude Code拿到的就是跟团队一致的 AI 开发环境。IDE 插件的配置很难做到这种程度的“配置即代码”。另外一个现实因素是迭代速度。Claude Code 本身的更新节奏很快新功能不断往上加CLI 版本跟进最及时。绑死在某个 IDE 插件上反而要等插件适配体验上总会慢半拍。2. 核心细节解析与实操要点2.1 先搞懂 MCP 在鸿蒙场景下的具体用法MCP 这个协议听起来很抽象拆开来看核心就三件事服务器、工具、资源。服务器是一个独立进程负责跟外部环境打交道工具是服务器暴露出来的可执行动作比如“触发一次 HAP 构建”“查询 SDK 路径”“拉取最新崩溃日志”资源是服务器暴露给 AI 的上下文数据比如“当前工程完整的模块依赖树”。Claude Code 作为客户端通过标准协议跟服务器通信需要的时候自动调用工具、读取资源不用我们手工在提示词里塞命令细节。我在鸿蒙工程里最常用的几个 MCP Server整理成表格供对照MCP Server暴露能力典型使用场景deveco-command封装 hvigorw 构建、签名、预览命令AI 改完代码后自动编译验证拉报错信息回来改oh-package-mcp读取和修改 oh-package.json5 依赖声明AI 识别到需要第三方库时自动补依赖hdc-logcat-mcp抓取模拟器或真机运行日志让 AI 根据异常堆栈反推问题点file-system-mcp限制范围内的文件读写保证 AI 只操作工作目录避免误伤系统文件配置 MCP Server 有两种方式用户级和项目级。用户级通过claude mcp add命令注册好处是全局可用适合配置通用工具项目级则在.mcp.json里声明随仓库走适合配置跟具体工程绑定的工具。我做鸿蒙开发时强烈建议用项目级配置因为hvigorw的路径、SDK 版本这些信息跟项目强相关换了工程配置大概率不能复用写进仓库反而更方便。2.2 Skill 的目录结构与触发逻辑Skill 本质上是一套“带说明书的指令包”它的目录结构并不复杂~/.claude/skills/ arkts-page-generator/ SKILL.md templates/ basic-page.ets list-page.etsSKILL.md是整个 Skill 的入口里面要写清楚这个技能的名称、描述、使用场景和执行步骤。Claude Code 会根据用户提问的内容结合SKILL.md里description字段的语义描述来决定是否触发这个 Skill。所以写描述是一件非常重要的事情要具体、贴近用户说法不适合用大而空的词。我的一个实操心得是description里最好包含两到三个高频触发词。比如一个生成 ArkTS 页面的 Skill描述里就要明确出现“新增页面”“创建页面”“ArkTS 页面”这类表达。否则 AI 匹配不到触发条件Skill 就形同虚设。另外关于模板的颗粒度我踩过很大的坑。一开始我试图把完整页面所有逻辑都塞进模板结果生成出来的代码特别僵化动不动就是模板里的硬编码改起来比从零写还麻烦。后面调整策略模板只提供“骨架 关键片段”业务逻辑让 AI 根据需求动态生成灵活性和准确度都提升了很多。一个好的模板是约束结构而不是约束内容这句话放在 Skill 设计里尤其正确。2.3 CLAUDE.md 的核心写法从项目信息到编码规范CLAUDE.md 很容易被误用成一个“资料大全”我在初版本里塞进去的接口文档堆起来比项目代码还长结果 AI 的表现反而变差。后来我意识到CLAUDE.md 的定位是“注意力手册”只承载那些 AI 每次干活都必须知道的高频关键信息其他内容放到专门的文档目录里按需读取。我现在的写法固定分四块项目概览、目录结构、编码规范、常用命令。项目概览用两三句话交代工程类型、Stage 模型、目标 API 版本避免 AI 对项目环境做出离谱假设。目录结构标注核心代码路径特别是entry/src/main/ets下的页面和组件目录。编码规范重点写强制规则比如禁用any类型、状态变量声明要求、装饰器使用约定等。常用命令则把构建、预览、签名、日志抓取都列出来让 AI 知道去哪执行命令。写编码规范这部分要特别注意一个度。不是把团队内部所有 lint 规则都抄进去而是精选那些“AI 最容易犯且后果严重”的规则。比如 ArkTS 里状态管理的处理方式、资源引用的路径规则、页面路由注册要求这些写进去最划算。我之前还试过把代码格式化细节写进 CLAUDE.md比如缩进用几个空格事实证明完全没有必要反而浪费上下文空间。2.4 对等接入的验证指标怎么定聊完三个工具的细节还需要解决一个问题怎么判断“对等接入”真的成功了我给自己定了一套验证指标分享出来供参考。能力对等不应该只看“能生成代码”还要看是否能覆盖 DevEco Code 日常承担的核心任务。我列了六项第一能根据一句话需求生成一个注册了路由的 ArkTS 页面第二能正确处理State、Prop、Link父子组件数据联动第三改完代码会主动调用构建类 MCP 工具进行编译验证第四能通过 hdc 日志定位崩溃问题并给出修复路径第五在 CLAUDE.md 明示禁止any的情况下生成的代码不会出现any第六能按 Skill 模板生成固定结构的列表页同时填充真实业务逻辑。这六项全过了才说明工具链切换基本合格。我自己在项目里把这六项做成了每次接入新成员 AI 工具链时都要跑的“上岗测试”。有标准就有抓手不然凭感觉判断很容易出现“看着能用一上线就崩”的问题。3. 实操过程与核心环节实现3.1 环境准备安装 Claude Code 与 Node 版本避坑安装步骤本身不复杂但是有几个前提条件需要提前处理好。首先是 Node.js 环境Claude Code 对 Node.js 版本有最低要求太老的版本装了也起不来。我是用 nvm 管理 Node 版本的切到最新的 LTS 版本再操作这一步能避免后续很多未知报错。# 切换到较新的 Node.js LTS 版本 node -v npm -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证是否安装成功 claude --version # 进入鸿蒙工程目录并启动 cd ~/workspace/harmony-app claude第一次启动需要完成账号登录流程按命令行提示操作即可。登录成功后建议先不急着干活随便跑一个对话确认交互没问题再往下配置。我在这一步就遇到过安装成功但启动后进程异常退出的情况直接重新执行安装命令覆盖安装一次就恢复了。另外一个小建议Claude Code 的体验受 shell 环境的影响比较大如果你平时用的是定制过的 zsh 或者 PowerShell注意看看启动时的环境变量是否正常。有些临时别名或者代理类环境变量配置可能会干扰到子进程调用这也是后面容易出现“工具调不通”的根源之一。3.2 编写 CLAUDE.md一份可以直接改用的模板下面这份模板是从我实际项目中删减出来的保留了最核心的结构可以直接铺到你的鸿蒙工程根目录# HarmonyOS APP - ArkTS Development ## 项目概览 本项目是一个面向 HarmonyOS 手机的日常工具类应用采用 Stage 模型 目标 API 版本为 12主模块为 entry核心代码位于 entry/src/main/ets。 ## 目录结构 - entry/src/main/ets/entryability/ - Ability 生命周期相关 - entry/src/main/ets/pages/ - 页面代码使用 ArkUI 声明式语法 - entry/src/main/ets/common/ - 公共组件与工具方法 - entry/src/main/resources/ - 字符串、颜色等资源文件 ## 编码规范 - 使用 TypeScript 严格模式禁止使用 any - 页面组件使用 Component 和 Entry 装饰器文件名与组件名保持一致 - 状态管理优先使用 State、Prop、Link避免直接修改全局变量 - 单位使用 vp涉及像素转换时用 vp2px() 方法不要硬编码具体像素值 ## 常用命令 - 构建hvigorw assembleHap - 预览hvigorw --mode module -p productdefault preview - 签名hvigorw signHap - 日志hdc log -a -x写完第一件事不是急着开发而是在 Claude Code 里做一次“上岗提问”。比如问“这个项目的主入口 Ability 在哪个文件”如果它能准确回答entry/src/main/ets/entryability/下的文件说明 CLAUDE.md 已经被正确识别并生效了。如果答非所问优先检查文件编码和位置CLAUDE.md 一定放在项目根目录且不要用 BOM 头的 UTF-8 编码。3.3 配置一个常用的 ArkTS 页面生成 Skill在 Claude Code 里配置 Skill 的收益比大多数人想象中来得更快。我的第一个 Skill 就是页面生成器用了几周后又陆续加了日志分析、依赖检查等技能现在日常工作中有一半以上的重复流程都走的是 Skill。3.3.1 创建 SKILL.md先创建目录~/.claude/skills/arkts-page-generator/在里面新建SKILL.md--- name: arkts-page-generator description: 根据用户需求生成完整的 ArkTS 页面代码包含 Component、Entry 装饰器以及对应的组件布局和状态管理逻辑。 --- ## 使用场景 当用户需要进入一个新页面或者要求“新增一个某某页面”时使用本 Skill。 ## 执行步骤 1. 确认页面对应的路由配置在 main_pages.json 中注册 2. 根据页面类型选择模板basic-page.ets 或 list-page.ets 3. 在模板基础上填充业务状态变量优先使用 State 管理 4. 输出完整代码并同时给出需要在 oh-package.json5 中补充的依赖如有 5. 建议在 build() 方法内按区块添加结构注释3.3.2 添加模板文件在templates/目录下放一个基础页面模板basic-page.ets内容不需要太完整保留骨架就好Entry Component struct PageName { State message: string Hello HarmonyOS; build() { Column({ space: 12 }) { Text(this.message) .fontSize(20) .fontWeight(FontWeight.Bold) } .width(100%) .padding(16) } }这个模板故意不写复杂的业务代码只提供一个“页面该长什么样”的基准。AI 生成具体页面时会在这个基准上填充实际业务字段和布局既保证了结构统一又不会因为模板过度约束导致生成结果生硬。Skill 写好后在用户级~/.claude/skills/和项目级.claude/skills/各放一份。用户级的适合个人常用技能项目级适合团队在仓库里维护统一模板项目级优先级更高能覆盖用户级同名配置。3.4 接入 DevEco 相关 MCP Server这是整个接入方案里最花时间也是收益最大的一环。鸿蒙开发不像 Web 前端那样可以随便在浏览器里即时预览代码能不能编译、运行是否正常很多时候必须真实跑一次才知道。把构建和日志能力通过 MCP 暴露给 AIClaude Code 就能在修改代码后自己触发构建把报错拉回来分析再修改、再验证形成一个完整闭环。3.4.1 MCP Server 的最小实现我这里用一个封装了hvigorw调用的 MCP Server 举例核心逻辑就是通过 MCP 标准接口把命令行工具包一层import { Server } from modelcontextprotocol/sdk/server/index.js; const server new Server({ name: deveco-command, version: 0.1.0 }, { capabilities: { tools: { buildHap: { description: 构建 HAP 包, inputSchema: { type: object, properties: { module: { type: string, description: 模块名默认 entry } } } }, signHap: { description: 对构建产物签名, inputSchema: { type: object, properties: { hapPath: { type: string, description: HAP 文件路径 } } } } } } });这段代码只是示意真正落地时还需要处理工具执行输出、超时控制、日志截断等细节。MCP SDK 提供了完善的基础设施照着官方示例扩展工具即可难度不大。3.4.2 配置 .mcp.json推荐用项目级配置在工程根目录创建一个.mcp.json{ mcpServers: { deveco-command: { command: npx, args: [tsx, config/mcp/deveco-command-mcp/index.ts] }, hdc-logcat: { command: npx, args: [tsx, config/mcp/hdc-logcat-mcp/index.ts] } } }配置完成后在 Claude Code 里启动会话输入claude mcp list查看已连接的服务器。如果列表里能看到deveco-command和hdc-logcat且状态为 connected说明 MCP 层已经打通。这里多说一句.mcp.json放进仓库里随代码走团队里其他人克隆下来就能直接用不需要各自再注册一遍。如果发现其他成员拉取后 MCP 不生效优先检查 Node 依赖是否装齐这类 npx 启动的 Server 经常因为tsx未安装而静默失败。3.5 能力对等验证清单所有配置完成后的最后一步是跑一遍完整的验证。我自己的建议是不要凭感觉判断直接按下面清单逐项打勾生成一个新的 ArkTS 页面确认Entry/Component装饰器、.build()结构、页面路由注册全部正确用State和Prop实现一个父子组件数据联动示例验证状态管理符合规范修改代码后主动询问“帮我构建一下”确认 Claude Code 能自动触发 deveco-command MCP 工具完成编译故意制造一个空指针异常让 AI 通过 hdc 日志定位问题并给出修复建议在需求里明确提出“页面使用列表展示”确认 AI 触发 list-page Skill 而不是临时自由发挥观察整个会话中是否出现被 CLAUDE.md 明令禁止的写法如any类型六项全部通过后再把 Claude Code 投入到日常开发中。如果哪一项卡住了回看对应环节列表页不触发 Skill 就检查描述不主动构建就检查 MCP 配置出现any就检查 CLAUDE.md 是否被正确加载。大部分问题都能在这三个环节里找到答案。4. 常见问题与排查技巧实录4.1 Skill 没被触发先从描述词查起Skill 没被触发是我在接入初期遇到最频繁的问题明明写好了技能包AI 却像没看见一样。排查分三步先确认SKILL.md头部的description是否足够贴近用户的自然表达比如用户说“我要加一个设置页”而描述里只有“生成 ArkTS 页面”这种抽象短语匹配度就可能不够其次用claude skill list查看 Skill 是否被正确扫描到最后如果前两步没问题那就是提示词和描述之间的语义距离太远解决办法是往描述里多塞几个同义触发词。这段经历给我的启发是写 Skill 描述的时候要站在“用户会怎么说”而不是“技能能做什么”的角度去措辞。你要让 AI 在做意图匹配的时候能第一时间命中而不是靠它自己理解发散。4.2 CLAUDE.md 写太长导致上下文被稀释有人可能觉得 CLAUDE.md 写得越全越好我最初也是这样做的结果适得其反。把整个项目需求文档、接口协议、第三方库说明都塞进去之后Claude Code 每次会话都要带着这些冗长的背景信息注意力被大量无关内容稀释处理核心任务时反而变笨了。我的调整方案是只保留高频且关键的信息把其余内容移到项目docs目录需要时通过“读取文件”的方式动态加载。比如接口文档不会在 CLAUDE.md 里罗列而是告诉 AI“接口定义在docs/api.md涉及网络层修改前先读这个文件”。这样既保证信息可达又不会长期占用上下文窗口。4.3 构建类 MCP 工具超时hvigorw 构建 HarmonyOS 应用尤其是首次构建耗时可能超过一两分钟。而 MCP 工具默认的会话超时通常是几十秒这就导致 AI 调用构建工具后迟迟等不到结果最终判定工具调用失败。我的处理办法是把耗时操作改造成异步任务模式MCP Server 收到构建请求后先返回一个任务 ID随后在后台执行构建AI 拿到任务 ID 后通过轮询接口查询构建状态。这样即便构建耗时五分钟整个过程也不会因为超时被中断。如果不想搞得这么复杂也可以直接调大 MCP 客户端的超时阈值只是这样遇到真正卡死的任务时排查起来会更困难。4.4 子进程执行环境不一致Claude Code 在终端里启动后它执行 MCP 工具和命令时依赖的是当前 shell 的环境变量。如果你在.zshrc或 PowerShell profile 里配置了自定义路径、别名但 Claude Code 启动时继承的环境不完整就会出现“手动在终端里跑命令没问题AI 调工具却报找不到命令”的情况。解决方案是让 MCP Server 自己负责环境准备在 server 启动脚本里显式设置PATH不要依赖外层 shell 的默认环境。或者在 Claude Code 的配置里指定一个统一的环境变量文件。这样团队成员的机器配置不一样也不会影响工具链稳定性。4.5 上下文窗口被工具返回结果刷屏MCP 工具返回结果如果太大比如一次完整构建日志有几千行AI 的上下文窗口很快就被这些中间信息塞满导致后续对话质量急剧下降。最直观的表现是 AI 变得“健忘”刚分析完的代码转个身就忘了。我给构建类 MCP Server 增加了maxLines参数默认只回传最后 200 行日志AI 如果觉得内容不够可以显式请求更多。日志抓取类工具类似默认截断到错误堆栈部分。这个优化做完之后会话的可用长度明显变长AI 的连续推理能力也稳了很多是投入产出比非常高的一个调整。这次从 DevEco Code 切换到 Claude Code 的实战我前前后后折腾了两周多踩过的坑比预想的多但最后跑通时收获也远超预期。以前写一个稍复杂的列表页从新建文件到确认能编译怎么也要一个多小时现在把需求描述清楚Claude Code 生成骨架再手动调整几处数据格式整个流程基本压缩到二十分钟以内。最有价值的倒不是生成速度而是 MCP 接通以后AI 能自己构建、自己看报错、自己改代码这个正循环一旦跑起来生产力提升相当明显。如果你也正在做鸿蒙开发手头又想尝试通用 AI 编程工具我的建议是别一上来就追求把所有能力一次接完。先配好 CLAUDE.md让 AI 理解项目再写一个高频用到的 Skill让 AI 会干活最后再考虑用 MCP 接通构建和日志链路让 AI 能验证自己的产出。每一步都有即时反馈信心攒够了再扩展其他场景会从容得多。
` 与 MoviePy 记录 KAN 结构演化)
