HarmonyOS掌上记账APP开发实践第87篇:DevEco Code AI Agent中如何配置和使用各种代理

HarmonyOS掌上记账APP开发实践第87篇:DevEco Code AI Agent中如何配置和使用各种代理 代理配置和使用专门的代理。代理是专门的 AI 助手可以针对特定任务和工作流程进行配置。它们允许您创建具有自定义提示词、模型和工具访问权限的专用工具。Tip使用 Plan 代理来分析代码和审查建议而不会进行任何代码更改。您可以在会话期间切换代理或使用提及来调用它们。类型DevEco Code 中有两种类型的代理主代理和子代理。主代理主代理是您直接交互的主要助手。您可以使用Tab键或配置的switch_agent快捷键来循环切换它们。这些代理处理您的主要对话。工具访问通过权限进行配置——例如Build 启用了所有工具而 Plan 则受到限制。Tip您可以在会话期间使用Tab键在主代理之间切换。DevEco Code 内置了三个主代理Build、Goal和Plan。我们将在下面介绍它们。子代理子代理是主代理可以调用来执行特定任务的专业助手。您也可以通过在消息中 提及它们来手动调用。DevEco Code 内置了两个子代理General和Explore。我们将在下面介绍它们。内置代理DevEco Code 内置了三个主代理和两个子代理以及若干隐藏的系统代理。使用 Build模式primaryBuild 是启用了所有工具的默认主代理。这是用于需要完全访问文件操作和系统命令的开发工作的标准代理。使用 Goal模式primary一个多轮目标驱动代理遵循 5 阶段 SDD规范驱动开发工作流需求分析 → 架构设计 → 任务分解 → 实现 → 验证。每个阶段完成后需经用户确认才能进入下一阶段确保高质量的工程产出。实现阶段委托给spec-implementation子代理验证阶段委托给spec-verify子代理。使用 Plan模式primary一个专为规划和分析设计的受限代理。我们使用权限系统来为您提供更多控制权并防止意外更改。默认情况下以下所有项均设置为askfile edits所有写入、补丁和编辑bash所有 bash 命令当您希望 LLM 分析代码、建议更改或创建计划而不对代码库进行任何实际修改时此代理非常有用。使用 General模式subagent一个用于研究复杂问题和执行多步骤任务的通用代理。拥有完整的工具访问权限todo 除外因此可以在需要时修改文件。可用于并行运行多个工作单元。使用 Explore模式subagent一个用于探索代码库的快速只读代理。无法修改文件。当您需要按模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时请使用此代理。使用 Compaction模式primary隐藏的系统代理将长上下文压缩为较小的摘要。它会在需要时自动运行且无法在 UI 中选择。使用 Title模式primary隐藏的系统代理用于生成简短的会话标题。它会自动运行且无法在 UI 中选择。使用 Summary模式primary隐藏的系统代理用于创建会话摘要。它会自动运行且无法在 UI 中选择。使用 Spec-Implementation模式subagent隐藏的子代理由 Goal 代理在第 4 阶段自动调用。它根据已审批的规范文档执行实现任务环境搭建 → 基础功能 → 用户故事 → 最终打磨并返回实现报告。使用 Spec-Verify模式subagent隐藏的子代理由 Goal 代理在第 5 阶段自动调用。它负责构建、部署和 UI 验证支持两种验证范围仅构建验证build-only和构建 UI 验证buildui并返回结构化的验证报告。用法对于主代理在会话期间使用Tab键循环切换。您也可以使用配置的switch_agent快捷键。子代理可以通过以下方式调用由主代理根据其描述自动调用以执行专门任务。通过在消息中 提及子代理来手动调用。例如general help me search for this function会话间导航当子代理创建自己的子会话时您可以使用以下方式在父会话和所有子会话之间导航LeaderRight或配置的session_child_cycle快捷键向前循环父会话 → 子会话1 → 子会话2 → ... → 父会话LeaderLeft或配置的session_child_cycle_reverse快捷键向后循环父会话 ← 子会话1 ← 子会话2 ← ... ← 父会话这使您可以在主对话和专门的子代理工作之间无缝切换。配置您可以自定义内置代理或通过配置创建自己的代理。代理可以通过两种方式进行配置JSON在deveco.json配置文件中配置代理{ $schema: https://opencode.ai/config.json, agent: { build: { mode: primary, model: deveco/glm-5.1, prompt: {file:./prompts/build.txt}, tools: { write: true, edit: true, bash: true } }, plan: { mode: primary, model: deveco/glm-5.1, tools: { write: false, edit: false, bash: false } }, code-reviewer: { description: Reviews code for best practices and potential issues, mode: subagent, model: deveco/glm-5.1, prompt: You are a code reviewer. Focus on security, performance, and maintainability., tools: { write: false, edit: false } } } }Markdown您还可以使用 Markdown 文件定义代理。将它们放在全局~/.config/deveco/agents/项目级.deveco/agents/--- description: Reviews code for quality and best practices mode: subagent model: deveco/glm-5.1 temperature: 0.1 tools: write: false edit: false bash: false --- You are in code review mode. Focus on: - Code quality and best practices - Potential bugs and edge cases - Performance implications - Security considerations Provide constructive feedback without making direct changes.Markdown 文件名即为代理名称。例如review.md会创建一个名为review的代理。选项让我们详细了解这些配置选项。描述使用description选项提供代理的功能及使用场景的简要描述。{ agent: { review: { description: Reviews code for best practices and potential issues } } }这是一个必需的配置选项。温度使用temperature配置控制 LLM 响应的随机性和创造力。较低的值使响应更加集中和确定而较高的值则增加创造力和多样性。{ agent: { plan: { temperature: 0.1 }, creative: { temperature: 0.8 } } }温度值通常范围为 0.0 到 1.00.0-0.2非常集中和确定性的响应适合代码分析和规划0.3-0.5平衡的响应兼顾一定创造力适合一般开发任务0.6-1.0更有创造力和多样性的响应适合头脑风暴和探索{ agent: { analyze: { temperature: 0.1, prompt: {file:./prompts/analysis.txt} }, build: { temperature: 0.3 }, brainstorm: { temperature: 0.7, prompt: {file:./prompts/creative.txt} } } }如果未指定温度DevEco Code 将使用模型特定的默认值大多数模型通常为 0Qwen 模型为 0.55。最大步数控制代理在被强制以纯文本响应之前可以执行的最大代理迭代次数。这允许希望控制成本的用户对代理操作设置限制。如果未设置此选项代理将持续迭代直到模型选择停止或用户中断会话。{ agent: { quick-thinker: { description: Fast reasoning with limited iterations, prompt: You are a quick thinker. Solve problems with minimal steps., steps: 5 } } }当达到限制时代理会收到一个特殊的系统提示词指示其回复工作摘要和建议的剩余任务。⚠️Caution旧版maxSteps字段已弃用。请改用steps。禁用设置为true以禁用代理。{ agent: { review: { disable: true } } }提示词使用prompt配置为代理指定自定义系统提示词文件。提示词文件应包含针对代理用途的具体指令。{ agent: { review: { prompt: {file:./prompts/code-review.txt} } } }此路径相对于配置文件所在位置。因此它同时适用于全局 DevEco Code 配置和项目级配置。模型使用model配置为代理覆盖模型。适用于针对不同任务使用不同的优化模型。例如用更快的模型进行规划用更强大的模型进行实现。Tip如果您不指定模型主代理将使用全局配置的模型而子代理将使用调用它的主代理所使用的模型。{ agent: { plan: { model: deveco/glm-5.1 } } }DevEco Code 配置中的模型 ID 使用provider/model-id格式。例如deveco/glm-5.1。工具使用tools配置控制代理中可用的工具。您可以通过将特定工具设置为true或false来启用或禁用它们。{ $schema: https://opencode.ai/config.json, tools: { write: true, bash: true }, agent: { plan: { tools: { write: false, bash: false } } } }Note代理级配置会覆盖全局配置。您还可以使用通配符同时控制多个工具。例如要禁用 MCP 服务器中的所有工具{ $schema: https://opencode.ai/config.json, agent: { readonly: { tools: { mymcp_*: false, write: false, edit: false } } } }了解更多关于工具的信息。权限您可以配置权限来管理代理可以执行的操作。目前edit、bash和webfetch工具的权限可以配置为ask— 运行工具前提示审批allow— 允许所有操作无需审批deny— 禁用该工具{ $schema: https://opencode.ai/config.json, permission: { edit: deny } }您可以按代理覆盖这些权限。{ $schema: https://opencode.ai/config.json, permission: { edit: deny }, agent: { build: { permission: { edit: ask } } } }您还可以在 Markdown 代理中设置权限。--- description: Code review without edits mode: subagent permission: edit: deny bash: *: ask git diff: allow git log*: allow grep *: allow webfetch: deny --- Only analyze code and suggest changes.您可以为特定的 bash 命令设置权限。{ $schema: https://opencode.ai/config.json, agent: { build: { permission: { bash: { git push: ask, grep *: allow } } } } }这可以使用 glob 模式。{ $schema: https://opencode.ai/config.json, agent: { build: { permission: { bash: { git *: ask } } } } }您还可以使用*通配符来管理所有命令的权限。由于最后匹配的规则优先请将*通配符放在前面将具体规则放在后面。{ $schema: https://opencode.ai/config.json, agent: { build: { permission: { bash: { *: ask, git status *: allow } } } } }了解更多关于权限的信息。模式使用mode配置控制代理的模式。mode选项用于确定代理的使用方式。{ agent: { review: { mode: subagent } } }mode选项可以设置为primary、subagent或all。如果未指定mode则默认为all。隐藏使用hidden: true将子代理从自动补全菜单中隐藏。适用于只应由其他代理通过 Task 工具以编程方式调用的内部子代理。{ agent: { internal-helper: { mode: subagent, hidden: true } } }这仅影响自动补全菜单中的用户可见性。如果权限允许模型仍然可以通过 Task 工具调用隐藏的代理。Note仅适用于mode: subagent的代理。任务权限使用permission.task控制代理可以通过 Task 工具调用哪些子代理。使用 glob 模式进行灵活匹配。{ agent: { orchestrator: { mode: primary, permission: { task: { *: deny, orchestrator-*: allow, code-reviewer: ask } } } } }当设置为deny时子代理将从 Task 工具描述中完全移除因此模型不会尝试调用它。Tip规则按顺序评估最后匹配的规则优先。在上面的示例中orchestrator-planner同时匹配*deny和orchestrator-*allow但由于orchestrator-*在*之后所以结果为allow。Tip用户始终可以通过自动补全菜单直接调用任何子代理即使代理的任务权限会拒绝它。颜色使用color选项自定义代理在 UI 中的视觉外观。这会影响代理在界面中的显示方式。使用有效的十六进制颜色例如#FF5733或主题颜色primary、secondary、accent、success、warning、error、info。{ agent: { creative: { color: #ff6b6b }, code-reviewer: { color: accent } } }Top P使用top_p选项控制响应多样性。这是控制随机性的温度替代方案。{ agent: { brainstorm: { top_p: 0.9 } } }值范围从 0.0 到 1.0。较低的值更加集中较高的值更加多样化。其他选项您在代理配置中指定的任何其他选项都将作为模型选项直接传递给提供商。这允许您使用提供商特定的功能和参数。例如使用 OpenAI 的推理模型时您可以控制推理力度{ agent: { deep-thinker: { description: Agent that uses high reasoning effort for complex problems, model: openai/gpt-5, reasoningEffort: high, textVerbosity: low } } }这些附加选项是模型和提供商特定的。请查阅您的提供商文档以获取可用参数。Tip运行deveco models查看可用模型列表。创建代理您可以使用以下命令创建新代理deveco agent create此交互式命令将询问代理的保存位置——全局或项目级。描述代理应该做什么。生成合适的系统提示词和标识符。让您选择代理可以访问哪些工具。最后创建一个包含代理配置的 Markdown 文件。使用场景以下是不同代理的一些常见使用场景。Build 代理启用所有工具的完整开发工作Goal 代理规范驱动的多阶段目标开发从需求到验证的全流程管控Plan 代理分析和规划不进行任何更改Review 代理具有只读访问权限和文档工具的代码审查Debug 代理专注于问题排查启用 bash 和读取工具Docs 代理文档编写具有文件操作但不使用系统命令示例以下是一些您可能会觉得有用的示例代理。Tip您有想要分享的代理吗提交 PR。文档代理--- description: Writes and maintains project documentation mode: subagent tools: bash: false --- You are a technical writer. Create clear, comprehensive documentation. Focus on: - Clear explanations - Proper structure - Code examples - User-friendly language安全审计代理--- description: Performs security audits and identifies vulnerabilities mode: subagent tools: write: false edit: false --- You are a security expert. Focus on identifying potential security issues. Look for: - Input validation vulnerabilities - Authentication and authorization flaws - Data exposure risks - Dependency vulnerabilities - Configuration security issues