@mison/ag-kit-cn 2.0.1 → 3.0.0

package/docs/official/codex/config-advanced.md

@@ -1,358 +0,0 @@
-# 高级配置（Advanced Configuration）
-
-> 来源：`https://developers.openai.com/codex/config-advanced`  
-> 同步日期：2026-02-12  
-> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
-
-当你需要更细粒度控制模型提供方、安全策略、MCP、可观测性等能力时，使用本页配置。  
-基础项先看 `config-basic.md`。
-
-## Profiles（命名配置集）
-
-Profile 可把一组配置命名保存，并通过 CLI 快速切换。
-
-注意：
-
-- 当前为实验能力，后续可能调整。
-- Codex IDE 扩展当前不支持 profile 切换。
-
-示例：
-
-```toml
-model = "gpt-5-codex"
-approval_policy = "on-request"
-
-[profiles.deep-review]
-model = "gpt-5-pro"
-model_reasoning_effort = "high"
-approval_policy = "never"
-
-[profiles.lightweight]
-model = "gpt-4.1"
-approval_policy = "untrusted"
-```
-
-调用方式：
-
-```bash
-codex --profile deep-review
-```
-
-设置默认 profile：
-
-```toml
-profile = "deep-review"
-```
-
-## 单次运行覆盖配置（CLI）
-
-除编辑 `~/.codex/config.toml` 外，也可为单次运行覆盖配置。
-
-- 有专用参数时优先用专用参数（如 `--model`）。
-- 其他键用 `-c` / `--config`。
-
-```bash
-# 专用参数
-codex --model gpt-5.2
-
-# 通用覆盖（值按 TOML 解析）
-codex --config model='"gpt-5.2"'
-codex --config sandbox_workspace_write.network_access=true
-codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'
-```
-
-说明：
-
-- 支持点号路径设置嵌套键（如 `mcp_servers.context7.enabled=false`）。
-- `--config` 值按 TOML 解析；解析失败时按字符串处理。
-
-## 配置与状态目录
-
-Codex 本地状态目录：`$CODEX_HOME`（默认 `~/.codex`）。
-
-常见文件：
-
-- `config.toml`：本地配置
-- `auth.json`：文件型凭据存储（或系统 keychain/keyring）
-- `history.jsonl`：会话历史（启用持久化时）
-- 日志与缓存文件
-
-## 项目级配置（`.codex/config.toml`）
-
-Codex 会从项目根到当前目录逐层加载 `.codex/config.toml`。  
-同名键冲突时，离当前目录最近的配置生效。
-
-安全规则：
-
-- 仅受信任项目加载项目级 `.codex/config.toml`
-- 不受信任项目会忽略项目级配置
-
-路径解析规则：
-
-- 项目配置中的相对路径，按该配置文件所在 `.codex/` 目录解析
-
-## 项目根识别
-
-默认遇到 `.git` 即视为项目根。可通过 `project_root_markers` 调整：
-
-```toml
-project_root_markers = [".git", ".hg", ".sl"]
-```
-
-若设置为空数组：
-
-```toml
-project_root_markers = []
-```
-
-则不向上查找父目录，当前目录即项目根。
-
-## 自定义模型提供方（Model Provider）
-
-Provider 决定 Codex 如何连接模型（`base_url`、协议、鉴权、请求头等）。
-
-```toml
-model = "gpt-5.1"
-model_provider = "proxy"
-
-[model_providers.proxy]
-name = "OpenAI via Proxy"
-base_url = "http://proxy.example.com"
-env_key = "OPENAI_API_KEY"
-
-[model_providers.ollama]
-name = "Ollama"
-base_url = "http://localhost:11434/v1"
-```
-
-附加请求头：
-
-```toml
-[model_providers.example]
-http_headers = { "X-Example-Header" = "example-value" }
-env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }
-```
-
-## OSS 模式（本地开源模型）
-
-`--oss` 可切换到本地 provider（如 Ollama、LM Studio）。
-
-```toml
-oss_provider = "ollama" # 或 lmstudio
-```
-
-## Azure 与数据驻留（Data Residency）
-
-Azure 示例：
-
-```toml
-[model_providers.azure]
-name = "Azure"
-base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
-env_key = "AZURE_OPENAI_API_KEY"
-query_params = { api-version = "2025-04-01-preview" }
-wire_api = "responses"
-```
-
-数据驻留示例：
-
-```toml
-model_provider = "openaidr"
-
-[model_providers.openaidr]
-name = "OpenAI Data Residency"
-base_url = "https://us.api.openai.com/v1"
-```
-
-## 推理、冗长度与上下文限制
-
-```toml
-model_reasoning_summary = "none"
-model_verbosity = "low"
-model_supports_reasoning_summaries = true
-model_context_window = 128000
-```
-
-说明：
-
-- `model_verbosity` 仅对 Responses API provider 生效。
-- Chat Completions provider 可能忽略该设置。
-
-## 审批策略与沙箱策略
-
-```toml
-approval_policy = "untrusted"   # 也可 on-request / on-failure / never
-sandbox_mode = "workspace-write"
-
-[sandbox_workspace_write]
-exclude_tmpdir_env_var = false
-exclude_slash_tmp = false
-writable_roots = ["/Users/YOU/.pyenv/shims"]
-network_access = false
-```
-
-提示：
-
-- `workspace-write` 下某些环境会保持 `.git/`、`.codex/` 只读。
-- 若需控制“哪些命令可跳出沙箱”，结合 `rules` 使用。
-- `danger-full-access` 会关闭沙箱隔离，仅适用于你已具备外部隔离措施的环境。
-
-## Shell 环境变量策略
-
-`shell_environment_policy` 控制 Codex 启动子进程时可继承哪些环境变量。
-
-```toml
-[shell_environment_policy]
-inherit = "none" # all / core / none
-set = { PATH = "/usr/bin", MY_FLAG = "1" }
-ignore_default_excludes = false
-exclude = ["AWS_*", "AZURE_*"]
-include_only = ["PATH", "HOME"]
-```
-
-说明：
-
-- 匹配规则为不区分大小写的 glob。
-- 默认会过滤包含 `KEY` / `SECRET` / `TOKEN` 的变量名（除非显式放开）。
-
-## MCP 配置
-
-MCP 细节请参见 `mcp.md`。  
-常见配置入口为 `[mcp_servers.<name>]`。
-
-## 可观测性与遥测（OTel + Metrics）
-
-默认关闭。启用示例：
-
-```toml
-[otel]
-environment = "staging"
-exporter = "none"       # 或 otlp-http / otlp-grpc
-log_user_prompt = false
-```
-
-HTTP 导出示例：
-
-```toml
-[otel]
-exporter = { otlp-http = {
-  endpoint = "https://otel.example.com/v1/logs",
-  protocol = "binary",
-  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
-}}
-```
-
-gRPC 导出示例：
-
-```toml
-[otel]
-exporter = { otlp-grpc = {
-  endpoint = "https://otel.example.com:4317",
-  headers = { "x-otlp-meta" = "abc123" }
-}}
-```
-
-### 典型事件
-
-- `codex.conversation_starts`
-- `codex.api_request`
-- `codex.sse_event`
-- `codex.websocket_request`
-- `codex.websocket_event`
-- `codex.user_prompt`（默认脱敏）
-- `codex.tool_decision`
-- `codex.tool_result`
-
-### 常见 OTel 指标
-
-| 指标 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `codex.api_request` | counter | API 请求计数 |
-| `codex.api_request.duration_ms` | histogram | API 请求耗时 |
-| `codex.sse_event` | counter | SSE 事件计数 |
-| `codex.sse_event.duration_ms` | histogram | SSE 处理耗时 |
-| `codex.tool.call` | counter | 工具调用计数 |
-| `codex.tool.call.duration_ms` | histogram | 工具执行耗时 |
-
-### 匿名指标开关
-
-```toml
-[analytics]
-enabled = false
-```
-
-该开关与 OTel 导出独立。
-
-## 反馈开关
-
-默认允许 `/feedback`。可全局禁用：
-
-```toml
-[feedback]
-enabled = false
-```
-
-## 推理内容显示控制
-
-```toml
-hide_agent_reasoning = true
-# show_raw_agent_reasoning = true
-```
-
-建议仅在确有需要时显示原始推理内容。
-
-## 通知（notify / TUI 通知）
-
-外部通知程序：
-
-```toml
-notify = ["python3", "/path/to/notify.py"]
-```
-
-通知参数为单个 JSON 字符串，常见字段：
-
-- `type`
-- `thread-id`
-- `turn-id`
-- `cwd`
-- `input-messages`
-- `last-assistant-message`
-
-TUI 相关键位于 `[tui]`：
-
-- `tui.notifications`
-- `tui.notification_method`（`auto` / `osc9` / `bel`）
-- `tui.animations`
-- `tui.alternate_screen`
-- `tui.show_tooltips`
-
-## 历史持久化
-
-关闭历史：
-
-```toml
-[history]
-persistence = "none"
-```
-
-限制历史文件大小：
-
-```toml
-[history]
-max_bytes = 104857600
-```
-
-## 可点击引用（file_opener）
-
-```toml
-file_opener = "vscode" # 或 cursor / windsurf / vscode-insiders / none
-```
-
-## 项目指令发现
-
-两项关键参数：
-
-- `project_doc_max_bytes`
-- `project_doc_fallback_filenames`
-
-用于控制 `AGENTS.md`（及备选文件）读取范围与容量。

package/docs/official/codex/config-basic.md

@@ -1,141 +0,0 @@
-# 配置基础（Config basics）
-
-> 来源：`https://developers.openai.com/codex/config-basic`  
-> 同步日期：2026-02-12  
-> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
-
-Codex 会从多个层级读取配置。用户默认配置位于 `~/.codex/config.toml`，也可以在项目内通过 `.codex/config.toml` 做覆盖。  
-出于安全考虑，项目级配置只会在“受信任项目”中加载。
-
-## Codex 配置文件
-
-- 用户级配置：`~/.codex/config.toml`
-- 项目级配置：`<repo>/.codex/config.toml`
-
-在 Codex IDE 扩展中可通过右上角齿轮进入：
-
-`Codex Settings > Open config.toml`
-
-CLI 与 IDE 共享同一套配置层。你可以用它：
-
-- 设置默认模型与提供方（provider）
-- 配置审批策略与沙箱
-- 配置 MCP 服务器
-
-## 配置优先级（从高到低）
-
-1. CLI 参数与 `--config` 覆盖值
-2. `--profile <name>` 对应的 profile 配置
-3. 项目级 `.codex/config.toml`（从项目根到当前目录逐层加载，越近优先级越高，仅受信任项目）
-4. 用户级配置 `~/.codex/config.toml`
-5. 系统级配置（Unix 上可能存在 `/etc/codex/config.toml`）
-6. 内置默认值
-
-建议：
-
-- 把通用默认值放在用户级配置
-- 把场景差异放进 profile
-
-如果项目被标记为“不受信任”，Codex 会跳过项目内 `.codex/` 层，回退到用户级/系统级/内置默认值。
-
-## 常用配置项
-
-### 默认模型
-
-```toml
-model = "gpt-5.2"
-```
-
-### 命令审批策略
-
-```toml
-approval_policy = "on-request"
-```
-
-### 沙箱级别
-
-```toml
-sandbox_mode = "workspace-write"
-```
-
-### Web Search 模式
-
-`web_search` 可选值：
-
-- `"cached"`：使用缓存检索结果（默认）
-- `"live"`：实时联网检索（等价 `--search`）
-- `"disabled"`：关闭 Web Search
-
-```toml
-web_search = "cached"
-# web_search = "live"
-# web_search = "disabled"
-```
-
-### 推理强度
-
-```toml
-model_reasoning_effort = "high"
-```
-
-### 沟通风格
-
-```toml
-personality = "friendly" # 或 pragmatic / none
-```
-
-### 子进程环境变量策略
-
-```toml
-[shell_environment_policy]
-include_only = ["PATH", "HOME"]
-```
-
-### 日志目录
-
-```toml
-log_dir = "/absolute/path/to/codex-logs"
-```
-
-也可在单次运行时覆盖：
-
-```bash
-codex -c log_dir=./.codex-log
-```
-
-## 功能开关（Feature Flags）
-
-在 `config.toml` 中使用 `[features]` 表启用/禁用可选能力。
-
-```toml
-[features]
-shell_snapshot = true
-```
-
-### 常见功能键
-
-| 键名 | 默认值 | 成熟度 | 说明 |
-| :--- | :---: | :--- | :--- |
-| `collaboration_modes` | `true` | Stable | 协作模式（如 plan mode） |
-| `personality` | `true` | Stable | 人格/沟通风格控制 |
-| `request_rule` | `true` | Stable | 智能审批（`prefix_rule` 建议） |
-| `shell_tool` | `true` | Stable | 默认 shell 工具 |
-| `undo` | `true` | Stable | 按回合撤销能力 |
-| `shell_snapshot` | `false` | Beta | Shell 快照加速重复命令 |
-| `unified_exec` | `false` | Beta | PTY 统一执行工具 |
-| `apply_patch_freeform` | `false` | Experimental | 启用自由格式 `apply_patch` |
-| `apps` | `false` | Experimental | 启用 Apps/Connectors |
-| `runtime_metrics` | `false` | Experimental | 在 TUI 展示运行指标 |
-| `remote_models` | `false` | Experimental | 启动前刷新远程模型列表 |
-| `web_search` | `true` | Deprecated | 旧开关，建议改用顶层 `web_search` |
-
-说明：
-
-- 未写入某个功能键时，沿用默认值。
-- 建议优先使用 Stable/Beta 功能，Experimental 功能需谨慎启用。
-
-### 启用与禁用方式
-
-- 在 `config.toml` 的 `[features]` 下设置 `feature_name = true/false`
-- CLI 启用：`codex --enable feature_name`
-- CLI 连续启用多个：`codex --enable a --enable b`

package/docs/official/codex/config-reference.md

@@ -1,223 +0,0 @@
-# 配置参考（Configuration Reference）
-
-> 来源：`https://developers.openai.com/codex/config-reference`  
-> 同步日期：2026-02-12  
-> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。  
-> 说明：完整示例请结合 `config-sample.md` 一并阅读。
-
-本页用于快速检索 Codex 常用配置项。  
-配置分为两类：
-
-- `config.toml`：运行时配置
-- `requirements.toml`：受管控环境下的限制策略
-
-## `config.toml`
-
-### 核心与模型
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `model` | string | 默认模型名称 |
-| `review_model` | string | `/review` 专用模型（可选） |
-| `model_provider` | string | 当前模型提供方 ID |
-| `oss_provider` | string | `--oss` 模式默认本地 provider |
-| `model_context_window` | number | 模型上下文窗口 token 上限 |
-| `model_auto_compact_token_limit` | number | 自动压缩触发阈值 |
-| `tool_output_token_limit` | number | 单次工具输出的 token 限制 |
-| `log_dir` | string | 本地日志目录 |
-
-### 推理与表达
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `model_reasoning_effort` | string | 推理强度（如 `low`/`medium`/`high`） |
-| `model_reasoning_summary` | string | 推理摘要策略 |
-| `model_verbosity` | string | 响应冗长度 |
-| `model_supports_reasoning_summaries` | bool | 强制声明支持推理摘要 |
-| `personality` | string | 默认沟通风格（如 `friendly`） |
-
-### 指令与提示词覆盖
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `developer_instructions` | string | 额外开发指令（优先于项目文档前注入） |
-| `instructions` | string | 旧字段（兼容） |
-| `compact_prompt` | string | 压缩提示词内联覆盖 |
-| `model_instructions_file` | string | 覆盖内置基础指令的文件路径 |
-| `experimental_compact_prompt_file` | string | 压缩提示词文件路径 |
-
-### 审批与沙箱
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `approval_policy` | string | 审批策略（`untrusted`/`on-request`/`on-failure`/`never`） |
-| `sandbox_mode` | string | 沙箱模式（`read-only`/`workspace-write`/`danger-full-access`） |
-
-`[sandbox_workspace_write]` 子表常见键：
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `network_access` | bool | 是否允许沙箱内外网访问 |
-| `writable_roots` | string[] | 额外可写目录白名单 |
-| `exclude_tmpdir_env_var` | bool | 是否排除 `$TMPDIR` |
-| `exclude_slash_tmp` | bool | 是否排除 `/tmp` |
-
-### 身份与认证
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `cli_auth_credentials_store` | string | 凭据存储方式（`file`/`keyring`/`auto`） |
-| `chatgpt_base_url` | string | ChatGPT 登录后端地址 |
-| `forced_chatgpt_workspace_id` | string | 限定 ChatGPT workspace ID |
-| `forced_login_method` | string | 强制登录方式（`chatgpt`/`api`） |
-| `mcp_oauth_credentials_store` | string | MCP OAuth 凭据存储策略 |
-| `mcp_oauth_callback_port` | number | MCP OAuth 回调端口 |
-
-### 项目文档与根目录发现
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `project_doc_max_bytes` | number | 每层项目指令文档读取上限 |
-| `project_doc_fallback_filenames` | string[] | `AGENTS.md` 缺失时的备选文件名 |
-| `project_root_markers` | string[] | 项目根目录识别标记 |
-
-### 历史与引用链接
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `file_opener` | string | 引用链接协议（`vscode`/`cursor`/`none` 等） |
-
-`[history]` 子表：
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `persistence` | string | 历史持久化模式（`save-all`/`none`） |
-| `max_bytes` | number | 历史文件大小上限 |
-
-### Shell 环境策略
-
-`[shell_environment_policy]` 子表：
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `inherit` | string | 继承策略（`all`/`core`/`none`） |
-| `ignore_default_excludes` | bool | 是否忽略默认敏感变量过滤 |
-| `exclude` | string[] | 额外排除模式 |
-| `include_only` | string[] | 仅保留变量白名单 |
-| `set` | table | 强制注入/覆盖变量 |
-| `use_login_shell` | bool | 是否通过登录 shell 初始化 |
-
-### 通知与界面
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `notify` | string[] | 外部通知程序命令 |
-| `hide_agent_reasoning` | bool | 隐藏推理事件输出 |
-| `show_raw_agent_reasoning` | bool | 显示原始推理内容 |
-| `disable_response_storage` | bool | 禁止响应存储（若版本支持） |
-| `profile` | string | 默认 profile 名称 |
-| `web_search` | string | Web Search 模式（`cached`/`live`/`disabled`） |
-
-`[tui]` 子表常见键：
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `notifications` | bool/string[] | TUI 通知开关或事件白名单 |
-| `notification_method` | string | 终端通知方式（`auto`/`osc9`/`bel`） |
-| `animations` | bool | 是否启用动画 |
-| `alternate_screen` | string | 是否使用备用屏幕 |
-| `show_tooltips` | bool | 是否显示引导提示 |
-| `status_line` | string[] | 底部状态栏项 |
-
-### 中央功能开关
-
-`[features]` 子表（示例）：
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `collaboration_modes` | bool | 协作模式能力 |
-| `request_rule` | bool | 智能审批建议 |
-| `shell_snapshot` | bool | Shell 快照 |
-| `unified_exec` | bool | 统一执行工具 |
-| `apply_patch_freeform` | bool | 自由格式补丁工具 |
-| `apps` | bool | Apps/Connectors |
-| `personality` | bool | 风格控制能力 |
-| `runtime_metrics` | bool | 运行指标展示 |
-| `remote_models` | bool | 远程模型刷新 |
-
-### MCP 服务器
-
-`[mcp_servers.<name>]` 支持两类配置：
-
-1. **STDIO**：`command` + `args`
-2. **HTTP**：`url`
-
-常见键：
-
-- `enabled`
-- `required`
-- `env` / `env_vars`
-- `http_headers` / `env_http_headers`
-- `startup_timeout_sec`
-- `tool_timeout_sec`
-- `enabled_tools`
-- `disabled_tools`
-- `bearer_token_env_var`
-
-### 模型提供方
-
-`[model_providers.<name>]` 常见键：
-
-- `name`
-- `base_url`
-- `wire_api`（`responses` / `chat`）
-- `env_key`
-- `query_params`
-- `http_headers`
-- `env_http_headers`
-- `request_max_retries`
-- `stream_max_retries`
-- `stream_idle_timeout_ms`
-
-### 其他常见子表
-
-| 子表 | 用途 |
-| :--- | :--- |
-| `[profiles.<name>]` | 命名配置集 |
-| `[skills.<path>]` | 按路径启停 Skill |
-| `[apps.<app_name>]` | App/Connector 开关 |
-| `[projects."<absolute_path>"]` | 项目信任级别 |
-| `[analytics]` | 匿名指标开关 |
-| `[feedback]` | `/feedback` 开关 |
-| `[otel]` | OTel 总开关与导出策略 |
-| `[otel.exporter."otlp-http"]` | OTel HTTP 导出 |
-| `[otel.exporter."otlp-grpc"]` | OTel gRPC 导出 |
-
-## `requirements.toml`
-
-`requirements.toml` 用于组织/企业环境“限制可用能力”，防止本地配置越权。
-
-### 常见限制项
-
-| 键 | 类型 | 说明 |
-| :--- | :--- | :--- |
-| `allowed_approval_policies` | string[] | 允许的审批策略集合 |
-| `allowed_sandbox_modes` | string[] | 允许的沙箱模式集合 |
-
-### MCP 约束（示例）
-
-```toml
-allowed_approval_policies = ["untrusted", "on-request", "on-failure"]
-allowed_sandbox_modes = ["read-only", "workspace-write"]
-
-[mcp_servers.docs]
-identity = { command = "codex-mcp" }
-
-[mcp_servers.remote]
-identity = { url = "https://example.com/mcp" }
-```
-
-说明：
-
-- 通过 `requirements.toml` 可以禁止高风险策略（如 `approval_policy = "never"`、`sandbox_mode = "danger-full-access"`）。
-- 组织可用它统一团队安全基线。