# uni-agent
uni-agent 是专为 uni-app / uni-app x 开发者打造的 AI 编程助手，内置了丰富的技能（Skills）、子智能体（Subagents）和知识库，帮助您高效完成跨平台应用开发。
它的设计理念和使用技巧另见 https://doc.dcloud.net.cn/uni-app-x/ai/
欢迎加入 uni-agent 技术交流群 交流讨论。
# 安装插件
如下图所示,工具栏,点击最右侧的 AI 图标,即可安装 uni-agent 插件。
# 启动插件
HBuilderX,可以通过以下方式打开聊天视图。
- 工具栏,点击最右侧的
AI图标 - 菜单【视图】【插件扩展视图】【uni-agent】
- 快捷键: Windows
Ctrl+Alt+I; MacOS⌃⌘I
# 连接到 LLM 服务
在 uni-agent 中要连接到 LLM 服务，主要有两类模型来源：
- DCloud 账户订阅（推荐） — 在 HBuilderX 中登录 DCloud 账户，通过订阅套餐获取可用模型配置。
- 自定义 Key — 通过设置面板手动填写 API Keys 等环境变量，接入自己的模型服务。
模型来源需要在设置中主动选择
打开 uni-agent 设置后，需要在 模型选择 中主动选择当前要使用的模型来源并保存，插件会按所选项加载 DCloud 订阅模型或自定义 Key。仅填写自定义 Key 不会自动覆盖 DCloud 订阅；只有选中 自定义Key 时，才会使用自定义环境变量。具体模型说明见后文 模型介绍。
# 方式一：DCloud 账户订阅（推荐）
通过 DCloud 账户订阅 uni-agent 套餐后，插件会自动获取套餐中的 API 地址、密钥和模型配置，无需手动填写任何环境变量。
默认使用的是全球顶尖的 AI Coding 模型。也可以在 uni-agent 的设置中选择聚合中转、DeepSeek V4 或智谱 GLM 模型。
# 订阅类型
目前订阅说明分为个人版和企业版：
套餐价格、额度、限额规则、续费、升配、自动续费等说明，请以对应订阅说明文档和 DCloud 开发者中心页面展示为准。
# 使用步骤
购买订阅或资源包
选择订阅类型与模型
- 打开 uni-agent 聊天视图，在
订阅类型中选择 个人版 或 企业版。 - 如当前账号同时拥有个人版与企业版授权，可按实际使用场景手动切换，两者互不影响。
- 选择企业版前，请确认当前成员已经获得企业席位或共享资源包权限。
- 打开 uni-agent 聊天视图，在
在设置中选择模型来源与档位
- 打开 uni-agent 设置，在 模型选择 中选择 默认模型、聚合中转、DeepSeek 或 智谱。
- 如果当前来源下提供了多个模型档位，可继续在 模型档位 中选择具体模型，例如
1x、2x、Flash、Pro、GLM-5.2。 - 点击【保存】后，插件会按所选模型来源和档位获取并注入对应配置；在聊天输入区的模型下拉中，也可以直接快速切换。
自动配置生效
- 插件会自动向 DCloud 服务端请求您的套餐信息。
- 使用
uni-agent时，插件自动从套餐信息中提取 API 地址、密钥、模型提供商和所选模型等配置。
# 企业版补充说明
- 成员需使用
uni-agent v1.7.1及以上版本，才能看到企业版切换选项。 - 在移动端切换到企业版的操作步骤：
- 确保已开启移动端远程控制。
- 在移动端APP界面右上角轻触菜单按钮后轻触切换到企业版。
# 自动配置行为
- 选择 DCloud 订阅模型时：如果当前选择了 默认模型、聚合中转、DeepSeek 或 智谱，插件会自动请求套餐信息并注入对应配置。
- 切换模型来源或档位时：在设置中切换模型来源或具体模型档位并保存后，插件会按新的选择重新初始化配置。
- 登出时：插件会清除所有通过订阅注入的环境变量，并重新初始化。
# 方式二：手动配置环境变量
如果您拥有自己的 API 密钥（例如自建服务或第三方提供），可以通过设置面板手动配置环境变量，并在 模型选择 中切换到 自定义Key。
注意：
智商不足的AI无法发挥uni-agent的威力，想达到数字员工的水平，符合要求的AI模型只有1、2家。
注意中转站的风险。你的代码逻辑、各种key信息（如支付key）泄露给中转站会造成很大危害；中转站的掺水行为也很严重。
每个AI会什么、不会什么，都是不一样的。uni-agent的调度、技能、知识库都是按照自带AI调教的。配置了其他模型后，可能会表现变差。
举个例子，某AI对uni的新功能了解度是70%，那么把所有uni文档都通过知识库放在前文里会造成大量token的浪费。
只需要提供AI不知道的30%即可。但这30%的背景知识对于另一个AI可能是不足的，因为它对uni的新功能掌握度达不到70%。
# 使用步骤
- 打开设置面板
- 在 uni-agent 的聊天界面中，点击
设置打开设置面板，然后在模型选择中切换到自定义Key配置
- 在 uni-agent 的聊天界面中，点击
- 填写环境变量
在编辑器中使用
KEY=VALUE格式填写环境变量，每行一个，以#开头的行为注释，会被忽略，点击此处查看环境变量详细说明。配置示例：
# uni-agent 配置 UNI_AGENT_BASE_URL=your_provider_api_base_url UNI_AGENT_API_KEY=your_api_key UNI_AGENT_PROVIDER=anthropic UNI_AGENT_MODEL=anthropic/claude-sonnet-4-5 UNI_AGENT_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5 UNI_AGENT_MODEL_CONTEXT_WINDOW=258000其中
UNI_AGENT_MODEL_CONTEXT_WINDOW为可选项，用于为 自定义Key 模式下的模型声明上下文窗口大小。
- 保存并生效
- 保存后，环境变量配置会存储在插件的全局存储中，下次初始化 uni-agent 时，这些环境变量会自动注入到进程中
# 模型介绍
uni-agent 内置模型主要服务于 uni-app / uni-app x 开发、项目理解、代码生成、重构、排障和工具调用。不同模型来源与档位代表不同的能力、速度、稳定性、成本和数据链路；同样是 1x、2x，在不同来源下也不代表同一个底层模型。具体底层模型会随服务端配置升级，文档不公开具体型号。
# 默认模型
默认模型是推荐优先使用的 DCloud 订阅模型来源。uni-agent 内置的技能（Skills）、知识库、项目分析和调度策略主要基于该来源完整验证，适合大多数开发任务。
1x：直连上一代国际顶尖模型，偏向日常高质量编码与稳定响应，适合常规问答、功能开发、代码解释、轻量重构和一般问题定位。2x：直连最新一代国际顶尖模型，使用更高能力档位，适合复杂需求拆解、跨文件重构、长上下文分析、疑难错误排查和高风险代码修改，通常消耗更高、响应时间更长。
# 聚合中转
聚合中转是 DCloud 订阅下的第三方中转线路。由于经过第三方中转，数据安全边界不如默认模型，不建议处理密钥、未公开业务策略或其它高度敏感内容。
1x：使用上一代国际顶尖模型，偏向响应效率与编码质量的均衡档位，适合日常代码生成、问题分析和中等复杂度的工具调用任务。2x：使用最新一代国际顶尖模型，偏向更强推理与复杂代码处理能力，适合架构分析、多步骤任务规划、跨模块修改和高难度排障，通常消耗更高、响应时间更长。
# DeepSeek
DCloud 订阅的国产模型来源，适合对国产化或数据出境更敏感的场景。
Flash：使用deepseek-v4-flash模型，偏向响应速度与消耗控制，适合日常问答、轻量代码生成、简单错误定位和短上下文任务。Pro：使用deepseek-v4-pro模型，偏向更强推理与复杂代码处理能力，适合复杂需求拆解、长上下文分析、跨文件修改和高难度排障，通常消耗更高、响应时间更长。
注意:
deepseek系列模型均不支持图片识别。
# 智谱
DCloud 订阅的智谱 GLM 模型来源，适合希望使用国产 GLM 能力的场景，当前以 GLM-5.2 档位为主。
注意:
智谱系列模型不支持图片识别。
# 模型计费与消耗说明
uni-agent 聚合了多个行业顶尖的大模型。由于不同模型的底层算力成本不同，每次问答的实际额度消耗会根据选择的模型及具体使用场景动态计算。
# 1. 影响计费的五大核心要素
每次问答的计费并不是固定的，而是由以下五个条件综合决定：
- 输入（Input Token）：您发送给 AI 的提示词和选中代码的长度。
- 输出（Output Token）：AI 生成的回复和代码长度。
- 缓存（Cache）：重复使用的上下文命中缓存时，通常会享受更低的计费折扣。
- 上下文大小（Context Size）：对话历史越长，或关联的本地项目文件越多，消耗的 Token 越多。
- 思考深度（Reasoning Depth）：选择不同“思考深度”时，模型消耗的 Token 也会不同，思考等级越高消耗越快。
# 2. 模型消耗速率与特性一览表
为了方便您合理规划额度，以下为各模型在相同条件下的相对消耗速率（以默认模型 1x 为基准）：
| 模型来源 | 档位名称 | 相对消耗速率 | 核心优势与适用场景 | 特殊注意事项 |
|---|---|---|---|---|
| 默认模型 (推荐优先使用) | 1x | 1x (基准) | 直连上上一代国际顶尖模型，偏向日常高质量编码与稳定响应，适合常规问答、功能开发、代码解释、轻量重构和一般问题定位。 | DCloud 订阅原生模型，优先推荐。 |
| 1.1x | 1.1x | 直连最新一代国际顶尖模型中档模型，偏向日常高质量编码与稳定响应，适合常规问答、功能开发、代码解释、轻量重构和一般问题定位。 | DCloud 订阅原生模型，优先推荐。 | |
| 2x | 2x | 直连上一代国际顶尖模型，使用更高能力档位，适合复杂需求拆解、跨文件重构、长上下文分析、疑难错误排查和高风险代码修改。 | DCloud 订阅原生模型，消耗更高，响应时间较长。 | |
| 2.1x | 2.1x | 直连最新一代国际顶尖模型，使用更高能力档位，适合复杂需求拆解、跨文件重构、长上下文分析、疑难错误排查和高风险代码修改。 | DCloud 订阅原生模型，消耗更高，响应时间较长。 | |
| DeepSeek (国产化/敏感出境) | Flash | 最低 (< 1x) | 使用 deepseek-v4-flash。响应极快，适合日常问答、轻量代码生成、简单错误定位和短上下文任务。 | ❌ 不支持图片识别。 |
| Pro | 约 1x | 使用 deepseek-v4-pro。适合复杂需求拆解、长上下文分析、跨文件修改和高难度排障。 | ❌ 不支持图片识别。 | |
| 聚合中转 (第三方线路) | 1x | 约 2x | 响应效率与编码质量均衡。适合日常代码生成、问题分析和中等复杂度的工具调用任务。 | ⚠️ 经过第三方中转，请勿处理密钥、未公开策略等高度敏感内容。 |
| 2x | 约 4x | 直连最新一代国际顶尖模型。适合架构分析、多步骤任务规划、跨模块修改和高难度排障。 | 消耗较高，响应时间较长。 | |
| 智谱 (国产 GLM 线路) | GLM 5.2 | 约 2.5x | 国产智谱顶尖档位。提供较强的逻辑推理能力，适合解决复杂问题或高难度排障。 | ❌ 不支持图片识别。消耗较高，建议按需调用。 |
注意:
智谱系列模型自2026年7月14日起由DCloud官方进行临时补贴，价格调整为 GLM 官方 API 计价的 2 折（综合倍率约 2.5x）。临时补贴结束后恢复原定价（综合倍率约 7x）。
# 3. 额度优化（省钱）与选型最佳实践
- uni-app 项目开发首选
默认模型 1x：因为内置的 uni-app 框架知识库和调度策略对该模型做了完整验证，它的回答在生态内最精准，且性价比最高。 - 注重隐私避免使用中转：如果您的项目中包含商业机密、支付密钥或未公开的业务核心逻辑，请坚守
默认模型或DeepSeek/智谱线路，避免切换至聚合中转。 - 善用“新会话”清理上下文：长会话会导致后续的每一次追加提问都带上所有历史记录，从而成倍增加输入 Token 的消耗。一个阶段的任务解决后，及时点击“新会话”可大幅节省额度。
# uni-agent 界面与核心功能
uni-agent 聊天视图可以理解为 4 个区域：
- 顶部工具区：新会话、历史会话、大纲、设置等入口
- 中间消息区：显示对话内容、工具执行过程与结果
- 底部输入区：输入问题、使用斜杠命令、切换执行模式
- 底部变更区：当 AI 修改代码后，显示当前仍需关注的文件变更
下面按实际使用场景介绍这些能力。
# 会话管理
# 新会话
用于开始一段全新的对话。点击聊天视图右上角【新会话】后，会创建一个新的会话并重置当前会话的大纲与对话上下文；当你需要切换问题主题、重新梳理需求，或希望避免旧对话内容影响新的讨论时，可以使用该功能。
# 历史会话
用于管理和回到以前保存的会话记录。便于你从过往对话中快速续聊或复盘。
查看历史会话 点击聊天视图右上角【历史会话】后，会弹出历史会话列表，并显示会话标题与时间，在历史会话列表中，点击某条记录即可加载该会话内容；加载后，你可以在原会话上下文中继续提问，或查看此前的分析与结论。
删除历史会话 当某些会话不再需要时，可以在历史会话列表中对对应记录执行删除操作，将其从历史记录中移除，以保持列表整洁。
# 大纲
用于查看当前会话的结构化摘要，并在长对话中快速定位关键内容。
查看会话大纲 点击聊天视图右上角【大纲】后，会在右侧展示由 uni-agent 基于当前对话自动生成的大纲条目。
快速定位 当对话内容较长时，可以在右侧大纲中点击对应条目，快速跳转/滚动到相关内容位置，从而减少手动翻找。
# 上下文窗口
此功能在 uni-agent v1.6.1+ 版本中提供。
这不是套餐额度，也不是对话消耗的Token数量。
# 理解上下文窗口：别让你的 AI 变成“鱼的记忆” 🐟
什么是上下文窗口？ 你可以把 AI 想象成一个记性极差但读书极快的天才。 它并不记得你昨天说了什么，而是当你每次发问时，它都会瞬间把这张叫作“上下文”的临时草稿纸从头到尾重读一遍。
上下文窗口的作用 AI 并不是真的有长久记忆。它之所以能接住你的话茬，是因为它在回答前，会快速复习这张“纸”上记录的聊天记录和代码片段。
它是如何“保持清醒”的？ 虽然这张纸的长度有限（uni-agent 设置了 258k 的超大容量），但 uni-agent 通过自动压缩机制解决了“失忆”问题。 当内容过多时，系统会自动精简之前的次要细节，确保核心需求和重要上下文始终留在纸上。
💡 小贴士：Token 是什么？ Token 是 AI 世界的重量单位。就像坐飞机有行李额度，一个汉字或一个单词都会占用一点点“额度”。 258k 额度很大，足够装下一本中型小说，但一次性塞入整个工程的代码，额度也会很快见底。
# 省钱与效率指南：别花“冤枉钱” 💰
Token 的使用量直接关系到算力成本。如果你不想浪费额度，请记住以下技巧：
- 新功能，新起点：如果你已经完成了一个模块，准备开始做完全无关的新功能，请务必开启新会话。如果不切断，AI 每次回答新问题都要被迫重读一遍旧功能的 200k(举例) 无用代码，白白消耗你的 Token 额度。
- 精简输入：避免发送大段重复的日志或无关的编译输出。信息越精炼，你的上下文窗口就越耐用。
- 利用压缩特性：当会话已经触发自动压缩后，AI 对细节的把握可能略有下降。如果你需要处理极其精密的算法逻辑，建议在当前会话重新提供一份简洁的背景代码，或者新开会话。
# 调整上下文窗口长度
灵活配置模型记忆深度，在响应速度、细节保留与 Token 成本之间找到最佳平衡点。
⚠️ 注意：设置面板中的上下文窗口调整仅对 DCloud 订阅模型显示；如果使用 自定义Key，请通过
UNI_AGENT_MODEL_CONTEXT_WINDOW环境变量手动指定。
通过上下文窗口界面右上角的 [设置] 按钮打开设置面板后，您可以手动调整上下文窗口的长度。
切换不同的订阅模型来源或模型档位后，可用上下文范围会按当前模型自动刷新：
- 如果当前模型支持可调范围，界面会显示默认值和最大值，并可通过滑杆调整。
- 如果当前模型使用固定上下文窗口，界面会显示固定值。
- 不同订阅模型来源的上下文窗口设置会分别保存。
💡 建议：在处理复杂问题、需要 AI 记住更多细节时(如大型项目重构、深度技术咨询)，可以适当调高窗口长度，以减少过早触发自动压缩的可能，保持更多上下文信息在 AI 的“视野”中。 调高的同时也会增加 Token 的使用量，建议根据实际需求进行调整。
# 输入、模式与快捷命令
# Code / Plan 模式切换
在输入框附近可以切换 Code 和 Plan 两种模式：
- Code 模式：适合直接让 uni-agent 读取项目、修改代码、执行工具、排查问题。
- Plan 模式：适合先让 uni-agent 梳理需求、分析方案、拆解步骤，再决定是否进入具体实现。
如果你已经明确要它直接动手改代码，优先使用 Code；如果问题较复杂、需要先讨论方案或生成实施计划，优先使用 Plan。
plan模式使用后，要实施时，记得切回code模式。
# 切换模型与思考深度
输入框左下角当前模型的下拉按钮，除了能切换 思考深度，也可以快速切换当前订阅模型的 模型来源 和 模型档位。
- 思考深度：常见选项包括 关闭、低、均衡、高、较高、极高。不同模型支持的档位可能不同，请以当前菜单显示为准。
- 模型来源与档位：在同一个下拉菜单的二级列表中，可以切换 默认模型、聚合中转、DeepSeek、智谱 及其对应档位，例如
1x、2x、Flash、Pro、GLM-5.2。 - 即时生效：切换后会对后续发送的消息立即生效，并记住当前选择。
- 自定义Key 模式：该位置会显示当前自定义模型名称，但不会提供订阅模型档位切换。
# /init：初始化项目规则与上下文
在输入框中输入 /init 并发送后，uni-agent 会自动分析当前代码仓库，并尝试创建或更新项目根目录下的 AGENTS.md，帮助后续的 AI 协作更贴合当前项目规范。
该过程通常会关注以下内容：
- 项目的构建 / lint / 测试命令
- 代码风格、命名、类型与错误处理约定
- 仓库中已有的 AI 协作规则，例如
AGENTS.md、CLAUDE.md、.cursor/rules/、.cursorrules、.github/copilot-instructions.md
如果你希望后续的 AI 改代码行为更贴合当前项目规范，建议先执行一次 /init。
# /undo：撤销上一轮对话及相关改动
在输入框中输入 /undo 并发送后，uni-agent 会尝试撤销上一轮对话及其关联的代码改动，用于快速回退刚刚那一轮不满意的结果。
适合以下场景：
- 上一轮生成的代码方向不对
- 刚才的修改需要整体撤回重做
- 希望回到上一个稳定状态重新提问
# /compact：压缩当前会话上下文
在输入框中输入 /compact 并发送后，uni-agent 会压缩当前会话中的历史上下文，保留后续继续交流所需的关键信息，以减少上下文占用。
适合以下场景：
- 当前对话已经很长，希望继续交流时减少上下文负担
- 需要保留已有结论，但不想让完整历史内容持续参与后续推理
- 长时间连续对话后，希望整理上下文再继续提出新问题
# 重新编辑最后一条用户消息
对于最后一条用户消息，可以直接在消息旁点击 重新编辑，修改原问题后再次发送，而不必重新手动复制整段内容。
这个功能适合：
- 微调刚才的需求描述
- 补充遗漏条件
- 基于上一条提问快速改写后重试
重新编辑并发送后，uni-agent 会基于更新后的问题重新继续后续流程。
# 项目上下文与设置
# 切换项目
用于切换 uni-agent 读取与回答时所基于的项目上下文。点击聊天视图右下角项目名称旁的【切换项目】后，会弹出可选项目列表，并标记当前正在使用的项目（例如“[当前项目] unix-demo”）。
切换项目会影响后续对话中“读取项目文件、理解目录结构、解析配置（如页面与路由）”的上下文来源。
# 同时处理多个项目的任务
如果您想让 uni-agent 同时处理多个项目的任务，可以将需要同步处理的项目在新窗体中打开，并在每个窗体的 uni-agent 视图中切换到对应项目，这样每个窗体的 uni-agent 就会基于当前所选的项目上下文进行对话和操作。
如下图，HBuilderX 同时导入了 unix-demo 和 hello-uni-app-demo 两个项目，我想让 uni-agent 同时处理这个两个项目的任务，那么我就可以将 hello-uni-app-demo 项目在新窗体中打开，然后再打开 uni-agent 聊天视图，这样新窗体的 uni-agent 就会基于当前所选的项目上下文进行对话和操作。
具体操作：在项目上点击右键，选择【在新窗体中打开】 > 在新窗体中的右上角点击 AI 以打开 uni-agent 聊天视图 > 在聊天输入框中开启新聊天即可。
# 设置
用于选择 uni-agent 当前使用的模型来源、模型档位，调整订阅模型的上下文窗口，配置权限自动允许，并在使用自定义 Key 时填写 API Keys 等环境变量。
点击聊天视图右上角【设置】进入配置面板后，先在 模型选择 中选择当前要使用的模型来源：默认模型、聚合中转、DeepSeek、智谱 或 自定义Key。如果当前订阅来源下提供了多个模型档位，可继续在 模型档位 中选择具体项；如果选择 自定义Key，再按 KEY=VALUE 的格式逐行填写环境变量（以 # 开头的行会被忽略）。设置页下方还可以开启 权限自动允许。点击【保存】后，所选模型来源、模型档位、权限设置和自定义环境变量会写入插件的全局存储，并在后续会话中生效。
# 模型和档位选择
模型选择用于指定 uni-agent 当前使用的模型来源和档位。不同来源和档位的能力定位、适用场景以及 1x / 2x 差异，详情请查看 模型介绍。
# 权限设置
设置窗口中的 权限自动允许 用于控制 uni-agent 是否自动通过常见权限请求。
- 开启后，会自动允许读写文件、执行命令和访问外部目录等权限请求。
- 仅建议在你信任的项目和运行环境中开启。
- 如果你希望每次涉及副作用操作都手动确认，请保持关闭。
# 文件变更展示
当 uni-agent 在对话过程中修改了项目文件后，聊天窗口底部会显示 文件变更列表，帮助你快速看到本轮对话影响了哪些文件。
这个区域的作用包括：
- 汇总当前仍需关注的文件修改
- 帮助你快速确认改动范围
- 作为继续查看、复核和后续处理代码改动的入口
如果一次对话修改了多个文件，建议在继续下一轮提问前，先查看这里列出的变更，确保当前修改符合预期。
# 环境变量说明
uni-agent 运行时常用的环境变量如下：
| 变量名 | 必填 | 说明 | 示例值 |
|---|---|---|---|
UNI_AGENT_BASE_URL | 是 | uni-agent API 服务的基础地址 | your_provider_api_base_url |
UNI_AGENT_API_KEY | 是 | API 认证密钥，用于身份验证 | your_api_key |
UNI_AGENT_PROVIDER | 是 | AI 模型提供商标识 | anthropic、openai-compatible |
UNI_AGENT_MODEL | 是 | 默认使用的模型 | anthropic/claude-sonnet-4-5 |
UNI_AGENT_SMALL_FAST_MODEL | 否 | 用于快速任务的小模型 | anthropic/claude-haiku-4-5 |
UNI_AGENT_MODEL_CONTEXT_WINDOW | 否 | 自定义Key 模式下声明模型的上下文窗口大小 | 258000 |
如果你使用的是 自定义Key，并且希望 uni-agent 按你的模型真实上下文窗口来估算和展示上下文容量，可以额外填写 UNI_AGENT_MODEL_CONTEXT_WINDOW。
openai-compatible 模型提供商配置说明
如果 UNI_AGENT_PROVIDER 配置为 openai-compatible，可以使用任何兼容 OpenAI API 的服务商和模型，例如 deepseek、azure-openai 等。
- 以 deepseek 模型提供商为例，环境变量配置如下：
UNI_AGENT_BASE_URL=https://api.deepseek.com
UNI_AGENT_API_KEY=your_deepseek_api_key
UNI_AGENT_PROVIDER=openai-compatible
UNI_AGENT_MODEL=openai-compatible/deepseek-chat
UNI_AGENT_SMALL_FAST_MODEL=openai-compatible/deepseek-chat
# 配置自定义规则
您可以在项目根目录创建一个 AGENTS.md 文件为 uni-agent 提供自定义规则，该文件中的规则会被注入到与大模型对话的上下文中，以便针对您的项目规范 uni-agent 的行为。
# uni-app的AGENTS.md 文件示例
# 项目自定义规则
## 项目概述
本项目是一个基于 uni-app 开发的跨平台电商应用，支持 H5、微信小程序和 App 三端。（**此处务必自行定义**）
## 技术栈
- 框架：uni-app（Vue 3 + Composition API）
- UI 组件库：uni-ui
- 网络请求：uni.request 封装
- 样式：SCSS，采用 BEM 命名规范
## 代码规范
- 页面文件放在 `pages/` 目录，按模块分子目录
## 接口约定
- 后端接口基础地址通过 `BASE_URL` 环境变量配置
- 所有接口返回格式为 `{ code, data, message }`，code 为 0 表示成功
- Token 存储在 `uni.getStorageSync('token')` 中，请求头携带 `Authorization: Bearer <token>`
## 注意事项
- 除了在web的条件编译中，其他情况不要使用 `window`、`document` 等浏览器专有 API，请使用 uni 提供的跨平台 API
- 图片视频字体等多媒体文件资源统一放在 `static/` 目录
# 子代理
子代理是面向特定开发任务提供的专业化协作能力，可以针对特定任务和工作流程进行配置。它可以为某类任务配置更聚焦的提示词、工具范围和行为约束，让 uni-agent 在处理复杂需求时按场景调用更合适的能力。
# 内置子代理
uni-agent 结合 uni-app / uni-app x 场景补充了专用子代理。以下是可用于日常开发任务的内置子代理。
| 子代理 | 适用项目 | 适用场景 | 典型任务 |
|---|---|---|---|
Code | 所有项目 | 直接开发、修改代码、执行工具、完成交付型任务 | 实现功能、修复 bug、重构代码、运行构建或测试 |
Plan | 所有项目 | 需求分析、方案设计、代码审查、实施计划 | 分析复杂需求、拆解任务、评估改动风险、生成实施方案 |
general | 所有项目 | 复杂问题研究、多步骤任务、并行处理 | 调研多个模块、整理复杂结论、执行跨文件分析 |
explore | 所有项目 | 只读代码库探索、快速搜索、定位实现 | 查找文件、搜索关键字、理解接口调用链路、回答代码结构问题 |
unicloud | uni-app x | uniCloud、云函数、云对象、云数据库、云端接口联调 | 设计云对象方法、排查云函数报错、检查数据库权限、分析前后端调用链路 |
uts_native | uni-app x | UTS、原生能力调用、平台差异、原生插件开发 | 编写 UTS 原生插件、处理 Android / iOS 差异、排查原生 API 调用问题 |
# 自定义子代理
uni-agent 支持通过 Markdown 文件自定义子代理。自定义子代理适合沉淀项目或团队中的专项能力，例如接口审查、兼容性检查、云端权限检查、业务模块重构建议等。
# 文件格式
每个 Markdown 文件定义一个子代理，文件需要放在 agents 目录直属层级下。文件 frontmatter 用于声明子代理配置，正文作为子代理的提示词内容。
frontmatter 支持的常用字段：
| 字段 | 说明 |
|---|---|
name | 子代理名称。建议使用唯一、稳定、易理解的英文标识 |
description | 子代理能力描述。应写清楚适用场景，便于 uni-agent 判断何时使用 |
注意 配置完成后，需要重启 HBuilderX，再次发起会话时，自定义子代理才会生效。
# 全局配置
全局子代理对所有项目生效，目录位置因操作系统而异：
- Windows：
%APPDATA%/HBuilder X/extensions/hbuilderx-ai-chat/uni-agent/agents - macOS：
~/Library/Application Support/HBuilder X/extensions/hbuilderx-ai-chat/uni-agent/agents
# 项目级配置
项目级子代理仅对当前项目生效，目录位于项目根目录下：
.hbuilderx/uni-agent/agents
当项目级子代理与全局或内置子代理同名时，项目级配置优先。
# 使用子代理
使用子代理时，需要在提示词中明确写出希望使用的子代理名称，并说明项目类型、任务背景和希望关注的专业方向。uni-agent 会根据提示词中的子代理名称和任务描述使用对应能力。
推荐写法：
使用 uts_native 子代理处理任务。我需要用 UTS 在 Android 端调用系统相册能力，请从 UTS 原生能力和跨平台兼容角度帮我设计实现方案。
使用 unicloud 子代理。调用 uniCloud 云对象时报权限错误，请按 uniCloud 场景帮我排查前端调用、云对象方法和数据库权限配置。
# 场景示例
以下示例展示如何通过 自定义技能 + 自定义子代理 的组合，定制一个代码审查工作流，该工作流可以自动对项目中修改的代码进行审核、修复、验证，直至满足代码审查要求。
自定义技能示例：.hbuilderx/uni-agent/skills/code_review/SKILL.md
---
name: code-review
description: 用于 review 当前工作区的代码，当用户要求 review 代码时使用
---
## 严格遵守
你必须将以下任务追加到你的任务列表中，根据下面定义的执行逻辑追踪并完成它：
- [ ] 1. 调用子Agent进行审查
- [ ] 2. 分析报告并决定是否修复
- [ ] 3. 修复代码
- [ ] 4. 重复步骤1~3
## 执行逻辑
- Step 1. **调用子Agent进行审查** 启动一个独立的 `code-reviewer` subagent，将用户的review需求交给该agent，将此agent命名为`代码评审员`
> 以下是对评审员的评审要求，你可以一并合到Prompt中发给它
> - 审查当前工作区中修改的代码
> - **重要** 评审报告必须以[PASS]或者[FAIL] 开头
> - 审核结果最后要输出此次审核的最终评分，满分100分
* 如果报告以 `[PASS]` 开头，表示代码已通过审查，流程结束，你向用户输出最终代码和“审查通过”的结论。
* 如果报告以 `[FAIL]` 开头，进入下一步。
- Step 2. **分析报告并决定是否修复** 处理`代码评审员`评审的结果，判断是否真的存在问题：
* 仔细阅读`代码评审员`列出的所有问题。
* 判断每个问题是否真实、是否需要修复。如果某些问题属于误报或不合理，你可以决定忽略它们。
* 如果有问题无法确定，或者存在疑问，向用户需求帮助，让用户来确认
* 对于需要修复的问题，在脑海（或执行环境）中规划修改方案。
- Step 3. **修复代码**
* 根据上述规划，完成代码修复。
* 修复时**仅针对报告中列出的问题**，不要引入额外的功能变更。
- Step 4. **重复步骤1~3**
* 将修复后的代码再次发送给 subagent `代码评审员`审查。
* 重复循环直到`代码评审员`返回 `[PASS]`。
自定义子代理示例：.hbuilderx/uni-agent/agents/code-reviewer.md
---
name: code-reviewer
description: 代码质量审查专家。审查代码的安全性、性能、可维护性和规范一致性。
---
你是一名代码审查专家，负责确保代码变更达到高质量标准。
## 工作流程
1. 通过 `git diff` 或用户指定确定待审查的代码变更
2. 阅读变更文件，理解上下文和意图
3. 按清单逐项检查，生成结构化报告
## 审查清单
- **代码质量**：简洁性、命名规范、重复代码、错误处理、测试覆盖
- **安全性**：硬编码密钥、输入验证、SQL注入/XSS等漏洞风险
- **性能**：算法复杂度、资源使用、潜在瓶颈
- **可维护性**：遵循项目规范、注释充分、模块边界清晰
## 输出格式
- ❌ **高风险**（必须修复）：位置+问题+修复示例
- ⚠️ **中风险**（建议修复）：位置+问题+改进方向
- 💡 **低风险**（可选项）：优化机会+参考方案
## 注意事项
- 必须实际阅读代码，不凭空论断
- 问题分类需符合实际严重程度
- 指出具体位置（文件:行号）
- 承认代码的优点，给出明确结论
# 注意事项
- 使用子代理时，需要在提示词中写出子代理名称，并自然描述任务场景；不需要使用特殊符号或额外命令。
- 内置子代理会按当前项目类型加载；如果项目类型识别不匹配，对应项目类型的内置子代理不会参与。
- 项目级子代理优先级高于全局子代理和内置子代理；同名配置会覆盖低优先级配置。
- 子代理描述越清晰，uni-agent 越容易在合适场景使用它。建议在
description中明确写出适用项目、任务类型和触发条件。
# 配置自定义技能
uni-agent 支持通过自定义技能（Skills）来扩展其能力。您可以创建自定义技能，让 uni-agent 在对话中根据业务场景进行自动调用。
自定义技能支持两种配置方式：全局配置 和 项目级配置。
# 配置优先级
当同名技能同时存在于多个位置时，优先级如下：
项目级配置 > 全局配置 > 内置技能
# 全局配置
全局配置的技能对所有项目生效，技能目录位置因操作系统而异：
- Windows：
%APPDATA%/HBuilder X/extensions/hbuilderx-ai-chat/uni-agent/config/skills - macOS：
~/Library/Application Support/HBuilder X/extensions/hbuilderx-ai-chat/uni-agent/config/skills
# 项目级配置
项目级配置的技能仅对当前项目生效，技能目录位于项目根目录下：
.hbuilderx/uni-agent/skills
# 技能目录结构
每个技能是 skills 目录下的一个子文件夹，文件夹内包含一个 SKILL.md 文件：
skills/
└── my_skill/
└── SKILL.md
# SKILL.md 文件格式
SKILL.md 文件由两部分组成：
Frontmatter（YAML 格式）：定义技能的名称和描述，描述中应明确技能的调用要求和场景，以确保 Agent 能够准确使用
- name: 技能名称，必须唯一
- description: 技能描述，需详细说明技能的功能、调用条件和使用场景，帮助 Agent 理解何时以及如何调用此技能
- project: 技能适用的项目类型，支持
uniapp和uniappx，若为空，则代表支持所有项目类型- 在全局配置中，uni-agent 会判断SKILL项目类型与当前项目类型是否匹配，如果不匹配则不会将技能描述追加到提示词中，以节省token消耗
正文：技能被调用时发送给大模型的 Prompt 内容
# 配置示例
以下示例创建一个名为 code_review 的代码审查技能：
文件路径（全局配置 - Windows）：%APPDATA%/HBuilder X/extensions/hbuilderx-ai-chat/uni-agent/config/skills/code_review/SKILL.md
---
name: code_review
description: 对修改的代码进行审查，检查潜在问题并给出优化建议，编码完成后必须调用此技能
project: uniapp
---
请对以下代码进行审查，重点关注：
1. 代码逻辑是否正确
2. 是否存在性能问题
3. 是否符合 uni-app 跨平台开发规范（避免使用平台特有 API）
4. 命名是否清晰、规范
请给出具体的修改建议和优化后的代码。
配置完成后，需要重启 HBuilderX，再次发起会话时，Agent 会根据技能描述内容自动调用技能。
# 配置 MCP 服务
uni-agent 支持配置本地和远程 MCP 服务器。通过 MCP（Model Context Protocol），uni-agent 可以连接外部工具，将 MCP 服务提供的能力作为工具使用。
此功能在 uni-agent v1.6.3+ 版本中提供。
# 本地 MCP
本地 MCP 会在本机启动一个进程作为 MCP 服务端，通过标准输入输出（stdio）与 uni-agent 通信。
配置本地 MCP 时，需要将 type 设置为 "local"，并通过 command 指定启动命令及参数：
{
"type": "local",
"command": ["node", "/paths/some-mcp-server.js", "--some-args"],
"enabled": true,
"environment": {
"MY_VAR": "value"
}
}
# 远程 MCP
远程 MCP 通过 HTTP 地址连接已有的 MCP 服务，不需要在本机启动服务进程。
配置远程 MCP 服务功能在 uni-agent v1.6.8+ 版本中提供
配置远程 MCP 时，需要将 type 设置为 "remote"，并通过 url 指定远程 MCP 服务地址：
{
"type": "remote",
"url": "https://my-mcp-server.com/mcp",
"enabled": true
}
如果远程 MCP 服务需要认证，可通过 headers 设置认证头，例如使用 Bearer Token：
{
"type": "remote",
"url": "https://my-mcp-server.com/mcp",
"enabled": true,
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
请根据 MCP 服务提供方的要求设置请求头名称和值。为避免泄露凭据，不建议将包含真实密钥的配置文件提交到代码仓库。
# 全局配置
全局配置对所有项目生效，需要在以下路径创建或编辑 config.json 文件：
- Windows：
%APPDATA%/HBuilder X/extensions/hbuilderx-ai-chat/uni-agent/config/config.json - macOS：
~/Library/Application Support/HBuilder X/extensions/hbuilderx-ai-chat/uni-agent/config/config.json
在 config.json 中通过 mcp 字段配置 MCP 服务器。mcp 对象中的每个键为服务器名称，值为该服务器的配置对象：
{
"mcp": {
"local-server-name": {
"type": "local",
"command": ["node", "/paths/some-mcp-server.js", "--some-args"],
"enabled": true,
"environment": {
"MY_VAR": "value"
}
},
"remote-server-name": {
"type": "remote",
"url": "https://my-mcp-server.com/mcp",
"enabled": true,
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
# 项目级配置
项目级配置仅对当前项目生效，需要在项目根目录下创建 MCP JSON 文件，如需配置多个则需要创建多个 MCP JSON 文件：
.hbuilderx/uni-agent/mcps/my-mcp-name.json
{
"type": "local",
"command": ["node", "/paths/some-mcp-server.js", "--some-args"],
"enabled": true,
"environment": {
"MY_VAR": "value"
}
}
其中 my-mcp-name 为 uni-agent 加载的 MCP 服务名称。项目级配置同样支持本地 MCP 和远程 MCP，例如远程 MCP 可配置为：
{
"type": "remote",
"url": "https://my-mcp-server.com/mcp",
"enabled": true,
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
配置参数与全局配置中 mcp["server-name"] 中的参数相同。当项目级与全局配置中存在同名服务器时，项目级配置优先。
# 配置项说明
mcp 对象中的每个键为服务器名称，值为该服务器的配置对象，支持以下字段：
| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
type | string | 是 | - | 服务器类型。"local" 表示本地 MCP，"remote" 表示远程 MCP |
command | string[] | 本地 MCP 必填 | - | 本地 MCP 启动命令及参数，数组形式。第一个元素为可执行文件路径或命令名，后续元素为传递给该命令的参数 |
url | string | 远程 MCP 必填 | - | 远程 MCP 服务地址 |
environment | object | 否 | {} | 传递给本地 MCP 服务器进程的环境变量，以键值对形式定义 |
headers | object | 否 | {} | 连接远程 MCP 服务时随请求发送的请求头。远程 MCP 需要认证时，仅支持通过该字段设置认证头 |
enabled | boolean | 否 | true | 是否启用该服务器。设为 false 可临时禁用而无需删除配置 |
timeout | number | 否 | 5000 | 获取工具列表的超时时间（毫秒）。如果 MCP 服务器启动较慢，可适当增大此值 |
配置保存后，需要重启 HBuilderX，再次发起会话时，uni-agent 即可加载新的 MCP 服务器。
如需使用 Figma 或蓝湖 MCP 实现设计稿转代码，请参考：uni-agent 使用 Figma / 蓝湖 MCP 实现设计稿转代码
# 配置自定义命令
uni-agent 支持通过自定义命令保存常用提示词，便于你在聊天输入框中通过 /命令名 快速调用。它适合处理那些会反复执行的任务，例如审查当前改动、补充文档说明、分析报错原因等。
# 内置命令
uni-agent 当前内置了以下命令：
/init：初始化项目规则与上下文/undo：撤销上一轮对话及相关改动/compact：压缩当前会话上下文，减少上下文占用，便于在长对话中继续交流
这些内置命令由系统提供，不可自定义，也不可覆盖。
# 创建自定义命令文件
自定义命令通过项目级 Markdown 文件进行配置，文件目录位于项目根目录下：
.hbuilderx/uni-agent/commands/
配置规则如下：
- 每个 Markdown 文件对应一个自定义命令，文件名即命令名，例如
review.md对应/review - 文件 frontmatter 中可通过
description指定命令描述 - 配置完成后，需要重启 HBuilderX 才能生效
# 自定义命令示例
例如，在项目根目录下创建文件 .hbuilderx/uni-agent/commands/review.md：
---
description: 审查当前改动并给出改进建议
---
请检查当前项目中的改动，重点关注以下内容：
1. 是否存在明显的逻辑错误
2. 是否有潜在的兼容性或健壮性问题
3. 是否有可以优化的实现方式
4. 如果发现问题，请给出具体修改建议
创建完成并重启 HBuilderX 后，即可在聊天输入框中输入：
/review
uni-agent 会读取该命令文件中的内容，并按预设提示词执行对应任务。
# 移动端
需 uni-agent v1.6.0+、DCloud App v3.8.25+ 版本支持
它是你电脑上 HBuilderX AI 的伴随端。离开工位后，你也可以在手机上继续与 AI对话、追加任务、处理授权、查看结果，随时跟进任务进展。
# 怎么用
- PC 端：打开 HBuilderX，在 uni-agent 右下角开启“远程控制”开关
- 移动端：打开 DCloud App，连接对应的电脑服务端；如果出现多个服务端，选择你要操作的那一台电脑。
鸿蒙系统：由于目前 DCloud App 暂未适配原生鸿蒙（HarmonyOS NEXT），因此无法直接在鸿蒙系统中安装运行。目前可以通过「卓易通」来兼容运行。安装方法：
- 下载Dcloud App的apk安装包
- 点这个文件，打开方式选“卓易通”，按提示点允许安装。
注意⚠️：电脑务必设置避免自动休眠
# 常用功能
- 随时查看任务进展
- 继续与 AI 对话，补充需求或追加任务
- 及时处理权限确认
- 查看项目代码和执行结果
- 手机端除了可以指挥AI外，还可以手机预览和发布应用，包括
- web版发布到uniCloud的前端网页托管，在手机上看效果
- 打包apk下载到手机上看效果
- 上传uniCloud云函数部署服务器
# 遇到问题先看这里
- 看不到服务端：请检查电脑上的 HBuilderX、uni-agent 和“远程控制”开关是否正常开启
- 连上后没有内容：请重新选择历史会话，或断开后重新连接
# uni-agent CLI 使用指南
uni-agent 提供了一个轻量的命令行接口（CLI），旨在支持无图形界面（Headless）或自动化脚本场景下的任务执行。
注意：此Cli是HBuilderX的cli工具，一般在HBuilderX.exe的同级目录中（macOS 为 HBuilderX.app 内的 Contents/MacOS 目录）。
# 用法
./cli uni-agent --prompt <instruction> --project <absolute_path> [options]
# 示例
# 基本用法
直接向 AI 发送代码修改或解释指令：
uni-agent --prompt "查看当前项目" --project "/abs/path/to/project"
# 上下文对话
使用 --continue 参数在当前 Session 中追加后续指令：
uni-agent --prompt "现在使用 async/await 模式重写" --project "/abs/path/to/project" --continue true
# 安全性与权限
# YOLO 模式
默认情况下，uni-agent 在执行任何具有副作用的操作（如写入文件、执行 shell 脚本）前都会请求人工确认。使用 --yolo 模式可跳过所有安全提示，实现全自动化执行。
警告: 使用 YOLO 模式允许模型在没有监督的情况下修改本地文件系统。
请确保在使用 --yolo 参数前已做好充分准备和备份，以避免潜在的数据丢失或安全风险。
uni-agent --prompt "重构所有导出函数以使用命名导出" --project "./" --yolo true
# 参数参考
| 参数 | 类型 | 描述 |
|---|---|---|
--prompt | string | 必填。 发送给 Agent 的指令或问题。 |
--project | string | 必填。 目标项目目录的绝对路径。 |
--continue | boolean | 如果为 true，则在当前会话中追加后续指令。 |
--yolo | boolean | 如果为 true，则自动批准所有工具执行和文件修改。 |
--help | boolean | 显示此帮助信息并退出。 |
注意：CLI 模式下的所有操作都将直接影响项目文件，请确保在使用
--yolo参数前已做好充分准备和备份。
# 安装指定版本
如需使用某一特定版本的 uni-agent 插件（例如兼容性要求或回退到旧版本），请前往 uni-agent 的插件页面操作：
- 打开上述链接，进入 uni-agent 的插件详情页。
- 在「更新记录」中找到目标版本，点击该版本右侧的 「下载此版本」，下载对应版本的插件包（ZIP）。
- 将插件拷贝到 HBuilderX 插件目录：解压下载的 ZIP，将解压得到的插件文件夹复制到 HBuilderX 的
plugins目录下。解压后的文件夹名带版本号（如hbuilderx-ai-chat_1.5.1.260312193），复制时请将文件夹重命名为hbuilderx-ai-chat（去掉版本号后缀），否则插件可能无法被正确识别。- Windows：HBuilderX 安装目录下的
plugins目录 - macOS：
HBuilderX.app内Contents/HBuilderX/plugins目录（右键 HBuilderX.app → 显示包内容 → 进入上述路径）
- Windows：HBuilderX 安装目录下的
- 安装后确认：重启 HBuilderX，再通过右上角的【AI】打开 uni-agent，确认版本与功能是否符合预期。
若安装或使用指定版本时遇到问题，可加入 uni-agent 技术交流群 咨询。
# 常见问题排查
# 点击右上角AI图标无法打开 uni-agent
该问题通常是由于升级 uni-agent 插件时，因插件目录下的文件被进程占用导致卸载插件时有残留文件，导致插件未安装成功。
解决办法
- 进入 HBuilderX 安装目录下的
plugins文件夹 - 找到
hbuilderx-ai-chat文件夹，并删除该文件夹（若删除失败，可查看是否有进程占用，杀掉进程后删除） - 重启 HBuilderX
- 点击右上角 AI 图标，根据引导重新安装 uni-agent 插件即可
如以上都解决不了，请 进入交流群 反馈问题
# 报错：小助手接口未配置，为了更好的发挥小助手的效果，目前仅订阅账号可以使用
目前uni小助手对应的AI，是DCloud免费补贴给开发者的，没有向开发者计费，所以非订阅模型不能使用。
# 报错：fetch failed
最常见的原因是防火墙、代理软件、VPN 或安全软件。 大多数情况下，先按下面步骤排查：
先暂时关闭系统防火墙，再重启 HBuilderX 后重试，如果关闭防火墙后恢复正常，优先放行报错里的端口，例如
4096配置防火墙具体步骤如下：
打开
系统设置并进入网络和Internet
进入
防火墙点击高级设置
点击
入站规则->新建规则
选择端口
选择TCP，并在输入框中填入报错中的端口号，比如：4096
选择允许连接
默认全部勾选
名称随意填写一个
保存后重启HBuilderX
如果开启了代理或者VPN，把
127.0.0.1、localhost、::1加入白名单或设为直连，再重启HBuilderX重试
如以上都解决不了，请 进入交流群
# 其他问题
如果您在使用 uni-agent 的过程中遇到任何问题或者有好的建议，欢迎加入我们的 uni-agent 技术交流群 沟通交流。
本页导读
