farming-code 2.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Farming Code contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# Farming
+
+> Chinese version: [README.zh_cn.md](./README.zh_cn.md)
+
+[![CI](https://github.com/zhuwenzhuang/farming/actions/workflows/ci.yml/badge.svg)](https://github.com/zhuwenzhuang/farming/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/zhuwenzhuang/farming?label=release)](https://github.com/zhuwenzhuang/farming/releases)
+[![npm](https://img.shields.io/npm/v/farming-code?label=npm)](https://www.npmjs.com/package/farming-code)
+[![License](https://img.shields.io/github/license/zhuwenzhuang/farming)](./LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)
+![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-555)
+
+Farming is a remote browser workspace for AI coding agents. The current public product line is **Farming 2**.
+
+It brings remote terminal sessions, Codex / Claude Code, project-scoped agents, open editors, file search, lightweight editing, git review tools, usage signals, and machine status into one browser page. The goal is to reduce the context switching that usually happens between SSH, an IDE, browser tabs, monitoring pages, and separate agent panels.
+
+Farming is designed around remote hosting. Agents, shells, project files, and git state keep running on the remote machine. A desktop browser is good for editing, reviewing, searching, and long follow-up sessions; a mobile browser is good for checking progress, switching sessions, and sending a short intervention while away from the desk.
+
+The browser exposes two live interfaces over the same backend: Farming Code at `/farming/code/` and the original CRT interface at `/farming/crt/`. `/farming/` continues to open Farming Code. If Code cannot start or render, the failure view keeps the live CRT interface visible behind the bounded error details, without restarting running agents.
+
+For a product-oriented introduction, screenshots, and the architecture diagram, see the [Farming 2 Wiki](https://github.com/zhuwenzhuang/farming/wiki/English).
+
+![Farming Code workspace](./docs/products/code/assets/01-code-workspace.png)
+
+> If you are an AI agent contributing to this repository, read [AGENTS.md](./AGENTS.md) first.
+
+## Why Farming Exists
+
+Current AI-agent interfaces are often chat-session lists. They are not great at showing which long-running task matters now, which agent is waiting, which one is stale, and where a human should intervene.
+
+Farming first solves the practical workbench problem: put the tools needed to supervise coding agents into one remote UI. Longer term, it explores attention management through a Main Agent that can observe, coordinate, and summarize multiple child agents.
+
+## Farming 2
+
+Farming 2 turns the project into a remote coding workbench:
+
+- start and manage Codex, Claude, OpenCode, Qoder, bash, and zsh sessions in the browser;
+- discover and resume local Codex, Claude, OpenCode, and Qoder session history, then reconnect it to live Farming terminals;
+- group agents by project;
+- open Project Files with Open Editors, file tree, search, Monaco editing, Markdown/image preview, git changes, diff, and blame;
+- click terminal `path:line` references and HTTP URLs;
+- set Codex / Claude launch profiles for permissions, model, and speed where the underlying runtime supports them; App Server Codex updates permissions on its current thread, while terminal-owned sessions restart and resume when they already have a provider session id, or start fresh when no resumable id exists yet;
+- attach text and images to composer messages;
+- view lightweight usage, context, token-rate, quota, and CPU/MEM signals where available;
+- access the same remote service from desktop and mobile browsers.
+
+Screenshots, install details, and product notes are in [Farming 2 product guide](./docs/products/code/README.md).
+
+## Quick Start
+
+The easiest path is the npm package. Run Farming on the same development machine where `codex` or `claude` already works in a normal shell.
+
+```bash
+npm install --global farming-code
+farming daemon
+```
+
+Farming defaults to port `6694`, base path `/farming`, config directory `~/.farming`, and token auth. The first authenticated start generates a random readable token and stores it in `~/.farming/.session-token`; later restarts and upgrades reuse that token unless `FARMING_TOKEN` is explicitly set. In Chinese time zones this is a Chinese haiku-style passphrase by default; Japanese time zones use Japanese haiku-style passphrases, and other time zones use English passphrases. The startup log prints a URL like:
+
+```text
+http://linux-host:6694/farming?token=<startup-token>
+```
+
+Open that URL in a desktop or mobile browser, click `New Agent`, choose `Codex`, `Claude Code`, `bash`, or `zsh`, select a workspace, and start working.
+
+## Downloads
+
+The npm package is the default distribution. GitHub release artifacts remain available for manual installation.
+
+Farming uses these practical deployment shapes:
+
+| Environment | Artifact | When to use it |
+| --- | --- | --- |
+| macOS and Linux | `npm install --global farming-code` | Default path. Requires Node.js 22 or newer and a system runtime that can load `node-pty`. |
+| Standalone use | platform CLI from GitHub Releases | Manual installation for environments that do not want npm; upgrades remain manual. |
+| Directory deployment | `farming-<version>-<platform>-<arch>.tar.gz` | App bundle with production dependencies and launcher scripts; it uses the target system runtime. |
+| Legacy Linux x64 (glibc < 2.28) | `farming-<version>-linux-x64-legacy-glibc228.tar.gz` | First-install bootstrap with a pinned glibc 2.28 runtime. It installs Farming under `~/.farming/npm`; later one-click updates use npm like the default installation. A Node.js 22 executable and npm are still required. |
+| Custom older Linux build | `farming-<version>-linux-x64-glibc217.tar.gz` | Separately built bundle that rebuilds `node-pty` against a glibc 2.17 baseline; it still needs a usable target Node.js runtime. |
+
+If you want Farming to launch Codex or Claude Code, install and log in to those CLIs on the same machine first. Farming hosts their CLI sessions; it does not replace their installation or account setup.
+
+## Architecture
+
+```text
+Browser skins
+  React + Vite + Monaco + terminal renderer
+        |
+        | HTTP / WebSocket
+        v
+Farming core
+  Express server + token auth + agent manager + session providers
+        |
+        | native pty host + session engine
+        v
+Execution environment
+  bash / zsh / Codex / Claude Code
+```
+
+The backend owns agent lifecycle, WebSocket state sync, session engines, workspace file APIs, session providers, model/profile discovery, usage collection, and configuration. Frontend skins organize those capabilities into different experiences. New interactive sessions use the native pty host by default, keeping node-pty agent processes outside the Farming server process so the server and browser can reconnect to live terminals. The native pty host persists across Farming server restarts unless `FARMING_NATIVE_PTY_HOST_PERSIST=0` is set, then exits after an idle grace period once no live sessions or clients remain. Set `FARMING_SESSION_ENGINE=local` only when debugging the in-process node-pty engine.
+
+The browser terminal renderer defaults to xterm.js. The older Ghostty web renderer is still kept as an explicit debug path through `localStorage.farmingTerminalEngine = 'ghostty'`.
+
+## Install And Run
+
+### Install From npm
+
+```bash
+npm install --global farming-code
+farming daemon
+```
+
+Open **Settings → Updates** to check and install a newer npm version in one click. Farming installs the new package while the current server is still running, restarts only after installation succeeds, and attempts to restore the previous version if the new server cannot start. The equivalent manual command is `npm install --global farming-code@latest`.
+
+### Build From Source
+
+```bash
+npm install
+npm run release:cli
+```
+
+To build an app bundle:
+
+```bash
+npm install
+npm run release:app
+```
+
+The standard app bundle includes production dependencies and launcher scripts, and uses the target system runtime as installed.
+
+For Linux x64 systems whose glibc is older than 2.28, build the release asset that carries the pinned legacy runtime:
+
+```bash
+npm run release:app:legacy-linux
+```
+
+The resulting `farming-<version>-linux-x64-legacy-glibc228.tar.gz` is a bootstrap package. It extracts the runtime to `~/.farming/glibc228`, installs the bundled Farming release into the private prefix `~/.farming/npm`, and writes a stable compatibility launcher at `~/.farming/bin/farming`. Later updates install `farming-code` into that same prefix through npm, then restart with the compatibility launcher; the tarball is not downloaded again for ordinary application updates.
+
+For a separately built `node-pty` ABI baseline, run the following command inside a clean Linux x64 builder that has glibc 2.17, Node.js 22+, GCC/G++, Make, and Python 3:
+
+```bash
+npm run release:app:linux-compat
+```
+
+The command forces `node-pty` to build from source and rejects the archive unless its native module requires no newer than glibc 2.17. Install it remotely with `FARMING_REMOTE=user@host FARMING_RELEASE_TARBALL=<archive> npm run release:remote:linux-compat`. This ABI-focused bundle still uses the target machine's Node.js and libc.
+
+When a clean source checkout is already present on a provisioned Linux x64 builder host, `scripts/build-linux-compat-release-on-builder.sh` automates the remaining container build, ABI verification, packaged bash-agent smoke, and artifact output. Set `FARMING_COMPAT_IMAGE` to an image that already exists on that host. The script uses `--pull=never` and disables container networking by default so release builds reuse existing images and caches instead of downloading infrastructure implicitly; set `FARMING_COMPAT_ALLOW_NETWORK=1` only when an intentional cache refresh is required.
+
+### Run A Single-File CLI
+
+```bash
+chmod +x farming
+./farming daemon
+```
+
+By default it listens on port `6694`, serves under `/farming`, creates `~/.farming`, enables token auth, and prints a browser URL containing the startup token.
+
+Useful commands:
+
+```bash
+./farming status
+./farming logs
+./farming url
+./farming stop
+```
+
+### Run An App Bundle
+
+```bash
+tar -xzf farming-<version>-linux-x64.tar.gz
+cd farming-<version>-linux-x64
+./farming
+```
+
+The standard bundle uses the target machine's ordinary Node.js and native runtime. On a legacy Linux x64 host, download the `-legacy-glibc228.tar.gz` bundle instead and run `./farming` once. After bootstrap, use `~/.farming/bin/farming`; that stable launcher keeps npm updates, server restarts, and PTY child processes on the bundled compatibility runtime.
+
+## Development
+
+```bash
+npm install
+npm start
+```
+
+For trusted local development only, token auth can be disabled:
+
+```bash
+npm run start:no-auth
+```
+
+## Configuration
+
+Runtime settings are stored in `~/.farming/settings.json`.
+Agent session metadata is stored separately in `~/.farming/sessions/`. Farming
+uses stable `fsess_*` files for its own Agent records; live `agent-...` ids and
+Codex / Claude provider session ids are stored as metadata on those records.
+The main Projects page membership lives in `sessions/index.json` and is exposed
+as `mainPageSessionKeys` only for API compatibility.
+Archived run history is stored in `~/.farming/history/runs.json`, not in
+`settings.json`.
+Theme overrides, the startup token, server pid/state/log files, and native pty
+host logs live under the same config directory.
+
+Common settings:
+
+- `defaultLaunchAgent`
+- `agentLaunchProfiles.codex`
+- `agentLaunchProfiles.claude`
+- `agentHomes` (home metadata for Codex, Claude, OpenCode, and Qoder; each provider keeps a non-removable `default` home)
+- `workspaceHistory`
+- `dangerouslySkipAgentPermissionsByDefault` (launch supported coding agents such as Codex, Claude, OpenCode, Qoder, Qwen, Aider, GitHub Copilot CLI, and Amazon Q with their provider-specific dangerous permission-skip flags by default)
+
+Native terminal sessions are owned by a Farming pty host reached through a local socket derived from `configDir`. By default the host is preserved during server shutdown so a restarted Farming server can recover live terminals; after the last live session and client disappear, the host shuts itself down after a short idle grace period. Set `FARMING_NATIVE_PTY_HOST_PERSIST=0` to tie the host lifetime to the server process. Terminal work should target the native pty host and xterm.js path.
+
+Update behavior follows the installation method. npm installations and legacy Linux installations bootstrapped from `-legacy-glibc228.tar.gz` read versions from the npm registry and provide one-click upgrades in **Settings → Updates**. They install into their existing npm prefix while the old service remains alive, then restart and roll back on startup failure. Source checkouts update through Git, and standalone CLI artifacts are replaced manually. Standard app-bundle installations remain a directory-deployment path and may use a trusted HTTP(S) package directory or manifest URL stored as `settings.updateUrl`.
+
+The simplest source is an HTTP(S) directory URL ending in `/` that lists platform-tagged `farming-<version>-<platform>-<arch>.tar.gz` app bundles and an adjacent `<bundle>.sha256` file for every bundle. Farming verifies the selected bundle's SHA-256 and archive layout before extraction, then runs its installer.
+
+Example deployment templates:
+
+- `config/farming.deploy.env.example`
+- `config/farming.install.env.example`
+
+Real `.env` files are ignored by git.
+
+## Security
+
+Farming controls real terminals and agent processes on the target machine. Run it on trusted development hosts and trusted networks. Do not expose it directly to the public internet without an additional layer such as VPN, SSH tunnel, HTTPS reverse proxy, or network ACLs.
+
+The startup token protects both HTTP and WebSocket traffic. It is generated on first authenticated startup, persisted in `~/.farming/.session-token`, and reused across restarts and upgrades. The generated token is designed to be easier to copy than a long hexadecimal secret: Chinese time zones get a Chinese haiku-style passphrase by default, Japanese time zones get a Japanese haiku-style passphrase, and other time zones get an English passphrase. `FARMING_TOKEN_LOCALE=zh|ja|en|auto` can override generation behavior for a new token.
+
+`FARMING_DISABLE_AUTH=1` is only for trusted local development. Terminal-owned Codex / Claude sessions apply a permission change by restarting with the selected CLI flags, resuming when a provider session id is available and starting fresh otherwise. App Server Codex applies the new approval and sandbox policy to its existing thread without a CLI restart.
+
+See [SECURITY.md](./SECURITY.md) for the reporting policy and deployment notes.
+
+## Troubleshooting
+
+- **No `codex` or `claude` option works**: verify the CLI is installed, logged in, and runnable from a normal shell on the same host.
+- **Native PTY cannot start**: verify the target system's Node.js and packaged `node-pty` runtime are compatible. On Linux x64 with glibc older than 2.28, use the `-legacy-glibc228` app bundle.
+- **Port already in use**: pass `--port <port>` or let the default daemon mode choose the next available port when no explicit port is provided.
+- **Phone cannot connect**: use the network URL printed by the server and make sure the phone can reach the target machine.
+- **Lost the token URL**: run `./farming url`, or check `./farming logs`.
+
+## Repository Layout
+
+```text
+farming/
+├── .gitattributes          # Source archive export rules
+├── backend/                 # Node.js server, session engines, and backend APIs
+├── src/                     # React + Vite frontend; Farming Code helpers live under src/components/code/
+├── frontend/skins/crt/      # Independent live CRT entry, app, and visual effects
+├── frontend/*.js            # Shared terminal/session browser bridges
+├── docs/products/code/      # Farming Code product docs and screenshots
+├── docs/products/crt/       # CRT skin layout docs
+├── config/                  # deployment / install templates
+├── scripts/                 # release, deployment, screenshots, tests
+├── tests/e2e/               # Playwright browser flows
+├── pkg.config.cjs
+└── bin/farming
+```
+
+`releases/` is a local packaging output directory and is not committed.
+
+## Tests
+
+```bash
+npm run check
+```
+
+Common individual checks:
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+npm run test:e2e:playwright
+```
+
+## Authors
+
+- [zhuwenzhuang](https://github.com/zhuwenzhuang)
+- [l4wei](https://github.com/l4wei)
+
+## Contributing
+
+Issues and pull requests are welcome. Start with [CONTRIBUTING.md](./CONTRIBUTING.md), and keep user-facing docs updated when behavior or packaging changes.
+
+## License
+
+Farming is released under the MIT License. See [LICENSE](./LICENSE).

package/README.zh_cn.md

@@ -0,0 +1,329 @@
+# Farming
+
+> English version: [README.md](./README.md)
+
+[![CI](https://github.com/zhuwenzhuang/farming/actions/workflows/ci.yml/badge.svg)](https://github.com/zhuwenzhuang/farming/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/zhuwenzhuang/farming?label=release)](https://github.com/zhuwenzhuang/farming/releases)
+[![npm](https://img.shields.io/npm/v/farming-code?label=npm)](https://www.npmjs.com/package/farming-code)
+[![License](https://img.shields.io/github/license/zhuwenzhuang/farming)](./LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)
+![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-555)
+
+Farming 是一个面向 AI coding agent 的远程浏览器工作台。当前公开版本是 **Farming 2**。
+
+它当前已经把远程 terminal、Codex / Claude Code、历史 session、项目级 agent、打开的编辑器、项目文件、搜索、轻量编辑、git review、usage 和机器状态收进同一个页面，减少人在 SSH、IDE、浏览器、监控页面和 agent 面板之间反复切换。
+
+远程托管和多端浏览器接入是 Farming 的内核能力：agent、shell、项目文件和 git 状态都留在远程机器上持续运行；用户可以从电脑端浏览器做长时间操作，也可以从手机浏览器随时回到现场，看进度、切 session，或者做一次轻量介入。Farming 2 把这套能力组织成一个面向 Codex / Claude Code 的浏览器工作台，当前默认 UI 皮肤叫 Farming Code。
+
+浏览器现在通过同一个后端提供两套实时 UI：`/farming/code/` 是 Farming Code，`/farming/crt/` 是原始 CRT 界面；`/farming/` 仍默认打开 Farming Code。当 Code 无法启动或渲染时，故障页面会在错误详情浮层后显示仍连接当前 Agent 的 CRT 界面，不会重启正在运行的 Agent。
+
+产品介绍、截图和架构图见 [Farming 2 Wiki](https://github.com/zhuwenzhuang/farming/wiki)。
+
+![Farming Code 工作台](./docs/products/code/assets/01-code-workspace.png)
+
+> 如果你是参与本仓库开发的 AI Agent，请先阅读 [`AGENTS.md`](./AGENTS.md)，中文版本见 [`AGENTS.zh_cn.md`](./AGENTS.zh_cn.md)。
+
+## 当前价值与长期目标
+
+当前阶段，Farming 做的是一件很实在的事：把指挥 AI coding agent 时最常打开的工具能力放到一起。用户可以在同一个远程工作台里看 live terminal、恢复 Codex / Claude session、检查文件、搜索代码、做小修改、看 blame、看 usage 和 CPU/MEM 状态。它不是完整 IDE，也不是新的 agent 模型；它先把“观察现场”和“轻量介入”这两个高频动作变短。
+
+远程托管是这里的关键价值。长任务可以继续跑在 Linux 开发机上，浏览器只是进入现场的入口；电脑端适合编辑、搜索、审查和长时间跟进，手机端适合离开电脑后查看状态、确认输出、发一句输入或启动一个简单 agent。这样用户不用把本地机器、远程 shell、agent session 和项目文件拆成几套上下文来回维护。
+
+更长期的目标仍然是人的注意力管理。人类注意力有限，也没有真正的多线程处理能力；当多个 agent 同时工作时，真正消耗人的不是某一个终端，而是在不同页面、不同任务状态和不同上下文之间反复切换。
+
+Farming 未来希望探索的是：让系统逐步判断哪些 agent 值得关注，哪些任务只是后台推进，哪些变化需要汇报，哪些地方需要人介入。Main Agent 是这个方向上的长期机制：它最终应该结合 Codex、Claude Code、shell agent 和更多工具型 agent，观察任务状态、组织子 agent、汇总进展，并减少人的上下文切换。
+
+这部分仍在探索中，是 Farming 的终极目标；Farming 2 先把工具整合和远程工作台体验做好，作为后续 Main Agent 和多 agent 注意力管理能力的基础。
+
+## Farming 2 带来的变化
+
+Farming 2 是本仓库最近最大的一次产品变化。它把 Farming 从一个较轻的复古 agent monitor，推进成了更实用的远程 coding workbench，也为长期的 Main Agent 注意力管理目标补齐底座：
+
+- 在浏览器里启动和管理 Codex、Claude、OpenCode、Qoder、bash 和 zsh session；
+- 发现并恢复 Codex、Claude、OpenCode 和 Qoder 的本地历史 session，再重新接入 Farming 托管的实时 terminal；
+- Codex / Claude 启动选项按 provider 收敛，不展示当前 agent 无法表达的控件；
+- 在一个工作区里组织 project-scoped agents、pinned/unread sessions、Search、History 和 active terminals；
+- 提供 Project Files：Open Editors、文件树、文件搜索、Monaco 编辑、Markdown/图片预览、git changes、git diff、行级 git blame；
+- terminal 输出里的 `path:line` 可直接打开文件，`http(s)` URL 可直接在新标签页打开；
+- Codex / Claude Composer 暴露底层运行时能表达的启动权限、模型和速度 profile；App Server Codex 会直接更新当前 thread 的权限，terminal-owned session 切换权限时才重启 CLI：已有 provider Session ID 时 resume，还没有可 resume 的 ID 时启动新会话；
+- Composer 支持文本附件；粘贴或选择图片时会保存到 Farming 服务侧 `~/.farming/attachments`，并把图片路径插入消息，便于远端 Codex / Claude 读取；Farming 自动生成的图片附件默认保留 7 天后清理；
+- 显示轻量 usage、context、token rate、quota 与机器状态，例如 CPU、MEM；
+- 复用 Farming 的远程托管和多端浏览器接入能力，让桌面和手机访问同一套远程 Linux 服务。
+
+具体截图、安装方式和产品说明见 [Farming 2 产品介绍](./docs/products/code/README.zh_cn.md)。
+
+## 快速开始
+
+默认推荐通过 npm 安装，把 Farming 运行在已经能正常执行 `codex` 或 `claude` 的开发机上。
+
+```bash
+npm install --global farming-code
+farming daemon
+```
+
+默认端口是 `6694`，浏览器路径是 `/farming`，配置目录是 `~/.farming`，并默认启用 token auth。首次鉴权启动会生成一个随机但可读的口令，并保存到 `~/.farming/.session-token`；之后重启和升级都会复用这个 token，除非显式设置 `FARMING_TOKEN`。在中文时区默认是中文俳句式口令，日本时区默认是日文俳句式口令，其它时区默认是英文短语。启动日志会打印类似下面的 URL：
+
+```text
+http://linux-host:6694/farming?token=<startup-token>
+```
+
+把完整 URL 复制到桌面或手机浏览器中打开，点击 `New Agent`，选择 `Codex`、`Claude Code`、`bash` 或 `zsh`，填入 workspace，就可以进入远程工作台。
+
+## 下载与部署形态
+
+npm 包是默认发布形态；也可以从 [GitHub Releases](https://github.com/zhuwenzhuang/farming/releases) 下载手动安装产物。
+
+Farming 2 当前有三种实际部署形态：
+
+| 环境 | 产物 | 适用场景 |
+| --- | --- | --- |
+| macOS 与 Linux | `npm install --global farming-code` | 默认路径，需要 Node.js 22+，并且系统 runtime 能加载 `node-pty`。 |
+| 不使用 npm 的环境 | GitHub Releases 平台 CLI | 手动安装，升级也需要手动替换。 |
+| 目录部署 | `farming-<version>-<platform>-<arch>.tar.gz` | 包含 production dependencies 和 launcher 脚本的 App Bundle，直接使用目标系统 runtime。 |
+| 老 Linux x64（glibc < 2.28） | `farming-<version>-linux-x64-legacy-glibc228.tar.gz` | 带固定 glibc 2.28 runtime 的首次安装引导包。它把 Farming 安装到 `~/.farming/npm`；后续与普通 npm 安装一样一键更新。目标机仍需 Node.js 22 和 npm。 |
+| 自建老 Linux 包 | `farming-<version>-linux-x64-glibc217.tar.gz` | 独立构建的兼容包；基于 glibc 2.17 重新编译 `node-pty`，但仍要求目标机有可用的 Node.js runtime。 |
+
+如果要通过 Farming 启动 Codex 或 Claude Code，同一台机器上仍然需要提前安装并登录对应 CLI。Farming 托管的是这些 CLI session，不替代它们自己的安装和账号流程。
+
+## 架构
+
+```text
+浏览器皮肤
+  React + Vite + Monaco + terminal renderer
+        |
+        | HTTP / WebSocket
+        v
+Farming 内核
+  Express server + token auth + agent manager + session providers
+        |
+        | native pty host + session engine
+        v
+执行环境
+  bash / zsh / Codex / Claude Code
+```
+
+内核负责 agent 生命周期、WebSocket 状态同步、session engine、workspace 文件 API、历史 session provider、模型/profile 发现、usage 采集和配置管理。产品皮肤负责把这些能力组织成不同体验。新的交互 session 默认使用 native pty host：node-pty agent 进程放在独立 host 进程里，Farming server 和浏览器可以重新连回仍存活的 terminal。native pty host 默认会跨 Farming server 重启保留；当没有 live session 和 client 后会在空闲宽限期后退出。只有希望 host 跟随 server 一起退出时才设置 `FARMING_NATIVE_PTY_HOST_PERSIST=0`。只有调试进程内 node-pty engine 时才设置 `FARMING_SESSION_ENGINE=local`。
+
+浏览器 terminal renderer 默认使用 xterm.js。旧的 Ghostty web renderer 仍保留为显式调试路径，可通过 `localStorage.farmingTerminalEngine = 'ghostty'` 切换。
+
+## 安装与发布
+
+Farming 2 最适合运行在一台 Linux 开发机上；这台机器里应当已经能在普通 SSH shell 中正常运行 Codex 或 Claude Code。
+
+默认安装方式：
+
+```bash
+npm install --global farming-code
+farming daemon
+```
+
+npm 安装后可在 **设置 → 更新** 一键升级。Farming 会先在旧服务仍运行时完成 npm 安装，安装成功后才重启；如果新服务无法启动，会尝试恢复旧版本。等价的手动命令是 `npm install --global farming-code@latest`。
+
+兼容发布形态主要有两种：
+
+- 单文件 CLI：适合现代 Linux 和 macOS，拿到一个 `farming` 可执行文件后直接运行。
+- App bundle：适合目录式部署；包是一个 tarball，解压后通过根目录 `./farming` 脚本启动，脚本负责 Node heap 和运行环境。
+
+源码远程部署脚本是开发团队把当前 checkout 部署到固定 Linux 机器的便捷路径。
+
+如果要启动 Codex 或 Claude Code，目标机器上还需要提前安装并登录对应 CLI，确保在普通 SSH shell 中直接运行 `codex` 或 `claude` 能进入交互。
+
+### 从源码打包
+
+构建单文件 CLI：
+
+```bash
+npm install
+npm run release:cli
+```
+
+构建可解压运行的 app bundle：
+
+```bash
+npm install
+npm run release:app
+```
+
+`release:app` 会生成 `releases/<version>/farming-<version>-<platform>-<arch>.tar.gz`，包内包含已经构建好的前端、production dependencies 和根目录启动脚本，使用目标系统 runtime。
+
+如果目标是 glibc 低于 2.28 的 Linux x64，构建带固定 glibc 2.28 runtime 的发布资产：
+
+```bash
+npm run release:app:legacy-linux
+```
+
+它会生成 `farming-<version>-linux-x64-legacy-glibc228.tar.gz`。这是首次安装引导包：安装器把 runtime 解压到 `~/.farming/glibc228`，把包内 Farming 版本放入私有 prefix `~/.farming/npm`，并生成稳定入口 `~/.farming/bin/farming`。后续普通版本更新直接通过 npm 安装到同一 prefix，再用兼容 launcher 重启；不需要反复下载兼容 tar。
+
+如果只需要将 `node-pty` 编译到更低 ABI，仍可在干净的 Linux x64 构建环境中准备 glibc 2.17、Node.js 22+、GCC/G++、Make 和 Python 3，然后运行：
+
+```bash
+npm run release:app:linux-compat
+```
+
+该命令会强制从源码编译 `node-pty`，并在其 native module 依赖高于 glibc 2.17 时拒绝产物。远程安装使用 `FARMING_REMOTE=user@host FARMING_RELEASE_TARBALL=<archive> npm run release:remote:linux-compat`。这个 ABI 包仍使用目标机器自己的 Node.js 和 libc。
+
+如果已经在配置好的 Linux x64 构建机上准备了干净源码，`scripts/build-linux-compat-release-on-builder.sh` 可以继续自动完成容器构建、ABI 校验、打包后 bash Agent 冒烟和产物输出。通过 `FARMING_COMPAT_IMAGE` 指定构建机上已经存在的镜像。脚本使用 `--pull=never`，并默认关闭容器网络，以复用已有镜像和缓存，避免发布时隐式下载构建环境；只有确实需要主动刷新缓存时才设置 `FARMING_COMPAT_ALLOW_NETWORK=1`。
+
+### 启动单文件 CLI
+
+拿到对应平台的单文件 `farming` 后：
+
+```bash
+chmod +x farming
+./farming daemon
+```
+
+它会优先监听 `6694`、挂载到 `/farming`，并自动创建 `~/.farming/settings.json`、token 文件和必要运行目录；如果未显式指定端口且 `6694` 已占用，会自动上探选择可用端口。启动后终端会打印带 token 的浏览器 URL。前台运行可直接执行 `./farming` 或 `./farming start`；常用管理命令是 `./farming status`、`./farming logs`、`./farming stop`。
+
+### 启动 app bundle
+
+普通 Linux 上：
+
+```bash
+tar -xzf farming-<version>-linux-x64.tar.gz
+cd farming-<version>-linux-x64
+./farming
+```
+
+标准包的启动脚本直接使用目标机器的普通 Node.js 和 native runtime。glibc 低于 2.28 的 Linux x64 请改用 `-legacy-glibc228` 包并执行一次 `./farming` 完成引导；之后使用 `~/.farming/bin/farming`。这个稳定入口保证 npm 更新、server 重启和 PTY 子进程都继续经过兼容 runtime。
+
+App bundle 常用命令：
+
+```bash
+./farming status
+./farming logs
+./farming stop
+./farming start
+./farming url
+```
+
+### 源码远程部署
+
+如果本机可以 SSH 到目标 Linux，且已经配置 `config/farming.deploy.env`：
+
+```bash
+npm run release:remote
+```
+
+这条路径会从当前源码 checkout 构建 app bundle、上传到远端、安装并启动服务，适合团队开发和 dogfood。
+
+### 开发调试
+
+只在本地开发 Farming 本身时，才需要直接启动源码服务：
+
+```bash
+npm install
+npm start
+```
+
+服务启动后会打印一个 token URL。仅在可信本地开发环境中，可以关闭 token 校验：
+
+```bash
+npm run start:no-auth
+```
+
+远程安装和 release 细节见 [`docs/products/code/README.zh_cn.md`](./docs/products/code/README.zh_cn.md)。
+
+## 配置
+
+运行时配置存储在 `~/.farming/settings.json`。
+Agent session 元数据单独存储在 `~/.farming/sessions/`。Farming 使用稳定的
+`fsess_*` 文件作为自己的 Agent 记录；live `agent-...` id 以及 Codex / Claude
+provider session id 都作为这些记录上的元数据保存。主页面 Projects membership
+存放在 `sessions/index.json`，`mainPageSessionKeys` 只是为兼容 API 暴露出来的投影。
+归档 run/history 存储在 `~/.farming/history/runs.json`，不属于 `settings.json`。
+主题覆盖配置、启动 token、server pid/state/log 文件和 native pty host 日志也都在同一个 config 目录下。
+
+主要用户配置项：
+
+- `defaultLaunchAgent`：New Agent 默认 provider，目前是 `codex` 或 `claude`；
+- `agentLaunchProfiles.codex`：Codex 的启动权限、模型、reasoning、service tier profile；
+- `agentLaunchProfiles.claude`：Claude 的启动 permission、model、effort profile；
+- `agentHomes`：管理 Codex、Claude、OpenCode、Qoder 的 agent home 元数据，每项只包含 `id` 和 `path`；每个 provider 都保留不可删除的 `default` home；
+- `workspaceHistory`：New Agent 启动时使用的最近 workspace；
+- `dangerouslySkipAgentPermissionsByDefault`：是否默认让支持的 coding agent（如 Codex、Claude、OpenCode、Qoder、Qwen、Aider、GitHub Copilot CLI、Amazon Q）使用各自最激进的权限绕过启动 flag。
+
+Native terminal session 由 Farming pty host 托管，通过从 `configDir` 派生的本地 socket 连接。默认保留 host 以支持 server 重启恢复；最后一个 live session 和 client 都消失后，host 会在短暂空闲宽限期后自退出。后续 terminal runtime 工作应面向 native pty host 和 xterm.js 链路。
+
+更新行为跟随安装方式：普通 npm 安装和通过 `-legacy-glibc228.tar.gz` 引导的老 Linux 安装都读取 npm registry，并在 **设置 → 更新** 提供一键升级。更新先安装到原有 npm prefix，旧服务在安装期间继续运行；随后重启，新服务启动失败时回退。源码 checkout 通过 Git 更新，单文件 CLI 手动替换。标准 App bundle 仍作为目录部署路径，可使用保存在 `settings.updateUrl` 中的可信 HTTP(S) 包目录或 manifest URL。
+
+最简单的更新源是一个以 `/` 结尾的 HTTP(S) 目录 URL，目录里列出带平台标记的 `farming-<version>-<platform>-<arch>.tar.gz` app bundle，并为每个 bundle 提供相邻的 `<bundle>.sha256` 文件。Farming 会在解压前校验所选 bundle 的 SHA-256 与归档路径，再运行 installer。
+
+部署配置模板位于 `config/`：
+
+- `config/farming.deploy.env.example`
+- `config/farming.install.env.example`
+
+真实 `.env` 配置文件会被 git 忽略。
+
+## 安全
+
+Farming 可以控制目标机器上的真实 terminal 和 agent 进程，适合运行在可信开发机和可信网络中。不要在没有 VPN、SSH tunnel、HTTPS 反向代理或网络 ACL 等额外安全层的情况下直接暴露到公网。
+
+启动 token 会同时保护 HTTP 页面和 WebSocket 连接。它在首次鉴权启动时随机生成，持久保存到 `~/.farming/.session-token`，并在后续重启和升级中复用。生成的新 token 刻意做成比长十六进制串更容易复制的可读口令：中文时区默认生成中文俳句式口令，日本时区默认生成日文俳句式口令，其它时区默认生成英文短语；也可以用 `FARMING_TOKEN_LOCALE=zh|ja|en|auto` 显式指定新 token 的生成语言。
+
+`FARMING_DISABLE_AUTH=1` 只应该用于可信本地开发环境。terminal-owned 的 Codex / Claude session 切换权限时会用所选 flag 重启 CLI：已有 provider Session ID 时会 resume，还没有可 resume 的 ID 时启动新会话。App Server Codex 则直接在当前 thread 上更新审批和 sandbox 策略，不启动 CLI。
+
+安全上报和部署注意事项见 [SECURITY.md](./SECURITY.md)。
+
+## 排错
+
+- **Codex 或 Claude Code 无法启动**：先确认同一台机器上对应 CLI 已安装、已登录，并能在普通 shell 中直接运行。
+- **Native PTY 无法启动**：检查目标系统的 Node.js 与打包的 `node-pty` runtime 是否兼容；glibc 低于 2.28 的 Linux x64 请使用 `-legacy-glibc228` 包。
+- **端口占用**：可以传 `--port <port>`；如果没有显式指定端口，默认 daemon 启动会自动上探选择可用端口。
+- **手机访问不了**：使用启动日志里打印的 Network URL，并确认手机能访问目标开发机。
+- **找不到 token URL**：运行 `./farming url`，或查看 `./farming logs`。
+
+## 目录结构
+
+```text
+farming/
+├── .gitattributes          # 源码归档 export-ignore 规则
+├── backend/                 # Node.js server、session engine、agent manager、session/history/usage/file/slash-command APIs
+├── src/                     # React + Vite 前端；Farming Code 皮肤与交互 helper 位于 src/components/code/
+├── frontend/skins/crt/      # 独立的实时 CRT 入口、应用逻辑与视觉效果
+├── frontend/*.js            # 多皮肤共享的 terminal/session 浏览器 bridge
+├── docs/
+│   ├── products/code/       # Farming 2 产品介绍、Farming Code 皮肤截图、安装说明和验收 dogfood 方案
+│   └── products/crt/        # CRT 皮肤 README 和布局说明
+├── config/                  # 部署 / 安装配置模板
+├── scripts/                 # 部署、release、测试、产品截图和辅助脚本
+├── tests/e2e/               # Playwright 展示与浏览器流程测试
+├── reference/               # 外部项目源码、工具链和调研 walkthrough；不作为 Farming 运行时依赖
+├── pkg.config.cjs           # 平台 CLI 应用打包配置（@yao-pkg/pkg + legacy pkg）
+└── bin/farming              # 开发态产品 CLI；发布后二进制也叫 farming
+```
+
+公开产品文档现在从根 README 和 `docs/products/` 下的皮肤 README 进入。`releases/` 是本地打包输出目录，不提交到源码仓库。
+
+## 测试
+
+运行主检查：
+
+```bash
+npm run check
+```
+
+常用单项命令：
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+npm run test:e2e:playwright
+```
+
+Playwright 测试会在合适位置使用 fake coding-agent executable，常规 UI 回归不会消耗真实 Codex / Claude 额度。
+
+## 作者
+
+- [zhuwenzhuang](https://github.com/zhuwenzhuang)
+- [l4wei](https://github.com/l4wei)
+
+## 贡献
+
+欢迎提交 issue 和 pull request。开始前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)；如果改动影响用户可见行为、打包方式或部署方式，请同步更新 README、产品文档和相关验收说明。
+
+## License
+
+MIT