本系列的第一部分。第二部分将介绍完整的工具目录。第三部分将介绍 ObjectScript 技能。第四部分将介绍基准测试以及如何衡量实际的改进效果。
隐藏在注释中的问题
托马斯·马祖尔（Thomas Mazur）关于 VS Code 生产力——Peacock、作用域工作区文件、Copilot 代理模式——的 博文《青蛙、鸡、AI 和 VS Code》 在评论区揭示了一个更尖锐的问题。皮耶特罗·迪·莱奥（Pietro Di Leo）和 Mike.W 指出，当你在 VS Code 中进行服务器端开发时， isfs:// 大多数 IRIS 生产环境所使用的“工作区”中，Copilot 只能看到编辑器中打开的文件，无法对虚拟文件系统进行索引。对于拥有数千个类的成熟 IRIS 应用程序而言，AI 的工作效果就像是透过钥匙孔观察一样。
John Murray 向大家推荐了我正在开发的项目——iris-agentic-dev——并指出目前开发者社区中尚无相关文章。因此，本文将阐述：该问题产生的原因、该工具如何解决该问题，以及如何在约五分钟内完成部署。
为什么 AI 无法“看到”你的命名空间
当你打开一个 isfs:// 工作区时，你的 IRIS 类存储在服务器上，而非本地磁盘。VS Code ObjectScript 扩展会通过 Atelier API 按需将它们流式传输给你——打开一个类，它就加载该类；保存时，它就将文件写回服务器。这种机制在编辑时运行得非常顺畅。
像 Copilot 这样的 AI 助手的工作方式则不同。它们需要了解你正在编辑的文件周围的代码情况。 谁调用了这个方法？哪些类继承自该类？还有哪些代码会用到这个全局变量？在本地项目中，助手可以扫描文件来回答这些问题。而 isfs:// 工作区仅在你打开文件时才会加载文件，因此没有完整的文件可供扫描。
对于仅包含几个类的新项目，这种情况或许尚可接受。但对于生产环境中的 IRIS 系统——拥有上万个类、Ensemble 生产环境、自定义 %Library 子类，以及历经多年开发积累的业务逻辑——面对棘手的问题，AI 几乎变得毫无用处。 如果你自己粘贴上下文代码，它或许能帮你编写新方法。但它无法帮助你理解整个系统。
为 AI 提供另一种连接方式，使其能够直接向 IRIS 查询，而不是在磁盘上爬取数据。
什么是 iris-agentic-dev
iris-agentic-dev 是一个MCP 服务器——这是一个后台进程，为 AI 助手提供了一套工具，它们可以通过调用这些工具与正在运行的 IRIS 实例进行交互。 它支持 GitHub Copilot（通过 VS Code 扩展）、Claude Code、Cursor 和 OpenCode。IRIS 实例可在 Windows 或 Linux 上原生运行，也可在 Docker 中运行。
配置完成后，可直接在聊天界面中使用 MCP 服务器的工具。VS Code 1.99 及更高版本支持 Copilot 代理模式下的 MCP；Claude Code 和 OpenCode 自发布以来便已支持该功能。
iris-agentic-dev 通过与 ObjectScript 扩展相同的 Atelier REST API 连接到 IRIS。随后，该助手可以：
- 搜索整个命名空间——支持全文搜索、正则表达式搜索和按类别搜索，无需打开任何文件
- 编译类并获取带行号的错误信息
- 运行 ObjectScript并查看输出结果
- 针对任何命名空间执行 SQL 查询
- 检查类定义——属性、方法、参数、继承链
- 检查 Ensemble 生产流程——哪些项正在运行、各项之间的连接关系、消息正文、业务规则逻辑，以及运行配置与源代码控制之间的差异
- 运行单元测试并报告结果
- 调试——将 INT 行号映射回原始源代码行，提取错误日志
第 2 部分涵盖了完整的工具目录。助理无需根据几个打开的标签页进行猜测，而是可以直接向 IRIS 查询命名空间本身的信息。
---
与社区共建
我在自己的 IRIS 工作中屡次遇到这一限制后，便启动了这个项目。此后，社区的贡献一直塑造着它——这些贡献往往来自那些多次参与的同一批人。 约翰·默里（John Murray）曾在“青蛙与鸡”讨论帖中向大家推荐了这个项目，他还开发了您将在下文第 2 步中使用的“服务器管理器”身份验证集成：无需在配置文件中手动输入凭据，MCP 服务器会通过与 AuthenticationProvider 服务器管理器扩展本身所使用的机制，直接从操作系统钥匙串中读取凭据。多里安·特图（Dorian TETU）则在搜索准确性、源代码控制提取以及精准编辑差异方面贡献了修复方案。
该项目作为开源项目发布在 intersystems-community GitHub 组织下。欢迎提交贡献和错误报告，包括“在我的环境中无法运行”这类反馈。
入门指南：VS Code + GitHub Copilot
如果您已经使用安装了 InterSystems ObjectScript 扩展的 VS Code，这是最快捷的入门方式。
先决条件：VS Code、GitHub Copilot 订阅以及InterSystems ObjectScript 扩展（您几乎肯定已经安装了）。
步骤 1 — 安装 VS Code 扩展
在 VS Code 市场中搜索iris-agentic-dev并安装。首次激活时，该扩展程序会定位或下载 MCP 服务器二进制文件：如果你已将其添加到 PATH 环境变量中（例如通过 brew install iris-agentic-dev），则使用该二进制文件；否则会自动下载适合您平台的二进制文件。无论哪种情况，该扩展都会自动向 Copilot 注册——无需手动配置。
安装完成后，iris-agentic-dev 工具集将出现在 Copilot 的代理模式中。
步骤 2 — 验证连接
打开 Copilot Chat 并切换至代理模式。输入以下问题：
“调用 check_config 并向我显示结果。”
此时应能看到您的 IRIS 连接详细信息——主机、端口、命名空间、Atelier API 版本。如果已安装InterSystems Server Manager扩展，iris-agentic-dev 会自动查找您的服务器配置，并从操作系统钥匙串中检索凭据。 该 VS Code 扩展会跟随当前活动的 objectscript.conn，因此拥有多个 Server Manager 条目的开发者将持续使用该工作区所选的连接。若在 VS Code 扩展外部运行 MCP 服务器，当配置了多个服务器时，请将 IRIS_SERVER_NAME 设置为 intersystems.servers中选择相应的键。check_config的结果会显示当前活动的连接以及检测到的其他服务器。
check_config 确认了 Copilot 正在使用的 IRIS 主机、端口、命名空间和连接源。
步骤 3 — 提出一个需要整个命名空间的问题
现在尝试提出一个仅凭当前打开的标签页难以回答的问题：
“查找该命名空间中所有继承自
%Persistent的类 。一共有多少个？”“
MyApp.SomeClass上有哪些属性与方法 ？”“编译
MyApp.*.cls并显示所有错误。”
这些操作均无需您事先打开相关文件。助手会从 IRIS 中获取答案。
入门指南：Claude 代码
安装二进制文件（Mac）：
brew tap intersystems-community/tap
brew install iris-agentic-dev
或者直接从发布页面下载适用于 Mac Intel、Linux 或 Windows 的版本。
**配置连接。**创建 ~/.iris-agentic-dev.toml：
host = "localhost"
web_port = 52773
username = "_SYSTEM"
password = "SYS"
namespace = "USER"
使用 Claude Code 注册：
claude mcp add --scope user iris-agentic-dev -- iris-agentic-dev mcp
然后验证：
> Call check_config and show me the result.
示例：iris-agentic-dev工具如何支持分析 IRIS 互操作性应用程序
以下是与irisdemo-demo-readmission生产环境的实际交互示例——这是一个医疗互操作性演示，用于处理医院出院事件并评估患者的再入院风险。
“ADT A03出院消息是如何流经该生产环境的？”
步骤 1：查找已编译的内容。
iris_symbols("IRISDemo.*")
→ 31 classes: BO.*, BP.*, BS.*, DTL.*, Util.*, and more
关键类：IRISDemo.BP.ReadmissionRisk.Process、IRISDemo.DTL.HL7Discharge、IRISDemo.DTL.HL7Update、IRISDemo.HISHL7v2FileFeedRoutingRule。
步骤 2：查找路由器的规则。
extract_message_map_routing("IRISDemo.HISHL7v2FileFeedRoutingRule")
→ NOT_FOUND — Ens.Rule.Definition, not a routing table class
Ens.Rule.Definition 类在 XData 中包含路由逻辑。该工具无法映射该结构，因此请直接阅读类源代码：
iris_doc("IRISDemo.HISHL7v2FileFeedRoutingRule.cls") → XData rules:
Rule 1: docName=ADT_A01 or ADT_A08 → transform DTL.HL7Update, target Readmission Risk Process
Rule 2: docName=ADT_A03 → transform DTL.HL7Update, target Readmission Risk Process
A03 出院流程会经过 IRISDemo.DTL.HL7Update，该模块会在请求中添加 UpdateMessageType="A03" 字段——正是该字段使得业务流程能够根据出院与入院情况进行不同的分支处理。
步骤 3：映射业务流程。
extract_message_map_routing("IRISDemo.BP.ReadmissionRisk.Process")
→ kind: bpl, 4 outbound calls:
Update Encounter → LACE SOAP Operation
Calculate Risk with LACE → LACE SOAP Operation
Calculate Risk with ML → Readmission ML Model Consumer
EMR Readmission Update → HisDB Encounter Update Operation
步骤 4：获取完整的步骤树。
docs_introspect("IRISDemo.BP.ReadmissionRisk.Process") → xdata_flow:
Call: Update Encounter → LACE SOAP Operation
Call: Calculate Risk with LACE → LACE SOAP Operation
Call: Calculate Risk with ML → Readmission ML Model Consumer
Call: EMR Readmission Update → HisDB Encounter Update Operation [async]
If: Discharge OK?
(request.UpdateMessageType = "A03") && (context.UpdateEncounterResult = 1)
If: Risk Alert?
(context.RiskScore > 11) || (context.MLReadmissionRisk > 0.15)
assign: Compose Alert Message
Call: Add Patient to Risk Program → Care Team [async]
Call: Alert Care Team → Risk Alert Email Operation
sync: Follow up SLA 2 days
If: No follow up? (synctimedout)
本次会话还指出，存在一个 IRISDemo.DTL.HL7Discharge，它将 9 个 HL7 字段映射到一个 DischargeRequest —— 但路由规则从未将 A03 发送通过它。这是死代码，无需打开文件即可发现。
完整的交互过程——包括每次工具调用、响应及推理步骤——均收录于此GitHub Gist 中。
助手通过四个步骤回答了这个问题：A03出院数据到达路由器，被转换为一个 UpdateEncounterRequest，其中触发事件被标记为分支信号，随后业务流程依次运行 LACE 和 ML 风险评分——若任一评分超过阈值，则向护理团队发出警报并启动为期 2 天的随访。未打开任何文件。所有数据均来自 IRIS。
后续内容预告
第2部分——工具：对工具目录的实用指南：每种工具的功能、使用时机，以及它能解决哪些IRIS特有的问题。对于打开的编辑器缓冲区无法解答的问题，搜索、内省和Ensemble工具尤为有用。
第 3 部分 — 技能：实时连接无法弥补 AI 模型对 ObjectScript 理解的不足：细微的语法差异、%Status 传播、$$$ 宏，以及在通用训练数据中罕见的 COS 特有惯用语。 “技能”是针对这些弱点设计的简短指令文件。在我包含 22 个任务的 ObjectScript 修复测试套件中，一份名为 objectscript-review的205词检查清单，将针对Claude Sonnet 4.6的通过率从73%提升至100%——这仅是在一个小型公开测试套件上进行的一次运行，其中包含所有相应的限制条件。第3部分将介绍这些技能的功能；第4部分将探讨该数据的可信度。
第 4 部分——基准测试：基准测试框架的工作原理、运行方法以及数据含义。 其中包括技能在哪些方面有帮助、在哪些方面无效，以及至少有一项技能在全局加载时似乎会损害性能——指令越多并不总是越好。此外，还探讨了此规模测试套件的局限性：来自公开任务的污染风险、单次运行的变异性，以及为何针对一个模型测得的性能提升对另一个模型几乎没有参考价值。
链接
- GitHub：intersystems-community/iris-agentic-dev
- VS Code 扩展：Marketplace 上的 iris-agentic-dev（适用于 IRIS）
- 二进制文件（Mac、Linux、Windows）：发布页面
- 原始讨论帖：青蛙、鸡、AI 和 VS Code
Thomas Dyar —— InterSystems 公司人工智能平台与生态系统高级经理，iris-agentic-dev 作为开源项目发布于 intersystems-community GitHub 组织下。