@tanlinfeng/project-docs-workflow 2.0.0 → 2.1.0

package/README.md

@@ -30,12 +30,71 @@ npx @tanlinfeng/project-docs-workflow
 | `npx @tanlinfeng/project-docs-workflow --dir <path>` | 指定 skills 根目录（默认 `~/.agents/skills`） |
 | `npx @tanlinfeng/project-docs-workflow --force` | 覆盖已存在的 `project-docs-workflow`（**仅主 skill**；依赖 skill 仍不覆盖） |
 | `npx @tanlinfeng/project-docs-workflow --dry-run` | 只打印将执行的操作，不写入任何文件 |
+| `npx @tanlinfeng/project-docs-workflow --with-matt-skills` | 可选：依赖 skill 改从上游 `mattpocock/skills` 安装**完整版**（需 Node >= 22.20） |
+| `npx @tanlinfeng/project-docs-workflow --matt-agent <name>` | 上游安装使用的 agent（默认 `codex`，落盘到其全局目录 `~/.agents/skills`） |
 | `npx @tanlinfeng/project-docs-workflow check` | 检查依赖 skill 的解析状态，全部可解析时退出码为 0，否则为 1 |
+| `npx @tanlinfeng/project-docs-workflow uninstall` | 依据**安装清单**卸载本包安装的 skill（只删本包装的，见下文「卸载」） |
+| `npx @tanlinfeng/project-docs-workflow uninstall --dry-run` | 只打印卸载计划（将删除 / 保留哪些），不写入 |
+| `npx @tanlinfeng/project-docs-workflow uninstall --force` | 跳过交互确认；非 TTY 场景下**必须**加此参数 |
 
 ### 覆盖策略（安全优先）
 
 安装器**永不覆盖用户已存在的同名 skill**。若目标目录中已存在同名目录，会打印 `同名 skill 已存在，保留用户版本：<name>` 并跳过。只有对主 skill `project-docs-workflow` 使用 `--force` 时才会覆盖它；依赖 skill 即使加了 `--force` 也仍会跳过。
 
+### 可选：从上游安装「完整版」依赖 skill
+
+包内自带的依赖 skill 是来自 `mattpocock/skills` 的**轻量版**。如果你更想要**完整上游版本**，可以启用 `--with-matt-skills`：安装器会调用官方 `skills` CLI（npm 包 `skills`）执行
+
+```bash
+npx --yes skills@latest add mattpocock/skills -g -y -a <agent> -s <name1> <name2> ...
+```
+
+- **交互式询问**：不带 `--with-matt-skills` 时，仅当 stdout 与 stdin **都是 TTY**、动作为 `install`（非 `check`）、且非 `--dry-run` 时，才提示一次 `是否从上游安装依赖 skill 的完整版（mattpocock/skills）？[y/N] `，**默认否**（空输入或其它输入均视为否）。非 TTY / 管道 / CI 场景**完全不询问**，不会挂起。
+- **受管集合**：仅这 8 个名字参与上游安装：`grilling`、`grill-me`、`grill-with-docs`、`domain-modeling`、`tdd`、`deepwork`、`retro`、`improve-codebase-architecture`；`doc-opt` 与主 skill 不属于上游集合，维持原有行为。
+- **永不覆盖**：调用上游前会先检测这 8 个名字里哪些在目标目录中**已存在**，已存在者**原样保留、绝不提交给上游**；只有缺失的名字才会通过 `-s` 传给上游。
+- **顺序与去重**：先跑上游；随后复核上游目标目录，仍然缺失的名字才回退复制本包的轻量版。启用上游时，由上游负责的名字不会再复制轻量版；未启用时（默认）行为与之前完全一致。
+- **降级、绝不失败**：Node < 22.20、找不到 `npx`、上游非 0 退出或网络错误时，只打印中文告警并回退到缺失项的轻量版安装，整体仍以退出码 0 结束。
+- **agent 与目录注意**：上游固定以 `-a <agent> -g` 安装到该 agent 的**全局目录**（默认 `codex` → `~/.agents/skills`，正好与默认目标一致）。可用 `--matt-agent <name>` 覆盖 agent。若你传入了非默认的 `--dir`，上游部分**无法跟随 `--dir`**（仍落到 agent 全局目录），安装器会明确告警，同时 `--dir` 下的轻量版仍按原逻辑处理。
+- **dry-run**：`--dry-run --with-matt-skills` 只打印将执行的上游命令、以及哪些名字因已存在而跳过，不实际执行。
+
+## 卸载
+
+安装时，本包会在 `<target>/.project-docs-workflow.install.json`（`<target>` 为 `--dir` 或默认 `~/.agents/skills`）写入一份**安装清单**，记录每个被处理过的 skill 及其**归属**。卸载完全依据这份清单，而不是靠猜测。
+
+清单形如：
+
+```json
+{
+  "version": "2.1.0",
+  "target": "/home/me/.agents/skills",
+  "updatedAt": "2026-10-12T05:24:36.386Z",
+  "entries": {
+    "project-docs-workflow": { "kind": "main",     "action": "installed", "at": "…" },
+    "tdd":                    { "kind": "lite",     "action": "installed", "at": "…" },
+    "doc-opt":                { "kind": "doc-opt",  "action": "installed", "at": "…" },
+    "deepwork":               { "kind": "lite",     "action": "skipped",   "at": "…" },
+    "retro":                  { "kind": "upstream", "action": "installed", "agent": "codex", "at": "…" }
+  }
+}
+```
+
+- `kind`：`main` / `lite` / `doc-opt`（本包复制的轻量版）/ `upstream`（委托上游 `skills` CLI 安装的完整版）。
+- `action`：`installed`（本次由本包创建）、`forced`（被 `--force` 覆盖，仍属本包）、`skipped`（安装时已存在，本包原样保留，**永不删除**）。
+- 每次成功 `install` 都会**合并更新**清单（不会丢失旧条目）；`--dry-run` 不写清单。
+
+**归属规则（安全优先）**：`uninstall` 只删除清单中 `action` 为 `installed` / `forced` 的名字——无论是本包复制的轻量版，还是本包委托上游安装的完整版。凡是安装时**已存在**（记为 `skipped`）的名字，一律不碰；首次记为 `skipped` 的名字即使后续再次安装也始终保持 `skipped`。
+
+用法：
+
+```bash
+npx @tanlinfeng/project-docs-workflow uninstall [--dir <path>] [--dry-run] [--force]
+```
+
+- **确认**：在交互式终端会询问一次 `确认卸载本包安装的 skill？[y/N] `，**默认否**。非交互式（管道 / CI / 非 TTY）**拒绝执行**，除非显式传入 `--force`。`--dry-run` 从不询问、从不写入。
+- **删除方式**：`main` / `lite` / `doc-opt` 直接删除 `<target>/<name>` 目录。`upstream` 的完整版**优先委托上游** `skills` CLI 卸载（按 agent 批量）：`npx --yes skills@latest remove <names> -g -y -a <agent>`；当无法委托时（Node < 22.20、找不到 `npx`、上游非 0 退出）会打印告警并**回退直接删除**目录，并提示上游锁文件 `~/.agents/.skill-lock.json` 可能残留过期条目，可用 `npx skills@latest list` 核对。
+- **收尾**：处理完成后删除清单文件本身；**不会**删除目标目录本身，其它文件与空目录保持不动。
+- **幂等**：没有可删项时打印友好提示并以退出码 0 结束。若**清单缺失**，会告警「无清单，尽力而为」，此时**仅**在 `project-docs-workflow` 存在时询问是否删除它，其余 skill 一律不动。
+
 ## 直接复制（不使用 npm 安装器）
 
 也可以完全跳过安装器，手动把 `skills/` 下需要的内容复制进你的 skills 根目录：
@@ -77,6 +136,8 @@ skill 在引用依赖能力时，遵循两级解析：
 
 部分内置 skill 内容摘自 <https://github.com/mattpocock/skills>（MIT License，Copyright (c) 2026 Matt Pocock），详见 [`NOTICE`](./NOTICE)。
 
+上表中的 8 个上游依赖 skill 都可以改用完整版：安装时加 `--with-matt-skills` 即会从上游安装（见上文「可选：从上游安装『完整版』依赖 skill」）。
+
 ## 版本说明
 
 本包版本 `2.x` 与「模板生成 v2」对齐：模板结构与生成约定以 v2 为准。
@@ -91,7 +152,11 @@ MIT，见 [`LICENSE`](./LICENSE)。
 
 `project-docs-workflow` is an npm-packaged agent **skill bundle** for project documentation workflows: issue tracking, ADRs, PDRs, a terminology glossary, and the workflow that ties them together. The main skill is self-contained via internal `references/deps/*.md` fallbacks, and ships with lightweight dependency skills (trimmed from [mattpocock/skills](https://github.com/mattpocock/skills), MIT, Matt Pocock) plus a bundled `doc-opt` bonus skill.
 
-Install with `npx @tanlinfeng/project-docs-workflow` (defaults to `~/.agents/skills`; options: `--dir <path>`, `--force`, `--dry-run`, and the `check` subcommand). The installer **never overwrites** an existing skill of the same name — it skips it, preserving your version. `--force` overwrites only the main `project-docs-workflow` skill.
+Install with `npx @tanlinfeng/project-docs-workflow` (defaults to `~/.agents/skills`; options: `--dir <path>`, `--force`, `--dry-run`, `--with-matt-skills`, `--matt-agent <name>`, and the `check` / `uninstall` subcommands). The installer **never overwrites** an existing skill of the same name — it skips it, preserving your version. `--force` overwrites only the main `project-docs-workflow` skill.
+
+Every successful install writes an **install manifest** at `<target>/.project-docs-workflow.install.json` recording, per skill name, the `kind` (`main`/`lite`/`doc-opt`/`upstream`) and `action` (`installed`/`forced`/`skipped`), merged across re-installs. `uninstall [--dir <path>] [--dry-run] [--force]` removes **only** the names this package owns (`installed`/`forced`) and never touches names that pre-existed (`skipped`, decided by the record, not by guessing). On a TTY it asks once (`[y/N]`, default No); on a non-TTY it refuses unless `--force` is given. Lite/main/doc-opt copies are deleted directly; upstream full versions are removed via the `skills` CLI (`npx --yes skills@latest remove <names> -g -y -a <agent>`), falling back to direct deletion with a warning about a possibly-stale `~/.agents/.skill-lock.json` if delegation is impossible. `--dry-run` prints the plan and never prompts or writes; the manifest is deleted afterwards, the target directory itself is left in place.
+
+Optionally, `--with-matt-skills` installs the **full upstream** versions of the dependency skills from `mattpocock/skills` via the official `skills` CLI (`npx --yes skills@latest add mattpocock/skills -g -y -a <agent> -s ...`, requires Node >= 22.20). Without the flag, an interactive TTY gets a single prompt (default **No**); non-TTY/piped/CI runs never prompt. The 8 upstream-managed names are `grilling`, `grill-me`, `grill-with-docs`, `domain-modeling`, `tdd`, `deepwork`, `retro`, `improve-codebase-architecture`; `doc-opt` and the main skill are unaffected. Any name already present is left untouched and never sent upstream, and the installer re-checks afterwards, falling back to the bundled lite copy for anything still missing. If upstream can't run (Node too old, no `npx`, non-zero exit, network error), it warns and falls back — the install still exits 0. Upstream installs into the agent's global dir (`codex` → `~/.agents/skills`), so it cannot follow a custom `--dir` (a warning is printed).
 
 You can also copy `skills/*` directly into your skills root (skip any existing directory name, never overwrite); copying just `skills/project-docs-workflow` works standalone thanks to the internal ref fallbacks.
 

package/bin/install.js

@@ -4,11 +4,35 @@
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
+const { spawnSync } = require("child_process");
 
 const PKG_ROOT = path.join(__dirname, "..");
 const SKILLS_DIR = path.join(PKG_ROOT, "skills");
 const MAIN_SKILL = "project-docs-workflow";
 const DEFAULT_TARGET = path.join(os.homedir(), ".agents", "skills");
+// 安装清单：记录本包每次安装处理过的 skill 及其归属，供 uninstall 精确卸载。
+const MANIFEST_NAME = ".project-docs-workflow.install.json";
+const PKG_VERSION = require(path.join(PKG_ROOT, "package.json")).version;
+
+// 可选上游：mattpocock/skills 的完整版依赖 skill。
+// 官方安装器是 vercel-labs/skills 提供的 `skills` CLI（npm 包 skills），
+// 固定以 `-a <agent> -g` 安装到该 agent 的全局目录（codex 为 ~/.agents/skills）。
+const UPSTREAM_REPO = "mattpocock/skills";
+const UPSTREAM_DEFAULT_AGENT = "codex";
+// 上游安装器要求 Node >= 22.20（本项目不引入 semver 依赖，手工比较 major/minor）。
+const UPSTREAM_MIN_NODE = { major: 22, minor: 20 };
+// 仅这 8 个依赖 skill 属于上游集合；doc-opt 与主 skill 不属于。
+const MATT_DEP_NAMES = [
+  "grilling",
+  "grill-me",
+  "grill-with-docs",
+  "domain-modeling",
+  "tdd",
+  "deepwork",
+  "retro",
+  "improve-codebase-architecture",
+];
+const MATT_DEP_SET = new Set(MATT_DEP_NAMES);
 
 // 依赖 skill 的按名解析与 ref 兜底映射。
 // 顺序：先按名解析 <target>/<name>/SKILL.md，其次尝试 ref 兜底文件。
@@ -36,27 +60,55 @@ function usage() {
       "用法：",
       "  project-docs-workflow [install] [选项]   安装 skill 到目标目录（默认动作）",
       "  project-docs-workflow check   [选项]     检查依赖 skill 的解析状态",
+      "  project-docs-workflow uninstall [选项]   依据安装清单卸载本包安装的 skill",
       "",
       "选项：",
       "  --dir <path>   指定目标 skills 根目录（默认 ~/.agents/skills）",
-      "  --force        覆盖已存在的 project-docs-workflow（仅主 skill；依赖仍不覆盖）",
+      "  --force        覆盖已存在的 project-docs-workflow（仅主 skill；依赖仍不覆盖）；",
+      "                 uninstall 时为非交互确认（非 TTY 下必须显式传入）",
       "  --dry-run      仅打印将执行的操作，不实际写入",
+      "  --with-matt-skills",
+      "                 可选：改从上游 mattpocock/skills 安装依赖 skill 的完整版",
+      "                 （需 Node >= 22.20；无此 flag 时在交互式终端会询问一次，默认否）",
+      "  --matt-agent <name>",
+      "                 上游安装使用的 agent（默认 codex，落盘到其全局目录 ~/.agents/skills）",
       "  -h, --help     显示本帮助",
     ].join("\n")
   );
 }
 
 function parseArgs(argv) {
-  const opts = { command: "install", target: DEFAULT_TARGET, force: false, dryRun: false };
+  const opts = {
+    command: "install",
+    target: DEFAULT_TARGET,
+    force: false,
+    dryRun: false,
+    withMattSkills: false,
+    mattAgent: UPSTREAM_DEFAULT_AGENT,
+  };
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if (arg === "install" || arg === "check") {
+    if (arg === "install" || arg === "check" || arg === "uninstall") {
       opts.command = arg;
     } else if (arg === "--force") {
       opts.force = true;
     } else if (arg === "--dry-run") {
       opts.dryRun = true;
+    } else if (arg === "--with-matt-skills") {
+      opts.withMattSkills = true;
+    } else if (arg === "--matt-agent") {
+      const value = argv[++i];
+      if (!value) {
+        fail("--matt-agent 需要一个参数");
+      }
+      opts.mattAgent = value;
+    } else if (arg.startsWith("--matt-agent=")) {
+      const value = arg.slice("--matt-agent=".length);
+      if (!value) {
+        fail("--matt-agent 需要一个参数");
+      }
+      opts.mattAgent = value;
     } else if (arg === "--dir") {
       const value = argv[++i];
       if (!value) {
@@ -101,6 +153,104 @@ function isFile(p) {
   }
 }
 
+// —— 上游（mattpocock/skills）相关辅助 ——
+
+function existsAt(p) {
+  return isDir(p) || isFile(p);
+}
+
+// 手工解析 process.versions.node 并与 22.20 比较（不引入 semver 依赖）。
+function nodeMeetsUpstream() {
+  const parts = String(process.versions.node).split(".");
+  const major = parseInt(parts[0], 10) || 0;
+  const minor = parseInt(parts[1], 10) || 0;
+  if (major !== UPSTREAM_MIN_NODE.major) {
+    return major > UPSTREAM_MIN_NODE.major;
+  }
+  return minor >= UPSTREAM_MIN_NODE.minor;
+}
+
+// 同步等待若干毫秒（用于 stdin 非阻塞时的短暂重试，避免忙等）。
+function sleepSync(ms) {
+  try {
+    const sab = new SharedArrayBuffer(4);
+    Atomics.wait(new Int32Array(sab), 0, 0, ms);
+  } catch (e) {
+    /* 忽略：无法等待时直接继续 */
+  }
+}
+
+// 同步读取 stdin 的一行。仅在已确认 stdin 为 TTY 时调用。
+function readLineSync() {
+  const buf = Buffer.alloc(1);
+  let line = "";
+  for (;;) {
+    let bytesRead = 0;
+    try {
+      bytesRead = fs.readSync(0, buf, 0, 1, null);
+    } catch (err) {
+      if (err && err.code === "EAGAIN") {
+        sleepSync(10);
+        continue;
+      }
+      if (err && (err.code === "EOF" || err.code === "ENXIO")) {
+        return line;
+      }
+      throw err;
+    }
+    if (bytesRead === 0) {
+      return line;
+    }
+    const ch = buf.toString("utf8", 0, 1);
+    if (ch === "\n") {
+      return line;
+    }
+    if (ch !== "\r") {
+      line += ch;
+    }
+  }
+}
+
+function npxCommand() {
+  return process.platform === "win32" ? "npx.cmd" : "npx";
+}
+
+// 组装上游命令参数（不含可执行文件名），以便打印或执行。
+function buildUpstreamArgs(opts, names) {
+  return ["--yes", "skills@latest", "add", UPSTREAM_REPO, "-g", "-y", "-a", opts.mattAgent, "-s"].concat(
+    names
+  );
+}
+
+function quoteArg(arg) {
+  return /[\s"]/.test(arg) ? '"' + arg.replace(/"/g, '\\"') + '"' : arg;
+}
+
+function upstreamCommandString(opts, names) {
+  return [npxCommand()].concat(buildUpstreamArgs(opts, names)).map(quoteArg).join(" ");
+}
+
+// 决定是否启用上游安装。仅在 install 且非 dry-run、且 stdin/stdout 均为 TTY 时提示。
+function decideUpstream(opts) {
+  if (opts.withMattSkills) {
+    return true;
+  }
+  if (opts.command !== "install" || opts.dryRun) {
+    return false;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return false;
+  }
+  process.stdout.write("是否从上游安装依赖 skill 的完整版（mattpocock/skills）？[y/N] ");
+  let answer = "";
+  try {
+    answer = readLineSync().trim().toLowerCase();
+  } catch (e) {
+    answer = "";
+  }
+  return answer === "y" || answer === "yes";
+}
+
 // 列出 skills/ 下的所有子目录名；缺失时返回空数组（由调用方给出提示）。
 function listSkillDirs() {
   if (!isDir(SKILLS_DIR)) {
@@ -123,6 +273,130 @@ function copySkill(name, dest, dryRun) {
   console.log("  ✓ 已安装 " + name + " → " + dest);
 }
 
+// —— 安装清单（manifest）——
+
+function manifestPath(target) {
+  return path.join(target, MANIFEST_NAME);
+}
+
+function loadManifest(target) {
+  const p = manifestPath(target);
+  if (!isFile(p)) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (data && typeof data === "object" && data.entries && typeof data.entries === "object") {
+      return data;
+    }
+  } catch (e) {
+    /* 忽略：清单损坏时按缺失处理 */
+  }
+  return null;
+}
+
+// 合并新旧条目：归属一旦记在本包名下（installed/forced），后续因「已存在」而 skip 时不被降级；
+// 而初次即为 skipped（安装时已存在、非本包安装）的名字始终保持 skipped。
+function mergeEntries(prev, fresh) {
+  const out = Object.assign({}, prev);
+  for (const name of Object.keys(fresh)) {
+    const f = fresh[name];
+    const p = out[name];
+    if (f.action === "skipped" && p && p.action !== "skipped") {
+      continue;
+    }
+    out[name] = f;
+  }
+  return out;
+}
+
+function writeManifest(target, entries) {
+  const p = manifestPath(target);
+  const data = {
+    version: PKG_VERSION,
+    target: path.resolve(target),
+    updatedAt: new Date().toISOString(),
+    entries,
+  };
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n");
+  console.log("已写入安装清单：" + p);
+}
+
+function removeManifest(target) {
+  const p = manifestPath(target);
+  if (!isFile(p)) {
+    return;
+  }
+  try {
+    fs.rmSync(p, { force: true });
+    console.log("已删除安装清单：" + p);
+  } catch (e) {
+    console.log("⚠ 无法删除安装清单：" + p + "（" + e.message + "）");
+  }
+}
+
+// 依赖 skill 的 kind：doc-opt 单列，其余依赖（含其它 skills/* 目录）视为 lite。
+function depKind(name) {
+  return name === "doc-opt" ? "doc-opt" : "lite";
+}
+
+// —— 上游卸载命令组装 ——
+
+function buildUpstreamRemoveArgs(names, agent) {
+  return ["--yes", "skills@latest", "remove"].concat(names).concat(["-g", "-y", "-a", agent]);
+}
+
+function upstreamRemoveString(names, agent) {
+  return [npxCommand()].concat(buildUpstreamRemoveArgs(names, agent)).map(quoteArg).join(" ");
+}
+
+function groupByAgent(list) {
+  const map = new Map();
+  for (const item of list) {
+    if (!map.has(item.agent)) {
+      map.set(item.agent, []);
+    }
+    map.get(item.agent).push(item.name);
+  }
+  return map;
+}
+
+// 优先委托上游 skills CLI 卸载；不可用时（Node 过旧 / npx 缺失 / 非 0 退出）回退直接删除目录。
+function removeUpstreamWithFallback(names, agent, target) {
+  const directFallback = (reason) => {
+    console.log("  ⚠ " + reason);
+    for (const name of names) {
+      const dest = path.join(target, name);
+      if (existsAt(dest)) {
+        fs.rmSync(dest, { recursive: true, force: true });
+        console.log("  ✓ 已直接删除 " + name);
+      } else {
+        console.log("  - 未找到 " + name + "（跳过）");
+      }
+    }
+    console.log(
+      "  注意：上游锁文件 ~/.agents/.skill-lock.json 可能残留过期条目；可用 `npx skills@latest list` 核对。"
+    );
+  };
+
+  if (!nodeMeetsUpstream()) {
+    directFallback("当前 Node " + process.versions.node + " < 22.20，无法运行上游卸载器。");
+    return;
+  }
+  console.log("  将执行：" + upstreamRemoveString(names, agent));
+  const res = spawnSync(npxCommand(), buildUpstreamRemoveArgs(names, agent), {
+    stdio: "inherit",
+    env: Object.assign({}, process.env, { DISABLE_TELEMETRY: "1", DO_NOT_TRACK: "1" }),
+  });
+  if (res.error) {
+    directFallback("上游卸载无法执行（" + (res.error.code || res.error.message) + "）。");
+  } else if (res.status !== 0) {
+    directFallback("上游卸载失败（退出码 " + res.status + "）。");
+  } else {
+    console.log("  ✓ 已通过 skills CLI 卸载：" + names.join("、"));
+  }
+}
+
 function runInstall(opts) {
   const dirs = listSkillDirs();
   if (dirs === null || dirs.length === 0) {
@@ -136,6 +410,15 @@ function runInstall(opts) {
     fail("缺少主 skill 目录：skills/" + MAIN_SKILL);
   }
 
+  // 是否启用上游完整版安装（可能触发一次交互式询问，仅限 TTY + install + 非 dry-run）。
+  const upstreamEnabled = decideUpstream(opts);
+
+  const nowIso = new Date().toISOString();
+  const freshEntries = {};
+  const record = (name, entry) => {
+    freshEntries[name] = Object.assign({ at: nowIso }, entry);
+  };
+
   const target = opts.target;
   console.log("目标目录：" + target + (opts.dryRun ? "（dry-run，不会写入）" : ""));
   if (!opts.dryRun) {
@@ -148,6 +431,7 @@ function runInstall(opts) {
   console.log("主 skill：" + MAIN_SKILL);
   if (mainExists && !opts.force) {
     console.log("  同名 skill 已存在，保留用户版本：" + MAIN_SKILL + "（如需覆盖请加 --force）");
+    record(MAIN_SKILL, { kind: "main", action: "skipped" });
   } else if (mainExists && opts.force) {
     if (opts.dryRun) {
       console.log("  [dry-run] 将覆盖 " + MAIN_SKILL + " → " + mainDest);
@@ -155,8 +439,59 @@ function runInstall(opts) {
       fs.rmSync(mainDest, { recursive: true, force: true });
       copySkill(MAIN_SKILL, mainDest, false);
     }
+    record(MAIN_SKILL, { kind: "main", action: "forced" });
   } else {
     copySkill(MAIN_SKILL, mainDest, opts.dryRun);
+    record(MAIN_SKILL, { kind: "main", action: "installed" });
+  }
+
+  // 可选：先从上游安装 8 个依赖 skill 的完整版。
+  // upstreamHandled 记录「本次由上游负责」的名字，这些名字不再复制本包轻量版。
+  let upstreamHandled = new Set();
+  if (upstreamEnabled) {
+    console.log("上游依赖 skill（mattpocock/skills 完整版）：");
+    if (opts.target !== DEFAULT_TARGET) {
+      console.log(
+        "  ⚠ 检测到自定义 --dir：上游安装固定使用 agent 全局目录（" +
+          opts.mattAgent +
+          " → ~/.agents/skills），无法跟随 --dir；--dir 下的轻量版仍按原逻辑处理。"
+      );
+    }
+    const preexisting = MATT_DEP_NAMES.filter((name) => existsAt(path.join(target, name)));
+    const missing = MATT_DEP_NAMES.filter((name) => preexisting.indexOf(name) === -1);
+    if (preexisting.length > 0) {
+      console.log("  已存在，保留且不提交上游：" + preexisting.join("、"));
+    }
+    if (missing.length === 0) {
+      console.log("  8 个依赖 skill 均已在目标目录，无需上游安装。");
+    } else if (opts.dryRun) {
+      console.log("  [dry-run] 将执行：" + upstreamCommandString(opts, missing));
+      upstreamHandled = new Set(missing);
+    } else if (!nodeMeetsUpstream()) {
+      console.log(
+        "  ⚠ 当前 Node " +
+          process.versions.node +
+          " < 22.20，无法运行上游安装器；将对缺失项回退轻量版。"
+      );
+    } else {
+      console.log("  将执行：" + upstreamCommandString(opts, missing));
+      const res = spawnSync(npxCommand(), buildUpstreamArgs(opts, missing), {
+        stdio: "inherit",
+        env: Object.assign({}, process.env, { DISABLE_TELEMETRY: "1", DO_NOT_TRACK: "1" }),
+      });
+      if (res.error) {
+        console.log(
+          "  ⚠ 上游安装无法执行（" +
+            (res.error.code || res.error.message) +
+            "）；将对缺失项回退轻量版。"
+        );
+      } else if (res.status !== 0) {
+        console.log("  ⚠ 上游安装失败（退出码 " + res.status + "）；将对缺失项回退轻量版。");
+      }
+      // 复核：仅把「本次新增」的名字标记为已由上游处理；已存在者走下面的保留逻辑。
+      const nowPresent = MATT_DEP_NAMES.filter((name) => existsAt(path.join(target, name)));
+      upstreamHandled = new Set(nowPresent.filter((name) => missing.indexOf(name) !== -1));
+    }
   }
 
   // 其他依赖 skill：永不覆盖。
@@ -166,21 +501,152 @@ function runInstall(opts) {
     console.log("  （未发现其他目录）");
   }
   for (const name of others) {
+    if (upstreamEnabled && MATT_DEP_SET.has(name) && upstreamHandled.has(name)) {
+      console.log(
+        (opts.dryRun
+          ? "  [dry-run] 将由上游安装完整版，跳过轻量版："
+          : "  已由上游安装完整版，跳过轻量版：") + name
+      );
+      record(name, { kind: "upstream", action: "installed", agent: opts.mattAgent });
+      continue;
+    }
     const dest = path.join(target, name);
     if (isDir(dest) || isFile(dest)) {
       console.log("  同名 skill 已存在，保留用户版本：" + name);
+      record(name, { kind: depKind(name), action: "skipped" });
       continue;
     }
     copySkill(name, dest, opts.dryRun);
+    record(name, { kind: depKind(name), action: "installed" });
   }
 
   if (opts.dryRun) {
     console.log("dry-run 完成，未写入任何文件。");
   } else {
+    const prev = loadManifest(target);
+    const merged = mergeEntries(prev ? prev.entries : {}, freshEntries);
+    writeManifest(target, merged);
     console.log("安装完成。");
   }
 }
 
+function confirmUninstall(opts) {
+  // 返回 "yes"|"no"|"refuse"。--force 直接视为 yes。
+  if (opts.force) {
+    return "yes";
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return "refuse";
+  }
+  process.stdout.write("确认卸载本包安装的 skill？[y/N] ");
+  let answer = "";
+  try {
+    answer = readLineSync().trim().toLowerCase();
+  } catch (e) {
+    answer = "";
+  }
+  return answer === "y" || answer === "yes" ? "yes" : "no";
+}
+
+function runUninstall(opts) {
+  const target = opts.target;
+  const manifest = loadManifest(target);
+
+  // 无清单：尽力而为，仅处理主 skill。
+  if (!manifest) {
+    console.log("⚠ 未找到安装清单：" + manifestPath(target) + "（无清单，尽力而为）");
+    const mainDest = path.join(target, MAIN_SKILL);
+    if (!existsAt(mainDest)) {
+      console.log("目标目录中不存在 " + MAIN_SKILL + "，无需卸载。");
+      process.exit(0);
+    }
+    console.log("仅处理主 skill：" + MAIN_SKILL + "（其余 skill 保持不动）");
+    if (opts.dryRun) {
+      console.log("  [dry-run] 将删除 " + MAIN_SKILL + " → " + mainDest);
+      console.log("dry-run 完成，未写入任何文件。");
+      process.exit(0);
+    }
+    const decision = confirmUninstall(opts);
+    if (decision === "refuse") {
+      console.log("非交互式终端：为避免误删，已拒绝卸载。如确认请显式传入 --force。");
+      process.exit(1);
+    }
+    if (decision === "no") {
+      console.log("已取消卸载。");
+      process.exit(0);
+    }
+    fs.rmSync(mainDest, { recursive: true, force: true });
+    console.log("  ✓ 已删除 " + MAIN_SKILL);
+    console.log("清单缺失：其余 skill 一律保持不动。");
+    process.exit(0);
+  }
+
+  // 依据清单归属构建计划：record 说「本包安装」才删，skipped 永不删。
+  const entries = manifest.entries || {};
+  const removeLocal = [];
+  const removeUpstream = [];
+  const keep = [];
+  for (const name of Object.keys(entries).sort()) {
+    const e = entries[name] || {};
+    if (e.action === "installed" || e.action === "forced") {
+      if (e.kind === "upstream") {
+        removeUpstream.push({ name, agent: e.agent || UPSTREAM_DEFAULT_AGENT });
+      } else {
+        removeLocal.push(name);
+      }
+    } else {
+      // skipped 或未知状态：一律保留。
+      keep.push(name);
+    }
+  }
+
+  console.log("目标目录：" + target + (opts.dryRun ? "（dry-run，不会写入）" : ""));
+  const allRemove = removeLocal.concat(removeUpstream.map((u) => u.name));
+  console.log("将移除（本包安装）：" + (allRemove.length ? allRemove.join("、") : "（无）"));
+  for (const name of keep) {
+    console.log("保留（安装时已存在，非本包安装）：" + name);
+  }
+
+  if (allRemove.length === 0) {
+    console.log("没有需要移除的 skill（清单中无本包安装项）。");
+    process.exit(0);
+  }
+
+  if (opts.dryRun) {
+    for (const name of removeLocal) {
+      console.log("  [dry-run] 将删除 " + name + " → " + path.join(target, name));
+    }
+    for (const [agent, names] of groupByAgent(removeUpstream)) {
+      console.log("  [dry-run] 上游完整版（" + agent + "）：" + upstreamRemoveString(names, agent));
+    }
+    console.log("  [dry-run] 将删除安装清单：" + manifestPath(target));
+    console.log("dry-run 完成，未写入任何文件。");
+    process.exit(0);
+  }
+
+  const decision = confirmUninstall(opts);
+  if (decision === "refuse") {
+    console.log("非交互式终端：为避免误删，已拒绝卸载。如确认请显式传入 --force。");
+    process.exit(1);
+  }
+  if (decision === "no") {
+    console.log("已取消卸载。");
+    process.exit(0);
+  }
+
+  for (const name of removeLocal) {
+    fs.rmSync(path.join(target, name), { recursive: true, force: true });
+    console.log("  ✓ 已删除 " + name);
+  }
+  for (const [agent, names] of groupByAgent(removeUpstream)) {
+    console.log("上游完整版（" + agent + "）：");
+    removeUpstreamWithFallback(names, agent, target);
+  }
+  removeManifest(target);
+  console.log("卸载完成。");
+  process.exit(0);
+}
+
 function runCheck(opts) {
   const target = opts.target;
   console.log("检查依赖 skill 解析状态（目标目录：" + target + "）：");
@@ -219,6 +685,8 @@ function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.command === "check") {
     runCheck(opts);
+  } else if (opts.command === "uninstall") {
+    runUninstall(opts);
   } else {
     runInstall(opts);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanlinfeng/project-docs-workflow",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "publishConfig": {
     "access": "public"
   },