开发者接入总览

蜂巢把自然语言任务交给员工自己的智能体运行环境，并保存对话、文件和可重复使用的方法。接入前先确定：你要让自己的程序调用蜂巢，还是让蜂巢调用自己的业务系统？这决定了接口、身份和维护责任。

选择接入方式

你要完成什么	从哪里开始	交付什么
后端提交智能体任务，读取回答或文件处理结果	开放API	持有服务端Key的调用程序
任务耗时较长，提交后稍后读取结果	异步长任务	提交、轮询和取消逻辑
让脚本访问现有业务API	业务身份和Skill开发	业务网关、账号关联与查询脚本
把现有工具服务提供给智能体	MCP接入	只读Streamable HTTP服务
提供设备列表、报表或操作页面	业务面板	HTML或完整面板ZIP

Skill是一份可带脚本、模板和参考资料的工作说明。MCP是一种让智能体发现和调用外部工具的协议。业务面板则是员工直接打开的页面。三者可以配合使用，分配其中一项不会自动分配其它能力。

先分清三类权限

1. 蜂巢管理员分配员工可以使用哪些业务系统，以及哪些Skill、MCP和面板。
2. 蜂巢身份服务向目标业务系统证明：当前是哪名员工，他现在是否仍有这个系统的使用资格。
3. 业务系统把蜂巢身份关联到自己的业务账号，检查设备、记录和写操作等实际权限。

例如，员工有工单系统资格且获分配查询Skill，不代表他能读取所有工单。业务网关仍需核验身份，业务系统仍需按实际业务账号过滤结果。提示词和Skill中的文字不能代替这些检查。

“综合”或具体业务系统范围决定任务使用的上下文与能力目录；它不是独立文件系统或网络隔离。同一员工的不同对话共享他的持久工作空间。开放API调用也会使用Key绑定员工的工作空间，设计并发任务时要避免覆盖同名文件。

准备第一个只读接入

1. 选择一个能独立核对结果的查询，例如列出本人有权查看的工单。
2. 与管理员确认稳定的system_key、公共属性和测试员工的系统资格；需要什么资源就分别分配什么资源。
3. 若查询需要蜂巢业务身份，为该系统配置启用的统一身份客户端，并由业务后端保管客户端Secret。
4. 业务网关完成在线Token核验，业务系统完成用户关联与数据权限检查。
5. 选择Skill、MCP或面板，先跑通一次只读查询，再检查未关联、无权限、过期和撤权等失败场景。

成功应有可检查的业务结果。保存地址、通过包格式检查或连接测试，只能证明对应步骤完成，不能代替业务查询和权限验证。

三种身份不要混用

身份	用于什么	谁可以持有
开放API Key	外部后端调用蜂巢智能体	调用方后端
短期业务Token	Skill、MCP或面板调用指定业务系统	当次业务调用程序；仅在内存中使用
OIDC客户端Secret	业务后端兑换授权码或在线核验业务Token	业务后端

业务面板和公开网站不能保存开放API Key或客户端Secret。面板通过自己的异步接口取得短期身份，不读取工作台登录凭据；脚本通过Runtime内受控入口取得身份，不自己提交员工ID。

本文示例使用https://hive.example.invalid，该地址不能实际连接。接入时替换为管理员提供的蜂巢地址，按目标部署配置HTTPS与可信证书。凭据由服务端安全配置注入，示例不会提供可用凭据。

当前适用边界

当前蜂巢支持Hive Pi和OpenCode两种执行引擎。可用模型、业务资源和运行容量取决于企业配置及员工分配。开放API不是完整OpenAI协议实现，MCP也没有通用OAuth接入流程。

蜂巢目前处于单节点企业内网MVP阶段。本文说明当前产品契约，不证明某个部署已完成业务联调或生产验收。真实写操作的确认、幂等、结果回读和恢复办法，需要在具体业务系统中落实。

发生问题时，按接入排查确认失败发生在哪一步。