@mison/ag-kit-cn 2.0.1 → 3.0.0-beta.0

package/docs/official/sources-index.md

@@ -1,8 +1,12 @@
 # 官方来源证据索引
 
-> 用途：为 `docs/official` 中文整理文档提供可机器校验的最小证据层（来源 URL + 拉取时间 + 快照哈希）。
+> 用途：为 `docs/official` 提供可复核的证据层（来源 URL + 时间 + SHA/提交记录）。
 
-## Antigravity
+## 历史本地快照（2026-02-12 UTC）
+
+> 说明：以下为此前本地中文整理稿的归档记录，保留用于追溯。
+
+### Antigravity
 
 | 本地文件 | 来源 URL | 拉取时间 (UTC) | SHA256 |
 | --- | --- | --- | --- |
@@ -10,7 +14,7 @@
 | `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
+### Codex
 
 | 本地文件 | 来源 URL | 拉取时间 (UTC) | SHA256 |
 | --- | --- | --- | --- |
@@ -23,10 +27,53 @@
 | `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` |
 
-## 校验方法
+## 在线核验结果（2026-03-04 UTC）
+
+> 说明：本节记录官方线上文档当前内容哈希。该哈希对应“远端当前内容”，用于判断更新，不等于本地整理稿哈希。
+
+### Antigravity（规则类）
+
+| 官方 URL | 当前 SHA256 | Last-Modified |
+| --- | --- | --- |
+| `https://antigravity.google/assets/docs/agent/skills.md` | `0e22e88bb316540d5db941e1c794f7a498536dead8f563e5da41d9530ede3b03` | `N/A` |
+| `https://antigravity.google/assets/docs/agent/rules-workflows.md` | `738e8982afda84f8ec75940472e225994ff65ed872296d31fb07c26888d447fd` | `N/A` |
+| `https://antigravity.google/assets/docs/agent/agent-modes-settings.md` | `cfa1662105b8401c77fdfa617ad264f40827573377958db1f14b22c5d99fb78c` | `N/A` |
+| `https://antigravity.google/assets/docs/agent/strict-mode.md` | `fefb2693dfdfdf641d37261e5e46f5e77090c8d4ad227f17d5b93bdc9e6e3ca7` | `N/A` |
+| `https://antigravity.google/assets/docs/agent/sandbox-mode.md` | `24ba64c5f270bd889654f660eb26d460a39ef95a366616a745bff756000f2863` | `N/A` |
+| `https://antigravity.google/assets/docs/tools/mcp.md` | `f2111a68a10bc8de059538faa9f7409ed71c17b3256176e0828b476fd71b03fd` | `N/A` |
+
+### Codex（规则类）
+
+| 官方 URL | 当前 SHA256 | Last-Modified |
+| --- | --- | --- |
+| `https://developers.openai.com/codex/skills.md` | `84f3062af1e105e62d926ec5156301c6058072961b800b1d9d5936f13dbbb260` | `Wed, 04 Mar 2026 01:27:34 GMT` |
+| `https://developers.openai.com/codex/rules.md` | `31d5ee04c58d6fc31389c9188cbeebc44a5c1fc74ce4ddce7c9a692b8d86de36` | `Wed, 04 Mar 2026 01:27:35 GMT` |
+| `https://developers.openai.com/codex/guides/agents-md.md` | `783657b995e1245d38e71854cd563d52021db2ddd3502b619a6a2a10785953fe` | `Wed, 04 Mar 2026 01:27:37 GMT` |
+| `https://developers.openai.com/codex/mcp.md` | `e46307e000c9f9b49560b69c866245ae8886ace76b12cc0cca71985a055fb65a` | `Wed, 04 Mar 2026 01:27:36 GMT` |
+| `https://developers.openai.com/codex/workflows.md` | `9ddeeaf1caecd91f225a94eb0dcea6c830da997b20c44da063abfd39cdf7dbc1` | `Wed, 04 Mar 2026 01:27:38 GMT` |
+| `https://developers.openai.com/codex/security.md` | `0f438953c912d4b17b124d9be3c1c32c22927a9a97cc15d46b32acd70da01e52` | `Wed, 04 Mar 2026 01:27:39 GMT` |
+
+### Gemini CLI（规则类）
+
+| 文档路径（仓库） | Raw URL | 当前 SHA256 | 最近提交 (SHA) | 提交时间 (UTC) |
+| --- | --- | --- | --- | --- |
+| `docs/cli/skills.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/skills.md` | `1c20e188cbf39efa93d0fd4f48f1dc605c9f156c62bfc725206f60cee82fcc01` | `d1ca8c0c80b4` | `2026-02-16T04:18:36Z` |
+| `docs/cli/creating-skills.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/creating-skills.md` | `f234e2ff0f1e8f49580137a99abf4fbcd8299afcf349e0710743fde1b35ed1e5` | `d43d772e657b` | `2026-01-29T23:52:06Z` |
+| `docs/cli/plan-mode.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/plan-mode.md` | `da18320390139d08efe28c4c7431047ad2a0860df93bfc8668d7b1d5ae2f1344` | `b5f3eb2c9c61` | `2026-03-03T21:36:51Z` |
+| `docs/core/subagents.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/core/subagents.md` | `b1345de3c156d7c59e047b66e96bd2653bf364e32e9e3b706d2ebe87c78e73d6` | `9e95b8b3c53d` | `2026-02-24T17:22:09Z` |
+| `docs/core/remote-agents.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/core/remote-agents.md` | `a5b6e6ad1ef617a8c5c5d8835e2808714fa85bcd4d0589d46b7197fa31ec2505` | `3103697ea73e` | `2026-01-27T22:15:28Z` |
+| `docs/tools/mcp-server.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/tools/mcp-server.md` | `e96e899d818d2e72b3f296ad8d5ea2544497d2ab90de2c42c0280a2950858ce2` | `20d884da2fe1` | `2026-02-27T20:04:36Z` |
+| `docs/reference/policy-engine.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/reference/policy-engine.md` | `abf7f48de1d77c1619d7add259f8788f9ca142824adaab003abb7fa7f1af3643` | `c89d4f9c6c97` | `2026-02-27T23:41:47Z` |
+| `docs/cli/gemini-md.md` | `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/gemini-md.md` | `d1ccf1120ae69e90f4becabe11342b4c857b4e8fc2807219dab96ef923ee338e` | `d25c469f7723` | `2026-02-19T23:47:39Z` |
+
+Gemini CLI 仓库最新推送时间：`2026-03-04T02:20:00Z`
+
+## 校验命令示例
 
 ```bash
-shasum -a 256 docs/official/codex/skills.md
+curl -fsSL --compressed https://developers.openai.com/codex/skills.md | shasum -a 256
 ```
 
-将输出哈希与本表对比即可。
+```bash
+gh api "repos/google-gemini/gemini-cli/commits?path=docs/cli/plan-mode.md&per_page=1"
+```

package/docs/operations.md

@@ -1,145 +1,75 @@
 # Ag-Kit（命令行工具）运维手册
 
-本文面向维护 Ag-Kit 及其管理的 Agent（智能体）资源的 DevOps（运维）或高级用户。
+本文面向维护 Ag-Kit 及其托管资源的 DevOps 与高级用户，基线为 v3 统一目录体系。
 
-## 1. 目录结构详解
-
-### 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            # 自动管理的忽略规则
+├── .agents/              # Canonical（唯一主目录）
+│   ├── manifest.json     # 完整性清单（v3）
+│   ├── skills/ agents/ workflows/ rules/
+│   ├── AGENTS.md         # 托管区块源
+│   ├── antigravity.rules # 托管区块源
+│   └── mcp_config.json   # MCP（含 Context7 主备）
+├── .agent/               # Antigravity 兼容投影（自动生成）
+├── .gemini/              # Gemini 兼容投影（自动生成/合并）
+├── .agents-backup/       # 覆盖前自动备份
+├── AGENTS.md             # 根入口（保留用户内容 + 托管区块）
+└── antigravity.rules     # 根托管说明（保留用户内容 + 托管区块）
 ```
 
-> 说明：`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 漂移检测警告
+### Legacy 目录策略
+- `.codex`：仅在识别为本工具托管 legacy 时迁移/清理。
+- 非托管 `.codex`：保留不删除。
 
-当 `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 自愈
+## 2. 核心运维动作
 
+### 2.1 初始化/升级
 ```bash
-ag-kit doctor --fix
+ag-kit init
+ag-kit update
 ```
 
-- **功能**:
-    - 如果 `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 客户端升级
+- `--target gemini|codex` 仍兼容，但内部归一为 full。
+- 非交互默认 full；遇到 `.agent` / `.gemini/agents` 冲突时，交互询问处理策略。
 
+### 2.2 批量更新
 ```bash
-npm install -g @mison/ag-kit-cn@latest
+ag-kit update-all --targets full
 ```
 
-若你以源码方式安装过，也可以继续使用源码升级：
+- 工作区索引：`~/.ag-kit/workspaces.json`（或 `AG_KIT_INDEX_PATH` 自定义）。
+- 可配合 `--prune-missing` 清理失效路径。
 
+### 2.3 诊断与修复
 ```bash
-git -C /path/to/antigravity-kit-cn pull
-cd /path/to/antigravity-kit-cn
-npm install -g .
+ag-kit doctor
+ag-kit doctor --fix
 ```
 
-### 3.2 资源库迁移：Gemini -> Codex
-
-1. 在项目根目录执行：
-    ```bash
-    ag-kit init --target codex --force
-    ```
-2. 系统会自动识别旧版 `.agent`，将其编译为 `.agents` 结构。
-3. 确认 `.agents` 生成无误。
-4. 移除旧版 `.agent`（可选）：
-    ```bash
-    rm -rf .agent
-    ```
-
-## 4. 日常维护
+- 检查 `.agents` 与 manifest 完整性。
+- 自动重放托管区块与兼容投影。
 
-### 4.1 清理本地生成产物
+## 3. 备份与漂移
 
-在仓库根目录执行：
+- 更新前若检测到用户修改冲突，会备份到 `.agents-backup/<timestamp>/`。
+- `manifest.json` 无法解析时，走全量快照备份后再更新。
 
-```bash
-npm run clean
-```
+## 4. MCP（Context7 主备）
 
-- 会清理常见生成目录：`.temp_ag_kit`、`coverage`、`web/.next`、`web/node_modules`、`web/out`、`web/.turbo`。
-- 只想预览，不实际删除：
+默认托管：
+- `context7`: `@upstash/context7-mcp`
+- `context7_backup`: `@iflow-mcp/context7-mcp@1.0.0`
 
-```bash
-npm run clean:dry-run
-```
+说明：官方不可用时可切备用；配置示例仅使用规范字段（如 `env`），不使用 `values`。
 
-### 4.2 回归检查
-
-```bash
-npm test
-```
-
-- 当前测试命令仅扫描 `tests/` 目录，避免误执行 `web/.next` 等构建产物中的文件。
-- 若需要检查前端代码规范（可选），先安装依赖再执行：
-
-```bash
-npm install --prefix web
-npm run lint --prefix web
-```
+## 5. 卸载注意
 
-### 4.3 一键健康复检
+不要无条件删除 `.codex`、`.gemini`。推荐仅删除本工具托管目录：
 
 ```bash
-npm run health-check
+rm -rf .agents .agent .agents-backup .gemini
 ```
 
-- 会顺序执行：`npm test`、CLI 临时工作区链路验证（`init/status/doctor/update/update-all/exclude`）、`npm run clean:dry-run`。
-- 适合升级后或准备发布前的快速回归确认。
+如需删除 `.codex`，请先确认其为本工具托管 legacy。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/ag-kit-cn",
-  "version": "2.0.1",
+  "version": "3.0.0-beta.0",
   "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
   "repository": {
     "type": "git",
@@ -25,12 +25,13 @@
     "clean:dry-run": "node scripts/clean.js --dry-run",
     "health-check": "bash scripts/health-check.sh",
     "postinstall": "node scripts/postinstall-check.js",
-    "test": "node --test tests"
+    "test": "node --test \"tests/**/*.test.js\""
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
+    ".agents/**",
     ".agent/**",
     "bin/**",
     "scripts/postinstall-check.js",