mac
83 lines
4.0 KiB
Markdown
83 lines
4.0 KiB
Markdown
# Codex 插件市场 —— 桌面客户端
|
||
|
||
跨平台（macOS / Windows / Linux）的 Codex 插件 · 技能 **备份 / 分享 / 一键安装** 工具。
|
||
基于 Electron，全部逻辑本地运行；凭证只存在本机（系统安全存储加密）。
|
||
|
||
## 功能
|
||
- **插件市场**：浏览官方市场，搜索 / 筛选，一键安装到 `~/.codex` 并自动启用。
|
||
- **从本机导出 / 上传**：扫描本机插件与技能，勾选后导出到本地目录，或打包推送到 GitHub 并自动登记到市场。**凭证文件（auth.json / config.toml / history 等）已自动排除。**
|
||
- **从 GitHub 拉取还原**：输入任意仓库，拉取后勾选还原到本机，可选自动在 `config.toml` 启用。
|
||
- **设置**：保存默认 GitHub Token（`safeStorage` 加密存储）。
|
||
- **会话记忆**：软件开着就自动工作——监视 `~/.codex/sessions`，每次会话告一段落（静默几分钟）后自动浓缩成「交接摘要」：
|
||
存入本机 SQLite 记忆库（可检索），并写到对应项目根目录的 `HANDOFF.md`（状态快照），同时在项目 `AGENTS.md` 里加一段
|
||
「先读 HANDOFF」引导。之后**新开 Codex 会话说「继续」，就能接上之前聊的**，不用带着超长上下文。
|
||
摘要优先调用「路由中转」当前分组的 LLM，未配置或失败时退化为本地规则提取；可全局或按项目关闭。
|
||
|
||
## 开发运行
|
||
```bash
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
## 打包分发
|
||
```bash
|
||
# 当前平台
|
||
npm run dist
|
||
|
||
# 指定平台（需对应系统或已配置交叉编译）
|
||
npm run dist:mac # 产出 dist/*.dmg（x64 + arm64）
|
||
npm run dist:win # 产出 dist/*Setup.exe
|
||
```
|
||
产物在 `dist/`。打包配置见 `electron-builder.yml`，图标在 `build/`（icns/ico/png）。
|
||
|
||
## macOS 首次打开报「已损坏，移到废纸篓」
|
||
|
||
**这不是包坏了。** 本应用未购买 Apple 开发者证书、未做公证(notarization)，
|
||
只有临时(ad-hoc)签名。macOS 对「从网上下载」的这类 app 会自动加隔离标记
|
||
(`com.apple.quarantine`) 并由 Gatekeeper 拦截，在 Apple 芯片上表现为「已损坏」。
|
||
|
||
**解决**：把 app 拖到「应用程序」后，双击 DMG 里的 `fix-quarantine.command`，或在「终端」执行一次（去掉隔离标记）：
|
||
|
||
```bash
|
||
xattr -cr "/Applications/TD工具箱.app"
|
||
```
|
||
|
||
之后正常双击即可打开，只需做一次。（若提示权限不足，命令前加 `sudo ` 再回车输入开机密码。）
|
||
|
||
DMG 里同时放了 `激活教程.txt`，客户可以先看这个文件再操作。
|
||
|
||
> 想彻底免掉这一步、让用户双击即开，需要 Apple Developer 账号($99/年)做
|
||
> Developer ID 签名 + 公证，届时在 `electron-builder.yml` 的 `mac` 段配置证书即可。
|
||
|
||
## GitHub Token 说明
|
||
上传功能需要 **classic** personal access token，并勾选最上面的 **repo** 复选框：
|
||
<https://github.com/settings/tokens>
|
||
|
||
- 传**公开**仓库：`public_repo` 权限即可。
|
||
- 传**私有**仓库：需要完整 `repo` 权限。
|
||
- fine-grained token 目前不受支持（推送会失败），请用 classic token。
|
||
|
||
安装公开仓库的插件无需任何 token；安装私有仓库需在「设置」里保存 token。
|
||
|
||
## 项目结构
|
||
```
|
||
electron/
|
||
main.js 主进程：窗口 + IPC + GitHub(isomorphic-git) + 市场 API
|
||
preload.js 契约边界，暴露 window.api（冻结）
|
||
lib/
|
||
codex.js 扫描 / 打包 / 还原 / config.toml 启用
|
||
secrets.js safeStorage 密钥存储
|
||
renderer/
|
||
index.html UI 结构
|
||
styles.css 深色为主 · 靛蓝→紫渐变
|
||
app.js 前端逻辑（只经 window.api.*）
|
||
build/ 打包图标
|
||
electron-builder.yml 打包配置
|
||
CONTRACT.md 前后端 / 分工契约（唯一事实来源）
|
||
```
|
||
|
||
## 隐私
|
||
- 市场地址与密钥只存在于主进程，不出现在前端代码。
|
||
- 打包上传时严格排除：`auth.json`、`config.toml`、`history.jsonl`、`*.sqlite*`、`*.log`、`*.bak`、`.DS_Store`、`installation_id`。
|
||
- 还原写入 `config.toml` 前会自动备份为 `config.toml.bak-exporter`。
|