merge: reconcile latest main changes

README.md

@@ -16,7 +16,7 @@ Makelore 是一个面向软件、视觉创作、互动学习与智能机器人
 ## 当前产品状态
 
 - 桌面技术栈：Electron、React 19、Vite、TypeScript、Zustand、Tailwind CSS。
-- AI 编程核心对话运行时：Electron Main 按需启动一个长驻 Pi Agent Server，同一进程内为每条 Conversation 建立独立的 Runtime、Session、凭证视图、扩展上下文和 JSONL 通道，同时复用 Pi 模块与进程启动成本；Server 异常退出时所有旧通道统一失效，下一次恢复只重启一个 Server。Renderer 不直接启动或调用 Pi，也不读取其 wire 类型。项目与 Conversation 元数据先从本地读取，选中对话后才按需准备对应逻辑线程；输入框不等待运行时准备完成。同一助手工具批次中，会取得项目写租约的 `bash`、`edit`、`write` 与动态产品工具按顺序执行，避免批次在命令启动前自锁；纯只读工具仍可并行。子 Agent 仍使用独立的短生命周期进程，以保留并发配额、故障和写入边界；macOS 上两类后台进程都使用 Electron 自带的 Helper，不在 Dock 中创建额外应用图标。
+- AI 编程核心对话运行时：Electron Main 按需启动一个长驻 Pi Agent Server，同一进程内为每条 Conversation 建立独立的 Runtime、Session、凭证视图、扩展上下文和 JSONL 通道，同时复用 Pi 模块与进程启动成本；Server 异常退出时所有旧通道统一失效，下一次恢复只重启一个 Server。正式包中的 Agent Server 从明确传入的 `resources/pi-runtime` 根定位依赖清单与包入口，不从脚本所在目录或应用 `node_modules` 猜测解析。Renderer 不直接启动或调用 Pi，也不读取其 wire 类型。项目与 Conversation 元数据先从本地读取，选中对话后才按需准备对应逻辑线程；输入框不等待运行时准备完成。同一助手工具批次中，会取得项目写租约的 `bash`、`edit`、`write` 与动态产品工具按顺序执行，避免批次在命令启动前自锁；纯只读工具仍可并行。子 Agent 仍使用独立的短生命周期进程，以保留并发配额、故障和写入边界；macOS 上两类后台进程都使用 Electron 自带的 Helper，不在 Dock 中创建额外应用图标。
 - AI 编程历史与配额反馈：Pi 上下文压缩不删除用户可见的 active-branch 历史，压缩摘要保持 Main-private；Renderer 首次渲染最近 120 个节点，向上滚动时按 100 个节点追加更早内容并保持阅读位置。Main 精确识别 `token_point_balance_exhausted` / `词元点数余额不足`，只向 Renderer 投影不可重试的稳定配额错误和安全中文提示，重开会话后仍可见且不暴露上游原始错误或 request id。
 - 桌面性能策略：应用窗口使用不透明浅色表面并默认保留硬件合成；仅在显式安全模式或短时间内重复 GPU 进程崩溃时启用软件渲染，并把故障原因保存在用户数据目录。启动关键路径只创建本地应用壳，认证、代理、同步、更新和遥测在首帧后延迟初始化；开发版可通过 `app:performance` 快照观察 GPU、进程、WebContents、事件循环与 Renderer Long Task 聚合指标。
 - 后台生命周期：Main 统一维护模块活动状态与任务租约。隐藏窗口、离开模块和关闭开发浏览器会释放非必要连接；生成、Code 执行、下载与发布构建持有租约并在完成后释放。已写入 Pi 的 prompt 或上下文整理即使确认超过 10 秒，也会继续持有运行所有权与后台租约，直到迟到响应、权威事件、明确失败或用户清理使其收敛；此时同一 Conversation 不接受重叠 mutation，其他 Conversation 不受影响。各模块的后台连接、轮询和子进程必须通过同一生命周期入口登记。
@@ -32,7 +32,8 @@ Makelore 是一个面向软件、视觉创作、互动学习与智能机器人
 - AI 学习：主区展示服务端分页项目卡片，详情页用安全 Markdown 渲染 README；原始 HTML 被禁用，Markdown 图片节点直接加载服务端校验后的无凭据 HTTPS URL，包括 SVG 和 Electron 支持的其他图片格式，不经过服务端下载、识别、转码或镜像。下载按钮打开系统保存对话框，Main 不按 `Content-Length`、声明字节数或客户端上限阻断下载，流式校验 SHA-256 与 ZIP 签名后原子保存。客户端不提供课程生成、课程播放器、本地课程库、Agent、ASR 或课堂 runtime。运营管理与接口字段见 [`docs/learning-project-catalog-server-contract.md`](docs/learning-project-catalog-server-contract.md)。
 - 插件市场 Release A：侧栏不再提供独立插件入口，项目配置中的“插件服务”统一承载“发现插件”“我的插件”“项目启用”三个标签。它们分别管理 Marketplace 浏览获取，账号 Library 与本机安装/更新/删除设备包，以及当前项目启用与配置；“免费获取”只写入账号 Library，“下载/更新”才写入本机 Package Store，“启用到项目”和“分配给伙伴”仍是彼此独立的动作，不会因获取或下载自动推进。旧插件路由仅保留兼容跳转。
 - 插件运行架构：Renderer 只调用 Main-owned Marketplace facade；Main 负责账号、请求 deadline、签名/摘要校验、不可变 Release、current selection 与原子回滚。下一代 Pi worker 使用同一个 effective snapshot，将每个有效 Skill 与已验证 Package Store root 成对传给 resource loader、Extension Host 和 CLI；`skill_only` 不依赖运行时 Policy，也不执行分发包中的任意代码。正式激活仍等待官方 Ed25519 公钥（production key activation HOLD）；生产私钥只能来自部署 secret，测试使用注入的临时密钥。
-- 原生 Web Search 是 `platform_hosted` 精选插件：用户仍需依次免费获取、下载、启用到项目并分配给伙伴，每次搜索还必须显式确认 Token Point 消耗。Renderer 与插件包不持有 Provider 密钥、模型或 URL；Main 只调用固定 Works Square typed route，并把收费状态作为 closed receipt 展示。正式激活仍等待官方签名公钥、`WEB_SEARCH_OPENAI_API_KEY`、模型、价格与隐私文案；开发和验收不得把 fake Provider 结果当作生产 OpenAI 通过。
+- 原生 Web Search 是所选模型的核心能力：只有 Main 已确认当前模型、Provider 与凭据支持搜索时，父 Pi worker 才会获得 `makelore_web_search`；它沿用该模型的普通调用与计费，不经过 Marketplace 获取、Release/Admission、Plugin Charge 或浏览器兜底，也不向 child worker 下发。真实已选付费 Provider 搜索仍需单独验收，测试替身不能当作生产通过。
+- 设备包只允许由 Conversation 内的 Agent 工具发起：先检查 npm、Git、绝对本地插件目录或单个 `SKILL.md`，展示预览，再在后续独立步骤取得用户确认后由 Main 写入不可变本机 generation。安装不运行生命周期脚本；Pi extension 会以桌面当前用户权限执行，因此确认界面必须明确说明风险。新建或空闲父 worker 自动刷新，活动父 worker 在本轮结算后刷新，child worker 不继承；“我的插件”把设备包与官方插件分开展示，Renderer 不提供安装源选择器。
 - 提示词博物馆：只陈列经过审核的作品预览、Prompt、分类以及作者/来源/许可证信息，支持搜索、使用场景/风格/主体筛选和详情抽屉；“使用此 Prompt”只把原文带回当前 Canvas 对话草稿，不自动发送、不构成社区。列表和详情数据由服务端提供，客户端不打包数据集；服务端字段契约见 [`docs/prompt-museum-server-contract.md`](docs/prompt-museum-server-contract.md)。
 - 视觉系统：单一浅色主题，品牌蓝 `#3A5578`、星火橙 `#F26A3D`、白色画布与低饱和蓝灰层级。
 - 字体系统：Renderer UI 内嵌 Inter Variable 与经过字符子集化的 Source Han Sans SC WOFF2，按字符范围统一中英文并保留系统中文字体 fallback；代码、路径和日志使用独立等宽字体。
@@ -74,7 +75,7 @@ pnpm run package:win
 pnpm run package:linux
 ```
 
-Windows 打包脚本会先准备目标架构所需的 Pi、Python 与 uv 运行时资源，产物写入忽略的 `release/` 目录。AI 学习不再携带独立播放器产物。Windows 正式包中的 Pi、Python 和 uv 均从安装目录解析；缺少本地资源时启动或产物验证会直接失败，不会回退到系统 Python、npm 或 npx 下载。Git、项目编译器和用户选择的浏览器仍属于项目/系统工具，不属于内置 Pi 运行时。macOS 与 Linux 的双架构产物需要分别完成对应架构的 staging 与产物验证后再发布。
+各平台打包脚本会先准备目标架构所需的 Pi、Python 与 uv 运行时资源，产物写入忽略的 `release/` 目录。AI 学习不再携带独立播放器产物。正式包中的 Pi、Python 和 uv 均从安装目录解析；Agent Server 以已 staged 的 `resources/pi-runtime/package.json` 为解析锚点，并校验目标包入口仍位于该包内部。缺少本地资源或合法入口时启动和产物验证会直接失败，不会回退到应用 `node_modules`、系统 Python、npm 或 npx 下载。Git、项目编译器和用户选择的浏览器仍属于项目/系统工具，不属于内置 Pi 运行时。macOS、Windows 与 Linux 的各架构产物需要分别完成对应架构的 staging 与产物验证后再发布。
 
 Pi 正式包必须继续运行 `pnpm run verify:artifact:pi`、`pnpm run smoke:pi:real` 和 `pnpm run perf:pi:release`。这里的 `real` 表示从最终产品可执行文件启动最终 `resources/pi-runtime`，并使用受控的 Provider-shaped 回环服务验证会话、工具、中止、结算、重开、并发隔离、子 Agent 与退出；它不表示真实外部 Provider 已验证。各目标平台、证据字段、兼容边界与整版本回滚步骤见 [`docs/pi-runtime-release-runbook.md`](docs/pi-runtime-release-runbook.md)。
 
@@ -114,7 +115,7 @@ Pi 正式包必须继续运行 `pnpm run verify:artifact:pi`、`pnpm run smoke:p
 ### 项目内置编码技能
 
 - 产品内置四个核心编码技能根：`agent-browser`（开发浏览器）、`frontend-slides`（项目演示）、`grilling`（方案质询）和 `planning-with-files`（项目规划），统一从 vendor-neutral 的 `resources/coding-skills/` 打包。`data-service`（开发数据）由固定的 `resources/coding-plugins/data-service/` 插件包持有，不在核心技能根中复制路径或定义。
-- Marketplace 插件 Skill（包括 Web Search）从已签名 Package Store Release 动态物化，不进入核心技能根，也不靠静态工具白名单；只有下一代 parent worker 的冻结 effective snapshot 同时满足安装、账号 Library、项目启用与伙伴分配时才生效，child worker 不继承 hosted tool。
+- Marketplace 官方插件 Skill 从已签名 Package Store Release 或受控内置定义动态物化，不进入核心技能根；只有 parent worker 的冻结 effective snapshot 满足对应账号、设备、项目与伙伴条件时才生效，child worker 不继承 hosted tool。所选模型的 Web Search 与 Conversation 安装的设备包使用各自独立的 Main-owned 合同，不属于这条 Marketplace 生命周期。
 - 项目插件“启用”和把插件技能分配给智能体是两个独立动作：只有项目已启用 Data Service 时，未分配的 `data-service` 才可供新选择；禁用后，已有分配仍会显示并继续保存在智能体的 `skillIds`，但处于不可用且不生效的状态，重新启用后恢复生效。未启用的技能不进入该智能体的有效 Pi 资源集合。
 - `data-service` 只在用户显式请求后触发：先检查并说明最小集合，用户确认后配置一次、复制 SDK 资产，再用本地预览执行 put/read-back；它不用于已发布作品。
 - 创建项目智能体时，`agent-browser`、`grilling` 与 `planning-with-files` 默认启用；`frontend-slides` 作为专项能力可手动启用。用户可以在创建或编辑智能体时调整选择。最终选择写入项目智能体的 `skillIds`。
@@ -130,7 +131,7 @@ Pi 正式包必须继续运行 `pnpm run verify:artifact:pi`、`pnpm run smoke:p
 - “可用技能”入口使用模块图标；点击技能后先展示目录结构，再展示主文件 `SKILL.md` 原文，并支持返回技能列表。
 - 一个智能体可以拥有多条互相独立的 Pi Session；智能体和对话元数据分别由 `.makelore/project.json` 与 `.makelore/conversations.json` 保存，稳定的智能体与对话 id 保持本地历史连续。
 - 核心聊天页左侧把本地对话嵌套在展开的所属智能体下，并在该智能体子组中提供新建入口；首次选择没有对话的智能体时立即创建本地元数据，同时异步准备对应运行时。即使准备被阻塞或超时，输入框仍可编辑，草稿也不会丢失。
-- Conversation 历史按需从 Main-owned Snapshot 读取。Session hydration 沿完整 active branch 投影可见历史；公开 SSE 只交付 Snapshot 与按 Conversation、worker generation 分组的 `patch-batch`。Renderer 整批校验连续 seq 后在一次状态事务中顺序应用，缺口或畸形批次只恢复目标 Conversation，隐藏 Conversation 的流式更新不会提交选中时间线。时间线默认挂载最近 120 个节点，接近顶部时按 100 个节点自动追加更早内容并补偿新增高度，保持当前阅读锚点。
+- Conversation 历史按需从 Main-owned Snapshot 读取。Session hydration 沿完整 active branch 投影可见历史；公开 SSE 只交付 Snapshot 与按 Conversation、worker generation 分组的 `patch-batch`。Renderer 整批校验连续 seq 后在一次状态事务中顺序应用，缺口或畸形批次只恢复目标 Conversation，隐藏 Conversation 的流式更新不会提交选中时间线。Main 发出 `lifecycle:sleep` 时页面关闭旧事件流；视图挂载、项目上下文变化、窗口重新可见或获得焦点时，已选 Conversation 会静默重读权威 Snapshot，从而收敛后台已结束的任务，但绝不重放已接受或状态不确定的 mutation。时间线默认挂载最近 120 个节点，接近顶部时按 100 个节点自动追加更早内容并补偿新增高度，保持当前阅读锚点。
 - 核心时间线按每条用户消息组织为“用户消息、连续处理过程、结论回复”。Pi 的流式 thinking、工具、压缩、重试、通知和 `subagent.v1` 单个/并行/串行子任务共享一条轻量过程轨道；运行时显示“处理中”和活动指示，完成后按耗时（历史缺少计时时按项目数）收纳为可展开的“已处理”摘要。文字层级按结构化事件类型划分，不按文案关键词猜测：助手在工具调用前后直接对用户说的过程正文与最终结论都使用黑色；thinking、工具输入输出、压缩、子任务和运行状态使用浅灰辅助文字，仍在运行的灰色缩略文字带有低对比度 Shimmer 擦拭高光，结束后停止动画；错误状态保持红色。折叠的 thinking、助手过程正文和工具输出固定展示第一个可见块的首个非空行，横向偏移始终为零；尾部流式更新不会替换未变化的首行预览，展开后仍可查看完整内容。两类流式文字均在原位更新且不做位移动画，助手过程正文也不使用 Shimmer。工具调用用一行摘要持续展示工具名称、最新输入或输出和运行状态，并可按流式批次轻量整行轮动。思考、助手过程正文和工具节点均可展开查看完整详情，工具的累计输出和浏览器附件留在对应的二级展开区而不形成独立气泡。结论回复按安全 Markdown 排版标题、列表、引用、代码和表格；可点击的 HTTP/HTTPS 与本地 HTML 链接统一使用无底色的橙色文字。左键通过 Main-owned 系统入口交给默认浏览器打开；右键可打开系统菜单，网页链接可复制地址，本地链接还可在访达或系统文件夹中显示。同一回复已经给出完整 HTML 路径时，对应的相对查看路径也会解析到该文件。内部 `turn-start`/`turn-end` 只维持事件顺序、不呈现在界面。
 - Composer 使用贴底的复合输入面板，支持文字、登录后的语音转写，以及粘贴或选择 PNG/JPEG/WebP/GIF 图片；每条消息最多 16 张图片、最多并行上传 4 张。语音录制通过现有 Main-owned Works Speech Host API 转成文字，并在项目或账号切换时立即停止；当前对话的模型与思考强度组合入口、语音及发送/中止入口保留在底部控制行，模型入口默认使用透明底色。模型与思考强度通过向上展开的分级菜单切换，只列出当前 Provider 或 Makelore 已验证模型档案实际支持的选项；Qwen3.6 Plus 使用混合思考开关，Qwen3.8 Max 暴露低/中/高三档并把产品“高”映射到服务端 `xhigh`。模型仅报告 `off` 时明确显示“不可调”，不伪造未知模型的推理档位。切换完成后静默刷新当前 Snapshot，只有真正恢复 worker 时才显示本地 Agent 重连提示。重复读取 Snapshot 不发布无变化的 worker 状态；Snapshot 与 SSE 批次竞态时，Renderer 会丢弃已覆盖事件并只应用连续的新尾部，避免形成伪重连循环。上下文接近模型限制或发生溢出时由 Pi 自动整理，Composer 不提供手动整理入口；自动整理的进度和结果仍显示在对话过程轨道中。图片在发送前只保留本地预览，点击发送时才经 Main-owned 有界二进制接口上传一次；Main 在落盘前核对 MIME 与最小图片签名，状态与事件只保存 attachment id，时间线按需读取二进制并创建临时 object URL，不保存重复 base64。智能体报告 `changed-file.v1` 后，输入框上方会展示当前轮次的文件数与增删行统计，并可展开查看 Main-owned 变更快照中的逐文件差异。
 - Makelore 在应用侧按 Session 独立提交、跟踪和隔离运行状态，不使用“当前对话正在回复”的全局界面锁；同一 Session 的后续消息仍按顺序排队。最终产品中的 Pi 运行时会通过受控 Provider-shaped 回环 smoke 验证同一 Agent Server 内多个 Conversation 逻辑线程的重叠执行、状态隔离、凭证引用隔离、单线程关闭和 Server 崩溃后重启，以及独立子 Agent 进程的隔离与回收；真实外部 Provider 的并发、限流、协议兼容和凭证隔离仍是独立风险，未执行真实 Provider 验证时不得标记为 Pass。