chore(task): archive chrome-message-response-compat

2026-09-17 13:22:11 +08:00 · 2026-09-17 02:07:01 +08:00
parent a92e1d2421
commit 0cf88a21f5
4 changed files with 77 additions and 0 deletions
@@ -0,0 +1,4 @@
+{"file":".trellis/spec/chrome-extension/frontend/quality-guidelines.md","reason":"Focused test, strict typecheck, build, and formatting expectations for the extension package."}
+{"file":".trellis/spec/project/architecture.md","reason":"Review ownership boundaries and ensure the adapter does not duplicate configuration logic."}
+{"file":".trellis/spec/project/async-state-boundaries.md","reason":"Review that callback adaptation preserves queue, error, and one-response semantics."}
+{"file":".trellis/spec/chrome-extension/frontend/type-safety.md","reason":"Review the Chrome listener signature and external-message boundary types under strict TypeScript."}
@@ -0,0 +1,4 @@
+{"file":".trellis/spec/chrome-extension/frontend/index.md","reason":"Chrome extension package boundary, required pre-change reading, and package validation baseline."}
+{"file":".trellis/spec/project/architecture.md","reason":"Entry-adapter ownership and source-layout rules for changing the Service Worker composition root."}
+{"file":".trellis/spec/project/async-state-boundaries.md","reason":"Preserve the existing async configuration queue and guarantee one callback response per request."}
+{"file":".trellis/spec/chrome-extension/frontend/type-safety.md","reason":"Chrome API boundary typing and single-owner message contract rules."}
@@ -0,0 +1,43 @@
+# 兼容低版本 Chrome 的 async onMessage 响应
+
+## Goal
+
+将 Service Worker 接收 Popup 配置消息的 `chrome.runtime.onMessage` 入口改为 Chrome 旧版可用的 callback 响应模式，使配置读取、保存和清除不依赖 Promise-returning message listener，同时保持现有配置、授权边界、队列和错误码语义不变。
+
+## Confirmed Facts
+
+- `apps/chrome-extension/src/service-worker-entry.ts:203` 的 `handleConfigurationMessage` 是返回 `Promise<OneTalkConfigMessageResponse>` 的异步业务处理函数，且在 `:284` 被直接注册为 `chrome.runtime.onMessage` listener。
+- 该处理函数服务 `onetalk.config.get`、`onetalk.config.save` 和 `onetalk.config.clear`，并保留 Popup sender 校验、初始化等待、串行配置队列、存储错误映射和稳定的 `OneTalkConfigMessageResponse`。
+- `apps/chrome-extension/test/service-worker-entry-config.test.js:75` 目前直接 `await listener(...)`，未模拟 `sendResponse` 或断言 listener 返回 `true`；save、clear 和回调错误路径也没有入口层测试。
+- 页面 `port.onMessage` 长连接，以及 Popup 侧只接收状态通知的 `runtime.onMessage` listener，不是 Promise-returning 配置响应入口，不属于本次改造。
+- `apps/chrome-extension/manifest.template.json` 未声明 `minimum_chrome_version`，但 Popup 使用 MAIN world scripting；本任务不改变产品的整体最低 Chrome 支持线。
+
+## Requirements
+
+1. Service Worker 的 Chrome runtime message listener 必须接收 `sendResponse`，并同步返回字面值 `true`，以保持异步响应通道对旧版 Chrome 有效。
+2. 可以保留现有异步配置处理逻辑，但必须由适配器在 Promise 完成后调用 `sendResponse`，且每次请求最多响应一次。
+3. 保持现有消息校验、Popup sender 拒绝、get/save/clear 分支、配置串行化、初始化等待、稳定错误码和响应字段不变。
+4. 不通过增加隐式 fallback、修改业务状态机或新增第二套配置处理逻辑来实现兼容。
+5. 仅更新必要的 Service Worker 类型声明、事件适配代码和对应测试；不在本任务中新增环境检查功能、`minimum_chrome_version`、无痕模式策略或隐私权限。
+
+## Acceptance Criteria
+
+- [ ] Service Worker 不再把返回 Promise 的业务函数直接注册为 `chrome.runtime.onMessage` listener；listener 返回字面值 `true` 并通过 `sendResponse` 返回结果。
+- [ ] 已授权 Popup 的 `config.get`、`config.save`、`config.clear` 仍返回原有安全响应；未授权 sender 仍返回 `sender_not_allowed`，无效配置仍返回 `invalid_configuration`。
+- [ ] 异步初始化、配置队列和已知异常路径均能完成 callback 响应，且没有重复响应或未处理 Promise rejection。
+- [ ] 回归测试覆盖 callback 调用、`return true`、成功响应、拒绝响应和异步错误/存储错误路径。
+- [ ] `pnpm --filter @trade-message-center/chrome-extension test`、`pnpm --filter @trade-message-center/chrome-extension typecheck` 和受影响包 build 通过；若无法运行真实旧版 Chrome，明确记录为未验证边界。
+- [ ] 变更 diff 仅包含预期的 Service Worker 入口及其配置消息测试，不改变页面 Port 消息、Bright 协议或服务端行为。
+
+## Out of Scope
+
+- 插件运行环境检查 UI 或诊断协议。
+- 修改 Manifest 的 `minimum_chrome_version` 或权限声明。
+- 无痕窗口支持、Chrome 全局隐私设置、第三方 Cookie 或 `chrome.privacy` 检查。
+- Bright WebSocket、OneTalk 页面桥、同步引擎、服务端和数据库改造。
+
+## Key Decisions
+
+- 保留现有异步配置业务处理作为唯一的行为实现；仅在 Chrome 事件边界以 `message, sender, sendResponse` 适配，并在其 Promise 结算后调用一次 `sendResponse`。
+- listener 必须同步返回字面值 `true`，不以 Promise 返回值承载响应。
+- 不承诺特定最低 Chrome 版本：这次只解除该 listener 的兼容性约束，其他 Manifest 与 API 依赖保持不变。
@@ -0,0 +1,26 @@
+{
+  "id": "chrome-message-response-compat",
+  "name": "chrome-message-response-compat",
+  "title": "兼容低版本 Chrome 的 async onMessage 响应",
+  "description": "将 Service Worker Popup 配置消息改为 callback + return true，兼容低版本 Chrome，保持现有配置和错误语义",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "ybf",
+  "assignee": "ybf",
+  "createdAt": "2026-09-17",
+  "completedAt": "2026-09-17",
+  "branch": "tree2",
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}