farming-code 2.2.6 → 2.2.8

package/README.zh_cn.md

@@ -9,321 +9,177 @@
 ![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**。
+Farming 是一个运行在开发机上的浏览器 AI Coding Agent 工作台。它把多个实时 Agent、结构化对话、真实终端、项目文件、Review、历史记录和运行时控制放在一起，同时代码仓库和 Agent 进程仍然留在开发机上。
 
-它当前已经把远程 terminal、Codex / Claude Code、历史 session、项目级 agent、打开的编辑器、项目文件、搜索、轻量编辑、git review、usage 和机器状态收进同一个页面，减少人在 SSH、IDE、浏览器、监控页面和 agent 面板之间反复切换。
+把 Farming 运行在你平时使用 Coding CLI 的机器旁边，就可以从电脑或手机回到同一批工作。关闭浏览器不会停止 Agent；Farming Server 重启时，独立的原生 PTY Host 也可以保留正在运行的终端会话。
 
-远程托管和多端浏览器接入是 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 在同一批 Agent 和 Session 上提供两套完整的浏览器界面。
 
-产品介绍、截图和架构图见 [Farming 2 Wiki](https://github.com/zhuwenzhuang/farming/wiki)。
+### Farming Code
 
-![Farming Code 工作台](./docs/products/code/assets/01-code-workspace.png)
+默认工作台，适合阅读对话、介入任务、编辑文件，以及持续 Review 同一个演进中的修改。
 
-> 如果你是参与本仓库开发的 AI Agent，请先阅读 [`AGENTS.md`](./AGENTS.md)，中文版本见 [`AGENTS.zh_cn.md`](./AGENTS.zh_cn.md)。
+![Farming Code 结构化 Chat](./docs/products/code/assets/11-code-agent-process.png)
 
-## 当前价值与长期目标
+### Farming CRT
 
-当前阶段，Farming 做的是一件很实在的事：把指挥 AI coding agent 时最常打开的工具能力放到一起。用户可以在同一个远程工作台里看 live terminal、恢复 Codex / Claude session、检查文件、搜索代码、做小修改、看 blame、看 usage 和 CPU/MEM 状态。它不是完整 IDE，也不是新的 agent 模型；它先把“观察现场”和“轻量介入”这两个高频动作变短。
+键盘优先的控制室，适合同时观察多个 Agent、打开结构化 Chat 或原生 Terminal、搜索历史和查看实时用量遥测。
 
-远程托管是这里的关键价值。长任务可以继续跑在 Linux 开发机上，浏览器只是进入现场的入口；电脑端适合编辑、搜索、审查和长时间跟进，手机端适合离开电脑后查看状态、确认输出、发一句输入或启动一个简单 agent。这样用户不用把本地机器、远程 shell、agent session 和项目文件拆成几套上下文来回维护。
+![Farming CRT 控制台](./docs/products/crt/assets/01-crt-dashboard.png)
 
-更长期的目标仍然是人的注意力管理。人类注意力有限，也没有真正的多线程处理能力；当多个 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，就可以进入远程工作台。
+| | Farming Code | Farming CRT |
+| --- | --- | --- |
+| 更适合 | 长对话、文件、编辑、Diff、Review | 总览监控、键盘控制、终端操作、遥测 |
+| 实时 Session | 结构化 Chat 与真实 PTY Terminal | 磷光风格 Chat 与真实 xterm Terminal |
+| 导航方式 | 项目侧栏、Search、History、Files | 稳定 Agent 机位和键盘控制台 |
+| 外观 | 浅色与深色 | CRT 效果、终端字号、可选 Dynamic Heat |
+| 入口 | `/farming/code/` 或 `/farming/` | `/farming/crt/` |
 
-## 下载与部署形态
+切换界面不会重启或复制 Agent。如果 Farming Code 启动或渲染失败，有限范围的诊断层仍会保留后面的实时 CRT 界面，而不是把正在运行的 Session 一起遮掉。
 
-npm 包是默认发布形态；也可以从 [GitHub Releases](https://github.com/zhuwenzhuang/farming/releases) 下载手动安装产物。
+完整能力矩阵和截图导览见 [Farming 2 产品总览](./docs/products/README.zh_cn.md)。两套界面的完整流程分别见 [Farming Code 指南](./docs/products/code/README.zh_cn.md) 和 [Farming CRT 指南](./docs/products/crt/README.zh_cn.md)。
 
-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。 |
+- 按项目组织实时 Agent，置顶重点工作、重命名、查看未读状态，并归档或恢复任务。
+- Codex、Claude Code、OpenCode 和 Qoder 使用结构化 ACP Chat。计划、推理、工具调用、权限请求、内嵌终端、子 Session、附件、排队追问和精确修改摘要都可以保留，但不会淹没最终答案。
+- 需要原汁原味 CLI 行为时打开真实 PTY Terminal。Chat / Terminal 切换会改变实际运行时，并在身份可用时安全地恢复同一个 Provider Session。
+- 修改运行中 Codex 所支持的模型、思考强度、Fast、Ultra 和权限设置。Terminal 的修改会在下一条消息前作用到当前工作流，而不是只改未来的启动 Profile。
+- 浏览 Project Files 和 Open Editors，用 ripgrep 搜索、Monaco 轻量编辑、预览 Markdown/图片、跟随 `path:line` 链接，并检查 Git Changes、Diff 和 Blame。
+- 围绕同一个演进中的 Change 跨 Revision Review，让 Finding 与对比版本绑定，标记文件已审阅，并关注多轮之间真正有意义的变化。
+- 搜索实时 Agent 和受支持 Provider 的完整 Session 归档，然后打开、继续、恢复或 Resume 对应工作。
+- 在 Provider 提供所需数据时查看 CPU/MEM、Token Rate、Context、Quota、Provider 用量，以及 CRT 的按日/实时 Token 遥测。
+- 在电脑和手机浏览器中使用同一个服务；不同布局围绕不同设备上可用的注意力设计。
 
-如果要通过 Farming 启动 Codex 或 Claude Code，同一台机器上仍然需要提前安装并登录对应 CLI。Farming 托管的是这些 CLI session，不替代它们自己的安装和账号流程。
+![Farming Code 项目文件与 Blame](./docs/products/code/assets/04-files-editor-blame.png)
 
-## 架构
+![Farming Review](./docs/products/code/assets/10-review-workflow.png)
 
-```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 路径
 
-内核负责 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`。
+Farming 会发现开发机上已经安装的 CLI。有 ACP 支持的 Provider 使用更完整的结构化运行时，其他检测到的 Coding Agent 仍然可以作为一等 Terminal Session 使用。
 
-浏览器 terminal renderer 默认使用 xterm.js。旧的 Ghostty web renderer 仍保留为显式调试路径，可通过 `localStorage.farmingTerminalEngine = 'ghostty'` 切换。
+| Agent | 结构化 Chat | 原生 Terminal | History / Resume |
+| --- | --- | --- | --- |
+| Codex | ACP | 是 | 是 |
+| Claude Code | ACP | 是 | 是 |
+| OpenCode | ACP | 是 | 是 |
+| Qoder | ACP | 是 | 是 |
+| Qwen Code | — | 是 | 取决于 CLI |
+| Aider | — | 是 | 取决于 CLI |
+| GitHub Copilot CLI | — | 是 | 取决于 CLI |
+| Amazon Q | — | 是 | 取决于 CLI |
+| bash / zsh | — | 是 | 没有 Provider Session Resume |
 
-## 安装与发布
+Farming 承载的是已经能在同一台机器正常工作的 CLI，不替代 Provider 的安装、登录和账户配置。
 
-Farming 2 最适合运行在一台 Linux 开发机上；这台机器里应当已经能在普通 SSH shell 中正常运行 Codex 或 Claude Code。
+## 快速开始
 
-默认安装方式：
+安装 Node.js 22 或更新版本，并先安装、登录至少一个受支持的 Coding CLI：
 
 ```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。
+默认端口是 `6694`，Base Path 是 `/farming`，配置目录是 `~/.farming`，Token 鉴权默认开启。启动日志会打印类似下面的 URL：
 
-如果只需要将 `node-pty` 编译到更低 ABI，仍可在干净的 Linux x64 构建环境中准备 glibc 2.17、Node.js 22+、GCC/G++、Make 和 Python 3，然后运行：
-
-```bash
-npm run release:app:linux-compat
+```text
+http://development-host:6694/farming?token=<startup-token>
 ```
 
-该命令会强制从源码编译 `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` 后：
+打开 URL，选择 **New Agent**、Agent 类型和 Workspace，然后从 Chat 或 Terminal 开始工作。常用守护进程命令：
 
 ```bash
-chmod +x farming
-./farming daemon
+farming status
+farming url
+farming logs
+farming stop
 ```
 
-它会优先监听 `6694`、挂载到 `/farming`，并自动创建 `~/.farming/settings.json`、token 文件和必要运行目录；如果未显式指定端口且 `6694` 已占用，会自动上探选择可用端口。启动后终端会打印带 token 的浏览器 URL。前台运行可直接执行 `./farming` 或 `./farming start`；常用管理命令是 `./farming status`、`./farming logs`、`./farming stop`。
+第一次带鉴权启动会把随机、可读的 Token 写入 `~/.farming/.session-token`；后续重启和升级都会复用，除非显式设置 `FARMING_TOKEN`。Token 默认根据时区使用中文、日文或英文。
 
-### 启动 app bundle
+![启动 Agent](./docs/products/code/assets/02-start-agent-picker.png)
 
-普通 Linux 上：
+## 桌面与手机
 
-```bash
-tar -xzf farming-<version>-linux-x64.tar.gz
-cd farming-<version>-linux-x64
-./farming
-```
+桌面端把项目、对话、文件和 Review 放在彼此靠近的位置。移动端一次聚焦一段对话、一个终端或一个文件，并把导航移入抽屉，更适合查看进度和发送短介入。
 
-标准包的启动脚本直接使用目标机器的普通 Node.js 和 native runtime。glibc 低于 2.28 的 Linux x64 请改用 `-legacy-glibc228` 包并执行一次 `./farming` 完成引导；之后使用 `~/.farming/bin/farming`。这个稳定入口保证 npm 更新、server 重启和 PTY 子进程都继续经过兼容 runtime。
+<p align="center">
+  <img src="./docs/products/code/assets/05-mobile-agent-chat.jpg" alt="Farming Code 手机界面" width="320">
+  &nbsp;&nbsp;
+  <img src="./docs/products/crt/assets/09-crt-mobile-dashboard.jpg" alt="Farming CRT 手机界面" width="320">
+</p>
 
-App bundle 常用命令：
+## 安装与更新
 
-```bash
-./farming status
-./farming logs
-./farming stop
-./farming start
-./farming url
-```
+npm 包是默认分发方式。**Settings → Updates** 可以原地升级 npm 安装：Farming 会在当前 Server 仍运行时安装新包，只在安装成功后重启；新 Server 无法启动时会尝试回退。
 
-### 源码远程部署
+GitHub Releases 也提供独立 CLI 和目录 Bundle。旧版 Linux x64 可以用 `linux-x64-legacy-glibc228` 完成第一次安装，后续应用更新继续使用同一个私有 npm Prefix。受控环境还可以单独构建 glibc 2.17 ABI Bundle。当前产物和版本说明见 [GitHub Releases](https://github.com/zhuwenzhuang/farming/releases)。
 
-如果本机可以 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 目录下。
-
-主要用户配置项：
+只有在可信本地开发环境中，才可以用 `npm run start:no-auth` 关闭 Token 鉴权。
 
-- `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/`：
+```text
+Farming Code / Farming CRT
+  React, Monaco, xterm.js, CRT browser skin
+                 │ HTTP + WebSocket
+                 ▼
+Farming core
+  auth, Agent manager, ACP, history, files, review, usage
+                 │ native PTY host + session providers
+                 ▼
+Development host
+  repositories, shells, Codex, Claude Code, OpenCode, Qoder, ...
+```
 
-- `config/farming.deploy.env.example`
-- `config/farming.install.env.example`
+后端负责生命周期、鉴权、Session 路由、Workspace 边界、History 和配置。交互式 Terminal 默认由独立的原生 PTY Host 持有，因此浏览器和 Server 可以重新连接，而不需要替换实际进程。xterm.js 是产品默认终端渲染器；Ghostty Web Adapter 只保留为显式调试路径。
 
-真实 `.env` 配置文件会被 git 忽略。
+运行时设置存放在 `~/.farming/settings.json`。Farming Session 元数据、项目成员索引、归档运行、主题设置、更新状态、日志和启动 Token 使用 `~/.farming/` 下彼此独立的文件。外部 Provider History 仍然只读。
 
 ## 安全
 
-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`。
-
-## 目录结构
+Farming 会控制目标机器上的真实终端和文件。请只运行在可信开发机和可信网络中，不要在没有 VPN、SSH Tunnel、HTTPS Reverse Proxy 或等价访问控制时直接暴露到公网。
 
-```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/` 是本地打包输出目录，不提交到源码仓库。
+Token 鉴权同时保护 HTTP 和 WebSocket。`FARMING_DISABLE_AUTH=1` 只适合可信本地开发；Workspace 文件 API 会校验所有路径都位于所选项目根目录内。报告和部署说明见 [SECURITY.md](./SECURITY.md)。
 
-## 测试
+## 文档
 
-运行主检查：
-
-```bash
-npm run check
-```
+- [Farming 2 产品总览与能力矩阵](./docs/products/README.zh_cn.md)
+- [Farming Code 指南](./docs/products/code/README.zh_cn.md)
+- [Farming CRT 指南](./docs/products/crt/README.zh_cn.md)
+- [移动端指南](./docs/products/code/mobile-guide.zh_cn.md)
+- [ACP 运行时](./docs/products/code/acp-runtime.zh_cn.md)
+- [Review 基础](./docs/products/code/review-foundation.zh_cn.md)
+- [版本历史](https://github.com/zhuwenzhuang/farming/releases)
+- [贡献者说明](./AGENTS.zh_cn.md)
 
-常用单项命令：
+## 开发检查
 
 ```bash
 npm test
 npm run typecheck
 npm run lint
+FARMING_BASE_PATH=/farming npm run build
 npm run test:e2e:playwright
 ```
 
-Playwright 测试会在合适位置使用 fake coding-agent executable，常规 UI 回归不会消耗真实 Codex / Claude 额度。
+产品截图由匿名 Demo Workspace 和真实浏览器流程生成：
 
-## 作者
-
-- [zhuwenzhuang](https://github.com/zhuwenzhuang)
-- [l4wei](https://github.com/l4wei)
-
-## 贡献
-
-欢迎提交 issue 和 pull request。开始前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)；如果改动影响用户可见行为、打包方式或部署方式，请同步更新 README、产品文档和相关验收说明。
+```bash
+npm run docs:product:screenshots
+```
 
 ## License
 
-MIT
+Farming 使用 [MIT License](./LICENSE)。第三方组件声明见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。

package/backend/acp-runtime.js

@@ -23,6 +23,7 @@ const DEFAULT_CANCEL_TIMEOUT_MS = 15_000;
 const DEFAULT_HISTORY_REPLAY_MIN_WAIT_MS = 350;
 const DEFAULT_HISTORY_REPLAY_QUIET_MS = 150;
 const DEFAULT_HISTORY_REPLAY_MAX_WAIT_MS = 5_000;
+const CODEX_SET_SESSION_MODEL_METHOD = 'session/set_model';
 
 let sdkPromise;
 const runtimeRequire = createRequire(__filename);
@@ -386,6 +387,16 @@ class AcpRuntime extends EventEmitter {
       binding.configOptions = sessionResponse?.configOptions || [];
       binding.sessionState.currentModeId = String(binding.modes?.currentModeId || '');
       binding.sessionState.configOptions = JSON.parse(JSON.stringify(binding.configOptions));
+      if (provider === 'codex' && options.serviceTier && options.serviceTier !== 'config') {
+        const fastOption = binding.configOptions.find(option => (
+          option.type === 'boolean'
+          && /fast/i.test(`${option.id || ''} ${option.name || ''} ${option.category || ''}`)
+        ));
+        const fastEnabled = ['fast', 'priority'].includes(options.serviceTier);
+        if (fastOption && fastOption.currentValue !== fastEnabled) {
+          await this.applySessionConfigOption(binding, fastOption.id, fastEnabled, { emit: false });
+        }
+      }
       binding.state = 'idle';
       binding.updatedAt = new Date().toISOString();
       this.emitRuntime(binding);
@@ -857,6 +868,87 @@ class AcpRuntime extends EventEmitter {
 
   async setSessionConfigOption(agentId, configId, value) {
     const binding = this.requireBinding(agentId);
+    const option = binding.configOptions?.find(candidate => candidate.id === String(configId || ''));
+    if (
+      binding.provider === 'codex'
+      && option?.type === 'select'
+      && /(^|[\s_-])model([\s_-]|$)/i.test(`${option.id} ${option.name || ''} ${option.category || ''}`)
+    ) {
+      // Let the adapter choose a supported fallback effort from its current
+      // snapshot first. The refresh extension requires an explicit effort and
+      // would otherwise reject a valid model change (for example ultra -> a
+      // model that tops out at max).
+      await this.applySessionConfigOption(binding, configId, value, { emit: false });
+      const reasoning = binding.configOptions?.find(candidate => (
+        candidate.type === 'select'
+        && /(reasoning|thought)/i.test(`${candidate.id} ${candidate.name || ''} ${candidate.category || ''}`)
+      ));
+      if (typeof reasoning?.currentValue === 'string' && reasoning.currentValue) {
+        await this.refreshCodexSessionModel(binding, String(value ?? ''), reasoning.currentValue);
+        return this.applySessionConfigOption(binding, configId, value);
+      }
+      this.emitSession(binding);
+      return { sessionId: binding.sessionId, configOptions: binding.configOptions };
+    }
+    return this.applySessionConfigOption(binding, configId, value);
+  }
+
+  async setSessionConfigOptions(agentId, changes) {
+    const binding = this.requireBinding(agentId);
+    const normalized = Array.isArray(changes)
+      ? changes.filter(change => change && typeof change.configId === 'string' && Object.prototype.hasOwnProperty.call(change, 'value'))
+      : [];
+    if (normalized.length === 0) throw new Error('ACP config options are required');
+
+    const configById = new Map((binding.configOptions || []).map(option => [option.id, option]));
+    const modelChange = normalized.find(change => {
+      const option = configById.get(change.configId);
+      return option?.type === 'select'
+        && /(^|[\s_-])model([\s_-]|$)/i.test(`${option.id} ${option.name || ''} ${option.category || ''}`);
+    });
+    const reasoningChange = normalized.find(change => {
+      const option = configById.get(change.configId);
+      return option?.type === 'select'
+        && /(reasoning|thought)/i.test(`${option.id} ${option.name || ''} ${option.category || ''}`);
+    });
+
+    let response;
+    const handled = new Set();
+    if (binding.provider === 'codex' && modelChange && reasoningChange) {
+      await this.applySessionConfigOption(binding, modelChange.configId, modelChange.value, { emit: false });
+      await this.applySessionConfigOption(binding, reasoningChange.configId, reasoningChange.value, { emit: false });
+      const currentReasoning = binding.configOptions?.find(candidate => (
+        candidate.type === 'select'
+        && /(reasoning|thought)/i.test(`${candidate.id} ${candidate.name || ''} ${candidate.category || ''}`)
+      ));
+      await this.refreshCodexSessionModel(
+        binding,
+        String(modelChange.value ?? ''),
+        String(currentReasoning?.currentValue || reasoningChange.value || '')
+      );
+      response = await this.applySessionConfigOption(binding, modelChange.configId, modelChange.value);
+      handled.add(modelChange);
+      handled.add(reasoningChange);
+    }
+    for (const change of normalized) {
+      if (handled.has(change)) continue;
+      response = await this.setSessionConfigOption(agentId, change.configId, change.value);
+    }
+    return response;
+  }
+
+  async refreshCodexSessionModel(binding, model, effort) {
+    await withTimeout(
+      binding.connection.request(CODEX_SET_SESSION_MODEL_METHOD, {
+        sessionId: binding.sessionId,
+        modelId: `${model}[${effort}]`,
+      }),
+      this.requestTimeoutMs,
+      'Codex ACP session/set_model capability refresh'
+    );
+  }
+
+  async applySessionConfigOption(binding, configId, value, options = {}) {
     const request = typeof value === 'boolean'
       ? { sessionId: binding.sessionId, configId: String(configId || ''), type: 'boolean', value }
       : { sessionId: binding.sessionId, configId: String(configId || ''), value: String(value ?? '') };
@@ -867,7 +959,7 @@ class AcpRuntime extends EventEmitter {
     );
     binding.configOptions = response?.configOptions || binding.configOptions;
     binding.sessionState.configOptions = JSON.parse(JSON.stringify(binding.configOptions));
-    this.emitSession(binding);
+    if (options.emit !== false) this.emitSession(binding);
     return { sessionId: binding.sessionId, configOptions: binding.configOptions };
   }