dsh-codex-connect 0.1.0-alpha.4.6 → 0.1.0-alpha.4.8

package/INSTALL.md

@@ -12,6 +12,8 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
 
 ## Install and validate
 
+The only verified combination is DSH plugin API packages `0.1.0-rc.6`, `@earendil-works/pi-ai` `0.82.1`, and Node.js `^22.19.0 || >=24.0.0`. Upgrade the DSH API packages and pi-ai together, then rerun `dsh-codex-connect doctor --json` and `pnpm --silent run check:compatibility`; the contract does not make claims about future versions.
+
 1. Check `dsh --version` or `dsh --help`. From a Harness checkout use `pnpm dsh`.
 2. Install the package:
 
@@ -19,7 +21,7 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
    dsh plugin --profile web add dsh-codex-connect@alpha
    ```
 
-   After `0.1.0-alpha.4.6` is published, pin it exactly with `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.6`. If npm is unavailable after its matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.6'`.
+   After `0.1.0-alpha.4.8` is published, pin it exactly with `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.8`. If npm is unavailable after its matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.8'`.
 
 3. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
 4. Confirm the effective `agent-default-model` and `web.searchProvider` values are unchanged from before installation.
@@ -31,6 +33,17 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
 
 6. If the user explicitly requests login, open **Settings → Plugins → Plugin configuration → Codex Connect**, or check `status` and then use `login` or `login --device-code`. OAuth approval belongs to the user.
 
+### Remote browser access
+
+The default Web OAuth boundary is loopback-only. When DSH runs on one device and you open it from another device on a trusted network through an IP address or domain, run the following on the device that runs DSH with the exact origin from the browser address bar:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+dsh plugin --profile web exec dsh-codex-connect trusted-origins
+```
+
+The value is a full `http://` or `https://` origin including its port, not a bare device IP and not a path/query/fragment. Use `untrust-origin <origin>` to remove it. Restrict this to a trusted network and never expose the route publicly; use an SSH tunnel when that is safer. The Web client does not edit this list.
+
 ## Optional configuration
 
 Use **Settings → Plugins → Plugin configuration → Codex Connect** for live, staged Save/Discard edits. The package row accepts the same `enableSearch` and `enableImageTool` fields as its composition base, both defaulting to `false`. Enabling search registers a provider but does not select it; selecting `web.searchProvider: openai-codex` is a second explicit profile change. Setting `agent-default-model` to `openai-codex` is also a separate explicit change.

package/README.md

@@ -7,59 +7,87 @@ English | [中文](docs/README.zh.md)
 Connect your ChatGPT subscription to DeepSeek Harness with OAuth, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/hero.jpg" alt="Codex Connect — ChatGPT OAuth for DeepSeek Harness" width="100%">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/hero.jpg" alt="Codex Connect — ChatGPT OAuth for DeepSeek Harness" width="100%">
 </p>
 
 `dsh-codex-connect` adds the `openai-codex` model catalog and a separate ChatGPT OAuth login. Models run through Harness's normal LLM service, so streaming, tool calls, reasoning replay, compaction, filesystem controls, permission gates, and approval prompts remain Harness-owned. It does not turn a ChatGPT subscription into an OpenAI Platform API credential.
 
 Installation is additive. The bundle does not replace the current default model or search route, and its standalone search provider and `view_image` tool are disabled until explicitly enabled.
 
-## See it in Harness
+Every UI screenshot in this English guide is captured from the English-localized Harness UI. The [Chinese guide](docs/README.zh.md) uses a Chinese capture of the same state. Model and provider identifiers keep their canonical spelling in both languages.
 
-Sign in and manage the plugin from **Settings → Plugins → Plugin configuration → Codex Connect**.
+## Quick start (about five minutes)
+
+This guide uses the `web` profile. Replace `web` with the name of the Harness profile you already use. You need a working `dsh` installation; from a DeepSeek Harness source checkout, prefix the commands with `pnpm`.
+
+### 1. Install the plugin into one profile
+
+```sh
+dsh plugin --profile web add dsh-codex-connect@alpha
+```
+
+Expected result: the package is added to that profile. This does not change the profile's default model or global search route.
+
+To reproduce this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.8`. If npm is unavailable after the matching GitHub prerelease exists, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.8'`. A local checkout can be installed as `link:/absolute/path/to/dsh-codex-connect`.
+
+### 2. Start Harness
+
+```sh
+dsh web
+```
+
+Expected result: the Harness web UI opens for the selected profile.
+
+### 3. Find the Codex Connect card
+
+Open **Settings → Plugins → Plugin configuration → Codex Connect**.
+
+Expected result: a fresh installation shows **Not signed in** and a **Sign in with ChatGPT** button. The card is where you later manage optional capabilities too.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/oauth-status.jpg" alt="Codex Connect ChatGPT OAuth status inside Harness plugin configuration" width="720">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/plugin-entry.jpg" alt="Collapsed English-localized Codex Connect entry under Harness plugin configuration" width="720">
 </p>
 
-Optional Codex search and `view_image` capabilities remain explicit, profile-scoped choices:
+### 4. Sign in with ChatGPT
+
+Click **Sign in with ChatGPT** and complete the browser approval yourself. Do not copy an authorization URL, code, token, or account identifier into an issue, log, or configuration file.
+
+Expected result: the account area changes to **Signed in**. The screenshot below is the successful end state after this step; it is not the initial sign-in screen.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/plugin-configuration.jpg" alt="Codex Connect optional capability settings in DeepSeek Harness" width="720">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/oauth-status.jpg" alt="English-localized Codex Connect signed-in state inside Harness plugin configuration" width="720">
 </p>
 
-Codex models then appear in Harness's normal model picker alongside the existing providers:
+### 5. Choose a model and make one safe check
+
+Open Harness's normal model picker and select an `openai-codex` model for the agent or session you are using. This selection is separate from writing the profile's default model or global search route.
+
+The picker groups the available entries under **OpenAI Codex**. Model identifiers such as `GPT-5.6 Luna` are canonical names, so they intentionally remain un-translated.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/model-selector.jpg" alt="OpenAI Codex models in the DeepSeek Harness model picker" width="320">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/model-selector.jpg" alt="OpenAI Codex model group in the English-localized DeepSeek Harness model picker" width="360">
 </p>
 
-## Install
+To confirm the configured plugin row locally, run:
 
 ```sh
-dsh plugin --profile web add dsh-codex-connect@alpha
-dsh web
+dsh --profile web --dump-config
 ```
 
-After `0.1.0-alpha.4.6` is published, pin it exactly with `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.6`. If npm is unavailable after its matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.6'`. From a DeepSeek Harness source checkout, prefix commands with `pnpm`. For a local checkout, install `link:/absolute/path/to/dsh-codex-connect`.
+Expected result: the configuration has exactly one `llm-openai-codex` row. Keep this configuration dump local; it may include unrelated profile settings.
 
-Sign in from **Settings → Plugins → Plugin configuration → Codex Connect → Sign in with ChatGPT**, or use the CLI:
+For secret-free status and diagnostics that do not start OAuth, run:
 
 ```sh
-dsh plugin --profile web exec dsh-codex-connect login
-dsh plugin --profile web exec dsh-codex-connect status
-dsh plugin --profile web exec dsh-codex-connect doctor
+dsh plugin --profile web exec dsh-codex-connect status --json
+dsh plugin --profile web exec dsh-codex-connect doctor --json
 ```
 
-The doctor command reads process and filesystem metadata only. It never opens the OAuth document or prints a token, authorization URL, authorization code, account id, or auth-file content.
-
-For automation, `doctor --json` emits exactly one secret-free JSON document with schema version 1, package/version/Node metadata, credential-file state and safe mode, capabilities, conflict status, and hints; it omits the absolute credential path and OAuth/account/expiry data. `status --json` emits only signed-in or signed-out state with package metadata. `doctor --json` reads metadata only; `status --json` reads the credential solely to determine sign-in state, but neither mode prints credential contents or starts OAuth. Signed-out status still exits with code 1.
+Expected result: `status --json` reports `signed-in` and exits `0`, while `doctor --json` prints one secret-free JSON document. A signed-out `status --json` exits `1`; return to step 4 instead of treating that as a plugin failure.
 
-## Explicit configuration
+## Optional capabilities (off by default)
 
-Open **Settings → Plugins → Plugin configuration → Codex Connect** to manage the ChatGPT account and optional capabilities in one card. Changes use Harness's revision-fenced settings store and apply live. **Save changes** affects only this plugin's capability section; it never selects a default model or global search route.
-
-The installed bundle row remains the composition base and is intentionally inert beyond model-provider registration:
+The installed bundle is intentionally inert beyond model-provider registration:
 
 ```yaml
 - id: llm-openai-codex
@@ -68,6 +96,21 @@ The installed bundle row remains the composition base and is intentionally inert
     enableImageTool: false
 ```
 
+Open **Settings → Plugins → Plugin configuration → Codex Connect** to manage the account and these options in one card. **Save changes** affects only this plugin's capability section and applies live. It never selects a default model or a global search route.
+
+### Enable only the capability you intend to use
+
+- `enableSearch: true` registers Codex as an available search provider. It does not select the profile's global search route.
+- `enableImageTool: true` enables `view_image` for approved local reads and public-network image fetches on vision-capable models.
+
+The screenshot below is an example after someone has explicitly enabled capabilities. It does not show the fresh-install default. This English guide uses the English-localized capture; the Chinese guide shows the matching Chinese-localized state.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/plugin-configuration.jpg" alt="English-localized Codex Connect optional capability configuration after explicit opt-in" width="720">
+</p>
+
+### Change a default model or global search route separately
+
 To make a Codex model the default for new agents, add or update the separate Harness row yourself:
 
 ```yaml
@@ -77,7 +120,7 @@ To make a Codex model the default for new agents, add or update the separate Har
     model: gpt-5.6-sol
 ```
 
-The card can enable Codex standalone search. Selecting it as the profile's global search provider remains a separate explicit choice:
+Selecting Codex as the profile's global search route is another explicit change:
 
 ```yaml
 - id: llm-openai-codex
@@ -91,8 +134,6 @@ The card can enable Codex standalone search. Selecting it as the profile's globa
     searchProvider: openai-codex
 ```
 
-To add the image-loading tool, set `enableImageTool: true` on `llm-openai-codex`. Browser paste/drop remains a Harness attachment feature and does not depend on this tool.
-
 | Field | Default | Values |
 |---|---:|---|
 | `enableSearch` | `false` | boolean |
@@ -102,18 +143,28 @@ To add the image-loading tool, set `enableImageTool: true` on `llm-openai-codex`
 | `searchContextSize` | `medium` | `low`, `medium`, `high` |
 | `searchMaxOutputTokens` | `10000` | positive integer |
 
-## Credentials, diagnostics, and conflicts
+## Reauthentication, diagnostics, and conflicts
 
-- OAuth is stored separately at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` by default); `~/.codex/auth.json` is never copied or modified.
-- The parent directory and file are created with owner-only permissions where supported. Writes are atomic, and refresh writes use a cross-process file lock.
-- Status and diagnostics return only non-sensitive state. OAuth flow output is confined to an explicit `login` operation.
-- Browser OAuth routes accept only loopback clients and loopback Host/Origin values; sign-in fails closed when no valid HTTPS authorization URL arrives within 30 seconds.
-- A second adapter cannot own `openai-codex`. Startup fails with a focused hint when the legacy `dsh-codex` bundle or a manual provider row conflicts.
+- If the card says **Sign in again** or the server asks for reauthentication, click that action and complete the same safe browser flow. It preserves this plugin's capability settings and does not silently change your default model or global search route. Do not run `logout` just to renew a session.
+- `doctor` reads process and filesystem metadata only. `doctor --json` emits exactly one secret-free JSON document with schema version 1, package/version/Node metadata, credential-file state and safe mode, capabilities, conflict status, and hints. It omits the absolute credential path and OAuth, account, and expiry data.
+- `status --json` emits only signed-in or signed-out state with package metadata. `status --json` reads the credential only to determine sign-in state, but never prints credential contents or starts OAuth.
+- OAuth is stored separately at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` by default). `~/.codex/auth.json` is never copied or modified. The parent directory and file use owner-only permissions where supported, writes are atomic, and refresh writes use a cross-process file lock.
+- By default, the OAuth routes accept loopback browser requests only. When DSH runs on one device and you open it from another device on a trusted network, approve the browser address-bar origin explicitly on the device that runs DSH:
+
+  ```sh
+  dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+  dsh plugin --profile web exec dsh-codex-connect trusted-origins
+  dsh plugin --profile web exec dsh-codex-connect untrust-origin http://192.168.1.20:3080
+  ```
+
+  Replace the example with the exact origin from the browser address bar, including scheme and port; do not enter the accessing device's IP, a bare host, a path, a query, or a fragment. Trust only a network you control, never expose this route to the public Internet, and use an SSH tunnel as the fallback when explicit network trust is not appropriate. The browser page only displays and copies this command; it never changes the allowlist itself.
+- If startup reports an `openai-codex` collision, an old `dsh-codex` bundle or manual provider row may already own the adapter. Inspect the effective configuration and remove only the confirmed conflicting owner. Do not delete auth files or unrelated providers.
 - Removing the package does not delete OAuth state. Run `logout` only when credential removal is intended.
 
 ## Compatibility and security boundary
 
-- Alpha compatibility targets the current Harness `0.1.0-rc.5` main-line composition and compatible `0.1.0-rc.6` plugin APIs, Node.js `^22.19.0 || >=24.0.0`, and the pinned `@earendil-works/pi-ai` Codex provider.
+- The only verified compatibility combination is DSH plugin API packages `0.1.0-rc.6`, `@earendil-works/pi-ai` `0.82.1`, and Node.js `^22.19.0 || >=24.0.0`; see [compatibility.json](compatibility.json).
+- Upgrade the DSH plugin API packages and `@earendil-works/pi-ai` as one group, then run `dsh-codex-connect doctor --json` and the compatibility check again. This contract does not make claims about future versions.
 - ChatGPT plan eligibility, model access, quotas, and backend behavior are controlled by OpenAI and may change.
 - The Codex endpoint does not enforce the ordinary Responses `max_output_tokens` field. Harness compaction still works, but that summary cap cannot be imposed server-side on this route.
 - Shell, filesystem, skills, MCP, subagents, approvals, permissions, attachments, session persistence, compaction, and recovery continue to come from the active Harness profile.
@@ -129,6 +180,10 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
+## Releases
+
+Maintainers publish alpha versions through the [manual OIDC release workflow](.github/workflows/release.yml); see the [alpha release runbook](RELEASING.md) for the separate, short-lived `latest` promotion step.
+
 ## Legal / Acknowledgements
 
 Copyright 2026 Frank Song for the modifications and additional work in Codex Connect. This project includes software derived from [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex); Copyright 2026 Yan-Zero is retained for the upstream material. Both are distributed under Apache-2.0, with details in [NOTICE](NOTICE). This project is not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.

package/compatibility.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dshPluginApi": {
+    "version": "0.1.0-rc.6",
+    "packages": [
+      "@deepseek-ai/dsh-agent",
+      "@deepseek-ai/dsh-atomic-write",
+      "@deepseek-ai/dsh-attachment",
+      "@deepseek-ai/dsh-home-paths",
+      "@deepseek-ai/dsh-host-webserver",
+      "@deepseek-ai/dsh-invariants",
+      "@deepseek-ai/dsh-llm",
+      "@deepseek-ai/dsh-llm-pi-ai",
+      "@deepseek-ai/dsh-fs",
+      "@deepseek-ai/dsh-session",
+      "@deepseek-ai/dsh-settings",
+      "@deepseek-ai/dsh-tools",
+      "@deepseek-ai/dsh-web"
+    ]
+  },
+  "piAi": {
+    "package": "@earendil-works/pi-ai",
+    "version": "0.82.1"
+  }
+}

package/docs/README.zh.md

@@ -7,59 +7,87 @@
 通过 OAuth 将你的 ChatGPT 订阅连接到 DeepSeek Harness，同时保留用户自主默认项、Harness 原生审批、非敏感诊断和可靠的会话恢复。
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/hero.jpg" alt="Codex Connect — 通过 ChatGPT OAuth 连接 DeepSeek Harness" width="100%">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/zh/hero.jpg" alt="Codex Connect — 通过 ChatGPT OAuth 连接 DeepSeek Harness" width="100%">
 </p>
 
 `dsh-codex-connect` 提供 `openai-codex` 模型目录和独立的 ChatGPT OAuth 登录。模型仍走 Harness 标准 LLM 服务，因此流式输出、工具调用、reasoning replay、压缩、文件系统控制、权限门禁和审批提示仍由 Harness 负责。ChatGPT 订阅不会因此变成 OpenAI Platform API 凭据。
 
 安装是增量的：bundle 不会替换当前主模型或搜索路由；独立搜索提供方和 `view_image` 工具也默认关闭，必须显式开启。
 
-## 在 Harness 中的样子
+本中文指南中的 UI 截图均来自中文本地化的 Harness 界面；[English 版](../README.md) 使用同一状态的英文截图。模型与提供方标识保留其规范拼写，不随界面语言翻译。
 
-在 **设置 → 插件 → 插件配置 → Codex Connect** 中登录并管理插件。
+## 五分钟快速开始
+
+本指南使用 `web` profile。请把 `web` 替换成你已经在用的 Harness profile 名称。你需要先有可用的 `dsh` 安装；如果在 DeepSeek Harness 源码 checkout 中运行，请在命令前加 `pnpm`。
+
+### 1. 将插件装入一个 profile
+
+```sh
+dsh plugin --profile web add dsh-codex-connect@alpha
+```
+
+预期结果：包被加入该 profile。这个动作不会更改 profile 的默认模型或全局搜索路由。
+
+如需精确复现这个版本，使用 `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.8`。对应 GitHub prerelease 已创建但 npm 不可用时，可使用 `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.8'`。本地 checkout 可安装为 `link:/absolute/path/to/dsh-codex-connect`。
+
+### 2. 启动 Harness
+
+```sh
+dsh web
+```
+
+预期结果：所选 profile 的 Harness Web UI 打开。
+
+### 3. 找到 Codex Connect 卡片
+
+打开 **设置 → 插件 → 插件配置 → Codex Connect**。
+
+预期结果：新安装时账户区显示 **尚未登录**，并出现 **使用 ChatGPT 登录** 按钮。之后管理可选能力也在同一张卡片中完成。
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/oauth-status.jpg" alt="Harness 插件配置中的 Codex Connect ChatGPT OAuth 状态" width="720">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/zh/plugin-entry.jpg" alt="Harness 插件配置中的中文 Codex Connect 折叠入口" width="720">
 </p>
 
-Codex 搜索与 `view_image` 都是显式、按 profile 控制的可选能力：
+### 4. 使用 ChatGPT 登录
+
+点击 **使用 ChatGPT 登录**，并自行完成浏览器审批。不要把授权 URL、授权码、token 或账户标识复制到 Issue、日志或配置文件中。
+
+预期结果：账户区变为 **已登录**。下图展示的是完成本步骤后的成功状态，不是开始登录前的页面。
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/plugin-configuration.jpg" alt="DeepSeek Harness 中的 Codex Connect 可选能力设置" width="720">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/zh/oauth-status.jpg" alt="Harness 插件配置中的中文 Codex Connect 已登录状态" width="720">
 </p>
 
-Codex 模型会和现有提供方一起出现在 Harness 原生模型选择器中：
+### 5. 选择模型并做一次安全检查
+
+打开 Harness 原生模型选择器，为当前正在使用的 agent 或会话选择一个 `openai-codex` 模型。这个选择与写入 profile 的默认模型或全局搜索路由是两件事。
+
+选择器会把可用项归在 **OpenAI Codex** 下。`GPT-5.6 Luna` 一类模型标识是规范名称，因此会保留原样，不翻译。
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/model-selector.jpg" alt="DeepSeek Harness 模型选择器中的 OpenAI Codex 模型" width="320">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/zh/model-selector.jpg" alt="中文 DeepSeek Harness 模型选择器中的 OpenAI Codex 模型分组" width="360">
 </p>
 
-## 安装
+如需在本机确认插件配置行，运行：
 
 ```sh
-dsh plugin --profile web add dsh-codex-connect@alpha
-dsh web
+dsh --profile web --dump-config
 ```
 
-在 `0.1.0-alpha.4.6` 发布后，如需精确固定此版本，使用 `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.6`。在对应 GitHub prerelease 已创建且 npm 不可用时，可使用 `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.6'`。在 DeepSeek Harness 源码 checkout 中运行时，在命令前加 `pnpm`。本地开发可安装 `link:/absolute/path/to/dsh-codex-connect`。
+预期结果：配置中恰好有一条 `llm-openai-codex`。请只在本机查看这份配置输出，它可能包含无关的 profile 设置。
 
-可在 **设置 → 插件 → 插件配置 → Codex Connect → 使用 ChatGPT 登录**，也可使用 CLI：
+如需不启动 OAuth 的非敏感状态和诊断输出，运行：
 
 ```sh
-dsh plugin --profile web exec dsh-codex-connect login
-dsh plugin --profile web exec dsh-codex-connect status
-dsh plugin --profile web exec dsh-codex-connect doctor
+dsh plugin --profile web exec dsh-codex-connect status --json
+dsh plugin --profile web exec dsh-codex-connect doctor --json
 ```
 
-`doctor` 只读取进程与文件系统元数据，不打开 OAuth 文件，也不会输出 token、授权 URL、授权码、账户 ID 或认证文件内容。
-
-供脚本使用时，`doctor --json` 只输出一条可解析的非敏感 JSON，包含 schema version 1、包/版本/Node 信息、认证文件状态与安全 mode、能力、冲突状态和提示；它省略认证文件绝对路径以及 OAuth、账户和过期时间信息。`status --json` 只输出 signed-in 或 signed-out 状态及包元数据。`doctor --json` 只读取元数据；`status --json` 仅为判断登录态读取认证文件，但两者都不会输出认证文件内容或启动 OAuth；signed-out 状态仍返回退出码 1。
+预期结果：`status --json` 报告 `signed-in` 并以 `0` 退出，`doctor --json` 只输出一条非敏感 JSON。尚未登录时 `status --json` 会以 `1` 退出；回到第 4 步登录即可，不要把它当作插件故障。
 
-## 显式配置
+## 可选能力（默认关闭）
 
-打开 **设置 → 插件 → 插件配置 → Codex Connect**，可以在同一张卡片中管理 ChatGPT 账户和可选能力。更改通过 Harness 带 revision 防护的设置存储保存，并即时生效；**保存更改**只影响本插件的能力配置，绝不会选择默认模型或全局搜索路由。
-
-安装后的 bundle 行仍是 composition base，只注册模型提供方，不改变路由：
+安装后的 bundle 只注册模型提供方，默认不额外启用任何能力：
 
 ```yaml
 - id: llm-openai-codex
@@ -68,7 +96,22 @@ dsh plugin --profile web exec dsh-codex-connect doctor
     enableImageTool: false
 ```
 
-如需把 Codex 模型设为新 agent 的默认模型，需要自行添加或修改 Harness 的独立配置项：
+打开 **设置 → 插件 → 插件配置 → Codex Connect**，即可在同一张卡片中管理账户和这些选项。**保存更改**只影响本插件的能力配置并即时生效，绝不会选择默认模型或全局搜索路由。
+
+### 只开启你准备使用的能力
+
+- `enableSearch: true` 会把 Codex 注册为可选择的搜索提供方，不会把它选为 profile 的全局搜索路由。
+- `enableImageTool: true` 会为具备视觉能力的模型启用 `view_image`，用于审批后的本地读取和公网图片获取。
+
+下图是有人显式开启能力之后的配置示例，不是新安装的默认状态。本中文指南使用中文本地化截图；English 版展示同一状态的英文截图。
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/zh/plugin-configuration.jpg" alt="中文 Codex Connect 显式开启可选能力后的配置示例" width="720">
+</p>
+
+### 单独更改默认模型或全局搜索路由
+
+如需把 Codex 模型设为新 agent 的默认模型，需要自行添加或修改独立的 Harness 配置项：
 
 ```yaml
 - id: agent-default-model
@@ -77,7 +120,7 @@ dsh plugin --profile web exec dsh-codex-connect doctor
     model: gpt-5.6-sol
 ```
 
-卡片可以启用 Codex 独立搜索；如需把它选为 profile 的全局搜索提供方，仍需单独显式配置：
+如需把 Codex 选为 profile 的全局搜索路由，还需要另做一次显式配置：
 
 ```yaml
 - id: llm-openai-codex
@@ -91,27 +134,56 @@ dsh plugin --profile web exec dsh-codex-connect doctor
     searchProvider: openai-codex
 ```
 
-如需图片加载工具，在 `llm-openai-codex` 上设置 `enableImageTool: true`。浏览器粘贴/拖放属于 Harness 附件能力，不依赖该工具。
-
-## 凭据、诊断与冲突
-
-- OAuth 单独存储于 `$DSH_HOME/.openai-codex-auth.json`（默认 `~/.dsh`），不会复制或修改 `~/.codex/auth.json`。
-- 支持的平台上，父目录与文件使用仅所有者可访问权限；写入采用原子替换，刷新写入使用跨进程文件锁。
-- 状态和诊断只返回非敏感信息；OAuth 交互只会由显式 `login` 操作触发。
-- 浏览器 OAuth 路由只接受 loopback 客户端和 loopback Host/Origin；30 秒内没有得到有效的 HTTPS 授权地址时会安全失败，不会一直挂起。
-- 两个 adapter 不能同时占用 `openai-codex`。旧 `dsh-codex` bundle 或手动 provider 配置冲突时，启动会给出明确迁移提示。
+| 字段 | 默认值 | 可选值 |
+|---|---:|---|
+| `enableSearch` | `false` | boolean |
+| `enableImageTool` | `false` | boolean |
+| `searchModel` | `gpt-5.6-sol` | Codex model id |
+| `searchMode` | `cached` | `cached`、`indexed`、`live` |
+| `searchContextSize` | `medium` | `low`、`medium`、`high` |
+| `searchMaxOutputTokens` | `10000` | 正整数 |
+
+## 重新登录、诊断与冲突
+
+- 卡片显示 **重新登录**，或服务端要求重新认证时，点击该操作并完成同一套安全的浏览器流程。它会保留本插件的能力配置，不会偷偷改动默认模型或全局搜索路由。不要为了刷新会话而运行 `logout`。
+- `doctor` 只读取进程与文件系统元数据。`doctor --json` 只输出一条可解析的非敏感 JSON，包含 schema version 1、包/版本/Node 信息、认证文件状态与安全 mode、能力、冲突状态和提示；它省略认证文件绝对路径以及 OAuth、账户和过期时间信息。
+- `status --json` 只输出 signed-in 或 signed-out 状态及包元数据。它只为判断登录态读取认证文件，但不会输出认证文件内容或启动 OAuth。
+- OAuth 单独存储于 `$DSH_HOME/.openai-codex-auth.json`（默认 `~/.dsh`）。`~/.codex/auth.json` 不会被复制或修改。支持的平台上，父目录与文件使用仅所有者可访问权限；写入采用原子替换，刷新写入使用跨进程文件锁。
+- 默认情况下，OAuth 路由只接受 loopback 浏览器请求。当 DSH 在一台设备运行，而你从可信网络中的另一台设备打开 DSH 时，请在运行 DSH 的设备上显式批准浏览器地址栏中的 origin：
+
+  ```sh
+  dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+  dsh plugin --profile web exec dsh-codex-connect trusted-origins
+  dsh plugin --profile web exec dsh-codex-connect untrust-origin http://192.168.1.20:3080
+  ```
+
+  将示例替换为浏览器地址栏中的精确 origin，包括协议和端口；不要填写当前访问设备的 IP、裸主机、路径、query 或 fragment。只在你信任的网络中使用，不要把该路由暴露到公网；不适合显式信任网络时，请使用 SSH tunnel。浏览器页面只会显示并复制这条命令，不会自行修改授权列表。
+- 启动报告 `openai-codex` 冲突时，旧 `dsh-codex` bundle 或手动 provider 配置可能已占用该 adapter。先检查有效配置，只移除已确认的冲突所有者。不要删除认证文件或无关 provider。
 - 移除包不会删除 OAuth 状态；只有确实需要删除凭据时才运行 `logout`。
 
 ## 兼容性与安全边界
 
-- Alpha 面向当前 Harness `0.1.0-rc.5` 主线组合与兼容的 `0.1.0-rc.6` 插件 API、Node.js `^22.19.0 || >=24.0.0` 和固定版本的 `@earendil-works/pi-ai` Codex provider。
+- 当前唯一已验证的兼容组合是 DSH 插件 API packages `0.1.0-rc.6`、`@earendil-works/pi-ai` `0.82.1` 和 Node.js `^22.19.0 || >=24.0.0`；详见 [compatibility.json](../compatibility.json)。
+- 升级时请将 DSH 插件 API packages 与 `@earendil-works/pi-ai` 作为一组升级，再运行 `dsh-codex-connect doctor --json` 和兼容性检查。本契约不对未来版本作判断。
 - ChatGPT 套餐资格、模型权限、额度和后端行为由 OpenAI 控制，可能变化。
+- Codex 端点不会强制普通 Responses 的 `max_output_tokens` 字段。Harness 压缩仍可工作，但这个摘要上限不能由服务端在该路由上强制。
 - shell、文件系统、skills、MCP、subagents、审批、权限、附件、会话持久化、压缩与恢复继续由当前 Harness profile 提供。
 - 远程 `view_image` 只允许公共 HTTP(S) 目标；每一次 DNS 结果与重定向都会重新检查，并将连接固定到已验证地址，从而阻止 localhost、私网、link-local 服务和云元数据地址。
 - 安装、构建、测试、doctor 和包内容验证均不需要真实 OAuth。
 
 详见 [安装运行手册](../INSTALL.md)、[Alpha 发布清单](../RELEASING.md)、[MIGRATION.md](../MIGRATION.md) 与 [架构说明](design.zh.md)。
 
+## 开发
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+## 发布
+
+维护者通过[手动 OIDC 发布 workflow](../.github/workflows/release.yml)发布 Alpha；`latest` 的独立短期提升步骤见 [Alpha 发布清单](../RELEASING.md)。
+
 ## 法律与致谢
 
 Codex Connect 的修改与新增工作 Copyright 2026 Frank Song。本项目包含派生自 [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex) 的软件；上游内容继续保留 Copyright 2026 Yan-Zero。两部分均按 Apache-2.0 发布，详情见 [NOTICE](../NOTICE)。本项目与 OpenAI、ChatGPT、Codex、DeepSeek 或 DeepSeek Harness 不存在隶属关系，也未获得其背书。

package/docs/design.md

@@ -10,9 +10,9 @@ The Host registers `llm-openai-codex` as the plugin-owned settings namespace and
 
 ## OAuth persistence
 
-The plugin uses `$DSH_HOME/.openai-codex-auth.json`, separate from Codex CLI/Desktop state. The file format is strict and versioned. POSIX reads reject group/world-accessible files. Parent directories and files are created with owner-only modes, writes are atomic, and refresh mutations use the Harness cross-process file lock. Callers receive cloned credentials.
+The plugin uses `$DSH_HOME/.openai-codex-auth.json`, separate from Codex CLI/Desktop state. The file format is strict and versioned. POSIX reads reject group/world-accessible files. Parent directories and files are created with owner-only modes, writes are atomic, and refresh mutations use the Harness cross-process file lock. Callers receive cloned credentials. Browser-origin trust is a separate `$DSH_HOME/.openai-codex-trusted-origins.json` sidecar with `version: 1`, `mode: "allowlist"`, and exact normalized HTTP(S) origins; it never contains OAuth material and is changed only by the standalone CLI.
 
-The settings routes and CLI reuse the existing OAuth path and route names for migration compatibility. Only an explicit login operation emits an authorization URL or code. Browser requests must come from a loopback peer with a loopback Host and, when supplied, an exact loopback HTTP(S) Origin. A login challenge accepts only credential-free HTTPS URLs and fails closed after 30 seconds or when the provider finishes without a URL; logout and disposal cancel pending waiters. Status responses are redacted. Doctor uses `lstat` metadata and never opens the document.
+The settings routes and CLI reuse the existing OAuth path and route names for migration compatibility. Only an explicit login operation emits an authorization URL or code. Browser requests are accepted by default only from loopback; a remote request must use an exact effective HTTP(S) origin in the current sidecar, must not carry cross-site Fetch Metadata, and must match any supplied Origin exactly. The sidecar is re-read for every request, and unknown fields or modes fail closed. A login challenge accepts only credential-free HTTPS URLs and fails closed after 30 seconds or when the provider finishes without a URL; logout and disposal cancel pending waiters. Status responses are redacted. Doctor uses `lstat` metadata and never opens the document.
 
 ## Search and images
 

package/docs/design.zh.md

@@ -10,9 +10,9 @@ Host 将 `llm-openai-codex` 注册为插件自有 settings namespace，并在 LL
 
 ## OAuth 持久化
 
-插件使用 `$DSH_HOME/.openai-codex-auth.json`，与 Codex CLI/Desktop 状态分离。文件格式严格且有版本号；POSIX 上会拒绝组/其他用户可读文件。父目录和文件按仅所有者权限创建，写入采用原子替换，刷新修改使用 Harness 跨进程文件锁，返回给调用方的是凭据副本。
+插件使用 `$DSH_HOME/.openai-codex-auth.json`，与 Codex CLI/Desktop 状态分离。文件格式严格且有版本号；POSIX 上会拒绝组/其他用户可读文件。父目录和文件按仅所有者权限创建，写入采用原子替换，刷新修改使用 Harness 跨进程文件锁，返回给调用方的是凭据副本。浏览器 origin 授权单独存放于 `$DSH_HOME/.openai-codex-trusted-origins.json`，格式为 `version: 1`、`mode: "allowlist"` 和规范化的精确 HTTP(S) origin；其中不含 OAuth 内容，且只能通过独立 CLI 修改。
 
-为兼容迁移，设置页路由、OAuth 路径和 provider id 不改名。浏览器请求必须来自 loopback 对端，并带有 loopback Host；若带 Origin，则必须与该本地 HTTP(S) 源精确匹配。登录挑战只接受不含凭据的 HTTPS 地址；30 秒内未得到地址、provider 已结束但没有地址、退出登录或插件卸载时，所有 waiter 都会被清理。只有显式登录会输出授权 URL 或代码；状态输出会脱敏。doctor 只用 `lstat` 检查元数据，不打开文件。
+为兼容迁移，设置页路由、OAuth 路径和 provider id 不改名。浏览器请求默认只允许 loopback；远程请求必须使用当前 sidecar 中的精确有效 HTTP(S) origin，不能带 cross-site Fetch Metadata，若带 Origin 还必须精确匹配。每次请求都会重新读取 sidecar；未知字段或错误 mode 会快速失败。登录挑战只接受不含凭据的 HTTPS 地址；30 秒内未得到地址、provider 已结束但没有地址、退出登录或插件卸载时，所有 waiter 都会被清理。只有显式登录会输出授权 URL 或代码；状态输出会脱敏。doctor 只用 `lstat` 检查元数据，不打开文件。
 
 ## 搜索与图片