@mison/ling 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@
 
 ## [Unreleased]
 
+## [ling-1.2.0] - 2026-03-14
+
+### 新增
+
+- `antigravity` 作为独立目标进入 CLI 主链路：`init/update/update-all/status/doctor/global sync/spec enable|disable` 均可直接指定，不再由 `gemini` 隐式代管。
+- 共享 `.agent/` 工作区新增本地安装状态文件 `.ling/install-state.json`，用于准确记录 `gemini` / `antigravity` 的逻辑注册身份，即使工作区未写入全局索引也能正确识别。
+
+### 变更
+
+- 全局同步默认目标调整为 `codex + gemini + antigravity`；`--target gemini` 仅写入 `~/.gemini/skills/`，`--target antigravity` 仅写入 `~/.gemini/antigravity/skills/`。
+- README、TECH、PLAN 与测试基线同步对齐新的三目标语义，并补充共享 `.agent/` 的状态识别说明。
+- 健康检查与维护链路统一收口到 `npm`，Web 子项目不再保留 `bun.lock`。
+
+### 维护
+
+- `reference/` 清理重复官方资料：删除 `reference/official-docs/` 镜像，仅保留 `reference/official/` 单份受管参考。
+- 根目录与 `reference/.gitignore` 调整为白名单模式，仅跟踪 `reference/official/`、`reference/docs-archive/` 等保留资料。
+
 ## [ling-1.1.1] - 2026-03-14
 
 ### 新增
@@ -80,7 +98,8 @@
 
 本项目在 Ling 重启前的 2.x/3.x 版本记录已冻结，不再维护。
 
-[Unreleased]: https://github.com/MisonL/Ling/compare/ling-1.1.1...HEAD
+[Unreleased]: https://github.com/MisonL/Ling/compare/ling-1.2.0...HEAD
+[ling-1.2.0]: https://github.com/MisonL/Ling/releases/tag/ling-1.2.0
 [ling-1.1.1]: https://github.com/MisonL/Ling/releases/tag/ling-1.1.1
 [ling-1.1.0]: https://github.com/MisonL/Ling/releases/tag/ling-1.1.0
 [ling-1.0.2]: https://github.com/MisonL/Ling/releases/tag/ling-1.0.2

package/README.md

@@ -12,178 +12,196 @@
 npm install -g @mison/ling
 ```
 
-然后在你的目标项目中初始化：
+`ling` 解决三件事：
+
+- 项目内安装 Gemini / Antigravity / Codex 资产
+- 全局同步可复用 Skills
+- 为项目启用 Spec 工作流
+
+最常见的项目初始化：
 
 ```bash
 cd /path/to/your-project
-ling init --target gemini   # 安装 Gemini 结构（.agent）
-ling init --target codex    # 安装 Codex 结构（.agents + 托管规则注入）
-# 或者直接 ling init，在交互中选择目标
+ling init --target gemini
+ling init --target antigravity
+ling init --target codex
 ```
 
-说明：
-- npm 安装的主命令入口为 `ling`。
-
-可选：不做全局安装，直接在仓库目录执行：
+如果要同时安装多个目标：
 
 ```bash
-cd /path/to/Ling
-node bin/ling.js init --target codex --path /path/to/your-project
+ling init --targets gemini,antigravity,codex
 ```
 
-如需源码开发安装：
+如果你要先做全局 Skills 安装：
 
 ```bash
-git clone https://github.com/MisonL/Ling.git
-cd Ling
-npm install -g .
+ling global sync
+ling global sync --target codex
+ling global sync --target gemini
+ling global sync --target antigravity
 ```
 
-这会把所选目标结构安装到你的项目中（`gemini -> .agent`，`codex -> .agents`），并把 Codex 托管内容注入工作区 `AGENTS.md` 与 `ling.rules`（说明性托管区块，不是 Codex 官方 `.rules` 审批策略文件）。
+## 先选模式
 
-### 全局安装（跨项目复用 Skills）
+| 你要做什么 | 命令 | 结果 |
+| --- | --- | --- |
+| 给当前项目安装完整资产 | `ling init` | 项目内生成 `.agent/` / `.agents/`；共享 `.agent/` 时会维护 `.ling/install-state.json` |
+| 给电脑全局同步可复用 Skills | `ling global sync` | 写入 `~/.codex/skills/`、`~/.gemini/skills/` 等 |
+| 给项目启用 Spec 工作流 | `ling spec init` | 项目内生成 `issues.csv` 等 Spec 资产 |
 
-为区分“项目安装”和“全局安装”，提供专用命令面：
+一句话区分：
 
-- 项目安装：`ling init` / `ling update`（功能最完整）
-- 全局安装：`ling global sync`（仅同步 Skills，跨项目复用）
-- 默认行为：`ling global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini`
-- 真实落盘：
-  - `codex` -> `~/.codex/skills/`
-  - `gemini` -> 同时写入 `~/.gemini/skills/` 与 `~/.gemini/antigravity/skills/`
+- `init` 面向项目
+- `global sync` 面向整台电脑
+- `spec init` 面向项目里的任务驱动流程
 
-示例：
+## 项目安装
+
+项目安装是默认用法，也是能力最完整的模式。
+
+- `gemini` 写入项目内 `.agent/`
+- `antigravity` 写入项目内 `.agent/`（与 Gemini 复用目录，命令与状态独立）
+- `codex` 写入项目内 `.agents/`
+- Ling 会在项目内写入 `.ling/install-state.json`，用于记录共享 `.agent/` 上到底注册了 `gemini`、`antigravity` 还是两者
+- Codex 额外注入工作区 `AGENTS.md` 和 `ling.rules`
 
 ```bash
-ling global sync
-ling global sync --target codex
-ling global sync --target gemini
-ling global status
+cd /path/to/your-project
+ling init --target gemini
+ling init --target antigravity
+ling init --target codex
+ling update
+ling doctor
 ```
 
-全局安装只同步 Skills，不写入 Rules/Agents/Workflows，避免全局副作用。
-覆盖同名 Skill 前会自动备份；手动回滚方式见 `docs/TECH.md`。
+非交互环境下，`init` 必须显式传 `--target` 或 `--targets`。
 
-规划与边界细节见：`docs/PLAN.md`（规划）与 `docs/TECH.md`（技术）。
+## 全局 Skills
 
-版本与发布约定：
-- npm 包版本遵循 SemVer（`package.json`）
-- git tag 与 CLI `--version` 显示使用 `ling-<SemVer>`（例如 `ling-1.0.0`）
+全局模式只做一件事：把 Skills 同步到真实消费端目录，方便跨项目复用。
 
-### 已有资产冲突处理（交互确认 + 备份回退）
+```bash
+ling global sync
+ling global sync --target codex
+ling global sync --target gemini
+ling global sync --target antigravity
+ling global status
+```
 
-当检测到目标目录已存在且内容不同（或 Codex 目录存在漂移、缺失 `manifest.json`、包含未知文件）时，`ling` 会在交互终端中逐项询问处理方式：
+- `codex` -> `~/.codex/skills/`
+- `gemini` -> `~/.gemini/skills/`
+- `antigravity` -> `~/.gemini/antigravity/skills/`
 
-- `k` 保留（跳过此资产）
-- `b` 备份后移除（推荐）
-- `r` 直接移除（不备份）
+全局模式不会写入项目 Rules、Agents、Workflows，也不会改你的全局 `~/.codex/rules`。
 
-同一类别的冲突可选择“一键复用”，后续遇到同类资产不再重复询问。
+## Spec
 
-备份落盘位置：
-- 项目级预备份：
-  - Gemini：`<project>/.agent-backup/<timestamp>/preflight/.agent/`
-  - Codex：`<project>/.agents-backup/<timestamp>/preflight/.agents/` 或 `<project>/.agents-backup/<timestamp>/preflight/.codex/`
-- 全局 Skills：`$HOME/.ling/backups/global/<timestamp>/...`
-- Spec Profile：`$HOME/.ling/backups/spec/<timestamp>/before/...`
+Spec 是核心进阶功能，但理解它只需要记住两句：
 
-非交互环境（无 TTY 或 `--non-interactive`）不会进入询问：
-- `update`/`update-all`/`global sync`/`spec enable` 在需要覆盖时默认执行“备份后覆盖”
-- `init` 在检测到已有资产且未指定 `--force` 时会报错提示改用交互终端或显式 `--force`
+- `ling spec enable` 给这台电脑安装全局 Spec 工具箱
+- `ling spec init` 给当前项目创建真正要用的 `issues.csv`
 
-### Spec Profile（可选进阶能力）
+也就是说：
 
-- 默认关闭，不随 `ling init / update / global sync` 自动安装
-- 当前已落地全局层命令：
-  - `ling spec status`
-  - `ling spec enable`
-  - `ling spec disable`
-- 默认目标：`ling spec enable` 未指定目标时，会启用 `codex + gemini`
-- 当前全局层会安装：
-  - Skills：`harness-engineering`、`cybernetic-systems-engineering`
-  - Spec 运行模板：写入 `~/.ling/spec/templates/`
-  - Spec 参考资料：写入 `~/.ling/spec/references/`
-- 目标平台落盘：
-  - `codex` -> `~/.codex/skills/`
-  - `gemini` -> 同时写入 `~/.gemini/skills/` 与 `~/.gemini/antigravity/skills/`
+- 全局 Spec 负责模板、参考资料、约束
+- 项目里的 `issues.csv` 永远放在项目根目录
 
-示例：
+最常用的两种方式：
 
 ```bash
-ling spec status
-ling spec enable --target codex
-ling spec disable --target codex
+# 完整模式：项目自带 Spec 资产
+cd /path/to/your-project
+ling spec init
+
+# 轻量模式：只在项目里放 issues.csv，其他能力走全局后备
+cd /path/to/your-project
+ling spec enable
+ling spec init --csv-only
 ```
 
-说明：
+你会得到：
 
-- `spec enable` 会在覆盖同名 Skill 前自动备份到 `~/.ling/backups/spec/<timestamp>/...`
-- `spec disable` 会优先恢复启用前快照；若启用前不存在同名资源，则删除由 Spec 安装的资源
-- 项目级 `spec init/remove/doctor` 仍处于后续阶段，本版本尚未开放
+- 完整模式：`<project>/.ling/spec/`、`<project>/issues.csv`、`<project>/docs/reviews/`、`<project>/docs/handoff/`
+- `--csv-only`：`<project>/issues.csv`、`<project>/docs/reviews/`、`<project>/docs/handoff/`
+- 全局 Spec 资源：`~/.ling/spec/templates/`、`~/.ling/spec/references/`、`~/.ling/spec/profiles/`
 
-### Codex 规则边界说明
+如果你只想要一个本机演练空间，而不是某个真实项目：
 
-- `ling.rules`：本项目生成并注入的托管说明文件，用于记录受管资源与运维约束。
-- `.rules`（如 `~/.codex/rules/default.rules`）：Codex 官方的命令审批/执行策略文件（Starlark 规则，支持 `prefix_rule()`）。
-- 默认行为：本项目不会自动写入你的全局 `~/.codex/rules`，避免引入不可预期的全局副作用。
-- 如需启用官方 `.rules` 审批策略，请参考 `docs/TECH.md` 的「Codex 官方 `.rules`（手动配置）」小节。
+```bash
+ling spec init --spec-workspace
+```
 
-### 跨平台与文本编码约束
+`spec doctor` 用于检查当前项目的 Spec 状态。
 
-- 编码与换行：分发到用户项目与全局目录的模板资源使用 UTF-8 与 LF。
-- 终端可读性：模板文本与脚本输出避免使用 Emoji 或装饰性 Unicode 字符，统一采用纯 ASCII 标记，提升 Windows/WSL/Linux/macOS 的显示一致性。
+## 常用命令
 
-### 注意：关于 `.gitignore` 的重要说明
+| 命令 | 用途 |
+| --- | --- |
+| `ling init` | 在项目内安装目标资产 |
+| `ling update` | 更新当前项目已安装目标 |
+| `ling doctor` | 诊断当前项目安装状态 |
+| `ling status` | 输出项目安装状态 |
+| `ling global sync` | 全局同步 Skills |
+| `ling global status` | 查看全局 Skills 状态 |
+| `ling spec enable` | 启用全局 Spec 工具箱 |
+| `ling spec init` | 在当前项目初始化 Spec |
+| `ling spec doctor` | 检查当前项目 Spec 状态 |
+| `ling update-all` | 批量更新已登记项目 |
 
-如果你正在使用 **Cursor** 或 **Windsurf** 等 AI 编辑器，将 `.agent/`、`.agents/` 添加到 `.gitignore` 可能会阻止 IDE 索引工作流，导致斜杠命令（如 `/plan`、`/debug`）无法出现在对话建议中。
+常用示例：
 
-**推荐方案：**
-1. 确保 `.agent/`、`.agents/` **不要** 出现在项目的 `.gitignore` 中。
-2. 作为替代方案，将其加入本地排除文件：`.git/info/exclude`。
+```bash
+ling init --targets gemini,antigravity,codex --path ./myapp
+ling init --target antigravity --path ./myapp
+ling init --target codex --force --path ./myapp
+ling update --path ./myapp
+ling doctor --target codex --fix --path ./myapp
+ling spec enable
+ling spec init --csv-only --path ./myapp
+ling update-all --targets antigravity,codex
+ling global sync --quiet --dry-run
+```
 
-## 包含内容
+## 文档
 
-| 组件 | 数量 | 描述 |
-| --- | --- | --- |
-| Agents（智能体） | 20 | 专家级 AI 人设（前端、后端、安全、产品、QA 等） |
-| Skills（技能） | 38 | 特定领域的知识模块 |
-| Workflows（工作流） | 12 | 斜杠命令流程 |
+- [技术说明](docs/TECH.md)
+- [设计规划](docs/PLAN.md)
+- [贡献说明](CONTRIBUTING.md)
+- [更新日志](CHANGELOG.md)
 
-## 使用方法
+## 使用说明
 
-### 使用智能体
+- `ling` 的仓库模板源是 `.agents/`
+- 文本与模板资源使用 UTF-8 与 LF
+- 不会自动写入全局 `~/.codex/rules`
+- 如果 AI 编辑器依赖索引，请不要把 `.agent/`、`.agents/` 放进项目 `.gitignore`
 
-**无需显式提及智能体！** 系统会自动检测并应用合适专家：
+版本约定：
 
-```
-你："添加 JWT 认证"
-AI：正在应用 @security-auditor + @backend-specialist...
+- npm 版本遵循 SemVer
+- Git tag 和 `ling --version` 显示为 `ling-<SemVer>`
 
-你："修复深色模式按钮"
-AI：正在使用 @frontend-specialist...
+源码方式运行：
 
-你："登录返回 500 错误"
-AI：正在使用 @debugger 进行系统化分析...
+```bash
+git clone https://github.com/MisonL/Ling.git
+cd Ling
+npm install
+node bin/ling.js init --target codex --path /path/to/your-project
 ```
 
-**工作原理：**
-
-- 静默分析请求
-- 自动检测领域（前端、后端、安全等）
-- 选择最佳专家
-- 告知你正在应用哪方面的专业知识
-- 无需了解系统架构即可获得专家级响应
-
-**优势：**
+## 包含内容
 
-- 零学习曲线：描述需求即可
-- 始终获得专家响应
-- 透明：显示正在使用的智能体
-- 仍可显式提及智能体进行覆盖
+| 组件 | 数量 | 描述 |
+| --- | --- | --- |
+| Agents（智能体） | 20 | 专家级 AI 人设（前端、后端、安全、产品、QA 等） |
+| Skills（技能） | 49 | 特定领域的知识模块（以 `SKILL.md` 为准，含子技能目录） |
+| Workflows（工作流） | 12 | 斜杠命令流程 |
 
-### 使用工作流
+## 工作流与命令
 
-使用斜杠命令调用工作流：
+工作流通过斜杠命令触发：
 
 | 命令 | 描述 |
 | --- | --- |
@@ -200,75 +218,9 @@ AI：正在使用 @debugger 进行系统化分析...
 | `/test` | 生成并运行测试 |
 | `/ui-ux-pro-max` | 50 种风格的设计 |
 
-示例：
-
-```
-/brainstorm 认证系统
-/create 带 Hero 部分的着陆页
-/debug 为什么登录失败
-```
+技能会按上下文自动加载，不需要手工管理大多数 Skill。
 
-### 使用技能
-
-技能会根据任务上下文自动加载。AI 会阅读技能描述并应用相关知识。
-
-## CLI 工具
-
-CLI（命令行界面）工具：
-
-| 命令 | 描述 |
-| --- | --- |
-| `ling init` | 安装指定目标：gemini/codex |
-| `ling update` | 更新当前项目已安装目标 |
-| `ling update-all` | 批量更新所有已登记工作区 |
-| `ling doctor` | 诊断安装完整性（可 `--fix` 自愈） |
-| `ling global sync` | 全局同步 Skills（默认同步 codex + gemini；其中 gemini 同步到 gemini-cli 与 antigravity） |
-| `ling global status` | 查看全局 Skills 安装状态 |
-| `ling exclude` | 管理全局索引排除清单 |
-| `ling status` | 检查安装状态 |
-
-### 常用选项
-
-```bash
-ling init --target gemini --path ./myapp        # 安装 Gemini 到指定目录
-ling init --target codex --path ./myapp         # 安装 Codex 到指定目录
-ling init --targets gemini,codex --path ./myapp # 一次安装多个目标
-ling init --non-interactive --target codex      # 非交互模式必须显式指定目标
-ling init --target codex --no-index --path ./tmp-workspace # 安装但不写入全局索引
-ling init --branch dev --force                  # 覆盖安装并指定分支
-ling init --quiet --dry-run                     # 预览操作而不执行
-ling update --target codex --path ./myapp       # 更新指定目标（默认会刷新索引）
-ling update --target codex --no-index --path ./myapp # 更新但不刷新索引
-ling doctor --target codex --fix --path ./myapp # 检查并自动修复
-ling update-all --targets codex                 # 批量更新所有登记工作区里的 codex 目标
-ling update-all --prune-missing                 # 清理索引中已失效的路径
-ling exclude list                               # 查看排除清单
-ling exclude add --path /path/to/dir            # 新增排除路径
-ling exclude remove --path /path/to/dir         # 删除排除路径
-```
-
-### 状态命令约定
-
-- `ling status --quiet`：输出 `installed` / `broken` / `missing`
-- `ling global status --quiet`：输出 `installed` / `broken` / `missing`
-- 退出码：`0=installed`，`1=broken`，`2=missing`
-- `status` 面向自动化健康判断；如需问题明细，使用 `ling doctor`
-
-### 批量更新机制
-
-- 执行 `ling init` / `ling update` 时，会把工作区路径登记到全局索引文件：
-  - macOS / Linux / WSL: `~/.ling/workspaces.json`
-  - Windows PowerShell / CMD: `%USERPROFILE%\.ling\workspaces.json`
-- 默认会自动排除灵轨工具包源码目录和系统临时目录（如 macOS `/var/folders/...`、`/tmp`、`/private/tmp`，Linux `/tmp`，Windows `%TEMP%`）。
-- 可通过 `--no-index` 让 `init/update` 跳过索引登记（适合临时验证目录）。
-- `ling update` 只依赖当前目录（或 `--path` 指定目录）的已安装目标，不依赖全局索引。
-- 执行 `ling update-all` 时，会遍历索引并批量更新每个工作区（可通过 `--targets` 限定目标）。
-- 可用 `--prune-missing` 自动移除索引里已失效的工作区路径。
-- 对于历史项目（尚未登记，或曾经 `--no-index` 跳过登记），可在该项目执行一次不带 `--no-index` 的 `ling update`（或 `ling init --force`）后纳入索引。
-- 可通过 `ling exclude add/remove/list` 维护自定义排除路径（支持排除整棵目录树）。
-- 也可通过环境变量 `LING_INDEX_PATH` 指定自定义索引路径。
-
-### 开发维护命令
+## 开发维护命令
 
 ```bash
 npm run clean           # 清理本地生成产物（如 web/.next、web/node_modules）
@@ -287,26 +239,17 @@ npm run lint
 
 ## 卸载
 
-### 卸载本机全局 CLI
-
 ```bash
 npm uninstall -g @mison/ling
 ```
 
-如果你之前安装过旧包：`@mison/ag-kit-cn`（已停止维护），可一并清理：
+旧包和上游旧包如已安装，可一并清理：
 
 ```bash
 npm uninstall -g @mison/ag-kit-cn
-```
-
-如果你还安装过上游英文版，可一并清理：
-
-```bash
 npm uninstall -g antigravity-kit @vudovn/ag-kit
 ```
 
-### 卸载某个项目内的灵轨
-
 macOS / Linux / WSL:
 
 ```bash
@@ -331,13 +274,13 @@ rmdir /s /q .agents-backup
 rmdir /s /q .codex
 ```
 
-### 清理批量更新索引（可选）
+可选：把某个项目移出批量更新索引
 
 ```bash
 ling exclude add --path /path/to/your-project
 ```
 
-说明：全局卸载只会移除 `ling` 命令，不会删除你本地 clone 的源码目录。
+全局卸载只会移除 `ling` 命令，不会删除你本地 clone 的源码目录。
 
 ## 请我喝咖啡
 

package/bin/adapters/gemini.js

@@ -7,7 +7,11 @@ const GitHelper = require("../utils/git-helper");
 
 class GeminiAdapter extends BaseAdapter {
     get targetName() {
-        return "gemini";
+        return this.options.targetName || "gemini";
+    }
+
+    get targetLabel() {
+        return this.targetName === "antigravity" ? "Antigravity" : "Gemini";
     }
 
     getInstalledVersion() {
@@ -108,7 +112,7 @@ class GeminiAdapter extends BaseAdapter {
                  this.log(`[clean] 已从 .gitignore 移除 ${cleanupResult.removedCount} 条规则`);
             }
             
-            this.log("[ok] [Gemini] 安装完成 (.agent)");
+            this.log(`[ok] [${this.targetLabel}] 安装完成 (.agent)`);
         } finally {
             if (cleanup) cleanup();
         }

package/bin/interactive.js

@@ -22,7 +22,7 @@ function isInteractiveTerminal() {
 /**
  * Prompt user to select targets from a list.
  * Supports multiple selection by comma separated numbers or names.
- * Currently simplified for 'gemini' and 'codex'.
+ * Currently supports 'gemini', 'antigravity', and 'codex'.
  * @param {object} options CLI options
  * @returns {Promise<string[]>} List of selected targets
  */
@@ -40,7 +40,8 @@ async function selectTargets(options) {
     try {
         console.log("\n[select] 请选择要安装的目标 (多选请用逗号分隔):");
         console.log("   1. Gemini (适用于 Cursor/VSCode)");
-        console.log("   2. Codex (兼容性增强版)");
+        console.log("   2. Antigravity (独立体系，项目级复用 .agent)");
+        console.log("   3. Codex (兼容性增强版)");
         
         const answer = await askQuestion(rl, "\n请输入序号或名称（必填）: ");
         const input = answer.trim();
@@ -55,11 +56,12 @@ async function selectTargets(options) {
         for (const part of parts) {
             const p = part.toLowerCase();
             if (p === "1" || p === "gemini") selection.push("gemini");
-            else if (p === "2" || p === "codex") selection.push("codex");
+            else if (p === "2" || p === "antigravity") selection.push("antigravity");
+            else if (p === "3" || p === "codex") selection.push("codex");
         }
 
         if (selection.length === 0) {
-            throw new Error("无效的目标选择，请输入 1 / 2 / gemini / codex（可多选）");
+            throw new Error("无效的目标选择，请输入 1 / 2 / 3 / gemini / antigravity / codex（可多选）");
         }
 
         return [...new Set(selection)];