docs: integrate agent browser background debugging contract
This commit is contained in:
@@ -92,7 +92,7 @@ Main 在接收带图消息时立即将上传 attachment id 放入 optimistic use
|
||||
| AI 编程上下文压缩 | Renderer compact action / Pi compaction events | correlated compact RPC → target projector → Snapshot/Patch timeline | Pi `0.84.2` 的手动 compact 不发 `agent_settled`；RPC success 或权威 compaction failure 终结 compact 并 exactly-once 释放对应 ownership，不提前结算普通 prompt |
|
||||
| AI 编程 Provider 错误 | Pi logical-thread Provider 请求 | selected thread-local credential store → Main AI proxy → Works 模型上游 → projector safe error | 确定性的 Works user-context 缺失使缓存 gateway credential 过期、返回非重试认证失败且不重放请求；Renderer 只看到固定 Provider-auth 提示，不能把它解释为 Pi 崩溃 |
|
||||
| AI 编程子 Agent | parent logical thread `subagent.v1` tool call | explicit extension → authenticated Main bridge → scheduler → independent ephemeral Pi child process | child 并发最多 4、单次最多 8、禁止递归；child 使用 FIFO 进程预算 8，shared parent 逻辑线程不各占一个 process lease；coding child 与 parent 共用项目 write lease，父 abort/crash/generation 失效必须清理 child 与 permit |
|
||||
| 共享开发浏览器 | 用户面板打开或 parent Agent `agent_browser open` | 当前项目身份 → Main-owned browser route/module → sandboxed `WebContentsView` + bounded CDP → 同一 Renderer 右侧 viewport/Console/Network | Agent 发起打开后先通知 Renderer 展示并最多等待 5 秒取得当前 generation 的可见 bounds；项目 id 仅允许具备 Renderer capability 的请求使用。非 Web、文件注入、跨目标及宿主级 CDP 被拒绝；诊断 owner 释放到零后停止采集。 |
|
||||
| 共享开发浏览器 | 用户打开作品或 parent Agent `agent_browser open` | 当前项目身份 → Main-owned browser route/module → sandboxed `WebContentsView` + bounded CDP → 同一作品 viewport/Console/Network | 新浏览器首次打开通知 Renderer 展示，最多等待 5 秒取得当前 generation 的可见 bounds；之后切回操作对话保留工具访问，重复 open/导航只发布 state、不请求 show。隐藏截图通过原生 capture 请求一帧后执行原 CDP 命令，不抢标签或焦点。项目 id 仅允许具备 Renderer capability 的请求使用；非 Web、文件注入、跨目标及宿主级 CDP 被拒绝；诊断 owner 释放到零后停止采集。 |
|
||||
| 客户端更新检查 | 设置页 | Renderer update store → IPC → Main AppUpdater → 目标 feed | Main 记录并重抛原始错误；Renderer 只显示去重、脱敏的单条提示，稳定源缺包不伪装为最新版 |
|
||||
| Design Workspace load | Canvas 中央区与右侧 Works rail | Renderer Host API → Main-owned Works Square V2 adapter → current Workspace/Direction/Living Form projection | 一个 Workspace 公开一个 current Direction 与 persistent Agent Session；右 rail 只选择/创建/删除 Workspace，conversation timeline 是交互历史，不是独立 authority object |
|
||||
| Design input and reconciliation | Chat/direct edit/decision/proposal/lock/Asset binding/restore | Renderer draft → Main → `design.input.apply` → canonical Direction projection | 全部进入同一 reducer；accepted 前 draft 保持本地，revision conflict 刷新权威投影，unknown result 复用原 command/operation identity |
|
||||
|
||||
@@ -23,8 +23,8 @@
|
||||
| `electron/services/project-release-builder.ts` | Main-owned 安全快照、本地 npm/Vite 构建、source+built 双归档与 v1 contract | 固定 npm 11.6.2；项目 Vite 由 lockfile 决定；Vite config/plugins 以桌面用户权限执行 |
|
||||
| `electron/services/publish-runtime.ts` | 安装包内 npm 闭包定位与 Electron Node 执行 | 不回退全局 npm/PATH；缺失或版本不符 fail closed |
|
||||
| `electron/services/static-release-server.ts` | 用内存 built snapshot 建立一次性 loopback origin | 预检和最终上传归档必须来自相同文件字节；总是清理临时服务 |
|
||||
| `electron/agent-browser/module.ts`, `electron/api/routes/agent-browser.ts`, `src/lib/agent-browser.ts`, and `src/pages/Chat/AgentBrowserPanel.tsx` | 项目级共享开发浏览器、可见 viewport 协调、Console/Network 诊断与 built artifact 临时预检 | 用户和 parent Agent 共享同一 sandboxed 页面；Main 校验当前项目、generation、bounds 与 CDP method。诊断按 owner 引用计数，关闭/切换/隐藏/休眠会释放 view 与 debugger；发布预检仍只是 UX fail-fast，不生成可信 receipt。 |
|
||||
| `electron/agent-browser/electron-adapter.ts` | Electron WebContents/CDP 设备指标、事件与临时 partition 适配 | probe 不挂载 UI，并在结束后销毁视图、清理隔离存储 |
|
||||
| `electron/agent-browser/module.ts`, `electron/api/routes/agent-browser.ts`, `src/lib/agent-browser.ts`, and `src/pages/Chat/AgentBrowserPanel.tsx` | 项目级共享开发浏览器、首次 viewport 初始化、Console/Network 诊断与 built artifact 临时预检 | 用户和 parent Agent 共享同一 sandboxed 页面；Main 校验当前项目、generation、bounds 与 CDP method。首次打开等待可见 bounds；切回操作对话只隐藏 view，保留调试能力，重复 open/导航不强制切页。诊断按 owner 引用计数；明确关闭浏览器、切换项目/模块、隐藏窗口或休眠仍释放 view 与 debugger。发布预检仍只是 UX fail-fast，不生成可信 receipt。 |
|
||||
| `electron/agent-browser/electron-adapter.ts` | Electron WebContents/CDP 设备指标、事件与临时 partition 适配 | 隐藏页面截图先用 stayHidden 原生 capture 请求一帧，再执行原 CDP 截图，保留参数且不展示页面、不转移焦点、不持续关闭后台节流。发布 probe 不挂载 UI，并在结束后销毁视图、清理隔离存储 |
|
||||
| `electron/services/project-packager.ts` | 受控项目扫描、静态 ZIP 生成和敏感/历史控制文件排除 | 只允许可发布 `ProjectType`，不提供 Compose 或手工 ZIP 路径 |
|
||||
| `electron/services/works-submission-binding.ts` | submission binding v2 持久化与旧 schema 迁移 | 旧中间态终止为 `legacy_retired`；文件名暂作安装兼容 |
|
||||
| `electron/api/works-play-url.ts` | 公共播放 URL 的共享安全校验 | 公共 `play_url` 必须同源 HTTPS 且精确匹配 App 路径 |
|
||||
|
||||
@@ -48,7 +48,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
|
||||
| Pi Conversation Runtime | 一个长驻 Pi `0.84.2` Agent Server 承载每条 active/warm Conversation 的隔离逻辑 Runtime/Session/JSONL channel | 严格 LF JSONL RPC、generation recovery、Snapshot hydration；正式包从 staged `pi-runtime` manifest/root 定位并校验 Pi 包入口；top-level 逻辑 turn 并发 4、warm idle LRU 8；Server 退出统一使旧 channel 失效并按需单实例重启 |
|
||||
| Pi Provider & Managed Resources | Provider catalog、thread-local secret projection、model/resource revision、Prompt/Skill/extension materialization、selected-model tools | Works `model_capabilities_v2` 由 Main 归一化并持久化，作为受管模型图片/思考能力唯一依据；未知不回退本地 profile。Main 保存原生 reasoningChoice 并冻结供应商字段，经 Pi 请求钩子发送。父/子凭据仍限于目标执行上下文；Web Search 保持独立适配器、所选模型及普通模型计费，不回退 agent_browser；secret 不进入 argv、catalog 或 Renderer |
|
||||
| Pi Extension, Subagents & Lifecycle | 必需的生成式 Makelore extension、Main 显式选定的已安装 extensions、UI interaction、ephemeral child、write lease 与 background run lease | Makelore bridge 固定为首个 extension，其余选定 extension 全部经 Pi 的 explicit additional paths 加载且 ambient discovery 关闭；child 并发 4、单次最多 8、禁止递归；active/uncertain run 不因页面隐藏或 confirmation timeout 被停止，replacement/stop 必须可解释并清理所有 ownership |
|
||||
| Shared Agent Browser | Project-scoped sandboxed `WebContentsView`、Renderer 右侧面板与 Main-owned CDP bridge | 用户和 Agent 操作同一页面；Renderer 必须先提供可见 bounds，Agent `open` 最多等待 5 秒取得可见 viewport。Console/Network 诊断按 owner 引用计数；关闭面板、切换项目/模块、隐藏窗口或后台休眠会清理 view、debugger 与轮询。 |
|
||||
| Shared Agent Browser | Project-scoped sandboxed `WebContentsView`、作品页与 Main-owned CDP bridge | 用户和 Agent 操作同一页面；新浏览器首次打开最多等待 5 秒取得 Renderer 提供的可见 bounds。已初始化页面切回操作对话后仍可调试；重复 open/导航只更新状态，不强制切页。隐藏截图按需请求一帧，不展示页面或转移焦点。Console/Network 诊断按 owner 引用计数；明确关闭浏览器、切换项目/模块、隐藏窗口或后台休眠仍清理 view、debugger 与轮询。 |
|
||||
| Code-owned Official Project Plugins | Existing Account acquisition or system-included delivery → project enablement → effective parent snapshot | Data Service、Game Resource 与 Project Scaffold 都不要求 Agent assignment，项目启用后自动进入每个父 Agent；child 不继承 Plugin。三者不经过设备下载、更新、Beta 或 artifact 签名；Game Resource 的一次确认由 Main 提交一次、内部轮询并把全部终态输出自动写入冻结的原项目，恢复本地交付不得重新生成或计费；Project Scaffold 的 `.mjs` 仍只来自签名客户端固定资源。需要分配的 Marketplace 下载包保持原规则。 |
|
||||
| Device Packages | Conversation install tools → Main-owned inspect/preview/confirm/commit → immutable local generation → parent Skill/Pi-extension resources | 支持 npm、Git、绝对本地 Plugin 目录与 loose `SKILL.md`；没有可见安装入口、Account Library、Release、Admission 或 Marketplace Package Store。可执行 extension 与非空 Skill `scripts/` 拥有桌面用户权限，必须披露并独立确认；生命周期脚本禁用。每个 generation 包含所有显式安装且当前启用的 Skill/extension；新/idle parent 自动刷新，active parent 在 turn settled 后刷新，child 始终为空。 |
|
||||
| Unified Plugin Workspace | Project Configuration 的 `插件` ResourceCard → `/project-config/plugins` same-page wide sheet | 复用统一 Plugin controller 与生命周期；Project Configuration 保持挂载，Code 侧栏不再提供独立入口；`/plugins` 和旧 Plugin URL 仅做保留查询条件的兼容重定向 |
|
||||
|
||||
@@ -4,6 +4,8 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
|
||||
|
||||
## Integrated Through
|
||||
|
||||
- 2026-09-27：从 `220e899` 无冲突快进合入浏览器修复源 `a52e747a00fb5c6ff680bb7e4e691c07d003e34f`。首次打开新浏览器仍等待真实视口；切回操作对话后保留工具访问，重复 open/导航不强制切到作品页。隐藏截图按需请求一帧，保留截图参数且不转移焦点。明确关闭、项目/模块切换、窗口隐藏/休眠及 sandbox/CDP 限制保持。产品、测试、README 和源记录与已验证版本完全一致，沿用 134 项相关测试、4 个 Electron 用例、标准 typecheck/build；额外 Main 全量检查有既有 66 项诊断，无新增。3 份外来文档原样保留；未推送、打包或安装。见[源任务](tasks/20260927-browser-tab-focus-5c92d7a1.md)和[集成记录](tasks/20260927-merge-browser-focus-6edcb784.md)。本条澄清“隐藏作品标签”与“关闭浏览器/隐藏窗口”的区别。
|
||||
|
||||
- 2026-09-27：无冲突合入已独立审查源 `56cefe84e7b654bcc20f2b8fde7f97336134fec8`，包含工具活动去重 `8a74721`。三个只读工具提供按层目录、连续 UTF-8 原文及精确续读位置；协议 2 采用 12 批／64 KiB 累计成功结果／8 KiB 单页，额度耗尽后消费最后结果并进入回答。同一逻辑工具跨 Run 只显示一项，暂停不再重复显示失败。产品、测试、README 和源记录与审查版本一致；沿用源 72 项客户端测试、Renderer 类型检查及 Vite 构建，Main 全量检查的既有 97 项诊断无新增。原 3 份外来文档原样保留。未推送、打包或安装；先部署配套 Yuxi API／worker，再更新客户端，真实模型验收另行完成。见[源任务](tasks/20260926-teacher-read-expired-087d82f7.md)和[集成记录](tasks/20260926-merge-teacher-read-ml-616605aa.md)。本条更新新客户端额度，旧条目保留为历史。
|
||||
|
||||
- 2026-09-26：从 `287dcd303d3c99665e95eca3345c4ee3270a855f` 无冲突快进合入已独立审查源 `60c20f996e8428d4dfbd5efb92792d3900722af5`。云端咨询最多执行六批本地读取。Yuxi 消费最后一批结果后通过 `tool_choice: none` 请求最终答案；Main 保留第七批保护，并区分 `teacher_read_limit`、`teacher_context_expired` 和 `teacher_protocol_invalid`。真实模型与安装版验收保持独立，失败问题不自动重试。 产品、测试和源记录与审查版本一致，沿用源验证；两仓共 5 份外来文档原样保留。未推送、部署或更新安装版。见[源任务](tasks/20260926-teacher-read-expired-087d82f7.md)和[集成记录](tasks/20260926-merge-teacher-read-ml-616605aa.md)。
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
|
||||
| Date | Task | Outcome | Docs Updated |
|
||||
|---|---|---|---|
|
||||
| 2026-09-27 | 合入浏览器切页与后台调试修复 | 快进合入 a52e747；切回对话不阻断工具，重复 open 不抢标签，隐藏截图不抢焦点；3 份外来文档保持 | architecture、domain、current-state、integration task |
|
||||
| 2026-09-14 | 合入用户级微信账号管理 | 已审查源快进到本地 main；多账号、可选目标、切换保留登录，原有 3 份文档保留 | 个人云平台 ADR、决策索引、架构、当前状态、本任务 |
|
||||
| 2026-09-04 | Land official Project Scaffold Plugin on local main | Fast-forwarded verified integration head `b92e7ba` onto local `main` while preserving three explicitly adopted historical task documents unchanged; no package, publication, deployment, or push was performed | current-state, landing task |
|
||||
| 2026-09-04 | Official Marketplace Project Scaffold integration | 将 `makelore.project-scaffold` 作为代码所有、随签名客户端交付的 bundled `skill_only` Plugin 接入 Account Library/项目启用/Agent 分配；官方 `.mjs` 不经过下载 artifact，下载包仍保持文本/图片 P0 限制 | ADR-008、current-state、architecture、domain、success criteria、integration task |
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# Task: Integrate agent browser tab focus fix
|
||||
|
||||
## Identity
|
||||
|
||||
- Task ID: 20260927-merge-browser-focus-6edcb784
|
||||
- Mode: Integration
|
||||
- Branch: main
|
||||
- Worktree: D:\Datas\OthersProjects\makelore
|
||||
- Base commit: 220e89992b4d847eadcc64bd8faf058d0e25d36d
|
||||
- Owner: codex
|
||||
- Status: Ready for Integration
|
||||
|
||||
## Scope
|
||||
|
||||
- Integrate source a52e747 from task 20260927-browser-tab-focus-5c92d7a1 into local main. Promote its verified browser lifecycle/focus contract; no new product implementation.
|
||||
|
||||
## Intent And Constraints
|
||||
|
||||
- Concurrent and Planning Gates Passed. Official start/status establish exclusive integration ownership at 220e899. Entry, own/source records, relevant positioning, decisions, architecture, domain and verification context loaded. Refreshed 123 peer records; packaging-170 is isolated and has no product edits. Historical placeholder records remain unknown without a concrete dependency.
|
||||
- User confirmed release --force of the completed teacher-read integration and --adopt-existing of the three known foreign documents. They remain unchanged and outside this commit.
|
||||
- Current user request supersedes the old all-tools-require-visible-view rule: only first viewport initialization requests foreground presentation. Keep explicit teardown, sandbox, generation/project and CDP guards.
|
||||
- Plan: fast-forward exact source, verify source/product equality, promote canonical documentation, pass drift/whitespace checks and commit. Reuse source validation if product bytes are identical. No push, deployment, build artifact, installation, cleanup or new reviewer.
|
||||
|
||||
## Outcome
|
||||
|
||||
- Fast-forwarded local main from 220e899 to source a52e747a00fb5c6ff680bb7e4e691c07d003e34f without conflicts. Product, tests, README and imported source record match the tested source exactly.
|
||||
- Promoted the first-viewport versus hidden-tab distinction and hidden-screenshot behavior into architecture/domain/current-state/history. Explicit browser close, project/module/window teardown and sandbox/CDP boundaries are unchanged.
|
||||
- The three adopted foreign task documents remain unchanged and uncommitted. No remote push, package, installation, production request or deletion.
|
||||
|
||||
## Verification
|
||||
|
||||
- Exact source ancestry and product/test/README/source-record equality passed; no merge resolution or product edit occurred.
|
||||
- Reused source evidence: 134 related unit tests, 4 Electron scenarios, standard typecheck and Vite build passed. Extra Main-wide compiler check retains 66 baseline diagnostics, zero additions and none in touched files.
|
||||
- Whitespace and official task-aware documentation checks passed; adopted documents retain their recorded original states.
|
||||
|
||||
## Follow-ups
|
||||
|
||||
- Source worktree remains available pending the separate cleanup confirmation. Installed client still needs a rebuilt package to receive the fix.
|
||||
|
||||
## Promotion Candidates
|
||||
|
||||
- Source promotion accepted under the user's browser-fix and merge authorization; applied to module-map, data-flow, system-overview and business-rules. Older visibility wording is clarified; no unresolved product decision or source-record edit.
|
||||
@@ -124,10 +124,12 @@
|
||||
the configuration page remains mounted. Code sidebar must not add a standalone
|
||||
Plugin entry; `/plugins` and older Plugin URLs are compatibility redirects only.
|
||||
- 共享开发浏览器必须绑定当前项目和当前 generation。Renderer 的 `project_id` 与
|
||||
viewport presentation 仅可由具备 Renderer capability 的请求使用；Agent `open`
|
||||
必须等待真实可见 bounds 后才报告成功。非 Web 协议、文件注入、跨 target 与宿主级
|
||||
CDP 命令保持拒绝，诊断按 owner 引用计数；关闭面板、项目/模块切换、窗口隐藏或
|
||||
后台休眠必须销毁 view、detach debugger 并停止无所有者轮询。
|
||||
viewport presentation 仅可由具备 Renderer capability 的请求使用；新浏览器首次
|
||||
`open` 必须等待真实可见 bounds 后才报告成功。已初始化页面切回操作对话时只隐藏，
|
||||
仍可执行工具；重复 `open` 或导航不得强制切换用户标签。隐藏截图按需请求一帧，
|
||||
保留原 CDP 参数，不展示页面或转移输入焦点。非 Web 协议、文件注入、跨 target 与
|
||||
宿主级 CDP 命令保持拒绝，诊断按 owner 引用计数；明确关闭浏览器、项目/模块切换、
|
||||
窗口隐藏或后台休眠仍必须销毁 view、detach debugger 并停止无所有者轮询。
|
||||
- Code-owned official bundled Plugins may be `platform_hosted` or `skill_only`.
|
||||
Data Service is system-included; Game Resource, Game Audio and `makelore.project-scaffold` retain
|
||||
Account Library, project enablement, Release, and Admission state where applicable,
|
||||
|
||||
Reference in New Issue
Block a user