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

package/CHANGELOG.md

@@ -7,24 +7,26 @@
 
 ## [Unreleased]
 
-## [3.0.0-beta.0] - 2026-03-04
+## [3.0.0] - 2026-03-13
 
-### 新增
+### 重大变更
 
-- 统一 full 目录体系：`ag-kit init/update` 默认安装 `.agents`（Canonical），并自动生成 `.agent` / `.gemini` 兼容投影。
-- Context7 MCP 双通道：默认同步 `context7`（官方）与 `context7_backup`（备用）配置。
-- 冲突交互：检测到已有 `.agent` 或 `.gemini/agents` 时，支持交互式处理策略选择。
+- **仓库模板源统一**：仓库内统一收敛到 `.agents/` 作为唯一 Canonical 模板源；旧 `.agent/` 仅保留输入兼容，不再作为主路径。
+- **项目级 Codex 体系稳定化**：Codex 项目安装/更新统一落到 `.agents/`，并继续支持从遗留 `.codex/` 自动迁移。
+- **全局安装模型重构**：`ag-kit global sync/status` 成为统一的全局 Skills 安装/更新入口。
 
-### 变更
+### 新增
 
-- `--target gemini|codex` 保持兼容，但内部归一为 full 安装流程。
-- `doctor/status/update-all` 统一按 full 模式工作，索引目标收敛为 `full`。
-- `.codex` 迁移策略更新：仅清理可识别为本工具托管的 legacy 目录；非托管目录保留。
+- **全局 Skills 同步**：
+  - `codex` 同步到 `~/.codex/skills/`
+  - `gemini` 同时同步到 `~/.gemini/skills/` 与 `~/.gemini/antigravity/skills/`
+- **状态契约收紧**：`ag-kit status --quiet` 与 `ag-kit global status --quiet` 统一输出 `installed / broken / missing`，并使用固定退出码 `0 / 1 / 2`。
+- **跨平台验证增强**：新增 `ci:verify`、Node 版 `health-check` 与 GitHub Actions 跨平台工作流。
 
 ### 修复
 
-- 修复升级场景对非托管 `.codex` 目录的误删除风险。
-- 修复 `.gemini/settings.json` 合并行为，保留用户非托管字段。
+- **旧索引兼容**：`update-all` 现在能自动归一化历史索引中的 `targets.full`，不再要求手工清理索引。
+- **全局路径对齐真实工具**：修正之前全局路径和真实消费端不一致的问题，确保文档、测试、CI 与实际工具行为一致。
 
 
 ## [2.0.2] - 2026-02-04

package/README.md

@@ -15,21 +15,26 @@
 npm install -g @mison/ag-kit-cn
 ```
 
+或使用 Bun：
+
+```bash
+bun install -g @mison/ag-kit-cn
+```
+
 然后在你的目标项目中初始化：
 
 ```bash
 cd /path/to/your-project
-ag-kit init                   # 统一 full 安装（.agents 为主目录）
-# 兼容参数仍可用，但会归一为 full
-ag-kit init --target codex
-ag-kit init --target gemini
+ag-kit init --target gemini   # 安装 Gemini 结构（.agent）
+ag-kit init --target codex    # 安装 Codex 结构（.agents + 托管规则注入）
+# 或者直接 ag-kit init，在交互中选择目标
 ```
 
 可选：不做全局安装，直接在仓库目录执行：
 
 ```bash
 cd /path/to/antigravity-kit-cn
-node bin/ag-kit.js init --path /path/to/your-project
+node bin/ag-kit.js init --target codex --path /path/to/your-project
 ```
 
 如需源码开发安装：
@@ -40,21 +45,46 @@ cd antigravity-kit-cn
 npm install -g .
 ```
 
-安装会统一写入 `.agents`，并自动生成兼容投影（`.agent`、`.gemini`），同时把托管内容注入工作区 `AGENTS.md` 与 `antigravity.rules`（说明性托管区块，不是 Codex 官方 `.rules` 审批策略文件）。
+这会把所选目标结构安装到你的项目中（`gemini -> .agent`，`codex -> .agents`），并把 Codex 托管内容注入工作区 `AGENTS.md` 与 `antigravity.rules`（说明性托管区块，不是 Codex 官方 `.rules` 审批策略文件）。
+
+### 全局安装（跨项目复用 Skills）
+
+为区分“项目安装”和“全局安装”，提供专用命令面：
+
+- 项目安装：`ag-kit init` / `ag-kit update`（功能最完整）
+- 全局安装：`ag-kit global sync`（仅同步 Skills，跨项目复用）
+- 默认行为：`ag-kit global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini`
+- 真实落盘：
+  - `codex` -> `~/.codex/skills/`
+  - `gemini` -> 同时写入 `~/.gemini/skills/` 与 `~/.gemini/antigravity/skills/`
+
+示例：
+
+```bash
+ag-kit global sync
+ag-kit global sync --target codex
+ag-kit global sync --target gemini
+ag-kit global status
+```
+
+全局安装只同步 Skills，不写入 Rules/Agents/Workflows，避免全局副作用。
+覆盖同名 Skill 前会自动备份；手动回滚方式见 `docs/TECH.md`。
+
+规划与边界细节见：`docs/PLAN.md`（规划）与 `docs/TECH.md`（技术）。
 
 ### Codex 规则边界说明
 
 - `antigravity.rules`：本项目生成并注入的托管说明文件，用于记录受管资源与运维约束。
 - `.rules`（如 `~/.codex/rules/default.rules`）：Codex 官方的命令审批/执行策略文件（Starlark 规则，支持 `prefix_rule()`）。
 - 默认行为：本项目不会自动写入你的全局 `~/.codex/rules`，避免引入不可预期的全局副作用。
-- 如需启用官方 `.rules` 审批策略，请参考 `docs/codex-rules-template.md`。
+- 如需启用官方 `.rules` 审批策略，请参考 `docs/TECH.md` 的「Codex 官方 `.rules`（手动配置）」小节。
 
 ### ⚠️ 关于 `.gitignore` 的重要说明
 
-如果你正在使用 **Cursor** 或 **Windsurf** 等 AI 编辑器，将 `.agent/`、`.agents/`、`.gemini/` 添加到 `.gitignore` 可能会阻止 IDE 索引工作流，导致斜杠命令（如 `/plan`、`/debug`）无法出现在对话建议中。
+如果你正在使用 **Cursor** 或 **Windsurf** 等 AI 编辑器，将 `.agent/`、`.agents/` 添加到 `.gitignore` 可能会阻止 IDE 索引工作流，导致斜杠命令（如 `/plan`、`/debug`）无法出现在对话建议中。
 
 **推荐方案：**
-1. 确保 `.agent/`、`.agents/`、`.gemini/` **不要** 出现在项目的 `.gitignore` 中。
+1. 确保 `.agent/`、`.agents/` **不要** 出现在项目的 `.gitignore` 中。
 2. 作为替代方案，将其加入本地排除文件：`.git/info/exclude`。
 
 ## 包含内容
@@ -134,34 +164,42 @@ CLI（命令行界面）工具：
 
 | 命令 | 描述 |
 | --- | --- |
-| `ag-kit init` | 安装统一 full 结构（`.agents` + 兼容投影） |
-| `ag-kit update` | 更新当前项目（自动收敛 legacy 目录） |
+| `ag-kit init` | 安装指定目标：gemini/codex |
+| `ag-kit update` | 更新当前项目已安装目标 |
 | `ag-kit update-all` | 批量更新所有已登记工作区 |
 | `ag-kit doctor` | 诊断安装完整性（可 `--fix` 自愈） |
+| `ag-kit global sync` | 全局同步 Skills（默认同步 codex + gemini；其中 gemini 同步到 gemini-cli 与 antigravity） |
+| `ag-kit global status` | 查看全局 Skills 安装状态 |
 | `ag-kit exclude` | 管理全局索引排除清单 |
 | `ag-kit status` | 检查安装状态 |
 
 ### 常用选项
 
 ```bash
-ag-kit init --path ./myapp                        # full 安装（.agents 主目录）
-ag-kit init --target codex --path ./myapp         # 兼容写法，仍归一为 full
-ag-kit init --target gemini --path ./myapp        # 兼容写法，仍归一为 full
-ag-kit init --non-interactive --path ./myapp      # 非交互默认 full
-ag-kit init --no-index --path ./tmp-workspace     # 安装但不写入全局索引
+ag-kit init --target gemini --path ./myapp        # 安装 Gemini 到指定目录
+ag-kit init --target codex --path ./myapp         # 安装 Codex 到指定目录
+ag-kit init --targets gemini,codex --path ./myapp # 一次安装多个目标
+ag-kit init --non-interactive --target codex      # 非交互模式必须显式指定目标
+ag-kit init --target codex --no-index --path ./tmp-workspace # 安装但不写入全局索引
 ag-kit init --branch dev --force                  # 覆盖安装并指定分支
 ag-kit init --quiet --dry-run                     # 预览操作而不执行
-ag-kit update --path ./myapp                      # 更新并收敛 legacy
-ag-kit update --target codex --path ./myapp       # 兼容写法，仍归一为 full
-ag-kit update --no-index --path ./myapp           # 更新但不刷新索引
-ag-kit doctor --fix --path ./myapp                # 检查并自动修复
-ag-kit update-all --targets full                  # 批量更新登记工作区
+ag-kit update --target codex --path ./myapp       # 更新指定目标（默认会刷新索引）
+ag-kit update --target codex --no-index --path ./myapp # 更新但不刷新索引
+ag-kit doctor --target codex --fix --path ./myapp # 检查并自动修复
+ag-kit update-all --targets codex                 # 批量更新所有登记工作区里的 codex 目标
 ag-kit update-all --prune-missing                 # 清理索引中已失效的路径
 ag-kit exclude list                               # 查看排除清单
 ag-kit exclude add --path /path/to/dir            # 新增排除路径
 ag-kit exclude remove --path /path/to/dir         # 删除排除路径
 ```
 
+### 状态命令约定
+
+- `ag-kit status --quiet`：输出 `installed` / `broken` / `missing`
+- `ag-kit global status --quiet`：输出 `installed` / `broken` / `missing`
+- 退出码：`0=installed`，`1=broken`，`2=missing`
+- `status` 面向自动化健康判断；如需问题明细，使用 `ag-kit doctor`
+
 ### 批量更新机制
 
 - 执行 `ag-kit init` / `ag-kit update` 时，会把工作区路径登记到全局索引文件：
@@ -179,19 +217,21 @@ ag-kit exclude remove --path /path/to/dir         # 删除排除路径
 ### 开发维护命令
 
 ```bash
-npm run clean           # 清理本地生成产物（如 web/.next、web/node_modules）
-npm run clean:dry-run   # 预览将被清理的路径
-npm test                # 只执行 tests/ 目录下测试
-npm run health-check    # 一键执行全链路健康复检
+bun run clean           # 清理本地生成产物（如 web/.next、web/node_modules）
+bun run clean:dry-run   # 预览将被清理的路径
+bun run test            # 只执行 tests/ 目录下测试
+bun run health-check    # 一键执行全链路健康复检
 ```
 
 如果你在 `web/` 子项目内开发，可按需执行：
 
 ```bash
-npm install --prefix web
-npm run lint --prefix web
+bun install --cwd web
+bun run lint --cwd web
 ```
 
+> 说明：若你通过 `bun install -g` 安装 CLI，Bun 默认会阻止本包 `postinstall`。上游同名包冲突提示会在首次执行 `ag-kit init/update/update-all/global sync` 时给出。
+
 ## 卸载
 
 ### 卸载本机全局 CLI
@@ -212,17 +252,14 @@ macOS / Linux / WSL:
 
 ```bash
 cd /path/to/your-project
-rm -rf .agent .agents .agents-backup .gemini antigravity.rules
-# 若确认 .codex 是本工具托管 legacy（含 manifest.json 且 target=codex/full），可再删除：
-# rm -rf .codex
+rm -rf .agent .agents .agents-backup .codex
 ```
 
 Windows PowerShell:
 
 ```powershell
 Set-Location C:\path\to\your-project
-Remove-Item .agent,.agents,.agents-backup,.gemini,antigravity.rules -Recurse -Force -ErrorAction SilentlyContinue
-# 若确认 .codex 为本工具托管 legacy，再手动删除 .codex
+Remove-Item .agent,.agents,.agents-backup,.codex -Recurse -Force -ErrorAction SilentlyContinue
 ```
 
 Windows CMD:
@@ -232,9 +269,7 @@ cd /d C:\path\to\your-project
 rmdir /s /q .agent
 rmdir /s /q .agents
 rmdir /s /q .agents-backup
-rmdir /s /q .gemini
-del /f /q antigravity.rules
-REM 若确认 .codex 为本工具托管 legacy，再手动删除 .codex
+rmdir /s /q .codex
 ```
 
 ### 清理批量更新索引（可选）