@mison/ling 1.0.2 → 1.1.1

package/.agents/rules/GEMINI.md

@@ -27,6 +27,23 @@ trigger: always_on
 
 ---
 
+## Spec 协议（任务跟踪 CSV 驱动）
+
+当工作区存在 `issues.csv` 时，视其为任务跟踪文件（单一事实源），并遵循：
+
+1. 读取 `issues.csv` 并只锁定一个原子任务。
+2. 将任务状态从“未开始”改为“进行中”，再开始开发。
+3. 修改完成后运行最小充分验证，并记录证据。
+4. 自审通过后将状态改为“已完成”。
+5. 若验证失败，先修复或回退，不得静默降级。
+
+模板参考：
+
+- 优先：`.ling/spec/templates/driver-prompt.md`
+- 其次：`~/.ling/spec/templates/driver-prompt.md`（若已启用全局 Spec Profile）
+
+---
+
 ##  请求分类器（第 1 步）
 
 **在执行任何动作前，先对请求分类：**

package/.agents/skills/clean-code/SKILL.md

@@ -143,24 +143,34 @@ File to edit: UserService.ts
 
 > [CRITICAL]  **核心要求：** 每个代理完成后仅运行所属技能脚本。
 
+### 脚本路径约定
+
+下表中的 `<skills_root>` 代表 Skills 根目录，常见取值：
+
+- Ling 仓库源码：`.agents/skills`
+- Gemini 工作区：`.agent/skills`
+- Codex 全局：`~/.codex/skills`
+- Gemini CLI 全局：`~/.gemini/skills`
+- Antigravity 全局：`~/.gemini/antigravity/skills`
+
 ### 代理 -> 脚本映射
 
 | 代理 | 脚本 | 命令 |
 |-------|--------|---------|
-| **frontend-specialist** | UX Audit | `python .agent/skills/frontend-design/scripts/ux_audit.py .` |
-| **frontend-specialist** | A11y Check | `python .agent/skills/frontend-design/scripts/accessibility_checker.py .` |
-| **backend-specialist** | API Validator | `python .agent/skills/api-patterns/scripts/api_validator.py .` |
-| **mobile-developer** | Mobile Audit | `python .agent/skills/mobile-design/scripts/mobile_audit.py .` |
-| **database-architect** | Schema Validate | `python .agent/skills/database-design/scripts/schema_validator.py .` |
-| **security-auditor** | Security Scan | `python .agent/skills/vulnerability-scanner/scripts/security_scan.py .` |
-| **seo-specialist** | SEO Check | `python .agent/skills/seo-fundamentals/scripts/seo_checker.py .` |
-| **seo-specialist** | GEO Check | `python .agent/skills/geo-fundamentals/scripts/geo_checker.py .` |
-| **performance-optimizer** | Lighthouse | `python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
-| **test-engineer** | Test Runner | `python .agent/skills/testing-patterns/scripts/test_runner.py .` |
-| **test-engineer** | Playwright | `python .agent/skills/webapp-testing/scripts/playwright_runner.py <url>` |
-| **Any agent** | Lint Check | `python .agent/skills/lint-and-validate/scripts/lint_runner.py .` |
-| **Any agent** | Type Coverage | `python .agent/skills/lint-and-validate/scripts/type_coverage.py .` |
-| **Any agent** | i18n Check | `python .agent/skills/i18n-localization/scripts/i18n_checker.py .` |
+| **frontend-specialist** | UX Audit | `python <skills_root>/frontend-design/scripts/ux_audit.py .` |
+| **frontend-specialist** | A11y Check | `python <skills_root>/frontend-design/scripts/accessibility_checker.py .` |
+| **backend-specialist** | API Validator | `python <skills_root>/api-patterns/scripts/api_validator.py .` |
+| **mobile-developer** | Mobile Audit | `python <skills_root>/mobile-design/scripts/mobile_audit.py .` |
+| **database-architect** | Schema Validate | `python <skills_root>/database-design/scripts/schema_validator.py .` |
+| **security-auditor** | Security Scan | `python <skills_root>/vulnerability-scanner/scripts/security_scan.py .` |
+| **seo-specialist** | SEO Check | `python <skills_root>/seo-fundamentals/scripts/seo_checker.py .` |
+| **seo-specialist** | GEO Check | `python <skills_root>/geo-fundamentals/scripts/geo_checker.py .` |
+| **performance-optimizer** | Lighthouse | `python <skills_root>/performance-profiling/scripts/lighthouse_audit.py <url>` |
+| **test-engineer** | Test Runner | `python <skills_root>/testing-patterns/scripts/test_runner.py .` |
+| **test-engineer** | Playwright | `python <skills_root>/webapp-testing/scripts/playwright_runner.py <url>` |
+| **Any agent** | Lint Check | `python <skills_root>/lint-and-validate/scripts/lint_runner.py .` |
+| **Any agent** | Type Coverage | `python <skills_root>/lint-and-validate/scripts/type_coverage.py .` |
+| **Any agent** | i18n Check | `python <skills_root>/i18n-localization/scripts/i18n_checker.py .` |
 
 > [FAIL]  **错误做法：** `test-engineer` 运行 `ux_audit.py`
 > [OK]  **正确做法：** `frontend-specialist` 运行 `ux_audit.py`

package/.agents/skills/doc.md

@@ -18,7 +18,11 @@
 
 | 范围 | 路径 | 说明 |
 |---------|-----------|-------|
-| **Workspace（工作区）** | `<workspace-root>/.agent/skills/` | 仅作用于当前项目 |
+| **Ling 仓库源码（Canonical）** | `<ling-repo>/.agents/skills/` | 模板源，用于构建与分发 |
+| **Workspace（工作区）** | `<workspace-root>/.agent/skills/` | 仅作用于当前项目（Gemini/Antigravity） |
+| **Global（全局）** | `~/.codex/skills/`、`~/.gemini/skills/`、`~/.gemini/antigravity/skills/` | 跨项目复用（按目标工具读取） |
+
+> 约定：下文示例使用 `<skills_root>` 表示 Skills 根目录；请按你的安装方式替换为上表路径。
 
 ### 技能目录结构
 
@@ -39,7 +43,7 @@ my-skill/
 ### 步骤 1：创建目录
 
 ```bash
-mkdir -p .agent/skills/code-review
+mkdir -p <skills_root>/code-review
 ```
 
 ### 步骤 2：创建 SKILL.md
@@ -119,12 +123,12 @@ Agent（智能体）会自动识别 `code-review` 技能，加载信息并按指
 ### 步骤 1：创建目录
 
 ```bash
-mkdir -p .agent/skills/license-header-adder/resources
+mkdir -p <skills_root>/license-header-adder/resources
 ```
 
 ### 步骤 2：创建模板文件
 
-**`.agent/skills/license-header-adder/resources/HEADER.txt`**：
+**`<skills_root>/license-header-adder/resources/HEADER.txt`**：
 
 ```
 /*
@@ -136,7 +140,7 @@ mkdir -p .agent/skills/license-header-adder/resources
 
 ### 步骤 3：创建 SKILL.md
 
-**`.agent/skills/license-header-adder/SKILL.md`**：
+**`<skills_root>/license-header-adder/SKILL.md`**：
 
 ```markdown
 ---

package/CHANGELOG.md

@@ -7,6 +7,31 @@
 
 ## [Unreleased]
 
+## [ling-1.1.1] - 2026-03-14
+
+### 新增
+
+- Spec 项目级工作区初始化与诊断：新增 `ling spec init` / `ling spec doctor`，在工作区落盘 `.ling/spec` 资产与 `issues.csv` 校验。
+- Spec Profiles 资产：全局与项目级均包含 `profiles/`，并纳入完整性校验与回退语义。
+- Spec 资产分支拉取：`ling spec init --branch <name>` 支持从指定分支的 `.spec/` 拉取 templates/references/profiles。
+
+### 变更
+
+- Spec 状态判定强化：`ling spec status` 增加文件级完整性校验，且在 `state.json` 缺失但检测到残留 artifacts 时返回 `broken` 并给出修复提示。
+- CI 改为 npm：CI 矩阵不再依赖 bun，统一使用 `npm ci/test/run` 执行验证。
+
+## [ling-1.1.0] - 2026-03-13
+
+### 新增
+
+- 已有资产冲突处理：`init/update/update-all/global sync/spec enable` 在交互终端逐项确认（保留 / 备份后移除 / 直接移除），并支持按资产类别复用选择。
+- 预备份与回退：项目级覆盖前快照落盘到 `.agent-backup/.agents-backup`；全局与 Spec 维持快照备份路径。
+
+### 维护
+
+- ag-kit 更名清理：内部 CLI 入口更名为 `bin/ling-cli.js`，并移除 `AG_KIT_*` 兼容环境变量与 `~/.ag-kit` 控制目录迁移逻辑。
+- 托管区块标记更名为 `LING MANAGED BLOCK`，并兼容识别旧 `AG-KIT` 标记后自动迁移。
+
 ## [ling-1.0.2] - 2026-03-13
 
 ### 变更
@@ -22,7 +47,7 @@
 
 ### 维护
 
-- CLI 入口权限：`bin/ling.js` 设置为可执行，保持与 `bin/ag-kit.js` 一致。
+- CLI 入口权限：`bin/ling.js` 设置为可执行，保持与 `bin/ling-cli.js` 一致。
 
 ## [ling-1.0.0] - 2026-03-13
 
@@ -35,7 +60,6 @@
 
 - 品牌更名基础设施：
   - 主命令切换为 `ling`
-  - `ag-kit` 保留兼容入口
   - 目标目录结构：`gemini -> .agent/`，`codex -> .agents/`
   - 控制目录、索引和备份默认迁移到 `~/.ling/`
   - `antigravity.rules` 收敛为 `ling.rules`
@@ -56,7 +80,9 @@
 
 本项目在 Ling 重启前的 2.x/3.x 版本记录已冻结，不再维护。
 
-[Unreleased]: https://github.com/MisonL/Ling/compare/ling-1.0.2...HEAD
+[Unreleased]: https://github.com/MisonL/Ling/compare/ling-1.1.1...HEAD
+[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
 [ling-1.0.1]: https://github.com/MisonL/Ling/releases/tag/ling-1.0.1
 [ling-1.0.0]: https://github.com/MisonL/Ling/releases/tag/ling-1.0.0

package/README.md

@@ -6,25 +6,12 @@
 
 > 面向 Gemini CLI、Antigravity 与 Codex 的中文 AI Agent 模板工具包，提供 Skills、Agents、Workflows 与 CLI 的一键安装、更新和治理。
 
-## 致谢
-
-本项目吸收并整合了社区项目的经验与资产，感谢：
-
-- [vudovn/antigravity-kit](https://github.com/vudovn/antigravity-kit)
-- [2217173240/Coding-Agent-prompt-best-practice](https://github.com/2217173240/Coding-Agent-prompt-best-practice)
-
 ## 快速安装
 
 ```bash
 npm install -g @mison/ling
 ```
 
-或使用 Bun：
-
-```bash
-bun install -g @mison/ling
-```
-
 然后在你的目标项目中初始化：
 
 ```bash
@@ -83,6 +70,27 @@ ling global status
 - npm 包版本遵循 SemVer（`package.json`）
 - git tag 与 CLI `--version` 显示使用 `ling-<SemVer>`（例如 `ling-1.0.0`）
 
+### 已有资产冲突处理（交互确认 + 备份回退）
+
+当检测到目标目录已存在且内容不同（或 Codex 目录存在漂移、缺失 `manifest.json`、包含未知文件）时，`ling` 会在交互终端中逐项询问处理方式：
+
+- `k` 保留（跳过此资产）
+- `b` 备份后移除（推荐）
+- `r` 直接移除（不备份）
+
+同一类别的冲突可选择“一键复用”，后续遇到同类资产不再重复询问。
+
+备份落盘位置：
+- 项目级预备份：
+  - 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/...`
+
+非交互环境（无 TTY 或 `--non-interactive`）不会进入询问：
+- `update`/`update-all`/`global sync`/`spec enable` 在需要覆盖时默认执行“备份后覆盖”
+- `init` 在检测到已有资产且未指定 `--force` 时会报错提示改用交互终端或显式 `--force`
+
 ### Spec Profile（可选进阶能力）
 
 - 默认关闭，不随 `ling init / update / global sync` 自动安装
@@ -138,7 +146,7 @@ ling spec disable --target codex
 | 组件 | 数量 | 描述 |
 | --- | --- | --- |
 | Agents（智能体） | 20 | 专家级 AI 人设（前端、后端、安全、产品、QA 等） |
-| Skills（技能） | 37 | 特定领域的知识模块 |
+| Skills（技能） | 38 | 特定领域的知识模块 |
 | Workflows（工作流） | 12 | 斜杠命令流程 |
 
 ## 使用方法
@@ -263,21 +271,20 @@ ling exclude remove --path /path/to/dir         # 删除排除路径
 ### 开发维护命令
 
 ```bash
-bun run clean           # 清理本地生成产物（如 web/.next、web/node_modules）
-bun run clean:dry-run   # 预览将被清理的路径
-bun run test            # 只执行 tests/ 目录下测试
-bun run health-check    # 一键执行全链路健康复检
+npm run clean           # 清理本地生成产物（如 web/.next、web/node_modules）
+npm run clean:dry-run   # 预览将被清理的路径
+npm test                # 执行 tests/ 目录下测试
+npm run health-check    # 一键执行全链路健康复检
 ```
 
 如果你在 `web/` 子项目内开发，可按需执行：
 
 ```bash
-bun install --cwd web
-bun run lint --cwd web
+cd web
+npm install
+npm run lint
 ```
 
-> 说明：若你通过 `bun install -g` 安装 CLI，Bun 默认会阻止本包 `postinstall`。上游同名包冲突提示会在首次执行 `ling init/update/update-all/global sync` 时给出。
-
 ## 卸载
 
 ### 卸载本机全局 CLI
@@ -353,6 +360,13 @@ ling exclude add --path /path/to/your-project
   </tr>
 </table>
 
+## 致谢
+
+本项目吸收并整合了社区项目的经验与资产，感谢：
+
+- [vudovn/antigravity-kit](https://github.com/vudovn/antigravity-kit)
+- [2217173240/Coding-Agent-prompt-best-practice](https://github.com/2217173240/Coding-Agent-prompt-best-practice)
+
 ## 许可证
 
-MIT © Vudovn, Mison
+MIT © [vudovn](https://github.com/vudovn), [Mison](https://github.com/MisonL), [2217173240](https://github.com/2217173240)

package/bin/adapters/codex.js

@@ -140,11 +140,11 @@ class CodexAdapter extends BaseAdapter {
         if (!isCodexPrebuilt) {
             if (hasSkillsDir) {
                 this.log("[build] 检测到模板目录格式，正在构建 Codex 结构...");
-                const mockRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-root-"));
+                const mockRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ling-build-root-"));
                 const mockAgents = path.join(mockRoot, ".agents");
                 this._copyDir(installSource, mockAgents);
 
-                buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-out-"));
+                buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ling-build-out-"));
                 CodexBuilder.build(mockRoot, buildTemp);
                 installSource = buildTemp;
                 sourceLabel = `${sourceLabel}:compiled`;
@@ -157,7 +157,7 @@ class CodexAdapter extends BaseAdapter {
                 };
             } else if (hasAgentsRoot) {
                 this.log("[build] 检测到仓库根目录格式(.agents)，正在构建 Codex 结构...");
-                buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-out-"));
+                buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ling-build-out-"));
                 CodexBuilder.build(installSource, buildTemp);
                 installSource = buildTemp;
                 sourceLabel = `${sourceLabel}:compiled`;
@@ -169,11 +169,11 @@ class CodexAdapter extends BaseAdapter {
                 };
             } else if (hasLegacyAgentRoot) {
                 this.log("[build] 检测到旧版仓库根目录格式(.agent)，正在构建 Codex 结构...");
-                const mockRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-root-"));
+                const mockRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ling-build-root-"));
                 const mockAgents = path.join(mockRoot, ".agents");
                 this._copyDir(path.join(installSource, ".agent"), mockAgents);
 
-                buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-out-"));
+                buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ling-build-out-"));
                 CodexBuilder.build(mockRoot, buildTemp);
                 installSource = buildTemp;
                 sourceLabel = `${sourceLabel}:compiled`;
@@ -191,7 +191,7 @@ class CodexAdapter extends BaseAdapter {
     }
 
     _createStaging(installSource, sourceLabel) {
-        const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-codex-stage-"));
+        const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), "ling-codex-stage-"));
         this._copyDir(installSource, stagingDir);
 
         const manifestPath = path.join(stagingDir, "manifest.json");

package/bin/adapters/gemini.js

@@ -70,7 +70,7 @@ class GeminiAdapter extends BaseAdapter {
             }
 
             if (this._samePath(installSource, targetDir) && !this.options.dryRun) {
-                const tempSource = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-gemini-src-"));
+                const tempSource = fs.mkdtempSync(path.join(os.tmpdir(), "ling-gemini-src-"));
                 this._copyDir(installSource, tempSource);
                 const oldCleanup = cleanup;
                 cleanup = () => {

package/bin/core/generator.js

@@ -37,6 +37,7 @@ class RuleGenerator {
         agentsMd += `1. Managed resources are synchronized under \`.agents/skills\`.\n`;
         agentsMd += `2. Do not rename managed skill folders manually.\n`;
         agentsMd += `3. Use \`ling doctor --target codex --fix\` to recover missing managed artifacts.\n`;
+        agentsMd += `4. If \`issues.csv\` exists, treat it as the task tracking source of truth and keep at most one task in \`进行中\`.\n`;
 
         // 3. Generate risk controls
         let lingRules = `# Ling Risk Controls (Codex Managed)\n\n`;

package/bin/interactive.js

@@ -15,6 +15,10 @@ function askQuestion(rl, query) {
     });
 }
 
+function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
 /**
  * Prompt user to select targets from a list.
  * Supports multiple selection by comma separated numbers or names.
@@ -27,6 +31,10 @@ async function selectTargets(options) {
         throw new Error("非交互模式下必须通过 --target 或 --targets 指定目标");
     }
 
+    if (!isInteractiveTerminal()) {
+        throw new Error("当前环境不是交互终端，请通过 --target 或 --targets 指定目标");
+    }
+
     const rl = createInterface();
     
     try {
@@ -60,6 +68,65 @@ async function selectTargets(options) {
     }
 }
 
+/**
+ * Create an interactive prompter for resolving asset conflicts.
+ * @param {object} options CLI options
+ * @returns {{resolveConflict: function, close: function}|null}
+ */
+function createConflictPrompter(options) {
+    if (options.nonInteractive || !isInteractiveTerminal()) {
+        return null;
+    }
+
+    const rl = createInterface();
+    const categoryDefaults = new Map();
+
+    async function resolveConflict(conflict) {
+        const category = String(conflict.category || "default");
+        if (categoryDefaults.has(category)) {
+            return categoryDefaults.get(category);
+        }
+
+        const label = String(conflict.label || "未知资产");
+        const location = conflict.path ? ` (${conflict.path})` : "";
+
+        console.log(`\n[confirm] 检测到已存在资产: ${label}${location}`);
+        console.log("请选择处理方式:");
+        console.log("  k) 保留(跳过此资产)");
+        console.log("  b) 备份后移除(推荐)");
+        console.log("  r) 直接移除(不备份)");
+
+        while (true) {
+            const answer = String(await askQuestion(rl, "请输入 k / b / r: ")).trim().toLowerCase();
+            let action = "";
+            if (answer === "k") action = "keep";
+            if (answer === "b") action = "backup";
+            if (answer === "r") action = "remove";
+
+            if (!action) {
+                console.log("[warn] 输入无效，请重新输入。");
+                continue;
+            }
+
+            const applyAnswer = String(await askQuestion(rl, `是否对同类资产(类别: ${category})后续冲突复用该选择? (y/N): `))
+                .trim()
+                .toLowerCase();
+            if (applyAnswer === "y" || applyAnswer === "yes") {
+                categoryDefaults.set(category, action);
+            }
+
+            return action;
+        }
+    }
+
+    function close() {
+        rl.close();
+    }
+
+    return { resolveConflict, close };
+}
+
 module.exports = {
-    selectTargets
+    selectTargets,
+    createConflictPrompter,
 };