@givolt/i3-composer-agent 2.2.1 → 2.2.3

package/.agents/plugins/marketplace.json

@@ -6,7 +6,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "2.2.1",
+      "version": "2.2.3",
       "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
       "source": {
         "source": "local",

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "2.2.1",
+      "version": "2.2.3",
       "source": "./",
       "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
       "homepage": "https://github.com/49780522/i3-composer-agent",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
   "author": {
     "name": "Givolt"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
   "author": {
     "name": "Givolt"

package/README.md

@@ -1,4 +1,4 @@
-# i3 Composer Agent v2.2.1
+# i3 Composer Agent v2.2.3
 
 **Intelligence. Integration. Innovation.**
 
@@ -26,8 +26,9 @@ WorkBuddy 在第 2 项。上下键移动，空格勾选/取消，回车确认；
 确认工具后选择项目/全局范围并确认安装。
 
 全部目标均安装 25 个技能、共享参考资料，以及完整评测/Hook/脚本配套。
-CodeBuddy、WorkBuddy、Claude Code 另安装 9 个短命令和 4 个 Agent 角色。
-其他工具通过其原生 Skills 机制使用；短命令支持取决于宿主。
+全部目标同时提供 9 个命令和 4 个 Agent 角色提示。
+CodeBuddy、WorkBuddy、Claude Code 使用原生命令入口；其他工具通过 Skills 机制使用，
+命令和角色文件可作为资料读取，是否自动发现取决于宿主。
 目录预设来自固定的 [Skills CLI 工具登记](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
 并增加 WorkBuddy。目录预设验证与每个宿主的实际执行验收分别记录。
 
@@ -53,44 +54,71 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 同版本、同范围的清单所属未修改内容会复用，新增客户端合并到清单。
 升级、修改过的内容及未登记同名冲突需确认替换；非交互使用 `--force` 前可先看 dry-run。
 安装成功后清理替换掉的旧内容及本安装器所属历史备份，失败则恢复原文件。
-迁移只清理旧清单所属的无前缀 Skill/命令路径，保留自定义内容。
-标准 MIT 许可随共享参考资料安装。`npx -y` 确认 npm 下载；包的 `--yes` 确认安装计划。
+升级按文件归属清理旧副本，保留用户新增文件；2.2.2 的分散配套资料迁入工具根；2.2.1 的评测结果保留原位。
+同名结果内容不同时会在写入前停止；未归属本包的资料冲突也需先处理，`--force` 不会接管。
+成功后不保留临时备份。`npx -y` 确认 npm 下载；包的 `--yes` 确认安装计划。
 
 ## 安装内容与可选功能
 
 | 内容 | 默认安装 | 用途 |
 | --- | --- | --- |
 | `skills/`（含技能内部的 `scripts/` 等资源） | 是 | 工程工作流及运行辅助文件 |
-| `references/` | 是 | 技能引用的检查清单与参考资料 |
-| `commands/`、`agents/` | CodeBuddy、WorkBuddy、Claude Code | 短命令与专业角色 |
-| `hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
-| `scripts/` | 是 | 评测运行器、五项校验脚本及其共享库 |
-| `evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
+| `i3-composer-agent/references/` | 是 | 技能引用的检查清单与参考资料 |
+| `commands/`、`agents/` | 是；发现与调用依宿主支持 | 短命令与专业角色提示 |
+| `i3-composer-agent/hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
+| `i3-composer-agent/scripts/` | 是 | 评测运行器、五项校验、全部原版脚本回归测试及共享库 |
+| `i3-composer-agent/evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
 
-完整配套默认放在宿主目录下的 `i3-composer-agent/`，例如
-`.codebuddy/i3-composer-agent/` 或 `~/.workbuddy/i3-composer-agent/`。
-其中保留对应的技能、命令、角色、参考资料与清单，供评测、校验和 Hook 的相对路径使用；
-宿主调用入口继续安装在其原生目录。该配套与技能一起升级、复用和失败恢复。
+以项目安装的 `.codebuddy/` 为例，默认目录为：
 
-从配套目录运行以下检查，不调用模型：
+```text
+.codebuddy/
+├─ skills/                         # 宿主和评测共用的实际技能
+├─ commands/                       # 一份命令
+├─ agents/                         # 一份角色提示
+├─ i3-composer-agent/               # 配套工具根，不是第二份插件
+│  ├─ package.json                 # 独立 CommonJS 配置，提供 npm test
+│  ├─ README.md
+│  ├─ scripts/                     # 全部脚本、原有回归测试及 lib/
+│  ├─ evals/                       # 中英文用例、样例、插件评测及结果
+│  ├─ hooks/
+│  ├─ references/
+│  ├─ docs/
+│  └─ adapters/                    # 其他命令格式和插件清单的校验输入
+└─ .i3-composer-agent.json          # 版本、布局、能力与文件归属清单
+```
+
+每个宿主基址只有一份技能；公共资料集中在配套工具根目录。技能内部的 scripts/references 保留。
+WorkBuddy 全局安装将基址换为 `~/.workbuddy/`，Codex 项目安装为 `.agents/`。
+评测、校验和适用的 Hook 读取宿主使用的实际内容，不生成第二份完整插件。
+
+进入配套目录后运行以下命令，不调用模型：
 
 ```bash
+cd .codebuddy/i3-composer-agent
 npm test
 node scripts/run-evals.js --locale zh-CN --min-rank1 95
 ```
 
+`npm test` 执行五项校验、中英文确定性评测和全部原版脚本回归测试。
+原版英文案例完整保留，中文案例作为增量，两种语言分别通过门槛。
+脚本也可使用绝对路径从任意目录运行；无需 `npm install`。
+
 模型行为评测需要主动运行并消耗模型额度，详见 [评测说明](evals/README.md)。
-本包的 `npm test` 检查随包技能的结构和中英文触发，不是业务项目测试或宿主执行验收。
+原生脚本按安装清单检查本包内容，支持业务项目的 ESM/CommonJS 设置。
+配套根与独立插件导出目录均可执行 `npm test`；这些检查均不能代替业务项目测试或宿主执行验收。
 评测结果不进入安装替换清单。安装过程不执行评测，也不自动启用 Hook。
 
 可选 Hook 不影响普通技能和命令的使用，默认中文交互也不依赖 Hook。
 未配置 Hook 时，自动注入、缓存和代码块保护这些增强功能不会运行。
 会话注入仅适合缺少原生技能路由的宿主；已有原生路由时不应重复注入元技能。
-缓存与代码块保护的配置说明分别在配套目录的 `hooks/SDD-CACHE.md`、
-`hooks/SIMPLIFY-IGNORE.md`，当前示例针对 Claude Code，其他宿主需适配自己的事件协议。
+缓存与代码块保护的配置说明位于 `i3-composer-agent/hooks/` 下的 `SDD-CACHE.md`、
+`SIMPLIFY-IGNORE.md`，当前示例针对 Claude Code，其他宿主需适配自己的事件协议。
 脚本依赖 Bash、jq；缓存还需 curl 和哈希工具，代码块保护还需其文档列出的工具。
 Windows PowerShell 本身不会自动提供这些脚本依赖。
 
+`i3-composer-agent/adapters/` 中的其他命令格式与插件清单用于完整回归校验，不自动注册插件。
+
 ## 通过宿主插件管理器安装
 
 默认配套已包含 Skills、Commands、Agents、references、evals、hooks 和 scripts。

package/bin/asset-fingerprint.cjs

@@ -3,7 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { nativeContent } = require('./native-content.cjs');
+const { renderAsset } = require('./native-layout.cjs');
 
 // Compare the complete tree without following links. When asset is provided,
 // hash the source as it will be rendered by the native installer.
@@ -21,13 +21,11 @@ function fingerprint(file, asset) {
     if (stat.isDirectory()) {
       for (const entry of fs.readdirSync(current).sort()) {
         if (asset && entry === '.DS_Store') continue;
-        if (asset?.kind === 'support' && ['results', 'node_modules', '.git'].includes(entry)) continue;
         if (!visit(path.join(current, entry), path.join(relative, entry))) return false;
       }
     } else {
-      const content = asset && current.endsWith('.md')
-        ? Buffer.from(nativeContent(fs.readFileSync(current, 'utf8'), asset))
-        : fs.readFileSync(current);
+      const bytes = fs.readFileSync(current);
+      const content = asset ? renderAsset(bytes, asset) : bytes;
       hash.update(String(content.length) + '\n');
       hash.update(content);
     }

package/bin/i3-composer-agent.cjs

@@ -46,7 +46,8 @@ ${pkg.name}
 上下键移动/跨页，空格勾选/取消，回车确认；列表下实时显示已选，q/Esc 退出。
 CodeBuddy、WorkBuddy、Claude Code 同时安装短命令和 Agent 角色。
 其他工具通过 Skills 调用，短命令支持取决于宿主。
-所有工具默认安装完整配套目录 i3-composer-agent/，含 evals、hooks、scripts 及所需资料。
+所有工具默认安装单份 skills、commands、agents；配套资料集中在 i3-composer-agent/。
+评测、脚本和 Hook 读取同一份已安装技能。--prepare 用于另行导出标准插件并按宿主方式注册。
 WorkBuddy 桌面版建议全局安装，便于技能列表和输入补全发现。
 评测需主动运行；Hook 文件已提供，需按宿主事件协议单独启用。
 --prepare 仅供插件管理器安装方式使用，不自动注册插件或启用 Hook。
@@ -201,12 +202,16 @@ async function main() {
   if (plan.reused.length) console.log(`已复用同版本的 ${plan.reused.length} 个未修改内容。`);
   for (const target of plan.targets) {
     console.log(`已为 ${target.agents.join(', ')} 安装技能：${target.skillsDirectory}`);
-    if (target.commandsDirectory) console.log(`命令：/i3-spec、/i3-plan、/i3-build、/i3-ship（共 ${fs.readdirSync(target.commandsDirectory).filter(file => file.endsWith('.md')).length} 个工作流）：${target.commandsDirectory}`);
-    console.log(`配套目录（含 evals、hooks、scripts）：${target.supportDirectory}`);
-    console.log(`中文评测：node "${path.join(target.supportDirectory, 'scripts/run-evals.js')}" --locale zh-CN --min-rank1 95`);
+    if (target.nativeCommands) console.log(`命令：/i3-spec、/i3-plan、/i3-build、/i3-ship（共 ${target.catalog.commands.length} 个工作流）：${target.commandsDirectory}`);
+    else console.log(`命令和角色资料已提供；是否自动发现取决于宿主：${target.commandsDirectory}、${target.personasDirectory}`);
+    console.log(`评测资料：${target.evalsDirectory}`);
+    console.log(`完整校验：进入 "${target.toolkitDirectory}" 后运行 npm test`);
+    console.log(`中文评测：node "${path.join(target.scriptsDirectory, 'run-evals.js')}" --locale zh-CN --min-rank1 95`);
+    console.log(`Hook：${target.hooksDirectory}（尚未启用）`);
   }
+  for (const file of plan.preserved || []) console.log(`保留了用户文件：${file}`);
   console.log('请重新加载 IDE 窗口或新建宿主会话以发现安装内容。');
   if (plan.agents.some(id => !['codebuddy', 'workbuddy', 'claude-code'].includes(id))) console.log('这些工具通过技能 ID 调用；生命周期短命令支持取决于宿主。');
-  console.log('安装完成。评测运行方式见配套目录 evals/README.md；Hook 文件已安装，尚未启用。');
+  console.log('安装完成。评测说明见 i3-composer-agent/evals/README.md；Hook 需按宿主事件协议启用。');
 }
 main().catch(error => { console.error(`${name}: ${error.message}`); process.exitCode = 1; });

package/bin/install.cjs

@@ -6,7 +6,8 @@ const os = require('node:os');
 const crypto = require('node:crypto');
 const registry = require('./agent-targets.json');
 const { cleanupBackups } = require('./cleanup-backups.cjs');
-const { nativeContent } = require('./native-content.cjs');
+const { nativeAssets, renderAsset } = require('./native-layout.cjs');
+const { migrationAssets, pruneRetiredDirectories, ownsAsset } = require('./native-migration.cjs');
 const { fingerprint } = require('./asset-fingerprint.cjs');
 const root = path.resolve(__dirname, '..');
 const name = 'i3-composer-agent';
@@ -49,8 +50,10 @@ function checkDestination(file) {
 }
 function assetPath(base, file) { return path.relative(base, file).split(path.sep).join('/'); }
 function manifestContent(plan, asset) {
-  return JSON.stringify({ name, version, entryPrefix: 'i3-', scope: plan.scope, agents: asset.target.agents,
-    assets: plan.assets.filter(item => item.base === asset.base && item.kind !== 'legacy').map(item => assetPath(asset.base, item.destination)) }, null, 2) + '\n';
+  return JSON.stringify({ name, version, layoutVersion: 3, entryPrefix: 'i3-', scope: plan.scope, agents: asset.target.agents,
+    capabilities: { nativeCommands: !!asset.target.nativeCommands, nativeAgents: !!asset.target.nativeCommands, hooks: 'manual' },
+    catalog: asset.target.catalog, resources: asset.target.resources,
+    assets: plan.assets.filter(item => item.base === asset.base && !['legacy', 'result'].includes(item.kind)).map(item => assetPath(asset.base, item.destination)) }, null, 2) + '\n';
 }
 function planInstallation({ agents, scope, projectDir = process.cwd(), home = os.homedir(), env = process.env }) {
   agents = selectAgents(agents);
@@ -61,24 +64,17 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     const agent = registry.agents.find(item => item.id === id);
     const skillsDirectory = destination(scope === 'project' ? path.resolve(projectDir, agent.projectSkillsDir) : globalSkillsDir(agent, home, env));
     const base = path.dirname(skillsDirectory);
-    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, referencesDirectory: path.join(base, 'references'), supportDirectory: path.join(base, name), base });
+    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, toolkitDirectory: path.join(base, name), referencesDirectory: path.join(base, name, 'references'),
+      commandsDirectory: path.join(base, 'commands'), personasDirectory: path.join(base, 'agents'),
+      evalsDirectory: path.join(base, name, 'evals'), scriptsDirectory: path.join(base, name, 'scripts'),
+      hooksDirectory: path.join(base, name, 'hooks'), docsDirectory: path.join(base, name, 'docs'), base });
     const target = targets.get(skillsDirectory);
     target.agents.push(id);
     if (['codebuddy', 'workbuddy', 'claude-code'].includes(id)) {
-      target.commandsDirectory = path.join(base, 'commands');
-      target.personasDirectory = path.join(base, 'agents');
+      target.nativeCommands = true;
     }
   }
   const assets = [];
-  function addDirectory(sourceDirectory, destinationDirectory, kind) {
-    if (exists(destinationDirectory) && fs.lstatSync(destinationDirectory).isSymbolicLink()) {
-      throw new Error(`安装目录是符号链接（symlink）： ${destinationDirectory}. 请选择其真实目录。`);
-    }
-    for (const entry of fs.readdirSync(path.join(root, sourceDirectory)).sort()) {
-      if (entry === '.DS_Store') continue;
-      assets.push({ source: path.join(root, sourceDirectory, entry), destination: destination(path.join(destinationDirectory, entry)), kind });
-    }
-  }
   for (const target of targets.values()) {
     const manifestFile = path.join(target.base, `.${name}.json`);
     const previous = exists(manifestFile) && !fs.lstatSync(manifestFile).isSymbolicLink()
@@ -87,7 +83,7 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     // Earlier Windows installs persisted backslashes. Normalize before lookup
     // and containment checks so owned upgrades work across both manifest forms.
     if (owned) previous.assets = previous.assets.map(relative => typeof relative === 'string' ? relative.replaceAll('\\', '/') : relative);
-    const sameVersion = owned && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
+    const sameVersion = owned && previous.layoutVersion === 3 && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
     if (owned && previous.scope === scope && Array.isArray(previous.agents)) {
       const applicable = previous.agents.filter(id => {
         const agent = registry.agents.find(item => item.id === id);
@@ -97,47 +93,23 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
       });
       target.agents = [...new Set([...applicable, ...target.agents])];
     }
+    target.nativeCommands = target.agents.some(id => ['codebuddy', 'workbuddy', 'claude-code'].includes(id));
     const start = assets.length;
-    addDirectory('skills', target.skillsDirectory, 'skill');
-    addDirectory('references', target.referencesDirectory, 'reference');
-    if (target.commandsDirectory) {
-      addDirectory('.claude/commands', target.commandsDirectory, 'command');
-      addDirectory('agents', target.personasDirectory, 'persona');
-      const docs = path.join(target.base, 'docs');
-      if (exists(docs) && fs.lstatSync(docs).isSymbolicLink()) throw new Error(`安装目录是符号链接（symlink）： ${docs}.`);
-      assets.push({ source: path.join(root, 'docs/agents.md'), destination: destination(path.join(target.base, 'docs/agents.md')), kind: 'documentation' });
-    }
-    const licenseDirectory = path.join(target.referencesDirectory, name);
-    if (exists(licenseDirectory) && fs.lstatSync(licenseDirectory).isSymbolicLink()) throw new Error(`安装目录是符号链接（symlink）： ${licenseDirectory}.`);
-    assets.push({ source: path.join(root, 'LICENSE'), destination: destination(path.join(licenseDirectory, 'LICENSE')), kind: 'attribution' });
-    // Keep the canonical plugin layout for eval fixtures, validators and Hook
-    // relative paths. Native entry points above remain host-adapted copies.
-    for (const relative of pluginFiles) {
-      const file = path.join(target.supportDirectory, relative);
-      if (destination(file) !== file) throw new Error(`配套目录包含符号链接（symlink）： ${file}`);
-      assets.push({ source: path.join(root, relative), destination: file, kind: 'support' });
-    }
-    if (owned) {
-      const legacy = fs.readdirSync(path.join(root, 'skills')).filter(id => id.startsWith('i3-')).map(id => `skills/${id.slice(3)}`);
-      if (target.commandsDirectory) legacy.push(...fs.readdirSync(path.join(root, '.claude/commands')).filter(file => file.startsWith('i3-') && file.endsWith('.md')).map(file => `commands/${file.slice(3)}`));
-      legacy.push(`${name}-LICENSE`, `${name}-NOTICE.md`);
-      const current = new Set(assets.slice(start).map(asset => assetPath(target.base, asset.destination)));
-      for (const relative of previous.assets) {
-        // Retire only owned native entries or entries inside this package's
-        // companion directory. Never let a manifest extend the deletion scope.
-        if (typeof relative !== 'string' || relative.includes('\0') || relative.includes(':')
-          || relative.split('/').some(part => ['', '.', '..'].includes(part))) continue;
-        if (!/^(skills|commands|agents|references)\/[^/]+$/.test(relative) && !relative.startsWith(`${name}/`)) continue;
-        if (relative.startsWith(`${name}/`) && destination(path.join(target.base, relative)) !== path.join(target.base, relative)) continue;
-        if (!current.has(relative)) legacy.push(relative);
-      }
-      for (const relative of new Set(legacy)) {
-        const file = destination(path.join(target.base, relative));
-        if (previous.assets.includes(relative) && exists(file)) assets.push({ destination: file, kind: 'legacy' });
+    const additions = nativeAssets(root, target, pluginFiles, version);
+    const current = new Set(additions.map(asset => asset.relative));
+    assets.push(...additions, ...migrationAssets(target, owned ? previous : undefined, current));
+    for (const asset of additions) {
+      // A new grouped resource must not take ownership of an unrelated file,
+      // even when --force confirms replacement of a previous installation.
+      const previousOwned = owned && ownsAsset(previous, asset.relative);
+      asset.protectedResource = /^(references|evals|hooks|scripts|docs|i3-composer-agent)\//.test(asset.relative);
+      if (exists(asset.destination) && !previousOwned && asset.protectedResource) {
+        throw new Error(`未归属本包的同名资源，不能覆盖，请先处理：${asset.destination}`);
       }
     }
     assets.push({ target, destination: destination(manifestFile), kind: 'manifest', mergeable: sameVersion });
     for (const asset of assets.slice(start)) {
+      if (destination(asset.destination) !== asset.destination) throw new Error(`安装目录包含符号链接（symlink）：${asset.destination}`);
       asset.base = target.base;
       asset.buddyCommand = asset.kind === 'command' && target.agents.some(id => ['codebuddy', 'workbuddy'].includes(id));
       asset.scope = scope;
@@ -149,6 +121,9 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     }
   }
   for (const asset of assets) { checkDestination(asset.destination); asset.existing = exists(asset.destination); }
+  for (const asset of assets.filter(item => item.existing)) {
+    if (!fs.lstatSync(asset.destination).isFile()) throw new Error(`目标文件被目录或符号链接占用（symlink）：${asset.destination}`);
+  }
   const plan = { mode: 'install', scope, agents, targets: [...targets.values()], assets };
   for (const asset of assets.filter(item => item.kind === 'manifest' && item.mergeable)) {
     asset.observedFingerprint = fingerprint(asset.destination);
@@ -172,13 +147,6 @@ function executeInstallation(plan, { force = false } = {}) {
     fs.mkdirSync(directory);
     createdDirectories.push(directory);
   }
-  function portable(file, asset, markdown = false) {
-    if (fs.statSync(file).isDirectory()) {
-      for (const entry of fs.readdirSync(file)) portable(path.join(file, entry), asset);
-    } else if (markdown || file.endsWith('.md')) {
-      fs.writeFileSync(file, nativeContent(fs.readFileSync(file, 'utf8'), asset));
-    }
-  }
   try {
     // Stage every target before replacing the first installed asset.
     for (const [index, asset] of plan.assets.entries()) {
@@ -192,17 +160,22 @@ function executeInstallation(plan, { force = false } = {}) {
       if (asset.kind === 'manifest') {
         fs.writeFileSync(asset.staged, manifestContent(plan, asset));
       } else {
-        fs.cpSync(asset.source, asset.staged, { recursive: true, filter: file => {
-          if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`包内容中包含符号链接（symlink）： ${file}`);
-          return path.basename(file) !== '.DS_Store' && (asset.kind !== 'support'
-            || !/(?:^|[\\/])(?:results|node_modules|\.git)(?:[\\/]|$)/.test(path.relative(root, file)));
-        } });
-        portable(asset.staged, asset, asset.source.endsWith('.md'));
+        if (!fs.lstatSync(asset.source).isFile()) throw new Error(`包内容不是普通文件：${asset.source}`);
+        const bytes = fs.readFileSync(asset.source);
+        fs.writeFileSync(asset.staged, asset.kind === 'result' ? bytes : renderAsset(bytes, asset));
+        fs.chmodSync(asset.staged, fs.statSync(asset.source).mode & 0o777);
       }
     }
     for (const asset of plan.assets) {
       const context = contexts.get(asset.base);
+      if (destination(asset.destination) !== asset.destination) throw new Error(`安装期间目录变成符号链接（symlink）：${asset.destination}`);
       mkdir(path.dirname(asset.destination));
+      if (exists(asset.destination) && !fs.lstatSync(asset.destination).isFile()) throw new Error(`安装期间目标不再是普通文件：${asset.destination}`);
+      if (!asset.existing && exists(asset.destination) && (asset.protectedResource || asset.kind === 'result')) {
+        throw new Error(`安装期间出现未归属文件：${asset.destination}`);
+      }
+      if (asset.kind === 'result' && fingerprint(asset.source) !== asset.expectedFingerprint) throw new Error(`安装期间评测结果已改变：${asset.source}`);
+      if (asset.kind === 'result' && asset.existing && fingerprint(asset.destination) !== asset.expectedFingerprint) throw new Error(`安装期间目标评测结果已改变：${asset.destination}`);
       if (asset.reusable) {
         const unchanged = fingerprint(asset.destination) === asset.expectedFingerprint
           && fingerprint(asset.staged) === asset.expectedFingerprint;
@@ -225,12 +198,27 @@ function executeInstallation(plan, { force = false } = {}) {
         change.written = true;
       }
     }
+    pruneRetiredDirectories(plan.assets);
     completed = true;
+    const ownedPaths = new Set(plan.assets.filter(asset => asset.kind !== 'legacy').map(asset => asset.destination));
+    plan.preserved = [];
+    function findUserFiles(directory) {
+      if (!exists(directory) || fs.lstatSync(directory).isSymbolicLink()) return;
+      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory()) findUserFiles(file);
+        else if (!ownedPaths.has(file) && !file.split(path.sep).includes('results')) plan.preserved.push(file);
+      }
+    }
+    for (const target of plan.targets) {
+      findUserFiles(path.join(target.base, name));
+      for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs']) findUserFiles(path.join(target.base, category, name));
+    }
     return [];
   } catch (error) {
     for (const change of committed.reverse()) {
       if (change.written) fs.rmSync(change.destination, { recursive: true, force: true });
-      if (change.backup) fs.renameSync(change.backup, change.destination);
+      if (change.backup) { mkdir(path.dirname(change.destination)); fs.renameSync(change.backup, change.destination); }
     }
     rolledBack = true;
     throw error;