📄 修正架构/测试/i18n 文档过期事实并解决跨文档政策冲突#1616
Merged
CodFrm merged 13 commits intoJul 20, 2026
Merged
Conversation
- AGENTS.md/copilot-instructions.md/architecture*.md: 用 Repo<T>/DAO<T>/OPFSRepo 后端分类
替换"新实体一律 Repo<T>"的过期普遍规则；架构速览补充 agent/、extension/、queue.ts；
新增 docs/references/architecture-agent.md 覆盖 Agent 子系统（工具注册表、LLM 工具循环、
后台会话/子代理/定时任务生命周期、存储后端、跨 context 委派边界）
- architecture-build.md: rspack entry 补上 common、json.worker
- architecture-gm-api.md: 明确 sendMessage vs connect 的选择依据与 DOM/linter 落点路径
- develop.md: 记录 toast.ts 对 no-restricted-imports 的完整豁免（同时覆盖 Sonner 与 Radix）
- verification.md: 补充"何时可跳过本指南"、按比例的前置检查、TDD 例外与 bug 复现的同步、
可见的 report.md 创建步骤、双主题验证注意事项
- verification-debugging.md: 补充 Firefox 无独立 Offscreen 页面的调试提示
- design-patterns.md: 移除过期的固定 locale 数与未经测量的百分比断言
- translation.md/src/locales/README.md: 记录 i18n-usage.test.ts 的真实扫描范围与盲区；
修正 i8next 拼写；翻译工作流去重指向 translation.md
- DOC-MAINTENANCE.md: 扩大到全部 tracked agent/contributor Markdown，新增
baseline/working-diff/final-tree 区分、政策一致性检查、隐私扫描、批量编辑建议
- packages/{message,filesystem,cloudscript}/README.md: 修正过期/模糊的实现描述
- 删除未被引用且已过期的 src/pages/options/routes/Setting/Setting/i18nKeys.md 迁移快照
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This was referenced Jul 19, 2026
Collaborator
Author
|
回应 PR review (scriptscat#1616 review comment)： - .github/copilot-instructions.md: 缩减为纯 router + Copilot 专属规则（中文 review、 全量 diff review），共享架构/命令/测试内容改为链接 AGENTS.md，消除与常驻文档的重复 - AGENTS.md: 精简 Service & Data Layers 与 SOLID 条目的内联细节，改为更短的指针链接， 降低常驻文件的 token 增长 - docs/develop.md: 修正 toast.ts override 的措辞——只有 Sonner 例外是有意的，Radix 限制仍是约定但当前未被 harness 覆盖，不应读作"允许导入 Radix 单包" - docs/references/architecture-agent.md: - 修正三处错误 class 名（ChatService、AgentTaskService、CompactService， 而非 AgentChatService/TaskService/AgentCompactService） - 修正 retry 排除条件的精确描述（只排除 400/401/403/404，不是全部 4xx） - 修正导航实现归属（chrome.tabs，在 dom.ts 中，与 trusted 模式无关）并澄清 dom_cdp.ts 是 dom.ts 调用的 helper 而非独立服务 - 修正测试覆盖声称，改为要求现场核对 test 清单而非假设完整覆盖 - docs/references/architecture-data.md: 删除重复的 `Repo<T>` heading - docs/DOC-MAINTENANCE.md: link-integrity 脚本改用 `git ls-files '*.md'` 动态发现， 而不是遗漏 .github/package README 与新增 reference 的固定列表；架构 owner 行补上 architecture-agent.md - docs/README.md: 索引补上 architecture-agent.md - docs/references/develop-testing.md: 删除不可审计的 "~15%" 性能数字，改为要求 同环境实测 - packages/cloudscript/README.md: 修正导出包并非解压即可运行——package.json 声明了 外部依赖 scriptcat-nodejs，需要先 npm install Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in d6f3329 (pushed):
未改动项：无（全部 8 条均已处理）。 |
Collaborator
Author
|
补充：结合 #1603 中 @CodFrm 提到 Copilot 使用较少的情况，本 PR 也精简了 相关讨论：#1603 (comment) |
Collaborator
Author
|
结论：建议继续修改。最新提交已解决前一轮大部分问题，但仍有 3 项中等优先级问题；其中两项会直接误导 agents 执行。
建议仅修正上述三项，并在最终 SHA 再跑 link checker、重读 PR body；其他已修部分应保留。 |
回应 PR review 第二轮 (issuecomment-5016140703)： - architecture-agent.md: screenshot() 不受 trusted 选项控制（selector 截图/后台 tab 优先用 CDP，前台 tab 用 captureVisibleTab）；tab monitoring 始终走 CDP，没有 非 CDP 路径；只有 click/fill 真正按 trusted 分支。逐条核对 dom.ts 后重写该段， 不再把四类动作统一套进 default/trusted 二选一模型 - DOC-MAINTENANCE.md: link-integrity 脚本的排除模式补上 mailto: 与 app:（原来只排除 https?:/#，导致 3 处合法的 mailto: 链接被误报 BROKEN），并让 fenced-block 剔除同时 处理 ``` 与 ~~~；已验证修正后跑出 0 条 BROKEN，且对手动注入的无效链接仍能正确报错 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in dc5cf98 (pushed), plus a PR-body fix:
最终树 ref： |
Collaborator
Author
|
结论：
验证结果：
建议保留其他修正，仅处理上述两项。 |
回应 PR review 第三轮 (issuecomment-5016202376)：
- docs/architecture.md: "A new service" recipe 不再规定统一 `Group + IMessageQueue +
DAOs` constructor；改为先判断 context/Agent/cross-cutting 类别，再链接
architecture-services.md#adding-a-service 的决策路径
- docs/references/architecture-services.md:
- 修正遗漏的错误 class 名（`ChatService`、`AgentTaskService`，而非
`AgentChatService`/`TaskService`——上一轮只改了 architecture-agent.md，
漏改本文件里的同一处引用）
- 明确 context services 的依赖集合本身也会随服务变化（ResourceService 只需
(Group, mq)，PopupService 需要五个参数），"Group + IMessageQueue + DAOs"
是构造器注入原则的简写，不是固定参数清单
已核对 `git grep` 确认仓库内不再有 `AgentChatService`/`AgentCompactService`/裸
`TaskService` 的残留引用。
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in 70c5466 (pushed), plus a PR-body fix:
最终树 ref： |
Collaborator
Author
|
回应 PR review 第四轮 (issuecomment-5016264308)： architecture-services.md 把 context service 描述成统一的 "pure DI"、"never new internally"、"no work in constructor"，但 ResourceService 会以字段初始化器内部 创建 ResourceDAO 并在 constructor body 里做 logger/cache 初始化；SubscribeService 同样内部创建 SubscribeDAO 与 ScriptDAO。三处绝对表述改为：共享/外部拥有的 collaborator 通常经 constructor 注入；service 本地专用的 DAO/helper 是否内部 `new` 因 service 而异（举 ResourceService/SubscribeService 为反例）；init() 用于 handler 注册、跨 service 订阅及依赖完整 object graph 的 late wiring，而非"constructor 不能做任何事"。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in 7d3e6da (pushed):
最终树 ref： |
cyfung1031
added
P0
cyfung1031
commented
Jul 19, 2026
cyfung1031
left a comment
cyfung1031
left a comment
Collaborator
Author
There was a problem hiding this comment.
已对 docs/references/architecture-services.md 做了多轮事实复核（目录/职责、构造与依赖、组合根、测试替身、跨 context 生命周期）。当前仍有会直接误导贡献者的事实问题：
src/app/service/queue.ts被误写成MessageQueuewiring，实际仅包含消息 payload/type；实现和实例化在别处。- 文档推导的“跨 service 使用的 DAO 必须注入并共享同一实例”并非现有 invariant：
ScriptService与SubscribeService各自构造SubscribeDAO，后者也自建ScriptDAO。 MockMessage实现的是Messagetransport，不是IMessageQueue；测试中它用于构造Server/Group，传给 service 的 pub/sub 依赖仍是MessageQueue或应为单独的 fake。ScriptService示例写成空 constructor 且标注~20 more handlers；真实 constructor 有 logger/cache/ScriptUpdateCheck初始化，init()当前约有 32 个 handler。建议标注local setup omitted，并把数量改成不漂移的many more。ServiceWorkerManager不是给每个 service 都传Group + mq（如LogService、AgentService），应改成“按需创建 Group/传入 mq”。OffscreenManager、SandboxManager和 content/inject 的ScriptRuntime只是在 composition/handler registration 角色上相似，并不遵循同一依赖和初始化形状；ScriptRuntime还有contentInit()/externalMessage()。
目录、类名和文档相对链接本轮均已核对可解析。建议修正以上事实表述后再合并。
…例失真、manager 构造与跨 context 假设） 回应 PR review (#pullrequestreview-4731038208)： - queue.ts 只定义 MessageQueue payload/type（如 TInstallScript、TDeleteScript）， 不是 wiring 本身——实现在 packages/message/message_queue.ts，各入口/manager 自行 实例化。已修正两处（quick map 描述 + 目录树注释）。 - 删除"跨 service 使用的 DAO 必须注入并共享同一实例"的推导：ScriptService 与 SubscribeService 各自构造 SubscribeDAO，SubscribeService 也自建 ScriptDAO 而非复用 manager 传给其他 service 的 scriptDAO。改为"是否共享实例按 cache/lifetime/测试替换 需求个案决定，以最近邻实现为准"。 - 修正 MockMessage 误用：它实现的是 Message transport（用于测试中构造 Server/Group），不是 IMessageQueue 的替身；测试传给 service 的仍是真实 MessageQueue（个别方法用 vi.fn() mock）。 - ScriptService 示例 constructor 补注释说明并非空 body，handler 数量改成 "many more"（原 "~20 more" 与实际 31 个不符且会漂移），并提示用 git grep 现查。 - ServiceWorkerManager 的"每个 service 都拿 Group + 共享 mq"说法改正：LogService 无 mq，AgentService 也无 mq（拿 offscreenSend）；示例代码补上两者的真实构造签名。 - 删除 OffscreenManager/SandboxManager/ScriptRuntime "遵循同一 shape" 的说法，改为 说明三者只是角色相似(wire deps + register handlers)，构造/依赖形状互不相同， ScriptRuntime 还有其他两者没有的 contentInit()/externalMessage()。 以上均已对照实际源码（script.ts、resource.ts、subscribe.ts、log.ts、agent.ts、 offscreen/index.ts、sandbox/index.ts、content/script_runtime.ts、 packages/message/mock_message.ts、script.test.ts）逐条核实。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in 09fe390 (pushed):
最终树 ref： |
cyfung1031
commented
Jul 19, 2026
Collaborator
Author
There was a problem hiding this comment.
针对最新树 09fe390e 的复审。上一轮 6 项 finding 的对应修改均已落地；以下是最新文本仍残留的事实/一致性问题。
| 严重度 | Finding | 证据 | 为什么 | 最小修正 | 验证 |
|---|---|---|---|---|---|
| Medium | 主架构页仍保留已被 service reference 否定的统一 constructor / init() 模式。 |
observed — docs/architecture.md 仍称 services 都接收 Group、IMessageQueue、DAO 并在 init() 注册 handlers；而最新 architecture-services.md 已列出 LogService、AgentService 与其他 context 的反例。 |
两份 owner 文档给出相反 invariant；读者从主入口进入时仍会套用已知错误的统一模板。 | 把主架构页该 bullet 改为“service 依赖与 lifecycle 因 context/subsystem 而异；常见模式是 constructor wiring + explicit lifecycle hook”，并链接 service reference，不再枚举统一 Group/IMessageQueue/DAO 形状。 |
git grep -n "Services are constructor-injected|receive their.*Group|register message handlers in an.*init" -- docs AGENTS.md，逐条确认没有把示例重新写成全局规则。 |
| Medium | architecture-services.md 仍把 context service 的 handler/subscription 注册绝对化为发生在 init()。 |
observed — 文件开头与 Agent composition 段分别写 handlers/subscriptions “are registered in init()” (L9-L13、L129-L140)；但 ScriptRuntime.contentInit() 注册 runtime/addElement handler，content 入口在 init() 前单独调用它。 |
文档刚强调各 context lifecycle shape 不同，却仍在总则中保留统一 lifecycle invariant，会误导新增 content/inject wiring。 | 改为“handlers/subscriptions 通常在显式 lifecycle methods 中注册（常见为 init()，content 另有 contentInit()，inject 另有 externalMessage()）”；Agent 段同样避免概括全部 context services。 |
搜索 \.on( / \.subscribe( 所在方法，至少核对 service_worker/、content/script_runtime.ts、offscreen/base.ts、sandbox/runtime.ts，确认文档列出的 lifecycle 例外完整。 |
| Low | MessageQueue 被描述为在每个 entry point/manager 实例化，范围仍过宽。 |
observed — architecture-services.md 写 implementation “is instantiated per entry point/manager”；但 src/content.ts、src/inject.ts 和 SandboxManager 都没有实例化 MessageQueue。 |
“per entry point/manager”看起来是全称断言；实际只有需要 pub/sub 的部分 composition roots 持有实例。 | 改为“is instantiated by the composition roots that need pub/sub (for example Service Worker and Offscreen)”。 | git grep -n "new MessageQueue" -- src packages，把实际实例化点与文档示例逐项比对。 |
| Low | DAO 实例选择原因被写成已证实的实现事实，但源码只证明它是 case-by-case。 | observed — architecture-services.md 断言选择 “is decided … by caching needs, lifetime, and whether tests need to substitute it”；当前源码能证明注入/自建并存，但没有记录每个选择均由这三项驱动。 |
合理的设计考量被写成历史事实，后续 contributor 可能据此虚构现有代码的 ownership/lifetime contract。 | 改成规范性措辞：“When deciding, consider cache ownership, lifetime, and test substitution needs; existing choices are case-by-case, so check the nearest implementation.” | 对列出的 ScriptDAO/SubscribeDAO/ResourceDAO 实例化点检查注释、cache 开关和测试替换方式；没有证据的原因不要用陈述式归因。 |
回应 PR review (#pullrequestreview-4731478283)：
- docs/architecture.md: "Services are constructor-injected" 一条仍称所有 service 统一
接收 Group/IMessageQueue/DAO 并在 init() 注册 handler，与 architecture-services.md
已列出的 LogService/AgentService/ScriptRuntime 反例矛盾。改为陈述依赖与 lifecycle
因 context/subsystem 而异，链接到 service reference 而不是自己重新枚举统一形状。
- docs/references/architecture-services.md:
- handler/subscription 注册不再绝对写成发生在 init()：补充 ScriptRuntime.contentInit()
在 content 入口 init() 之前单独注册 runtime/addElement handler 的反例，
"Agent composition" 段同样改措辞。
- MessageQueue 实现的实例化范围从过宽的"per entry point/manager"改为准确列出实际
实例化点：service_worker.ts、offscreen/base.ts、src/pages/store/global.ts
（UI 页面订阅广播）；content/inject/sandbox 均不实例化，并给出可复核的
git grep 命令。
- DAO 共享 vs 自建的原因不再写成已证实的实现事实（源码只证明是 case-by-case），
改为规范性决策指南（cache ownership/lifetime/test substitution 是决策时应考虑的
因素，不是每个现有实例背后已记录的理由）。
已用 git grep 确认仓库内不再有 "Services are constructor-injected"/"receive their...Group"/
"register message handlers in an...init" 等统一措辞残留。
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in a310dc8 (pushed):
最终树 ref： |
Collaborator
Author
|
Reviewed against
|
回应 PR review comment (issuecomment-5017464125)：
- Testing the Internals: 测试段仍写 "message-bus behavior uses MockMessage" 并称
service 统一经 constructor 收 IMessageQueue/DAO、用 MockMessage 构造 service ——
这是本 PR 第五轮刚在 architecture-services.md 修正过的同一误解在另一处重现。
已核对 mock_message.ts/script.test.ts 拆成两层：MockMessage 只是 Server/Group
的 transport fake；service 的 IMessageQueue 依赖测试中用真实 MessageQueue（个别
方法 spy）或窄 fake，不是 MockMessage。
- Big Picture 图注："MessageQueue ... broadcasts ... across ALL contexts" 与本 PR
刚确立的实例化边界矛盾，改为准确指向"当前只有 SW/Offscreen/UI pages 会实例化"。
- "A new persisted entity" recipe 仍统一要求"construct in manager, expose via
group.on"；已核对 AgentModelService（内部默认 new AgentModelRepo()）与
AgentChatRepo（模块级 singleton `agentChatRepo`）两个反例，改为按 backend +
subsystem 找最近邻，只有真正由 context composition root 拥有且需要 RPC 暴露时
才走 manager/group.on。
- architecture-services.md 里建议的 `git grep -n "new MessageQueue"` 命令会误命中
MessageQueueGroup 与测试文件；已验证换成
`git grep -n -E 'new MessageQueue\s*\(' -- src packages | grep -vE '\.(test|spec)\.[cm]?[jt]sx?:'`
精确返回三处生产实例化点（service_worker.ts、offscreen/base.ts、
pages/store/global.ts）。
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
Author
|
Addressed in 2ca3768 (pushed):
最终树 ref： |
Collaborator
Author
|
对
|
Collaborator
Author
|
@CodFrm 不理AI的review了。合并吧 |
报告是给人读来判断实现是否正确的，所以截图、视频、日志、资源都直接嵌进 report.md：视频用 <video> 并配上运行中截下的关键帧（video 既不可跳读， 也不是每个 viewer 都能播），日志与短 fixture 用代码块贴出决定结论的那几行。 仅归档/二进制/超大日志保留裸链接。
- CAT.agent.* 并非「不走 @GMContext.API/@grant/@PermissionVerify.API」：
cat_agent.ts 用 @GMContext.API({follow})、gm_agent.ts 用 @PermissionVerify.API、
compat-grant.js 里五个 CAT.agent.* 都是注册过的 grant。改写为「同一套注册路径，
区别在点号 grant + follow/dotAlias + connect() 流式」，两处重复表述一并修正。
- grant/compat 表在 packages/eslint/compat-grant.js，不在 linter-config.ts
（后者只有 rules/globals/env）。
- 配方已是 5 步，删掉残留的「four-step recipe」措辞。
- 工具名按 name: 字段更正：sub_agent.ts 注册为 agent，tab_tools.ts 无 tab_* 前缀。
- architecture.md 传输表 MessageQueue 行的「All contexts」与本文件 76-78 行
刚确立的实例化边界矛盾，改为 SW/Offscreen/UI 页面。
task/sub_agent 是模块简写，grep 不到；实际注册名是 create_task （task_tools.ts）与 agent（sub_agent.ts:26）。仅改注释，无行为变更。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Checklist / 检查清单
背景
AGENTS.md/架构文档等仍把"新实体一律Repo<T>"、"service 都在src/app/service/<context>/"当作普遍规则,但当前树已经有
DAO<T>（Dexie）、OPFSRepo（OPFS）、custom repository,以及src/app/service/agent/、extension/等跨 context 组织方式。当前架构文档也完全没有覆盖已合入的 Agent 子系统。此外,.github/copilot-instructions.md、docs/verification.md、docs/references/design-patterns.md等文档存在过期事实（Firefox Offscreen、path alias 示例、固定 locale 数量、未经测量的百分比断言）与政策前后不一致
（TDD 例外未在 architecture/verification 中同步）。
本次改动
.github/copilot-instructions.md/docs/architecture.md及docs/references/architecture-*.md:用
Repo<T>/DAO<T>/OPFSRepo的后端分类替换过期的"一律Repo<T>"规则;架构速览补充agent/、extension/、queue.ts;新增docs/references/architecture-agent.md覆盖 Agent 子系统(工具注册表、LLM 工具循环、后台会话/子代理/定时任务生命周期、存储后端选择、跨 context 委派边界)。
docs/references/architecture-build.md: rspack entry 清单补上common、json.worker。docs/references/architecture-gm-api.md: 明确sendMessage与connect的选择依据,以及 DOM handler /linter 注册的准确落点路径。
docs/develop.md: 记录toast.ts对no-restricted-imports的完整豁免(同时覆盖 Sonner 与 Radix两类限制,不是只豁免 Sonner)。
docs/verification.md: 补充"何时可跳过本指南"的路由说明、按比例的前置检查(而非机械要求全量 Vitest)、bug 复现分支与 TDD 例外的同步、可见化的"先建
report.md"步骤、双主题 UI 验证的注意事项与证据要求。docs/references/verification-debugging.md: 补充 Firefox 无独立 Offscreen 页面的调试提示。docs/references/design-patterns.md: 移除过期的固定 8 locale 数与未经测量支持的德语/俄语约 30% 更长的断言,改为要求用当前 locale 表中的真实长字符串 fixture 验证。
docs/translation.md/src/locales/README.md: 记录i18n-usage.test.ts的真实扫描范围与盲区;修正
i8next拼写;翻译工作流改为链接translation.md,不重复维护第二份流程。docs/DOC-MAINTENANCE.md: 扩大到全部 tracked 的 agent/contributor Markdown(含.github/*.md、package-local README);新增 baseline/working-diff/proposed-final-tree 的区分、跨文档政策一致性检查、
lint/config 记录深度要求、批量编辑建议、隐私/来源清理 gate、link-checker 的 best-effort 边界说明、
duplicate heading 的 review-queue 处理方式,以及"完成声明需匹配实际证据范围"的要求。
docs/README.md/docs/pull-request.md: 更新维护范围摘要与 owner 关系;PR 指南明确只拥有 PR body,title/commit 规则链接到
develop.md,并补充文档类 PR 的按比例验证要求。packages/message/README.md: 按当前 API 重写传输方式说明(单次调用用sendMessage、流式/长连接用connect、广播用MessageQueue),并链接 SW→Offscreen 的 Chrome/Firefox 差异。packages/filesystem/README.md: 补齐当前 provider 清单(Google Drive、Dropbox、S3),并说明 Zip 是同一抽象的归档/本地备份实现,不是远端 provider。
packages/cloudscript/README.md: 修正标题与用途描述,说明当前只有localtarget,产出可执行归档而非上传云端。
src/pages/options/routes/Setting/i18nKeys.md。已知限制
README.md、四份 localized README、SECURITY.md、docs/cloud-sync.md、九份docs/references/terminology-*.md、.github/pull_request_template.md、example/agent/README.md、packages/chrome-extension-mock/README.md、CONTRIBUTING*.md未改动 —— 未发现与当前树矛盾的具体错误,或需要产品/安全 owner 确认才能改动的内容,不属本轮范围。
.github/copilot-instructions.md已在 review 迭代中缩减为纯 router(只保留 Chinese review 与全量diff review 的 Copilot 专属规则,共享架构/命令/测试内容链接到
AGENTS.md);未做的是验证目标 Copilotsurface 是否会可靠跟随该链接,这一点仍标记为待确认,不代表文件结构本身未缩减。
Review 迭代记录
8525a8ee）后收到 8 项 review 发现(AGENTS.md/copilot-instructions.md 常驻文档冗余、DOC-MAINTENANCE.md 固定文件清单遗漏新增文档、toast.ts override 措辞误导、architecture-agent.md 三处
错误 class 名、retry 4xx 排除范围失准、architecture-data.md 重复 heading、cloudscript README 可运行性
失实、develop-testing.md 不可审计的 ~15% 数字),已在 commit
d6f33294全部修复。d6f33294的 review）后收到 3 项 medium 发现(architecture-agent.md 把 screenshot/monitoring错误套进 default/trusted 二选一模型、link-checker 排除模式漏掉
mailto:/app:导致 3 条合法链接被误报 BROKEN、PR 描述本节的"未缩减为纯 router"说法与最新文件矛盾),已在 commit
dc5cf980修复,并已更新本节。
dc5cf980的 review）后收到 1 项 high、1 项 low 发现(architecture.md 的 "A new service" 配方仍规定统一
Group + IMessageQueue + DAOsconstructor,与 architecture-services.md 的 nearest-neighbor原则矛盾;architecture-services.md 遗留上一轮未改到的错误 class 名
AgentChatService/TaskService;以及本节"验证"里的复现命令没跟上最终
~~~fence 处理版本),已在 commit70c54667修复,并已更新本节与下方"验证"。
70c54667的 review）后收到 1 项 medium 发现(architecture-services.md 把 context service描述成统一 "pure DI / never new internally / no work in constructor",但
ResourceService会字段初始化内部创建
ResourceDAO并在 constructor body 做 logger/cache 初始化、SubscribeService同样内部创建两个DAO,三处绝对表述与实现矛盾),已在 commit
7d3e6da5修复:改为"共享/外部拥有的 collaborator 通常经constructor 注入,service 本地专用的 DAO/helper 是否内部
new因 service 而异",并以两个反例佐证。7d3e6da5的完整 PR review）后收到 6 项事实问题(queue.ts被误写成MessageQueuewiring,实际只有 payload/type 定义;"跨 service DAO 必须共享同一实例"的推导与
ScriptService/SubscribeService各自构造独立
SubscribeDAO/ScriptDAO矛盾;MockMessage被误当作IMessageQueue替身,实为Messagetransport;ScriptService示例写成空 constructor 且 handler 数标成会漂移的~20;ServiceWorkerManager被描述成给每个 service 都传Group + mq,但LogService/AgentService都没有mq;OffscreenManager/SandboxManager/ScriptRuntime被误称"遵循同一 shape"),已在 commit09fe390e全部修复,逐条对照源码核实。09fe390e的完整 PR review）后收到 2 项 medium、2 项 low 发现(architecture.md 仍保留统一constructor/
init()断言,与 service reference 已列出的反例矛盾;architecture-services.md 把 handler注册绝对写成发生在
init(),但ScriptRuntime.contentInit()会在init()之前单独注册 handler;MessageQueue实例化范围被写成过宽的"per entry point/manager",实际只有 service_worker.ts、offscreen/base.ts、以及订阅广播的 UI 页面会实例化;DAO 共享/自建的原因被写成已证实的实现事实,但源码只
证明是 case-by-case),已在 commit
a310dc80全部修复,并已用git grep确认仓库内不再有统一constructor/init() 措辞残留。
a310dc80的 review comment）后收到 1 项 high、2 项 medium、1 项 low 发现(architecture.md的 Testing 段在另一处重复了刚被否定的"service 统一经 constructor 收 IMessageQueue/DAO、用 MockMessage
构造 service"说法;Big Picture 图注称 MessageQueue 向 ALL contexts 广播,与本轮已确立的实例化边界矛盾;
"A new persisted entity" recipe 仍统一要求 construct in manager + group.on,与 AgentModelService/
AgentChatRepo 的实际 ownership 矛盾;建议的
git grep "new MessageQueue"命令会误命中MessageQueueGroup 与测试文件),已在 commit
2ca37683全部修复。验证
相对链接检查的权威、可复现命令唯一存放在
docs/DOC-MAINTENANCE.md§ Link integrity——本节不再复制一份可能与之漂移的副本(上一轮已发生过一次:PR body 里的命令缺了最终版本的
~~~fence 处理)。其余检查:
git diff --check # 无空白/合并冲突标记问题git grep/git ls-tree对当前树(src/app/repo、src/app/service/、rspack.config.ts、eslint.config.mjs、tsconfig.json、src/locales/、src/service_worker.ts、src/app/service/offscreen/event_page_manager.ts、packages/filesystem/)的直接查询结果,详见各文件 diff。pnpm test/pnpm run lint:本次改动仅涉及 Markdown,不涉及可执行代码路径。DOC-MAINTENANCE.md的权威命令在最终树重跑一次:输出 0 条BROKEN;并注入一条无效相对链接确认检查仍会正确报错(验证后已还原,未保留在 diff 中)。
AgentChatService/AgentCompactService/裸TaskService(误指 Agent 服务时)的残留引用。
2ca376838919bb397725b77661b89868ab0a317b(2ca37683)。