1. 鸿蒙 ArkTS 开发里AI 生成代码为什么总“跑偏”鸿蒙应用开发用 ArkTS 作为主力语言它长得像 TypeScript但骨子里是另一套约束不允许any、不允许结构化类型带来的隐式转换、状态管理要用State/Prop/Link这套装饰器、UI 必须走声明式 ArkUI 的组件树。通用大模型在训练时见过海量 TypeScript 和 React 代码一让它写鸿蒙页面很容易把useState、interface宽松赋值、动态属性访问这些习惯带进来编译直接报错。我试过让模型写一个带列表刷新的 ArkTS 页面它给我返回了let data: any[] []还顺手用了Object.keys遍历对象——这两样在 ArkTS 里都不合规。问题不在于模型笨而在于它缺少两样东西一是鸿蒙最新的 API 元数据二是团队自己的编码约束。前者靠 MCP 把知识库接进来解决后者靠 Rules 把规范钉死。这篇就围绕这两件事展开怎么用 MCP Rules 约束 AI 产出符合鸿蒙工程规范的 ArkTS 代码同时把团队所有 AI 工具的 Key 统一收敛到 TaoToken 这一条通道上避免每个工具散配一套密钥。适合正在做鸿蒙应用、又想把 AI 编程助手真正用起来的团队。2. 前置准备TaoToken 统一 Key 与工程目录约定在动手配 MCP 和 Rules 之前先把“通道”这件事理清楚。团队里往往同时用着好几个 AI 工具IDE 里的编程助手、命令行里的 Agent、偶尔还要开个对话窗口问问题。如果每个工具各自去申请 Key、各自记额度管理成本很快就上来了。TaoToken 在这里扮演的是统一入口的角色一个 Key 覆盖多种模型调用工具侧只认一个 API 地址和一份密钥。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册后在控制台生成 Key 即可。API 基地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填。工程侧我建议先约定好目录结构后面 MCP 和 Rules 都往里放harmony-app/ ├── entry/ # 鸿蒙主模块 │ └── src/main/ets/ ├── .ai/ │ ├── rules/ # 规则文件目录 │ │ ├── arkts-base.md │ │ └── team-style.md │ └── mcp/ │ └── servers.json # MCP Server 清单 ├── settings.json # 工具级配置 └── config.toml # Agent 级配置.ai/rules/放 Markdown 规则.ai/mcp/放 MCP Server 定义settings.json和config.toml分别给不同工具读取。这样换工具时规则和 MCP 不用重写只改读取路径。Key 的获取走控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 生成后建议按“工具名-用途”命名方便后面排查是哪个工具在消耗额度。3. 可复制配置settings.json 与 config.toml 骨架先给settings.json的骨架。这份配置面向 IDE 类工具核心是把模型请求指向 TaoToken并把 Rules 目录和 MCP 清单挂上去{ ai.provider: openai-compatible, ai.baseUrl: https://taotoken.net/api, ai.apiKey: ${env:TAOTOKEN_API_KEY}, ai.model: claude-sonnet-4-20250514, ai.rulesDir: .ai/rules, ai.rulesEnabled: [arkts-base.md, team-style.md], ai.mcpConfig: .ai/mcp/servers.json, ai.context.include: [entry/src/main/ets/**/*.ets], ai.context.exclude: [**/build/**, **/oh_modules/**] }几个点说明一下。apiKey用环境变量引用不要把明文写进仓库团队协作时每人本地设一次TAOTOKEN_API_KEY就行。rulesEnabled显式列出启用的规则文件避免误加载草稿。context.exclude把构建产物和依赖目录排掉否则 AI 读上下文时会浪费大量 token 在无关文件上。再给config.toml这份面向命令行 Agent 类工具[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 max_tokens 8192 [rules] dir .ai/rules files [arkts-base.md, team-style.md] priority project-first [mcp] config_path .ai/mcp/servers.json auto_start true timeout_seconds 30 [workspace] root . include [entry/src/main/ets/**/*.ets]priority project-first表示工程级规则覆盖全局规则团队里不同项目有特殊约定时不会互相打架。auto_start true让 MCP Server 随 Agent 启动省去手动拉起的步骤。MCP 清单servers.json长这样这里挂一个鸿蒙知识库 Server 和一个文档检索 Server{ mcpServers: { harmony-kb: { command: node, args: [.ai/mcp/harmony-kb-server.js], env: { KB_INDEX_PATH: .ai/kb/harmony-index.json } }, context-docs: { command: npx, args: [-y, taotoken/context-docs-mcp], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} } } } }harmony-kb指向本地构建的鸿蒙 API 索引context-docs走 TaoToken 的文档检索能力。两个 Server 各司其职一个管鸿蒙专有知识一个管通用文档。4. Rules 规则片段把 ArkTS 约束写进 AI 的“岗前培训”Rules 的作用是让 AI 在生成代码前先读一遍约束。规则文件用 Markdown 写越具体越好别写“请遵循最佳实践”这种空话。下面是我在用的arkts-base.md片段# ArkTS 基础约束 ## 类型系统 - 禁止使用 any 和 unknown所有变量必须有明确类型 - 禁止结构化类型隐式转换对象赋值必须类型完全匹配 - 接口定义使用 interface禁止用 type 定义对象结构 - 数组声明必须带元素类型如 string[]、number[] ## 状态管理 - 组件状态用 State父子传值用 Prop双向绑定用 Link - 跨组件共享用 Provide/Consume禁止用全局变量传状态 - 状态变更必须触发 UI 刷新禁止直接修改 State 对象的嵌套属性 ## UI 构建 - 使用声明式 ArkUI禁止命令式 DOM 操作 - 列表用 List ListItem禁止用 ForEach 直接渲染大数组 - 组件必须标注 Component入口组件标注 Entry ## API 使用 - 优先使用 ohos 开头的官方模块 - 废弃 API 禁止使用遇到弃用提示必须替换为新 API - 异步操作统一用 async/await禁止回调嵌套超过两层再给一份team-style.md管团队自己的约定# 团队编码风格 ## 命名 - 组件名用大驼峰如 UserProfileCard - 方法名用小驼峰如 fetchUserList - 常量全大写下划线如 MAX_RETRY_COUNT ## 文件组织 - 每个组件单独一个 .ets 文件 - 页面级组件放 pages/通用组件放 components/ - 工具函数放 utils/每个文件导出单一职责 ## 注释 - 公开方法必须写 JSDoc 注释 - 复杂逻辑块前写单行注释说明意图 - 禁止无意义注释如 // 定义变量规则写完后AI 在生成代码时会先做一轮自检。比如你让它“写一个用户列表页”它会先确认类型是否明确、状态装饰器是否用对、列表是否用 List 组件。不符合的地方它会主动调整而不是直接吐出一段跑不通的代码。5. 验证请求确认 AI 真的按鸿蒙规范输出配好之后怎么验证别只看它能不能生成代码要看它生成的是不是“鸿蒙的代码”。我一般用三个检查动作。第一个动作让它处理一个已知有弃用 API 的文件。在对话里输入检查 entry/src/main/ets/pages/Index.ets 中的 API 弃用问题 查询知识库后给出修复方案并直接修改文件。如果 MCP 和 Rules 都生效你会看到它先调用check_editor_errors之类的检查工具再调用harmony-kb检索替代 API最后才动代码。整个过程在工具调用日志里能看到不是直接凭记忆改。第二个动作故意让它写一段容易“漂移”的代码写一个 ArkTS 函数接收一个用户对象数组返回按年龄排序后的新数组。观察它有没有用any、有没有用sort的可变版本、类型标注是否完整。合规的输出应该类似interface User { name: string; age: number; } function sortUsersByAge(users: User[]): User[] { return [...users].sort((a: User, b: User) a.age - b.age); }注意[...users]先复制再排序避免修改原数组参数和返回值都带类型。如果它返回users.sort(...)直接改原数组说明 Rules 里的约束没吃透回去检查规则文件是否被正确加载。第三个动作跑一次编译。把 AI 生成的代码放进工程执行hvigorw assembleHap --mode module -p productdefault编译通过是最硬的验证。如果报 ArkTS 语法错误把错误信息贴回对话让它结合 Rules 重新修正。反复几轮后规则会越来越准。6. 本篇常见错排查配置过程中踩过的坑集中说几个。MCP Server 起不来。先看servers.json里的command路径对不对node和npx是否在 PATH 里。如果报超时把timeout_seconds从 30 调到 60本地索引大的时候启动会慢。日志一般在工具的输出面板里搜mcp关键字能看到具体报错。Rules 没生效。最常见的原因是路径写错。settings.json里的rulesDir是相对工程根目录的如果你在子目录打开工具相对路径就偏了。改成绝对路径或者确认工作区根目录设置正确。另一个原因是规则文件编码不是 UTF-8中文注释乱码会导致解析失败。API 请求 401。检查TAOTOKEN_API_KEY环境变量是否在当前终端会话里生效。IDE 类工具有时不继承 shell 环境变量需要在工具设置里单独填。Key 本身去控制台确认没过期、没被禁用。模型返回的代码还是带 any。说明 Rules 的优先级不够或者模型没读到规则。在config.toml里把priority设为project-first并在对话开头显式提醒“请先读取 .ai/rules 下的规则再生成代码”。有些工具支持在系统提示里注入规则摘要开启那个选项效果更稳。上下文里混入了 build 产物。检查context.exclude是否覆盖了build/和oh_modules/。鸿蒙工程的oh_modules体积很大不排除的话 AI 每次都要读一堆第三方声明文件既慢又容易干扰判断。7. 把通道和规范固定下来走到这里团队里每个成员的 AI 工具都指向同一个 TaoToken 通道Key 只需要在控制台管一份。MCP 负责把鸿蒙知识库和文档检索接进来让模型不再靠过时记忆写代码Rules 负责把 ArkTS 语法约束和团队风格钉死让生成结果直接可编译。后续要扩展也简单新工具接入时复制settings.json或config.toml骨架改一下读取路径就行知识库更新时重建harmony-index.jsonMCP Server 下次启动自动加载。规则文件可以按模块拆分比如arkts-ui.md、arkts-network.md在rulesEnabled里按需启用。需要长期跑编码任务或者搭 Agent 工作流的可以看下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 额度模型更适合持续调用。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 参数细节以文档为准。Key 管理还是走控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。想先验证模型输出质量的直接开模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 试几轮把规则片段贴进去看效果比在工程里反复编译快得多。