|
| 1 | +--- |
| 2 | +name: gettokens-codex-extensions-management |
| 3 | +description: GetTokens Codex Skills / MCP 扩展管理：源码校准解析、全局 Skill roots、MCP section/tool 语义、Git source、UI 验收与整理拆分。 |
| 4 | +--- |
| 5 | + |
| 6 | +# GetTokens Codex Extensions Management |
| 7 | + |
| 8 | +用于实现、审查或整理 Codex `Skills` / `MCP Servers` 工作区。触发词包括：Codex skills、MCP servers、`~/.codex/config.toml`、`[[skills.config]]`、`tk://github.com`、`tk://gitlab.com`、Skill 预览/移除/更新。 |
| 9 | + |
| 10 | +## 1. Source Truth |
| 11 | +- 先读当前仓库实现，再核对 Codex 源码或已归档参考，不凭记忆补字段。 |
| 12 | +- Skills 只展示全局 roots，不展示 project / repo / git 追加 roots： |
| 13 | + - `$CODEX_HOME/skills` |
| 14 | + - `$HOME/.agents/skills` |
| 15 | + - `$CODEX_HOME/skills/.system` |
| 16 | + - `/etc/codex/skills` |
| 17 | +- MCP 列表只把 `[mcp_servers.<id>]` 一级 table 作为 server。 |
| 18 | +- `[mcp_servers.<id>.tools.<tool>]` 是 parent server 的嵌套 tool approval，不是独立 server。 |
| 19 | + |
| 20 | +## 2. Skills Rules |
| 21 | +- 只识别含 `SKILL.md` 的目录。 |
| 22 | +- `SKILL.md` 预览使用 `react-markdown` + `rehype-sanitize`，渲染前移除 YAML front matter。 |
| 23 | +- Snapshot 只返回文件路径、类型和可预览标记；文件内容必须点击单个文件后懒加载并前端缓存。 |
| 24 | +- Skill 启停使用 Codex 支持的 `[[skills.config]] enabled = false`。 |
| 25 | +- 启用 Skill 时移除匹配的禁用 override，不写 `enabled = true`。 |
| 26 | +- 移除 Skill 必须删除本地目录并校验目录不存在，否则 Codex 仍会扫描到。 |
| 27 | +- 移除需 alert dialog 二次确认，成功后关闭详情 modal 并显示短暂成功 HUD。 |
| 28 | +- Finder 打开必须校验路径属于已配置 skill roots。 |
| 29 | +- Git source 只支持显式 schema： |
| 30 | + - `tk://github.com/<owner>/<repo>?ref=<ref>&path=<skill-dir>` |
| 31 | + - `tk://gitlab.com/<namespace>/<repo>?ref=<ref>&path=<skill-dir>` |
| 32 | +- 自建 GitLab 需要 allowlist；凭据不得写入 manifest。 |
| 33 | + |
| 34 | +## 3. MCP Rules |
| 35 | +- Transport 由字段推断：`command` => `stdio`，`url` => `streamable_http`。 |
| 36 | +- `command` 与 `url` 同时存在时不能保存。 |
| 37 | +- `bearer_token` 不是 Codex MCP 保存字段；只支持 `bearer_token_env_var`。 |
| 38 | +- 保存单个 server 时只 patch 目标 section，保留未知字段、其他 server 和非 MCP 配置。 |
| 39 | +- 编辑 modal 左侧表单只展示当前 server 有值的可选字段；必填字段保留。 |
| 40 | +- 右侧当前值只展示有用值；空可选项直接忽略。 |
| 41 | +- 原始 `config.toml` 编辑器保存后必须重读结构化 snapshot，避免结构化视图用旧数据。 |
| 42 | + |
| 43 | +## 4. UI Preferences |
| 44 | +- 侧边栏内 Skills / MCP 拆成两个 tab/entry。 |
| 45 | +- 右侧主体按会话页面的信息层级组织：列表为主，详情/编辑用 modal 或 detail layer。 |
| 46 | +- 不使用多层卡片嵌套。 |
| 47 | +- 优先复用已有通用组件和全局样式： |
| 48 | + - `WorkspacePageHeader` |
| 49 | + - `SegmentedControl` |
| 50 | + - `ToggleSwitch` |
| 51 | + - `btn-swiss` |
| 52 | + - `input-swiss` |
| 53 | + - `select-swiss` |
| 54 | +- Skill 列表点击整行打开详情，嵌套 toggle 必须阻止行点击冒泡。 |
| 55 | +- modal 要有视口约束高度和底部间距；长内容在内部明确滚动，不让文件切换导致整个页面跳动。 |
| 56 | + |
| 57 | +## 5. Split & Cleanup Pattern |
| 58 | +- 前端大文件优先按稳定边界拆： |
| 59 | + - `CodexExtensionsFeature.tsx`：页面 controller、列表、加载保存调度。 |
| 60 | + - `SkillsModals.tsx`：Skill 预览、Git 安装、删除确认、成功 HUD。 |
| 61 | + - `McpModals.tsx`：MCP server editor、config TOML editor、MCP 字段组件。 |
| 62 | + - `adapters.ts`：Wails DTO 与前端 model 互转、clone、来源格式化。 |
| 63 | + - `model.ts`：纯解析/序列化/dirty diff 逻辑。 |
| 64 | +- 后端大文件第一刀优先移动 DTO / 内部结构体到 `*_types.go`，保持 Wails 方法签名和解析函数行为不变。 |
| 65 | +- 不在同一轮把 UI 拆分、解析算法重写、存储 schema 迁移混在一起。 |
| 66 | + |
| 67 | +## 6. Verification |
| 68 | +- 前端结构调整后至少运行： |
| 69 | + - `npm run typecheck` |
| 70 | + - `npm run test:unit -- src/features/codex-extensions/model.test.mjs` |
| 71 | +- 后端 Codex extensions 变更后至少运行： |
| 72 | + - `go test ./internal/wailsapp -run 'Codex|Mcp|Skill'` |
| 73 | +- 视觉/交互变化需要浏览器或 Wails 实际截图，截图归档到对应 `space/screenshots/`。 |
| 74 | +- 收尾时更新 space README、`docs-linhay/dev/`、`docs-linhay/memory/YYYY-MM-DD.md`，再执行 `qmd update` 与 `qmd embed`。 |
0 commit comments