@sugarforever/dsh-lark
用于 DeepSeek Harness 的 Feishu/Lark WebSocket 通道插件
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:sugarforever/dsh-lark#155df87e283bfdc90a79fb4ad5debc417cbe9082Lark 以 @sugarforever/dsh-lark 发布，当前版本为 0.2.6。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
@sugarforever/dsh-lark 是一个 DeepSeek Harness Host 插件。安装后，用户可以直接从飞书或 Lark 与 Harness Agent 对话，并继续使用 Harness 中配置的模型、工具、系统提示和会话存储。
插件使用飞书官方 @larksuiteoapi/node-sdk 的 Channel API，通过 WebSocket 长连接接收消息，不需要公网服务器、域名或 Webhook 回调地址。官方 SDK 负责连接、自动重连、消息去重、过期事件过滤、同一聊天的串行处理、消息格式转换和发送回复；插件负责把飞书会话映射到 Harness Session，再把消息交给 Agent。
^22.19.0 或 >=24.0.0。npx 运行 DeepSeek Harness 0.1.0-rc.6 或更高的 0.1.x 版本。im.message.receive_v1。如果尚未运行过 Harness，可以先启动一次 Web Profile：
npx @deepseek-ai/dsh web
首次启动会创建 web Profile。默认目录是 ~/.dsh/profiles/web；如果设置了 DSH_HOME，则位于 $DSH_HOME/profiles/web。
以下名称在飞书中国版和国际版 Lark 控制台中可能略有区别，但配置内容相同。
不要把 App Secret 直接写进仓库中的 YAML 文件。后续通过 Harness Settings 页面保存，或者通过启动环境变量传给插件。
默认配置下，应用需要开通以下三个权限：
| 权限标识 | 控制台中的权限名称 | 用途 | 是否必需 |
|---|---|---|---|
im:message.p2p_msg:readonly | 获取用户发给机器人的单聊消息 | 接收用户与机器人的单聊消息 | 是 |
im:message.group_at_msg:readonly | 获取群组中 @机器人的消息 | 接收群聊中明确 @机器人的消息 | 是 |
im:message:send_as_bot | 以应用的身份发消息 | 让机器人回复单聊、群聊和话题消息 | 是 |
飞书控制台中显示的中文名称可能随平台版本略有调整，应以权限标识为准。添加 im.message.receive_v1 事件时，控制台通常也会提示补充前两个接收权限。
如果开发者后台支持批量导入权限，可以直接复制下面的配置：
{
"scopes": {
"tenant": [
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message:send_as_bot"
],
"user": []
}
}
这组配置对应插件的默认行为：接收单聊消息、接收群聊中 @机器人的消息，以及以机器人身份发送回复。导入后仍需在事件订阅中添加 im.message.receive_v1，并发布新版本，权限和事件配置才会应用到已安装的机器人。
如果需要让机器人处理群聊中没有 @机器人的普通消息，还要额外开通：
| 权限标识 | 控制台中的权限名称 | 用途 | 是否必需 |
|---|---|---|---|
im:message.group_msg | 获取群组中所有消息 | 配合 requireMention: false 接收群内全部消息 | 仅关闭 @限制时需要 |
im:message.group_msg 的权限范围更大，通常需要企业管理员审批。默认的 requireMention: true 不需要申请这个权限。
有些企业会直接批准范围更大的 im:message 权限，它也可以覆盖消息读取和发送场景，但本插件不要求使用这个宽泛权限。优先申请上表中的最小权限即可。
权限变更可能需要企业管理员审批。测试时如果机器人能够加入聊天，但收不到消息或不能回复，先检查权限是否仍处于待审批状态。
im.message.receive_v1。长连接模式由插件主动连接飞书，因此本地电脑、内网服务器和没有公网入口的开发环境都可以运行。
只修改后台配置但没有发布新版本时，事件和权限通常不会在正式应用中生效。
从 npm 安装到 Harness Web Profile：
npx @deepseek-ai/dsh plugin --profile web add @sugarforever/dsh-lark
Harness 的 Agent、Session、Settings 等服务由 Profile Bundle 在运行时提供。
插件将这些包声明为 optional peer，以适配 DSH 的 Bundle 加载机制；它不会在
Profile 中重复安装另一套 Harness。从 0.2.3 起兼容 0.1.0-rc.7、
0.1.2-rc.1 及稳定的 0.1.x 版本，并通过 CI 持续验证最新发布的 Harness
版本，因此升级到后续 RC 通常不需要重新发布插件。
查看已经安装的插件：
npx @deepseek-ai/dsh plugin --profile web list
开发本项目时，也可以安装本地目录：
git clone https://github.com/sugarforever/dsh-lark.git
cd dsh-lark
npm install
npm test
npm run typecheck
npm run build
npx @deepseek-ai/dsh plugin --profile web add "$PWD"
插件安装后保持启用，但在 App ID 和 App Secret 尚未配置时不会建立飞书连接。这样安装完成后就能直接配置，而不必编辑 profile patch。
启动 Web Profile：
npx @deepseek-ai/dsh web
打开 Harness 的 Settings，选择 飞书与 Lark。这里可以配置 App ID、App Secret、飞书或 Lark 域名、访问策略和 Agent 参数。Provider 和 Model 来自 Harness 当前的模型目录，选择 Provider 后，Model 下拉框只显示该 Provider 的模型；留空时跟随 Harness 默认配置。
点击保存后，普通参数写入 $DSH_HOME/settings.yaml 的 lark-channel section；App Secret 通过 Harness Credentials 保存到 $DSH_HOME/.credentials.yaml，不会写入普通 Settings，也不会从 Host 回显到浏览器。
Secret 输入框为空不代表凭据丢失。页面会明确显示“Secret 已配置”或“Secret 未配置”：
appSecret，页面会显示只读状态，不能通过 UI 覆盖或删除该来源。配置或凭据变化后，插件会关闭旧 WebSocket 和会话资源，再创建新的 channel，不需要重启 Harness。
对于 CI、容器或服务部署，也可以继续使用环境变量。默认 CredentialRef 是 DSH_LARK_APP_SECRET，启动环境的同名变量优先于 Credentials 文件：
export DSH_LARK_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
npx @deepseek-ai/dsh web
环境变量来源只读，并且在 Harness 启动时冻结。修改它仍然需要重启进程。App ID 等普通参数可以在 profile patch 中作为 composition base 提供，也可以在配置页面中覆盖：
- id: lark-channel
config:
appId: cli_xxxxxxxxxxxxxxxx
appSecretRef: DSH_LARK_APP_SECRET
domain: feishu
不要再次使用 insert 创建同名实例，否则会出现 duplicate loader entry id: lark-channel。
Profile patch 是基础配置，Settings 页面保存的普通参数是覆盖层。已经通过 UI 保存的 appId、domain 等值优先于 patch；删除对应的 Settings 覆盖后，才会重新使用 patch 中的值。appSecretRef 默认保持为 DSH_LARK_APP_SECRET，UI 保存的 Secret 会写到这个引用名对应的 Harness Credential 中。
旧版本使用的明文 appSecret 仍可作为只读兼容来源，但不建议继续保留。迁移时先在 UI 中保存 Secret 或设置 DSH_LARK_APP_SECRET，确认连接成功后，再从 patch 中删除 appSecret。
连接成功后，终端会出现：
dsh-lark: WebSocket connected
运行期间如果网络中断，官方 SDK 会尝试重新连接，并输出 WebSocket reconnecting 和 WebSocket reconnected。
同一个单聊中的后续消息会继续使用同一个 Harness Session，因此能够保留前文。 Harness 重启后，插件会恢复对应的持久化 Session；如果该 Session 已经在当前进程中运行，则直接复用现有 Agent，不会重复创建或恢复。
@机器人 加上问题。默认配置下，没有 @机器人的群消息会被忽略。如果关闭 requireMention，还需要确保应用获得接收群内全部消息的权限，并经过企业管理员批准。
话题中的消息会使用 chat_id + thread_id 建立独立 Session。不同话题不会共享对话记录，机器人回复会留在原来的话题中。
下面的例子包含目前支持的所有配置项：
- id: lark-channel
disabled: false
config:
appId: cli_xxxxxxxxxxxxxxxx
appSecretRef: DSH_LARK_APP_SECRET
domain: feishu
requireMention: true
dmMode: open
groupAllowlist:
- oc_xxxxxxxxxxxxxxxx
dmAllowlist:
- ou_xxxxxxxxxxxxxxxx
provider: deepseek-official
model: deepseek-v4-flash
workspace: /absolute/path/to/workspace
agentPreset: coding
errorMessage: 抱歉，处理这条消息时遇到了问题，请稍后重试。
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
appId | 连接时是 | 空字符串 | 飞书或 Lark 应用的 App ID |
appSecretRef | 否 | DSH_LARK_APP_SECRET | Harness Credentials 中保存 App Secret 的引用名 |
domain | 否 | feishu | 中国版使用 feishu，国际版使用 lark |
requireMention | 否 | true | 群聊是否必须 @机器人 |
dmMode | 否 | open | 单聊策略：open、allowlist 或 disabled |
groupAllowlist | 否 | [] | 允许使用机器人的群 chat_id 列表；空数组表示不限制 |
dmAllowlist | 否 | [] | dmMode: allowlist 时允许访问的用户 open_id 列表 |
provider | 否 | Harness 默认值 | 为这个渠道指定模型 Provider |
model | 否 | Harness 默认值 | 为这个渠道指定模型 |
workspace | 否 | 第一个已注册 Workspace；没有时为 DSH 进程工作目录 | Agent 使用的工作目录；显式路径优先 |
agentPreset | 否 | Harness 当前默认 Preset | Agent 使用的 Preset，决定工具、系统提示等组合 |
errorMessage | 否 | 内置中文提示 | Agent 执行失败时返回给用户的文本，最长 500 个字符 |
provider 和 model 建议同时设置。如果都不设置，插件会读取 Harness 当前的默认模型配置。
飞书会话创建 Agent 时会沿用 Harness Web 客户端的两项关键行为：挂载 Agent Preset，并把 Session 关联到 Workspace。Preset 提供该会话的工具、系统提示和其他 Agent 级能力；Workspace 提供 cwd，并让会话出现在对应工作区中。
workspace：使用 Harness Workspace 列表中的第一个工作区。workspace：始终使用该路径；如果它已经注册为 Workspace，Session 同时关联到该 Workspace。agentPreset：解析 Harness 当前默认 Preset。agentPreset：使用指定 Preset；名称不存在时，本次会话创建会失败并向飞书返回安全错误提示。如果希望机器人始终操作固定项目，建议显式配置：
workspace: /Users/you/github/project
agentPreset: coding
升级到包含 Workspace/Preset 关联的版本后，同一飞书聊天会创建新的 v2 Session；旧版本产生的未关联 Session 不会被继续复用。
只允许指定群聊使用机器人：
requireMention: true
groupAllowlist:
- oc_group_one
- oc_group_two
只允许指定用户发起单聊：
dmMode: allowlist
dmAllowlist:
- ou_user_one
- ou_user_two
完全关闭单聊：
dmMode: disabled
群聊白名单使用 chat_id，单聊白名单使用发送者的 open_id。这些标识可以通过飞书 API、事件调试信息或管理员工具取得。生产环境不要开启原始事件日志后长期保留消息内容。
$DSH_HOME/.credentials.yaml 是权限为 0600 的明文 YAML，不是加密保险库；同一 OS 用户运行的进程仍可读取。errorMessage 中配置的失败提示。chat_id 或 thread_id。检查 App ID 和 App Secret 是否来自同一个应用，环境变量是否在启动 DSH 的进程中可见。如果凭据曾经泄露，应先在开发者后台轮换 App Secret。
依次检查：
im.message.receive_v1。groupAllowlist 是否排除了当前群聊。检查应用是否拥有发送消息权限，并查看终端中的飞书 API 错误。回复目标被撤回时，官方 SDK 会尝试降级为普通消息；其他权限错误仍需要在应用后台处理。
检查 dmMode。当它是 allowlist 时，发送者的 open_id 必须出现在 dmAllowlist 中；当它是 disabled 时，所有单聊都会被忽略。
把 requireMention 改成 false，并为应用申请接收群内全部消息的权限。这个权限通常需要管理员审批，开启前应同步评估群消息的隐私范围和模型调用成本。
检查运行环境能否访问飞书的 HTTPS 和 WebSocket 服务，并检查企业代理、防火墙、TLS 中间人或网络出口限制。不要为同一个应用启动多个插件实例。
在 Harness Settings → 飞书与 Lark 保存后查看其中的 Runtime 状态。Settings 和 Credentials 文件支持热更新，插件会重建 WebSocket。只有修改启动环境变量时才需要重启 Harness。
升级插件：
npx @deepseek-ai/dsh plugin --profile web update
update 会保留 Profile 的 cordis.patch.yml、Harness Settings 和 Credentials，因此已有的 App ID、访问策略、Workspace、模型选择和 App Secret 不需要重新填写。升级后重启 dsh web，新的 Host 和 Client bundle 才会一起加载。
@sugarforever/dsh-zvec-grep 是独立插件；需要 Workspace 语义搜索时请单独安装。Lark 插件不会安装或装配它，因此两个插件可以在同一个 Profile 中各自升级。
卸载插件：
npx @deepseek-ai/dsh plugin --profile web remove @sugarforever/dsh-lark
卸载后再检查 Web Profile 的 cordis.patch.yml，确认没有残留的手工配置实例。环境变量可以随后从服务配置或启动脚本中移除。
npm install
npm test
npm run typecheck
npm run build
npm pack --dry-run
在仓库中完成构建后执行：
npm install
npm run build
npx @deepseek-ai/dsh plugin --profile web add "$PWD"
这会把 Web Profile 中的 @sugarforever/dsh-lark 依赖改为当前本地目录。它只覆盖该 Profile 使用的插件包，不会改写 npm registry 中的生产版本。由于服务端和 Web 客户端 bundle 都在 Harness 启动时加载，安装本地构建后需要重新启动 dsh web；之后在 Settings 中修改 Lark 参数仍然可以热生效。
恢复 npm 上的生产版本：
npx @deepseek-ai/dsh plugin --profile web remove @sugarforever/dsh-lark
npx @deepseek-ai/dsh plugin --profile web add @sugarforever/dsh-lark
仓库中的 .github/workflows/publish.yml 由已发布的 GitHub Release 触发。工作流会依次完成以下操作：
package.json 版本一致。npm ci 安装锁定版本的依赖。工作流不使用 NPM_TOKEN。如果 npm 中已经存在完全相同的版本，工作流会跳过不可重复的 npm 发布，但仍会生成并上传 GitHub artifact 和 Release 附件。
如果 @sugarforever/dsh-lark 尚未在 npm 中创建，需要先从本地发布第一个版本：
npm login
npm ci
npm test
npm run typecheck
npm run build
npm pack --dry-run
npm publish --access public
首个版本发布后，在 npmjs.com 打开 @sugarforever/dsh-lark 的 Settings → Trusted Publisher，选择 GitHub Actions，并填写：
sugarforeverdsh-larkpublish.ymlnpm publish除非 GitHub 工作流也配置了完全相同的 Environment，否则 Trusted Publisher 中不要填写 Environment name。
根据改动范围选择 SemVer 版本类型：
npm version patch
# 或 npm version minor
# 或 npm version major
npm version 会同时更新 package.json 和 package-lock.json，创建版本提交并生成匹配的 tag。例如版本 0.1.1 对应 v0.1.1。
把提交和 tag 推送到 GitHub：
git push origin main --follow-tags
然后在 GitHub 中为该 tag 创建并发布 Release。发布 Release 后，GitHub Actions 会自动执行 npm 发布流程。如果 tag 去掉 v 后与 package.json 中的版本不同，工作流会在发布前失败。
创建 Release 前，可以在本地运行同样的检查：
npm ci
npm test
npm run typecheck
npm run build
npm pack --dry-run
架构和生命周期说明见 docs/architecture.md。