1. HarmonyOS7 下 DevEco Code 的 AI Agent 到底能做什么如果你最近在折腾 HarmonyOS7 的鸿蒙应用开发大概率已经发现 DevEco Code 里多了一个叫 AI Agent 的能力。简单说它不是一个聊天窗口而是一个能读你仓库、按需加载指令、然后动手改代码的代理。它最核心的扩展机制就是 skill——你可以把它理解成给代理准备的「技能卡片」每张卡片用一份 SKILL.md 描述「我是谁、我什么时候该被用、我具体做什么」。这套机制解决的是一个很实际的问题鸿蒙项目里总有一些重复动作比如生成 release notes、统一 ArkTS 代码风格、按模板补全 module.json5 配置。以前你要么每次手动写 prompt要么把一大段规则塞进系统提示里既臃肿又难维护。skill 让这些规则变成仓库里可版本管理的文件代理在需要时才加载完整内容平时只看到一行名称和描述。这篇面向的是已经在用 DevEco Code、想跑通第一个鸿蒙 AI Agent 任务的开发者。我会先讲 skill 的安装位置和发现机制再给出 config.toml 的配置骨架然后接上 TaoToken 的统一 Key 和 API 通道最后用一个真实请求验证 skill 是否生效。整个过程不需要你改 DevEco Code 的源码全部通过配置文件和目录结构完成。需要提前说明的是skill 的加载依赖模型通道能正常返回工具调用。如果你本地模型通道不稳定skill 列表可能压根不会出现在代理上下文里。所以配置骨架和通道接入这两步要一起做缺一个都跑不通。2. 前置准备TaoToken 统一 Key 与 API 通道在写 config.toml 之前先把模型通道准备好。DevEco Code 的 AI Agent 需要一个兼容 Anthropic 协议或 OpenAI 协议的端点TaoToken 提供的就是这种统一入口一个 Key 可以走多个模型省得你在鸿蒙项目里为每个模型单独配一遍环境变量。先拿到 Key。打开控制台页面登录后进入 API Keys 管理新建一个 Key 并复制。这个 Key 只在创建时完整显示一次建议直接写进项目的环境变量文件而不是硬编码到 config.toml 里。控制台地址是 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 。拿到 Key 之后确认一下接入文档里的 base_url 格式。TaoToken 的 API 根地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填这个。如果你用的是 Anthropic 兼容模式路径通常会在后面拼 /v1/messages如果是 OpenAI 兼容模式则是 /v1/chat/completions。具体拼法以接入文档为准文档入口在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里有个容易踩的坑很多人把 base_url 写成带 UTM 的官网地址结果请求 404。记住 API 通道只认 https://taotoken.net/api 这个干净路径官网首页那个带参数的链接是给人看的不是给程序调的。环境变量建议这样设Linux/macOS 下写进 ~/.zshrc 或 ~/.bashrcexport TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows 下用系统环境变量面板添加或者 PowerShell 里临时设$env:TAOTOKEN_API_KEYsk-你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设完之后开个新终端用echo $TAOTOKEN_API_KEY确认能打印出来。这一步看着简单但后面 config.toml 里引用变量名时拼错一个字母代理就会报鉴权失败排查起来很费时间。3. config.toml 配置骨架与 skill 目录结构DevEco Code 的 skill 发现机制分项目级和全局级两层。项目级路径会从当前工作目录向上遍历直到 git 工作树根目录沿途加载所有匹配的 SKILL.md。全局级则从用户主目录下的固定路径加载。你要做的第一件事是决定 skill 放哪。项目级推荐放在.deveco/skills/name/SKILL.md这是 DevEco Code 原生路径。如果你有 Claude 或通用 agent 的兼容需求也可以放.claude/skills/name/SKILL.md或.agents/skills/name/SKILL.mdDevEco Code 会一并识别。全局级对应~/.config/deveco/skills/name/SKILL.md、~/.claude/skills/name/SKILL.md、~/.agents/skills/name/SKILL.md。目录结构长这样以项目级为例your-harmony-project/ ├── .deveco/ │ └── skills/ │ └── arkts-style/ │ └── SKILL.md ├── entry/ │ └── src/main/ets/ └── config.toml每个 skill 一个文件夹文件夹名必须和 SKILL.md 里 frontmatter 的 name 字段完全一致。name 的规则很严1 到 64 个字符只能小写字母和数字可以用单个连字符分隔不能以连字符开头或结尾不能有连续两个连字符。等效正则是^[a-z0-9](-[a-z0-9])*$。像ArkTS-Style这种大写加连字符的写法会被直接忽略必须写成arkts-style。SKILL.md 必须以 YAML frontmatter 开头只识别这几个字段name 必填、description 必填、license 可选、compatibility 可选、metadata 可选。description 长度 1 到 1024 字符要写得足够具体因为代理就是靠这一行决定要不要加载这个 skill。写得太泛比如「帮助写代码」代理基本不会选中它。一个鸿蒙场景下的 SKILL.md 示例--- name: arkts-style description: Enforce ArkTS naming and state decorator conventions for HarmonyOS7 entry modules license: MIT compatibility: deveco metadata: audience: harmony-developers workflow: arkts --- ## What I do - Check State / Prop / Link decorator usage against project conventions - Rename variables to lowerCamelCase and components to UpperCamelCase - Flag direct UI updates outside the UI thread ## When to use me Use this when editing files under entry/src/main/ets and the change touches component state.frontmatter 里不认识的字段会被忽略所以别指望自定义字段能传参给代理所有逻辑都要写在正文里。接下来是 config.toml 骨架。DevEco Code 的模型通道和权限配置可以放在项目根目录的 config.toml 里也可以放在全局配置目录。下面这份骨架把模型通道、skill 权限、代理覆盖三块都留了位置[model] provider anthropic-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_name claude-sonnet-4-20250514 max_tokens 8192 [permission.skill] * allow internal-* deny experimental-* ask [agent.plan.permission.skill] internal-* allow这里有几个点要解释。api_key_env填的是环境变量名不是 Key 本身这样 Key 不会进版本库。model_name按你实际订阅的模型填TaoToken 支持多个模型具体可用列表在模型对话页面能看到地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。权限部分用通配符控制* allow表示默认放行所有 skillinternal-*拒绝experimental-*加载前询问。deny 的技能对代理完全隐藏连 available_skills 列表里都不会出现。如果你想让某个内置代理拥有不同权限用[agent.name.permission.skill]覆盖。想彻底禁用某个代理的 skill 功能加一行[agent.name.tools]下面写skill false禁用后 available_skills 整段会被省略。4. 验证 skill 生效与首个鸿蒙 AI Agent 任务配置写完先别急着让代理改代码用一次最小请求确认 skill 被正确发现。启动 DevEco Code 后在项目根目录打开代理对话输入一句能触发 skill 列表的指令比如「列出当前可用的 skills」。如果通道正常代理会调用 skill 工具并返回类似下面的结构available_skills skill namearkts-style/name descriptionEnforce ArkTS naming and state decorator conventions for HarmonyOS7 entry modules/description /skill /available_skills看到这段就说明发现机制和权限都通了。如果列表是空的先检查 SKILL.md 文件名是不是全大写frontmatter 里 name 和 description 是否都在以及 name 是否和文件夹名一致。这三项是最常见的失败原因。确认列表之后跑一个真实任务。在代理里输入「用 arkts-style 检查 entry/src/main/ets/pages/Index.ets 里的状态装饰器用法」。代理会调用skill({ name: arkts-style })加载完整内容然后读取文件并给出修改建议。加载动作可以在工具调用日志里看到这是判断 skill 是否真正生效的关键——列表里有不代表加载成功加载失败通常是 frontmatter 格式问题。如果你想验证模型通道本身可以先用模型对话页面发一条简单消息确认 Key 和 base_url 没问题。模型对话入口是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。通道通了再回来调 skill能省掉一半排查时间。对于长期在鸿蒙项目里跑编码代理的场景建议用 Coding Plan 而不是按次调用额度更稳适合每天都要跑 skill 的节奏。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你用的是 Claude Code 那套 Anthropic 兼容工作流接入说明在 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-codeutm_campaignrewrite 。5. 本篇常见错误排查skill 不显示九成是下面几个原因。第一文件名写成了skill.md或Skill.md必须是全大写SKILL.md。第二frontmatter 缺少 name 或 description或者 YAML 缩进用了 tab 而不是空格。第三name 字段和所在文件夹名不一致比如文件夹叫arkts-style但 frontmatter 写arktsStyle。第四name 里出现了大写字母或连续连字符正则不通过。权限相关的坑也很典型。* allow写在[permission.skill]段下才生效如果误写到[permission]段下代理会按默认策略处理可能直接隐藏所有 skill。另外 deny 的优先级高于 allow如果你同时写了* allow和internal-* denyinternal 开头的技能一定不可见这是预期行为。通道层面的报错通常是 401 或 404。401 检查TAOTOKEN_API_KEY环境变量是否在当前终端可见DevEco Code 是从启动它的 shell 继承环境变量的如果你在 IDE 里启动但环境变量只写在了另一个终端就会读不到。404 检查 base_url 是不是写成了带 UTM 的官网地址正确值是 https://taotoken.net/api 。模型名写错会返回 400去模型对话页面确认一下当前可用的模型标识。还有一个隐蔽问题项目级 skill 的向上遍历会停在 git 工作树根目录。如果你的鸿蒙项目是 monorepo 的子目录且 git 根在更上层那.deveco/skills要放在 git 根那一层才会被扫到放在子目录里代理从子目录启动时能发现但从根目录启动就发现不了。统一放在 git 根目录最稳。6. 把 skill 和通道固定成团队规范跑通第一个任务之后建议把 skill 目录和 config.toml 一起提交到仓库让团队里每个人拉下来就能用同一套代理行为。config.toml 里只放环境变量名Key 通过各自的本地环境注入这样既统一了行为又不会泄露凭证。skill 的 description 要当成接口文档来写因为它直接决定代理会不会选中这个技能改 description 相当于改路由规则改完记得重新验证一次 available_skills 列表。后续要加新技能就按name/SKILL.md建目录name 保持小写连字符风格正文里把「做什么」和「什么时候用」分开写清楚。权限先用* allow跑通等技能多了再按前缀收紧。通道这边日常调试用模型对话页面快速验证正式编码任务走 Coding Plan接入细节随时查接入文档。整套流程不需要动 DevEco Code 本身全部靠目录约定和配置文件完成升级 IDE 也不会丢。
