feat: v0.3 零侵入架构 + lingshu upgrade

CHANGELOG.md

@@ -0,0 +1,102 @@
+# 更新日志 (Changelog)
+
+本项目的所有显著变更都记录于此。
+
+格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.3.0] - 2026-05-31
+
+> **主题：零侵入 (Zero-Intrusion)** —— CLI 即唯一引擎，派生仓只保留治理资产。
+
+### ⚠️ BREAKING CHANGES
+
+- **派生仓不再携带 `.lingshu/` 目录与 `package.json`**。同步引擎完全内置于 CLI，
+  仓库只保留 `reference/` 治理资产与 AI 工具产物。
+- **同步统一走 `lingshu sync`**，不再有 `npm run sync`。团队每位成员需各自
+  `npm install -g @ruobai/lingshu` 一次；CI 改用 `npx -y @ruobai/lingshu`。
+- **`tool` 命令重设计**：`baseline`/`personal` → `track`/`untrack`，直接编辑
+  `.gitignore`（`.gitignore` 成为「入库 vs 忽略」的唯一真相）。
+
+### Added
+
+- **内置 adapter 注册表**（`src/core/registry.mjs`）：6 大工具开箱即用，零配置。
+- **`lingshu upgrade`**：将存量项目迁移到零侵入结构。
+  - v0.2.x → v0.3：删 `.lingshu/`、删/瘦身 `package.json`、把 cursor frontmatter
+    迁入 `reference/rules/*.md`、改造 CI、重装 hooks、重生成基线产物。
+  - 灵枢 1.0（无 `reference/rules/` 真源）：检测并给出手动迁移指引，不做有损迁移。
+  - 支持 `--dry-run` 预览、`--force`。
+- **`lingshu hooks install`**：为存量项目补装内置 git hooks。
+- **零配置逃生舱**：可选 `reference/.lingshu.json` 声明自定义适配器 / 覆盖基线。
+- **规则文件自带 frontmatter**：`reference/rules/*.md` 通过 `order` 控制合并顺序，
+  cursor 的 `.mdc` frontmatter 直接读自规则文件本身。
+
+### Changed
+
+- 同步引擎（`src/core/adapters.mjs`）从「读项目内 `.lingshu/config/adapters.mjs`」
+  改为「读内置注册表 + 约定发现 `reference/rules/*.md`」。
+- `init` 不再写入 `package.json` / `adapters.mjs`；git hooks 改为 CLI 内联写入
+  `.git/hooks/`（不再依赖 `postinstall`）。
+- 模板瘦身：移除 `templates/default/` 内的 `.lingshu/`、`package.json` 及预置
+  `CLAUDE.md`/`AGENTS.md`（改为 `init` 时生成）。
+- 生成产物头部与规则真源中对旧引擎（`.lingshu/scripts` / `npm run sync`）的引用
+  统一更新为 `lingshu sync`。
+- smoke 测试扩充至 17 项，覆盖零侵入契约、`tool track/untrack`、`upgrade` 全路径。
+
+## [0.2.6] - 2026-05-08
+
+### Fixed
+
+- `limb add/init/adopt` 成功后自动维护 `.gitignore`：非约定命名追加 `<name>/`，
+  约定命名（被 `*-server/` 等通配覆盖）幂等跳过。
+
+## [0.2.5] - 2026-05-08
+
+### Fixed
+
+- 修复派生项目缺失 `.gitignore`：npm publish 会把 `.gitignore` 当 `.npmignore`
+  并自身排除。模板内改名为 `_gitignore`，`init` 时复原为 `.gitignore`。
+
+## [0.2.4] - 2026-05-08
+
+### Added
+
+- `sync` 默认 auto 模式：仅同步 baseline + 已存在产物的 personal 工具。
+- `limb init`（创建空肢体 + git init）与 `limb adopt`（纳入已有本地目录）。
+
+## [0.2.3] - 2026-05-08
+
+### Changed
+
+- `init` 默认仅生成基线产物（baseline-only），新增 `--all-tools`。
+- `init` 注入项目身份至 `package.json` 的 `description`。
+
+## [0.2.2] - 2026-05-08
+
+### Fixed
+
+- 修复致命 bug：`copyTemplate` 用绝对路径匹配 `node_modules`，导致全局安装时
+  整个模板树被误过滤为空。改为只看相对模板根的路径。
+
+## [0.2.1] - 2026-05-08
+
+### Changed
+
+- 文档清理：去除 SyncBase 双品牌、夸大词与 🌀 图标。
+
+## [0.2.0] - 2026-05-08
+
+### Added
+
+- 首次开源发布：GitHub + npm 公网 + MIT 协议。
+- 核心命令 `init` / `sync` / `doctor` / `tool` / `limb`。
+- 包名 `@ruobai/lingshu`（若白知行 npm scope）。
+
+[0.3.0]: https://github.com/imrui/lingshu-cli/compare/v0.2.6...v0.3.0
+[0.2.6]: https://github.com/imrui/lingshu-cli/compare/v0.2.5...v0.2.6
+[0.2.5]: https://github.com/imrui/lingshu-cli/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/imrui/lingshu-cli/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/imrui/lingshu-cli/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/imrui/lingshu-cli/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/imrui/lingshu-cli/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/imrui/lingshu-cli/releases/tag/v0.2.0

README.md

@@ -9,6 +9,8 @@
 
 `@ruobai/lingshu` 是 [灵枢架构 (LingShu)](https://github.com/imrui/lingshu-template) 的官方命令行工具，把 7 步手动流程压缩为 1 条命令。
 
+> **v0.3 零侵入**：同步引擎完全内置于本 CLI，派生仓**不再携带** `.lingshu/` 目录与 `package.json`——只保留 `reference/` 治理资产与 AI 工具产物。存量项目可用 `lingshu upgrade` 一键迁移。
+
 ---
 
 ## 1 分钟上手
@@ -34,9 +36,11 @@ npm install -g @ruobai/lingshu
 npm install -g git+ssh://git@github.com/imrui/lingshu-cli.git
 
 # 锁定版本
-npm install -g git+ssh://git@github.com/imrui/lingshu-cli.git#v0.2.6
+npm install -g git+ssh://git@github.com/imrui/lingshu-cli.git#v0.3.0
 ```
 
+> 团队协作提示：v0.3 起派生仓不含 `package.json`，同步统一走全局 `lingshu sync`。**团队每位成员各全局安装一次**即可；CI 用 `npx -y @ruobai/lingshu` 临时调用。
+
 ## 创建新项目
 
 ```bash
@@ -48,7 +52,7 @@ lingshu init my-lingshu-app \
 
 > 把 `your-org` 替换为你的 GitHub 组织或用户名。
 
-一条命令完成：拷贝模板 → 注入项目身份 → 配置 AI 工具基线 → 生成 `CLAUDE.md / AGENTS.md` → `git init` 与 remote → 安装 git hooks → 克隆肢体仓。
+一条命令完成：拷贝模板 → 注入项目身份 → 生成 `CLAUDE.md / AGENTS.md` → `git init` 与 remote → 安装 git hooks（内置写入 `.git/hooks/`）→ 克隆肢体仓。
 
 ---
 
@@ -61,7 +65,7 @@ lingshu init my-lingshu-app \
 | `<name>` | 项目目录名（位置参数） |
 | `--here` | 在当前目录初始化（不创建子目录） |
 | `--remote=<url>` | 设置 git remote origin |
-| `--tools=<list>` | 基线工具列表（默认 `claude-code,codex`） |
+| `--tools=<list>` | 指定生成哪些工具的产物（默认基线 `claude-code,codex`） |
 | `--all-tools` | 同时生成 personal 工具产物（cursor / trae / qoder / antigravity）；默认不生成，留待开发者本地按需 `lingshu sync` |
 | `--limbs=<list>` | 肢体仓 `name:url,name:url` 格式 |
 | `--no-git` | 跳过 git init |
@@ -90,11 +94,13 @@ lingshu init my-lingshu-app \
 
 ### `lingshu tool <subcmd>`
 
+管理「某工具产物是否入 git」。v0.3 起 `.gitignore` 本身就是唯一真相，子命令直接增删它。
+
 | 子命令 | 说明 |
 |--------|------|
-| `list` | 列出所有适配器及状态 |
-| `baseline <tool>` | 将工具改为基线（产物入库） |
-| `personal <tool>` | 将工具改为个人（产物 gitignore） |
+| `list` | 列出所有内置工具及其追踪状态（tracked / ignored） |
+| `track <tool>` | 让该工具产物入库（从 `.gitignore` 移除其忽略规则） |
+| `untrack <tool>` | 让该工具产物不入库（向 `.gitignore` 追加其忽略规则） |
 
 ### `lingshu limb <subcmd>`
 
@@ -105,7 +111,26 @@ lingshu init my-lingshu-app \
 | `init <name>` | 创建空肢体目录 `<name>/` 并完成 `git init`（无 remote） |
 | `adopt <name> <local-path>` | 把已有本地目录复制到 `<name>/` 纳入肢体管理 |
 
-> 三个新增子命令覆盖了"远程未建好就先本地起"和"把现有目录纳入"等真实场景。`add` 仍然是远程克隆的快捷方式。
+> 三个子命令覆盖了"远程未建好就先本地起"和"把现有目录纳入"等真实场景。`add` 仍然是远程克隆的快捷方式。
+
+### `lingshu hooks <subcmd>`
+
+| 子命令 | 说明 |
+|--------|------|
+| `install` | 在当前项目安装内置 git hooks（`post-merge`：`git pull` 后自动 `lingshu sync`）。`init` 时已自动安装，本命令供存量项目补装 |
+
+### `lingshu upgrade`
+
+把存量项目迁移到 v0.3 零侵入结构。
+
+| 选项 | 说明 |
+|------|------|
+| _(无参数)_ | 执行迁移 |
+| `--dry-run` | 仅预览将执行的动作，不写盘 |
+| `--force` | 即使检测到风险（如 `package.json` 含业务依赖）也继续 |
+
+- **v0.2.x → v0.3**：删除 `.lingshu/`、删除/瘦身 `package.json`、把原 `adapters.mjs` 的 cursor frontmatter 迁入 `reference/rules/*.md`、改造 CI 为 `npx`、重装 hooks、重生成基线产物。
+- **灵枢 1.0**（规则散落在产物、无 `reference/rules/` 真源）：无法无损自动迁移，给出明确的手动迁移指引。
 
 ---
 
@@ -120,16 +145,16 @@ lingshu init my-lingshu-app \
 | Qoder | `.qoder/rules/*.md` | 个人 |
 | Antigravity | `.agent/rules/*.md` | 个人 |
 
-新增工具：编辑生成项目的 `.lingshu/config/adapters.mjs` 即可。
+内置 6 大工具开箱即用，无需任何配置。若需接入未内置的工具，可在项目的 `reference/.lingshu.json` 声明自定义适配器（可选逃生舱）。
 
 ---
 
 ## 设计原则
 
 1. **零依赖**：纯 Node 内置模块，避免 `node_modules` 膨胀
 2. **跨平台**：兼容 Win / macOS / Linux
-3. **薄包装**：CLI 不做模板里 `.lingshu/scripts/` 已能做的事
-4. **可演进**：模板可替换，适配器可扩展
+3. **零侵入**：同步引擎在 CLI 内，派生仓只留治理资产，不背引擎与 `package.json`
+4. **可演进**：模板可替换，适配器内置可扩展
 
 ---
 
@@ -140,10 +165,11 @@ lingshu init my-lingshu-app \
 | `init` | ✅ |
 | `sync` | ✅ |
 | `doctor` | ✅ |
-| `tool` | ✅ |
+| `tool`（track/untrack） | ✅ |
 | `limb` | ✅ |
+| `hooks` | ✅ |
+| `upgrade` | ✅ |
 | `archive` | 🚧 待规划 |
-| `upgrade` | 🚧 待规划 |
 
 ---
 
@@ -153,7 +179,7 @@ lingshu init my-lingshu-app \
 git clone git@github.com:imrui/lingshu-cli.git
 cd lingshu-cli
 
-npm test                       # 运行 5 个 smoke 测试
+npm test                       # 运行 smoke 测试（17 项）
 node bin/lingshu.mjs --help    # 本地试运行
 npm link                       # 全局链接，方便调试
 ```
@@ -187,4 +213,4 @@ npm link                       # 全局链接，方便调试
 
 [MIT](./LICENSE) © 2026 imrui
 
-> CLI 内嵌的模板（`templates/default/package.json`）`license` 字段保持 `UNLICENSED` 占位，由通过 `lingshu init` 派生的新项目作者自决。
+> 本 CLI 以 MIT 协议开源。通过 `lingshu init` 派生的新项目不含任何脚手架 `package.json`，协议由项目作者自决。

bin/lingshu.mjs

@@ -8,8 +8,10 @@
  *   init <name>       初始化新的灵枢项目
  *   sync              重新分发规则到本地 AI 工具
  *   doctor            架构健康检查
- *   tool <subcmd>     管理 AI 工具支持（list/baseline/personal）
+ *   tool <subcmd>     管理 AI 工具支持（list/track/untrack）
  *   limb <subcmd>     管理肢体仓（list/add）
+ *   hooks <subcmd>    安装 git hooks（install）
+ *   upgrade           迁移存量项目到 v0.3 零侵入结构
  *   --version, -v     显示版本
  *   --help, -h        显示帮助
  */
@@ -43,8 +45,8 @@ ${pkg.description}  v${pkg.version}
 
   doctor               架构健康检查（物理结构 + SSoT 真源 + 一致性）
 
-  tool <subcmd>        管理 AI 工具支持
-                       子命令: list | baseline <tool> | personal <tool>
+  tool <subcmd>        管理 AI 工具产物的 git 追踪状态
+                       子命令: list | track <tool> | untrack <tool>
 
   limb <subcmd>        管理肢体仓
                        子命令:
@@ -53,6 +55,12 @@ ${pkg.description}  v${pkg.version}
                          init <name>                创建空肢体（mkdir + git init）
                          adopt <name> <local-path>  纳入已有本地目录
 
+  hooks <subcmd>       安装灵枢 git hooks
+                       子命令: install
+
+  upgrade              将存量项目迁移到 v0.3 零侵入结构
+                       选项: --dry-run（仅预览）, --force
+
   --version, -v        显示版本
   --help, -h           显示帮助
 
@@ -65,6 +73,8 @@ const COMMANDS = {
   doctor: () => import('../src/commands/doctor.mjs'),
   tool: () => import('../src/commands/tool.mjs'),
   limb: () => import('../src/commands/limb.mjs'),
+  hooks: () => import('../src/commands/hooks.mjs'),
+  upgrade: () => import('../src/commands/upgrade.mjs'),
 };
 
 async function main() {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruobai/lingshu",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "灵枢架构 CLI — AI 原生项目脚手架 | 若白知行出品",
   "type": "module",
   "bin": {
@@ -16,7 +16,8 @@
     "src",
     "templates",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"

src/commands/doctor.mjs

@@ -26,8 +26,6 @@ export default async function doctor() {
     'reference/management/tasks',
     'reference/management/walkthroughs',
     'reference/management/reports',
-    '.lingshu/scripts',
-    '.lingshu/config',
   ];
   for (const d of requiredDirs) {
     if (existsSync(join(root, d))) ok(d);

src/commands/hooks.mjs

@@ -0,0 +1,31 @@
+/**
+ * lingshu hooks <subcmd>
+ *
+ *   install        在当前项目安装灵枢 git hooks（post-merge 自动同步）
+ *
+ * 供存量项目补装 hooks；init 时已自动安装。
+ */
+
+import { log } from '../utils/log.mjs';
+import { installHooks } from '../core/hooks.mjs';
+import { isLingshuProject } from '../core/adapters.mjs';
+
+export default async function hooks({ args }) {
+  const [sub = 'install'] = args;
+  const root = process.cwd();
+
+  if (sub !== 'install') {
+    log.error(`未知子命令: ${sub}`);
+    log.hint('可用: install');
+    process.exit(1);
+  }
+
+  if (!isLingshuProject(root)) throw new Error('当前目录不是灵枢项目（未找到 reference/rules/）');
+
+  const { installed, skipped } = installHooks(root);
+  if (skipped) {
+    log.warn('当前目录不是 git 仓库，跳过 hooks 安装');
+    return;
+  }
+  log.ok(`已安装 git hooks: ${installed.join(', ')}`);
+}