@namewta/speculo 0.7.1 → 0.7.2

package/template/skills/optimize-codex-config/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: optimize-codex-config
+description: 体检并优化本机 Codex 配置；当任务涉及 config.toml、auth.json、自定义模型供应商、权限、Agent、MCP、Hook、配置漂移，或 Codex 的 401、403、404、413、SSE、超时与 compaction 故障时使用。
+---
+
+# Optimize Codex Config
+
+以**体检**为主导词：先建立脱敏事实，再提出配置变更。默认只读；修改本机配置前必须向用户展示完整目标和脱敏 diff，并取得本次修改的明确确认。
+
+## 1. 锁定范围与权限
+
+1. 解析实际 `CODEX_HOME`；未显式设置时使用当前用户的 `~/.codex`。将它转成绝对路径并确认目标是目录且不是符号链接。
+2. 将请求归类为只读体检、故障诊断或配置修改。只读体检和诊断不取得写权限。
+3. 将本 skill 的写入边界限制为用户明确指定的本机 Codex 文件。CC Switch 数据库、远端 API、反向代理和 Nginx 只输出归因与交接建议。
+4. 在任何可能写入前记录 `config.toml` 的哈希、大小和修改时间，并检查目标文件是否存在已证明的可写句柄。普通 Codex CLI、ChatGPT/Codex 应用进程及其 helper 的存在不构成 writer 证据。
+
+**完成标准：** 实际 `CODEX_HOME`、任务类型、允许写入的文件和外部边界均已明确；符号链接、已证明的活跃 writer、不明确目标，或修改任务无法取得 writer 观测时已成为 blocker。只读任务可以把不可用探针记录为 unknown 后继续。
+
+## 2. 建立只读基线
+
+从本 `SKILL.md` 所在目录运行：
+
+```bash
+node scripts/audit-codex-config.mjs --codex-home <absolute-directory> --json
+```
+
+需要离线或可复现 fixture 时加入 `--no-command-probes`；需要缩小会话扫描范围时使用 `--since-days <N>`。先运行 `--help` 核对当前接口；CLI 不在导出的 `PATH` 中时，用 `command -v codex` 取得绝对路径并传给 `--codex-bin`。
+
+1. 保留审计脚本的结构化结果；不得把 `auth.json` 内容、提示词、工具输出、完整接口 URL 或 bearer token复制进报告。
+2. 直接查看配置时，先遮蔽 `experimental_bearer_token`、静态认证 header、环境变量值和 URL 主机。只检查 `auth.json` 的存在、文件类型、权限和 Codex 报告的认证模式，不读取或打印文件内容。
+3. 对配置、供应商、认证、权限、Agent、MCP、Hook 或历史设置提出判断前，读取 [configuration contract](references/configuration-contract.md)，并用已安装 CLI 与当前官方配置参考验证每个拟使用的键。
+4. 把用户提供的既有设置视为需要保留或评估的事实，不把个人模型、认证方式或权限策略提升为通用默认值。
+
+**完成标准：** 当前版本、配置指纹、认证存储模式、供应商契约、权限、Agent、MCP、Hook、会话故障和 writer 状态均有脱敏证据；无法取得的事实被标为 unknown。
+
+## 3. 归因故障
+
+当请求包含 HTTP 状态码、SSE、超时或 compaction 失败时，读取 [troubleshooting](references/troubleshooting.md)，按其中证据梯度完成归因。
+
+1. 关联错误发生前最近一次 `token_count`，但只保留 token 数和模型上下文窗口。
+2. 区分本机配置、认证、供应商 wire API、远端模型服务和前置代理。HTML 代理错误页属于代理证据，不归因给模型。
+3. 对外部问题给出可复现证据、影响、临时本机缓解和服务端交接项。本 skill 不探测或修改用户未授权的远端系统。
+
+**完成标准：** 每个错误只有一个主要归属域，证据与推断分开，所有本机缓解都标明质量、成本或频率代价。
+
+## 4. 设计目标状态
+
+只询问审计无法发现且会改变方案的偏好：模型与推理等级、认证存储、审批与沙箱、网络访问、Agent 并发、供应商认证方式、历史保留，以及 MCP/Hook 的保留意图。
+
+输出确认包：
+
+1. 当前状态和问题证据；
+2. 目标状态及每项理由；
+3. 逐文件脱敏 diff；
+4. 明确保留的未知项、MCP、Hook、profile 和兼容设置；
+5. 备份名、原子写入方法、验证命令和回滚条件；
+6. 不在本机范围内的外部 blocker。
+
+只采用当前官方参考与已安装 CLI 均能验证的键。项目级 `.codex/config.toml` 不承载 provider、auth 或其他被 Codex 忽略的机器级设置。
+
+**完成标准：** 用户无需猜测任何目标值；diff 不含 secret；未关联的现有设置不会被清理；外部问题不会伪装成本机可修复项。
+
+## 5. 确认后原子写入
+
+只有用户在看到确认包后明确同意本次变更，才执行以下动作：
+
+1. 重读指纹；若配置已变化、存在目标文件的可写句柄，或 writer 探针仍为 unknown，停止并重新体检。
+2. 为每个待改文件创建不覆盖的 `*.pre-optimize-<YYYYMMDD-HHMMSS>.bak`，并将包含凭据的文件权限设为 `0600`。
+3. 在同一目录写临时文件、解析或加载验证成功后 rename 到目标，保留与任务无关的表和注释。
+4. 仅在用户明确要求且已安装 Codex 能验证格式时处理 `auth.json`。文件存储是有效选择，不强制迁移钥匙串；不得自行发明认证 JSON schema。
+
+**完成标准：** 写入前后的指纹、备份和确认可对应；目标文件是原子替换结果；没有越出已确认文件集合。
+
+## 6. 验证与交付
+
+1. 运行 `codex doctor --json`，再核对 `codex features list` 和 `codex debug models --bundled` 中与目标相关的能力。
+2. 验证配置加载、认证模式、权限与沙箱、MCP、Hook、Agent 和旧会话恢复。只有用户授权可能计费的网络请求后，才执行最小第三方 API 请求。
+3. 任一必须验证项失败时恢复备份，重跑相同检查并报告原始失败与回滚结果。
+4. 报告已改变、已保留、已验证、未验证和外部 blocker；不回显任何 secret 或完整 URL。
+
+**完成标准：** 所有已确认变更通过本机验证，或已完整回滚；报告包含命令、退出码和关键脱敏证据。

package/template/skills/optimize-codex-config/references/configuration-contract.md

@@ -0,0 +1,103 @@
+# Codex Configuration Contract
+
+在设计或修改 `config.toml`、`auth.json`、模型供应商、权限、Agent、MCP、Hook 或历史配置时完整应用本契约。配置键会随 Codex 版本变化；以已安装 CLI 和当前 [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) 为最终事实源。
+
+## 1. 配置归属与事实优先级
+
+1. 用户级配置位于 `$CODEX_HOME/config.toml`；profile 文件位于同一目录并通过 `--profile` 选择。
+2. 受信任项目可以使用 `.codex/config.toml` 覆盖项目设置，但 provider、auth、host metadata、通知、profile 选择和 telemetry 等机器级键会被忽略，必须留在用户级配置。
+3. 先读取现有配置、`codex doctor --json`、`codex features list` 和 `codex debug models --bundled`，再核对当前官方参考。API 模型网页上的最大上下文不是本机 Codex 目录的替代品。
+4. 只更改与目标直接相关的键。MCP、Hook、profile、插件、历史兼容项和未知集成默认原样保留，直到有证据证明无效且用户确认删除。
+
+## 2. 模型与推理
+
+- 从已安装模型目录选择 model，并确认所选 reasoning effort 受支持。常规工作可以从 `medium` 或现有值开始；`high`、`xhigh` 和更高等级只在质量收益能够覆盖延迟与成本时采用。
+- `plan_mode_reasoning_effort` 独立于普通 `model_reasoning_effort`；未设置时使用 Codex 内置 Plan preset。
+- 仅在自定义模型目录确实需要时设置 `model_context_window`。不得为了绕过 compaction 或代理限制而夸大它。
+- `model_auto_compact_token_limit` 是触发阈值，不是服务端请求体限制。降低它会更早、更频繁地压缩，并可能改变成本和上下文质量。
+- `model_auto_compact_token_limit_scope` 默认是 `total`；只有理解 carried prefix 行为后才选择 `body_after_prefix`。
+
+## 3. 第三方 Responses 供应商
+
+Codex 当前自定义供应商只支持 `responses` wire API。供应商必须兼容 Codex 实际使用的 Responses 请求、SSE 输出、工具项和 compaction 路径；仅兼容 Chat Completions 不够。
+
+使用存储在 `auth.json` 的 OpenAI-style API key 时，可以采用：
+
+```toml
+model = "gpt-5.6-sol"
+model_provider = "third-party"
+model_reasoning_effort = "high"
+plan_mode_reasoning_effort = "xhigh"
+cli_auth_credentials_store = "file"
+
+[model_providers.third-party]
+name = "Third Party Responses"
+base_url = "https://relay.example/api-root"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+`base_url` 必须是供应商声明的 API root。先确认 Codex 最终请求路径，不能机械添加或删除 `/v1`。生产连接优先 HTTPS；HTTP 会在主机到中转之间明文传输凭据和内容。
+
+供应商使用独立环境变量时改用：
+
+```toml
+[model_providers.third-party]
+name = "Third Party Responses"
+base_url = "https://relay.example/api-root"
+wire_api = "responses"
+env_key = "THIRD_PARTY_API_KEY"
+```
+
+动态 token 可以使用 `[model_providers.<id>.auth]` 下的 command、args、cwd、timeout 和 refresh interval。`auth`、`env_key`、`experimental_bearer_token` 与 `requires_openai_auth` 是互斥认证路线；每个供应商只保留一条。
+
+仅在证据要求时调整 `request_max_retries`、`stream_max_retries` 或 `stream_idle_timeout_ms`。重试不能修复稳定的 401、403、404 或 413。
+
+## 4. 认证存储
+
+- `cli_auth_credentials_store = "file"` 正式选择 `$CODEX_HOME/auth.json`；`keyring` 选择系统钥匙串；`auto` 由 Codex 决定。三者是偏好，不是安全等级排序。
+- 文件模式下，验证 `auth.json` 是普通文件、权限为 `0600` 且 `codex doctor --json` 报告认证可用。不要读取、打印、diff 或记录其中的 key。
+- 保留已安装 Codex 创建并验证过的 JSON schema。需要重新登录时优先通过 stdin 使用 `codex login --with-api-key`；手工修改只有在当前 schema 已被可靠确认时进行。
+- 自定义 provider 的 command-backed token 和 `env_key` 不应同时把同一 secret 写入 `auth.json` 或 `config.toml`。
+
+## 5. 权限、沙箱与网络
+
+一个保守、可交互的本机基线是：
+
+```toml
+approval_policy = "on-request"
+approvals_reviewer = "auto_review"
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+network_access = false
+```
+
+这只是安全起点，不是固定默认。`approval_policy = "never"` 和 `sandbox_mode = "danger-full-access"` 适合用户明确接受风险的受控环境；不要通过 profile 名称暗示它们更安全。
+
+`default_permissions` 与 `sandbox_mode` / `[sandbox_workspace_write]` 是两套选择，不能混合。网络访问只按实际工具需求开放；第三方模型请求由 Codex host 发出，不等同于给沙箱内命令开放任意网络。
+
+## 6. Agent、MCP、Hook 与历史
+
+Agent 配置先确认当前 CLI 支持的键：
+
+```toml
+[agents]
+enabled = true
+max_concurrent_threads_per_session = 4
+default_subagent_model = "gpt-5.6-terra"
+default_subagent_reasoning_effort = "medium"
+```
+
+并发数由 CPU、内存、供应商速率限制和成本共同决定。不要假定四个线程适合所有机器或接口。
+
+- 对每个 MCP 逐项验证 command/path、启动、tool discovery 和审批策略；不因某个 MCP 失败而清理其他 MCP。
+- Hook 按事件和集成所有者保留。两个 Hook 调用不同集成时不是重复；只有调用链、输入和副作用等价时才合并。
+- `history.persistence` 和 `history.max_bytes` 由隐私、恢复需求和磁盘预算决定。修改前验证旧会话与数据库兼容。
+- 审计期间 `config.toml` 指纹变化或目标文件存在已证明的可写句柄时，先关闭写入来源并重新审计；进程名本身不是 writer 证据。修改任务无法取得精确 writer 观测时保持 blocked，且不得覆盖竞争写入。
+
+## 7. 确认包与写入契约
+
+确认包必须列出当前值、目标值、理由、脱敏 diff、保留项、备份路径、验证和回滚。对每个 secret 只写 `<redacted>` 或“存在/不存在”。
+
+确认后在目标目录创建权限正确的临时文件，完成 TOML/JSON 和 Codex 加载验证后原子 rename。写入前再次比较哈希、大小和 mtime；任一变化都使原确认失效。验证失败时恢复备份并重复验证，不留下部分应用状态。

package/template/skills/optimize-codex-config/references/troubleshooting.md

@@ -0,0 +1,79 @@
+# Codex Provider Troubleshooting
+
+当 Codex 出现 HTTP 状态码、SSE、超时或 compaction 故障时完整应用本手册。官方事实分别来自 [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference)、[Authentication](https://learn.chatgpt.com/docs/auth) 和 [Compaction](https://developers.openai.com/api/docs/guides/compaction)。
+
+## 1. 证据梯度
+
+按以下顺序收集并停止在能够唯一归因的位置：
+
+1. 已安装 Codex 版本、active provider、认证模式和配置加载结果；
+2. 错误状态、响应 content type、代理签名和最终 path 的脱敏形态；
+3. 错误前最近一次 `last_token_usage` 与 `model_context_window`；
+4. 同一接口的最小 Responses 请求、SSE 行为和重试一致性；
+5. 只有具备服务器权限时才查看反向代理与上游日志。
+
+报告原始事实和推断的边界。不得用接口 URL、API key、提示词或工具输出充当证据附件。
+
+## 2. 状态路由
+
+| 症状 | 主要归属 | 首要检查 | 无效做法 |
+|---|---|---|---|
+| 401 | 认证 | provider 选择、认证路线、header 格式、key 是否属于该服务 | 增加 HTTP 重试 |
+| 403 | 授权或策略 | 模型权限、账户策略、代理 ACL、来源限制 | 重写 prompt |
+| 404 | endpoint / wire API | `base_url`、最终 `/responses` path、是否错误叠加 `/v1`、Responses 兼容性 | 更换 reasoning effort |
+| 413 | 供应商或网关，待证据归因 | 响应类型、HTML/Server header、请求体边界、代理 location 继承 | 提高模型上下文或反复重试 |
+| 429 | 服务限流 | RPM/TPM、并发 Agent、retry-after、账户额度 | 无限并发重试 |
+| SSE 中断 | 流式传输 | content type、代理 buffering、idle timeout、上游心跳 | 把稳定 4xx 当瞬时网络错误 |
+| 超时 | 客户端、代理或模型 | 发生阶段、首 token 时间、idle/total timeout、服务日志 | 同时扩大所有 timeout |
+
+## 3. 413 与 remote compact
+
+Standalone compaction 会发送完整上下文窗口；长会话因此可能产生远大于普通请求的 JSON body。`/responses/compact` 返回的窗口是后续请求的权威上下文，不应自行裁剪。
+
+自动审计只有在 413 响应带有 Nginx、Envoy、HAProxy、Cloudflare、Varnish 等明确代理签名时，才把主要归属标为 `external_proxy_body_limit`。供应商 JSON 413 或没有代理签名的响应保持 `request_body_limit_unattributed`，不得直接交接给代理管理员。
+
+满足以下证据时，才把代理限制标记为已确认并完成服务器交接：
+
+- Codex 报告 remote compact 或 `/responses` 请求返回 413；
+- 响应是 Nginx 等代理生成的 HTML，而不是模型服务 JSON；
+- 较小请求能进入上游，超过稳定字节边界后始终 413。
+
+Nginx 的 `client_max_body_size` 默认是 `1m`。只有实测边界或 `nginx -T` 能证明配置时，才把“1 MiB”写成确定结论；否则写成最可能原因。
+
+本机临时缓解按优先级为：
+
+1. 生成脱敏 handoff 后开启新会话；
+2. 依据失败时 token 规模试验性降低 `model_auto_compact_token_limit`，并说明压缩频率、成本和上下文质量代价；
+3. 仅当当前 `codex features list` 确认该 feature 存在时，临时关闭 `remote_compaction_v2` 作为诊断，并验证本地压缩是否可用。
+
+不得把 `model_context_window` 改成 API 模型网页的最大值来解决 413；更晚触发压缩通常会制造更大的 body。
+
+服务器交接建议包含：在实际命中的 `server` 或 `/responses` location 设置足够的 `client_max_body_size`（当前约 272k Codex 上下文可从 `32m` 起步）、用 `nginx -T` 确认继承、`nginx -t` 校验并平滑 reload。SSE 仍异常时再单独检查 buffering 与 timeout。Skill 只交接，不执行这些服务器动作。
+
+## 4. Compaction 判定
+
+- 以 `codex debug models --bundled` 的 active model 窗口为本机事实，不从 API 产品页反推 Codex 客户端阈值。
+- `total_token_usage` 是会话累计量；诊断某次失败应使用此前最近一次 `last_token_usage`。
+- `model_auto_compact_token_limit` 未设置时使用模型默认；`total` 与 `body_after_prefix` 的计数语义不同，变更时必须记录原值。
+- 远程压缩失败但普通请求成功，优先比较 body 大小、compact 能力和代理路径，不重新认证全部配置。
+
+## 5. SSE 与超时
+
+先确认响应是 `text/event-stream` 且事件格式与 Responses API 兼容。把“连接前超时”“首 token 超时”“流式 idle 超时”分开记录；只调整命中的那一层。
+
+`stream_idle_timeout_ms` 和 `stream_max_retries` 属于 provider 设置。代理层需要管理员核对 streaming buffering、read timeout 和连接关闭行为；本机重试仅适用于已证明的瞬时中断。
+
+## 6. 交付格式
+
+每个故障报告固定包含：
+
+```text
+classification: <local_config|authentication|provider_contract|external_proxy|upstream_service>
+evidence: <status, content type/proxy signature, token metadata, reproducible boundary>
+local_action: <none or confirmed mitigation>
+tradeoff: <quality/cost/frequency/security impact>
+external_handoff: <owner, exact check, success condition>
+verification: <command, exit code, redacted result>
+```
+
+只有证据支持的层级可以标记为已解决；其余保持 blocker 或 unknown。