工业 IDE Agent 工程化：多轮循环、工具安全与可观测性实践

把大模型接入 IDE 并不困难，真正的挑战是让它在真实工程中稳定运行：能够理解项目、调用工具、接受授权，并在失败后保持可解释、可恢复。

本文聚焦技术实现与工程取舍；面向使用者的功能概览见：工业机器人 IDE 智能助手：编程、诊断与 3D 场景协同。

本文以某工业 IDE Agent 的工程实践为背景，讨论多轮循环、提示词路由、工具安全、上下文管理、领域知识加载、外部工具协议和运行日志。为避免暴露具体产品与内部实现，文中的名称、接口、阈值和案例数据均已抽象化。

1. 两层架构：交互与执行分离

系统分为 Webview 和扩展宿主两层：

Webview
  ├─ 对话与流式渲染
  ├─ Agent 循环
  ├─ 上下文和工具编排
  └─ 工具请求
         ↓
Extension Host
  ├─ 消息校验
  ├─ 用户审批
  ├─ 文件、命令和诊断能力
  ├─ 外部工具客户端
  └─ 运行日志

Webview 负责交互和推理编排，但不是最终信任源。文件写入、命令执行和外部系统操作必须由宿主重新校验并完成审批。消息协议还应限制命令名、字段集合、字符串长度和对象深度，并使用会话标识隔离过期请求。

2. Agent 循环不只是持续请求模型

典型循环包含以下步骤：

1. 构造系统提示、对话历史、技能目录和工具描述；
2. 发起流式模型请求；
3. 聚合文本与工具调用；
4. 校验参数并按副作用分组；
5. 执行工具，将结果回填给模型；
6. 继续下一轮，直到生成最终答复。

只读查询适合并发，写操作和外部系统修改默认串行。对部分兼容模型，还需要处理工具调用被错误输出为普通文本的情况，但这类兜底必须经过严格解析，不能把任意文本当成可执行指令。

固定的调用次数或简单的“重复参数”判断容易误伤批量任务。更稳妥的约束包括用户取消、可配置运行时限、上下文预算和完成证据校验。

3. 提示词负责路由，领域知识按需加载

系统提示适合动态注入当前工作区、活动文件、项目元数据、安全边界和可用技能目录。项目类型应来自真实元数据，而不是根据目录名或文件名猜测。

当任务类型与当前项目不完全匹配时，温和提醒通常比一律阻断更实用。真正的领域资料应拆分为可按需加载的 Skill：

domain-skill/
  SKILL.md
  references/
    project-layout.md
    variables.md
    control-flow.md
    motion.md

系统提示只保留名称与用途，模型在命中任务后再加载相关章节。这样既减少上下文占用，也能让知识维护与主循环解耦。

4. 工具设计强调批量、证据和验证

多文件工程任务应优先提供批量读写能力，减少模型轮次和重复审批。批量操作必须限制文件数量、总数据量和单项大小，并在部分失败时返回逐项结果。

模型声称“完成”不等于任务真的完成。循环应检查是否存在成功的执行结果；工具被拒绝、超时或失败时，最终答复必须如实反映状态。

代码写入后还应主动调用 IDE 诊断能力。由于语言服务可能延迟更新，诊断工具可以短暂轮询并合并结果，避免第一次查询为空造成误判。

5. 审批必须留在可信宿主

风险操作通常需要临时允许、项目级允许、长期允许和拒绝等决策。授权应由宿主根据工具与规范化参数生成稳定指纹，并绑定当前会话；超时、窗口切换、取消和重复回复都要安全收敛。

持久化时只保存必要的授权规则，避免记录原始敏感参数。安装领域技能等低频操作可以采用统一默认位置，但覆盖已有内容仍应得到明确确认。

6. 上下文预算要区分累计消耗与单轮输入

累计 Token 反映成本，单轮输入才决定是否接近上下文上限。工程上可设置软阈值与硬阈值：接近软阈值时逐步压缩旧工具参数、早期工具结果和较早对话；超过硬阈值时停止继续膨胀并要求重新规划。

压缩应优先处理可重新查询的信息，保留最近的代码、诊断和执行结果。过早摘要关键工程数据会降低后续修复质量。

7. 外部工具与 3D 场景：查询统一，修改明确

外部工具可通过统一协议动态接入 Agent，但仍需经过宿主审批、超时、取消和结果预算控制。

复杂 3D 场景适合提供统一快照，一次返回模型概要、机器人状态、路径树、工具坐标系、工件坐标系和几何边界等信息。修改能力则保持独立并显式命名，便于审计副作用。

批量加载场景资源时要加入节流或队列。渲染系统不是普通数据库，瞬间加载大量网格可能造成内存和主线程压力。

8. 可观测性不能破坏主流程

运行日志应按项目与会话隔离，记录 Agent 生命周期、模型请求耗时、上下文压缩、工具执行、审批和异常信息。账号、令牌、绝对路径、项目名称与会话标识必须脱敏或散列。

日志数据需要先转换为可序列化的普通对象；日志写入失败只能产生告警，不能中断 Agent。分层耗时记录还能区分瓶颈究竟来自模型、宿主、外部工具还是渲染端。

9. 可复用的工程原则

1. 真实接口和元数据优先于推测；
2. 执行结果优先于模型表述；
3. 批量能力优先于大量单次循环；
4. 权限决策必须留在可信宿主；
5. 守护策略要控制误伤；
6. 日志等旁路能力不能影响主流程；
7. 累计成本和单轮上下文要分开衡量；
8. 排障必须覆盖模型、Webview、宿主和外部工具整条链路。

从演示原型到工程 Agent，差距不在工具数量，而在失败场景下是否仍然一致、可验证、可解释。