@heihei0299/matt-skills 3.0.12 → 3.0.14

package/README.md

@@ -2,6 +2,12 @@
 
 面向项目仓库的 Agent skills 与配置模板。模板包含项目 skeleton、`AGENTS.md`、项目上下文占位文件，以及 pi / opencode 所需的项目配置；共享 Skills 由 CLI 从 Workspace 的 canonical source 直接组装到目标项目。
 
+## 环境要求
+
+- Node.js `>=18`。
+- npm（随 Node.js 提供，用于安装和运行 CLI；也可通过 `npx` 直接调用）。
+- Git（`sync`、`check` 和发布流程需要）。
+
 ## 模板内容
 
 ```text
@@ -15,6 +21,7 @@ template/
 共享 Skills 不作为 Template Snapshot 的持久化副本；`init`、普通 `sync` 和项目级 `install` 都从 Workspace 的 canonical source 分发到唯一的 `.agents/skills/`。`.pi/skills/`、`.opencode/skills/` 和 `.claude/skills/` 仅用于项目自定义 skills。
 
 - `PROJECT.md` 描述项目是什么；操作规则放在 `AGENTS.md`。
+- 分发的 `AGENTS.md` 提供通用工作流；项目专用规则、命令、测试方式和完成标准由目标项目更具体的 `AGENTS.md` 补充。
 - `.opencode/CONTEXT.md` / `.pi/CONTEXT.md` 保存领域术语与边界。
 - `.agents/skills/` 承载共享 skills；同步只处理可分发 skill 名称，不删除额外的项目自定义 skills。
 - `ci-guard`、`commit-check` 是本仓库维护用的 repo-local skills，不会分发到目标项目。
@@ -55,7 +62,7 @@ npx @heihei0299/matt-skills sync --all       # 同步全部可分发 skills
 npx @heihei0299/matt-skills sync --dry-run --json
 ```
 
-`init` 默认保护已有 `AGENTS.md`；需要刷新完整模板时使用 `init --all`。默认 `sync` 只刷新 `AGENTS.md` 的 `matt-skills:managed` 受管区块并保留标记外的项目规则；旧的无标记 `AGENTS.md` 原样保留，`sync --all` 才整体刷新。`sync` 不删除目标项目的额外文件或自定义 skills。
+`init` 默认保护已有 `AGENTS.md`；需要刷新完整模板时使用 `init --all`。默认 `sync` 保留已有 `AGENTS.md` 和项目规则，`sync --all` 才将其整体刷新为当前分发模板。`sync` 不删除目标项目的额外文件或自定义 skills。
 
 默认 programming 范围中的 4 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`。
 
@@ -100,7 +107,7 @@ npx @heihei0299/matt-skills sync --all             # 同步全部可分发范围
 
 ## 发布
 
-推送 `v*` 标签会触发 GitHub Actions：全量测试、模板检查和 npm 发布。
+版本由推送的 `v*` 标签决定；GitHub Actions 会在发布时从 tag 设置 npm 包版本，并执行全量测试与模板检查。
 
 ```sh
 npm test

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readdir, readFile, writeFile, cp, stat, rm, mkdir } from 'node:fs/promises';
+import { readdir, readFile, writeFile, cp, stat, lstat, rm, mkdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -74,7 +74,7 @@ Sync options:
   --help, -h      Show this help
   项目 skills：${PROJECT_SKILL_DIRS}
 
-说明：默认不带 --all 增量同步默认 programming skill，并只更新 AGENTS.md 的 matt-skills 受管区块；没有受管标记的现有 AGENTS.md 原样保留。--all 时同步全部可分发 skill 并强制刷新 AGENTS.md。
+说明：默认不带 --all 增量同步默认 programming skill，并保留现有 AGENTS.md；--all 时同步全部可分发 skill 并强制刷新 AGENTS.md。
 
 提示：matt-skills --help 查看全量
 `;
@@ -236,6 +236,57 @@ function projectSkillTargets(target) {
   return [...targets.values()];
 }
 
+const LEGACY_PROJECT_SKILL_DIRS = ['.pi/skills', '.opencode/skills', '.claude/skills'];
+
+async function isSafeRealPath(targetPath) {
+  const absolute = path.resolve(targetPath);
+  const root = path.parse(absolute).root;
+  let current = root;
+  for (const segment of path.relative(root, absolute).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if ((await lstat(current)).isSymbolicLink()) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function sameMetadata(left, right) {
+  return (left.mode & 0o7777) === (right.mode & 0o7777)
+    && left.uid === right.uid
+    && left.gid === right.gid;
+}
+
+async function sameTree(left, right) {
+  try {
+    const [leftInfo, rightInfo] = await Promise.all([lstat(left), lstat(right)]);
+    if (leftInfo.isSymbolicLink() || rightInfo.isSymbolicLink()) return false;
+    if (leftInfo.isDirectory() !== rightInfo.isDirectory()) return false;
+    if (leftInfo.isDirectory()) {
+      const [leftEntries, rightEntries] = await Promise.all([
+        readdir(left, { withFileTypes: true }),
+        readdir(right, { withFileTypes: true }),
+      ]);
+      if (!sameMetadata(leftInfo, rightInfo) || leftEntries.length !== rightEntries.length) return false;
+      const rightNames = new Set(rightEntries.map((entry) => entry.name));
+      for (const entry of leftEntries) {
+        if (!rightNames.has(entry.name) || !await sameTree(path.join(left, entry.name), path.join(right, entry.name))) {
+          return false;
+        }
+      }
+      return true;
+    }
+    if (leftInfo.isFile() && rightInfo.isFile()) {
+      return (await readFile(left)).equals(await readFile(right)) && sameMetadata(leftInfo, rightInfo);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 const GLOBAL_DIRS = {
   codex: '.codex/skills',
   pi: '.pi/agent/skills',
@@ -441,12 +492,20 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
   const allSkills = await listSkillNames({ onlyProgramming });
   const skillTargets = projectSkillTargets(target);
   const skillsDir = path.resolve(target, PROJECT_DIRS.codex);
-  const preservedRepoLocal = [];
-  const preserveLocations = skillTargets.map(({ tool, dir }) => ({
-    dir,
-    label: PROJECT_DIRS[tool],
-    isWorkspaceSource: path.resolve(dir) === path.resolve(SKILLS_DIR),
+  const legacyLocations = LEGACY_PROJECT_SKILL_DIRS.map((relative) => ({
+    dir: path.resolve(target, relative),
+    label: relative,
+    isWorkspaceSource: false,
   }));
+  const preservedRepoLocal = [];
+  const preserveLocations = [
+    ...skillTargets.map(({ tool, dir }) => ({
+      dir,
+      label: PROJECT_DIRS[tool],
+      isWorkspaceSource: path.resolve(dir) === path.resolve(SKILLS_DIR),
+    })),
+    ...legacyLocations,
+  ];
   for (const { dir } of skillTargets) await mkdir(dir, { recursive: true });
   for (const name of REPO_LOCAL_SKILLS) {
     for (const location of preserveLocations) {
@@ -476,8 +535,34 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
       }
     }
   }
-  // Project skill directories may contain project-local Skills. Preserve them because
-  // their origin cannot be distinguished safely from a historical shared mirror.
+  const distributableSkillNames = (await listSkillNames({ onlyProgramming: false })).filter((name) => !REPO_LOCAL_SKILLS.has(name));
+  const cleanedLegacy = [];
+  for (const location of legacyLocations) {
+    let entries;
+    try {
+      if (!await isSafeRealPath(location.dir)) continue;
+      const locationInfo = await lstat(location.dir);
+      if (!locationInfo.isDirectory()) continue;
+      entries = await readdir(location.dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === '.git' || entry.name.endsWith('.bak')) continue;
+      if (!distributableSkillNames.includes(entry.name)) continue;
+      const src = path.join(SKILLS_DIR, entry.name);
+      const dst = path.join(location.dir, entry.name);
+      try {
+        if (await sameTree(src, dst)) {
+          await rm(dst, { recursive: true, force: true });
+          cleanedLegacy.push(`${location.label}/${entry.name}`);
+        }
+      } catch {}
+    }
+  }
+  // Legacy harness dirs may contain project-local Skills. Only exact canonical
+  // trees of clearly distributable skills are removed; repo-local, modified or
+  // unknown trees remain untouched.
   // 清理过时的 .pi/settings.json 指向
   try {
     const piSettings = path.join(target, '.pi/settings.json');
@@ -489,6 +574,9 @@ async function syncCommand({ dest, all, dryRun, json, upstreamUrl, ref }) {
       }
     }
   } catch {}
+  if (cleanedLegacy.length) {
+    process.stdout.write(`迁移清理：${cleanedLegacy.join(', ')} 旧共享副本已移除\n`);
+  }
   if (preservedRepoLocal.length) {
     process.stdout.write(`迁移提示：${preservedRepoLocal.join(', ')} 已不再分发，现有副本已保留\n`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "3.0.12",
+  "version": "3.0.14",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/template/AGENTS.md

@@ -1,6 +1,5 @@
 # AGENTS.md
 
-<!-- matt-skills:managed:start -->
 ## Workflow
 
 按任务选择最匹配的 skill / 工具：
@@ -76,4 +75,3 @@ codegraph node "<符号>"
 ## Completion
 
 完成时说明改动或审查结论、已执行验证、未执行验证及原因、剩余风险；如有 commit，报告 commit hash。
-<!-- matt-skills:managed:end -->