@bryanhu/codexly 0.39.1 → 0.41.0

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 的端到端恰好一次执行。

package/docs/text-file-editing.md

@@ -0,0 +1,97 @@
+# 文本文件编辑方案
+
+## 选择
+
+采用 **CodeMirror 6**，由 `packages/ui` 提供共享编辑器，Web（含移动浏览器）与 Tauri 桌面复用。文件访问走现有 HTTP / Tauri 原生边界。评估日期：2026-10-10。
+
+| 方案                            | 适配本项目的判断                                                                                   |
+| ------------------------------- | -------------------------------------------------------------------------------------------------- |
+| CodeMirror 6                    | 模块化、可视区域渲染、增量文本状态，支持按语言异步加载；适合现有多端、低占用目标，选用。           |
+| Monaco                          | IDE 能力丰富，但官方明确不支持移动浏览器；当前需要文本编辑，额外语言服务和 Worker 管理成本不划算。 |
+| textarea / contenteditable 自研 | 初始开销小，但需自行维护查找替换、撤销历史、选择和输入法兼容；长期成本高。                         |
+| 富文本编辑器                    | 本次需要无损编辑代码与文档源码，不需要 Word 或富文本模型。                                         |
+
+依据：[CodeMirror 系统指南](https://codemirror.net/docs/guide/)、[API 参考](https://codemirror.net/docs/ref/)、[官方扩展示例](https://codemirror.net/examples/)、[Monaco 官方 FAQ](https://github.com/microsoft/monaco-editor#faq)。指南明确描述了 viewport 渲染、不可变状态、按帧安排测量，以及卸载必须调用 `EditorView.destroy()`；实现遵循这些生命周期约束。
+
+## 行为与边界
+
+项目文件的源码预览直接作为编辑区域，不再使用编辑弹窗或额外编辑工具栏。Markdown 沿用已有的渲染 / 源码切换；源码模式直接编辑，不支持编辑的文件继续只读预览。
+
+- 支持项目根目录及已验证 worktree 内的 UTF-8 文本，包含空文件和带 BOM 的文件。适用于代码、Markdown、JSON、YAML、XML、SQL、普通文本等。
+- JS/TS/JSX/TSX、JSON、Markdown、Python、Rust、HTML、CSS、YAML、SQL、XML 提供按需语法；其余文本可以编辑，使用纯文本显示。
+- 单文件最大 2 MiB，输入事务按保存后的 UTF-8 字节数校验（含 BOM、CRLF、中文及代理对）；超限粘贴或输入整笔拒绝，原正文、选择与撤销历史不变。保存和读取边界继续独立检查。正文超过 256 KiB 时在同一事务中停用解析，缩小后恢复；异步语言加载完成须重查当前大小。超限文件保留已有分页预览。
+- 保留 LF / CRLF 与 UTF-8 BOM；粘贴文本匹配当前换行。为避免隐式改写，混合换行、孤立 CR、无效 UTF-8 和二进制拒绝编辑。
+- Word / Office、PDF、图片等不进入文本编辑。符号链接、`.git` 路径、项目外路径不可写；现有项目外只读引用不扩大为编辑权限。
+- 当前入口要求明确的项目 `rootPath`。无项目根目录的临时聊天和外部引用保持预览。首版不提供新建文件、另存为、编码转换、LSP 或自动格式化。
+- 提供撤销重做和 `⌘/Ctrl+S`；正文失焦、切换窗口 / 标签页、离开文件时自动保存。输入期间不逐键写盘，没有查找替换与独立编辑工具栏。保存成功或失败通过 toast 提示，仅显示文件名；编辑受限、读取失败、超限输入或保存失败时，还须在文件面板内显示常驻原因与恢复动作，不能只依赖短暂 toast；成功文案为“xxx 文件已保存”，默认同行，宽度不足时自动换行。
+- 保存链串行执行，合并重复失焦；保存期间的新输入使用回执版本继续补存，全部完成才提示成功。失败和外部冲突保留草稿，不强制覆盖磁盘。
+- 面板关闭、Markdown 模式切换、页面内路由和桌面辅助窗口关闭先等待保存，失败则保持原位置。直接切换文件或卸载时补存；失败草稿仅在当前窗口内存保留，重新打开相同文件恢复；保存成功后解除草稿退出保护，会话进入有预算的闲置缓存。页面退出保护当前及保留草稿，应用退出提示包含未保存编辑；草稿不持久化，强制退出、崩溃、刷新后放弃退出提示不保证恢复。
+
+## 数据与存储
+
+共享契约：`ProjectTextFile { path, content, version, revision? }`，`SaveProjectTextFileRequest { path, content, expectedVersion }`，保存只返回新版本与可选修订标记，不回传全文；旧边界缺少修订标记时重开会安全回退到完整读取。
+
+- HTTP：`GET /v1/projects/:projectId/files/text?rootPath=…&path=…`；`POST` 同一路径，查询参数携带 `rootPath`。
+- 桌面：`read_project_text_file` / `save_project_text_file`；先验证项目/worktree 根目录，再进行严格路径检查。主窗口与独立文件窗口显式授权。
+- 版本为原始 UTF-8 字节的 SHA-256。服务端读取完整且有界的快照；保存前校验版本，写同目录临时文件、同步磁盘、复验版本和目标，再原子替换。
+- 同文件保存串行，不同文件可并行。Rust 在 `spawn_blocking` 中执行读写/哈希，Node 使用异步文件 I/O；完成后释放锁引用。
+- `TEXT_FILE_CONFLICT`（HTTP 409）与 `TEXT_FILE_UNSUPPORTED`（HTTP 400）为可识别错误。认证、Host 检查、请求限制继承已有服务交付层。
+- 版本比较与文件替换并不是操作系统级 CAS：不协作的外部程序在最终复验与替换之间仍存在极短竞争窗口。这里提供常规乐观并发保护，不能声称可以锁住任意外部编辑器。
+
+## 性能约束
+
+编辑器只在打开可编辑源码预览时下载，加载编辑器模块后先检查共享会话，再决定是否完整读取；语言解析器独立拆包。输入状态留在 CodeMirror 的持久化文本树，React 只接收布尔状态，不逐键拼接全文，不逐键发 HTTP / IPC，不后台轮询。
+
+有项目根目录的文本文件先走共享编辑会话读取，等待期间只显示加载状态，不并行读取分页预览或渲染只读代码块。Markdown 渲染按需取用同一会话正文，切回源码复用已有文本树，不再次读取全文；可编辑正文不另存到分页 Query 缓存。不可编辑、超限或编辑器加载失败时才启用原有分页回退；没有项目根目录的外部引用继续只读分页。
+
+保存仅提交一次完整文本。2 MiB 上限下，全文提交比补丁协议更易校验和恢复；未来若支持更大文件或高频协作，再引入增量协议。编辑文本不进入全局 Query 缓存；共享会话缓存按客户端对象隔离，用弱引用管理生命周期，键包含项目、根目录和文件路径。每个客户端最多保留 16 个闲置会话，按文本树、保存快照与累计历史估算 64 MiB 的保留预算；超额按 LRU 淘汰闲置已保存会话。活动会话、正在保存的状态和失败草稿受保护，可以超出闲置缓存预算，不能为了容量丢弃未保存修改。另设页面全局编辑/草稿容量预算：最多 16 个活动或未保存文件、32 MiB UTF-8 正文预留，每个文件在读取前预留完整 2 MiB，所有客户端/项目共用，重复打开及在途读取只占一份；满额的新文件回退分页只读并提示先处理已有草稿。失败读取或闲置且已保存时归还预留，已有草稿重开不受满额影响。闲置未保存会话释放撤销历史、视图绑定与解析状态，复用正文文本树并保留选择、滚动、换行与保存版本。正文预留与缓存估算不是 JS 堆上限，`history({ minDepth: 30 })` 也不是字节级内存限制。保存后只失效对应文件预览与所属根目录 Git 状态。
+
+预览内编辑构建测量：编辑器主异步资源约 301.5 kB 原始 / 98.1 kB gzip；这不包含按需语言包和所有共享依赖。Web 初始静态闭包约 293 KiB gzip，仍满足 320 KiB 预算。桌面工作区/Markdown 场景预算分别调整为 1,560,000 / 2,040,000 字节，新增完整编辑场景 2,050,000 字节预算；首屏和单异步资源上限保持原值。
+
+状态层实测：本机 Node 24 上，2,097,137 字节文档执行 1,000 次同长度局部替换约 29.6 ms，GC 后保留堆增长约 8.24 MiB。该数据包含状态构造与修改，不包含 DOM、WebView 和网络，不能代替真实输入延迟测量。
+
+## 验证
+
+- Node 文件操作：编码、BOM、CRLF、权限、超限、路径与符号链接、外部修改、删除、并发保存。
+- HTTP / 客户端：Schema、错误、读取及条件保存；原生客户端验证命令和参数。
+- Rust：相同文本与并发安全边界，完整 Clippy / 单测。
+- 编辑状态：保存快照隔离、撤销后的未保存状态、换行保留；独立性能测试测量近 2 MiB 文档的 1,000 次状态编辑。
+- Web、桌面与 legacy 桌面构建、静态检查、性能预算通过。桌面 484 项测试通过；Rust 712 项单测通过（10 项忽略），Clippy、集成与性能基线通过。预览内编辑版本的 Web 全量回归 2,099 项通过（20 项跳过），桌面 484 项通过，状态与既有性能回归 15 项通过。
+- 使用 `chrome-devtools-mcp --autoConnect` 经 CDP 连接运行中的 Chrome，在共享组件测试页验证中文文本输入、失焦保存及 toast、CRLF 保留、保存期间继续编辑、失败保留草稿与重试、切换文件恢复草稿、不可编辑文件回退只读预览。测试页使用内存文件服务，真实磁盘边界由 Node / Rust 测试覆盖。
+- Chrome 390 × 844 移动与触摸仿真下无页面横向溢出；45,000 行 / 855,000 字节文本开启纯文本模式，初始仅渲染 64 行，滚动到底部后渲染 65 行，控制台无错误。该数据验证可视区域渲染，不代表实体移动设备输入延迟。
+- 实体设备触摸、中文 IME 组合输入和各平台原生 WebView 仍需真机验收，未标为通过。
+
+### 预览内编辑回归
+
+- 自动保存状态测试覆盖不逐键写盘、无修改不保存、失焦合并、保存期间输入、失败重试、版本冲突、切换文件恢复草稿及保存后解除草稿保护。
+- 导航测试验证先等待保存，失败保持当前页，成功继续导航；复制入口读取当前编辑内容。
+- 使用 Chrome DevTools MCP 的独立共享组件测试页检查真实 DOM 失焦、toast、正文直接编辑和文件切换；测试服务为内存文件，文件系统写入边界沿用上一轮验证。
+
+### 分屏会话复用
+
+- 右栏仍只挂载活动分屏，卸载时销毁 `EditorView`，保留会话的持久化文本树、选择和滚动快照；已保存会话继续保留撤销历史和语言状态，闲置未保存草稿则执行容量压缩。重新挂载只重配视图回调，不将全文序列化为字符串再建树；卸载清除视图闭包，避免缓存持有已销毁 DOM。
+- 同一文件的首次加载及重新校验均合并在途请求。短暂失焦不取消共享读取，切回来等待同一结果；预算淘汰时中止可取消请求。桌面客户端在 IPC 启动前（含等待运行时期间）检查 AbortSignal；已经进入操作系统的同步读取不能强制取消，结果由共享缓存复用。
+- 每次重新激活已保存会话，HTTP `GET /v1/projects/:projectId/files/text/revision?rootPath=…&path=…` 或原生命令 `read_project_text_file_revision` 只检查元数据并返回 `{ revision }`；修订标记变化才重新读取全文。未保存草稿与正在保存的会话直接复用，后续保存仍进行 SHA-256 冲突校验。
+- 修订标记绑定完整读取的快照及原子保存回执。Node 使用设备号、inode、大小、纳秒 mtime/ctime 与创建时间；Rust 使用大小、修改/创建时间，以及 Unix 的设备号、inode 和纳秒 ctime，Windows 增加原生文件属性与时间字段。元数据检查是缓存失效机制，不替代正文 SHA-256：文件系统时间精度、Windows 上刻意恢复同长度文件时间等情况可能使标记保持相同，保存仍会拒绝实际正文冲突。校验失败或文件删除时不展示旧的已保存编辑状态。
+- 使用 Chrome DevTools MCP 经 CDP 连接运行中的 Chrome，在真实共享组件、活动分屏卸载规则的内存服务验证页中，四屏切换 12 次，全文读取从修复前 13 次降至 4 次（每份文件首次各 1 次），另有 9 次元数据检查；连续重挂 3 次仍为 4 次全文读取。该页面验证共享挂载流程，磁盘与 IPC 边界分别由 Node/Rust/客户端测试覆盖。
+- 自动回归覆盖条目/字节预算、活动和失败草稿保护、在途读取合并、外部版本变化、元数据变化但正文相同、校验失败重试，以及文本树、CRLF、选择和撤销历史保留。
+
+本轮验证：Web 全量 2,113 项通过（20 项跳过），桌面前端 489 项通过；Rust 全量 713 项通过（10 项忽略）及集成测试通过，最后的回执变更另做文本文件专项验证。两端类型检查、Lint、Rust Clippy、Web/桌面/legacy 构建及资源预算通过。Chrome 中保存后切屏保留同一文本树和选区、撤销成功；外部变更新增 1 次全文读取，1,000 行文件的滚动位置在重挂前后均为 1,200 px。原生 WebView 与 Windows/Ubuntu 真机未在本轮验收。
+
+### 输入与异常草稿容量回归
+
+- 共享状态测试覆盖精确 2 MiB 边界、超限输入不进入文档/撤销历史、UTF-8 多字节与 CRLF、孤立代理及跨变更边界的代理对，并用确定性 Unicode 编辑与实际序列化字节数比较。
+- 解析测试覆盖输入增大时同步降级、缩小后恢复，以及语言异步加载完成时正文已超阈值的竞态。
+- 容量测试分别覆盖条目与正文字节预算、跨客户端共享、满额时不读取新文件、已存草稿恢复、失败读取归还预留、并发打开共用名额和保存后释放容量。
+
+本轮容量验证：Web 全量 2,132 项通过（20 项跳过），桌面前端完整检查通过（489 项测试，含常规与 legacy 构建及资源预算）；最终共享专项含边界检查 30 项通过。Chrome CDP 的真实粘贴事件验证约 2.4 MiB 中文粘贴整笔拒绝，288 KiB 正文同步停用解析、撤销后恢复；390 × 844 触摸仿真验证 270 KiB 正文降级及撤销恢复，无横向溢出、控制台错误。浏览器验证使用内存保存服务；原生 WebView 和实体 IME 未在本轮重新验收。
+
+### 编辑受限提示与恢复
+
+- 容量满、编辑器加载失败与不支持编辑的文件须说明只读原因，以及仍可查看/复制正文；容量满与临时加载失败提供“重试编辑”，无需关闭或重新打开文件。重试期间保留只读正文与说明，按钮显示进度并禁用重复提交；成功后原位恢复编辑。
+- 超限输入说明是编辑后的文件会超过 2 MiB，整笔输入未应用、原内容未变、仍可继续编辑；提供减少粘贴量/删除部分正文的建议。提示可主动确认，并在下一次有效正文修改后解除。
+- 保存失败或冲突随会话保留原因，提供“重试保存”；成功才清除保存失败提示。超限提示解除后仍须显示此前的保存失败，不能覆盖未解决的错误。冲突重试仍遵循 expectedVersion，禁止强制覆盖。
+- 大正文解析降级说明高亮暂停、仍可编辑和保存，缩小后自动恢复；只在阈值变化时更新提示，不逐键复制正文或重渲染 React。
+- 两端复用 `core/text-editor-notice` 与同一份中英文文案。Chrome CDP 验证实际容量满的常驻原因、恢复编辑、保存失败与按钮重试、超限后继续输入、读取失败原位恢复，以及 390 × 844 布局无横向溢出。组件测试覆盖各原因、动作及可访问提示，保存状态测试覆盖提示保留与解除。
+
+提示功能验证：Web 全量 2,142 项通过（20 项跳过），桌面 489 项测试及 `check:web` 通过；两端类型、Lint、架构、常规/legacy 构建与资源预算通过。共享专项 39 项通过，Chrome CDP 验证常驻提示、原位恢复、按钮保存重试及移动布局。

package/docs/usage-statistics.md

@@ -0,0 +1,51 @@
+# 用量统计
+
+在 **设置 → 用量统计** 查看 Codex 与 Claude 的实际 Token 用量。Web、移动浏览器与桌面共用页面；同一台主机上的 Web 和桌面共用 `~/.codexly/state.sqlite3`，不会因切换客户端重复累计。
+
+## 页面
+
+- 年度热力图：颜色表示当天已记录的总 Token 数，可切换年份和引擎。
+- 总量、活跃天数与单日峰值采用等宽等高概览卡片；月度趋势与引擎占比保持统一边界与间距。
+- 点击热力图或使用图内日期选择器查看当天任务，按用量展示前 50 项；有实际分类或已选日期时才展开明细区。
+- 统计口径收在默认折叠的“统计说明”中。仅在引擎实际提供分类字段时展示明细；`—` 表示未提供，`≥` 表示只有部分活动提供了该分类。
+- 日期统一按 UTC 归属，手机上的热力图可独立横向滚动，默认定位到最近日期。键盘可使用方向键、Home 和 End 浏览日期，Enter 选择。
+
+统计反映应用观测到的实际新增用量，**不代表订阅剩余额度、费用或官方账单**。功能不会扫描历史会话来回填旧记录。
+
+## 数据口径
+
+### Codex
+
+消费 `thread/tokenUsage/updated` 的 `tokenUsage.total` 累计值，以原生会话 ID 持久化计数水位；首次使用 `total - last` 建立旧记录基线，随后只累计实际增长。重复、迟到的旧通知不重复计数。
+
+优先使用实际返回的 `totalTokens`，只有输入与输出均存在时才允许将二者相加。Codex 的 `inputTokens` 包含 `cachedInputTokens`，展示输入明细时扣除已单列的缓存读取；输出已经包含推理 Token，不再另加一次。协议未返回缓存写入时不推测该值。
+
+上下文指示器仍使用 `tokenUsage.last`，与累计消耗相互独立。
+
+### Claude
+
+优先消费 SDK `result.modelUsage` 的模型累计用量，它包含子代理及辅助模型调用。实际返回的普通输入、输出、缓存读取与写入互不重叠，可相加得到已报告总量；不会重复叠加 `result.usage`。提供方只返回 `usage` 时按回合 ID 幂等记录其实际字段。
+
+SDK 可能在恢复会话时带回旧累计量。已有统计水位优先于首次基线；旧会话首次接入统计时，只归属本次可确认的字段，避免将以前的消耗错误计入今天。assistant 消息按原生消息 ID 去重；其输出占位值不能用来补算实际输出。进程异常终止且未返回可靠结果时不估算缺失用量。
+
+## 性能与持久化
+
+采集仅处理结构化用量及结果边界；正文 Token 增量不产生统计存储调用。Web 在既有 SQLite Worker 中执行短事务；桌面使用有界 FIFO 队列和 Tokio 阻塞池，流式投递不等待统计写盘。同步和异步存储错误均与任务执行隔离。
+
+两端执行同一份 SQL：计数水位更新与日汇总在同一事务中提交；上游后来补充的分类先建立水位，只记录此后可确认的增量，不将旧分类回填到今天；计数未变化的重复通知不修改数据库，不增加 WAL 帧。统计表不外键级联到任务，删除任务不会抹除已消耗的用量。统计不保存提示词、模型输出、密钥或账单。
+
+页面只读取有日期索引的年度汇总与有界任务明细，不启动引擎，不扫描聊天正文，不新增 WebSocket 或轮询。年度汇总按年份共用缓存，引擎标签在本地即时筛选最多 732 条日汇总，首次切换也不新增年度请求或重挂统计区域；当天前 50 项任务仍按所选引擎查询，避免先截断再筛选而漏项。组件、样式及响应校验器按需加载，年度数据缓存 30 秒、闲置查询缓存保留 5 分钟，可手动刷新。
+
+## 接口与验证
+
+- Web：`GET /v1/usage?year=2026&engine=codex&day=2026-10-22`，`engine` 和 `day` 可省略。复用访问控制，年份限制为 2000–9999，响应不允许 HTTP 缓存。
+- 桌面：`get_token_usage`，主窗口 ACL 授权，不依赖 Codex 运行时。
+- 共用协议及 SQL：`packages/protocol/src/token-usage.ts`、`token-usage-sql.json`。
+- 回归：`usage-statistics.test.ts`、`token-usage.test.ts`、`token-usage-routes.test.ts`、`usage-statistics-model.test.ts` 以及 Rust `local_catalog::token_usage`。
+- 性能回归：`token-usage.performance.test.ts` 验证十万条正文增量没有统计存储调用；WAL 用例验证重复通知不写盘。
+
+## 官方依据
+
+- [OpenAI Codex App Server](https://developers.openai.com/codex/app-server)：使用官方用量通知，字段以仓库锁定的协议版本及本地官方源码为准。
+- [Claude Agent SDK 用量跟踪](https://code.claude.com/docs/en/agent-sdk/cost-tracking)：区分主循环用量与全树累计模型用量、恢复会话及并行消息去重。
+- [GitHub 贡献日历](https://docs.github.com/en/account-and-profile/concepts/contributions-on-your-profile)：年度日历热力图及 UTC 日期参考。

package/docs/usage.en.md

@@ -0,0 +1,77 @@
+# Use the workspace
+
+[Documentation](README.md) · [简体中文](usage.md) · [Getting started](getting-started.en.md)
+
+This guide covers desktop, computer browsers, and mobile browsers. Files, Git operations, and agents run on the computer hosting Codexly. Desktop adds a native terminal, global shortcuts, a separate task window, system notifications, and tray integration.
+
+## Projects and tasks
+
+Add a disk folder as a project, or create a temporary task without project context. Git tools require a repository at the project root; ordinary subdirectories do not borrow a parent repository.
+
+Pin, archive, restore, or permanently delete tasks. Sidebar shortcuts help you move between projects and show unread completions, pending approvals, and running tasks. Use the task board to review work centrally. Search can find projects, tasks, messages, and files; some entry points depend on the enabled engine.
+
+Switch the sidebar between projects and a timeline grouped by Today, Yesterday, the last seven days, and Earlier. Groups can be collapsed. The task board and extensions are in the sidebar header, with schedules in the icon area; settings, notifications, and help are at the bottom. The notification center separates unread and read alerts, supports marking all as read, and opens the linked task when selected.
+
+## Conversations and queues
+
+Choose a model and the permission and reasoning options offered by that engine. Attach files or images, reference project files with `@`, and Skills with `$`. Existing tasks keep their original engine.
+
+Save a name, shortcut, and instructions in **Settings → Saved prompts**, choosing global or project scope. Type `/` in chat to select a prompt: it inserts at the cursor, preserves existing text, and does not send automatically. Project prompts override global prompts with the same shortcut. Prompts stay in the current browser or desktop client and do not synchronize with host task data. When space is limited, composer options such as model selection move into a menu.
+
+Follow streaming replies, commands, tools, plans, subagents, and file changes. Respond to approvals and questions in the task. Steer running work or queue follow-ups; queued messages can be reordered, withdrawn for editing, or cancelled before execution. Claude foreground interruption and background-task stopping are separate controls.
+
+Recent history loads first. Load older turns from the top, and expand execution groups for their details. Claude supports forks from completed replies and context compaction through the command menu. Commands and capabilities follow the selected engine.
+
+## Panes and mobile
+
+Desktop and computer browsers support up to four task panes. Use **Split layout** in the task header, a task's sidebar menu, or the blank-chat context menu. Shortcuts are `⌘+⌥+Arrow` on macOS and `Ctrl+Alt+Arrow` on Windows / Ubuntu.
+
+Drag dividers to resize panes. Drafts and queues are independent; files, Git, and the desktop terminal follow the focused task. Navigation from notifications, search, or the task board preserves the layout.
+
+Use the drag handle in a task pane header to move it onto another pane to swap their positions; drop feedback identifies the target.
+
+Mobile keeps a single-task view. Switch projects and tasks through the sidebar and open files, changes, or settings as needed. Native desktop terminals and global shortcuts are unavailable. See [mobile connections](web.en.md#mobile-and-lan-access).
+
+## Files and previews
+
+Open source, Markdown, images, and PDFs in center tabs while the project tree stays visible on the right. Diffs, file reviews, and commit details also use center tabs. Select **Chat** to return to the conversation. Images support zoom and pan; attachments keep their dedicated previews.
+
+Use the file toolbar to compare with chat side by side or above, drag the divider to resize, and click the selected comparison button again to focus on the document. The tab bar is hidden when only chat is open. Task navigation returns to chat while keeping open file tabs. Each task pane owns its tabs. Mobile uses a single tab group and closes overlay sidebars when opening a file.
+
+On a phone or another LAN device, download files that cannot be previewed and open them with an app on that device. Choosing the system default from the file tree, chat file links, or search results first shows a download prompt; transfer starts when you select Download. Local Web access and desktop can still open files with applications on the host.
+
+Edit text in source mode; switch Markdown to source first. UTF-8 files up to 2 MiB are editable, preserving line endings and BOM. Other files remain read-only. Edits save on blur, file navigation, or window switching; use `⌘/Ctrl+S` to save manually, with undo and redo available.
+
+Failed saves or external conflicts keep your draft in the current window and offer recovery actions. Drafts are held in memory and may not survive refreshes, forced exits, or crashes. Confirm save status before leaving.
+
+## Git and worktrees
+
+Review changes, select files, and commit locally or commit and push. Push existing commits independently. A failed push preserves the local commit; resolve the connection or authentication problem and retry pushing.
+
+The toolbar supports remote setup, branch publication, fetch, and fast-forward-only pull. Commit drafts are scoped to the device, project, worktree, and branch. Git uses the host computer's identity and credentials, including from mobile.
+
+Choose or create a worktree from the branch menu beneath the composer, then send the first message there. Existing conversations retain their original directory. Dependencies and ignored environment files are not copied automatically. Resolve merge conflicts in an external Git tool. See the bilingual [Git guide](git-workflow.md).
+
+## Scheduled work
+
+Create a schedule with a project, request, engine, model, and repeat rule. Both engines are supported; Claude-only setups select Claude automatically. Changing a schedule's engine affects future runs, not existing conversations.
+
+The host must remain awake with the desktop app or Web server running. An unknown execution outcome pauses further runs: inspect the linked conversation before deleting and recreating the schedule. Cleanup retries do not launch the work again.
+
+## Extensions and settings
+
+Select Codex or Claude in the extension center and manage Skills, MCP, and official plugins within their global or project scope. Available operations differ by engine. Claude can list, enable, disable, and remove existing MCP definitions; add new definitions through native configuration. Start a new conversation after extension changes for complete loading.
+
+Search and filter extensions, then choose global or current-project scope before making changes. Claude supports installing, enabling, disabling, updating, and uninstalling plugins from the official catalog. Its project Skills and MCP lists show that project's configuration only. Codex project MCP entries are read-only. Third-party Skills marketplace entry points have been removed; local Skills remain manageable. MCP toggles show configuration, not live connection status.
+
+Models, reasoning, permissions, and context settings are engine-specific. Defaults apply to new tasks; existing conversations retain their choices. Declaring a context window does not increase a provider's actual capacity. Claude permissions do not provide Codex's OS sandbox, and extension configuration is not copied across engines.
+
+## Usage statistics
+
+Open **Settings → Usage statistics** to filter token totals, active days, trends, and a yearly heatmap by year and engine. Select a date for its top 50 tasks by usage. Dates use UTC; the heatmap scrolls horizontally on mobile. Statistics record newly observed usage without backfilling earlier history and do not represent remaining credits, costs, or official billing. Desktop and Web on the same host share these records.
+
+## Data across clients
+
+Desktop and Web under the same OS user on the same computer share projects, tasks, and history in `~/.codexly`. Mobile reads the Web host's data. Another computer does not automatically synchronize these directories. Shared storage does not imply simultaneous control of the same running agent session.
+
+Browsers connected to one Web server synchronize project todos and asynchronous questions, refreshing after reconnection or returning to the page. Drafts and pane preferences are not guaranteed to synchronize across devices. See the [storage reference (中文)](local-catalog.md).

package/docs/usage.md

@@ -0,0 +1,79 @@
+# 工作台使用
+
+[文档导航](README.md) · [English](usage.en.md) · [首次使用](getting-started.md)
+
+本指南适用于桌面端、电脑 Web 和移动浏览器。项目文件、Git 操作和智能体始终位于运行 Codexly 的电脑上。桌面应用提供额外的原生终端、快捷键、独立任务窗口、通知和托盘集成。
+
+## 项目与任务
+
+将一个磁盘文件夹添加为项目。项目根目录是 Git 仓库时可使用 Git 面板；普通子目录不会自动借用父仓库。无需项目上下文时可创建临时任务。
+
+侧栏可置顶任务、查看运行状态、归档历史，并从归档列表恢复或永久删除任务。「已固定」和「运行中」快捷区方便跨项目切换；未查看的完成任务、待审批和运行状态会显示提醒。任务看板提供集中查看任务的入口。
+
+侧栏支持项目与时间线视图切换；时间线按今天、昨天、近 7 天与更早分组，可折叠分组。任务看板与扩展位于侧栏头部，定时任务位于图标区；底部提供设置、通知与帮助入口。通知中心区分未读和已读，可全部标为已读，点击通知进入对应任务。
+
+使用搜索查找项目、任务、历史消息和文件；部分搜索入口依赖已启用引擎的能力，详见[搜索参考](global-search.md)。
+
+## 发送需求与继续对话
+
+输入需求后选择模型和当前引擎支持的权限、思考强度等选项。可以附加文件或图片，用 `@` 引用项目文件、用 `$` 引用 Skills。具体控件按引擎与模型能力显示；新任务可选择引擎，已有任务不切换引擎。
+
+在「设置 → 常用提示词」保存名称、快捷词与内容，选择全局或项目范围；聊天输入 `/` 后选择提示词，内容插入光标位置并保留已有输入，不会自动发送。同快捷词优先使用项目版本。提示词仅保存在当前浏览器或桌面客户端，不随主机任务数据跨客户端同步。输入区空间不足时，模型等配置收进菜单，展开后仍可调整。
+
+任务运行时，查看流式回答、命令输出、工具调用、计划、子代理与文件变更。审批和异步问题需要在当前任务中处理。你可以给运行中的任务补充要求，也可将后续消息加入队列，执行前排序、撤回修改或取消。Claude 的运行中引导、前台中断与后台任务停止各有入口；停止前台不代表所有后台任务都已停止。
+
+历史先加载最近回合，在顶部继续读取更早内容；展开执行过程时才读取对应细节。Claude 可从已完成回复处分叉新会话，也可在命令菜单中压缩上下文。不同引擎的命令与能力以界面为准。
+
+## 分屏与移动视图
+
+桌面应用和电脑浏览器最多支持四个任务分屏。在任务标题栏「分屏布局」选择双、三、四分屏预设，也可通过侧栏任务菜单或聊天空白处右键菜单打开指定方向的分屏。
+
+macOS 使用 `⌘+⌥+方向键`，Windows / Ubuntu 使用 `Ctrl+Alt+方向键`。拖动分割线调整大小；每个分屏保留独立草稿与消息队列，项目文件、Git 面板和桌面终端跟随当前聚焦任务。从通知、搜索或看板进入任务会保留分屏布局。
+
+使用任务标题栏的拖动手柄，将当前分屏拖到另一个分屏，可交换两者的位置；拖动时的目标提示帮助确认落点。
+
+移动端保持单任务视图，通过侧栏切换项目与任务，按需打开文件、变更和设置面板；不提供桌面原生终端或全局快捷键。连接方式见 [Web 与移动端](web.md)。
+
+## 文件与预览
+
+在右侧项目面板中浏览文件，点击后在中栏标签打开代码、Markdown、图片或 PDF，文件树保持原位。文件差异、批量审核与提交详情也进入中栏；点击「聊天」返回会话。图片支持缩放和拖动，聊天附件继续使用对应预览。
+
+文件标签工具栏支持「与聊天左右对照」「与聊天上下对照」，拖动分割线调整大小，再次点击已选中的对照按钮恢复单栏。只有聊天时隐藏标签栏；从任务入口切换任务时回到聊天，并保留已打开的文件标签。每个任务分屏独立管理文件标签；手机上使用单组标签，打开文件后自动收起覆盖内容的侧栏。详见[工作区设计与操作](document-workspace.md)。
+
+从手机或其他局域网设备访问时，不能预览的文件可通过「下载」保存到当前设备，再用本机应用打开；文件树、聊天文件链接和搜索结果中的「系统默认」会先显示下载提示，点击后才传输文件。本机 Web 与桌面端仍可调用主机上的应用打开文件。
+
+打开文本源码即可编辑，Markdown 需先切换到源码模式。支持最大 2 MiB 的 UTF-8 文本，保留原换行和 BOM；其他文件只读。失焦、离开文件或切换窗口时自动保存，`⌘/Ctrl+S` 可手动保存，也可撤销和重做。
+
+保存失败或外部修改冲突时，保留当前窗口草稿并提供恢复操作。草稿保存在内存，刷新、强制退出或崩溃后不保证恢复；离开前确认保存状态。详见[文本文件编辑](text-file-editing.md)。
+
+## Git 与 worktree
+
+在变更面板审阅差异、选择文件并编辑提交信息，执行「提交」或「提交并推送」；已有本地提交可单独推送，无需制造新的文件变更。推送失败不会撤销已经保存的本地提交，修复认证或连接后重试推送即可。
+
+顶部工具栏提供远端配置、发布分支、获取更新和仅快进拉取。提交信息草稿按当前设备、项目、worktree 与分支保存。Git 使用运行 Codexly 的电脑上的身份和远端认证，手机上的 Git 账号不会自动用于主机。
+
+从输入区下方的分支菜单选择或新建 worktree，再在该目录中发送第一个消息。原会话保持原目录，新任务使用选中的 worktree。依赖与忽略的环境文件不会自动复制；合并冲突需在外部 Git 工具处理。详见 [Git 操作指南](git-workflow.md)。
+
+## 定时任务
+
+在「定时任务」创建计划，选择项目、需求、引擎与模型，配置重复规则并预览后续执行时间。Codex 与 Claude 都可用于计划；只配置 Claude 时自动使用 Claude。修改计划引擎影响后续执行，已经创建的聊天保留原引擎。
+
+计划在提供服务的电脑上执行，电脑须保持唤醒，桌面应用或 Web 服务须运行。若执行结果不确定，系统会暂停后续运行；先检查关联对话，确认实际结果后再删除并重建计划。显示清理中的任务会自动重试清理，不会因此再次执行需求。
+
+## 扩展与设置
+
+在扩展中心选择 Codex 或 Claude，分别管理 Skills、MCP 和官方插件，并注意全局与项目范围。不同引擎提供的操作不同；Claude 当前支持查看、启停和移除已有 MCP 配置，新增 MCP 需通过其原生配置完成。扩展配置改变后，新建会话以完整加载。
+
+通过搜索和筛选定位扩展，先选择全局或当前项目，再执行对应范围的操作。Claude 支持安装、启停、更新和卸载官方目录中的插件；项目 Skills 与 MCP 列表仅展示该项目的配置。Codex 项目 MCP 只读。应用已移除第三方技能市场入口，本地 Skills 仍可管理；开关表示启用配置，不代表 MCP 已实时连接。
+
+模型、思考强度、权限和上下文窗口按引擎配置。模型默认值用于新任务，已有会话保留自己的选择；窗口声明不会扩大模型或服务商的真实容量。Claude 权限模式不等同于 Codex 的系统沙盒，扩展配置也不在两种引擎间自动复制。详见[引擎参考](agent-engines.md)与[上下文设置](model-context-window.md)。
+
+## 用量统计
+
+在「设置 → 用量统计」按年份和引擎查看 Token 总量、活跃天数、趋势与年度热力图，选择日期查看当天用量最高的 50 项任务。日期按 UTC 归属；手机可横向滚动热力图。统计只记录功能启用后观测到的实际新增用量，不回填旧历史，也不代表剩余额度、费用或官方账单。详见[用量统计参考](usage-statistics.md)。
+
+## 数据与多端使用
+
+同机同一系统用户下，桌面与 Web 共用 `~/.codexly` 中的项目、任务和历史；手机访问 Web 主机的数据。另一台电脑不会自动同步这些本地目录，也不应将同机共享理解为可同时控制同一执行会话。
+
+多个浏览器连接同一个 Web 服务时，项目待办与异步问题会同步；重新连接或回到页面会刷新状态。草稿、分屏等界面偏好不保证跨设备同步。备份及迁移见[常见问题](faq.md)。

package/docs/web-autostart.md

@@ -1,5 +1,9 @@
 # Web startup at login
 
+[Documentation](README.md) · [Web and mobile](web.en.md) · [简体中文](web-autostart.zh-CN.md)
+
+For the desktop app, use **Settings → General → Launch at login**. This guide manages the Web server used by computer and mobile browsers; agents execute on its host.
+
 The Web npm package provides `codexly autostart` to run Codexly after the current user logs in. Both local and LAN modes keep the browser closed. Managed startup skips the initial update check and interactive prompts and uses the installed version.
 
 ## Configure and manage
@@ -71,9 +75,9 @@ macOS may expose controls for background items. Run `enable` again if the item h
 
 Uses a current-user logon trigger, `InteractiveToken`, and least privilege. No Windows password is saved and no boot trigger is registered. The task removes the default execution time and battery restrictions, ignores duplicate starts, and retries failures up to five times at one-minute intervals.
 
-The CLI uses built-in PowerShell, Task Scheduler, and `icacls`. Policies that prohibit user tasks produce an error without automatic elevation. Inspect the named task's history and last result in Task Scheduler; `status` also reports numeric task state and last result.
+The CLI uses built-in PowerShell, Task Scheduler, Windows Script Host (JScript), and `icacls`. Policies that prohibit user tasks produce an error without automatic elevation. Inspect the named task's history and last result in Task Scheduler; `status` also reports numeric task state and last result.
 
-Browser suppression is guaranteed by the application. Windows determines how the task's console is presented; Task Scheduler's `Hidden` setting is not treated as a console-hiding guarantee.
+Login startup runs silently without opening a browser or a visible command window. The task uses a GUI script host to start Node with its console hidden, waits for Node to exit, and returns its exit code so failure retries still work. Logs remain available through `autostart logs`; stop the service with `autostart disable`. Existing registrations need `codexly autostart repair --now` after updating to apply the silent launcher.
 
 ### Ubuntu
 

package/docs/web-autostart.zh-CN.md

@@ -1,5 +1,9 @@
 # Web 登录自启动
 
+[文档导航](README.md) · [Web 与移动端](web.md) · [English](web-autostart.md)
+
+桌面应用请使用「设置 → 通用 → 开机启动」；本指南的后台 Web 服务可供电脑和移动浏览器访问，智能体运行于该服务所在主机。
+
 此功能由 Web npm 包的 CLI 提供，用于当前用户登录系统后运行 Codexly。配置入口是 `codexly autostart`，本机和 LAN 模式均不打开浏览器。后台启动跳过启动前更新检查和终端询问，直接使用已安装版本。
 
 ## 配置与使用
@@ -71,9 +75,9 @@ macOS 系统设置可能显示或允许禁用相关后台项目；被禁用后
 
 计划任务仅在当前用户登录时触发，使用 `InteractiveToken` 和普通权限，不保存 Windows 密码，不配置开机触发器。任务取消默认执行时限与电池供电限制，重复登录不启动第二份实例，异常退出最多重试五次，间隔一分钟。
 
-CLI 使用 Windows 自带的 PowerShell、Task Scheduler 和 `icacls`。企业策略禁止创建用户任务时命令会明确失败，不自动提升权限。需要更多系统诊断时，在任务计划程序中查看 `Codexly Web <SID>` 的历史和最后运行结果；`status` 也显示任务状态和结果数字。
+CLI 使用 Windows 自带的 PowerShell、Task Scheduler、Windows Script Host（JScript）和 `icacls`。企业策略禁止创建用户任务时命令会明确失败，不自动提升权限。需要更多系统诊断时，在任务计划程序中查看 `Codexly Web <SID>` 的历史和最后运行结果；`status` 也显示任务状态和结果数字。
 
-本功能保证不打开浏览器；计划任务的控制台呈现由 Windows 决定，不把 Task Scheduler 的 `Hidden` 属性当作隐藏控制台的保证。
+登录后静默后台启动，不打开浏览器或可见的命令行窗口。计划任务通过图形脚本宿主以隐藏控制台方式启动 Node，等待其退出并回传退出码，保留异常重试能力。日志通过 `autostart logs` 查看，停止服务使用 `autostart disable`。已有登录项在更新后需要执行 `codexly autostart repair --now`，才能应用静默启动器。
 
 ### Ubuntu