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

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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  [中文使用说明](README.md) · [English README](README.en.md)
4
4
 
5
+ ## 0.0.1-beta.3
6
+
7
+ - 聊天里先显示 Gemini 润色版,再附上完整的 GPT 原稿。Gemini 返回原文时会注明,正文只显示一次。跳过或失败时会说明原因并保留原稿。可以单独要求只看润色后的正文。
8
+ - Replies show the Gemini rewrite followed by the complete original GPT draft. An unchanged reply appears once with a review label. If polishing skips or fails, the reply identifies the outcome and shows the original. You can ask for just the polished text.
9
+
10
+ ## 0.0.1-beta.2
11
+
12
+ - 项目没有指定润色模式时,普通提问也会自动触发润色。使用前,在 Codex 中信任插件的 `UserPromptSubmit` 钩子。已选“只在我要求时”或“关闭”的项目会沿用该选择。
13
+ - Projects without a saved mode now polish ordinary replies automatically once the `UserPromptSubmit` hook is trusted. Projects set to on-demand or off keep their preference.
14
+
5
15
  ## 0.0.1-beta.1
6
16
 
7
17
  ### 简体中文
@@ -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.1` of `@kyun.si/codex-polish` to `dist/kyun.si-codex-polish-0.0.1-beta.1.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.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).
26
26
 
27
27
  ## Reporting Bugs
28
28
 
@@ -34,14 +34,15 @@ Report security vulnerabilities privately. [Security policy](SECURITY.en.md)
34
34
 
35
35
  Open a GitHub pull request with the reason for the change, steps to reproduce or verify it, and results from the tests you ran. For changes involving a provider, say whether you used a mock or a live account. Use synthetic samples or authorized, de-identified material. The project uses the [Apache License 2.0](LICENSE).
36
36
 
37
- ## Publishing to npm
37
+ ## Publishing a beta
38
38
 
39
- For the first release, a maintainer with publish access to `@kyun.si` must sign in to npm, test and pack the project as shown above, then publish the tarball manually from the repository root.
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`:
40
40
 
41
41
  ```sh
42
- npm publish ./dist/kyun.si-codex-polish-0.0.1-beta.1.tgz --tag beta --access public
42
+ git tag v0.0.1-beta.3
43
+ git push origin v0.0.1-beta.3
43
44
  ```
44
45
 
45
- After the first publish succeeds, add a GitHub trusted publisher in the npm package settings. Select `mreasonyang/codex-polish` and enter `publish.yml` as the workflow filename. [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
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.
46
47
 
47
- For subsequent betas, use a Git tag of the form `vX.Y.Z-beta.N`. For example, after updating the package version to `0.0.1-beta.2`, create a GitHub Release for tag `v0.0.1-beta.2` and select **Set as a pre-release**. The workflow checks the version, runs the tests, and publishes with the npm `beta` tag. Reserve `latest` for stable releases.
48
+ npm grants publishing access per package. Configure this package’s trusted publisher for the `mreasonyang/codex-polish` repository and the `publish.yml` workflow, and enable **Allow npm publish** and **Allow npm dist-tag**. Tag access lets the workflow remove `latest` if npm sets it on the first beta. GitHub authenticates the workflow to npm on each release without a stored npm token. [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
package/CONTRIBUTING.md CHANGED
@@ -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.1` 版打包为 `dist/kyun.si-codex-polish-0.0.1-beta.1.tgz`。默认测试无需 API 密钥,原生安装测试会使用临时 Codex 配置。另有一项在线测试需要显式开启,会向 OpenAI 发出四次付费请求。[运行在线检查](docs/technical.md)
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)
25
25
 
26
26
  ## 反馈问题
27
27
 
@@ -33,14 +33,15 @@ npm pack --ignore-scripts --pack-destination dist
33
33
 
34
34
  请通过 GitHub Pull Request 提交改动,附上改动原因、复现或验证方法,以及实际跑过的测试结果。如果改动涉及 Gemini 或 OpenAI,写明用的是模拟服务还是真实账号。测试样本请使用虚构内容,或已获授权且脱敏的材料。本项目采用 [Apache License 2.0](LICENSE)。
35
35
 
36
- ## 发布到 npm
36
+ ## 发布 beta
37
37
 
38
- 首次发布时,拥有 `@kyun.si` 发布权限的维护者需登录 npm,完成上面的测试和打包,然后在源码根目录手动发布该压缩包。
38
+ 将 `package.json` 和插件清单中的版本一同改为 `X.Y.Z-beta.N`,提交后推送同名 Git 标签。例如发布 `0.0.1-beta.3` 时运行:
39
39
 
40
40
  ```sh
41
- npm publish ./dist/kyun.si-codex-polish-0.0.1-beta.1.tgz --tag beta --access public
41
+ git tag v0.0.1-beta.3
42
+ git push origin v0.0.1-beta.3
42
43
  ```
43
44
 
44
- 首次发布成功后,在 npm 包设置中为 GitHub 仓库 `mreasonyang/codex-polish` 添加可信发布者,工作流文件名填写 `publish.yml`。[npm 可信发布设置](https://docs.npmjs.com/trusted-publishers/)
45
+ GitHub Actions 会测试这个标签的代码,将安装包发布到 npm 的 `beta` 标签,并创建 GitHub 预发布版。如果某一步失败,可以在 Actions 中选择发布工作流,用已有标签重试。
45
46
 
46
- 后续测试版使用 `vX.Y.Z-beta.N` 格式的 Git 标签。比如将包版本更新为 `0.0.1-beta.2` 后,在 GitHub 上用标签 `v0.0.1-beta.2` 创建 Release,勾选 **Set as a pre-release**。工作流会核对版本、运行测试,再发布到 npm 的 `beta` 标签。`latest` 留给正式版。
47
+ npm 按包授权。此包使用 GitHub 仓库 `mreasonyang/codex-polish` 的 `publish.yml` 工作流,可信发布者勾选 **Allow npm publish** 和 **Allow npm dist-tag**。后一项让工作流在 npm 把首个 beta 同时标记为 `latest` 时自动清理标签。发布时 GitHub 会向 npm 证明工作流身份,仓库无需保存 npm 令牌。[npm 可信发布设置](https://docs.npmjs.com/trusted-publishers/)
package/README.en.md CHANGED
@@ -2,24 +2,31 @@
2
2
 
3
3
  **English** | **[简体中文](README.md)**
4
4
 
5
- Ask Codex to polish a reply and it sends the draft to Gemini through Antigravity’s `agy acp`. If the rewrite fails a check, you get the original. By default, it runs only when you ask.
5
+ Codex Polish uses Gemini through Antigravity’s `agy acp` to polish Codex’s final replies. When you get a rewrite, the chat shows Gemini’s version first, followed by the full original GPT draft for comparison. Projects default to automatic mode. Once you trust the plugin hook and start a new chat, ordinary questions trigger polishing.
6
6
 
7
7
  In one test, Codex had to report that the export button was fixed and had passed local tests. A production check was still pending. Both texts below are translated from that test.
8
8
 
9
- - **Draft** “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.”
10
- - **After** “The export button is fixed and passed local tests. It still needs to be checked in production.”
9
+ **Polished by Gemini**
10
+
11
+ The export button is fixed and passed local tests. It still needs to be checked in production.
12
+
13
+ **Original GPT draft**
14
+
15
+ 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.
16
+
17
+ To see just the rewrite for one reply, say **“Only show the polished text.”** If you ask for plain JSON, a command, or a verbatim quotation, the reply keeps that exact format.
11
18
 
12
19
  ## Quick Start
13
20
 
14
21
  You need macOS or Linux, Node.js 22.16+, and a [Codex CLI](https://developers.openai.com/codex/cli/) with plugin support. In T3 Code, select Codex and install the plugin on the machine running that backend.
15
22
 
16
- 1. **Install the plugin.** The first beta is `0.0.1-beta.1`. Once it is published to npm, use this command to install the version tagged `beta`.
23
+ 1. **Install the plugin.** Use this command to install the beta from npm.
17
24
 
18
25
  ```sh
19
26
  npx @kyun.si/codex-polish@beta setup
20
27
  ```
21
28
 
22
- You can also install directly from the GitHub source, even before the first npm release.
29
+ You can also clone the repository and run the installer locally.
23
30
 
24
31
  ```sh
25
32
  git clone https://github.com/mreasonyang/codex-polish.git
@@ -30,7 +37,7 @@ You need macOS or Linux, Node.js 22.16+, and a [Codex CLI](https://developers.op
30
37
  On macOS, you can also download and extract the GitHub repository, then double-click [Install Codex Polish.command](Install%20Codex%20Polish.command) in its root folder.
31
38
 
32
39
  2. **Connect Gemini.** Setup reuses the Antigravity CLI (`agy` 1.2.1+) if it finds it. If it offers to install the official CLI, press Enter to accept. For unattended installation, add `--install-agy` to either `setup` command above. Your existing Antigravity sign-in works over ACP. If asked to sign in, run `agy` on the machine that runs Codex.
33
- 3. **Try it.** Start a new project chat and ask **"Explain what DNS does in one sentence, then polish your reply."** Click **Setup** or say **"Set up Codex Polish"** to check your setup.
40
+ 3. **Trust the hook and try an ordinary question.** Automatic polishing sends eligible questions and drafts to Google, with up to two completed exchanges by default. In Codex **Settings → Hooks** (`/hooks` in the CLI), trust the plugin’s `UserPromptSubmit` hook. Start a new chat in your project and ask **“Explain what DNS does in one sentence.”** To switch the project to manual mode, say **“Only polish when I ask.”**
34
41
 
35
42
  ## Project Settings
36
43
 
@@ -38,7 +45,7 @@ Settings are saved in each project’s `.codex/` directory and carry over to new
38
45
 
39
46
  | Setting | Default | Natural prompt |
40
47
  | --- | --- | --- |
41
- | Mode | Manual (when asked) | "Polish automatically in this project", "Only polish when I ask", or "Turn off Codex Polish" |
48
+ | Mode | Automatic (requires a trusted hook) | "Only polish when I ask", "Turn off Codex Polish", or "Polish automatically in this project" |
42
49
  | Gemini model | Gemini 4 Hydrogen | "Choose a rewrite model" (lists runtime account options, which can differ) or "Restore the default rewrite model" |
43
50
  | History turns | Up to 2 earlier question-and-answer pairs | "Include the last 5 exchanges" or "Don't include any conversation history when polishing replies" (`0` to `10`, max 16 KiB) |
44
51
  | OpenAI checks | On when `OPENAI_API_KEY` is set | "Use Gemini only" or "Use OpenAI checks when a key is available" |
@@ -48,13 +55,13 @@ Without `OPENAI_API_KEY`, eligible drafts go straight to ACP. With OpenAI checks
48
55
 
49
56
  ## Privacy and Hooks
50
57
 
51
- Manual rewrites of the current question and draft need no hook. Automatic mode requires trusting `UserPromptSubmit` in Codex (`/hooks` or **Settings → Hooks**) and enabling automatic mode for the project. That hook is also required to include history, even in manual mode. Start a fresh chat after trusting the hook.
58
+ In automatic mode, the trusted `UserPromptSubmit` hook reminds Codex to polish the final reply to an ordinary question. Before trusting the hook, you can still say **“Polish this reply”** to share just the current question and draft. In manual mode, only explicit requests trigger polishing. Including history still requires the trusted hook. Turning polishing off skips even explicit requests.
52
59
 
53
60
  For a rewrite, Google receives your current question and reply draft. The plugin replaces fixed details such as commands, paths, links, and numbers with placeholders. Ordinary prose is still readable. If history is enabled and available, Google also receives earlier exchanges as written, including code. The plugin skips turns with detected secrets, attachments, or incomplete output. OpenAI checks use only the protected current question and draft, plus the proposed rewrite for the final check. The plugin writes no draft logs of its own. Codex, your providers, and any global `agy` hooks have their own settings.
54
61
 
55
62
  ## If a Reply Stays Unchanged
56
63
 
57
- Exact-output requests, already clear drafts when OpenAI checks are active, missing models, or failed checks keep the original draft. Say **"Check Codex Polish setup"** to inspect `agy` and cooldowns, **"Choose a rewrite model"** to verify model access, or **"Why wasn't my last reply polished?"** for the turn's reason.
64
+ If Gemini returns the same text, the reply says it left the draft unchanged and shows the text once. If polishing was skipped before sending the draft, the request failed to finish, or the rewrite failed a check, the reply says what happened and shows the original GPT draft. Ask **“Why wasn’t my last reply polished?”** for that turn’s reason, or **“Check Codex Polish setup”** to troubleshoot the connection.
58
65
 
59
66
  ## Check, Update, or Uninstall
60
67
 
@@ -64,7 +71,7 @@ Exact-output requests, already clear drafts when OpenAI checks are active, missi
64
71
  | Update | `npx @kyun.si/codex-polish@beta update` | Get the latest source, then run `node scripts/install.mjs update` |
65
72
  | Uninstall | `npx @kyun.si/codex-polish@beta uninstall` | `node scripts/install.mjs uninstall` |
66
73
 
67
- Updates preserve your project settings and the plugin’s enabled state. Start a new chat after upgrading, and review the updated hook if Codex prompts you. Uninstalling keeps your `.codex` project settings and shared `agy` binary.
74
+ Updates preserve saved project modes and the plugin’s enabled state. Projects with no saved mode also pick up the automatic default. Start a new chat after upgrading, and review the updated hook if Codex prompts you. Uninstalling keeps your `.codex` project settings and shared `agy` binary.
68
75
 
69
76
  ## References and License
70
77
 
package/README.md CHANGED
@@ -2,26 +2,33 @@
2
2
 
3
3
  **简体中文** | [English](README.en.md)
4
4
 
5
- 在 Codex 里说一句「把这段回复润色一下」,Codex 就会通过 Antigravity 的 `agy acp` 请 Gemini 改写草稿。默认只在你点名时运行。改写失败或检查没通过,你看到的还是原稿。
5
+ Codex Polish 通过 Antigravity 的 `agy acp` 请 Gemini 润色 Codex 的最终回复。采用改稿时,聊天里会先显示 Gemini 润色版,再显示完整的 GPT 原稿,方便逐句对照。项目默认使用自动模式,信任插件的 hook 并新开聊天后,像平常一样提问即可触发。
6
6
 
7
7
  ## 改写示例
8
8
 
9
9
  一次测试里,Codex 要告诉用户导出按钮修好了,本地测过了,线上还没验。
10
10
 
11
- - **原稿** “关于导出按钮的修复进度,这里向你说明一下实际情况。目前导出按钮已经修复,本地测试已经通过,线上还没有验证。”
12
- - **改写后** “导出按钮目前已经修复,本地测试也已通过,不过线上还没有验证。”
11
+ **Gemini 润色版**
12
+
13
+ 导出按钮目前已经修复,本地测试也已通过,不过线上还没有验证。
14
+
15
+ **GPT 原稿**
16
+
17
+ 关于导出按钮的修复进度,这里向你说明一下实际情况。目前导出按钮已经修复,本地测试已经通过,线上还没有验证。
18
+
19
+ 这轮只想看改稿,可以说 **“只给我润色后的正文”**。如果指定只输出 JSON、命令或逐字引文,回复会遵守指定格式。
13
20
 
14
21
  ## 三步快速开始
15
22
 
16
23
  支持 macOS 和 Linux。需要 Node.js 22.16 或更新版本,以及支持插件的 [Codex CLI](https://developers.openai.com/codex/cli/)。如果你用 T3 Code,选择 Codex 后端,并把插件装在运行该后端的机器上。
17
24
 
18
- 1. **安装插件。** 首个测试版为 `0.0.1-beta.1`。发布到 npm 后,可用以下命令安装 `beta` 标签对应的版本。
25
+ 1. **安装插件。** 用下面的命令安装 npm 上的测试版。
19
26
 
20
27
  ```sh
21
28
  npx @kyun.si/codex-polish@beta setup
22
29
  ```
23
30
 
24
- 也可以直接从 GitHub 源码安装,包括在 npm 首次发布之前。
31
+ 也可以下载源码,运行仓库里的安装脚本。
25
32
 
26
33
  ```sh
27
34
  git clone https://github.com/mreasonyang/codex-polish.git
@@ -32,7 +39,7 @@
32
39
  在 macOS 上也可以下载并解压 GitHub 仓库,在项目根目录双击[安装回复润色.command](安装回复润色.command)。
33
40
 
34
41
  2. **连接 Gemini。** 安装器会复用已有的 Antigravity CLI(`agy` 1.2.1 或更新版本)。如果没装,按回车即可安装官方版本。无人值守安装时,在上述 `setup` 命令末尾加上 `--install-agy`。插件默认沿用 Antigravity 登录。只有收到登录提示时,才需要在运行 Codex 的机器上打开 `agy` 登录。
35
- 3. **试着润色一句话。** 在项目里新开聊天,发 **“用一句话解释 DNS,再把你的回复润色一下。”** 想检查配置时,点击 **Setup** 或说 **“配置回复润色”**。
42
+ 3. **信任 hook,试一次普通提问。** 自动润色会将符合条件的问题和草稿发给 Google,默认最多附带最近 2 轮完整问答。在 Codex 的 **设置 → Hooks**(CLI 输入 `/hooks`)里信任本插件的 `UserPromptSubmit`,然后在项目里新开聊天,问 **“用一句话解释 DNS。”** 想改成手动,可以在项目里说 **“只在我要求时润色”**。
36
43
 
37
44
  ## 项目设置
38
45
 
@@ -40,7 +47,7 @@
40
47
 
41
48
  | 设置 | 默认值 | 可以这样说 |
42
49
  | --- | --- | --- |
43
- | 什么时候润色 | 只在点名时 | “给这个项目开启自动润色”“只在我要求时润色”“关闭回复润色” |
50
+ | 什么时候润色 | 自动(需信任 hook) | “只在我要求时润色”“关闭回复润色”“给这个项目开启自动润色” |
44
51
  | Gemini 模型 | Gemini 4 Hydrogen | “选择改写模型”会列出当前账号可用的模型,也可以说“恢复默认改写模型” |
45
52
  | 带几轮历史 | 最近 2 轮 | “带最近 5 轮对话”“润色时不带历史”。一轮是之前的一个问题和对应的最终回复,可选 0 到 10 轮,历史正文合计最多 16 KiB |
46
53
  | OpenAI 检查 | 配了 `OPENAI_API_KEY` 时启用 | “这个项目只用 Gemini 改写”“有密钥时用 OpenAI 检查” |
@@ -50,13 +57,13 @@
50
57
 
51
58
  ## 谁会收到对话内容
52
59
 
53
- 手动润色当前问答可以直接用。要让 Gemini 参考历史,或开启自动润色,需要在 Codex 的 `/hooks` 或 **设置 → Hooks** 里信任 `UserPromptSubmit`,再开一个新聊天。要自动润色,还需要为项目开启自动模式。
60
+ 自动模式下,受信任的 `UserPromptSubmit` 会在普通提问时提醒 Codex 润色最终回复。信任前,仍可说 **“把这轮回复润色一下”**,仅发送本轮材料。手动模式只在点名时触发,附带历史同样需要信任 hook。关闭后,即使点名也会跳过润色。
54
61
 
55
62
  每次润色,Google 都会收到当前问题和草稿,其中的代码、命令、路径、链接和数值会先替换成占位符,普通文字仍可读。附带的历史则按原文发送,可能包含代码。插件会跳过检测到凭据、带附件或回复不完整的历史轮次。启用检查时,OpenAI 只会收到经过占位符处理的本轮材料,最后一次检查还会收到候选改稿。插件本身不记录草稿。Codex、服务商和全局 `agy` 钩子各有自己的日志设置。
56
63
 
57
64
  ## 为什么还是原稿?
58
65
 
59
- 如果要求原样输出、OpenAI 判断原稿已经够清楚、所选模型不可用,或改稿没通过校验,插件都会保留原稿。可以问 **“为什么上条回复没润色?”** 查看本轮原因,或说 **“检查回复润色环境”** 排查安装与连接。
66
+ 如果 Gemini 返回的文字和原稿相同,回复会注明 Gemini 已返回原文,正文只显示一次。如果在发送前跳过、请求未完成或改稿没通过检查,回复会说明本轮实际情况,并附上 GPT 原稿。需要排查时,可以问 **“为什么上条回复没润色?”** 或 **“检查回复润色环境”**。
60
67
 
61
68
  ## 检查、更新与卸载
62
69
 
@@ -66,7 +73,7 @@
66
73
  | 更新 | `npx @kyun.si/codex-polish@beta update` | 取得新版源码后运行 `node scripts/install.mjs update` |
67
74
  | 卸载 | `npx @kyun.si/codex-polish@beta uninstall` | `node scripts/install.mjs uninstall` |
68
75
 
69
- 更新会保留项目设置和插件启用状态。升级后新开一个聊天。如果 Codex 提示钩子内容已变更,请重新审查并信任。卸载后,项目的 `.codex` 设置和共用的 `agy` 会保留。
76
+ 更新会保留已保存的项目模式和插件启用状态。此前未设置模式的项目也会采用默认的自动模式。升级后新开一个聊天。如果 Codex 提示钩子内容已变更,请重新审查并信任。卸载后,项目的 `.codex` 设置和共用的 `agy` 会保留。
70
77
 
71
78
  ## 文档与许可
72
79
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  [简体中文](technical.md) · [Overview](../README.en.md)
4
4
 
5
- Codex Polish `0.0.1-beta.1` 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.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.
6
6
 
7
7
  ## Project Settings and Inheritance
8
8
 
@@ -10,7 +10,7 @@ Each project stores its settings as individual files inside `.codex`. The plugin
10
10
 
11
11
  | File | Values and Default | Behavior |
12
12
  | --- | --- | --- |
13
- | `.codex/codex-polish.mode` | `manual` (default), `auto`, `off` | `manual` runs on explicit requests. `auto` runs on eligible turns with the trusted hook. `off` skips rewrites even when requested. |
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
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
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
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. |
@@ -29,15 +29,21 @@ When `.codex/codex-polish.language` is `auto`, chat prompts match the user's cur
29
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
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
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 delivers the verified rewrite. With Decisions enabled, comparing the protected question, draft, and candidate rewrite must score `P(substantive change) <= 0.05`. Any stage failure returns the original draft, and user cancellation ends the turn. |
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. |
33
33
 
34
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)
35
35
 
36
36
  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
37
 
38
+ ## What Appears in the Final Reply
39
+
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.
41
+
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.
43
+
38
44
  ## Outgoing Content, Hooks, and Limits
39
45
 
40
- Manual mode needs no hook to polish the current question and draft. Automatic mode requires trusting the plugin's `UserPromptSubmit` hook in Codex (`Settings -> Hooks` or `/hooks` in the CLI) and setting the project mode to `auto`. The same trusted hook is also required to include conversation history in both manual and automatic modes. See [Codex plugins](https://developers.openai.com/plugins/build/plugins) and [Codex hooks](https://learn.chatgpt.com/docs/hooks#where-codex-looks-for-hooks) for host behavior.
46
+ 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)
41
47
 
42
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`.
43
49
 
@@ -85,7 +91,7 @@ Using Node.js 22.16 and Antigravity CLI 1.5.12, the Codex agent selected `gemini
85
91
 
86
92
  ### Checks still open
87
93
 
88
- - 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. Compare the chosen text with the native final message and the transcript after reopening the chat.
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.
89
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.
90
96
  - 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).
91
97
 
@@ -95,4 +101,4 @@ Once the beta is published to npm, install it with `npx @kyun.si/codex-polish@be
95
101
 
96
102
  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.
97
103
 
98
- If you packed version `0.0.1-beta.1` locally, you can also run `npx --yes file:./kyun.si-codex-polish-0.0.1-beta.1.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.
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.
package/docs/technical.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](technical.en.md) · [项目首页](../README.md)
4
4
 
5
- `codex-polish` 的 `0.0.1-beta.1` 版包含两个 Codex 技能。[改写技能](../plugins/codex-polish/skills/codex-polish/SKILL.md) 在最终答复交付前润色草稿,[设置技能](../plugins/codex-polish/skills/codex-polish-setup/SKILL.md) 检查运行环境并保存项目设置。
5
+ `codex-polish` 的 `0.0.1-beta.3` 版包含两个 Codex 技能。[改写技能](../plugins/codex-polish/skills/codex-polish/SKILL.md) 在最终答复交付前润色草稿,[设置技能](../plugins/codex-polish/skills/codex-polish-setup/SKILL.md) 检查运行环境并保存项目设置。
6
6
 
7
7
  ## 模式、配置文件与查找规则
8
8
 
@@ -10,7 +10,7 @@
10
10
 
11
11
  | 配置文件 | 取值范围与默认值 | 运行行为 |
12
12
  | --- | --- | --- |
13
- | `.codex/codex-polish.mode` | `manual`(默认)、`auto`、`off` | `manual` 仅在用户点名时润色,处理当前问题和草稿不需要 hook。`auto` 需在宿主设置或 CLI `/hooks` 中信任插件的 `UserPromptSubmit` hook。`off` 完全停用,即使点名要求润色也不会外发。 |
13
+ | `.codex/codex-polish.mode` | `auto`(默认)、`manual`、`off` | 未保存模式时使用 `auto`。在 Codex 的 **设置 → Hooks** 或 CLI `/hooks` 中信任插件的 `UserPromptSubmit`,再新开聊天,普通提问就会触发润色流程。`manual` 仅在点名时触发。两种模式都可以点名润色本轮问答,无需 hook。`off` 跳过所有润色请求。 |
14
14
  | `.codex/codex-polish.model` | 模型 ID,默认 `gemini-4-hydrogen`(Gemini 4 Hydrogen) | 保存当前项目选用的 Gemini 模型。选项在运行时通过 ACP 从当前登录的 Antigravity 账号实时读取,不同账号返回的列表可能不同。仅查看模型菜单不会发送草稿或历史。下次改写时会核对所选模型,若已下线则本轮保留原稿。 |
15
15
  | `.codex/codex-polish.history-turns` | `0`–`10` 的整数,默认 `2` | 控制附带的最近完整问答轮数,从下次改写起生效。设为 `0` 只发本轮问题和草稿。保存大于 `10` 的值会报错。文件中的值不在范围内或格式无效时,本轮不带历史。无论手动还是自动模式,读取历史都需要受信任的 `UserPromptSubmit` hook。 |
16
16
  | `.codex/codex-polish.decisions` | `auto`(默认)、`off` | 与触发模式分开设置。`auto` 按 `OPENAI_API_KEY` 决定是否调用 OpenAI,`off` 始终只用 ACP。 |
@@ -28,10 +28,16 @@
28
28
  | 2. 风格判定 | 直接 ACP 路径在本地检查通过后立即进入改写。开启 Decisions 时,只有 `P(需要改写) ≥ 0.80` 才进入改写,原本清楚的草稿直接保留。 |
29
29
  | 3. ACP 改写 | 在临时工作区启动关闭了默认内置工具的专用编辑角色,使用已配置的 Antigravity 身份建立会话,核对项目选中的模型,拒绝全部权限请求,且只接收请求 ID 匹配的完整 `end_turn`。 |
30
30
  | 4. 固定内容还原 | 占位符必须按顺序逐一对应。还原后再次校验固定内容、数值与单位、控制字符、疑似凭据以及受支持的 Markdown 结构。 |
31
- | 5. 原意复核与交付 | 直接 ACP 路径通过本地校验即采用改稿。开启 Decisions 时还需满足 `P(实质变化) ≤ 0.05`。任一阶段未通过均回退原稿,用户取消则直接结束本轮。 |
31
+ | 5. 原意复核与交付 | 直接 ACP 路径通过本地校验即采用改稿。开启 Decisions 时,有改动的候选还需满足 `P(实质变化) ≤ 0.05`。任一阶段未通过均回退原稿,用户取消则直接结束本轮。 |
32
32
 
33
33
  相关接口规范见 [Google ACP 认证](https://antigravity.google/docs/ide/extensions/acp)、[Decisions API](https://developers.openai.com/api/reference/resources/decisions/methods/create) 与 [Antigravity 角色的工具配置](https://github.com/google-antigravity/antigravity-cli/releases/tag/1.2.1)。
34
34
 
35
+ ## 最终回复如何显示
36
+
37
+ 采用改稿时,Codex 在同一条最终消息中用普通 Markdown 标出 **Gemini 润色版** 和 **GPT 原稿**。前一段逐字显示通过检查并还原后的改稿,后一段逐字显示交给插件前的草稿。
38
+
39
+ 如果 Gemini 确实返回了相同的文字,回复会说明 Gemini 返回了原文,正文只显示一次。在发送前跳过、请求未完成或改稿被拒绝时,回复说明可确认的原因,只显示原稿。明确要求“只给润色后的正文”时只交付选定的正文。JSON、单条命令及其他逐字输出按用户要求直接交付,不加标题或状态。
40
+
35
41
  ## 隐私边界、文本保护与历史限制
36
42
 
37
43
  本轮问题和待润色草稿在外发给 OpenAI 或 Google 之前都会先做字面量占位符替换。这些占位符保护代码、命令、路径、链接和数字等固定片段。服务商仍可读取普通正文。
@@ -63,7 +69,7 @@
63
69
 
64
70
  `setup` 和 `update` 支持 `--install-agy`,在缺少 Antigravity CLI 时可自动安装。更新会保留项目设置与插件启用状态。同一版本号的新构建也能用 `update` 覆盖或重试中断的更新。
65
71
 
66
- 手头有本地打包的 `0.0.1-beta.1` 版时,也可以在压缩包所在目录运行 `npx --yes file:./kyun.si-codex-polish-0.0.1-beta.1.tgz uninstall`。卸载会清理该插件与专用市场,按当前 Codex 配置清除冷却记录和会话指针,保留各项目的 `.codex/` 配置和共用的 `agy`,并提示被手动修改过的安装文件备份位置。
72
+ 手头有本地打包的 `0.0.1-beta.3` 版时,也可以在压缩包所在目录运行 `npx --yes file:./kyun.si-codex-polish-0.0.1-beta.3.tgz uninstall`。卸载会清理该插件与专用市场,按当前 Codex 配置清除冷却记录和会话指针,保留各项目的 `.codex/` 配置和共用的 `agy`,并提示被手动修改过的安装文件备份位置。
67
73
 
68
74
  ## 已验证记录与真机验收
69
75
 
@@ -88,4 +94,4 @@ CODEX_POLISH_TEST_LIVE_DECISIONS=1 node --test --test-name-pattern='live fidelit
88
94
 
89
95
  1. 分别在无 OpenAI 密钥和开启 Decisions 的项目中核对工具轨迹,确认只有当前 agent 持有 ACP 进程、模型选择准确且结束后进程回收干净。
90
96
  2. 用超过 4 KiB 的中文长文在两个 Codex 会话中并发运行,确认正文、占位符和会话 ID 不串线,并核对缺模型、权限请求、取消和断流时的回退表现。
91
- 3. 对照校验工具输出、原生最终消息和重开会话后的记录,统计盲评偏好、严重事实反转、漏调率、逐字一致率和端到端延迟。统计门槛要求校准集和盲评集合计至少 200 个已交付的真实样本。[验收数据格式和指标](../evaluation/README.md)
97
+ 3. 在原生最终消息和重开会话后的记录中核对状态、两版顺序及正文。采用改稿时分别对照还原后的改稿和原始草稿。统计盲评偏好、严重事实反转、漏调率、选定正文的逐字一致率和端到端延迟。统计门槛要求校准集和盲评集合计至少 200 个已交付的真实样本。[验收数据格式和指标](../evaluation/README.md)
@@ -13,7 +13,7 @@ node --test tests/evaluation.test.mjs
13
13
 
14
14
  1. Obtain permission to use the samples and remove sensitive content. Assign a stable `case_id` to each original prompt and draft. Record the variants and votes for that case in one JSONL row, assigned to a single split. A repeated ID in any row or split stops the script with the offending line number.
15
15
  2. Label independently whether each original draft needs rewriting, then select thresholds on the calibration split. Freeze the plugin settings, model, and concise prompt used for the prompt-only baseline, and use that frozen setup across all blind samples. Each report corresponds to one frozen configuration.
16
- 3. Record the host tool trace, the selected reply text, and the native final message. For each blind sample, generate a prompt-only baseline reply using the same task, Codex model, and context with only a concise style instruction added. For samples that adopt a rewrite, also pair the rewrite against the original draft.
16
+ 3. Record the host tool trace, the selected reply text, and the native final message. Use the complete message to check the status, labels, section order, and original draft. For blind rating, take only the displayed body of the selected reply, omitting the plugin’s labels and status. Generate a prompt-only baseline reply using the same task, Codex model, and context with only a concise style instruction added. For samples that adopt a rewrite, also pair the rewrite against the original draft.
17
17
  4. Randomize each pair into A and B. Raters see only the user prompt, required context, and two anonymous replies, choosing A, B, or a tie. After unblinding, record `plugin_side` and `pick`. An independent fact checker compares the original draft against the delivered reply and flags any severe fact reversal, such as turning "tests were not run" into "tests passed." The script consumes the collected records, while the data provider verifies authorization, split assignment, and blinding.
18
18
 
19
19
  ## JSONL Record Fields
@@ -26,11 +26,11 @@ node --test tests/evaluation.test.mjs
26
26
  | `workflow_expected`, `workflow_ran` | Whether the turn should run through the plugin, and whether the host trace shows it actually ran. Turns skipped by rule can be `false` |
27
27
  | `triggered` | `true` when the check decides to trigger an external rewrite, even if a failure happens afterward |
28
28
  | `outcome` | `original` when delivering the initial draft, `adopted` when using the rewrite, `fallback` when delivering the original draft after a workflow error or validation rejection, `cancelled` when the user cancels and nothing is delivered |
29
- | `selected_text`, `final_text` | The final chosen text and the text actually shown to the user in the native session, preserving spaces and newlines. Omit or set to `null` when cancelled |
29
+ | `selected_text`, `final_text` | Take the first from the chosen rewrite or original draft. Independently take the second from its corresponding body in the native final message. Use the polished body when both versions appear, or the sole body when one appears. Exclude plugin labels and status. Preserve punctuation, spaces, and newlines within the body. Omit or set to `null` when cancelled |
30
30
  | `elapsed_ms` | Total milliseconds from draft ready to native final message display. Set to `null` when unmeasured or cancelled |
31
31
  | `severe_fact_reversal` | Human fact-check result for the delivered reply. Set `true` if a severe reversal is found, `false` if checked and none is found, or `null` if unchecked or cancelled |
32
32
  | `vs_original` | One vote for each blind record that adopted a rewrite. `{"plugin_side":"B","pick":"A"}` means the rewrite appeared on side B and the rater chose the original draft. Use `"pick":"tie"` for a tie |
33
- | `vs_prompt_only` | One vote for each delivered blind record. The plugin side holds the actual delivered reply and the other side holds the prompt-only baseline, using the same format. Omit or set to `null` when missing or not applicable |
33
+ | `vs_prompt_only` | One vote for each delivered blind record. The plugin side shows `final_text` and the other side shows the prompt-only baseline, using the same format. Omit or set to `null` when missing or not applicable |
34
34
 
35
35
  ## Reading the Report
36
36
 
@@ -13,7 +13,7 @@ node --test tests/evaluation.test.mjs
13
13
 
14
14
  1. 取得使用授权并去除敏感信息。每条原始问题与草稿分配一个稳定的 `case_id`。同一个原稿及其变体使用同一 ID,划分时只进一个集合。脚本遇到重复 ID 会报行号并退出。
15
15
  2. 独立标注原稿是否需要改写,再用校准集选择阈值。冻结插件配置、模型和仅提示对照的简洁提示,将这组配置用于全部盲评样本。每份报告对应一次冻结配置。
16
- 3. 记录宿主实际工具轨迹、选定的正文和原生最终消息。每条盲评样本用同一任务、同一 Codex 模型和上下文生成仅加简洁提示的对照答复。对采用改稿的样本,再与原稿配对比较。
16
+ 3. 记录宿主实际工具轨迹、选定的正文和原生最终消息。在整条消息中核对状态、来源标签、版本顺序和原稿。盲评只取实际显示的选定正文,去掉插件标签和状态。每条盲评样本用同一任务、同一 Codex 模型和上下文生成仅加简洁提示的对照答复。对采用改稿的样本,再与原稿配对比较。
17
17
  4. 每对随机排列成 A/B。评分者只看到用户问题、必要上下文和两篇匿名答复,分别选 A、B 或平局。揭盲后合并 `plugin_side` 和 `pick`。由独立核事实的人对照原稿和交付文本标出严重事实反转,例如把「没跑测试」改为「测试通过」。脚本消费采集结果,数据提供者负责核实授权、分组和盲法。
18
18
 
19
19
  ## 一行记录的字段
@@ -26,11 +26,11 @@ node --test tests/evaluation.test.mjs
26
26
  | `workflow_expected`、`workflow_ran` | 该回合是否应走插件,以及从宿主轨迹观察到是否实际运行。按约定跳过的回合可填 `false` |
27
27
  | `triggered` | 判定触发外部改写时为 `true`,即使随后发生故障 |
28
28
  | `outcome` | `original` 交付初稿,`adopted` 采用改稿,`fallback` 工作流出错或校验驳回后交付原稿,`cancelled` 用户取消且本轮未交付 |
29
- | `selected_text`、`final_text` | 最终选定的文本和原生会话中用户实际看到的文本。保留空格和换行。取消时省略或填 `null` |
29
+ | `selected_text`、`final_text` | 前者取自选定的改稿或原稿,后者独立取自原生最终消息中对应的正文。双版本回复只取润色版正文,单版本回复取唯一正文。排除插件添加的标签和状态,保留正文自身的标点、空格和换行。取消时省略或填 `null` |
30
30
  | `elapsed_ms` | 草稿就绪到原生最终消息显示的总毫秒数。缺测或取消填 `null` |
31
31
  | `severe_fact_reversal` | 对已交付正文的人工结论。发现严重反转填 `true`,已检查且无反转填 `false`,未检查或取消填 `null` |
32
32
  | `vs_original` | 盲评中采用改稿的记录填写一票。用 `{"plugin_side":"B","pick":"A"}` 表示改稿放在 B,评分者选了原稿。平局为 `"pick":"tie"` |
33
- | `vs_prompt_only` | 所有已交付的盲评记录各填一票。插件一侧放实际交付结果,另一侧放仅提示对照。格式同上。缺失或不适用的票省略或填 `null` |
33
+ | `vs_prompt_only` | 所有已交付的盲评记录各填一票。插件一侧放 `final_text`,另一侧放仅提示对照。格式同上。缺失或不适用的票省略或填 `null` |
34
34
 
35
35
  ## 读报告
36
36
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kyun.si/codex-polish",
3
- "version": "0.0.1-beta.1",
3
+ "version": "0.0.1-beta.3",
4
4
  "license": "Apache-2.0",
5
5
  "description": "Codex plugin that rewrites replies with Gemini via Antigravity ACP · 通过 Antigravity ACP 调用 Gemini 改写 Codex 回复的插件",
6
6
  "os": [
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-polish",
3
- "version": "0.0.1-beta.1",
3
+ "version": "0.0.1-beta.3",
4
4
  "description": "Rewrites Codex drafts with Gemini for cleaner replies. 用 Gemini 改写 Codex 草稿,让回复更清晰。",
5
5
  "skills": "./skills/",
6
6
  "hooks": "./hooks/hooks.json",
@@ -32,7 +32,7 @@ const DECISION_REASONS = {
32
32
 
33
33
  export function projectSettings(cwd) {
34
34
  const [value, scope] = readProjectSetting(cwd, MODE_FILE, 16, { allowMissingLink: true });
35
- return [value === null ? 'manual' : MODES.includes(value) ? value : 'off', scope];
35
+ return [value === null ? 'auto' : MODES.includes(value) ? value : 'off', scope];
36
36
  }
37
37
 
38
38
  function parseHistoryTurns(value, lang) {
@@ -271,15 +271,15 @@ function runHook() {
271
271
  if (event?.hook_event_name !== 'UserPromptSubmit') return;
272
272
  const [mode, scope] = projectSettings(event.cwd);
273
273
  rememberHistorySource(event, mode);
274
- if (mode === 'auto' && !workflowCooldown(scope, decisionsSettings(event.cwd).decisions_enabled)) {
275
- console.log(JSON.stringify({ hookSpecificOutput: {
276
- hookEventName: 'UserPromptSubmit',
277
- additionalContext: tr(
278
- '本项目已开启自动改写。完成任务后,在发送最终回复前使用已安装的 codex-polish:codex-polish 技能。请遵守用户本轮指定的输出格式、取消或禁止外发的要求。',
279
- 'Automatic rewriting is on for this project. After completing the task, use the installed codex-polish:codex-polish skill before sending the final answer. Honor the user’s requested format, cancellations, and requests to keep content local.',
280
- language(event.cwd)),
281
- } }));
282
- }
274
+ if (mode !== 'auto') return;
275
+ const lang = language(event.cwd);
276
+ const paused = workflowCooldown(scope, decisionsSettings(event.cwd).decisions_enabled);
277
+ const additionalContext = paused
278
+ ? tr('自动润色因上次服务故障暂时暂停。常规回复请在最终消息里注明本轮未润色,再给出 GPT 原稿。遵守用户的格式要求;若本轮明确点名润色,可按技能手动重试。',
279
+ 'Automatic polishing is temporarily paused after a service failure. For ordinary replies, mark the final answer as unpolished and show the original GPT draft. Honor the requested format. An explicit polish request can still use the skill.', lang)
280
+ : tr('本项目已开启自动改写。完成任务后,在发送最终回复前使用已安装的 codex-polish:codex-polish 技能。常规回复请在最终消息中显示润色结果和完整 GPT 原稿,两版相同时注明并只显示一次。遵守用户指定的输出格式、取消或禁止外发的要求。',
281
+ 'Automatic rewriting is on for this project. Before sending the final answer, use the installed codex-polish:codex-polish skill. In ordinary replies show the result and the full original GPT draft. If identical, label it and show it once. Honor the requested format, cancellations, and requests to keep content local.', lang);
282
+ console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext } }));
283
283
  }
284
284
 
285
285
  const commands = {
@@ -74,7 +74,8 @@ export function readProjectSetting(cwd, filename, maxBytes, { allowMissingLink =
74
74
  const settings = path.join(base, '.codex');
75
75
  try {
76
76
  if (fs.lstatSync(settings).isSymbolicLink()) {
77
- if (!allowMissingLink || fs.lstatSync(path.join(settings, filename), { throwIfNoEntry: false })) {
77
+ if (!allowMissingLink || !fs.statSync(settings, { throwIfNoEntry: false })?.isDirectory() ||
78
+ fs.lstatSync(path.join(settings, filename), { throwIfNoEntry: false })) {
78
79
  return [invalid, base];
79
80
  }
80
81
  } else {
@@ -1,36 +1,38 @@
1
1
  ---
2
2
  name: codex-polish
3
- description: Uses Gemini to polish Codex's final reply when you ask, or when project auto mode prompts. 你要求润色这轮回复,或项目自动模式触发时运行。
3
+ description: Polishes Codex's final reply with Gemini when you ask or a trusted automatic-mode hook prompts. 在你点名或受信任的自动润色 hook 提醒时运行。
4
4
  ---
5
5
 
6
6
  # 润色本轮回复
7
7
 
8
- 先完成用户任务,准备一份本来就可以交付的完整正文。始终保留这份原稿。只在最终答复前运行一次,不润色工具调用、进度更新或待原样交付的文件。
8
+ 先完成用户任务,准备一份可以直接发出的完整回复,作为本轮的 GPT 原稿。保留这份原稿直到交付。只在最终答复前运行一次,不润色工具调用、进度消息或待原样交付的文件。
9
9
 
10
- ## 本轮可否处理
10
+ ## 触发与输出格式
11
11
 
12
- 用本文件的安装位置定位 `scripts/`、`references/` 和 `../../hooks/preferences.mjs`。记住**本轮开始时实际工作目录的绝对路径**(即使它是仓库的子目录),后面的 `--cwd` 始终用它。用户本轮主动点名时 `--trigger explicit`,仅因项目提醒触发时 `--trigger auto`。重复的提醒只处理一次。用户本轮禁止外发、材料不适合外发、宿主无法持续读写并回收同一个子进程,直接交付原稿。
12
+ 用本文件的安装位置定位 `scripts/`、`references/` 和 `../../hooks/preferences.mjs`。记住本轮开始时的绝对工作目录(可以是仓库子目录),后面的 `--cwd` 始终用它。用户本轮主动点名时用 `--trigger explicit`。普通提问只有收到本轮受信任的 `UserPromptSubmit` 提醒才用 `--trigger auto`。重复的提醒只处理一次。
13
13
 
14
- 使用 Node.js 22.16 或更新版本。先在实际执行工具的环境运行 `node …/hooks/preferences.mjs check --cwd "<原项目目录>"`。模式为 `off`、仅提醒触发而模式为 `manual`、`blockers` 非空、或自动触发且 `cooldown` 非空时,直接交付原稿。找不到 Node.js、帮助脚本无法运行或结果不完整,也沿用原稿。记下本轮 `gemini_model`,默认值为 `gemini-4-hydrogen`。插件状态提示使用本项目的界面语言。在自动语言模式下优先跟随本轮用户说的中文或英文,无法判断时用 `check.ui_language`。最终答复始终保持待润色原稿的语言。按 `google_auth_method` 选择 ACP 步骤。默认的 `existing-session` 由官方进程使用已有登录,直接建立新会话。显式指定 API key 或企业身份时,才发送对应的认证请求。CLI 能否找到 `codex` 供安装排查参考,正在运行的宿主可以直接提供执行工具。
14
+ 用户取消就结束。用户禁止外发或要求 JSON、命令、补丁、逐字引用等固定格式时,按用户要求直接答复。用户明确只想看润色后的正文时,走下述润色流程,最终只交付选定的正文。其他情况下,润色结果与原稿都要在**用户可见的最终消息**中交代。
15
15
 
16
- 用户规定只给命令、JSON、补丁、逐字引用或其他固定格式时,按指定格式交付。只取本轮问题、当前有效的用户要求和答复原稿。这两个字段只写本轮材料。需要改写时,脚本会按当前项目的历史轮数为 ACP 附上最近的完整问答,默认 2 轮,最多 10 轮,设为 0 时只发本轮材料。不要自行查阅、挑选、概括或转录前文。
16
+ 用 Node.js 22.16 或更新版本运行 `node …/hooks/preferences.mjs check --cwd "<原项目目录>"`。模式为 `off`,或仅由提醒触发且模式为 `manual` 时,按普通回复交付。记下 `gemini_model`(默认 `gemini-4-hydrogen`)、`google_auth_method` 和本轮的显示语言。状态和标题使用项目设置的中文或英文。语言为自动时跟随本轮用户的语言,无法判断时用 `check.ui_language`。原稿和改稿保持原稿的语言。
17
17
 
18
- ## 判定、改写与交付
18
+ 材料不适合外发、执行工具不能持续读写并回收同一子进程、Node.js 或帮助脚本不可用、`blockers` 非空、自动触发且 `cooldown` 非空时,按下文“保留原稿”交付。CLI 能否找到 `codex` 供安装排查参考,正在运行的宿主可以直接提供执行工具。
19
19
 
20
- 下面的脚本均用 Node.js 运行,从标准输入接收一个 UTF-8 JSON 对象,读标准输出的 JSON。使用宿主的安全 stdin;只有 shell 可用时,用 JSON 序列化器生成单行 JSON,再用单引号 heredoc 分隔符送入脚本。不要把正文插进 shell 表达式或当命令执行,不写草稿到项目文件。所有步骤检查退出状态与返回字段。失败时交付原稿。
20
+ ## 判定与改写
21
21
 
22
- 1. 调用 `scripts/text_guard.mjs prepare`,输入 `{"question":问题,"draft":原稿}`。若 `bypass` 为真,直接交付原稿。保存成功结果中的 `protected_question` 和 `protected_draft`。下文的“受保护文本”均指这两个返回值。
23
- 2. 看本轮 `check.decisions_enabled`。为真时选择 `decisions`,为假时选择 `acp`。运行 `node …/hooks/preferences.mjs decision judge --cwd "<原项目目录>" --trigger <auto或explicit> --route <所选路由>`,等待 `action: "rewrite"`。保存返回的 `route` 和可能的 `recovery_token`。两条路径的输入如下。
24
- - `acp`:这个入口只在本地检查项目模式、依赖和冷却状态,标准输入留空。符合条件就继续改写,即便原稿已经很通顺。
25
- - `decisions`:从标准输入提供受保护的 `question` 和 `draft`,供 OpenAI 做风格判定。需要改写的概率达到 0.80 才继续。
26
- 3. 读取 [ACP 操作步骤](references/acp.md)。**你就是 ACP 客户端。** 在本轮用你的持久执行工具启动官方 `agy acp`,对同一个进程逐条收发。按步骤用 acp_payload.mjs 组装一次改写请求,由当前 agent 将它直接交给同一个进程。不要委派给子 agent,不写或启动 ACP 驱动脚本、MCP 代理或后台服务。发送 prompt 前再运行第一个 `check`,确认原项目仍允许本次调用、Decisions 路由与第 2 步一致、`gemini_model` 与建立 ACP 会话前相同且本轮要求仍有效,再提交一次。当前要求仅允许外发本轮内容时,按 ACP 步骤省略历史。发生服务故障且用户仍在等待时,按操作步骤收尾,用 `node …/hooks/preferences.mjs note-failure <固定故障码> --cwd "<原项目目录>"` 记录原因,再交付原稿。记录失败也交付原稿。
27
- 4. 调用 `scripts/text_guard.mjs restore`,输入原始 `question`、原始 `draft` 和受保护的 `candidate`。仅当返回 `ok: true`,才保留还原的 `text`。若 `route` 为 `decisions` 且它与原稿相同,可以直接交付原稿。
28
- 5. 调用 `node …/hooks/preferences.mjs decision verify --cwd "<原项目目录>" --trigger <auto或explicit> --route <第2步返回的route>`。第 2 步返回了恢复标记时传入 `--recovery-token <标记>`。
29
- - `acp`:标准输入留空。本地确认项目仍允许改写后,返回 `action: "accept"` 即逐字交付第 4 步还原的正文。这条路径没有模型原意复核。
30
- - `decisions`:从标准输入提供受保护的 `question`、`draft` 和 ACP 返回的 `candidate`。仅在 OpenAI 判断实质变化概率不超过 0.05 且返回 `action: "accept"` 时交付还原稿。
22
+ 脚本从标准输入读取 UTF-8 JSON,输出 JSON。使用宿主的安全 stdin。只有 shell 可用时,用 JSON 序列化器生成单行 JSON,再用单引号 heredoc 分隔符送入脚本。不要把正文当作 shell 代码执行,不写草稿到项目文件。检查退出状态、完整结果和返回字段,失败时保留原稿。
31
23
 
32
- 若本轮项目设置或凭据变化导致路由不一致,或任一步失败,交付原稿。
24
+ 1. 调用 `scripts/text_guard.mjs prepare`,输入 `{"question":问题,"draft":原稿}`。两项只含本轮问题及其当前要求和完整原稿,不加入展示用的标题。若 `bypass` 为真,保留原稿,固定格式按用户要求直接交付。保存返回的 `protected_question` 和 `protected_draft`。
25
+ 2. `check.decisions_enabled` 为真时选择 `decisions`,否则选择 `acp`。运行 `node …/hooks/preferences.mjs decision judge --cwd "<原项目目录>" --trigger <auto或explicit> --route <所选路由>`。只在 `action: "rewrite"` 时继续。保存返回的 `route` 和可能的 `recovery_token`。
26
+ - `acp` 的标准输入留空。此入口在本地检查项目模式、依赖和冷却状态。通过就继续,即便原稿已经很通顺。
27
+ - `decisions` 从标准输入接收受保护的 `question` 和 `draft`。OpenAI 判断需要改写的概率达到 0.80 才继续。`reason: "already_clear"` 时保留原稿,并说明 OpenAI 判断无需润色。
28
+ 3. 读取 [ACP 操作步骤](references/acp.md)。**你就是 ACP 客户端。** 用本轮的持久执行工具启动官方 `agy acp`,对同一进程逐条收发。默认 `existing-session` 使用已有登录,显式指定 API key 或企业身份才发送对应认证请求。发送 prompt 时,在同一个工具调用中把 `acp_payload.mjs` 的 stdout 直接重定向到已打开的 ACP 输入(见参考命令)。不要先打印整帧再抄到下一次调用。不要委派给子 agent,不写或启动 ACP 驱动脚本、MCP 代理或后台服务。脚本按项目设置自动附上最近完整问答,默认 2 轮、最多 10 轮。不要自行查阅、挑选或概括。若本轮要求省略历史,按操作步骤只发本轮材料。提交 prompt 前再运行第一个 `check`,确认原项目仍允许调用、Decisions 路由和所选模型一致、用户要求仍有效,只提交一次。服务故障按步骤收尾,用 `node …/hooks/preferences.mjs note-failure <固定故障码> --cwd "<原项目目录>"` 记录,再保留原稿。记录失败也保留原稿。
29
+ 4. 调用 `scripts/text_guard.mjs restore`,传入最初的原始 `question`、`draft` 和受保护的 `candidate`。常规回复同时传入 `display_language`(`zh` 或 `en`)。用户明确只看润色正文时省略此字段。只有 `ok: true` 才保留已经还原的 `text` 及常规回复的 `display_text`。确保工具输出预算足以取得完整结果,优先在宿主内解析后只取需要展示的字段。候选校验不通过时只交付原稿。若 `route` 为 `decisions` 且还原后的 `text` 与原稿逐字相同,进入交付,无需再请求 OpenAI。
30
+ 5. 否则运行 `node …/hooks/preferences.mjs decision verify --cwd "<原项目目录>" --trigger <auto或explicit> --route <第2步返回的route>`。有恢复标记时传 `--recovery-token <标记>`。直接 `acp` 路径标准输入留空,本地核对项目仍允许改写。`decisions` 从标准输入接收受保护的 `question`、`draft` 与 ACP 返回的 `candidate`,实质变化概率不超过 0.05 才采用。只在 `action: "accept"` 时交付候选。路由变化、检查未通过或失败时保留原稿。
33
31
 
34
- 任一步出错都不自动重发付费请求。若上下文恢复后无法确认先前的请求状态,放弃该候选。用户中途取消就结束本轮;收到修正要求则丢弃旧候选,回答最新要求。单篇文本被拒绝、固定内容冲突,或启用 Decisions 时被判为已足够清楚、可能改变原意,都只影响这一篇。
32
+ ## 在最终消息中交付
35
33
 
36
- 自动模式正常交付原稿即可。用户主动点名且因配置或服务故障跳过时,可用一句进度提示说明原因,如“这轮保留原稿,当前 Codex 环境找不到 agy。”最终正文保持原样。用户要求严格格式时不额外提示。排查时报告阶段、固定故障码及剩余等待时间,隐藏材料及凭据。
34
+ - **常规回复**逐字发送第 4 步的 `display_text`。有改动时,其中先是 Gemini 润色版,再是最初的完整 GPT 原稿。两版逐字相同时,其中只出现一次正文,标题说明 Gemini 返回了相同原稿。不要另写前言、摘要或差异说明,不要让用户去工具日志查原稿。
35
+ - **保留原稿**时,在最初的完整原稿前用界面语言说明本轮的实际结果。发送前跳过可写“本轮未润色,以下是 GPT 原稿。”OpenAI 判断无需改写可写“OpenAI 判断无需润色,以下是 GPT 原稿。”请求失败写“润色未完成,以下是 GPT 原稿。”改稿被拒写“润色稿未通过检查,以下是 GPT 原稿。”只说明有证据的原因,不展示被拒的内容、占位符、凭据或服务端原始报错。
36
+ - **只看润色正文**时,采用候选就逐字发送 `text`,否则逐字发送最初的原稿。不加标题、状态或对照。固定格式、关闭、取消继续遵守前述规则。
37
+
38
+ 不为展示多调用一次模型,不重发结果不明或失败的付费请求。若上下文恢复后无法确认先前的请求状态,放弃候选。用户中途修正要求就丢弃旧候选,回答最新要求。排查故障时可报告阶段、固定故障码和剩余等待时间。
@@ -20,7 +20,7 @@
20
20
  3. 对输入管道逐次写入一条完整的 JSON 行,然后从同一运行句柄读返回值。用执行工具在临时目录执行 `printf '%s\n' '<已安全引用的一帧>' > .acp-in`;有参数的文本始终交给 JSON 序列化器和安全引用,不拼入命令代码。若管道写入阻塞,限定在同一控制请求的期限内中断本次写入并回收服务。每帧通过 JSON 序列化器生成,末尾追加一个换行。正文中的换行属于 JSON 字符串;不可拆成多个请求或把正文当作 shell 命令执行。先发下列帧并等待对应的 `id`:
21
21
 
22
22
  ```json
23
- {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{},"clientInfo":{"name":"codex-polish","version":"0.0.1-beta.1"}}}
23
+ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{},"clientInfo":{"name":"codex-polish","version":"0.0.1-beta.3"}}}
24
24
  ```
25
25
 
26
26
  确认 `result.protocolVersion == 1`。生产中若服务端提供 `agentInfo.name`,应与官方 `Antigravity ACP Server` 一致,身份或协议版本冲突记 `acp_protocol_error`。
@@ -58,10 +58,9 @@
58
58
  发送 prompt 前,用 [请求组装脚本](../scripts/acp_payload.mjs) 的绝对路径和**原项目目录**。脚本通过标准输入接收 `{"sessionId":"<本次 ACP 会话>","question":"<受保护的本轮问题>","draft":"<受保护的原稿>"}`。在本轮临时目录执行以下命令,将返回的一条 JSON-RPC 帧直接交给已经打开的官方进程。用本轮真实值替换示例内容。命令只把历史保存在内存中,不要先打印帧、让模型复述历史或把帧写入文件。
59
59
 
60
60
  ```sh
61
- frame=$(node "<插件内 acp_payload.mjs 的绝对路径>" --cwd "<原项目绝对路径>" <<'CODEX_POLISH_INPUT'
61
+ node "<插件内 acp_payload.mjs 的绝对路径>" --cwd "<原项目绝对路径>" > .acp-in <<'CODEX_POLISH_INPUT'
62
62
  {"sessionId":"<本次 ACP 会话>","question":"<受保护的问题>","draft":"<受保护的原稿>"}
63
63
  CODEX_POLISH_INPUT
64
- ) && printf '%s\n' "$frame" > .acp-in
65
64
  ```
66
65
 
67
66
  使用原生 stdin 通道时,在同一工具调用内部将脚本成功返回的完整 stdout 直接写入进程句柄,输出预算须足以容纳整帧。截断、脚本报错或传输结果不明时沿用原稿,不尝试重发。用户本轮禁止附带历史时,省略 `--cwd`;禁止外发时跳过整个流程。
@@ -27,7 +27,8 @@ const EXACT = new RegExp([
27
27
  /(?:只要|仅需)\s*(?:一(?:条|行|个)\s*)?(?:命令|代码|json|补丁)/.source,
28
28
  /(?:原样|逐字|一字不改地?)\s*(?:输出|返回|复述|引用|复制)/.source,
29
29
  /(?:固定|严格按(?:照)?|完全按照|严格遵守)(?:指定|以下|下面|这个|此)?格式/.source,
30
- /\b(?:return|output|reply with|give me|print)\s+(?:only|exactly)\b/.source,
30
+ // A final "return only the polished text" clause requests a rewrite without headings.
31
+ /\b(?:return|output|reply with|give me|print)\s+(?:exactly\b|only\b(?!\s+(?:the\s+)?polished\s+(?:text|reply|answer|version|prose|body)[.!?]?\s*$))/.source,
31
32
  /\b(?:json|yaml|code|commands?|patch|diff)\s+only\b|\bverbatim\b/.source,
32
33
  ].join('|'), 'iu');
33
34
 
@@ -65,6 +66,10 @@ const FENCE = /^ {0,3}(`{3,}|~{3,})/;
65
66
  const FROZEN_LINE = /^(?:[ \t]*>| {4,}\S|\t\S|[ \t]*\[[^\]]+\]:|[ \t]*\|.*\||[ \t]*(?:-{3,}|\*{3,}|_{3,})[ \t]*$|[ \t]*(?:\$ |PS> )\S)/;
66
67
  const COMMAND_LINE = new RegExp('^[ \\t]*(?:' + COMMANDS + /(?:[ \t]+[ -~]*)?|(?:\.\/|~\/|\/)[A-Za-z0-9_./-]+[ \t]+[ -~]+/.source + ')$');
67
68
  const STRUCTURE = /^([ \t]*)(#{1,6}(?=\s)|[-*+](?=\s)|[0-9]+[.)](?=\s)|>|\||`{3,}|~{3,}|\[[^\]]+\]:)/;
69
+ const DISPLAY_LABELS = {
70
+ zh: { polished: 'Gemini 润色版', original: 'GPT 原稿', unchanged: 'Gemini 已核对,和 GPT 原稿相同' },
71
+ en: { polished: 'Polished by Gemini', original: 'Original GPT draft', unchanged: 'Gemini reviewed the GPT draft and left it unchanged' },
72
+ };
68
73
 
69
74
  class Skip extends Error {}
70
75
 
@@ -183,7 +188,14 @@ export function run(action, payload) {
183
188
  if (!isDeepStrictEqual([...actual.values()], [...literals.values()])) throw new Skip('literal_changed');
184
189
  if (!isDeepStrictEqual(structure(text), structure(payload.draft)) || STRUCTURED.test(text))
185
190
  throw new Skip('structure_changed');
186
- return { ok: true, text };
191
+ const { draft, display_language } = payload;
192
+ if (display_language === undefined) return { ok: true, text };
193
+ if (display_language !== 'zh' && display_language !== 'en') throw new Skip('invalid_input');
194
+ const labels = DISPLAY_LABELS[display_language];
195
+ const display_text = text === draft
196
+ ? `**${labels.unchanged}**\n\n${draft}`
197
+ : `**${labels.polished}**\n\n${text}\n\n**${labels.original}**\n\n${draft}`;
198
+ return { ok: true, text, display_text };
187
199
  } catch (error) {
188
200
  if (!(error instanceof Skip)) throw error;
189
201
  return action === 'prepare' ? { bypass: true, reason: error.message } : { ok: false, reason: error.message };
@@ -17,11 +17,11 @@ Use one language for the conversation, including menus, status, examples and rec
17
17
 
18
18
  Opening **Setup** or saying “配置回复润色” / “Set up Codex Polish” starts with local checks. Keep the first answer short. Skip the general tour if the user asked about a particular setting.
19
19
 
20
- At first use, explain that the current reply can be polished manually. To include earlier exchanges or use automatic rewrites, the user must trust Codex Polish’s `UserPromptSubmit` in Codex **Settings → Hooks** (`/hooks` in the CLI), then start a new chat. Automatic rewriting also needs auto mode enabled for that project.
20
+ Use the effective project mode from the local check. A project without a saved mode starts in automatic mode. Before inviting the user to trust Codex Polish’s `UserPromptSubmit`, explain what polishing shares. Google receives the current question and draft with fixed details masked, plus up to the configured number of eligible earlier exchanges as written (two by default). If OpenAI checks are enabled, OpenAI receives the protected current question and draft, plus the candidate on the final check.
21
21
 
22
22
  - **A required step is missing.** Lead with the next step from the [中文指南](references/credentials.md) or [English guide](references/credentials.en.md). For `agy_missing`, explain that Gemini needs the Antigravity CLI. The user can run `node scripts/install.mjs setup --install-agy` from the extracted package on the machine running Codex, then ask to check setup again. Offer Google's installation guide if the package is unavailable. Use the existing sign-in and suggest opening `agy` to sign in only if Antigravity requests authentication. When a saved model or optional OpenAI key is invalid, offer the relevant recovery choice.
23
- - **Ready to try in the default mode.** Give one example that works in a fresh chat: “用一句话解释 DNS,再把你的回复润色一下。” / “Explain what DNS does in one sentence, then polish your reply.” Say that polishing sends the question and draft to Google and can include the last two completed exchanges by default. For existing projects, report their actual mode and history count. A healthy project that is off should get the action to turn on on-demand polishing. If it already uses automatic polishing, explain that it applies to eligible replies.
24
- - **Offer a short path onward.** For example, “直接试用 · 自动润色 · 更多设置” / “Try it · Polish automatically · More settings”. Keep the user's current settings until they choose. “Try it” can run the example if the user chooses it. “More settings” leads to the choices below, including the model picker. A local check does not open a provider session or ask for API keys. Run the model lookup only when the user chooses it or explicitly asks to verify available models.
23
+ - **Ready to try.** For automatic mode, direct the user to Codex **Settings → Hooks** (`/hooks` in the CLI) to trust `UserPromptSubmit`. Have them start a fresh chat and ask an ordinary question such as “用一句话解释 DNS。” / “Explain what DNS does in one sentence.” For manual mode, show the explicit request “把这轮回复润色一下” / “Polish this reply”. Explicit requests work before trusting the hook and use only the current question and draft then. If the project is off, explain that the user can choose automatic or manual mode to try polishing.
24
+ - **Offer a short path onward.** For example, in automatic mode offer “只在我要求时润色 · 关闭回复润色 · 更多设置” / “Only polish when I ask · Turn off Codex Polish · More settings”. Keep the user's current settings until they choose. “More settings” leads to the choices below, including the model picker. A local check does not open a provider session or ask for API keys. Run the model lookup only when the user chooses it or explicitly asks to verify available models.
25
25
 
26
26
  ## Project settings
27
27
 
@@ -29,7 +29,7 @@ When asked to show settings, describe the current values in plain language. Offe
29
29
 
30
30
  | What the user can change | What to do |
31
31
  | --- | --- |
32
- | **什么时候润色 / When to polish** | “只在我要求时 / Only when I ask” → `set-mode manual` (default). “自动润色 / Polish automatically” → `set-mode auto`. “关闭 / Turn off” → `set-mode off`. Append `--cwd "<project>"`. Off also skips explicit requests. For auto, explain which question, draft and history can go to Google, and which material goes to OpenAI when enabled. Help the user trust the plugin's `UserPromptSubmit` hook in Settings → Hooks (CLI: `/hooks`) and start a fresh chat. |
32
+ | **什么时候润色 / When to polish** | “自动润色 / Polish automatically” → `set-mode auto` (default). “只在我要求时 / Only when I ask” → `set-mode manual`. “关闭 / Turn off” → `set-mode off`. Off also skips explicit requests. For auto, explain the sharing and hook steps above. |
33
33
  | **改写模型 / Rewrite model** | “选择改写模型 / Choose a rewrite model” opens the account's live Gemini list below. Default is Gemini 4 Hydrogen. “恢复默认模型 / Restore the default model” → `set-model --reset`. |
34
34
  | **带多少对话历史 / Conversation history** | “带最近 5 轮 / Include the last 5 exchanges” → `set-history-turns 5`. Accept 0–10, default 2. Zero sends just the current question and draft. One exchange is one earlier completed user input and final Codex reply. History needs a trusted hook and readable transcript. Up to 16 KiB can be attached, so fewer exchanges may fit. For “no history just this time”, omit `--cwd` from the ACP prompt formatter for this rewrite only. |
35
35
  | **额外检查 / Extra OpenAI checks** | Explain what the choice does in ordinary words. With an OpenAI key, OpenAI checks whether editing is worthwhile and whether the result keeps the meaning. “这个项目只用 Gemini 改写 / Use only Gemini for rewrites in this project” → `set-decisions off`. “有密钥时使用 OpenAI 检查 / Use OpenAI checks when a key is available” → `set-decisions auto` (default). Without a key, Gemini can handle eligible rewrites. OpenAI receives current material only. |
@@ -47,6 +47,8 @@ Show every returned Gemini name in provider order. Mark the **project's saved ch
47
47
 
48
48
  Use the guide in the conversation's language for Antigravity sign-in, optional OpenAI key creation, or enterprise identities. Never ask users to paste keys in chat. `existing-session` uses Antigravity's own login. If ACP reports authentication required, ask the user to open `agy` in a terminal on the machine running Codex and sign in. Google AI Studio keys apply only when the user explicitly selects `gemini-api-key`. Offer the English or Chinese guide for that exact case.
49
49
 
50
- For “为什么没改写 / Why wasn't my reply polished?”, distinguish local setup issues, manual/off mode, deliberate fixed-format output and later provider failures. If OpenAI checks are active, an already clear draft or a change in meaning can also keep the original. Use actionable wording for the actual cause. For a cooldown, give the remaining time and remedy. A request to **test the connection** authorizes the ACP initialize handshake and cleanup without a draft. A successful handshake establishes connectivity. Successfully opening a session and reading the model menu also checks the signed-in account. Do not use a writing request to test setup without the user asking.
50
+ For “为什么没改写 / Why wasn't my reply polished?”, use the status and available trace for that turn. The original can appear because Gemini returned the same text, the draft was never sent, the request failed, or the candidate failed a check. Report only the stage you can establish. A successful rewrite normally shows both versions in the final reply. A user who requests only the polished text sees one body, and exact-output requests keep their required format. For a cooldown, give the remaining time and remedy.
51
+
52
+ A request to **test the connection** authorizes the ACP initialize handshake and cleanup without a draft. A successful handshake establishes connectivity. Successfully opening a session and reading the model menu also checks the signed-in account. Do not use a writing request to test setup without the user asking.
51
53
 
52
54
  Use `project-hook` only when the host has not loaded the plugin hook and the user asks for a project hook. Merge it into `.codex/hooks.json` without duplicating an existing handler. The user trusts it in Codex.
@@ -6,13 +6,15 @@
6
6
 
7
7
  1. Install the plugin on the machine that runs Codex, using the same system account. It looks for `agy` on the Codex process’s PATH and then at `~/.local/bin/agy`. On a first install from Finder or an interactive terminal, you can accept the offer to install Google’s official CLI or skip it. For an unattended install or to add the CLI later, run `node scripts/install.mjs setup --install-agy` from the extracted package. You can also install it directly from Google. [Antigravity installation guide](https://antigravity.google/docs/getting-started/?tab=cli)
8
8
  2. The plugin uses your existing Antigravity sign-in. If Antigravity requests authentication, run `agy` in your terminal and sign in. If your shell can’t find the installed CLI, open `~/.local/bin/agy` directly.
9
- 3. Start a fresh Codex chat in your project and say **“Check Codex Polish setup.”** To see which Gemini models the account can use, say **“Choose a rewrite model.”** To try polishing a reply, ask **“Explain what DNS does in one sentence, then polish your reply.”**
9
+ 3. Projects default to automatic polishing. On a rewrite, Google receives your current question and draft with fixed details such as code, commands, and paths masked. Up to two earlier completed exchanges are included as written by default. In Codex **Settings → Hooks** (`/hooks` in the CLI), trust the plugin’s `UserPromptSubmit` hook. Start a fresh project chat and ask **“Explain what DNS does in one sentence.”**
10
10
 
11
- The default setup works without API keys. If Codex runs on a remote machine, follow these steps there.
11
+ Say **“Only polish when I ask”** for manual mode or **“Turn off Codex Polish”** to disable polishing. Before trusting the hook, you can still ask explicitly to polish a reply using just the current question and draft. The default setup works without API keys. If Codex runs on a remote machine, follow these steps there.
12
+
13
+ Say **“Check Codex Polish setup”** to inspect the local configuration or **“Choose a rewrite model”** to see the Gemini models your account can use.
12
14
 
13
15
  ## Optional OpenAI checks
14
16
 
15
- Turn these on if you want OpenAI to check whether a draft needs editing and whether the edit keeps its meaning. The plugin uses the Decisions API with `gpt-6-luna`. The OpenAI project linked to the key covers the API usage. [Decisions API](https://developers.openai.com/api/docs/guides/decisions)
17
+ When `OPENAI_API_KEY` is set, the default configuration uses OpenAI to check whether the draft needs editing and whether the edit keeps its meaning. These checks send the protected current question and draft to OpenAI, plus the candidate for the final check. The OpenAI project linked to the key covers the Decisions API usage for `gpt-6-luna`. [Decisions API](https://developers.openai.com/api/docs/guides/decisions)
16
18
 
17
19
  1. Open your OpenAI project’s **API keys** page. Choose **Create new secret key**, name it something like `codex-polish`, and save it in a password manager. For restricted keys, allow `POST /v1/decisions` and make sure the project can use `gpt-6-luna`. [Create a project key](https://platform.openai.com/api-keys)
18
20
  2. Pass the key as `OPENAI_API_KEY` to the process running Codex. In a bash or zsh terminal, run these commands. Paste the key when prompted, then press Return. The terminal hides it while you type.
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](credentials.en.md)
4
4
 
5
- 在项目里开一个新聊天,试一句 **“用一句话解释 DNS,再把你的回复润色一下。”** 插件默认沿用 Antigravity 登录,普通登录不用额外申请密钥。如果想让 OpenAI 判断什么时候值得润色、改稿有没有保留原意,再配置下面的可选服务。
5
+ 插件默认沿用 Antigravity 登录,普通登录不用额外申请密钥。如果想让 OpenAI 判断什么时候值得润色、改稿有没有保留原意,可以配置下面的可选服务。
6
6
 
7
7
  ## 准备 Antigravity
8
8
 
@@ -10,9 +10,11 @@
10
10
 
11
11
  只有 Antigravity 提示需要登录时,才需要在自己的终端运行 `agy` 登录。如果终端找不到命令,可以直接运行 `~/.local/bin/agy`。登录后回 Codex 再试一次改写。[ACP 认证说明](https://antigravity.google/docs/ide/extensions/acp#authentication)
12
12
 
13
+ 项目默认自动润色。改写时,Google 会收到本轮问题和草稿,代码、命令、路径等固定内容会先替换成占位符。默认最多附带之前 2 轮完整问答,历史按原文发送。在 Codex 的 **设置 → Hooks**(CLI 输入 `/hooks`)里信任插件的 `UserPromptSubmit`,再开一个项目聊天,问 **“用一句话解释 DNS。”** 如果想自己决定何时润色,可以说 **“只在我要求时润色”**。信任 hook 前也可以点名润色本轮问答。想停用就说 **“关闭回复润色”**。
14
+
13
15
  ## 选配 OpenAI Decisions
14
16
 
15
- 默认有 `OPENAI_API_KEY` 时启用 Decisions,没有时直接走 ACP。在项目里说 **“有 key 时用 Decisions”** 可以恢复这个默认设置。想保留现有 OpenAI key、只关掉本项目的两次判定,就说 **“这个项目只用 ACP”**。
17
+ 默认有 `OPENAI_API_KEY` 时启用 Decisions,没有时直接走 ACP。OpenAI 会收到用占位符保护了固定内容的本轮问题和草稿,最后一次检查还会收到候选改稿。在项目里说 **“有 key 时用 Decisions”** 可以恢复这个默认设置。想保留现有 OpenAI key、只关掉本项目的两次判定,就说 **“这个项目只用 ACP”**。
16
18
 
17
19
  要启用 Decisions,可以直接用自己已有的项目密钥,也可以按下面的步骤新建一个。
18
20
 
@@ -576,25 +576,28 @@ async function setup(root, store, run, setEnabled, action) {
576
576
  ),
577
577
  false
578
578
  ];
579
- if (action === 'setup') {
580
- const lang = language(),
581
- guide = join(target, lang === 'zh' ? GUIDE : GUIDE.replace('credentials.md', 'credentials.en.md'));
582
- return [
583
- tr(
584
- `回复润色 ${version} 已安装。手动润色当前问答可以直接用。\n要自动润色或让 Gemini 参考之前的问答,请在 Codex 的「设置 → Hooks」(CLI 输入 /hooks)中信任「回复润色」的 UserPromptSubmit,然后新开一个聊天。要开启自动润色,可以说「给这个项目开启自动润色」。\n配置指南:${guide}`,
585
- `Codex Polish ${version} is installed. You can ask it to polish the current reply right away.\nFor automatic rewrites or to include earlier exchanges, open Settings → Hooks in Codex (/hooks in the CLI), trust the Codex Polish UserPromptSubmit hook, and start a new chat. To enable automatic rewrites, say “Polish automatically in this project”.\nSetup guide: ${guide}`,
586
- lang
587
- ),
588
- true
589
- ];
590
- }
591
- return [
579
+ const lang = language();
580
+ const status = action === 'setup'
581
+ ? tr(`回复润色 ${version} 已安装。`, `Codex Polish ${version} is installed.`, lang)
582
+ : tr(`回复润色已更新到 ${version}。`, `Updated Codex Polish to ${version}.`, lang);
583
+ const lines = [
584
+ status,
592
585
  tr(
593
- `回复润色已更新到 ${version}。新开一个 Codex 项目对话,说「配置回复润色」就能查看设置。`,
594
- `Updated Codex Polish to ${version}. Open a new project chat in Codex and say “Set up Codex Polish”.`
586
+ '未设置模式的项目默认自动润色,已保存的模式继续生效。改写时,Google 会收到用占位符保护了固定内容的本轮问题和草稿,以及按原文附带的历史问答(默认最多 2 轮)。开启 OpenAI 检查时,OpenAI 只收到本轮材料。',
587
+ 'Projects without a saved mode default to automatic polishing. Saved modes still apply. On a rewrite, Google receives the current question and draft with fixed details masked, plus earlier exchanges as written (up to two by default). Optional OpenAI checks use only current-turn material.',
588
+ lang
595
589
  ),
596
- false
590
+ tr(
591
+ '要自动润色或附带历史,请在 Codex 的「设置 → Hooks」(CLI 输入 /hooks)中信任本插件的 UserPromptSubmit,再新开一个聊天。想改模式,可以说「只在我要求时润色」或「关闭回复润色」。',
592
+ 'For automatic polishing or history, trust the plugin’s UserPromptSubmit hook in Codex Settings → Hooks (/hooks in the CLI), then start a new chat. To change modes, say “Only polish when I ask” or “Turn off Codex Polish”.',
593
+ lang
594
+ )
597
595
  ];
596
+ if (action === 'setup') {
597
+ const guide = join(target, lang === 'zh' ? GUIDE : GUIDE.replace('credentials.md', 'credentials.en.md'));
598
+ lines.push(tr(`配置指南:${guide}`, `Setup guide: ${guide}`, lang));
599
+ }
600
+ return [lines.join('\n'), action === 'setup'];
598
601
  }
599
602
  // Node has no unlinkat. Pin each directory as the kernel cwd for this synchronous
600
603
  // walk and check inode identity after chdir, before any relative unlink/rmdir.
@@ -950,19 +953,21 @@ export function configurationSteps(checks) {
950
953
  lang
951
954
  )
952
955
  );
953
- lines.push(
954
- checks.mode === 'off'
955
- ? tr(
956
- '这个项目已关闭改写。想试用的话,可以先说「改回手动润色」。',
957
- 'Rewriting is off in this project. To try it, say “Switch to on-demand rewrites”.',
958
- lang
959
- )
960
- : tr(
961
- '试一句:「用一句话解释 DNS,再把你的回复润色一下。」',
962
- 'Try “Explain what DNS does in one sentence, then polish your reply.”',
963
- lang
964
- )
965
- );
956
+ const examples = {
957
+ auto: [
958
+ '在已信任 hook 的新聊天里,直接问「用一句话解释 DNS。」就会触发自动润色。',
959
+ 'After trusting the hook, try automatic polishing in a new chat. Ask “Explain what DNS does in one sentence.”'
960
+ ],
961
+ manual: [
962
+ '这个项目只在点名时润色。试一句:「用一句话解释 DNS,再把你的回复润色一下。」',
963
+ 'This project polishes only when asked. Try “Explain what DNS does in one sentence, then polish your reply.”'
964
+ ],
965
+ off: [
966
+ '这个项目已关闭改写。想试用的话,可以先说「改回手动润色」。',
967
+ 'Rewriting is off in this project. To try it, say “Switch to on-demand rewrites”.'
968
+ ]
969
+ };
970
+ lines.push(tr(...examples[checks.mode], lang));
966
971
  return [lines, pages];
967
972
  }
968
973
  async function ask(prompt) {