Skip to content

Commit d6120b5

Browse files
linhaylinhay
committed
docs: distill codex binary workflow
1 parent 3bb2282 commit d6120b5

5 files changed

Lines changed: 272 additions & 5 deletions

File tree

‎.agents/skills/gettokens-codex-binary-management/SKILL.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
name: gettokens-codex-binary-management
3+
description: GetTokens Codex 二进制管理：Codex CLI 版本源、下载、激活、回退、托管 PATH、release cache、版本说明和紧凑列表 UI。
4+
---
5+
6+
# GetTokens Codex Binary Management
7+
8+
当任务涉及 Codex 二进制管理、Codex CLI 版本切换、release 拉取、下载/激活流程、托管 PATH，或修改 `frontend/src/features/codex-binary` / `internal/codexbinary` 时使用本 skill。
9+
10+
## 1. 业务边界
11+
- Codex Binary 是独立业务，负责 Codex CLI 二进制源切换、下载、激活、回退、更新与变更记录。
12+
- 不接入账号池、local apply、用量、会话管理或路由策略流程。
13+
- 用户可见界面保持窄范围：
14+
- 当前启用摘要
15+
- 托管 PATH 状态
16+
- release 筛选
17+
- 单一版本列表
18+
- 下载 / 激活动作
19+
- 变更记录
20+
- 版本行更多菜单
21+
- 默认筛选为 `stable`。Alpha / prerelease 必须由用户通过筛选显式进入。
22+
23+
## 2. 数据流程
24+
- 进入页面只加载本地 snapshot/cache，不要每次进入都自动请求 GitHub releases。
25+
- `检查更新` 是显式远端刷新边界。
26+
- 远端 release 数据应写入本地缓存，后续进入页面优先复用缓存。
27+
- 历史版本必须分页拉取，不只拿最新正式版。
28+
- 优先使用 GitHub REST；REST 失败或限流时可 fallback 到 Atom / HTML release 页，但当 Atom 最近窗口几乎全是 alpha 时，仍必须能补到 stable 历史版本。
29+
- prerelease 判断不能把 `rust-v` 前缀里的连字符当成 prerelease。应检测 version/tag 中的 alpha/beta/rc/pre/preview 标记。
30+
- 版本说明必须使用 `react-markdown` + `rehype-sanitize` 安全渲染，禁止直接注入远端 HTML。
31+
32+
## 3. 下载 / 激活语义
33+
- 下载和激活是两个独立动作。
34+
- 远端未安装版本显示 `下载`。
35+
- 下载中的版本隐藏下载/激活按钮，只显示阶段、百分比和大小进度。
36+
- 已下载版本显示 `激活`。
37+
- 旧版本在 UI 中仍显示 `激活`。内部可保留 rollback 语义用于 action 推导和成功提示测试。
38+
- 下载完成后只导入托管版本目录，不自动激活；除非后续需求明确改变。
39+
- 下载或导入失败不能破坏当前 active shim。
40+
- 当前启用版本不能删除，前端和后端都必须阻止。
41+
42+
## 4. Managed PATH
43+
- 不假设用户一定使用 `~/.zshrc`。
44+
- 后端负责识别 shell/profile 目标：
45+
- zsh：优先现有 `ZDOTDIR/.zshrc` / `ZDOTDIR/.zprofile`
46+
- bash：优先现有 `.bashrc` / `.bash_profile` / `.profile`
47+
- fish：使用 `XDG_CONFIG_HOME/fish/config.fish` 或 `~/.config/fish/config.fish`
48+
- 只写入 GetTokens 自己的标记 PATH block。
49+
- 写入前备份目标 profile。
50+
- 重复启用必须幂等，不能重复插入 PATH block。
51+
52+
## 5. UI 规则
53+
- Codex Binary 页面保持紧凑、操作导向，避免说明型/营销型文案堆叠。
54+
- 版本列表不要使用卡中卡布局。
55+
- 版本行布局：
56+
- 左侧：版本身份与紧凑状态
57+
- 身份附近：可用时显示文件大小
58+
- 右侧：主操作和菜单
59+
- 点击行主体展开/收起 release notes
60+
- 主操作直接放在 cell 上：
61+
- `下载`
62+
- `激活`
63+
- 次级操作放进右侧菜单：
64+
- 远端 release：在浏览器中打开
65+
- 已安装版本：在 Finder 中打开
66+
- 已安装且非当前版本：删除
67+
- 行内按钮必须阻止事件冒泡，避免误触发 release notes 展开。
68+
- 页面和长 notes 滚动区域使用稳定 scrollbar gutter，避免滚动条出现/消失导致宽度抖动。
69+
- 进度条沿用当前实现和用户最新视觉反馈；普通下载进度不要回退成错误/警告色。
70+
71+
## 6. 前端结构
72+
- `CodexBinaryFeature.tsx` 保持为 controller：
73+
- snapshot 加载
74+
- 显式远端刷新
75+
- 下载轮询
76+
- 激活/下载/删除/Finder/浏览器动作
77+
- notes 与菜单状态
78+
- 视图组件放在 `frontend/src/features/codex-binary/components/`：
79+
- summary panel
80+
- version list
81+
- version cell
82+
- release URL、任务大小等纯展示工具放入 `presentation.ts`。
83+
- 行合并、release 筛选、action 推导、任务进度、binary size 格式化保留在 `model.ts`。
84+
- 不新增 catch-all helper 文件。
85+
86+
## 7. 后端 / Wails 边界
87+
- 领域逻辑放在 `internal/codexbinary`。
88+
- Wails-facing 方法放在 `internal/wailsapp`，随后必须通过 root `app.go`、必要的 root DTO/mapper 和前端 generated bindings 暴露。
89+
- Wails 生成的 `frontend/wailsjs/go/models.ts` 可能带尾随空白；交付前运行：
90+
- `perl -i -pe 's/[ \t]+$//' frontend/wailsjs/go/models.ts`
91+
- `perl -0pi -e 's/\n[ \t]*\n\z/\n/' frontend/wailsjs/go/models.ts`
92+
- `git diff --check`
93+
94+
## 8. 验证
95+
- 仅前端结构或 UI 调整：
96+
- `npm --prefix frontend run typecheck`
97+
- `npm --prefix frontend run test:unit -- src/features/codex-binary/model.test.mjs`
98+
- `npm --prefix frontend run build`
99+
- 浏览器预览检查 `http://localhost:34115/#frame=codex&workspace=binary-management`
100+
- 后端、DTO 或 Wails 调整：
101+
- 跑 `internal/codexbinary` / `internal/wailsapp` 相关 Go 测试
102+
- 影响 shared Wails/root binding 时跑 `go test ./...`
103+
- public Wails DTO/方法形状变化后重新生成 bindings
104+
- 视觉调整截图放到 `docs-linhay/spaces/20260511-codex-binary-management/screenshots/<YYYYMMDD>/codex-binary/`。
105+
106+
## 9. 文档
107+
- 需求、范围、实施状态、截图和未完成项写入 `docs-linhay/spaces/20260511-codex-binary-management/README.md`。
108+
- 稳定决策写入 `docs-linhay/memory/YYYY-MM-DD.md`。
109+
- 文档或记忆写回后运行 `qmd update` 与 `qmd embed`。

‎.agents/skills/gettokens-domain-engineering/SKILL.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,24 @@ This skill unifies the technical rules for building, styling, and debugging GetT
7777
- `auth.json` uses field-level merge
7878
- do not rewrite the whole file and destroy user ordering, comments, or unknown fields
7979

80+
## 3.1 Codex Workspace & Local Config Surfaces
81+
- **Codex Binary**: For Codex CLI binary version/source management, use the dedicated `gettokens-codex-binary-management` skill. Keep it as an independent binary-management business; do not merge it into account pool, local apply, usage, session, or routing flows.
82+
- **Browser Support**: New Codex workspace tabs must be usable in a normal browser preview when the interaction is layout/config-flow checkable. Do not let missing `window.go.main.App` make the page blank; provide explicit preview data and visible preview-only save behavior.
83+
- **Frame URL Rule**: Modal/detail layers opened from Codex workspaces should preserve the frame hash, for example `#frame=codex&workspace=<key>&detail=<id>`, when the surrounding feature already follows frame/detail routing. Closing a modal should remove only the detail marker.
84+
- **Wails Binding Boundary**: Any Wails-facing Codex method added under `internal/wailsapp` must also be exposed through root `app.go`, mirrored in root DTOs/mappers when needed, and regenerated into `frontend/wailsjs`. Frontend should import from generated bindings only after the root `main.App` method exists.
85+
- **Raw + Structured Config Editors**:
86+
- If a page provides both a structured editor and a raw `config.toml` editor, saving either path must reload or resync the other path before showing success.
87+
- Browser preview raw editors should edit in-memory preview text and label the result as preview-only; desktop editors should read/write the real file through Wails.
88+
- Raw saves must not bypass structured validation for later structured edits. After raw save, re-read the parsed snapshot and surface TOML errors instead of keeping stale rows.
89+
- **MCP Config Semantics**:
90+
- `[mcp_servers.<id>.tools.<tool>]` belongs to the parent server and must not be rendered as a separate server row.
91+
- `bearer_token` is not a valid Codex MCP field for saved config; prompt for `bearer_token_env_var` instead.
92+
- Preserve unknown fields and non-MCP config when patching a single server section.
93+
- **Skills UI Semantics**:
94+
- Skills list rows should be whole-row detail entries. Nested toggles must stop propagation and stay semantically independent.
95+
- Skill detail is a modal/detail layer, not a permanent right column. Keep source/root/file metadata in the modal when the list row would otherwise become too dense.
96+
- Render `SKILL.md` with the existing safe Markdown stack (`react-markdown` + `rehype-sanitize`) after stripping front matter; do not inject raw HTML.
97+
8098
## 4. Quota Rules
8199
- **Path**: `AccountsPage` -> `GetCodexQuota` -> Wails -> `POST /v0/management/api-call`.
82100
- **Logic**: CLIProxyAPI injects token via `auth_index` for target `chatgpt.com/backend-api/wham/usage`.

‎docs-linhay/dev/20260514-codex-binary-session-distillation.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Codex Binary 会话蒸馏
2+
3+
## 背景
4+
5+
本轮围绕 Codex 二进制管理从设计、业务边界、远端版本拉取、下载/激活、托管 PATH、版本 cell UI、菜单操作、进度展示到前端拆文件完成了一整轮迭代。用户明确要求“蒸馏会话，整理 skill / 行为 / 偏好 / 工作流”，因此将稳定模式沉淀为项目级 skill，并记录本次不升级到 `AGENTS.md` 的判断。
6+
7+
## 沉淀为 Skill 的内容
8+
9+
新增项目级 skill：
10+
11+
- `.agents/skills/gettokens-codex-binary-management/SKILL.md`
12+
13+
覆盖范围：
14+
15+
- Codex Binary 独立业务边界。
16+
- GitHub Releases / Atom / HTML fallback 与本地缓存策略。
17+
- 下载与激活分离。
18+
- 一键托管 PATH 的 shell/profile 识别边界。
19+
- 紧凑版本列表 UI、更多菜单、release notes 展开方式。
20+
- 前端拆分结构：controller、components、presentation、model。
21+
- Wails/root binding 约束与生成文件空白清理。
22+
- 自动化验证与截图落位。
23+
24+
同时在 `.agents/skills/gettokens-domain-engineering/SKILL.md` 的 Codex workspace 区域补了指向，避免后续 Codex Binary 需求继续被塞进通用工程规则。
25+
26+
## 行为与偏好
27+
28+
本轮稳定偏好：
29+
30+
- 全程中文交付与中文文案。
31+
- Codex Binary 页面应极简、紧凑，主要只显示下载、激活和变更记录。
32+
- 下载、激活是两个独立阶段，不同时显示在同一个未安装版本上。
33+
- 次级动作放在右侧菜单，主按钮只保留当前阶段最关键动作。
34+
- 不要卡中卡，不要解释性文案堆叠，不要把操作台做成营销页。
35+
- 默认看正式版，Alpha 通过筛选进入。
36+
- 不要每次进入页面都刷新 GitHub，显式点击“检查更新”才远端拉取。
37+
- 需要真实页面截图/浏览器核对来判断 UI 是否可接受。
38+
- 复杂前端文件要及时拆成 controller、组件和展示工具，避免单文件继续膨胀。
39+
40+
## 工作流
41+
42+
后续同类需求推荐流程：
43+
44+
1. 先确认是否属于 Codex Binary 独立业务；若涉及账号池、local apply、用量或会话，默认不并入。
45+
2. 更新对应 space 的需求、验收标准或实施状态。
46+
3. 后端先保证 `internal/codexbinary` 领域服务和 Wails/root binding 闭环。
47+
4. 前端保持 `CodexBinaryFeature.tsx` 为 controller，复杂视图拆到 `components/`，纯展示逻辑放 `presentation.ts`。
48+
5. UI 调整后必须看真实页面，不只靠代码推断。
49+
6. 运行相关前端/Go 测试；若触碰 Wails 生成文件，清理 `models.ts` 空白并跑 `git diff --check`。
50+
7. 写回 space README、memory，并执行 `qmd update` / `qmd embed`。
51+
52+
## 不纳入的临时内容
53+
54+
以下内容暂不升级为长期规则：
55+
56+
- 本轮具体截图文件名和每一次版本 cell 的中间布局方案。
57+
- “绿色进度条”等单点视觉争议的历史讨论，只在 skill 中保留当前实现应避免回退到异常/警告色的原则。
58+
- 是否未来支持取消下载、事件推送、断点续传。这些仍是需求待办，不作为已完成规则。
59+
- AGENTS 级规则不更新；本轮沉淀主要是功能域工作流，不是全仓统一硬约束。
60+
61+
## 后续入口
62+
63+
- Codex Binary 需求：优先使用 `gettokens-codex-binary-management`。
64+
- 文档、space、memory、qmd：继续使用 `gettokens-ops-governance`。
65+
- 会话整理：继续使用 `gettokens-session-skill-distill`。

‎docs-linhay/memory/2026-05-14.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# 2026-05-14
2+
3+
## 会话蒸馏
4+
5+
- 用户要求“蒸馏会话，整理 skill / 行为 / 偏好 / 工作流”。已将 Codex Binary 本轮稳定模式沉淀为项目级 skill：`.agents/skills/gettokens-codex-binary-management/SKILL.md`。
6+
- 新 skill 覆盖 Codex Binary 独立业务边界、远端 release/cache、下载与激活分离、托管 PATH、紧凑版本列表 UI、前端拆分结构、Wails/root binding、验证与文档写回。
7+
- 已在 `gettokens-domain-engineering` 的 Codex workspace 章节补充指向：Codex CLI 二进制管理需求优先使用专用 skill，不并入账号池、local apply、用量、会话或路由流程。
8+
- 已新增 `docs-linhay/dev/20260514-codex-binary-session-distillation.md`，记录本轮沉淀内容、用户偏好、后续工作流和不纳入 AGENTS 的临时内容。
9+
- 本轮未更新 `AGENTS.md`：结论是这些规则属于 Codex Binary 功能域工作流，尚未上升为全仓长期硬约束。

0 commit comments

Comments
 (0)