@finleywdx/ai-init 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xfp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @finleywdx/ai-init
+
+> AI 工程化工作流初始化器 —— 一条命令，把「spec-kit 规范驱动开发 + 跨会话记忆层 + 质量门禁」铺进你的新项目。
+
+`@finleywdx/ai-init` 提供命令行工具 `ai-init`。在你的新项目（如 Next.js）里运行它，它会：
+
+1. **编排 [spec-kit](https://github.com/github/spec-kit)**：为 5 个主流 AI 编码 agent（Cursor、Claude、Codex、Gemini、Copilot）一次性安装 `/speckit.*` 系列命令，把「规范 → 计划 → 任务 → 实现」的规范驱动开发（SDD）流程带进项目。
+2. **铺设 Finley 增量层**：一套轻量的 `.finley/` 质量门禁 + 记忆脚本（纯 Python 标准库实现，无第三方依赖）。
+3. **写好 AI 助手说明**：在 `AGENTS.md` 里生成一个 Finley 工作流区块，告诉任意 AI 助手该怎么在本项目里干活。
+
+## 它和 spec-kit 是什么关系？
+
+spec-kit 负责**规范驱动开发的主流程**（constitution → specify → plan → tasks → implement）。`ai-init` 不重造这套流程，而是**编排调用** spec-kit 的 `specify` CLI 完成安装，再在其之上补两块 spec-kit 不覆盖的工程纪律：
+
+- **质量门禁（Quality Gate）**：一条 `gate.py`，在提交前统一跑 lint / typecheck / test，强制「写完代码必须过门禁」。
+- **记忆层（Memory）**：一套 `add_session.py` + journal，把「本次会话做了什么」持久化到仓库，让下次会话不必从零理解项目。
+
+> 灵感来自 [Trellis](https://github.com/) 的「规范/任务/记忆搬进仓库」理念，但 Finley 只做最小可用的增量层，把主流程交给 spec-kit。
+
+## 环境要求
+
+运行 `ai-init init` 的机器需要具备（缺失会被检测并阻断，同时打印中文安装指引）：
+
+| 依赖 | 版本 | 用途 |
+| --- | --- | --- |
+| Node.js | ≥ 18 | 运行本 CLI |
+| Git | 任意近版 | 版本控制 / journal 分支探测 |
+| Python | ≥ 3.11 | 运行 `gate.py` / `add_session.py`（需标准库 `tomllib`） |
+| uv | 任意 | spec-kit 的安装与运行依赖 |
+
+此外还需要 spec-kit 的 `specify` CLI。若未安装，`ai-init` 会给出用 uv 安装的指引（替换 `<tag>` 为最新版本，如 `v0.12.4`）：
+
+```bash
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@<tag>
+```
+
+## 安装
+
+在你的项目里作为开发依赖安装：
+
+```bash
+npm i -D @finleywdx/ai-init
+```
+
+或全局安装：
+
+```bash
+npm i -g @finleywdx/ai-init
+```
+
+也可以免安装直接用 npx：
+
+```bash
+npx @finleywdx/ai-init init
+```
+
+## 用法
+
+在**目标项目根目录**运行：
+
+```bash
+ai-init init
+```
+
+它会依次执行：环境检测 → 编排 spec-kit → 铺设 `.finley/` → 合并 `AGENTS.md`。
+
+### 常用选项
+
+```bash
+# 只安装指定的 spec-kit integration（逗号分隔）
+ai-init init --integration cursor,claude
+
+# 跳过 spec-kit 编排，只铺设 Finley 增量层
+ai-init init --skip-speckit
+
+# 只打印将执行的操作，不真正调用 specify、不写盘
+ai-init init --dry-run
+
+# 不向 specify 传 --ignore-agent-tools（默认会传，以免因未装某个 agent CLI 而失败）
+ai-init init --no-ignore-agent-tools
+
+ai-init --version
+ai-init --help
+```
+
+> 关于多 integration：spec-kit 的 `specify init` 每次只接受**单个** `--integration`。`ai-init` 因此采用「首个 integration 用 `specify init .` 初始化，其余用 `specify integration install <name> --force` 逐个追加」的方式一次装齐 5 个 agent。
+
+## 初始化后的目录
+
+```text
+你的项目/
+├── .specify/                       # spec-kit 管理（规格 / 模板 / 记忆）
+├── .cursor/ .claude/ ...           # 各 agent 的 /speckit.* 命令（spec-kit 生成）
+├── .finley/
+│   ├── config.yaml                 # 质量门禁命令映射 + 开发者/journal 配置
+│   ├── scripts/
+│   │   ├── gate.py                 # 质量门禁：lint / typecheck / test
+│   │   └── add_session.py          # 记忆层：写 journal
+│   └── workspace/<开发者>/         # 跨会话记忆 journal（自动生成）
+├── .agents/skills/
+│   ├── finley-quality-gate/SKILL.md
+│   └── finley-memory/SKILL.md
+└── AGENTS.md                       # 含 Finley 工作流区块
+```
+
+## 初始化后的日常工作流
+
+1. **确立原则**：`/speckit.constitution` —— 定义代码质量、测试、UX、性能等治理原则。
+2. **写规格**：`/speckit.specify` —— 描述「做什么 / 为什么」，先别谈技术栈。
+3. **澄清**：`/speckit.clarify` —— 补齐规格里模糊的地方（建议在 plan 之前）。
+4. **定方案**：`/speckit.plan` —— 给出技术栈与架构选择。
+5. **拆任务**：`/speckit.tasks` —— 生成可执行的任务清单。
+6. **一致性检查**：`/speckit.analyze` —— 跨规格/计划/任务做一致性与覆盖度检查（建议在 implement 之前）。
+7. **实现**：`/speckit.implement` —— 按任务清单写代码。
+8. **质量门禁（提交前强制）**：
+   ```bash
+   python .finley/scripts/gate.py
+   ```
+   有红项必须修复后重跑，直至全绿。门禁会读取 `.finley/config.yaml`，占位命令会自动从 `package.json` scripts（前端）与 `pyproject.toml`（后端 ruff/mypy/pytest）探测。
+9. **收尾写 journal（记忆层）**：
+   ```bash
+   python .finley/scripts/add_session.py --title "本次工作标题" --summary "做了什么" --commit "abc1234"
+   ```
+   新会话开场时，主动读取 `.finley/workspace/<开发者>/` 里最近的 journal 恢复上下文。
+
+> Codex CLI 的 skills 模式使用 `$speckit-*`；斜杠命令的确切形态以你所用 agent 平台为准。
+
+## 配置 `.finley/config.yaml`
+
+```yaml
+quality:
+  frontend:
+    lint: "<占位: 前端 lint 命令，如 npm run lint>"
+    typecheck: "<占位: 前端类型检查命令，如 npm run typecheck>"
+    test: "<占位: 前端测试命令，如 npm test>"
+  backend:
+    lint: "<占位: 后端 lint 命令，如 ruff check .>"
+    typecheck: "<占位: 后端类型检查命令，如 mypy .>"
+    test: "<占位: 后端测试命令，如 pytest>"
+developer: ""          # 留空则自动探测（FINLEY_DEVELOPER > git user.name > 系统用户名）
+journal:
+  max_lines: 2000      # journal 超过该行数自动轮转
+```
+
+- 值形如 `<占位: ...>` 时，`gate.py` 会尝试自动探测；你也可以随时替换成项目真实命令。
+- 前端探测：`package.json` 的 `scripts` 里的 `lint` / `typecheck`(或 `type-check`) / `test`，并按锁文件选择 npm / pnpm / yarn / bun。
+- 后端探测：`pyproject.toml` 里检测到 `ruff` → `ruff check .`；`mypy` → `mypy .`；`pytest` → `pytest`。
+
+---
+
+## 发布这个包到 npm（维护者向）
+
+本仓库是 `@finleywdx/ai-init` 的源码。发布步骤：
+
+```bash
+# 1. 安装依赖
+npm install
+
+# 2. 构建（tsup 产物在 dist/；prepublishOnly 会在 publish 前自动 clean + build）
+npm run build
+
+# 3. 本地自检
+node dist/cli.js --version
+node dist/cli.js --help
+
+# 4. 预览将要发布的文件清单
+npm pack --dry-run
+
+# 5. 登录 npm
+npm login
+
+# 6. 发布（scope 包默认私有，公开发布必须加 --access public）
+npm publish --access public
+```
+
+发布内容由 `package.json` 的 `files` 白名单控制，仅包含 `dist/`、`templates/`、`README.md`、`LICENSE`。`bin` 字段把 `ai-init` 指向构建产物 `dist/cli.js`。
+
+### 本地联调
+
+```bash
+npm run build
+npm link              # 在本仓库
+# 到另一个测试项目里：
+npm link @finleywdx/ai-init
+ai-init init --dry-run
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/cli.js

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/utils/fs.ts
+import { fileURLToPath } from "url";
+import path from "path";
+import fs from "fs";
+function templatesDir() {
+  return fileURLToPath(new URL("../templates", import.meta.url));
+}
+function readOwnPackageJson() {
+  const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+  const raw = fs.readFileSync(pkgPath, "utf-8");
+  return JSON.parse(raw);
+}
+function copyDir(srcDir, destDir, destRoot = destDir, result = { created: [], skipped: [] }) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, destRoot, result);
+    } else {
+      const rel = path.relative(destRoot, destPath);
+      if (fs.existsSync(destPath)) {
+        result.skipped.push(rel);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+        result.created.push(rel);
+      }
+    }
+  }
+  return result;
+}
+function readText(filePath) {
+  return fs.readFileSync(filePath, "utf-8");
+}
+function writeText(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+function exists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+// src/utils/exec.ts
+import { execa } from "execa";
+async function commandExists(command) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  try {
+    await execa(probe, [command]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function tryOutput(command, args = []) {
+  try {
+    const { stdout } = await execa(command, args);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+async function run(command, args = [], options = {}) {
+  try {
+    const result = await execa(command, args, { reject: false, ...options });
+    return {
+      ok: result.exitCode === 0,
+      exitCode: result.exitCode,
+      stdout: typeof result.stdout === "string" ? result.stdout : "",
+      stderr: typeof result.stderr === "string" ? result.stderr : ""
+    };
+  } catch (err) {
+    const e = err;
+    return {
+      ok: false,
+      exitCode: e.exitCode,
+      stdout: typeof e.stdout === "string" ? e.stdout : "",
+      stderr: typeof e.stderr === "string" ? e.stderr : e.message ?? String(err)
+    };
+  }
+}
+
+// src/utils/logger.ts
+import pc from "picocolors";
+var log = {
+  info(msg) {
+    console.log(`${pc.cyan("\u203A")} ${msg}`);
+  },
+  step(msg) {
+    console.log(`
+${pc.bold(pc.cyan("\u25B6"))} ${pc.bold(msg)}`);
+  },
+  success(msg) {
+    console.log(`${pc.green("\u2714")} ${msg}`);
+  },
+  warn(msg) {
+    console.warn(`${pc.yellow("\u26A0")} ${msg}`);
+  },
+  error(msg) {
+    console.error(`${pc.red("\u2717")} ${msg}`);
+  },
+  detail(msg) {
+    console.log(`  ${pc.dim(msg)}`);
+  },
+  title(msg) {
+    console.log(pc.bold(pc.magenta(msg)));
+  }
+};
+
+// src/steps/check-env.ts
+import pc2 from "picocolors";
+function parseMajor(version) {
+  if (!version) return null;
+  const m = version.match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  return m ? Number(m[1]) : null;
+}
+function parseMinor(version) {
+  if (!version) return null;
+  const m = version.match(/(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2])] : null;
+}
+async function checkNode() {
+  const major = parseMajor(process.version);
+  const ok = major !== null && major >= 18;
+  return {
+    ok,
+    label: "Node.js \u2265 18",
+    detail: process.version,
+    hint: "\u8BF7\u5B89\u88C5 Node.js 18 \u6216\u66F4\u9AD8\u7248\u672C\uFF1Ahttps://nodejs.org/ \uFF08\u63A8\u8350\u7528 nvm/fnm \u7BA1\u7406\u7248\u672C\uFF09\u3002"
+  };
+}
+async function checkGit() {
+  const has = await commandExists("git");
+  const ver = has ? await tryOutput("git", ["--version"]) : null;
+  return {
+    ok: has,
+    label: "Git",
+    detail: ver ?? "\u672A\u5B89\u88C5",
+    hint: "\u8BF7\u5B89\u88C5 Git\uFF1Ahttps://git-scm.com/downloads"
+  };
+}
+async function checkPython() {
+  const bin = await commandExists("python3") ? "python3" : await commandExists("python") ? "python" : null;
+  const ver = bin ? await tryOutput(bin, ["--version"]) : null;
+  const mm = parseMinor(ver);
+  const ok = mm !== null && (mm[0] > 3 || mm[0] === 3 && mm[1] >= 11);
+  return {
+    ok,
+    label: "Python \u2265 3.11",
+    detail: ver ?? "\u672A\u5B89\u88C5",
+    hint: "\u8BF7\u5B89\u88C5 Python 3.11 \u6216\u66F4\u9AD8\u7248\u672C\uFF1Ahttps://www.python.org/downloads/ \u3002\n    \u95E8\u7981\u4E0E\u8BB0\u5FC6\u811A\u672C\u7528\u7EAF\u6807\u51C6\u5E93\uFF08tomllib\uFF09\u5B9E\u73B0\uFF0C\u9700 3.11+\u3002"
+  };
+}
+async function checkUv() {
+  const has = await commandExists("uv");
+  const ver = has ? await tryOutput("uv", ["--version"]) : null;
+  return {
+    ok: has,
+    label: "uv\uFF08spec-kit \u4F9D\u8D56\uFF09",
+    detail: ver ?? "\u672A\u5B89\u88C5",
+    hint: "spec-kit \u901A\u8FC7 uv \u5B89\u88C5\u4E0E\u8FD0\u884C\u3002\u8BF7\u5B89\u88C5 uv\uFF1A\n    macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh\n    \u6216\u89C1 https://docs.astral.sh/uv/"
+  };
+}
+async function checkSpecify() {
+  const available = await commandExists("specify");
+  const version = available ? await tryOutput("specify", ["--version"]) : null;
+  return { available, version };
+}
+async function checkEnv() {
+  log.step("\u6B65\u9AA4 1/4\uFF1A\u73AF\u5883\u68C0\u6D4B");
+  const checks = await Promise.all([
+    checkNode(),
+    checkGit(),
+    checkPython(),
+    checkUv()
+  ]);
+  for (const c of checks) {
+    if (c.ok) {
+      log.success(`${c.label} \u2014 ${pc2.dim(c.detail)}`);
+    } else {
+      log.error(`${c.label} \u2014 ${pc2.dim(c.detail)}`);
+    }
+  }
+  const failed = checks.filter((c) => !c.ok);
+  if (failed.length > 0) {
+    console.log();
+    log.error(`\u73AF\u5883\u68C0\u6D4B\u672A\u901A\u8FC7\uFF1A\u7F3A\u5C11 ${failed.length} \u9879\u5FC5\u9700\u4F9D\u8D56\u3002`);
+    console.log(pc2.bold("\n\u8BF7\u5148\u5B89\u88C5\u4EE5\u4E0B\u4F9D\u8D56\u540E\u91CD\u8BD5\uFF1A\n"));
+    for (const c of failed) {
+      console.log(`${pc2.red("\u2022")} ${pc2.bold(c.label)}`);
+      console.log(`    ${c.hint}
+`);
+    }
+    return false;
+  }
+  const specify = await checkSpecify();
+  if (specify.available) {
+    log.success(`specify CLI \u2014 ${pc2.dim(specify.version ?? "\u5DF2\u5B89\u88C5")}`);
+  } else {
+    log.warn("\u672A\u68C0\u6D4B\u5230 spec-kit \u7684 specify CLI\u3002");
+    console.log(
+      pc2.dim(
+        "    \u53EF\u7528 uv \u5B89\u88C5\uFF08\u66FF\u6362 <tag> \u4E3A\u6700\u65B0\u7248\u672C\uFF0C\u5982 v0.12.4\uFF09\uFF1A\n    uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@<tag>\n    \u5B89\u88C5\u540E\u91CD\u8DD1 ai-init init \u5373\u53EF\u81EA\u52A8\u7F16\u6392 spec-kit\u3002"
+      )
+    );
+  }
+  return true;
+}
+
+// src/steps/run-speckit.ts
+import pc3 from "picocolors";
+var DEFAULT_INTEGRATIONS = [
+  "cursor",
+  "claude",
+  "codex",
+  "gemini",
+  "copilot"
+];
+async function runSpeckit(options) {
+  const {
+    cwd,
+    integrations = DEFAULT_INTEGRATIONS,
+    ignoreAgentTools = true,
+    dryRun = false
+  } = options;
+  log.step("\u6B65\u9AA4 2/4\uFF1A\u7F16\u6392 spec-kit");
+  const list = [...integrations];
+  if (list.length === 0) {
+    log.warn("\u672A\u6307\u5B9A\u4EFB\u4F55 integration\uFF0C\u8DF3\u8FC7 spec-kit \u7F16\u6392\u3002");
+    return { ok: true, installed: [], failed: [], skipped: true };
+  }
+  const specify = await checkSpecify();
+  if (!specify.available && !dryRun) {
+    log.error("\u672A\u627E\u5230 specify CLI\uFF0C\u65E0\u6CD5\u7F16\u6392 spec-kit\u3002");
+    console.log(
+      pc3.dim(
+        "    \u8BF7\u5148\u5B89\u88C5 spec-kit\uFF08\u66FF\u6362 <tag> \u4E3A\u6700\u65B0\u7248\u672C\uFF0C\u5982 v0.12.4\uFF09\uFF1A\n    uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@<tag>\n    \u5B89\u88C5\u540E\u91CD\u8DD1 ai-init init\u3002\u672C\u6B21\u5C06\u8DF3\u8FC7 spec-kit\uFF0C\u4EC5\u94FA\u8BBE Finley \u589E\u91CF\u5C42\u3002"
+      )
+    );
+    return { ok: false, installed: [], failed: [...list], skipped: true };
+  }
+  const installed = [];
+  const failed = [];
+  const [first, ...rest] = list;
+  const initArgs = ["init", ".", "--integration", first, "--force"];
+  if (ignoreAgentTools) initArgs.push("--ignore-agent-tools");
+  log.info(`\u521D\u59CB\u5316 spec-kit\uFF08\u9996\u4E2A integration\uFF09\uFF1A${pc3.bold(first)}`);
+  log.detail(`$ specify ${initArgs.join(" ")}`);
+  if (dryRun) {
+    installed.push(first);
+  } else {
+    const res = await run("specify", initArgs, { cwd, stdio: "inherit" });
+    if (res.ok) {
+      log.success(`spec-kit \u5DF2\u521D\u59CB\u5316\u5E76\u5B89\u88C5 integration\uFF1A${first}`);
+      installed.push(first);
+    } else {
+      log.error(`specify init \u5931\u8D25\uFF08integration=${first}\uFF0C\u9000\u51FA\u7801 ${res.exitCode ?? "?"}\uFF09\u3002`);
+      if (res.stderr) log.detail(res.stderr.split("\n").slice(0, 8).join("\n"));
+      failed.push(first);
+      return { ok: false, installed, failed: [...list], skipped: false };
+    }
+  }
+  for (const name of rest) {
+    const args = ["integration", "install", name, "--force"];
+    log.info(`\u8FFD\u52A0 integration\uFF1A${pc3.bold(name)}`);
+    log.detail(`$ specify ${args.join(" ")}`);
+    if (dryRun) {
+      installed.push(name);
+      continue;
+    }
+    const res = await run("specify", args, { cwd, stdio: "inherit" });
+    if (res.ok) {
+      log.success(`\u5DF2\u5B89\u88C5 integration\uFF1A${name}`);
+      installed.push(name);
+    } else {
+      log.warn(`integration \u5B89\u88C5\u5931\u8D25\uFF1A${name}\uFF08\u9000\u51FA\u7801 ${res.exitCode ?? "?"}\uFF09\uFF0C\u7EE7\u7EED\u5176\u4F59\u9879\u3002`);
+      if (res.stderr) log.detail(res.stderr.split("\n").slice(0, 6).join("\n"));
+      failed.push(name);
+    }
+  }
+  const ok = failed.length === 0;
+  if (ok) {
+    log.success(`spec-kit \u7F16\u6392\u5B8C\u6210\uFF0C\u5DF2\u5B89\u88C5 integration\uFF1A${installed.join(", ")}`);
+  } else {
+    log.warn(
+      `spec-kit \u7F16\u6392\u90E8\u5206\u5B8C\u6210\u3002\u6210\u529F\uFF1A${installed.join(", ") || "\u65E0"}\uFF1B\u5931\u8D25\uFF1A${failed.join(", ")}\u3002`
+    );
+  }
+  return { ok, installed, failed, skipped: false };
+}
+
+// src/steps/scaffold-finley.ts
+import path2 from "path";
+import pc4 from "picocolors";
+var MARKER_START = "<!-- FINLEY:START -->";
+var MARKER_END = "<!-- FINLEY:END -->";
+function scaffoldFinley(options) {
+  const { cwd } = options;
+  const tpl = templatesDir();
+  log.step("\u6B65\u9AA4 3/4\uFF1A\u94FA\u8BBE Finley \u589E\u91CF\u5C42");
+  const finleyResult = copyDir(path2.join(tpl, "finley"), path2.join(cwd, ".finley"), cwd);
+  const skillsResult = copyDir(
+    path2.join(tpl, "agents-skills"),
+    path2.join(cwd, ".agents", "skills"),
+    cwd
+  );
+  const created = [...finleyResult.created, ...skillsResult.created];
+  const skipped = [...finleyResult.skipped, ...skillsResult.skipped];
+  for (const f of created) log.success(`\u521B\u5EFA ${f}`);
+  for (const f of skipped) log.detail(`\u5DF2\u5B58\u5728\uFF0C\u8DF3\u8FC7 ${pc4.dim(f)}`);
+  mergeAgentsMd(cwd, tpl);
+}
+function mergeAgentsMd(cwd, tpl) {
+  const agentsPath = path2.join(cwd, "AGENTS.md");
+  const section = readText(path2.join(tpl, "AGENTS.section.md")).trim();
+  log.step("\u6B65\u9AA4 4/4\uFF1A\u5408\u5E76 AGENTS.md");
+  if (!exists(agentsPath)) {
+    writeText(agentsPath, section + "\n");
+    log.success("\u521B\u5EFA AGENTS.md \u5E76\u5199\u5165 Finley \u533A\u5757\u3002");
+    return;
+  }
+  const original = readText(agentsPath);
+  const startIdx = original.indexOf(MARKER_START);
+  const endIdx = original.indexOf(MARKER_END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = original.slice(0, startIdx);
+    const after = original.slice(endIdx + MARKER_END.length);
+    const updated = `${before}${section}${after}`;
+    if (updated === original) {
+      log.detail("AGENTS.md \u7684 Finley \u533A\u5757\u5DF2\u662F\u6700\u65B0\uFF0C\u65E0\u9700\u6539\u52A8\u3002");
+    } else {
+      writeText(agentsPath, updated);
+      log.success("\u66F4\u65B0 AGENTS.md \u4E2D\u5DF2\u6709\u7684 Finley \u533A\u5757\u3002");
+    }
+    return;
+  }
+  const sep = original.endsWith("\n") ? "\n" : "\n\n";
+  writeText(agentsPath, original + sep + section + "\n");
+  log.success("\u5728\u5DF2\u6709 AGENTS.md \u672B\u5C3E\u8FFD\u52A0 Finley \u533A\u5757\u3002");
+}
+
+// src/commands/init.ts
+import pc5 from "picocolors";
+async function init(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const integrations = options.integrations?.length ? options.integrations : [...DEFAULT_INTEGRATIONS];
+  log.title("\n\u{1F331} Finley \xB7 AI \u5DE5\u7A0B\u5316\u5DE5\u4F5C\u6D41\u521D\u59CB\u5316\u5668\n");
+  log.info(`\u76EE\u6807\u76EE\u5F55\uFF1A${pc5.bold(cwd)}`);
+  if (options.dryRun) log.warn("dry-run \u6A21\u5F0F\uFF1A\u4E0D\u4F1A\u771F\u6B63\u8C03\u7528 specify\uFF0C\u4E5F\u4E0D\u4F1A\u6C61\u67D3\u76EE\u5F55\u3002");
+  const envOk = await checkEnv();
+  if (!envOk) {
+    log.error("\n\u521D\u59CB\u5316\u5DF2\u4E2D\u6B62\uFF1A\u8BF7\u5B89\u88C5\u4E0A\u9762\u5217\u51FA\u7684\u4F9D\u8D56\u540E\u91CD\u8BD5\u3002");
+    return 1;
+  }
+  let speckitSkipped = false;
+  if (options.skipSpeckit) {
+    log.step("\u6B65\u9AA4 2/4\uFF1A\u7F16\u6392 spec-kit");
+    log.warn("\u5DF2\u901A\u8FC7 --skip-speckit \u8DF3\u8FC7 spec-kit \u7F16\u6392\u3002");
+    speckitSkipped = true;
+  } else {
+    const res = await runSpeckit({
+      cwd,
+      integrations,
+      ignoreAgentTools: options.ignoreAgentTools ?? true,
+      dryRun: options.dryRun
+    });
+    speckitSkipped = res.skipped;
+  }
+  if (options.dryRun) {
+    log.step("\u6B65\u9AA4 3/4\uFF1A\u94FA\u8BBE Finley \u589E\u91CF\u5C42");
+    log.warn("dry-run\uFF1A\u8DF3\u8FC7\u590D\u5236\u6A21\u677F\u3002");
+    log.step("\u6B65\u9AA4 4/4\uFF1A\u5408\u5E76 AGENTS.md");
+    log.warn("dry-run\uFF1A\u8DF3\u8FC7\u5199\u5165 AGENTS.md\u3002");
+  } else {
+    scaffoldFinley({ cwd });
+  }
+  console.log();
+  log.title("\u2705 \u521D\u59CB\u5316\u5B8C\u6210");
+  printNextSteps(speckitSkipped);
+  return 0;
+}
+function printNextSteps(speckitSkipped) {
+  console.log(pc5.bold("\n\u63A5\u4E0B\u6765\uFF1A"));
+  const lines = [];
+  if (speckitSkipped) {
+    lines.push(
+      "\u5148\u5B89\u88C5 spec-kit \u540E\u91CD\u8DD1\u4EE5\u8865\u5168\u547D\u4EE4\uFF1A",
+      "  uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@<tag>"
+    );
+  }
+  lines.push(
+    "\u7F16\u8F91 .finley/config.yaml\uFF0C\u628A quality \u91CC\u7684\u5360\u4F4D\u66FF\u6362\u6210\u9879\u76EE\u771F\u5B9E\u547D\u4EE4\uFF08\u4E5F\u53EF\u7559\u7ED9 gate.py \u81EA\u52A8\u63A2\u6D4B\uFF09\u3002",
+    "\u5728 AI \u52A9\u624B\u91CC\u6309 spec-kit \u6D41\u7A0B\u63A8\u8FDB\uFF1A",
+    "  /speckit.constitution \u2192 /speckit.specify \u2192 /speckit.clarify \u2192 /speckit.plan \u2192",
+    "  /speckit.tasks \u2192 /speckit.analyze \u2192 /speckit.implement",
+    "\u5B9E\u73B0\u5B8C\u6210\u3001\u63D0\u4EA4\u524D\u5FC5\u987B\u8DD1\u8D28\u91CF\u95E8\u7981\uFF1A",
+    "  python .finley/scripts/gate.py",
+    "\u4E00\u6BB5\u5DE5\u4F5C\u6536\u5C3E\u65F6\u8BB0\u5F55 journal\uFF1A",
+    '  python .finley/scripts/add_session.py --title "..." --summary "..."'
+  );
+  for (const l of lines) console.log(`  ${pc5.cyan("\u203A")} ${l}`);
+  console.log(pc5.dim("\n\u8BE6\u89C1\u9879\u76EE\u6839\u76EE\u5F55\u7684 AGENTS.md \u4E0E .agents/skills/\u3002"));
+}
+
+// src/cli.ts
+function main() {
+  const pkg = readOwnPackageJson();
+  const program = new Command();
+  program.name("ai-init").description(
+    "AI \u5DE5\u7A0B\u5316\u5DE5\u4F5C\u6D41\u521D\u59CB\u5316\u5668\uFF1A\u628A spec-kit \u5DE5\u4F5C\u6D41 + \u8BB0\u5FC6\u5C42 + \u8D28\u91CF\u95E8\u7981\u521D\u59CB\u5316\u8FDB\u4F60\u7684\u9879\u76EE\u3002"
+  ).version(pkg.version, "-v, --version", "\u8F93\u51FA\u7248\u672C\u53F7");
+  program.command("init").description("\u5728\u5F53\u524D\u76EE\u5F55\u521D\u59CB\u5316 Finley \u5DE5\u4F5C\u6D41\uFF08\u7F16\u6392 spec-kit + \u94FA\u8BBE\u589E\u91CF\u5C42 + \u5408\u5E76 AGENTS.md\uFF09").option(
+    "-i, --integration <names>",
+    "\u4EE5\u9017\u53F7\u5206\u9694\u6307\u5B9A\u8981\u5B89\u88C5\u7684 spec-kit integration\uFF08\u9ED8\u8BA4 cursor,claude,codex,gemini,copilot\uFF09"
+  ).option("--skip-speckit", "\u8DF3\u8FC7 spec-kit \u7F16\u6392\uFF0C\u4EC5\u94FA\u8BBE Finley \u589E\u91CF\u5C42").option("--no-ignore-agent-tools", "\u4E0D\u5411 specify \u4F20 --ignore-agent-tools\uFF08\u9ED8\u8BA4\u4F1A\u4F20\uFF09").option("--dry-run", "\u53EA\u6253\u5370\u5C06\u6267\u884C\u7684\u64CD\u4F5C\uFF0C\u4E0D\u771F\u6B63\u8C03\u7528 specify\u3001\u4E0D\u5199\u76D8").action(async (opts) => {
+    const integrations = typeof opts.integration === "string" ? opts.integration.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+    try {
+      const code = await init({
+        integrations,
+        skipSpeckit: opts.skipSpeckit,
+        // commander 的 --no-ignore-agent-tools 会把 ignoreAgentTools 置为 false
+        ignoreAgentTools: opts.ignoreAgentTools,
+        dryRun: opts.dryRun
+      });
+      process.exit(code);
+    } catch (err) {
+      log.error(`\u521D\u59CB\u5316\u8FC7\u7A0B\u4E2D\u53D1\u751F\u672A\u9884\u671F\u9519\u8BEF\uFF1A${err.message}`);
+      process.exit(1);
+    }
+  });
+  program.parse(process.argv);
+}
+main();