autosnippet 3.2.9 → 3.2.11

package/lib/shared/PathGuard.js

@@ -1,326 +0,0 @@
-/**
- * PathGuard — 文件写入路径安全守卫（双层防护）
- *
- * 防止 AutoSnippet 在项目目录之外 或 项目内非法位置 创建文件。
- * BiliDemo/data 事件的根因：process.cwd() 解析到非预期目录，DB/日志等写操作
- * 逃逸到用户项目外，创建了脏数据。
- *
- * 双层防护：
- *  Layer 1 — assertSafe(path):
- *    边界检查，拦截写到 projectRoot 外的操作
- *  Layer 2 — assertProjectWriteSafe(path):
- *    项目内作用域检查，仅允许写入以下前缀：
- *      .autosnippet/     — 运行时 DB、记忆、对话、信号快照
- *      {kbDir}/          — 知识库（recipes、candidates、skills、guard 文件）
- *      .cursor/          — Cursor IDE 集成
- *      .vscode/          — VSCode 集成
- *      .github/          — Copilot instructions
- *      .gitignore        — 追加忽略规则
- *    项目内其他位置（如 data/、src/ 等）一律拦截
- *
- * 设计：
- *  - 单例模式，通过 configure() 绑定 projectRoot
- *  - 新建文件/目录前调用 assertProjectWriteSafe() 校验
- *  - 修改已有文件前调用 assertSafe() 校验（不限制项目内位置）
- *  - 允许白名单目录（Xcode snippets、全局缓存等）
- *  - 错误不静默：越界写操作抛出 PathGuardError
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-export class PathGuardError extends Error {
-  /**
-   * @param {string} targetPath - 被拦截的目标路径
-   * @param {string} projectRoot - 当前项目根目录
-   * @param {string} [reason] - 拦截原因
-   */
-  constructor(targetPath, projectRoot, reason) {
-    const msg = reason
-      ? `[PathGuard] ${reason}: "${targetPath}"`
-      : `[PathGuard] 写入路径越界: "${targetPath}" 不在允许范围内。`;
-    super(
-      msg +
-        `\n  projectRoot: ${projectRoot}` +
-        `\n  提示: 检查 process.cwd() 或 projectRoot 配置是否正确`
-    );
-    this.name = 'PathGuardError';
-    this.targetPath = targetPath;
-    this.projectRoot = projectRoot;
-  }
-}
-
-/**
- * 项目内允许 AutoSnippet 创建新文件/目录的前缀
- * 注意：这是相对于 projectRoot 的前缀列表
- */
-const PROJECT_WRITE_SCOPE_PREFIXES = [
-  '.autosnippet', // 运行时 DB、记忆、对话、信号快照
-  '.cursor', // Cursor IDE 集成
-  '.vscode', // VSCode 集成
-  '.github', // Copilot instructions
-];
-
-/**
- * 项目根目录下允许直接写入的文件（非目录前缀匹配）
- */
-const PROJECT_ROOT_WRITABLE_FILES = ['.gitignore', '.env'];
-
-class PathGuard {
-  /** @type {string|null} 项目根目录（绝对路径） */
-  #projectRoot = null;
-
-  /** @type {string|null} AutoSnippet 包自身根目录 */
-  #packageRoot = null;
-
-  /** @type {Set<string>} 额外允许的绝对路径前缀 */
-  #allowList = new Set();
-
-  /** @type {string|null} 知识库目录名（如 'AutoSnippet'） */
-  #knowledgeBaseDir = null;
-
-  /** @type {boolean} 是否已配置 */
-  #configured = false;
-
-  /**
-   * 配置 PathGuard（每个进程执行一次）
-   * @param {object} opts
-   * @param {string} opts.projectRoot - 用户项目根目录（绝对路径）
-   * @param {string} [opts.packageRoot] - AutoSnippet 包自身根目录
-   * @param {string} [opts.knowledgeBaseDir='AutoSnippet'] - 知识库目录名
-   * @param {string[]} [opts.extraAllowPaths] - 额外允许的路径前缀
-   */
-  configure({ projectRoot, packageRoot, knowledgeBaseDir, extraAllowPaths = [] }) {
-    if (!projectRoot || !path.isAbsolute(projectRoot)) {
-      throw new Error(`[PathGuard] projectRoot 必须是绝对路径，收到: "${projectRoot}"`);
-    }
-
-    this.#projectRoot = path.resolve(projectRoot);
-    this.#packageRoot = packageRoot ? path.resolve(packageRoot) : null;
-    this.#knowledgeBaseDir = knowledgeBaseDir || null; // 延迟解析
-
-    // 默认白名单：全局缓存 + 平台 Snippets 目录
-    const HOME = process.env.HOME || process.env.USERPROFILE || '';
-    if (HOME) {
-      this.#allowList.add(path.join(HOME, '.autosnippet', 'cache'));
-      this.#allowList.add(path.join(HOME, '.autosnippet', 'snippets'));
-      if (process.platform === 'darwin') {
-        this.#allowList.add(path.join(HOME, 'Library/Developer/Xcode/UserData/CodeSnippets'));
-      }
-    }
-
-    // 用户自定义白名单
-    for (const p of extraAllowPaths) {
-      if (path.isAbsolute(p)) {
-        this.#allowList.add(path.resolve(p));
-      }
-    }
-
-    this.#configured = true;
-  }
-
-  /** 是否已配置 */
-  get configured() {
-    return this.#configured;
-  }
-
-  /** 当前 projectRoot */
-  get projectRoot() {
-    return this.#projectRoot;
-  }
-
-  /**
-   * 设置知识库目录名（可在 configure 之后延迟设置）
-   * @param {string} dirName - 如 'AutoSnippet'、'Knowledge' 等
-   */
-  setKnowledgeBaseDir(dirName) {
-    if (dirName && typeof dirName === 'string') {
-      this.#knowledgeBaseDir = dirName;
-    }
-  }
-
-  /**
-   * Layer 1: 断言路径在允许的边界范围内
-   * 用于修改已有文件的场景（如 XcodeIntegration 插入 header、SpmHelper 修改 Package.swift）
-   * @param {string} targetPath - 要写入的绝对路径
-   * @throws {PathGuardError}
-   */
-  assertSafe(targetPath) {
-    if (!this.#configured) {
-      return;
-    }
-
-    if (!targetPath || typeof targetPath !== 'string') {
-      throw new PathGuardError(String(targetPath), this.#projectRoot);
-    }
-
-    const resolved = path.resolve(targetPath);
-
-    // 1. 项目目录内 — 允许
-    if (this.#isUnder(resolved, this.#projectRoot)) {
-      return;
-    }
-
-    // 2. AutoSnippet 包自身目录内（logs/ 等）— 允许
-    if (this.#packageRoot && this.#isUnder(resolved, this.#packageRoot)) {
-      return;
-    }
-
-    // 3. 白名单目录 — 允许
-    for (const allowed of this.#allowList) {
-      if (this.#isUnder(resolved, allowed)) {
-        return;
-      }
-    }
-
-    // 越界
-    throw new PathGuardError(resolved, this.#projectRoot);
-  }
-
-  /**
-   * Layer 2: 断言路径在项目内允许的写入作用域中
-   * 用于创建新目录/新文件的场景（如 mkdirSync、writeFileSync 创建新文件）
-   * 比 assertSafe() 更严格：即使在 projectRoot 内，也只允许写入特定前缀
-   * @param {string} targetPath - 要创建的绝对路径
-   * @throws {PathGuardError}
-   */
-  assertProjectWriteSafe(targetPath) {
-    if (!this.#configured) {
-      return;
-    }
-
-    // 先做边界检查
-    this.assertSafe(targetPath);
-
-    const resolved = path.resolve(targetPath);
-
-    // 如果不在 projectRoot 内（在白名单/packageRoot 中），跳过项目内检查
-    if (!this.#isUnder(resolved, this.#projectRoot)) {
-      return;
-    }
-
-    // 计算相对于 projectRoot 的路径
-    const relative = path.relative(this.#projectRoot, resolved);
-    const firstSegment = relative.split(path.sep)[0];
-
-    // 检查是否在允许的前缀中
-    for (const prefix of PROJECT_WRITE_SCOPE_PREFIXES) {
-      if (firstSegment === prefix) {
-        return;
-      }
-    }
-
-    // 检查知识库目录（动态解析）
-    const kbDir = this.#resolveKnowledgeBaseDir();
-    if (kbDir && firstSegment === kbDir) {
-      return;
-    }
-
-    // 检查根目录可写文件（如 .gitignore）
-    if (PROJECT_ROOT_WRITABLE_FILES.includes(relative)) {
-      return;
-    }
-
-    // 不在允许的写入范围内
-    throw new PathGuardError(
-      resolved,
-      this.#projectRoot,
-      `项目内写入范围受限: "${relative}" 不在允许的目录中（允许: ${[...PROJECT_WRITE_SCOPE_PREFIXES, kbDir || 'AutoSnippet'].join(', ')}）`
-    );
-  }
-
-  /**
-   * 安全检查（不抛错，返回 boolean）
-   * @param {string} targetPath
-   * @returns {boolean}
-   */
-  isSafe(targetPath) {
-    try {
-      this.assertSafe(targetPath);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * 项目内写入范围检查（不抛错，返回 boolean）
-   * @param {string} targetPath
-   * @returns {boolean}
-   */
-  isProjectWriteSafe(targetPath) {
-    try {
-      this.assertProjectWriteSafe(targetPath);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * 将相对路径安全地解析到 projectRoot 下
-   * 替代 path.resolve(relativePath)（后者基于 cwd，不安全）
-   * @param {string} relativePath
-   * @returns {string} 绝对路径
-   */
-  resolveProjectPath(relativePath) {
-    if (!this.#configured || !this.#projectRoot) {
-      // 未配置时 fallback 到 cwd（向后兼容）
-      return path.resolve(relativePath);
-    }
-    const resolved = path.resolve(this.#projectRoot, relativePath);
-    this.assertSafe(resolved);
-    return resolved;
-  }
-
-  /**
-   * 重置状态（仅用于测试）
-   */
-  _reset() {
-    this.#projectRoot = null;
-    this.#packageRoot = null;
-    this.#allowList.clear();
-    this.#knowledgeBaseDir = null;
-    this.#configured = false;
-  }
-
-  /**
-   * resolved 是否在 base 目录下
-   */
-  #isUnder(resolved, base) {
-    return resolved === base || resolved.startsWith(base + path.sep);
-  }
-
-  /**
-   * 解析知识库目录名
-   * 优先使用 configure 阶段传入的值，否则尝试运行时探测
-   */
-  #resolveKnowledgeBaseDir() {
-    if (this.#knowledgeBaseDir) {
-      return this.#knowledgeBaseDir;
-    }
-
-    // 运行时探测: 查找包含 AutoSnippet.boxspec.json 的子目录
-    try {
-      const entries = fs.readdirSync(this.#projectRoot, { withFileTypes: true });
-      for (const e of entries) {
-        if (e.isDirectory() && !e.name.startsWith('.')) {
-          if (fs.existsSync(path.join(this.#projectRoot, e.name, 'AutoSnippet.boxspec.json'))) {
-            this.#knowledgeBaseDir = e.name;
-            return e.name;
-          }
-        }
-      }
-    } catch {
-      /* ignore */
-    }
-
-    // 默认
-    return 'AutoSnippet';
-  }
-}
-
-// 单例 — 整个进程共享
-const pathGuard = new PathGuard();
-
-export default pathGuard;

package/lib/shared/RecipeReadinessChecker.js

@@ -1,78 +0,0 @@
-/**
- * RecipeReadinessChecker — 共享 Recipe-Ready 字段完整性检查
- *
- * ⚠️ 已重构为 UnifiedValidator 的薄封装。
- * 保留此模块以兼容旧调用方签名，新代码请直接使用 UnifiedValidator。
- *
- * @param {object} item - 候选数据（扁平字段或含 metadata 的对象）
- * @returns {{ ready: boolean, missing: string[], suggestions: string[] }}
- */
-
-import { UnifiedValidator } from './UnifiedValidator.js';
-import { LanguageService } from './LanguageService.js';
-
-const STANDARD_CATEGORIES = [
-  'View',
-  'Service',
-  'Tool',
-  'Model',
-  'Network',
-  'Storage',
-  'UI',
-  'Utility',
-];
-
-/**
- * Bootstrap 等特殊来源使用的 category 白名单
- */
-const WHITELISTED_CATEGORIES = ['bootstrap', 'knowledge', 'general'];
-
-/**
- * 检查候选是否具备直接提升为 Recipe 的所有必要字段。
- *
- * 薄封装: 内部调用 UnifiedValidator，将结果转换为旧格式 { ready, missing, suggestions }。
- *
- * @param {object} item  扁平字段对象（title, trigger, description …）
- * @returns {{ ready: boolean, missing: string[], suggestions: string[] }}
- */
-export function checkRecipeReadiness(item) {
-  const validator = new UnifiedValidator();
-  const result = validator.validate(item, {
-    skipUniqueness: true, // readiness 检查不做去重
-  });
-
-  // 转换为旧格式: errors → missing 字段名, warnings → suggestions
-  const missing = [];
-  const suggestions = [];
-
-  for (const error of result.errors) {
-    // 从错误消息中提取字段名: "缺少必填字段: fieldName — rule"
-    const match = error.match(/缺少必填字段:\s*(\S+)/);
-    if (match) {
-      missing.push(match[1]);
-    }
-    suggestions.push(error);
-  }
-
-  for (const warning of result.warnings) {
-    suggestions.push(warning);
-  }
-
-  return { ready: missing.length === 0, missing, suggestions };
-}
-
-/**
- * 从 Candidate 的 metadata 对象展开为扁平字段后检查 readiness。
- */
-export function checkReadinessFromCandidate(candidate) {
-  const meta = candidate.metadata || {};
-  const flat = {
-    ...meta,
-    code: candidate.code,
-    language: candidate.language,
-    category: candidate.category,
-  };
-  return checkRecipeReadiness(flat);
-}
-
-export { STANDARD_CATEGORIES, WHITELISTED_CATEGORIES };

package/lib/shared/StyleGuide.js

@@ -1,107 +0,0 @@
-/**
- * StyleGuide.js — 项目特写写作指南（唯一权威来源）
- *
- * 供内部 Agent (bootstrap-producer.js) 和
- * 外部 Agent (MissionBriefing submissionSpec) 共享使用。
- *
- * @module shared/StyleGuide
- */
-
-import { V3_FIELD_SPEC, FieldLevel, VALID_KINDS } from './FieldSpec.js';
-
-// ── 「项目特写」写作指南全文 ────────────────────────────────
-
-export const PROJECT_SNAPSHOT_STYLE_GUIDE = `# 「项目特写」写作要求
-
-submit_knowledge 的 content.markdown 字段必须是「项目特写」。
-
-## 什么是「项目特写」
-将一种技术的**基本用法**与**本项目的具体特征**融合为一体。
-
-## 四大核心内容
-1. **项目选择了什么** — 采用了哪种写法/模式/约定
-2. **为什么这样选** — 统计分布、占比、历史决策
-3. **项目禁止什么** — 反模式、已废弃写法
-4. **新代码怎么写** — 可直接复制使用的代码模板 + 来源标注 (来源: FileName.ext:行号)
-
-## 格式要求
-- 标题使用项目真实类名/前缀，不用占位名
-- 代码来源标注: (来源: FileName.ext:行号)
-- 不要纯代码罗列，必须有项目上下文
-- 标题和正文中不得出现 "Agent" 字样`;
-
-// ── Cursor 交付字段规范（从 FieldSpec 自动生成） ────────────
-
-/**
- * 生成 Cursor 交付字段规范文本（供 Producer STYLE_GUIDE 和 MissionBriefing 使用）
- * @returns {string}
- */
-export function getCursorDeliverySpec() {
-  const required = [];
-  const expected = [];
-
-  for (const field of V3_FIELD_SPEC) {
-    // 跳过嵌套字段和非 Cursor 交付字段容器
-    if (field.name.includes('.')) continue;
-    if (['content', 'reasoning', 'title', 'description', 'headers',
-         'category', 'language', 'knowledgeType', 'usageGuide'].includes(field.name)) continue;
-
-    if (field.level === FieldLevel.REQUIRED) {
-      required.push(`- ${field.name}: ${field.rule}`);
-    } else if (field.level === FieldLevel.EXPECTED) {
-      expected.push(`- ${field.name}: ${field.rule}`);
-    }
-  }
-
-  const parts = [];
-  if (required.length > 0) {
-    parts.push('### 必填（REQUIRED）');
-    parts.push(required.join('\n'));
-  }
-  if (expected.length > 0) {
-    parts.push('### 推荐（EXPECTED）');
-    parts.push(expected.join('\n'));
-  }
-
-  parts.push(`\n### 规范`);
-  parts.push(`1. trigger 以 @ 开头，kebab-case，不得在同一批次重复`);
-  parts.push(`2. doClause 英文祈使句，不含中文`);
-  parts.push(`3. coreCode 是可直接复制到编辑器的纯代码`);
-  parts.push(`4. kind 根据内容本质判断：强制约束 → rule，实现模式 → pattern，项目事实 → fact`);
-
-  return parts.join('\n');
-}
-
-/**
- * 构建完整的 Producer STYLE_GUIDE（合并项目特写要求 + Cursor 交付字段规范）
- * @returns {string}
- */
-export function buildProducerStyleGuide() {
-  return [
-    PROJECT_SNAPSHOT_STYLE_GUIDE,
-    '',
-    '## Cursor 交付字段（每个 submit_knowledge 必须附带）',
-    '',
-    '每个候选必须提供以下交付字段，它们直接决定在 Cursor IDE 中作为 Rules 的展示质量。',
-    '注意：language / category / knowledgeType / source 由系统自动设置，无需填写。',
-    '',
-    getCursorDeliverySpec(),
-  ].join('\n');
-}
-
-/**
- * 构建提交要求文本（Producer 复用）
- * @returns {string}
- */
-export const SUBMIT_REQUIREMENTS = `要求:
-1. 每个独立的知识点单独提交为一个候选 — 目标: 至少 3 个候选
-2. 先使用分析中已有的代码片段直接提交候选; 仅在需要更多代码上下文时才用 read_project_file
-3. filePaths 填写分析中提到的相关文件路径
-4. description 中文简述 ≤80 字，引用真实类名
-5. reasoning 中 sources 必须非空，填写来源文件名如 ["FileName.m"]，confidence 填 0.7~0.9
-6. 不要跳过任何分析中提到的知识点
-7. 如果 read_project_file 失败（文件不存在），直接用分析文本内容提交，不要重试其他路径
-8. 每个候选必须有 trigger (@kebab-case)、kind (rule/pattern/fact)、doClause (英文祈使句)
-9. dontClause（反向约束）、whenClause（触发场景）、coreCode（代码骨架）均为必填
-10. content 必须是包含 markdown 和 rationale 的对象: { markdown: "项目特写正文", rationale: "设计原理", pattern: "可选代码片段" }。⚠️ rationale 是必填字段，解释为什么采用这种做法
-11. kind 只能是 rule/pattern/fact 三选一，不要填写维度名（如 best-practice/architecture/code-standard 都不是合法 kind 值）`;