198 lines
16 KiB
Markdown
198 lines
16 KiB
Markdown
# 项目文件治理计划
|
||
|
||
## 当前任务：AgentBus 通讯测试（已完成）
|
||
|
||
- **目标：** 检查面板与 AgentBus 的实时双向通信，不主动发送新测试消息。
|
||
- **结果：** `health/ready`、`api/status` 正常；4 个渠道均 `connected/session_ready`；日志见 4 次握手、1 次入站、2 次出站、0 次断线或本地发送失败。
|
||
|
||
## 2026-08-20 — ERP 会话待机保活（已完成）
|
||
|
||
- **目标：** 在已有且允许访问的 ERP 标签页中，以固定周期发送带 Cookie 的只读请求，减少服务端因长期无请求而失效；不刷新页面、不新开标签、不干扰执行中的业务任务。
|
||
|
||
### 阶段
|
||
|
||
- [x] 设计并实现 `chrome.alarms` 定时器、现有标签页限定、执行中跳过、会话响应检测、状态记录和用户开关。
|
||
- [x] 增加定向静态回归，递增扩展版本并同步平台最低版本、mapping 和源码版本断言。
|
||
- [x] 生成版本化 ZIP/发布清单并运行项目规定完整验证。
|
||
|
||
### 当前边界与决策
|
||
|
||
- 保活只作用于 `https://lwlt.hisy.cc` 已存在标签页，默认约 5 分钟一次，首次延迟约 1 分钟；电脑/浏览器休眠导致的 alarm 延迟不宣称可覆盖。
|
||
- 页面侧使用 `GET /System/Mainlt.asp`、`credentials=include`、`cache=no-store`；不使用 `tabs.reload()`，不调用任何 ERP 保存接口，不改变 DOM 或业务 operation。
|
||
- `erpAutomationEnabled=false`、用户关闭“ERP 待机保活”、无 ERP 标签页、权限缺失或插件有执行中任务时跳过；失败只记录状态并在插件面板提示，不自动登录或绕过权限。
|
||
- `archive/` 只保存旧发布物，当前源码和 `dist/release-manifest.json` 为活动规则与交付入口。
|
||
|
||
## 当前任务：AgentBus 无受理/处理中/结果消息但任务成功的链路诊断
|
||
|
||
- **状态：** 诊断完成；只读检查，不修改业务源码，不重试任务，不发送外部消息，不重启或部署。
|
||
- **目标：** 从任务创建、状态事件、回复路由、AgentBus listener 和持久化 outbox 逐段确认为什么任务可成功而三类 AgentBus 消息均未到达，并区分设计行为、运行时配置/连接问题与代码缺口。
|
||
|
||
### 阶段
|
||
|
||
- [x] 读取治理规则、活动 planning 文件和当前工作区状态，确认不覆盖既有未提交改动。
|
||
- [x] 通过业务登记定位 AgentBus/当前业务契约，读取相关 Skill、Schema、mapping 和实现代码。
|
||
- [x] 追踪 accepted、processing、result 三类事件的生成、路由、持久化和发送条件，核对测试覆盖。
|
||
- [x] 结合现有日志/证据边界收敛根因；如缺少任务 ID 或运行时渠道快照，明确需要的最小补充证据。
|
||
- [x] 更新计划、发现和进度并给出只读诊断结论；不执行外部发送或任务重试。
|
||
|
||
### 当前边界与决策
|
||
|
||
- “任务成功”与“AgentBus 消息送达”分开判断；不能仅凭任务终态推断渠道发送成功。
|
||
- 不读取 `.env` 或其他秘密配置，不主动访问/发送 AgentBus，不重启控制面；仅检查非秘密配置样例、源码、测试和已有证据。
|
||
- `archive/` 只作追溯，当前源码、契约和活动测试优先。
|
||
|
||
### 错误记录
|
||
|
||
| 错误 | 处理 |
|
||
|---|---|
|
||
| 登记表链接的 `agent设计规范/businesses/confirmation_export.md` 不存在 | 不重复查找该路径；改用当前登记表、`business-behavior-registry.md`、`lwlt-confirmation` Skill、AgentBus 契约、Schema/mapping 与控制面实现核对 |
|
||
| 首次合并计划更新时把 findings 内容误放到 `task_plan.md` 匹配块，补丁未应用 | 已确认没有文件被修改；拆分为仅更新阶段状态和错误记录的补丁，不重复原匹配方式 |
|
||
| 直接调用 bundled Node 的 `--run check:repo` 时其脚本子进程找不到 `node` | 改用 bundled Node 与其 `node/bin`、fallback `bin` 一起加入本次命令的 `PATH`；不修改环境文件或持久化 shell 配置 |
|
||
|
||
### 诊断结论
|
||
|
||
- `processing` 消息不是当前协议的一部分；AgentBus 只发送一次 `task.progress(status=accepted)` 和一次终态 `task.result`。
|
||
- 任务成功与 AgentBus 送达解耦。手工来源或没有 `channel_id`/入站 frame 路由的任务不会生成 AgentBus delivery；AgentBus 入站任务则必须经过 accepted durable delivery，之后才会生成 result delivery。
|
||
- 若该任务确实来自 AgentBus 且 accepted/result 都没有，根因只能继续在任务发生时的 `source/channel_id`、`agentbus_deliveries` 状态或 listener 日志中区分；当前没有该任务 ID，不能把历史断点唯一归因给某个渠道或 WebSocket 错误。
|
||
- 本次只读探针显示当前 4 个启用渠道均 `connected=true`、`session_ready=true`；这是当前状态，不是该历史任务发生时的证据。
|
||
- 最新现场日志已定位到 `TASK-20260819102429-R13bn8w`：入站为 AgentBus，accepted 与 completed result 均出现 `outbound_durable_delivery_sent`，且 AgentBus 服务端随后返回 `accepted`/`delivered` 确认帧；控制面未出现该任务对应的发送失败或断线。
|
||
- 因此本轮诊断边界已从控制面收敛到 AgentBus 网关向微信适配器/会话的下游投递或展示；不改本地发送逻辑，不重试外部消息。
|
||
|
||
## 当前任务：confirmation_export Chrome host 权限阻断修复
|
||
|
||
- **状态：** 修复完成；两次用户任务均未写入 ERP，未重试、未部署。
|
||
- **目标：** 找出 `Cannot access contents of the page. Extension manifest must request permission to access the respective host.` 的实际触发路径，修复 `confirmation_export` 的受控浏览器执行并保持未知 host fail-closed；补充回归门禁、递增扩展版本并同步版本化制品。
|
||
|
||
### 阶段
|
||
|
||
- [x] 读取两份日志、活动 planning 文件、业务登记和当前工作区状态，确认两次失败均为同一权限错误。
|
||
- [x] 核对 Chrome manifest、ERP tab/redirect/frame 注入路径和当前测试覆盖，确定最小修复边界。
|
||
- [x] 实施权限/注入修复及回归测试；同步扩展版本、mapping、平台最低版本、ZIP 和发布清单。
|
||
- [x] 运行项目规定验证并记录结果；不执行真实 ERP 重试、写入、外部发送、重启或部署。
|
||
|
||
### 当前边界与决策
|
||
|
||
- 只处理 `confirmation_export` 浏览器执行前门禁与扩展发布同步；不重试用户给出的两个任务。
|
||
- 只允许当前登记的 ERP host/经验证重定向 host；不为规避错误而开放任意网站权限。
|
||
- 无法唯一确认页面 host、frame 或扩展版本时继续阻断，不伪造导出成功。
|
||
|
||
### 错误记录
|
||
|
||
| 错误 | 处理 |
|
||
|---|---|
|
||
| `agent设计规范/businesses/confirmation_export.md` 不存在，登记表中的链接为悬空入口 | 改用 `business-behavior-registry.md`、`lwlt-confirmation` Skill、Schema、mapping 和实现源码继续核对，并保留该治理缺口记录 |
|
||
| 对 `https://lwlt.hisy.cc/System/Mainlt.asp` 的只读 HEAD/重定向探测连接超时 | 不重复外部探测；转为基于本地 manifest、注入路径和测试夹具定位，真实 host 仍以浏览器运行时明确拒绝为准 |
|
||
| 默认 shell 没有 `node` 命令，首次语法检查未启动 | 使用 workspace bundled Node 绝对路径重跑；不修改 PATH 或环境文件 |
|
||
|
||
### 当前实现摘要
|
||
|
||
- `background.js`：`chrome.permissions.contains` 前检、批准 ERP origin/tab 复核、同源导航竞态一次重试、脚本注入错误结构化并 fail-closed。
|
||
- `LianSyn-platform/app.js`：桥接状态展示 ERP 页面权限；权限不可用时不再自动 claim/handoff 新任务。
|
||
- 发布：扩展 `0.5.137`，ZIP SHA-256 `6c00c6e8240fad80bc8fbe8e932dfaf22ad32e494c957717c2d7537785f09fd5`；`check:repo` 9/9 已通过。
|
||
|
||
### 最终验证
|
||
|
||
- `check`、`test:control-plane` 66/66、`test:legacy` 215/215、`build`、`git diff --check`：通过。
|
||
- 定向 operation plan：40/40；生命周期契约：47/47；`check:repo`：9/9。
|
||
- 未执行真实 ERP 任务重试、ERP 写入、外部发送、控制面重启或部署；浏览器 live host 因只读网络探测超时未进行实时复测。
|
||
|
||
## 当前任务：visitor-list XLSX 转换失败修复
|
||
|
||
- **状态：** 修复完成；未重试该 ERP 任务、未写入 ERP、未向 AgentBus 外发原始 XLS。
|
||
- **目标：** 找出 `visitor_xlsx_conversion_failed:conversion_failed` 的实际根因，确保 HTML-in-XLS 能生成可校验的真实 XLSX；转换失败时继续保持 fail-closed，不回传手机无法打开的原始 XLS。
|
||
|
||
### 阶段
|
||
|
||
- [x] 读取用户日志、活动 planning 文件和当前工作区状态，确认最终状态为 `blocked`。
|
||
- [x] 核对 `convertDocumentToXlsx()`、调用方和 LibreOffice 运行环境，使用脱敏 fixture 重现失败。
|
||
- [x] 实施最小修复并增加覆盖转换失败/成功与 AgentBus 可见性门禁的回归测试。
|
||
- [x] 运行项目规定验证；在用户已授权范围内重启面板并验证 live/ready 与 AgentBus 状态。
|
||
|
||
### 当前边界
|
||
|
||
- 只处理文件转换与交付契约；不重试原任务，不提交 ERP 写入，不发送外部业务消息。
|
||
- 原始 ERP `.xls` 只能作为平台源归档；游客信息对 AgentBus/微信仍只允许真实 `.xlsx`。
|
||
|
||
### 错误记录
|
||
|
||
| 错误 | 处理 |
|
||
|---|---|
|
||
| 首次脱敏 LibreOffice 复现脚本在 bundled Node 24 下同时使用 CommonJS `require` 与顶层 `await`，触发 `ERR_AMBIGUOUS_MODULE_SYNTAX`，尚未执行转换 | 改用纯 ESM `import` 形式重跑，不重复该脚本形态 |
|
||
| bundled macOS LibreOffice 将 HTML 输入按 Writer/Web 文档加载后直接导出 Calc XLSX 时收到 `SIGABRT`，输出目录只留下锁文件和临时文件 | 先比较保留 `.xls` 扩展名、HTML→ODS→XLSX 等不同导入路径；不把崩溃当作可交付结果 |
|
||
|
||
## 当前任务：散拼母团创建写后回查假阴性修复
|
||
|
||
- **状态：** 修复与版本化交付完成；不重提 ERP 创建请求，未执行真实 ERP 写入、重试或部署。用户授权后已重启控制面并通过健康检查。
|
||
- **目标：** 当 `shared_plan_create` 已收到 ERP 成功响应但精确团号回查暂未命中时，通过清空列表筛选、有限只读重试和按日期兜底回查正确收敛结果，避免把真实成功误报为 `erp_result_uncertain`。
|
||
|
||
### 已确认决策
|
||
|
||
- 任一 ERP 返回团号未命中即进入恢复回查，不再只按“返回团号数少于日期数”判断。
|
||
- 每次精确回查显式清空客户、产品、领队和状态等非目标筛选；允许有限次数延迟重查。
|
||
- 精确回查仍未完整命中时，按请求日期逐日唯一核验；任何歧义或缺失继续保持 `execution_uncertain`。
|
||
- 全过程只读回查，禁止再次调用 `SubmitInfoForm()` 或 `POST /System/DAT/plan.asp`。
|
||
|
||
### 阶段
|
||
|
||
- [x] 读取项目约束、活动 planning 文件、业务登记、业务页、Skill、Schema、mapping、日志与当前实现。
|
||
- [x] 实现精确团号回查的筛选清理与有限只读重试。
|
||
- [x] 修正按日期兜底触发条件并保留严格唯一门禁。
|
||
- [x] 增加回归测试，覆盖“ERP 返回完整团号但首次列表回查为空”的成功收敛与持续缺失阻断。
|
||
- [x] 递增扩展版本，同步平台最低版本、mapping、版本化 ZIP 和发布清单。
|
||
- [x] 运行定向测试及项目规定完整验证并记录结果。
|
||
|
||
### 错误记录
|
||
|
||
| 错误 | 处理 |
|
||
|---|---|
|
||
| 首次打包命令把扩展目录到项目 `dist/` 的相对路径写成 `../../../dist`，ZIP 未创建 | 已确认正确路径为 `../../dist`；不复用错误命令，改用正确显式目标重新打包 |
|
||
| 完整验证首次运行在控制面测试 `confirmation export preserves visitor Excel while converting other types` 失败：测试桩未生成 `.xlsx` 输出 | 已确认该测试与控制面游客 XLSX 并行改动在本任务开始前已存在：当前转换器要求 `.xlsx`，测试桩仍只写 `team.pdf`。为保留未确认的游客交付策略，本轮不修改；其余控制面 60/60 通过 |
|
||
| legacy 全量测试发现一处转义正则仍断言旧扩展版本 `0.5.134` | 该断言属于本次版本同步范围；定位后改为 `0.5.135` 并重跑 legacy，不重复错误断言 |
|
||
| 最终哈希复核脚本在命令替换中直接调用 `node`，当前 shell PATH 未持久注入 bundled Node | `check:repo` 与 `git diff --check` 已先通过；哈希复核改用 bundled Node 绝对路径单独重跑，不重复 PATH 假设 |
|
||
|
||
### 最终验证
|
||
|
||
- `check:repo`：9/9 通过；`check`、`build`、`git diff --check`：通过。
|
||
- 定向回查：14/14；生命周期回查门禁：1/1；legacy：214/214。
|
||
- 控制面：60/61；唯一失败是本轮未改动的游客 XLSX 测试桩与其并行实现不一致。
|
||
- 控制面重启后：`/health/live`、`/health/ready`、数据库、Schema 和迁移均正常；4 个 AgentBus 渠道全部连接并完成 session-ready。未触发 ERP 任务重试。
|
||
|
||
## 当前任务：visitor-list AgentBus XLSX 交付
|
||
|
||
- **状态：** 已实施并完成定向回归；保留原始 ERP `.xls` 归档，生成真实 `.xlsx`，AgentBus/微信只返回 `.xlsx`。未写入 ERP、未重试、未重启、未部署。
|
||
- **目标：** 修复 HTML-in-XLS 在手机/微信上的兼容性，同时不丢失 ERP 原始源证据，并让 AgentBus 对游客信息只发送移动端可打开的 XLSX。
|
||
|
||
### 阶段
|
||
|
||
- [x] 读取治理规则、活动 planning 文件和工作区状态。
|
||
- [x] 从用户日志确认 `Visitor.xls` 的文件名、MIME、字节数和 SHA-256。
|
||
- [x] 对照历史 ERP 实时源响应证据确认游客名单是 HTML-in-XLS，而非标准 BIFF/OLE `.xls`。
|
||
- [x] 核对插件 `arrayBuffer`/base64、控制面 native 分支、OSS 写入和下载响应均保持源字节。
|
||
- [x] 用户确认“源 `.xls` 归档 + 真实 `.xlsx` 交付”，并明确 AgentBus 返回 XLSX。
|
||
- [x] 增加 XLSX 转换器、双附件元数据和 AgentBus/回执可见性过滤；转换失败时阻断原始 XLS 外部交付。
|
||
- [x] 增加转换器、任务准备、回执和 AgentBus 回归测试；同步当前 Skill、Schema、mapping、插件提示和运营模板。
|
||
- [x] 完成表格产物结构验证及项目门禁验证。
|
||
|
||
### 当前结论
|
||
|
||
- 用户日志中的源文件为 9,377 字节，声明 `application/vnd.ms-excel; Charset=UTF-8`，文件名为 `LW-260816Z-A Visitor.xls`。
|
||
- 历史实时采集记录显示 `/System/Business/orders_Visitor.asp` 返回 `application/vnd.ms-excel`，但首字节为 HTML 文档头，属于 HTML-in-XLS wrapper；桌面 Excel 可兼容解析，手机 Office/微信通常按扩展名与真实签名拒绝。
|
||
- 插件用 `response.arrayBuffer()` 读取并计算 SHA/base64；控制面 `visitor-list` 分支沿用同一字节、文件名和 MIME；OSS 设置附件 disposition，因此当前证据不支持传输过程损坏。
|
||
- 仅改扩展名或 MIME 不能修复；移动端兼容需要真实 `.xlsx`（保留表格语义）或 PDF。生成派生文件改变了此前“游客信息保持 ERP 原生 Excel”的外部交付约束；经用户确认后改为“原始 XLS 仅平台归档，AgentBus/微信只交付 XLSX”。
|
||
|
||
### 既已完成的相关实施
|
||
|
||
- `confirmation_export` 现按类型交付：`visitor-list` 保留源 XLS 并生成真实 XLSX，AgentBus/微信只返回 XLSX；其余类型继续转 PDF，转换失败回退源文件。
|
||
- 已同步控制面、Skill、输出契约、Schema、mapping、插件提示、测试、版本化 Skill/扩展 ZIP、运营 DOCX 和发布清单。
|
||
- 散拼子单导出二次查询已移除固定“收客中”过滤，仍保留母团/子单/`ddid`/`tid` 唯一核验。
|
||
|
||
### 最终验证
|
||
|
||
- `check:repo` 9/9、`check`、控制面 66/66、legacy 214/214、`build`、`git diff --check` 全部通过。
|
||
- `lwlt-confirmation` Skill 官方 `quick_validate.py` 通过；运营 DOCX 15 页逐页渲染检查通过；扩展 0.5.136 ZIP 与发布清单哈希通过。
|
||
|
||
### 归档与约束
|
||
|
||
- 本文件超限前的完整版本已冻结于 [visitor 移动端诊断前计划](archive/project-history/2026-08-18/task_plan-pre-compression-visitor-mobile-diagnosis.md)；更早快照见同目录 README。
|
||
- 保留工作区既有未提交改动；不读取、复制或输出秘密配置；真实 ERP 写入、外部发送、重启和部署需用户另行明确授权。
|