@bryanhu/codexly 0.39.1 → 0.40.0

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.en.md

@@ -0,0 +1,65 @@
+# 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.
+
+## 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.
+
+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.
+
+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
+
+Browse source, Markdown, images, and PDFs. Images support zoom and pan. Chat attachments, file links, and task-local images open in their corresponding previews.
+
+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.
+
+## 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,67 @@
+# 工作台使用
+
+[文档导航](README.md) · [English](usage.en.md) · [首次使用](getting-started.md)
+
+本指南适用于桌面端、电脑 Web 和移动浏览器。项目文件、Git 操作和智能体始终位于运行 Codexly 的电脑上。桌面应用提供额外的原生终端、快捷键、独立任务窗口、通知和托盘集成。
+
+## 项目与任务
+
+将一个磁盘文件夹添加为项目。项目根目录是 Git 仓库时可使用 Git 面板；普通子目录不会自动借用父仓库。无需项目上下文时可创建临时任务。
+
+侧栏可置顶任务、查看运行状态、归档历史，并从归档列表恢复或永久删除任务。「已固定」和「运行中」快捷区方便跨项目切换；未查看的完成任务、待审批和运行状态会显示提醒。任务看板提供集中查看任务的入口。
+
+使用搜索查找项目、任务、历史消息和文件；部分搜索入口依赖已启用引擎的能力，详见[搜索参考](global-search.md)。
+
+## 发送需求与继续对话
+
+输入需求后选择模型和当前引擎支持的权限、思考强度等选项。可以附加文件或图片，用 `@` 引用项目文件、用 `$` 引用 Skills。具体控件按引擎与模型能力显示；新任务可选择引擎，已有任务不切换引擎。
+
+任务运行时，查看流式回答、命令输出、工具调用、计划、子代理与文件变更。审批和异步问题需要在当前任务中处理。你可以给运行中的任务补充要求，也可将后续消息加入队列，执行前排序、撤回修改或取消。Claude 的运行中引导、前台中断与后台任务停止各有入口；停止前台不代表所有后台任务都已停止。
+
+历史先加载最近回合，在顶部继续读取更早内容；展开执行过程时才读取对应细节。Claude 可从已完成回复处分叉新会话，也可在命令菜单中压缩上下文。不同引擎的命令与能力以界面为准。
+
+## 分屏与移动视图
+
+桌面应用和电脑浏览器最多支持四个任务分屏。在任务标题栏「分屏布局」选择双、三、四分屏预设，也可通过侧栏任务菜单或聊天空白处右键菜单打开指定方向的分屏。
+
+macOS 使用 `⌘+⌥+方向键`，Windows / Ubuntu 使用 `Ctrl+Alt+方向键`。拖动分割线调整大小；每个分屏保留独立草稿与消息队列，项目文件、Git 面板和桌面终端跟随当前聚焦任务。从通知、搜索或看板进入任务会保留分屏布局。
+
+移动端保持单任务视图，通过侧栏切换项目与任务，按需打开文件、变更和设置面板；不提供桌面原生终端或全局快捷键。连接方式见 [Web 与移动端](web.md)。
+
+## 文件与预览
+
+在项目面板中浏览文件，预览代码、Markdown、图片与 PDF；图片支持缩放和拖动。聊天中的附件、文件链接与任务本地图片也可进入对应预览。
+
+从手机或其他局域网设备访问时，不能预览的文件可通过「下载」保存到当前设备，再用本机应用打开；文件树、聊天文件链接和搜索结果中的「系统默认」会先显示下载提示，点击后才传输文件。本机 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)。
+
+## 数据与多端使用
+
+同机同一系统用户下，桌面与 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
 

package/docs/web.en.md

@@ -0,0 +1,123 @@
+# Web and mobile guide
+
+[Documentation](README.md) · [简体中文](web.md) · [Desktop installation](../desktop/docs/installation.en.md)
+
+The Web server runs on the computer holding your projects. Computers, phones, and tablets access it through browsers. The desktop app runs independently; start a Web server for mobile access to the same host.
+
+## Requirements and startup
+
+The host needs Node.js >=24.0.0. Supported browsers are Chrome / Chromium 116+, Firefox 124+, and Safari 17.4+. Mobile devices need only a compatible browser. The npm package installs Web dependencies and reads agent configuration on the host.
+
+Try without a global installation:
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start
+```
+
+The default URL is `http://127.0.0.1:3210`; occupied ports are skipped, so use the printed address. Keep the terminal running and press `Ctrl+C` to stop. Follow [agent setup](getting-started.en.md) on first use.
+
+For regular use:
+
+```bash
+npm install --global @bryanhu/codexly@latest
+codexly
+```
+
+`codexly` means `codexly start`. Use `codexly start --no-open` to suppress browser opening.
+
+## Mobile and LAN access
+
+1. Start LAN mode on the host: `codexly start --lan` after global installation, or use the command below.
+2. Connect your mobile device to the same trusted LAN and open the printed LAN URL.
+3. Enter the access password from the terminal. Do not use `127.0.0.1` on the phone: that refers to the phone itself.
+4. Open a host project to follow tasks, send messages, handle approvals, and review files and changes.
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start --lan
+```
+
+LAN mode listens on network interfaces without opening a host browser. Keep the host awake with the service running. Allow the port through its firewall; guest Wi-Fi or client isolation may block device-to-device connections.
+
+LAN mode uses unencrypted HTTP and is only for trusted networks. Never expose it directly through public forwarding or proxies. `--allowed-host` only extends the Host allowlist; it adds no encryption or authentication.
+
+A random password is generated by default. Restarts invalidate random pairing codes and all sessions. Explicit fixed passwords remain usable, but users must log in again. Autostart saves and reuses its own password.
+
+## Common options
+
+After global installation, use these with `codexly start`. For temporary use, prefix the command with `npx --package @bryanhu/codexly@latest`.
+
+| Option                        | Purpose                                                                                   |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `--port <port>`               | Starting port; occupied ports are skipped                                                 |
+| `--no-open`                   | Suppress browser opening                                                                  |
+| `--lan`                       | Enable trusted LAN access                                                                 |
+| `--lan-password <password>`   | Fixed 16–128 character password with uppercase, lowercase, and numbers; requires `--lan`  |
+| `--session-ttl <duration>`    | Fixed session lifetime, e.g. `12h`; omitted sessions last until restart; requires `--lan` |
+| `--workspace <absolute-path>` | Restrict project roots; repeatable                                                        |
+| `--allowed-host <domain>`     | Allow an exact proxy domain; repeatable                                                   |
+| `--codex-home <directory>`    | Set Codex configuration/history location; does not move `~/.codexly`                      |
+| `--codex-bin <path>`          | Use a compatible external Codex executable; affects Codex only                            |
+
+Quote shell-special characters in passwords. Run `codexly start --help` for complete help.
+
+The bundled Codex CLI is `0.163.0`. External executables supplied through `--codex-bin` or `CODEXLY_CODEX_BIN` must satisfy `>=0.163.0,<0.164.0`. Claude uses the package's pinned SDK dependency and does not require an external Codex executable.
+
+Multiple instances skip occupied ports. The launch directory does not determine application storage. Temporary tasks default to the user's home directory or the first explicit `--workspace` root. Separate `--codex-home` directories isolate Codex data only, not the shared Codexly application directory.
+
+## Start after login
+
+Requires a stable global npm installation; temporary `npx` installations cannot register startup. Supported systems are macOS, Windows, and Ubuntu with a systemd user manager.
+
+```bash
+codexly autostart enable
+codexly autostart status
+```
+
+Local and LAN startup keep the browser closed. Enable LAN startup and start immediately:
+
+```bash
+codexly autostart enable --lan --now
+codexly autostart credentials
+```
+
+Use `status` for actual URLs and `credentials` to reveal the saved password explicitly.
+
+```bash
+codexly autostart logs
+codexly autostart restart
+codexly autostart disable
+codexly autostart repair --now
+```
+
+Repeated `enable` updates the same login entry. Without `--now`, changes apply on restart or next login. Use `repair --now` after moving Node.js or the global package directory; disable startup before uninstalling. Shell profiles are not loaded, so temporary shell API keys and proxy variables are not automatically inherited. See [startup details](web-autostart.md). Desktop uses **Settings → General → Launch at login** instead.
+
+## Updates and uninstall
+
+Click the sidebar version when an update appears to read notes and install it, or check **Settings → About**. Built-in updates probe the official registry and a mirror with fallback; mirrors may lag. Global installations can also update with:
+
+```bash
+npm install --global @bryanhu/codexly@latest
+```
+
+An older release installed into a system directory with `sudo npm install --global` may need one manual elevated upgrade. Later built-in updates request elevation when needed. Save file edits before updating and follow restart or reconnection prompts.
+
+To uninstall:
+
+```bash
+codexly autostart disable
+npm uninstall --global @bryanhu/codexly
+```
+
+Skip the first command if startup was never configured. Uninstalling preserves projects and `~/.codexly`, which may still be used by desktop.
+
+## Troubleshooting
+
+Check terminal errors, the actual URL and port, Node.js version, and network first:
+
+```bash
+codexly --version
+codexly doctor
+codexly start --help
+```
+
+`doctor` checks local environment and Codex readiness; it does not verify Claude API access or inference credits. For Claude-only setups, inspect Claude settings and the actual error rather than treating missing Codex configuration as an application-wide failure.

package/docs/web.md

@@ -0,0 +1,123 @@
+# Web 与移动端使用指南
+
+[文档导航](README.md) · [English](web.en.md) · [桌面安装](../desktop/docs/installation.md)
+
+Web 服务运行在保存项目的电脑上，电脑、手机和平板通过浏览器访问。桌面应用独立运行；要让手机访问同机项目，请额外启动 Web 服务。
+
+## 环境与启动
+
+主机需要 Node.js >=24.0.0；浏览器要求 Chrome / Chromium 116+、Firefox 124+ 或 Safari 17.4+。手机只需兼容浏览器，无需 Node.js。Web 依赖随 npm 包安装，运行时配置在主机上读取。
+
+无需全局安装即可试用：
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start
+```
+
+默认打开 `http://127.0.0.1:3210`；端口占用时自动递增，以终端输出为准。保持终端运行，按 `Ctrl+C` 停止。首次使用按[连接指南](getting-started.md)配置 Codex 或 Claude。
+
+日常使用建议全局安装：
+
+```bash
+npm install --global @bryanhu/codexly@latest
+codexly
+```
+
+`codexly` 等同于 `codexly start`。不希望自动打开浏览器时运行 `codexly start --no-open`。
+
+## 移动端与局域网访问
+
+1. 在主机启动局域网模式；全局安装后使用 `codexly start --lan`，临时使用运行下方命令。
+2. 将手机或平板连接同一可信局域网，在浏览器中打开终端显示的局域网地址。
+3. 输入终端显示的访问密码。不要在手机上使用 `127.0.0.1`，它指向手机自身。
+4. 选择主机上的项目，查看任务、发送消息、处理审批或打开文件和变更。
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start --lan
+```
+
+`--lan` 监听网络接口且不自动打开主机浏览器。主机须保持开机、唤醒并运行服务；关闭服务或主机休眠后，手机无法继续操作。检查防火墙是否允许对应端口，访客 Wi-Fi 或客户端隔离可能阻止设备互访。
+
+局域网使用未加密 HTTP，仅适用于可信网络，不要通过端口转发或公网代理直接公开。`--allowed-host` 只扩展 Host 白名单，不提供加密或额外认证。
+
+默认生成随机密码；服务重启会使随机配对码和所有登录会话失效。显式设置的固定密码重启后仍可使用，但需重新登录。自启动服务会保存并复用自己的密码，见下文。
+
+## 常用启动参数
+
+以下命令在全局安装后可直接使用；临时安装时在 `npx --package @bryanhu/codexly@latest` 后使用同样参数。
+
+| 参数                     | 用途                                                                 |
+| ------------------------ | -------------------------------------------------------------------- |
+| `--port <端口>`          | 指定起始端口，占用时自动递增                                         |
+| `--no-open`              | 不自动打开浏览器                                                     |
+| `--lan`                  | 开启可信局域网访问                                                   |
+| `--lan-password <密码>`  | 固定局域网密码，16–128 位，含大写、小写字母和数字；须与 `--lan` 合用 |
+| `--session-ttl <时长>`   | 固定登录有效期，如 `12h`；省略则持续到服务重启；须与 `--lan` 合用    |
+| `--workspace <绝对路径>` | 限制项目选择根目录，可重复指定                                       |
+| `--allowed-host <域名>`  | 允许准确的代理域名，可重复指定                                       |
+| `--codex-home <目录>`    | 指定 Codex 原生配置与历史目录，不改变 `~/.codexly` 应用目录          |
+| `--codex-bin <路径>`     | 使用兼容的外部 Codex 程序，仅影响 Codex 引擎                         |
+
+含 Shell 特殊字符的密码需要正确加引号。用 `codexly start --help` 查看完整帮助。
+
+当前内置 Codex CLI `0.163.0`；`--codex-bin` 或 `CODEXLY_CODEX_BIN` 指定的外部版本须满足 `>=0.163.0,<0.164.0`。Claude 使用 npm 包固定的 SDK 依赖，无需配置外部 Codex 才能使用。
+
+多实例启动会跳过占用端口。启动目录不决定应用数据目录；临时任务默认使用用户主目录，或第一个显式 `--workspace` 根目录。`--codex-home` 只隔离 Codex 自身的数据，不隔离共享的 Codexly 应用目录。
+
+## 登录后后台启动
+
+需要稳定的全局 npm 安装，临时 `npx` 安装不能登记系统登录项。支持 macOS、Windows，以及提供 systemd 用户管理器的 Ubuntu。
+
+```bash
+codexly autostart enable
+codexly autostart status
+```
+
+本机和 LAN 自启动都不自动打开浏览器。需要局域网后台运行并立即启动时：
+
+```bash
+codexly autostart enable --lan --now
+codexly autostart credentials
+```
+
+`status` 查看实际地址与状态，`credentials` 显式显示保存的局域网密码。常用维护命令：
+
+```bash
+codexly autostart logs
+codexly autostart restart
+codexly autostart disable
+codexly autostart repair --now
+```
+
+`enable` 更新同一个登录项；不加 `--now` 时，修改在重启或下次登录生效。更换 Node.js 或全局 npm 目录后使用 `repair --now`；卸载前先 `disable`。登录项不读取 Shell profile，终端临时设置的 API Key 和代理不会自动带入。完整说明见 [Web 登录自启动](web-autostart.zh-CN.md)。桌面应用使用「设置 → 通用 → 开机启动」，无需此 CLI。
+
+## 更新与卸载
+
+侧栏出现新版本时，点击版本号查看更新日志并安装；也可在「设置 → 关于」检查更新。内置更新探测官方源与镜像，并在失败时回退；镜像同步可能有延迟。全局安装也可手动更新：
+
+```bash
+npm install --global @bryanhu/codexly@latest
+```
+
+若旧版曾通过 `sudo npm install --global` 安装到系统目录，可能需手动以同样权限升级一次；后续内置更新按需请求提权。更新前保存编辑中的文件，按界面提示重启或重新连接。
+
+卸载全局 npm 包：
+
+```bash
+codexly autostart disable
+npm uninstall --global @bryanhu/codexly
+```
+
+未配置自启动时可跳过第一行。卸载包不会自动删除项目或 `~/.codexly` 数据；该目录可能仍被桌面端使用，不要仅为卸载 Web 而删除。
+
+## 排查问题
+
+先看启动终端错误，确认实际地址、端口、Node.js 版本和网络，再运行：
+
+```bash
+codexly --version
+codexly doctor
+codexly start --help
+```
+
+`doctor` 提供本地环境与 Codex 检查，不代替 Claude API 和模型额度验证。仅使用 Claude 时应结合 Claude 设置与具体错误排查，不能将 Codex 未配置直接视为整个应用不可用。更多说明见[常见问题](faq.md)。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bryanhu/codexly",
-  "version": "0.39.1",
-  "description": "通过 Web 操作本地 Coding Agent 的应用",
+  "version": "0.40.0",
+  "description": "支持 Codex 与 Claude 的本地 AI 编程工作台，覆盖桌面、Web 与移动浏览器",
   "type": "module",
   "author": "BryanHu",
   "homepage": "https://github.com/BryanHoo/Codexly#readme",
@@ -15,9 +15,12 @@
   "keywords": [
     "ai",
     "codex",
+    "claude",
     "coding-agent",
     "developer-tools",
-    "web"
+    "desktop",
+    "web",
+    "mobile"
   ],
   "engines": {
     "node": ">=24.0.0",
@@ -38,7 +41,21 @@
     "docs/web-autostart.zh-CN.md",
     "CHANGELOG.md",
     "LICENSE",
-    "docs/agent-engines.md"
+    "docs/agent-engines.md",
+    "README.en.md",
+    "docs/README.md",
+    "docs/getting-started.md",
+    "docs/getting-started.en.md",
+    "docs/usage.md",
+    "docs/usage.en.md",
+    "docs/web.md",
+    "docs/web.en.md",
+    "docs/faq.md",
+    "docs/text-file-editing.md",
+    "docs/global-search.md",
+    "docs/conversation-performance.md",
+    "docs/scheduled-task-idempotency.md",
+    "docs/images/codexly-preview.png"
   ],
   "publishConfig": {
     "access": "public"