dsh-codex-community 0.0.1

package/docs/architecture.md

@@ -0,0 +1,106 @@
+# 架构
+
+[简体中文](architecture.md) | [English](architecture.en.md)
+
+## 责任范围
+
+本插件注册 Codex route、设置命名空间、OAuth 流程、会话偏好和可靠性策略。消息转换、模型协议、工具权限、session 持久化与 OAuth 协议行为通过 DSH、`@deepseek-ai/dsh-llm-pi-ai` 和 pi-ai 的公开接口完成。
+
+```text
+DSH Web 设置 ── loopback RPC ── AuthorizationBridge
+                                      │
+                         dsh-codex/openai-codex
+                                      │
+                         CodexCredentialStore
+                                      │
+                             ChatGPT OAuth grant
+
+Harness Agent Loop
+        │
+        ├── SessionPreferences ── Fast / transport
+        │
+        ▼
+StreamResilience ── CodexRouteAdapter (`dsh-codex`)
+                              │
+                              ▼
+                PiAiAdapter (`openai-codex`) ── CodexPiProvider
+        ▲
+        └── attachment service ── ImagePolicy
+```
+
+## ProviderRuntime
+
+`ProviderRuntime` 在 `dsh-codex` 设置命名空间中创建 `dsh-codex` route 和 OAuth 流程。外层 `CodexRouteAdapter` 把 DSH route 映射到 PiAiAdapter 内部的 canonical `openai-codex` provider，并在 provider info、模型、stream 历史 source 与错误边界恢复外部 route。这样可以保留 pi-ai 对 response ID、reasoning signature、tool-call ID 和 replay envelope 的语义。
+
+每次请求从当前设置生成不可变 profile；已开始的请求不会被并发设置修改影响，下一次请求会读取新配置，外层 adapter 实例保持不变。
+
+模型目录来自安装版本的 pi-ai。模型筛选、图片预算、缓存策略、超时和有界重试在 profile 边界一次解析。未知模型或重复模型在产生网络请求前失败；未配置 `models` 时展示完整目录，显式空数组则不展示任何模型。
+
+## CodexCredentialStore
+
+凭据记录键为 `dsh-codex/openai-codex`。存储适配器只读取和修改这一条记录，并且只接受 OAuth grant；API key、其他 provider 的记录或结构无效的数据都会失败关闭。写入和删除经过 DSH credentials service 的串行接口：删除先获得锁时不会再发起 refresh，refresh 已获得锁时删除会等待并成为最终状态，避免退出后凭据复活。
+
+Web 设置页只接收登录方法、脱敏提示、授权页面地址、验证码和完成状态。access token、refresh token、完整 grant 与完整 provider 错误不会跨过 loopback RPC，也不会写入命令输出。
+
+## AuthorizationBridge
+
+Host 端通过 DSH authorization service 启动、取消和观察登录流程，并通过 credentials service 查询“是否已配置”或执行退出。RPC 限制并发 attempt、长轮询 waiter、事件数量、字符串长度和可接受 URL。登录结果返回后，插件会在 credentials service 持有该记录的串行写锁时再次检查取消信号；这个 mutate 回调是取消的线性化点：回调选择 grant 前的取消会阻止写入，选择后写入会完成，插件不会再用补偿性删除回滚，因为那可能删除另一个 DSH 进程已经排队的新登录。无凭据内容的 generation tracker 会把提交阶段保持到对应 `authorization/settled`；设置页和 `/codex-login cancel` 在同一同步调用栈内拒绝已经过线性化点的取消，并继续观察最终 `authorized` 状态。退出登录绕过这道限制，先中止活动 attempt，再通过同一串行记录路径显式删除凭据，因此已经开始的旧写入不能在退出完成后复活。已经结束但仍处于短期保留期的 attempt ID 不能取消后来启动的登录。
+
+`/codex-login status|cancel|logout` 使用同一边界，并禁止把命令输入写入会话记录。
+
+## SessionPreferences
+
+`/codex` 只修改接收命令的当前会话：
+
+- `fast on|off` 控制是否发送 priority service tier，默认关闭；
+- `transport` 可选 `auto`、`sse`、`websocket` 或 `websocket-cached`，默认 `auto`；
+- `reset` 恢复当前会话默认值。
+
+偏好保存在有容量上限的内存表中，返回不可变快照，不写入全局 provider 设置。Fast 请求失败后不会自动以另一 service tier 重放，避免重复工具副作用。真实账号是否允许该 tier 必须通过发布验收确认。
+
+DSH 原始 session ID 只用于偏好查询和消息/replay provenance；传给 pi-ai 的 transport/cache session ID 带有 `dsh-codex:` 命名空间。`/codex reset`、`agent/disposed` 和 runtime dispose 只通过 pi-ai 的公开、精确 session API 清理本插件拥有的 WebSocket 连接、fallback 与 debug 状态，不调用无参全局清理，也不影响同进程其他 pi-ai consumer 的 session。该命名空间只进入 pi-ai stream options，不改写历史消息或 replay envelope。
+
+## ModelEnablement
+
+本插件的设置页通过 `llm.discoverModels` 从当前 pi-ai catalog 展示可请求模型，并把选择写入 `dsh-codex` 设置命名空间。Runtime 只注册该命名空间的直接 discovery handler，不为本 route 注册通用 configurable-provider directory，避免干扰 DSH 的通用模型编辑器。
+
+设置页至少要求选中一个模型。全选且条目没有自定义字段时移除 `models` 覆盖，使目录随 pi-ai 版本更新；部分选择、额外字段和自定义参数保留显式配置。目录筛选只影响模型发现，精确指定的隐藏模型仍可解析，因此旧会话不会仅因模型被隐藏而失效。
+
+## ImagePolicy
+
+可选配置会解析为不可变、没有 optional 数字的完整策略。attachment contract 只收到 `{ maxPixels, maxBytes }`。零、负数、浮点、`NaN` 和超安全整数会在配置边界被拒绝。
+
+远程图片通过 `tools/execute` middleware 扩展现有 `read_image`。本地路径原样交给原工具；HTTP(S) URL 经过公网 DNS 校验、地址固定、逐跳重定向校验、总超时、MIME allowlist，以及响应和解压后的字节上限。通过校验的内容先写入 DSH attachment store，再按原工具的 output schema 返回。
+
+每个插件实例最多同时执行 2 个远程图片任务并排队 32 个；队列已满时返回 `TOO_MANY_REQUESTS`。排队期间取消会移除任务，下载阶段取消会终止网络工作。插件卸载会先关闭 limiter、原子拒绝所有排队任务，并用独立 lifetime signal 中止仍处于模型解析或网络阶段的活动任务；Context cleanup 会等待已经进入 `saveImage` 的任务收敛。DSH 当前公开的 `saveImage` 接口没有 `AbortSignal` 或回滚合同，因此保存开始后的取消只保证不向调用方返回成功，不能保证删除可能已经落盘的附件；执行槽也要等 `saveImage` 结束后才释放。有界队列和生命周期封口共同防止卸载后继续启动新工作或造成无限内存增长。
+
+## FailureNormalizer 与 QuotaObserver
+
+`FailureNormalizer` 将 DSH `LlmFailure` 和嵌入的结构化 JSON 转换为稳定分类。只有可验证的结构化 `code`/`type`（例如 `AccountQuotaExceeded`、`insufficient_quota`）或窄化的账户级文本特征确认用量耗尽时才映射成 `QUOTA`；普通 429 保持 `RATE_LIMIT`。多个嵌入 JSON 各自保持独立来源：reset、request ID 和 status 只能来自 failure 顶层或一个自身也能独立证明配额的 `error` envelope，不能跨 envelope 拼接。pi-ai `0.82.1` 会把不同 429 折叠成同一条 ChatGPT usage-limit 文案，且不再提供原始 code/body；这种无结构证据的结果映射为非自动重试的 `QUOTA_OR_RATE_LIMIT`，不会谎称为已确认账户配额。
+
+`QUOTA`、`QUOTA_OR_RATE_LIMIT` 和已确认 transport 的输出均重新构造为最小 failure，只保留固定脱敏消息、code，以及可选的有效 HTTP status/受限字符集 request ID；不回显任意 provider 字段或 WebSocket close reason。`QUOTA_OR_RATE_LIMIT` 不写入 `QuotaObserver`：无 partial 输出时直接失败且不重试，已有安全纯文本时只保存 partial。
+
+`QuotaObserver` 只记录成功终止、`QUOTA` 和通过严格格式及有限时距校验的 reset timestamp。快照只有 `unknown`、`recent-success` 和 `exhausted` 三态。它不轮询账户、不展示余额或百分比，也不调用未公开的套餐额度接口。
+
+## StreamResilience
+
+该模块运行在 `llm/stream` waterfall：
+
+1. 原样转发 provider chunk，并记录开放 block；
+2. 在终止 error、直接抛出的已确认 quota/usage-limit/transport、公开 `STREAM_CLOSED`/WebSocket failure 或无终止 chunk 的 EOF 到达时做窄化分类；
+3. 若已有纯文本且没有工具调用，闭合开放 block、追加恢复提示，并以 `stop` 完成；
+4. 若存在工具调用（包括没有文本的纯工具流），返回非重试失败，不重放整次请求。
+
+模块不自行执行工具，也不增加隐藏的 pre-stream 重试。只有没有产生内容且命中 retry policy 的 `RATE_LIMIT`、`SERVER`、`TIMEOUT` 或已确认 `TRANSPORT` 才可由上层最多重试两次；直接抛出的已确认 failure 走同一脱敏与恢复路径，不相关的异常仍原样抛出。Fast 和 transport 选择不会触发 service-tier 降级或整次请求重放。
+
+## Profile 组合
+
+`codex-community.patch.yml` 只插入 authorization 与 `dsh-codex`，不修改通用 `llm-pi-ai` Cordis row。其他 pi-ai provider 可在同一 profile 中继续使用。
+
+本插件的外部 route 是 `dsh-codex`，凭据键是 `dsh-codex/openai-codex`；通用插件的 route 和凭据范围保持不变。用户若同时启用两条 Codex route，模型选择器会显示两个 provider 组。每次升级 DSH 都必须重跑 bundle 共存、replay 与隔离 profile 加载测试。
+
+## 其他能力边界
+
+- 会话压缩使用 DSH 自带的自动压缩和 `/compact`；本插件不改写压缩协议；
+- Web search 使用 DSH 的工具和对应凭据，不复用 ChatGPT OAuth；
+- 图片生成或编辑需要单独的模型、凭据与计费边界，`0.0.1` 不提供该能力。

package/docs/compatibility.en.md

@@ -0,0 +1,53 @@
+# Compatibility and support boundaries
+
+[简体中文](compatibility.md) | [English](compatibility.en.md)
+
+Last updated: 2026-08-29.
+
+| Component or environment | `0.0.1` evidence | Status |
+| --- | --- | --- |
+| DeepSeek Harness | `test/fixtures/dsh-runtime/pnpm-lock.yaml` locks the complete `@deepseek-ai/dsh@0.1.1-rc.2` runtime/peer graph and validates the `dsh-llm` schema and stream contract | Exact version verified |
+| pi-ai | OAuth, catalog, Codex payload, and replay contract tests against `@earendil-works/pi-ai@0.82.1` | Public contract verified; real sign-in pending |
+| Node.js | Complete local suite on `22.22.2`; [CI run 33224023141](https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33224023141) covers 22 and 24 on all three operating systems | `>=22.19.0 <25` |
+| macOS arm64 | Local tests, build, attachment seam, and isolated profile startup; `macos-latest` CI passes on Node 22 and 24 | Local and CI automation verified |
+| Windows x64 | `windows-latest` CI on Node 22 and 24 completes the frozen DSH install, the full check suite, release-draft verification, exact-candidate install, and disposable Web/profile startup | CI automation verified; real user environment pending |
+| Linux x64 | `ubuntu-latest` CI on Node 22 and 24 completes the same checks and Web/profile smoke | CI automation verified |
+| Real ChatGPT OAuth login | Automation does not read or modify a user's real grant | Controlled acceptance pending |
+| Real Codex conversation | Automation does not consume user account quota | Controlled acceptance pending |
+| Text / reasoning / usage / tools / replay | Public PiAiAdapter success, tool-call, and two-turn replay automation passes | Live reasoning, tool round trip, and conversation continuity are pending |
+| Codex image input | Attachment-seam and budget-projection automation passes | A live request with `maxPixels=4194304` is pending |
+| auto / SSE / WebSocket / cached | Transport mapping and session isolation pass in automation | One live request through each transport is pending |
+| Fast / priority tier | Verified that only an explicit per-session choice changes `service_tier` | Account entitlement and live network pending |
+| npm / GitHub Release | The strict workflow verifies the candidate, Registry readback, and Release assets | `0.0.1` uses npm `latest` and a full GitHub Release |
+
+The `0.0.x` line is a technical preview and declares compatibility only with the exact DSH release candidate above. Before `0.0.1` is formally published, Linux, macOS, and Windows CI/profile smoke must reach `3/3`, supply-chain verification must be complete, and a maintainer must approve the release. The real OAuth, conversation, image, transport, and Fast rows may remain at `0/13` when the formal release is published; post-release validation completes them one by one afterward. Incomplete checks must remain visible and must never be presented as verified capabilities; findings are fixed and iterated in `0.0.2`.
+
+The root `pnpm-lock.yaml` locks plugin dependencies, while `test/fixtures/dsh-runtime/pnpm-lock.yaml` independently locks the complete DSH runtime and peer graph used by compatibility smoke. CI runs `pnpm --dir test/fixtures/dsh-runtime install --frozen-lockfile --ignore-scripts` instead of handing that peer graph to direct npm resolution, avoiding nondeterministic dependency results and uncontrolled memory use. This frozen layer verifies Web/profile integration; it does not claim coverage of native terminal or native-build capabilities in DSH dependencies that require lifecycle scripts. Dependency upgrades must use a pinned-version PR, update and review both lockfiles, repeat complete CI, profile smoke, and supply-chain verification before publication, and renew controlled live validation afterward. The scheduled compatibility workflow only verifies the current locked graph and reports Registry drift; neither a broad semver range nor one scheduled run proves cross-RC compatibility.
+
+## Profile composition
+
+The `0.0.1` bundle does not modify the general `llm-pi-ai` Cordis row. It adds:
+
+- the `dsh-codex` route;
+- the `dsh-codex` settings namespace;
+- the `dsh-codex/openai-codex` OAuth credential record and sign-in flow.
+
+Other pi-ai providers remain usable in the same profile. This plugin does not register a general configurable-provider directory; its settings page manages model selection. If the user also enables the general `openai-codex` route, the model selector shows two Codex provider groups with different routes. The two credential scopes neither read nor migrate each other.
+
+## Model and session capabilities
+
+The model catalog comes from the installed pi-ai `0.82.1`; it is not a live online directory. The settings page requires at least one selected model. Selecting all removes the model override and follows future catalog versions only when entries have no custom fields. Partial selections or entries with custom fields retain explicit configuration. An absent `models` value advertises the complete catalog, while an explicit empty array advertises none; exact hidden models remain resolvable, so catalog filtering does not invalidate older sessions.
+
+Images are sent only to models that declare `image` input. A text-only model rejects an image before provider I/O.
+
+Fast and transport preferences set by `/codex` exist only for the current process and session. Restarting, removing the plugin, or running `/codex reset` restores defaults. Fast is off by default and a failure is not replayed automatically on a lower tier.
+
+## Credentials and capability boundaries
+
+- The Codex route accepts ChatGPT OAuth only and does not read an OpenAI Platform API key.
+- Cancel sign-in through the plugin settings page or `/codex-login cancel`: cancellation succeeds before write linearization, while an in-progress commit is reported as too late and remains observed through its final state; `logout` always deletes the credential. The current DSH public seam has no post-commit cancellation barrier, so third-party code that calls `ctx.authorization.cancel()` directly bypasses this coordination and is not a supported `0.0.1` interaction path.
+- When a plugin or hot-reload flow owner is disposed, sign-in is cancelled before commit selection, while a selected credential commit is allowed to reach its final write before disposal completes. An unsupported or malformed stored record is shown as `invalid`, requires signing in again or signing out to clear it, and is never presented as signed in.
+- The quota card shows recent request-derived observations, not a live balance, percentage, or proactive account query.
+- DSH Web search uses its own provider and credentials; it does not reuse ChatGPT OAuth.
+- `0.0.1` does not provide image generation or editing.
+- Session compaction continues to use DSH's built-in automatic compaction and `/compact`.

package/docs/compatibility.md

@@ -0,0 +1,53 @@
+# 兼容性与支持边界
+
+[简体中文](compatibility.md) | [English](compatibility.en.md)
+
+最近更新：2026-08-29。
+
+| 组件或环境 | `0.0.1` 证据 | 状态 |
+| --- | --- | --- |
+| DeepSeek Harness | `test/fixtures/dsh-runtime/pnpm-lock.yaml` 锁定完整 `@deepseek-ai/dsh@0.1.1-rc.2` runtime/peer 图，并验证 `dsh-llm` schema 与 stream contract | 精确版本已验证 |
+| pi-ai | `@earendil-works/pi-ai@0.82.1` 的 OAuth、模型目录、Codex payload 与 replay 合同测试 | 公开合同已验证；真实登录待验收 |
+| Node.js | 本地 `22.22.2` 完整测试；[CI 运行 33224023141](https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33224023141) 在三种系统上覆盖 22 与 24 | `>=22.19.0 <25` |
+| macOS arm64 | 本地测试、构建、attachment seam 与隔离 profile 启动；`macos-latest` 的 Node 22/24 CI 通过 | 本地与 CI 自动化已验证 |
+| Windows x64 | `windows-latest` 的 Node 22/24 CI 完成冻结 DSH 安装、完整检查套件、发布草案校验、精确候选包安装与一次性 Web/profile 启动 | CI 自动化已验证；真实用户环境待验收 |
+| Linux x64 | `ubuntu-latest` 的 Node 22/24 CI 完成同一组检查与 Web/profile smoke | CI 自动化已验证 |
+| ChatGPT OAuth 真实登录 | 自动化不读取或修改用户真实 grant | 受控验收待完成 |
+| Codex 真实网络对话 | 自动化不消耗用户账户配额 | 受控验收待完成 |
+| 文本 / reasoning / usage / 工具 / replay | 公开 PiAiAdapter 成功流、工具调用和两轮 replay 自动化已通过 | 真实 reasoning、工具闭环与连续对话待验收 |
+| Codex 图片输入 | attachment seam 与预算投影自动化已通过 | `maxPixels=4194304` 真实请求待验收 |
+| auto / SSE / WebSocket / cached | transport 映射与会话隔离自动化已通过 | 四种真实请求待验收 |
+| Fast / priority tier | 已验证仅在当前会话开启时改变 `service_tier` | 账号权限与真实网络待验收 |
+| npm / GitHub Release | 严格工作流校验候选、Registry 回读与 Release 资产 | `0.0.1` 使用 npm `latest` 与正式 GitHub Release |
+
+`0.0.x` 是技术预览，只对表中的精确 DSH 预发布版本声明兼容。`0.0.1` 在正式发布前必须完成 Linux、macOS 和 Windows 三平台 CI/profile smoke `3/3`、完整供应链校验和维护者批准。表中真实 OAuth、对话、图片、transport 和 Fast 状态可在正式发布时保持 `0/13`，并在发布后逐项补齐。这些未完成项必须如实展示，不能冒充已验证能力；发现的问题在 `0.0.2` 中修复和迭代。
+
+根目录 `pnpm-lock.yaml` 锁定插件依赖，`test/fixtures/dsh-runtime/pnpm-lock.yaml` 独立锁定兼容性 smoke 的完整 DSH runtime 与 peer 图；CI 使用 `pnpm --dir test/fixtures/dsh-runtime install --frozen-lockfile --ignore-scripts`，不把该 peer 图交给直接 npm 解算，以避免不确定依赖结果和内存失控。该冻结层验证 Web/profile 集成，不声称覆盖 DSH 依赖中需要生命周期脚本的原生终端或本机构建能力。依赖升级必须通过固定版本变更 PR，同时更新并审查两套 lockfile，在发布前重跑完整 CI、profile smoke 和供应链校验，发布后重新记录受控真实验证。定时兼容工作流只验证当前锁定图并报告 Registry 漂移，不能从宽泛 semver 或一次定时运行推断跨 RC 兼容。
+
+## Profile 组合
+
+`0.0.1` 的 bundle 不修改通用 `llm-pi-ai` Cordis row。它新增：
+
+- `dsh-codex` route；
+- `dsh-codex` 设置命名空间；
+- `dsh-codex/openai-codex` OAuth 凭据记录与登录流程。
+
+其他 pi-ai provider 可以在同一 profile 中继续使用。本插件不注册通用 configurable-provider directory；模型选择由本插件设置页管理。若用户另外启用通用 `openai-codex`，模型选择器会显示两个不同 route 的 Codex provider 组，两个凭据范围互不读取或迁移。
+
+## 模型与会话能力
+
+模型目录来自安装的 pi-ai `0.82.1`，不是在线动态目录。设置页至少要求选中一个模型；全选且条目没有自定义字段时移除模型覆盖并随以后版本的目录更新；部分选择或已有自定义字段时保留显式配置。未配置 `models` 时展示完整目录，显式空数组则不展示任何模型；精确指定的隐藏模型仍可解析，因此旧会话不会因目录筛选失效。
+
+图片只发送给明确声明 `image` input 的模型。text-only 模型在 provider I/O 前拒绝图片。
+
+`/codex` 的 Fast 和 transport 偏好只存在于当前进程、当前会话。重启、插件卸载或执行 `/codex reset` 后恢复默认值。Fast 默认关闭；失败后不会自动降级重放。
+
+## 凭据与功能边界
+
+- Codex route 只接受 ChatGPT OAuth，不读取 OpenAI Platform API key；
+- 请通过插件设置页或 `/codex-login cancel` 取消登录：写入线性化前会正常取消，提交已经开始时会明确提示无法取消并继续等待最终状态；`logout` 始终删除凭据。DSH 当前公共 seam 没有“提交后禁止取消”能力，第三方代码直接调用 `ctx.authorization.cancel()` 会绕过这一协调，不属于 `0.0.1` 支持的交互路径；
+- 插件或热重载 flow owner 卸载时，提交选择前的登录会取消，已经进入凭据提交的登录会等待最终写入再完成卸载；不支持类型或结构损坏的已存记录显示为 `invalid`，需要重新登录或退出清除，不会显示为已登录；
+- 额度卡只显示请求产生的最近观测，不提供实时余额、百分比或主动账户查询；
+- DSH 的 Web search 使用它自己的 provider 和凭据，不复用 ChatGPT OAuth；
+- `0.0.1` 不提供图片生成或编辑；
+- 会话压缩继续使用 DSH 自带的自动压缩和 `/compact`。

package/docs/configuration.en.md

@@ -0,0 +1,61 @@
+# Configuration reference
+
+[简体中文](configuration.md) | [English](configuration.en.md)
+
+The production configuration for the `dsh-codex` bundle lives under `dsh-codex.config` in `codex-community.patch.yml`. A normal installation already supplies safe defaults. The settings page saves `models` only when needed, so the default bundle omits that key.
+
+## Bundle defaults
+
+```yaml
+partialResponseRecovery: true
+cacheRetention: short
+streamIdleTimeoutMs: 300000
+maxRequestImageBytes: 20971520
+requestImagePixelBudget: 4194304
+requestImageMaxBytes: 1048576
+```
+
+Omitting `models` makes the model selector show every Codex model in the currently installed catalog.
+
+## Top-level fields
+
+| Key | Type and allowed values | Default | Unit and behavior |
+| --- | --- | --- | --- |
+| `partialResponseRecovery` | Boolean | `true` | No unit. When enabled, a stream that fails after safe plain text can close the text and preserve the partial response. When disabled, the error remains an error instead of converting the partial response to success. A stream with an incomplete tool call always fails closed. |
+| `models` | Array of model entries, or omitted | Omitted | No unit. Omission exposes the complete catalog; an empty array hides every Codex model from the selector; a non-empty array exposes only the listed models. Saved sessions can still resolve a catalog model by its exact model ID. |
+| `cacheRetention` | `none`, `short`, or `long` | `short` | No unit. Passed through as the context-cache retention policy for Codex requests. The plugin does not convert these enum values into fixed durations. |
+| `streamIdleTimeoutMs` | Number from `1` through `2147483647`, inclusive | `300000` | Milliseconds. Limits only idle time waiting for the next provider stream item, not consumer processing time. Fractions inside the range are accepted. Expiry produces `TIMEOUT`. |
+| `maxRequestImageBytes` | Positive safe integer from `1` through `9007199254740991`, inclusive | `20971520` | Bytes. Bounds the accumulated base64 image payload for one request; text, tools, image descriptors, and JSON structure are excluded. Over-budget images are replaced with fixed text, oldest first. |
+| `requestImagePixelBudget` | Positive safe integer from `1` through `9007199254740991`, inclusive | `4194304` | Pixels. Total-pixel budget for each request image, mapped to attachment request `maxPixels`. The default equals `2048 × 2048`. |
+| `requestImageMaxBytes` | Positive safe integer from `1` through `9007199254740991`, inclusive | `1048576` | Raw bytes. Byte budget for each generated request-image version, mapped to attachment request `maxBytes`. The default is `1 MiB`. |
+
+## Model entries
+
+Each `models` entry supports these fields:
+
+| Key | Required | Type and range | Behavior |
+| --- | --- | --- | --- |
+| `id` | Yes | String | Must name a Codex model in the currently installed catalog. Unknown or duplicate IDs are rejected during configuration validation. |
+| `name` | No | String | Overrides the model display name. Omission uses the catalog name. |
+| `contextWindow` | No | Positive safe integer from `1` through `9007199254740991`, inclusive | Overrides the model context window. |
+| `maxTokens` | No | Positive safe integer from `1` through `9007199254740991`, inclusive | Overrides the model output cap and becomes the request default when no output cap is specified explicitly. |
+
+Example:
+
+```yaml
+models:
+  - id: gpt-5.4
+    name: Codex
+    contextWindow: 272000
+    maxTokens: 128000
+```
+
+Model IDs and capabilities follow the pinned runtime catalog. Check the catalog discovered by the settings page before editing; do not infer that an example ID is always available.
+
+## Validation and activation
+
+- An omitted or `null` Boolean, enum, timeout, or image limit receives its default. `models: null` does not select the default catalog; omit `models` instead.
+- Type mismatches, unknown enum values, ordinary numbers outside the allowed ranges, fractional image limits, and unknown or duplicate model IDs are rejected during plugin load or settings save. A rejected update does not replace the last valid configuration.
+- Use only the finite JSON/YAML numbers listed above. `NaN`, infinity, and undocumented fields are outside the supported configuration interface.
+- A configuration update takes effect on the next adapter operation. An operation already in progress continues with the immutable configuration snapshot it captured at start.
+- `/codex` Fast and transport preferences are temporary state for the current session in the current process, not bundle configuration keys.

package/docs/configuration.md

@@ -0,0 +1,61 @@
+# 配置参考
+
+[简体中文](configuration.md) | [English](configuration.en.md)
+
+`dsh-codex` bundle 的生产配置位于 `codex-community.patch.yml` 的 `dsh-codex.config`。正常安装已经写入安全默认值；`models` 由设置页面按需保存，因此默认 bundle 不包含该键。
+
+## Bundle 默认配置
+
+```yaml
+partialResponseRecovery: true
+cacheRetention: short
+streamIdleTimeoutMs: 300000
+maxRequestImageBytes: 20971520
+requestImagePixelBudget: 4194304
+requestImageMaxBytes: 1048576
+```
+
+省略 `models` 表示模型选择器显示当前安装目录中的全部 Codex 模型。
+
+## 顶层字段
+
+| 键 | 类型与允许值 | 默认值 | 单位与行为 |
+| --- | --- | --- | --- |
+| `partialResponseRecovery` | 布尔值 | `true` | 无单位。开启时，流在安全纯文本之后失败可闭合文本并保存半段回复；关闭时保留错误结果，不把半段回复转换为成功。含未完成工具调用的流始终失败关闭。 |
+| `models` | 模型条目数组；也可省略 | 省略 | 无单位。省略时显示全部目录模型；空数组隐藏模型选择器中的全部 Codex 模型；非空数组只显示列出的模型。已保存会话仍可按精确模型 ID 解析目录模型。 |
+| `cacheRetention` | `none`、`short` 或 `long` | `short` | 无单位。原样传给 Codex 请求的上下文缓存保留策略；本插件不把这些枚举换算为固定时长。 |
+| `streamIdleTimeoutMs` | 数字，`1` 至 `2147483647`（含边界） | `300000` | 毫秒。只限制等待下一段提供方流数据的空闲时间，不限制消费端处理时间；允许范围内的小数。超时产生 `TIMEOUT`。 |
+| `maxRequestImageBytes` | 正安全整数，`1` 至 `9007199254740991`（含边界） | `20971520` | 字节。限制一次请求累积的 base64 图片载荷；文本、工具、图片描述和 JSON 结构不计入。超过预算时从最旧图片开始以固定文本替代。 |
+| `requestImagePixelBudget` | 正安全整数，`1` 至 `9007199254740991`（含边界） | `4194304` | 像素。每张请求图片的总像素预算，并映射到 attachment 请求的 `maxPixels`。默认值等于 `2048 × 2048`。 |
+| `requestImageMaxBytes` | 正安全整数，`1` 至 `9007199254740991`（含边界） | `1048576` | 原始字节。每张请求图片生成版本的字节预算，并映射到 attachment 请求的 `maxBytes`。默认值为 `1 MiB`。 |
+
+## 模型条目
+
+每个 `models` 条目支持以下字段：
+
+| 键 | 必填 | 类型与范围 | 行为 |
+| --- | --- | --- | --- |
+| `id` | 是 | 字符串 | 必须是当前安装目录中的 Codex 模型 ID；未知或重复 ID 在配置验证时被拒绝。 |
+| `name` | 否 | 字符串 | 覆盖模型显示名称；省略时使用目录名称。 |
+| `contextWindow` | 否 | 正安全整数，`1` 至 `9007199254740991`（含边界） | 覆盖模型上下文窗口。 |
+| `maxTokens` | 否 | 正安全整数，`1` 至 `9007199254740991`（含边界） | 覆盖模型输出上限，并成为未显式指定输出上限时的请求默认值。 |
+
+示例：
+
+```yaml
+models:
+  - id: gpt-5.4
+    name: Codex
+    contextWindow: 272000
+    maxTokens: 128000
+```
+
+模型 ID 与能力随锁定的运行时目录变化。修改前请以设置页面发现的目录为准，不要从示例推断某个 ID 一定可用。
+
+## 校验与生效
+
+- 省略或写成 `null` 的布尔值、枚举、超时和图片限制会回填各自默认值；`models: null` 不表示默认目录，应省略 `models`。
+- 类型错误、未知枚举、超出范围的普通数值、图片限制的小数，以及模型的未知或重复 ID 会在插件加载或设置保存时被拒绝；被拒绝的更新不会替换最后一次有效配置。
+- 只应使用上表列出的有限 JSON/YAML 数值。`NaN`、无穷值和未列出的字段不属于受支持的配置接口。
+- 配置更新从下一次适配器操作生效；正在进行的操作继续使用启动时捕获的不可变配置快照。
+- `/codex` 的 Fast 与传输偏好是当前进程、当前会话的临时状态，不是 bundle 配置键。

package/docs/contribution-sources.en.md

@@ -0,0 +1,35 @@
+# Contribution and licensing rules
+
+[简体中文](contribution-sources.md) | [English](contribution-sources.en.md)
+
+These rules keep the code maintainable, behavior verifiable, and origin and licensing auditable.
+
+## Development requirements
+
+- Production code depends only on exported public APIs and does not import unexported internals from DSH, pi-ai, or another dependency.
+- Behavioral changes include reproducible tests and update the corresponding Chinese and English documentation.
+- Error reports, fixtures, and logs remove tokens, OAuth codes, cookies, credentials, and private conversation content.
+- Code, tests, documentation, and media with unclear origin or licensing are not accepted.
+- Contributions intentionally submitted for inclusion are provided under the project's Apache-2.0 license; contributors must have the right to submit and grant that license.
+- Every new dependency documents its purpose, version, license, runtime permissions, and supply-chain impact.
+- Public-interface changes state their compatibility impact and migration path.
+
+## Review checklist
+
+1. Does the change cover only a clearly stated problem or feature?
+2. Do tests cover the normal path, failure path, and boundary inputs?
+3. Do sign-in, credentials, network, files, and tool side effects retain least privilege?
+4. Does every user-visible behavior have complete Chinese and English documentation?
+5. Are compatibility, known limitations, and acceptance status accurate?
+6. Will new files enter the npm package, and are they required at runtime?
+
+## Repository gates
+
+- `scripts/check-syntax.mjs` checks production-source import boundaries.
+- A strict TypeScript consumer checks public declarations.
+- Language-pair checks verify counterpart files, required markers, and Markdown structure to catch common one-language-only drift.
+- The npm-pack allowlist controls published files.
+- Architecture documents record current module boundaries and verification invariants.
+- `NOTICE` and `THIRD_PARTY_NOTICES.md` record dependencies, interoperability marks, and license information.
+
+See [CONTRIBUTING.en.md](../CONTRIBUTING.en.md) for the complete submission workflow.

package/docs/contribution-sources.md

@@ -0,0 +1,35 @@
+# 贡献与许可规范
+
+[简体中文](contribution-sources.md) | [English](contribution-sources.en.md)
+
+本规范用于保持代码可维护、行为可验证、来源和许可可审计。
+
+## 开发要求
+
+- 生产代码只依赖已导出的公开 API，不引用 DSH、pi-ai 或其他依赖的未导出内部路径；
+- 行为变更必须附带可复现测试，并同步更新相关中英文文档；
+- 错误报告、fixture 和日志必须去除 token、OAuth code、cookie、凭据和私人会话内容；
+- 不提交来源不明或许可不清晰的代码、测试、文档与媒体；
+- 有意提交的贡献按本项目 Apache-2.0 许可证提供；贡献者必须有权提交并授予该许可；
+- 新依赖必须说明用途、版本、许可证、运行权限和供应链影响；
+- 公共接口变更必须说明兼容性影响和迁移方式。
+
+## 评审清单
+
+1. 变更是否只覆盖明确的问题或功能；
+2. 正常路径、错误路径和边界输入是否有测试；
+3. 登录、凭据、网络、文件和工具副作用是否保持最小权限；
+4. 用户可见行为是否有完整的中英文说明；
+5. 兼容性、已知限制和验收状态是否准确；
+6. 新增文件是否会进入 npm 包，是否确实需要发布。
+
+## 仓库门禁
+
+- `scripts/check-syntax.mjs` 检查生产源码的导入边界；
+- 严格 TypeScript consumer 检查公开类型；
+- 中英文配对检查验证对应文件、关键标记和 Markdown 结构，发现常见的单语更新漂移；
+- npm pack 白名单检查控制发布文件；
+- 架构文档记录当前模块边界与验证不变量；
+- `NOTICE` 与 `THIRD_PARTY_NOTICES.md` 记录依赖、互操作标识和许可证信息。
+
+完整提交流程见 [CONTRIBUTING.md](../CONTRIBUTING.md)。

package/docs/github-about.md

@@ -0,0 +1,15 @@
+# GitHub About 与 Topics / GitHub About and topics
+
+## About（中英双语，建议原样填写）
+
+```text
+社区维护的 DeepSeek Harness Codex 插件：OAuth、模型、图片与流式恢复；非官方 / Community Codex plugin for DSH: OAuth, models, images, stream recovery; unofficial.
+```
+
+## Topics
+
+```text
+dsh dsh-plugin deepseek-harness codex chatgpt oauth llm
+```
+
+该文案不超过 GitHub About 的长度限制。除非对应承诺已经有持续证据，否则不要写成“stable”“official”或“fully compatible”。

package/docs/releases/v0.0.1.acceptance.json

@@ -0,0 +1,160 @@
+{
+  "schemaVersion": 3,
+  "version": "0.0.1",
+  "releaseStatus": "approved",
+  "testedCommit": "5d1cedeb3288d22ee2994f0908902e7b825c6704",
+  "approvedBy": "YukiRyou",
+  "approvedAt": "2026-08-29T05:37:44Z",
+  "approvalEvidenceUrl": "https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33236406601",
+  "platforms": {
+    "linux": {
+      "status": "passed",
+      "testedAt": "2026-08-29T05:33:06Z",
+      "runner": "github-hosted-ubuntu-latest-x64",
+      "nodeVersion": "24.19.0",
+      "dshVersion": "0.1.1-rc.2",
+      "profileSmoke": "passed",
+      "evidenceUrl": "https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33236406601/job/99058047865"
+    },
+    "macos": {
+      "status": "passed",
+      "testedAt": "2026-08-29T05:33:13Z",
+      "runner": "github-hosted-macos-latest-arm64",
+      "nodeVersion": "24.18.0",
+      "dshVersion": "0.1.1-rc.2",
+      "profileSmoke": "passed",
+      "evidenceUrl": "https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33236406601/job/99058047873"
+    },
+    "windows": {
+      "status": "passed",
+      "testedAt": "2026-08-29T05:34:53Z",
+      "runner": "github-hosted-windows-latest-x64",
+      "nodeVersion": "24.19.0",
+      "dshVersion": "0.1.1-rc.2",
+      "profileSmoke": "passed",
+      "evidenceUrl": "https://github.com/yoshino-xiao7/dsh-codex/actions/runs/33236406601/job/99058047824"
+    }
+  },
+  "liveAcceptance": {
+    "oauthWebSignIn": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "flowStartedFromSettings": false,
+        "credentialConfigured": false,
+        "postSignInRequestSucceeded": false
+      }
+    },
+    "modelCatalog": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "settingsCatalogVisible": false,
+        "conversationModelSelectable": false
+      }
+    },
+    "textStream": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "nonEmptyTextDelta": false,
+        "terminalStopObserved": false
+      }
+    },
+    "reasoningStream": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "reasoningBlockObserved": false,
+        "terminalStopObserved": false
+      }
+    },
+    "terminalUsage": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "inputTokensObserved": false,
+        "outputTokensObserved": false
+      }
+    },
+    "toolRoundTrip": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "toolCallObserved": false,
+        "toolExecuted": false,
+        "toolResultReturned": false,
+        "followUpSucceeded": false
+      }
+    },
+    "replayContinuity": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "firstTurnSucceeded": false,
+        "secondTurnUsedPriorContext": false,
+        "secondTurnSucceeded": false
+      }
+    },
+    "imageMaxPixels": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "nativeImageAccepted": false,
+        "maxPixels4194304Projected": false,
+        "requestSucceeded": false
+      }
+    },
+    "transportAuto": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "requestSucceeded": false
+      }
+    },
+    "transportSse": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "requestSucceeded": false
+      }
+    },
+    "transportWebsocket": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "requestSucceeded": false
+      }
+    },
+    "transportWebsocketCached": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "firstTurnSucceeded": false,
+        "secondTurnSucceeded": false
+      }
+    },
+    "fastPriority": {
+      "status": "pending",
+      "testedAt": "TBD",
+      "evidenceUrl": "TBD",
+      "assertions": {
+        "priorityRequested": false,
+        "requestSucceeded": false,
+        "noAutomaticDowngrade": false
+      }
+    }
+  }
+}