@mison/ag-kit-cn 2.0.1

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

@@ -0,0 +1,141 @@
+# 配置基础（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

@@ -0,0 +1,223 @@
+# 配置参考（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"`）。
+- 组织可用它统一团队安全基线。

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

@@ -0,0 +1,216 @@
+# 配置示例（Sample Configuration）
+
+> 来源：`https://developers.openai.com/codex/config-sample`  
+> 同步日期：2026-02-12  
+> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
+
+以下示例可作为 `config.toml` 起点。  
+按需复制你需要的键，不建议无差别全量粘贴。
+
+```toml
+################################################################################
+# Codex 示例配置（config.toml）
+# 说明：
+# - 根键必须位于各表定义之前
+# - 未设置的键会回退默认值
+# - 示例中部分键为可选项，按需启用
+################################################################################
+
+################################################################################
+# 核心模型
+################################################################################
+
+model = "gpt-5.2-codex"
+model_provider = "openai"
+# review_model = "gpt-5.2-codex"
+# oss_provider = "ollama"
+
+################################################################################
+# 推理与冗长度
+################################################################################
+
+model_reasoning_effort = "medium"     # minimal / low / medium / high / xhigh
+model_reasoning_summary = "auto"      # auto / concise / detailed / none
+model_verbosity = "medium"            # low / medium / high
+# model_supports_reasoning_summaries = false
+
+################################################################################
+# 指令覆盖
+################################################################################
+
+# developer_instructions = "额外开发指令"
+# instructions = "旧字段，兼容使用"
+# compact_prompt = "覆盖压缩提示词"
+# model_instructions_file = "/path/to/instructions.txt"
+# experimental_compact_prompt_file = "/path/to/compact_prompt.txt"
+
+################################################################################
+# 审批与沙箱
+################################################################################
+
+approval_policy = "on-request"        # untrusted / on-request / on-failure / never
+sandbox_mode = "read-only"            # read-only / workspace-write / danger-full-access
+
+[sandbox_workspace_write]
+network_access = false
+exclude_tmpdir_env_var = false
+exclude_slash_tmp = false
+writable_roots = []
+
+################################################################################
+# 认证与登录
+################################################################################
+
+cli_auth_credentials_store = "file"   # file / keyring / auto
+# chatgpt_base_url = "https://chatgpt.com/backend-api/"
+# forced_chatgpt_workspace_id = ""
+# forced_login_method = "chatgpt"      # chatgpt / api
+# mcp_oauth_credentials_store = "auto" # auto / file / keyring
+# mcp_oauth_callback_port = 4321
+
+################################################################################
+# 项目文档读取策略
+################################################################################
+
+project_doc_max_bytes = 32768
+project_doc_fallback_filenames = []
+project_root_markers = [".git"]
+
+################################################################################
+# Web Search
+################################################################################
+
+web_search = "cached"                 # cached / live / disabled
+
+################################################################################
+# 通知与输出
+################################################################################
+
+# notify = ["python3", "/path/to/notify.py"]
+hide_agent_reasoning = false
+show_raw_agent_reasoning = false
+file_opener = "vscode"                # vscode / cursor / windsurf / none
+log_dir = "~/.codex/log"
+
+################################################################################
+# Shell 环境变量策略
+################################################################################
+
+[shell_environment_policy]
+inherit = "all"                       # all / core / none
+ignore_default_excludes = false
+exclude = []
+include_only = []
+set = {}
+use_login_shell = false
+
+################################################################################
+# 历史记录
+################################################################################
+
+[history]
+persistence = "save-all"              # save-all / none
+# max_bytes = 104857600
+
+################################################################################
+# TUI 配置
+################################################################################
+
+[tui]
+notifications = true                  # true / false / ["agent-turn-complete"]
+# notification_method = "auto"        # auto / osc9 / bel
+animations = true
+show_tooltips = true
+alternate_screen = "auto"
+# status_line = ["model", "context-remaining", "git-branch"]
+
+################################################################################
+# 功能开关（features）
+################################################################################
+
+[features]
+collaboration_modes = true
+request_rule = true
+shell_tool = true
+undo = true
+shell_snapshot = false
+unified_exec = false
+apply_patch_freeform = false
+personality = true
+runtime_metrics = false
+apps = false
+
+################################################################################
+# MCP 服务器示例
+################################################################################
+
+[mcp_servers.context7]
+enabled = true
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+startup_timeout_sec = 10.0
+tool_timeout_sec = 60.0
+
+[mcp_servers.github]
+enabled = false
+url = "https://github-mcp.example.com/mcp"
+bearer_token_env_var = "GITHUB_TOKEN"
+startup_timeout_sec = 10.0
+tool_timeout_sec = 60.0
+
+################################################################################
+# Provider 示例
+################################################################################
+
+[model_providers.openai]
+name = "OpenAI"
+base_url = "https://api.openai.com/v1"
+wire_api = "responses"
+
+[model_providers.ollama]
+name = "Ollama"
+base_url = "http://localhost:11434/v1"
+wire_api = "chat"
+
+[model_providers.azure]
+name = "Azure"
+base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
+wire_api = "responses"
+query_params = { api-version = "2025-04-01-preview" }
+env_key = "AZURE_OPENAI_API_KEY"
+
+################################################################################
+# 命名配置集（profiles）
+################################################################################
+
+[profiles.deep-review]
+model = "gpt-5-pro"
+model_reasoning_effort = "high"
+approval_policy = "on-request"
+sandbox_mode = "read-only"
+
+[profiles.fast-local]
+model_provider = "ollama"
+model = "qwen2.5-coder:14b"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+
+################################################################################
+# 其他策略开关
+################################################################################
+
+[analytics]
+enabled = true
+
+[feedback]
+enabled = true
+
+[projects."/absolute/path/to/project"]
+trust_level = "trusted"               # trusted / untrusted
+```
+
+## 使用建议
+
+1. 先写最小配置：`model`、`approval_policy`、`sandbox_mode`。
+2. 再按场景补充：`features`、`mcp_servers`、`model_providers`。
+3. 团队协作时统一 `requirements.toml` 约束，避免配置越权。

package/docs/official/codex/mcp.md

@@ -0,0 +1,107 @@
+# 模型上下文协议（MCP）
+
+> 来源：`https://developers.openai.com/codex/mcp`  
+> 同步日期：2026-02-12  
+> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
+
+MCP（Model Context Protocol）用于把模型连接到外部工具与上下文。  
+在 Codex 中，你可以通过 MCP 让 Agent 访问第三方文档、浏览器工具、设计工具等。
+
+Codex CLI 与 IDE 扩展都支持 MCP，且共用同一份配置。
+
+## 支持的 MCP 类型
+
+- `STDIO` 服务器（本地进程）
+  - 支持环境变量注入
+- `Streamable HTTP` 服务器（远程地址）
+  - 支持 Bearer Token
+  - 支持 OAuth（若服务器支持）
+
+## MCP 配置位置
+
+默认写入：
+
+```text
+~/.codex/config.toml
+```
+
+也可在项目内配置：
+
+```text
+<repo>/.codex/config.toml
+```
+
+注意：项目级配置仅在“受信任项目”中生效。
+
+## 使用 CLI 配置 MCP
+
+### 添加服务器
+
+```bash
+codex mcp add <server-name> -- <stdio-command>
+```
+
+示例（Context7）：
+
+```bash
+codex mcp add context7 -- npx -y @upstash/context7-mcp
+```
+
+### 查看帮助与状态
+
+```bash
+codex mcp --help
+codex mcp list
+codex mcp get <server-name>
+```
+
+在 Codex TUI 中，可用 `/mcp` 查看当前会话可用服务器。
+
+## 通过 `config.toml` 手动配置
+
+### STDIO 示例
+
+```toml
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+```
+
+### HTTP 示例
+
+```toml
+[mcp_servers.docs_remote]
+url = "https://example.com/mcp"
+bearer_token_env_var = "DOCS_TOKEN"
+```
+
+常见可选字段：
+
+- `enabled`：是否启用
+- `required`：启动失败时是否阻断会话
+- `env` / `env_vars`：注入环境变量
+- `http_headers` / `env_http_headers`：HTTP 头
+- `startup_timeout_sec`：启动超时
+- `tool_timeout_sec`：工具调用超时
+- `enabled_tools` / `disabled_tools`：工具白名单/黑名单
+
+## OAuth 登录（按需）
+
+若远程 MCP 支持 OAuth，可执行：
+
+```bash
+codex mcp login <server-name>
+```
+
+## 常见 MCP 场景
+
+- 文档检索：接入官方 API/SDK 文档
+- 浏览器自动化：页面检查、交互、抓取
+- 设计协作：Figma 等上下文接入
+- 内部平台：接入公司内部服务与知识库
+
+## 安全建议
+
+- 默认最小权限：只配置必要服务器和必要工具。
+- Token 使用环境变量注入，不写死在仓库。
+- 对高风险服务器设置 `required = false`，避免启动失败阻断主流程。