Telebot 技术路线转换:产品与开发总结
本文回顾我将 Telebot 从 LangGraph/Python 应用重建为官方 DeepSeek Harness 插件集的过程,包括选型考虑、产品范围、架构取舍和开发经验。
项目代码:Telebot 的 Harness 插件分支(dsh-plugin)。该链接指向持续更新的开发分支,后续代码和功能可能与本文描述有所不同。
一、背景与决策
原版 Telebot 以 Python、LangChain/LangGraph ReAct 工作流为基础,逐步接入飞书、文件和 Shell、Codex、知识库、定时任务、发布及多维表格等能力。随着能力增加,项目需要同时维护 Agent 执行、上下文、路由、渠道、调度、业务工具与运行环境。旧版已有相当多的业务规则和测试,但这些能力集中在同一个应用的运行链路中,新增功能需要考虑与既有路由、状态、权限和调度的配合。
本次选择以官方 DeepSeek Harness 为宿主,将 Telebot 重建为可独立安装的插件集。产品仍面向飞书和本机桌面对话中的实际工作,底层则复用官方 Agent、Session、模型、命令、Shell 和 schedule。旧项目作为行为参考,不迁入其 Python Agent 循环或运行时依赖。
我的主要考虑有以下五点。这些是作出选择时的判断和预期收益,与后文记录的实际交付结果分开表述。
| 主要考虑 | 选型时的判断与预期收益 |
|---|---|
| 生态丰富 | 社区中有大量开源插件,官方也在持续更新;希望直接利用已有能力,减少重复建设,并为后续需求保留选择空间。 |
| 技术路线好 | 认可 Cordis 的插件与服务组合架构,将不同模块作为插件接入,复用官方通用运行能力。 |
| 方便迭代 | 功能插件可以分别开发、维护和迭代;新需求可以继续作为模块加入,减少在庞大应用中处理耦合及调度混乱的负担。 |
| 形态适配 | 当前工作可以拆分为几个边界比较明确的功能模块,业务形态与插件组合方式匹配,技术上具有可行性。 |
| 预计工作量不大 | 已有实现可作为参考对象,行为规则比较清晰,可以沿用已有需求理解和验收场景,预期重建工作量可控。 |
实施中,知识库采用外部 dsh-knowledge@0.5.2,是复用生态能力的具体选择。插件之间仍需协调共享 core、宿主版本及跨模块契约;授权、兼容性和真实验收也需要重新落实。丰富的生态提供了选择空间,具体插件仍需逐个验证兼容性。“工作量不大”是我当时的预估,目前没有足够记录量化实际工时或节省比例。
二、产品定义与范围
目标是提供一组安装在外部官方发行版上的插件,让用户通过飞书或官方桌面对话使用所需能力。飞书与桌面共享业务实现,但身份与权限分开;桌面入口经可信宿主识别后默认完整权限,飞书继续执行身份、资源和操作授权。业务结果应以可读文本或卡片呈现,危险写入保留必要的冻结、确认、幂等和回执。
| 模块 | 产品职责 |
|---|---|
| core | 公共服务、会话与宿主适配、共享契约和交互能力。 |
| desktop | 官方原生桌面对话入口与可信身份适配。 |
| feishu | 飞书渠道、消息与附件,以及文档、多维表格、日历、任务等业务接入和授权。 |
| codex | 复用本机 Codex CLI,支持检查、规划、执行、历史与产物。 |
| adviser | 无状态第二意见;当前正式配置中保持停用。 |
| publishing | 报告、原文发布和受控 Git 交付。 |
| automation | 在官方 schedule 时钟之上处理业务规则、授权、执行与投递账本。 |
| 外部知识库 | 使用上游 dsh-knowledge,不复制源码或自建同名知识库插件。 |
产品不另建应用宿主、聊天前端、Agent 循环、插件加载器、通用 Shell 执行器或第二个定时器。旧知识库迁移及飞书知识空间绑定已取消;生产数据迁移没有执行。功能完成需要分别验证业务行为、资源授权、失败恢复及实际部署效果。
范围的演进与取舍
下表记录目标如何收敛,具体发生日期没有充分记录的条目不补写日期。
| 议题 | 当前决定及其影响 |
|---|---|
| 飞书与桌面入口 | 从飞书连接宿主的目标扩展到原生桌面可独立使用业务插件;增加 desktop 适配,业务实现共用,两个入口的身份与权限分开。 |
| 知识库 | 改用外部插件;取消自建同名插件、旧知识库迁移及飞书知识空间绑定,避免继续维护另一套知识库引擎。 |
| 飞书身份 | 统一使用应用身份,取消用户 OAuth 和身份回退;资源可用范围取决于应用实际权限及插件授权规则。 |
| 平台与账户 | 当前优先 Windows,Linux/macOS 保留为待验收范围;复用既有 Codex CLI 登录,不增加 Codex/OpenCLI 账户要求,顾问账户接入不在当前验收范围。 |
| 配置入口 | 统一接入官方原生设置页及所有者认证接口,不保留独立配置站点。 |
| 更新与交付 | 当前使用官方管理器支持且实际验证过的安装方式;远程不停机更新和统一安装迁移向导不在本轮实施范围。 |
主动取消的能力不再作为遗漏追补;延期或待验收能力仍需按计划单独取得证据。增加新的范围须明确改变哪项产品决定,不能仅因旧实现中存在相似代码就自动纳入。
三、调研与方案形成
动手之前要回答四个问题:官方扩展点能不能承载现有工作、旧能力该怎么划分、哪些规则必须保留,以及怎么证明插件在真实的官方发行版里确实装得起来、组合得对。
先把判断依据定下来。 实施只以官方 profile、插件管理器和公开服务为边界;缺 API 时记录兼容门禁、去找官方兼容版本,而不是把私有 fork 变成生产前提。
宿主管通用能力。 Agent/Session、模型、命令、Shell 和 schedule 全部由官方提供,插件只实现自己的策略和适配,不再写一套调度与执行框架。
领域与宿主隔离。 领域层只用本地 DTO 和端口,Cordis 与官方 API 收在 adapter 和装配层;共享的运行时服务定义统一由 core 拥有,避免不同包产生互不兼容的服务身份。
按行为迁移,而不是搬代码。 参考旧版的消息、授权、定时和产物规则,在新宿主上重新设计实现与测试,不假设旧的数据结构或 Python 依赖能直接复用。
版本和安装要可复现。 每个安装包声明精确的 engines.dsh 和宿主 peer,以外部官方发行版、打包产物和官方管理器为兼容目标,不把工作区链接或源码目录当生产依赖。
用户数据不能丢。 运行配置和业务数据存在用户目录或显式数据目录,凭据交给官方 credentials;验证环境放在 D 盘,原有兼容联接和用户数据保持不变。
版本上也有过一次切换:早期验证过 0.2.2-alpha.2,当前对照的桌面目标与正式安装版本是 0.2.1-rc.5。但版本号本身不说明兼容性——扩展点、依赖和原生入口都要逐项对齐,在开发环境或 Web 组合里跑通,也不能直接推广到用户桌面。
需要说明的是,这一段是根据开发计划、代码结构和最终交付反推出来的;仓库里没有留下每次调研的具体日期、候选方案对比和工时记录,所以不补写。
四、开发过程与关键演进
旧版从 5 月做到 10 月,思路是不断往同一个应用里加能力:先写设计文档、搭起能跑的基础 Agent,再依次接上 skill 化工作流、LangChain 适配、飞书单入口、Codex 受控执行、知识库、定时投递和多维表格。到 10 月底,它已经覆盖了后来需要重建的大部分业务行为,代码也积累了较重的耦合。
11 月 1 日转入插件重建后,节奏明显变快,几乎每半天推进一个台阶。
第一步,按能力边界拆包。 把仓库切成 core、feishu、desktop、codex、adviser、publishing、automation 七个插件,删除旧的 Python 应用树。通用运行能力留给官方宿主,插件只负责各自领域的策略和适配,旧进度文档整体归档。
第二步,配置回到官方入口。 插件配置接入官方原生设置页和所有者认证接口,不再维护独立配置站点;配套补齐飞书配置、安装、桌面入口和运维四份文档。
第三步,修掉配置的空值问题。 可选字段留空时,保存与重读会出现异常,于是把空值语义写进配置契约,并同步更新状态文档。
第四步,收体验。 调整飞书的通道层、本地存储适配、资源发现和链接解析,理顺 core 的会话与交互契约,也让 automation 的工具入参校验更严格。
第五步,让结果可读、确认可用。 预览和回执改成富文本呈现;确认回复不再依赖固定短语,改由模型结合入站时冻结的候选做一次意图判断,再由确定性代码核对权限、有效期和一次性消费。
这五步之后,插件的骨架和交互都立住了,剩下的工作转向真实验收与兼容性核对。
具体实现中,飞书事件和回调需要去重,资源写操作需绑定用户、会话与目标并在确认后核验;执行和投递分账,避免投递失败导致业务重做。自动化复用官方时钟,同时保留周期、时区、补跑、授权和未知状态处理。Codex 使用本机 CLI,检查/规划维持只读语义。以上规则说明了插件化之后仍需保留的业务复杂度。
对话体验的演进
工具接通之后,还需要让用户能看懂结果、自然回应,并在继续聊天时保留正确上下文。当前迭代形成了几项明确要求:结果和进度用可读富文本或卡片呈现;未回答的卡片不阻塞新问题,答案仍能返回原请求;业务确认接受口语、礼貌表达和常见错字;执行结果既进入原会话,也进入当前续聊,避免用户不知道确认后发生了什么。
语义确认将理解表达与决定执行范围分开:模型结合入站时冻结的候选,做一次无工具意图判断;确定性代码继续核对候选归属、权限、有效期、执行范围和一次性消费。模型不能借确认回复生成新的写入授权;歧义、候选失效或判断失败均不默认执行,改变预览内容则需重做预览。这让用户表达更自然,同时保留可核验的执行边界。
五、测试与交付方法
验证从旧版 Python 测试体系转为按插件与安装层分组的统一入口。测试清单集中维护,按模块选择本地规则或宿主安装层检查,共享契约变更追加受影响消费者。
| 层次 | 目的和证据边界 |
|---|---|
| 本地域与客户端 | 验证业务规则、权限、状态、交互与异常路径;普通变更只运行受影响模块,共享契约再追加消费者。 |
| 安装与组合 | 构建、打包并检查归档闭包,使用仓库外官方发行版和官方管理器,在隔离 home 中验证宿主接线;组合测试使用 ACP v1、loopback 模型及平台模拟,不调用付费模型。 |
| 原生配置和入口 | 测试官方设置生命周期、所有者接口、桌面身份及权限隔离;ACP 不能替代原生命令注册表或业务授权测试。 |
| 真实服务 | `pnpm verify —live preflight |
| 发布兼容 | pnpm verify --release 用于明确的发行或兼容升级;普通变更不反复执行全部业务套件。 |
最近一次语义确认修复中,本地模块检查、官方 ACP 资源链路及正式启动检查通过;通过官方模型服务调用本地模拟模型,验证无工具意图判断、冻结执行、幂等和续聊上下文。这次修复没有运行 Web、发送真实飞书测试消息、改写远端资源或调用付费模型。冷启动超时预算调整后,针对性 ACP 门禁通过。各次证据只适用于对应版本和验证范围,历史测试计数不能简单相加或视为最新完整发行回归。
截至 2026-11-01,正式 desktop profile 已安装七个自有插件,六个启用、adviser 停用;外部知识库为 0.5.2。官方 Harness 目标为 0.2.1-rc.5,已核对启动、配置入口及配置/凭据保留。正式界面视觉和更新后的真实飞书交互仍由用户验收。真实入站及部分表格操作有历史日志证据,但不能推及复杂卡片、媒体、ACL、通知及定时投递全部通过。Linux/macOS、真实搜索、Git 远端认证、OpenCLI 账户以及生产数据迁移和恢复也未完成专项验收。
六、开发经验与问题复盘
| 已出现的问题或约束 | 调整与可复用经验 |
|---|---|
| 可选 JSON 配置存在空值处理问题 | 将空值语义纳入配置契约,并验证保存、重读及错误反馈。配置体验需要自己的测试,不能只验证插件能加载。 |
| 固定确认短语难以覆盖口语和错字 | 增加当前会话模型的单次无工具判断,并保留冻结候选及确定性校验;测试同时覆盖普通问题、歧义、失效和重复消费。 |
| 原生设置和身份依赖具体宿主接口 | 配置统一使用官方设置扩展和所有者接口;在实际官方发行版中验证接线、共享服务身份及权限隔离,尽早发现兼容门禁。 |
| 冷启动初始化预算影响组合测试 | 调整预算后针对性门禁通过。测试超时预算与用户感知的响应速度分别评价,放宽超时不能作为性能已经改善的证据。 |
| 开发持续迭代,旧记录容易被当成现行要求 | 将需求约束、当前事实和验证证据分别管理,明确证据与产物的关联;历史版本和归档只作证据,恢复工作先核对当前状态。 |
| 多模块变更容易反复触发无关验证 | 使用统一模块清单;普通变更只验证受影响模块,共享契约追加消费者,发行和兼容升级再执行完整门禁。保留旧证据的适用版本,避免用累计通过数代替当前覆盖。 |
| 安装更新、数据恢复和外部变更的可逆性不同 | 更新前备份配置、凭据和业务数据;渠道 schema 3 的恢复使用兼容快照,保持单写者,不通过删除租约绕过保护。外部写入和 unknown 结果单独核对,不能靠代码回退撤销。 |
这些调整也适用于后续的 AI 辅助开发:把用户反馈落实为明确的产品契约和可重跑场景,恢复工作时读取当前状态及相关模块,完成变更后留下适用范围清楚的证据。当前记录不足以量化这种组织方式节省了多少时间或调用成本。
七、结果与后续
本次转换把原本由项目整体承担的通用 Agent 运行职责交给官方宿主,并把渠道、入口和业务能力组织为可组合的插件。旧版最有价值的资产是已经明确的业务行为、授权规则和测试场景;插件边界、宿主兼容、交付和安全语义则需要在新架构中重新落实。
后续优先完成用户负责的界面与真实飞书交互验收,并按实际需求安排其他平台、真实服务以及生产数据迁移与恢复演练;这不恢复已取消的旧知识库迁移和飞书知识空间绑定。新功能先明确领域边界、宿主公开扩展点、权限与失败恢复,再按受影响模块验证;升级官方版本需在兼容升级分支重建、验证并更新精确元数据。