@mison/ling 1.1.0 → 1.1.1

package/bin/utils.js

@@ -1,9 +1,17 @@
-const { execSync } = require("child_process");
+const { execSync, spawnSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
 
-const REPO_URL = "https://github.com/MisonL/Ling.git";
+const DEFAULT_REPO_URL = "https://github.com/MisonL/Ling.git";
+
+function resolveRepoUrl() {
+    const override = process.env.LING_REPO_URL;
+    if (typeof override === "string" && override.trim()) {
+        return override.trim();
+    }
+    return DEFAULT_REPO_URL;
+}
 
 function parseJsonSafe(raw) {
     try {
@@ -51,14 +59,15 @@ function cloneBranchAgentDir(branch, options) {
 
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ling-"));
     const logFn = options && options.logger ? options.logger : console.log;
+    const repoUrl = resolveRepoUrl();
 
-    if (!options.quiet) logFn(`[download] 正在从 ${REPO_URL} 拉取分支 ${safeBranch} ...`);
+    if (!options.quiet) logFn(`[download] 正在从 ${repoUrl} 拉取分支 ${safeBranch} ...`);
 
-    try {
-        execSync(`git clone --depth 1 --branch ${safeBranch} ${REPO_URL} "${tempDir}"`, {
-            stdio: options.quiet ? "ignore" : "pipe",
-        });
-    } catch (err) {
+    const cloneResult = spawnSync("git", ["clone", "--depth", "1", "--branch", safeBranch, repoUrl, tempDir], {
+        encoding: "utf8",
+        stdio: options.quiet ? "ignore" : "pipe",
+    });
+    if (cloneResult.status !== 0) {
         fs.rmSync(tempDir, { recursive: true, force: true });
         throw new Error(`无法拉取分支 ${safeBranch}，请确认分支存在且网络可用`);
     }
@@ -82,8 +91,42 @@ function cloneBranchAgentDir(branch, options) {
     };
 }
 
+function cloneBranchSpecDir(branch, options) {
+    const safeBranch = branch.trim();
+    if (!/^[A-Za-z0-9._/-]+$/.test(safeBranch)) {
+        throw new Error(`非法分支名: ${branch}`);
+    }
+
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ling-"));
+    const logFn = options && options.logger ? options.logger : console.log;
+    const repoUrl = resolveRepoUrl();
+
+    if (!options.quiet) logFn(`[download] 正在从 ${repoUrl} 拉取分支 ${safeBranch} (spec) ...`);
+
+    const cloneResult = spawnSync("git", ["clone", "--depth", "1", "--branch", safeBranch, repoUrl, tempDir], {
+        encoding: "utf8",
+        stdio: options.quiet ? "ignore" : "pipe",
+    });
+    if (cloneResult.status !== 0) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        throw new Error(`无法拉取分支 ${safeBranch}，请确认分支存在且网络可用`);
+    }
+
+    const specDir = path.join(tempDir, ".spec");
+    if (!fs.existsSync(specDir)) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        throw new Error(`分支 ${safeBranch} 中未找到 .spec 目录`);
+    }
+
+    return {
+        specDir,
+        cleanup: () => fs.rmSync(tempDir, { recursive: true, force: true }),
+    };
+}
+
 module.exports = {
     parseJsonSafe,
     readGlobalNpmDependencies,
-    cloneBranchAgentDir
+    cloneBranchAgentDir,
+    cloneBranchSpecDir
 };

package/docs/TECH.md

@@ -65,19 +65,27 @@ cd web && npm install && npm run lint
 ### 测试隔离
 - `LING_GLOBAL_ROOT`：替代 `$HOME`（用于测试与 CI，避免污染真实用户目录）
 
-## Spec Profile：`ling spec enable/disable/status`
+## Spec Profile：`ling spec ...`
 ### 当前范围
-- 当前只实现全局层：
+- 全局 Spec Profile（机器级）：
   - `ling spec enable [--target codex|gemini] [--dry-run] [--quiet]`
   - `ling spec disable [--target codex|gemini] [--dry-run] [--quiet]`
   - `ling spec status [--quiet]`
-- 默认目标：未指定 `--target/--targets` 时启用 `codex + gemini`
-- 当前 Spec 源目录：`.spec/`
+  - 默认目标：未指定 `--target/--targets` 时启用 `codex + gemini`
+- 项目级 Spec 资产（工作区级）：
+  - `ling spec init [--path <dir>] [--target codex|gemini|--targets codex,gemini] [--branch <name>] [--dry-run] [--quiet]`
+    - 未指定 `--path` 时，默认初始化 Spec 工作区目录：`$HOME/.ling/spec-workspace`
+    - 指定 `--targets` 时，会同时执行对应目标的 `ling init` 安装（`.agent/.agents`）
+    - 指定 `--branch` 时，Spec 资产将从该分支的 `.spec/` 拉取（用于验证或灰度 Spec 模板）
+  - `ling spec doctor [--path <dir>] [--quiet]`
+    - 会校验 `issues.csv` 表头与状态枚举，并检查 `.ling/spec/` 目录是否完整
+- Spec 源目录：`.spec/`
 
 ### 落盘与状态
 - Spec 状态文件：`$HOME/.ling/spec/state.json`
 - Spec templates：`$HOME/.ling/spec/templates/`
 - Spec references：`$HOME/.ling/spec/references/`
+- Spec profiles：`$HOME/.ling/spec/profiles/`
 - Spec 备份目录：`$HOME/.ling/backups/spec/<timestamp>/before/...`
 
 ### 当前安装内容
@@ -94,6 +102,10 @@ cd web && npm install && npm run lint
   - `harness-engineering-digest.md`
   - `gda-framework.md`
   - 相关 quickstart / README
+- Profiles：
+  - `codex/AGENTS.spec.md`
+  - `codex/ling.spec.rules.md`
+  - `gemini/GEMINI.spec.md`
 
 ### 状态契约
 - `ling spec status --quiet` 输出：
@@ -108,11 +120,13 @@ cd web && npm install && npm run lint
 ### 回退语义
 - `spec enable`：
   - 若目标位置已存在同名 Skill，会先备份再覆盖
-  - 若 `templates/` 或 `references/` 已存在，也会先备份
+  - 若 `templates/`、`references/` 或 `profiles/` 已存在，也会先备份
 - `spec disable`：
   - 若存在备份，恢复启用前快照
   - 若启用前不存在资源，则删除由 Spec 安装的目录
-- 当前尚未实现项目级 `spec init / remove / doctor`
+- `spec init`：
+  - 会在工作区内写入 `.ling/spec/`（templates/references/profiles）与 `issues.csv`，并创建 `docs/reviews`、`docs/handoff`
+  - 当检测到冲突资产时，支持保留 / 备份后覆盖 / 直接覆盖
 
 ## 状态契约（自动化）
 - `ling status --quiet` / `ling global status --quiet` 只输出三态：
@@ -168,6 +182,7 @@ cp -a "$HOME/.ling/backups/global/$ts/antigravity/$skill" "$HOME/.gemini/antigra
 - `LING_INDEX_PATH`：工作区索引文件路径（默认 `~/.ling/workspaces.json`）
 - `LING_GLOBAL_ROOT`：全局目录根（替代 `$HOME`）
 - `LING_SKIP_UPSTREAM_CHECK`：跳过上游同名包安装提示（测试用）
+- `LING_REPO_URL`：覆盖默认仓库地址（主要用于测试与私有镜像）
 
 ## 安装提示机制
 - npm 全局安装：`postinstall` 会尽力检测并提示上游英文版 `@vudovn/ag-kit` 冲突。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/ling",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "面向 Gemini CLI、Antigravity 与 Codex 的中文 AI Agent 模板工具包",
   "repository": {
     "type": "git",

package/tests/spec-init-doctor.test.js

@@ -0,0 +1,175 @@
+const { test, describe, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("node:child_process");
+
+const REPO_ROOT = path.resolve(__dirname, "..");
+const CLI_PATH = path.join(REPO_ROOT, "bin", "ling.js");
+
+function runCli(args, options = {}) {
+    const env = {
+        ...process.env,
+        LING_SKIP_UPSTREAM_CHECK: "1",
+        ...options.env,
+    };
+
+    return spawnSync(process.execPath, [CLI_PATH, ...args], {
+        cwd: options.cwd || REPO_ROOT,
+        env,
+        encoding: "utf8",
+    });
+}
+
+describe("Spec init/doctor", () => {
+    let tempRoot;
+    let workspaceRoot;
+
+    beforeEach(() => {
+        tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ling-spec-init-"));
+        workspaceRoot = path.join(tempRoot, "workspace");
+        fs.mkdirSync(workspaceRoot, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    });
+
+    test("spec init should create workspace assets and doctor should report installed", () => {
+        const env = {
+            LING_GLOBAL_ROOT: tempRoot,
+            LING_INDEX_PATH: path.join(tempRoot, "workspaces.json"),
+        };
+
+        const initResult = runCli(["spec", "init", "--path", workspaceRoot, "--quiet"], { env });
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        assert.ok(fs.existsSync(path.join(workspaceRoot, "issues.csv")), "issues.csv should be created");
+        assert.ok(fs.existsSync(path.join(workspaceRoot, ".ling", "spec", "templates", "driver-prompt.md")), "spec templates should be created");
+        assert.ok(fs.existsSync(path.join(workspaceRoot, ".ling", "spec", "references", "gda-framework.md")), "spec references should be created");
+        assert.ok(fs.existsSync(path.join(workspaceRoot, ".ling", "spec", "profiles", "codex", "AGENTS.spec.md")), "spec profiles should be created");
+        assert.ok(
+            fs.existsSync(path.join(workspaceRoot, ".ling", "spec", "profiles", "codex", "ling.spec.rules.md")),
+            "spec profile rules should be created",
+        );
+        assert.ok(fs.existsSync(path.join(workspaceRoot, ".ling", "spec", "profiles", "gemini", "GEMINI.spec.md")), "spec profiles should be created");
+        assert.ok(fs.existsSync(path.join(workspaceRoot, "docs", "reviews")), "docs/reviews should exist");
+        assert.ok(fs.existsSync(path.join(workspaceRoot, "docs", "handoff")), "docs/handoff should exist");
+
+        const doctorResult = runCli(["spec", "doctor", "--path", workspaceRoot, "--quiet"], { env });
+        assert.strictEqual(doctorResult.status, 0, doctorResult.stderr || doctorResult.stdout);
+        assert.strictEqual((doctorResult.stdout || "").trim(), "installed");
+    });
+
+    test("spec doctor should report broken when multiple tasks are in 进行中", () => {
+        const env = {
+            LING_GLOBAL_ROOT: tempRoot,
+            LING_INDEX_PATH: path.join(tempRoot, "workspaces.json"),
+        };
+
+        const initResult = runCli(["spec", "init", "--path", workspaceRoot, "--quiet"], { env });
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        const issuesPath = path.join(workspaceRoot, "issues.csv");
+        fs.writeFileSync(
+            issuesPath,
+            [
+                "ID,标题,内容,验收标准,审查要求,状态,标签",
+                "A,任务A,内容A,验收A,审查A,进行中,高优先级",
+                "B,任务B,内容B,验收B,审查B,进行中,高优先级",
+                "",
+            ].join("\n"),
+            "utf8",
+        );
+
+        const doctorResult = runCli(["spec", "doctor", "--path", workspaceRoot, "--quiet"], { env });
+        assert.strictEqual(doctorResult.status, 1, doctorResult.stderr || doctorResult.stdout);
+        assert.strictEqual((doctorResult.stdout || "").trim(), "broken");
+    });
+
+    test("spec doctor should report broken when issues.csv is missing but spec directory exists", () => {
+        const env = {
+            LING_GLOBAL_ROOT: tempRoot,
+            LING_INDEX_PATH: path.join(tempRoot, "workspaces.json"),
+        };
+
+        const initResult = runCli(["spec", "init", "--path", workspaceRoot, "--quiet"], { env });
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        fs.rmSync(path.join(workspaceRoot, "issues.csv"), { force: true });
+
+        const doctorResult = runCli(["spec", "doctor", "--path", workspaceRoot, "--quiet"], { env });
+        assert.strictEqual(doctorResult.status, 1, doctorResult.stderr || doctorResult.stdout);
+        assert.strictEqual((doctorResult.stdout || "").trim(), "broken");
+    });
+
+    test("spec init should support --branch for spec assets", () => {
+        const gitCheck = spawnSync("git", ["--version"], { encoding: "utf8" });
+        if (gitCheck.status !== 0) {
+            return;
+        }
+
+        const sourceRepo = path.join(tempRoot, "spec-source-repo");
+        fs.mkdirSync(sourceRepo, { recursive: true });
+
+        const runGit = (args) =>
+            spawnSync("git", args, {
+                cwd: sourceRepo,
+                encoding: "utf8",
+            });
+
+        const initRes = runGit(["init", "--initial-branch", "main"]);
+        if (initRes.status !== 0) {
+            assert.strictEqual(runGit(["init"]).status, 0);
+            assert.strictEqual(runGit(["checkout", "-b", "main"]).status, 0);
+        }
+
+        const specRoot = path.join(sourceRepo, ".spec");
+        const templatesDir = path.join(specRoot, "templates");
+        const referencesDir = path.join(specRoot, "references");
+        const profilesCodexDir = path.join(specRoot, "profiles", "codex");
+        const profilesGeminiDir = path.join(specRoot, "profiles", "gemini");
+        fs.mkdirSync(templatesDir, { recursive: true });
+        fs.mkdirSync(referencesDir, { recursive: true });
+        fs.mkdirSync(profilesCodexDir, { recursive: true });
+        fs.mkdirSync(profilesGeminiDir, { recursive: true });
+
+        fs.writeFileSync(path.join(templatesDir, "issues.template.csv"), "ID,状态\nX,未开始\n", "utf8");
+        fs.writeFileSync(path.join(templatesDir, "driver-prompt.md"), "branch driver prompt", "utf8");
+        fs.writeFileSync(path.join(templatesDir, "review-report.md"), "branch review report", "utf8");
+        fs.writeFileSync(path.join(templatesDir, "phase-acceptance.md"), "branch acceptance", "utf8");
+        fs.writeFileSync(path.join(templatesDir, "handoff.md"), "branch handoff", "utf8");
+
+        fs.writeFileSync(path.join(referencesDir, "README.md"), "branch readme", "utf8");
+        fs.writeFileSync(path.join(referencesDir, "harness-engineering-digest.md"), "branch digest", "utf8");
+        fs.writeFileSync(path.join(referencesDir, "gda-framework.md"), "branch gda", "utf8");
+        fs.writeFileSync(path.join(referencesDir, "cse-quickstart.md"), "branch quickstart", "utf8");
+
+        fs.writeFileSync(path.join(profilesCodexDir, "AGENTS.spec.md"), "branch codex agents", "utf8");
+        fs.writeFileSync(path.join(profilesCodexDir, "ling.spec.rules.md"), "branch codex rules", "utf8");
+        fs.writeFileSync(path.join(profilesGeminiDir, "GEMINI.spec.md"), "branch gemini profile", "utf8");
+
+        assert.strictEqual(runGit(["add", "."]).status, 0);
+        assert.strictEqual(
+            runGit(["-c", "user.name=ling-test", "-c", "user.email=ling-test@example.com", "commit", "-m", "spec assets"]).status,
+            0,
+        );
+
+        const env = {
+            LING_GLOBAL_ROOT: tempRoot,
+            LING_REPO_URL: sourceRepo,
+            LING_INDEX_PATH: path.join(tempRoot, "workspaces.json"),
+        };
+
+        const initResult = runCli(["spec", "init", "--path", workspaceRoot, "--branch", "main", "--quiet"], { env });
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        const installedPrompt = path.join(workspaceRoot, ".ling", "spec", "templates", "driver-prompt.md");
+        assert.strictEqual(fs.readFileSync(installedPrompt, "utf8"), "branch driver prompt");
+
+        const doctorResult = runCli(["spec", "doctor", "--path", workspaceRoot, "--quiet"], { env });
+        assert.strictEqual(doctorResult.status, 0, doctorResult.stderr || doctorResult.stdout);
+        assert.strictEqual((doctorResult.stdout || "").trim(), "installed");
+    });
+});

package/tests/spec-profile.test.js

@@ -51,11 +51,14 @@ describe("Spec Profile", () => {
         const stateFile = path.join(tempRoot, ".ling", "spec", "state.json");
         const templatesDir = path.join(tempRoot, ".ling", "spec", "templates");
         const referencesDir = path.join(tempRoot, ".ling", "spec", "references");
+        const profilesDir = path.join(tempRoot, ".ling", "spec", "profiles");
 
         assert.ok(fs.existsSync(codexSkill), "missing installed codex spec skill");
         assert.ok(fs.existsSync(stateFile), "missing spec state");
         assert.ok(fs.existsSync(path.join(templatesDir, "issues.template.csv")), "missing spec template");
         assert.ok(fs.existsSync(path.join(referencesDir, "harness-engineering-digest.md")), "missing spec reference");
+        assert.ok(fs.existsSync(path.join(profilesDir, "codex", "AGENTS.spec.md")), "missing spec profile");
+        assert.ok(fs.existsSync(path.join(profilesDir, "codex", "ling.spec.rules.md")), "missing spec profile rules");
 
         const statusResult = runCli(["spec", "status", "--quiet"], { env });
         assert.strictEqual(statusResult.status, 0);
@@ -67,6 +70,7 @@ describe("Spec Profile", () => {
         assert.ok(!fs.existsSync(stateFile), "spec state should be removed after final disable");
         assert.ok(!fs.existsSync(templatesDir), "spec templates should be removed after final disable");
         assert.ok(!fs.existsSync(referencesDir), "spec references should be removed after final disable");
+        assert.ok(!fs.existsSync(profilesDir), "spec profiles should be removed after final disable");
     });
 
     test("spec disable should restore pre-existing skill backup", () => {
@@ -83,4 +87,68 @@ describe("Spec Profile", () => {
         assert.strictEqual(disableResult.status, 0, disableResult.stderr || disableResult.stdout);
         assert.strictEqual(fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8"), "legacy skill");
     });
+
+    test("spec enable should repair missing assets and skills when state exists", () => {
+        const env = { LING_GLOBAL_ROOT: tempRoot };
+
+        const enableResult = runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
+        assert.strictEqual(enableResult.status, 0, enableResult.stderr || enableResult.stdout);
+
+        const templatesDir = path.join(tempRoot, ".ling", "spec", "templates");
+        const codexSkillDir = path.join(tempRoot, ".codex", "skills", "harness-engineering");
+        fs.rmSync(templatesDir, { recursive: true, force: true });
+        fs.rmSync(codexSkillDir, { recursive: true, force: true });
+
+        const brokenResult = runCli(["spec", "status", "--quiet"], { env });
+        assert.strictEqual(brokenResult.status, 1);
+        assert.strictEqual((brokenResult.stdout || "").trim(), "broken");
+
+        const repairResult = runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
+        assert.strictEqual(repairResult.status, 0, repairResult.stderr || repairResult.stdout);
+
+        const repairedStatus = runCli(["spec", "status", "--quiet"], { env });
+        assert.strictEqual(repairedStatus.status, 0);
+        assert.strictEqual((repairedStatus.stdout || "").trim(), "installed");
+
+        assert.ok(fs.existsSync(path.join(templatesDir, "issues.template.csv")), "templates should be repaired");
+        assert.ok(fs.existsSync(path.join(codexSkillDir, "SKILL.md")), "spec skill should be repaired");
+    });
+
+    test("spec status should report broken when an asset file is missing", () => {
+        const env = { LING_GLOBAL_ROOT: tempRoot };
+
+        const enableResult = runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
+        assert.strictEqual(enableResult.status, 0, enableResult.stderr || enableResult.stdout);
+
+        const driverPrompt = path.join(tempRoot, ".ling", "spec", "templates", "driver-prompt.md");
+        assert.ok(fs.existsSync(driverPrompt), "driver-prompt.md should exist after enable");
+        fs.rmSync(driverPrompt, { force: true });
+
+        const statusResult = runCli(["spec", "status", "--quiet"], { env });
+        assert.strictEqual(statusResult.status, 1);
+        assert.strictEqual((statusResult.stdout || "").trim(), "broken");
+
+        const repairResult = runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
+        assert.strictEqual(repairResult.status, 0, repairResult.stderr || repairResult.stdout);
+        assert.ok(fs.existsSync(driverPrompt), "driver-prompt.md should be repaired");
+    });
+
+    test("spec status should report broken when state.json is missing but assets exist", () => {
+        const env = { LING_GLOBAL_ROOT: tempRoot };
+
+        const templatesDir = path.join(tempRoot, ".ling", "spec", "templates");
+        fs.mkdirSync(templatesDir, { recursive: true });
+        fs.writeFileSync(path.join(templatesDir, "issues.template.csv"), "sentinel", "utf8");
+
+        const statusResult = runCli(["spec", "status", "--quiet"], { env });
+        assert.strictEqual(statusResult.status, 1);
+        assert.strictEqual((statusResult.stdout || "").trim(), "broken");
+
+        const repairResult = runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
+        assert.strictEqual(repairResult.status, 0, repairResult.stderr || repairResult.stdout);
+
+        const repairedStatus = runCli(["spec", "status", "--quiet"], { env });
+        assert.strictEqual(repairedStatus.status, 0);
+        assert.strictEqual((repairedStatus.stdout || "").trim(), "installed");
+    });
 });