@givolt/i3-composer-agent 2.2.0 → 2.2.2

package/.agents/plugins/marketplace.json

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

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "2.2.0",
+      "version": "2.2.2",
       "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.0",
+  "version": "2.2.2",
   "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
   "author": {
     "name": "Givolt"

package/.codex-plugin/plugin.json

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

package/README.md

@@ -1,4 +1,4 @@
-# i3 Composer Agent v2.2.0
+# i3 Composer Agent v2.2.2
 
 **Intelligence. Integration. Innovation.**
 
@@ -18,15 +18,17 @@ npx @givolt/i3-composer-agent --workbuddy --scope global
 ```
 
 首屏依次为 CodeBuddy、WorkBuddy、Codex、Claude Code、Cursor、Gemini CLI，
-WorkBuddy 在第 2 项。选 `7`/`更多` 打开其余工具，每页 10 项；`n` 下一页、`p` 上一页、
-`b` 返回，`/关键词` 搜索全部 80 个工具。编号在分页和搜索中保持一致。
-输入编号或 ID（中英文逗号均可）累积多选，跨页保留；`-编号/ID` 移除选择。
-回车或 `done`/`完成` 确认已选工具，随后选择项目/全局范围并确认安装；`q`/`取消` 退出。
-通过参数预选的工具会保留，仍可继续多选。
-
-全部目标均安装 25 个技能和共享参考资料。
-CodeBuddy、WorkBuddy、Claude Code 另安装 9 个短命令和 4 个 Agent 角色。
-其他工具通过其原生 Skills 机制使用；短命令支持取决于宿主。
+WorkBuddy 在第 2 项。上下键移动，空格勾选/取消，回车确认；列表原地刷新，
+下方实时显示已选工具。移到“更多”按空格或直接按 `m` 打开其他工具。
+更多列表上下移动可跨页，`n`/`p` 或 PageDown/PageUp 整页翻页，`b`/左键返回常用。
+按 `/` 输入关键词实时搜索全部 80 个工具；回车或下键结束输入，再用空格选择。
+搜索、翻页和命令参数预选均保留选择。搜索外 `q`、Esc 或 Ctrl-C 取消。
+确认工具后选择项目/全局范围并确认安装。
+
+全部目标均安装 25 个技能、共享参考资料，以及完整评测/Hook/脚本配套。
+全部目标同时提供 9 个命令和 4 个 Agent 角色提示。
+CodeBuddy、WorkBuddy、Claude Code 使用原生命令入口；其他工具通过 Skills 机制使用，
+命令和角色文件可作为资料读取，是否自动发现取决于宿主。
 目录预设来自固定的 [Skills CLI 工具登记](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
 并增加 WorkBuddy。目录预设验证与每个宿主的实际执行验收分别记录。
 
@@ -52,12 +54,68 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 同版本、同范围的清单所属未修改内容会复用，新增客户端合并到清单。
 升级、修改过的内容及未登记同名冲突需确认替换；非交互使用 `--force` 前可先看 dry-run。
 安装成功后清理替换掉的旧内容及本安装器所属历史备份，失败则恢复原文件。
-迁移只清理旧清单所属的无前缀 Skill/命令路径，保留自定义内容。
-标准 MIT 许可随共享参考资料安装。`npx -y` 确认 npm 下载；包的 `--yes` 确认安装计划。
+升级按文件归属清理旧副本，保留用户新增文件；旧评测结果迁入新的 evals 分组。
+同名结果内容不同时会在写入前停止；未归属本包的资料冲突也需先处理，`--force` 不会接管。
+成功后不保留临时备份。`npx -y` 确认 npm 下载；包的 `--yes` 确认安装计划。
 
-## 注册完整插件
+## 安装内容与可选功能
 
-完整插件包含 Skills、Commands、Agents、Hooks 和 references。准备持久目录：
+| 内容 | 默认安装 | 用途 |
+| --- | --- | --- |
+| `skills/`（含技能内部的 `scripts/` 等资源） | 是 | 工程工作流及运行辅助文件 |
+| `references/i3-composer-agent/` | 是 | 技能引用的检查清单与参考资料 |
+| `commands/`、`agents/` | 是；发现与调用依宿主支持 | 短命令与专业角色提示 |
+| `hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
+| `scripts/` | 是 | 评测运行器、五项校验脚本及其共享库 |
+| `evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
+
+以项目安装的 `.codebuddy/` 为例，默认目录为：
+
+```text
+.codebuddy/
+├─ skills/                         # 宿主和评测共用的实际技能
+├─ commands/                       # 一份命令
+├─ agents/                         # 一份角色提示
+├─ references/i3-composer-agent/
+├─ evals/i3-composer-agent/         # 用例、样例、插件评测与运行结果
+├─ hooks/i3-composer-agent/
+├─ scripts/i3-composer-agent/       # .cjs 入口及 lib/
+├─ docs/i3-composer-agent/
+└─ .i3-composer-agent.json          # 版本、布局、能力与文件归属清单
+```
+
+每个宿主基址只有一份技能；公共资料按插件名称分组。技能内部的 scripts/references 保留。
+WorkBuddy 全局安装将基址换为 `~/.workbuddy/`，Codex 项目安装为 `.agents/`。
+评测、校验和适用的 Hook 读取宿主使用的实际内容，不生成第二份完整插件。
+
+从业务项目目录运行以下检查，不调用模型；也可用脚本绝对路径从任意目录运行：
+
+```bash
+node .codebuddy/scripts/i3-composer-agent/validate-skills.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-versions.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-commands.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-reference-links.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-artifact-paths.cjs
+node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --locale zh-CN --min-rank1 95
+```
+
+模型行为评测需要主动运行并消耗模型额度，详见 [评测说明](evals/README.md)。
+原生脚本按安装清单检查本包内容，支持业务项目的 ESM/CommonJS 设置。
+独立插件导出目录仍可执行 `npm test`；上述检查均不能代替业务项目测试或宿主执行验收。
+评测结果不进入安装替换清单。安装过程不执行评测，也不自动启用 Hook。
+
+可选 Hook 不影响普通技能和命令的使用，默认中文交互也不依赖 Hook。
+未配置 Hook 时，自动注入、缓存和代码块保护这些增强功能不会运行。
+会话注入仅适合缺少原生技能路由的宿主；已有原生路由时不应重复注入元技能。
+缓存与代码块保护的配置说明位于 `hooks/i3-composer-agent/` 下的 `SDD-CACHE.md`、
+`SIMPLIFY-IGNORE.md`，当前示例针对 Claude Code，其他宿主需适配自己的事件协议。
+脚本依赖 Bash、jq；缓存还需 curl 和哈希工具，代码块保护还需其文档列出的工具。
+Windows PowerShell 本身不会自动提供这些脚本依赖。
+
+## 通过宿主插件管理器安装
+
+默认配套已包含 Skills、Commands、Agents、references、evals、hooks 和 scripts。
+若希望另行导出目录，交给宿主插件管理器管理：
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codebuddy
@@ -65,7 +123,9 @@ npx @givolt/i3-composer-agent --prepare --codex
 npx @givolt/i3-composer-agent --prepare --claude
 ```
 
-此模式准备 `./i3-composer-agent/` 并输出宿主注册命令。
+`--prepare` 只准备 `./i3-composer-agent/` 运行文件并输出宿主注册命令，
+不会把插件自动注册到宿主，也不会启用可选 Hook。普通技能安装完成后无需再执行它。
+需要让宿主插件管理器统一发现和管理插件时，再按下面步骤注册：
 在 CodeBuddy Code（终端）或 Claude Code 中执行：
 
 ```text
@@ -80,8 +140,8 @@ codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-按宿主管理器选择安装范围，启用后新建会话。原生文件安装与完整插件注册是两种入口。
-原生安装不自动启用插件 Hook；无需 Hook，入口本身也要求默认中文回复。
+按宿主管理器选择安装范围，启用后新建会话。原生文件安装与插件注册是两种入口。
+本包没有默认 Hook 注册配置；插件启用后，可选 Hook 仍需按上面的用途和宿主要求单独配置。
 
 ## 命令
 

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.
@@ -24,9 +24,8 @@ function fingerprint(file, asset) {
         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

@@ -34,7 +34,7 @@ ${pkg.name}
   --project-dir <dir> 项目安装根目录，默认当前目录
   --yes              确认明确指定的非交互安装
   --list-agents      列出全部支持的工具目录
-  --prepare          准备完整插件，供宿主原生插件管理器注册
+  --prepare          另行导出插件目录并显示宿主注册步骤
   --extract          导出完整插件内容
   --dir <directory>  插件输出目录；隐含 --prepare
   --dry-run          显示安装/导出计划，不写入文件
@@ -43,11 +43,14 @@ ${pkg.name}
   --help             显示帮助
 
 终端向导先显示常用工具，WorkBuddy 在第 2 项；选择“更多”可分页/搜索全部工具。
-编号或 ID 支持多选，跨页保留选择；回车或 done/完成确认，q/取消退出。
+上下键移动/跨页，空格勾选/取消，回车确认；列表下实时显示已选，q/Esc 退出。
 CodeBuddy、WorkBuddy、Claude Code 同时安装短命令和 Agent 角色。
-其他工具获得 Skills 与参考资料，短命令支持取决于宿主。
+其他工具通过 Skills 调用，短命令支持取决于宿主。
+所有工具默认安装单份 skills、commands、agents；资料按 references/evals/hooks/scripts/docs 分组。
+评测、脚本和 Hook 读取同一份已安装技能。--prepare 用于另行导出标准插件并按宿主方式注册。
 WorkBuddy 桌面版建议全局安装，便于技能列表和输入补全发现。
-完整插件及 Hook 注册使用 --prepare。
+评测需主动运行；Hook 文件已提供，需按宿主事件协议单独启用。
+--prepare 仅供插件管理器安装方式使用，不自动注册插件或启用 Hook。
 `;
 
 function quote(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
@@ -134,6 +137,7 @@ function prepare() {
   }
   console.log(identity);
   console.log(`已在 ${directory} 准备好 ${name}`);
+  console.log('包含 evals、hooks、scripts 及依赖资料；评测需主动运行，Hook 需按宿主事件协议启用。');
   if (host === 'extract') return;
   console.log('\n请在目标宿主中执行以下原生命令注册并启用插件：');
   const selector = `${name}@${name}`;
@@ -198,11 +202,15 @@ 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}`);
+    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(`中文评测：node "${path.join(target.scriptsDirectory, 'run-evals.cjs')}" --locale zh-CN --min-rank1 95`);
+    console.log(`Hook：${target.hooksDirectory}（尚未启用）`);
   }
+  for (const directory of plan.preserved || []) console.log(`旧目录中保留了用户文件：${directory}`);
   console.log('请重新加载 IDE 窗口或新建宿主会话以发现安装内容。');
   if (plan.agents.some(id => !['codebuddy', 'workbuddy', 'claude-code'].includes(id))) console.log('这些工具通过技能 ID 调用；生命周期短命令支持取决于宿主。');
-  console.log('原生技能安装完成；插件 Hook 需按宿主方式注册和启用。');
-  if (plan.agents.some(id => ['codebuddy', 'codex', 'claude-code'].includes(id))) console.log('如需 CodeBuddy、Codex 或 Claude Code 完整插件，请使用 --prepare 和对应宿主参数。');
+  console.log('安装完成。评测说明见 evals/i3-composer-agent/README.md；Hook 需按宿主事件协议启用。');
 }
 main().catch(error => { console.error(`${name}: ${error.message}`); process.exitCode = 1; });

package/bin/install.cjs

@@ -6,11 +6,13 @@ 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 } = require('./native-migration.cjs');
 const { fingerprint } = require('./asset-fingerprint.cjs');
 const root = path.resolve(__dirname, '..');
 const name = 'i3-composer-agent';
 const version = require('../package.json').version;
+const pluginFiles = require('../package.json').i3ComposerAgent.pluginFiles;
 const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
 function exists(file) {
   try { fs.lstatSync(file); return true; }
@@ -46,9 +48,12 @@ function checkDestination(file) {
     throw new Error('安装目标必须位于包目录之外。');
   }
 }
+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 => path.relative(asset.base, item.destination)) }, null, 2) + '\n';
+  return JSON.stringify({ name, version, layoutVersion: 2, 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);
@@ -59,30 +64,26 @@ 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'), base });
+    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, referencesDirectory: path.join(base, 'references', name),
+      commandsDirectory: path.join(base, 'commands'), personasDirectory: path.join(base, 'agents'),
+      evalsDirectory: path.join(base, 'evals', name), scriptsDirectory: path.join(base, 'scripts', name),
+      hooksDirectory: path.join(base, 'hooks', name), docsDirectory: path.join(base, 'docs', name), 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()
       ? JSON.parse(fs.readFileSync(manifestFile, 'utf8')) : undefined;
     const owned = previous?.name === name && Array.isArray(previous.assets);
-    const sameVersion = owned && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
+    // 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.layoutVersion === 2 && 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);
@@ -92,49 +93,38 @@ 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' });
-    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 => path.relative(target.base, asset.destination)));
-      for (const relative of previous.assets) {
-        // Only installer-owned top-level assets can be retired. Ignore malformed
-        // or escaping manifest paths rather than extending their deletion scope.
-        if (typeof relative !== 'string' || !/^(skills|commands|agents|references)\/[^/\\]+$/.test(relative)
-          || relative.includes('\0') || ['.', '..'].includes(relative.split('/')[1])) 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 && previous.assets.some(relative => relative === asset.relative
+        || (previous.layoutVersion !== 2 && asset.relative.startsWith(relative + '/')));
+      asset.protectedResource = /^(references|evals|hooks|scripts|docs)\//.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;
       asset.personasDirectory = target.personasDirectory;
-      if (sameVersion && previous.assets.includes(path.relative(target.base, asset.destination)) && asset.source && exists(asset.destination)) {
+      if (sameVersion && previous.assets.includes(assetPath(target.base, asset.destination)) && asset.source && exists(asset.destination)) {
         asset.expectedFingerprint = fingerprint(asset.source, asset);
         asset.reusable = fingerprint(asset.destination) === asset.expectedFingerprint;
       }
     }
   }
   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);
@@ -158,13 +148,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()) {
@@ -178,16 +161,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';
-        } });
-        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;
@@ -210,12 +199,14 @@ function executeInstallation(plan, { force = false } = {}) {
         change.written = true;
       }
     }
+    pruneRetiredDirectories(plan.assets);
     completed = true;
+    plan.preserved = plan.targets.map(target => path.join(target.base, name)).filter(file => exists(file));
     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;