dsh-feishu-control

English | 中文

通过飞书安全地远程控制运行在自己机器上的 DeepSeek Harness 编码 Agent。机器人使用飞书长连接主动出站连接，不需要公网 IP、端口转发或回调域名。

本包是可安装的 DSH profile bundle，包含飞书能力接口、长连接 provider、Agent consumer 和交互式审批桥。

安全默认值

• 发送者白名单为空时拒绝所有人。
• 群聊默认关闭；启用后默认要求消息包含提及。
• 飞书重投的近期消息不会重复驱动 Agent。
• 较长的 Agent 回复会按顺序拆成不破坏 Unicode 字符的多条消息。
• 卡片审批只接受白名单操作者及原会话中的点击。
• 文本审批使用应答码区分并发请求。
• 未回答、超时或撤回的审批失败关闭。
• 缺少飞书凭证时启动直接失败，不会静默运行。

这个插件能让远程消息触发本机编码 Agent。Agent 可能执行命令、读写文件并消耗 API 额度。只应把白名单授予可信用户，并让 Agent 在权限受限的账户和工作目录中运行。

前置条件

• Node.js ^22.19.0 或 >=24.0.0。
• 已经安装 DeepSeek Harness 的 dsh CLI，完成 DeepSeek 模型/API 配置，并至少成功启动过一次。
• 一个飞书企业自建应用。
• DeepSeek API key。

本插件不是 DeepSeek Harness 本体，也不会替你安装或配置 Harness。请先在终端确认 dsh --version 有结果，并确认 dsh 本身可以正常启动，再继续安装插件。

小白推荐：插件广场安装 + 终端向导

不需要下载源码，也不需要编辑 YAML。先在 DeepSeek Harness Desktop 的插件广场安装，或在其内置终端运行标准安装命令：

dsh plugin add --save-exact dsh-feishu-control@latest

然后在普通终端运行配置向导：

pnpm dlx dsh-feishu-control@latest setup

向导会逐步完成：

1. 检查 dsh 和 pnpm 是否存在，并再次确认 Harness 已经成功运行过。
2. 提醒你完成飞书机器人、长连接、事件、权限和应用发布设置。
3. 安全输入 App ID 和 App Secret；Secret 输入时不会显示。
4. 配置允许控制 Agent 的飞书用户 open_id。
5. 选择 Agent 只能操作的项目工作目录。
6. 自动寻找插件实际安装的 Profile，不会在插件广场安装后重复安装。
7. 写入本机配置并检查对应 Profile；最后提示重启 Desktop。

如果尚未通过插件广场安装，向导会明确说明并切换到独立终端模式，使用精确版本创建 feishu-control Profile。

向导将飞书凭证保存到 $DSH_HOME/.env（默认是 ~/.dsh/.env），并把文件权限设为仅当前系统用户可读写。这个文件不会位于项目仓库中，但同一系统账户下运行的程序和 Agent 工具仍可能读取它；建议使用专用低权限账户。

Harness 0.1.0-rc.8 及以上版本禁止在 .env 中使用 DSH_* 名称，因此 0.1.1 改用 FEISHU_CONTROL_*。再次运行 setup 会自动迁移旧的 DSH_FEISHU_* 配置，并且不会打印已保存的密钥；旧名称仅在启动终端显式 export 时继续兼容。

如果不知道自己的 open_id，按以下步骤完成首次授权：

1. 首次运行向导时输入 ou_placeholder，完成其余配置并启动服务。
2. 私聊飞书机器人，复制回复中显示的真实 open_id。
3. 终端模式按 Ctrl+C 停止服务；Desktop 模式完全退出 Desktop。
4. 再次运行 pnpm dlx dsh-feishu-control@latest setup。
5. 当向导显示已有的 [ou_placeholder] 时，粘贴真实 open_id 覆盖它并完成配置。
6. 重新启动终端服务，或重新打开 Desktop。此后白名单内的消息才会交给 Agent。

安装后常用命令：

# 检查是否安装和配置完整（不会显示密钥）
pnpm dlx dsh-feishu-control@latest doctor

# 仅限独立终端模式：在向导保存的工作目录中启动
pnpm dlx dsh-feishu-control@latest start

Desktop 用户不要另外运行 start；请完全退出并重新打开 DeepSeek Harness Desktop。

pnpm dlx 会临时取得 npm 上发布的安装向导并执行 feishu-control 命令，所以用户无需克隆仓库。只有项目维护者从源码开发时才需要使用 pnpm run feishu-control。

手动安装

以下步骤适合希望自己管理环境变量和 DSH profile 的开发者；第一次使用建议采用上面的终端向导。

1. 创建飞书应用

1. 进入飞书开放平台并创建企业自建应用。
2. 添加“机器人”能力。
3. 在“事件与回调”中选择“使用长连接接收事件”。
4. 订阅 im.message.receive_v1 和 card.action.trigger。
5. 开通 im:message、im:message:send_as_bot 和 im:message.p2p_msg 权限。
6. 仅在需要群聊功能时开通 im:message.group_at_msg。
7. 创建版本并发布应用。

2. 配置凭证和白名单

在启动 dsh 的环境中设置：

export DEEPSEEK_API_KEY=replace-with-your-deepseek-key
export FEISHU_CONTROL_APP_ID=replace-with-your-app-id
export FEISHU_CONTROL_APP_SECRET=replace-with-your-app-secret
export FEISHU_CONTROL_ALLOWED_OPEN_IDS=replace-with-your-open-id
export FEISHU_CONTROL_WORKSPACE=/absolute/path/to/a/project
export FEISHU_CONTROL_PERMISSION_MODE=workspace-write

多个 open_id 用英文逗号分隔。白名单为空或缺失时，机器人会拒绝所有消息。

如果不知道自己的 open_id，可先配置一个不存在的值，例如 ou_placeholder，启动后私聊机器人。回复会显示发送者自己的 open_id；复制它，停止服务，再次运行 setup 替换占位值并重启。多个 open_id 仍使用英文逗号分隔。

不要提交 .env 或真实凭证。本仓库的 .env.example 只包含占位值。

3. 安装并启动

DeepSeek Harness Desktop 插件广场

dsh plugin add --save-exact dsh-feishu-control@latest
pnpm dlx dsh-feishu-control@latest setup

安装及配置完成后，完全退出并重新打开 DeepSeek Harness Desktop。插件广场命令使用当前 Desktop Profile，因此不需要手工指定 --profile。

独立终端 Profile

dsh plugin --profile feishu-control add --save-exact dsh-feishu-control@latest
dsh --profile feishu-control --dump-config
cd /path/to/the/workspace-the-agent-may-control
dsh --profile feishu-control

这里的 feishu-control 是 DSH profile 名称。npm 包同时提供同名的安装向导命令；向导最终仍然通过 dsh --profile feishu-control 启动 DeepSeek Harness。

插件优先使用 FEISHU_CONTROL_WORKSPACE 作为 Agent 工作目录和 Harness 沙箱根目录；未设置时才使用启动 dsh 时所在的目录。请选择专用项目目录，保持 FEISHU_CONTROL_PERMISSION_MODE=workspace-write，不要使用用户主目录或文件系统根目录。

从 GitHub 安装

dsh plugin --profile feishu-control add --save-exact github:SkyCui/dsh-feishu-control#<commit-sha>

Git 安装会执行本包的 prepare 构建脚本。pnpm 10 及以上默认阻止依赖安装脚本；第一次安装若被拒绝，请按照 dsh/pnpm 输出，把精确的包键加入该 profile 的 pnpm-workspace.yaml 中的 allowBuilds，然后使用固定 commit SHA 重试。只应授权可信源码。

npm 和插件市场安装使用预构建产物，不需要授权本包的构建脚本。

模型路由

机器人创建的 Agent 会话默认使用当前 Profile 的默认模型选择（dsh-base 提供的 agent-default-model 组合条目；Desktop GUI 与一次性命令 dsh -p "task" 也会读取 这份共享选择），并沿用其中的推理强度（reasoning effort），因此无需额外配置模型。 每次开始新一轮对话时，未固定的字段都会读取当时的共享默认值；已经在执行的一轮会 继续使用组装提示词时取得的同一份选择。

若想为飞书会话固定不同的模型，任选其一：

• 环境变量（无需编辑 YAML）：在 $DSH_HOME/.env 设置 FEISHU_CONTROL_PROVIDER 和/或 FEISHU_CONTROL_MODEL 后重启服务。每个变量只 固定自己的字段；只要还有路由字段未设置，该字段与推理强度就继续跟随 Profile 的 共享默认选择。两项都设置则选择完全固定路由。
• Profile 配置：在插件所在 Profile 的 cordis.patch.yml 中覆盖完整的 feishu-agent 配置并加上 provider 和/或 model 字段；显式配置按字段优先于 默认选择。

注意：cordis.patch.yml 的补丁会替换目标行的整个 config，因此覆盖时必须写全 其余字段（cwd、allowedOpenIds、allowGroupChats、requireMentionInGroups）。

群聊

群聊默认关闭。若确实需要群聊，在插件实际所在 Profile 的 cordis.patch.yml 中覆盖完整的 feishu-agent 配置，例如 $DSH_HOME/profiles/feishu-control/cordis.patch.yml：

- id: feishu-agent
  config:
    cwd: !!js process.env.FEISHU_CONTROL_WORKSPACE ?? process.cwd()
    allowedOpenIds: !!js "process.env.FEISHU_CONTROL_ALLOWED_OPEN_IDS?.split(',').map(value => value.trim()).filter(Boolean) ?? []"
    allowGroupChats: true
    requireMentionInGroups: true

当前提及检测只确认消息存在提及，不能确认被提及的一定是机器人。对安全要求较高的部署应保持群聊关闭。

审批行为

需要用户批准的操作会发送交互式卡片。卡片发送失败时，机器人改发带六位应答码的文本：

允许 a1b2c3
拒绝 a1b2c3

同一聊天只有一个文本审批时，也可以直接回复“允许”或“拒绝”。存在多个审批时，必须携带对应应答码。

开发与验证

本仓库独立解析 npm 上发布的 DSH API 包，不需要相邻的 deepseek-harness checkout。

pnpm install
pnpm verify
pnpm pack

pnpm verify 依次执行类型检查、单元测试、构建和发布入口验证。prepack 会在打包或发布前自动执行完整验证。

pnpm check:package-types 还会使用 Are The Types Wrong 检查打包后的 ESM 类型声明。

已知限制

• 会话和消息去重记录仅保存在内存中，进程重启后会清空。
• 消息去重最多保留最近 2,000 个消息 ID。
• 群聊提及检测无法确认具体被提及的用户。
• 只支持文本消息和审批卡片，不支持媒体与附件。

安全报告

请参阅 SECURITY.md。

许可证

MIT