minecodex 2.0.8 → 2.0.9

package/packages/cli/native/README.md

@@ -1,49 +0,0 @@
-# Stable MineCodex background host
-
-`MineCodex.app` is the small, universal native owner of MineCodex's macOS
-background item. The npm package ships the built app only; native source and the
-build script remain development inputs.
-
-The production app bundle is intentionally versioned independently from the npm
-package. Its ad-hoc code identity must stay byte-for-byte stable across ordinary
-JavaScript releases because macOS records the helper's designated requirement.
-Do not rebuild or change the bundle for an npm version bump. If native behavior
-must change, plan an explicit signed-helper migration or introduce a new service
-identifier and verify the macOS Background Items upgrade path before release.
-
-Rebuild deliberately with:
-
-```bash
-npm run build:service
-```
-
-## Icon bundle revision 1.0.1
-
-This is an explicit native resource revision: `CFBundleIconFile` now points to
-`Contents/Resources/MineCodex.icns`, bundle version is `2`, and the outer app is
-re-signed. The service host executable remains byte-for-byte unchanged. The
-manager's ad-hoc designated requirement changes when its Info.plist changes.
-The service identifier and launch-agent plist remain unchanged.
-
-The existing `MacPlatformAdapter.installService()` is the migration path: run the
-old installed manager's `unregister` before replacing its bundle; verify the new
-staged bundle; replace it; then register and kickstart the new service. An old
-registration failure aborts replacement. Use `mcx install` / the normal update
-flow; do not copy a new icon or re-sign the installed app in place. System approval
-may be required after re-registration; preserve macOS's decision and existing CLI
-reporting. Real Background Items approval and UI upgrade acceptance must be checked
-on a target installation before release.
-
-The icon uses the filled project mark on a neutral rounded backing so one ICNS
-remains legible in light and dark system surfaces. SVG artwork is generated at
-`assets/brand/minecodex-service-icon.svg` by `npm run build:icons`. Rasterize that
-SVG into an iconset at 16/32/128/256/512px and each size's @2x resolution, then run
-`iconutil -c icns <iconset> -o app-template/Contents/Resources/MineCodex.icns`.
-Commit the resulting template ICNS with any deliberate native artwork revision.
-`npm run build:service` copies it into the built bundle before signing. Ordinary
-JavaScript releases continue shipping the existing signed bundle unchanged.
-
-Validation for this revision: strict deep signature verification, universal
-architectures, ICNS structure and plist checks, system icon loading through
-`NSWorkspace`, installer regressions, and npm package audit. These checks do not
-register a background item or change an installed service.

package/packages/codex-adapter/README.md

@@ -1,16 +0,0 @@
-# Codex 公共环境适配
-
-该私有 workspace 隔离多个插件共同依赖的 Codex Renderer 机制。专有业务协议放在插件的 `src/adapters/codex/`；视觉适配放在 UI 的 `src/native/`。完整层次与文件导航见根 ARCHITECTURE.md 和 AGENTS.md。
-
-`createCodexEnvironment()` 是可显式序列化的工厂，无 Node 闭包和 IO imports。宿主按 Renderer 生命周期创建一个实例，通过 `config.codex` 提供给插件，卸载/重注入时重新创建。
-
-| 接口 | 结果与约束 |
-| --- | --- |
-| `composer(element?, {threadOnly, purpose}?)` | 默认仅可见的 Codex thread 输入框；Prompts 使用 `purpose:"insertion"` 支持 Chat、Work、Codex、Temporary Chat 与面板 chat bar。优先当前焦点所在输入框，并可显式绑定插入目标。返回 editable/root/body/add/threadId；非thread不提供身份，隐藏祖先返回 null |
-| `currentThreadId(element?)` | 从合格输入框取得 UUID；不从残留 sidebar 选中项猜当前线程 |
-| `composerSurface(element?)` | 返回可见正式会话外壳 root/threadId，独立于编辑区是否存在或暂时 inert；供会话状态呈现与宿主统计订阅使用。真正隐藏、移入浮层、切换 home 或卸载时返回 null；不能作为文字插入许可 |
-| `rail()` / `railSlot(ownGroup)` | 可见原生 rail 与模板/滚动区/固定组句柄；不包含插件菜单策略 |
-| `currentFiber(element)` / `props(element,predicate,limit?)` | 仅供 native Adapter 使用；优先匹配当前 committed props，支持最近祖先的 scope |
-| `report(name,available,reason?)` / `diagnostics()` | 最新能力状态的副本；不持有凭据、原始账户数据或用户内容 |
-
-不要增加一个包含所有插件的 CodexGateway。新契约只有在被多个模块实际共用时进入这里。选择器、React 机制改动在本模块验证；插件专有协议改动在所属 Adapter 验证。正常界面不暴露内部诊断。

package/packages/runtime-host/README.md

@@ -1,213 +0,0 @@
-# Codex Runtime Host
-
-本机个人 Codex 功能的统一运行宿主。它是统一 Injector 与生命周期宿主，负责：
-
-- 连接或启动支持 loopback CDP 的隔离 Codex 桌面实例；
-- 从同级项目的 `codex-feature.json` 注册 Sidebar 或 Conversation toolbar 入口；
-- 挂载 full-page、Pinned Summary，并把 Detail iframe Surface 优先注册为 Codex 原生右侧 Task Tab；
-- 把 Codex 当前 resolved Theme Tokens 同步给每个 Surface；
-- 执行经过 manifest allowlist、Surface 身份和 renderer token 校验的 Host actions；
-- 维护共享 CDP、注入与可信通信；插件专有的 Codex 协议由各功能 Adapter 维护。
-
-各功能项目继续拥有自己的数据、HTTP API 与页面。宿主不读取业务数据库；单个
-功能服务失效不会阻止 Codex 或其他功能运行。
-
-## 启动与验证
-
-```bash
-npm start
-npm test
-npm run check:runtime
-```
-
-宿主默认扫描上层目录中的同级项目。只有当 manifest 的 `healthUrl` 返回的 JSON 同时满足
-`ok === true`、`service === feature.id`、`protocolVersion === 1`，且 `instanceId` 等于本次 RuntimeHost
-生成并传给功能进程的 `MINECODEX_FEATURE_INSTANCE_ID` 时，宿主才会复用现有服务。仅仅可达或
-返回 2xx 的 foreign / stale 服务不会被信任；身份不匹配时，宿主会在项目目录执行其
-`command`。可用以下环境变量启动隔离实例：
-
-```bash
-CODEX_FEATURES_ROOT=/path/to/features \
-CODEX_RUNTIME_PROFILE_DIR=/tmp/codex-profile \
-CODEX_RUNTIME_CDP_PORT=9232 \
-MINECODEX_CODEX_EXECUTABLE=/path/to/Codex \
-npm start
-```
-
-## Sidebar / page manifest
-
-旧 manifest 保持兼容；没有 `entry` 时默认仍是 Sidebar：
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "images",
-  "label": "Images",
-  "surfaceUrl": "http://127.0.0.1:47831/",
-  "placement": { "after": "sites", "order": 10 },
-  "command": ["node", "src/main.mjs"],
-  "icon": {
-    "viewBox": "0 0 24 24",
-    "markup": "<rect ...></rect>"
-  }
-}
-```
-
-## Conversation toolbar / responsive summary manifest
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "notes",
-  "label": { "en": "Notes", "zh-CN": "笔记" },
-  "surfaceUrl": "http://127.0.0.1:47832/?surface=summary",
-  "healthUrl": "http://127.0.0.1:47832/api/health",
-  "entry": {
-    "kind": "conversation-toolbar",
-    "ariaLabel": { "en": "Toggle pinned notes", "zh-CN": "切换固定笔记" }
-  },
-  "pinnedSummary": {
-    "label": { "en": "Pinned Notes", "zh-CN": "固定笔记" },
-    "surfaceUrl": "http://127.0.0.1:47832/?surface=summary",
-    "presentation": "responsive-summary",
-    "overlayLabel": { "en": "Toggle notes", "zh-CN": "切换笔记" },
-    "pinnedLabel": { "en": "Toggle pinned notes", "zh-CN": "切换固定笔记" }
-  },
-  "detailTabs": [
-    { "id": "todo", "label": { "en": "Todo", "zh-CN": "待办" }, "surfaceUrl": "http://127.0.0.1:47832/?surface=todo" },
-    { "id": "prompts", "label": { "en": "Prompts", "zh-CN": "提示词" }, "surfaceUrl": "http://127.0.0.1:47832/?surface=prompts" }
-  ],
-  "hostActions": ["insert-text", "attach-file", "open-detail-tab", "open-editor-modal", "resolve-file-paths"],
-  "command": ["node", "src/main.mjs"],
-  "icon": { "resource": "node_modules/lucide-static/icons/notebook-tabs.svg" }
-}
-```
-
-`icon.resource` 必须留在功能项目目录内。宿主读取真实 SVG 的 `viewBox` 与内部
-markup；功能不需要把第三方 SVG 复制进 manifest。
-
-`label`、`entry.ariaLabel`、Pinned Summary 的三个 label 与 Detail Tab label 均可使用
-单个字符串或 `{ "en": "…", "zh-CN": "…" }` locale map。字符串 manifest 保持
-向后兼容；locale map 以 English 为 fallback，并按 Codex 文档语言选择显示文本。
-Host action、feature id 与 detail id 是协议标识，必须保持语言无关。
-
-Conversation toolbar 入口复制原生按钮结构后会规范化交互类：关闭态保持透明并使用
-tertiary icon color，只有真实 hover 或 `data-state=open` 时才使用 Codex 原生
-`list-hover-background`，避免把创建瞬间的原生激活样式固化到功能按钮上。
-Conversation toolbar 的结构遵循原生分组，而不只追求图标顺序：有原生 Summary 时，
-Feature 入口直接加入 Summary 所在的中间功能组并紧跟在 Summary 后；New Chat 尚无
-Summary 时，宿主在中间 toolbar 的右端建立同构的 Summary feature group。可见的
-`Toggle bottom panel` 仅作为 New Chat 状态下定位中间 toolbar 的稳定锚点，Feature 不会
-进入也不会扩宽最右侧的 Bottom Panel / Side Panel 原生组。
-
-## Surface 协议
-
-Surface 发给 Host：
-
-- `codex-personal:ready`
-- `codex-personal:close`
-- `codex-personal:open-thread`
-- `codex-personal:host-action`
-- `codex-personal:surface-metrics`
-
-Host 发给 Surface：
-
-- `codex-personal:theme`
-- `codex-personal:host-result`
-- `codex-personal:surface-active`（`active: true | false`）
-
-`codex-personal:theme` 同时携带标准化后的 `locale`（当前为 `en` 或 `zh-CN`），
-Surface 可用它同步自身可见文案与辅助功能标签。
-Page Surface 每次显示或隐藏时都会收到 `codex-personal:surface-active`；iframe 重新加载后，
-Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的轮询或其他后台工作。
-
-每个 iframe 消息同时校验 `event.origin` 与准确的 `contentWindow`。Host action
-还必须在对应 feature 的 allowlist 中；需要 Node/CDP 的原生动作使用每个 Renderer
-独立的随机 binding token，并按 target 串行执行。功能页面只有收到明确成功结果后
-才能更新“最近调用”等产品状态。
-
-当前 Host actions：
-
-- `insert-text`：替换已保存的 Composer selection/caret；无法恢复时另起一行追加。
-- `attach-file`：用 CDP 填充临时 file input，再把真实 `File` drop 给 Composer；只有
-  观察到原生附件 chip/preview 才报告 `attach`，否则明确返回 `insert-path`。
-- `open-detail-tab`：动态发现当前 Codex React right-panel controller 与当前 Task scope，
-  传入包含 `Component`、`isAvailable`、`kind` 和 `dropDestinations` 的标签描述对象，
-  用稳定的 `featureId-detailId` 聚焦或创建唯一原生 Tab；capability 不可用时返回明确错误。
-- `resolve-file-paths`：通过 Codex preload 暴露的 Electron file bridge 解析 Finder
-  drop 的真实 `File` 对象。
-
-## Adapter 生命周期与故障边界
-
-- 只在 top frame 安装 Runtime，绝不向业务 iframe 注入 binding token。
-- Watch / refresh 串行；已连接 Renderer 不重复连接，关闭 target 会清理状态。
-- 当前 Codex document 始终直接注入或替换 Runtime，绝不通过 CDP reload Codex 页面。
-  本地 Surface 不直接导航到 loopback URL：Host 先创建 `about:blank` iframe，再校验
-  manifest URL、health service/protocol/instance，抓取 HTML 并用 `Page.setDocumentContent`
-  写入目标 frame。Images/Notes 只向精确的 `app://-` Origin 开放 CORS。
-- CDP 重连时同步轮换后的 binding token；保留已就绪的 Surface 和编辑草稿，
-  使用新 token 重试未就绪页面，避免弹窗停留在空白 iframe。
-- 入口由 Renderer 内的 MutationObserver 幂等挂载，React 重绘不会产生重复入口。
-- Summary 根据对话主区域宽度连续派生 `overlay / shift / gutter`：小于 1096px
-  使用临时 Popover；1096–1535px 预留 316px 并把对话内容左移 158px；更宽时
-  放入右侧 gutter 而不移动对话。
-- Popover 与 inline Summary 只占可见矩形，不使用透明全屏 overlay；原生 Portal
-  可以保持更高层级。Surface 上报自然高度，Host 再按窗口可用高度截断，内容组件
-  自己拥有唯一的纵向 scroller。
-- Host 把当前 Codex Summary 的 section title、row type、icon color/size、radius、
-  border、dropdown background 和 elevation tokens 发送给 Surface。
-- 新客户端会话默认关闭；Thread 切换关闭 Pinned Summary 并清除旧 Composer Range。
-- Detail Tab 使用 Codex 当前 `local-thread` scope，因此标签状态跟随 Task；React panel
-  中的 iframe 继续注册同一套可信 Host origin、`contentWindow`、Theme 与 Host-action bridge。
-- Surface 以 `ready` handshake 标记可用。若第一次加载发生在服务离线期间，下一次
-  打开只重新请求 Host 加载这个未 ready 的 frame；已经 ready 的 Surface 不重载、不打断草稿。
-
-## 当前接口分类
-
-| 路径 | 分类 | 说明 |
-| --- | --- | --- |
-| loopback HTTP、manifest、Surface message schema | 项目自有稳定接口 | 可由测试直接覆盖 |
-| `window.electronBridge.getPathForFile` | 当前稳定 internal/preload | 仅用于 Finder `File` 路径解析 |
-| React right-panel `openTab`、Task scope、JSX runtime | private internal capability | 动态发现 bundle 并做能力检测；失败时返回明确的不可用错误 |
-| toolbar、summary、tabs、Composer selectors | DOM inference | 统一留在本 Adapter |
-| `Runtime.addBinding`、`DOM.setFileInputFiles`、注入脚本 | high-risk CDP | 必须使用隔离 profile 验收 |
-| `togglePinnedSummary`、`composer.addFiles` 字符串 | 探索证据 | 当前实现不把它们当契约 |
-
-这是非官方 CDP / DOM Adapter，不是公开的 Codex Contribution API。Codex 更新后按协议所有者修复：共享注入和生命周期归宿主，专有原生组件与 API 归对应插件 Adapter；领域规则与 Web UI不应直接跟随外部协议重写。
-
-
-## 共享弹窗与浮层
-
-通用视觉、原生材质分支、遮罩及层级的权威来源为根 [DESIGN.md](../../DESIGN.md)，内部文件导航见 [AGENTS.md](../../AGENTS.md)。组件库目标与现有实现归属见 [UI 架构](../ui/ARCHITECTURE.md)。本节只说明当前接入契约。
-
-`packages/ui/src/install.mjs` 组装共享组件源码，在 Renderer 中只安装一次，由 page-script 的 `config.ui` 调用：
-
-```js
-config.ui.heading(dialog, { title, closeLabel, onClose, back });
-const actions = config.ui.footer(document.createElement("div"));
-actions.append(config.ui.action(saveButton, "primary"));
-config.ui.overlay(backdrop);
-config.ui.surface(popover); // 只统一材质，保留功能的定位与内容
-```
-
-`heading` 标记 dialog 并创建标题及 Close；`back` 是可选的已有按钮节点。容器宽高、内容、原生 dialog 或自定义焦点管理、关闭后的焦点恢复继续由功能负责。`footer` 只装饰直接子按钮，`action` 的 tone 为 ghost / secondary / primary / danger。不要再在插件中复制背景、阴影、标题和底部按钮规则。
-
-共享组件已迁入 UI workspace。Prompts 与 Sites 管理弹窗选用 opaque / Sites Share；Quick Prompts 使用 ComposerMenu；管理菜单和模型列表选择 Dropdown，Session Status 与任务切换选择 Popover。组件库负责各分支视觉，宿主不复制实现。
-
-page-script 可以用 manifest 的 `entry.resources` 声明本功能内的 CSS/图标资源，宿主读取后通过 `config.resources` 一次传入。JSON 作为数据、其他文件作为文本；越出功能目录的路径会被拒绝。它不改变 host action、服务启动或消息协议。
-
-Images 提示词面板沿用原生 File info 的附属信息面板结构；iframe 页面继续通过宿主接收主题。会话统计与云 Library 业务归所属插件，Runtime Host 只组合业务能力和外部连接。领域规则与架构层参见根 [ARCHITECTURE.md](../../ARCHITECTURE.md)。
-
-`entry.sourceFactory` 可声明本插件内的源码工厂，导出 `createPageScriptSource()` 并返回 Renderer 函数体字符串。工厂路径不能越出插件；纯领域函数由插件工厂序列化，宿主不维护规则副本。Images 使用这一接口共享图片提示词溯源规则。
-
-Model Slider 的模型规则、原生控制器适配和专有呈现位于插件 `src/domain` / `src/frontend`，安装源码由插件工厂组装。宿主仅提供配置、locale、共享 UI、图标与刷新调度，维护 ensure/dispose 接线；原生菜单开合和节点恢复由插件负责。
-
-## 项目控制台入口
-
-Runtime Host 在账号菜单 Settings 下挂载 MineCodex 项目入口，不属于可开关的插件。`minecodex/open-control-panel` 是独立 builtin action，必须通过对应 renderer 的 binding token 验证；它不接受任意 URL 或 shell 参数，固定调用包内 CLI 的 `gui` 命令。组件的项目图标、外链箭头与菜单模板由共享 UI 提供。
-
-CLI 继续通过一次性 browser exchange 打开控制台。macOS 默认 Safari 与 Chrome/Chromium、Edge、Brave、Vivaldi 支持查找现有控制台标签页并激活；没有匹配页才调用系统默认浏览器打开登录地址。自动化权限被拒绝时返回错误，不用重复开页掩盖失败。其他浏览器和 Windows 保留系统 URL 打开行为，目前不保证标签页复用。
-
-### 暂停功能的接入
-
-`codex-feature.json` 的 `disabled:true` 表示保留源码但暂停运行时接入。发现阶段在加载 Adapter、资源和注入源码之前跳过该功能，显式启用 ID 也不能恢复它。Task Toast（`unread-inbox`）于 2026-10-03 暂停；CLI／控制台已移除其注册入口，配置归一化清除旧启用项。恢复时须同时重新评估注入场景并恢复 manifest 与用户入口。

package/packages/ui/DESIGN.md

@@ -1,38 +0,0 @@
-# MineCodex UI 组件库的局部约定
-
-通用视觉与原生适配规则只维护在根 [DESIGN.md](../../DESIGN.md)。内部文档与代码路由见根 [AGENTS.md](../../AGENTS.md)，架构见 [ARCHITECTURE.md](ARCHITECTURE.md)。
-
-本级只负责共享组件自身的结构、接入与实现边界，不维护另一份颜色、字体、材质、遮罩或sidebar规则。
-
-## 当前阶段
-
-`packages/ui` 已建立独立私有 workspace，组件、token、安装源码与验证均在本级维护；实际目录见架构文档。未使用的原生组件分支不会仅因规范列出而预建空壳。
-
-## 组件职责
-
-- 原生适配层：解析实际token、主题、zoom和能力状态；共享锚点仅包含真实跨插件需求。原生事实遵循根规范，不在每个组件重新猜测。
-- 材质与层级基础：按Dialog、Dropdown、Popover、ComposerMenu、Page的原生分支提供有限选项，将遮罩与Portal规则同所选组件匹配。
-- Dialog：提供容器、标题、Close及操作区的结构；插件填表单、列表或确认内容。
-- Button：通过 `action(node, "danger-solid")` 提供原生实色警戒分支，保留既有 `danger` soft 分支；通用 token 与适用规则见根 DESIGN.md。表达操作角色和状态，保留Cancel ghost、实际次级outline与主操作solid的语义区分；业务动作由插件传入。
-- Navbar：使用成对 default/selected 图标管理展示状态；原生图标与选中状态适配集中在 native 层，保留原生路由与 sidebar hover。退出注入页面时按当前 committed 原生状态恢复选中属性，不回放进入时的旧状态；原生目的地变化时及时移除替身图标，原节点复用或重渲染后仍保证只显示一个图标。
-- Tooltip：处理声明式标记、hover/focus、aria关联、关闭与卸载，不接管原生Tooltip。
-- Page 的 `sidebar:"none"` 分支通过 native/page Adapter 取得原生无上下文侧栏页面壳；`releasePage` 释放时区分返回原页面和用户主动导航，禁用时清理。
-- 页面、菜单与浮层：提供对应类型的外壳、挂载和通用交互，不读取提示词、会话或站点业务数据。
-
-## 接入约束
-
-当前page-script通过 `config.ui` 使用公共能力；现有API包括 `heading`、`footer`、`action`、`overlay`、`surface`。`surface(node, kind, options)` 显式区分原生材质；`page`、`mount`、`trapFocus`、`composerMenu`、`tooltipSurface`、`navigationRail` 维护实际复用的层级、焦点与定位。`entry.resources` 通过 `config.resources` 提供插件自身 CSS 与图标，通用视觉仍由组件库维护。
-
-独立全页面且无专属二级导航的功能使用 `config.ui.page(node, { sidebar:"none" })`。移除页面前调用 `config.ui.releasePage(node)`；若用户正在主动选择原生导航，则传 `{ restoreNavigation:false }`，避免恢复动作覆盖用户选择。`sidebar:"none"` 页面通过 `onNavigate` 接收原生路由提交后的退出通知；一级、二级和程序化导航共用该契约，悬浮展开与加载中的通知不关闭页面。Adapter 在通知前取消路由订阅并放弃恢复旧位置，功能回调负责移除内容与恢复自身状态。默认 `sidebar:"inherit"` 保留现有接入行为，不自动迁移其他功能。页面壳的产品规则与验收标准见根 DESIGN.md 的「全页面功能的页面壳选择」。
-
-Renderer安装函数经序列化注入，必须自包含。组件代码与Node/CDP隔离，宿主负责组装注入源码、生命周期和iframe主题桥；不为整理目录引入不必要的打包系统。
-
-通用生命周期契约由组件库维护。原生已经提供的焦点圈定、Escape和关闭机制优先复用；插件继续拥有业务状态、内容更新和具体回调。迁移时同步触发点焦点恢复、异步卸载及原生节点归属验证。
-
-## 验证边界
-
-组件验证关注可注入性、结构与回调、状态清理、挂载/焦点以及所选原生类型的实际行为，不镜像每条CSS写实现测试。布局、材质和原生状态变化按风险做隔离验收；只移动文件时验证导入、序列化、发布名单与已有功能回归。
-
-## 账号菜单接入
-
-`accountMenuEntry({label, icon, externalIcon, onOpen})` 通过 native/account-menu Adapter 获取原生 Settings 模板与关闭句柄。组件只修改脱离 React 的副本，负责重建去重、相邻键盘导航与卸载；回调拥有打开动作，组件不读取控制台 token 或浏览器状态。通用位置与视觉规则见根 DESIGN.md。