BeeWorks IM SDK Docs
v1
文档/Browser JS SDK/开发指南

BeeWorks IMSDK Agent Skills ​

@beeworks/imsdk-agent-kit 是面向开发 Agent 的使用指引包。它把 BeeWorks Web IM SDK 与 Jitsi Adapter 的集成约束、生命周期语义和常见排障 路径整理成可被 Agent 按需加载的 Skill，帮助 Agent 在已有项目中选择正确的 API、配置浏览器资源并完成验证。

Agent Kit 不包含 IM SDK 运行时代码、WASM 文件或 Jitsi 服务，也不会改变线上 应用的依赖运行方式。运行时仍需按 快速开始 安装和配置 @beeworks/imsdk；嵌入 Jitsi 会议时再安装 @beeworks/imsdk-jitsi-adapter。

快速接入 Agent Skills ​

如果 Agent 已经安装并发现 Skill，直接描述开发任务即可，不需要再粘贴 prompt。 如果 Agent 不支持自动发现 npm 包里的 Skill，点击下面的按钮复制一次引导词，再 粘贴到开发对话中。按钮只复制内容，完整文本按需展开查看。

复制后粘贴到开发对话即可
展开查看完整内容
你是当前项目的开发 Agent。当前项目使用 BeeWorks Web IM SDK。

开始工作前，先加载 BeeWorks IMSDK Agent Kit，并把它作为本轮开发的工作规范。

【1. 加载 Skill】

优先读取项目依赖中的文件：

- node_modules/@beeworks/imsdk-agent-kit/skills/beeworks-imsdk/SKILL.md
- node_modules/@beeworks/imsdk-agent-kit/skills/beeworks-jitsi-adapter/SKILL.md

如果当前仓库直接包含 Agent Kit，则读取：

- packages/imsdk-agent-kit/skills/beeworks-imsdk/SKILL.md
- packages/imsdk-agent-kit/skills/beeworks-jitsi-adapter/SKILL.md

如果文件不存在，并且当前环境允许安装依赖，先执行：

    npm install --save-dev @beeworks/imsdk-agent-kit

安装后直接读取 node_modules 中的文件；不要假设刚安装的 Skill 已经自动注入到
当前对话。

【2. 按任务读取 references】

不要一次加载全部文档，只读取当前任务需要的 references：

- IMSDK 初始化、WASM、Vite、Webpack、SSR：
  beeworks-imsdk/references/initialization.md
- 登录、连接、事件和登出：
  beeworks-imsdk/references/events-and-lifecycle.md
- 消息、会话、好友、讨论组、会议和呼叫：
  beeworks-imsdk/references/features.md
- IMSDK 故障排查：
  beeworks-imsdk/references/troubleshooting.md
- Jitsi 接入流程：
  beeworks-jitsi-adapter/references/api-and-flow.md
- Jitsi 会话、角色、事件和清理：
  beeworks-jitsi-adapter/references/session-events.md
- Jitsi 加载、媒体和权限问题：
  beeworks-jitsi-adapter/references/troubleshooting.md

【3. 开发约束】

- 以项目当前安装的 @beeworks/imsdk 和 .d.ts 为 API 事实来源，不要凭旧示例猜测 API。
- 以项目当前安装的 @beeworks/imsdk-jitsi-adapter 类型和文档为事实来源。
- 不要把 Jitsi 依赖加入核心 IMSDK。
- 不要记录、持久化或展示 JWT、应用 Token 或完整的生产服务地址。
- SDK 源码改动放在 modules/。
- Protobuf 改动放在 proto/，然后运行 npm run compile:proto。
- 不要直接编辑 modules/protobufv3/、dist/ 或 WASM 生成物。
- 公共 API 改动需要更新 TSDoc、运行 npm run docs:gen，并在 demo/index.html 增加验证示例。
- 遵守仓库中的 AGENTS.md、CONTRIBUTING.md 及其他目录级开发规则。
- 完成修改后运行 npx tsc --noEmit 和与任务相关的测试。

【4. 开始任务】

先简要说明：

1. 识别到的 @beeworks/imsdk 和 @beeworks/imsdk-jitsi-adapter 版本。
2. 将使用的 Skill 和 references。
3. 准备修改的文件及验证方式。

然后再开始编码。遇到版本差异时，以当前项目源码、类型声明和 API 文档为准，并
明确指出差异，不要静默采用旧版本行为。

按步骤使用 ​

1. 安装 Agent Kit ​

将 Agent Kit 安装为开发工具，然后选择一种 Skill 发现范围。用户级和项目级安装 二选一，不需要同时执行：

bash
npm install --save-dev @beeworks/imsdk-agent-kit
# 用户级：当前用户的所有项目可用
npx beeworks-imsdk-agent-kit install --user

2. 选择 Skill 发现范围 ​

如果只希望当前项目使用 Skill：

bash
npx beeworks-imsdk-agent-kit install --target ./.agent-skills

安装器不会使用 npm postinstall，不会在安装依赖时隐式修改用户配置。已有 未受管理的同名 Skill 默认不会被覆盖；确需覆盖时显式添加 --force。

3. 开始开发 ​

安装并发现 Skill 后，直接向开发 Agent 描述任务即可。只有在 Agent 不支持自动发现 时，才使用上面“一步达成”里的复制按钮。也可以从命令行获取同一份引导词： npx beeworks-imsdk-agent-kit prompt；它与包内的 AGENT_BOOTSTRAP_PROMPT.md 保持同步。

包含的 Skill ​

beeworks-imsdk ​

用于核心 @beeworks/imsdk 的浏览器集成和 SDK 源码维护，覆盖：

  • init、login、连接与登出生命周期。
  • Vite、Webpack、script 标签和 SSR 场景下的 WASM 资源配置。
  • 消息、会话、好友、讨论组、会议和即时呼叫 API 的选择。
  • EVENT 事件语义、用户数据隔离和资源清理。
  • modules/、proto/、生成 protobuf、文档和 Demo 的修改边界。

beeworks-jitsi-adapter ​

用于 @beeworks/imsdk-jitsi-adapter 的浏览器会议集成，覆盖：

  • start()、join()、mount() 三种会议流程。
  • Jitsi External API 动态加载和 iframe 挂载。
  • 会话状态、主持人角色、参与者和设备错误事件。
  • leave()、end()、dispose() 的生命周期差异。
  • Jitsi 本地会话状态与核心 SDK MEETING_STATE_CHANGED 的边界。

常用命令 ​

bash
# 查看包内 Skill
npx beeworks-imsdk-agent-kit list

# 校验包内 Skill 或指定安装目录
npx beeworks-imsdk-agent-kit verify
npx beeworks-imsdk-agent-kit verify --target ./.agent-skills

# 卸载由 Agent Kit 管理的文件
npx beeworks-imsdk-agent-kit uninstall --user

卸载时，安装器会保留被开发者修改过的文件；只有显式传入 --force 才会删除 这些修改。

版本与安全 ​

Agent Kit 独立于运行时包发布。当前 references 面向以下版本范围：

text
@beeworks/imsdk: >=1.0.0 <2
@beeworks/imsdk-jitsi-adapter: >=0.1.0 <0.2.0

当项目使用其他版本时，应让 Agent 以项目中安装的 .d.ts、README 和 API 文档 为准。不要把 JWT、应用 Token 或生产环境地址写入 Skill、示例或日志。

相关 API 入口：

IM SDK代码示例 ↗