From e36d29166cfba7e793358b2eee7bc724f4a3ec1a Mon Sep 17 00:00:00 2001 From: rui Date: Sun, 31 May 2026 02:10:14 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E8=BF=81=E7=A7=BB=E6=9C=AC=E4=BB=93?= =?UTF-8?q?=E8=87=B3=20v0.3=20=E9=9B=B6=E4=BE=B5=E5=85=A5=E7=BB=93?= =?UTF-8?q?=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 经 lingshu upgrade 迁移：移除 .lingshu/ 与 package.json - reference/rules 注入 frontmatter，去除对旧引擎（.lingshu/scripts、npm run sync）引用 - CI 改用 npx @ruobai/lingshu；README 重写为零侵入版 - 重新生成 CLAUDE.md / AGENTS.md --- .github/workflows/rules-consistency.yml | 5 +- .lingshu/README.md | 66 --------- .lingshu/config/adapters.mjs | 95 ------------- .lingshu/hooks/post-merge | 10 -- .lingshu/scripts/doctor.mjs | 83 ----------- .lingshu/scripts/install-hooks.mjs | 43 ------ .lingshu/scripts/sync-rules.mjs | 180 ------------------------ AGENTS.md | 12 +- CLAUDE.md | 12 +- README.md | 80 ++++------- package.json | 19 --- reference/rules/ai-behavior.md | 7 + reference/rules/lingshu-core.md | 13 +- 13 files changed, 61 insertions(+), 564 deletions(-) delete mode 100644 .lingshu/README.md delete mode 100644 .lingshu/config/adapters.mjs delete mode 100644 .lingshu/hooks/post-merge delete mode 100644 .lingshu/scripts/doctor.mjs delete mode 100644 .lingshu/scripts/install-hooks.mjs delete mode 100644 .lingshu/scripts/sync-rules.mjs delete mode 100644 package.json diff --git a/.github/workflows/rules-consistency.yml b/.github/workflows/rules-consistency.yml index 15e11d0..107cd95 100644 --- a/.github/workflows/rules-consistency.yml +++ b/.github/workflows/rules-consistency.yml @@ -12,7 +12,6 @@ on: branches: [master, main] paths: - 'reference/rules/**' - - '.lingshu/**' - 'CLAUDE.md' - 'AGENTS.md' @@ -26,7 +25,7 @@ jobs: with: node-version: '20' - name: 校验 SSoT 与基线产物一致性 - run: node .lingshu/scripts/sync-rules.mjs --check --baseline + run: npx -y @ruobai/lingshu sync --check --baseline doctor: name: 架构健康度体检 @@ -38,4 +37,4 @@ jobs: with: node-version: '20' - name: 运行 doctor - run: node .lingshu/scripts/doctor.mjs + run: npx -y @ruobai/lingshu doctor diff --git a/.lingshu/README.md b/.lingshu/README.md deleted file mode 100644 index 881d031..0000000 --- a/.lingshu/README.md +++ /dev/null @@ -1,66 +0,0 @@ -# .lingshu/ — 项目元数据空间 - -> 本目录是 **灵枢架构** 的"项目内核"，独立于任何 AI 工具，承载项目级脚本与配置。 - -## 目录结构 - -``` -.lingshu/ -├── config/ -│ └── adapters.mjs # AI 工具适配清单（SSoT → 各工具产物的映射） -├── scripts/ -│ ├── sync-rules.mjs # 规则分发脚本（核心） -│ ├── doctor.mjs # 架构健康检查 -│ └── install-hooks.mjs # 安装 git hooks -└── hooks/ - └── post-merge # 拉取后自动同步规则 -``` - -## 命名说明 - -`.lingshu/` 不是任何 AI 工具的目录（区别于 `.cursor/`、`.trae/`、`.qoder/`、`.agent/`）， -而是 **灵枢架构自身** 的元数据空间，故名 `.lingshu`。 - -## 常用命令 - -```bash -npm run sync # 分发规则到所有 AI 工具目录 -npm run sync:check # 仅校验一致性（用于 CI） -npm run sync -- --only=cursor,codex # 仅同步指定工具 -npm run sync -- --baseline # 仅同步基线工具 -npm run doctor # 运行架构健康检查 -npm run hooks:install # 安装/更新 git hooks -``` - -## 工作原理 - -``` - ┌──────────────────────────────────┐ - │ reference/rules/ (SSoT 真源) │ - │ ├── ai-behavior.md │ - │ └── lingshu-core.md │ - └─────────────┬────────────────────┘ - │ - │ sync-rules.mjs - │ (按 adapters.mjs 配置) - ▼ - ┌──────────────────┴──────────────────┐ - │ 生成产物 (artifact) │ - ├──────────────────────────────────────┤ - │ ✅ baseline (入库): │ - │ - CLAUDE.md (Claude Code) │ - │ - AGENTS.md (Codex) │ - │ │ - │ ❌ personal (gitignore): │ - │ - .cursor/rules/ │ - │ - .trae/rules/ │ - │ - .qoder/rules/ │ - │ - .agent/rules/ │ - └──────────────────────────────────────┘ -``` - -- **真源唯一**：所有规则改动只能在 `reference/rules/` 进行 -- **基线工具入库**：保证团队成员克隆即用（无需先跑脚本） -- **个人偏好工具**：本地生成，不污染 git -- **CI 守护**：GitHub Actions 校验入库产物与真源的一致性 -- **Hook 自动化**：`git pull` 后 post-merge 自动重新分发 diff --git a/.lingshu/config/adapters.mjs b/.lingshu/config/adapters.mjs deleted file mode 100644 index b6b0b9b..0000000 --- a/.lingshu/config/adapters.mjs +++ /dev/null @@ -1,95 +0,0 @@ -/** - * 灵枢 AI 工具适配清单 - * - * 职责：定义 SSoT 真源 → 各 AI 工具产物的映射规则。 - * 修改本文件后执行 `npm run sync` 重新分发。 - * - * 适配器类型： - * - 'directory'：每个 source 在目标目录下生成一个独立文件（适用 Cursor/Trae/Qoder/Antigravity） - * - 'file'：所有 source 合并为单一文件（适用 Claude Code 的 CLAUDE.md、Codex 的 AGENTS.md） - */ - -/** SSoT 真源文件清单 */ -export const sources = [ - { name: 'lingshu-core', path: 'reference/rules/lingshu-core.md' }, - { name: 'ai-behavior', path: 'reference/rules/ai-behavior.md' }, -]; - -/** 各 AI 工具适配器 */ -export const adapters = { - cursor: { - type: 'directory', - target: '.cursor/rules/', - extension: '.mdc', - frontmatter: { - 'ai-behavior': { - name: 'ai-behavior', - description: '灵枢智能体行为准则：Plan 模式存档、真理同步流与原子化交付', - globs: '**/*', - trigger: 'always_on', - }, - 'lingshu-core': { - name: 'lingshu-core', - description: '灵枢架构核心准则：脑体解耦、Git 物理隔离与路径映射', - globs: '**/*', - trigger: 'always_on', - }, - }, - }, - - trae: { - type: 'directory', - target: '.trae/rules/', - extension: '.md', - }, - - qoder: { - type: 'directory', - target: '.qoder/rules/', - extension: '.md', - }, - - antigravity: { - type: 'directory', - target: '.agent/rules/', - extension: '.md', - }, - - 'claude-code': { - type: 'file', - target: 'CLAUDE.md', - header: [ - '', - '', - '', - '', - '# 灵枢 (LingShu) — Claude Code 项目指令', - '', - '> 本文件由灵枢分发脚本自动生成。所有规则的真理来源位于 `reference/rules/`。', - '', - ].join('\n'), - separator: '\n\n---\n\n', - }, - - codex: { - type: 'file', - target: 'AGENTS.md', - header: [ - '', - '', - '', - '', - '# 灵枢 (LingShu) — AI Agents 项目指令', - '', - '> 本文件由灵枢分发脚本自动生成。所有规则的真理来源位于 `reference/rules/`。', - '', - ].join('\n'), - separator: '\n\n---\n\n', - }, -}; - -/** - * 团队基线工具：默认入库（产物受 git 追踪，保证克隆即用） - * 个人偏好工具：默认 ignore（每位开发者本地生成，互不干扰） - */ -export const baseline = ['claude-code', 'codex']; diff --git a/.lingshu/hooks/post-merge b/.lingshu/hooks/post-merge deleted file mode 100644 index cc6ca1d..0000000 --- a/.lingshu/hooks/post-merge +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/sh -# 灵枢 post-merge hook -# 当 git pull / git merge 后，若 SSoT 或适配器配置变更，自动重新分发规则到本地工具。 - -CHANGED=$(git diff HEAD@{1} HEAD --name-only 2>/dev/null) - -if echo "$CHANGED" | grep -qE "^(reference/rules/|\.lingshu/config/)"; then - echo "检测到灵枢规则变更，正在重新分发..." - node .lingshu/scripts/sync-rules.mjs -fi diff --git a/.lingshu/scripts/doctor.mjs b/.lingshu/scripts/doctor.mjs deleted file mode 100644 index ed7f88c..0000000 --- a/.lingshu/scripts/doctor.mjs +++ /dev/null @@ -1,83 +0,0 @@ -#!/usr/bin/env node -/** - * 灵枢架构健康检查（跨平台） - * 替代 .agent/workflows/self-audit.md 的 PowerShell 版本，可在 Windows / macOS / Linux 运行。 - */ - -import { existsSync, readFileSync } from 'node:fs'; -import { join, resolve, dirname } from 'node:path'; -import { fileURLToPath } from 'node:url'; - -const __filename = fileURLToPath(import.meta.url); -const __dirname = dirname(__filename); -const ROOT = resolve(__dirname, '../..'); - -const c = { - green: s => `\x1b[32m${s}\x1b[0m`, - red: s => `\x1b[31m${s}\x1b[0m`, - yellow: s => `\x1b[33m${s}\x1b[0m`, - cyan: s => `\x1b[36m${s}\x1b[0m`, - dim: s => `\x1b[2m${s}\x1b[0m`, - bold: s => `\x1b[1m${s}\x1b[0m`, -}; - -let errors = 0, warnings = 0; -const ok = m => console.log(c.green(` ✓ ${m}`)); -const warn = m => { console.log(c.yellow(` ⚠ ${m}`)); warnings++; }; -const fail = m => { console.log(c.red (` ✗ ${m}`)); errors++; }; - -console.log(c.cyan(c.bold('\n灵枢架构健康检查\n'))); - -// 1. 物理完整性 -console.log(c.cyan('[1/4] 物理完整性')); -const requiredDirs = [ - 'reference/rules', - 'reference/docs', - 'reference/management/plans', - '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); - else fail(`${d} 缺失`); -} - -// 2. SSoT 真源 -console.log(c.cyan('\n[2/4] SSoT 真源完整性')); -const ssotFiles = [ - 'reference/rules/ai-behavior.md', - 'reference/rules/lingshu-core.md', -]; -for (const f of ssotFiles) { - if (existsSync(join(ROOT, f))) ok(f); - else fail(`${f} 缺失`); -} - -// 3. 灵枢宣言 -console.log(c.cyan('\n[3/4] 灵枢宣言注入')); -const manifesto = join(ROOT, 'reference/README.md'); -if (existsSync(manifesto)) { - const txt = readFileSync(manifesto, 'utf8'); - if (txt.includes('中枢一动，全栈皆通')) ok('灵枢宣言已注入'); - else warn('reference/README.md 缺少核心宣言口号'); -} else { - fail('reference/README.md (灵枢宣言) 缺失'); -} - -// 4. 规则一致性提示 -console.log(c.cyan('\n[4/4] 规则一致性')); -console.log(c.dim(' (调用 sync-rules --check 进行严格校验)')); -console.log(c.dim(' 推荐执行: npm run sync:check\n')); - -// 总结 -if (errors === 0 && warnings === 0) { - console.log(c.green(c.bold('✅ 灵枢架构健康度：优秀\n'))); -} else if (errors === 0) { - console.log(c.yellow(c.bold(`⚠️ 通过，但有 ${warnings} 处提醒\n`))); -} else { - console.log(c.red(c.bold(`❌ 失败：${errors} 处错误，${warnings} 处提醒\n`))); - process.exit(1); -} diff --git a/.lingshu/scripts/install-hooks.mjs b/.lingshu/scripts/install-hooks.mjs deleted file mode 100644 index 0531827..0000000 --- a/.lingshu/scripts/install-hooks.mjs +++ /dev/null @@ -1,43 +0,0 @@ -#!/usr/bin/env node -/** - * 安装灵枢 Git Hooks（跨平台） - * - * 将 .lingshu/hooks/ 下的脚本复制到 .git/hooks/，并赋予执行权限。 - * 用法: node .lingshu/scripts/install-hooks.mjs - */ - -import { copyFileSync, chmodSync, existsSync, readdirSync, mkdirSync, statSync } from 'node:fs'; -import { join, resolve, dirname } from 'node:path'; -import { fileURLToPath } from 'node:url'; - -const __filename = fileURLToPath(import.meta.url); -const __dirname = dirname(__filename); -const ROOT = resolve(__dirname, '../..'); - -const HOOKS_SRC = join(ROOT, '.lingshu/hooks'); -const HOOKS_DST = join(ROOT, '.git/hooks'); - -if (!existsSync(join(ROOT, '.git'))) { - console.log('ℹ️ 跳过 hooks 安装：当前目录不是 git 仓库'); - process.exit(0); -} - -if (!existsSync(HOOKS_SRC)) { - console.log('ℹ️ 跳过 hooks 安装：.lingshu/hooks/ 不存在'); - process.exit(0); -} - -mkdirSync(HOOKS_DST, { recursive: true }); - -let installed = 0; -for (const hook of readdirSync(HOOKS_SRC)) { - const src = join(HOOKS_SRC, hook); - if (!statSync(src).isFile()) continue; - const dst = join(HOOKS_DST, hook); - copyFileSync(src, dst); - try { chmodSync(dst, 0o755); } catch { /* Windows 下忽略权限错误 */ } - console.log(` ✓ 已安装 hook: ${hook}`); - installed++; -} - -console.log(`\n✅ 共安装 ${installed} 个 git hook\n`); diff --git a/.lingshu/scripts/sync-rules.mjs b/.lingshu/scripts/sync-rules.mjs deleted file mode 100644 index 84f714b..0000000 --- a/.lingshu/scripts/sync-rules.mjs +++ /dev/null @@ -1,180 +0,0 @@ -#!/usr/bin/env node -/** - * 灵枢规则分发脚本 - * - * 用法： - * node .lingshu/scripts/sync-rules.mjs # 默认 = baseline + 已存在产物的 personal - * node .lingshu/scripts/sync-rules.mjs --all # 全部工具 - * node .lingshu/scripts/sync-rules.mjs --baseline # 仅基线 - * node .lingshu/scripts/sync-rules.mjs --only=cursor,codex # 仅特定工具 - * node .lingshu/scripts/sync-rules.mjs --check # 仅校验，不写入（用于 CI） - * - * 跨平台：纯 Node.js 内置模块，零依赖。 - */ - -import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, readdirSync } from 'node:fs'; -import { dirname, join, resolve } from 'node:path'; -import { fileURLToPath } from 'node:url'; -import { adapters, sources, baseline } from '../config/adapters.mjs'; - -const __filename = fileURLToPath(import.meta.url); -const __dirname = dirname(__filename); -const ROOT = resolve(__dirname, '../..'); - -const args = process.argv.slice(2); -const isCheck = args.includes('--check'); -const onlyBaseline = args.includes('--baseline'); -const onlyAll = args.includes('--all'); -const onlyArg = args.find(a => a.startsWith('--only=')); -const onlyTools = onlyArg ? onlyArg.slice('--only='.length).split(',').map(s => s.trim()).filter(Boolean) : null; - -const c = { - green: s => `\x1b[32m${s}\x1b[0m`, - red: s => `\x1b[31m${s}\x1b[0m`, - yellow: s => `\x1b[33m${s}\x1b[0m`, - cyan: s => `\x1b[36m${s}\x1b[0m`, - dim: s => `\x1b[2m${s}\x1b[0m`, - bold: s => `\x1b[1m${s}\x1b[0m`, -}; - -/** 序列化 frontmatter（YAML 子集） */ -function renderFrontmatter(meta) { - if (!meta) return ''; - const lines = ['---']; - for (const [k, v] of Object.entries(meta)) { - lines.push(`${k}: ${v}`); - } - lines.push('---', ''); - return lines.join('\n'); -} - -/** 读取 SSoT 文件，剥除已有 frontmatter（防止重复包裹） */ -function loadSource(srcPath) { - const full = join(ROOT, srcPath); - if (!existsSync(full)) { - throw new Error(`SSoT 文件缺失: ${srcPath}`); - } - let content = readFileSync(full, 'utf8'); - if (content.startsWith('---\n') || content.startsWith('---\r\n')) { - const m = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/); - if (m) content = content.slice(m[0].length); - } - return content.replace(/^\s*\n+/, ''); -} - -/** 渲染单个适配器，返回 [{ to, content }] 列表 */ -function renderAdapter(toolName, cfg) { - const out = []; - - if (cfg.type === 'directory') { - const targetDir = join(ROOT, cfg.target); - - // 清理与 sources 同名的旧产物（保护用户自定义文件） - if (existsSync(targetDir)) { - for (const f of readdirSync(targetDir)) { - const stem = f.replace(/\.(md|mdc)$/, ''); - if (sources.find(s => s.name === stem)) { - if (!isCheck) rmSync(join(targetDir, f)); - } - } - } - - for (const src of sources) { - const body = loadSource(src.path); - const fm = cfg.frontmatter?.[src.name]; - const content = (fm ? renderFrontmatter(fm) : '') + body; - const relTarget = cfg.target.replace(/\/?$/, '/') + src.name + cfg.extension; - out.push({ to: relTarget, content }); - } - } else if (cfg.type === 'file') { - const parts = sources.map(src => loadSource(src.path)); - const sep = cfg.separator ?? '\n\n---\n\n'; - const header = cfg.header ?? ''; - const body = (header ? header + sep : '') + parts.join(sep); - out.push({ to: cfg.target, content: body }); - } else { - throw new Error(`未知适配器类型: ${cfg.type}`); - } - - return out; -} - -function decideTargets() { - if (onlyTools) return onlyTools; - if (onlyBaseline) return baseline; - if (onlyAll) return Object.keys(adapters); - // auto：baseline + 已存在产物的 personal - return Object.keys(adapters).filter((name) => { - if (baseline.includes(name)) return true; - const cfg = adapters[name]; - return existsSync(join(ROOT, cfg.target)); - }); -} - -function main() { - const targets = decideTargets(); - let exitCode = 0; - let writes = 0, drifts = 0, missing = 0; - - console.log(c.cyan(c.bold('\n灵枢规则分发'))); - console.log(c.dim(` 模式: ${isCheck ? 'CHECK（仅校验）' : 'SYNC（生成产物）'}`)); - console.log(c.dim(` 根目录: ${ROOT}`)); - console.log(c.dim(` 目标工具: ${targets.join(', ')}\n`)); - - for (const tool of targets) { - const cfg = adapters[tool]; - if (!cfg) { - console.log(c.yellow(` ⚠ 未知工具: ${tool}（跳过）`)); - continue; - } - - const tag = baseline.includes(tool) ? c.green('[baseline]') : c.dim('[personal]'); - console.log(`${tag} ${c.bold(tool)}:`); - - try { - const items = renderAdapter(tool, cfg); - for (const { to, content } of items) { - const fullTarget = join(ROOT, to); - - if (isCheck) { - if (!existsSync(fullTarget)) { - console.log(c.red(` ✗ 缺失: ${to}`)); - missing++; exitCode = 1; - } else { - const existing = readFileSync(fullTarget, 'utf8'); - if (existing !== content) { - console.log(c.red(` ✗ 漂移: ${to}`)); - drifts++; exitCode = 1; - } else { - console.log(c.green(` ✓ ${to}`)); - } - } - } else { - mkdirSync(dirname(fullTarget), { recursive: true }); - writeFileSync(fullTarget, content, 'utf8'); - console.log(c.green(` ✓ ${to}`)); - writes++; - } - } - } catch (e) { - console.log(c.red(` ✗ 错误: ${e.message}`)); - exitCode = 1; - } - } - - console.log(''); - if (isCheck) { - if (exitCode === 0) { - console.log(c.green(c.bold('✅ 一致性校验通过\n'))); - } else { - console.log(c.red(c.bold(`❌ 一致性校验失败（缺失 ${missing}，漂移 ${drifts}）`))); - console.log(c.yellow(' 请运行 `npm run sync` 重新生成，并提交基线工具产物。\n')); - } - } else { - console.log(c.green(c.bold(`✅ 规则分发完成（共写入 ${writes} 个文件）\n`))); - } - - process.exit(exitCode); -} - -main(); diff --git a/AGENTS.md b/AGENTS.md index 7e0bd9c..5412ca3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ - - + + # 灵枢 (LingShu) — AI Agents 项目指令 -> 本文件由灵枢分发脚本自动生成。所有规则的真理来源位于 `reference/rules/`。 +> 本文件由 `lingshu sync` 自动生成。所有规则的真理来源位于 `reference/rules/`。 --- @@ -29,7 +29,7 @@ - **🚫 禁止根目录通配提交**: - **严禁** 在根目录执行 `git add .` 或 `git commit -a`，这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 - - 根目录 Git **仅允许** 追踪：`reference/`, `.lingshu/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 + - 根目录 Git **仅允许** 追踪：`reference/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 - **✅ 肢体仓独立提交**: - 修改具体业务代码后，必须显式 `cd [limb-folder_name]/` 进入子目录。 @@ -42,8 +42,8 @@ ## 3. 规则真源约束 (SSoT for Rules) - **真源唯一**: 所有 AI 行为规则的真源位于 `reference/rules/`。 -- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `.lingshu/scripts/sync-rules.mjs` 自动生成的产物**，禁止手动编辑。 -- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `npm run sync` 重新分发。 +- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 +- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 - **CI 保障**: GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 ## 4. 环境与依赖标准 (Stack Standard) diff --git a/CLAUDE.md b/CLAUDE.md index 0aaf927..4121080 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,10 +1,10 @@ - - + + # 灵枢 (LingShu) — Claude Code 项目指令 -> 本文件由灵枢分发脚本自动生成。所有规则的真理来源位于 `reference/rules/`。 +> 本文件由 `lingshu sync` 自动生成。所有规则的真理来源位于 `reference/rules/`。 --- @@ -29,7 +29,7 @@ - **🚫 禁止根目录通配提交**: - **严禁** 在根目录执行 `git add .` 或 `git commit -a`，这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 - - 根目录 Git **仅允许** 追踪：`reference/`, `.lingshu/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 + - 根目录 Git **仅允许** 追踪：`reference/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 - **✅ 肢体仓独立提交**: - 修改具体业务代码后，必须显式 `cd [limb-folder_name]/` 进入子目录。 @@ -42,8 +42,8 @@ ## 3. 规则真源约束 (SSoT for Rules) - **真源唯一**: 所有 AI 行为规则的真源位于 `reference/rules/`。 -- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `.lingshu/scripts/sync-rules.mjs` 自动生成的产物**，禁止手动编辑。 -- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `npm run sync` 重新分发。 +- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 +- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 - **CI 保障**: GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 ## 4. 环境与依赖标准 (Stack Standard) diff --git a/README.md b/README.md index 60699f0..812f1fd 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ | 🧠 **中枢-肢体解耦** | 文档/规则集中于中枢仓，业务代码分散于嵌套肢体仓 | | 📜 **规则 SSoT** | 所有 AI 行为规则统一写在 `reference/rules/`，避免多副本漂移 | | 🤖 **多 AI 工具适配** | 一处定义，自动分发至 6 大主流 AI 编码工具 | -| 🌍 **跨平台脚本** | 纯 Node.js 实现，Win/macOS/Linux 通用 | +| 🪶 **零侵入** | 同步引擎在全局 CLI 内，仓库只留治理资产，无 `.lingshu/`、无 `package.json` | | 🛡️ **CI 守护** | GitHub Actions 自动校验真源与产物的一致性 | | ⚙️ **拉取自动重分发** | `git pull` 后 post-merge hook 自动重新分发规则 | @@ -40,8 +40,8 @@ | Qoder | `.qoder/rules/*.md` | ❌ | 个人偏好 | | Antigravity | `.agent/rules/*.md` | ❌ | 个人偏好 | -> **基线工具** 产物入库，保证团队成员克隆即用；**个人偏好工具** 由各开发者本地按需生成。 -> 新增工具支持：仅需在 `.lingshu/config/adapters.mjs` 添加一项配置。 +> **是否入库由 `.gitignore` 决定**，可用 `lingshu tool track/untrack <工具>` 调整。 +> 内置工具不满足需求时，可在 `reference/.lingshu.json` 声明自定义适配器（可选逃生舱）。 --- @@ -49,19 +49,9 @@ ```text . -├── .lingshu/ # 项目元数据空间（不属于任何 AI 工具） -│ ├── config/ -│ │ └── adapters.mjs # AI 工具适配清单 -│ ├── scripts/ -│ │ ├── sync-rules.mjs # 规则分发（核心） -│ │ ├── doctor.mjs # 架构健康检查 -│ │ └── install-hooks.mjs # Git hooks 安装器 -│ └── hooks/ -│ └── post-merge # 拉取后自动同步规则 -│ -├── reference/ # 真源 (Reference) +├── reference/ # 真源 (Reference) — 中枢的全部资产 │ ├── rules/ # AI 规则 SSoT -│ │ ├── lingshu-core.md # 架构核心宪法 +│ │ ├── lingshu-core.md # 架构核心准则 │ │ └── ai-behavior.md # 智能体行为准则 │ ├── docs/ # 静态真理：PRD、契约、架构 │ ├── experience/ # 经验复利：高分 Prompt、避坑笔记 @@ -71,28 +61,29 @@ │ ├── walkthroughs/ # 存证：逻辑决策、代码演练 │ └── reports/ # 审计：汇总报告、数据库变更 │ -├── CLAUDE.md # Claude Code 入口（基线，自动生成） -├── AGENTS.md # Codex / 通用 Agents 入口（基线，自动生成） +├── CLAUDE.md # Claude Code 入口（基线，由 lingshu sync 生成） +├── AGENTS.md # Codex / 通用 Agents 入口（基线，由 lingshu sync 生成） │ -├── .cursor/ .trae/ .qoder/ # AI 工具规则目录（自动生成 / gitignore） -├── .agent/ # Antigravity：rules 自动生成，workflows 入库 +├── .cursor/ .trae/ .qoder/ # AI 工具规则目录（按需生成 / gitignore） +├── .agent/ # Antigravity 规则目录 │ -├── package.json # npm 脚本入口 ├── .github/workflows/ # GitHub Actions：CI 一致性守护 ├── .gitignore # 灵枢版忽略规则（物理隔绝肢体仓 + 个人产物） └── README.md ``` +> 同步引擎不在仓库内，而在全局 CLI [@ruobai/lingshu](https://www.npmjs.com/package/@ruobai/lingshu)。仓库保持纯净的开发资产。 + --- ## 快速开始 (Getting Started) ### 推荐方式：使用 @ruobai/lingshu CLI（一条命令） -[@ruobai/lingshu](https://www.npmjs.com/package/@ruobai/lingshu) 是灵枢架构的官方脚手架（若白知行出品），把下方 7 步手动流程压缩为 1 条命令： +[@ruobai/lingshu](https://www.npmjs.com/package/@ruobai/lingshu) 是灵枢架构的官方脚手架（若白知行出品），把下方手动流程压缩为 1 条命令： ```bash -# 一次性安装 +# 一次性安装（团队每位成员各装一次） npm install -g @ruobai/lingshu # 一键创建项目（请将 your-org 替换为你的 GitHub 组织或用户名） @@ -123,10 +114,10 @@ git push -u origin master git clone git@github.com:your-org/my-lingshu-app-server.git my-lingshu-app-server git clone git@github.com:your-org/my-lingshu-app-ui.git my-lingshu-app-ui -# 4. 初始化灵枢工具链 -npm install # 安装依赖（含自动安装 git hooks） -npm run sync # 分发规则到本地 AI 工具目录 -npm run doctor # 架构健康检查 +# 4. 生成基线产物 + 安装 hooks（需先全局安装 @ruobai/lingshu） +lingshu sync --baseline # 分发规则到 CLAUDE.md / AGENTS.md +lingshu hooks install # 安装 git hooks +lingshu doctor # 架构健康检查 ``` ### 项目结构概览（接入后） @@ -135,7 +126,6 @@ npm run doctor # 架构健康检查 my-lingshu-app/ # [中枢仓] 逻辑定义与 AI 指令中心 ├── my-lingshu-app-server/ # [肢体仓 A] 后端代码（嵌套子仓） ├── my-lingshu-app-ui/ # [肢体仓 B] 前端代码（嵌套子仓） -├── .lingshu/ # 项目元数据 ├── reference/ # 真理之源 ├── CLAUDE.md / AGENTS.md # 基线 AI 指令 └── README.md # 项目指挥总纲 @@ -153,7 +143,7 @@ grep -rl "lingshu-template" --exclude-dir=node_modules . | xargs sed -i 's/lings # "请将仓库内所有文件中的 'lingshu-template' 替换为 'my-lingshu-app'" ``` -替换后执行 `npm run sync` 重新生成基线产物。 +替换后执行 `lingshu sync` 重新生成基线产物。 --- @@ -164,7 +154,7 @@ grep -rl "lingshu-template" --exclude-dir=node_modules . | xargs sed -i 's/lings ``` reference/rules/*.md ← 编辑这里（唯一真源） ↓ - npm run sync ← 一键分发 + lingshu sync ← 一键分发 ↓ ┌──────────┬──────────────┐ ↓ ↓ ↓ @@ -176,18 +166,20 @@ grep -rl "lingshu-template" --exclude-dir=node_modules . | xargs sed -i 's/lings | 命令 | 用途 | |------|------| -| `npm run sync` | 分发规则到所有 AI 工具 | -| `npm run sync:baseline` | 仅同步基线工具（CLAUDE.md / AGENTS.md） | -| `npm run sync:check` | 校验一致性（CI 用，不写文件） | -| `npm run sync -- --only=cursor,codex` | 仅同步指定工具 | -| `npm run doctor` | 架构健康检查 | -| `npm run hooks:install` | 安装/重装 git hooks | +| `lingshu sync` | 分发规则（baseline + 已激活的个人工具） | +| `lingshu sync --baseline` | 仅同步基线工具（CLAUDE.md / AGENTS.md） | +| `lingshu sync --all` | 同步所有工具 | +| `lingshu sync --only=cursor,codex` | 仅同步指定工具 | +| `lingshu sync --check` | 校验一致性（CI 用，不写文件） | +| `lingshu tool list` | 查看工具矩阵与入库状态 | +| `lingshu tool track/untrack <工具>` | 调整某工具产物是否入库 | +| `lingshu doctor` | 架构健康检查 | +| `lingshu hooks install` | 安装/重装 git hooks | ### 自动化机制 -- ⚡ **`git pull` 后** → `post-merge` hook 检测 SSoT 变更，自动 `sync` +- ⚡ **`git pull` 后** → `post-merge` hook 检测 `reference/rules/` 变更，自动 `lingshu sync` - 🛡️ **PR 提交时** → GitHub Actions 校验 baseline 产物一致性，漂移即拒绝合并 -- 🔄 **`npm install` 后** → `postinstall` 钩子自动安装 git hooks --- @@ -208,20 +200,8 @@ grep -rl "lingshu-template" --exclude-dir=node_modules . | xargs sed -i 's/lings --- -## 演进路线 (Roadmap) - -| 阶段 | 状态 | 目标 | -|:---:|:---:|------| -| **P0** | ✅ 完成 | 中枢-肢体架构 + 多 AI 工具规则副本 | -| **P1** | ✅ 完成 | 规则 SSoT + 跨平台分发 + CI 守护 | -| **P2** | ✅ 完成 | [@ruobai/lingshu](https://www.npmjs.com/package/@ruobai/lingshu) 一键脚手架（init / sync / doctor / tool / limb） | -| **P3** | 📋 待启动 | 文档温度分层 + 自动归档（`lingshu archive`） | -| **P4** | 📋 待启动 | 模板版本管理（`lingshu upgrade`） | - ---- - ## License [MIT](./LICENSE) © 2026 imrui -> 注：本仓库为架构模板。基于本模板派生的新项目可自行选择协议（默认 `templates/default/package.json` 中 `license` 字段为 `UNLICENSED` 占位，由作者自决）。 +> 注：本仓库为架构模板。基于本模板派生的新项目可自行选择协议。 diff --git a/package.json b/package.json deleted file mode 100644 index 1362a6e..0000000 --- a/package.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "name": "lingshu-template", - "version": "0.2.1", - "description": "灵枢架构 (LingShu) — AI 原生开发的中枢模版", - "private": true, - "type": "module", - "scripts": { - "sync": "node .lingshu/scripts/sync-rules.mjs", - "sync:check": "node .lingshu/scripts/sync-rules.mjs --check", - "sync:baseline": "node .lingshu/scripts/sync-rules.mjs --baseline", - "doctor": "node .lingshu/scripts/doctor.mjs", - "hooks:install": "node .lingshu/scripts/install-hooks.mjs", - "postinstall": "node .lingshu/scripts/install-hooks.mjs" - }, - "engines": { - "node": ">=18" - }, - "license": "MIT" -} diff --git a/reference/rules/ai-behavior.md b/reference/rules/ai-behavior.md index 2f3477f..c9abe6c 100644 --- a/reference/rules/ai-behavior.md +++ b/reference/rules/ai-behavior.md @@ -1,3 +1,10 @@ +--- +order: 2 +name: ai-behavior +description: 灵枢智能体行为准则：Plan 模式存档、真理同步流与原子化交付 +globs: **/* +trigger: always_on +--- # 🤖 灵枢智能体行为准则 (Agentic Workflow) ## 1. 思考模式：真理驱动 (Truth Driven) diff --git a/reference/rules/lingshu-core.md b/reference/rules/lingshu-core.md index 52cdd2c..5887e12 100644 --- a/reference/rules/lingshu-core.md +++ b/reference/rules/lingshu-core.md @@ -1,3 +1,10 @@ +--- +order: 1 +name: lingshu-core +description: 灵枢架构核心准则：脑体解耦、Git 物理隔离与路径映射 +globs: **/* +trigger: always_on +--- # 灵枢架构核心准则 (LingShu Core Principles) ## 1. 架构拓扑定义 (Architecture Topology) @@ -18,7 +25,7 @@ - **🚫 禁止根目录通配提交**: - **严禁** 在根目录执行 `git add .` 或 `git commit -a`，这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 - - 根目录 Git **仅允许** 追踪：`reference/`, `.lingshu/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 + - 根目录 Git **仅允许** 追踪：`reference/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 - **✅ 肢体仓独立提交**: - 修改具体业务代码后，必须显式 `cd [limb-folder_name]/` 进入子目录。 @@ -31,8 +38,8 @@ ## 3. 规则真源约束 (SSoT for Rules) - **真源唯一**: 所有 AI 行为规则的真源位于 `reference/rules/`。 -- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `.lingshu/scripts/sync-rules.mjs` 自动生成的产物**，禁止手动编辑。 -- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `npm run sync` 重新分发。 +- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 +- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 - **CI 保障**: GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 ## 4. 环境与依赖标准 (Stack Standard)