@mison/ling 1.0.0

package/bin/utils/managed-block.js

@@ -0,0 +1,65 @@
+const fs = require("fs");
+const path = require("path");
+
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function detectLineEnding(content) {
+    return content.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function buildMarkers(blockId) {
+    const id = String(blockId || "default").trim();
+    return {
+        begin: `<!-- BEGIN AG-KIT MANAGED BLOCK: ${id} -->`,
+        end: `<!-- END AG-KIT MANAGED BLOCK: ${id} -->`,
+    };
+}
+
+function buildManagedBlock(blockId, body, lineEnding = "\n") {
+    const markers = buildMarkers(blockId);
+    const normalizedBody = String(body || "").replace(/\r?\n/g, lineEnding).trimEnd();
+    return `${markers.begin}${lineEnding}${normalizedBody}${lineEnding}${markers.end}`;
+}
+
+function upsertManagedBlock(filePath, blockId, body, options = {}) {
+    const dryRun = Boolean(options.dryRun);
+    const original = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+    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",
+    );
+
+    let next = "";
+    let action = "unchanged";
+
+    if (!original) {
+        next = `${managedBlock}${lineEnding}`;
+        action = "created";
+    } else if (blockRegex.test(original)) {
+        next = original.replace(blockRegex, managedBlock);
+        action = next === original ? "unchanged" : "updated";
+        if (next && !/\r?\n$/.test(next)) {
+            next += lineEnding;
+        }
+    } else {
+        next = `${original.replace(/\r?\n?$/, "")}${lineEnding}${lineEnding}${managedBlock}${lineEnding}`;
+        action = "appended";
+    }
+
+    if (!dryRun && action !== "unchanged") {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, next, "utf8");
+    }
+
+    return { action };
+}
+
+module.exports = {
+    buildManagedBlock,
+    upsertManagedBlock,
+};

package/bin/utils/manifest.js

@@ -0,0 +1,244 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+class ManifestManager {
+    constructor(manifestPath, options = {}) {
+        this.manifestPath = manifestPath;
+        this.options = options;
+        this.manifest = {
+            version: 2,
+            target: typeof options.target === "string" ? options.target : "",
+            kitVersion: typeof options.kitVersion === "string" ? options.kitVersion : "",
+            updatedAt: "",
+            files: {},
+        };
+        this.lastLoadError = null;
+    }
+
+    /**
+     * Compute SHA-256 hash of a string or buffer
+     * @param {string|Buffer} content 
+     * @returns {string} sha256 hash
+     */
+    static computeHash(content) {
+        return crypto.createHash("sha256").update(content).digest("hex");
+    }
+
+    static normalizeFileEntry(entry) {
+        if (typeof entry === "string") {
+            return { hash: entry, source: "" };
+        }
+        if (!entry || typeof entry !== "object") {
+            return null;
+        }
+        const hash = typeof entry.hash === "string" ? entry.hash : "";
+        const source = typeof entry.source === "string" ? entry.source : "";
+        if (!hash) {
+            return null;
+        }
+        return { hash, source };
+    }
+
+    static extractHash(entry) {
+        if (typeof entry === "string") {
+            return entry;
+        }
+        if (entry && typeof entry === "object" && typeof entry.hash === "string") {
+            return entry.hash;
+        }
+        return "";
+    }
+
+    static normalizeManifestShape(input) {
+        const output = {
+            version: typeof input.version === "number" ? input.version : 2,
+            target: typeof input.target === "string" ? input.target : "",
+            kitVersion: typeof input.kitVersion === "string" ? input.kitVersion : "",
+            updatedAt: typeof input.updatedAt === "string" ? input.updatedAt : "",
+            files: {},
+        };
+
+        if (!input.files || typeof input.files !== "object") {
+            return output;
+        }
+
+        for (const [relPath, entry] of Object.entries(input.files)) {
+            const normalized = ManifestManager.normalizeFileEntry(entry);
+            if (!normalized) {
+                continue;
+            }
+            output.files[relPath] = normalized;
+        }
+
+        return output;
+    }
+
+    /**
+     * Load manifest from disk
+     */
+    load() {
+        this.lastLoadError = null;
+        if (fs.existsSync(this.manifestPath)) {
+            try {
+                const raw = fs.readFileSync(this.manifestPath, "utf8");
+                this.manifest = ManifestManager.normalizeManifestShape(JSON.parse(raw));
+            } catch (err) {
+                this.lastLoadError = err;
+                this.manifest = {
+                    version: 2,
+                    target: typeof this.options.target === "string" ? this.options.target : "",
+                    kitVersion: typeof this.options.kitVersion === "string" ? this.options.kitVersion : "",
+                    updatedAt: "",
+                    files: {},
+                };
+            }
+        }
+        return this.manifest;
+    }
+
+    /**
+     * Save manifest to disk
+     */
+    save() {
+        this.manifest.updatedAt = new Date().toISOString();
+        if (!this.manifest.target && this.options.target) {
+            this.manifest.target = this.options.target;
+        }
+        if (!this.manifest.kitVersion && this.options.kitVersion) {
+            this.manifest.kitVersion = this.options.kitVersion;
+        }
+        const dir = path.dirname(this.manifestPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(this.manifestPath, `${JSON.stringify(this.manifest, null, 2)}\n`, "utf8");
+    }
+
+    /**
+     * Generate manifest entries from a directory recursively
+     * @param {string} rootDir Directory to scan
+     * @param {string} [baseDir] Base directory for relative paths (default: rootDir)
+     * @returns {object} { file: hash } map
+     */
+    static generateFromDir(rootDir, baseDir = rootDir) {
+        const entries = ManifestManager.generateFileEntriesFromDir(rootDir, {
+            baseDir,
+        });
+        const hashes = {};
+        for (const [relPath, entry] of Object.entries(entries)) {
+            hashes[relPath] = entry.hash;
+        }
+        return hashes;
+    }
+
+    /**
+     * Generate managed file entries from a directory recursively
+     * @param {string} rootDir Directory to scan
+     * @param {object} options
+     * @param {string} [options.baseDir=rootDir] Base directory for relative paths
+     * @param {string} [options.sourcePrefix=""] Prefix recorded in `source` field
+     * @returns {object} { file: { hash, source } } map
+     */
+    static generateFileEntriesFromDir(rootDir, options = {}) {
+        const baseDir = options.baseDir || rootDir;
+        const sourcePrefix = typeof options.sourcePrefix === "string" ? options.sourcePrefix.trim() : "";
+        const files = {};
+        
+        function scan(dir) {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    scan(fullPath);
+                } else if (entry.isFile()) {
+                    const content = fs.readFileSync(fullPath);
+                    const hash = ManifestManager.computeHash(content);
+                    const relPath = path.relative(baseDir, fullPath).split(path.sep).join("/");
+                    files[relPath] = {
+                        hash,
+                        source: sourcePrefix ? `${sourcePrefix}/${relPath}` : relPath,
+                    };
+                }
+            }
+        }
+        
+        if (fs.existsSync(rootDir)) {
+            scan(rootDir);
+        }
+        return files;
+    }
+
+    /**
+     * Compare existing manifest with current file system state to detect user changes
+     * @param {string} projectRoot 
+     * @returns {object} { modified: [], missing: [], unknown: [] } 
+     */
+    checkDrift(projectRoot) {
+        // This checks if the files listed in the manifest (which should match what we installed)
+        // still match what is currently on disk.
+        // Useful for doctor or update pre-check.
+        const drift = {
+            modified: [], // Hash mismatch
+            missing: [],  // File in manifest but not on disk
+        };
+
+        for (const [relPath, entry] of Object.entries(this.manifest.files || {})) {
+            const expectedHash = ManifestManager.extractHash(entry);
+            if (!expectedHash) {
+                continue;
+            }
+            const absPath = path.join(projectRoot, relPath);
+            if (!fs.existsSync(absPath)) {
+                drift.missing.push(relPath);
+            } else {
+                const content = fs.readFileSync(absPath);
+                const currentHash = ManifestManager.computeHash(content);
+                if (currentHash !== expectedHash) {
+                    drift.modified.push(relPath);
+                }
+            }
+        }
+        return drift;
+    }
+
+    /**
+     * Select user-modified files to backup during overwrite:
+     * currentHash != manifestHash AND currentHash != incomingHash
+     * @param {string} projectRoot
+     * @param {object} incomingFiles Next manifest files map
+     * @returns {string[]} relative file paths
+     */
+    collectSmartOverwriteConflicts(projectRoot, incomingFiles = {}) {
+        const modified = [];
+        const existingFiles = this.manifest.files || {};
+
+        for (const [relPath, manifestEntry] of Object.entries(existingFiles)) {
+            const expectedHash = ManifestManager.extractHash(manifestEntry);
+            if (!expectedHash) {
+                continue;
+            }
+
+            const absPath = path.join(projectRoot, relPath);
+            if (!fs.existsSync(absPath)) {
+                continue;
+            }
+
+            const currentHash = ManifestManager.computeHash(fs.readFileSync(absPath));
+            if (currentHash === expectedHash) {
+                continue;
+            }
+
+            const incomingHash = ManifestManager.extractHash(incomingFiles[relPath]);
+            if (incomingHash && currentHash === incomingHash) {
+                continue;
+            }
+
+            modified.push(relPath);
+        }
+
+        return modified;
+    }
+}
+
+module.exports = ManifestManager;

package/bin/utils.js

@@ -0,0 +1,89 @@
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const REPO_URL = "https://github.com/MisonL/Ling.git";
+
+function parseJsonSafe(raw) {
+    try {
+        return JSON.parse(raw);
+    } catch (err) {
+        return null;
+    }
+}
+
+function readGlobalNpmDependencies() {
+    const cmd = "npm ls --global --depth=0 --json --silent";
+    let output = "";
+
+    try {
+        output = execSync(cmd, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    } catch (err) {
+        output = typeof err.stdout === "string" ? err.stdout : "";
+    }
+
+    if (!output || output.trim() === "") {
+        return null;
+    }
+
+    const data = parseJsonSafe(output);
+    if (!data || typeof data !== "object") {
+        return null;
+    }
+
+    const deps = data.dependencies;
+    if (!deps || typeof deps !== "object") {
+        return {};
+    }
+
+    return deps;
+}
+
+function cloneBranchAgentDir(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(), "ag-kit-"));
+    const logFn = options && options.logger ? options.logger : console.log;
+
+    if (!options.quiet) logFn(`[download] 正在从 ${REPO_URL} 拉取分支 ${safeBranch} ...`);
+
+    try {
+        execSync(`git clone --depth 1 --branch ${safeBranch} ${REPO_URL} "${tempDir}"`, {
+            stdio: options.quiet ? "ignore" : "pipe",
+        });
+    } catch (err) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        throw new Error(`无法拉取分支 ${safeBranch}，请确认分支存在且网络可用`);
+    }
+
+    const clonedAgentsDir = path.join(tempDir, ".agents");
+    const clonedAgentDir = path.join(tempDir, ".agent");
+    let templateDir = "";
+
+    if (fs.existsSync(clonedAgentsDir)) {
+        templateDir = clonedAgentsDir;
+    } else if (fs.existsSync(clonedAgentDir)) {
+        templateDir = clonedAgentDir;
+    } else {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        throw new Error(`分支 ${safeBranch} 中未找到 .agents 或 .agent 目录`);
+    }
+
+    return {
+        agentDir: templateDir,
+        cleanup: () => fs.rmSync(tempDir, { recursive: true, force: true }),
+    };
+}
+
+module.exports = {
+    parseJsonSafe,
+    readGlobalNpmDependencies,
+    cloneBranchAgentDir
+};

package/docs/PLAN.md

@@ -0,0 +1,54 @@
+# 灵轨规划（PLAN）
+
+## 一句话
+灵轨只做一件事：把仓库内统一的 `.agents/` 模板，优雅地投影到不同平台（Gemini/Antigravity 与 Codex），并提供安全、可回滚的更新机制。
+
+## 设计原则
+- 命令面少而强：用 `sync` 统一“首次安装 + 更新”，避免双心智。
+- 默认安全：不做全局清理、不自动写入高风险全局规则。
+- 模板源单一：仓库 Canonical 为 `.agents/`；旧 `.agent/` 只作为输入兼容，不作为主路径。
+
+## 能力边界（项目 vs 全局）
+### 项目安装（功能最完整）
+- 命令：`ling init` / `ling update` / `ling status` / `ling doctor`
+- 目标输出：
+  - `gemini` -> 项目内 `.agent/`（兼容 Gemini/Antigravity 工作区规范）
+  - `codex` -> 项目内 `.agents/`（受管目录）+ 注入工作区 `AGENTS.md` / `ling.rules` 托管区块
+
+### 全局安装（跨项目复用 Skills）
+- 命令：`ling global sync` / `ling global status`
+- 默认行为：`ling global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini`
+- 目标路径：
+  - `codex` -> `$HOME/.codex/skills/`
+  - `gemini` -> 同时写入 `$HOME/.gemini/skills/` 与 `$HOME/.gemini/antigravity/skills/`
+- 安全边界：全局只同步 Skills，不写入全局 Rules/Agents/Workflows。
+
+## 覆盖与回滚（全局同步）
+- 覆盖单位：每个 Skill 目录。
+- 覆盖策略：只覆盖同名 Skill；不清理用户已有的其他 Skill。
+- 覆盖前备份：每次覆盖同名 Skill 前备份到 `$HOME/.ling/backups/global/<timestamp>/...`。
+
+## Spec Profile（可选进阶层）
+### 当前阶段已落地
+- 命令：`ling spec enable` / `ling spec disable` / `ling spec status`
+- 默认关闭，必须显式启用
+- 当前只开放全局层，不进入项目级注入
+- 目标资源：
+  - Skills：`harness-engineering`、`cybernetic-systems-engineering`
+  - Templates：`$HOME/.ling/spec/templates/`
+  - References：`$HOME/.ling/spec/references/`
+- 回退原则：启用前先备份同名资源；停用时优先恢复原资源
+
+### 后续阶段
+- 项目级 `spec init / remove / doctor`
+- `.spec/profiles/` 的项目投影与可逆注入
+
+## 兼容策略
+- Gemini/Antigravity：输出 `.agent/`，保持与官方工作区机制一致。
+- Codex：受管目录为 `.agents/`，并使用 `manifest.json` 做完整性与漂移检测；识别并迁移遗留 `.codex/`。
+- 全局同步遵循真实消费端目录，而不是仓库模板源目录；仓库内仍以 `.agents/` 作为唯一 Canonical。
+
+## 成功标准
+- `ling global sync` 一条命令即可完成全局 Skills 安装/更新（默认 codex + gemini，其中 gemini 同步到 gemini-cli 与 antigravity）。
+- 覆盖可回滚：每次覆盖同名 Skill 都有可用备份。
+- 跨平台 CI（Linux/macOS/Windows）验证主链路通过。

package/docs/TECH.md

@@ -0,0 +1,191 @@
+# 灵轨技术说明（TECH）
+
+## 快速验证（维护者）
+```bash
+bun install
+bun run test
+bun run ci:verify
+bun run health-check
+cd web && bun install && bun run lint
+```
+
+## 核心目录与职责
+- `.agents/`：仓库模板源（Canonical）
+- `bin/ling.js`：CLI 入口与命令分发
+- `bin/adapters/`：目标差异（`gemini` / `codex`）
+- `bin/core/`：构建/转换（将 Workflows 投影为 Codex Skills 等）
+- `bin/utils/`：原子写入、manifest、托管区块等通用能力
+
+## 路径映射（最重要）
+### 项目级（功能最完整）
+- `gemini`：项目根目录 `.agent/`
+- `codex`：项目根目录 `.agents/`（受管）+ `.agents-backup/`（漂移覆盖备份）
+
+### 全局级（仅同步 Skills）
+- `codex`：`$HOME/.codex/skills/`
+- `gemini-cli`：`$HOME/.gemini/skills/`
+- `antigravity`：`$HOME/.gemini/antigravity/skills/`
+
+> 说明：仓库内 Skills 源路径为 `.agents/skills/`，全局同步会将其投影到真实工具读取的全局目录；仓库 Canonical 仍是 `.agents/`。
+
+## 端到端链路（简述）
+### 项目安装 / 更新
+- `init`：选择目标 -> 适配器 `install()` -> 落盘目标目录（Gemini: `.agent/`；Codex: `.agents/`）->（Codex）注入托管区块到工作区 `AGENTS.md` 与 `ling.rules`
+- `update`：自动检测已安装目标（或通过 `--target/--targets` 指定）-> 适配器 `update()` ->（Codex）漂移检测与备份 -> 原子替换
+- `doctor`：检查完整性；`--fix` 尝试修复（Codex 支持迁移 `.codex/` 与重写托管区块）
+
+### Codex 构建（Workflow -> Skill）
+- 输入：`.agents/skills/` 与 `.agents/workflows/`
+- 规则：每个 Workflow `<name>.md` 会转换为一个 Skill：`workflow-<name>/SKILL.md`
+- 输出（受管目录 `.agents/` 内）：`skills/`、`codex.json`、`AGENTS.md`、`ling.rules`、`manifest.json`
+
+## 全局同步：`ling global sync/status`
+### 默认目标
+- 未指定 `--target/--targets`：默认同步 `codex + gemini`
+- `--target gemini` / `--targets codex,gemini` 中的 `gemini` 会同时写入 gemini-cli 与 antigravity 两个消费端目录
+
+### 来源与覆盖策略
+- 来源：默认使用本包内置 `.agents/`；也可用 `--branch <name>` 从远端分支拉取模板源
+- 覆盖单位：每个 Skill 目录
+- 覆盖策略：只覆盖同名 Skill，不清理其他 Skill
+- 原子替换：按 Skill 目录原子替换，避免半写状态
+- 覆盖前备份：覆盖同名 Skill 前备份到 `$HOME/.ling/backups/global/<timestamp>/<consumer>/<skill>/...`
+  - `consumer` 可能是 `codex`、`gemini-cli`、`antigravity`
+
+### 测试隔离
+- `LING_GLOBAL_ROOT`：替代 `$HOME`（用于测试与 CI，避免污染真实用户目录）
+
+## Spec Profile：`ling spec enable/disable/status`
+### 当前范围
+- 当前只实现全局层：
+  - `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/`
+
+### 落盘与状态
+- Spec 状态文件：`$HOME/.ling/spec/state.json`
+- Spec templates：`$HOME/.ling/spec/templates/`
+- Spec references：`$HOME/.ling/spec/references/`
+- Spec 备份目录：`$HOME/.ling/backups/spec/<timestamp>/before/...`
+
+### 当前安装内容
+- 全局 Skills：
+  - `harness-engineering`
+  - `cybernetic-systems-engineering`
+- Templates：
+  - `issues.template.csv`
+  - `driver-prompt.md`
+  - `review-report.md`
+  - `phase-acceptance.md`
+  - `handoff.md`
+- References：
+  - `harness-engineering-digest.md`
+  - `gda-framework.md`
+  - 相关 quickstart / README
+
+### 状态契约
+- `ling spec status --quiet` 输出：
+  - `installed`
+  - `broken`
+  - `missing`
+- 退出码沿用统一约定：
+  - `0` = `installed`
+  - `1` = `broken`
+  - `2` = `missing`
+
+### 回退语义
+- `spec enable`：
+  - 若目标位置已存在同名 Skill，会先备份再覆盖
+  - 若 `templates/` 或 `references/` 已存在，也会先备份
+- `spec disable`：
+  - 若存在备份，恢复启用前快照
+  - 若启用前不存在资源，则删除由 Spec 安装的目录
+- 当前尚未实现项目级 `spec init / remove / doctor`
+
+## 状态契约（自动化）
+- `ling status --quiet` / `ling global status --quiet` 只输出三态：
+  - `installed`：检测到目标且完整性正常
+  - `broken`：检测到目标但存在残缺、漂移或结构异常
+  - `missing`：未检测到任何已安装目标
+- 退出码固定为：
+  - `0` = `installed`
+  - `1` = `broken`
+  - `2` = `missing`
+- 若需要问题明细，使用 `ling doctor`；`status` 负责健康状态，`doctor` 负责诊断细节。
+
+## 手动回滚（全局 Skills）
+1. 找到备份目录：`$HOME/.ling/backups/global/<timestamp>/...`
+2. 按 Skill 回滚（推荐一次只处理一个 Skill 目录）：
+   - Codex 目标：恢复到 `$HOME/.codex/skills/<skill>/`
+   - Gemini CLI：恢复到 `$HOME/.gemini/skills/<skill>/`
+   - Antigravity：恢复到 `$HOME/.gemini/antigravity/skills/<skill>/`
+
+macOS / Linux 示例（把某个 Skill 回滚为备份版本）：
+```bash
+ts="2026-03-12T12-00-00-000Z"
+skill="clean-code"
+rm -rf "$HOME/.codex/skills/$skill"
+cp -a "$HOME/.ling/backups/global/$ts/codex/$skill" "$HOME/.codex/skills/$skill"
+```
+
+Windows PowerShell 示例：
+```powershell
+$ts = "2026-03-12T12-00-00-000Z"
+$skill = "clean-code"
+Remove-Item "$HOME\\.codex\\skills\\$skill" -Recurse -Force -ErrorAction SilentlyContinue
+Copy-Item "$HOME\\.ling\\backups\\global\\$ts\\codex\\$skill" "$HOME\\.codex\\skills\\$skill" -Recurse -Force
+```
+
+Gemini CLI 回滚示例：
+```bash
+ts="2026-03-12T12-00-00-000Z"
+skill="clean-code"
+rm -rf "$HOME/.gemini/skills/$skill"
+cp -a "$HOME/.ling/backups/global/$ts/gemini-cli/$skill" "$HOME/.gemini/skills/$skill"
+```
+
+Antigravity 回滚示例：
+```bash
+ts="2026-03-12T12-00-00-000Z"
+skill="clean-code"
+rm -rf "$HOME/.gemini/antigravity/skills/$skill"
+cp -a "$HOME/.ling/backups/global/$ts/antigravity/$skill" "$HOME/.gemini/antigravity/skills/$skill"
+```
+
+## 环境变量
+- `LING_INDEX_PATH`：工作区索引文件路径（默认 `~/.ling/workspaces.json`）
+- `LING_GLOBAL_ROOT`：全局目录根（替代 `$HOME`）
+- `LING_SKIP_UPSTREAM_CHECK`：跳过上游同名包安装提示（测试用）
+
+## 安装提示机制
+- npm 全局安装：`postinstall` 会尽力检测并提示上游英文版 `@vudovn/ag-kit` 冲突。
+- Bun 全局安装：Bun 默认会阻止本包 `postinstall`；因此冲突提示以内置 CLI 运行期检查为准，会在 `init` / `update` / `update-all` / `global sync` 时提示。
+- 冲突提示只负责提醒，不会自动修改当前安装状态；如需清理可执行 `npm uninstall -g @vudovn/ag-kit`。
+
+## 常见故障
+- 更新中断：原子替换保证不会出现半写状态；重新运行 `update`/`global sync` 即可。
+- Windows `EPERM/EBUSY`：通常是目录被占用；关闭占用 `.agents/` 或目标 Skill 目录的进程后重试。
+- 漂移覆盖：Codex 若检测到用户修改受管文件，会在覆盖前写入 `.agents-backup/<timestamp>/`。
+
+## 跨平台与文本编码约束
+- 编码与换行：仓库内分发的文本与模板资源使用 UTF-8 与 LF（避免 CRLF 引发的解析与 diff 噪声）。
+- 终端可读性：模板文本与脚本输出避免使用 Emoji 或装饰性 Unicode 字符，统一采用纯 ASCII 标记（例如 `[OK]`、`[FAIL]`），以提升 Windows/WSL/Linux/macOS 终端与编辑器的显示一致性。
+- Web 文档站快捷键提示：搜索弹窗在 macOS 显示 `Cmd + K`，在其他平台显示 `Ctrl + K`。
+- 安全基线检查：安全扫描脚本会检查 Web 站点的基础安全响应头配置；当前实现位于 `web/next.config.ts`。
+
+## Codex 官方 `.rules`（手动配置）
+灵轨不会自动写入全局 `~/.codex/rules/default.rules`，避免引入不可预期的全局副作用。若你需要启用 Codex 官方命令审批策略（如 `prefix_rule()`），可按需手动创建：
+
+```python
+# default.rules
+load("builtin://rules/rules.star", "prefix_rule")
+
+rules = [
+    prefix_rule(["ls"], action="allow"),
+    prefix_rule(["cat"], action="allow"),
+    prefix_rule(["rg"], action="allow"),
+    prefix_rule(["git", "status"], action="allow"),
+]
+```