@betterdanlins/ai-memory 0.1.0 → 0.4.0

package/src/framework.js

@@ -0,0 +1,260 @@
+import { createHash } from 'node:crypto';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildManifest } from './manifest.js';
+import { matchesLegacyV01Baseline } from './legacy-v0.1.js';
+import { migrationsBetween } from './migrations.js';
+import { assertNoSymlinkPath, resolveSafeDestination } from './path-safety.js';
+import { render } from './render.js';
+import { ScaffoldError } from './scaffold.js';
+
+export const CURRENT_SCHEMA_VERSION = 1;
+export const METADATA_DEST = '.ai/ai-memory.json';
+
+const USER_PREFIXES = [
+  '.ai/config/',
+  '.ai/memory/',
+  'docs/architecture/',
+  'docs/requirements/v',
+  'docs/design/v',
+];
+
+const MIXED_FILES = new Set(['AGENTS.md', 'CLAUDE.md', '.claude/settings.json']);
+const FRAMEWORK_EXCEPTIONS = new Set(['docs/requirements/README.md', 'docs/design/README.md']);
+
+export function ownershipFor(dest) {
+  if (MIXED_FILES.has(dest)) return 'mixed';
+  if (FRAMEWORK_EXCEPTIONS.has(dest)) return 'framework';
+  if (USER_PREFIXES.some(prefix => dest.startsWith(prefix))) return 'user';
+  return 'framework';
+}
+
+export function hashContent(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export async function detectInstallation(targetDir) {
+  const metadataPath = path.join(targetDir, '.ai', 'ai-memory.json');
+  try {
+    const metadata = JSON.parse(await readFile(metadataPath, 'utf8'));
+    validateMetadata(metadata, metadataPath);
+    return { kind: 'metadata', metadata };
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      if (err instanceof SyntaxError) throw new Error(`框架元数据不是有效 JSON: ${metadataPath}`, { cause: err });
+      throw err;
+    }
+  }
+
+  const readmePath = path.join(targetDir, '.ai', 'README.md');
+  try {
+    const readme = await readFile(readmePath, 'utf8');
+    if (readme.includes('@betterdanlins/ai-memory')) {
+      const facts = await readLegacyFacts(targetDir, readme);
+      return { kind: 'legacy', version: '0.1.0', schemaVersion: 0, ...facts };
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  return { kind: 'none' };
+}
+
+export async function writeFrameworkMetadata({
+  targetDir, templatesRoot, frameworkVersion, tools, projectName, techStack, date, previousMetadata,
+}) {
+  const manifest = await buildManifest(templatesRoot, tools);
+  const files = {};
+  for (const { dest } of manifest) {
+    const content = await readFile(path.join(targetDir, ...dest.split('/')), 'utf8');
+    files[dest] = { ownership: ownershipFor(dest), sha256: hashContent(content) };
+  }
+
+  const metadata = {
+    frameworkVersion,
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    generatedAt: previousMetadata?.generatedAt ?? new Date().toISOString(),
+    ...(previousMetadata ? { updatedAt: new Date().toISOString() } : {}),
+    tools: [...tools],
+    templateVars: { projectName, techStack, date },
+    files,
+  };
+  const metadataPath = path.join(targetDir, '.ai', 'ai-memory.json');
+  await mkdir(path.dirname(metadataPath), { recursive: true });
+  await writeFile(metadataPath, JSON.stringify(metadata, null, 2) + '\n', { flag: previousMetadata ? 'w' : 'wx' });
+  return metadata;
+}
+
+export async function planFrameworkUpdate({ targetDir, templatesRoot, frameworkVersion }) {
+  const installation = await detectInstallation(targetDir);
+  if (installation.kind === 'none') throw new Error('当前目录不是 ai-memory 项目,请先运行 init');
+
+  const tools = installation.kind === 'metadata' ? installation.metadata.tools : installation.tools;
+  const rawVars = installation.kind === 'metadata' ? installation.metadata.templateVars : installation.templateVars;
+  const vars = { modelProfile: 'inherit', ...rawVars, frameworkVersion };
+  if (installation.kind === 'metadata' && compareVersions(installation.metadata.frameworkVersion, frameworkVersion) > 0) {
+    throw new Error(`项目框架版本 ${installation.metadata.frameworkVersion} 高于当前 CLI ${frameworkVersion},请使用更新版本的 CLI`);
+  }
+  const fromSchema = installation.kind === 'metadata' ? installation.metadata.schemaVersion : 0;
+  const migrations = migrationsBetween(fromSchema, CURRENT_SCHEMA_VERSION);
+  const manifest = await buildManifest(templatesRoot, tools);
+  const desiredDests = new Set(manifest.map(({ dest }) => dest));
+  const actions = [];
+
+  for (const { src, dest } of manifest) {
+    const desired = render(await readFile(src, 'utf8'), vars);
+    const current = await readOptional(path.join(targetDir, ...dest.split('/')));
+    const ownership = ownershipFor(dest);
+    if (current === undefined) {
+      actions.push({ action: 'add', dest, ownership });
+      continue;
+    }
+
+    const currentHash = hashContent(current);
+    const desiredHash = hashContent(desired);
+    if (currentHash === desiredHash) {
+      actions.push({ action: 'unchanged', dest, ownership });
+    } else if (ownership === 'user') {
+      actions.push({ action: 'preserve', dest, ownership });
+    } else {
+      const matchesBaseline = installation.kind === 'metadata'
+        ? installation.metadata.files[dest]?.sha256 === currentHash
+        : matchesLegacyV01Baseline(dest, current, vars);
+      const action = matchesBaseline ? 'update' : ownership === 'mixed' ? 'merge' : 'review';
+      actions.push({ action, dest, ownership, currentHash, desiredHash });
+    }
+  }
+
+  if (installation.kind === 'metadata') {
+    for (const [dest, record] of Object.entries(installation.metadata.files)) {
+      if (desiredDests.has(dest) || !(await exists(path.join(targetDir, ...dest.split('/'))))) continue;
+      actions.push({
+        action: record.ownership === 'user' ? 'preserve' : 'review-remove',
+        dest,
+        ownership: record.ownership,
+      });
+    }
+  }
+
+  return {
+    installation,
+    frameworkVersion,
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    tools,
+    templateVars: vars,
+    migrations,
+    actions,
+  };
+}
+
+export async function applyFrameworkUpdate({ targetDir, templatesRoot, plan }) {
+  const blockers = plan.actions.filter(item => ['merge', 'review', 'review-remove'].includes(item.action));
+  if (blockers.length) {
+    throw new Error(`存在 ${blockers.length} 个需合并/审查项,未写入任何文件:\n${blockers.map(item => `- ${item.dest}`).join('\n')}`);
+  }
+  const manualMigrations = plan.migrations.filter(item => !item.automatic);
+  if (manualMigrations.length) {
+    throw new Error(`存在不可自动执行的 Schema 迁移: ${manualMigrations.map(item => item.id).join(', ')}`);
+  }
+
+  const vars = plan.templateVars;
+  const manifest = await buildManifest(templatesRoot, plan.tools);
+  const sources = new Map(manifest.map(entry => [entry.dest, entry.src]));
+  const candidates = [];
+
+  for (const action of plan.actions.filter(item => item.action === 'add' || item.action === 'update')) {
+    const src = sources.get(action.dest);
+    if (!src) throw new Error(`升级计划缺少当前模板: ${action.dest}`);
+    const destPath = resolveSafeDestination(targetDir, action.dest);
+    await assertNoSymlinkPath(targetDir, destPath);
+    if (action.action === 'update') {
+      const current = await readFile(destPath, 'utf8');
+      if (action.currentHash && hashContent(current) !== action.currentHash) {
+        throw new Error(`文件在预检后发生变化,请重新 dry-run: ${action.dest}`);
+      }
+    }
+    candidates.push({ ...action, destPath, content: render(await readFile(src, 'utf8'), vars) });
+  }
+
+  const summary = { written: [], skipped: [], imported: [], fallback: [] };
+  for (const [index, item] of candidates.entries()) {
+    try {
+      await mkdir(path.dirname(item.destPath), { recursive: true });
+      await writeFile(item.destPath, item.content, { flag: item.action === 'add' ? 'wx' : 'w' });
+      summary.written.push(item.dest);
+    } catch (err) {
+      throw new ScaffoldError({
+        phase: 'update', dest: item.dest, destPath: item.destPath, cause: err, summary,
+        notWritten: candidates.slice(index).map(({ dest }) => dest),
+      });
+    }
+  }
+
+  const previousMetadata = plan.installation.kind === 'metadata' ? plan.installation.metadata : undefined;
+  try {
+    await writeFrameworkMetadata({
+      targetDir,
+      templatesRoot,
+      frameworkVersion: plan.frameworkVersion,
+      tools: plan.tools,
+      projectName: vars.projectName,
+      techStack: vars.techStack,
+      date: vars.date,
+      previousMetadata,
+    });
+    summary.written.push(METADATA_DEST);
+  } catch (err) {
+    throw new ScaffoldError({
+      phase: 'update', dest: METADATA_DEST, destPath: path.join(targetDir, '.ai', 'ai-memory.json'),
+      cause: err, summary, notWritten: [METADATA_DEST],
+    });
+  }
+  return summary;
+}
+
+async function readLegacyFacts(targetDir, readme) {
+  const state = await readOptional(path.join(targetDir, '.ai', 'memory', 'project-state.md')) ?? '';
+  const projectName = state.match(/^- 项目:(.+)$/m)?.[1]?.trim() || path.basename(path.resolve(targetDir));
+  const techStack = state.match(/^- 技术栈:(.+)$/m)?.[1]?.trim() || '(待补充)';
+  const date = readme.match(/生成于 (\d{4}-\d{2}-\d{2})/)?.[1]
+    || state.match(/最后更新:(\d{4}-\d{2}-\d{2})/)?.[1]
+    || new Date().toISOString().slice(0, 10);
+  const tools = [];
+  if (await exists(path.join(targetDir, 'CLAUDE.md'))) tools.push('claude');
+  if (await exists(path.join(targetDir, 'AGENTS.md'))) tools.push('codex');
+  return { tools, templateVars: { projectName, techStack, date } };
+}
+
+function validateMetadata(metadata, metadataPath) {
+  if (!metadata || typeof metadata !== 'object') throw new Error(`框架元数据格式无效: ${metadataPath}`);
+  if (typeof metadata.frameworkVersion !== 'string' || !Number.isInteger(metadata.schemaVersion)) {
+    throw new Error(`框架元数据缺少版本字段: ${metadataPath}`);
+  }
+  if (!Array.isArray(metadata.tools) || !metadata.templateVars || !metadata.files) {
+    throw new Error(`框架元数据缺少安装基线: ${metadataPath}`);
+  }
+}
+
+async function readOptional(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return undefined;
+    throw err;
+  }
+}
+
+const exists = filePath => access(filePath).then(() => true, err => {
+  if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return false;
+  throw err;
+});
+
+function compareVersions(left, right) {
+  const parse = value => value.split('-', 1)[0].split('.').map(part => Number.parseInt(part, 10) || 0);
+  const a = parse(left);
+  const b = parse(right);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const difference = (a[i] ?? 0) - (b[i] ?? 0);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return 0;
+}

package/src/legacy-v0.1.js

@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto';
+
+const BASELINE_HASHES = {
+  '.ai/README.md': '5398a845005031d7905faeae29b2891af94eaaf7104b415e5fed3657fc42ee2f',
+  'CLAUDE.md': '1ab2be083986c96f13ff126daf8f0d77ceff9918e695996e10706c1f1770d866',
+  'AGENTS.md': 'b8f49a179b35f2c111450d24a840fc964cc3049dc3cc0b87c8193e1940fb7a42',
+  '.claude/agents/critic.md': 'e3686c1735337b06fc3679de7302b477b1cff851f162d72a5ee855d86e7e8501',
+  '.claude/commands/critic.md': 'cca4f2f98542c340fd169c55ac60c77a8cade348059d5f21374dfa0589225ff4',
+  '.claude/commands/finalize-requirement.md': '3e0613d64d9f9e91d6f801fab77eec016cd874f3ca3ccd63118e24dd281a4158',
+  '.claude/commands/new-requirement.md': 'f6409b11e74f0d134c8856e87e39d0bc5dc3760269e9be0bf954668ce7e1f0c3',
+  '.claude/commands/update-memory.md': '9fa499b665763a9d25e09a7aa20b4dca22216f5ef32f411c643ccc5c096b7617',
+  '.claude/settings.json': '7a800ca223aef127d4872baa481e7d75a8adc3c278e59d1e8383b58bfe9f8a29',
+  '.claude/skills/critic/SKILL.md': '2d1537599c3f01dd03103fb1ad6777a439179561c0d054d17d120542b458faeb',
+  '.claude/skills/memory-update/SKILL.md': 'c63cb7c3ff2b6e20f61619703112e3f0a75c22e9d37deabb38e40655c15f66d7',
+  '.claude/skills/requirements-flow/SKILL.md': '41bcad8765c3f1d44821a4fecc6322b0534a166ef1362161300e434bbe9593c1',
+  '.agents/skills/critic/SKILL.md': 'c9cb6471ab6c45360177a18b1ed7a900d943b16ae0e19045374e2767655c5da8',
+  '.agents/skills/memory-update/SKILL.md': 'c63cb7c3ff2b6e20f61619703112e3f0a75c22e9d37deabb38e40655c15f66d7',
+  '.agents/skills/requirements-flow/SKILL.md': '3417925a8fff47e7990739c04eab7a9a4a598372c73ff3be6b8b9683871a6dd7',
+  '.ai/skills/architecture.md': 'd67e2275b8bc2797a5644d2eacbc0e4d23e04cf3e980e41f2081f556f0e243a8',
+  '.ai/skills/code-review.md': 'c241b82763e8ee5948bac6ce2a00437347b95b18e5cad09d07669c75881cc1d9',
+  '.ai/skills/critic.md': '24efea9e792435fbc1f3ff7204f153f33dd8c27bded656b2877ca6c84ef53d05',
+  '.ai/skills/memory-update.md': '5d5e61cae831a5d74744f579fc6f550abfd42a3ef287bf791b4c9e2a235638e8',
+  '.ai/skills/requirements-flow.md': 'b95f2649002cd028fc72122d243e39c16365aa1ed9b38d390522db7542b75f21',
+  'docs/requirements/README.md': '968085f9824686deb3282ab7e82970899a73a06e8ccb31c55e6aadd8e87d91ec',
+};
+
+const VARIABLE_KEYS = {
+  '.ai/README.md': ['projectName', 'date'],
+  'CLAUDE.md': ['projectName', 'techStack'],
+  'AGENTS.md': ['projectName', 'techStack'],
+};
+
+export function matchesLegacyV01Baseline(dest, content, vars) {
+  const baseline = BASELINE_HASHES[dest];
+  if (!baseline) return false;
+  let normalized = content;
+  for (const key of VARIABLE_KEYS[dest] ?? []) {
+    const value = String(vars[key] ?? '');
+    if (!value) return false;
+    normalized = normalized.replaceAll(value, `{{${key}}}`);
+  }
+  return createHash('sha256').update(normalized).digest('hex') === baseline;
+}

package/src/manifest.js

@@ -16,7 +16,26 @@ export async function buildManifest(templatesRoot, tools) {
       entries.push({ src: path.join(groupDir, ...rel.split('/')), dest: rel });
     }
   }
-  return entries.sort((a, b) => a.dest < b.dest ? -1 : a.dest > b.dest ? 1 : 0);
+  const sorted = entries.sort((a, b) => a.dest < b.dest ? -1 : a.dest > b.dest ? 1 : 0);
+  assertUniqueDestinations(sorted);
+  return sorted;
+}
+
+function assertUniqueDestinations(entries) {
+  const sourcesByDest = new Map();
+  for (const { src, dest } of entries) {
+    const sources = sourcesByDest.get(dest) ?? [];
+    sources.push(src);
+    sourcesByDest.set(dest, sources);
+  }
+
+  const conflicts = [...sourcesByDest]
+    .filter(([, sources]) => sources.length > 1)
+    .map(([dest, sources]) => `- ${dest}\n${sources.map(src => `  - ${src}`).join('\n')}`);
+
+  if (conflicts.length > 0) {
+    throw new Error(`Duplicate template destinations:\n${conflicts.join('\n')}`);
+  }
 }
 
 async function walk(dir, prefix) {

package/src/migrations.js

@@ -0,0 +1,28 @@
+export const MIGRATIONS = [
+  {
+    id: 'bootstrap-schema-v1',
+    from: 0,
+    to: 1,
+    automatic: true,
+    description: '为无元数据的 legacy 项目建立所有权与生成基线;既有文件保持保守审查',
+  },
+];
+
+export function migrationsBetween(from, to) {
+  if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to < 0) {
+    throw new Error(`无效 Schema 版本: ${from} → ${to}`);
+  }
+  if (from > to) throw new Error(`项目 Schema ${from} 高于当前 CLI Schema ${to},请使用更新版本的 CLI`);
+
+  const result = [];
+  let current = from;
+  while (current < to) {
+    const migration = MIGRATIONS.find(item => item.from === current);
+    if (!migration || migration.to <= current || migration.to > to) {
+      throw new Error(`缺少 Schema 迁移路径: ${current} → ${to}`);
+    }
+    result.push(migration);
+    current = migration.to;
+  }
+  return result;
+}

package/src/model-routing.js

@@ -0,0 +1,108 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { assertNoSymlinkPath } from './path-safety.js';
+
+export const MODEL_ROUTING_DEST = '.ai/config/model-routing.json';
+export const MODEL_ROUTING_SCHEMA_VERSION = 1;
+
+export const STAGES = [
+  'brainstorm',
+  'requirement-finalize',
+  'feature-design',
+  'write-plan',
+  'implementation',
+  'routine-tests',
+  'test-execution',
+  'failure-diagnosis',
+  'adversarial-testing',
+  'final-review',
+];
+
+const PROFILES = {
+  inherit: Object.fromEntries(STAGES.map(stage => [stage, stage === 'test-execution' ? 'none' : 'inherit'])),
+  balanced: {
+    brainstorm: 'premium',
+    'requirement-finalize': 'premium',
+    'feature-design': 'premium',
+    'write-plan': 'premium',
+    implementation: 'standard',
+    'routine-tests': 'economy',
+    'test-execution': 'none',
+    'failure-diagnosis': 'standard',
+    'adversarial-testing': 'premium',
+    'final-review': 'premium',
+  },
+  quality: {
+    brainstorm: 'premium',
+    'requirement-finalize': 'premium',
+    'feature-design': 'premium',
+    'write-plan': 'premium',
+    implementation: 'premium',
+    'routine-tests': 'standard',
+    'test-execution': 'none',
+    'failure-diagnosis': 'premium',
+    'adversarial-testing': 'premium',
+    'final-review': 'premium',
+  },
+};
+
+export const MODEL_PROFILES = Object.freeze(Object.keys(PROFILES));
+
+export function createModelRoutingConfig(profile = 'inherit') {
+  assertProfile(profile);
+  return { schemaVersion: MODEL_ROUTING_SCHEMA_VERSION, profile, overrides: {} };
+}
+
+export function resolveModelRouting(config) {
+  validateModelRoutingConfig(config);
+  return { ...PROFILES[config.profile], ...config.overrides };
+}
+
+export async function readModelRoutingConfig(targetDir) {
+  const configPath = path.join(targetDir, ...MODEL_ROUTING_DEST.split('/'));
+  await assertNoSymlinkPath(targetDir, configPath);
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new Error(`缺少模型路由配置: ${MODEL_ROUTING_DEST};请先更新 ai-memory 框架`);
+    if (err instanceof SyntaxError) throw new Error(`模型路由配置不是有效 JSON: ${MODEL_ROUTING_DEST}`, { cause: err });
+    throw err;
+  }
+  validateModelRoutingConfig(config);
+  return config;
+}
+
+export async function writeModelRoutingConfig(targetDir, config) {
+  validateModelRoutingConfig(config);
+  const configPath = path.join(targetDir, ...MODEL_ROUTING_DEST.split('/'));
+  await assertNoSymlinkPath(targetDir, configPath);
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+  return config;
+}
+
+export function validateModelRoutingConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('模型路由配置必须是对象');
+  }
+  if (config.schemaVersion !== MODEL_ROUTING_SCHEMA_VERSION) {
+    throw new Error(`不支持的模型路由 Schema: ${config.schemaVersion}`);
+  }
+  assertProfile(config.profile);
+  if (!config.overrides || typeof config.overrides !== 'object' || Array.isArray(config.overrides)) {
+    throw new Error('模型路由 overrides 必须是对象');
+  }
+  for (const [stage, tier] of Object.entries(config.overrides)) {
+    if (!STAGES.includes(stage)) throw new Error(`未知模型路由阶段: ${stage}`);
+    if (!['inherit', 'premium', 'standard', 'economy', 'none'].includes(tier)) {
+      throw new Error(`阶段 ${stage} 的模型等级无效: ${tier}`);
+    }
+  }
+}
+
+function assertProfile(profile) {
+  if (!MODEL_PROFILES.includes(profile)) {
+    throw new Error(`model profile 仅支持 ${MODEL_PROFILES.join('、')},收到: ${profile}`);
+  }
+}

package/src/path-safety.js

@@ -0,0 +1,51 @@
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+
+export function resolveSafeDestination(targetDir, dest) {
+  if (typeof dest !== 'string' || dest.length === 0) {
+    throw new Error('模板目标路径必须是非空相对路径');
+  }
+  if (dest.includes('\\')) {
+    throw new Error(`模板目标路径必须使用 "/" 分隔: ${dest}`);
+  }
+  if (path.posix.isAbsolute(dest) || path.win32.isAbsolute(dest) || /^[A-Za-z]:/.test(dest)) {
+    throw new Error(`模板目标路径不能是绝对路径: ${dest}`);
+  }
+
+  const segments = dest.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw new Error(`模板目标路径包含无效路径段: ${dest}`);
+  }
+
+  const root = path.resolve(targetDir);
+  const destination = path.resolve(root, ...segments);
+  const relative = path.relative(root, destination);
+  if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`模板目标路径超出目标目录: ${dest}`);
+  }
+  return destination;
+}
+
+export async function assertNoSymlinkPath(targetDir, destPath) {
+  const root = path.resolve(targetDir);
+  const destination = path.resolve(destPath);
+  const relative = path.relative(root, destination);
+  if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`目标路径不在目标目录内: ${destPath}`);
+  }
+
+  let current = root;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    let stats;
+    try {
+      stats = await lstat(current);
+    } catch (err) {
+      if (err.code === 'ENOENT') return;
+      throw err;
+    }
+    if (stats.isSymbolicLink()) {
+      throw new Error(`目标路径包含符号链接或 junction: ${current}`);
+    }
+  }
+}

package/src/scaffold.js

@@ -1,33 +1,134 @@
-import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { mkdir, readFile, writeFile, access, lstat, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { buildManifest } from './manifest.js';
+import { assertNoSymlinkPath, resolveSafeDestination } from './path-safety.js';
 import { render } from './render.js';
 
 const IMPORT_DESTS = new Set(['.ai/memory/user-profile.md', '.ai/memory/feedback.md']);
 
+export class ScaffoldError extends Error {
+  constructor({ phase, dest, destPath, cause, summary, notWritten }) {
+    super(`生成 ${dest} 失败(${phase}): ${cause.message}`, { cause });
+    this.name = 'ScaffoldError';
+    this.code = phase === 'prepare' ? 'SCAFFOLD_PREPARE_FAILED' : 'SCAFFOLD_WRITE_FAILED';
+    this.phase = phase;
+    this.dest = dest;
+    this.destPath = destPath;
+    this.summary = copySummary(summary);
+    this.notWritten = [...notWritten];
+  }
+}
+
 export async function scaffold({ templatesRoot, targetDir, vars, tools, onConflict, importFrom }) {
+  const importRoot = importFrom ? await validateImportRoot(importFrom) : undefined;
   const manifest = await buildManifest(templatesRoot, tools);
-  const summary = { written: [], skipped: [] };
-  for (const { src, dest } of manifest) {
-    const destPath = path.join(targetDir, ...dest.split('/'));
+  const summary = { written: [], skipped: [], imported: [], fallback: [] };
+  const candidates = [];
+
+  for (const entry of manifest) {
+    const destPath = resolveSafeDestination(targetDir, entry.dest);
     if (await exists(destPath)) {
+      const { dest } = entry;
       if ((await onConflict(dest)) !== 'overwrite') { summary.skipped.push(dest); continue; }
     }
+    candidates.push({ ...entry, destPath });
+  }
+
+  for (const { destPath } of candidates) {
+    await assertNoSymlinkPath(targetDir, destPath);
+  }
+
+  const planned = [];
+  for (const candidate of candidates) {
+    const { src, dest, destPath } = candidate;
     let content;
-    if (importFrom && IMPORT_DESTS.has(dest)) {
-      const importSrc = path.join(importFrom, '.ai', 'memory', path.basename(dest));
-      if (await exists(importSrc)) {
-        content = await readFile(importSrc, 'utf8');
+    let source = 'template';
+    try {
+      if (importRoot && IMPORT_DESTS.has(dest)) {
+        const importSrc = path.join(importRoot, '.ai', 'memory', path.basename(dest));
+        content = await readOptionalImport(importSrc);
+        source = content === undefined ? 'fallback' : 'import';
+      }
+      if (content === undefined) {
+        content = render(await readFile(src, 'utf8'), vars);
       }
+    } catch (err) {
+      throw new ScaffoldError({
+        phase: 'prepare', dest, destPath, cause: err, summary,
+        notWritten: candidates.map(({ dest: pending }) => pending),
+      });
+    }
+    planned.push({ dest, destPath, content, source });
+  }
+
+  for (const [index, item] of planned.entries()) {
+    const { dest, destPath, content, source } = item;
+    try {
+      await mkdir(path.dirname(destPath), { recursive: true });
+    } catch (err) {
+      throw writeError('mkdir', item, err, summary, planned, index);
     }
-    if (content === undefined) {
-      content = render(await readFile(src, 'utf8'), vars);
+    try {
+      await writeFile(destPath, content);
+    } catch (err) {
+      throw writeError('write', item, err, summary, planned, index);
     }
-    await mkdir(path.dirname(destPath), { recursive: true });
-    await writeFile(destPath, content);
     summary.written.push(dest);
+    if (source === 'import') summary.imported.push(dest);
+    if (source === 'fallback') summary.fallback.push(dest);
   }
   return summary;
 }
 
-const exists = (p) => access(p).then(() => true, () => false);
+async function exists(filePath) {
+  try {
+    await lstat(filePath);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return false;
+    throw err;
+  }
+}
+
+function writeError(phase, item, cause, summary, planned, index) {
+  return new ScaffoldError({
+    phase,
+    dest: item.dest,
+    destPath: item.destPath,
+    cause,
+    summary,
+    notWritten: planned.slice(index).map(({ dest }) => dest),
+  });
+}
+
+function copySummary(summary) {
+  return Object.fromEntries(Object.entries(summary).map(([key, value]) => [key, [...value]]));
+}
+
+async function validateImportRoot(importFrom) {
+  const root = path.resolve(importFrom);
+  let info;
+  try {
+    info = await stat(root);
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new Error(`导入目录不存在: ${root}`, { cause: err });
+    throw new Error(`无法访问导入目录 ${root}: ${err.message}`, { cause: err });
+  }
+  if (!info.isDirectory()) throw new Error(`导入路径不是目录: ${root}`);
+  try {
+    await access(root, constants.R_OK);
+  } catch (err) {
+    throw new Error(`导入目录不可读 ${root}: ${err.message}`, { cause: err });
+  }
+  return root;
+}
+
+async function readOptionalImport(importSrc) {
+  try {
+    return await readFile(importSrc, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return undefined;
+    throw new Error(`无法读取导入文件 ${importSrc}: ${err.message}`, { cause: err });
+  }
+}