@nathan33/nao-skill 0.1.0 → 0.3.0

package/README.md

@@ -139,20 +139,23 @@ PM 是任务状态权威，以状态机驱动执行：
 .agents/scripts/ui-tokens-check.sh <repo>             # 扫 UI 硬编码色值（绕过 Design Tokens）
 ```
 
-## 安装（npm 发布）
+## 安装与升级（npm 发布）
 
-发布为 **`@nathan33/nao-skill`**，提供 `nao-skill install` CLI 一键接入项目：
+发布为 **`@nathan33/nao-skill`**，CLI `nao-skill` 一键接入项目：
 
 ```bash
 npm install -g @nathan33/nao-skill          # 全局安装 CLI
 # 或在任意项目里直接：npx @nathan33/nao-skill install
 
-nao-skill install                            # 安装到当前目录
-nao-skill install /path/to/proj --force      # 指定目录；--force 覆盖同名文件
+nao-skill install                            # 安装/合并到当前目录（保守，不覆盖已有）
+nao-skill install /path/to/proj --force      # 指定目录；--force 备份后覆盖同名
+nao-skill update                             # 升级已有安装（源优先 + 清理废弃 + 留自定义）
 ```
 
+- **install（保守合并）**：目标已有同名文件默认保留项目既有；`--force` 覆盖；写入 `.agents/.nao-version` 版本标记。
+- **update（升级）**：机制文件源优先覆盖（项目定制应放 `AGENTS.md`）、备份清理已知废弃路径（如旧版 `skills/checklists/`，防 skill 冲突）到 `.agents/.nao-obsolete/`、保留项目自定义文件。
+- **旧版检测**：install 发现版本落后或废弃路径 → 提示运行 `update`。
 - **安装内容**：`.agents/` 全套（角色卡 / 技能 / 交付清单 / 协议 / roles.yaml / 工具链 / 模板）+ 生成 `AGENTS.md`（已存在则提示按 §七 合并，不覆盖）。
-- **合并策略**：目标已有同名文件默认保留项目既有（避免覆盖自定义）；`--force` 备份后覆盖。
 - **发布**：`npm publish --access public`（scope 包需 `--access public`）。
 
 ## 目录结构

package/bin/nao-skill.js

@@ -17,6 +17,7 @@
  *   bash .agents/scripts/nao-fleet.sh check / ensure arch rd-fe ...
  *   角色卡经 fleet 拉起时 --append-system-prompt 注入；checklists 按需读取
  */
+import { execFileSync } from 'node:child_process';
 import {
   cpSync,
   existsSync,
@@ -34,6 +35,11 @@ const PKG = JSON.parse(readFileSync(new URL('../package.json', import.meta.url),
 const SRC = fileURLToPath(new URL('../.agents', import.meta.url));
 const TEMPLATE_AGENTS = fileURLToPath(new URL('../.agents/templates/AGENTS.md.example', import.meta.url));
 
+// 已知废弃路径（相对项目根）：旧版遗留，update 时备份后移除
+const OBSOLETE = ['.agents/skills/checklists'];
+// 安装版本标记（install/update 写入，供下次检测升级）
+const VERSION_FILE = '.agents/.nao-version';
+
 const log = (...a) => console.log('[nao-skill]', ...a);
 const warn = (...a) => console.error('[nao-skill]', ...a);
 
@@ -59,6 +65,67 @@ function copyDir(src, dst, force) {
   return { copied, skipped, overwritten };
 }
 
+// 已知 pi 插件（nao 舰队生态），name → npm 包
+const PI_PLUGINS = {
+  intercom:   { pkg: 'pi-intercom',            desc: '多会话协作（舰队机制核心依赖）' },
+  'ask-me':   { pkg: 'pi-ask-me',              desc: '提问/访谈工具' },
+  subagents:  { pkg: 'pi-subagents',           desc: '子代理委派' },
+  'web-access': { pkg: 'pi-web-access',        desc: '网页访问' },
+  codegraph:  { pkg: '@sean_pedersen/pi-codegraph', desc: 'CodeGraph 代码定位（pi 集成）' },
+};
+
+function piSettingsPath() {
+  return join(process.env.HOME || process.env.USERPROFILE || '', '.pi', 'agent', 'settings.json');
+}
+
+function readPackages() {
+  try {
+    const d = JSON.parse(readFileSync(piSettingsPath(), 'utf8'));
+    return Array.isArray(d.packages) ? d.packages : [];
+  } catch {
+    return [];
+  }
+}
+
+function installedPlugins() {
+  const pkgs = readPackages();
+  const out = {};
+  for (const [name, { pkg }] of Object.entries(PI_PLUGINS)) {
+    out[name] = pkgs.includes(`npm:${pkg}`) || pkgs.includes(pkg);
+  }
+  return out;
+}
+
+function pluginsList() {
+  const installed = installedPlugins();
+  log(`pi 插件状态（settings: ${piSettingsPath()}）`);
+  for (const [name, { pkg, desc }] of Object.entries(PI_PLUGINS)) {
+    console.log(`  ${installed[name] ? '✓' : '·'} ${name.padEnd(11)} ${pkg.padEnd(26)} ${desc}${installed[name] ? '' : '（缺失）'}`);
+  }
+  console.log('\n安装: nao-skill plugins install <name...> | plugins install-all');
+}
+
+function pluginsInstall(names, all = false) {
+  const targets = all ? Object.keys(PI_PLUGINS) : names;
+  const todo = [];
+  for (const n of targets) {
+    const p = PI_PLUGINS[n];
+    if (!p) { warn(`未知插件: ${n}（可用: ${Object.keys(PI_PLUGINS).join(', ')}）`); continue; }
+    if (installedPlugins()[n]) { log(`已安装: ${n}`); continue; }
+    todo.push([n, p]);
+  }
+  if (!todo.length) { log('全部插件已就绪。'); return; }
+  for (const [n, p] of todo) {
+    log(`安装 ${n} → pi install npm:${p.pkg} ...`);
+    try {
+      execFileSync('pi', ['install', `npm:${p.pkg}`], { stdio: 'inherit' });
+      log(`✓ ${n} 安装完成（重启 pi 会话后生效）`);
+    } catch (e) {
+      warn(`✗ ${n} 安装失败: ${e.message}（确认 pi 已安装且在 PATH）`);
+    }
+  }
+}
+
 function install(target, force) {
   if (!existsSync(SRC)) {
     warn(`包内 .agents 缺失：${SRC}（发布物损坏？）`);
@@ -77,6 +144,16 @@ function install(target, force) {
     }
   }
 
+  // 版本标记 + 升级/废弃检测
+  const prev = readInstalledVersion(target);
+  writeFileSync(join(target, VERSION_FILE), PKG.version);
+  if (prev && prev !== PKG.version) {
+    warn(`检测到旧版安装（v${prev} → v${PKG.version}）：建议运行 nao-skill update 升级机制文件。`);
+  }
+  for (const p of detectObsolete(target)) {
+    warn(`发现废弃路径 ${p}（旧版遗留，可能导致 skill 冲突）：建议运行 nao-skill update 清理。`);
+  }
+
   const agentsMd = join(target, 'AGENTS.md');
   if (!existsSync(agentsMd)) {
     let tpl = readFileSync(TEMPLATE_AGENTS, 'utf8');
@@ -95,11 +172,55 @@ function install(target, force) {
   log('  角色卡：.agents/prompts/ · 技能：.agents/skills/ · 交付清单：.agents/checklists/');
 }
 
+function update(target) {
+  // 源优先升级：机制文件以包为权威（项目定制应放 AGENTS.md，不在机制文件里改）
+  const dst = join(target, '.agents');
+  if (!existsSync(dst)) {
+    log('目标无 .agents/，直接完整安装。');
+    return install(target, false);
+  }
+  let overwritten = 0;
+  for (const e of readdirSync(SRC)) {
+    const s = join(SRC, e);
+    const d = join(dst, e);
+    rmSync(d, { recursive: true, force: true });
+    cpSync(s, d, { recursive: true });
+    overwritten++;
+  }
+  // 清理已知废弃路径（先备份到 .agents/.nao-obsolete/）
+  for (const p of OBSOLETE) {
+    const full = join(target, p);
+    if (existsSync(full)) {
+      const bakDir = join(dst, '.nao-obsolete');
+      mkdirSync(bakDir, { recursive: true });
+      cpSync(full, join(bakDir, `${basename(p)}-${Date.now()}`), { recursive: true });
+      rmSync(full, { recursive: true, force: true });
+      log(`废弃路径已备份并移除: ${p}（备份于 .agents/.nao-obsolete/）`);
+    }
+  }
+  // 项目自定义文件保留（源没有的不动）
+  writeFileSync(join(target, VERSION_FILE), PKG.version);
+  log(`✔ 升级完成：机制文件以 v${PKG.version} 为准，项目自定义已保留。`);
+}
+
+function readInstalledVersion(target) {
+  try { return readFileSync(join(target, VERSION_FILE), 'utf8').trim(); } catch { return null; }
+}
+
+function detectObsolete(target) {
+  return OBSOLETE.filter((p) => existsSync(join(target, p)));
+}
+
 function help() {
   console.log(`nao-skill v${PKG.version} — nao 多角色 AI 开发舰队安装器
 
 用法:
   nao-skill install [dir] [--force]   安装/合并 .agents/ 到目标项目（默认当前目录）
+  nao-skill install --plugins          项目接入时顺带安装 pi 舰队插件
+  nao-skill update [dir]              升级已有安装：源优先覆盖 + 清理废弃路径 + 保留项目自定义
+  nao-skill plugins list              列出已知 pi 插件与安装状态
+  nao-skill plugins install <名...>   安装指定插件（intercom/ask-me/subagents/web-access/codegraph）
+  nao-skill plugins install-all       安装全部舰队插件
   nao-skill --version                 显示版本
   nao-skill --help                    显示本帮助
 
@@ -124,18 +245,47 @@ if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
 } else if (cmd === 'install' || cmd === 'i') {
   let target = process.cwd();
   let force = false;
+  let withPlugins = false;
   const rest = args.slice(1);
   for (let i = 0; i < rest.length; i++) {
     if (rest[i] === '--force' || rest[i] === '-f') force = true;
+    else if (rest[i] === '--plugins') withPlugins = true;
     else if (rest[i] === '--target') target = resolve(rest[++i]);
     else if (!rest[i].startsWith('-')) target = resolve(rest[i]);
     else { warn(`未知参数: ${rest[i]}`); process.exit(2); }
   }
-  if (!existsSync(target) || !statIsDir(target)) {
+  if (!statIsDir(target)) {
     warn(`目标目录无效: ${target}`);
     process.exit(2);
   }
   install(target, force);
+  if (withPlugins) pluginsInstall([], true);
+} else if (cmd === 'plugins' || cmd === 'plugin') {
+  const sub = args[1];
+  const rest = args.slice(2);
+  if (sub === 'list' || sub === 'ls' || !sub) {
+    pluginsList();
+  } else if (sub === 'install' || sub === 'add') {
+    pluginsInstall(rest);
+  } else if (sub === 'install-all' || sub === 'installAll') {
+    pluginsInstall([], true);
+  } else {
+    warn(`未知插件命令: ${sub}（可用: list / install / install-all）`);
+    process.exit(2);
+  }
+} else if (cmd === 'update' || cmd === 'u') {
+  let target = process.cwd();
+  const rest = args.slice(1);
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--target') target = resolve(rest[++i]);
+    else if (!rest[i].startsWith('-')) target = resolve(rest[i]);
+    else { warn(`未知参数: ${rest[i]}`); process.exit(2); }
+  }
+  if (!statIsDir(target)) {
+    warn(`目标目录无效: ${target}`);
+    process.exit(2);
+  }
+  update(target);
 } else {
   warn(`未知命令: ${cmd}（可用: install）`);
   process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {