HarmonyOS掌上记账APP开发实践第85篇：DevEco Code AI Agent工具指令配置与调试指南

1. 记账 APP 里 Agent 指令为什么总报错在 HarmonyOS 掌上记账 APP 的开发过程中我逐渐把重复性工作交给了 DevEco Code 的 AI Agent生成 ArkTS 页面骨架、批量补全数据模型、跑单元测试、整理资源文件。但真正上手后你会发现Agent 并不是「说一句话就干活」的黑盒它背后是一套工具指令Tool系统。LLM 本身不能直接改你的代码它只能「请求调用某个工具」由 DevEco Code 去执行再把结果回传给模型。工具指令配置错了表现就是Agent 反复说「我将要修改文件」但文件没变、bash 命令被拒绝、grep 搜不到本该存在的文件、MCP 工具名对不上导致调用失败。这篇聚焦的就是这个场景你已经能让 Agent 跑起来但工具指令调用频繁报错。我会给出一份可直接复制的工具指令配置骨架settings.json 与 config.toml 两套示例然后逐条讲每个内置工具的验证动作和报错排查路径。目标很明确——读完你能独立完成工具指令的接入与调通而不是靠反复重启 IDE 碰运气。适合谁已经用过 DevEco Code、写过至少一个 ArkTS 页面、想让 Agent 稳定接管记账 APP 里 CRUD 与测试流程的开发者。核心检索词先摆出来DevEco Code 的 AI Agent 工具指令本质是用 permission 字段控制 LLM 能调用哪些工具、以什么权限调用内置工具覆盖 bash、edit、write、read、grep、glob、patch、skill、todowrite、webfetch、websearch、question还能通过自定义工具和 MCP 服务器扩展。2. 前置TaoToken 接入与 Agent 模型准备工具指令要跑起来前提是 Agent 背后有一个能稳定响应 function calling 的模型。我这边习惯用 TaoToken 做统一接入它的 API 兼容主流协议配置成本低。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM。第一步是拿 Key。打开控制台里的 API Keys 页面创建密钥https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后立刻复制页面刷新就不再完整显示。如果你还没确定用哪个模型可以先去模型对话页面试一下工具调用是否正常https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了 base_url 和鉴权头的写法。把 Key 配到 DevEco Code 的模型提供商设置里或者写进环境变量后面 Agent 才能发起工具调用请求。注意工具指令报错里有一类根本不是配置问题而是模型不支持并行工具调用或 function calling 格式不兼容。先用模型对话页面确认模型能正常返回 tool_calls再回来调 DevEco Code 的 permission。如果你打算长期让 Agent 接管记账 APP 的编码任务比如每天生成报表页、跑回归可以考虑 Coding Plan额度更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。Claude Code 相关的接入说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。3. 可复制的工具指令配置骨架DevEco Code 的工具指令配置核心是permission字段每个工具可以设allow、deny、ask三种状态。默认全部启用且无需权限这在真实项目里其实挺危险——Agent 可能直接覆盖你的记账核心逻辑。下面这份 settings.json 骨架是我在记账 APP 里实际用的兼顾安全和效率。{ $schema: https://opencode.ai/config.json, permission: { read: allow, grep: allow, glob: allow, edit: ask, write: ask, patch: ask, bash: ask, webfetch: allow, websearch: allow, todowrite: allow, skill: allow, question: allow, lsp: allow, mymcp_*: ask } }这里的设计逻辑读类工具read/grep/glob全放开因为只读不破坏写类工具edit/write/patch统一走askAgent 每次改文件前弹确认避免它把BillModel.ets里的金额字段类型改错bash 也走ask因为记账 APP 里跑hvigor构建或git操作需要人工把关。MCP 用通配符mymcp_*统一要求审批防止第三方工具越权。如果你更习惯 TOML 风格config.toml 等价写法如下[permission] read allow grep allow glob allow edit ask write ask patch ask bash ask webfetch allow websearch allow todowrite allow skill allow question allow lsp allow mymcp_* ask几个容易踩的点先说清楚。write和patch都受edit权限控制也就是说你只写edit askwrite 和 patch 也会跟着走审批不用单独列。lsp是实验性工具必须设置环境变量DEVECO_EXPERIMENTAL_LSP_TOOLtrue或DEVECO_EXPERIMENTALtrue才生效否则配了 permission 也调不起来。websearch只在用 DevEco Code 提供商、或设置DEVECO_ENABLE_EXA为真值如true或1时可用启动命令是DEVECO_ENABLE_EXA1 deveco。4. 逐条指令验证与成功结果配好之后别急着让 Agent 干大活逐条验证每个工具指令能不能通。下面是我在记账 APP 项目里用的验证动作每条都给出预期结果。4.1 read / grep / glob 只读三件套让 Agent 执行「读取entry/src/main/ets/model/BillModel.ets的前 30 行」。成功时 Agent 会返回文件内容片段而不是说「我无法访问文件」。如果报错permission denied检查 permission 里 read 是否为 allow。grep 验证「在entry/src/main/ets下搜索State」。成功返回带行号的匹配列表。这里有个坑grep 和 glob 底层用 ripgrep默认遵循.gitignore。如果你的记账数据 mock 文件放在被忽略的目录里搜不到是正常的。解决办法是在项目根目录建.ignore文件显式放行!node_modules/ !dist/ !build/glob 验证「用**/*.ets找出所有 ArkTS 文件」。成功返回按修改时间排序的路径列表。如果返回空先确认当前工作目录是不是项目根。4.2 edit / write / patch 写操作让 Agent 执行「在BillModel.ets里把amount: number改成amount: number // 单位分」。因为 edit 设了 ask你应该看到审批弹窗确认后文件才变。成功标志是文件内容真的改了且 Agent 回传了 diff。write 验证「新建entry/src/main/ets/pages/ReportPage.ets」。注意 write 会覆盖已存在文件所以务必保持 ask。patch 验证「应用这个 diff 到BillModel.ets」。patch 适合从外部来源导入改动。注意如果 Agent 一直说「我将修改」但没弹审批多半是 permission 写成了 allow 但工具调用参数格式不对或者模型没正确生成 tool_calls。回到模型对话页面确认模型能力。4.3 bash 命令执行让 Agent 执行「运行git status」。成功返回仓库状态。记账 APP 里常用的是hvigorw assembleHap构建但这类命令耗时长建议还是手动跑Agent 只用来做轻量检查。bash 报错最常见的是命令本身不存在或路径不对先手动在终端跑一遍确认。4.4 todowrite / question 交互类todowrite 验证「创建一个待办列表包含生成报表页、补单元测试、更新资源」。成功时 Agent 会维护一个任务列表并在后续步骤里更新进度。question 验证让 Agent 在实现方案有分歧时向你提问成功时你会看到带选项的提问卡片可以选也可以自定义输入。4.5 lsp 实验性工具先设环境变量再启动DEVECO_EXPERIMENTAL_LSP_TOOLtrue deveco。然后让 Agent 执行「跳转到BillModel的定义」。支持的操作包括 goToDefinition、findReferences、hover、documentSymbol、workspaceSymbol、goToImplementation、prepareCallHierarchy、incomingCalls、outgoingCalls。如果报错说工具不可用八成是环境变量没生效重启 IDE 再试。5. 本篇常见错排查路径工具指令报错看着五花八门其实归成几类按下面路径走基本能定位。第一类permission denied或工具被拒绝。先看 permission 字段拼写allow/deny/ask三个值别写错。再看是不是被通配符覆盖了比如你给mymcp_*设了 ask某个具体 MCP 工具名不匹配这个前缀就不会走这条规则。第二类Agent 说要用工具但没执行。这通常是模型侧问题——模型没返回合法的 tool_calls或者返回了但参数不符合 schema。去模型对话页面单独测一次工具调用确认模型支持。TaoToken 接入的话检查 base_url 和鉴权头是否按文档配对了。第三类grep/glob 搜不到文件。九成是.gitignore或.ignore的问题。ripgrep 默认排除 gitignore 里的路径用.ignore显式放行。另外确认搜索路径是相对项目根还是绝对路径。第四类lsp 工具不可用。检查DEVECO_EXPERIMENTAL_LSP_TOOL或DEVECO_EXPERIMENTAL是否设为真值且是在启动 DevEco Code 之前设的。设完要重启。第五类websearch 不可用。确认是否用 DevEco Code 提供商或DEVECO_ENABLE_EXA是否为真值。这个工具无需 API Key直连 Exa AI 托管服务如果还是不行检查网络出口。第六类write 覆盖了不该覆盖的文件。这是权限设成 allow 的后果改回 ask并且养成让 Agent 先 read 再 write 的习惯。排查时建议开一个最小复现项目只放一个BillModel.ets逐条工具测排除项目复杂度干扰。6. 把工具指令调稳之后工具指令调通之后Agent 在记账 APP 里的价值才真正体现它能稳定地读模型、搜引用、改页面、跑检查而不是每次都在权限上卡壳。我的经验是permission 不要图省事全设 allow写操作和 bash 一定留 ask读操作放开MCP 用通配符统一管控。这样既让 Agent 跑得顺又不会某天醒来发现核心账目逻辑被改乱。如果你在接入或排障过程中卡住优先看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 相关的问题去 API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 重新确认。模型工具调用能力不确定时用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 快速验证。长期让 Agent 接管编码任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 会更合适。