@mison/ling 1.0.1 → 1.1.0

package/bin/ling.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
 
-require("./ag-kit.js");
+require("./ling-cli.js");

package/bin/utils/managed-block.js

@@ -10,6 +10,14 @@ function detectLineEnding(content) {
 }
 
 function buildMarkers(blockId) {
+    const id = String(blockId || "default").trim();
+    return {
+        begin: `<!-- BEGIN LING MANAGED BLOCK: ${id} -->`,
+        end: `<!-- END LING MANAGED BLOCK: ${id} -->`,
+    };
+}
+
+function buildLegacyMarkers(blockId) {
     const id = String(blockId || "default").trim();
     return {
         begin: `<!-- BEGIN AG-KIT MANAGED BLOCK: ${id} -->`,
@@ -29,10 +37,9 @@ function upsertManagedBlock(filePath, blockId, body, options = {}) {
     const lineEnding = detectLineEnding(original);
     const managedBlock = buildManagedBlock(blockId, body, lineEnding);
     const markers = buildMarkers(blockId);
-    const blockRegex = new RegExp(
-        `${escapeRegex(markers.begin)}[\\s\\S]*?${escapeRegex(markers.end)}`,
-        "m",
-    );
+    const legacyMarkers = buildLegacyMarkers(blockId);
+    const blockRegex = new RegExp(`${escapeRegex(markers.begin)}[\\s\\S]*?${escapeRegex(markers.end)}`, "m");
+    const legacyRegex = new RegExp(`${escapeRegex(legacyMarkers.begin)}[\\s\\S]*?${escapeRegex(legacyMarkers.end)}`, "m");
 
     let next = "";
     let action = "unchanged";
@@ -46,6 +53,12 @@ function upsertManagedBlock(filePath, blockId, body, options = {}) {
         if (next && !/\r?\n$/.test(next)) {
             next += lineEnding;
         }
+    } else if (legacyRegex.test(original)) {
+        next = original.replace(legacyRegex, managedBlock);
+        action = "updated";
+        if (next && !/\r?\n$/.test(next)) {
+            next += lineEnding;
+        }
     } else {
         next = `${original.replace(/\r?\n?$/, "")}${lineEnding}${lineEnding}${managedBlock}${lineEnding}`;
         action = "appended";

package/bin/utils.js

@@ -49,7 +49,7 @@ function cloneBranchAgentDir(branch, options) {
         throw new Error(`非法分支名: ${branch}`);
     }
 
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-"));
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ling-"));
     const logFn = options && options.logger ? options.logger : console.log;
 
     if (!options.quiet) logFn(`[download] 正在从 ${REPO_URL} 拉取分支 ${safeBranch} ...`);

package/docs/TECH.md

@@ -2,11 +2,11 @@
 
 ## 快速验证（维护者）
 ```bash
-bun install
-bun run test
-bun run ci:verify
-bun run health-check
-cd web && bun install && bun run lint
+npm install
+npm test
+npm run ci:verify
+npm run health-check
+cd web && npm install && npm run lint
 ```
 
 ## 核心目录与职责
@@ -20,6 +20,9 @@ cd web && bun install && bun run lint
 ### 项目级（功能最完整）
 - `gemini`：项目根目录 `.agent/`
 - `codex`：项目根目录 `.agents/`（受管）+ `.agents-backup/`（漂移覆盖备份）
+- 项目级预备份（覆盖前快照）：
+  - Gemini：`<project>/.agent-backup/<timestamp>/preflight/.agent/`
+  - Codex：`<project>/.agents-backup/<timestamp>/preflight/.agents/` 或 `<project>/.agents-backup/<timestamp>/preflight/.codex/`
 
 ### 全局级（仅同步 Skills）
 - `codex`：`$HOME/.codex/skills/`
@@ -31,9 +34,16 @@ cd web && bun install && bun run lint
 ## 端到端链路（简述）
 ### 项目安装 / 更新
 - `init`：选择目标 -> 适配器 `install()` -> 落盘目标目录（Gemini: `.agent/`；Codex: `.agents/`）->（Codex）注入托管区块到工作区 `AGENTS.md` 与 `ling.rules`
-- `update`：自动检测已安装目标（或通过 `--target/--targets` 指定）-> 适配器 `update()` ->（Codex）漂移检测与备份 -> 原子替换
+- `update`：自动检测已安装目标（或通过 `--target/--targets` 指定）->（冲突时交互确认或默认预备份）-> 适配器 `update()` ->（Codex）漂移检测与备份 -> 原子替换
 - `doctor`：检查完整性；`--fix` 尝试修复（Codex 支持迁移 `.codex/` 与重写托管区块）
 
+### 已有资产冲突处理（项目级）
+- 触发条件：
+  - `gemini`：`.agent/` 已存在且与内置模板不一致
+  - `codex`：`.agents/` 或 `.codex/` 已存在且存在漂移、缺失 `manifest.json` 或包含未知文件
+- 交互终端会逐项询问处理方式：保留 / 备份后移除 / 直接移除，并支持按资产类别复用选择
+- 非交互环境不会进入询问：需要覆盖时默认执行“备份后覆盖”；`init` 若检测到已有资产且未显式 `--force` 则报错
+
 ### Codex 构建（Workflow -> Skill）
 - 输入：`.agents/skills/` 与 `.agents/workflows/`
 - 规则：每个 Workflow `<name>.md` 会转换为一个 Skill：`workflow-<name>/SKILL.md`
@@ -161,7 +171,6 @@ cp -a "$HOME/.ling/backups/global/$ts/antigravity/$skill" "$HOME/.gemini/antigra
 
 ## 安装提示机制
 - npm 全局安装：`postinstall` 会尽力检测并提示上游英文版 `@vudovn/ag-kit` 冲突。
-- Bun 全局安装：Bun 默认会阻止本包 `postinstall`；因此冲突提示以内置 CLI 运行期检查为准，会在 `init` / `update` / `update-all` / `global sync` 时提示。
 - 冲突提示只负责提醒，不会自动修改当前安装状态；如需清理可执行 `npm uninstall -g @vudovn/ag-kit`。
 
 ## 常见故障

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mison/ling",
-  "version": "1.0.1",
-  "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
+  "version": "1.1.0",
+  "description": "面向 Gemini CLI、Antigravity 与 Codex 的中文 AI Agent 模板工具包",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/MisonL/Ling.git"
@@ -18,7 +18,10 @@
     "skills",
     "templates"
   ],
-  "author": "vudovn",
+  "author": "Mison",
+  "contributors": [
+    "vudovn"
+  ],
   "license": "MIT",
   "scripts": {
     "clean": "node scripts/clean.js",
@@ -50,7 +53,6 @@
     "docs/TECH.md"
   ],
   "bin": {
-    "ling": "bin/ling.js",
-    "ag-kit": "bin/ag-kit.js"
+    "ling": "bin/ling.js"
   }
 }

package/scripts/ci-verify.js

@@ -9,6 +9,7 @@ const REPO_ROOT = path.resolve(__dirname, "..");
 const CLI_PATH = path.join(REPO_ROOT, "bin", "ling.js");
 
 function runCli(args, options = {}) {
+    const allowedStatuses = options.allowedStatuses || [0];
     const env = {
         ...process.env,
         LING_SKIP_UPSTREAM_CHECK: "1",
@@ -21,9 +22,11 @@ function runCli(args, options = {}) {
         encoding: "utf8",
     });
 
-    if (result.status !== 0) {
+    if (!allowedStatuses.includes(result.status)) {
         const message = result.stderr || result.stdout || "";
-        throw new Error(`命令失败: ling ${args.join(" ")}\n${message}`);
+        throw new Error(
+            `命令失败: ling ${args.join(" ")}\n(exit=${result.status})\n${message}`.trim(),
+        );
     }
 
     return result.stdout || "";
@@ -82,7 +85,10 @@ function main() {
         throw new Error(`spec status 结果异常: ${specStatus}`);
     }
     runCli(["spec", "disable", "--target", "codex", "--quiet"], { env });
-    const specStatusAfterDisable = runCli(["spec", "status", "--quiet"], { env }).trim();
+    const specStatusAfterDisable = runCli(["spec", "status", "--quiet"], {
+        env,
+        allowedStatuses: [0, 2],
+    }).trim();
     if (specStatusAfterDisable !== "missing") {
         throw new Error(`spec disable 后状态异常: ${specStatusAfterDisable}`);
     }

package/scripts/postinstall-check.js

@@ -58,7 +58,7 @@ async function main() {
         return;
     }
 
-    if (process.env.LING_SKIP_UPSTREAM_CHECK === "1" || process.env.AG_KIT_SKIP_UPSTREAM_CHECK === "1") {
+    if (process.env.LING_SKIP_UPSTREAM_CHECK === "1") {
         return;
     }
 
@@ -72,13 +72,12 @@ async function main() {
     }
 
     console.warn(`\n[warn] 检测到全局已安装上游英文版 ${UPSTREAM_GLOBAL_PACKAGE}`);
-    console.warn("[warn] 上游英文版与当前版本共用 `ag-kit` 兼容命令名，后安装者会覆盖该入口。");
-    console.warn("[warn] 为避免后续混淆，建议仅保留一个来源。\n");
+    console.warn("[warn] 为避免 Skills/模板来源混用导致的行为差异，建议仅保留一个来源。\n");
 
     if (!canPromptUser()) {
         console.warn("[info] 当前环境不是交互式终端，无法确认是否自动卸载。");
         console.warn(`[hint] 如需卸载，请手动执行: npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`);
-        console.warn("[info] 本次将继续安装；安装完成后正式命令请使用 `ling`。\n");
+        console.warn("[info] 本次将继续安装；安装完成后请使用 `ling`。\n");
         return;
     }
 
@@ -86,7 +85,7 @@ async function main() {
 
     if (!shouldUninstall) {
         console.warn(`[info] 已保留 ${UPSTREAM_GLOBAL_PACKAGE}，继续安装当前版本。`);
-        console.warn("[info] 结果说明：正式命令请使用 `ling`，旧 `ag-kit` 仅保留兼容入口。\n");
+        console.warn("[info] 结果说明：安装完成后请使用 `ling`。\n");
         return;
     }
 
@@ -101,7 +100,7 @@ async function main() {
     console.warn(`[error] 自动卸载 ${UPSTREAM_GLOBAL_PACKAGE} 失败，将继续安装当前版本。`);
     console.warn("[info] 若需手动处理，请执行：");
     console.warn(`   npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`);
-    console.warn("[info] 安装完成后，正式命令请使用 `ling`；旧 `ag-kit` 仅保留兼容入口。\n");
+    console.warn("[info] 安装完成后请使用 `ling`。\n");
 }
 
 main().catch((err) => {

package/tests/clean-script.test.js

@@ -9,7 +9,7 @@ describe("Clean Script", () => {
     let tempRoot;
 
     beforeEach(() => {
-        tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-clean-test-"));
+        tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ling-clean-test-"));
     });
 
     afterEach(() => {

package/tests/cli-smoke.test.js

@@ -27,6 +27,37 @@ describe("CLI Smoke", () => {
     let workspaceDir;
     let indexPath;
 
+    function findFirstTimestampDir(backupRoot) {
+        if (!fs.existsSync(backupRoot)) {
+            return "";
+        }
+        const entries = fs
+            .readdirSync(backupRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+        return entries.length > 0 ? path.join(backupRoot, entries[entries.length - 1]) : "";
+    }
+
+    function findTimestampDirContaining(backupRoot, relPath) {
+        if (!fs.existsSync(backupRoot)) {
+            return "";
+        }
+        const entries = fs
+            .readdirSync(backupRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+
+        for (const name of entries) {
+            const candidate = path.join(backupRoot, name, relPath);
+            if (fs.existsSync(candidate)) {
+                return path.join(backupRoot, name);
+            }
+        }
+        return "";
+    }
+
     beforeEach(() => {
         tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ling-cli-test-"));
         workspaceDir = path.join(tempDir, "workspace");
@@ -273,6 +304,60 @@ describe("CLI Smoke", () => {
         assert.strictEqual(result.status, 0, result.stderr || result.stdout);
     });
 
+    test("init --force should create preflight backup for existing gemini .agent", () => {
+        const agentDir = path.join(workspaceDir, ".agent");
+        fs.mkdirSync(agentDir, { recursive: true });
+        fs.writeFileSync(path.join(agentDir, "custom.txt"), "custom", "utf8");
+
+        const result = runCli(
+            ["init", "--target", "gemini", "--path", workspaceDir, "--force", "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+        const backupRoot = path.join(workspaceDir, ".agent-backup");
+        const tsDir = findFirstTimestampDir(backupRoot);
+        assert.ok(tsDir, "expected .agent-backup timestamp directory to exist");
+        assert.ok(fs.existsSync(path.join(tsDir, "preflight", ".agent", "custom.txt")));
+    });
+
+    test("update should create preflight backup for gemini when overwriting in non-interactive mode", () => {
+        const agentDir = path.join(workspaceDir, ".agent");
+        fs.mkdirSync(agentDir, { recursive: true });
+        fs.writeFileSync(path.join(agentDir, "custom.txt"), "custom", "utf8");
+
+        const result = runCli(
+            ["update", "--target", "gemini", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+        const backupRoot = path.join(workspaceDir, ".agent-backup");
+        const tsDir = findFirstTimestampDir(backupRoot);
+        assert.ok(tsDir, "expected .agent-backup timestamp directory to exist");
+        assert.ok(fs.existsSync(path.join(tsDir, "preflight", ".agent", "custom.txt")));
+    });
+
+    test("update should create preflight backup for codex when unknown files exist in managed dir", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        fs.writeFileSync(path.join(workspaceDir, ".agents", "unknown.txt"), "unknown", "utf8");
+
+        const updateResult = runCli(
+            ["update", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(updateResult.status, 0, updateResult.stderr || updateResult.stdout);
+
+        const backupRoot = path.join(workspaceDir, ".agents-backup");
+        const tsDir = findTimestampDirContaining(backupRoot, path.join("preflight", ".agents", "unknown.txt"));
+        assert.ok(tsDir, "expected .agents-backup preflight backup to exist");
+    });
+
     test("status --quiet should report missing with exit code 2 when nothing is installed", () => {
         const result = runCli(
             ["status", "--path", workspaceDir, "--quiet"],

package/tests/managed-block.test.js

@@ -25,7 +25,7 @@ describe("ManagedBlock", () => {
         assert.strictEqual(result.action, "appended");
         const content = fs.readFileSync(targetFile, "utf8");
         assert.ok(content.includes("User Content"));
-        assert.ok(content.includes("BEGIN AG-KIT MANAGED BLOCK: codex-core-rules"));
+        assert.ok(content.includes("BEGIN LING MANAGED BLOCK: codex-core-rules"));
         assert.ok(content.includes("managed line"));
     });
 
@@ -38,4 +38,21 @@ describe("ManagedBlock", () => {
         assert.ok(content.includes("v2"));
         assert.ok(!content.includes("v1"));
     });
+
+    test("should migrate legacy AG-KIT markers when updating managed block", () => {
+        fs.writeFileSync(
+            targetFile,
+            `# User Content\n\n<!-- BEGIN AG-KIT MANAGED BLOCK: codex-core-rules -->\nlegacy\n<!-- END AG-KIT MANAGED BLOCK: codex-core-rules -->\n`,
+            "utf8",
+        );
+
+        const result = upsertManagedBlock(targetFile, "codex-core-rules", "v2");
+
+        assert.strictEqual(result.action, "updated");
+        const content = fs.readFileSync(targetFile, "utf8");
+        assert.ok(content.includes("BEGIN LING MANAGED BLOCK: codex-core-rules"));
+        assert.ok(!content.includes("BEGIN AG-KIT MANAGED BLOCK: codex-core-rules"));
+        assert.ok(content.includes("v2"));
+        assert.ok(!content.includes("legacy"));
+    });
 });

package/tests/phase-c.test.js

@@ -66,9 +66,9 @@ describe('Phase C Integration', () => {
         // Verification 4: Workspace managed block injection
         const workspaceAgents = fs.readFileSync(path.join(workDir, 'AGENTS.md'), 'utf8');
         const workspaceRules = fs.readFileSync(path.join(workDir, 'ling.rules'), 'utf8');
-        assert.ok(workspaceAgents.includes('BEGIN AG-KIT MANAGED BLOCK: codex-core-rules'));
+        assert.ok(workspaceAgents.includes('BEGIN LING MANAGED BLOCK: codex-core-rules'));
         assert.ok(workspaceAgents.includes('test-skill'));
-        assert.ok(workspaceRules.includes('BEGIN AG-KIT MANAGED BLOCK: codex-risk-controls'));
+        assert.ok(workspaceRules.includes('BEGIN LING MANAGED BLOCK: codex-risk-controls'));
 
         const codexJson = JSON.parse(fs.readFileSync(path.join(codexDir, 'codex.json'), 'utf8'));
         assert.strictEqual(codexJson.version, pkg.version);

package/tests/standards-compliance.test.js

@@ -79,7 +79,7 @@ describe('Standards Compliance', () => {
 
     test('critical mechanism tokens should remain aligned with reference snapshot', { skip: !fs.existsSync(REF_ROOT) }, () => {
         const refRoot = REF_ROOT;
-        const tokenRegex = /(ag-kit|ling|python3?|checklist\.py|verify_all\.py|security_scan\.py|ux_audit\.py|accessibility_checker\.py|schema_validator\.py|lint_runner\.py|type_coverage\.py|playwright_runner\.py|lighthouse_audit\.py|api_validator\.py|mobile_audit\.py|seo_checker\.py|geo_checker\.py|i18n_checker\.py|\.agent\/|\.agents\/|\.agents-backup\/|\.codex\/|AGENTS\.md|antigravity\.rules|ling\.rules|manifest\.json|--target|--targets|--fix|--path|--no-index|--dry-run|--quiet|--force)/g;
+        const tokenRegex = /(ling|python3?|checklist\.py|verify_all\.py|security_scan\.py|ux_audit\.py|accessibility_checker\.py|schema_validator\.py|lint_runner\.py|type_coverage\.py|playwright_runner\.py|lighthouse_audit\.py|api_validator\.py|mobile_audit\.py|seo_checker\.py|geo_checker\.py|i18n_checker\.py|\.agent\/|\.agents\/|\.agents-backup\/|\.codex\/|AGENTS\.md|antigravity\.rules|ling\.rules|manifest\.json|--target|--targets|--fix|--path|--no-index|--dry-run|--quiet|--force)/g;
         const slashCommandRegex = /(?:^|[\s`"'(\[])(\/(?:brainstorm|create|debug|deploy|enhance|orchestrate|plan|preview|status|test|ui-ux-pro-max))(?=$|[\s`"'，。,.:：)\]])/gm;
 
         const markdownFiles = [];

package/tests/transformer.test.js

@@ -9,7 +9,7 @@ describe("ResourceTransformer", () => {
     let tempDir;
 
     beforeEach(() => {
-        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-transformer-test-"));
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ling-transformer-test-"));
     });
 
     afterEach(() => {

package/tests/versioning.test.js

@@ -7,7 +7,6 @@ const { spawnSync } = require("node:child_process");
 
 const REPO_ROOT = path.resolve(__dirname, "..");
 const LING_CLI = path.join(REPO_ROOT, "bin", "ling.js");
-const AG_KIT_CLI = path.join(REPO_ROOT, "bin", "ag-kit.js");
 const pkg = require(path.join(REPO_ROOT, "package.json"));
 
 function runCli(cliPath, args, envOverrides = {}) {
@@ -40,12 +39,3 @@ test("ling --version should print ling- prefixed version tag", () => {
     assert.strictEqual(stdout, `ling version ling-${pkg.version}`);
     assert.ok(!stdout.includes("[warn]"), "ling entry should not include legacy alias warning");
 });
-
-test("ag-kit --version should warn and print ling- prefixed version tag", () => {
-    const result = runCli(AG_KIT_CLI, ["--version"]);
-    assert.strictEqual(result.status, 0, result.stderr || result.stdout);
-    const lines = String(result.stdout || "").trim().split(/\r?\n/);
-    assert.ok(lines.some((line) => line.includes("[warn]")), "ag-kit entry should include legacy alias warning");
-    assert.strictEqual(lines[lines.length - 1], `ling version ling-${pkg.version}`);
-});
-