网页是入口，契约才是边界：AI 时代的工程软件如何被系统调用

一套工程软件能打开项目、改参数、看结果，当然重要。

但如果它只能在自己的网页里工作，它就很难进入项目管理系统、审查平台和 AI Agent 的工作流。

最后就会变成：人会用，系统不会调；页面很完整，能力却出不去。

网页可以是入口，不能成为边界。

一、过去的软件围绕人操作，现在还要面对系统调用

传统工程软件主要服务一个明确的人机流程。

用户打开软件、选择文件、执行命令、查看结果，闭环就算成立。

今天的工作环境不一样了。

项目资料在企业平台里，模型在图形工作台里，计算在求解器里，问题清单要回到审查系统，最后还要进入报告和审批流程。

AI Agent 也不再满足于“点一下这个页面”。它会追问：

• 能调用什么能力；
• 输入是什么结构；
• 返回是什么结果；
• 哪些操作会改项目；
• 失败后怎么恢复；
• 结果能不能回到原始对象和证据。

如果这些问题没有答案，系统只能模拟点击，不能稳定使用专业能力。

按钮可以演示，契约才能集成。

二、工作台、核心能力和接入契约，是三件不同的事

专业软件至少可以拆成三层。

第一层是工作台。它把任务组织成人能理解的流程：打开项目、选择对象、调整参数、运行计算、查看结果、保存成果。

第二层是核心能力。它回答“软件真正会做什么”，比如图形渲染、几何处理、结构求解、规则检查、文件解析和报告生成。

第三层是接入契约。它规定外部系统怎么发现能力、传什么数据、收什么状态、处理什么错误、保存什么结果。

三层不能互相替代。

只有工作台，没有接入契约，软件很难嵌入别的系统。

只有 API，没有工作台，真实用户又很难检查过程、理解状态和处理异常。

核心能力不稳定时，界面和接口做得再完整，也只是把不确定性包装了两次。

三、Graphics 的做法：Workbench 和 SDK 不是同一种产品

ArchSight Graphics 现在把这三层分得很清楚。

Workbench v1.3.0 是官方工作台，负责 BIM/CAD 模型浏览、工程对象、参数化构件、项目文件和场景组织。

@archsight/graphics SDK v1.0.0 是二次开发入口，负责工程构件协议、项目文件类型、渲染计划和最小 viewer runtime。

两者用的是同一套核心能力，但面对的是不同责任。

SDK 一旦对外，就不能再只依赖仓库内部路径。

当前发布边界固定了根入口和七个一级子路径，内置 examples/basic 和 examples/vanilla-ts，并通过公共 API 快照、真实 tarball 安装、类型检查、构建和浏览器 smoke 来验证。

这意味着，外部团队拿到的是可独立验证的发布包，不是只能在原仓库里跑通的示例。

这里也有一条必须说清的边界：SDK 目前仍采用私有预览和商业受控分发。“对外提供”指向获得授权的集成方承担公共接口承诺，不等于公开发布到 npm，也不等于核心实现已经开源。

这条边界也保护了 Workbench。

Workbench 可以继续迭代完整体验，SDK 只负责稳定契约。两者分开，产品才不会把内部实现和对外承诺绑死在一起。

ArchSight Graphics 在线体验：

https://graphics.archsight.cn/

四、Solver 的做法：能嵌入，不等于接入完成

ArchSight Solver 走的是另一条路。

它本身就是一套完整结构力学工作台，外部系统更需要的是把它嵌入现有业务页面，并由宿主管理项目生命周期。

当前线上版本已经更新到 v1.6.2。

v1.6.1 先把仓库内置 Reference Host 的基础接入闭环跑通。v1.6.2 在这条基线上继续往前走，把目标从“基础功能可接通”推进到“工作台可持续使用、宿主可稳定接入”：

• 独立工作台与嵌入模式使用同一套工程打开、修改、保存、恢复和只读边界；
• 同一份 canonical .slv 可以在两种模式下完成计算、修改失效、重算、导出、保存和重开；
• 建模问题和求解失败会返回带对象定位、原因与处理建议的结构化诊断；
• 结果记录模型签名、工程修订和请求来源，模型改变后旧结果立即失效并禁止导出；
• Host Protocol 1.0 固化了状态机、请求关联、超时、迟到消息和兼容规则；
• 新增无框架 TypeScript SolverHostClient，接入方不必再自行维护 postMessage 会话和保存超时。

这比“把网页放进 iframe”多做了一层。

嵌入只解决画面出现在哪里。接入还要解决项目属于谁、谁负责保存、怎样确认保存成功、怎样限制来源、怎样区分只读和可编辑、旧版本缺能力时怎么失败。

在 Reference Host 的实际界面中，宿主负责新建、打开、保存、只读和诊断入口；Solver 仍负责参数建模、结构计算、结果查看与导出。

Solver 的会话仍然使用协议版本、sessionId、nonce 和 requestId 关联消息；跨域宿主需要进入精确来源白名单。SolverHostClient 会统一处理 capability 协商、launch、保存握手、超时和迟到快照，避免出现“页面连上了，却无法可靠保存”的假成功。

这套统一验收已经进入 CI、tag release 和构建后 Docker 镜像门禁。线上版本发布页也已显示 v1.6.2。

它证明的是 Solver 自身的工作台与宿主接入基线已经升级，不代表任何外部客户系统已经完成接入。

ArchSight Solver 在线体验：

https://solver.archsight.cn/

开源仓库：

https://github.com/ArchSightLabs/archsight-solver

五、AI Agent 真正需要的，不是更多按钮

当专业软件开始被 AI Agent 使用，接入契约会比界面自动化更重要。

一个能用的 Agent 能力，至少要回答五件事。

1. 能力可以被发现

Agent 需要知道哪些动作是可执行的，哪些只是展示信息。模板、命令、参数和输出不能藏在操作手册里。

2. 输入必须结构化

工程对象、项目版本、荷载、构件、图层和状态都需要明确字段。让模型自己从说明里猜数据结构，等于把契约错误变成幻觉。

3. 结果必须可检查

专业结果不能只给一句自然语言总结。至少要保留对象标识、输入版本、执行状态、错误信息和必要证据，用户才能回到原始项目复核。

4. 副作用必须受控

读取、试算、修改和保存不是同一种权限。只读模式必须真的不能改；保存请求必须等宿主确认，不能把“消息已发出”写成“项目已保存”。

5. 失败必须可见

版本不兼容、输入无效、执行超时和结果缺失，都应该形成明确状态。Agent 最危险的行为不是报错，而是在没有完成时继续假装完成。

这些要求听起来像工程常识。到了 AI 场景里，它们反而更容易被忽略，因为自然语言会制造一种“什么都能接”的错觉。

模型可以理解很多表达，系统契约却不能靠猜。

六、不是所有能力都应该塞进同一个平台

强调可接入，不等于每套工程软件都要变成大型平台。

Graphics 不需要在 SDK 里内置企业账号、项目审批和组织协作。

Solver 也不需要把课程、订阅、远程存储和企业权限塞进开源核心。

这些能力应该由宿主系统负责。

专业模块负责自己最擅长的部分：图形、几何、求解、项目契约和结果表达。

宿主负责用户、权限、流程、存储和业务关系。

双方通过稳定协议连接。

这样做有两个好处。

一是责任清楚。出了问题，可以判断是专业能力、数据契约、宿主流程还是权限配置的问题。

二是演进更稳。业务平台可以换页面和流程，专业模块可以升级内部实现，只要公共契约不变，双方不必一起重写。

七、判断一套工程软件是否可接入，可以先看七件事

如果企业准备把一项专业能力接进现有系统，可以先看这七件事：

1. 是否存在明确、受版本管理的公共入口；
2. 是否有独立于原仓库的最小接入示例；
3. 项目文件和输入数据是否带版本与校验规则；
4. 读取、编辑、保存和导出是否有清楚的权限边界；
5. 失败、超时和不兼容是否对用户可见；
6. 自动化测试是否覆盖真实外部安装或跨系统交互；
7. 专业模块与账号、流程、存储等宿主职责是否分开。

其中任何一项缺失，都不代表产品不能用。

它只是在接入规模变大之后，更容易变成维护成本。

结语：界面负责让人工作，契约负责让系统协作

工程软件不会因为 AI 出现就失去界面。

专业人员仍然需要工作台来理解项目、检查输入、查看过程和复核结果。

AI Agent 也不能替代这些责任。

变化在于，界面不再是唯一入口。

一项专业能力既要能被人完整使用，也要能被其他系统稳定调用。前者依赖工作台，后者依赖公开契约、版本边界和验证证据。

未来更有生命力的工程软件，不一定是功能最多的软件。

它要清楚知道自己负责什么，也清楚知道怎样把这部分能力交给更大的工作流程。

如果你正在处理类似接入

如果你的团队正在把工程图形、结构计算或其他专业能力接进现有系统，欢迎通过文末入口或平台私信，简单说明当前系统、要接的任务和已经验证到哪一步。我们先判断边界是否对，再决定要不要继续往下走。

关注我们

欢迎搜索并关注 筑见实验室，获取更多建筑 AI、结构计算与工程数字化实践：