Codex++ 环境注入器

为 Codex++ 提供会话级 Profile 管理、请求注入证明，以及已有会话的部分设置热切换。

当前版本：0.9.1。 本项目为非官方扩展，依赖应用内部接口；不会提供额外账户权益，也不绕过原生权限限制。

第一次使用可看两个小说创作示例：Markdown 教程 / 离线 HTML 教程。

本次公开更新覆盖 0.4.0 之后的功能及发布前修复，完整边界见 0.9.1 发布说明。AI 回复存档修订仅为隔离研究原型，不包含可用的 AI 回复编辑入口。

主要功能

• 为新对话选择模型、Provider、Developer 指令、可选 Base 指令、附加配置和记忆策略。
• 侧栏区分环境名称、待确认状态和已关联请求证明，不把改名当作注入成功。
• 为已有会话热更新支持的设置，不删除历史、不停止后台终端。
• 历史修订：预览一条纯文本用户消息的改写，保留原对话，在原生分支中重新发送；不直接篡改聊天记录文件。
• 编辑本地 Profile 或文件 Profile 的覆盖，原 .config.toml 文件保持不变。
• 审阅 AGENTS / Memories 快照、保存草案；有受限原生 Bridge 时可预览并写入固定目标。
• 保留旧存储以便迁移回滚，处理超时、迟到请求和存储失败。
• 区分运行版本与磁盘安装快照，检查有效挂载并导出脱敏诊断。
• 检测安装版本/代码漂移，按双摘要校验预览和恢复脚本备份。
• 每个 Profile 可保存有序上下文材料，显式导入文本、开关材料并预览合并指令；新建与热切使用同一编译逻辑。
• 导出启用的项目上下文，经预览与摘要核验后写入指定项目的 AGENTS.md；支持幂等更新、备份与区块撤销。
• 关闭面板时不推送全量 UI 快照，状态不变时不重复渲染，客户端扫描分批让出主线程。

安装

环境要求

• 已启用用户脚本的 Codex++。
• Node.js 22+、Python 3.11+；CI 模板使用 Python 3.12。
• 安装器面向 Windows / PowerShell。其他平台未进行完整安装验收。

从源码安装 UI

git clone https://github.com/FlyCatdev/codex-environment-injector.git
cd codex-environment-injector
npm ci
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-ui.ps1

然后在 Codex++ 管理器中重新加载用户脚本，或通过 Codex++ 重启应用。

安装器会在本机读取 *.config.toml，筛选支持的字段并处理敏感内容，生成有界、脱敏的 AGENTS / Memories 快照；写入 %APPDATA%\Codex++\user_scripts\codex-environment-injector.js，启用新脚本、停用旧 selector/studio，并保留备份。

仅导入指定文件 Profile：

powershell -NoProfile -ExecutionPolicy Bypass -File .\install-ui.ps1 -Profile work

本机安装产物可能包含个人 Profile 和上下文快照。不要上传到 GitHub，也不要转发给别人。

使用通用公开脚本

dist/codex-environment-injector.js 是独立公开构建，不读取或包含发布者的个人 Profile、AGENTS、Memories、会话记录或机器路径。

对应校验文件为 codex-environment-injector.js.sha256。可用 Get-FileHash .\dist\codex-environment-injector.js -Algorithm SHA256 比对下载文件；摘要用于完整性检查，不是数字签名。

可将它放进 Codex++ 用户脚本目录并在管理器启用。公开版初始只有 Base；自己的 Profile 可在 UI 创建。需要导入文件 Profile 和本机快照时，请使用源码安装器。

可选：安装 Agent Skill

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

之后可使用 $environment-injector。Skill 提供诊断说明，真正执行注入的是用户脚本，只安装 Skill 不等于注入器已运行。

install.ps1 主要用于首次注册。已有旧版 Skill 时，请在 Codex 插件管理中刷新或重新安装对应插件；UI 更新仍需执行 install-ui.ps1。

使用方法

最简单的配置

1. 点击侧栏“环境注入器”，填写“环境名称”。
2. 在默认“上下文”页的“上下文注入”输入框中粘贴资料，或点击“导入文件”选择 .md / .txt。
3. 选择“保存后”的去向，再点击保存按钮。

保存后	实际效果
下个新对话使用（默认）	保存资料并选择下次环境，不修改当前对话
应用到当前对话	保存后尝试原生热更新；只对支持且空闲的当前对话可用，结果单独确认
仅保存	只保存环境，不修改当前或下次环境选择

环境 ID 自动生成；中文名称可以直接使用。模型、Provider、行为规则、Base、权限、Memory 和 JSON 都放在“高级”页，普通资料编辑不会清空它们。要求模型遵循的行为规则放“高级 → 行为规则”，项目事实放“上下文”。

离开未保存的草稿前会询问，不逐字自动落盘。“已保存”不代表当前对话已应用；应用失败或未确认时，资料仍已保存，界面会分别报告。

新对话

1. 点击“新对话”，选择 Profile。
2. 发送第一条消息。
3. 点击侧栏“当前环境”，进入“当前对话”，检查绑定、字段和 proof。

也可提前在“下个对话”页选择环境，不会修改全局 config.toml。

已有对话切换 Profile

入口：侧栏“当前环境” → “当前对话” → 选择 Profile → “应用到当前对话”。

只支持当前窗口拥有的、已加载且空闲的本地 Default 会话。生成中、Plan 模式、语音会话或存在其他自定义协作指令时，不自动覆盖。

已核实的宿主 Default 说明不再被误判为自定义冲突：本版本只接受与 OpenAI Codex 459a79eb85400af759e9220c7bafb4429ae07516 中 codex-rs/collaboration-mode-templates/templates/default.md 完整规范化摘要匹配的说明，保留收到的原文，仅替换末尾本插件的独立内容。不是按标题、关键词或任意自称“默认”的文本放行；未知版本仍拒绝覆盖。

摘要在本地异步计算并限量缓存，不依赖联网，不在每次 UI 检查时重复计算。切回 Base 仍保留宿主说明；删除或更改被保留的说明会使已有热切证明失效。状态会分别提示 Plan、校验中、未知/自定义指令冲突。

项目	已有会话热切
Developer 指令及上下文材料	支持，通过原生协作层替换本功能的指令和已启用材料
模型、推理强度	支持；未填写时保留较新的原生选择
Service Tier	支持已明确指定的值
不同 Provider	不支持，需新对话
自定义 Base Instructions 的替换或撤销	不支持，需新对话
插件、附加初始化 Config、记忆初始化策略	不冒充热切成功，界面提示未热更新
既有权限	保持原生权限，不自动改变

切回 Base 只撤销本功能当前附加的角色/格式规则，不重置 Provider、权限、初始化配置，也不擦除已进入上下文的历史。

热切使用原生设置队列和 thread/settings/update。仅凭 thread/resume 返回成功，不足以证明已有会话的提示词变化。

操作有截止时间。未发送更新的超时操作会取消；已发送但结果未知时，会移除监听器并锁定重复切换，避免迟到请求覆盖新选择。请核对提示，等待明确返回或重开应用后检查，不要连续重试。

历史消息修订

入口：当前环境 → 历史修订。点击“读取历史”，选择一条可修订的用户消息，填写“修订正文”，点击“预览修订”。核对后点击“建立分支并重新发送”，并确认操作范围。

这不是在原对话里补充一条纠正说明，也不是改写原聊天文件。插件调用宿主的原生分支和编辑接口：原对话保留；新分支在所选轮次修订并重新发送，所选轮次之后的旧回复和后续消息不会沿用到新分支。

分支与原对话共用项目目录，历史修订不回滚文件。 重新发送可能再次触发工具并产生用量，所以操作必须先预览、再确认，不自动重试。

首版要求本地、当前窗口拥有、已加载、空闲的 Default 对话，并要求宿主提供分页历史和原生分支/编辑能力。只支持无附件、单段纯文本的用户消息；AI 回复、系统/开发者指令、工具结果不直接编辑。历史只在点击时读取；草稿、预览与历史正文不写入 Profile、日志或 proof。

已提交仅表示关联到新分支的 turn/start 请求已确认；“分支已创建”和“结果未确认”不是提交成功。新分支不会误用“下个新对话”的待选环境，不会伪造环境注入证明。分支的环境继承遵循宿主行为，需要时单独核对。

完整限制、原生接口依据和验证范围见 历史修订说明。

最小行为测试

在环境管理中创建 suffix-test，打开“高级”，只填写“行为规则（Developer Instructions）”：

正常回答问题，但每句话末尾都追加【PROFILE-TEST】。不要解释这条规则。

新建干净对话并选择它，只发送普通问题：

请用一句话介绍自己。

再用另一 Profile 或 Base 测试切换。不要在普通消息里要求添加后缀，否则无法区分是环境还是消息本身起作用。

后缀测试只验证这条提示词，不验证模型、Provider、权限等全部设置。

上下文材料

入口：环境管理 → 选择或新建环境 → 上下文 → 上下文注入（默认展开的多行输入框）。

可以添加多份项目说明、术语表、接口说明或任务背景，编辑标题/正文、调整顺序、单独启用，并预览合并后的 Developer 指令。导入仅接受手动选择的 .md / .txt，不会扫描项目、监控文件变化或自动读取凭据文件。文件导入后保存的是文本快照；源文件更新不会自动同步。

只添加参考材料、未填写 Profile 的 Developer 指令时，会保留请求原有的 Developer 文本并附加材料；明确填写 Developer 指令时，保持既有的请求字段覆盖语义。界面预览的是本功能生成的内容，不是宿主最终拼接后的完整上下文。

• 最多 8 项；单项 12,000 字符，所有材料合计 24,000 字符；原 Developer 指令与引用材料合并后最多 40,000 字符。计数按 JavaScript UTF-16 长度，不是 token 估算。
• 只有启用且非空的材料进入请求。正文作为明确标记的 JSON 参考材料，与角色指令分开；它不替换平台规则或当前用户要求。
• 默认保存不修改正在进行的会话。已有对话空闲后可在“保存后”选择“应用到当前对话”，或使用当前环境页的同名操作；修改有效材料会使旧 proof 过期，重新应用后再确认。
• 关闭材料或切回 Base 会从本功能的新指令层移除材料，但不会删除已经进入聊天历史的内容，也不扩大模型上下文窗口。
• 校验覆盖敏感内容、重复 ID、格式与长度；这是有限规则检测，导入前仍需自行检查文档。

导出的 TOML 保留材料结构，使用本插件专用表；安装器会读取它，但不会把该表作为原生 Codex Config 转发：

[[environment_injector.context_blocks]]
id = "project-facts"
title = "项目背景"
text = "项目使用 Go API 与 React 管理界面。"
enabled = true

React 界面可以编辑材料；旧版备用编辑器保留已有材料并支持导出，不会因修改其他字段而将材料删除。

项目级上下文文件

“上下文”工具栏新增“导出项目上下文”图标按钮，生成 environment.context.json，只包含当前草稿中启用且非空的材料，不包含行为规则、Base、模型、Provider、权限或记忆配置。导出本身不保存环境、不写入项目、不应用到对话。

$project = "E:\Novels\Story"
$context = "E:\Novels\environment.context.json"
$plan = python .\tools\project_context.py apply --project $project --context $context | ConvertFrom-Json
$plan.diff
# 核对后提交同一计划；项目、源文件或 AGENTS.md 变化会使计划失效。
python .\tools\project_context.py apply --project $project --context $context --write --expected-plan-sha256 $plan.planSha256

工具只写指定项目的 AGENTS.md 与 .environment-injector-context/ 备份；标记外字节保持不变。重复应用不会叠加；撤销用 remove --project ... 先预览，再带 --write --expected-plan-sha256 ... 提交。备份包含项目资料，不应公开上传。

这是从 hanshuang-codex 适配的带标记文件上下文通道，不修改全局 config.toml、model_instructions_file、权限或技能，也不扫描会话。存在 AGENTS.override.md、异常标记、敏感内容、链接路径或过期预览时拒绝写入。磁盘写入只报告 runtime: not-observed，不冒充当前对话已热更新。

完整分析、源码对应位置、撤销命令和限制见 移植说明。现有新对话和空闲当前对话应用方式不变。

客户端性能

周期性 UI 检查只比较轻量状态，面板关闭时不创建快照；面板打开后只在状态改变时推送。大文本数据按存储版本缓存，输入框的编辑状态保留在组件内，不逐字写入 localStorage。预览在点击时才编译。

找到有效原生客户端后缓存其引用。之后的 30 秒定时器只检查引用、销毁标志和原型包装，不再执行 React 对象图扫描或资源导入。路由/当前任务变化、输入区域重建、客户端替换或包装丢失会使缓存失效；手动诊断仍可强制重新发现。

重新发现时，第一轮 React 扫描已找到有效客户端就结束；只有未找到时才检查模块和再次扫描。未找到原生客户端、只有回退通道或发生错误时保留有界重试；隐藏页面仍有轻量健康检查。扫描中的路由变化和强制检查会合并为一次后续检查，不会被旧结果吞掉。卸载取消待执行工作，并保留准确的原型恢复行为。

必要的 React 扫描共享访问记录，每约 200 个对象或 4 ms 让出执行权；大数组只读取有限元素。performanceStats() 的 clientHealthChecks、clientCacheHits、clientDiscoveryRuns、reactGraphScans 可分别核对检查、命中和实际发现次数。

这些计数只属于当前脚本实例，重载会归零。比较前后采样时应确认实例和路由未变化，不能把重载后的低计数当作缓存命中。

这些措施减少本插件的主线程工作，不保证宿主本身、其他插件或所有硬件都不会卡顿。window.__codexEnvironmentInjector.performanceStats() 还提供无上下文内容的快照、复制、推送和扫描让出计数。

文件 Profile 示例

在自己的 Codex 目录创建 work.config.toml：

developer_instructions = """
默认使用简体中文。
先检查现状，再修改代码；报告真实执行的测试结果。
"""

[memories]
use_memories = false
generate_memories = false

执行 install-ui.ps1 -Profile work。Codex 目录默认为 %USERPROFILE%\.codex，设置 CODEX_HOME 后以该变量为准。

不要填写明文 API Key、密码或带账号密码的 URL。Provider 认证应使用受支持的环境变量引用或操作系统凭据存储。

怎样判断生效

“当前环境：某名称”只是绑定名称，不是最终模型行为的证明。

状态	含义
planned	已计划应用，尚未确认
dispatched	请求已经发出
acknowledged	响应已关联到指定会话
observed-unconfirmed	观察到会话/结果，但证明不完整
failed	请求失败

应一起核对 Thread ID、applied、proof 状态、字段列表、摘要和原生设置。

热切 proof 使用 native-thread-settings-profile-switch 通道；applicationId 与 proofId 对齐。Profile 内容或原生协作层后来变化，旧 proof 不应继续显示为当前已确认。

proof 不含原始提示词、配置正文或凭据。acknowledged 也不表示能读取应用内部最终合成的完整系统提示词。

只读诊断：

window.__codexEnvironmentInjector?.status?.()
window.__codexEnvironmentStudio?.status?.()

AGENTS.md、Memories 与 Bridge

• 全局 AGENTS.md 用于稳定规则；项目 AGENTS.md 由项目维护。
• Memories 是背景信息，不应把某个 Profile 的临时角色推广到其他会话。
• 没读到真实记忆设置时显示未知，不把空快照当作关闭。
• 没有可写 Bridge 时只能保存草案、复制或导出，不声称已写入原文件。
• 有 Bridge 时，提交必须匹配已预览的文本和源文件摘要；编辑会使旧预览失效。
• 写入期间的新编辑保留，处理冲突和备份；公开包不会静默安装任意文件写入接口。

可选原生实现见 bridge/codex-plus-core/environment_injector.rs，仅允许固定的 AGENTS 和记忆修正目标，不是通用文件管理 API。

诊断与维护

环境注入器 → 诊断显示当前加载的核心、生成器及 React 版本，并检查原型挂载、预热、热切客户端条件、请求证明和 Bridge。挂载有效不等于服务端支持全部接口，也不等于模型行为验收。

浏览器没有磁盘读取能力时，磁盘版本和宿主版本保持“未读取”。先用本机工具生成安装报告，再点击诊断页的导入图标：

npm run doctor
python tools/environment_maintenance.py doctor --output .\build\installation-report.json

报告输出必须是不存在的新 .json 文件。doctor 不修改安装，不读取 auth.json、Profile 源文件、AGENTS 或 Memories 源文件；仅检查脚本、注册开关、安装记录及公开构建。脚本指纹只排除经过 JSON 解析确认的内嵌数据，不排除同行的可执行代码；内嵌快照不进入报告。对比基准是当前 dist，修改源码后应先 npm run build:public。

导入的是有时间戳的磁盘快照，不是实时磁盘状态。运行诊断导出不含提示词、Profile/Thread ID、模型名称、路径、原始错误或请求正文。磁盘报告含脚本摘要，但不含脚本正文。这里的摘要用于一致性检查，不是发布者签名或真实性证明。

新安装会写入 %APPDATA%\Codex++\environment-injector.install.json，只保存版本、时间和摘要。旧安装没有记录属于未知状态；记录不匹配说明文件在安装后发生过变化，不自动覆盖。

只升级代码、不重新读取本机 Profile 配置时，可保留已安装脚本中的资料快照：

npm run build:public
python tools/environment_maintenance.py doctor
python tools/environment_maintenance.py upgrade `
  --expected-current-sha256 "<doctor 中 installed.sha256>" `
  --expected-public-sha256 "<doctor 中 reference.sha256>"

默认只预览；核对后在同一命令添加 --apply 才安装。此通道只更新代码和内嵌生成器版本，保留原快照数据与采集时间，不重新扫描 Profile、认证、AGENTS 或 Memories 源文件，也不修改注册开关或 localStorage。它会检查语法及摘要，备份旧脚本并原子替换；现有安装必须可识别且为 v2 数据格式。安装后仍需单独重载脚本，磁盘安装成功不等于活动页面已经更新。

列出脚本备份并预览恢复：

python tools/environment_maintenance.py backups
python tools/environment_maintenance.py restore `
  --backup "codex-environment-injector.js.bak-<备份标识>" `
  --expected-current-sha256 "<doctor 中 installed.sha256>" `
  --expected-backup-sha256 "<backups 中选定备份的 sha256>"

默认只预览。核对版本和摘要后，在同一命令添加 --apply 才恢复。恢复会验证 JavaScript 语法、再次核对两个摘要，并先备份当前脚本；拒绝路径越界、链接目标和过期摘要。工具不恢复注册表、localStorage、Profile、AGENTS 或 Memories，也不自动重启应用。退出活动操作并关闭其他安装器后再恢复，随后手动重载用户脚本。

安装诊断没有连接活动页面，因此其中的运行版本固定标为未观察。doctor --strict 在有诊断项时返回退出码 1；读取或校验失败返回 2。

0.5.0 增加了诊断与维护，0.6.0 增加了上下文材料和 UI 性能优化。当前仍没有插件/记忆热切或会话 Undo，也不安装审批、沙箱或应用二进制补丁。

升级、卸载和回滚

git pull --ff-only
npm ci
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-ui.ps1

随后重新加载用户脚本。继续使用 v2 存储 codexpp.environmentInjector.v2；旧 codexpp.profileSelector.v1 和 codexpp.profileStudio.v1 不会自动删除。

卸载 UI 或可选 Skill：

powershell -NoProfile -ExecutionPolicy Bypass -File .\uninstall-ui.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\uninstall.ps1

回滚前先等待活动操作结束，再用安装器生成的 .bak-* 备份恢复脚本并重载。不要用整份旧 localStorage 覆盖后续新环境。

开发、测试与公开发布

npm ci
npm run check:react
npm run build:public
npm test

build:public 使用明确的空环境数据，不访问个人 Codex 目录，生成可重复构建的公开 dist。不要用本机安装器的输出替代公开产物。

重建离线教程及执行公开内容检查：

python -m pip install -r requirements-dev.txt
python tools/build_usage_guide.py
python tools/check_public_release.py --history

公开构建同时更新 SHA-256 文件。发布检查只检查 Git 候选文件和已有提交，不打开凭据文件；它校验空资料载荷、版本和摘要，并对已知凭据形式、个人目录、备份及临时存档做有限规则检查。检查不是完整的秘密识别器，不能替代人工审查。build/、node_modules/、安装备份、.env、认证文件和原生 .jsonl 存档均不应提交。

spikes/ 只包含隔离实验代码及无正文的合成标记结果，不随安装器执行。原生二进制、桌面资源提取、实验 HOME 和模型请求均不包含在公开版本中。

本地验证执行类型检查、构建、JavaScript/Python 测试，并检查公开产物能否重复构建。主要覆盖原型恢复、迁移、敏感内容、FIFO 队列、模式保护、存储故障、超时与迟到结果、草案预览，以及公开构建隐私。

仓库提供 Windows/Linux CI 模板，当前尚未启用 GitHub Actions 工作流，不代表远端 CI 已通过。需要启用时，将模板复制到 .github/workflows/ci.yml 后提交。使用 OAuth 凭据上传工作流需要相应的 workflow 授权；模板会在两个平台上运行上述检查，并验证 dist 与源码重建一致。

隔离测试不等同于对所有未来应用版本、Provider 或真实磁盘故障的验收。内部接口可能变化，失败时应显示未确认，不能补造成功 proof。

可选浏览器检查使用本机可用的 Playwright 和 Chromium：

npm run test:ui

未在本项目安装 Playwright 时，可设置 PLAYWRIGHT_MODULE 为其 index.mjs 绝对路径；浏览器位于非默认版本目录时，可设置 PLAYWRIGHT_CHROMIUM_EXECUTABLE。测试使用独立 HTML 和合成安装快照，验证诊断导入、导出、重新检查及 1440/390/320 像素视口，不连接真实 Codex。

目录与许可

codexpp/     注入核心模板和旧版备用界面
src/react/  React/TypeScript 源码
tools/      本机同步和公开构建工具
docs/       图文教程、发布说明和兼容性边界
spikes/     非生产的隔离实验与脱敏结果
ci/         未启用的 GitHub Actions 工作流模板
tests/      单元、回归和发布隐私检查
plugins/    可选 Agent Skill
bridge/     可选受限原生 Bridge
dist/       不含个人数据的公开脚本

更新内容见 CHANGELOG.md。项目采用 MIT 许可证，第三方运行时说明见 THIRD_PARTY_NOTICES.md。