@mison/ag-kit-cn 2.0.1

package/docs/official/antigravity/rules-workflows.md

@@ -0,0 +1,96 @@
+---
+slug: rules-workflows
+section: 代理
+title: 规则与工作流
+path:
+  - 代理
+  - 规则与工作流
+---
+
+# 规则与工作流（中文整理）
+
+> 来源：`https://antigravity.google/docs/rules-workflows`  
+> 同步日期：2026-02-12  
+> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
+
+# Rules（规则）
+
+Rules 是用户手动定义的约束，可在全局和工作区层级生效，用于把 Agent 的行为对齐到你的团队规范、技术栈和个人风格。
+
+## 快速开始
+
+1. 在编辑器 Agent 面板顶部点击 `...` 打开 Customizations。
+2. 进入 `Rules` 面板。
+3. 点击 `+ Global` 创建全局规则，或点击 `+ Workspace` 创建工作区规则。
+
+规则文件本质是 Markdown 文档。每个规则文件上限为 `12,000` 字符。
+
+## 全局规则
+
+- 路径：`~/.gemini/GEMINI.md`
+- 作用域：所有工作区
+
+## 工作区规则
+
+- 路径：`<workspace-root>/.agent/rules/`
+- 作用域：当前工作区（或对应 Git 根目录）
+
+## 规则激活方式
+
+每条规则可配置激活方式：
+
+- `Manual`：通过输入框 `@提及` 手动启用。
+- `Always On`：始终启用。
+- `Model Decision`：由模型根据规则自然语言描述决定是否启用。
+- `Glob`：按文件匹配模式启用（例如 `*.js`、`src/**/*.ts`）。
+
+## `@` 引用机制
+
+规则文件可通过 `@filename` 引用其他文件：
+
+- 相对路径：相对于规则文件所在目录解析。
+- 绝对路径：优先按真实绝对路径解析。
+- 若绝对路径不存在，系统会尝试按仓库相对路径解析。
+
+示例：
+
+- `@/path/to/file.md`：先尝试 `/path/to/file.md`，不存在则尝试 `workspace/path/to/file.md`。
+
+# Workflows（工作流）
+
+Workflows 用于把重复性任务固化为“可复用步骤序列”，例如部署、回评审意见、批量检查等。  
+工作流保存为 Markdown 文件，可通过斜杠命令 `/workflow-name` 调用。
+
+与 Rules 的区别：
+
+- Rules：提供长期、可复用的行为约束（提示层）。
+- Workflows：提供结构化执行步骤（流程层）。
+
+## 创建工作流
+
+1. 在 Agent 面板顶部点击 `...` 打开 Customizations。
+2. 进入 `Workflows` 面板。
+3. 点击 `+ Global` 创建全局工作流，或点击 `+ Workspace` 创建工作区工作流。
+
+## 执行工作流
+
+在 Agent 中输入：
+
+```text
+/workflow-name
+```
+
+工作流支持互相调用。例如 `/workflow-1` 的步骤中可包含“调用 `/workflow-2`”和“调用 `/workflow-3`”。
+
+工作流文件包含：
+
+- 标题
+- 描述
+- 有序步骤说明
+
+每个工作流文件上限为 `12,000` 字符。
+
+## 让 Agent 生成工作流
+
+你也可以直接让 Agent 帮你生成工作流。  
+当你已经手动完成一轮完整操作后，Agent 可以利用会话历史自动归纳并产出可复用工作流。

package/docs/official/antigravity/skills.md

@@ -0,0 +1,147 @@
+---
+title: 技能
+slug: skills
+path: ['代理', '技能']
+---
+
+# Agent 技能（中文整理）
+
+> 来源：`https://antigravity.google/docs/skills`  
+> 同步日期：2026-02-12  
+> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
+
+Skills 是扩展 Agent 能力的开放标准（见 `https://agentskills.io`）。  
+一个 Skill 是一个目录，至少包含一个 `SKILL.md` 指令文件。
+
+## 什么是 Skill
+
+Skill 是可复用的能力包，通常包含：
+
+- 任务处理指令
+- 最佳实践与约束
+- 可选脚本与资源文件
+
+会话开始时，Agent 先看到所有 Skill 的元信息（名称、描述）。  
+当某个 Skill 与当前任务相关时，Agent 再读取完整 `SKILL.md` 并执行。
+
+## Skill 存放位置
+
+Antigravity 支持两类 Skill：
+
+| 位置 | 作用域 |
+| :--- | :--- |
+| `<workspace-root>/.agent/skills/<skill-folder>/` | 工作区级 |
+| `~/.gemini/antigravity/skills/<skill-folder>/` | 全局级（所有工作区） |
+
+- 工作区 Skill：适合项目专属流程（如部署规范、测试约定）。
+- 全局 Skill：适合跨项目复用的个人工具或通用能力。
+
+## 如何创建 Skill
+
+1. 在 Skill 目录下创建文件夹。
+2. 在该文件夹中创建 `SKILL.md`。
+
+```text
+.agent/skills/
+└── my-skill/
+    └── SKILL.md
+```
+
+`SKILL.md` 示例：
+
+```markdown
+---
+name: my-skill
+description: 用于处理某类任务，在需要 X 或 Y 时使用。
+---
+
+# 我的 Skill
+
+这里写详细指令。
+
+## 何时使用
+
+- 场景 1
+- 场景 2
+
+## 如何执行
+
+按步骤给出模式、约束、输出要求。
+```
+
+## Frontmatter 字段
+
+| 字段 | 是否必填 | 说明 |
+| :--- | :--- | :--- |
+| `name` | 否 | Skill 唯一标识（建议小写 + 连字符）。省略时默认使用目录名。 |
+| `description` | 是 | 描述 Skill 的用途与触发场景，供 Agent 判断是否启用。 |
+
+建议：
+
+- 用第三人称描述 Skill 行为。
+- 包含关键触发词，便于 Agent 识别。
+
+## 推荐目录结构
+
+`SKILL.md` 是必需项，其他目录可选：
+
+```text
+.agent/skills/my-skill/
+├── SKILL.md        # 必需：核心指令
+├── scripts/        # 可选：执行脚本
+├── examples/       # 可选：示例实现
+└── resources/      # 可选：模板/资源
+```
+
+## Agent 如何使用 Skill
+
+Skill 使用“渐进式加载（progressive disclosure）”模式：
+
+1. **发现**：会话开始时仅加载 Skill 名称和描述。
+2. **激活**：判断相关后才读取完整 `SKILL.md`。
+3. **执行**：按 Skill 指令完成当前任务。
+
+你通常无需显式指定 Skill；Agent 会按上下文决定。  
+如需强制使用，可在对话中点名 Skill。
+
+## 编写最佳实践
+
+### 单一职责
+
+每个 Skill 聚焦一个能力，避免“全能型”大杂烩 Skill。
+
+### 描述精确
+
+`description` 要明确写出“做什么 + 什么时候用”。
+
+### 脚本黑盒化
+
+若包含脚本，优先让 Agent 用 `--help` 理解用法，避免无谓读取完整源码。
+
+### 添加决策分支
+
+复杂 Skill 建议加入“条件分支”说明，帮助 Agent 在不同场景选择正确路径。
+
+## 示例：代码审查 Skill
+
+```markdown
+---
+name: code-review
+description: 审查代码中的缺陷、风格问题与最佳实践偏差，适用于 PR 审查与质量检查。
+---
+
+# 代码审查 Skill
+
+## 审查清单
+
+1. 正确性：是否满足需求与预期行为？
+2. 边界条件：异常与错误路径是否覆盖？
+3. 风格一致性：是否符合项目规范？
+4. 性能：是否存在明显低效实现？
+
+## 反馈方式
+
+- 说明具体问题位置与影响
+- 解释原因，不只给结论
+- 提供可执行替代方案
+```

package/docs/official/codex/agents-md.md

@@ -0,0 +1,119 @@
+# 使用 AGENTS.md 自定义指令
+
+> 来源：`https://developers.openai.com/codex/guides/agents-md`  
+> 同步日期：2026-02-12  
+> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
+
+Codex 在执行任务前会读取 `AGENTS.md` 指令链。  
+通过“全局 + 项目 + 子目录”分层指令，你可以让 Agent 在不同仓库中保持一致行为，并允许就近覆盖。
+
+## Codex 如何发现与合并指令
+
+Codex 启动时会构建一次指令链（TUI 通常是每次启动会话时构建）。
+
+### 发现顺序
+
+1. **全局层（Codex Home）**
+   - 目录：`$CODEX_HOME`（默认 `~/.codex`）
+   - 优先读取：`AGENTS.override.md`
+   - 若无再读取：`AGENTS.md`
+   - 同层最多取第一个非空文件
+
+2. **项目层（从项目根到当前目录）**
+   - 每一层目录按顺序检查：
+     - `AGENTS.override.md`
+     - `AGENTS.md`
+     - `project_doc_fallback_filenames` 中定义的备选文件名
+   - 每层目录最多取一个文件
+
+3. **合并顺序**
+   - 从根目录到当前目录依次拼接
+   - 越靠近当前目录的文件越“后出现”，覆盖能力越强
+
+### 大小限制
+
+- 受 `project_doc_max_bytes` 控制（默认 `32 KiB`）
+- 空文件会被跳过
+- 达到上限后停止继续追加
+
+## 创建全局指令
+
+```bash
+mkdir -p ~/.codex
+```
+
+在 `~/.codex/AGENTS.md` 写入跨项目通用规范，例如：
+
+```markdown
+# 全局工作约定
+
+## 代码风格
+- 先保证正确性，再追求优化
+- 变更应尽量小而可回滚
+
+## 输出要求
+- 先给结论，再给依据
+- 明确列出未完成项与风险
+```
+
+## 创建项目级与目录级指令
+
+在仓库根目录放项目总约束：
+
+```text
+repo/
+├── AGENTS.md
+└── services/
+    ├── AGENTS.md
+    └── api/
+        └── AGENTS.md
+```
+
+这样可以形成“总规则 -> 模块规则 -> 子模块规则”的分层覆盖。
+
+## 备选文件名（Fallback）
+
+当目录内不存在 `AGENTS.md` 时，可以通过配置补充候选文件名：
+
+```toml
+project_doc_fallback_filenames = ["TEAM.md", "ASSISTANT.md"]
+```
+
+用途：
+
+- 与历史文档命名兼容
+- 渐进迁移到 `AGENTS.md`
+
+## 验证是否生效
+
+建议检查：
+
+1. `AGENTS.md` 是否在预期目录存在且非空
+2. 项目是否被标记为受信任
+3. `project_doc_max_bytes` 是否过小导致截断
+4. 是否被同层的 `AGENTS.override.md` 覆盖
+
+## 常见问题排查
+
+### 指令没生效
+
+- 检查当前 `cwd` 是否在目标目录链下
+- 检查项目是否不受信任（会跳过项目级配置层）
+- 检查文档是否超限被截断
+
+### 指令互相冲突
+
+- 按目录层级拆分职责
+- 通用规则上移到根目录
+- 细节规则下沉到子目录
+
+### 想临时覆盖全局规则
+
+- 在 `~/.codex` 放置 `AGENTS.override.md`，其优先级高于同层 `AGENTS.md`
+
+## 实践建议
+
+- 全局层只放稳定工作约定
+- 项目根放仓库级规范（测试、提交、架构约束）
+- 子目录放模块级细则（接口契约、边界约束）
+- 指令保持短句、可执行、可验证

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

@@ -0,0 +1,358 @@
+# 高级配置（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`（及备选文件）读取范围与容量。