已知限制与使用边界

AI Agent 可以显著提高开发效率，但仍受到模型能力、上下文、工具、工作区、网络和执行预算限制。文档应主动说明这些边界，避免把流程完成误解为结果可靠。

大型仓库

大型仓库可能超过模型上下文或检索能力。Agent 可能只看到部分文件、遗漏跨模块依赖，或根据摘要做出错误判断。

建议：

• 明确任务范围；
• 提供入口文件和相关模块；
• 先生成仓库结构摘要；
• 分阶段执行和验收；
• 对跨模块改动运行完整测试。

结构化输出不稳定

不同模型对 JSON、Tool Calling 和 Schema 的遵循程度不同。启用思考模式后，部分模型可能只返回 reasoning_content，而没有可解析的最终内容。

此类问题应通过模型配置、严格校验和有限重试处理，不能把思考文本直接当作结果。

多 Agent 冲突

多个 Agent 同时修改相同文件时，可能出现覆盖、重复实现、冲突合并或测试针对错误版本运行的问题。

使用 Swarm 前，应明确工作区模式、分支策略、合并责任人和最终测试对象。

长任务与恢复

长任务可能因模型超时、网络断开、服务重启、Sandbox 回收或队列异常中断。系统是否能从中间状态恢复，取决于当前版本和部署配置。

对于关键任务，应保留阶段性提交、状态快照和可重复执行的验证命令。

本地与云端差异

同一个任务在本地和云端环境中可能得到不同结果，常见原因包括：

• 操作系统和架构差异；
• 依赖版本不同；
• 网络访问策略不同；
• 环境变量和 Secret 不一致；
• 文件权限和路径差异；
• Docker、VM 或 Sandbox 限制。

MCP 兼容性

MCP Server 可以成功连接，但具体工具仍可能因为协议版本、Schema、认证、返回大小或传输方式而失败。

接入第三方 MCP 时，应逐个验证工具，而不是只验证 Server 在线。

测试可信度

Agent 可能误读测试输出、忽略跳过项、把环境失败当作代码失败，或把命令未执行误报为通过。

最终验收应检查真实命令、工作目录、退出码和测试统计。

权限与安全

Agent 获得的文件、Shell、网络和凭证权限越大，潜在影响范围越大。跳过审批并不会提高结果正确率，只会减少人工阻断。

高风险权限应仅在隔离环境中临时启用。

成本不可完全预测

任务成本会受到上下文长度、Agent 数量、模型选择、工具调用、重试次数和执行环境时长影响。复杂任务可能显著超出初始估计。

应设置 Token、时间、并发、重试和云资源上限。

结果需要人工复核

以下任务不应仅依赖 Agent 自动完成：

• 生产数据库结构变更；
• 身份认证、支付和权限系统修改；
• 基础设施删除或大规模迁移；
• 密钥、证书和安全策略变更；
• 法律、合规和隐私结论；
• 无法在目标环境中验证的发布任务。

当前文档边界

本文描述的是通用风险与建议，不代表所有功能都已在当前 Heicode 版本中实现。具体支持情况应以当前版本、部署方式、界面和发布说明为准。