dsh-lark-bot

dsh-lark-bot

🌏 英文版：[README_EN.md](README_EN.md)

把 DeepSeek Harness 接入飞书

🌐 官网落地页 dsh-lark-bot.arr2018.dpdns.org · 备用 GitHub Pages

⚠️ 仅认准官方渠道： 唯一官方仓库 PlutoKeating/dsh-lark-bot，唯一官方 npm 包 dsh-lark-bot（同源双包 dsh-feishu-bot，维护者 plutokeating）。本项目从不提供 Windows 可执行文件（.exe），也没有任何“下载即运行”的安装包——任何以本项目名义提供 exe / “下载后双击运行”的页面、仓库或第三方分发渠道均为假冒 / 恶意来源，请勿下载或运行。官方安装唯一命令：npx dsh-lark-bot@latest setup --profile dsh-lark。仿冒仓库取证与完整声明见文末「假冒仓库警告」及 docs/security/2026-08-17-impostor-repo-evidence/。

场景

你的 DeepSeek Harness 只能“贴身”用？ dsh 跑在本机，每次看进度、改任务都得回到电脑前；离开工位后任务卡住、跑偏甚至 dsh 崩了，你都收不到任何消息——回来才发现白等半天。

dsh-lark-bot 把遥控器装进你的飞书：在私聊、群聊、话题里直接指挥本机 dsh coding agent，流式卡片的飞书原生折叠面板实时展示思考与工具调用，最终回答单独成消息；任务完成还能主动推送到你所在的任何群并 @ 你；即使 dsh 崩溃下线，飞书里依然叫得应——发 /safemode 进入仅核心安全模式，直接在聊天里定位问题、重启引擎。这是唯一“dsh 挂了你不会失联”的桥接方案。

适合谁：在飞书 / Lark（私聊、群聊、话题）里指挥本机 dsh coding agent 的开发者与团队，尤其是需要多项目隔离、角色分工、并行任务与会话归档的协作场景。

能做什么

基础能力：

• 私聊、群聊、话题（thread）里指挥本机 dsh coding agent，图片 / 文本文件直接发给 bot 即可；
• 流式过程卡以飞书原生折叠面板实时展示思考、工具调用与结果，完成后最终回答单独发送，支持交互按钮（停止 / 计划门禁 / 审批 / 问答卡）；
• Git 仓库内为每个会话自动创建隔离 worktree 项目工作区，多项目互不干扰。

十一项全网独有组合：

• 🆘 Guardian 安全网守护——“永远叫得应”：DSH 崩溃后飞书仍会回复你，/safemode 进入仅核心安全模式直接重启。
• 👥 多角色 Agent——“一个机器人，一整个团队”：/role 切换或指派 PM / 开发 / 文档等角色，每个角色独立人设、模型偏好与规则。
• 🤝 多机器人交接——“一个群，多个独立 Agent”：bot add 增加独立身份/服务/凭据/上下文的实例，可信机器人可在同群通过真实 @ 交接，连续协作有硬上限。
• ⚡ 并行多任务——“不用排队”：同一群聊同时跑多个任务、会话隔离；其他方案只能串行排队。
• 🧾 崩溃后可对账——“发出去了不是石沉大海”：消息先写持久任务账本再入队；重启恢复排队项，中断任务保留 checkpoint 并由 /jobs 显式重试。
• 🗂 会话归档与清理——“会话列表不会烂掉”：/archive 归档旧任务、/retention 配置自动保留策略。
• 📣 跨会话主动通知 + @人——“活干完了它会来找你”：A 群跑完任务主动推送到 B 群 / 私聊并 @ 你。
• ⚙️ dsh Web 可视化设置——“不用背环境变量”：在官方 Settings → Plugins 页面点选应用、工作目录、模型、并行数与提醒，并可直达诊断。
• 🔑 对话内管理模型和密钥——“不用离开飞书”：/providers /provider /key 直接查看、切换供应商、热更新密钥。
• 🎚️ 快速 / 平衡 / 深度模式——“任务强度一键选”：/mode 按 scope 持久选择，下一轮生效且不打断当前任务。
• 🧭 关键任务先拍板——“计划看清再动手”：完整计划先单独发出，再用卡片批准执行或附意见继续规划，原任务自动续跑。

30 秒上手

前置条件（先装好本体，再装遥控器）：

1. DeepSeek Harness（dsh）已安装并配置好 DEEPSEEK_API_KEY —— dsh-lark-bot 是 dsh 的插件，dsh 才是 agent 本体，缺一不可；
2. Node.js ≥ 22.19（见 package.json engines）与一个飞书 / Lark 账号。

三步上线：

# ① 一键安装（无需先全局安装任何东西；自动装进 dsh profile，并默认同时安装「安全网守护」）
npx dsh-lark-bot@latest setup --profile dsh-lark

# ② 启动
dsh --profile dsh-lark

③ 首次启动终端打印二维码 → 飞书 / Lark App 扫码创建或选择 PersonalAgent 应用 → 绑定后私聊直接发消息；群聊 / 话题默认 @bot，也可显式开启受白名单保护的无 @ 模式。

setup 自动完成：定位本机 dsh → 预批准 pnpm 构建策略 → 标准 dsh plugin add → 默认安装「安全网守护」系统服务，一条命令完成全部安装。

无需公网 IP / 域名 / 服务器 / 内网穿透（飞书 WebSocket 出站长连接），Linux / macOS / Windows 通用。 已有 PersonalAgent 应用时可跳过扫码（见「配置」）：DSH_LARK_APP_ID=cli_xxx DSH_LARK_APP_SECRET=<secret> DSH_LARK_TENANT=feishu dsh --profile dsh-lark 升级同样一条命令：npx dsh-lark-bot@latest upgrade --profile dsh-lark --yes

完整使用方式

常用命令

在飞书里向 bot 发送普通消息即可开始工作，常用命令：

bot 自带的命令帮助、状态、错误提示与交互卡片均提供中文 / English。Card JSON 2.0 在各文本组件使用飞书原生 i18n_content，同一张群卡会按每位读者的客户端语言显示；无法取得读者语言的普通 Markdown、toast 与旧客户端降级路径同时显示中英文。agent 生成的回答、推理、工具输入输出和用户原文 保持原样，不自动翻译。

飞书消息中的图片会下载到本地 media 目录并传给 dsh；文本类文件会读取内容并注入任务上下文。

DSH session 消息级同步（web adapter）：发送 /session 只会列出当前 canonical workspace 的非 subagent session 元数据，不显示正文；选择后确认卡会列明标题、ID、workspace、更新时间、 回填数量、当前 scope，以及是否替换/独占迁移。只有确认后才发送有数量和字节双重上限的历史 transcript 卡并持久绑定。私聊允许已授权用户；member scope 仅本人；共享 group/topic 仅 profile 管理员；跨 scope 独占迁移也仅 profile 管理员。WebUI 或 dsh-TUI 的 open/resume/activity 永远不会 自动切换飞书绑定，也不会广播给所有 scope。绑定后，DSH session/event 是唯一真源：外部用户消息 镜像为带来源的 bot 消息，assistant chunk 节流更新同一张 bot-owned 卡，最终消息原位终态化；更新 失败才追加增量。bridge 以持久 seq cursor 重连补齐，并用 message ID / event seq / prompt rpcId 抑制飞书回显；tool/thinking 默认不投影。状态位于 profile 的 session-projections.json（0600），包含 路由、待确认历史水位/cursor、当前 turn 来源和消息映射；仅为跨重启续写流式卡保存其未终态正文， 不复制完整 transcript。历史确认完成前 live 事件保持串行等待，发送失败会在启动/重连时重试。 新投影卡使用稳定的飞书 uuid 幂等创建，覆盖发送成功但 cursor 尚未落盘时的崩溃重放。

/newg <群名>：自动新建私密群、拉发送者入群并回复群链接——新群即新 scope / 新会话，当前会话不受影响。需应用具备 im:chat 与 im:chat.members:write_only 权限。

同一 scope（私聊 / 群聊 / 话题）默认 2 个任务并行（DSH_LARK_SCOPE_CONCURRENCY 或 /concurrency 调整）：多条消息以独立 run 并行推进，每个 run 使用独立 dsh session 与 runId；/status 查看当前 workspace 的 run，/new 只停止当前 workspace，/stop 一次性终止 scope 内全部运行。

会话状态卡：/status 展示工作区、有效模型、session、显式投影绑定/cursor、active runs、版本、上下文占用、 累计 input / output / cache token，以及待审批 / 待提问 / 待批准计划；点击“刷新”会原位更新同一张卡。 只展示 adapter 或模型目录明确提供的数据：ACP 可提供真实 context used / size 与累计 token， SDK 可提供每次模型调用的 token/cache 用量；上游未提供的字段显示“暂无”，不按文本长度估算。 累计用量随 scope 持久化；最近的 context 快照按 canonical provider/model 与 native session 分别保留， 并行 run 不会互相覆盖，当前身份不匹配时也不会复用旧占用值。会话与指标按 scope + workspace 持久化；/cd / /ws use 会中断原工作区仍在运行的任务，但不会删除其会话、指标或归档，切回即可 继续；只有 /new / /reset 清空当前 workspace。待处理卡与归档列表/清理也只统计当前 workspace。 成员 scope 的刷新只允许 owner 操作。

消息与任务可靠性：普通 agent 消息以飞书 messageId 去重，先原子写入 profile 的 jobs.json（0600）再进入内存队列。进程重启后，尚未开始的 queued 消息自动回到原 scope、thread 与 workspace；崩溃时已 running 的任务会转为 interrupted，保留最后安全阶段、run/native session 标识，但不会自动重复可能已有外部副作用的操作。用 /jobs 对账、/jobs show <消息ID> 查看，确认后 再 /jobs retry <消息ID>。/status 和重连提示会显示当前 workspace 的账本统计。保证范围从 bridge 已经收到并成功落盘开始；断网期间飞书从未投递给 bridge 的事件无法由本地账本恢复。 若首次落盘失败，bot 会明确回复“未接收/未执行，请重发”；若执行前 running receipt 失败，任务不会 启动，并明确落为 failed 或保留 queued 等待重启恢复。终态落盘失败也会提示对账；残留 running 会在 出站通道就绪后安全标为 interrupted，中断通知失败会跨启动继续投递。

群聊会话隔离：管理员可用 /isolation group|topic|member 在“整群共享 / 话题独立 / 成员独立”之间切换；默认 topic 保持既有行为。切换只改变后续消息的 scope 路由，不迁移或 删除已有会话，切回即可继续；切换前已发出的停止 / 审批 / 问答卡仍绑定原 scope，/stop 也会 覆盖当前成员可达的切换前 scope。成员模式的任务卡会显示发送者 open_id，避免误把别人的上下文 当成当前对话。策略持久化在 ~/.dsh-lark/profiles/<profile>/isolation.json。

多角色 Agent：管理员用 /role save <id> <name> --persona <文案> [--model <id>] [--tools <csv>] [--rules <文案>] 定义 PM / 开发 / 文档等角色，/role set <id> 绑定到当前 scope；每个 run 携带角色 persona 与规则，角色模型低于每会话 /model use。角色定义持久化在 ~/.dsh-lark/profiles/<profile>/roles.json。

多机器人实例与 @ 交接：

dsh-lark-bot bot add reviewer --model gateway/review-model # 无凭据参数时扫码创建独立 PersonalAgent
dsh-lark-bot bot list
dsh-lark-bot bot status reviewer
dsh-lark-bot bot remove reviewer                       # 保留会话/工作树数据

每个实例使用独立的 bridge profile、dsh-lark-<name> profile、 ~/.dsh-lark/bots/<name>/dsh DSH_HOME、OS 用户服务、飞书与 provider 凭据、模型目录、 session/scope/worktree/archive；添加/移除不会重启其他实例。可在执行 bot add 时为当前进程设置 该实例专用的 DEEPSEEK_API_KEY；自定义 provider 凭据可在实例启动后通过 /key set 写入独立凭据库。 连接后，本机共享的 fleet.json 只把已登记 bot open_id 视为可信 peer。agent 获得 peer 的精确 open_id，可用 lark_notify 在当前群真实 @ 对方并附交接摘要；未知 bot、未 @、system/anonymous 消息不进入 agent， bot 发来的 /... 也只作为任务文本。共享 handoffs.json 对 messageId 去重并在全 fleet 统计连续 交接，默认 6 轮；任一新鲜真人消息（即使未 @）立即重置。成员隔离群中的 bot 交接使用该实例的 group/topic scope，避免生成无人可操作的 bot-owned 审批卡。额外实例由自己的 service 常驻；默认 guardian 仍只救援其配置的主实例。 default 主机器人不能通过 bot remove 删除，避免附加实例管理误伤既有机器人。 附加实例仅支持各自隔离 runtime 的 sdk / acp（以及 legacy headless）；bot add 与运行时都会 拒绝 web，因为共享 Web agent 的广播事件流无法提供实例级 session 隔离。

出站 @ 提及与跨会话通知：/notify <scope|chatId> <text> 可向其他会话推送汇报（管理员）；agent 侧内置 lark_notify dsh 工具（SDK / ACP runtime 均可装配），任务完成后主动向其他群 / 话题发消息并 @ 成员。回调走 127.0.0.1 本地端口 + 随机 token，不暴露公网。

可配置主动提醒：Web 设置默认关闭、不刷屏，也可为未单独设置的会话选择“完成与失败”或“全部”。普通用户可用 /notifications on current 覆盖当前 scope，默认 @ 自己并在审批等待 10 分钟后只提醒一次；可用 events=、mentions=、remind= 调整。管理员还可把目标设为已登记的其他 scope|chatId。偏好原子持久化到 profile，重启不丢，并在 /status 显示；/notifications off 显式关闭，/notifications default 恢复 Web 默认值。

回复流量控制：默认保持即时逐条回复。profile 管理员或当前群的群主/群管理员可用 /replies set merge=5 batch=3 interval=10 dedupe=60 为当前 scope 开启 5 秒合并窗口、每条合并最多 3 个任务、两批至少间隔 10 秒，并在 60 秒内抑制同一发送者在同 workspace 的近似重复任务；超出批量上限的答案在 bridge 进程存活期间继续排队，不会因批量上限被丢弃。/replies 与 /status 显示有效策略，/replies default 恢复默认。

任务执行模式：发送 /mode 可用双语卡片选择 quick（快速：直接回答，只做必要检查）、balanced（平衡：兼顾速度与可靠性，默认）或 deep（深度：充分调查并验证假设与结果）；也可直接发送 /mode quick|balanced|deep，/effort 是等价别名。选择按隔离 scope 持久化并显示在 /status。每个 run 启动时固化模式，因此切换只影响下一轮，不会中断当前任务、清空上下文或绕过权限/计划审批。

结果文件直接回传：SDK / ACP / Web agent 可调用 lark_send_file，把当前会话 workspace、实际执行 worktree、当前 scope 归档或实例日志中的文件直接上传到原飞书聊天 / 话题；普通 /archive [note] 会在落盘后立即发送 Markdown + JSONL，失败时保留路径并可用 /archive send <id> [scope|chatId] 重试或由管理员转发到指定会话。上传只接受普通文件，默认单文件不超过 20 MiB；真实路径必须位于 bridge 计算的会话目录内，runtime 自报 cwd 不能扩大边界。

逐操作审批与 scope 权限策略：默认 SDK 与 Web 宿主在 tools/pre-execute 强制拦截高风险调用，并接入 dsh rc.8 官方 approval/request seam；ACP 走原生 session/request_permission。默认 ask 会弹出“允许执行一次 / 拒绝”卡。管理员可用 /permission allow 对当前隔离 scope 自动放行逐工具审批，或用 /permission deny 直接拒绝并向聊天给出明确反馈；/permission ask 恢复逐次询问。member 隔离下可从目标 /status 复制 scope，执行 /permission <策略> <scope>；只允许修改当前聊天内 scope。策略成功落盘后才确认，持久化到 profile 的 permission-policies.json（0600），重启不丢，且显示在 /status。该策略不绕过较大/高风险任务的计划门禁；legacy headless 不具备工具回调能力。

关键任务计划门禁：SDK / ACP / Web agent 在修改文件、运行脚本等较大或高风险动作前使用 lark_request_plan_approval；同一 turn 未获批准时，runtime pre-execute 策略会拒绝写入、删除、 移动、命令执行与 run_code。bridge 先把完整 Markdown 计划作为普通消息发出，再弹出“批准，开始执行 / 继续规划”决策卡；卡内可填写修改意见。工具在等待期间阻塞且暂停空闲超时，批准后原任务自动继续； 继续规划时 agent 会收到意见、修订计划并再次请求确认。门禁无固定十分钟截止，跟随所属 run 的取消 信号；停止任务会精确取消该 session 的 pending 卡并撤回。legacy headless adapter 不具备工具回调能力。

任务中向你提问（问答卡）：agent 需要你拍板、确认或补充信息时，通过 lark_ask_user 工具弹问答卡（单选 / 多选 / 自由文本）。可提交卡片，也可直接回复该卡片输入任意文字；单选/多选没有合适项时，回复文字就是补充答案。系统按被回复的 card messageId 精确匹配 pending 问题，回答后任务自动继续，等待期间运行超时看门狗暂停。（与 /ask 的“你主动提问”方向相反。）

计划、审批与问答卡提交后会立即显示成功提示、发送一条终态确认并撤回原卡，避免按钮仍停留在聊天中造成“未生效”的误解；确认或撤回失败不会影响已经提交给 agent 的决策、审批结果或答案。

安全网守护：独立于 dsh 进程、系统级常驻的最小守护进程（systemd / LaunchAgent / Windows 启动项），默认随 setup 安装。dsh 正常时静默；dsh 下线或无法 boot（如第三方插件破坏 profile 组合）时自动接管飞书通道，无需命令行即可自救：

• /safemode：进入仅核心安全模式（仅 dsh-base + dsh-headless 官方核心，不加载第三方插件），优先 SDK 流式引擎、失败回退 headless，直接在聊天里定位 / 修复 / 禁用损坏插件；
• /safemode plugins：列出故障 profile 的插件清单；/safemode status：查看状态；/safemode stop：终止当前安全任务（或点卡片 ⏹）；/safemode exit：重启完整 profile 并交还通道。

安全模式任务有空闲超时（DSH_LARK_GUARDIAN_SAFE_TIMEOUT_MS，默认 10 分钟，仅持续无活动事件才终止），超时 / 失败都给出明确终态。安装：

# 随 setup 默认安装；已安装后也可单独安装 / 重装：
dsh-lark-bot guardian install --dsh-profile dsh-lark

不需要时 setup --no-guardian 跳过；单独卸载用 dsh-lark-bot guardian uninstall。

正常引擎后台服务（issue #23）：安装仍只有 setup 这一条路径；如需登录后自动运行、退出终端 仍在线，可再用一条命令把同一个标准 dsh profile 交给系统用户服务托管（不会启动第二套桥接引擎）：

dsh-lark-bot service install --profile dsh-lark
dsh-lark-bot service status --profile dsh-lark
dsh-lark-bot service logs --profile dsh-lark -n 200 -f
dsh-lark-bot service restart --profile dsh-lark
dsh-lark-bot service stop --profile dsh-lark
dsh-lark-bot service start --profile dsh-lark
dsh-lark-bot service uninstall --profile dsh-lark

Linux 优先使用 systemd user unit，无 user systemd 时回退 XDG supervisor；macOS 使用 LaunchAgent， Windows 使用登录计划任务。服务异常退出会自动重启，doctor 会报告已安装服务的状态。guardian 发现正常引擎掉线时会优先重启该受管服务，避免重复拉起；upgrade --restart 也走同一路径。 stop / uninstall 会持久记录“期望停止”，guardian 不会擅自拉起；install/start 若检测到同 profile 的前台进程会拒绝并提示先停止，生命周期锁阻止并发双启动。 机器睡眠或断网期间 WebSocket 无法收消息；恢复后 SDK 自动重连，并向最近活跃会话发送恢复提示。

模型 / Provider / 凭据管理

配置以 dsh 官方方式持久化（与 dsh Web Settings → Models 同一存储协议），改动下一请求生效、无需重启：

• 交互式管理卡片：/providers（或 /provider、/model、/key）打开管理卡片；当前模型带 ✅ 标记，可直接点选其他模型或“恢复默认”，下一轮生效且保留上下文。增删改查按 BotFather 式的多轮向导完成——能选择的用按钮点选（API 协议、provider、模型、凭据引用）， 需要填值的用卡片输入（ID、Base URL、模型列表、密钥值），写入前有确认卡，随时可取消。
• /model use <provider/model>：按会话精确路由并热切换模型（也兼容唯一模型 ID，下一轮生效）；/model default <id>：写入 dsh 默认模型。
• /providers：查看 provider、模型与凭据状态；/provider add|update|remove：管理自定义 provider （需 --api / --base-url / 至少一个 --model，与官方 schema 一致）或 deepseek-official。
• /key set|remove|list：读写 ~/.dsh/.credentials.yaml（0600）；settings 只存 apiKeyEnv 引用， 字面密钥不进 settings / 聊天记录。
• 凭据引用必须关联：/key set <引用名> <值> 只写入凭据文件；provider 要生效还须在其 apiKeyEnv 字段引用同一名字（/provider add|update ... --api-key-env <引用名>，或向导中填写）。 引用名与 provider ID 相同且 provider 未设 apiKeyEnv 时，/key set 会自动补关联； 已存在的老配置在下次运行时也会自动补齐。
• 热重载：桥接在每轮运行前把模型解析为「provider + model」路由并传给 dsh runtime；SDK 适配器 在路由变化时自动重建 runtime（下一轮生效）。pi-ai 的 Base URL 填根域名（如 https://www.kingapi.xyz）会自动补全为 /v1。dsh runtime 启动后需几百毫秒才注册 pi-ai 路由，桥接会重试握手直到注册完成（避免 “no adapter registered for provider”）。

安全提醒：在飞书会话输入密钥会对可见成员暴露，建议私聊使用或 --api-key-env 引用环境变量；bot 不在任何回复中回显密钥值。

升级、禁用与卸载

升级

推荐：一行命令彻底升级（v0.12.0+ 新增，issue #10）

npx dsh-lark-bot@latest upgrade --profile dsh-lark --yes

upgrade 自动完成：检测当前已装版本 / 运行中 CLI / npm 最新版 → 升级包本体 （dsh plugin add <name>@<latest>）→ 幂等重装并重启 guardian 服务 → 升级后运行 doctor 验证。覆盖运行中实例的安全处理：

• 默认不打断运行中的 dsh profile，只提示重启命令（升级不影响配置 / 会话 / 凭据）；
• --restart：升级后自动重启 guardian 服务与（受管/后台的）dsh profile 进程；
• --check：只报告版本与运行状态，零改动；
• --rollback：回滚到上一次升级前的版本（记录在 ~/.dsh-lark/upgrade-state.json）；
• --force：无法访问 npm（离线）时按当前运行版本重装；
• --no-guardian：跳过守护升级；
• runtime profile 一致性修复：升级后自动把 dsh-lark-sdk / dsh-lark-acp 的 own-package 链接重指到新版本，并当场幂等重装版本陈旧的 SDK server / ACP 依赖。

无需交互确认时加 --yes（非交互环境不带 --yes 会安全中止）。其余方式：

• 插件本体：重跑 setup（或 dsh plugin --profile <name> add dsh-lark-bot）拉取 npm 最新版。
• 安全网守护：随 upgrade / setup 一起安装 / 升级（幂等重装），也可单独 dsh-lark-bot guardian install。
• CLI 工具（可选）：npm i -g dsh-lark-bot@latest；使用 npx 时无需全局安装。
• 升级后重启 profile（未用 --restart 时）：dsh --profile dsh-lark。

禁用

保持插件加载但停止桥接引擎：启动 profile 前导出 DSH_LARK_DISABLED=1。彻底移除见下节。

卸载

dsh plugin --profile dsh-lark remove dsh-lark-bot

卸载后 profile 不再加载本插件。本地状态（配置 / 会话 / 归档 / 角色）保留在 ~/.dsh-lark； 如需清除，先备份再删除该目录。

更详细的安装、状态目录、日志和排障说明见 docs/QUICK_START.md。

FAQ（典型用例与常见问题）

典型用例

Q: 出门在外，想用手机指挥本机的 DeepSeek Harness？

A: 可以。安装并扫码绑定后，用飞书手机 App 发消息即可指挥本机 dsh coding agent；任务完成还能跨会话主动推送并 @ 你。安装：npx dsh-lark-bot@latest setup --profile dsh-lark → dsh --profile dsh-lark → 扫码 → 开聊。

Q: 多个项目 / 多人协作，怎么隔离与分工？

A: 每个会话自动落在独立 git worktree，项目级 AGENTS.md 自动注入；管理员用 /role 定义并绑定角色、用 /invite 管理白名单；同群默认 2 个任务并行（/concurrency 调整），/archive + /retention 控制归档与保留。

Q: dsh 崩溃 / 掉线后，飞书机器人还能用吗？

A: 能。setup 默认安装独立于 dsh 的「安全网守护」：dsh 崩溃时守护自动接管飞书通道并先尝试自动重启；仍失败时发 /safemode 进入仅核心安全模式定位 / 修复问题，/safemode exit 恢复完整 profile。全程不需要命令行。

常见问题

Q: DeepSeek Harness 怎么接入飞书？

A: 安装 Node.js ≥ 22 与 DeepSeek Harness（已配置 DEEPSEEK_API_KEY），执行 npx dsh-lark-bot@latest setup --profile dsh-lark，再 dsh --profile dsh-lark 扫码绑定即可。私聊直接发消息；群聊 / 话题默认 @bot，也可按下文的权限与白名单要求开启无 @ 模式。

Q: 需要公网 IP、域名或服务器吗？

A: 不需要。飞书通道使用 WebSocket 长连接（出站连接），本机在 NAT 后面也能用，免公网服务器、免域名、免内网穿透。

Q: dsh-lark-bot 和其他 DeepSeek Harness 飞书插件（如 harness-lark）有什么区别？

A: 功能组合最全：安全网守护、多角色 Agent、多机器人可信交接、并行多任务、持久任务对账、会话归档、跨会话主动通知、dsh Web 可视化设置、对话内模型 / 密钥管理、执行模式与关键任务计划门禁十一项合一；标准 dsh profile bundle，setup 是唯一安装路径；可选 service install 只负责把同一 profile 交给 OS 常驻，不是第二套运行时。

Q: 项目从哪下载？会不会有假冒版本？

A: 唯一官方仓库是 github.com/PlutoKeating/dsh-lark-bot，唯一官方 npm 包是 dsh-lark-bot / dsh-feishu-bot（维护者 plutokeating）。本项目从不提供 .exe 或“下载即运行”的安装包；任何以项目名义分发 exe 的仓库或页面都是假冒来源，请勿运行（详见文末「假冒仓库警告」）。

关键词

dsh · deepseek · deepseek harness · feishu · lark · bridge · bot · chatbot · messaging · qrcode · typescript · feishu-bot · lark-bot · dsh-plugin · deepseek-harness · im-bridge · ai-agent · workspace · self-healing

兼容性

• DeepSeek Harness（dsh）：已验证 dsh 0.1.0-rc.8（最后验证 2026-08-20：临时安装 + SDK JSON-RPC / ACP runtime initialize、工具/审批、live session 续接与 restart collision 探针），通过官方 @deepseek-ai/dsh-sdk-client / @deepseek-ai/dsh-acp 接入； 具体锁定版本、升级政策与自动化探测见 docs/COMPATIBILITY.md， adapter 接入细节见 docs/adapter-notes.md，rc.8 差异、已知风险和 自动/人工验证边界见 docs/DSH_RC8_AUDIT.md。
• 运行时：Node.js ≥ 22.19（见 package.json engines）。
• 平台：Linux / macOS / Windows（飞书 WebSocket 出站长连接，免公网服务器 / 域名 / 内网穿透）。
• 默认 adapter 为官方 @deepseek-ai/dsh-sdk-client（SDK JSON-RPC runtime，原生 session 续跑 + token 级流式事件）；DSH_LARK_ADAPTER=acp 切到官方 ACP server（审批卡）；headless 保留旧版 子进程 fallback；DSH_LARK_ADAPTER=web 驱动本地 dsh web agent（session.prompt + /api/events.mux，网页端成为唯一写者，从根上消除多写者会话损坏）。首次启动自动在 ~/.dsh/profiles/dsh-lark-sdk（或 dsh-lark-acp）创建 runtime profile。

已知限制

• ACP 模式会话每次全新（上游限制，无续跑）；SDK 协议暂无 mid-turn cancel，/stop 会关闭 对应 runtime 并自动重建。
• 桥接引擎作为 dsh 插件在 dsh 进程内运行，agent 执行使用官方 dsh SDK runtime 子进程 （嵌套 runtime 是有意取舍，用于按工作区隔离的 runtime 池与 scope 内并行 run）。 唯一的进程级例外是默认安装的「安全网守护」——它独立于 dsh / Cordis 常驻，仅在 dsh 下线后接管飞书通道，正常运行时保持静默。
• 飞书文档评论、富文本回复为规划中能力，尚未实现。
• pnpm ≥ 10 的构建脚本策略由 setup 自动处理；手动 dsh plugin add 时若报 ERR_PNPM_IGNORED_BUILDS，按官方指引在 profile 的 pnpm-workspace.yaml 加 allowBuilds: { protobufjs: true } 后重试。

配置

dsh Web 可视化设置（推荐）

打开本机 dsh Web，进入 Settings → Plugins → Plugin configuration → dsh-lark-bot。页面可直接查看和修改服务区域、App ID、App Secret、默认项目文件夹、默认模型、每会话并行任务数、adapter 与默认提醒策略：

• App Secret 标记为 secret，只能写入，Web 响应、卡片和日志都不会回显；扫码绑定后实际生效的 profile 会作为页面初始值，App ID 不会错误显示为空。

• 点击“保存设置”后，凭据、区域、工作目录和 adapter 会安全停止旧 generation 后自动重连；模型、并行数和提醒会热更新到下一任务/提醒，不中断正在执行的任务，页面逐项标明时机。

• “快速诊断”可在本页直接检查设置连接、App ID、工作目录、模型和远程只读状态；需要运行态详情时可继续复制 /status 或 /doctor 到飞书会话。

• 浏览器半侧由本包的 ./client 动态加载并注册到官方插件配置页，不需要 fork 或重建 dsh Web。没有 Web 设置服务时，现有飞书命令和下列环境变量仍可使用。

• 本地配置：~/.dsh-lark/config.json

• 状态根目录可用 DSH_LARK_HOME 覆盖

• 环境变量统一使用 DSH_LARK_* 前缀

• 模板见 .env.example

• 敏感项：DSH_LARK_APP_SECRET、DEEPSEEK_API_KEY 等凭据只保存在本机配置 / 环境中，日志与 卡片自动脱敏，仓库只提交 .env.example 模板。

会话运行在 Git 仓库中时，会自动在 ~/.dsh-lark/profiles/<profile>/worktrees/<scope-slug>-<path-hash>/ 创建隔离 worktree，并复制项目级 AGENTS.md。升级时会先从 Git registry 核验旧版 <scope-slug> worktree 的 owning repo：会话与旧 retention 归档归回真实项目，匹配时原位迁移并保留分支与未提交文件；当前指针已切到其他项目时则保留旧树并为新项目独立建树。

每个飞书 scope 默认保存最近 40 条对话消息（可用 /retention 或 DSH_LARK_RETENTION_MSGS 调整）；超出保留窗口的消息自动归档到 ~/.dsh-lark/profiles/<profile>/archives/（Markdown + JSONL，目录本身是 Git 仓库，每次归档独立 commit），支持 /archive 对当前 workspace 手动归档、 查看与执行保留策略清理。 SDK 模式下 dsh 原生 session 续跑，headless 模式则把历史注入下一次 prompt 实现近似记忆。

当前核心环境变量：

前往 GitHub