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

dsh-feishu-bot

DeepSeek Harness 的飞书（Lark）私聊前端：在飞书里驱动、监控、审批本地智能体，与 Web GUI 在同一进程内共享活跃会话和冷会话。

状态：M0–M7 产品工作与 M6 可靠性实现均已由自动化测试覆盖。stage-6 预览门禁会构建自包含的 @tingrudeng/dsh-feishu-bot@0.1.0-rc.11 tarball（Cordis 仍作为宿主 peer），审计其 manifest 与文件，生成绑定该 tarball 的 CycloneDX SBOM，在检出目录之外安装，导入全部四个入口点，并在干净的 DSH 配置档中完成组合。rc.8 发布成功验证了仅靠 tag 的 OIDC 工作流、npm latest 单调递增、远程 tag 到 commit 的校验、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 <sessionId|n> — 绑定已有会话；保留为 /ls 的文本回退方式
- /stop — 取消正在运行的轮次，同时保留排队中的后续消息
- /status / /effort <id> / /model / /release / /help
- 纯文本会发送到已绑定的会话。只要飞书聊天仍处于绑定状态，无论从飞书还是 Web 发起的每个人工任务，都会在飞书里拥有一个任务卡片和一份任务级持久结果；/release 会停止这种同步。子代理的续接轮次会修补原卡片，而不是新建消息，工具调用的过程说明不会作为结果投影。失败的任务卡片只显示白名单内的稳定错误码和重试次数，绝不显示服务商返回的任意错误消息。

安装（装入已有的 web 配置档）

飞书控制台配置、凭据、白名单、启动、命令和故障排查，见中文使用指南。

要从源码检出迁移到已发布的 DSH 构建？ 先读 docs/deploy-on-release-dsh.md。源码链接方式通过相邻的 deepseek-harness 检出解析 @deepseek-ai/，已发布的安装不提供这一路径；而且已发布的 latest 落后 master 49 个 commit，两次卡片合并都不在其中。

dsh plugin --profile web add /path/to/dsh-feishu-bot
dsh --profile web --dump-config # expect gateway, bridge, 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 描述文件。这一步不会发布 tag、GitHub Release 或 registry 包。registry 安装只走唯一支持的渠道 @tingrudeng/dsh-feishu-bot@latest。

配置档里还留着旧的未加作用域源包的，必须先删掉再装带作用域的 RC；DSH 按包名对 bundle 做协调，不会自动替换： sh
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 环境放行某个 job 之后，该 job 用 actions: read 等待所有更低的 workflow run_number 跑完。随后它会拒绝不够新的候选版本——候选必须严格新于 registry 当前的 RC latest；workflow 重跑会被拒绝，所以一次失败的不可变发布尝试需要一个新的、更高的 RC 标签。GitHub 对持有 contents: read 的 job token 隐藏 Draft Releases，因此 publish_npm 在 job 级别持有 contents: write，在不可逆的 npm 发布之前立刻重新校验 Draft。GitHub Actions 无法把该权限限定到单个 step：SHA 固定的 checkout 使用 token 但不持久化它，GH_TOKEN 只显式传给队列步骤和 Draft/tag 重新校验步骤，workflow 契约测试会拒绝该 job 中的 GitHub 写方法、release 变更命令、dist-tag 写入和 Git 推送。按从旧到新的顺序批准运行，或者在放行较新的运行之前显式取消被放弃的较旧运行。每次打新 RC 标签之前，都要重新确认受保护环境、v-rc. 标签的禁止更新/禁止删除规则、Action SHA 固定和 Immutable Releases 仍处于启用状态；workflow 会在每个发布边界重新校验剥离后的标签提交，但仓库策略才能封住剩下的标签检查/写入窗口。npm 版本端点和根 packument 都通过同一个 no-store 边界重试，直到 provenance 和 latest 可见。draft asset 的 GET 检查和把 prerelease 转为公开的 PATCH 不是一次原子的 GitHub API 操作，所以在 finalize 期间，无关的 contents: write 操作者不得改动 draft；PATCH 之后出现不一致会让 workflow 失败，但可能让一个坏的 prerelease 短暂可见或不可变。rc.7 完成了那次一次性 bootstrap 发布。现在 bootstrap 被永久拒绝，因为包已存在；为这个确切的 workflow/environment 配置 Trusted Publisher，移除 bootstrap secret/SHA，吊销其 token，并在创建 rc.8 之前设置 NPM_AUTH_MODE=oidc。这些是远程状态变更，需要单独授权；仅靠 workflow 文件不会执行它们。

凭据：在 dsh 凭据服务读取它们的位置设置 FEISHU_APP_ID / FEISHU_APP_SECRET。本仓库中不放任何 secret。

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

在部署配置档提供 allowedOpenIds 和 allowedWorkspaces 之前，bundle 补丁保持 fail-closed。配置好的 defaultWorkspace 会在 bridge 加载时校验，且必须解析到某个允许的根目录之内。

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

配置参考

Gateway 选项：

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

Bridge 选项：

| Key | Default | Purpose |
| allowedOpenIds | [] | 允许交互的用户；为空则拒绝所有人 |
| allowedWorkspaces | [] | /ls、/use 和 /new 可见的规范根目录；为空则不授权任何目录 |
| defaultWorkspace | unset | /new 的默认工作目录；支持 ~，如果解析出的目录不在允许的根目录内，加载会失败 |
| freshnessMs | 600000 | 新投递的飞书事件的最大年龄 |
| listingTtlMs | 300000 | 最新 /ls 卡片和序号快照的存活时间 |
| cardThrottleMs | 1000 | 非终态任务卡片补丁之间的最小间隔 |
| progressDetail | summary | 飞书任务卡片的详细程度。每一档都说明调用正在做什么*（沿用 Web GUI 自己的活动词汇，例如用「正在读取文件」代替工具名）：concise 只显示活动，summary 额外显示作用对象（文件、命令或查询）和耗时，full 再额外显示 token 用量。运行中的卡片还会在工具行上方列出智能体自己说过的话（保留最新 3 条，过长的会被截断）；concise 不显示这些 |
| recoveryTtlMs | 86400000 | 中断的入站工作可参与重启恢复的最大年龄 |
| disposeDrainTimeoutMs | 5000 | 关闭存储前，Bridge 等待已受理的聊天/卡片/审批/投影工作的截止时间 |
| inboundRetentionMs / inboundMaxRecords | 604800000 / 50000 | 终态入站记录的保留时长和硬容量；受保护的可恢复行会触发背压，而不是被驱逐 |
| outboundRetentionMs / outboundMaxRecords | 604800000 / 10000 | 旧版 outbox/死信的保留时长和硬容量 |
| 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 链接 |

结果卡片分段对完整的飞书 create-message 信封套用固定的 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。任务和审批卡片还会发送工作区基名、任务/工具状态、工具名、审批原因和可用的 token 使用情况事实；工具参数不会放在审批卡片上。没有出站内容过滤器；本地绝对 Markdown 链接只会得到展示层重写（label → label（/path）），路径本身仍会上传。信任边界是谁可以绑定，由 allowedOpenIds（空值拒绝所有人）和 allowedWorkspaces（/ls//use//new 都限定在配置的根目录内）以失败关闭方式强制执行。不要将会话不得离开本机的工作区加入允许列表。注意边界的准确含义：allowedWorkspaces 控制飞书可以绑定、列出或创建哪些会话——它并不限制已绑定会话的智能体可以读取什么。Harness 沙箱只围栏写入（读取在所有模式下都是操作系统用户级），因此智能体被要求读取工作区外的文件并复述时，它就会这么做，而该回复会像其他回复一样上传。读取隔离需要操作系统级隔离（专用用户账户），而不是此插件的配置。消息正文永远不会进入插件自己的日志或审计记录（仅 ID 和哈希）；Client/WS SDK 失败会经过递归脱敏器，而事件分发器保持静默，因此任意入站载荷都无法被打印。

许可证

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