antigravity-codex-worklog 0.0.0-stage → 0.2.0
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/LICENSE +21 -0
- package/README.md +159 -2
- package/README.zh-CN.md +156 -0
- package/assets/logo.svg +28 -0
- package/bin/cli.mjs +179 -0
- package/package.json +43 -4
- package/plugin.json +15 -0
- package/rules/AGENTS.md +37 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 lemonxiny55
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,160 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Codex Worklog Commentary for Antigravity
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/antigravity-codex-worklog)
|
|
4
|
+
[](https://github.com/lemonxiny55/antigravity-codex-worklog/releases)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
English | [简体中文](./README.zh-CN.md)
|
|
8
|
+
|
|
9
|
+
**Bring OpenAI Codex-style interleaved engineering commentary (`Commentary` / `Tool Preambles`) to Google Antigravity.**
|
|
10
|
+
|
|
11
|
+
Instead of silently running dozens of tool calls and summarizing only at the very end, this global Antigravity plugin instructs the agent to emit compact, evidence-anchored worklog updates **between logical tool batches** — letting you follow its reasoning live, spot directional drift early, and steer mid-execution.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Why & Inspiration
|
|
16
|
+
|
|
17
|
+
In OpenAI's open-source [`openai/codex`](https://github.com/openai/codex) and [`openai/harmony`](https://github.com/openai/harmony) specifications, coding agents separate output into three distinct layers:
|
|
18
|
+
|
|
19
|
+
1. **Internal Reasoning (`analysis`)**: Hidden scratchpad thinking.
|
|
20
|
+
2. **Interleaved Commentary (`commentary` / `MessagePhase::Commentary`)**: Short, factual progress updates (`default.md` *Preamble messages*, `gpt_5_codex_prompt.md` *Sharing progress updates*) placed directly between grouped tool executions.
|
|
21
|
+
3. **Final Answer (`final_answer`)**: Clean delivery without dumping raw file contents (*Presenting your work*).
|
|
22
|
+
|
|
23
|
+
By default, Antigravity models tend to place intermediate notes into collapsible `Thought` blocks and execute long tool chains silently. **Codex Worklog Commentary v0.2.0** brings that open-source Codex commentary protocol into Antigravity's native plugin rule system, including guardrails against common failure modes like premature turn termination (`openai/codex#7900`) and Plan-to-Execution drift.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Key Features (v0.2.0)
|
|
28
|
+
|
|
29
|
+
1. **Visible Channel Discipline**: Enforces writing progress updates into visible assistant message text alongside tool calls — never hidden solely inside `thought` blocks.
|
|
30
|
+
2. **Smart Cadence & Logical Batching**: Skips chatter on trivial Q&A or single reads; groups 1–4 related tool calls per batch and always sends a brief preamble before heavy or state-mutating operations.
|
|
31
|
+
3. **Evidence-Anchored 3-Part Micro-Cycle**: Every update covers concrete **Facts & Evidence** (counts, paths, exact errors, CI status), **Decision & Guardrail** (parameter tweaks, untouched files), and **Next Action Preview**.
|
|
32
|
+
4. **Anti-Premature-Termination Guardrail**: Prevents the `openai/codex#7900` failure pattern where an agent stops its turn right after outputting an interim status sentence.
|
|
33
|
+
5. **Plan-to-Execution Continuity**: Preserves interleaved commentary across Antigravity's dual-stage workflow (`exit_plan_mode` handoff from planning to execution).
|
|
34
|
+
6. **Language Mirroring & Dry Worklog Tone**: Automatically writes in the user's language (English, Chinese, etc.) with zero conversational filler and no full-file dumping at the end.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Example Timeline
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
Initial Preamble:
|
|
42
|
+
I'll create an isolated worktree from origin/main for the documentation fix
|
|
43
|
+
without touching existing dirty media files, then verify link checks and CI.
|
|
44
|
+
|
|
45
|
+
> Ran 3 commands (git status, git worktree add, link check)
|
|
46
|
+
|
|
47
|
+
Updated both READMEs in the isolated worktree while leaving 4 unrelated local
|
|
48
|
+
changes untouched. Local check verified 76 internal links; 2 external URLs hit
|
|
49
|
+
timeouts and are being re-checked individually. Next, I'll verify the external
|
|
50
|
+
URLs and open the PR.
|
|
51
|
+
|
|
52
|
+
> Ran 2 commands (curl verify, gh pr create)
|
|
53
|
+
|
|
54
|
+
PR #18 created and CI is green on Node 22/24. No pending review comments remain.
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
> **Tip — Steering Mid-Execution**: Because every update previews the exact next step, if you see the agent heading in the wrong direction, simply send a message while it is still working. Antigravity queues your message and redirects immediately after the current tool call finishes.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
### Option 1: One-Command Install via `npx` (Recommended)
|
|
64
|
+
|
|
65
|
+
Automatically installs the plugin into `~/.gemini/config/plugins/codex-worklog` on Windows, macOS, and Linux:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npx antigravity-codex-worklog@latest
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Check installation status:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npx antigravity-codex-worklog@latest status
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Option 2: Install via `git clone`
|
|
78
|
+
|
|
79
|
+
Clone directly into your global Antigravity plugins directory (`~/.gemini/config/plugins/codex-worklog`):
|
|
80
|
+
|
|
81
|
+
#### Windows (PowerShell)
|
|
82
|
+
|
|
83
|
+
```powershell
|
|
84
|
+
git clone https://github.com/lemonxiny55/antigravity-codex-worklog.git "$env:USERPROFILE\.gemini\config\plugins\codex-worklog"
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
#### macOS / Linux
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
git clone https://github.com/lemonxiny55/antigravity-codex-worklog.git ~/.gemini/config/plugins/codex-worklog
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Activation
|
|
94
|
+
|
|
95
|
+
1. Restart Antigravity (or reload the agent service / start a new session) so the plugin rules are discovered.
|
|
96
|
+
2. Open **Skills & Customizations** in the sidebar to confirm **Codex Worklog Commentary** is enabled. You can toggle it on or off globally anytime without deleting files.
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Updating & Uninstalling
|
|
101
|
+
|
|
102
|
+
### Update
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# Via npx
|
|
106
|
+
npx antigravity-codex-worklog@latest update
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
```powershell
|
|
110
|
+
# Or via git (Windows PowerShell)
|
|
111
|
+
git -C "$env:USERPROFILE\.gemini\config\plugins\codex-worklog" pull
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
# Or via git (macOS / Linux)
|
|
116
|
+
git -C ~/.gemini/config/plugins/codex-worklog pull
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Uninstall
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
# Via npx
|
|
123
|
+
npx antigravity-codex-worklog@latest uninstall
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
```powershell
|
|
127
|
+
# Or manually (Windows PowerShell)
|
|
128
|
+
Remove-Item -Recurse -Force "$env:USERPROFILE\.gemini\config\plugins\codex-worklog"
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
# Or manually (macOS / Linux)
|
|
133
|
+
rm -rf ~/.gemini/config/plugins/codex-worklog
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Repository Structure
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
antigravity-codex-worklog/
|
|
142
|
+
├── package.json # npm package & npx CLI entry
|
|
143
|
+
├── plugin.json # Antigravity plugin manifest
|
|
144
|
+
├── bin/
|
|
145
|
+
│ └── cli.mjs # Zero-dependency cross-platform plugin installer CLI
|
|
146
|
+
├── rules/
|
|
147
|
+
│ └── AGENTS.md # Always-on global worklog commentary rule (no frontmatter)
|
|
148
|
+
├── assets/
|
|
149
|
+
│ └── logo.svg # Dual-theme vector icon
|
|
150
|
+
├── README.md # English documentation
|
|
151
|
+
├── README.zh-CN.md # Chinese documentation
|
|
152
|
+
├── LICENSE # MIT License
|
|
153
|
+
└── .gitignore
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## License
|
|
159
|
+
|
|
160
|
+
[MIT](./LICENSE) © 2026 [lemonxiny55](https://github.com/lemonxiny55)
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# Codex Worklog Commentary(Antigravity 插件)
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/antigravity-codex-worklog)
|
|
4
|
+
[](https://github.com/lemonxiny55/antigravity-codex-worklog/releases)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
[English](./README.md) | 简体中文
|
|
8
|
+
|
|
9
|
+
**为 Google Antigravity 注入类似 OpenAI Codex 的「穿插式工程日志(Interleaved Commentary)」执行体验。**
|
|
10
|
+
|
|
11
|
+
在多步骤编程、排障或构建任务中,本全局插件会约束 Agent **在工具调用批次之间实时输出高信息密度的阶段汇报**,不再闷头跑完几十个命令才一次性总结——让你随时看清它的判断依据、及时发现方向偏差并在中途插话纠偏。
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 设计灵感与原理
|
|
16
|
+
|
|
17
|
+
参考 OpenAI 开源项目 [`openai/codex`](https://github.com/openai/codex) 与 [`openai/harmony`](https://github.com/openai/harmony) 的公开规范,Codex 之所以透明可控,源于它把输出切分为三层:
|
|
18
|
+
|
|
19
|
+
1. **内部思考(`analysis`)**:底层草稿推演,隐藏在折叠区中。
|
|
20
|
+
2. **穿插解说(`commentary` / `MessagePhase::Commentary`)**:在 `default.md`(*Preamble messages*)与 `gpt_5_codex_prompt.md`(*Sharing progress updates*)中定义的阶段性进展汇报,穿插于工具执行卡片之间。
|
|
21
|
+
3. **最终交付(`final_answer`)**:结论与路径索引直接交付,避免把整段文件源码倾倒进对话(*Presenting your work*)。
|
|
22
|
+
|
|
23
|
+
Antigravity 默认提示词偏向“静默连续调用工具 + 隐藏思考块 + 末尾统一总结”。**Codex Worklog Commentary v0.2.0** 借鉴 `openai/codex` 开源提示词工程与真实避坑经验(如 `openai/codex#7900` 防早停护栏),在 Antigravity 全局插件层完整复刻了这一体验。
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 核心特性(v0.2.0)
|
|
28
|
+
|
|
29
|
+
1. **可见通道硬约束**:强制要求把阶段汇报写入面向用户的**可见正文**,禁止只写进隐藏 `Thought` 思考块导致工具卡片之间一片空白。
|
|
30
|
+
2. **智能节奏与逻辑分组**:简单问答或单次轻量读文件不刷屏;多步任务按 1~4 个关联工具为一组穿插 1~3 句汇报,且在大改动、全量测试、构建或推送前必发前置预告。
|
|
31
|
+
3. **三段式证据锚点微循环**:每段汇报固定覆盖 **事实与证据**(精确计数、路径、报错原文、CI 状态)、**决策与风控边界**(参数调整依据、未触碰无关文件确认)与 **下一步动作预告**。
|
|
32
|
+
4. **防提前结束回合护栏**:规避 `openai/codex#7900` 典型坑——严禁在刚输出“接下来我将……”后未附带工具调用就提前结束回合。
|
|
33
|
+
5. **Plan / Execute 双阶段穿透**:兼容 Antigravity 的 `exit_plan_mode` 规划-执行双模型切换,确保进入实际改代码阶段后仍保持穿插汇报。
|
|
34
|
+
6. **自动语言镜像与工单口吻**:规则内核采用高指令遵循度的英文编写,输出语言自动跟随用户(中文提问即输出干练中文工程日志),去除客套寒暄且不在最终回复倾倒整文件正文。
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 效果示例
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
开局宣告:
|
|
42
|
+
我会从最新 origin/main 创建独立文档工作树处理本次修改,不触碰原仓库既有未提交改动,完成后核验站内链接与 CI 状态。
|
|
43
|
+
|
|
44
|
+
> 运行了 3 个命令(git status、git worktree add、链接校验)
|
|
45
|
+
|
|
46
|
+
独立工作树已创建,未改动原仓库 4 项本地修改。76 个站内链接已完成本地核验,另有 2 个外链连接超时正在单独复查。下一步我将补测外链并创建 PR。
|
|
47
|
+
|
|
48
|
+
> 运行了 2 个命令(curl 复查、gh pr create)
|
|
49
|
+
|
|
50
|
+
文档 PR #18 已创建,Node 22/24 CI 均通过,当前无待处理审查意见。
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
> **中途纠偏技巧**:由于每段汇报都会明确写明**下一步动作预告**,一旦发现它准备改错文件或方向跑偏,无需先点停止,直接在底部输入框发消息告诉它如何调整。Antigravity 会在当前命令刚结束时立即拦截原路线并按你的新指示转向。
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 安装方式
|
|
58
|
+
|
|
59
|
+
### 方式一:通过 `npx` 一键安装(推荐)
|
|
60
|
+
|
|
61
|
+
自动跨平台(Windows / macOS / Linux)将插件安装到 `~/.gemini/config/plugins/codex-worklog`:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npx antigravity-codex-worklog@latest
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
查看安装状态与文件完整性:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npx antigravity-codex-worklog@latest status
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 方式二:通过 `git clone` 安装
|
|
74
|
+
|
|
75
|
+
将仓库直接克隆到 Antigravity 全局插件目录(`~/.gemini/config/plugins/codex-worklog`):
|
|
76
|
+
|
|
77
|
+
#### Windows (PowerShell)
|
|
78
|
+
|
|
79
|
+
```powershell
|
|
80
|
+
git clone https://github.com/lemonxiny55/antigravity-codex-worklog.git "$env:USERPROFILE\.gemini\config\plugins\codex-worklog"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
#### macOS / Linux
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
git clone https://github.com/lemonxiny55/antigravity-codex-worklog.git ~/.gemini/config/plugins/codex-worklog
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### 启用生效
|
|
90
|
+
|
|
91
|
+
1. 重启 Antigravity(或重载服务端后新开会话),系统会自动发现并加载该全局插件。
|
|
92
|
+
2. 在左侧 **Skills & Customizations** 面板中找到 **Codex Worklog Commentary**,可随时一键开启或关闭,无需手动删文件。
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 更新与卸载
|
|
97
|
+
|
|
98
|
+
### 更新到最新版
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
# 通过 npx 一键更新
|
|
102
|
+
npx antigravity-codex-worklog@latest update
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
```powershell
|
|
106
|
+
# 或通过 git 更新(Windows PowerShell)
|
|
107
|
+
git -C "$env:USERPROFILE\.gemini\config\plugins\codex-worklog" pull
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
# 或通过 git 更新(macOS / Linux)
|
|
112
|
+
git -C ~/.gemini/config/plugins/codex-worklog pull
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### 彻底卸载
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
# 通过 npx 一键卸载
|
|
119
|
+
npx antigravity-codex-worklog@latest uninstall
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
```powershell
|
|
123
|
+
# 或手动卸载(Windows PowerShell)
|
|
124
|
+
Remove-Item -Recurse -Force "$env:USERPROFILE\.gemini\config\plugins\codex-worklog"
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# 或手动卸载(macOS / Linux)
|
|
129
|
+
rm -rf ~/.gemini/config/plugins/codex-worklog
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 仓库结构
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
antigravity-codex-worklog/
|
|
138
|
+
├── package.json # npm 包配置与 npx CLI 入口
|
|
139
|
+
├── plugin.json # Antigravity 插件清单
|
|
140
|
+
├── bin/
|
|
141
|
+
│ └── cli.mjs # 零依赖跨平台一键安装/更新/卸载脚本
|
|
142
|
+
├── rules/
|
|
143
|
+
│ └── AGENTS.md # 全局常驻穿插式工程日志规范(无 frontmatter)
|
|
144
|
+
├── assets/
|
|
145
|
+
│ └── logo.svg # 适配深浅双主题的矢量图标
|
|
146
|
+
├── README.md # 英文说明文档
|
|
147
|
+
├── README.zh-CN.md # Chinese documentation
|
|
148
|
+
├── LICENSE # MIT 开源协议
|
|
149
|
+
└── .gitignore
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## 开源协议
|
|
155
|
+
|
|
156
|
+
[MIT](./LICENSE) © 2026 [lemonxiny55](https://github.com/lemonxiny55)
|
package/assets/logo.svg
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" fill="none">
|
|
2
|
+
<!-- High-contrast rounded badge with ~10% outer transparent margin -->
|
|
3
|
+
<rect x="14" y="14" width="100" height="100" rx="22" fill="#18181B" stroke="#52525B" stroke-width="2" />
|
|
4
|
+
|
|
5
|
+
<!-- Subtle vertical timeline spine linking tool & commentary rows -->
|
|
6
|
+
<line x1="34" y1="36" x2="34" y2="92" stroke="#3F3F46" stroke-width="2" stroke-linecap="round" />
|
|
7
|
+
|
|
8
|
+
<!-- Row 1: Cyan terminal chevron (>_) + muted tool execution pill -->
|
|
9
|
+
<path d="M29 33L35 37L29 41" stroke="#22D3EE" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
|
|
10
|
+
<line x1="38" y1="41" x2="44" y2="41" stroke="#22D3EE" stroke-width="2.4" stroke-linecap="round" />
|
|
11
|
+
<rect x="50" y="33" width="46" height="8" rx="4" fill="#27272A" stroke="#3F3F46" stroke-width="1" />
|
|
12
|
+
<rect x="54" y="36" width="22" height="2" rx="1" fill="#A1A1AA" />
|
|
13
|
+
|
|
14
|
+
<!-- Row 2: Interleaved visible commentary lines -->
|
|
15
|
+
<circle cx="34" cy="56" r="3.5" fill="#F4F4F5" />
|
|
16
|
+
<rect x="44" y="53" width="54" height="5" rx="2.5" fill="#F4F4F5" />
|
|
17
|
+
<rect x="44" y="63" width="40" height="5" rx="2.5" fill="#D4D4D8" />
|
|
18
|
+
|
|
19
|
+
<!-- Row 3: Second compact tool pill + emerald verified status dot -->
|
|
20
|
+
<rect x="30" y="79" width="8" height="8" rx="2" fill="#27272A" stroke="#22D3EE" stroke-width="1.5" />
|
|
21
|
+
<rect x="44" y="79" width="38" height="8" rx="4" fill="#27272A" stroke="#3F3F46" stroke-width="1" />
|
|
22
|
+
<rect x="48" y="82" width="18" height="2" rx="1" fill="#A1A1AA" />
|
|
23
|
+
<circle cx="92" cy="83" r="4.5" fill="#34D399" />
|
|
24
|
+
|
|
25
|
+
<!-- Row 4: Final verified outcome bar -->
|
|
26
|
+
<circle cx="34" cy="95" r="2.5" fill="#34D399" />
|
|
27
|
+
<rect x="44" y="93" width="30" height="4" rx="2" fill="#71717A" />
|
|
28
|
+
</svg>
|
package/bin/cli.mjs
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import fs from "node:fs";
|
|
4
|
+
import os from "node:os";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
|
|
8
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
9
|
+
const __dirname = path.dirname(__filename);
|
|
10
|
+
const PACKAGE_ROOT = path.resolve(__dirname, "..");
|
|
11
|
+
|
|
12
|
+
const PLUGIN_DIR_NAME = "codex-worklog";
|
|
13
|
+
const PLUGIN_FILES = [
|
|
14
|
+
"plugin.json",
|
|
15
|
+
"rules/AGENTS.md",
|
|
16
|
+
"assets/logo.svg",
|
|
17
|
+
"README.md",
|
|
18
|
+
"README.zh-CN.md",
|
|
19
|
+
"LICENSE",
|
|
20
|
+
];
|
|
21
|
+
|
|
22
|
+
function readManifest(rootDir) {
|
|
23
|
+
const manifestPath = path.join(rootDir, "plugin.json");
|
|
24
|
+
return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function getDefaultTargetDir() {
|
|
28
|
+
return path.join(os.homedir(), ".gemini", "config", "plugins", PLUGIN_DIR_NAME);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function parseArgs(argv) {
|
|
32
|
+
let command = "install";
|
|
33
|
+
let targetDir = getDefaultTargetDir();
|
|
34
|
+
let smokeTest = false;
|
|
35
|
+
|
|
36
|
+
for (let i = 0; i < argv.length; i += 1) {
|
|
37
|
+
const arg = argv[i];
|
|
38
|
+
if (arg === "install" || arg === "update") {
|
|
39
|
+
command = "install";
|
|
40
|
+
} else if (arg === "uninstall" || arg === "remove") {
|
|
41
|
+
command = "uninstall";
|
|
42
|
+
} else if (arg === "status") {
|
|
43
|
+
command = "status";
|
|
44
|
+
} else if (arg === "--help" || arg === "-h" || arg === "help") {
|
|
45
|
+
command = "help";
|
|
46
|
+
} else if (arg === "--version" || arg === "-v") {
|
|
47
|
+
command = "version";
|
|
48
|
+
} else if (arg === "--target" && argv[i + 1]) {
|
|
49
|
+
targetDir = path.resolve(argv[i + 1]);
|
|
50
|
+
i += 1;
|
|
51
|
+
} else if (arg.startsWith("--target=")) {
|
|
52
|
+
targetDir = path.resolve(arg.slice("--target=".length));
|
|
53
|
+
} else if (arg === "--smoke-test") {
|
|
54
|
+
smokeTest = true;
|
|
55
|
+
} else {
|
|
56
|
+
throw new Error(`Unknown argument: ${arg}`);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
return { command, targetDir, smokeTest };
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function printHelp(version) {
|
|
64
|
+
console.log(`antigravity-codex-worklog v${version}
|
|
65
|
+
Codex-style interleaved progress commentary plugin installer for Google Antigravity.
|
|
66
|
+
|
|
67
|
+
Usage:
|
|
68
|
+
npx antigravity-codex-worklog [command] [options]
|
|
69
|
+
|
|
70
|
+
Commands:
|
|
71
|
+
install, update Install or update plugin in ~/.gemini/config/plugins/codex-worklog (default)
|
|
72
|
+
status Check installation status and version
|
|
73
|
+
uninstall, remove Remove the installed plugin directory
|
|
74
|
+
help Show this help message
|
|
75
|
+
|
|
76
|
+
Options:
|
|
77
|
+
--target <dir> Custom target plugin directory
|
|
78
|
+
-v, --version Print package version
|
|
79
|
+
-h, --help Show this help message`);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export function installPlugin(targetDir = getDefaultTargetDir()) {
|
|
83
|
+
const manifest = readManifest(PACKAGE_ROOT);
|
|
84
|
+
const existed = fs.existsSync(path.join(targetDir, "plugin.json"));
|
|
85
|
+
|
|
86
|
+
for (const relPath of PLUGIN_FILES) {
|
|
87
|
+
const src = path.join(PACKAGE_ROOT, relPath);
|
|
88
|
+
const dest = path.join(targetDir, relPath);
|
|
89
|
+
fs.mkdirSync(path.dirname(dest), { recursive: true });
|
|
90
|
+
fs.copyFileSync(src, dest);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
console.log(
|
|
94
|
+
`[codex-worklog] ${existed ? "Updated" : "Installed"} ${manifest.displayName} v${manifest.version}`
|
|
95
|
+
);
|
|
96
|
+
console.log(`[codex-worklog] Target: ${targetDir}`);
|
|
97
|
+
console.log(
|
|
98
|
+
`[codex-worklog] Restart Antigravity or start a new session, then check Skills & Customizations -> Codex Worklog Commentary.`
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export function uninstallPlugin(targetDir = getDefaultTargetDir()) {
|
|
103
|
+
if (!fs.existsSync(targetDir)) {
|
|
104
|
+
console.log(`[codex-worklog] Not installed at ${targetDir}`);
|
|
105
|
+
return;
|
|
106
|
+
}
|
|
107
|
+
fs.rmSync(targetDir, { recursive: true, force: true });
|
|
108
|
+
console.log(`[codex-worklog] Removed plugin directory: ${targetDir}`);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export function checkStatus(targetDir = getDefaultTargetDir()) {
|
|
112
|
+
const manifestPath = path.join(targetDir, "plugin.json");
|
|
113
|
+
if (!fs.existsSync(manifestPath)) {
|
|
114
|
+
console.log(`[codex-worklog] Status: not installed (${targetDir})`);
|
|
115
|
+
return false;
|
|
116
|
+
}
|
|
117
|
+
const installed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
|
|
118
|
+
const missing = PLUGIN_FILES.filter(
|
|
119
|
+
(relPath) => !fs.existsSync(path.join(targetDir, relPath))
|
|
120
|
+
);
|
|
121
|
+
console.log(
|
|
122
|
+
`[codex-worklog] Status: installed v${installed.version} at ${targetDir}`
|
|
123
|
+
);
|
|
124
|
+
if (missing.length > 0) {
|
|
125
|
+
console.log(`[codex-worklog] Missing files: ${missing.join(", ")}`);
|
|
126
|
+
return false;
|
|
127
|
+
}
|
|
128
|
+
console.log(`[codex-worklog] Integrity: all ${PLUGIN_FILES.length} plugin files verified.`);
|
|
129
|
+
return true;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
function runSmokeTest() {
|
|
133
|
+
const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "codex-worklog-smoke-"));
|
|
134
|
+
const targetDir = path.join(tmpRoot, PLUGIN_DIR_NAME);
|
|
135
|
+
try {
|
|
136
|
+
installPlugin(targetDir);
|
|
137
|
+
if (!checkStatus(targetDir)) {
|
|
138
|
+
throw new Error("Smoke test status check failed after install");
|
|
139
|
+
}
|
|
140
|
+
uninstallPlugin(targetDir);
|
|
141
|
+
if (fs.existsSync(targetDir)) {
|
|
142
|
+
throw new Error("Smoke test target directory still exists after uninstall");
|
|
143
|
+
}
|
|
144
|
+
console.log("[codex-worklog] Smoke test passed.");
|
|
145
|
+
} finally {
|
|
146
|
+
fs.rmSync(tmpRoot, { recursive: true, force: true });
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
function main() {
|
|
151
|
+
const manifest = readManifest(PACKAGE_ROOT);
|
|
152
|
+
const { command, targetDir, smokeTest } = parseArgs(process.argv.slice(2));
|
|
153
|
+
|
|
154
|
+
if (smokeTest) {
|
|
155
|
+
runSmokeTest();
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
switch (command) {
|
|
160
|
+
case "version":
|
|
161
|
+
console.log(manifest.version);
|
|
162
|
+
break;
|
|
163
|
+
case "help":
|
|
164
|
+
printHelp(manifest.version);
|
|
165
|
+
break;
|
|
166
|
+
case "status":
|
|
167
|
+
process.exitCode = checkStatus(targetDir) ? 0 : 1;
|
|
168
|
+
break;
|
|
169
|
+
case "uninstall":
|
|
170
|
+
uninstallPlugin(targetDir);
|
|
171
|
+
break;
|
|
172
|
+
case "install":
|
|
173
|
+
default:
|
|
174
|
+
installPlugin(targetDir);
|
|
175
|
+
break;
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
main();
|
package/package.json
CHANGED
|
@@ -1,6 +1,45 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "antigravity-codex-worklog",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Codex-style interleaved progress commentary and evidence-anchored engineering worklog plugin for Google Antigravity.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"antigravity-codex-worklog": "bin/cli.mjs",
|
|
8
|
+
"codex-worklog": "bin/cli.mjs"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"bin",
|
|
12
|
+
"rules",
|
|
13
|
+
"assets",
|
|
14
|
+
"plugin.json",
|
|
15
|
+
"README.md",
|
|
16
|
+
"README.zh-CN.md",
|
|
17
|
+
"LICENSE"
|
|
18
|
+
],
|
|
19
|
+
"scripts": {
|
|
20
|
+
"test": "node ./bin/cli.mjs --smoke-test"
|
|
21
|
+
},
|
|
22
|
+
"keywords": [
|
|
23
|
+
"antigravity",
|
|
24
|
+
"antigravity-plugin",
|
|
25
|
+
"google-antigravity",
|
|
26
|
+
"codex",
|
|
27
|
+
"worklog",
|
|
28
|
+
"commentary",
|
|
29
|
+
"ai-agent",
|
|
30
|
+
"coding-agent"
|
|
31
|
+
],
|
|
32
|
+
"author": "lemonxiny55",
|
|
33
|
+
"license": "MIT",
|
|
34
|
+
"engines": {
|
|
35
|
+
"node": ">=18.0.0"
|
|
36
|
+
},
|
|
37
|
+
"repository": {
|
|
38
|
+
"type": "git",
|
|
39
|
+
"url": "git+https://github.com/lemonxiny55/antigravity-codex-worklog.git"
|
|
40
|
+
},
|
|
41
|
+
"homepage": "https://github.com/lemonxiny55/antigravity-codex-worklog",
|
|
42
|
+
"bugs": {
|
|
43
|
+
"url": "https://github.com/lemonxiny55/antigravity-codex-worklog/issues"
|
|
44
|
+
}
|
|
45
|
+
}
|
package/plugin.json
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "codex-worklog",
|
|
3
|
+
"displayName": "Codex Worklog Commentary",
|
|
4
|
+
"description": "Codex-style interleaved progress commentary and evidence-anchored engineering worklog narration between tool calls for Antigravity.",
|
|
5
|
+
"version": "0.2.0",
|
|
6
|
+
"logo": "assets/logo.svg",
|
|
7
|
+
"author": "lemonxiny55",
|
|
8
|
+
"homepage": "https://github.com/lemonxiny55/antigravity-codex-worklog",
|
|
9
|
+
"repository": "https://github.com/lemonxiny55/antigravity-codex-worklog",
|
|
10
|
+
"suggestedPrompts": [
|
|
11
|
+
"Audit this repository's build and test pipeline with step-by-step worklog updates",
|
|
12
|
+
"Trace and fix the failing test while narrating each verification milestone",
|
|
13
|
+
"Refactor this module safely in small batches with progress commentary"
|
|
14
|
+
]
|
|
15
|
+
}
|
package/rules/AGENTS.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Codex-Style Interleaved Commentary & Worklog Protocol
|
|
2
|
+
|
|
3
|
+
When performing multi-step tasks (codebase exploration, debugging, file edits, builds/tests, or automation), narrate progress using **Codex-style interleaved engineering commentary** instead of running many tools silently and summarizing only at the end.
|
|
4
|
+
|
|
5
|
+
## 1. Visible Channel Discipline
|
|
6
|
+
|
|
7
|
+
- Always emit progress commentary in the **visible assistant message text** alongside your tool calls — never bury status updates solely inside hidden `thought`/`thinking` blocks.
|
|
8
|
+
|
|
9
|
+
## 2. Trigger & Smart Cadence
|
|
10
|
+
|
|
11
|
+
- **Skip for trivial turns**: Omit worklog narration for simple Q&A, pure explanations, or a single quick file read.
|
|
12
|
+
- **Initial Preamble**: Before the first tool batch on a multi-step task, write 2–3 sentences stating your approach, safety/scope boundaries (e.g., working directory/worktree, untouched files), and verification target.
|
|
13
|
+
- **Logical Batching**: Group related actions (typically 1–4 tool calls per batch) and emit one concise **Interleaved Progress Update** (1–3 sentences) before the next batch.
|
|
14
|
+
- **High-Latency / Mutating Preamble**: Always send a brief preamble immediately before heavy or state-changing operations (large edits, full test suites, builds, external API or git push actions).
|
|
15
|
+
|
|
16
|
+
## 3. Evidence-Anchored 3-Part Micro-Cycle
|
|
17
|
+
|
|
18
|
+
Each interleaved update must cover three concrete elements in compact prose:
|
|
19
|
+
|
|
20
|
+
1. **Facts & Evidence**: What just completed and exact observed results (counts, paths, error messages, modified parameters, pass/fail deltas, PR/CI status). Never write vague filler such as "checking files" or "working on it".
|
|
21
|
+
2. **Decision & Guardrail**: Engineering judgment derived from the evidence (why a parameter changed, deduplication checks before retrying, confirmation of untouched unrelated files).
|
|
22
|
+
3. **Next Action Preview**: The exact next step so the user can spot directional drift and steer mid-execution.
|
|
23
|
+
|
|
24
|
+
## 4. Anti-Premature-Termination Guardrail
|
|
25
|
+
|
|
26
|
+
- Never end a turn immediately after emitting an interim commentary update.
|
|
27
|
+
- Always attach the next tool call(s) in the **same model response** as your progress update, unless you are genuinely finished or explicitly blocked waiting for user input.
|
|
28
|
+
|
|
29
|
+
## 5. Plan-to-Execution Continuity
|
|
30
|
+
|
|
31
|
+
- When leaving Plan Mode (e.g., via `exit_plan_mode`), include a brief instruction in the plan reminding the execution phase to keep concise interleaved progress updates in visible text across edit and verification batches.
|
|
32
|
+
|
|
33
|
+
## 6. Tone, Language Mirroring & Final Delivery
|
|
34
|
+
|
|
35
|
+
- **Language Mirroring**: Always write both interim commentary and the final answer in the **user's language** (e.g., concise Chinese engineering worklog for Chinese prompts; concise English for English prompts).
|
|
36
|
+
- **Dry Engineering Worklog Tone**: Stay calm, objective, and dense in a first-person worklog style. Eliminate conversational pleasantries and filler ("Sure!", "Great!", "好的!", "没问题,我现在帮你……").
|
|
37
|
+
- **Final Answer Discipline**: Keep interim commentary separate from the final response. Lead directly with concrete changes and verified outcomes (skip redundant "Summary" headings), and **never dump full contents of newly written files** — cite file paths instead.
|