afucontext 0.1.19 → 0.1.21

package/README.md

@@ -16,17 +16,17 @@ In a long session, the same tool output can travel with every model request. AFU
 
 ## Quick start
 
-Install and sign in to your host first. You need npm, Node.js **22.19+ (22.x) or 24+** and Python **3.11+** on `PATH`. Pick one row, run the install command in your terminal, then use the launch command.
+Install and sign in to your host first. You need npm, Node.js **22.19+ (22.x) or 24+** and Python **3.11+** on `PATH`. Pick one row, run the install command in your terminal (the first npx run asks once to install the package; press Enter), then use the launch command. After that, add hosts, upgrade and remove with `afuctx`; see [Commands](#commands).
 
 | Host | System | Install | Launch after installation | Tested version |
 | --- | --- | --- | --- | --- |
-| <a id="afu-claude"></a>Claude Code | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install claude` | `claude` | 2.1.293 |
-| <a id="afu-codex"></a>Codex CLI | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install codex` | `codex` | 0.153.4 |
-| <a id="afu-pi"></a>Pi | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install pi` | `pi` | 0.84.4, 1.5.0 |
-| <a id="afu-dsh"></a>DSH | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | 0.2.2-rc.1 |
-| Codex CLI | Windows 10/11¹ | `npx.cmd --yes --registry=https://registry.npmjs.org "afucontext@0.1.19" install codex` | `codex` | preview, not yet tested; official in the next release |
-| Pi | Windows 10/11¹ | `npx.cmd --yes --registry=https://registry.npmjs.org "afucontext@0.1.19" install pi` | `pi` | preview, not yet tested; official in the next release |
-| DSH | Windows 10/11¹ | `npx.cmd --yes --registry=https://registry.npmjs.org "afucontext@0.1.19" install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | preview, not yet tested; official in the next release |
+| <a id="afu-claude"></a>Claude Code | macOS / Linux | `npx afucontext@latest install claude` | `claude` | 2.1.293 |
+| <a id="afu-codex"></a>Codex CLI | macOS / Linux | `npx afucontext@latest install codex` | `codex` | 0.153.4 |
+| <a id="afu-pi"></a>Pi | macOS / Linux | `npx afucontext@latest install pi` | `pi` | 0.84.4, 1.5.0 |
+| <a id="afu-dsh"></a>DSH | macOS / Linux | `npx afucontext@latest install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | 0.2.2-rc.1 |
+| Codex CLI | Windows 10/11¹ | `npx.cmd "afucontext@latest" install codex` | `codex` | preview, not yet tested; official in the next release |
+| Pi | Windows 10/11¹ | `npx.cmd "afucontext@latest" install pi` | `pi` | preview, not yet tested; official in the next release |
+| DSH | Windows 10/11¹ | `npx.cmd "afucontext@latest" install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | preview, not yet tested; official in the next release |
 
 Supported on macOS (Apple Silicon) and Linux x64. Start a new session after installing.
 
@@ -36,22 +36,34 @@ Supported on macOS (Apple Silicon) and Linux x64. Start a new session after inst
 
 <a id="results"></a>
 
+<a id="commands"></a>
+
 ## Commands
 
-The terminal commands (`afuctx …`) are placed in `~/.local/bin` by the first install of any host (the folder is created when missing). If that folder is not on `PATH`, the installer says so: add `export PATH="$HOME/.local/bin:$PATH"` to `~/.bashrc` or `~/.zshrc`, or use `npx --yes --registry=https://registry.npmjs.org afucontext@latest` in place of `afuctx`. Install, upgrade and remove replace the runtime itself, so they always run through npx.
+After installing, use `afuctx` in a terminal. The first install of any host places it in `~/.local/bin` (creating the folder when missing). Shell startup files are never edited (when the folder is not on `PATH` the installer prints the line to add, `export PATH="$HOME/.local/bin:$PATH"`, for `~/.bashrc` or `~/.zshrc`), an existing command of the same name is kept, and it is removed with the last host. Without `afuctx` (on Windows, or with `~/.local/bin` not on `PATH`), use `npx afucontext@latest` in its place; in Windows PowerShell use `npx.cmd "afucontext@latest"`.
+
+HOST below is `claude`, `codex`, `pi` or `dsh`; for DSH always add `--profile NAME`.
+
+### Install, upgrade and remove
 
 | Command | What it does |
 | --- | --- |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest install claude\|codex\|pi\|dsh` | Install for a host; for DSH add `--profile NAME` |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest install dsh --runtime-only` | Prepare only the runtime, for use with `dsh plugin --profile NAME add afucontext-dsh-plugin` |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest update` | Upgrade every host installed on this machine to this version |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest remove HOST` | Remove; host settings return to their state before installation. For DSH, `--profile NAME` removes one profile |
-| `afuctx status` | Whether each host is connected, how far the context is from the trigger, compactions applied; `--json` for the full record |
+| `npx afucontext@latest install HOST` | First install |
+| `afuctx install HOST` | Add another host |
+| `afuctx install dsh --runtime-only` | Prepare only the runtime, for use with `dsh plugin --profile NAME add afucontext-dsh-plugin` |
+| `afuctx update` | Upgrade every installed host to the latest release, one by one with the settings it was installed with, printing each version change |
+| `afuctx upgrade HOST` | Upgrade one host |
+| `afuctx remove HOST` | Remove; the host's settings return to how they were before install. For DSH, `--profile` removes one profile, without it all of them |
+
+`afuctx install`, `update`, `upgrade` and `remove` fetch the latest release from npm and run it. After upgrading Claude Code or Codex, start a new session to use the new version; after removing, restart the host.
+
+### Status and dashboard
+
+| Command | What it does |
+| --- | --- |
+| `afuctx` | Short status of recent sessions |
+| `afuctx status [HOST]` | Whether AFU is connected, the current context against the trigger, compactions so far; `--brief` for a summary (with each host's installed version), `--json` for everything |
 | `afuctx dashboard` | Open the local dashboard (same as `afuctx-admin`); `--prices FILE` estimates costs with your prices |
-| `afuctx doctor` | Checks host → AFU → model end to end, fixes what AFU can and gives exact steps for the rest; add a host name to check one |
-| `afuctx off` / `afuctx on` | Pause / resume: while paused the hosts talk to their models directly; the installation, logs and summaries stay. Add a host name for one host |
-| `afuctx repair codex --network` | Find and verify the proxy route to the model again (`repair claude` for Claude Code) |
-| `afuctx gc --dry-run` | List old runtimes and logs that can be removed; without `--dry-run` it removes them |
 | `afuctx --version` / `afuctx --help` | Version / help |
 
 Inside a host session:
@@ -62,6 +74,26 @@ Inside a host session:
 | Codex | `$afuctx-status` | `$afuctx-dashboard` |
 | Pi / DSH | `/afuctx-status` | `/afuctx-dashboard` |
 
+### When to compact
+
+| Command | What it does |
+| --- | --- |
+| `afuctx install HOST --ratio 0.3` | Compact earlier or later (between 0 and 1) |
+| `afuctx install HOST --context-window 200000` | Set the model window |
+| `afuctx install HOST --context-window auto --ratio auto` | Back to automatic |
+
+The two options combine: `--context-window 200000 --ratio 0.3` triggers at 60,000 tokens. Start a new session for the change to apply.
+
+### Troubleshooting and maintenance
+
+| Command | What it does |
+| --- | --- |
+| `afuctx doctor [HOST]` | Check host → AFU → model end to end; fixes what AFU can and gives concrete steps for the rest |
+| `afuctx off [HOST]` | Pause: the host talks to its model directly; AFU's installation, logs and summaries are kept |
+| `afuctx on [HOST]` | Resume |
+| `afuctx repair codex --network` | Find and verify the proxy route to the model service again (`repair claude` for Claude Code) |
+| `afuctx gc --dry-run` | List old runtimes and logs that can be cleaned; without `--dry-run` it cleans them |
+
 ## When something goes wrong
 
 | What you see | Do first |
@@ -69,6 +101,9 @@ Inside a host session:
 | After installing, the host cannot connect or keeps reconnecting | `afuctx off`: the host talks to its model directly right away. Then `afuctx doctor` to find the cause, and `afuctx on` once fixed |
 | Status says the model service is unreachable | `afuctx doctor` (or, for the network only, `afuctx repair codex --network`) |
 | A proxy app keeps the host from reaching AFU on this machine | Add `127.0.0.1` and `localhost` to the proxy app's bypass/exception list (for example AntFamily); `afuctx doctor` checks this |
+| Install reports `UPSTREAM_UNREACHABLE` | AFU could not reach the model service and changed nothing; install again from a terminal with your proxy set (`HTTPS_PROXY`) |
+| `HOST_CONFIG_INVALID` | Codex itself cannot read `~/.codex/config.toml` (for example a duplicate key) and AFU left it unchanged; fix it in an editor and retry |
+| `CONFIGURATION_CONFLICT` | Codex or you were changing the settings at the same time and AFU did not overwrite them; retry shortly |
 | Settings or hooks were damaged | Run the install command again |
 | No compaction after a reboot | Open a host session once (its hook starts AFU) |
 | You no longer want AFU | `remove`: the host's settings return to how they were before install |
@@ -95,27 +130,14 @@ In a LongBench V2 replay of 39 history questions (20 agent histories and 19 dial
 
 ### Open the dashboard
 
-| Where | Type |
-| --- | --- |
-| In a Claude Code session | `/afuctx:dashboard` |
-| In a Codex session | `$afuctx-dashboard` |
-| In a Pi or DSH session | `/afuctx-dashboard` |
-| In a terminal | `afuctx dashboard` |
+Open it from a host session or a terminal; see [Commands · Status and dashboard](#commands).
 
 - The dashboard runs in the background and does not occupy a terminal; opening it again reuses the same one, and it exits after 30 minutes without an open page.
 - It opens in the dark theme; switch to light, follow-system or English/Chinese in the top-right corner.
-- The terminal commands are placed in `~/.local/bin` by the installer for every host, creating the folder when needed. Shell startup files are never edited (the installer prints the line to add when the folder is not on `PATH`) and an existing command of the same name is kept (the installer says so). They are removed with the last integration, whichever host that is.
 
 ### Check the current session
 
-Type `/afuctx:status` in Claude Code, `$afuctx-status` in Codex, `/afuctx-status` in Pi or DSH, or run `afuctx status` in a terminal. It shows whether AFU is connected, the current context against the compaction threshold, and how many compactions have been applied.
-
-Without the terminal commands (for example when `~/.local/bin` is not on `PATH`), use the full npx commands. For Codex; for another host replace `codex` with `claude`, `pi` or `dsh`:
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 status codex --brief
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 ui
-```
+Run `afuctx status`, or the status command inside a host session (see [Commands](#commands)). It shows whether AFU is connected, the current context against the compaction threshold, and how many compactions have been applied.
 
 ### What the dashboard shows
 
@@ -150,49 +172,4 @@ If a window is still unknown, chat continues and `/afuctx:status` or `$afuctx-st
 
 ### Set the window or ratio manually
 
-Run the same install command with options, then start a new session. For Codex; for another host replace `codex` with `claude`, `pi` or `dsh`.
-
-| To | Option |
-| --- | --- |
-| Compact earlier or later | `--ratio 0.3` (between 0 and 1) |
-| Set the model window | `--context-window 200000` |
-| Restore automatic settings | `--context-window auto --ratio auto` |
-
-```sh
-# Trigger at 30% of a manually set 200,000-token window (60,000 tokens)
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install codex --context-window 200000 --ratio 0.3
-# Restore automatic settings
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install codex --context-window auto --ratio auto
-```
-
-For frequent use, run `npm install -g --registry=https://registry.npmjs.org afucontext@0.1.19` and use `afuctx` in place of the full `npx` invocation. For example, `afuctx dashboard --prices ./afu-prices.json` opens the dashboard with your price file to estimate costs.
-
-## Upgrade and remove
-
-After upgrading a Claude Code or Codex integration, start a new session to use the new gateway. To uninstall, remove the host integration first, then restart the host. Use the appropriate command below.
-
-To move every installed integration (Claude Code, Codex, Pi and each DSH profile) to the latest release in one step, run `update` with `@latest`. It upgrades them one by one with the settings they were installed with and prints the version change for each:
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@latest update
-```
-
-To check which version you have, run `--version` (the launcher), or `status --brief`, which shows the installed version of each host:
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@latest --version
-npx --yes --registry=https://registry.npmjs.org afucontext@latest status --brief
-```
-
-To upgrade or remove one host:
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 upgrade codex
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 remove codex
-```
-
-Use `remove pi` or `remove dsh` for those integrations. In Windows PowerShell, use `npx.cmd` and double-quote the package name.
-
-The dashboard listens on loopback. Logs record usage and receipts, and Pi/DSH also persist summaries in local session state. Generating summaries uses model tokens. Savings depend on subsequent reuse and actual cache hits.
-
-[Apache-2.0](LICENSE)
+To compact earlier or later, or to set the model window, run `afuctx install` with options; see [Commands · When to compact](#commands).

package/README.zh-CN.md

@@ -16,17 +16,17 @@
 
 ## 快速开始
 
-先安装并登录要使用的宿主，准备 npm、Node.js **22.19+（22.x）或 24+** 和 Python **3.11+**（需在 `PATH` 中）。选一行，在终端执行安装命令，然后用最后一列的命令启动。
+先安装并登录要使用的宿主，准备 npm、Node.js **22.19+（22.x）或 24+** 和 Python **3.11+**（需在 `PATH` 中）。选一行，在终端执行安装命令（第一次 npx 会问一次是否安装，回车确认即可），然后用最后一列的命令启动。装好后，再加别的宿主、升级、卸载都用 `afuctx`，见[命令](#commands)。
 
 | 宿主 | 系统 | 一键安装 | 安装后启动 | 实测版本 |
 | --- | --- | --- | --- | --- |
-| <a id="afu-claude"></a>Claude Code | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install claude` | `claude` | 2.1.293 |
-| <a id="afu-codex"></a>Codex CLI | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install codex` | `codex` | 0.153.4 |
-| <a id="afu-pi"></a>Pi | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install pi` | `pi` | 0.84.4、1.5.0 |
-| <a id="afu-dsh"></a>DSH | macOS / Linux | `npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | 0.2.2-rc.1 |
-| Codex CLI | Windows 10/11¹ | `npx.cmd --yes --registry=https://registry.npmjs.org "afucontext@0.1.19" install codex` | `codex` | 预览，未实测，下一版本正式提供 |
-| Pi | Windows 10/11¹ | `npx.cmd --yes --registry=https://registry.npmjs.org "afucontext@0.1.19" install pi` | `pi` | 预览，未实测，下一版本正式提供 |
-| DSH | Windows 10/11¹ | `npx.cmd --yes --registry=https://registry.npmjs.org "afucontext@0.1.19" install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | 预览，未实测，下一版本正式提供 |
+| <a id="afu-claude"></a>Claude Code | macOS / Linux | `npx afucontext@latest install claude` | `claude` | 2.1.293 |
+| <a id="afu-codex"></a>Codex CLI | macOS / Linux | `npx afucontext@latest install codex` | `codex` | 0.153.4 |
+| <a id="afu-pi"></a>Pi | macOS / Linux | `npx afucontext@latest install pi` | `pi` | 0.84.4、1.5.0 |
+| <a id="afu-dsh"></a>DSH | macOS / Linux | `npx afucontext@latest install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | 0.2.2-rc.1 |
+| Codex CLI | Windows 10/11¹ | `npx.cmd "afucontext@latest" install codex` | `codex` | 预览，未实测，下一版本正式提供 |
+| Pi | Windows 10/11¹ | `npx.cmd "afucontext@latest" install pi` | `pi` | 预览，未实测，下一版本正式提供 |
+| DSH | Windows 10/11¹ | `npx.cmd "afucontext@latest" install dsh --profile YOUR_PROFILE` | `dsh --profile YOUR_PROFILE` | 预览，未实测，下一版本正式提供 |
 
 支持 macOS（Apple Silicon）和 x64 Linux；安装后新开会话即可。
 
@@ -36,25 +36,37 @@
 
 <a id="results"></a>
 
-## 命令一览
+<a id="commands"></a>
 
-终端命令（`afuctx …`）在首次安装任一宿主后放到 `~/.local/bin`，目录不存在时会自动创建。该目录不在 `PATH` 时，安装程序会提示：把 `export PATH="$HOME/.local/bin:$PATH"` 加到 `~/.bashrc` 或 `~/.zshrc`，或者把 `afuctx` 换成 `npx --yes --registry=https://registry.npmjs.org afucontext@latest`。安装、升级、移除这类会替换运行时本身的命令，始终用 npx 执行。
+## 命令
+
+装好后在终端用 `afuctx`。它在首次安装任一宿主后放到 `~/.local/bin`，目录不存在时自动创建；不改 shell 配置（目录不在 `PATH` 时，安装程序会提示把 `export PATH="$HOME/.local/bin:$PATH"` 加到 `~/.bashrc` 或 `~/.zshrc`），不覆盖你已有的同名命令，移除最后一个宿主时一并删除。没有 `afuctx` 时（Windows，或 `~/.local/bin` 不在 `PATH` 中），把 `afuctx` 换成 `npx afucontext@latest`；Windows PowerShell 用 `npx.cmd "afucontext@latest"`。
+
+下面的"宿主"是 `claude`、`codex`、`pi` 或 `dsh`；DSH 都要加 `--profile 名称`。
+
+### 安装、升级、卸载
+
+| 命令 | 作用 |
+| --- | --- |
+| `npx afucontext@latest install 宿主` | 第一次安装 |
+| `afuctx install 宿主` | 再加一个宿主 |
+| `afuctx install dsh --runtime-only` | 只准备运行时，配合 `dsh plugin --profile 名称 add afucontext-dsh-plugin` 使用 |
+| `afuctx update` | 把已装的所有宿主一次升级到最新版，按安装时的设置逐个升级，并打印每个的版本变化 |
+| `afuctx upgrade 宿主` | 只升级一个宿主 |
+| `afuctx remove 宿主` | 卸载，宿主配置恢复成安装前的样子；DSH 加 `--profile` 只移除一个 profile，省略则移除全部 |
+
+`afuctx install`、`update`、`upgrade`、`remove` 会自动从 npm 取最新版执行。升级 Claude Code 或 Codex 后新开会话即用上新版；卸载后重启宿主。
+
+### 查看状态和面板
 
 | 命令 | 作用 |
 | --- | --- |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest install claude\|codex\|pi\|dsh` | 安装到指定宿主；DSH 加 `--profile 名称` |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest install dsh --runtime-only` | 只准备运行时，配合 `dsh plugin --profile 名称 add afucontext-dsh-plugin` 使用 |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest update` | 把本机已装的所有宿主一次升级到这个版本 |
-| `npx --yes --registry=https://registry.npmjs.org afucontext@latest remove 宿主` | 移除，宿主配置恢复成安装前的样子；DSH 可加 `--profile 名称` 只移除一个 profile |
-| `afuctx status` | 各宿主是否接入、当前上下文离触发线多远、已压缩几次；加 `--json` 输出完整信息 |
+| `afuctx` | 最近几个会话的简要状态 |
+| `afuctx status [宿主]` | 是否接入、当前上下文离触发线多远、已压缩几次；`--brief` 简要（含各宿主装的版本），`--json` 完整信息 |
 | `afuctx dashboard` | 打开本地面板（同 `afuctx-admin`）；`--prices 文件` 用自己的单价估算费用 |
-| `afuctx doctor` | 检查"宿主 → AFU → 模型"整条链路，能修的直接修，修不了的给出具体步骤；加宿主名只查一个 |
-| `afuctx off` / `afuctx on` | 暂停 / 恢复：暂停时宿主直连模型，AFU 的安装、日志、摘要都保留；加宿主名只作用于一个 |
-| `afuctx repair codex --network` | 重新查找并验证连到模型服务的代理（Claude Code 用 `repair claude`） |
-| `afuctx gc --dry-run` | 查看可清理的旧版本运行时和日志；去掉 `--dry-run` 才会真正清理 |
 | `afuctx --version` / `afuctx --help` | 版本号 / 帮助 |
 
-宿主会话里也可以直接用：
+宿主会话里：
 
 | 宿主 | 查看状态 | 打开面板 |
 | --- | --- | --- |
@@ -62,6 +74,26 @@
 | Codex | `$afuctx-status` | `$afuctx-dashboard` |
 | Pi / DSH | `/afuctx-status` | `/afuctx-dashboard` |
 
+### 调整压缩时机
+
+| 命令 | 作用 |
+| --- | --- |
+| `afuctx install 宿主 --ratio 0.3` | 提前或推迟压缩，取值 0 到 1 之间 |
+| `afuctx install 宿主 --context-window 200000` | 手动指定模型窗口 |
+| `afuctx install 宿主 --context-window auto --ratio auto` | 恢复自动 |
+
+两个参数可以一起用，例如 `--context-window 200000 --ratio 0.3` 即在 60,000 tokens 触发。改完后新开会话生效。
+
+### 排查和维护
+
+| 命令 | 作用 |
+| --- | --- |
+| `afuctx doctor [宿主]` | 检查"宿主 → AFU → 模型"整条链路，能修的直接修，修不了的给出具体步骤 |
+| `afuctx off [宿主]` | 暂停：宿主直连模型，AFU 的安装、日志、摘要都保留 |
+| `afuctx on [宿主]` | 恢复 |
+| `afuctx repair codex --network` | 重新查找并验证连到模型服务的代理（Claude Code 用 `repair claude`） |
+| `afuctx gc --dry-run` | 查看可清理的旧版本运行时和日志；去掉 `--dry-run` 才会真正清理 |
+
 ## 出问题时怎么办
 
 | 现象 | 先做 |
@@ -69,6 +101,9 @@
 | 装了以后宿主连不上、一直重连 | `afuctx off`，宿主立即恢复直连模型；之后运行 `afuctx doctor` 查原因，修好后 `afuctx on` |
 | 状态提示连不上模型服务 | `afuctx doctor`（只查网络也可以 `afuctx repair codex --network`） |
 | 代理软件导致连不上本机 AFU | 在代理软件（如 AntFamily）的例外 / 绕过列表里加入 `127.0.0.1` 和 `localhost`；`afuctx doctor` 会检查 |
+| 安装报 `UPSTREAM_UNREACHABLE` | AFU 连不上模型服务，什么都没改；在设置了代理（`HTTPS_PROXY`）的终端里重新安装 |
+| 报 `HOST_CONFIG_INVALID` | Codex 自己读不了 `~/.codex/config.toml`（比如有重复的键），AFU 没有改动它；用编辑器修好后重试 |
+| 报 `CONFIGURATION_CONFLICT` | 执行期间 Codex 或你正在改配置，AFU 没有覆盖；稍后重试 |
 | 配置或 hook 被改坏 | 重新执行安装命令 |
 | 重启后不压缩 | 开一次宿主会话（hook 会拉起 AFU） |
 | 彻底不用 | `remove`，宿主配置恢复成安装前的样子 |
@@ -95,27 +130,14 @@ AFU 连续几次连不上模型服务时，会自动重新查找并验证一条
 
 ### 打开面板
 
-| 在哪里 | 输入 |
-| --- | --- |
-| Claude Code 会话里 | `/afuctx:dashboard` |
-| Codex 会话里 | `$afuctx-dashboard` |
-| Pi / DSH 会话里 | `/afuctx-dashboard` |
-| 终端里 | `afuctx dashboard` |
+在宿主会话里或终端里打开，命令见[命令 · 查看状态和面板](#commands)。
 
 - 面板在后台运行，不占用终端；再次打开会复用同一个面板，30 分钟没有页面打开时自动退出。
 - 默认暗色主题，右上角可切换亮色、跟随系统和中英文。
-- 终端命令由安装程序放在 `~/.local/bin`，四个宿主都会放，目录不存在时自动创建。不改 shell 配置（目录不在 `PATH` 时会提示要加的那一行），不覆盖你已有的同名命令（会提示未覆盖）。移除最后一个接入时一并删除，不论是哪个宿主。
 
 ### 查看当前会话
 
-Claude Code 输入 `/afuctx:status`，Codex 输入 `$afuctx-status`，Pi 和 DSH 输入 `/afuctx-status`，终端里运行 `afuctx status`。会显示 AFU 是否已接入、当前上下文距离压缩触发线还有多少，以及已经生效的压缩次数。
-
-没有上面的终端命令时（例如 `~/.local/bin` 不在 `PATH` 中），可以用完整的 npx 命令。以 Codex 为例，其它宿主将 `codex` 换成 `claude`、`pi` 或 `dsh`：
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 status codex --brief
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 ui
-```
+用 `afuctx status` 或宿主会话里的状态命令（见[命令](#commands)）。会显示 AFU 是否已接入、当前上下文距离压缩触发线还有多少，以及已经生效的压缩次数。
 
 ### 面板内容
 
@@ -150,49 +172,4 @@ npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 ui
 
 ### 手动指定窗口和调整比例
 
-用同一条安装命令加参数即可，改完后新开会话生效。下面以 Codex 为例，其它宿主将 `codex` 换成 `claude`、`pi` 或 `dsh`。
-
-| 想做的事 | 参数 |
-| --- | --- |
-| 提前或推迟压缩 | `--ratio 0.3`（取值 0 到 1 之间） |
-| 手动指定模型窗口 | `--context-window 200000` |
-| 恢复自动 | `--context-window auto --ratio auto` |
-
-```sh
-# 在 30% 触发，并手动指定 200,000 的窗口（即 60,000 触发）
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install codex --context-window 200000 --ratio 0.3
-# 恢复自动设置
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 install codex --context-window auto --ratio auto
-```
-
-如果经常使用 AFU，可运行 `npm install -g --registry=https://registry.npmjs.org afucontext@0.1.19`，以后用 `afuctx` 代替完整的 `npx` 命令。例如，`afuctx dashboard --prices ./afu-prices.json` 用自己的单价文件打开面板估算费用。
-
-## 升级与移除
-
-升级 Claude Code 或 Codex 接入后，新开会话即可使用新版网关。需要移除时，先撤销对应宿主的接入，再重启宿主。以下两条命令分别用于升级和移除。
-
-想把已装的所有接入（Claude Code、Codex、Pi 和每个 DSH profile）一次升级到最新版，用 `@latest` 执行 `update`。它会按安装时的设置逐个升级，并打印每个接入从哪个版本升到哪个版本：
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@latest update
-```
-
-查看版本：`--version` 显示启动器版本，`status --brief` 显示每个宿主当前装的版本：
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@latest --version
-npx --yes --registry=https://registry.npmjs.org afucontext@latest status --brief
-```
-
-只升级或移除某一个宿主：
-
-```sh
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 upgrade codex
-npx --yes --registry=https://registry.npmjs.org afucontext@0.1.19 remove codex
-```
-
-Pi 和 DSH 可分别用 `remove pi` 或 `remove dsh` 撤销。Windows PowerShell 请使用 `npx.cmd` 并将包名放在双引号中。
-
-本地面板只监听回环地址。日志记录用量和回执，Pi/DSH 的本地会话状态还会保存摘要。生成摘要本身会调用模型，节省多少取决于后续复用和实际缓存命中。
-
-[Apache-2.0](LICENSE)
+提前或推迟压缩、手动指定模型窗口，用 `afuctx install` 加参数，见[命令 · 调整压缩时机](#commands)。

package/bin/afu.mjs

@@ -13,6 +13,12 @@ const root=resolve(dirname(fileURLToPath(import.meta.url)),'..');
 const manifest=JSON.parse(readFileSync(join(root,'release.json'),'utf8'));
 const env={...process.env,AFU_INSTALL_ROOT:root};
 let args=process.argv.slice(2);
+// State lives in the user's home directory; files written as root through
+// sudo become unreadable for that user. Root's own login is fine.
+if(process.platform!=='win32'&&process.getuid?.()===0&&process.env.SUDO_USER&&!['--version','-v','version','--help','-h','help'].includes(args[0]??'--help')){
+  console.error('afucontext: do not run AFU under sudo. AFU keeps its state in your home directory, and files written as root become unreadable for you. Run the same command again without sudo.');
+  process.exit(2);
+}
 if(['install','upgrade','status','remove','gc','native','repair','off','on','doctor'].includes(args[0])){
  const at=args.indexOf('--state');if(at>=0&&args[at+1])env.AFU_STATE_DIR=resolve(args[at+1]);
  const inline=args.find(a=>a.startsWith('--state='));if(inline&&inline.length>8)env.AFU_STATE_DIR=resolve(inline.slice(8));
@@ -77,8 +83,8 @@ try{
   // Only the bare launcher prints its own banner; "afu ui --help" and
   // "afu claude --help" belong to the subcommand or the host.
   if(!args.length || (['--help','-h'].includes(args[0]))){
-    const pkg=manifest.name||'afucontext',npx=`npx --yes --registry=https://registry.npmjs.org ${pkg}@latest`;
-    console.log(`afuctx ${manifest.version}: AFU Context, local context compression for coding agents\n\n  ${npx} install [claude|codex|pi|dsh]\n  ${npx} update            upgrade every installed host\n  ${npx} remove HOST\n  ${npx} status [HOST]\n  ${npx} dashboard         open the local dashboard\n  ${npx} gc --dry-run\n  ${npx} --version\n\nAfter installing, the same commands are on PATH as afuctx (status, dashboard, --help, --version) and afuctx-admin (dashboard). Host login remains managed by the host.`);
+    const pkg=manifest.name||'afucontext',npx=`npx ${pkg}@latest`;
+    console.log(`afuctx ${manifest.version}: AFU Context, local context compression for coding agents\n\n  ${npx} install [claude|codex|pi|dsh]\n  ${npx} update            upgrade every installed host\n  ${npx} remove HOST\n  ${npx} status [HOST]\n  ${npx} dashboard         open the local dashboard\n  ${npx} gc --dry-run\n  ${npx} --version\n\nAfter installing, the same commands are on PATH as afuctx (status, dashboard, --help, --version) and afuctx-admin (dashboard); afuctx install, update and remove run this package from npm. Host login remains managed by the host.`);
     process.exit(0);
   }
   if(['--version','-v','version'].includes(args[0])){console.log(manifest.version);process.exit(0);}

package/bin/host-autoload.py

@@ -401,6 +401,10 @@ def remove_record(host, record):
 
 
 def main():
+    from afu_context.local_cli import SUDO_REFUSAL, under_sudo
+    if under_sudo():
+        print(SUDO_REFUSAL, file=sys.stderr)
+        raise SystemExit(2)
     p = argparse.ArgumentParser()
     p.add_argument("action", choices=["install", "upgrade", "remove", "status"])
     p.add_argument("host", choices=["pi", "dsh"], nargs="?")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afucontext",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Local asynchronous context compression and diagnostics",

package/release.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.1.19",
+  "version": "0.1.21",
   "name": "afucontext",
-  "build": "62194a699342a041d610236ff46479044e6b87083142681a5c44094355291435",
-  "wheel": "afu_context_local-0.1.19-py3-none-any.whl",
+  "build": "ac2723431caf1b88720c948ddd41fd3cf9e4f5079e6c4bb5af426bc52693d59c",
+  "wheel": "afu_context_local-0.1.21-py3-none-any.whl",
   "prebuilt": false
 }

package/scripts/dsh-overlay.mjs

@@ -1,5 +1,5 @@
 /** Compose a disposable overlay using DSH's own YAML and patch semantics. */
-import {readFileSync, writeFileSync, realpathSync} from 'node:fs';
+import {readFileSync, writeFileSync, realpathSync, existsSync} from 'node:fs';
 import {createRequire} from 'node:module';
 import {join,isAbsolute,dirname} from 'node:path';
 import {pathToFileURL} from 'node:url';
@@ -86,8 +86,9 @@ if(process.argv[1] && import.meta.url===pathToFileURL(process.argv[1]).href) {
         writeFileSync(presetModule, `import Native from ${JSON.stringify(pathToFileURL(native).href)};\nimport {presetAdapter} from ${JSON.stringify(new URL('./dsh-presets.mjs',import.meta.url).href)};\nexport default presetAdapter(Native, ${JSON.stringify(moduleReference(process.argv[2]))}, ${JSON.stringify(process.argv[3])});\n`, {mode:0o600});
       } catch (error) { if(error.code!=='MODULE_NOT_FOUND') throw error; }
     }
-    // The commands module sits beside the provider module (commands.mjs).
-    const commands=process.argv[2] ? moduleReference(join(dirname(process.argv[2]),'commands.mjs')) : undefined;
+    // The commands module sits beside the provider module: commands.mjs in an
+    // installed bundle (host-autoload), commands.js in a source checkout.
+    const commands=process.argv[2] ? moduleReference(['commands.mjs','commands.js'].map(n=>join(dirname(process.argv[2]),n)).find(p=>existsSync(p)) ?? join(dirname(process.argv[2]),'commands.mjs')) : undefined;
     const patches=overlay(tree,moduleReference(process.argv[2]),presetModule && moduleReference(presetModule),commands);
     if (process.argv[5]==='web-compat') {
       const picker=tree.find(row=>!row.disabled && row.name==='@deepseek-ai/dsh-host-directory-picker-auto');

package/src/afu_host_integrations/dsh/dist/index.js

@@ -135,10 +135,23 @@ export class CompactDshEngine extends BasicCompactionEngine {
         if (!this.bindings.has(binding.key) && this.bindings.size >= 16)
             throw new Error("DSH binding limit reached");
         this.bindings.set(binding.key, binding);
-        const request = dshMessagesToRequest(messages, binding.key, mode);
+        const request = dshMessagesToRequest(messages, binding.key, mode, binding.contextWindow);
         const tokens = dshContextTokens(this.ctx, agent);
+        if (tokens === undefined && !dshHasMeter(this.ctx))
+            this.noteUnmeasured(agent);
         return tokens === undefined ? request : { ...request, metadata: { ...request.metadata, host_context_tokens: tokens } };
     }
+    /** Sessions already reported as running without DSH's token meter. */
+    unmeasured = new Set();
+    noteUnmeasured(agent) {
+        if (this.unmeasured.has(agent.session.id))
+            return;
+        this.unmeasured.add(agent.session.id);
+        if (this.unmeasured.size > 256)
+            this.unmeasured.delete(this.unmeasured.values().next().value);
+        // The trigger then follows AFU's own count of the text (see compression.py).
+        this.log("host_measure_unavailable", { session: sessionHash(agent.session.id) });
+    }
     async compactIfNeeded(agent, trigger, signal) {
         // afuctx off: DSH's own compaction, unchanged.
         if (afuPaused("dsh"))
@@ -354,6 +367,15 @@ function dshRemovedTokens(result) {
     const text = result.summary.map(b => b.type === "text" ? b.text : "").join("");
     return Math.max(0, shadowed - Math.ceil(text.length / 4));
 }
+/** Whether this DSH mounts a token meter at all (it reads 0 before a session's first request). */
+function dshHasMeter(ctx) {
+    try {
+        return typeof ctx.tokenMeter?.measure === "function";
+    }
+    catch {
+        return false;
+    }
+}
 /** DSH's own token meter (the measure its native compaction uses), if available. */
 function dshContextTokens(ctx, agent) {
     try {
@@ -365,7 +387,7 @@ function dshContextTokens(ctx, agent) {
         return undefined;
     }
 }
-export function dshMessagesToRequest(messages, sessionId, mode = "active") {
+export function dshMessagesToRequest(messages, sessionId, mode = "active", contextWindow) {
     const groups = toolCallGroups(messages);
     const items = messages.map((message) => {
         const content = normalizeContent(message.content);
@@ -391,7 +413,9 @@ export function dshMessagesToRequest(messages, sessionId, mode = "active") {
     return {
         schema_version: "1",
         session_id: sessionId,
-        token_budget: Math.max(20_000, estimatedTokens),
+        // The model's window when known: the trigger is min(budget, window *
+        // ratio), so a budget equal to the estimate would make it the trigger.
+        token_budget: Number.isSafeInteger(contextWindow) && contextWindow > 0 ? contextWindow : Math.max(20_000, estimatedTokens),
         items,
         query: "",
         mode,