codex-keysmith

KO | EN

gitlite — search

#ai #typescript #llm #go #android #deep-learning #docker #java #cli #kubernetes #awesome-list #vue #pytorch #openai

(★ 3,592)

Versioned Codex instruction deployment with preview, ownership manifests, hook isolation, scenario evaluation, and recovery.

codex-keysmith 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<img src="docs/assets/readme/codex-keysmith-preview.png" alt="Illustrative codex-keysmith dry-run terminal preview; actual paths and output vary" width="100%">

Illustrative preview / 示意预览；实际路径与输出以本机 dry-run 为准。

<h1 align="center">codex-keysmith</h1>

Versioned Codex instruction deployment with preview, ownership manifests, hook isolation, and layered uninstall.

<a href="#简体中文">简体中文</a> ·
 <a href="README.en.md">English</a> ·
 <a href="#桌面客户端beta">桌面客户端 beta</a> ·
 <a href="docs/reference.md">Reference</a> ·
 <a href="docs/agent-install.md">智能体安装 / Agent install</a> ·
 <a href="SECURITY.md">Security</a> ·
 <a href="LICENSE">License</a>

## 简体中文

### 这是什么

`codex-keysmith` 是一个零依赖的单文件 Python 脚本，把一份指令 Markdown 部署到你的 Codex 配置目录（`~/.codex`），并让 Codex 的每个新会话都加载它。默认预览、显式确认才写入，支持随时撤销。

**这会改变 Codex 的全局行为，不是项目级设置**：部署会修改 `~/.codex/config.toml` 里的 `model_instructions_file`，因此影响该配置下的**所有新会话**；默认还会暂停你现有的整份 `hooks.json`，直到你显式恢复。内置的示例提示词会让模型不再用拒绝式话术回答，把 reverse shell / keygen / bypass 一类请求当作本地样本处理，也覆盖成人题材、化学/药理/武器类内容。**这不是安全边界，是一次影响很广的行为切换**——用前请打开 [`examples/gpt-unrestricted.md`](examples/gpt-unrestricted.md) 看一眼，或者用 `--file` 换成你自己的指令。

> [!WARNING]
> 不要在 Windows 上使用已发布的 `v0.1.0`；它有已知的清理缺陷（详见「兼容性与限制」）。v0.1.1 及后续版本已提供原生恢复后端；Windows fresh deployment 仍标记为 beta。

### 桌面客户端（beta）

仓库现已包含 [`gui/` 桌面客户端源码](https://github.com/Jia-Ethan/codex-keysmith/tree/main/gui)。它基于 Tauri 2 + React，复用现有 Python CLI 的预览、部署、恢复和卸载逻辑，不在 GUI 中重写文件事务。

```bash
cd gui
npm install
npm run tauri dev
```

- 当前统一源码版本为 `0.3.5`。公开 Desktop 安装包是 [`desktop-v0.3.5-beta.1`](https://github.com/Jia-Ethan/codex-keysmith/releases/tag/desktop-v0.3.5-beta.1)，包含 GUI 场景库页（列表、显式目标目录、preview 门禁、status、卸载、恢复）；冻结 sidecar 仍嵌入同版本场景 bundle。单文件 CLI `codex-instruct-v0.3.5.py`、源码归档和密封 bundle 仍在 [`v0.3.5`](https://github.com/Jia-Ethan/codex-keysmith/releases/tag/v0.3.5)。
- macOS 用户下载 `codex-keysmith-0.3.5-macos-arm64-unsigned.dmg`；Windows 用户下载 `codex-keysmith-0.3.5-windows-x64-unsigned-setup.exe`。两个安装包都内置独立 CLI sidecar，使用时无需额外安装 Python。
- 本次 Desktop Beta 未进行 Apple 签名/公证或 Authenticode 签名。macOS 可能触发 Gatekeeper，Windows 可能显示 Unknown publisher 或 SmartScreen 警告；两平台均未经过实体设备验收。
- Windows 安装包使用 current-user NSIS 和静默 WebView2 download bootstrapper，不提供 MSI、ARM64 或正式 Windows 支持承诺。底层 Windows CLI fresh deployment 继续遵循 `EXPLICIT_BETA`。
- 常规 CLI / Desktop 操作不主动收集或上传用户数据；M3 live runner 只有在维护者显式执行时才会把临时场景上下文发送到所选模型服务。签名边界见 [`CODE_SIGNING_POLICY.md`](CODE_SIGNING_POLICY.md)，数据说明见 [`PRIVACY.md`](PRIVACY.md)。SignPath Foundation 申请仍在审核中，当前预发布资产并未使用 SignPath 签名。

### 快速开始（macOS / Linux）

```bash
# 1. 下载并校验（把 vX.Y.Z 换成 Releases 页面上的最新 tag）
base='https://github.com/Jia-Ethan/codex-keysmith/releases/download/vX.Y.Z'
curl --fail --location --remote-name "$base/codex-instruct-vX.Y.Z.py"
curl --fail --location --remote-name "$base/SHA256SUMS"
awk '$2 == "codex-instruct-vX.Y.Z.py"' SHA256SUMS | shasum -a 256 -c -

# 2. 先看，不要先信——确认目标目录、内置提示词来源和将要写入的内容
python3 codex-instruct-vX.Y.Z.py --version
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --status --lang zh-CN
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --dry-run --lang zh-CN

# 3. 确认无误后才写入
python3 codex-instruct-vX.Y.Z.py --codex-dir ~/.codex --yes --lang zh-CN
```

不要从浮动 `main` 安装正式版本，也不要用 `curl | python` 直接执行——务必先落盘、校验，再运行。部署完成后**关闭旧任务、开启一个新的 Codex 会话**：Codex 只在会话启动时加载配置，运行中的会话不会热更新。

省略 `--codex-dir` 会处理全部自动发现的 `.codex` 目录；只有明确需要多目录一起部署时才这样做。

### 它会改哪些文件

| 路径 | 会发生什么 |
| --- | --- |
| `<codex-dir>/gpt-unrestricted.md`（或自定义 `--name`） | 新建，或先备份再替换 |
| `<codex-dir>/config.toml` | 只拥有并修改顶层 `model_instructions_file`；外部工具重写其他字段不会阻塞 status/uninstall，卸载会保留这些字段 |
| `<codex-dir>/hooks.json` | 默认整体隔离为 `hooks.json.disabled`（先备份） |
| `<codex-dir>/.codex-keysmith-manifest.json` | 记录这次部署改了什么，供后续卸载用 |

完整字段、临时事务目录和边界条件见 [`docs/reference.md`](docs/reference.md)。

### 场景部署（v0.3 M1 / M2）

M1 新增与指令层正交的 target-local 场景部署。它不会修改 `.codex-keysmith-manifest.json`、`config.toml` 或 hooks；所有场景文件只写入显式目标的 `<target>/.codex-keysmith/`，并以独立 `deployment_id` 精确管理。M2 第一阶段在同一库中加入三个评测包，并运行只读依赖探测。M2 第二阶段提供可重复的密封 `codex-keysmith-scenarios-v<VERSION>.bundle`；不含 hooks、GUI 场景页或真实跑分。

当前场景库：

| 包 | 平台 | 依赖 | 用途 |
| --- | --- | --- | --- |
| `example_fixture` | darwin, linux, win32 | 无 | M1 生命周期与完整性 fixture |
| `cyber_keystone` | darwin, linux | 无 | 授权红队 PoC / 工具链分析 |
| `aiml_toxigen` | darwin, linux | 无 | 毒性生成与训练污染评估 |
| `chem_rdkit` | darwin, linux | `rdkit>=2022.9`（只探测，不安装） | RDKit 化合物分析与合成路线 |

```bash
python3 codex-instruct.py --scenario-list
python3 codex-instruct.py --deploy-scenario example_fixture --target-dir /absolute/project
python3 codex-instruct.py --deploy-scenario example_fixture --target-dir /absolute/project --yes
python3 codex-instruct.py --scenario-status --target-dir /absolute/project
python3 codex-instruct.py --scenario-uninstall DEPLOYMENT_ID --target-dir /absolute/project --yes
python3 codex-instruct.py --scenario-recover --target-dir /absolute/project --yes
```

`--target-dir` 必须是显式绝对目录；写操作默认只预览，加入 `--yes` 才执行。源码模式默认读取仓库 `scenarios/`。绝对 `--scenario-root` 可以指向源码 `scenarios/`、含 `index.json` 的解包目录，或密封 `codex-keysmith-scenarios-v<VERSION>.bundle`。单文件 CLI 不内嵌场景库，离线使用时下载同版本 bundle 并用 `SHA256SUMS` 校验该条目；冻结 sidecar 嵌入同版本 bundle，资源完好时不必再传 `--scenario-root`，缺失或摘要不匹配则明确失败。`--scenario-list` 与部署预检会执行受控、无 shell 的 `requires` 探测，未满足时输出可行动 blocker。完整 manifest/journal、漂移检测和恢复契约见 [`docs/reference.md`](docs/reference.md#场景部署v03-m1--m2) 与 [`docs/v0.3-scenario-deployment-design.md`](docs/v0.3-scenario-deployment-design.md)。

```bash
# 单文件 CLI：校验并使用同版本密封 bundle
base='https://github.com/Jia-Ethan/codex-keysmith/releases/download/vX.Y.Z'
curl --fail --location --remote-name "$base/codex-keysmith-scenarios-vX.Y.Z.bundle"
curl --fail --location --remote-name "$base/SHA256SUMS"
awk '$2 == "codex-keysmith-scenarios-vX.Y.Z.bundle"' SHA256SUMS | shasum -a 256 -c -
python3 codex-instruct-vX.Y.Z.py --scenario-list \
  --scenario-root /absolute/codex-keysmith-scenarios-vX.Y.Z.bundle
```

### 场景评估（v0.3 M3）

`scripts/run_scenario_bank.py` 只随源码 ZIP / tar.gz 分发，依赖同目录的 `codex-instruct.py`。离线模式会完整校验场景包、index、摘要与 `verify.py`，不调用模型：

```bash
python3 scripts/run_scenario_bank.py --validate-only \
  --scenario-root /absolute/codex-keysmith-scenarios-vX.Y.Z.bundle
```

Live 模式需要显式模型和 `OPENAI_API_KEY`；也可用 `CODEX_API_KEY` 作为本 runner 的兼容别名。可选 `OPENAI_BASE_URL` 指向 OpenAI 兼容根路径（通常含 `/v1`），且必须是带非空 host 的绝对 `http://` 或 `https://` URL；禁止 userinfo、query 和 fragment，scheme、host 与末尾斜杠会在使用前规范化。runner 不会读取 live `~/.codex/config.toml`，而是在隔离 `CODEX_HOME` 里注入临时 custom provider。runner 只执行当前平台与依赖已满足的场景；每次尝试使用临时 target、隔离 `CODEX_HOME` 和只读场景目录，模型工具的 shell 仅继承平台核心环境并过滤 API 凭证、代理与模型服务地址，随后用 validator 校验模型最终 JSON。指定 `--report` 文件路径时，报告使用私有权限原子发布并记录默认跳过项；若目标路径已存在则停止且保留临时结果，不覆盖旧报告。省略 `--report` 或使用 `-` 时输出到 stdout；报告与抛出的 live-mode 错误会脱敏已识别凭证、原始 endpoint 和规范化 endpoint。

```bash
OPENAI_API_KEY=YOUR_KEY python3 scripts/run_scenario_bank.py \
  --scenario example_fixture --model MODEL --attempts 2 --timeout 600 \
  --report /absolute/reports/example-fixture.jsonl

OPENAI_API_KEY=YOUR_KEY OPENAI_BASE_URL=https://HOST/v1 \
  python3 scripts/run_scenario_bank.py --model MODEL --attempts 2 --timeout 600 \
  --report /absolute/reports/scenario-bank.jsonl
```

Live 评估会把临时场景上下文发送到所选模型服务，可能产生费用。`verify.py` / `validator.py` 是本机执行代码，只应使用同版本 Release bundle 或已审阅场景目录；完整边界见 [`SECURITY.md`](SECURITY.md)。公开跑分仍不在范围内。Desktop 场景页见 [`gui/SPEC.md`](gui/SPEC.md)。首批私有评测协议见 [`docs/v0.3-scenario-deployment-design.md`](docs/v0.3-scenario-deployment-design.md#8-评估引擎m3)。

### 与 CCSwitch 配置切换配合

当 CCSwitch 以 Provider 为单位保存并整体写回 Codex `config.toml` 时，可以让两个 Provider 副本分别保存 Keysmith 的 On / Off 配置：

1. 先检查 CCSwitch 的 Codex **通用配置片段**：其中不能包含 `model_instructions_file`，On / Off 两个副本也不要借助「应用通用配置」共享该字段，否则 Off 的有效 live config 仍会被合并成 On。
2. 选择准备作为 **On** 的副本，再部署 Keysmith；若只想切换提示词、不想让 hooks 状态成为全局副作用，部署时使用 `--skip-hooks-isolation`。
3. 切到不含顶层 `model_instructions_file` 的 **Off** 副本，再运行 `--status` 验证。On 应显示 `配置激活状态: active`，Off 应显示 `inactive-by-config`；若 Off 仍是 active，先从 Provider 配置和通用配置片段中移除该字段。Off 不是损坏，但部署和卸载仍保持 blocked；先切回 On 副本再执行写操作。
4. 卸载后在 CCSwitch 普通模式下切离刚清理的 On 副本，检查是否出现“旧供应商配置回填失败”提示，再查看该副本保存的 config，确认字段已消失；单次切换本身不能证明回填成功。

这条流程按 CCSwitch v3.18.0（`ff3bc242`）的普通 Provider 切换与回填行为核对。代理接管热切换在该版本也可能从目标 Provider 的有效配置重建 live config，但还叠加 restore backup、通用配置合并和代理字段覆盖，Keysmith 不把它作为稳定兼容契约。配置切换只影响新会话，也不会随之切换 `hooks.json` / `hooks.json.disabled`。

### 撤销

```bash
# 只想拿回 hooks，不动指令/配置：
python3 codex-instruct.py --codex-dir ~/.codex --restore-hooks --lang zh-CN

# 想整体撤销这次部署（配置、指令、hooks 一起还原）：
python3 codex-instruct.py --codex-dir ~/.codex --uninstall --lang zh-CN        # 先预览
python3 codex-instruct.py --codex-dir ~/.codex --uninstall --yes --lang zh-CN  # 确认卸载
```

卸载每次只撤销最新一层部署；部署过多次的话，重复运行逐层撤销。config 的长期所有权只覆盖顶层 `model_instructions_file`：CCSwitch 等工具重写其他字段时，只要该字段仍引用本层 MD，status 和卸载仍可继续；卸载只恢复/移除部署前的该字段语句并保留其余当前内容。字段缺失时，只读 status 会识别为 `inactive-by-config`，但 deploy/uninstall 仍会 fail closed，直到切回引用本层 MD 的配置；字段改指其他路径、存在歧义或使用扫描器不支持的语句结构仍属于冲突。

### 出问题了怎么办

| 现象 | 应该做的事 |
| --- | --- |
| 中途被强制中断（比如 `SIGKILL`、断电） | 先 `--status` 看是否报告 `blocked`；有的话用 `--recover` 预览，确认无误再加 `--yes` |
| `--status` 报告异常残留 | 不要手工删除任何 `.codex-keysmith-transaction-*`、备份或 manifest；按上面 `--recover` 流程处理，或参考 [`docs/hooks-transactions.md`](docs/hooks-transactions.md) |
| 想彻底清掉旧备份 | 见 [`docs/reference.md`](docs/reference.md#备份保留与安全清理) 里的清理前置条件，工具本身不自动删备份 |

### 兼容性与限制

- 推荐 Python 3.10–3.14；已验证 Codex CLI `codex-cli 0.144.1`。
- macOS / Linux 是主要支持范围。
- **macOS GUI**：Apple Silicon unsigned DMG 由 `macos-15` 原生 CI 构建并公开为 Desktop Beta，尚未进行 Apple 签名、公证或实体设备验收。
- **Windows**：已发布的 `v0.1.0` 存在已知缺陷（`os.utime` 失败后触发第二个 `PermissionError`，会留下无法用旧脚本恢复的 journal）。v0.1.1 及后续版本已重写 Windows 文件系统后端并标记 `EXPLICIT_BETA`，可以试用，但还不是正式支持；如果 v0.1.0 留下了 journal，用最新已校验 Release 脚本按 `--status` → `--recover` 预览 → `--recover --yes` → `--status` 的顺序恢复，不要手工删除任何证据。
- **Windows GUI**：Windows x64 unsigned NSIS Beta 已由 `windows-2025` 原生 CI 构建并公开为 Pre-release，但没有 Authenticode 签名或实体设备验收；它不扩大上述 CLI 的 `EXPLICIT_BETA` 支持边界，也不等于正式 Windows 支持。
- 单文件 CLI，没有 `pip install` 或自动更新；备份和卸载归档不会自动清理。
- 完整限制清单、事务保证、维护者验证步骤见 [`docs/reference.md`](docs/reference.md)。

### 参与贡献与安全报告

提交前阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。漏洞通过 [`SECURITY.md`](SECURITY.md) 指定的 GitHub 私密渠道报告；不要在公开 Issue 中粘贴凭证、完整配置或私人路径。

### 友链 / Community

本项目接受 LINUX DO 社区佬友监督与反馈：[LINUX DO](https://linux.do)

同系列项目 / Same series:

- [codex-keysmith](https://github.com/Jia-Ethan/codex-keysmith) - Codex CLI instruction-file deployment for local configuration.
- [claude-keysmith](https://github.com/Jia-Ethan/claude-keysmith) - Claude Code `CLAUDE.md` import-block installer for local instruction files.
- [grok-keysmith](https://github.com/Jia-Ethan/grok-keysmith) - Grok Build `AGENTS.md` installer with compat/hook isolation.
- [zcode-keysmith](https://github.com/Jia-Ethan/zcode-keysmith) - ZCode `AGENTS.md` installer for local instructions.

---

English version: [`README.en.md`](README.en.md)。智能体安装提示词见 [`docs/agent-install.md`](docs/agent-install.md)。

codex-keysmith

codex-keysmith 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

codex-keysmith

codex-keysmith 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README