@bryanhu/codexly 0.39.1 → 0.40.0

package/dist/web/index.html

@@ -7,7 +7,7 @@
     <meta name="theme-color" content="#181818" media="(prefers-color-scheme: dark)" />
     <link rel="icon" href="/favicon.svg?v=4" type="image/svg+xml" />
     <title>Codexly</title>
-    <script type="module" crossorigin src="/assets/index-WWY-Ngf-.js"></script>
+    <script type="module" crossorigin src="/assets/index-BUna2uyD.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-B0Z9INg1.js">
     <link rel="modulepreload" crossorigin href="/assets/initial-deps-CqwWvUnY.js">
     <link rel="modulepreload" crossorigin href="/assets/react-runtime-CMZHB3u8.js">
@@ -17,11 +17,11 @@
     <link rel="modulepreload" crossorigin href="/assets/initial-deps-DZ-sH4cr.js">
     <link rel="modulepreload" crossorigin href="/assets/initial-deps-BeVJyoJH.js">
     <link rel="modulepreload" crossorigin href="/assets/initial-deps-CRaxZAOH.js">
-    <link rel="modulepreload" crossorigin href="/assets/scheduled-task-floating-ui~index~workbench-shell~workbench-inspector-changes~project-source~gjk7lcx5-ClgveiMa.js">
+    <link rel="modulepreload" crossorigin href="/assets/scheduled-task-floating-ui~index~workbench-shell~workbench-inspector-changes~project-source~dp1dands-ClgveiMa.js">
     <link rel="modulepreload" crossorigin href="/assets/initial-deps-DFOart6r.js">
-    <link rel="modulepreload" crossorigin href="/assets/initial-deps-n_ZBS3cC.js">
-    <link rel="modulepreload" crossorigin href="/assets/initial-deps-DG--jjIA.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BPQs_vk8.css">
+    <link rel="modulepreload" crossorigin href="/assets/initial-deps-CilSILfP.js">
+    <link rel="modulepreload" crossorigin href="/assets/initial-deps-CyMAtgCd.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-CB0Jmx2g.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/README.md

@@ -0,0 +1,49 @@
+# Codexly 文档
+
+Codexly 支持 Codex 与 Claude，提供桌面应用、电脑 Web 和移动浏览器三种使用方式。移动端连接 Web 服务，项目与智能体运行在提供服务的电脑上。
+
+[产品首页](../README.md) · [English README](../README.en.md) · [下载桌面版](https://github.com/BryanHoo/Codexly/releases)
+
+## 安装与第一次使用
+
+| 你想做什么                             | 中文                                            | English                                                    |
+| -------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
+| 选择使用端、连接智能体并创建第一个任务 | [首次使用](getting-started.md)                  | [Getting started](getting-started.en.md)                   |
+| 安装、更新或卸载桌面应用               | [桌面安装指南](../desktop/docs/installation.md) | [Desktop installation](../desktop/docs/installation.en.md) |
+| 启动 Web、连接手机或配置局域网访问     | [Web 与移动端](web.md)                          | [Web and mobile](web.en.md)                                |
+| 让 Web 服务在登录系统后启动            | [Web 登录自启动](web-autostart.zh-CN.md)        | [Web startup at login](web-autostart.md)                   |
+
+## 日常使用
+
+- [工作台使用](usage.md) · [Workspace guide](usage.en.md)：项目、任务、队列、分屏、文件、扩展与定时任务。
+- [Git 操作](git-workflow.md)：差异审阅、提交、远端同步、分支与 worktree，含英文说明。
+- [文本编辑](text-file-editing.md)：保存、文件限制与冲突处理。
+- [全局搜索](global-search.md)：项目、任务、消息与文件搜索。
+- [常见问题](faq.md)：本地数据、跨端使用、连接失败与更新。
+
+## 智能体与数据参考
+
+以下文档也包含实现细节，日常使用可先读首次使用与工作台指南。
+
+- [智能体引擎与连接](agent-engines.md)：Codex / Claude 的配置来源、能力边界及扩展范围。
+- [模型与思考强度](model-discovery.md)：模型目录、Claude 模型映射与能力来源。
+- [模型上下文窗口](model-context-window.md)：两种引擎的窗口和自动压缩设置。
+- [本地目录与任务](local-catalog.md)：同机共享数据、旧数据导入与配置目录。
+- [会话加载与性能](conversation-performance.md)：历史与执行过程按需加载。
+- [定时任务执行边界](scheduled-task-idempotency.md)：不确定结果与清理恢复。
+
+## 问题排查
+
+Web 先查看启动终端，按需运行 `codexly doctor`；桌面端可在「设置 → 关于」导出诊断材料。先确认出错的使用端和智能体，再按[常见问题](faq.md)排查。[桌面诊断日志](../desktop/docs/diagnostics.md)提供进一步分析方法。
+
+[问题反馈](https://github.com/BryanHoo/Codexly/issues) · [安全漏洞私密报告](../SECURITY.md) · [更新日志](../CHANGELOG.md)
+
+## 开发与维护
+
+- [贡献指南](../CONTRIBUTING.md)：源码开发、验证、文档维护与提交约定。
+- [桌面源码开发](../desktop/docs/development.md) · [English](../desktop/docs/development.en.md)。
+- [三端与双引擎能力参考](../desktop/docs/codexly-capability-matrix.md)。
+- [桌面运行时分发](../desktop/docs/provider-runtime-management.md)。
+- [联合发布](releasing.md)。
+
+`codex-*-upgrade.md`、带日期的测试报告、架构调研及迁移记录保留当时的背景和验证结果，不作为当前安装或能力说明。当前行为以使用指南、能力参考与对应版本的更新日志为准。

package/docs/agent-engines.md

@@ -8,6 +8,8 @@ Codexly 通过应用自己的任务目录保存聊天身份，新聊天可以选
 
 Web（含移动端）继续使用服务端依赖和原有初始化流程，浏览器不下载桌面执行文件。两端共用配置面板、模型能力、选择器和会话逻辑。
 
+日常使用先读[首次连接](getting-started.md)与[工作台指南](usage.md)；本文维护原生配置与实现边界。移动端是连接 Web 服务的浏览器界面，不是独立执行端；桌面应用不自动提供 LAN 服务，手机接入需另行[启动 Web 局域网模式](web.md#移动端与局域网访问)。macOS Legacy 桌面包仅支持 Codex。
+
 Claude 仅提供 API 配置：填写服务地址和密钥。官方地址为 `https://api.anthropic.com`；兼容服务必须支持 Anthropic Messages 协议，保存时自动检测 API Key 或 Token 认证，无需手动选择；检测要求服务提供 `/v1/models` 接口。应用不提供 Claude 账号登录。
 
 初始化点击“连接并开始使用”，设置页点击“保存连接”。输入和失焦不会保存密钥。普通模型与权限偏好自动保存。完成连接配置不能代替真实请求对密钥、额度及模型权限的验证。
@@ -53,7 +55,23 @@ Web 与桌面端的 Claude 模型选择仅显示 `Haiku`、`Sonnet`、`Opus`，
 
 权限模式是 Claude 的工具授权策略，不等于 Codex 的操作系统沙盒。会话级授权只能采用 SDK 返回的具体授权建议，不能把批准一个命令扩大成批准整类工具。当前会话的权限模式可在运行时切换，复用存活查询；SDK 主动退出计划模式等权限变更会同步到两端界面，失败时保留已确认状态并显示错误。
 
-Web 服务先启动本地目录与 HTTP，首次使用 Codex 功能时才启动其执行进程和读取模型目录。已初始化且仅启用 Claude 的用户，即使 Codex 执行文件不可用，也能启动 Web、查看历史并对话。未启用 Codex 时隐藏依赖它的搜索和扩展入口；在设置中启用后恢复。
+Web 服务先启动本地目录与 HTTP，首次使用 Codex 功能时才启动其执行进程和读取模型目录。已初始化且仅启用 Claude 的用户，即使 Codex 执行文件不可用，也能启动 Web、查看历史并对话。全局搜索按已启用引擎分别检索，Claude 历史使用应用摘要，不要求启动 Codex；扩展中心仍可进入并默认显示 Claude。详见[搜索边界](global-search.md)。
+
+### 扩展中心
+
+Codex 与 Claude 的 Skills、MCP 和官方插件统一使用紧凑列表、搜索、筛选和范围标识；安装、移除与开关按条目反馈状态。Codex 插件支持行内安装，点击名称查看能力，需要授权时保留授权入口；实际可用操作以各引擎原生接口为准。
+
+两种引擎共用全局／项目选择。Codex 项目 MCP 根据官方配置层显示，写入接口只允许修改全局配置，因此项目项只读并提供说明。Claude 列表按栏目和项目缓存，刷新后重读；大目录只挂载视口附近的条目，切换栏目不会反复初始化整个目录。
+
+Web 与桌面端共用精简的扩展列表，分别管理 Codex 和 Claude，切换分类不会切换引擎。Claude 的范围选择包含全局与当前项目；Skills、MCP 只显示所选范围的配置。项目 MCP 包含项目共享与项目私有定义，不混入全局配置。
+
+- **MCP**：读取已有的用户、项目共享和项目私有配置；支持按项目启停及按来源范围移除。本次不提供新增 MCP。开关表示配置是否启用，不代表实时连接状态。配置列表不回传地址中的凭据或环境变量值。
+- **Skills**：发现用户 `skills/` 和项目 `.claude/skills/`；开关通过官方 `skillOverrides` 保存可见性，不修改原始 `SKILL.md`。在项目中操作时写入项目私有设置。插件中的 Skills 通过所属插件管理。
+- **官方插件**：同步 `anthropics/claude-plugins-official`，通过同版本官方 CLI 安装、启停、更新和卸载。插件的下载、依赖和缓存由 Claude Code 管理，不直接改写安装登记文件。列表中的“官方”指官方维护的目录。
+
+配置变更后，新建会话以完整加载扩展。管理页面按需读取数据，不启动推理会话或主动连接所有 MCP 服务；Web 的配置位于服务所在的电脑。
+
+官方依据：[MCP 作用域与启停](https://code.claude.com/docs/en/mcp)、[Skills 可见性设置](https://code.claude.com/docs/en/skills#override-skill-visibility-from-settings)、[插件 CLI](https://code.claude.com/docs/en/plugins/cli-reference)。
 
 ## 定时任务
 
@@ -88,7 +106,7 @@ Claude 的 Write/Edit 成功返回后，使用实际结果中的文件路径和
 - 父回合 `result` 结束本轮回复，后台子代理仍可继续执行。后续回合复用存活的查询，后台结果更新创建它的原回合；没有前台或后台工作连续 30 秒后释放进程。实际 CLI 是否先返回父结果取决于任务类型与运行模式，不能由此推断所有后台任务的消息顺序。此生命周期遵循官方[流式输入](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode)与[子代理](https://code.claude.com/docs/en/agent-sdk/subagents)契约。
 - 运行中的 Claude 会话在下次发送前，通过 SDK 动态控制应用模型、思考强度和权限模式，无需重建查询，后台任务继续运行。未变化的参数不重复发送控制请求；控制失败时不发送新消息，重试只应用尚未成功的变更。连接凭据、项目配置加载来源和结构化输出 Schema 等启动配置仍需重建查询，后台工作存活时要求先停止后台工作。
 - 独立停止接口：Web 使用 `POST /v1/projects/:projectId/tasks/:taskId/session/stop`（要求幂等键），桌面使用 `stop_task_session`。参数包含 `taskId`，可选 `backgroundTaskId`：指定时仅停止该原生后台任务，省略时停止整个会话；不要求父回合仍在运行。子代理工具输出中的 `nativeTaskId` 是原生后台 ID。
-- 扩展中心原有安装管理仍属于 Codex。Claude 可以按设置加载项目配置；此次没有增加 Claude 扩展安装管理器。
+- 扩展中心按引擎分别管理原生扩展。Claude 使用官方 CLI 管理官方插件；两端共用界面与范围选择，扩展只在进入对应栏目时读取。
 - 执行上下文保留在官方 SDK 会话中。界面历史按记录保存到磁盘，内存只保留最近的有界投影，运行中定期写检查点。主回合超出展示缓存后不再追加“已省略较早执行记录”；Web 和桌面端均可在中栏顶部点击“加载更早记录”，先补齐同一回合的记录，再继续更早回合。每页最多 100 条记录并受字节预算限制，刷新或重启宿主后仍可续页。检查点恢复不会把异常退出伪装成成功。单条超长正文、工具结果和嵌套子代理输出仍保留有界预览；预览不会裁剪 SDK 实际工具参数或改变执行结果。旧版已从展示历史中丢弃的记录不能由新索引恢复。
 
 ### 资源与分发

package/docs/conversation-performance.md

@@ -0,0 +1,37 @@
+# 会话加载与性能 / Conversation Loading and Performance
+
+本文说明当前 Codexly 的会话加载与资源管理行为，适用于 Codex / Claude 任务，以及 Web（含移动端）和 Windows、Ubuntu、macOS 桌面应用。引擎历史读取细节可不同，界面共用按需加载和有界渲染策略。
+
+This document describes current conversation loading and resource management for Codex and Claude tasks across Web (including mobile) and Windows, Ubuntu, and macOS desktop apps. Engine history adapters differ, while the interface shares on-demand loading and bounded rendering.
+
+## 会话历史 / Conversation History
+
+打开任务时优先读取最近回合的问题与最终答复摘要，每页最多 10 个回合。顶部「加载更早历史」每次只读取一页更早回合，不加载回合内部的过程条目。展开某个回合的过程后独立读取执行条目，分页历史每次最多读取该回合的 100 个条目，支持继续加载与失败重试，不改变问题与最终答复的顺序；保留审查结果和条目耗时，长过程内容限制在当前分屏内。旧格式历史仍按回合读取完整过程，过程入口同样按需加载。分页是读取方式，不会删除磁盘上的历史记录。
+
+Opening a task loads summaries of recent questions and final answers, with up to 10 turns per page. The top history control loads one page of earlier turns without fetching their internal execution details. Expanding a turn’s process loads its details independently, with up to 100 items per page for paginated history and controls to load more or retry failures, while keeping questions and final answers in order. Review results and item timings are preserved, and long process content stays within the current pane. Legacy history reads the complete process by turn, also only when expanded. Pagination changes how history is read; it does not delete history on disk.
+
+## 代码与 Markdown / Code and Markdown
+
+两端共用代码查看器，按需加载语法模块并分批高亮，长代码按可见行渲染。完整代码的 UTF-8 大小超过 128 KiB 时使用纯文本，仍可查看和复制完整源码。流式 Markdown 保留增量内容，尾块异步收尾；正文的动画订阅与稳定内容分离，减少重复渲染。
+
+Both editions share a code viewer that loads grammars on demand, highlights in batches, and renders visible lines for long code. Code whose complete UTF-8 source exceeds 128 KiB uses plain text while retaining the full source for viewing and copying. Streaming Markdown retains incremental content and finalizes its tail asynchronously. Animation subscriptions are isolated from stable content to reduce repeated rendering.
+
+## 缓存与后台更新 / Caches and Background Updates
+
+非活跃任务快照最多保留 12 份，估算容量预算为 48 MiB；超过任一限制就释放最久未使用的非活跃快照，单份超预算快照直接释放。活跃任务不计入此预算，因此它不是整个应用的内存上限。重新打开被释放的任务会重新读取历史。
+
+The cache retains at most 12 inactive task snapshots within an estimated 48 MiB budget. Exceeding either limit evicts the least recently used inactive snapshots; a snapshot that exceeds the entire budget is released immediately. Active tasks are outside this budget, so it is not a total application memory limit. Reopening an evicted task reads its history again.
+
+两端在页面或 WebView 隐藏时继续提交已收到的任务事件，避免仅依赖动画帧导致后台状态停滞。空闲任务不保留事件提交的周期定时器。
+
+Both editions continue committing received task events while the page or WebView is hidden, preventing background state from stalling on animation-frame scheduling. Idle tasks do not retain periodic event-flush timers.
+
+## Web 多设备与传输 / Web Devices and Transport
+
+连接同一 Web 服务的浏览器与设备通过变更通知同步项目待办与异步问答。后台页面只将相关缓存标记为失效，恢复可见后读取最新状态；首次连接和断线重连也会校准。该机制不在独立 Web 服务与桌面应用之间同步本地数据。
+
+Browsers and devices connected to the same Web server synchronize project todos and asynchronous questions through change notifications. Hidden pages mark related caches stale and fetch current state when visible again. Initial connections and reconnections also refresh state. This does not synchronize local data between independent Web servers and desktop apps.
+
+Web 事件批次限制数量与 UTF-8 字节数，并对慢客户端施加发送缓冲限制。不可发送的超大事件会触发客户端读取快照恢复状态。搜索连接关闭后取消后续扫描与在途 RPC；历史附件在有界后台工作线程中落盘，每个任务的通知保持顺序。
+
+Web event batches are bounded by both count and UTF-8 size, with send-buffer limits for slow clients. An oversized event triggers snapshot recovery on the client. Closing a search connection cancels subsequent scans and pending RPC reads. History attachments are persisted by a bounded worker pool while preserving notification order within each task.

package/docs/faq.md

@@ -0,0 +1,63 @@
+# 常见问题
+
+[文档导航](README.md) · [首次使用](getting-started.md) · [Web 与移动端](web.md)
+
+## 桌面、Web、移动端是什么关系？
+
+桌面版是 macOS、Windows 和 Ubuntu 上的独立应用，内置运行时；Web 版通过 npm 启动本地服务。移动端是 Web 的小屏浏览器界面，不是独立安装包。桌面应用不自动开启局域网服务，需要手机访问时另行启动 `codexly start --lan`。
+
+## 只使用 Claude 可以吗？
+
+可以。聊天、项目、公共设置、Git 提交说明生成与定时任务不要求配置或启动 Codex。macOS Legacy 安装包除外，该版本只支持 Codex。已创建任务的引擎固定，要换引擎请新建任务。
+
+## Claude 怎么登录？
+
+应用不提供 Claude 账号登录。可复用主机上受支持的 Claude Code 认证，或填写支持 Anthropic Messages API 与 `/v1/models` 的服务地址和密钥。连接检测成功仅表示模型列表可读取，不保证模型调用权限、额度或计费可用。详见[连接指南](getting-started.md#claude)。
+
+## 为什么模型或思考强度没有显示？
+
+先确认当前引擎已经配置，连接地址、认证和模型权限有效。Codex 根据原生模型目录显示模型与支持的思考档位；兼容目录未声明推理能力时不会猜测，菜单可能隐藏。Claude 显示 Haiku / Sonnet / Opus，网关模型 ID 通过映射配置；思考档位以 SDK 报告为准。详见[模型参考](model-discovery.md)。
+
+## 文件和对话保存在哪里？会上传吗？
+
+项目文件位于运行 Codexly 的电脑上。应用数据在该系统用户的 `~/.codexly`，Codex 原生配置与会话默认在 `~/.codex`，Claude 默认在 `~/.claude`。引擎目录可分别由 `CODEX_HOME`、`CLAUDE_CONFIG_DIR` 改写。
+
+“本地工作台”指应用存储与执行位置，不表示离线模型。任务相关请求和上下文仍会发送到所配置的模型服务，MCP 和插件也按各自配置访问外部服务。
+
+## 桌面与 Web 会共享项目吗？换电脑会同步吗？
+
+同机同一系统用户的桌面与 Web 共用应用项目、任务和历史。手机访问 Web 主机的同一份数据；另一台电脑没有自动云同步。界面草稿、分屏偏好不保证跨设备同步，共享存储也不等于同一个运行会话可被两个进程同时控制。
+
+`--codex-home` 只改变 Codex 自身配置、历史和旧数据导入位置，不隔离 `~/.codexly`。详见[本地目录与任务](local-catalog.md)。
+
+## 怎么备份和迁移？
+
+退出桌面应用并停止所有 Web 服务后，备份 `~/.codexly`、实际使用的 Codex / Claude 配置与历史目录，以及项目文件。它们可能包含密钥和对话内容，应妥善保存。恢复后还需确认项目绝对路径、操作系统认证及系统钥匙串可用；仅复制应用目录不保证跨系统凭据和执行上下文可以直接使用。
+
+## 手机为什么打不开？
+
+确保使用 `--lan` 启动，手机与主机在同一可信局域网，并使用终端输出的局域网地址，而不是 `127.0.0.1`。检查主机是否休眠、服务是否仍运行、端口是否被防火墙阻止，以及 Wi-Fi 是否启用设备隔离。端口占用会自动递增，请以实际输出为准。
+
+服务重启后需要重新登录；普通 LAN 启动的随机密码会改变，自启动服务保存的密码可用 `codexly autostart credentials` 查看。不要为解决访问问题将服务直接暴露到公网。
+
+## 关闭窗口后任务和计划还会运行吗？
+
+浏览器页面不是执行主机；只要电脑唤醒且 Web 服务仍运行，关闭页面不会等于关闭服务。桌面版要区分最小化到托盘与真正退出；真正退出应用或停止 Web 服务后，不能继续处理任务或触发计划。具体运行状态以应用为准，休眠不会自动唤醒执行计划。
+
+定时任务显示结果不确定时，先查看关联会话确认实际结果，再删除并重建计划，避免重复执行。
+
+## 如何更新？Windows 便携版只换 EXE 可以吗？
+
+侧栏出现新版本后点击版本号，或到「设置 → 关于」检查更新。Web 全局安装也可重新运行 `npm install --global @bryanhu/codexly@latest`。
+
+Windows 便携版必须关闭应用并用新版 ZIP 的完整解压目录替换旧目录，保留主程序、Claude 宿主和 `runtime`。只换 EXE 会造成资源缺失或版本不匹配。macOS Legacy 与 Modern 有独立更新渠道，升级系统后需手动安装 Modern 才会切换。
+
+## 卸载会删除项目和历史吗？
+
+移除桌面应用或 npm 包不会自动删除项目，也不会清空共享的 `~/.codexly`。删除应用数据会影响同机其他 Codexly 使用端。清理前先备份并停用 Web 登录自启动；系统日志与缓存位置见[桌面安装指南](../desktop/docs/installation.md)。
+
+## 怎样反馈问题？
+
+请提供应用版本、系统及架构、桌面 / 电脑 Web / 移动浏览器、Codex / Claude、复现步骤与脱敏错误。Web 查看启动终端，必要时运行 `codexly doctor`；桌面在「设置 → 关于」导出诊断 ZIP，分析方法见[诊断指南](../desktop/docs/diagnostics.md)。原始 ZIP 留在本地，仅提交必要的脱敏片段。
+
+普通问题提交到 [Issues](https://github.com/BryanHoo/Codexly/issues)；漏洞请按[安全策略](../SECURITY.md)私密报告。

package/docs/getting-started.en.md

@@ -0,0 +1,54 @@
+# Get started with Codexly
+
+[Documentation](README.md) · [简体中文](getting-started.md)
+
+Choose a client, connect Codex or Claude, and start your first task in a local project.
+
+## Choose a client
+
+- **Desktop**: download from [Releases](https://github.com/BryanHoo/Codexly/releases) and follow [installation](../desktop/docs/installation.en.md). Runtimes are bundled; no separate Node.js, Bun, or CLI is needed. macOS Legacy supports Codex only.
+- **Computer browser**: install Node.js 24+, run the command below, and open the printed local address.
+- **Phone or tablet**: add `--lan` to the command on your computer, then open the printed LAN address on your mobile device and enter the password. See [Web and mobile](web.en.md).
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start
+```
+
+Desktop opens directly into the workspace; configure connections in Settings. Web provides first-use setup. Supported existing local configurations are recognized. You can configure just one agent and add the other later.
+
+## Connect an agent
+
+### Codex
+
+Use ChatGPT sign-in or configure a compatible API URL and key. Custom services must support the OpenAI Responses API and a model list. Select a model available through that connection; reasoning options follow its reported capabilities.
+
+### Claude
+
+Reuse supported Claude Code credentials on the host computer, or enter a service URL and key in Claude connection settings. The official API URL is `https://api.anthropic.com`; compatible services must support Anthropic Messages and `/v1/models`. Click the connection or save button to save credentials; typing or leaving the field does not submit them.
+
+In-app Claude account login is unavailable. Connection checks read the model list without a generation request; success does not verify inference credits or every model permission.
+
+Choose Haiku, Sonnet, or Opus. For gateways using custom model IDs, configure their mappings in Claude agent settings; official connections can usually leave mappings empty. Claude-only setups support conversations, common settings, Git commit message generation, and schedules without Codex configuration.
+
+### Where settings apply
+
+Desktop reads the local user's configuration. Web and mobile change configuration on the Web host, not on the browser device. Default directories are `~/.codex` and `~/.claude`, overridden by `CODEX_HOME` and `CLAUDE_CONFIG_DIR` respectively.
+
+Credentials, model access, and charges belong to your chosen provider. Codexly includes no model credits. Relevant project content is sent to that service as part of agent execution.
+
+## Start a task
+
+1. Add a folder as a project in the sidebar. Mobile selects a folder on the Web host.
+2. Open the project and create a task. Choose Codex or Claude in the composer when both are available; a single configured engine is selected automatically.
+3. Select a model and permissions. Permission semantics differ by engine; confirmation-based modes help you inspect operations.
+4. Describe a concrete goal, such as “Explain how this project starts and find its test entry points.” Attach files, reference project files with `@`, or Skills with `$` as needed.
+5. Follow execution and respond to approvals or questions. Review code changes in the Changes panel before committing.
+
+Use **New task** for a conversation without a project. Existing tasks keep their engine; create a new task to use the other agent.
+
+## Next steps
+
+- [Workspace guide](usage.en.md): steering, queues, panes, files, and schedules.
+- [Git workflow](git-workflow.md): branches, worktrees, commits, and pushes; includes English instructions.
+- [FAQ (中文)](faq.md): connections, shared data, and updates.
+- [Agent reference (中文)](agent-engines.md): native configuration, permissions, and extensions.

package/docs/getting-started.md

@@ -0,0 +1,54 @@
+# 首次使用 Codexly
+
+[文档导航](README.md) · [English](getting-started.en.md)
+
+目标：选择使用端，连接 Codex 或 Claude，用本机项目完成第一个任务。
+
+## 选择使用端
+
+- **桌面应用**：从 [Releases](https://github.com/BryanHoo/Codexly/releases) 下载安装包，按[安装指南](../desktop/docs/installation.md)打开。运行时已内置，无需另装 Node.js、Bun 或 CLI；macOS Legacy 仅支持 Codex。
+- **电脑浏览器**：安装 Node.js 24+，运行下方命令，打开终端显示的本机地址。
+- **手机和平板**：在电脑上使用下方命令并加上 `--lan`，再用移动浏览器访问终端显示的局域网地址、输入密码。完整步骤见 [Web 与移动端](web.md)。
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start
+```
+
+桌面端打开后直接进入工作台，在设置中配置连接；Web 首次使用时按初始化界面完成配置。已有受支持的本机配置会被识别。你可以只配置一个智能体，之后再添加另一个。
+
+## 连接 Codex 或 Claude
+
+### Codex
+
+在 Codex 连接设置中选择 ChatGPT 登录，或填写兼容服务的地址与密钥。自定义服务需支持 OpenAI Responses API 和模型列表。保存后选择服务实际提供的模型，模型和思考档位随当前连接变化。
+
+### Claude
+
+可复用运行 Codexly 的电脑上已有的受支持 Claude Code 凭据，也可在 Claude 连接设置中填写服务地址与密钥。官方 API 地址为 `https://api.anthropic.com`；兼容服务需支持 Anthropic Messages API 和 `/v1/models`。点击连接或保存按钮才会保存密钥，单纯输入或失焦不会提交。
+
+应用内不提供 Claude 账号登录。连接检测读取模型列表，不发送生成请求；检测成功不代表已经验证调用额度和全部模型权限。
+
+模型选择使用 Haiku、Sonnet、Opus 档位。使用网关且实际模型 ID 不同时，在 Claude 智能体设置中配置模型映射；官方连接通常可以留空。只配置 Claude 也可使用聊天、公共设置、Git 提交说明生成与定时任务，无需配置 Codex。
+
+### 配置在哪台设备上生效
+
+桌面应用读取本机用户配置；电脑与移动浏览器操作 Web 服务所在电脑的配置，而非浏览器所在设备。Codex 默认使用 `~/.codex`，Claude 默认使用 `~/.claude`；指定 `CODEX_HOME` 或 `CLAUDE_CONFIG_DIR` 时使用对应目录。
+
+密钥、模型权限与额度由所用服务管理。Codexly 不包含模型额度，项目中与任务相关的内容会按智能体行为发送给模型服务。
+
+## 创建第一个任务
+
+1. 在侧栏添加一个电脑上的文件夹作为项目。手机访问时选择的也是 Web 主机上的目录。
+2. 打开项目并新建任务。两种引擎都可用时，在输入区选择 Codex 或 Claude；只有一种时自动使用该引擎。
+3. 选择模型，按需要调整权限。不同引擎的权限语义不同，先使用需要确认的模式更便于检查操作。
+4. 输入明确的目标，例如「解释这个项目的启动方式，并找出测试入口」，再发送。可以添加附件、用 `@` 引用项目文件、用 `$` 引用 Skills。
+5. 查看输出与工具执行过程，处理出现的审批或问题。修改代码后，在变更面板审阅差异，再决定是否提交。
+
+无需项目时，可从「新建任务」开始临时对话。已有任务的引擎固定；希望使用另一种引擎时请新建任务。
+
+## 继续使用
+
+- [工作台使用](usage.md)：补充指令、消息队列、分屏、文件与定时任务。
+- [Git 操作](git-workflow.md)：分支、worktree、提交与推送。
+- [常见问题](faq.md)：连接失败、数据共享与更新。
+- [智能体技术参考](agent-engines.md)：原生配置、权限和扩展的详细边界。

package/docs/global-search.md

@@ -0,0 +1,49 @@
+# 全局搜索
+
+Web（含移动端）与桌面端共用搜索契约，支持任务标题、可见历史和项目文件。
+
+## 引擎与数据源
+
+两端按当前可用的引擎集合筛选：Web 使用初始化后的启用状态，桌面使用原生连接配置识别结果，传递 `engines=codex`、`claude` 或 `codex,claude`。单引擎不查询另一个引擎，双引擎按本地 `updatedAt DESC, id DESC` 综合搜索；旧客户端省略筛选时默认包含两种引擎。任务名称、固定与归档状态以应用目录为准，正文检索按持久化 provider 身份路由。
+
+| 来源        | 实现                                                                | 定位                                       |
+| ----------- | ------------------------------------------------------------------- | ------------------------------------------ |
+| 标题        | 应用目录先按引擎、标题与归档状态过滤，再分页；不启动引擎            | 打开任务                                   |
+| Codex 历史  | `thread/searchOccurrences`；仅 `-32601` 时回退可见消息分页匹配      | 官方 inclusive 游标                        |
+| Claude 历史 | Web/桌面复用已有问题与最终答复摘要检索；不创建 SDK 会话或模型请求   | 原消息 ID、回合 ID 与摘要页 inclusive 游标 |
+| 文件        | Web 使用 Node 扫描，桌面使用 Rust `ProjectFileSearch`，均独立于引擎 | 内部预览或系统打开                         |
+
+Claude 官方文档公开会话列举与消息读取，未给出与 Codex 等价的全文检索接口；本项目因此检索应用的可见摘要。摘要仅负责展示，执行上下文始终由官方 SDK 管理。历史不检索推理、工具输出或过程答复，文件搜索不检索源码正文。
+
+## 分页与故障
+
+- 标题每页 30 条；历史每批最多检查 10 个本地候选，并发上限 4，候选仅取首个精确命中。无匹配的候选页自动继续读取，直到找到命中、出现部分故障或范围耗尽，不能把较早任务误报成无结果。
+- 综合游标绑定查询、类别、归档与引擎集合；切换依赖重置弹窗分页和定位状态，Query key 同时包含引擎集合。
+- 单引擎失败保留健康源命中，通过 `unavailableEngines` 返回失败源，界面提示部分结果加载失败；精确匹配保留错误，取消不能转成部分成功。
+- 精确匹配每页最多 30 条。Claude 续查绑定任务、查询与摘要页，记录页内命中偏移；新回合到来不改变固定的续查位置。Codex 兼容路径与 Claude 共用 UTF-16 匹配范围及摘要截取函数。
+- 跳转以 `summary: true` 读取 inclusive 页，使用独立只读 Store，禁止覆盖实时任务 Store。定位失败保留结果并报错，不把任务首页当作命中。
+- 消息身份变化时，仅在同回合完整摘要唯一匹配后重新绑定，禁止只按关键词误跳。保留消息级高亮与现有虚拟列表定位，高亮不改变消息尺寸。
+
+## 性能与取消
+
+- 输入防抖 180ms，中文组合输入期间不查询；关闭弹窗取消请求并保留窗口内结果和滚动位置，不写磁盘、不轮询。
+- Claude 只分页读取摘要，不读取工具正文或完整 transcript。旧格式按已有规则补建摘要，稳定读取不另建全文索引或监视器。
+- HTTP 断连传播取消信号；桌面通过宿主 `cancelId` 在摘要页之间停止后续 I/O，不中断同宿主对话。有界队列饱和时取消帧为尽力交付，不承诺中断已开始的单次磁盘或官方内部操作。
+- 文件搜索使用大小写不敏感的相对路径子串匹配，最多两个并发扫描、50 条结果；跳过符号链接、隐藏文件、生成目录和项目 `.gitignore`/`.ignore` 匹配项。
+- 文件索引单根最多 16 MiB，总计最多 32 MiB/8 根，TTL 5 秒；超预算仍扫描目录尾部，只保留排序最前的 50 个命中。Web 定期释放 ignore 匹配缓存，不新增常驻监视器。
+- 文件预览与系统打开复用既有根目录授权；前端明确提示文件结果截断。
+
+## 官方依据
+
+- [Codex App Server](https://developers.openai.com/codex/app-server)：结合固定的 0.163.0 协议与 `.local/project-paths.json` 指向的官方本地源码验证接口。
+- [Claude 会话文档](https://code.claude.com/docs/en/agent-sdk/sessions)：会话列举、消息读取与持久化；本项目 SDK 固定为 0.3.300。
+- [node-ignore](https://github.com/kaelzhang/node-ignore)：使用 Git ignore 语义处理项目忽略规则。
+- [TanStack Query 请求取消](https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation)：查询函数消费 `AbortSignal`。
+
+## 验证
+
+- 根目录与桌面目录分别运行 `pnpm check`。
+- `pnpm test:claude-host` 覆盖真实独立宿主重启后的搜索及定位，并断言搜索无新增模型请求。
+- `src/cli-claude-start.test.ts` 覆盖真实 HTTP、SQLite、单/双引擎选择、Codex 离线与部分故障。
+- `catalog-search.test.ts`、Claude `global-search.test.ts` 及 Rust `application/catalog_search.rs` 测试覆盖聚合、归属、取消和分页。
+- 浏览器交互调试使用 Chrome DevTools MCP，通过 CDP 连接用户正在运行的 Chrome；自动测试不替代跨平台实机验收。

package/docs/local-catalog.md

@@ -18,7 +18,29 @@ Codexly 是目录、任务及其管理状态的唯一数据源。Web 和桌面
 | 对话正文与执行上下文 | 对应引擎                    | 通过适配器按需读取、恢复和分叉                           |
 | 导入标记             | managed_catalog_migration   | 与全部导入记录在同一事务提交                             |
 
-Web 使用现有的 `CODEX_HOME/codexly/state.sqlite3`，保持现有安装与隔离参数兼容；桌面端使用应用数据目录中的 `catalog.sqlite3`。两者共用 `packages/protocol/src/local-catalog-schema.json` 的表定义。Web 数据库操作在 SQLite Worker 执行，桌面端在阻塞池执行，流式通知不读取完整任务目录。
+Web 与桌面端在同一台电脑、同一系统用户下共用 `~/.codexly/state.sqlite3`，同时共用 `engines/claude` 历史投影目录。`CODEX_HOME` 和 `--codex-home` 仅决定 Codex 引擎的原生配置、会话位置及旧数据发现，不再决定应用数据位置。Codex、Claude 自身的配置与认证仍由官方引擎维护。
+
+| 平台    | 应用数据目录             |
+| ------- | ------------------------ |
+| macOS   | `/Users/<用户>/.codexly` |
+| Ubuntu  | `/home/<用户>/.codexly`  |
+| Windows | `%USERPROFILE%\.codexly` |
+
+Node 使用 [os.homedir()](https://nodejs.org/api/os.html#oshomedir)，桌面端使用 [Tauri homeDir](https://v2.tauri.app/reference/javascript/api/namespacepath/#homedir) 对应的原生接口，禁止拼接启动目录或通过系统应用数据目录创建第二份业务数据。引擎安装资源、操作系统登录服务登记、平台日志与可再生缓存仍遵循对应平台的专用目录。
+
+两端共用 `packages/protocol/src/local-catalog-schema.json` 的表定义及 `app-storage-migration.json` 的导入 SQL。Web 数据库操作在 SQLite Worker 执行，桌面端在阻塞池执行；WAL、外键、5 秒 busy timeout 和短事务支持同机多进程访问，不增加后台同步轮询。切回窗口时，两端共用的恢复逻辑只使项目、任务、归档和置顶列表失效，后台不读取聊天正文。
+
+## 应用目录升级
+
+升级前退出旧版本的 Web 服务和桌面应用，再分别启动新版本。首次启动发现 `CODEX_HOME/codexly`、默认 `~/.codex/codexly` 和旧 Tauri 应用目录（macOS Application Support、Ubuntu XDG 数据目录、Windows Roaming AppData）。已经迁移的目录以目标数据库内的标记判断；不再反复导入旧记录。
+
+- 若目标数据库尚不存在，使用 SQLite 的 [VACUUM INTO](https://www.sqlite.org/backup.html) 创建旧 Web 数据库的一致快照，包含 WAL 中已提交的数据。通过同目录临时文件和不覆盖目标的原子发布，避免并发启动替换已打开的数据库。
+- 在共享事务内合并旧桌面目录与任务，并提交对应源目录的完成标记。保留目标目录中已有的管理状态；按规范化路径合并项目，同 provider/sessionId 的会话不重复创建。Windows 扩展路径前缀统一为普通路径；保留实际大小写与路径分隔符。
+- 项目 ID 合并时复制对应附件、任务偏好及项目默认值到合并后的身份；已存在的目标文件优先。Claude 历史和其索引复制到共同的引擎目录。旧数据库、旧文件及已过时缓存保留在原位置，方便恢复；不复制活动 SQLite 的 db/wal/shm 文件组合。
+- 文件复制或数据库约束失败时不标记该源完成，下次启动可重试。完成标记与导入记录在同一事务内；迁移后删除的任务不会在后续重启时复活。
+- Web v34 通过数据库触发器维护旧设置、队列等业务表的外键投影。因此桌面端直接创建或删除目录时，Web 的关联写入仍有效。
+
+这属于同机共享存储。远程浏览器使用 Web 服务所在电脑的数据，不在浏览器设备上建立第二份数据库。
 
 公共 Project 暂时保留 `roots` 数组的传输形状，但输入、输出协议均要求恰好一项。两端选择器共用单选函数，选择新文件夹会替换旧选择。Git worktree 仍是任务的执行工作区，不增加项目根目录。
 

package/docs/model-context-window.md

@@ -1,4 +1,10 @@
-# 本机通用上下文窗口
+# 模型上下文窗口
+
+桌面、Web 与移动端按引擎分别配置上下文。Web 与移动端操作服务所在电脑，桌面端操作本机；两种引擎的数值范围和压缩设置不同。窗口声明不会扩大模型或服务商的真实容量。
+
+[文档导航](README.md) · [Claude 上下文管理](#claude-上下文管理)
+
+## Codex 上下文窗口
 
 在「设置 → 智能体配置 → 模型默认设置」中编辑「上下文窗口」。数字框以 **k tokens（千 tokens）** 为单位，填写 **272–1000 的整数**，例如 `400` 表示 400k，`1000` 表示 1M。失焦或按 Enter 保存；留空恢复模型默认值，Escape 取消当前输入。输入框与上方选择框统一为 160px 宽、32px 高，并靠右对齐；窄屏宽度受容器限制。
 
@@ -10,7 +16,7 @@
 
 Codexly 不联动写入 `model_auto_compact_token_limit`：该字段有独立的默认值与限制，由 Codex 处理。如果已经在其他客户端配置过自动压缩阈值，它仍按 Codex 的配置规则生效。
 
-## 实现契约
+### 实现契约
 
 - 全局协议字段 `modelContextWindow` 为 `null` 或 `1..Number.MAX_SAFE_INTEGER` 的整数，两端共用相同 Schema 边界。
 - 两端 UI 只接受空值或 272–1000 的整数，提交前乘以 1000；协议保留官方配置的整数兼容范围。
@@ -19,11 +25,11 @@ Codexly 不联动写入 `model_auto_compact_token_limit`：该字段有独立的
 - Codex 配置是权威来源；窗口不在 SQLite 或桌面应用偏好文件中维护第二份配置，也不进入项目默认值或回合参数。
 - 两端共用 `ModelContextWindowInput` 和输入解析函数；编辑期间只维护组件草稿，提交合法值后复用全局设置保存队列。
 
-## 验证
+### 验证
 
 `runtime-default-settings.test.ts` 和 `global-default-settings.test.ts` 验证 HTTP 端的保存、清空、缓存刷新及非法值拒绝；`model-context-window.test.ts` 验证输入边界；桌面 `context_window_should_*` 验证原生配置往返和应用偏好文件隔离。
 
-## 官方依据
+### 官方依据
 
 - [配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)：`model_context_window` 与自动压缩阈值定义。
 - [配置基础](https://learn.chatgpt.com/docs/config-file/config-basic)：用户配置目录与配置优先级。

package/docs/model-discovery.md

@@ -1,8 +1,12 @@
 # 模型与思考强度
 
-Web、移动端和桌面端均以 Codex App Server 的 `model/list` 为首选来源。按照返回的 `supportedReasoningEfforts`、`defaultReasoningEffort`、`isDefault` 和可见性展示模型，不维护模型名或思考档位白名单。
+桌面端、电脑 Web 与移动浏览器按当前任务的引擎展示模型；两种引擎分别读取能力，不共用模型白名单或凭据。日常连接步骤见[首次使用](getting-started.md)。
 
-## 账号与自定义 API
+## Codex 模型来源
+
+Codex 任务均以 Codex App Server 的 `model/list` 为首选来源。按照返回的 `supportedReasoningEfforts`、`defaultReasoningEffort`、`isDefault` 和可见性展示模型，不维护模型名或思考档位白名单。
+
+### 账号与自定义 API
 
 - 官方账号：使用当前账号的原生目录及 Codex 自身的认证和目录缓存策略；失败时不复用自定义 API 的目录。
 - 自定义 API：优先读取按当前配置创建的原生目录，失败或为空时尝试兼容 `/models`，再使用同一端点的持久化快照。重新连接后使用新认证刷新原生能力。
@@ -10,17 +14,27 @@ Web、移动端和桌面端均以 Codex App Server 的 `model/list` 为首选来
 - 明确声明的 `none` 表示关闭推理，与未声明能力不同。`xhigh`、`max`、`ultra` 以及未来字符串均按目录原值保留。
 - 手动命名可以覆盖展示名，不能清除已经取得的原生能力。切换端点不能复用旧凭据、旧目录地址或旧账号模型。
 
-## 原生目录配置
+### 原生目录配置
 
 `base_url` 是推理地址，`model_catalog_url` 可以是独立的目录地址。同端点重新连接和目录准备均保留用户配置的目录 URL。原生 Codex 会添加 `client_version`，处理 Provider 认证与目录协议；应用不自行复刻这套发现流程。`model_catalog_json` 的优先级仍由 Codex 决定。
 
 保留目录 TTL 缓存、并发请求合并、响应大小和超时限制；不添加后台轮询或逐模型能力请求。
 
-## 验证
+### 验证
 
 共享样例位于 `packages/provider-codex/src/custom-model-catalog-fixtures.json`，由 TypeScript 与 Rust 测试同时读取。运行相关模型目录测试、协议测试、会话提交测试及两端类型检查。实际本机验证只读取目录，不创建付费推理回合。
 
-## 官方依据
+### 官方依据
 
 - [App Server model/list](https://learn.chatgpt.com/docs/app-server#list-models-modellist)：从返回数据读取模型能力和默认值。
 - [自定义网关目录](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#serve-a-remote-catalog)：目录地址、完整元数据、认证与版本参数。
+
+## Claude 模型、映射与思考强度
+
+Claude 使用官方 SDK 提供的模型能力，任务选择器展示 Haiku、Sonnet、Opus；默认模型设置还可选择“自动”。官方服务通常将模型映射留空，由 Claude Code 解析推荐版本。兼容网关使用实际模型 ID 时，在 Claude 智能体设置中配置对应映射，不通过 Codex `/models` 推测能力。
+
+可将服务商提供的模型 ID 映射到任一档位；只有一个模型时也可将三个档位映射到同一 ID。清空恢复默认解析，已有原生 `availableModels` 白名单仍生效。连接验证需要 Anthropic Messages 兼容服务的 `/v1/models`，只读取目录，不验证生成额度。
+
+思考强度只显示 SDK 声明支持的档位，未知能力不猜测；切换模型清除不再受支持的档位。宿主环境变量可能覆盖配置，设置页显示覆盖来源。Web 与移动端修改服务所在电脑的配置，桌面端修改本机配置。
+
+映射、权限、配置优先级和验证入口详见[智能体引擎](agent-engines.md#模型映射与思考强度)；上下文容量和自动压缩见[上下文设置](model-context-window.md#claude-上下文管理)。

package/docs/scheduled-task-idempotency.md

@@ -0,0 +1,28 @@
+# 定时任务写接口幂等约定
+
+创建、更新、删除、启停及立即运行接口必须携带非空 `Idempotency-Key`，缺失或空字符串返回 `400`。列表、事件订阅和预览不需要该请求头。内置客户端的写请求已自动携带该请求头；调用方重试同一次操作时必须复用原 key，新操作应生成新 key。
+
+服务端统一使用 `runIdempotent`：
+
+- 同一操作、同一任务及同一 key 的并发请求共享进行中的执行；成功后的重试复用首次响应内容和状态码，不再次写入或启动 Agent。
+- 创建、更新和启停使用完整的已校验请求体生成指纹；同一作用域及 key 携带不同参数返回 `409 IDEMPOTENCY_CONFLICT`。创建的作用域为全局创建操作，更新、删除、启停和立即运行按操作及 `taskId` 隔离。删除和立即运行没有业务请求体，以 `{}` 作为指纹输入。
+- 立即运行复用的是首次接受请求时的任务快照；即使后台运行已结束，重试也不会再次启动。读取当前状态应调用列表接口。
+- 业务错误保持原有 `400`、`404`、`409` 映射；失败结果不缓存。失败可能发生于部分副作用之后，因此失败后重试不代表端到端“恰好一次”。进行中请求达到容量上限时返回 `503 IDEMPOTENCY_CAPACITY_EXCEEDED`。
+
+## 有效范围与重启边界
+
+幂等记录仅保存在当前 Server 实例的内存中。默认成功结果有效期为完成后 **10 分钟**，最多缓存 **1,000 条**，与其他使用该 runner 的接口共享容量；可通过 `idempotencyTtlMs`、`idempotencyCacheSize` 配置。容量淘汰可能提前结束保护。进行中请求不受成功结果 TTL 淘汰。
+
+Server 关闭、进程崩溃或重启后，幂等记录丢失；多个 Server 实例之间也不共享记录。定时任务及运行历史的持久化不等于请求 key 的持久化，因此跨重启或缓存淘汰后的同 key 重试可能再次创建或执行任务。响应丢失且超出保护范围时，应先核对任务列表及运行历史，不能把盲目重试视为安全操作。
+
+本约定采用请求标识、参数冲突校验和响应复用的接口设计原则，参考 [AWS：Making retries safe with idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)。当前实现不承诺跨重启的持久化幂等或 Agent 工作的端到端恰好一次执行。
+
+## 运行恢复与实例所有权
+
+多个 Web 实例可共享同一数据目录。SQLite 仓储在读取最新快照、修改状态和领取运行期间使用短暂的跨进程互斥；Provider 调用期间释放互斥，其他实例仍可正常读写。运行归属记录防止新实例把存活进程的运行误判为崩溃恢复，进程退出后由操作系统释放短期锁，失效的运行归属在后续检查中清理。实例每五秒检查其他实例的计划变更，本实例创建或修改的计划仍按最近截止时间唤醒。
+
+嵌入 Server 时，共享仓储必须提供 `withScheduledTaskLock` 及运行归属方法；没有这些方法的自定义仓储只能由一个调度服务拥有。上述协调不扩展 HTTP 请求 Key 的幂等范围。
+
+每次已领取的运行使用 `scheduled:<runId>` 保存独立持久提交阶段，与上述 HTTP 请求 Key 的内存缓存不同。已确认启动的结果先持久化，再清理附件；清理或结果写入失败显示 `cleanup_pending`，当前进程与重启恢复只重试收尾。Provider 调用结果无法确认时显示 `unknown`，保留已知 Task，暂停计划并禁止再次运行或启用；查看关联对话后可删除旧计划并重新创建。
+
+HTTP Key 重启后仍不保留：已完成运行后的新一次请求可能创建新 runId，本机制不承诺跨重启 HTTP 幂等或 Agent 的端到端恰好一次执行。