LWLT-AIBOT/archive/project-history/2026-08-18/task_plan-pre-compression-agentbus-status.md

项目文件治理计划

当前会话任务：AgentBus 渠道独立根路径与 404 修复

• 状态： 已完成；重复兼容记录清理和 listener 状态竞态修复均已加载运行。
• 问题事实： 当前 control-plane/src/server.ts 和 .build/control-plane/src/server.js 已包含 /api/channels；此前的 404 是旧进程未加载路由。默认渠道改名后旧进程曾补建重复兼容渠道；随后 listener 重载又暴露出“内部重载被写成已停用”的异步状态竞态。
• 本轮边界： 新增独立 /channels 管理页和页面路由；数据接口继续使用 /api/channels，渠道数据仍按当前管理员所属组织隔离；重复兼容记录只停用/隐藏，不物理删除。

实施清单

• 将 AgentBus 渠道面板从 AI 工作台移到独立 /channels 根路径。
• 增加 /channels 静态页面路由、导航激活态和缓存版本号。
• 保留 /api/channels CRUD/轮换接口并补充页面/路由契约测试。
• 完成全量验证并记录旧进程需要重启后才能加载新路由。
• 经用户授权重启控制面，验证 /api/channels 返回鉴权响应、/channels 返回 200、AgentBus session ready。
• 在独立渠道目录中增加“维护名称”，默认兼容渠道也可改名。
• 防止默认兼容渠道改名后重启生成重复渠道，并在启动时停用已产生的重复兼容记录。
• 修复渠道重载时把内部 stop 异步写成“已停用”的竞态；重载只写连接中/已连接，真正停用仍由管理员操作或服务关闭触发。
• 修复启动阶段同一渠道状态写入乱序；按渠道串行化 connecting → connected 状态落库。
• 经用户授权重启控制面，验证王徐明、阿虹两个 listener 均 enabled=true、connected=true、session_ready=true。

当前会话任务：多 AgentBus 用户渠道与插件串行队列

• 状态： 已完成；用户已确认方案并授权开始实施。
• 目标： 支持多个 AgentBus 来源/外部用户渠道，每个渠道独立保存 AgentBus key；插件/ERP 浏览器自动化同一组织同一时间只执行一个任务。
• 安全边界： 不读取或输出真实密钥；不执行 ERP 写入、生产部署或外部业务发送；本轮服务重启已获用户明确授权并完成。

已确认决策

1. 队列范围： 同一组织的 ERP 浏览器自动化全局单槽；其他任务在服务端持久化 FIFO，按 created_at,id 排队。
2. 渠道边界： 每个外部用户渠道拥有独立 AgentBus listener/WebSocket 连接和独立 key；渠道身份不创建后台登录账号，由管理员管理。
3. 可靠性： 入站路由、受理通知和最终回执使用持久化 outbox；断线、进程重启或排队期间可重试，不因内存超时误报。
4. 配置： WebSocket URL、client type、重连参数使用全局环境配置；渠道独立加密保存 key，可覆盖 bot address；旧的全局 token/bot 配置保留兼容。
5. 生命周期： 渠道支持启用/禁用和 key 轮换，不做物理删除；禁用不清理已有任务和待发送回执。
6. 范围排除： 不实现具体微信协议，不改变 Agent/Skill operation Schema，不做渠道级自动化策略。

实施阶段

• 读取项目记忆、业务登记表、相关 Skill/Schema/mapping/实现，并确认工作区脏改动需保留。
• 新增 migration 012：user_channels、tasks.channel_id、agentbus_deliveries。
• 新增渠道服务和 AgentBusManager：加密 key、CRUD/轮换、每渠道 listener、运行状态。
• 接入 durable AgentBus：按渠道幂等、受理 outbox、终态回执 outbox、断线释放租约、重连补发。
• 接入控制面 API 与操作台渠道管理；key 不回显。
• 接入组织级 FIFO ERP claim、排队信息和平台自动派发单任务防护。
• 同步配置示例、控制面文档、测试夹具及契约断言。
• 完成计划压缩后的仓库卫生、全量测试、构建和差异检查。

关键实现位置

• control-plane/migrations/012_agentbus_user_channels.sql
• control-plane/src/agentbus-channels.ts
• control-plane/src/agentbus.ts
• control-plane/src/task-service.ts
• control-plane/src/server.ts
• LianSyn-platform/app.js、index.html、styles.css
• control-plane/README.md、.env.example、.env.production.example

验证记录

• 已通过：控制面测试 53/53，含 listener 启动/重载状态回归和 durable channel listener 重投回归；build、git diff --check 通过。
• check:repo/test:legacy 当前仅被既有根目录 .DS_Store 和 dist/老挝联泰AI指令表-0.5.118.docx 哈希不一致阻断；这些用户既有文件未修改。check 已完成且无失败输出。
• 根目录活动计划压缩前完整快照：archive/project-history/2026-08-17/task_plan-pre-compression-agentbus-channels.md。

当前风险与收口条件

• 无可用生产 PostgreSQL/AgentBus 真实连接时，仅验证迁移文本、静态契约、单元测试和构建；不以本地模拟代替真实部署授权。
• 若全量验证发现与本轮无关的既有脏改动问题，只记录并保留，不回退用户改动。
• 所有源码验证和运行态检查已完成；清理采用停用/隐藏，不物理删除；未执行 ERP 写入、部署或外部发送。

当前会话任务：插件单任务/历史任务超时自愈

• 状态： 已完成；源码、发布包、运行态重启、历史任务收口和回归验证均已完成。
• 目标： 插件实际领取任务后 10 分钟无最终结果自动失败；历史任务超过 30 分钟无处理进展退出活动队列，避免单条卡死任务永久阻塞组织级 ERP 槽位。
• 安全边界： 不自动重试可能已跨过 ERP 写入边界的任务；历史任务只做失败标记和队列释放，保留回查证据；本轮未主动发起 ERP 写入。

实施清单

• 明确并实现单任务 10 分钟结果超时与租约释放。
• 明确并实现历史任务 30 分钟维护超时与活动执行槽解耦。
• 为 no_erp_write 与可能已写入 ERP 两类结果保留不同安全路径。
• 增加控制面、插件和队列回归测试，覆盖幂等、断线和重复清理。
• 完成插件构建/版本同步及可恢复运行态清理；运行态检查未发现可清除任务，未删除不确定写入历史。
• 修复历史维护查询的 42P10 错误，并立即收口 15 条超过 30 分钟的 reconciliation_pending 任务。
• 运行项目规定的完整检查、测试和构建。

交付与运行态备注

• 控制面已按用户授权优雅重启，当前进程 PID 93460；两个 AgentBus 会话均已 session_ready，重启后未再出现 error_42p10 或回调上下文错误。
• 历史 15 条任务已自动失败并释放执行队列；当前数据库中超过 30 分钟仍处于 reconciliation_pending 的任务为 0 条，未删除任何回查证据。
• 当前 Chrome 运行时清理入口已执行并返回 0 个运行中超时、0 个孤儿任务、0 个被清除的当前指针；此前浏览器心跳报告扩展版本 0.5.132 且状态 connected，当前发布插件已递增到 0.5.133。
• 用户本次测试任务已由持久化结果记录为 completed，AgentBus accepted/result 均为 delivered；该任务自身结果记录 write_attempted=true，不将其误报为“未写 ERP”。
• 当前发布插件为 0.5.133，发布清单和版本化 ZIP 已同步；不确定是否已跨 ERP 写入边界的历史任务只退出活动槽，不自动重试或删除证据。

已确认决策

1. 单任务 10 分钟计时从插件实际领取并开始执行起算，不从 AgentBus“已受理”或服务端排队起算。
2. 历史维护超时为 30 分钟；超时任务不自动重跑。
3. 明确未写 ERP 的任务可失败并释放执行槽；可能已写入 ERP 的任务保留回查保护，但不能永久占用新任务活动槽。

错误记录

• 首次追加本阶段计划时使用了不存在的旧上下文行，补丁未应用；随后改为以文件末尾现有内容为锚点，未产生部分修改。
• 本轮首次追加团队文件回传计划时沿用了已压缩文件中的错误锚点，补丁未应用；随后改用实际文件末尾锚点，未产生部分修改。

当前会话任务：团队文件源文件回传 AgentBus 来源渠道

• 状态： 实现已完成；功能验证通过，仓库卫生仍保留用户既有阻断。
• 目标： confirmation_export 任务成功取得 ERP 源文件后，将原始文件作为最终返回消息的一部分，沿任务记录的 AgentBus 来源渠道回传；现有平台附件保存与后台鉴权下载能力继续保留。
• 已确认事实： 当前链路能读取并保存源文件，但 AgentBus 入站只使用 payload.text，已有记录显示带附件的入站探测被受理而最终回执没有附件。
• 已确认决策： AgentBus 最终回执直接携带原始文件附件，同时保留现有下载地址作为兜底；需要限制消息大小、避免日志泄露，并兼容 OSS/数据库两种存储。

实施阶段

• 按治理规则读取项目入口、规划记忆、业务登记表及 confirmation_export 相关契约。
• 核对 AgentBus 当前出站帧、附件模型、来源渠道路由和回归测试边界。
• 定位附件“已落库但下载消失”的交付断点：后台地址需要登录且为相对路径；durable result 未投影顶层附件；当前结果文件名存在 UTF-8/Latin-1 乱码。
• 实现源文件回传，并同步契约/测试/配置（direct/durable 附件、大小上限、OSS 取件、文件名修复已落源码）。
• 执行项目规定的检查、测试和构建；check、控制面 53/53、build、git diff --check 通过，check:repo/legacy 仅受既有 .DS_Store 与 DOCX 哈希漂移阻断；不执行真实 ERP 写入、部署或外部发送。

本轮错误记录

• 首次合并附件修复补丁因当前工作区已有 getContent/OSS 回传骨架，锚点与实际源码不一致，补丁未应用；随后按实际函数边界拆分为小补丁，未产生部分修改。
• 类型检查首次复跑发现 attachmentMetadataFrame 的新增可选参数与 Array.map 的索引参数不兼容；改为显式箭头回调，未产生运行时失败。
• 全量门槛首次复跑发现根 .DS_Store、既有发布 DOCX 哈希漂移和 findings.md 超限；已将完整 findings 冻结到 archive/project-history/2026-08-17/findings-pre-compression-attachment.md 并压缩活动 findings，.DS_Store 与 DOCX 保留为用户既有阻断，未修改。
• 一次跨文件补丁误以为 getContent 位于 task-service.ts，未应用且未产生部分修改；随后按实际 artifact-store.ts 边界拆分补丁并通过 check。

当前会话追加：截图复核与运行态收口

• 状态： 控制面已按用户授权重启并恢复；历史文件名兼容修复和回归已完成，未发送外部消息。
• 证据： 截图显示 confirmation_export 仍只有文字回执且文件名乱码；当前控制面 PID 2545 于 21:44 启动，附件回传源码于 22:19 修改、.build 于 22:23 生成，运行进程未加载本次修复。
• 兼容性事实： 已新增共享读取时文件名纠正；新旧 artifact 在成功回执、AgentBus 附件和任务元数据路径统一修复，数据库原始记录与文件字节不变。

追加阶段

• 将截图内容视为问题证据，未把图片中的聊天文本当成操作指令。
• 只读核对源码、构建时间、控制面进程和附件读取路径。
• 用户授权后重启控制面并验证 /health/ready、/api/status 均显示 AgentBus connected=true、session_ready=true。
• 增加读取时的旧文件名修复并完成回归验证；控制面测试 54/54 通过。

追加验证

• check、build、git diff --check 通过；check:repo/test:legacy 仍仅受既有 .DS_Store 与 DOCX 发布哈希漂移阻断。
• 控制面第二次重启后的 PID 为 24031，未执行 ERP 写入、部署或外部发送。

当前会话追加：平台下载入口与渠道附件缺失复核

• 状态： 控制面与平台修复已完成；外部渠道是否渲染附件仍待上游协议确认。截图显示成功文字中有文件名，但 AgentBus 渠道未出现文件对象，平台“后台附件”区域也没有下载按钮。
• 已定位的前端缺口： LianSyn-platform/app.js 的 renderTaskArtifacts() 只从 task.result.report.artifacts[*].download_url 生成按钮，没有使用成功回执中的 success_receipt.receipt.reply_attachments 和 important_message.attachments 作为详情页兜底。
• 完成项： 已核对任务详情 API 实际返回的 result、success_receipt 和附件 URL，修复平台显示链路，并用本地契约测试验证 AgentBus 直接/持久化载荷仍携带源文件内容。

当前复核结果

• 已在登录态平台页面核对真实任务 TASK-20260817144147-1MYf84I：后台附件区域已显示 LLW-261202A-A 客户确认书.doc 和“下载文件”按钮，链接含该任务的 artifact ID。
• 该任务 API 详情同时返回完整 result.report.artifacts、success_receipt.receipt.reply_attachments 和 important_message.attachments；平台兜底修复已在页面生效。
• 控制面本地 direct/durable 契约测试曾确认旧实现会投影 payload.attachments[*].content_base64；更新后的微信适配器文档已提供权威 URL-only 附件协议，当前实现已切换为 HTTPS url 元数据。
• AgentBus 渠道实际渲染仍缺少上游可观测回执；当前不发送新的外部探测消息，保留“控制面已生成附件载荷、渠道适配器是否支持/渲染待上游确认”的边界。

当前会话追加：按微信渠道适配器协议切换 URL-only 附件

• 状态： 已完成；代码、运行配置和控制面重启均已完成，未发送真实外部文件测试。
• 协议事实： task.progress/task.result 使用 payload.attachments 元数据，附件必须提供 HTTPS url；适配器按白名单下载并顺序发送，AgentBus 不应携带 base64。
• 将 direct/durable 出站附件从 download_url/content_base64 改为 id、name、content_type、size、inline: false、HTTPS url 和可选 sha256。
• 拒绝 HTTP、数据库后台鉴权 URL 和无可访问 URL 的外部附件，保留平台后台下载能力。
• 同步 AgentBus 契约、控制面 README、环境示例和回归测试。
• 运行源码检查、控制面 54/54、构建和 git diff --check；check:repo/test:legacy 仍仅受既有 .DS_Store 与 DOCX 哈希漂移阻断。
• 在实际运行环境启用 OSS 配置并重启控制面；健康检查通过，重新生成团队文件任务和真实外部文件测试仍待用户安排。

当前会话追加：文件获取统一转 PDF

• 状态： 已完成；用户确认仅 confirmation_export 转 PDF，转换失败回退源文件。
• 已定位范围： 当前登记的文件获取 action 为 confirmation_export；现有链路保存 ERP 原始文件，converted=false，未接入转换器。
• 已确认决策： 转换失败时保留并回传源文件；不改变其他任务附件。
• 核对 PDF 转换运行时、部署依赖、源格式和附件回传字段。
• 实现平台 PDF 转换、超时/无效输出回退源文件、测试并同步容器配置。
• 重建确认导出 Skill/DOCX/扩展发布物，完成仓库卫生、全量测试、构建和渲染检查。
• 按用户授权重启面板并验证运行态转换器与 AgentBus 健康状态。
• 运行态： 面板已重启；/health/ready 返回数据库、Schema 和 3 个 AgentBus 渠道均正常且 session_ready=true。

当前会话追加：AgentBus 渠道状态同步修复

• 状态： 已完成；用户确认修复并重启。
• 防止旧进程停机回写覆盖新进程的 AgentBus 渠道状态。
• /api/channels 合并实时 listener 状态，避免面板显示陈旧的“已停用”。
• 增加会话 epoch 防护和回归测试；控制面 59/59、类型检查、构建通过。
• 运行态： 当前 3 个启用渠道均为 enabled=true、connected=true、session_ready=true；重复兼容渠道保持管理员停用状态。