@yottameta/yotta-memory 0.19.0 → 0.20.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## v0.20.1 (2026-10-01)
+
+- 安装器卫生批次：`bin/install.js` / `install.sh` 统一（未知参数报错 exit 2、`--help` / `--version`、残留清理白名单、嵌套载荷保留）；由模板单一真源渲染，接入漂移门禁。
+
+## v0.20.0 (2026-09-30)
+
+上下文分页 P2.5：先修 `memory.hook` 的 PREF 驱逐空转，再新增 `context.paging` 预算调用点。
+
+- 修复 `memory.hook` 对画像段落驱逐空转：hook / paging 决策实际生效时，画像段落按实时可读条目渲染并套用同一套过滤；自我接入档案不进候选、不可驱逐；无 provider 时仍读 `profile.md`，基线输出逐字节不变。
+- 修复 `profile` 只读单层目录：`private/<owner>/{prefs,bounds,commits}/YYYY/MM/` 里的分层条目现在也会进入静态画像；`context` 的实时画像路径不受影响。
+- 新增 `context.paging`：仅在用户显式传 `--budget` 时调用；`memory.hook` 先过滤，`context.paging` 再排序 / 分页。`drop` 始终安全应用；`order` 仅在 `complete:true` 且候选未超过 500 时应用；候选集外文件只记 note、不进入输出。
+- `context --json` 新增 `paging` 块（`status` / `provider_id` / `applied` / `dropped` / `ordered` / `truncated` / `budget` / `used` / `note`）；文本仅在 `context.paging` 实际被声明或触发时增加状态行；审计沿用 `provider-audit.jsonl`，不含记忆正文。
+- provider 子进程透传 `YOTTA_LICENSE_HOME` / `YOTTA_LICENSE_KEYS_DIR` / `YOTTA_LICENSE_BASE_URL` / `YOTTA_LICENSE_SERVER_ID`，与路线 B 授权隔离环境一致。
+- 协议文档升级 v1.1，新增 `context.paging` 请求 / 响应 / 回落说明。
+
 ## v0.19.0 (2026-09-28)
 - 新增扩展提供方（provider）装载点：`context` 可选调用本地 provider（capability `memory.hook`），在权限过滤后的候选集内驱逐条目；BOUND / COMMIT 与身份画像不可驱逐，预算 / 去重 / 宽限仍由引擎掌控。
 - 未配置 / 未授权 / 超时 / 非法输出一律 fail-open 回普通记忆；`provider.json` 非法只记状态、不阻断。

package/README.md

@@ -107,7 +107,7 @@ Each agent has a globally unique agent ID: it is the ownership key for private m
 ### Profile & start-of-work context (v0.6.0 + v0.9.0 + v0.14.0)
 
 - **profile**: aggregates `private/<owner>/` PREF / BOUND / COMMIT verbatim, grouped by type + subject + tags, written to `profile.md`; the engine infers nothing — profile conclusions are formed internally by the AI per the "memory discipline", never pasted as labels.
-- **context**: one-shot start-of-work package — multi-agent integration rules + identity + long-term summaries first (`consolidate` output) + user profile digest + optional task-focused memory (`--focus`) + time-ordered recent corridor + deduplicated high-value backfill + boundary reminders + commitments/anchors + session loop contract; supports `--budget` for dynamic memory and `--explain` selection trace.
+- **context**: one-shot start-of-work package — multi-agent integration rules + identity + long-term summaries first (`consolidate` output) + user profile digest + optional task-focused memory (`--focus`) + time-ordered recent corridor + deduplicated high-value backfill + boundary reminders + commitments/anchors + session loop contract; supports `--budget` for dynamic memory and `--explain` selection trace. Optional local providers can add `memory.hook` filtering and, when `--budget` is explicit, `context.paging` ordering/paging; `context --json` returns `hook` and `paging` blocks.
 - **Memory discipline**: SKILL.md embeds a rule layer (type red lines / proactive trigger capture / know-the-user three stages / psychological grounding & alignment / bottom lines / host isolation / anti-patterns).
 
 ### Retrieval: semantic search (v0.8.0 + v0.9.0 embedding)

package/README.zh-CN.md

@@ -22,7 +22,7 @@
 </p>
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
-> 🆕 **v0.19.0（扩展提供方装载点 + context JSON）**：`context` 可选调用用户显式配置的本地扩展提供方（capability `memory.hook`）参与「哪些记忆进上下文」——提供方只能驱逐本次候选集内条目，BOUND / COMMIT 与身份画像不可驱逐，预算 / 去重 / 宽限仍由引擎掌控；未配置 / 未授权 / 超时 / 非法输出一律回普通记忆。`context --json` 输出结构化 JSON（`schema` / `hook` / `text`）。配置与协议见 `references/provider-protocol.md`。
+> 🆕 **v0.20.0（上下文分页 + 画像驱逐修复）**：`memory.hook` 的 PREF 驱逐空转已修复——hook / paging 决策生效时，画像段落按实时可读条目渲染并套用同一套过滤；自我接入档案不进候选、不可驱逐。新增 `context.paging`：仅在显式 `--budget` 时调用，hook 先过滤、paging 再排序与分页；`drop` 始终安全应用，`order` 仅在 `complete:true` 且未截断时应用。`context --json` 新增 `paging` 块，`--explain` 增加 `[paging]` 轨迹。配置与协议见 `references/provider-protocol.md`。
 > 🆕 **v0.18.1（蒸馏溯源 + 日期绝对化 + 巩固标记 + 规则晋升建议 + 写入纪律）**：`distill` 新增分类型提取清单（事件 / 教训 / 待办 / 成长 / 规则边界 / 其他）+ 逐条 `[溯源: 文件#L<a>-L<b>]` + 实测质量指标 + 跳过与边界，`--json` 输出结构化报告；`consolidate` 摘要按条目 `created` 把「昨天 / 上周 / 本月 / 今年」写成绝对日期，归档副本写入巩固标记（`--undo` 剥离还原）；`maintain --rules` 只读给出「重复踩坑 → 建议升级为规则」（默认阈值 3，不自动写 BOUND）；记忆守则新增冲突权威顺序 6 层与写入纪律 3 条。
 
 > 🆕 **v0.18.0（命中打点 + 容量水位 + consolidate 提案闸门 + 上下文压缩审计）**：`recall` / `explain` / `feedback --useful` / `context` 记录本地命中元数据（`hit_days` 默认保留 90 天；`hit_queries` 只存查询 8 位指纹、最多 12 槽，不存原文；随文件加密 / 备份 / 导出），`config set usage_enabled false` 或命令级 `--no-usage` 可关；只读命令与跨 owner 私密条目不写。`maintain --capacity` 只读报告容量水位、30 / 90 天活跃度、LRU / LFU 淘汰候选（冷却期 30 天 + immutable / BOUND / evergreen / pinned 豁免）与晋升建议（≥3 次命中且 ≥3 个不同查询，只出建议命令）；`archive` 默认豁免冷却期与标签常青，`--force` 可显式覆盖。`consolidate` 默认等价 `--propose`（结构化报告 + `--json`），`--apply` 交互式需确认串、非交互必须 `--yes`；首次启用显示一次数据生命周期说明。`doctor` 规模体检新增 `scale_info_*` 与逐项 `ok / info / warning` 分级（`doctor.ok` 仍只看 critical）。新增 `context --audit [--from <文件|->] [--json] [--gate N]`：核对被压缩掉的内容是否已落盘，输出未落盘清单与 `remember` 建议命令，只读、不自动补写。`archive --dry-run` 只预览不改库（不动文件 / 不建事务快照 / 不写审计），无候选时不建整库快照，`archive --json` 输出结构化报告；MCP 侧只补只读 / 预演能力（`archive.dryRun`、`maintain.capacity`、`context.audit` + 内联 `auditText`、`consolidate` 只出 propose 报告），`archive --force` 与 `consolidate --apply / --undo` 仍只在命令行。上一版 v0.17.4：`rename` 消除平铺 / 分层同序号冲突（跨布局 fail-closed + 破坏性闸门 + 审计）。

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-memory
 description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、长期理解摘要、近期走廊、会话闭环、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删、doctor、事务快照、基线探针、恢复演练、记忆库安全扫描、scan、命中打点、容量水位、--capacity、--propose、上下文压缩审计、context --audit
-version: 0.19.0
+version: 0.20.1
 license: MIT
 ---
 
@@ -36,7 +36,7 @@ license: MIT
 - **可靠性基线（v0.12.0）**：`init` 对非空记忆库默认拒绝覆盖（`--attach` 接入现有库）；`forget` 先移入 `.trash/` 并写审计；新增 `backup volumes / setup / status / ensure-daily / schedule / drill`（用户确认真实独立卷后默认每日自动备份）与 `backup create / list / doctor / restore`。
 - **可靠性收口（v0.12.2）**：新增 `yotta-memory doctor` 开工检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份）；`maintain --apply`、`consolidate --apply`、`merge`、`archive`、`--purge` 在写入前自动创建事务快照，快照失败或严重检查异常时拒绝写入。
 - **运行时 hook 声明（v0.13.0）**：manifest 声明 `after_milestone` / `remember_commit`；里程碑记忆必须有真实文件路径证据才标 verified，缺证据时输出 `explicit-unverified` + 一次纠偏。
-- **扩展提供方装载点（v0.19.0）**：`context` 支持可选的本地扩展提供方（capability `memory.hook`）参与「哪些记忆进上下文」：提供方只能驱逐本次候选集内的条目；身份画像、BOUND / COMMIT、预算 / 去重 / 宽限仍由引擎掌控。未配置 / 未授权 / 超时 / 非法输出一律走普通记忆，输出不带扩展行；`context --json` 输出 `schema` / `hook` / `text`。配置与协议见 `references/provider-protocol.md`。
+- **扩展提供方装载点（v0.20.0）**：`context` 支持可选的本地扩展提供方参与「哪些记忆进上下文」：`memory.hook` 先按候选集驱逐 / 白名单过滤，`context.paging` 在显式 `--budget` 时再排序与分页。身份段落、自我接入档案、BOUND / COMMIT、预算 / 去重 / 宽限仍由引擎掌控；未配置 / 未授权 / 超时 / 非法输出一律走普通记忆。`context --json` 输出 `schema` / `hook` / `paging` / `text`，`--explain` 增加 `[paging]` 轨迹。配置与协议见 `references/provider-protocol.md`。
 
 - **蒸馏溯源与分类型提取（v0.18.1）**：`distill` 输出新增「分类型提取清单（事件 / 教训 / 待办 / 成长 / 规则边界 / 其他）+ 质量指标 + 跳过与边界」；每条提取项带 `[溯源: 文件#L<a>-L<b>]`，报告只给实测压缩比 / 条目覆盖 / 溯源覆盖 / 要素提取率，不承诺压缩倍数或语义保真。`distill --json` 输出结构化报告；帮助补 `--owner` / `--out`。
 - **日期绝对化与巩固标记（v0.18.1）**：`consolidate` 生成摘要正文时，按条目 `created`（缺则 `updated`）把「昨天 / 上周 / 本月 / 今年」等写成绝对日期（如 `昨天（2026-01-09）`）；「最近 / 前几天 / 刚才」等模糊词不归一。归档副本末尾追加一行 `<!-- yotta-memory: consolidated to … -->` 巩固标记；`--undo` 剥离标记并还原原始内容；标记失败不影响批次，只在报告与审计里计数。

package/bin/install.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
 /**
- * yotta-memory 跨平台安装器
+ * yotta-memory 跨平台安装器（YottaSkills）
+ *
  * 用法:
- *   npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y --package @yottameta/yotta-memory yotta-memory-install --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y --package @yottameta/yotta-memory yotta-memory-install -g              # 安装到全部已知智能体用户级目录
- *   npx -y --package @yottameta/yotta-memory yotta-memory-install                 # 安装到检测到的项目级目录
- *   npx -y --package @yottameta/yotta-memory yotta-memory-install --list          # 列出智能体 -> 默认目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>   # 按智能体默认用户级目录安装（推荐）
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --dir <path>     # 装到指定目录（用户改了目录的智能体）
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install -g               # 安装到全部已知智能体用户级目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install                  # 安装到检测到的项目级目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --list           # 列出智能体 -> 默认目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --dry-run        # 只显示将写入的目标，不写文件
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --version        # 显示版本
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --help           # 显示帮助
+ *
+ * 退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误
  */
 'use strict';
 const fs = require('fs');
@@ -16,6 +22,21 @@ const os = require('os');
 const SKILL_NAME = 'yotta-memory';
 const PKG_ROOT = path.join(__dirname, '..');
 
+// 顶层开发文件 / 目录：只在安装包顶层跳过；技能包内嵌套同名载荷必须保留。
+// 与 install.sh 同口径：开发件与运行时不相关目录一律不落目标。
+const TOP_SKIP = [
+  'package.json', 'package-lock.json', 'bin', 'lib', 'test',
+  '.github', '.git', '.gitignore', '.npmignore', '.gitattributes',
+  '.yotta', '.tmp', 'install.sh', 'node_modules',
+];
+const TOP_SKIP_SET = new Set(TOP_SKIP);
+// 缓存 / 编译产物：任意层级跳过，安装时同样清理。
+const CACHE_DIRS = new Set(['__pycache__', '.pytest_cache', '.mypy_cache']);
+
+class UsageError extends Error {}
+class TargetError extends Error {}
+class InstallError extends Error {}
+
 // 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
 // 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
 // Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
@@ -39,6 +60,26 @@ const AGENT_DIRS = {
   agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
 };
 
+const PROJECT_DIRS = [
+  '.claude/skills',
+  '.cursor/skills',
+  '.codex/skills',
+  '.config/goose/skills',
+  '.config/agents/skills',
+  '.opencode/skills',
+  '.codeium/windsurf/skills',
+  '.workbuddy/skills',
+  '.kiro/skills',
+  '.traecli/skills',
+  '.gemini/skills',
+  '.trae-cn/skills',
+  '.qwen/skills',
+  '.comate/skills',
+  '.codebuddy/skills',
+  '.kimi/skills',
+  '.agents/skills',
+];
+
 // Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
 function codexUserDir() {
   const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
@@ -57,106 +98,238 @@ function resolveUserDir(rel) {
   return path.join(os.homedir(), rel);
 }
 
-function installTo(dest) {
-  const target = path.join(dest, SKILL_NAME);
-  fs.mkdirSync(target, { recursive: true });
-  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
-  console.log('installed -> ' + target);
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function skillVersion() {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+    return data.version || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function usage() {
+  console.log(SKILL_NAME + ' 安装器（YottaSkills）');
+  console.log('');
+  console.log('用法:');
+  console.log('  node bin/install.js --agent <name>   按智能体默认用户级目录安装（推荐）');
+  console.log('  node bin/install.js --dir <path>     装到指定目录（用户改了目录的智能体）');
+  console.log('  node bin/install.js -g               安装到全部已知智能体用户级目录');
+  console.log('  node bin/install.js                  安装到检测到的项目级目录');
+  console.log('');
+  console.log('参数:');
+  console.log('  --agent <name>  智能体键名，见 --list');
+  console.log('  --dir <path>    自定义技能目录');
+  console.log('  -g, --global    安装到全部已知用户级目录');
+  console.log('  --list, -l      列出支持的智能体目录');
+  console.log('  --dry-run       只显示将写入的目标，不写文件');
+  console.log('  --version, -v   显示版本');
+  console.log('  --help, -h      显示帮助');
+  console.log('  --yes, -y       兼容参数（-g 不再强制要求）');
+  console.log('');
+  console.log('退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误');
+}
+
+function parseArgs(argv) {
+  const opts = { help: false, version: false, list: false, global: false, dryRun: false, yes: false, dir: null, agent: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--version' || arg === '-v') opts.version = true;
+    else if (arg === '--list' || arg === '-l') opts.list = true;
+    else if (arg === '--global' || arg === '-g') opts.global = true;
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--yes' || arg === '-y') opts.yes = true;
+    else if (arg === '--dir') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--dir 需要一个非空路径');
+      opts.dir = value;
+    } else if (arg === '--agent') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--agent 需要一个非空名称');
+      opts.agent = String(value).toLowerCase();
+    } else {
+      throw new UsageError('未知参数: ' + arg);
+    }
+  }
+  if (!opts.help && !opts.version) {
+    const selected = [opts.dir, opts.agent, opts.global].filter(Boolean).length;
+    if (selected > 1) throw new UsageError('--dir / --agent / -g 只能选一个');
+  }
+  return opts;
+}
+
+function printList() {
+  console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
+  for (const [key, value] of Object.entries(AGENT_DIRS)) {
+    const resolved = value.dirs.map(displayDir);
+    console.log('  ' + key.padEnd(10) + value.label.padEnd(18) + resolved.join('、'));
+  }
+  console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
+  console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+}
+
+function assertSafeTarget(target) {
+  const rel = path.relative(PKG_ROOT, target);
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+    throw new UsageError('目标目录不能在技能源目录内（防止自装自毁）');
+  }
 }
 
-function copyDir(src, dst, skip) {
+function shouldSkipCache(name, isFile) {
+  if (CACHE_DIRS.has(name)) return true;
+  if (isFile && (name.endsWith('.pyc') || name.endsWith('.pyo'))) return true;
+  return false;
+}
+
+function copyDir(src, dst, topLevel) {
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (skip.has(entry.name)) continue;
+    // 只跳过安装包顶层开发文件；template/ 等嵌套同名载荷必须保留。
+    if (topLevel && TOP_SKIP_SET.has(entry.name)) continue;
+    if (shouldSkipCache(entry.name, entry.isFile())) continue;
     const s = path.join(src, entry.name);
     const d = path.join(dst, entry.name);
     if (entry.isDirectory()) {
       fs.mkdirSync(d, { recursive: true });
-      copyDir(s, d, skip);
+      copyDir(s, d, false);
     } else if (entry.isFile()) {
       fs.copyFileSync(s, d);
     }
   }
 }
 
-function displayDir(rel) {
-  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
-  return '~/' + rel;
+// 清理旧版安装残留（fail-closed 白名单）：
+// 仅在目标目录已存在且含 SKILL.md 时触发；只删顶层开发项 + 任意层级缓存；
+// 不整目录删除、不跟随符号链接。
+function cleanResidue(target) {
+  const removed = [];
+  let stat = null;
+  try { stat = fs.statSync(target); } catch (_) { return removed; }
+  if (!stat.isDirectory()) return removed;
+  if (!fs.existsSync(path.join(target, 'SKILL.md'))) return removed;
+  for (const name of TOP_SKIP) {
+    const p = path.join(target, name);
+    let entry = null;
+    try { entry = fs.lstatSync(p); } catch (_) { continue; }
+    if (entry.isSymbolicLink()) continue;
+    fs.rmSync(p, { recursive: true, force: true });
+    removed.push(name);
+  }
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (CACHE_DIRS.has(entry.name)) {
+          fs.rmSync(p, { recursive: true, force: true });
+          removed.push(path.relative(target, p));
+        } else {
+          walk(p);
+        }
+      } else if (entry.isFile() && (entry.name.endsWith('.pyc') || entry.name.endsWith('.pyo'))) {
+        fs.unlinkSync(p);
+        removed.push(path.relative(target, p));
+      }
+    }
+  };
+  walk(target);
+  return removed;
 }
 
-function main() {
-  const args = process.argv.slice(2);
-  const isGlobal = args.includes('-g') || args.includes('--global');
-  const list = args.includes('--list') || args.includes('-l');
-  let explicitDir = null;
-  const di = args.indexOf('--dir');
-  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
-  let agent = null;
-  const ai = args.indexOf('--agent');
-  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
-
-  if (list) {
-    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
-    for (const [key, v] of Object.entries(AGENT_DIRS)) {
-      const resolved = v.dirs.map(displayDir);
-      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
+function installTo(dest, opts) {
+  if (!dest || typeof dest !== 'string') throw new UsageError('目标目录不能为空');
+  const target = path.resolve(dest, SKILL_NAME);
+  assertSafeTarget(target);
+  if (opts.dryRun) {
+    console.log('[dry-run] 将安装到 -> ' + target);
+    return target;
+  }
+  try {
+    for (const rel of cleanResidue(target)) console.log('已清理残留: ' + rel);
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(PKG_ROOT, target, true);
+    if (!fs.existsSync(path.join(target, 'SKILL.md'))) {
+      throw new InstallError('安装结果缺少 SKILL.md');
+    }
+  } catch (err) {
+    if (err instanceof UsageError || err instanceof TargetError || err instanceof InstallError) throw err;
+    throw new InstallError('安装到 ' + target + ' 失败: ' + err.message);
+  }
+  console.log('installed -> ' + target);
+  return target;
+}
+
+function run() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { usage(); return; }
+  if (opts.version) {
+    const version = skillVersion();
+    if (!version) {
+      console.error(SKILL_NAME + ' 版本未知（未找到 package.json）');
+      process.exitCode = 1;
+      return;
     }
-    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
-    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+    console.log(SKILL_NAME + ' v' + version);
     return;
   }
+  if (opts.list) { printList(); return; }
 
-  if (explicitDir) { installTo(explicitDir); return; }
+  if (opts.dir) { installTo(opts.dir, opts); return; }
 
-  if (agent) {
-    const info = AGENT_DIRS[agent];
+  if (opts.agent) {
+    const info = AGENT_DIRS[opts.agent];
     if (!info) {
-      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
-      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
-      return;
+      throw new UsageError('未收录智能体: ' + opts.agent + '。可用: ' + Object.keys(AGENT_DIRS).join(', ') + '；自定义目录请用 --dir <路径>。');
     }
-    installTo(resolveUserDir(info.dirs[0]));
+    installTo(resolveUserDir(info.dirs[0]), opts);
     console.log('完成。');
     return;
   }
 
-  if (isGlobal) {
+  if (opts.global) {
     const seen = new Set();
-    for (const v of Object.values(AGENT_DIRS)) {
-      for (const d of v.dirs) {
-        if (seen.has(d)) continue;
-        seen.add(d);
-        installTo(resolveUserDir(d));
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const rel of value.dirs) {
+        if (seen.has(rel)) continue;
+        seen.add(rel);
+        installTo(resolveUserDir(rel), opts);
       }
     }
-    console.log('完成。');
+    if (!opts.dryRun) console.log('完成。');
     return;
   }
 
-  const PROJECT_DIRS = [
-    '.claude/skills',
-    '.cursor/skills',
-    '.codex/skills',
-    '.config/goose/skills',
-    '.config/agents/skills',
-    '.opencode/skills',
-    '.codeium/windsurf/skills',
-    '.workbuddy/skills',
-    '.kiro/skills',
-    '.traecli/skills',
-    '.gemini/skills',
-    '.trae-cn/skills',
-    '.qwen/skills',
-    '.comate/skills',
-    '.codebuddy/skills',
-    '.kimi/skills',
-    '.agents/skills',
-  ];
-  let installedAny = false;
-  for (const d of PROJECT_DIRS) {
-    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  const dirs = PROJECT_DIRS.filter((d) => fs.existsSync(d));
+  if (!dirs.length) {
+    throw new TargetError('未检测到项目级智能体目录。可用 --agent <name> 装到用户级，或用 --dir <路径> 指定目录。');
   }
-  if (!installedAny) {
-    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+  for (const dir of dirs) installTo(dir, opts);
+  if (!opts.dryRun) console.log('完成。');
+}
+
+function main() {
+  try {
+    run();
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error('用法错误: ' + err.message);
+      usage();
+      process.exitCode = 2;
+    } else if (err instanceof TargetError) {
+      console.error('目标错误: ' + err.message);
+      process.exitCode = 4;
+    } else if (err instanceof InstallError) {
+      console.error('安装失败: ' + err.message);
+      console.error('修复建议: 检查目录权限与磁盘空间后重试，或用 --dir 换一个目录。');
+      process.exitCode = 1;
+    } else {
+      console.error('未知错误: ' + (err && err.message ? err.message : String(err)));
+      process.exitCode = 1;
+    }
   }
 }
 

package/bin/provider.js

@@ -94,6 +94,7 @@ function minimalEnv() {
   const keep = [
     'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'windir', 'COMSPEC', 'ComSpec',
     'TEMP', 'TMP', 'HOME', 'USERPROFILE', 'LANG', 'LC_ALL',
+    'YOTTA_LICENSE_HOME', 'YOTTA_LICENSE_KEYS_DIR', 'YOTTA_LICENSE_BASE_URL', 'YOTTA_LICENSE_SERVER_ID',
   ];
   const env = {};
   for (const key of keep) {