飞书私聊前端TingRuDeng/dsh-feishu-bot

dsh-feishu-bot

用于 DeepSeek Harness 的飞书（Lark）私聊前端：从飞书驱动、监控和审批本地 agent，在同一进程中与 Web GUI 共享实时和冷会话。

状态：M0–M7 产品工作以及 M6 可靠性实现均已由自动化测试覆盖。第 6 阶段预览门禁会构建一个自包含的 @tingrudeng/dsh-feishu-bot@0.1.0-rc.11 tarball（Cordis 仍为宿主 peer），审计其 manifest/文件，生成与 tarball 绑定的 CycloneDX SBOM，在检出目录之外安装，导入全部四个入口点，并在干净的 DSH profile 中完成组合。rc.8 发布成功验证了仅标签的 OIDC 工作流、单调递增的 npm latest、远程标签到提交的校验、GitHub/npm 来源验证，以及单 tarball 的 GitHub Prerelease 加 npm 发布。rc.11 包含 rc.9 的 S4 Markdown 转义统一、M7.0–M7.3 的模型/effort 选择、会话持久化所有权围栏，以及对 DSH 0.1.2-alpha.2 的兼容性；在预览包通过真实飞书验收之前，它仍是本地候选版本。源 link: 依赖有意保留用于本地调试，并已从打包后的 manifest 中移除。文档：中文使用指南 · 设计 · 里程碑记录 · 交接 · M0 验证记录 · weclaw 经验教训。

命令（私聊）

- /new [cwd] — 在允许的工作区下创建会话并绑定
- /ls — 未归档会话的两级卡片：先选择工作区，再点击真实会话标题进行绑定
- /use  — 绑定已有会话；保留作为 /ls 的文本回退
- /stop — 取消正在运行的轮次，同时保留已排队的后续消息
- /status / /effort  / /model / /release / /help
- 纯文本会发送到已绑定的会话。当飞书聊天保持绑定时，从飞书或 Web 启动的每个直接人工任务都会在飞书中拥有一个任务卡片和一个任务级持久结果；/release 会停止该同步。子 agent 的延续轮次会修补原卡片，而不是创建新消息，工具调用评论不会作为结果投射。失败的任务卡片会显示允许列表中的稳定错误码和重试次数，绝不会显示任意的提供方错误消息。

安装（到现有 web profile 中）

关于飞书控制台设置、凭据、允许列表、启动、命令和故障排除，请参阅中文使用指南。

dsh plugin --profile web add /path/to/dsh-feishu-bot
dsh --profile web --dump-config   # expect gateway, bridge, registry, and invariant rows
如需预构建的本地预览，请从干净的检出运行 pnpm release:preview。单一发布门禁会依次运行冻结安装、测试、类型检查、构建、tarball/manifest 审计、SBOM 生成、隔离安装、四入口导入、干净配置组合以及校验和生成。使用 dsh plugin --profile web add /absolute/path/to/the.tgz 安装生成的 artifacts/tingrudeng-dsh-feishu-bot-0.1.0-rc.11.tgz；验证 artifacts/SHA256SUMS，并在需要溯源时检查匹配的 .cdx.json 以及 release.json 描述符。这不会发布标签、GitHub Release 或注册表包。注册表安装使用唯一受支持的渠道 @tingrudeng/dsh-feishu-bot@latest。

仍包含旧的非作用域源包的配置文件必须在安装作用域 RC 之前将其移除；DSH 按包名协调 bundle，不会自动替换它：

dsh plugin --profile web remove dsh-feishu-bot
dsh plugin --profile web add @tingrudeng/dsh-feishu-bot@latest
维护者：.github/workflows/release.yml 只接受匹配的 RC 标签推送。它不使用 GitHub 有损的单待处理原生并发组：在受保护的 npm-release 环境接纳某个作业后，该作业使用 actions: read 等待每个更低的工作流 run_number 完成。然后它会拒绝一个并非严格新于注册表当前 RC latest 的候选；工作流重跑会被拒绝，因此一次失败的不可变发布尝试需要一个新的、更高的 RC 标签。GitHub 对 contents: read 作业令牌隐藏草稿发布，因此 publish_npm 具有作业级 contents: write，以在不可逆的 npm 发布前立即重新验证草稿。GitHub Actions 无法将该权限限定到单个步骤：SHA 固定的检出使用令牌而不持久化它，GH_TOKEN 仅显式传递给队列和草稿/标签重新验证步骤，并且工作流契约测试会拒绝来自该作业的 GitHub 写入方法、发布变更命令、dist-tag 写入和 Git 推送。按最旧优先批准运行，或在接纳较新的运行前显式取消被放弃的较旧运行。在每个新的 RC 标签之前，重新检查受保护环境、禁止更新/删除的 v-rc. 标签规则、Action SHA 固定和不可变发布是否仍处于启用状态；工作流会在每个发布边界重新检查剥离后的标签提交，但仓库策略会关闭剩余的标签检查/写入窗口。npm 版本端点和根 packument 都会通过同一个 no-store 边界重试，直到 provenance 和 latest 可见。草稿资产 GET 检查与使预发布公开的 PATCH 不是一次原子 GitHub API 操作，因此在 finalize 期间，无关的 contents: write 操作者不得修改草稿；PATCH 后不匹配会使工作流失败，但可能让一个错误的预发布短暂可见或不可变。rc.7 完成了首次引导发布。现在引导会被永久拒绝，因为该包已存在；在创建 rc.8 之前，为此确切的工作流/环境配置 Trusted Publisher，移除引导 secret/SHA，撤销其令牌，并设置 NPM_AUTH_MODE=oidc。这些是远程状态变更，需要单独授权；仅工作流文件本身不会执行它们。

凭据：在 dsh 凭据服务读取它们的位置设置 FEISHU_APP_ID / FEISHU_APP_SECRET。此仓库中不得有 secret。

飞书控制台先决条件（长连接模式）：订阅 im.message.receive_v1 事件并授予 im:message.p2p_msg:readonly，并且对于审批卡片，启用 card.action.trigger 回调；每次更改后发布一个应用版本。

在部署配置提供 allowedOpenIds 和 allowedWorkspaces 之前，bundle 补丁会故障关闭。配置的 defaultWorkspace 会在 bridge 加载期间验证，并且必须解析到允许的根目录内。

模型体验
- 插件不会注入系统提示词、模型指令或工具 schema。Provider、模型、系统提示词和工具行为仍归 DeepSeek Harness 所有。
- 普通的非命令飞书消息会原样进入绑定的会话，作为一个用户文本块，并带有 source.via = "feishu"；桥接层不会重写其内容。
- 审批卡片与现有的 approval/asked 事件配对。飞书或 Web 的胜出决策会解决正常的审批请求，因此 DeepSeek Harness 仍是规范 approval/decided 审计事件的所有者。重启失效绝不会伪造决策。

配置参考

网关选项：

| 键 | 默认值 | 用途 |
|---|---:|---|
| appIdRef / appSecretRef | bundle: FEISHU_APP_ID / FEISHU_APP_SECRET | 凭据服务引用；绝不使用原始密钥 |
| sendRetryBaseMs | 500 | 指数退避重试的基础延迟 |
| sendMaxAttempts | 4 | 文本和卡片发送共享的最大尝试次数 |
| sendCircuitCooldownMs | 30000 | 重试预算耗尽后每个聊天的冷却时间 |
| disposeDrainTimeoutMs | 5000 | 已接受发送的 HMR/关闭最大排空时间 |

桥接选项：

| 键 | 默认值 | 用途 |
|---|---:|---|
| allowedOpenIds | [] | 允许交互的用户；为空则拒绝所有人 |
| allowedWorkspaces | [] | 对 /ls、/use 和 /new 可见的规范根目录；为空则不授权任何目录 |
| defaultWorkspace | 未设置 | 默认 /new 工作目录；支持 ~，如果解析后的目录在允许的根目录之外则加载失败 |
| freshnessMs | 600000 | 新投递的飞书事件的最大年龄 |
| listingTtlMs | 300000 | 最新 /ls 卡片和序号快照的生命周期 |
| cardThrottleMs | 1000 | 非终态任务卡片补丁之间的最小间隔 |
| progressDetail | summary | 飞书任务卡片详情：concise 隐藏时长/token 信息，summary 显示时长但隐藏 token 用量，full 两者都显示 |
| recoveryTtlMs | 86400000 | 符合重启恢复条件的中断入站工作的最大年龄 |
| bindingCleanupTimeoutMs | 5000 | 绑定切换失败后处置新建会话的独立超时 |
| disposeDrainTimeoutMs | 5000 | 存储关闭前已准入的聊天/卡片/审批/投影工作的桥接截止时间 |
| inboundRetentionMs / inboundMaxRecords | 604800000 / 50000 | 终态入站保留时间和硬容量；受保护的可恢复行会导致背压而非被驱逐 |
| outboundRetentionMs / outboundMaxRecords | 604800000 / 10000 | 旧版发件箱/死信保留时间和硬容量 |
| outboundPendingTtlMs | 86400000 | 旧版未发送段被放弃并清除其正文的年龄 |
| deliveryRetentionMs / deliveryMaxRecords | 604800000 / 10000 | 规范结果投递保留时间和硬容量 |
| deliveryPendingTtlMs | 86400000 | 未发送的规范结果被放弃并清除其正文的年龄 |
| approvalPendingTtlMs / approvalMaxRecords | 86400000 / 1000 | 非活跃审批恢复事实的 TTL 与硬容量；活跃/新鲜的歧义行受保护 |
| projectionCursorRetentionMs / projectionCursorMaxRecords | 604800000 / 10000 | 未绑定游标的保留期与硬容量；活跃或待投递的游标受保护 |
| maintenanceIntervalMs | 86400000 | 保留清理扫描间隔；0 禁用周期性定时器，但启动清理仍会运行 |
| agentProvider / agentModel | 未设置 | 可选的成对覆盖；省略时，新会话和冷恢复会话遵循 Harness 的 agent-default-model |
| webUrl | http://127.0.0.1:3080 | 放置在审批卡片上的 Web GUI 链接 |

结果卡片分段在完整的飞书创建消息信封上使用固定的 24 KiB 软限制；它有意不作为部署设置。

可靠性与审计

- 网关构建不会启动长连接。桥接器首先打开两个存储域，完成本地对账/保留清理，并按每个聊天的 FIFO 顺序排队遗留输出、规范输出和会话日志追赶。然后它注册一个返回 Promise 的准入处理器并开始接收。排队的恢复 I/O 可能在就绪后继续，因此一个挂起的飞书请求不会阻塞插件激活；同一聊天的新工作仍会排在恢复之后按序处理。
- 入站 SDK 回调只有在以飞书 message_id 为键的 received 行持久化后才会完成。event_id 仍作为遗留/审计别名。业务处理随后在按聊天队列中异步进行；这是准入提交点，并不表示模型已经消费了该消息。
- 已提交的助手结果会从会话日志中重新读取。桥接器在推进其 (chat, session) 游标之前写入一个完整的规范投递，在发送时派生确定性分段，并为每个逻辑形状复用稳定的 32 位十六进制飞书 uuid。游标意味着“已持久物化”，而不是“已投递”。
- 传输失败被分类为永久性、可重试或歧义。只有明确的卡片形状拒绝才可能回退为文本；超时、断开连接和 5xx 类歧义会保留原始形状和 UUID。平台侧的 UUID 去重仍需要飞书实际接受，才能做出精确一次投递的声明。
- 文本/卡片创建和卡片补丁操作会被串行化并排空。HMR 会停止准入和接收，在配置的截止时间内排空已准入的聊天/卡片/审批/投影工作，然后关闭存储。如果桥接器截止时间到期，写入会被隔离；持久化的待处理工作会保留以供重启恢复。
- 保留限制是硬上限。终端行会首先被驱逐；活跃审批、可恢复的入站行、待处理投递以及活跃/保护性游标不会为了满足容量而被牺牲，因此准入可能因显式背压而失败。
- 不变量伴随器会拒绝一个活跃绑定，如果其会话在实时和持久化会话存储中都不存在。
- feishu-audit 事件包含操作名称、枚举结果、计数器以及标识符的稳定哈希。它们不包含消息/命令正文、凭据或完整文件系统路径。传输错误被缩减为错误类别和安全代码；Client/WS 日志被递归脱敏，EventDispatcher 日志则完全静默。

已验证的 DeepSeek Harness 基线

当前发布基线为 DeepSeek Harness 0.1.2-alpha.2，对应官方 master 提交 0a53fb55bea101816fa226bb964ae2bed71c343b（检查于 2026-08-31）。本地源码检查和发布工作流均使用此干净检出。

数据暴露模型

绑定一个聊天会将该会话的对话上传到飞书，这是设计使然：助手回复——包括模型选择打印的任何源代码、文件内容、命令输出或机密——都会被发送到字节跳动运营的飞书服务器。第一张 /ls 卡片会发送工作区基名和会话数量；进入某个工作区后，会发送该工作区的会话标题。它不会在卡片负载中发送完整工作区路径或会话 ID。其他命令回复可能包含绝对本地路径和完整会话 ID。任务和审批卡片还会额外发送工作区基名、任务/工具状态、工具名称、审批原因以及可用的令牌使用事实；工具参数不会放在审批卡片上。没有出站内容过滤器；绝对本地 Markdown 链接仅会接受展示层面的重写（label → label（/path）），而路径本身仍会被上传。信任边界是谁可以绑定，由 allowedOpenIds（空值会拒绝所有人）和 allowedWorkspaces（/ls//use//new 均限定在配置的根目录内）以故障关闭方式强制执行。不要将那些会话绝不能离开本机的工作区加入允许列表。注意该边界的准确含义：allowedWorkspaces 控制飞书可以绑定、列出或创建哪些会话——它并不限制已绑定会话的代理可以读取什么。Harness 沙箱仅限制写入（在所有模式下读取都是操作系统用户级别的），因此，如果要求代理读取其工作区之外的文件并复述出来，它就会这样做，而该回复会像其他回复一样被上传。读取隔离需要操作系统级别的隔离（专用用户账户），而不是此插件的配置。消息正文永远不会进入插件自身的日志或审计记录（仅 ID 和哈希）；Client/WS SDK 失败会经过递归脱敏器，而事件分发器则保持静默，因此任意入站负载都无法被打印。

许可证

MIT。设计文档中引用了其他社区桥接的架构参考；未复制任何 AGPL 代码。