agy-delegate-rs 0.1.5 → 0.1.6

package/INSTALL.en.md

@@ -0,0 +1,212 @@
+# Installation and configuration
+
+[简体中文](INSTALL.md) | English
+
+## Prerequisites
+
+- Source installation requires Rust 1.88+ and a C toolchain for your platform: typically GCC/Clang on Linux, Xcode Command Line Tools on macOS, or build tools matching your Rust toolchain on Windows. The project compiles SQLite. npm and GitHub Release binaries do not require these build tools.
+- Antigravity CLI must provide `agy`, stream-json, and `--gemini_dir`. Your existing login or API configuration must already have working model access. This project does not install or manage agy.
+- Codex CLI must support named permission profiles and have a working sandbox. The locally verified version is `0.160.0`. The tool calls `codex sandbox`; it does not separately invoke or check bubblewrap. `install` and `doctor` check actual read/write boundaries.
+
+Install Codex CLI with Node.js/npm:
+
+```sh
+npm install -g @openai/codex@0.160.0
+```
+
+Linux must satisfy the current Codex sandbox backend's requirements, including user namespace permissions where needed. Codex uses Seatbelt on macOS and its unelevated backend on Windows. Tests have passed in all six native CI environments across Linux, macOS, and Windows on x86_64 and ARM64, including project reads, rejected project writes, and writable temporary directories.
+
+Current model verification uses an existing API/protocol conversion service. Native OAuth login, system keychain access, and token refresh remain untested. All three operating systems require a local Codex CLI for sandbox execution.
+
+## Build and initialize
+
+Choose an installation method:
+
+- **GitHub Releases**: download the `.tar.gz` or `.zip` for your architecture, verify it against `SHA256SUMS`, extract it, and put the binary on PATH.
+- **npm**: run `npm install -g agy-delegate-rs`. Node.js 22.14+ is required; Rust is not. Optional dependencies select one native binary for your system and architecture, without installation scripts. Keep optional dependencies enabled. If the platform package is missing, reinstall with `npm install -g agy-delegate-rs --include=optional`.
+- **crates.io**: run `cargo install agy-delegate-rs --locked`, with the Rust and C toolchains described above.
+
+Prebuilt packages cover Linux x64/arm64 with static musl linking, macOS x64/arm64, and Windows x64/arm64. None of these methods installs agy or Codex CLI. Run `agy-delegate-rs install` for initial integration, then start a new Codex session. Verify model authentication with a real investigation.
+
+Upgrading from npm `0.1.3` or earlier changes the native executable path because newer versions use separate platform packages. **If you previously ran `install` or `register`, run `uninstall` with the old version before upgrading, then `install` with the new version.** Use the same configuration options as the original registration:
+
+```sh
+agy-delegate-rs uninstall
+npm install -g agy-delegate-rs@latest
+agy-delegate-rs install
+```
+
+If you have already upgraded and get an MCP ownership error, temporarily install `agy-delegate-rs@0.1.3` in the original npm prefix to restore its executable path, then follow the migration above. Configuration and history do not need to be deleted. `uninstall` first stops tasks in the selected state directory. Users without an MCP registration can install the new version directly; later platform package upgrades keep the same path.
+
+For installation from the repository:
+
+```sh
+cargo install --path . --locked
+agy-delegate-rs init
+agy-delegate-rs doctor
+```
+
+Ensure Cargo's bin directory is on PATH. `init` prints the configuration path, normally `agy-delegate-rs/config.toml` under your system's user configuration directory. On Linux this is usually `~/.config/agy-delegate-rs/config.toml`, subject to `XDG_CONFIG_HOME`.
+
+You can select a configuration file explicitly:
+
+```sh
+agy-delegate-rs init --config /absolute/path/config.toml
+agy-delegate-rs --config /absolute/path/config.toml doctor
+```
+
+`init` never overwrites an existing file or generates/copies credentials. Edit existing configuration directly. `doctor` returns JSON and exits unsuccessfully if a check fails. It checks configuration, environment files, program versions, public headless agy options, state storage, and sandbox boundaries. It does not call models or verify login, API connectivity, token refresh, or the actual data location used by `--gemini_dir`. Run a real investigation after initialization to verify your agy version and authentication.
+
+## Configuration
+
+Default template:
+
+```toml
+codex = "codex"
+agy = "agy"
+agy_args = []
+# Always passed explicitly; agy's interactive model selection does not affect tasks.
+model = "gemini-3.8-flash-high"
+log_bytes = 4000000
+profile_bytes = 128000000
+timeout = 600
+report_chars = 4000
+retention_days = 14
+max_history_jobs = 1000
+# agy_env_file = "/absolute/path/api.env"
+# effort = "high"
+# state_dir = "/absolute/path/state"
+```
+
+Explicit command-line options override file settings. Put configuration overrides before the subcommand, for example `agy-delegate-rs --model your-model --agy-env-file /absolute/path/api.env run --cwd /path/to/repo --task 'Trace entry points'`. `--config` and `--timeout` also work after the subcommand. File-relative paths resolve against the configuration directory. Plain `agy` and `codex` names are looked up on PATH; write relative executable paths as `./bin/agy`. Command-line paths resolve against the launch directory. `~` and environment variables in paths are not expanded; use full paths.
+
+`model` defaults to agy's built-in `gemini-3.8-flash-high`, meaning Gemini 3.8 Flash (High). Every new investigation and follow-up passes it explicitly, independently of the model selected in agy. The default also applies when there is no configuration file, `model` is omitted, or an old JSON snapshot contains `model: null`. An existing explicit model remains in effect. An unavailable model causes task failure; there is no automatic fallback.
+
+`effort` is optional and accepts `low`, `medium`, `high`, `xhigh`, or `max`; the installed agy and selected model determine which levels are supported. The default model ID already includes High, so no separate effort is needed. agy 1.3.2 also supports `model = "gemini-3.8-flash"` with `effort = "high"`, or command-line options `--model gemini-3.8-flash --effort high`. A separate effort must agree with any effort suffix in the model ID. For custom APIs or protocol converters, use the IDs accepted by `agy models` and your endpoint. This tool does not rewrite model names.
+
+Other settings:
+
+| Setting | Default | Purpose and range |
+| --- | --- | --- |
+| `timeout` | `600` | Task execution deadline, 1–7200 seconds |
+| `report_chars` | `4000` | Report length returned by task queries, 256–6000 characters |
+| `retention_days` | `14` | History retention, 1–365 days |
+| `max_history_jobs` | `1000` | History count limit, 10–10000 |
+| `log_bytes` | `4000000` | Limit for an individual agy log and retained stderr, 4096–32000000 bytes |
+| `profile_bytes` | `128000000` | Total file bytes in each managed conversation directory, 1000000–1000000000 |
+
+Retention settings apply to manual cleanup and automatic cleanup after workers save results. `agy_args` precede managed agy options: for example, `agy = "node"` with `agy_args = ["/absolute/path/agy.js"]`. You can also repeat `--agy-arg`. Keep credentials out of arguments. Protocol output has a separate 4 MB limit. `--profile-bytes` can override the conversation limit before the subcommand.
+
+The Rust version does not import the original Python project's `config.json` or task database automatically. Keep separate state directories when running both versions. Migrate executable paths, model IDs, and environment file paths manually; keep credentials out of TOML.
+
+Authentication environment variables are inherited; existing variables override `agy_env_file` values. Environment files reference your existing configuration, without adding credential fields to project configuration. Unknown configuration keys are rejected. Credential environment values and persistent task paths must be UTF-8. Run any protocol conversion service separately.
+
+New tasks use `state_dir/conversations/<root_id>` through `--gemini_dir`; follow-ups reuse it. On first use, only existing `settings.json` and `antigravity-oauth-token` files are copied from the default `~/.gemini/antigravity-cli`. Host conversations, plugins, and separate MCP configuration files are not copied. Existing private login files are preserved; refreshed credentials stay private and original files are not updated. Environment file credentials are passed through the environment; the host's `api.env` is not imported automatically. Keep private login data, model caches, and investigation history out of version control.
+
+## Register with Codex MCP
+
+After initialization:
+
+```sh
+agy-delegate-rs install
+# Register MCP without adding delegation rules:
+agy-delegate-rs register
+# Select a Codex configuration directory, also useful for isolated verification:
+agy-delegate-rs install --codex-home /absolute/path/codex-home
+```
+
+`install` first runs offline doctor checks, then registers MCP and adds managed AGENTS rules. It refuses to overwrite an existing Python registration or policy. After verifying the Rust version, remove the old integration manually. Existing external protocol conversion services can remain in use.
+
+Registration saves a snapshot of the effective configuration, including command-line overrides. Run `register` again after changes. The installer manages configuration and MCP integration; use npm, Cargo, or GitHub Releases to manage the executable itself.
+
+Ownership checks verify both the current executable path and the snapshot for the selected Codex directory. Upgrades retaining the same path can register again. Before moving the executable or changing installation channels, run `uninstall` from the original path. The tool does not take over registrations owned by another executable path.
+
+Install, register, and uninstall operations are mutually exclusive and recheck ownership after stopping tasks. Codex configuration writes have no shared lock or conditional update interface. Avoid simultaneous `codex mcp add/remove` calls or manual edits to the same file; external concurrent writes can still overwrite each other.
+
+Policy backup and restoration use file synchronization and atomic replacement. Unix also synchronizes the parent directory, persisting the backup, policy, and backup removal in order. Windows supports recovery after process interruption, but does not guarantee directory durability after power loss.
+
+For manual registration, add this to Codex's `config.toml`:
+
+```toml
+[mcp_servers.agy-delegate-rs]
+command = "/absolute/path/agy-delegate-rs"
+args = ["--config", "/absolute/path/config.toml", "mcp"]
+```
+
+TOML single-quoted strings are convenient for Windows paths. With default configuration, use `args = ["mcp"]`. Restart or reload Codex's MCP server to apply it.
+
+Available tools are `agy_submit`, `agy_status`, `agy_wait`, `agy_followup`, `agy_cancel`, and `agy_list`. Lists return brief status; use status/wait for details. Check task status and do not treat `incomplete` or failed tasks as completed. Uninstallation removes only matching registrations and verifies that managed rules have not been edited, preserving other settings and rules.
+
+## Run and clean up
+
+```sh
+agy-delegate-rs run --cwd /path/to/repo --task 'Trace entry points with file and line references'
+agy-delegate-rs submit --cwd /path/to/repo --task 'Trace entry points with file and line references'
+agy-delegate-rs wait JOB_ID --seconds 50
+agy-delegate-rs followup JOB_ID 'Continue checking the call chain'
+agy-delegate-rs submit --cwd /path/to/repo --task-file /path/to/task.txt
+agy-delegate-rs followup JOB_ID --task-file /path/to/followup.txt
+agy-delegate-rs report JOB_ID --output /path/to/new-report.txt
+agy-delegate-rs cleanup --dry-run
+agy-delegate-rs cleanup
+```
+
+Choose either `--task` or `--task-file`. `--task-file -` reads UTF-8 from stdin. Files are limited to 96000 bytes and tasks to 24000 characters. `report` returns the complete stored result regardless of query report limits; exports preserve existing files.
+
+Independent background workers continue after the MCP server closes. A wait timeout does not cancel work. State defaults to the system user data directory, configurable with `state_dir` or `--state-dir`.
+
+Cleanup selects finished tasks by last update time or by the retained history count. Preview `selected_ids` with `--dry-run`. Running tasks, orphaned tasks, and history belonging to conversations with active or unverified tasks are retained. Tasks with an ownership lock or a surviving sandbox process are also skipped.
+
+Cleanup removes task database records and log directories. Deleted job IDs cannot be queried or followed up. A conversation directory remains while other history references exist, allowing follow-ups through those records. Removing the last reference deletes the managed directory and returns its ID in `deleted_conversation_ids`. Shared `~/.gemini` data and original login files are preserved.
+
+Synchronous `run` also uses task records and workers, with the same cleanup rules. Ctrl-C requests cancellation. Cleanup runs in workers after saving results, without blocking submission. A synchronous result may show `cleanup_status: pending`; query `status JOB_ID` for the final outcome. Older unrecorded `run-*` directories are retained; remove them manually only after confirming no process uses them. Older shared-profile tasks continue using shared data, and cleanup removes only their records/logs. Managed directories without history proving ownership are also retained.
+
+Cleanup marks tasks `purging` before deleting logs and eligible conversation directories. Follow-ups in the same conversation are blocked during removal. Failed file deletion preserves records and returns failure details for retry. Partially deleted conversation directories remain `purging` to prevent resuming damaged conversations. Run `cleanup` again to recover after interruption. Retention limits count only history that is safe to remove; locked records and active conversations do not consume the retained count.
+
+Only one actual cleanup process may run per state directory. A second process returns `cleanup_active` and skips removal. The log directory's `.cleanup.lock` is retained for process locking; do not delete it while the tool is running. Replaced directories or unverifiable deletion boundaries cause records to be retained with a skip/error report.
+
+## Sandbox scope and uninstall
+
+New tasks can read project and ordinary host files, write managed conversation and task temporary directories, and access the network. Older shared-profile tasks can still write the host's `~/.gemini`. The sandbox protects project writes; it does not isolate accounts, credentials, or networks. Overlapping working/writable directories are rejected. Sandbox startup failure stops execution without an unsandboxed fallback.
+
+On Unix, cancellation fails and blocks follow-ups if the worker and sandbox group leader have exited but surviving child processes cannot be identified reliably. Manual process cleanup is required; there is currently no separate supervisor.
+
+First run `agy-delegate-rs uninstall` to stop and verify tasks in the selected state, remove matching MCP registration, and restore managed rules. Then remove the executable with `npm uninstall -g agy-delegate-rs`, `cargo uninstall agy-delegate-rs`, or by deleting your downloaded binary. If task termination cannot be verified or managed rules were edited, integration removal stops. Configuration, history, and agy settings are retained; data cleanup is a separate decision.
+
+Application log sizes are checked every 100 milliseconds. Exceeding the limit terminates the task; retained logs are truncated and redacted afterward. Managed conversation file sizes are checked before startup, roughly every 2 seconds during execution, and after termination. Exceeding `profile_bytes` terminates the entire sandbox process group. Scans do not follow symbolic links and fail tasks if a safe scan is impossible. Cancellation, timeout, and existing execution failures retain their original status/diagnostics, with final scan errors added separately.
+
+Monitoring is not a filesystem quota; limits can be exceeded between checks. `profile_bytes` covers managed conversation directories, not shared agy account directories or total disk usage across other tasks.
+
+If the operating system cannot confirm termination of the entire sandbox process group within the deadline, the task fails. A `tmp/UNVERIFIED_PROCESS` marker indicates that original logs remain in the private directory and must not be considered redacted. Stop and verify related processes before handling logs or cleanup. Uninstall rejects task directories it cannot verify.
+
+Uninstall cancels tasks in the selected `state_dir`, including CLI tasks, even if the current Codex directory has no Rust MCP registration. Codex directories sharing state also share the task pool and cleanup policy; use separate state directories for isolation. New submissions are blocked during shutdown checks. Retry uninstall later if a task is being submitted or started.
+
+## Maintainer releases
+
+`.github/workflows/release.yml` runs only on pushed `v*.*.*` tags, further restricted to stable `vMAJOR.MINOR.PATCH` versions. The tagged commit must be in the repository's default branch history, and tag, Cargo, and npm versions must match. Otherwise publication stops.
+
+One-time setup:
+
+1. Push the repository to `JIAFALSEDREAM/agy-delegate-rs`, set `main` as the default branch, and enable Actions.
+2. Add an Actions secret named `CARGO_REGISTRY_TOKEN` with permission to publish `agy-delegate-rs`. npm uses trusted publishing and does not need `NPM_TOKEN`.
+3. Your npm account must own the entry package and all six `agy-delegate-rs-{linux,darwin,win32}-{x64,arm64}` platform packages. Bootstrap missing packages by downloading `PACKAGE-VERSION.tgz` from GitHub Releases and running `npm publish ./PACKAGE-VERSION.tgz --access public` after npm login. Publish platform packages before the entry package. Existing packages do not need bootstrapping. If trusted publishing is not configured yet, the npm job may fail; rerun it after setup.
+4. Configure a Trusted Publisher for each npm package: GitHub Actions, owner `JIAFALSEDREAM`, repository `agy-delegate-rs`, workflow `release.yml`, and no Environment. Allow direct `npm publish`; staged publishing permissions do not replace this. Current npm documentation requires the first successful use within 2 days of configuration, otherwise recreate it.
+
+With npm 11.15+, you can configure trusted publishing after initial publication using the CLI and browser 2FA. For the entry package:
+
+```sh
+npm trust github agy-delegate-rs --repo JIAFALSEDREAM/agy-delegate-rs --file release.yml --allow-publish --yes
+```
+
+Repeat for each platform package. Cargo/npm repository metadata must match the actual Actions repository. Releases use tagged source, and crate packaging requires a clean working tree. Uncommitted local verification documents are excluded.
+
+For each release, update `Cargo.toml`, the entry npm package version and its six `optionalDependencies`, and this package's version in `Cargo.lock`. CI generates platform package metadata with the same version. Commit to the default branch, then create and push the tag. For example, when all versions are `0.1.3`:
+
+```sh
+git tag -a v0.1.3 -m 'Release v0.1.3'
+git push origin v0.1.3
+```
+
+The workflow validates the release, builds and tests all six native platforms, checks their sandboxes, and produces six binary archives, seven npm packages, and SHA-256 checksums. After all builds succeed, it publishes GitHub Releases, then npm and crates.io. The npm job publishes/verifies all platform packages before the entry package. CI does not call models; cross-platform authentication still requires verification on actual machines.
+
+Publication across the three channels is not atomic. Rerun failed jobs in Actions. If a version already exists on npm or crates.io, its integrity checksum must match before skipping it; different contents are rejected. Public GitHub Release assets are verified and reused. Only draft assets may be replaced. After manually bootstrapping npm packages, rerun the same job to reuse the original archives. Do not delete a published tag and republish different contents; fix the issue and release a new version.

package/INSTALL.md

@@ -0,0 +1,201 @@
+# 安装与配置
+
+简体中文 | [English](INSTALL.en.md)
+
+## 前提
+
+- 从源码安装需要 Rust 1.88 或更新版本，以及本平台的 C 编译工具链（Linux 常用 GCC/Clang，macOS 使用 Xcode Command Line Tools，Windows 按所选 Rust 工具链安装相应构建工具）；本项目编译 SQLite。npm 和 GitHub Release 预编译包无需这些构建工具。
+- 已安装能提供 `agy` 命令、stream-json 接口和 `--gemini_dir` 数据目录参数的 Antigravity CLI，且用户已有的登录或 API 配置能正常调用模型；本项目不安装或代管 agy。
+- 支持命名权限配置且沙箱可正常运行的 Codex CLI，本机验证版本为 0.160.0。本工具直接调用 `codex sandbox`，不单独调用或检查系统中的 bubblewrap；具体运行条件由 Codex 的沙箱后端决定，`install` / `doctor` 会实际验证读写边界。
+
+安装 Codex CLI 可使用 Node.js/npm：
+
+```sh
+npm install -g @openai/codex@0.160.0
+```
+
+Linux 的沙箱运行条件（如用户命名空间权限）需满足当前 Codex 后端要求；macOS 由 Codex 使用系统 Seatbelt，Windows 使用 Codex 的 unelevated 后端。Linux、macOS、Windows 的 x86_64 与 ARM64 共六种原生 CI 环境均已通过测试，并验证项目读取、写入被拒及临时目录可写。
+
+当前模型验收使用用户已有的 API/转换服务，原生 OAuth 登录、系统钥匙串访问和令牌刷新尚未实测。三端都依赖本机 Codex CLI，本项目通过它运行操作系统沙箱。
+
+## 构建与初始化
+
+可以选择以下安装方式：
+
+- GitHub Releases：下载匹配架构的 `.tar.gz` 或 `.zip`，对照 `SHA256SUMS` 校验，解压后将二进制放入 PATH。
+- npm：`npm install -g agy-delegate-rs`，需要 Node.js 22.14+，不需要 Rust；入口包通过可选依赖自动安装匹配系统与架构的平台包，只下载一个二进制，不使用安装脚本。不要禁用 optional dependencies；若缺少平台包，使用 `npm install -g agy-delegate-rs --include=optional` 重装。
+- crates.io：`cargo install agy-delegate-rs --locked`，需要前述 Rust 和 C 编译工具链。
+
+预编译包提供 Linux x64/arm64（musl 静态链接）、macOS x64/arm64、Windows x64/arm64，共六种组合。三种方式都不会安装 agy 或 Codex CLI；首次集成执行 `agy-delegate-rs install`，成功后新开 Codex 会话。模型认证仍需真实调查验证。
+
+从内置所有二进制的旧 npm 版（0.1.3 及更早）升级到按平台拆包版本时，原生程序路径会变化。**已经执行过 `install` 或 `register` 的用户，应在 npm 升级前先用旧版执行 `uninstall`，升级后再执行 `install`**，并沿用注册时的配置参数：
+
+```sh
+agy-delegate-rs uninstall
+npm install -g agy-delegate-rs@latest
+agy-delegate-rs install
+```
+
+如果已经升级且提示存在不属于当前程序的 MCP 注册，请在原 npm 安装前缀中暂时安装 `agy-delegate-rs@0.1.3`，恢复旧路径后按上述顺序迁移。无需删除配置或任务历史；`uninstall` 会先关闭该状态目录中的任务。未注册过 MCP 的用户可以直接安装新版，后续平台包升级保持相同路径。
+
+在仓库目录执行：
+
+```sh
+cargo install --path . --locked
+agy-delegate-rs init
+agy-delegate-rs doctor
+```
+
+`cargo install` 把程序放入 Cargo 的 bin 目录，请确保该目录在 PATH 中。`init` 输出配置文件路径，默认使用系统用户配置目录中的 `agy-delegate-rs/config.toml`。Linux 默认是 `~/.config/agy-delegate-rs/config.toml`，受 XDG_CONFIG_HOME 影响。
+
+也可以指定配置文件：
+
+```sh
+agy-delegate-rs init --config /absolute/path/config.toml
+agy-delegate-rs --config /absolute/path/config.toml doctor
+```
+
+`init` 不覆盖已有文件，不生成或复制密钥。需要修改时直接编辑配置。`doctor` 输出 JSON，检查配置、环境文件、程序版本、agy 的公开无界面参数、状态目录及实际沙箱读写边界；有失败项时退出码非零。它不调用模型，也不验证登录、API 连通性、令牌刷新或 `--gemini_dir` 的实际数据写入路径。初始化后用下文的 `run` 命令执行一次实际调查，确认当前 agy 版本和认证可用。
+
+## 配置
+
+默认模板：
+
+```toml
+codex = "codex"
+agy = "agy"
+agy_args = []
+# Always passed explicitly; agy's interactive model selection does not affect tasks.
+model = "gemini-3.8-flash-high"
+log_bytes = 4000000
+profile_bytes = 128000000
+timeout = 600
+report_chars = 4000
+retention_days = 14
+max_history_jobs = 1000
+# agy_env_file = "/absolute/path/api.env"
+# effort = "high"
+# state_dir = "/absolute/path/state"
+```
+
+命令行参数优先于文件设置。配置覆盖参数放在子命令之前，例如 `agy-delegate-rs --model your-model --agy-env-file /absolute/path/api.env run --cwd /path/to/repo --task '梳理入口'`；`--config` 和 `--timeout` 也可以放在子命令之后。文件中的相对路径以配置文件所在目录为基准；`agy`、`codex` 的单独程序名从 PATH 查找，指定相对程序路径时写成 `./bin/agy`。命令行路径以启动目录为基准。不支持自动展开 `~` 或路径中的环境变量，请写完整路径。
+
+`model` 默认是 agy 内置的 `gemini-3.8-flash-high`，即 Gemini 3.8 Flash (High)。新调查及续聊均显式传入该值，不沿用用户在 agy 中选中的模型。没有配置文件、配置中省略 `model`、旧快照中模型为 `null` 时，也使用此默认值；已有的非空模型配置保持优先。模型不可用时任务失败，不自动降级或切换。
+
+`effort` 是可选的思考等级，支持 `low`、`medium`、`high`、`xhigh`、`max`，具体可用等级由 agy 和所选模型决定。默认模型名已经包含 High，无需另设 `effort`。agy 1.3.2 支持裸名与等级分开指定：`model = "gemini-3.8-flash"` 配合 `effort = "high"`，或命令行 `--model gemini-3.8-flash --effort high`；若模型名已有等级后缀，单独设置的等级必须与后缀一致。自定义接口或协议转换服务应按 `agy models` 和接口实际接受的模型标识覆盖配置，本工具不自动改写模型名。
+
+`timeout` 为任务执行期限，范围 1–7200 秒；`report_chars` 限制后台任务查询返回的报告长度，范围 256–6000；`retention_days` 范围 1–365；`max_history_jobs` 范围 10–10000。后两项用于手动清理和 worker 保存任务结果后的自动清理。`agy_args` 放在托管的 agy 参数之前，例如 `agy = "node"` 配合 `agy_args = ["/absolute/path/agy.js"]`；也可重复传入 `--agy-arg`。参数中不要放凭据。`log_bytes` 范围 4096–32000000，限制单个 `agy.log` 及保留的 stderr；协议输出仍有独立的 4 MB 上限。`profile_bytes` 范围 1000000–1000000000，默认 128000000 字节，限制每个独立会话目录内的文件总大小，也可在子命令前传 `--profile-bytes`。
+
+Rust 版不自动导入原 Python 项目的 `config.json` 或任务数据库；并行使用时保留各自独立的状态目录。需手动迁移已有程序路径、模型和环境文件路径，不要复制密钥到 TOML 配置中。
+
+认证环境默认继承，环境变量优先于 `agy_env_file` 中的值。环境文件只引用用户已有的配置，不写入项目配置中的密钥字段；未知配置项会报错。凭据环境值及持久任务路径须为 UTF-8。自定义 API 若需要协议转换，应独立运行转换服务，本项目不提供它。
+
+新任务通过 `--gemini_dir` 使用 `state_dir/conversations/<root_id>`，同一会话的后续任务复用该目录。首次需要时，仅从默认 `~/.gemini/antigravity-cli` 复制已有的 `settings.json` 和 `antigravity-oauth-token`；不会复制宿主会话、插件或单独的 MCP 配置文件。已存在的私有登录文件不会被覆盖，刷新结果留在私有目录，原文件不回写。环境文件中的凭据通过环境传入，程序不会自动导入宿主的 `api.env`。独立目录中的登录文件、模型缓存与调查历史按私有数据保存，请勿提交到版本库。
+
+## 注册 Codex MCP
+
+初始化后可以使用安装助手：
+
+```sh
+agy-delegate-rs install
+# 只注册 MCP，不添加策略：
+agy-delegate-rs register
+# 指定 Codex 配置目录（也用于隔离验收）：
+agy-delegate-rs install --codex-home /absolute/path/codex-home
+```
+
+`install` 先运行离线 doctor，通过后注册 `agy-delegate-rs` MCP 并写入受管理的 AGENTS 策略。已有 Python 注册或策略时会拒绝覆盖；确认 Rust 版可用后，再手动移除旧的注册与受管理策略。外部协议转换服务可以继续保留。
+
+注册会保存当前有效配置（包括命令行覆盖）的快照，后续修改配置需要重新执行 `register`。安装助手管理配置与 MCP 集成；程序文件通过所选的 npm、Cargo 或 GitHub Release 安装渠道管理。
+
+注册归属同时核对当前二进制路径和本 Codex 目录的配置快照。沿用固定安装路径的升级可以重新注册；要移动二进制或切换安装渠道，请先从原路径执行 `uninstall`，移动后再安装集成。程序不会自动接管来自其它二进制路径的注册。
+
+安装、注册和卸载会互斥本工具的操作，并在关闭任务后重新核对注册归属。Codex 自身的配置写入没有共享锁或条件更新接口；操作期间请勿同时运行其它 `codex mcp add/remove` 或手动编辑同一配置。外部并发写入仍可能互相覆盖。
+
+规则备份和恢复使用文件同步与原子替换；Unix 还同步父目录，按备份、规则、备份删除的顺序持久化。Windows 支持进程中断后的恢复，但不承诺断电时的目录写入持久性。
+
+也可以手动在 Codex 的 `config.toml` 添加：
+
+```toml
+[mcp_servers.agy-delegate-rs]
+command = "/absolute/path/agy-delegate-rs"
+args = ["--config", "/absolute/path/config.toml", "mcp"]
+```
+
+Windows 路径可以使用 TOML 单引号。使用默认配置时 `args = ["mcp"]` 即可。重启或重新加载 Codex 的 MCP 服务后生效。
+
+提供 `agy_submit`、`agy_status`、`agy_wait`、`agy_followup`、`agy_cancel`、`agy_list`。列表只返回简短状态；详细结果通过 status/wait 查询。调用方必须检查状态，`incomplete` 或失败不能当作完成。助手卸载只删除匹配本程序与配置快照的注册，并校验受管理策略未被编辑，保留其它设置和规则。
+
+## 运行和清理
+
+```sh
+agy-delegate-rs run --cwd /path/to/repo --task '梳理入口，附文件行号'
+agy-delegate-rs submit --cwd /path/to/repo --task '梳理入口，附文件行号'
+agy-delegate-rs wait JOB_ID --seconds 50
+agy-delegate-rs followup JOB_ID '继续核查调用链'
+agy-delegate-rs submit --cwd /path/to/repo --task-file /path/to/task.txt
+agy-delegate-rs followup JOB_ID --task-file /path/to/followup.txt
+agy-delegate-rs report JOB_ID --output /path/to/new-report.txt
+agy-delegate-rs cleanup --dry-run
+agy-delegate-rs cleanup
+```
+
+`--task` 与 `--task-file` 二选一；`--task-file -` 从 stdin 读取 UTF-8。文件最多 96000 字节、任务最多 24000 个字符。`report` 读取完整存储结果，不受查询报告长度限制，导出时不覆盖已有文件。
+
+后台任务由独立 worker 执行，MCP 服务关闭后仍继续；`wait` 超时不取消任务。状态默认在系统用户数据目录中，可用 `state_dir` 配置或 `--state-dir` 指定。
+
+清理按任务最后更新时间判断过期，并保留最近的历史条数；任一条件达到即可选中已结束任务。`--dry-run` 只预览，检查 `selected_ids` 后再执行实际清理。运行中、孤儿任务，以及同一会话仍有活跃或未确认停止任务的历史都会保留；持有所有权锁或仍有沙箱进程的任务也跳过。
+
+实际清理删除本工具的任务数据库记录和日志目录。清理后的任务 ID 不能再查询或追问；同一会话还有其它历史记录时，独立目录仍保留，可以通过未删除的记录追问。删除最后一条历史引用时一并删除对应的受管会话目录，结果通过 `deleted_conversation_ids` 返回；用户的共享 `~/.gemini` 和原登录文件保留。
+
+同步 `run` 也使用任务记录和 worker，参与相同清理；Ctrl-C 请求取消任务，清理在已保存结果的 worker 中进行，不阻塞提交。同步结果中的 `cleanup_status` 可能仍为 `pending`；最终清理结果可通过 `status JOB_ID` 查询。旧版本未纳入任务记录的 `run-*` 目录仍保留，需确认无进程使用后自行处理。升级前使用共享 profile 的旧任务继续沿用共享数据，清理只删除其任务记录和日志，不删除共享 agy 会话。没有历史记录可确认归属的独立目录也会保留。
+
+清理先将任务标记为 `purging`，再删除日志和可清理的独立会话目录；在此期间不能追问同一会话。文件删除失败会返回失败项并保留任务记录，处理原因后可重试。如果会话目录删除失败，即使已删掉一部分数据也保留 `purging`，阻止恢复损坏的会话。清理进程中断后可再次运行 `cleanup` 完成恢复。过期和条数限制只作用于可安全清理的历史；被锁定或会话仍活跃的记录不占保留条数。
+
+同一状态目录只允许一个实际清理进程；同时启动的第二个进程返回 `cleanup_active` 跳过结果。日志根目录中的 `.cleanup.lock` 会保留以维持进程间锁，请勿在工具运行期间手动删除它。检测到日志或会话目录被替换、无法核验安全删除时，会保留任务记录并报告跳过或错误。
+
+## 沙箱范围与卸载
+
+新任务中的项目与普通宿主文件只读；本工具管理的独立会话目录和任务临时目录可写，并允许联网。旧版共享 profile 的任务仍允许写入宿主 `~/.gemini`。当前方案用于保护项目写入，不提供账号、凭据或网络隔离。工作目录与可写目录重叠时拒绝启动；沙箱启动失败时拒绝执行，不回退为无沙箱运行。
+
+Unix worker 与沙箱组长均已退出、但仍有子进程存活且身份无法核实时，取消会报错并阻止追问，需要人工清理；当前没有独立监督进程。
+
+先运行 `agy-delegate-rs uninstall`，取消并确认本状态目录的任务停止、撤销匹配的 MCP 注册并恢复受管理策略，再卸载程序：npm 安装使用 `npm uninstall -g agy-delegate-rs`，Cargo 安装使用 `cargo uninstall agy-delegate-rs`，GitHub Release 安装则删除自行放置的二进制。无法确认任务停止或策略已编辑时，助手拒绝继续删除集成。该操作不会自动删除配置、任务历史或用户 agy 配置；数据清理由用户单独决定。
+
+任务运行期间每 100 毫秒检查应用日志大小；超限即终止任务，结束后保留的日志会截断并脱敏。独立会话目录在启动前、运行中每轮约 2 秒及停止后检查文件总大小，超出 `profile_bytes` 会终止整个沙箱进程组。扫描不跟随符号链接，无法安全扫描时任务失败。取消、超时或已有执行错误会保留原状态与诊断，并附加结束检查的错误。
+
+这些监控不是文件系统硬配额，检查间隔内可能暂时超过限制。`profile_bytes` 只监控受管独立会话目录，不限制共享 agy 账号目录或其它任务的磁盘总占用。
+
+操作系统不能在期限内确认整个沙箱进程组结束时，任务会失败，tmp/UNVERIFIED_PROCESS 标记会说明原始日志仍保留在私有目录中；此时日志不能视为已脱敏。先确认并停止相关进程，再处理日志和清理。卸载会拒绝无法核验的任务目录。
+
+卸载的取消范围是选中的 state_dir，包括 CLI 任务，即使当前 Codex 配置目录没有 Rust 注册也会停止该任务池。多个 Codex 配置目录共用状态目录时共用任务池和清理策略；需要隔离任务时，请分别配置 state_dir。程序会在关闭检查期间阻止新提交；遇到正在提交或启动的任务时需稍后重试卸载。
+
+## 维护者发版
+
+`.github/workflows/release.yml` 仅由推送 `v*.*.*` tag 触发，进一步限制为稳定版本 `vMAJOR.MINOR.PATCH`。tag 指向的提交必须在仓库默认主分支历史中，且 tag、`Cargo.toml` 和 `npm/package.json` 版本一致；不符合时终止，不发布。
+
+首次发版前完成一次性设置：
+
+1. 将仓库推到 `JIAFALSEDREAM/agy-delegate-rs`，默认主分支设为 `main`，启用 Actions。
+2. 在仓库 Actions Secrets 中添加 `CARGO_REGISTRY_TOKEN`，需有发布 `agy-delegate-rs` 的权限。npm 不使用这个 token，也无需 `NPM_TOKEN`。
+3. npm 的入口包 `agy-delegate-rs` 和六个平台包 `agy-delegate-rs-{linux,darwin,win32}-{x64,arm64}` 必须由你的账号持有。不存在的平台包需首次手动发布：从 GitHub Release 下载对应的 `PACKAGE-VERSION.tgz`，本地登录 npm 后执行 `npm publish ./PACKAGE-VERSION.tgz --access public`。先发六个平台包，再发入口包；已有包无需重新引导。此时 workflow 的 npm job 可能因尚未配置可信发布失败，完成配置后重跑该 job。
+4. 为每个包分别配置 Trusted Publisher：在 npm 包设置中选择 GitHub Actions，填写 owner `JIAFALSEDREAM`、仓库名 `agy-delegate-rs`、workflow 文件名 `release.yml`，不填 Environment。允许直接 `npm publish`；新配置默认的 staged publishing 权限不代替此项。当前 npm 文档要求首次成功使用新配置在 2 天内完成，超时需重建配置。
+
+npm 11.15+ 也可在首次发布后通过 CLI 配置可信发布（按提示在浏览器完成账号 2FA）。下面以入口包为例，六个平台包分别替换包名执行：
+
+```sh
+npm trust github agy-delegate-rs --repo JIAFALSEDREAM/agy-delegate-rs --file release.yml --allow-publish --yes
+```
+
+Cargo/npm 元数据中的仓库地址必须与 Actions 的实际仓库一致，发版前会核对。版本与源代码保持 tag 内容，crate 打包要求工作区干净。本地未提交的验收文档不会进入 crate 或 npm 包。
+
+每次发版修改 Cargo/npm 两处版本、入口包 `optionalDependencies` 中的六个平台依赖版本，并更新 `Cargo.lock` 中的本包版本。六个平台包的元数据由 CI 自动生成，无需分别维护。提交到主分支后打 tag 并推送，例如版本均为 `0.1.3` 时：
+
+```sh
+git tag -a v0.1.3 -m 'Release v0.1.3'
+git push origin v0.1.3
+```
+
+流程先验证，并在 Linux、macOS、Windows 的 x86_64 与 ARM64 六种原生环境构建、执行测试与原生沙箱检查，生成六个二进制压缩包、七个 npm 安装包和 SHA-256 清单；全部构建通过后发布 GitHub Release，再分别发布 npm 和 crate。六个平台包由脚本自动生成、统一版本，npm job 先逐一发布并验证平台包，全部成功后才发布入口包；CI 负责维护，无需手工编辑七套元数据。跨平台的模型认证仍需实机验收，CI 不会调用模型。
+
+三个渠道不是原子事务。部分渠道失败时，在 Actions 重跑失败的 job；npm 和 crate 若已有相同版本，会比较现有包的完整性摘要，相同才跳过，不会覆盖不同内容。已公开的 GitHub Release 会校验并复用原资产，npm 内容不匹配时拒绝继续；只允许替换尚未公开的草稿资产。首次 npm 手动发布后也应重跑同一 job，以复用原安装包。不要删除已发布版本的 tag 后重复发不同内容；修复并提升版本再发。

package/README.en.md

@@ -0,0 +1,152 @@
+# agy-delegate-rs
+
+[简体中文](README.md) | English
+
+[![npm version](https://img.shields.io/npm/v/agy-delegate-rs?style=flat-square&logo=npm)](https://www.npmjs.com/package/agy-delegate-rs)
+[![crates.io version](https://img.shields.io/crates/v/agy-delegate-rs?style=flat-square&logo=rust)](https://crates.io/crates/agy-delegate-rs)
+[![GitHub release](https://img.shields.io/github/v/release/JIAFALSEDREAM/agy-delegate-rs?style=flat-square&logo=github)](https://github.com/JIAFALSEDREAM/agy-delegate-rs/releases/latest)
+[![CI status](https://img.shields.io/github/actions/workflow/status/JIAFALSEDREAM/agy-delegate-rs/ci.yml?branch=main&style=flat-square&logo=githubactions&label=CI)](https://github.com/JIAFALSEDREAM/agy-delegate-rs/actions/workflows/ci.yml)
+[![Rust 1.88+](https://img.shields.io/badge/Rust-1.88%2B-orange?style=flat-square&logo=rust)](Cargo.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+Delegate read-only repository investigations to Antigravity CLI (`agy`), with project files protected by the Codex operating system sandbox. Run investigations from the command line, or use the Codex MCP server to submit background tasks, retrieve results, and ask follow-up questions.
+
+Useful for tracing entry points and call chains, locating configuration, counting files, and comparing implementations. The tool calls your existing agy installation. Model hosting and API protocol conversion are managed separately.
+
+The default model is **Gemini 3.8 Flash (High)** (`gemini-3.8-flash-high`). Every investigation and follow-up passes the model explicitly, so switching models in agy does not affect this tool. Override it through this tool's configuration or command-line options.
+
+## Quick start
+
+### 1. Prepare dependencies
+
+- **Antigravity CLI**: an `agy` command supporting stream-json and `--gemini_dir`, with working model access.
+- **Codex CLI**: support for named permission profiles. The locally verified version is `0.160.0`.
+- **A working Codex sandbox**: the tool calls `codex sandbox`; Codex manages the platform backend. `install` checks the actual read/write boundaries.
+- **Node.js 22.14+**: required for the npm installation below.
+
+See the [installation guide](INSTALL.en.md#prerequisites) for prerequisites. This package does not install agy or Codex CLI.
+
+### 2. Install and connect to Codex
+
+```sh
+npm install -g agy-delegate-rs
+agy-delegate-rs install
+```
+
+npm selects the binary for your platform; Rust is not required. `install` checks dependencies and the sandbox, registers the MCP server, and adds managed AGENTS rules so Codex prefers MCP for read-only investigations. Start a new Codex session after installation to use `agy_submit` and the other tools.
+
+You can also download a binary from [GitHub Releases](https://github.com/JIAFALSEDREAM/agy-delegate-rs/releases), or run `cargo install agy-delegate-rs --locked`. Prebuilt archives and npm packages cover x86_64 and ARM64 on Linux, macOS, and Windows. Source installation requires Rust 1.88+ and a C toolchain for your platform.
+
+**Upgrading from older npm packages**: if you registered MCP with `0.1.3` or earlier, run `uninstall` with the old version before upgrading, then run `install` with the new version. See the [migration steps](INSTALL.en.md#build-and-initialize).
+
+### 3. Verify a real investigation
+
+```sh
+agy-delegate-rs run --cwd /absolute/path/to/repo --task 'Trace task scheduling entry points and call chains, with file and line references'
+```
+
+Installation checks and `doctor` do not call a model. This step verifies agy authentication and model access.
+
+## Everyday use
+
+### Command line
+
+`run` waits for completion and returns the result. For background tasks, use `submit`, then query or follow up with the returned job ID:
+
+```sh
+agy-delegate-rs submit --cwd /absolute/path/to/repo --task 'Locate configuration loading, with file and line references'
+agy-delegate-rs wait JOB_ID --seconds 50
+agy-delegate-rs followup JOB_ID 'Check the configuration override order'
+```
+
+A follow-up creates a new job ID and reuses the original conversation. Background tasks run in independent workers and continue after the MCP server closes. A `wait` timeout does not cancel the task.
+
+For longer instructions, use `--task-file /absolute/path/task.txt` instead of `--task`. Export a complete report with:
+
+```sh
+agy-delegate-rs report JOB_ID --output /absolute/path/new-report.txt
+```
+
+Exports never overwrite an existing file. See [running and cleanup](INSTALL.en.md#run-and-clean-up) for more commands.
+
+### Codex MCP
+
+| Tool | Purpose |
+| --- | --- |
+| `agy_submit` | Submit a read-only investigation and immediately return a job ID |
+| `agy_status` | Query task status and results |
+| `agy_wait` | Wait for a result; the task continues if the wait times out |
+| `agy_followup` | Continue the original conversation with a new job |
+| `agy_cancel` | Request termination of the task's local process tree |
+| `agy_list` | List recent tasks and recover job IDs |
+
+Provide a precise investigation scope and an absolute repository path. Always check the returned status: failed, incomplete, or timed-out investigations must not be treated as completed. Retrieve detailed results with `agy_status` or `agy_wait`.
+
+## Configuration and authentication
+
+Authentication environment variables are inherited by default. You can also load an existing environment file:
+
+```sh
+agy-delegate-rs --agy-env-file /absolute/path/api.env run --cwd /absolute/path/to/repo --task 'Locate the configuration entry point'
+```
+
+Existing environment variables take precedence over values in the file. Environment file contents are not written to task records. Place override options such as `--model`, `--agy`, `--codex`, and `--state-dir` before the subcommand.
+
+To create a configuration file, run `agy-delegate-rs init` and edit the path it prints. The default is in your system's user configuration directory, usually `~/.config/agy-delegate-rs/config.toml` on Linux. Run `register` again after configuration changes to update the snapshot used by MCP.
+
+The default model configuration is:
+
+```toml
+model = "gemini-3.8-flash-high"
+```
+
+This default also applies when there is no configuration file or `model` is omitted. `gemini-3.8-flash-high` is an agy built-in model ID that includes High reasoning effort. agy 1.3.2 also accepts the model and effort separately; choose either form:
+
+```toml
+model = "gemini-3.8-flash"
+effort = "high"
+```
+
+The corresponding command-line options are `--model gemini-3.8-flash --effort high`. In agy, the bare Gemini 3.8 Flash model name requires an effort. If a model ID already has an effort suffix, a separate `effort` must agree with it. Custom APIs and protocol converters must use model IDs accepted by the installed agy and endpoint; check `agy models`. agy manages login authentication and custom API settings. This tool does not translate model IDs or authentication protocols. If the model is unavailable, the task fails rather than switching models automatically.
+
+An explicitly configured model from an older version remains in effect. `null` model values in old JSON task snapshots fall back to this tool's default. To apply the new default to an existing MCP registration, check this tool's `model` configuration and run `agy-delegate-rs register` again.
+
+Use `agy-delegate-rs doctor` to check configuration, dependencies, and actual sandbox read/write boundaries. Verify model authentication with a real investigation.
+
+See the [installation guide](INSTALL.en.md) for all settings, custom Codex directories, and manual MCP registration. Run any API protocol conversion service separately.
+
+## Sandbox and data boundaries
+
+- **Read-only access**: project files and ordinary host files are read-only. New tasks may write only to their managed conversation directory and temporary task directory. A working directory overlapping a writable directory is rejected.
+- **Network and credentials**: network access for model calls is allowed. The sandbox restricts file writes; it does not isolate networks or credentials.
+- **Startup**: automatic approval of agy tool permissions is used inside the operating system sandbox. If sandbox startup fails, the task fails.
+- **Conversation data**: follow-ups reuse `state_dir/conversations/<root_id>`. On first use, existing `settings.json` and `antigravity-oauth-token` files are imported from the default `~/.gemini/antigravity-cli`. Subsequent refreshes stay in the private directory; original files are not updated.
+- **Storage limits**: managed conversation directories default to a 128,000,000-byte limit (`profile_bytes`). Periodic monitoring terminates tasks that exceed it; this is not a filesystem quota.
+
+State is stored in your system's user data directory under `agy-delegate-rs`, or the directory selected with `--state-dir`. Reports, caches, and private login files may contain sensitive data; keep them out of version control.
+
+Preview cleanup before removing history:
+
+```sh
+agy-delegate-rs cleanup --dry-run
+agy-delegate-rs cleanup
+```
+
+Deleted tasks cannot be queried or followed up. Removing the last history reference to a conversation also removes its managed directory. Older tasks using a shared profile continue to use their original data; cleanup preserves the user's shared `~/.gemini`. See [cleanup](INSTALL.en.md#run-and-clean-up) and [uninstallation](INSTALL.en.md#sandbox-scope-and-uninstall).
+
+## Support and validation
+
+This is a preview release. Tests and sandbox read/write checks have passed on all six native CI environments: x86_64 and ARM64 on Linux, macOS, and Windows.
+
+Real model calls, reconnection, follow-ups, and cleanup have been verified on Linux. Real model calls on macOS and Windows still need verification on actual machines. Native OAuth login, token refresh, and system keychain reuse have not been tested.
+
+Run tests from the source repository:
+
+```sh
+cargo test
+cargo test --test sandbox native_sandbox_preserves_fixture -- --ignored
+```
+
+## License
+
+The [MIT license](LICENSE) covers this project's code. The tool calls an externally installed Codex CLI and does not bundle its binary or bubblewrap.

package/README.md

@@ -1,55 +1,152 @@
 # agy-delegate-rs
 
-面向 Linux、macOS 和 Windows 的只读 agy 调查工具。调用用户已有的 agy，三端统一通过 Codex 的操作系统沙箱限制写入。当前为预览版：三端的 x86_64 与 ARM64 均已通过原生 CI 测试和真实沙箱检查；模型调用已在 Linux 验证，macOS、Windows 的模型认证仍待实机验收。
+简体中文 | [English](README.en.md)
 
-安装、配置、MCP 注册、环境诊断与历史清理见 [安装指南](INSTALL.md)。
+[![npm version](https://img.shields.io/npm/v/agy-delegate-rs?style=flat-square&logo=npm)](https://www.npmjs.com/package/agy-delegate-rs)
+[![crates.io version](https://img.shields.io/crates/v/agy-delegate-rs?style=flat-square&logo=rust)](https://crates.io/crates/agy-delegate-rs)
+[![GitHub release](https://img.shields.io/github/v/release/JIAFALSEDREAM/agy-delegate-rs?style=flat-square&logo=github)](https://github.com/JIAFALSEDREAM/agy-delegate-rs/releases/latest)
+[![CI status](https://img.shields.io/github/actions/workflow/status/JIAFALSEDREAM/agy-delegate-rs/ci.yml?branch=main&style=flat-square&logo=githubactions&label=CI)](https://github.com/JIAFALSEDREAM/agy-delegate-rs/actions/workflows/ci.yml)
+[![Rust 1.88+](https://img.shields.io/badge/Rust-1.88%2B-orange?style=flat-square&logo=rust)](Cargo.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
 
-支持 GitHub Release 预编译包、`npm install -g agy-delegate-rs` 和 `cargo install agy-delegate-rs --locked`。GitHub Release 和 npm 包覆盖 Linux、macOS、Windows 的 x86_64 与 ARM64，共六种组合；npm 入口包自动安装当前系统与架构的平台包，只下载对应二进制，无需 Rust。仍需自行安装 agy、Codex CLI 和对应沙箱依赖。依赖就绪后，可用 npm 安装并注册到 Codex：
+把代码库的只读调查交给 Antigravity CLI（`agy`），通过 Codex 的操作系统沙箱保护项目文件。支持直接在命令行运行，也支持作为 Codex MCP 服务提交后台任务、查询结果和继续追问。
+
+适合梳理入口与调用链、查找配置、统计文件、比较实现等调查任务。项目调用你已安装并配置好的 agy，不包含模型服务或 API 协议转换代理。
+
+默认使用 **Gemini 3.8 Flash (High)**（`gemini-3.8-flash-high`）。每次调查及续聊都会显式指定模型，用户在 agy 中切换模型不会影响本工具；也可通过本工具的配置或命令行覆盖。
+
+## 快速开始
+
+### 1. 准备依赖
+
+- **Antigravity CLI**：提供 `agy` 命令，支持 stream-json 和 `--gemini_dir`，且已能正常调用模型。
+- **Codex CLI**：支持命名权限配置，本机验证版本为 `0.160.0`。
+- **Codex 沙箱可用**：本工具直接调用 `codex sandbox`，由 Codex 管理平台沙箱后端；`install` 会实际验证读写边界。
+- **Node.js 22.14+**：使用下方 npm 安装方式时需要。
+
+依赖安装方法见[安装指南](INSTALL.md#前提)。本工具的安装包不会安装 agy 或 Codex CLI。
+
+### 2. 安装并接入 Codex
 
 ```sh
 npm install -g agy-delegate-rs
 agy-delegate-rs install
 ```
 
-`install` 先检查依赖和沙箱，再注册 MCP 与受管理的 AGENTS 策略。成功后新开 Codex 会话。自定义配置、从源码安装和清理方式见安装指南。
+npm 自动选择当前平台的二进制，无需 Rust。`install` 会先检查依赖和沙箱，再注册 MCP 服务并写入受管理的 AGENTS 策略，让 Codex 优先通过 MCP 委派只读调查。成功后新开 Codex 会话，即可使用 `agy_submit` 等工具。
+
+也可通过 [GitHub Releases](https://github.com/JIAFALSEDREAM/agy-delegate-rs/releases) 下载预编译包，或使用 `cargo install agy-delegate-rs --locked`。预编译包与 npm 包覆盖 Linux、macOS、Windows 的 x86_64 和 ARM64；从源码安装需要 Rust 1.88+ 和本平台的 C 编译工具链。
+
+**旧版 npm 用户**：如果已用 `0.1.3` 或更早版本注册 MCP，升级前需先用旧版执行 `uninstall`，升级后再执行 `install`。完整迁移步骤见[安装指南](INSTALL.md#构建与初始化)。
+
+### 3. 验证一次真实调查
+
+```sh
+agy-delegate-rs run --cwd /absolute/path/to/repo --task '梳理任务调度入口和调用链，附文件行号'
+```
+
+安装检查和 `doctor` 都不调用模型。这一步用于确认 agy 的认证和模型调用可用。
+
+## 日常使用
+
+### 命令行
+
+`run` 等待调查结束并返回结果。需要后台执行时，使用 `submit`，再用返回的任务 ID 查询或追问：
+
+```sh
+agy-delegate-rs submit --cwd /absolute/path/to/repo --task '查找配置加载位置，附文件行号'
+agy-delegate-rs wait JOB_ID --seconds 50
+agy-delegate-rs followup JOB_ID '继续核查配置覆盖顺序'
+```
+
+追问会产生新的任务 ID，并复用原会话。后台任务由独立 worker 执行，MCP 服务关闭后仍继续；`wait` 等待超时不会取消任务。
+
+长任务说明可以用 `--task-file /absolute/path/task.txt` 代替 `--task`。导出完整报告：
+
+```sh
+agy-delegate-rs report JOB_ID --output /absolute/path/new-report.txt
+```
+
+导出不会覆盖已有文件。更多命令见[运行和清理](INSTALL.md#运行和清理)。
+
+### Codex MCP
+
+| 工具 | 用途 |
+| --- | --- |
+| `agy_submit` | 提交只读调查，立即返回任务 ID |
+| `agy_status` | 查询任务状态和结果 |
+| `agy_wait` | 等待任务结果；等待超时后任务继续运行 |
+| `agy_followup` | 沿用原会话继续追问，生成新任务 |
+| `agy_cancel` | 请求停止任务的本地进程树 |
+| `agy_list` | 列出近期任务的简短状态，恢复任务 ID |
+
+提交时应给出明确的调查范围和仓库绝对路径。取得结果后必须检查任务状态：失败、未完成或超时的调查不能当作已完成。详细结果通过 `agy_status` 或 `agy_wait` 获取。
 
-## 前提
+## 配置与认证
 
-- 从源码安装需要 Rust 1.88+ 和本平台的 C 编译工具链；三端都需要 agy 和支持命名权限配置的 Codex CLI（本机验证为 0.160.0）。
-- agy 须支持 stream-json 和 `--gemini_dir` 数据目录参数。
-- agy 已能正常调用模型：原生登录或用户自行配置的兼容接口均可。
-- 自定义接口若需要协议转换，转换服务须独立运行；本项目不包含代理。
+认证环境默认继承，也可以加载已有的环境文件：
 
 ```sh
-cargo build --release
-./target/release/agy-delegate-rs run --cwd /path/to/repo --task '梳理任务调度入口，附文件行号'
+agy-delegate-rs --agy-env-file /absolute/path/api.env run --cwd /absolute/path/to/repo --task '查找配置入口'
 ```
 
-认证环境默认继承。已有环境文件可在子命令前通过 `--agy-env-file /path/to/api.env` 加载；已有环境变量优先，环境文件内容不写入任务记录。`--model`、`--agy`、`--codex` 等配置覆盖参数也写在子命令前。
+已有环境变量优先于环境文件中的值，环境文件内容不写入任务记录。`--model`、`--agy`、`--codex`、`--state-dir` 等覆盖参数放在子命令之前。
 
-Linux 上的真实模型调用、重连、续聊及清理已通过现有 API/转换服务验证；原生 OAuth 登录和刷新尚未实测。`doctor` 不调用模型，安装后仍需运行一条实际调查确认认证可用。
+需要配置文件时，先执行 `agy-delegate-rs init`，再编辑它输出的文件路径。默认位于系统用户配置目录下；Linux 通常为 `~/.config/agy-delegate-rs/config.toml`。配置修改后需重新执行 `register`，更新 MCP 使用的配置快照。
+
+默认模型配置如下；未创建配置文件或省略 `model` 时，也使用这个默认值：
+
+```toml
+model = "gemini-3.8-flash-high"
+```
+
+`gemini-3.8-flash-high` 是 agy 内置的模型标识，已经包含 High 思考等级。agy 1.3.2 也支持分开指定，两种方式选其一：
+
+```toml
+model = "gemini-3.8-flash"
+effort = "high"
+```
 
-## 沙箱边界
+对应命令行参数为 `--model gemini-3.8-flash --effort high`。裸模型名在 agy 中需要配合 `effort`；若模型名已有等级后缀，另设的 `effort` 必须与其一致。自定义 API 或协议转换服务应使用当前 agy/接口接受的模型标识，可通过 `agy models` 查看；登录认证与自定义接口的配置由 agy 管理，本工具不转换模型名或认证协议。模型不可用时任务失败，不自动切换到其它模型。
 
-- 项目及普通宿主文件只读；新任务只允许写入本工具管理的独立会话目录和单个任务临时目录。
-- 允许联网调用模型；这是防止项目被修改的工具，不是网络或凭据隔离工具。
-- 同一会话的追问复用独立目录。首次使用时从用户默认的 `~/.gemini/antigravity-cli` 导入已有 `settings.json` 和 `antigravity-oauth-token`，后续保留私有目录中的刷新结果，原文件不回写；系统钥匙串的登录复用仍需实机验收。
-- CLI 权限自动放行仅在操作系统沙箱内部使用；沙箱启动失败直接失败，不回退到无沙箱执行。
-- 工作目录与可写目录重叠时拒绝启动。
-- Linux 使用 Codex 的 Linux 沙箱（本机使用 bubblewrap/seccomp）；macOS 使用系统 Seatbelt；Windows 指定 Codex 的 `unelevated` 模式。
-- 六种原生 CI 环境均已验证项目读取、写入被拒及临时目录可写。Linux 另已验证真实模型读取和返回报告；macOS、Windows 的真实模型调用尚待实机验证。
+升级前的配置若已显式指定其它模型，会保留该选择；旧任务快照中的空模型会回退到本工具默认值。要让已注册的 MCP 使用新默认模型，请确认本工具配置中的 `model`，再执行 `agy-delegate-rs register`。
 
-状态默认保存在用户数据目录的 `agy-delegate-rs` 下，可用 `--state-dir` 指定。缓存、报告可能含私有代码，不应提交到版本库。
+遇到环境或沙箱问题时，可运行 `agy-delegate-rs doctor` 检查配置、依赖和实际沙箱读写边界；模型认证仍需通过真实调查验证。
 
-独立会话目录位于状态目录的 `conversations/<root_id>`。`profile_bytes` 默认 128000000 字节，监控整个会话目录内的文件总大小，超限终止任务；这是定时监控而非文件系统硬配额。自动或手动清理最后一条历史引用时才删除该目录，仍有记录可供追问时保留。私有目录中的登录文件和会话数据也不应提交到版本库。
+完整配置项、自定义 Codex 目录和手动 MCP 注册方法见[安装指南](INSTALL.md)。自定义 API 若需要协议转换，请单独运行转换服务。
 
-升级前已使用共享 profile 的旧任务继续沿用其原有数据；清理不会删除用户的共享 `~/.gemini`。
+## 沙箱与数据边界
 
-## 验证
+- **只读范围**：项目及普通宿主文件只读。新任务仅允许写入本工具管理的独立会话目录和任务临时目录；工作目录与可写目录重叠时拒绝启动。
+- **联网与凭据**：允许联网调用模型。沙箱用于限制文件写入，不提供网络或凭据隔离。
+- **启动保障**：agy 的权限自动放行仅在操作系统沙箱内部使用；沙箱启动失败时任务直接失败。
+- **会话数据**：同一会话的追问复用 `state_dir/conversations/<root_id>`。首次使用时从默认 `~/.gemini/antigravity-cli` 导入已有的 `settings.json` 和 `antigravity-oauth-token`；后续刷新留在私有目录，原文件不回写。
+- **存储限制**：会话目录默认限制为 128,000,000 字节（`profile_bytes`）。这是定时监控，超限会终止任务，并非文件系统硬配额。
+
+状态默认保存在系统用户数据目录的 `agy-delegate-rs` 下，可通过 `--state-dir` 指定。报告、缓存和私有登录文件可能包含敏感数据，请勿提交到版本库。
+
+清理历史前可先预览：
+
+```sh
+agy-delegate-rs cleanup --dry-run
+agy-delegate-rs cleanup
+```
+
+清理后的任务不能再查询或追问；删除会话的最后一条历史引用时，也会删除对应的独立会话目录。旧版使用共享 profile 的任务继续沿用原有数据，清理不会删除用户的共享 `~/.gemini`。清理条件与卸载步骤见[安装指南](INSTALL.md#运行和清理)及[沙箱范围与卸载](INSTALL.md#沙箱范围与卸载)。
+
+## 支持与验证
+
+当前为预览版。Linux、macOS、Windows 的 x86_64 与 ARM64 六种原生 CI 环境均已通过测试和沙箱读写检查。
+
+Linux 已验证真实模型调用、重连、续聊和清理；macOS、Windows 的真实模型调用仍待实机验收。原生 OAuth 登录、令牌刷新和系统钥匙串复用尚未实测。
+
+在源码仓库运行测试：
 
 ```sh
 cargo test
 cargo test --test sandbox native_sandbox_preserves_fixture -- --ignored
 ```
 
-MIT 许可证仅覆盖本项目代码。当前调用外部安装的 Codex CLI，不捆绑其二进制或 bubblewrap。
+## 许可证
+
+[MIT](LICENSE) 许可证仅覆盖本项目代码。本项目调用外部安装的 Codex CLI，不捆绑其二进制或 bubblewrap。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-delegate-rs",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Read-only agy investigations through the Codex OS sandbox",
   "license": "MIT",
   "repository": {
@@ -13,18 +13,21 @@
   "files": [
     "bin",
     "README.md",
+    "README.en.md",
+    "INSTALL.md",
+    "INSTALL.en.md",
     "LICENSE"
   ],
   "engines": {
     "node": ">=22.14.0"
   },
   "optionalDependencies": {
-    "agy-delegate-rs-linux-x64": "0.1.5",
-    "agy-delegate-rs-linux-arm64": "0.1.5",
-    "agy-delegate-rs-darwin-x64": "0.1.5",
-    "agy-delegate-rs-darwin-arm64": "0.1.5",
-    "agy-delegate-rs-win32-x64": "0.1.5",
-    "agy-delegate-rs-win32-arm64": "0.1.5"
+    "agy-delegate-rs-linux-x64": "0.1.6",
+    "agy-delegate-rs-linux-arm64": "0.1.6",
+    "agy-delegate-rs-darwin-x64": "0.1.6",
+    "agy-delegate-rs-darwin-arm64": "0.1.6",
+    "agy-delegate-rs-win32-x64": "0.1.6",
+    "agy-delegate-rs-win32-arm64": "0.1.6"
   },
   "os": [
     "linux",