@bryanhu/codexly 0.39.1 → 0.41.0

package/README.en.md

@@ -0,0 +1,109 @@
+<p align="center">
+  <img src="./apps/web/public/brand/codexly-mark.svg" alt="Codexly" width="88" />
+</p>
+
+<h1 align="center">Codexly</h1>
+
+<p align="center">A local AI coding workspace for Codex and Claude, on desktop, the Web, and mobile browsers.</p>
+
+<p align="center">
+  <a href="https://github.com/BryanHoo/Codexly/releases">Download desktop</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="./docs/README.md">Documentation</a> ·
+  <a href="./README.md">简体中文</a>
+</p>
+
+Codexly brings AI conversations, coding tasks, project files, changes, and Git into one workspace. Work on your computer, or follow progress, answer questions, and continue tasks from a phone or tablet on the same trusted network.
+
+Projects and agent processes run on the computer hosting Codexly. Your phone needs no coding environment. Model requests and relevant context are still sent to the model service you configure.
+
+![Codexly workspace showing projects, the task composer, and project files](docs/images/codexly-preview.png)
+
+## Choose how to use it
+
+| Client  | Best for                                                                                                   | Get started                                                                                                                              |
+| ------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Desktop | Daily local development with a project terminal, global shortcuts, a separate task window, and system tray | [Download for macOS, Windows, or Ubuntu](https://github.com/BryanHoo/Codexly/releases) · [Installation](desktop/docs/installation.en.md) |
+| Web     | Working in a computer browser or hosting a workspace on your LAN                                           | Install Node.js 24+ and [start the Web server](#web)                                                                                     |
+| Mobile  | Following tasks, approving tools, and reviewing files and changes from a phone or tablet browser           | Connect to a Web server with LAN access enabled; see [Mobile](#mobile)                                                                   |
+
+Desktop supports Windows 10/11 x64, Ubuntu 24.04+ x64, macOS 14.5+ on Apple Silicon or Intel, and a separate macOS 12.4+ Intel Legacy build. Packages include agent runtimes, with no separate Node.js or Bun installation. Legacy supports Codex only. Mobile uses a touch-friendly Web interface and requires no separate app.
+
+## What you can do
+
+- **Work with Codex or Claude**: configure either independently, or configure both and choose an engine for each new task. Existing tasks keep their engine.
+- **Follow execution**: see streaming replies, commands, tools, plans, and file changes. Respond to approvals and questions, steer running work, or queue follow-up messages persistently.
+- **Organize projects and tasks**: browse by project or timeline, pin, archive, or restore conversations, and handle unread alerts in the notification center. Open the task board, extensions, and schedules from the sidebar.
+- **Work in parallel**: open up to four task panes in the desktop app or a computer browser, drag to swap their positions, and keep independent drafts and queues. Mobile uses a single-task view.
+- **Read and edit project files**: browse code, Markdown, images, and PDFs, edit supported text files, attach files and images, and reference project files and Skills. LAN devices can download files that cannot be previewed through an explicit prompt.
+- **Reuse instructions and track usage**: save global or project prompts and insert them with `/`. View token statistics for both engines, a yearly heatmap, and daily task details in Settings.
+- **Complete Git work**: review diffs and history, manage branches and worktrees, commit selected files, commit and push, or push existing commits.
+- **Manage agent capabilities**: search, filter, and manage Skills, MCP, and official plugins by engine and global or project scope, with per-item operation status. Configure models, reasoning effort, permissions, and context settings.
+
+Each engine retains its own models, permissions, and extension capabilities. Claude supports history recovery, live steering, forks, and compaction. Codex-specific sandbox and Review features do not map to Claude permission modes. Available actions follow the selected engine; see [agent setup](docs/getting-started.en.md).
+
+## Quick start
+
+### Desktop
+
+1. Download the package for your system and architecture from [Releases](https://github.com/BryanHoo/Codexly/releases).
+2. Install and open Codexly. Configure Codex, Claude, or both in Settings; supported existing local configurations can be reused.
+3. Add a project folder, create a task, and send your request.
+
+For Windows portable builds, extract the entire ZIP and keep the executable, Claude host, and `runtime` directory together. See [installation, updates, and uninstall](desktop/docs/installation.en.md).
+
+### Web
+
+On a computer with **Node.js 24+**, run:
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start
+```
+
+The browser opens automatically. Otherwise, use the address printed in the terminal, normally `http://127.0.0.1:3210`. Keep the terminal running; press `Ctrl+C` to stop. Complete agent setup on first use, then add a project.
+
+For regular use, install globally:
+
+```bash
+npm install --global @bryanhu/codexly@latest
+codexly
+```
+
+See the [Web guide](docs/web.en.md) for options, background startup, and updates.
+
+### Mobile
+
+On the computer hosting your projects, run:
+
+```bash
+npx --package @bryanhu/codexly@latest codexly start --lan
+```
+
+Connect your phone or tablet to the same trusted LAN. Open the printed LAN address in its browser and enter the access password. Files, Git credentials, and agent settings belong to the host computer, which must remain awake with the service running.
+
+LAN mode uses HTTP: use it only on trusted networks and never expose it directly to the internet. The desktop app does not host mobile connections; start the Web server for mobile access. See [mobile and LAN access](docs/web.en.md#mobile-and-lan-access).
+
+## Connect Codex and Claude
+
+| Agent  | Connection                                                                                                                                                                 |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Codex  | Sign in with ChatGPT, or configure an OpenAI-compatible service supporting the Responses API and a model list                                                              |
+| Claude | Reuse supported local Claude Code credentials, or configure a service supporting the Anthropic Messages API and `/v1/models`; in-app Claude account login is not available |
+
+Claude-only setups do not require Codex. Model availability, usage limits, and charges depend on your account or provider; Codexly does not include model credits. Desktop uses local settings; Web and mobile use settings on the Web host.
+
+## Documentation and help
+
+- [Documentation index](docs/README.md): installation, usage, configuration, and troubleshooting.
+- [First task](docs/getting-started.en.md): connect an agent and start working.
+- [Workspace guide](docs/usage.en.md): conversations, panes, files, Git, extensions, and schedules.
+- [Web guide](docs/web.en.md): startup, mobile connections, and updates.
+- [FAQ (中文)](docs/faq.md): storage, cross-client use, connections, and updates.
+- [Changelog](CHANGELOG.md) · [Issues](https://github.com/BryanHoo/Codexly/issues) · [Security](SECURITY.md)
+- [Contributing](CONTRIBUTING.md): development, verification, and releases.
+
+Thanks to the [LinuxDO](https://linux.do/) community for their support.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -4,173 +4,105 @@
 
 <h1 align="center">Codexly</h1>
 
-<p align="center">
-  A local AI coding workspace for desktop and browser.
-</p>
-
-Codexly keeps coding tasks, conversations, project files, and Git work in one place. Choose the desktop app for a self-contained workspace or run the Web edition locally and open it from a browser, including on a mobile device on your trusted network. Your projects and agent runtimes stay on the computer running Codexly.
+<p align="center">支持 Codex 与 Claude 的本地 AI 编程工作台，在桌面、Web 和手机浏览器中处理项目。</p>
 
 <p align="center">
-  <a href="#get-codexly">Get Codexly</a>
-  ·
-  <a href="#features">Features</a>
-  ·
-  <a href="./README.zh-CN.md">简体中文</a>
-  ·
-  <a href="./LICENSE">License</a>
+  <a href="https://github.com/BryanHoo/Codexly/releases">下载桌面版</a> ·
+  <a href="#快速开始">快速开始</a> ·
+  <a href="./docs/README.md">使用文档</a> ·
+  <a href="./README.en.md">English</a>
 </p>
 
-Directories and tasks are managed locally by Codexly, with one disk folder per directory. Existing data is imported on first launch; see [local directories and tasks](docs/local-catalog.md).
-
-## Get Codexly
+Codexly 将 AI 对话、编程任务、项目文件、代码变更与 Git 操作集中在一个工作台。你可以在电脑上持续开发，也可以从同一可信局域网中的手机或平板查看进度、回答问题和继续任务。
 
-| Edition | Best for                                                                                             | Get started                                                                                                                                                         |
-| ------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Desktop | A native workspace with an integrated terminal, task window, system notifications, and tray controls | [Download for Windows, Ubuntu, or macOS](https://github.com/BryanHoo/Codexly/releases) and follow the [desktop installation guide](desktop/docs/installation.en.md) |
-| Web     | A local browser workspace accessible from your computer or another device on a trusted LAN           | Install Node.js 24+ and [start the Web edition](#start-the-web-edition)                                                                                             |
+项目文件与智能体在运行 Codexly 的电脑上处理；手机无需安装编程环境。使用模型时，相关请求与上下文仍会发送给你配置的模型服务。
 
-Desktop packages are available for Windows 10/11 x64, Ubuntu 24.04+ x64, macOS 14.5+ (Apple Silicon or Intel), and a separate Legacy build for macOS 12.4+ Intel. See the [installation instructions](desktop/docs/installation.en.md) for setup steps and system prompts on each platform. Desktop packages include the target platform’s Codex and Claude runtimes, with no separate Node or Bun installation or first-launch runtime download. macOS Legacy provides Codex only.
+![Codexly 工作台：项目列表、任务输入与项目文件面板](docs/images/codexly-preview.png)
 
-## Web Preview
+## 选择你的使用方式
 
-![Codexly preview](docs/images/codexly-preview.png)
+| 使用端 | 适合的场景                                                       | 开始方式                                                                                                                    |
+| ------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| 桌面端 | 在本机长期开发，使用集成终端、全局快捷键、独立任务窗口与系统托盘 | [下载 macOS、Windows 或 Ubuntu 版](https://github.com/BryanHoo/Codexly/releases) · [安装指南](desktop/docs/installation.md) |
+| Web 端 | 在电脑浏览器中使用，或让一台电脑提供局域网工作台                 | 安装 Node.js 24+ 后[启动 Web 服务](#web-端)                                                                                 |
+| 移动端 | 在手机、平板浏览器中跟进任务、审批工具操作、查看文件与变更       | 连接已开启局域网访问的 Web 服务，见[移动端连接](#移动端)                                                                    |
 
-## Features
+桌面版支持 Windows 10/11 x64、Ubuntu 24.04+ x64、macOS 14.5+（Apple Silicon / Intel），另有 macOS 12.4+ Intel Legacy 版。安装包内置智能体运行时，无需另装 Node.js 或 Bun；Legacy 仅支持 Codex。移动端使用适配小屏和触屏的 Web 界面，无需单独安装 App。
 
-- Choose Codex or Claude for each task and enable either engine independently, with shared chat, tool approvals, attachments, plans, subagents, message queues, and scheduled tasks. Claude also supports live steering, session forks, and compaction. See [agent engines and connections](docs/agent-engines.md).
+## 你可以用它做什么
 
-- Follow task responses, commands, approvals, reasoning summaries, and file changes as they arrive, with file edit timing and completion summaries; keep follow-up messages in a persistent queue.
-- Load recent conversation history first, fetch older turns from the top, and load execution details independently when expanding a process; long code previews use shared rendering and bounded highlighting. See [conversation loading and performance](docs/conversation-performance.md).
-- Open up to four task panes in desktop browsers and the desktop app, each with its own draft and message queue. File and Git panels follow the focused task; mobile Web keeps a single-task view.
-- Choose two, three, or four panes from **Split layout** in the task title bar, with auto fit, columns, rows, main-pane, or grid presets; keep the current chat and open new-task pages in the other panes. Available in desktop views.
-- Resize task panes by dragging their dividers, create tasks from the title bar, and see the model and reasoning effort while the composer is collapsed.
-- Edit project text files directly in the source preview on desktop or mobile, with undo, redo, and automatic saving when leaving the editor or switching windows.
-- Read streaming Markdown responses and copy their source text; zoom and pan message images, project images, and wallpapers, or view them at their original size.
-- Preview PDFs directly from chat attachments, file links, and the project file tree.
-- View task-local images embedded in Markdown responses and open them in the image preview.
-- Follow file citations, code review comments, and follow-up suggestions in assistant responses; selecting a suggestion fills the composer for further editing.
-- Choose a model, reasoning effort, Fast mode, approval policy, and file access level for each task, and configure the global [context window](docs/model-context-window.md).
-- Create projects and directories, search tasks, message history, and project files; inspect changes, work with branches and worktrees, commit selected files, commit and push, or push existing commits independently. See the [Git workflow guide](docs/git-workflow.md). Git actions require a repository at the project root; ordinary subdirectories do not use the parent repository.
-- Switch tasks from the sidebar’s **Pinned** and **Running** shortcuts, with unread completions first, followed by pending approvals and running tasks; unread completions remain in the group count until viewed. Collapse previews or open the full list, even with projects collapsed.
-- Identify each task's project through labels in the sidebar; collapsed projects still show unread completions, pending approvals, or running tasks.
-- Manage Skills, plugins, MCP services, projects, archived tasks, notifications, and scheduled work. Refresh official plugins to synchronize their state and report partial failures.
-- Request background compression of history files untouched for over 7 days under Settings → Agent → History storage. Web compresses server history; desktop compresses local history. Other Codex clients sharing that directory must support compressed history.
+- **用 Codex 或 Claude 处理项目**：独立配置任一引擎，也可同时配置并在新任务中选择；已有任务保留原引擎。
+- **跟进执行过程**：实时查看回复、命令、工具调用、计划与文件变更，在需要时处理审批和提问；为运行中的任务补充要求，或将后续消息加入持久队列。
+- **组织多项目任务**：按项目或时间线浏览，置顶、归档或恢复对话，通过通知中心处理未读提醒；从侧栏打开任务看板、扩展与定时任务。
+- **并行推进工作**：桌面应用和电脑浏览器支持最多四个任务分屏，可拖动交换位置，各自保留草稿与消息队列；移动端使用单任务视图。
+- **查看与修改项目文件**：浏览文件树、预览代码、Markdown、图片与 PDF，直接编辑支持的文本文件；给对话附加文件或图片，引用项目文件与 Skills；局域网设备可按提示下载无法预览的文件。
+- **复用指令与查看用量**：保存全局或项目常用提示词，用 `/` 插入输入框；在设置中查看双引擎 Token 统计、年度热力图与每日任务明细。
+- **完成 Git 工作流**：审阅差异与提交历史，管理分支和 worktree，选择文件提交、提交并推送，或独立推送已有提交。
+- **管理智能体能力**：在扩展中心按引擎和全局／项目范围管理 Skills、MCP 与官方插件，搜索、筛选并查看操作状态；在设置中调整模型、思考强度、权限及上下文。
 
-**Desktop** adds a native project terminal, global shortcuts, a separate task window, tray integration, and bundled agent runtimes. It supports Windows, Ubuntu, and macOS, with an option in general settings to launch at system login. See the [desktop guide](desktop/README.en.md) for its full feature set and update behavior.
+两种引擎保留各自的模型、权限和扩展能力，具体可用操作以界面为准。Claude 支持历史恢复、运行中引导、会话分叉与压缩；Codex 的沙盒、Review 等专属能力不等同于 Claude 权限模式。详见[智能体连接与配置](docs/getting-started.md#连接-codex-或-claude)。
 
-**Web** runs a local server and opens in your browser. It supports trusted LAN access from phones and other devices, task boards, Mermaid diagrams, and customizable workspace backgrounds. The Web edition includes Codex CLI `0.163.0` through `@openai/codex`; external binaries supplied through `--codex-bin <path>` or `CODEXLY_CODEX_BIN` must satisfy `>=0.163.0,<0.164.0`.
+## 快速开始
 
-Browsers and devices connected to the same Web server synchronize project todos and asynchronous questions. Reconnecting or returning to a visible page refreshes their state.
+### 桌面端
 
-In workspaces that support split view, open a task in another pane from its sidebar menu or right-click a blank area in the chat to split up, down, left, or right. Use `⌘+⌥+Arrow` on macOS or `Ctrl+Alt+Arrow` on Windows / Linux, up to four panes.
+1. 从 [Releases](https://github.com/BryanHoo/Codexly/releases) 下载对应系统和架构的安装包。
+2. 安装并打开 Codexly，在设置中配置 Codex、Claude 或两者；已有的受支持本机配置可直接复用。
+3. 添加项目文件夹，新建任务并发送需求。
 
-Drag a divider to resize adjacent panes; navigation from notifications, search, or the task board preserves the split layout.
+Windows 便携版请完整解压 ZIP，保留程序、Claude 宿主和 `runtime` 目录。各平台安装、更新与卸载步骤见[桌面安装指南](desktop/docs/installation.md)。
 
-## Start the Web Edition
+### Web 端
 
-Requires Node.js >=24.0.0 and Chrome/Chromium 116+, Firefox 124+, or Safari 17.4+.
-
-Run the latest version without installing it:
+在安装了 **Node.js 24+** 的电脑上运行：
 
 ```bash
 npx --package @bryanhu/codexly@latest codexly start
 ```
 
-Codexly opens the browser automatically. If it does not, use the address printed in the terminal; the default is `http://127.0.0.1:3210`. Keep the terminal running and press `Ctrl+C` to stop.
-
-Run `codexly --version` to check the installed version, or `codexly <command> --help` for command-specific options.
-
-Multiple Web instances can run from the same launch directory and share the same Codex Home; occupied ports are skipped automatically. The launch directory does not determine internal configuration or the temporary task directory. Temporary tasks use the user's home directory by default, or the first explicit `--workspace` root. Use different `--codex-home <directory>` values to isolate data.
-
-On first launch, enable Codex, Claude, or both. For Codex, sign in with ChatGPT or configure an OpenAI-compatible service supporting the Responses API and `GET /models`. Claude can reuse existing local credentials or connect to an Anthropic Messages-compatible API using its URL and key; the app does not offer Claude account login. Claude-only setups do not require Codex configuration.
-Custom providers discover available models and preserve declared capabilities and reasoning levels. The reasoning menu stays hidden when the catalog declares no reasoning support. See [models and reasoning effort](docs/model-discovery.md).
+浏览器会自动打开。若未打开，请使用终端显示的地址，默认是 `http://127.0.0.1:3210`。保持终端运行，按 `Ctrl+C` 停止服务。首次使用时完成智能体连接，再添加项目。
 
-For regular use, install Codexly globally:
+经常使用时可全局安装：
 
 ```bash
 npm install --global @bryanhu/codexly@latest
 codexly
 ```
 
-The installation command uses npm’s default registry (the official registry unless you have configured another), reuses the npm cache, and revalidates stale package metadata.
-
-## Web Startup at Login
-
-After a global npm installation, configure startup for the current user through the CLI. Supports macOS, Windows, and Ubuntu with a systemd user manager. Both local and LAN startup keep the browser closed.
-
-```bash
-codexly autostart enable             # Local mode, on the next login
-codexly autostart enable --lan --now  # LAN mode, also start now
-codexly autostart status
-codexly autostart credentials
-codexly autostart logs
-codexly autostart restart
-codexly autostart disable
-```
-
-Repeating `enable` updates the same entry with the supplied options. Without `--now`, a running instance applies changes on restart or the next login. Use `status` for actual URLs when a port is occupied. LAN startup saves and reuses its password; `credentials` reveals it explicitly. Sessions require authentication again after a restart.
-
-Temporary `npx` installations cannot register startup. Run `codexly autostart repair --now` after moving Node/npm, and disable before uninstalling the package. Use `codexly start --no-open` to suppress the browser during a foreground launch. See the [Web startup at login guide](docs/web-autostart.md) for configuration, environment handling, Linux linger restrictions, and troubleshooting.
+更多启动参数、后台运行和更新方法见 [Web 使用指南](docs/web.md)。
 
-## Using the Web Edition
+### 移动端
 
-Select **New task** for work that does not need a project. For repository work, add one host folder as the project directory, create a task, and submit your request with any required files, images, project references, or Skills. Archived tasks can be restored or permanently deleted from the project task list.
-
-The Changes toolbar shows the branch, push destination, and incoming/outgoing counts, with remote configuration, branch publishing, fetch, fast-forward pull, and independent push actions. The footer edits the commit message; the main button commits and **More Git actions** offers **Commit and push**. Drafts persist on the current device by project, worktree, and branch; AI generation can be undone. A failed push preserves the local commit for retry. **Publish branch** establishes upstream tracking, and history marks unpushed commits.
-
-Task controls set the model, reasoning, Fast mode, approval, and file access behavior. Notification preferences and the last complete project settings are saved for later tasks. The right inspector provides project files, sources, code changes, Git history, review, and commit actions. Project directories and files always come from the computer running Codexly, including when the UI is opened on another device.
-
-Scheduled tasks with an unknown outcome pause further runs. Inspect the linked conversation before deleting and recreating the schedule. Tasks marked as finishing cleanup retry cleanup automatically without another launch.
-
-Open a project text file in the source preview to edit it; switch Markdown to source mode first. Changes save when the editor loses focus, you leave the file, or you switch windows; use `⌘/Ctrl+S` to save manually. UTF-8 files up to 2 MiB are editable, with their line endings and BOM preserved. Larger or unsupported files remain read-only. Save errors and conflicts keep your draft in the current window and show recovery actions. Drafts are held in memory and are not guaranteed to survive a refresh, forced exit, or crash.
-
-## Web Local Network Access
-
-Start trusted LAN access with:
+在提供项目的电脑上启动局域网服务：
 
 ```bash
-codexly start --lan
+npx --package @bryanhu/codexly@latest codexly start --lan
 ```
 
-The terminal prints the LAN address and a random access password. Common options are:
+让手机或平板与电脑连接同一可信局域网，在浏览器中打开终端显示的局域网地址并输入访问密码。项目、Git 身份和智能体配置均来自这台电脑；使用期间电脑须保持开机、唤醒且服务运行。
 
-| Option                      | Purpose                                                                                    |
-| --------------------------- | ------------------------------------------------------------------------------------------ |
-| `--port <port>`             | Choose the starting port; occupied ports are skipped automatically                         |
-| `--lan-password <password>` | Set a 16-128 character password containing uppercase, lowercase, and number                |
-| `--allowed-host <domain>`   | Allow an exact reverse proxy domain; repeat the option for multiple domains                |
-| `--session-ttl <duration>`  | Set a fixed LAN session lifetime such as `12h`; omitted sessions last until server restart |
-| `--workspace <path>`        | Restrict project selection to this absolute root; repeat for multiple roots                |
+局域网模式使用 HTTP，仅用于可信网络，不要直接暴露到公网。桌面应用本身不提供手机连接入口；需要移动访问时启动 Web 服务。详见[移动端与局域网访问](docs/web.md#移动端与局域网访问)。
 
-Quote passwords containing shell-special characters. LAN mode uses unencrypted HTTP, so use it only on a trusted network and never expose it directly to the internet. Restarting Codexly invalidates random pairing codes and all sessions; an explicitly configured fixed password remains valid.
+## 连接 Codex 与 Claude
 
-## Web Diagnostics and Updates
+| 智能体 | 连接方式                                                                                                                            |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Codex  | 使用 ChatGPT 登录，或配置支持 Responses API 与模型列表的 OpenAI 兼容服务                                                            |
+| Claude | 复用受支持的本机 Claude Code 凭据，或填写支持 Anthropic Messages API 与 `/v1/models` 的服务地址和密钥；应用内不提供 Claude 账号登录 |
 
-Run `codexly doctor` when startup, Codex, or local data checks fail. Use `codexly --help` for all commands, `codexly start --help` or `codexly doctor --help` for command options, and `codexly --version` for the installed version.
+只使用 Claude 时无需配置 Codex。模型可用性、额度与费用由所用账号或服务决定，Codexly 不包含模型服务额度。桌面端在本机配置，Web 和移动端在 Web 服务所在电脑配置。
 
-Interactive startup and **Settings > About** check for new releases. When the sidebar shows an update, click the version to read its release notes and install it. Built-in updates probe the official registry and a mirror in parallel, use the first source that responds successfully, and fall back to the other source on failure. Package downloads and dependency installation reuse the selection for that update and your npm cache. New releases may appear later if the selected mirror is still synchronizing. A global installation can also be updated with:
+## 文档与帮助
 
-```bash
-npm install --global @bryanhu/codexly@latest
-```
-
-If an older Linux release was installed into a system directory with `sudo npm install --global`, manually run the command above with `sudo` once to reach a release that supports elevated updates. Later built-in updates request `sudo` access when needed.
-
-## Help
-
-- [Report an issue](https://github.com/BryanHoo/Codexly/issues)
-- [Contributing guide](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
-- [Changelog](CHANGELOG.md)
+- [文档导航](docs/README.md)：按安装、日常使用、配置与排障查找说明。
+- [首次使用](docs/getting-started.md)：连接智能体并完成第一个任务。
+- [工作台使用](docs/usage.md)：对话、分屏、文件、Git、扩展与定时任务。
+- [常见问题](docs/faq.md)：数据保存、跨端使用、连接与更新。
+- [更新日志](CHANGELOG.md) · [问题反馈](https://github.com/BryanHoo/Codexly/issues) · [安全策略](SECURITY.md)
+- [参与贡献](CONTRIBUTING.md)：源码开发、验证与发布入口。
 
-## Community
+感谢 [LinuxDO](https://linux.do/) 社区的支持。
 
-Thanks to the [LinuxDO](https://linux.do/) community for their support
-
-## License
+## 许可证
 
 [MIT](LICENSE)
-
-### Claude Agent
-
-New conversations can select Codex or Claude Agent (Claude Code). Configure the Claude API, defaults, permissions and tool rules in Settings. Existing conversations keep their engine; Claude account login is not supported. See the [engine guide](docs/agent-engines.md) for architecture, platform requirements and capability boundaries.

package/README.zh-CN.md

@@ -1,158 +1,7 @@
 # Codexly
 
-[English](README.md) | 简体中文
+中文说明已设为 GitHub 默认首页，请阅读 [中文 README](README.md)。
 
-Codexly 是本地 AI 编程工作台，提供桌面应用和 Web 版。它将编程任务、对话、项目文件与 Git 操作集中在一处。桌面版适合在本机持续工作；Web 版在本地运行，可通过浏览器从电脑或可信局域网中的移动设备访问。项目文件和智能体运行时始终留在运行 Codexly 的电脑上。
+支持 Codex 与 Claude，在桌面、Web 和移动浏览器中处理本地项目。
 
-目录和任务由 Codexly 自行管理，每个目录对应一个磁盘文件夹；旧数据首次启动时自动导入，详见[本地目录与任务](docs/local-catalog.md)。
-
-## 获取 Codexly
-
-| 版本   | 适用场景                                           | 开始使用                                                                                                                                 |
-| ------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| 桌面版 | 原生工作台、集成终端、独立任务窗口、系统通知与托盘 | [下载 Windows、Ubuntu 或 macOS 安装包](https://github.com/BryanHoo/Codexly/releases)，按[桌面安装指南](desktop/docs/installation.md)安装 |
-| Web 版 | 本机浏览器工作台，或从可信局域网内的其他设备访问   | 安装 Node.js 24+，按[Web 版启动步骤](#启动-web-版)运行                                                                                   |
-
-桌面安装包支持 Windows 10/11 x64、Ubuntu 24.04+ x64、macOS 14.5+（Apple Silicon / Intel），并提供 macOS 12.4+ Intel 的 Legacy 版本。安装步骤与各平台的系统提示见[安装指南](desktop/docs/installation.md)。桌面安装包已内置目标平台的 Codex 与 Claude 运行时，无需另装 Node、Bun 或首次启动下载；macOS Legacy 仅提供 Codex。
-
-## 主要功能
-
-- 选择 Codex 或 Claude 处理任务，可单独启用任一引擎；共用聊天、工具审批、附件、任务计划、子代理、消息队列和定时任务。Claude 还支持运行中引导、会话分叉与压缩，详见[智能体引擎与连接](docs/agent-engines.md)。
-
-- 实时查看任务回复、命令、审批、推理摘要和文件变更，查看文件编辑耗时与完成汇总，并用持久化队列安排后续消息。
-- 优先加载最近的会话历史，顶部按需读取更早回合，展开过程后独立加载执行条目；长代码预览共用渲染与有界高亮。详见[会话加载与性能](docs/conversation-performance.md)。
-- 在 Web 桌面浏览器与桌面应用中并行打开最多四个任务，各分屏保留独立草稿与消息队列；文件和 Git 面板跟随当前聚焦任务，Web 移动端保持单任务视图。
-- 从任务标题栏的「分屏布局」选择双、三、四分屏的自适应、横排、竖排、主辅或田字布局；保留当前会话，其余分屏打开新建页。仅桌面视图提供此入口。
-- 拖动分割线调整任务分屏尺寸，从任务标题栏新建任务；收起输入框后仍可查看当前模型与思考量。
-- 在桌面或移动端的项目文件源码预览中直接编辑文本，支持撤销重做，并在离开编辑区或切换窗口时自动保存。
-- 阅读流式 Markdown 回复并复制原始文本；缩放、拖动消息图片、项目图片与壁纸，或以原始尺寸查看。
-- 直接预览聊天附件、文件链接与项目文件树中的 PDF。
-- 查看 Markdown 回复中嵌入的任务本地图片，并打开图片预览。
-- 使用助手回复中的文件引用、代码审查评论与后续建议；点击建议后可在输入框继续编辑。
-- 为任务选择模型、思考量、快速模式、审批策略和文件访问范围，并在全局设置中配置[上下文窗口](docs/model-context-window.md)。
-- 新建项目及目录，跨项目搜索任务、历史消息和文件；检查变更、管理分支与 worktree，选择文件后提交或提交并推送，也可独立推送已有提交；详见 [Git 操作指南](docs/git-workflow.md)。Git 操作仅作用于项目根目录对应的仓库，普通子目录不会借用父仓库。 Web（含移动端）与桌面端均可在输入框底部分支菜单创建、选择 worktree；新工作树统一存放在主项目的 `.worktree/` 下。发送消息时再使用输入框中的 Claude / Codex、模型等配置创建任务，任务仍归属原项目。
-- 在侧栏「已固定」与「运行中」快捷区切换任务，未查看的完成任务优先于待审批与运行任务展示，并保留在分组总数中，查看后清除完成提醒；可折叠预览或打开完整列表，项目收起时仍可访问。
-- 通过侧栏任务的项目标签识别任务来源；项目收起时仍显示未读完成、等待审批或运行状态。
-- 管理 Skills、插件、MCP 服务、项目、归档任务、通知与定时工作；刷新官方插件可同步状态，并提示部分失败。
-- 在「设置 → 智能体配置 → 历史文件存储」手动请求后台压缩超过 7 天未写入的历史；Web 作用于服务端，桌面端作用于本机。共用历史目录的其他 Codex 客户端需支持压缩格式。
-
-**桌面版**提供原生项目终端、全局快捷键、独立任务窗口、托盘集成和随包内置的智能体运行时。支持 Windows、Ubuntu 和 macOS；在通用设置中可启用登录系统后自动启动。完整功能与更新方式见[桌面版指南](desktop/README.md)。
-
-**Web 版**在本机运行服务并由浏览器访问，支持手机等设备从可信局域网接入、任务看板、Mermaid 图表和自定义工作台背景。Web 版通过 `@openai/codex` 自带 Codex CLI `0.163.0`；使用 `--codex-bin <path>` 或 `CODEXLY_CODEX_BIN` 指定外部版本时，版本必须满足 `>=0.163.0,<0.164.0`。
-
-连接同一 Web 服务的浏览器与设备会同步项目待办和异步问答变更；断线重连或页面恢复可见时刷新状态。
-
-在支持分屏的工作台中，可从侧栏任务菜单打开任务分屏，也可在聊天空白处右键选择向上、向下、向左或向右分屏。快捷键为 macOS `⌘+⌥+方向键`，Windows / Linux `Ctrl+Alt+方向键`；最多四个分屏。
-
-拖动分割线可调整相邻分屏尺寸；从通知、搜索或任务看板跳转时保留分屏布局。
-
-## 启动 Web 版
-
-需要 Node.js >=24.0.0，以及 Chrome/Chromium 116+、Firefox 124+ 或 Safari 17.4+。
-
-无需安装，直接运行最新版本：
-
-```bash
-npx --package @bryanhu/codexly@latest codexly start
-```
-
-Codexly 会自动打开浏览器。若未打开，请访问终端输出的地址；默认地址为 `http://127.0.0.1:3210`。使用期间需保持终端运行，按 `Ctrl+C` 停止。
-
-运行 `codexly --version` 查看安装版本，或使用 `codexly <command> --help` 查看命令专属选项。
-
-可以在同一启动目录或同一 Codex Home 下同时运行多个 Web 实例；端口占用时自动递增。启动目录不决定应用内部配置或临时任务目录：临时任务默认使用用户主目录，显式指定 `--workspace` 时使用首个工作区。使用不同的 `--codex-home <目录>` 可隔离数据。
-
-首次启动时，选择启用 Codex、Claude 或两者。Codex 可使用 ChatGPT 登录，或配置兼容 Responses API 和 `GET /models` 的 OpenAI-compatible 服务；Claude 可复用本机已有认证，或填写兼容 Anthropic Messages API 的地址与密钥，不提供应用内 Claude 账号登录。仅启用 Claude 时无需配置 Codex。
-自定义 Provider 会发现可用模型，保留目录声明的能力与思考档位；未声明推理能力时隐藏思考强度菜单。详见[模型与思考强度](docs/model-discovery.md)。
-
-经常使用时可以全局安装：
-
-```bash
-npm install --global @bryanhu/codexly@latest
-codexly
-```
-
-安装命令使用 npm 默认源（未自行配置时为官方源），复用 npm 缓存并重新校验过期的包元数据。
-
-## Web 登录自启动
-
-全局安装后，通过 CLI 配置当前用户登录系统时自动运行。支持 macOS、Windows 和带 systemd 用户服务的 Ubuntu；本机与 LAN 模式均不自动打开浏览器。
-
-```bash
-# 本机模式；下次登录启动
-codexly autostart enable
-
-# LAN 模式；同时立即启动
-codexly autostart enable --lan --now
-
-codexly autostart status
-codexly autostart credentials
-codexly autostart logs
-codexly autostart restart
-codexly autostart disable
-```
-
-`enable` 保存本次提供的启动参数，默认本机模式和端口 3210；重复执行会更新同一个登录项。省略 `--now` 时，当前运行实例在重启或下次登录后应用新配置。端口占用会递增，请以 `status` 输出的实际地址为准。LAN 密码首次生成后保存复用，通过 `credentials` 显式查看；服务重启后需重新认证。
-
-需要稳定的全局 npm 安装，不能从 `npx` 临时缓存登记。Node/npm 安装路径变化后运行 `codexly autostart repair --now`；卸载 npm 包前运行 `codexly autostart disable`。普通前台启动可用 `codexly start --no-open` 禁止打开浏览器。
-
-配置位置、环境变量、Linux linger 限制和各系统故障排查见 [Web 登录自启动指南](docs/web-autostart.zh-CN.md)。
-
-## 使用 Web 版
-
-不依赖项目时，直接选择“新建任务”。处理仓库时，先添加一个运行端文件夹作为项目目录，再创建任务，并按需附加文件、图片、项目引用或 Skills 后提交需求。归档的任务可以从项目任务列表中恢复或永久删除。
-
-Git 变更面板顶部显示分支、推送目标及待同步数量，提供远端配置、发布分支、获取更新、仅快进拉取与独立推送。底部编辑提交信息，主按钮执行「提交」，「更多 Git 操作」提供「提交并推送」。草稿按项目、worktree 和分支保存在当前设备；AI 生成可撤销，推送失败会保留本地提交并可单独重试。首次推送可通过「发布分支」建立上游，历史中可查看未推送标记。
-
-任务控件用于设置模型、思考量、快速模式、审批方式和文件访问范围。通知偏好与项目最近一次完整设置会保存给后续任务。右侧检查器提供项目文件、来源、代码变更、Git 历史、审查和提交操作。即使从其他设备打开界面，项目目录和文件仍来自运行 Codexly 的电脑。
-
-定时任务显示“结果未知”时会暂停后续运行，请先查看关联对话；确认后可删除该计划并重新创建。“已启动，正在收尾”会自动重试清理，无需再次运行。
-
-打开项目文本文件的源码预览即可编辑，Markdown 需先切换到源码模式。编辑区失焦、离开文件或切换窗口时自动保存，也可按 `⌘/Ctrl+S` 手动保存。支持最大 2 MiB 的 UTF-8 文本，并保留换行与 BOM；更大或不支持的文件保持只读。保存失败或发生外部修改冲突时，当前窗口保留草稿并显示恢复操作。草稿仅保存在内存中，刷新、强制退出或崩溃后不保证恢复。
-
-## Web 局域网访问
-
-在可信局域网中启动：
-
-```bash
-codexly start --lan
-```
-
-终端会输出局域网地址和随机访问密码。常用选项如下：
-
-| 选项                        | 用途                                                 |
-| --------------------------- | ---------------------------------------------------- |
-| `--port <port>`             | 指定起始端口；端口被占用时自动尝试后续端口           |
-| `--lan-password <password>` | 设置 16 至 128 位密码，必须包含大小写字母和数字      |
-| `--allowed-host <domain>`   | 允许精确的反向代理域名；多个域名可重复传入           |
-| `--session-ttl <duration>`  | 设置固定会话期限，如 `12h`；省略时持续到 Server 重启 |
-| `--workspace <path>`        | 限制项目选择的绝对根目录；多个根目录可重复传入       |
-
-密码含 Shell 特殊字符时请使用引号。局域网模式使用未加密 HTTP，只能用于可信网络，禁止直接暴露到互联网。重启 Codexly 会使随机配对码和全部会话失效；显式设置的固定密码保持有效。
-
-## Web 诊断与更新
-
-启动、Codex 或本地数据检查失败时运行 `codexly doctor`。使用 `codexly --help` 查看完整命令，`codexly start --help` 或 `codexly doctor --help` 查看对应选项，`codexly --version` 查看版本。
-
-交互式启动和“设置 > 关于”会检查新版本。侧栏出现更新提示后，点击版本号即可查看更新日志并安装更新。内置更新会并行探测官方源和镜像源，优先使用最先成功响应的源，失败后切换另一个源；同一次更新的包下载和依赖安装复用选源结果及用户的 npm 缓存。若选中的镜像仍在同步，新版本可能稍晚显示。全局安装也可以通过以下命令更新：
-
-```bash
-npm install --global @bryanhu/codexly@latest
-```
-
-如果 Linux 上的旧版本通过 `sudo npm install --global` 安装到系统目录，首次升级到支持提权更新的版本时需要手动执行一次上述命令并在前面加上 `sudo`。后续内置更新会在需要时请求 `sudo` 权限。
-
-## 获取帮助
-
-- [问题反馈](https://github.com/BryanHoo/Codexly/issues)
-- [贡献指南](CONTRIBUTING.md)
-- [安全策略](SECURITY.md)
-- [版本记录](CHANGELOG.md)
-
-## 许可证
-
-[MIT](LICENSE)
-
-### Claude Agent
-
-新聊天可选择 Codex 或 Claude Agent（Claude Code）。在设置页配置 Claude API、默认模型、权限和工具规则；历史聊天不能切换引擎，不提供 Claude 官方账号登录。架构、平台要求和能力边界见[双引擎说明](docs/agent-engines.md)。
+[下载桌面版](https://github.com/BryanHoo/Codexly/releases) · [使用文档](docs/README.md) · [English](README.en.md)