@mison/ag-kit-cn 2.0.1 → 3.0.0

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

@@ -1,216 +0,0 @@
-# 配置示例（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

@@ -1,107 +0,0 @@
-# 模型上下文协议（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`，避免启动失败阻断主流程。

package/docs/official/codex/rules.md

@@ -1,79 +0,0 @@
-# 规则（命令审批规则）
-
-> 来源：`https://developers.openai.com/codex/rules`  
-> 同步日期：2026-02-12  
-> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
-
-Codex Rules 用于控制“哪些命令允许在沙箱外执行”，属于安全与审批策略层。  
-该能力为实验特性，后续可能调整。
-
-## 创建规则文件
-
-1. 在 `./codex/rules/` 下创建 `.rules` 文件（例如 `~/.codex/rules/default.rules`）。
-2. 写入规则。
-
-示例：在沙箱外执行 `gh pr view` 前必须提示审批。
-
-```python
-prefix_rule(
-    pattern = ["gh", "pr", "view"],
-    decision = "prompt",
-    justification = "查看 PR 需要人工确认",
-    match = [
-        "gh pr view 7888",
-        "gh pr view --repo openai/codex",
-    ],
-    not_match = [
-        "gh pr list",
-    ],
-)
-```
-
-## 规则字段说明
-
-`prefix_rule(...)` 常用字段：
-
-- `pattern`：命令前缀（按 token 匹配）
-- `decision`：命中后的动作
-- `justification`：规则说明（可选）
-- `match`：应命中的测试样例（可选）
-- `not_match`：不应命中的测试样例（可选）
-
-`decision` 常见值：
-
-- `prompt`：询问用户
-- `allow`：允许
-- `deny`：拒绝
-
-## 关于 shell 包装命令与复合命令
-
-常见包装命令包括：
-
-- `bash -lc "..."`
-- `sh -c "..."`
-- `zsh -lc "..."`
-- `python -c "..."`
-
-在可安全拆分时，Codex 可能提取出真实命令做前缀匹配；  
-在不可安全拆分时，会把整体当作一个命令匹配。
-
-### 可安全拆分的典型情况
-
-- 单一命令、无复杂重定向/管道/变量展开
-- 命令结构明确，不会因拆分改变语义
-
-### 不拆分的典型情况
-
-- 包含复杂 shell 语法（多条命令、重定向、条件、子 shell 等）
-- 拆分后可能造成语义偏差或安全风险
-
-## 测试规则文件
-
-建议每条规则都写 `match` / `not_match` 示例，作为“内联单元测试”。  
-这样可以在维护规则时快速验证匹配行为，减少误放行或误阻断。
-
-## 规则语言边界
-
-- Rules 只负责命令级审批策略，不负责业务逻辑说明。
-- 业务约束建议放在 `AGENTS.md` 或项目文档中。
-- 高风险命令建议默认 `prompt` 或 `deny`，再按需要放开。

package/docs/official/codex/skills.md

@@ -1,114 +0,0 @@
-# Agent 技能（Codex）
-
-> 来源：`https://developers.openai.com/codex/skills`  
-> 同步日期：2026-02-12  
-> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
-
-Skills 用于给 Codex 增加任务专用能力。  
-一个 Skill 通常打包了指令、参考资料以及可选脚本，便于 Agent 稳定复用某类流程。
-
-Skills 适用于 Codex CLI、IDE 扩展和 Codex App。
-
-## Skill 基本结构
-
-一个 Skill 目录至少包含 `SKILL.md`：
-
-```text
-my-skill/
-├── SKILL.md        # 必需：元信息 + 指令
-├── scripts/        # 可选：可执行脚本
-├── references/     # 可选：参考文档
-└── assets/         # 可选：模板/资源
-```
-
-`SKILL.md` 需包含 `name` 与 `description`：
-
-```markdown
----
-name: skill-name
-description: 说明该 skill 的用途与触发场景
-metadata:
-  short-description: 可选的简短说明
----
-
-# Skill 标题
-
-在此编写可执行指令。
-```
-
-## Codex 如何使用 Skills
-
-Codex 采用“渐进式加载”：
-
-1. 会话开始时先读取各 Skill 的元信息（`name`、`description`、路径等）。
-2. 仅当某 Skill 与当前任务相关时，才读取完整 `SKILL.md`。
-3. 执行过程中按 Skill 指令调用脚本/引用资料。
-
-## 创建 Skill
-
-两种方式：
-
-- 使用内置 Skill（例如 `$skill-creator`）辅助生成
-- 手动创建目录与 `SKILL.md`
-
-手动创建建议流程：
-
-1. 创建目录 `my-skill/`
-2. 写好 `SKILL.md` 的 frontmatter
-3. 按需补充 `scripts/`、`references/`、`assets/`
-
-## Skill 存放位置
-
-常见位置：
-
-- 全局：`$HOME/.agents/skills/`
-- 项目：从当前工作目录开始，向上到仓库根目录，按链路扫描 `.agents/skills/`
-
-实践建议：
-
-- 跨项目复用放全局
-- 项目专属流程放仓库内并随代码版本管理
-
-## 安装与管理
-
-可通过 CLI 管理技能开关与列表（实际命令以当前版本为准）：
-
-```bash
-codex skills list
-codex skills enable <skill-name>
-codex skills disable <skill-name>
-```
-
-对于 App/Server 场景，也可通过 API 传入 Skill 项。
-
-## 可选元数据
-
-除必填字段外，可在 frontmatter 增加元数据（如 `short-description`），用于改善 UI 展示和匹配体验。  
-但不要把业务逻辑藏在元数据里，核心行为应写在正文指令区。
-
-## 编写最佳实践
-
-### 1. 描述要能触发
-
-`description` 建议写清：
-
-- 做什么
-- 何时用
-- 不适用场景
-
-### 2. 单一职责
-
-一个 Skill 解决一类问题，不要做“万能包”。
-
-### 3. 脚本优先可执行
-
-把复杂流程写进 `scripts/`，在 `SKILL.md` 中说明参数与调用方式。  
-避免要求 Agent 反复阅读大段脚本源码。
-
-### 4. 给出决策分支
-
-复杂任务建议提供“条件 -> 路径”决策表，降低误用率。
-
-### 5. 保持可迁移
-
-尽量避免绑定私有路径与私有环境变量，必要时在 `references/` 说明依赖前置条件。

package/docs/official/sources-index.md

@@ -1,32 +0,0 @@
-# 官方来源证据索引
-
-> 用途：为 `docs/official` 中文整理文档提供可机器校验的最小证据层（来源 URL + 拉取时间 + 快照哈希）。
-
-## Antigravity
-
-| 本地文件 | 来源 URL | 拉取时间 (UTC) | SHA256 |
-| --- | --- | --- | --- |
-| `docs/official/antigravity/agent-modes-settings.md` | `https://antigravity.google/assets/docs/agent/agent-modes-settings.md` | `2026-02-12T12:56:22Z` | `614174f8c730a0db8b290dede16b294a9535cef7b9ddca9c108dc2ef583b2919` |
-| `docs/official/antigravity/rules-workflows.md` | `https://antigravity.google/assets/docs/agent/rules-workflows.md` | `2026-02-12T12:56:22Z` | `063b2e9c86555f0103d0fafee5f71caf330cd95fb25257841efe32d36ee9667b` |
-| `docs/official/antigravity/skills.md` | `https://antigravity.google/assets/docs/agent/skills.md` | `2026-02-12T12:56:22Z` | `2176fc1968c2188daed75b064f8771e4516b4b462cc5c1b98553e05cfab055fa` |
-
-## Codex
-
-| 本地文件 | 来源 URL | 拉取时间 (UTC) | SHA256 |
-| --- | --- | --- | --- |
-| `docs/official/codex/config-basic.md` | `https://developers.openai.com/codex/config-basic.md` | `2026-02-12T12:56:22Z` | `9a270e83da4e3467c117166cc69684cace72037c97c96f0f05f212d28ccf0809` |
-| `docs/official/codex/config-advanced.md` | `https://developers.openai.com/codex/config-advanced.md` | `2026-02-12T12:56:22Z` | `ed1ebb5ad918fd9043ebeb176d1f29654d76547c4ae896eb4718db320f98a1af` |
-| `docs/official/codex/config-reference.md` | `https://developers.openai.com/codex/config-reference.md` | `2026-02-12T12:56:22Z` | `e23bc1439e3f4cb907d165e6980ece03070d69484f74c4cb3dd95068c519a91c` |
-| `docs/official/codex/config-sample.md` | `https://developers.openai.com/codex/config-sample.md` | `2026-02-12T12:56:22Z` | `80af7755383b5f3956b3288435bca81ef02062f6dd988aa6205fe1ae95a3660b` |
-| `docs/official/codex/rules.md` | `https://developers.openai.com/codex/rules.md` | `2026-02-12T12:56:22Z` | `c9ca3c8bf4fa68ccf85c831388ea360b6e2108bcfcfcc0b7bd7e2ab5df173af1` |
-| `docs/official/codex/agents-md.md` | `https://developers.openai.com/codex/guides/agents-md.md` | `2026-02-12T12:56:22Z` | `ed8fd0bdb19826d907424d313d38b37fe9a60c78b96692f409e1f15373817aac` |
-| `docs/official/codex/mcp.md` | `https://developers.openai.com/codex/mcp.md` | `2026-02-12T12:56:22Z` | `bb7d0e864ed572a11067505f9cd673972610d2d53997db3647b309da00763fa2` |
-| `docs/official/codex/skills.md` | `https://developers.openai.com/codex/skills.md` | `2026-02-12T12:56:22Z` | `8ca8093fa07e50d302a76a6693789995bb733208fd3e89022e2ebd2328b3b64c` |
-
-## 校验方法
-
-```bash
-shasum -a 256 docs/official/codex/skills.md
-```
-
-将输出哈希与本表对比即可。

package/docs/operations.md

@@ -1,145 +0,0 @@
-# Ag-Kit（命令行工具）运维手册
-
-本文面向维护 Ag-Kit 及其管理的 Agent（智能体）资源的 DevOps（运维）或高级用户。
-
-## 1. 目录结构详解
-
-### 1.1 项目根目录
-
-```text
-/my-project
-├── .agent/               # Legacy（旧版）Gemini 模式直连目录（使用 Gemini 时）
-├── .agents/              # Codex 托管上游目录（只读/自动管理）
-│   ├── manifest.json     # 完整性清单，用于漂移检测
-│   ├── AGENTS.md         # 核心规则源（由构建器生成）
-│   ├── antigravity.rules # 风险控制源（由构建器生成）
-│   └── skills/           # 编译后的技能
-├── .agents-backup/       # Codex 自动备份目录（发生漂移覆盖时生成）
-├── .codex/               # Legacy 历史目录（更新/doctor 时自动迁移清理）
-├── AGENTS.md             # 工作区主入口（保留用户内容 + 托管区块注入）
-├── antigravity.rules     # 工作区托管说明（保留用户内容 + 托管区块注入）
-└── .gitignore            # 自动管理的忽略规则
-```
-
-> 说明：`antigravity.rules` 是本项目的托管说明文件，不等同于 Codex 官方 `.rules` 审批策略文件。  
-> Codex 官方策略文件通常位于 `~/.codex/rules/default.rules`，本项目不会自动写入该全局路径。
-
-### 1.2 全局数据
-
-- **macOS / Linux**: `~/.ag-kit/workspaces.json`
-- **Windows**: `%USERPROFILE%\.ag-kit\workspaces.json`
-- 默认不会把系统临时目录写入索引（如 macOS `/var/folders/...`、`/tmp`、`/private/tmp`，Linux `/tmp`，Windows `%TEMP%`）。
-- 对临时验证场景，可在 `init/update` 时加 `--no-index` 完全跳过索引登记。
-- `ag-kit update` 仅处理当前目录（或 `--path` 指定目录），不依赖全局索引。
-- `ag-kit update-all` 仅处理索引内工作区；若项目曾使用 `--no-index`，可在项目内执行一次不带 `--no-index` 的 `ag-kit update` 重新纳入索引。
-
-## 2. 故障排查
-
-### 2.1 更新失败或中断
-
-当前版本已引入 Atomic Update（原子更新）机制。
-
-- 更新过程先在临时目录准备，最后通过一次 `rename` 操作生效。
-- **现象**: 如果进程在更新阶段被中断，项目目录不会出现半写状态，可能残留临时目录（例如 `/tmp/ag-kit-*`）。
-- **解决**: 无需手动干预，重新运行 update 即可。
-
-### 2.2 漂移检测警告
-
-当 `ag-kit update` 或 `ag-kit doctor` 报告 Drift（漂移）时：
-
-- **原因**: 用户手动修改了 `.agents` 目录下的受管文件。
-- **后果**: 更新时会强制覆盖这些修改。
-- **自动备份**: 覆盖前，Ag-Kit 会将修改过的文件备份到 `.agents-backup/<timestamp>/`。
-- **智能覆盖**: 仅当文件确实是“用户修改且与新版本不同”时才备份；如果本地文件已与新版本一致，不会重复备份。
-- **解决**: 检查备份，将需要的修改迁移到上游源码或通过 Overlay（覆盖层）机制实现。
-
-### 2.3 Windows 权限问题
-
-- 如果遇到 `EPERM` 或 `EBUSY`：
-    - 确保没有 IDE 或终端占用 `.agents` 目录。
-    - 关闭占用后重新执行 `ag-kit update` 或 `ag-kit doctor --fix`。
-
-### 2.4 Doctor 自愈
-
-```bash
-ag-kit doctor --fix
-```
-
-- **功能**:
-    - 如果 `manifest.json` 丢失，会对照当前文件状态重新生成（注意：这会假设当前状态是正确的）。
-    - 会重同步 `AGENTS.md` 和 `antigravity.rules` 的托管区块。
-    - Gemini 目标当前不支持自动修复，建议执行 `ag-kit update --target gemini`。
-
-## 3. 升级流程
-
-### 3.0 Codex 官方 `.rules`（可选）
-
-如果你需要启用 Codex 官方命令审批策略（`prefix_rule()` 等），请手动配置 `~/.codex/rules/default.rules`。  
-可直接参考：`docs/codex-rules-template.md`。
-
-### 3.1 客户端升级
-
-```bash
-npm install -g @mison/ag-kit-cn@latest
-```
-
-若你以源码方式安装过，也可以继续使用源码升级：
-
-```bash
-git -C /path/to/antigravity-kit-cn pull
-cd /path/to/antigravity-kit-cn
-npm install -g .
-```
-
-### 3.2 资源库迁移：Gemini -> Codex
-
-1. 在项目根目录执行：
-    ```bash
-    ag-kit init --target codex --force
-    ```
-2. 系统会自动识别旧版 `.agent`，将其编译为 `.agents` 结构。
-3. 确认 `.agents` 生成无误。
-4. 移除旧版 `.agent`（可选）：
-    ```bash
-    rm -rf .agent
-    ```
-
-## 4. 日常维护
-
-### 4.1 清理本地生成产物
-
-在仓库根目录执行：
-
-```bash
-npm run clean
-```
-
-- 会清理常见生成目录：`.temp_ag_kit`、`coverage`、`web/.next`、`web/node_modules`、`web/out`、`web/.turbo`。
-- 只想预览，不实际删除：
-
-```bash
-npm run clean:dry-run
-```
-
-### 4.2 回归检查
-
-```bash
-npm test
-```
-
-- 当前测试命令仅扫描 `tests/` 目录，避免误执行 `web/.next` 等构建产物中的文件。
-- 若需要检查前端代码规范（可选），先安装依赖再执行：
-
-```bash
-npm install --prefix web
-npm run lint --prefix web
-```
-
-### 4.3 一键健康复检
-
-```bash
-npm run health-check
-```
-
-- 会顺序执行：`npm test`、CLI 临时工作区链路验证（`init/status/doctor/update/update-all/exclude`）、`npm run clean:dry-run`。
-- 适合升级后或准备发布前的快速回归确认。