@kyun.si/codex-polish 0.0.1-beta.3 → 0.0.1-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +21 -1
  2. package/CONTRIBUTING.en.md +6 -6
  3. package/CONTRIBUTING.md +6 -6
  4. package/README.md +34 -64
  5. package/SECURITY.en.md +6 -4
  6. package/SECURITY.md +5 -3
  7. package/docs/README.zh-CN.md +56 -0
  8. package/docs/technical.en.md +66 -44
  9. package/docs/technical.md +62 -38
  10. package/evaluation/README.en.md +1 -1
  11. package/evaluation/README.md +1 -1
  12. package/package.json +1 -2
  13. package/plugins/codex-polish/.codex-plugin/plugin.json +1 -1
  14. package/plugins/codex-polish/hooks/editor_prompt.mjs +51 -0
  15. package/plugins/codex-polish/hooks/history.mjs +107 -66
  16. package/plugins/codex-polish/hooks/preferences.mjs +137 -114
  17. package/plugins/codex-polish/hooks/project_setting.mjs +40 -30
  18. package/plugins/codex-polish/hooks/recovery.mjs +2 -69
  19. package/plugins/codex-polish/hooks/rewrite_mode.mjs +19 -0
  20. package/plugins/codex-polish/skills/codex-polish/SKILL.md +3 -33
  21. package/plugins/codex-polish/skills/codex-polish/WORKFLOW.md +47 -0
  22. package/plugins/codex-polish/skills/codex-polish/references/acp.md +30 -17
  23. package/plugins/codex-polish/skills/codex-polish/references/codex-polish-editor.md +4 -2
  24. package/plugins/codex-polish/skills/codex-polish/scripts/acp_models.mjs +31 -6
  25. package/plugins/codex-polish/skills/codex-polish/scripts/acp_payload.mjs +55 -30
  26. package/plugins/codex-polish/skills/codex-polish/scripts/cli_io.mjs +2 -2
  27. package/plugins/codex-polish/skills/codex-polish/scripts/decisions.mjs +49 -58
  28. package/plugins/codex-polish/skills/codex-polish/scripts/editor_role.mjs +48 -0
  29. package/plugins/codex-polish/skills/codex-polish/scripts/format_reply.mjs +171 -0
  30. package/plugins/codex-polish/skills/codex-polish/scripts/previous_reply.mjs +31 -0
  31. package/plugins/codex-polish/skills/codex-polish/scripts/rewrite_material.mjs +28 -0
  32. package/plugins/codex-polish/skills/codex-polish/scripts/text_guard.mjs +65 -166
  33. package/plugins/codex-polish/skills/codex-polish-setup/SKILL.md +37 -11
  34. package/plugins/codex-polish/skills/codex-polish-setup/references/credentials.en.md +10 -8
  35. package/plugins/codex-polish/skills/codex-polish-setup/references/credentials.md +7 -5
  36. package/scripts/install.mjs +389 -123
  37. package/scripts/native_cache.mjs +5 -5
  38. package/README.en.md +0 -84
package/CHANGELOG.md CHANGED
@@ -1,6 +1,26 @@
1
1
  # 更新记录 / Changelog
2
2
 
3
- [中文使用说明](README.md) · [English README](README.en.md)
3
+ [中文使用说明](docs/README.zh-CN.md) · [English README](README.md)
4
+
5
+ ## 0.0.1-beta.5
6
+
7
+ - The repository and npm beta now open with the English README. The Simplified Chinese guide is linked at the top. Both guides cover first setup, one-time Turbo rewrites, and what each provider receives.
8
+ - 仓库和 npm 测试包默认展示英文 README,顶部可切换至简体中文。两份指南都更新了安装步骤、单次 Turbo 用法和数据发送范围。
9
+
10
+ ## 0.0.1-beta.4
11
+
12
+ - 在普通模式也可以说“这题用 Turbo”或“让 Gemini 重写刚才那条”。单次请求直接走 Gemini,可以附上具体改法。下一条普通提问继续使用项目默认模式。
13
+ - A one-time Turbo request can rewrite the current draft or a specific earlier answer in the same chat. Give Gemini any directions for that rewrite. The next ordinary question uses the project's saved mode.
14
+ - 新增项目改写模式。普通模式(默认)沿用原有流程,Turbo 会跳过 OpenAI,将每份符合条件的草稿直接交给 Gemini,可直接说“切换到 Turbo 模式”或“恢复普通模式”。
15
+ - Projects can now choose a rewrite mode. Normal (default) keeps the existing workflow. Turbo skips OpenAI and sends every eligible draft directly to Gemini. Say “Switch to turbo mode” or “Switch back to normal mode”.
16
+ - OpenAI 风格检查只使用本轮问题、草稿和已设置的自定义润色提示词。历史问答仅在 Gemini 改写时附带,默认最多 2 轮,可选 0 到 10 轮。可以要求本轮不带历史。OpenAI 检查不可用或材料超过该接口限制时,直接交给 Gemini。
17
+ - The OpenAI style check uses only the current question, draft, and any custom polishing prompt. History goes only to Gemini when it rewrites. Projects can choose 0–10 exchanges (default 2), or omit history for one rewrite. When the OpenAI check is unavailable or its input limit is exceeded, the draft goes directly to Gemini.
18
+ - 可以在项目里说“查看润色提示词”“设置润色提示词”或“恢复默认润色提示词”。自定义提示词逐字保存在 `.codex/codex-polish.prompt.md`,供同一项目后续聊天使用。普通和 Turbo 模式都将原文作为 Gemini 的全部编辑指令。可选的 OpenAI 风格检查也会参考它。
19
+ - Projects can show, set, or restore the default polishing prompt in chat. Custom prompts are saved verbatim in `.codex/codex-polish.prompt.md` for future chats in the project. Normal and Turbo both use the saved text as Gemini’s complete editing prompt. The optional OpenAI style check also considers it.
20
+ - Gemini 返回改稿后,在支持折叠的客户端,完整原稿默认收起。点击润色版下方的“查看 GPT 原稿”即可对照。
21
+ - When a rewrite changes the text, clients that support folding show the full draft collapsed. Select “View original GPT draft” below the rewrite to compare.
22
+ - Gemini 和可选的 OpenAI 风格检查现在直接接收本轮问题和草稿原文,包括代码、路径、链接和数值。OpenAI 只在改写前判断草稿是否需要润色。本轮材料含疑似凭据或用户要求固定格式时,插件会在发送前跳过。两种模式收到 Gemini 的完整回复后只做显示排版。Gemini 返回原文时,正文只显示一次。
23
+ - Gemini and the optional OpenAI style check now receive the current question and draft as written, including code, paths, links, and numbers. OpenAI is called only before rewriting to decide whether the draft needs editing. The plugin skips suspected credentials and exact-output requests before sending. Both modes now format Gemini’s complete reply for display. If Gemini returns the original text, it appears once.
4
24
 
5
25
  ## 0.0.1-beta.3
6
26
 
@@ -2,12 +2,12 @@
2
2
 
3
3
  [简体中文](CONTRIBUTING.md)
4
4
 
5
- For installation, see the [project README](README.en.md). For the checks a reply goes through, see the [technical reference](docs/technical.en.md).
5
+ For installation, see the [project README](README.md). For details on when the plugin sends a draft and how it displays the reply, see the [technical reference](docs/technical.en.md).
6
6
 
7
7
  ## Where to Make Changes
8
8
 
9
9
  - `scripts/install.mjs` and the `.command` launchers handle installation, updates, status checks, uninstallation, and local marketplace registration.
10
- - `plugins/codex-polish/` contains the plugin manifest, the `UserPromptSubmit` hook, and two skills. `codex-polish` handles placeholder protection, optional OpenAI Decisions checks, `agy acp` rewrites, and validation. `codex-polish-setup` manages `.codex/codex-polish.*` settings, runtime model discovery, diagnostics, and the [credential guide](plugins/codex-polish/skills/codex-polish-setup/references/credentials.en.md).
10
+ - `plugins/codex-polish/` contains the plugin manifest, the `UserPromptSubmit` hook, and two skills. `codex-polish` checks rewrite eligibility locally, optionally asks OpenAI Decisions whether to edit the draft, runs rewrites through `agy acp`, and formats Gemini’s complete reply for display. `codex-polish-setup` manages `.codex/codex-polish.*` settings, runtime model discovery, diagnostics, and the [credential guide](plugins/codex-polish/skills/codex-polish-setup/references/credentials.en.md).
11
11
  - The full source tree includes the regression suite in `tests/` and the evaluation script and synthetic samples in `evaluation/`. See the [evaluation guide](evaluation/README.en.md).
12
12
  - When updating user-facing prompts or documentation, update both English and Chinese.
13
13
 
@@ -22,7 +22,7 @@ mkdir -p dist
22
22
  npm pack --ignore-scripts --pack-destination dist
23
23
  ```
24
24
 
25
- `npm pack` writes version `0.0.1-beta.3` of `@kyun.si/codex-polish` to `dist/kyun.si-codex-polish-0.0.1-beta.3.tgz`. Default tests need no API key. Native installer tests use a temporary Codex profile. A separate opt-in test makes four billable OpenAI requests. See the [live test instructions](docs/technical.en.md).
25
+ `npm pack` writes version `0.0.1-beta.5` of `@kyun.si/codex-polish` to `dist/kyun.si-codex-polish-0.0.1-beta.5.tgz`. Default tests need no API key. Native installer tests use a temporary Codex profile. The Decisions tests use mock responses to exercise the style check.
26
26
 
27
27
  ## Reporting Bugs
28
28
 
@@ -36,11 +36,11 @@ Open a GitHub pull request with the reason for the change, steps to reproduce or
36
36
 
37
37
  ## Publishing a beta
38
38
 
39
- Set the version in both `package.json` and the plugin manifest to `X.Y.Z-beta.N`. Commit the change and push the matching Git tag. For example, to publish `0.0.1-beta.3`:
39
+ Set the version in both `package.json` and the plugin manifest to `X.Y.Z-beta.N`. Commit the change and push the matching Git tag. For example, to publish `0.0.1-beta.5`:
40
40
 
41
41
  ```sh
42
- git tag v0.0.1-beta.3
43
- git push origin v0.0.1-beta.3
42
+ git tag v0.0.1-beta.5
43
+ git push origin v0.0.1-beta.5
44
44
  ```
45
45
 
46
46
  GitHub Actions tests the tagged code, publishes the package to npm with the `beta` tag, and creates a GitHub prerelease. If a step fails, run the publishing workflow again from the Actions tab and enter the existing tag.
package/CONTRIBUTING.md CHANGED
@@ -2,12 +2,12 @@
2
2
 
3
3
  [English](CONTRIBUTING.en.md)
4
4
 
5
- 安装和使用请看[项目说明](README.md)。改动插件前,可以先查[技术参考](docs/technical.md),了解一次改写经过哪些检查。
5
+ 安装和使用请看[项目说明](docs/README.zh-CN.md)。改动插件前,可以先查[技术参考](docs/technical.md),了解插件何时发送草稿、如何显示回复。
6
6
 
7
7
  ## 改哪里
8
8
 
9
9
  - `scripts/install.mjs` 和两个 `.command` 启动脚本负责安装、更新、环境检查和卸载。
10
- - `plugins/codex-polish/` 里有插件清单、钩子和两个技能。`codex-polish` 负责改写与校验,`codex-polish-setup` 负责设置、选择模型和检查环境。改动用户提示时,请一起更新中英文。
10
+ - `plugins/codex-polish/` 里有插件清单、钩子和两个技能。`codex-polish` 通过可选的 OpenAI 风格检查判断是否需要润色,经 ACP 把草稿交给 Gemini,并排版显示完整回复。`codex-polish-setup` 负责设置、选择模型和检查环境,详见[首次配置与登录指南](plugins/codex-polish/skills/codex-polish-setup/references/credentials.md)。改动用户提示或文档时,请同步更新中英文。
11
11
  - 完整源码的 `tests/` 放回归测试,`evaluation/` 放评测脚本和合成样本。[评测说明](evaluation/README.md)
12
12
 
13
13
  ## 本地测试与打包
@@ -21,7 +21,7 @@ mkdir -p dist
21
21
  npm pack --ignore-scripts --pack-destination dist
22
22
  ```
23
23
 
24
- `npm pack` 会把 `@kyun.si/codex-polish` 的 `0.0.1-beta.3` 版打包为 `dist/kyun.si-codex-polish-0.0.1-beta.3.tgz`。默认测试无需 API 密钥,原生安装测试会使用临时 Codex 配置。另有一项在线测试需要显式开启,会向 OpenAI 发出四次付费请求。[运行在线检查](docs/technical.md)
24
+ `npm pack` 会把 `@kyun.si/codex-polish` 的 `0.0.1-beta.5` 版打包为 `dist/kyun.si-codex-polish-0.0.1-beta.5.tgz`。默认测试无需 API 密钥,原生安装测试会使用临时 Codex 配置。Decisions 测试使用模拟响应验证风格判定。
25
25
 
26
26
  ## 反馈问题
27
27
 
@@ -35,11 +35,11 @@ npm pack --ignore-scripts --pack-destination dist
35
35
 
36
36
  ## 发布 beta
37
37
 
38
- 将 `package.json` 和插件清单中的版本一同改为 `X.Y.Z-beta.N`,提交后推送同名 Git 标签。例如发布 `0.0.1-beta.3` 时运行:
38
+ 将 `package.json` 和插件清单中的版本一同改为 `X.Y.Z-beta.N`,提交后推送同名 Git 标签。例如发布 `0.0.1-beta.5` 时运行:
39
39
 
40
40
  ```sh
41
- git tag v0.0.1-beta.3
42
- git push origin v0.0.1-beta.3
41
+ git tag v0.0.1-beta.5
42
+ git push origin v0.0.1-beta.5
43
43
  ```
44
44
 
45
45
  GitHub Actions 会测试这个标签的代码,将安装包发布到 npm 的 `beta` 标签,并创建 GitHub 预发布版。如果某一步失败,可以在 Actions 中选择发布工作流,用已有标签重试。
package/README.md CHANGED
@@ -1,86 +1,56 @@
1
- # Codex Polish · Codex 回复润色
1
+ # Codex Polish
2
2
 
3
- **简体中文** | [English](README.en.md)
3
+ **English** | [简体中文](docs/README.zh-CN.md)
4
4
 
5
- Codex Polish 通过 Antigravity 的 `agy acp` 请 Gemini 润色 Codex 的最终回复。采用改稿时,聊天里会先显示 Gemini 润色版,再显示完整的 GPT 原稿,方便逐句对照。项目默认使用自动模式,信任插件的 hook 并新开聊天后,像平常一样提问即可触发。
5
+ Codex Polish lets Gemini rewrite a Codex reply so it’s easier to read. Codex sends its draft through Antigravity (`agy acp`) and shows the rewrite in chat. In clients that support folding, you can expand the original underneath. Here’s an example translated from a Chinese test run.
6
6
 
7
- ## 改写示例
7
+ **Polished by Gemini**
8
8
 
9
- 一次测试里,Codex 要告诉用户导出按钮修好了,本地测过了,线上还没验。
9
+ The export button is fixed and passed local tests. It still needs to be checked in production.
10
10
 
11
- **Gemini 润色版**
11
+ <details>
12
+ <summary>View original GPT draft</summary>
12
13
 
13
- 导出按钮目前已经修复,本地测试也已通过,不过线上还没有验证。
14
+ Regarding progress with the export button fix, let me explain the actual situation. The export button has now been fixed, local tests have passed, and production verification has not yet been done.
14
15
 
15
- **GPT 原稿**
16
+ </details>
16
17
 
17
- 关于导出按钮的修复进度,这里向你说明一下实际情况。目前导出按钮已经修复,本地测试已经通过,线上还没有验证。
18
+ If Gemini returns the original wording, you see it once. If the rewrite fails, you get the draft and a short explanation.
18
19
 
19
- 这轮只想看改稿,可以说 **“只给我润色后的正文”**。如果指定只输出 JSON、命令或逐字引文,回复会遵守指定格式。
20
+ ## Quick start
20
21
 
21
- ## 三步快速开始
22
+ Requires **macOS or Linux**, **Node.js 22.16+**, a [Codex CLI](https://developers.openai.com/codex/cli/) with plugin support, and `agy` 1.2.1+. No API key is needed—it reuses your Antigravity sign-in.
22
23
 
23
- 支持 macOS 和 Linux。需要 Node.js 22.16 或更新版本,以及支持插件的 [Codex CLI](https://developers.openai.com/codex/cli/)。如果你用 T3 Code,选择 Codex 后端,并把插件装在运行该后端的机器上。
24
+ ```sh
25
+ npx @kyun.si/codex-polish@beta setup
26
+ ```
24
27
 
25
- 1. **安装插件。** 用下面的命令安装 npm 上的测试版。
28
+ Run the command in your project directory. Interactive setup offers to install `agy` if needed and lets you choose a rewrite mode. With the built-in prompt, **Normal** (default) can keep a clear draft as written. **Turbo** asks Gemini to rewrite each eligible draft. With T3 Code, select the Codex backend and install the plugin on the machine running it. [Other installation options](docs/technical.en.md#installation-updates-and-uninstall)
26
29
 
27
- ```sh
28
- npx @kyun.si/codex-polish@beta setup
29
- ```
30
+ - **Before trusting the hook:** Ask **“Why does a cache hit still take time? Use Turbo for this answer.”** Codex sends the draft to Gemini once, without attaching earlier exchanges.
31
+ - **Automatic mode (default):** Trust `UserPromptSubmit` in Codex **Settings → Hooks** (`/hooks` in the CLI) and start a **new chat**. Codex then runs the polishing workflow on ordinary questions and can include recent exchanges.
30
32
 
31
- 也可以下载源码,运行仓库里的安装脚本。
33
+ ## Useful chat prompts
32
34
 
33
- ```sh
34
- git clone https://github.com/mreasonyang/codex-polish.git
35
- cd codex-polish
36
- node scripts/install.mjs setup
37
- ```
35
+ - **“Have Gemini rewrite your last answer in two sentences.”** One-time Turbo skips the OpenAI check and rewrites the answer you picked. You can also name an earlier answer in the same chat. The next ordinary question uses your project default.
36
+ - **“Only polish when I ask.”** Sets the project to manual. **“Make Turbo the default for this project”** changes how it rewrites. **“Only show the polished text”** hides the comparison for one reply.
37
+ - **Model and prompt:** Defaults to **Gemini 4 Hydrogen** (`gemini-4-hydrogen`). Say **“Choose a rewrite model”** for live account models, or **“Set this project’s polishing prompt to: Lead with the conclusion. Use short sentences.”** (`.codex/codex-polish.prompt.md`).
38
38
 
39
- 在 macOS 上也可以下载并解压 GitHub 仓库,在项目根目录双击[安装回复润色.command](安装回复润色.command)。
39
+ ## Privacy and checks
40
40
 
41
- 2. **连接 Gemini。** 安装器会复用已有的 Antigravity CLI(`agy` 1.2.1 或更新版本)。如果没装,按回车即可安装官方版本。无人值守安装时,在上述 `setup` 命令末尾加上 `--install-agy`。插件默认沿用 Antigravity 登录。只有收到登录提示时,才需要在运行 Codex 的机器上打开 `agy` 登录。
42
- 3. **信任 hook,试一次普通提问。** 自动润色会将符合条件的问题和草稿发给 Google,默认最多附带最近 2 轮完整问答。在 Codex 的 **设置 → Hooks**(CLI 输入 `/hooks`)里信任本插件的 `UserPromptSubmit`,然后在项目里新开聊天,问 **“用一句话解释 DNS。”** 想改成手动,可以在项目里说 **“只在我要求时润色”**。
41
+ If the draft or question contains a suspected credential, Codex Polish skips that rewrite. If you ask for JSON only, a single command, or a verbatim quote, you get the requested format without a polishing label.
43
42
 
44
- ## 项目设置
43
+ - **OpenAI** receives the current question, draft and any custom prompt only when the optional Normal-mode style check runs. With no `OPENAI_API_KEY`, with the check off, or if it’s unavailable, eligible drafts go directly to Gemini. Turbo always skips the check.
44
+ - **Google** receives the selected draft, its original question, any custom prompt, and any directions you gave for this rewrite. With a trusted hook, the plugin includes up to two completed exchanges from before that answer by default. Set history to 0–10 exchanges or say **“Leave out history this time.”** The plugin keeps no draft log of its own.
45
45
 
46
- 直接对 Codex 说 **“查看回复润色设置”** 就能看到当前配置。每个项目单独保存,在同一项目新开的聊天也会沿用。
46
+ ## Maintenance
47
47
 
48
- | 设置 | 默认值 | 可以这样说 |
49
- | --- | --- | --- |
50
- | 什么时候润色 | 自动(需信任 hook) | “只在我要求时润色”“关闭回复润色”“给这个项目开启自动润色” |
51
- | Gemini 模型 | Gemini 4 Hydrogen | “选择改写模型”会列出当前账号可用的模型,也可以说“恢复默认改写模型” |
52
- | 带几轮历史 | 最近 2 轮 | “带最近 5 轮对话”“润色时不带历史”。一轮是之前的一个问题和对应的最终回复,可选 0 到 10 轮,历史正文合计最多 16 KiB |
53
- | OpenAI 检查 | 配了 `OPENAI_API_KEY` 时启用 | “这个项目只用 Gemini 改写”“有密钥时用 OpenAI 检查” |
54
- | 插件提示语言 | 自动识别中英文 | “插件提示改成中文”“恢复自动识别语言”。改稿始终沿用草稿的语言 |
48
+ | Action | Command |
49
+ | --- | --- |
50
+ | Check setup | `npx @kyun.si/codex-polish@beta doctor` |
51
+ | Update | `npx @kyun.si/codex-polish@beta update` |
52
+ | Uninstall | `npx @kyun.si/codex-polish@beta uninstall` |
55
53
 
56
- 没有 OpenAI 密钥也能用,符合条件的草稿会直接交给 Gemini。有密钥且启用了检查时,OpenAI 会先判断草稿是否值得润色,改完再核对原意。如果密钥无效,插件会保留原稿。可以修正或清除密钥,也可以把这个项目设为只用 Gemini。
54
+ `doctor` checks local dependencies, project settings and hook trust. Ask **“Choose a rewrite model”** to check your Antigravity sign-in and see the available models. After an update, Codex may ask you to trust the hook again.
57
55
 
58
- ## 谁会收到对话内容
59
-
60
- 自动模式下,受信任的 `UserPromptSubmit` 会在普通提问时提醒 Codex 润色最终回复。信任前,仍可说 **“把这轮回复润色一下”**,仅发送本轮材料。手动模式只在点名时触发,附带历史同样需要信任 hook。关闭后,即使点名也会跳过润色。
61
-
62
- 每次润色,Google 都会收到当前问题和草稿,其中的代码、命令、路径、链接和数值会先替换成占位符,普通文字仍可读。附带的历史则按原文发送,可能包含代码。插件会跳过检测到凭据、带附件或回复不完整的历史轮次。启用检查时,OpenAI 只会收到经过占位符处理的本轮材料,最后一次检查还会收到候选改稿。插件本身不记录草稿。Codex、服务商和全局 `agy` 钩子各有自己的日志设置。
63
-
64
- ## 为什么还是原稿?
65
-
66
- 如果 Gemini 返回的文字和原稿相同,回复会注明 Gemini 已返回原文,正文只显示一次。如果在发送前跳过、请求未完成或改稿没通过检查,回复会说明本轮实际情况,并附上 GPT 原稿。需要排查时,可以问 **“为什么上条回复没润色?”** 或 **“检查回复润色环境”**。
67
-
68
- ## 检查、更新与卸载
69
-
70
- | 操作 | 通过 npm 测试版 | 在源码根目录运行 |
71
- | --- | --- | --- |
72
- | 检查当前项目 | `npx @kyun.si/codex-polish@beta doctor` | `node scripts/install.mjs doctor` |
73
- | 更新 | `npx @kyun.si/codex-polish@beta update` | 取得新版源码后运行 `node scripts/install.mjs update` |
74
- | 卸载 | `npx @kyun.si/codex-polish@beta uninstall` | `node scripts/install.mjs uninstall` |
75
-
76
- 更新会保留已保存的项目模式和插件启用状态。此前未设置模式的项目也会采用默认的自动模式。升级后新开一个聊天。如果 Codex 提示钩子内容已变更,请重新审查并信任。卸载后,项目的 `.codex` 设置和共用的 `agy` 会保留。
77
-
78
- ## 文档与许可
79
-
80
- - [凭据与登录](plugins/codex-polish/skills/codex-polish-setup/references/credentials.md)
81
- - [技术说明与验证范围](docs/technical.md) · [如何评估润色效果](evaluation/README.md)
82
- - [贡献指南](CONTRIBUTING.md)
83
- - [安全问题反馈](SECURITY.md)
84
- - [更新记录](CHANGELOG.md)
85
-
86
- 本项目采用 [Apache License 2.0](LICENSE)。
56
+ [Credentials Guide](plugins/codex-polish/skills/codex-polish-setup/references/credentials.en.md) · [Technical Reference](docs/technical.en.md) · [Evaluation](evaluation/README.en.md) · [Contributing](CONTRIBUTING.en.md) · [Security](SECURITY.en.md) · [Changelog](CHANGELOG.md) · [Apache-2.0 License](LICENSE)
package/SECURITY.en.md CHANGED
@@ -1,17 +1,19 @@
1
1
  # Security
2
2
 
3
- [简体中文](SECURITY.md) · [README](README.en.md) · [Technical reference](docs/technical.en.md)
3
+ [简体中文](SECURITY.md) · [README](README.md) · [Technical reference](docs/technical.en.md)
4
4
 
5
5
  ## Report a vulnerability privately
6
6
 
7
7
  Please [report vulnerabilities privately on GitHub](https://github.com/mreasonyang/codex-polish/security/advisories/new). The maintainer can follow up with you in the report.
8
8
 
9
- Include the plugin version, steps to reproduce the issue, what you expected, and what happened. Add relevant details such as your operating system, the versions of Node.js, Codex CLI, and `agy`, or the status of a project setting or hook. Use a fictional exchange and placeholder values in your example. Remove keys, tokens, authorization headers, and private conversation text.
9
+ Include the plugin version, steps to reproduce the issue, what you expected, and what happened. Add relevant details such as your operating system, the versions of Node.js, Codex CLI, and `agy`, or the status of a project setting or hook. Use a fictional exchange and made-up values in your example. Remove keys, tokens, authorization headers, and private conversation text.
10
10
 
11
11
  ## Control what the plugin sends
12
12
 
13
+ When the optional style check runs in Normal mode, OpenAI receives only the current question and draft as written (including code, paths, and links) and any custom polishing prompt. Turbo, including a one-time Turbo request, skips OpenAI and calls Gemini through `agy acp`. Google receives the selected reply’s question and draft, any custom project prompt, and any directions you give for that Turbo rewrite. Optional history comes from before the selected reply. The default is up to 2 exchanges, configurable from 0 to 10. The plugin skips incomplete exchanges and those containing attachments or possible credentials. A possible credential in the rewrite material causes the plugin to skip the turn before sharing it. Once Gemini returns a complete reply, the plugin formats it locally for display.
14
+
13
15
  - To stop future rewrite requests in the current project, set `.codex/codex-polish.mode` to `off`.
14
- - To keep rewriting but send only the current turn to Google, set `.codex/codex-polish.history-turns` to `0`.
15
- - To turn off the plugin’s OpenAI checks, set `.codex/codex-polish.decisions` to `off`.
16
+ - To omit additional exchanges, set `.codex/codex-polish.history-turns` to `0` or say “Leave out history this time.” You can still request a rewrite of an earlier answer. The trusted hook stores the transcript location and turn locally so the plugin can retrieve that question and reply.
17
+ - To turn off the OpenAI style check, set `.codex/codex-polish.decisions` to `off`.
16
18
 
17
19
  If a key or token may have been exposed, revoke it with the provider and replace it wherever it is configured.
package/SECURITY.md CHANGED
@@ -1,17 +1,19 @@
1
1
  # 安全说明
2
2
 
3
- [English](SECURITY.en.md) · [使用说明](README.md) · [技术说明](docs/technical.md)
3
+ [English](SECURITY.en.md) · [使用说明](docs/README.zh-CN.md) · [技术说明](docs/technical.md)
4
4
 
5
5
  ## 私下报告漏洞
6
6
 
7
7
  如发现安全漏洞,请[私下提交漏洞报告](https://github.com/mreasonyang/codex-polish/security/advisories/new)。维护者可以在同一份报告里与你跟进。
8
8
 
9
- 在报告中写明插件版本、复现步骤、预期结果和实际结果。视问题补充操作系统、Node.js、Codex CLI 或 `agy` 的版本,以及相关的项目设置或钩子状态。请用虚构的对话和占位符演示问题,并删去密钥、令牌、认证头和私人对话原文。
9
+ 在报告中写明插件版本、复现步骤、预期结果和实际结果。视问题补充操作系统、Node.js、Codex CLI 或 `agy` 的版本,以及相关的项目设置或钩子状态。请用虚构的对话和示例值演示问题,并删去密钥、令牌、认证头和私人对话原文。
10
10
 
11
11
  ## 控制插件发送的内容
12
12
 
13
+ 普通模式启用风格检查时,OpenAI 只收到本轮问题和草稿原文(包括代码、路径和链接),以及已设置的自定义润色提示词。Turbo(含单次 Turbo)跳过 OpenAI,通过 `agy acp` 调用 Gemini。Google 收到待改回复对应的问题、草稿、自定义润色提示词(如有),以及你为这次 Turbo 改写提出的要求。可选历史取自目标回复之前,默认最多 2 轮,可设为 0 到 10 轮。带附件、含疑似凭据或尚未完成的历史轮次会被跳过。改写材料含疑似凭据时,插件在发送前跳过整轮。收到 Gemini 的完整回复后,插件在本地排版并显示正文。
14
+
13
15
  - 要停止当前项目后续的改写请求,将 `.codex/codex-polish.mode` 设为 `off`。
14
- - 要继续改写,但只向 Google 发送本轮内容,将 `.codex/codex-polish.history-turns` 设为 `0`。
16
+ - 要让 Gemini 省略附带的历史问答,将 `.codex/codex-polish.history-turns` 设为 `0`,或说“这次润色不带历史”。这时仍可点名重写之前的某条回复。受信任的 hook 会在本机保存会话位置与轮次,插件据此取得你选中的原问题和答复。
15
17
  - 要关闭插件的 OpenAI 检查,将 `.codex/codex-polish.decisions` 设为 `off`。
16
18
 
17
19
  如果密钥或令牌可能已经泄露,请到相应服务商处撤销受影响的凭据,并在使用它的配置中换用新凭据。
@@ -0,0 +1,56 @@
1
+ # Codex Polish · Codex 回复润色
2
+
3
+ [English](../README.md) | **简体中文**
4
+
5
+ Codex 的回答太绕时,可以让 Gemini 换个说法。Codex 通过 Antigravity(`agy acp`)发送原稿,在聊天里显示改写后的版本。支持折叠的客户端还可以点开原稿对照。下面是一次实际改写。
6
+
7
+ **Gemini 润色版**
8
+
9
+ 导出按钮目前已经修复,本地测试也已通过,不过线上还没有验证。
10
+
11
+ <details>
12
+ <summary>查看 GPT 原稿</summary>
13
+
14
+ 关于导出按钮的修复进度,这里向你说明一下实际情况。目前导出按钮已经修复,本地测试已经通过,线上还没有验证。
15
+
16
+ </details>
17
+
18
+ Gemini 返回原文时,正文只显示一次。改写失败时,你会看到原稿和原因。
19
+
20
+ ## 快速开始
21
+
22
+ 支持 **macOS 和 Linux**,需要 **Node.js 22.16+**、支持插件的 [Codex CLI](https://developers.openai.com/codex/cli/),以及 `agy` 1.2.1+。无需配置 API 密钥,直接复用本机已有的 Antigravity 登录。
23
+
24
+ ```sh
25
+ npx @kyun.si/codex-polish@beta setup
26
+ ```
27
+
28
+ 在项目目录运行上面的命令。交互安装时,如果缺少 `agy`,安装器会提示安装,也会让你选择改写模式,默认是**普通(Normal)**。使用内置提示词时,普通模式允许保留已经写清楚的原稿,**Turbo** 会要求 Gemini 改写每份符合条件的草稿。如果用 T3 Code,选择 Codex 后端,并在运行后端的机器上安装插件。[其他安装方式](technical.md#安装更新和卸载)
29
+
30
+ - **信任 hook 前手动试用:** 试试 **“为什么缓存命中了还要等?这条用 Turbo。”** 这次会直接把草稿交给 Gemini,不附带以前的问答。
31
+ - **自动模式(默认):** 在 Codex **设置 → Hooks**(CLI 输入 `/hooks`)中信任 `UserPromptSubmit` 并**新开聊天**。之后照常提问就会触发润色流程,也可以附上最近几轮对话。
32
+
33
+ ## 常用聊天指令
34
+
35
+ - **“让 Gemini 把上一条改成两句话。”** 这次会跳过 OpenAI 检查,直接改写指定的答复。也可以说“重写前面讲缓存的那条”。下一条普通提问仍然用项目原来的模式。
36
+ - **“只在我要求时润色。”** 这会把项目设为手动触发。想让项目以后默认用 Turbo,可以说“把这个项目的默认改写模式设成 Turbo”。只想看本轮改稿,就说“只给我润色后的正文”。
37
+ - **自定义模型与提示词:** 默认使用 **Gemini 4 Hydrogen**(`gemini-4-hydrogen`)。可说 **“选择改写模型”** 查询账号实时可用模型,或说 **“把这个项目的润色提示词设为:先写结论。尽量用短句。”**(保存在 `.codex/codex-polish.prompt.md`)。
38
+
39
+ ## 隐私与检查机制
40
+
41
+ 问题或草稿里有疑似密钥时,插件会跳过这次改写。要求只输出 JSON、一条命令或逐字引文时,回复会保留指定格式,不加润色标题。
42
+
43
+ - **OpenAI** 只在普通模式启用风格检查时收到本轮问题、草稿和项目自定义提示词。没配 `OPENAI_API_KEY`、关闭检查,或检查服务不可用时,符合条件的草稿会直接发给 Gemini。Turbo 总是跳过这项检查。
44
+ - **Google** 收到选中的草稿、它所回答的问题、项目自定义提示词,以及你为这次改写提出的要求。信任 hook 后,默认还会附上目标答复之前最多两轮完整问答。历史可设为 0 到 10 轮,也可以说“这次不带历史”。插件自身不记录草稿日志。
45
+
46
+ ## 维护与排查
47
+
48
+ | 操作 | 命令 |
49
+ | --- | --- |
50
+ | 检查配置 | `npx @kyun.si/codex-polish@beta doctor` |
51
+ | 更新 | `npx @kyun.si/codex-polish@beta update` |
52
+ | 卸载 | `npx @kyun.si/codex-polish@beta uninstall` |
53
+
54
+ `doctor` 检查本机依赖、项目设置和 hook 信任状态。要确认 Antigravity 登录是否可用,可以说 **“选择改写模型”**,查看账号当前能用的模型。插件更新后,Codex 可能提示你重新信任 hook。
55
+
56
+ [凭据与配置指南](../plugins/codex-polish/skills/codex-polish-setup/references/credentials.md) · [技术参考](technical.md) · [离线评测](../evaluation/README.md) · [参与贡献](../CONTRIBUTING.md) · [安全说明](../SECURITY.md) · [更新记录](../CHANGELOG.md) · [Apache-2.0 许可证](../LICENSE)
@@ -1,77 +1,97 @@
1
1
  # Codex Polish Technical Reference
2
2
 
3
- [简体中文](technical.md) · [Overview](../README.en.md)
3
+ [简体中文](technical.md) · [Overview](../README.md)
4
4
 
5
- Codex Polish `0.0.1-beta.3` is a Codex plugin for macOS and Linux. Its local scripts use built-in Node.js modules and require Node.js 22.16 or newer. The [rewrite skill](../plugins/codex-polish/skills/codex-polish/SKILL.md) polishes eligible final replies. The [setup skill](../plugins/codex-polish/skills/codex-polish-setup/SKILL.md) checks the environment and manages project settings.
5
+ Codex Polish `0.0.1-beta.5` is a Codex plugin for macOS and Linux. Its local scripts use built-in Node.js modules and require Node.js 22.16 or newer. The automatic hook directs Codex to follow the [polishing workflow](../plugins/codex-polish/skills/codex-polish/WORKFLOW.md) once the draft is ready and show the result in the final reply. Explicit requests use the same workflow through the [rewrite skill](../plugins/codex-polish/skills/codex-polish/SKILL.md). The [setup skill](../plugins/codex-polish/skills/codex-polish-setup/SKILL.md) checks the environment and manages project settings.
6
6
 
7
- ## Project Settings and Inheritance
7
+ ## Project Settings
8
8
 
9
- Each project stores its settings as individual files inside `.codex`. The plugin looks up each file independently, starting in the working directory where the turn began. The closest file wins. The search includes the first directory containing `.git` and stops there. If it reaches the user's home directory or the filesystem root first, it stops before reading settings there.
9
+ Settings live in the nearest Git repository’s root .codex directory. All directories in the same repository use those settings. Nested repositories and linked worktrees have their own settings. Outside Git, settings belong to the chosen folder.
10
10
 
11
11
  | File | Values and Default | Behavior |
12
12
  | --- | --- | --- |
13
13
  | `.codex/codex-polish.mode` | `auto` (default), `manual`, `off` | Without a saved mode, the project uses `auto`. The trusted hook triggers polishing for ordinary questions. `manual` runs only on explicit requests. `off` skips rewrites even when requested. |
14
- | `.codex/codex-polish.model` | Model ID, default `gemini-4-hydrogen` (Gemini 4 Hydrogen) | Stores the per-project Gemini model discovered from the signed-in Antigravity account over ACP. |
15
- | `.codex/codex-polish.history-turns` | Integer `0`–`10`, default `2` | Maximum completed exchanges to attach. Use `0` for the current turn only. Saving a value above `10` returns an error. An invalid or out-of-range setting disables history. Changes apply on the next rewrite. |
16
- | `.codex/codex-polish.decisions` | `auto` (default), `off` | `auto` uses `OPENAI_API_KEY` to determine whether to run OpenAI’s style and meaning checks. `off` uses ACP only. This setting is independent of the trigger mode. |
17
- | `.codex/codex-polish.language` | `auto` (default), `zh`, `en` | Sets the language for plugin prompts and setup checks. Polished replies always stay in the draft's own language. |
14
+ | `.codex/codex-polish.rewrite-mode` | `normal` (default), `turbo` | Once polishing is triggered, normal uses the saved Decisions setting. Turbo sends each eligible draft directly to Gemini. |
15
+ | `.codex/codex-polish.model` | Model ID, default `gemini-4-hydrogen` (Gemini 4 Hydrogen) | The model picker lists models from the signed-in Antigravity account without sending a draft or history. If the saved model becomes unavailable, that rewrite keeps the original draft. |
16
+ | `.codex/codex-polish.prompt.md` | UTF-8 text, defaults to the active mode’s built-in prompt | Custom text takes effect on the next rewrite and carries over to new chats in the same project. |
17
+ | `.codex/codex-polish.history-turns` | Integer `0`–`10`, default `2` | Maximum completed exchanges to attach to a Gemini rewrite. Use `0` to omit earlier exchanges. Saving a value above `10` returns an error. An invalid or out-of-range setting disables history. Changes apply on the next rewrite. |
18
+ | `.codex/codex-polish.decisions` | `auto` (default), `off` | In normal mode, `auto` enables the OpenAI style check when `OPENAI_API_KEY` is set. `off` uses ACP only. This setting is independent of the trigger mode. |
19
+ | `.codex/codex-polish.language` | `auto` (default), `zh`, `en` | Sets the language for plugin prompts and setup checks. |
20
+
21
+ Say “Switch to turbo mode” or “Switch back to normal mode” to save the project preference. From a source checkout, run `node plugins/codex-polish/hooks/preferences.mjs set-rewrite-mode turbo --cwd /path/to/project`. Use `normal` to switch back. The `check --cwd /path/to/project` command reports the effective `rewrite_mode`. An invalid value pauses polishing locally until you save either mode.
22
+
23
+ “Use Turbo for this answer” applies to the current draft. “Have Gemini rewrite the answer about caching” uses Turbo on the selected earlier reply in the same chat. Codex interprets the request in context. A question like “What does Turbo do?” asks for an explanation. A one-time rewrite uses `--trigger turbo`, goes directly to ACP, and expires after the reply. Saving the project default takes a separate request. Explicit requests work in `manual` mode and are skipped in `off` mode.
18
24
 
19
25
  When `.codex/codex-polish.language` is `auto`, chat prompts match the user's current message, falling back to the established chat language and then the system locale. Short replies such as menu numbers use the chat language. Terminal checks and the installer check the project setting first, then the system locale, and default to English.
20
26
 
27
+ ### Show, set, or restore the polishing prompt
28
+
29
+ In chat, say “Show the polishing prompt”, “Set this project's polishing prompt to: Lead with the conclusion, then give the evidence”, or “Restore the default polishing prompt”. You can also run these commands locally from the root of a source checkout. Replace `/path/to/project` with the target project directory. The setter saves standard input verbatim, including line breaks and surrounding spaces. The reader returns the effective `text` and its `source` (`default` or `custom`). With no custom prompt, it returns the built-in text for the active rewrite mode. With a custom prompt, the returned `text` is the complete editing prompt for Gemini in both Normal and Turbo. The role file’s header configures the ACP session and tool access. Its body contains only that text.
30
+
31
+ ```sh
32
+ node plugins/codex-polish/hooks/preferences.mjs prompt --cwd /path/to/project
33
+ node plugins/codex-polish/hooks/preferences.mjs set-prompt --cwd /path/to/project < my-prompt.md
34
+ node plugins/codex-polish/hooks/preferences.mjs set-prompt --reset --cwd /path/to/project
35
+ ```
36
+
37
+ You can edit the prompt file directly. Restoring the default removes the project prompt. Invalid UTF-8, whitespace-only contents, display controls or a suspected credential prevent polishing until the file is corrected or reset.
38
+
21
39
  ## Rewrite Routes, Stages, and Thresholds
22
40
 
23
- - **Direct ACP.** When `OPENAI_API_KEY` is missing, empty, or entirely whitespace, the plugin uses Gemini alone. Setting `codex-polish.decisions` to `off` has the same effect. Every eligible draft that passes local checks goes to Gemini, even if it already reads well.
24
- - **OpenAI Decisions and ACP.** With `codex-polish.decisions` set to `auto` and a nonblank key, the plugin checks the key’s format locally before contacting OpenAI. It asks `gpt-6-luna` whether to rewrite and, if a changed candidate passes local checks, whether the meaning was preserved. [Decisions API](https://developers.openai.com/api/reference/resources/decisions/methods/create)
41
+ - **Direct ACP.** Turbo always uses this route, even with an OpenAI key. Its built-in prompt asks Gemini to actively rewrite each eligible draft. In normal mode, when `OPENAI_API_KEY` is missing, empty, or entirely whitespace, the plugin uses Gemini alone. Setting `codex-polish.decisions` to `off` has the same effect. Every eligible draft that passes local checks goes to Gemini, even if it already reads well.
42
+ - **OpenAI Decisions and ACP.** In normal mode with `codex-polish.decisions` set to `auto` and a nonblank key, the plugin checks the key’s format locally before contacting OpenAI. It sends one request to `gpt-6-luna` to decide whether the draft needs editing. [Decisions API](https://developers.openai.com/api/reference/resources/decisions/methods/create)
25
43
 
26
- | Stage | Passing Condition |
44
+ | Stage | Behavior |
27
45
  | --- | --- |
28
- | 1. Text protection | Drafts with detected credentials, explicit exact-output requests, or unsupported structures return the original draft immediately. Code blocks, inline commands, links, citations, file paths, and numbers with units are replaced with turn-specific and source-specific literal placeholders. |
29
- | 2. Style check | Direct ACP proceeds immediately. With Decisions enabled, the protected current question and draft must score `P(needs rewrite) >= 0.80`. |
30
- | 3. ACP rewrite | The agent launches `agy acp` in a temporary workspace under a dedicated editor role, opens a session with the configured Antigravity identity, reads the live model list, and verifies the project model. It rejects tool permission requests and requires a complete `end_turn` matching the request ID. |
31
- | 4. Placeholder check | Every placeholder must appear in its original order. After restoring protected spans, the script verifies fixed tokens, numbers, units, and supported Markdown structures. |
32
- | 5. Meaning check and delivery | Direct ACP accepts the rewrite after local checks. With Decisions enabled, a changed candidate must also score `P(substantive change) <= 0.05` in the meaning check. Any stage failure returns the original draft, and user cancellation ends the turn. |
46
+ | 1. Local input checks | The plugin skips polishing if it detects a possible credential in the current question or draft, the user requests exact output such as JSON only, or the draft has an unsupported structure. |
47
+ | 2. Style check | Direct ACP proceeds after local checks. With Decisions enabled, OpenAI considers only the current question, draft, and any custom polishing prompt. Gemini rewrites when `P(needs rewrite) > 0.50`. |
48
+ | 3. ACP rewrite | Gemini loads the project’s effective prompt from the body of the editor role. The agent launches `agy acp` in a temporary workspace under a dedicated editor role, opens a session with the configured Antigravity identity, reads the live model list, and checks the project settings and selected model before sending. It rejects tool permission requests and collects only reply text from this session. The reply is ready to display once the agent has nonempty text and an `end_turn` matching the request ID. |
49
+ | 4. Display | Both modes format Gemini’s complete reply for display. The formatter ignores outer whitespace and line-ending differences when deciding whether to show one or both versions. |
33
50
 
34
- During a rewrite, `agy` connects to Google. The plugin's Node.js scripts contact a provider only for the optional OpenAI Decisions checks. The current Codex agent starts and cleans up the ACP process, selects the model, and exchanges protocol messages. [ACP operating instructions](../plugins/codex-polish/skills/codex-polish/references/acp.md)
51
+ During a rewrite, `agy` connects to Google. The plugin's Node.js scripts contact a provider only for the optional OpenAI style check. The current Codex agent starts and cleans up the ACP process, selects the model, and exchanges protocol messages. [ACP operating instructions](../plugins/codex-polish/skills/codex-polish/references/acp.md)
35
52
 
36
53
  The plugin requires the official Antigravity CLI 1.2.1 or later. By default it reuses the existing Antigravity sign-in on the machine and OS account running Codex. To use an AI Studio key or an enterprise identity, set `CODEX_POLISH_AGY_AUTH` to `gemini-api-key` or `agent-platform`, respectively. [Sign-in guide](../plugins/codex-polish/skills/codex-polish-setup/references/credentials.en.md) · [Google ACP authentication](https://antigravity.google/docs/ide/extensions/acp)
37
54
 
38
55
  ## What Appears in the Final Reply
39
56
 
40
- When Codex adopts a rewrite, it uses ordinary Markdown labels within one final chat message. **Polished by Gemini** introduces the accepted text with protected details restored. **Original GPT draft** introduces the complete draft from before polishing. Both bodies appear verbatim.
57
+ When Gemini returns a changed reply, the final message starts with **Polished by Gemini**. In the Codex app, select “View original GPT draft” below the rewrite to expand the full draft. Select it again to collapse it. Drafts retain their Markdown formatting. When a draft contains disclosure tags or container delimiters, the expanded view shows its Markdown source so you can read those markers verbatim.
58
+
59
+ For a selected passage or a previous Gemini version, the comparison is labeled **View original text**. Only the selected text and its question are used, along with any editing directions. Additional conversation history is omitted.
41
60
 
42
- If Gemini returns identical text, the reply says it left the draft unchanged and shows the text once. A skip before sending, an incomplete request, or a rejected rewrite gets a brief status based on what happened, followed only by the original. Asking for “only the polished text” gives you just the selected body. Requests for plain JSON, a single command, or other exact output receive the requested content without labels or status.
61
+ If Gemini returns identical text, the reply says it left the draft unchanged and shows the text once. If polishing is skipped before sending or the ACP request ends without a complete reply, the status explains what happened and the reply shows the original. Asking for “only the polished text” shows just Gemini’s text when the rewrite completes. Requests for plain JSON, a single command, or other exact output receive the requested content without labels or status.
62
+
63
+ When a visualization reference loses its delimiters in the ACP reply and unambiguously matches a reference in the draft, the formatter restores the delimiters. The formatter still displays Gemini’s reply if a reference changes or disappears. New visualization markers with no match in the draft appear as text.
43
64
 
44
65
  ## Outgoing Content, Hooks, and Limits
45
66
 
46
67
  For automatic polishing, trust the plugin's `UserPromptSubmit` hook in Codex (**Settings → Hooks** or `/hooks` in the CLI), then start a fresh chat. Explicit requests to polish the current question and draft work without the hook in both automatic and manual mode. Including earlier exchanges requires the trusted hook in either mode. [Codex plugins](https://developers.openai.com/plugins/build/plugins) · [Codex hooks](https://learn.chatgpt.com/docs/hooks#where-codex-looks-for-hooks)
47
68
 
48
- The hook records which transcript belongs to the current turn. Local Node.js code reads the exchanges directly from that transcript. If the hook is untrusted, the matching transcript is unavailable, no eligible history can be read, or the user limits sharing to the current turn, the plugin can still send the current question and draft alone. One exchange consists of the user's prompt (including follow-up messages within that turn) and Codex's final reply, excluding progress updates and tool output. The current question and draft are sent alongside history and do not count toward `.codex/codex-polish.history-turns`.
69
+ When the OpenAI style check runs, the plugin sends only the current `question`, `draft`, and any custom `editor_prompt` in `input_json.data`. Gemini receives the `question` and `draft` for the reply being rewritten and optional `history`. If the user gives editing directions for a one-time Turbo rewrite, the plugin includes them in `rewrite_request`. The Antigravity editor role supplies any custom project prompt. The question, draft, and history are sent as written, including code, commands, paths, links, quotations, and numbers.
70
+
71
+ The trusted hook records the transcript location and current turn locally so a user can select an earlier reply for rewriting. This record holds only metadata, even when history is set to zero. For an earlier rewrite, `question` and `draft` come from the same turn. If that turn showed both versions, the plugin uses the folded GPT draft. When the target is unclear or unavailable, Codex asks the user to identify it or supply the text.
72
+
73
+ Optional `history` comes from before the selected reply and is sent in chronological order. An exchange consists of a user prompt (including follow-up messages within that turn) and Codex's final reply. The plugin skips progress updates, tool output, incomplete exchanges, and exchanges with detected credentials or attachments. The target question and draft do not count toward the limit of 0–10 exchanges (default 2). With history at zero, an untrusted hook, no usable history, or a request to omit history for this rewrite, the ACP message omits `history`.
49
74
 
50
- - **Sent to Google over ACP.** Each rewrite sends a single ACP prompt containing the placeholder-protected current question and draft, plus up to the configured number of completed exchanges within a `16 KiB` total history cap. The reader scans up to the last 4 MiB of transcript, gives recent exchanges priority within the UTF-8 byte budget, and sends them in chronological order. It skips incomplete turns and turns with detected credentials or attachments. Earlier exchanges are sent with their original text and code. The current turn’s placeholders protect fixed tokens. The provider can still read ordinary prose. Opening the model menu in setup only queries available models and never sends drafts or history.
51
- - **Sent to OpenAI Decisions.** Only the placeholder-protected current question and draft (plus the candidate rewrite during the second check) are sent. Conversation history is never sent to OpenAI.
75
+ OpenAI caps each `input_json.data` at 256 KiB of compact UTF-8 JSON, 32 container levels, and 10,000 values. The plugin puts the current turn’s style check material in one such field and asks one predicate question. Oversized inputs go directly to Gemini in full. The `gpt-6-luna` model card separately lists a context window of 1,050,000 tokens. [Decisions API reference](https://developers.openai.com/api/reference/resources/decisions/methods/create) · [GPT-6 Luna model card](https://developers.openai.com/api/docs/models/gpt-6-luna)
76
+
77
+ On the Gemini API, the default `gemini-4-hydrogen` model shares a 1,048,576-token window across input, thinking, and output. On Antigravity, session overhead and the selected model also matter. For example, Antigravity lists a window of up to 512K tokens for Gemini 4 Neon. Google’s ACP documentation gives no exact byte limit for a Hydrogen rewrite prompt. Starting in version 1.5.8, `agy` reports context-window usage when it opens a session or changes models. [Hydrogen model card](https://aistudio.google.com/docs/models/gemini-4-hydrogen) · [Antigravity models](https://antigravity.google/docs/models#gemini-4-neon) · [Antigravity CLI 1.5.8](https://github.com/google-antigravity/antigravity-cli/releases/tag/1.5.8)
52
78
 
53
79
  The plugin never invokes `agy -p` and writes no draft logs of its own. Codex session logs and provider logs follow their own settings ([Google FAQ](https://antigravity.google/docs/faq)). The dedicated Antigravity editor role disables built-in tools ([Antigravity CLI 1.2.1](https://github.com/google-antigravity/antigravity-cli/releases/tag/1.2.1)), though global Antigravity hooks configured on the machine may still run.
54
80
 
55
- ## Failure Classes and Cooldowns
81
+ ## Handling failures
56
82
 
57
83
  | Failure Class | Handling |
58
84
  | --- | --- |
59
- | Locally malformed key, unsupported auth mode, missing `agy`, or unavailable Node.js or host process tools | The plugin keeps the draft locally. With Decisions enabled, a nonblank key containing whitespace, non-ASCII characters, or nonprintable characters fails local checks. Correct or clear the key, or set the project’s Decisions mode to `off`. The plugin looks for `agy` in `PATH`, then in `~/.local/bin`. |
60
- | Decisions network error, timeout, rate limit, quota failure, auth error, malformed JSON, or content refusal | Each request has a 10-second deadline. A key can pass the local format check and still receive HTTP 401 or 403 from OpenAI. Errors return the original draft and may trigger the cooldowns below. A content refusal affects only the current turn. |
85
+ | Unsupported Google authentication, missing agy, Node.js or host process tools | Keep the original. The plugin looks for agy in PATH and ~/.local/bin. |
86
+ | Decisions unavailable, key invalid, response invalid, or input exceeds the provider limit | Continue to Gemini after local checks. Each turn makes its own routing decision. |
61
87
  | ACP startup failure, auth failure, missing selected model, or mid-stream model switch | The agent aborts the rewrite, terminates the process, and delivers the original draft. |
62
- | ACP stall, truncated stream, or mismatched `end_turn` request ID | Each control request has a 10-second deadline. During generation, the agent stops after 30 seconds without valid progress for this session, or 90 seconds after process startup. Cleanup can take up to 3 additional seconds. The agent discards incomplete output without replaying the request. |
63
- | Modified numbers or units, dropped code, control characters, suspected credentials, or failed meaning check | Discards the entire candidate rewrite and delivers the original draft. |
88
+ | Slow or interrupted generation | Wait while the ACP process is running. On an explicit timeout, cancellation, disconnect or truncated result, discard incomplete output. A request is sent at most once. |
64
89
  | Project disabled mid-turn, updated user instructions, or cancellation | Re-checks project mode before sending text out. The agent discards the old candidate on new instructions. User cancellation ends the turn. If only the server cancels while the user waits, the plugin returns the original draft. |
65
90
 
66
- In automatic mode, service errors pause automatic rewrites for the current project within the active Codex profile.
67
-
68
- - **60-second cooldown.** Triggered by connection failures, timeouts, rate limits, or transient service errors.
69
- - **5-minute cooldown.** Triggered by authentication failures, explicit OpenAI quota exhaustion, or an unavailable selected Gemini model.
70
-
71
- Exact-format skips, content refusals, and failed draft validation do not trigger a cooldown. Cooldown records store only a scope hash, a fixed error code, a timestamp, and a random token. An explicit request in a later turn can retry during a cooldown. If the cache is unavailable, a failed rewrite still returns the original draft. Saying `"Check Codex Polish setup"` shows missing dependencies and any active cooldown timer, while `"Test ACP connection"` runs a standalone handshake without sending a draft.
72
-
73
91
  ## Verification Status
74
92
 
93
+ In a live local test, a synthetic conversation had 10 earlier exchanges totaling 16 KiB and a saved custom polishing prompt. OpenAI received one request with just `question`, `draft`, and `editor_prompt` as evidence, and returned HTTP 200. Gemini 4 Hydrogen then received all 10 exchanges over ACP and completed the rewrite.
94
+
75
95
  Run the offline test suite and synthetic report from the root of a full source checkout. The release archive ships both language versions of the evaluation guide. The test scripts, report generator, and sample data are available in the source checkout.
76
96
 
77
97
  ```sh
@@ -79,26 +99,28 @@ npm test
79
99
  node evaluation/report.mjs evaluation/example.jsonl
80
100
  ```
81
101
 
82
- The separate live meaning check makes four billable OpenAI Decisions requests to `gpt-6-luna`. It tests one faithful rewrite and one factual reversal in each of English and Chinese. The default suite skips it. To run it, set `OPENAI_API_KEY` in your terminal and opt in explicitly.
83
-
84
- ```sh
85
- CODEX_POLISH_TEST_LIVE_DECISIONS=1 node --test --test-name-pattern='live fidelity' tests/decisions.test.mjs
86
- ```
102
+ The Decisions tests use mock OpenAI responses to exercise the style threshold and API error handling. A simulated ACP server covers model changes, permission requests, interrupted replies and mixed session messages. The installer tests use a temporary Codex profile to install the packed archive, check hook registration, update the plugin and uninstall it.
87
103
 
88
104
  ### Verified on macOS
89
105
 
90
- Using Node.js 22.16 and Antigravity CLI 1.5.12, the Codex agent selected `gemini-4-hydrogen` over ACP and requested a rewrite. The reply passed local validation and retained the distinction between passing local tests and unverified production behavior. The test environment had no Python on PATH and no OpenAI key. The Node.js helpers made no network requests.
106
+ Using Node.js 22.16 and Antigravity CLI 1.5.12, the Codex agent selected `gemini-4-hydrogen` over ACP and requested a rewrite. The reply reported that local tests passed and production verification was still pending. The test environment had no Python on PATH and no OpenAI key. The Node.js helpers made no network requests.
107
+
108
+ In a T3 Code chat using the Codex backend, a one-time Turbo request rewrote the preceding visible answer through Gemini 4 Hydrogen. The delivered message contained the rewrite and the original draft.
91
109
 
92
110
  ### Checks still open
93
111
 
94
- - Verify a complete rewrite in the T3 chat interface. Exercise both routes with authorized, de-identified samples. Compare the tool trace with the selected model, completed output, and process cleanup. Check the status and section order in the native final message and again after reopening the chat. Compare each displayed body with its source.
95
- - Run Chinese drafts over 4 KiB in two chats simultaneously and check that each keeps its own text, placeholders, and session ID. Check fallback for an unavailable model, a permission request, cancellation, and a truncated stream.
112
+ - Exercise the Normal route in T3 Code both with and without Decisions, using authorized, de-identified samples. Compare the tool trace with the selected model, completed output, and process cleanup. Check the status and section order in the native final message and again after reopening the chat. In clients that support folding, verify that a new reply starts with the draft collapsed. Expand it and compare each body with its source.
113
+ - Run Chinese drafts over 4 KiB in two chats simultaneously and check that each keeps its own text and session ID. Check fallback for an unavailable model, a permission request, cancellation, and a truncated stream.
96
114
  - Collect at least 200 delivered real samples across the calibration and blind splits. Use the blind split to measure preference rates, severe fact reversals, missed workflows, verbatim display match, and end-to-end latency. Current thresholds are initial defaults, and `evaluation/example.jsonl` contains synthetic records (`demo_only`). See the [evaluation specification](../evaluation/README.en.md) and [contribution guide](../CONTRIBUTING.en.md).
97
115
 
98
116
  ## Installation, Updates, and Uninstall
99
117
 
100
- Once the beta is published to npm, install it with `npx @kyun.si/codex-polish@beta setup`. Replace `setup` with `update` to upgrade, `doctor` to check the current project, or `uninstall` to remove the plugin. For a source installation, run `node scripts/install.mjs setup` from the root of the GitHub checkout. The same subcommands work there. [Quick Start](../README.en.md#quick-start)
118
+ Install the published npm beta with `npx @kyun.si/codex-polish@beta setup`. Replace `setup` with `update` to upgrade, `doctor` to check the current project, or `uninstall` to remove the plugin. For a source installation, run `node scripts/install.mjs setup` from the root of the GitHub checkout. The same subcommands work there. [Quick Start](../README.md#quick-start)
119
+
120
+ For a Finder install on macOS, extract the repository archive and double-click [Install Codex Polish.command](../Install%20Codex%20Polish.command). Select the project you want to configure when prompted.
101
121
 
102
122
  Both `setup` and `update` accept `--install-agy` to install the Google CLI when needed. Updates preserve `.codex` project settings and the plugin’s enabled state. Re-running `update` with the same version replaces the build or recovers an interrupted update.
103
123
 
104
- If you packed version `0.0.1-beta.3` locally, you can also run `npx --yes file:./kyun.si-codex-polish-0.0.1-beta.3.tgz uninstall` in the directory containing the archive. Uninstall removes the plugin and its marketplace, clears cooldowns and session pointers for the active Codex profile, and prints the backup path for any manually edited installation files. It keeps shared `agy` binaries and project `.codex` files.
124
+ The installer registers one local marketplace per Codex profile. Updates stage a verified snapshot, atomically switch the marketplace manifest to the new snapshot and refresh the native plugin cache. If the refresh fails, the installer restores the previous snapshot and enabled state. Codex checks the installed plugin’s contents when deciding hook trust. An update to a bundled prompt or setup guide can therefore require a new approval even when the hook command is unchanged. The installer and `doctor` read the current status from `hooks/list`.
125
+
126
+ If you packed version `0.0.1-beta.5` locally, you can also run `npx --yes file:./kyun.si-codex-polish-0.0.1-beta.5.tgz uninstall` in the directory containing the archive. Uninstall removes the plugin and its marketplace, clears session pointers for the active Codex profile, and prints the backup path for any manually edited installation files. It keeps shared `agy` binaries and project `.codex` files.