code-frontmatter 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,136 @@
+import { z } from "zod";
+/**
+ * 语言注释规则 Schema
+ * 定义某种编程语言的 CFM 注释语法
+ */
+export declare const LanguageRuleSchema: z.ZodObject<{
+    /** 注释起始标记，如 "/*---" */
+    comment_start: z.ZodString;
+    /** 注释结束标记，如 "---*​/" */
+    comment_end: z.ZodString;
+    /** 该语言的文件扩展名列表 */
+    extensions: z.ZodArray<z.ZodString, "many">;
+    /** 行前缀（脚本语言使用），如 "# "，C 家族为 null */
+    line_prefix: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    comment_start: string;
+    comment_end: string;
+    extensions: string[];
+    line_prefix: string | null;
+}, {
+    comment_start: string;
+    comment_end: string;
+    extensions: string[];
+    line_prefix: string | null;
+}>;
+export type LanguageRule = z.infer<typeof LanguageRuleSchema>;
+/**
+ * CFM 表头严格 Schema（含全部必选字段）
+ * 用于校验完整规范的表头
+ */
+export declare const CfmSchema: z.ZodObject<{
+    /** 文件的核心用途和业务价值 */
+    intent: z.ZodString;
+    /** 文件的角色类型 */
+    role: z.ZodString;
+    /** 暴露的关键 API / 函数 / 组件 */
+    exports: z.ZodArray<z.ZodString, "many">;
+    /** 关键依赖 */
+    depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** 什么场景下才需要读取此文件全文 */
+    when_to_load: z.ZodOptional<z.ZodString>;
+    /** 副作用描述 */
+    side_effects: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** 是否修改外部状态 */
+    mutates_state: z.ZodOptional<z.ZodBoolean>;
+    /** 业务领域标签 */
+    domain: z.ZodOptional<z.ZodString>;
+    /** 给 AI 的特殊注意事项 */
+    ai_notes: z.ZodOptional<z.ZodString>;
+    /** 表头规范版本号 */
+    cfm_version: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    intent: string;
+    role: string;
+    exports: string[];
+    depends_on?: string[] | undefined;
+    when_to_load?: string | undefined;
+    side_effects?: string[] | undefined;
+    mutates_state?: boolean | undefined;
+    domain?: string | undefined;
+    ai_notes?: string | undefined;
+    cfm_version?: string | undefined;
+}, {
+    intent: string;
+    role: string;
+    exports: string[];
+    depends_on?: string[] | undefined;
+    when_to_load?: string | undefined;
+    side_effects?: string[] | undefined;
+    mutates_state?: boolean | undefined;
+    domain?: string | undefined;
+    ai_notes?: string | undefined;
+    cfm_version?: string | undefined;
+}>;
+export type CfmData = z.infer<typeof CfmSchema>;
+/**
+ * CFM 表头宽松 Schema（只要求 intent 字段）
+ * 用于渐进式表头补充场景——已有表头但尚不完整的文件
+ */
+export declare const CfmSchemaLoose: z.ZodObject<{
+    intent: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    intent: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    intent: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * 单个文件的 CFM 条目
+ * 包含文件路径和解析出的元数据
+ */
+export declare const CfmEntrySchema: z.ZodObject<{
+    /** 文件相对路径 */
+    file: z.ZodString;
+    /** 检测到的编程语言 */
+    language: z.ZodOptional<z.ZodString>;
+    /** 解析出的 CFM 表头数据 */
+    frontmatter: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** 校验警告信息 */
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    frontmatter: Record<string, unknown> | null;
+    language?: string | undefined;
+    warnings?: string[] | undefined;
+}, {
+    file: string;
+    frontmatter: Record<string, unknown> | null;
+    language?: string | undefined;
+    warnings?: string[] | undefined;
+}>;
+export type CfmEntry = z.infer<typeof CfmEntrySchema>;
+/**
+ * cfm_scan 的返回结果
+ */
+export interface ScanResult {
+    /** 扫描到的总文件数 */
+    total_files: number;
+    /** 有 CFM 表头的文件数 */
+    files_with_cfm: number;
+    /** 无 CFM 表头的文件数 */
+    files_without_cfm: number;
+    /** 所有文件的 CFM 条目 */
+    entries: CfmEntry[];
+}
+/**
+ * cfm_search 的返回结果
+ */
+export interface SearchResult {
+    /** 搜索查询 */
+    query: string;
+    /** 匹配的文件数 */
+    matches: number;
+    /** 匹配的 CFM 条目 */
+    entries: CfmEntry[];
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,kBAAkB;IAC3B,uBAAuB;;IAEvB,wBAAwB;;IAExB,kBAAkB;;IAElB,oCAAoC;;;;;;;;;;;;EAEtC,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,SAAS;IAElB,mBAAmB;;IAEnB,cAAc;;IAEd,0BAA0B;;IAI1B,WAAW;;IAEX,sBAAsB;;IAItB,YAAY;;IAEZ,eAAe;;IAEf,aAAa;;IAEb,mBAAmB;;IAEnB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;EAEhB,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;gCAIT,CAAC;AAEnB;;;GAGG;AACH,eAAO,MAAM,cAAc;IACvB,aAAa;;IAEb,eAAe;;IAEf,oBAAoB;;IAEpB,aAAa;;;;;;;;;;;;EAEf,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,eAAe;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB;IACnB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,aAAa;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACvB"}

package/dist/schema.js

@@ -0,0 +1,79 @@
+/*---
+intent: "定义 CFM 表头的 Zod Schema，用于校验从代码文件中提取的 YAML 元数据"
+role: model
+exports:
+  - "CfmSchema: CFM 表头的严格校验 Schema"
+  - "CfmSchemaLoose: 宽松模式 Schema（只要求 intent）"
+  - "CfmEntry: 单个文件的 CFM 条目类型（含文件路径和解析结果）"
+  - "LanguageRule: 语言注释规则类型定义"
+depends_on: ["zod"]
+when_to_load: "修改 CFM 字段定义或校验逻辑时加载"
+---*/
+import { z } from "zod";
+/**
+ * 语言注释规则 Schema
+ * 定义某种编程语言的 CFM 注释语法
+ */
+export const LanguageRuleSchema = z.object({
+    /** 注释起始标记，如 "/*---" */
+    comment_start: z.string(),
+    /** 注释结束标记，如 "---*​/" */
+    comment_end: z.string(),
+    /** 该语言的文件扩展名列表 */
+    extensions: z.array(z.string()),
+    /** 行前缀（脚本语言使用），如 "# "，C 家族为 null */
+    line_prefix: z.string().nullable(),
+});
+/**
+ * CFM 表头严格 Schema（含全部必选字段）
+ * 用于校验完整规范的表头
+ */
+export const CfmSchema = z.object({
+    // ---- 必选字段 ----
+    /** 文件的核心用途和业务价值 */
+    intent: z.string().max(500),
+    /** 文件的角色类型 */
+    role: z.string(),
+    /** 暴露的关键 API / 函数 / 组件 */
+    exports: z.array(z.string()),
+    // ---- 推荐字段 ----
+    /** 关键依赖 */
+    depends_on: z.array(z.string()).optional(),
+    /** 什么场景下才需要读取此文件全文 */
+    when_to_load: z.string().optional(),
+    // ---- 可选字段 ----
+    /** 副作用描述 */
+    side_effects: z.array(z.string()).optional(),
+    /** 是否修改外部状态 */
+    mutates_state: z.boolean().optional(),
+    /** 业务领域标签 */
+    domain: z.string().optional(),
+    /** 给 AI 的特殊注意事项 */
+    ai_notes: z.string().optional(),
+    /** 表头规范版本号 */
+    cfm_version: z.string().optional(),
+});
+/**
+ * CFM 表头宽松 Schema（只要求 intent 字段）
+ * 用于渐进式表头补充场景——已有表头但尚不完整的文件
+ */
+export const CfmSchemaLoose = z
+    .object({
+    intent: z.string(),
+})
+    .passthrough();
+/**
+ * 单个文件的 CFM 条目
+ * 包含文件路径和解析出的元数据
+ */
+export const CfmEntrySchema = z.object({
+    /** 文件相对路径 */
+    file: z.string(),
+    /** 检测到的编程语言 */
+    language: z.string().optional(),
+    /** 解析出的 CFM 表头数据 */
+    frontmatter: z.record(z.unknown()).nullable(),
+    /** 校验警告信息 */
+    warnings: z.array(z.string()).optional(),
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;KAUK;AAEL,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,uBAAuB;IACvB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,wBAAwB;IACxB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,kBAAkB;IAClB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,oCAAoC;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,iBAAiB;IACjB,mBAAmB;IACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3B,cAAc;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,0BAA0B;IAC1B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAE5B,iBAAiB;IACjB,WAAW;IACX,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC1C,sBAAsB;IACtB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEnC,iBAAiB;IACjB,YAAY;IACZ,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC5C,eAAe;IACf,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACrC,aAAa;IACb,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,mBAAmB;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,cAAc;IACd,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC1B,MAAM,CAAC;IACJ,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC;KACD,WAAW,EAAE,CAAC;AAEnB;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,aAAa;IACb,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,eAAe;IACf,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,oBAAoB;IACpB,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC7C,aAAa;IACb,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC"}

package/dist/tools/register.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 注册新语言的返回结果
+ */
+export interface RegisterResult {
+    /** 是否注册成功 */
+    success: boolean;
+    /** 结果消息 */
+    message: string;
+    /** 注册后的总语言数 */
+    total_languages?: number;
+}
+/**
+ * 校验输入参数并注册新语言
+ *
+ * @param name - 语言名称（如 "elixir"）
+ * @param config - 注释规则配置
+ * @returns 注册结果
+ */
+export declare function registerNewLanguage(name: string, config: {
+    comment_start: string;
+    comment_end: string;
+    extensions: string[];
+    line_prefix?: string | null;
+}): RegisterResult;
+//# sourceMappingURL=register.d.ts.map

package/dist/tools/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,aAAa;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IACJ,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,GACF,cAAc,CAwDhB"}

package/dist/tools/register.js

@@ -0,0 +1,69 @@
+/*---
+intent: "实现 cfm_register_language 工具：允许用户在运行时注册新的编程语言注释规则"
+role: service
+exports:
+  - "registerNewLanguage: 校验并注册新语言到语言注册表"
+depends_on: ["../registry.ts", "../schema.ts"]
+when_to_load: "修改语言注册接口或校验逻辑时加载"
+---*/
+import { registerLanguage, getAllLanguages } from "../registry.js";
+/**
+ * 校验输入参数并注册新语言
+ *
+ * @param name - 语言名称（如 "elixir"）
+ * @param config - 注释规则配置
+ * @returns 注册结果
+ */
+export function registerNewLanguage(name, config) {
+    // 参数校验
+    if (!name || name.trim().length === 0) {
+        return {
+            success: false,
+            message: "语言名称不能为空",
+        };
+    }
+    if (!config.comment_start || !config.comment_end) {
+        return {
+            success: false,
+            message: "comment_start 和 comment_end 不能为空",
+        };
+    }
+    if (!config.extensions || config.extensions.length === 0) {
+        return {
+            success: false,
+            message: "extensions 不能为空，至少需要一个文件扩展名",
+        };
+    }
+    // 校验扩展名格式
+    for (const ext of config.extensions) {
+        if (!ext.startsWith(".")) {
+            return {
+                success: false,
+                message: `扩展名 "${ext}" 格式错误，必须以 "." 开头（如 ".ex"）`,
+            };
+        }
+    }
+    // 构造语言规则
+    const rule = {
+        comment_start: config.comment_start,
+        comment_end: config.comment_end,
+        extensions: config.extensions,
+        line_prefix: config.line_prefix ?? null,
+    };
+    try {
+        registerLanguage(name, rule);
+        const allLanguages = getAllLanguages();
+        return {
+            success: true,
+            message: `语言 "${name}" 注册成功（扩展名: ${config.extensions.join(", ")}）`,
+            total_languages: Object.keys(allLanguages).length,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: error.message,
+        };
+    }
+}
+//# sourceMappingURL=register.js.map

package/dist/tools/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AAAA;;;;;;;KAOK;AAEL,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAenE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAC/B,IAAY,EACZ,MAKC;IAED,OAAO;IACP,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO;YACH,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,UAAU;SACtB,CAAC;IACN,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,aAAa,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC/C,OAAO;YACH,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,kCAAkC;SAC9C,CAAC;IACN,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO;YACH,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,6BAA6B;SACzC,CAAC;IACN,CAAC;IAED,UAAU;IACV,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAClC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO;gBACH,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,QAAQ,GAAG,4BAA4B;aACnD,CAAC;QACN,CAAC;IACL,CAAC;IAED,SAAS;IACT,MAAM,IAAI,GAAiB;QACvB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI;KAC1C,CAAC;IAEF,IAAI,CAAC;QACD,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAE7B,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;QACvC,OAAO;YACH,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,OAAO,IAAI,eAAe,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAClE,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM;SACpD,CAAC;IACN,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO;YACH,OAAO,EAAE,KAAK;YACd,OAAO,EAAG,KAAe,CAAC,OAAO;SACpC,CAAC;IACN,CAAC;AACL,CAAC"}

package/dist/tools/scan.d.ts

@@ -0,0 +1,15 @@
+import type { ScanResult } from "../schema.js";
+/**
+ * 扫描目录中所有代码文件的 CFM 表头
+ *
+ * @param directory - 要扫描的根目录（绝对路径）
+ * @param options - 扫描选项
+ * @returns 扫描结果汇总（含所有文件的 CFM 条目）
+ */
+export declare function scanDirectory(directory: string, options?: {
+    /** 自定义忽略目录 */
+    ignoreDirs?: string[];
+    /** 是否只返回有 CFM 表头的文件 */
+    cfmOnly?: boolean;
+}): Promise<ScanResult>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/tools/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/tools/scan.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAY,UAAU,EAAE,MAAM,cAAc,CAAC;AAiCzD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IACL,cAAc;IACd,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CAChB,GACP,OAAO,CAAC,UAAU,CAAC,CAsBrB"}

package/dist/tools/scan.js

@@ -0,0 +1,97 @@
+/*---
+intent: "实现 cfm_scan 工具：递归扫描目录下所有代码文件，提取 CFM 表头，返回汇总索引"
+role: service
+exports:
+  - "scanDirectory: 扫描指定目录，返回所有文件的 CFM 表头索引"
+depends_on: ["../parser.ts", "../registry.ts", "../schema.ts"]
+when_to_load: "修改文件扫描逻辑、过滤规则或结果格式时加载"
+ai_notes: "默认跳过 node_modules, .git, dist 等常见非源码目录"
+---*/
+import { readdir, stat } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+import { extractFrontmatter } from "../parser.js";
+import { getLanguageByExtension } from "../registry.js";
+/** 默认跳过的目录名 */
+const DEFAULT_IGNORE_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".svn",
+    ".hg",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".nuxt",
+    "__pycache__",
+    ".pytest_cache",
+    "venv",
+    ".venv",
+    "target",
+    "vendor",
+    ".idea",
+    ".vscode",
+    "coverage",
+]);
+/** 默认跳过的文件名 */
+const DEFAULT_IGNORE_FILES = new Set([
+    ".DS_Store",
+    "Thumbs.db",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+]);
+/**
+ * 扫描目录中所有代码文件的 CFM 表头
+ *
+ * @param directory - 要扫描的根目录（绝对路径）
+ * @param options - 扫描选项
+ * @returns 扫描结果汇总（含所有文件的 CFM 条目）
+ */
+export async function scanDirectory(directory, options = {}) {
+    const ignoreDirs = new Set([
+        ...DEFAULT_IGNORE_DIRS,
+        ...(options.ignoreDirs ?? []),
+    ]);
+    const entries = [];
+    // 递归遍历
+    await walkDirectory(directory, directory, ignoreDirs, entries);
+    // 按选项过滤
+    const filteredEntries = options.cfmOnly
+        ? entries.filter((e) => e.frontmatter !== null)
+        : entries;
+    return {
+        total_files: entries.length,
+        files_with_cfm: entries.filter((e) => e.frontmatter !== null).length,
+        files_without_cfm: entries.filter((e) => e.frontmatter === null).length,
+        entries: filteredEntries,
+    };
+}
+/**
+ * 递归遍历目录
+ */
+async function walkDirectory(rootDir, currentDir, ignoreDirs, entries) {
+    const items = await readdir(currentDir);
+    for (const item of items) {
+        const fullPath = join(currentDir, item);
+        // 跳过被忽略的文件
+        if (DEFAULT_IGNORE_FILES.has(item))
+            continue;
+        const itemStat = await stat(fullPath);
+        if (itemStat.isDirectory()) {
+            // 跳过被忽略的目录
+            if (ignoreDirs.has(item))
+                continue;
+            await walkDirectory(rootDir, fullPath, ignoreDirs, entries);
+        }
+        else if (itemStat.isFile()) {
+            const ext = extname(item);
+            // 只处理已注册语言的文件
+            if (!getLanguageByExtension(ext))
+                continue;
+            const relativePath = relative(rootDir, fullPath).replace(/\\/g, "/");
+            const entry = await extractFrontmatter(fullPath, relativePath);
+            entries.push(entry);
+        }
+    }
+}
+//# sourceMappingURL=scan.js.map

package/dist/tools/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../src/tools/scan.ts"],"names":[],"mappings":"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"}

package/dist/tools/search.d.ts

@@ -0,0 +1,22 @@
+import type { SearchResult } from "../schema.js";
+/**
+ * 在项目目录中搜索匹配条件的 CFM 表头
+ *
+ * 支持三种搜索维度：
+ * - keyword: 在 intent、exports、ai_notes 等文本字段中全文搜索
+ * - role: 精确匹配文件角色（如 "service", "component"）
+ * - domain: 精确匹配业务领域标签
+ *
+ * @param directory - 扫描的根目录
+ * @param query - 搜索条件
+ * @returns 搜索结果
+ */
+export declare function searchFrontmatter(directory: string, query: {
+    /** 关键字搜索（在 intent、exports、ai_notes 等字段中匹配） */
+    keyword?: string;
+    /** 按角色过滤 */
+    role?: string;
+    /** 按业务领域过滤 */
+    domain?: string;
+}): Promise<SearchResult>;
+//# sourceMappingURL=search.d.ts.map

package/dist/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IACH,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,GACF,OAAO,CAAC,YAAY,CAAC,CAqBvB"}

package/dist/tools/search.js

@@ -0,0 +1,84 @@
+/*---
+intent: "实现 cfm_search 工具：在已扫描的 CFM 索引中按关键字、角色、领域等条件搜索匹配文件"
+role: service
+exports:
+  - "searchFrontmatter: 搜索匹配条件的 CFM 条目"
+depends_on: ["./scan.ts", "../schema.ts"]
+when_to_load: "修改搜索逻辑或过滤条件时加载"
+---*/
+import { scanDirectory } from "./scan.js";
+/**
+ * 在项目目录中搜索匹配条件的 CFM 表头
+ *
+ * 支持三种搜索维度：
+ * - keyword: 在 intent、exports、ai_notes 等文本字段中全文搜索
+ * - role: 精确匹配文件角色（如 "service", "component"）
+ * - domain: 精确匹配业务领域标签
+ *
+ * @param directory - 扫描的根目录
+ * @param query - 搜索条件
+ * @returns 搜索结果
+ */
+export async function searchFrontmatter(directory, query) {
+    // 先获取全量扫描结果
+    const scanResult = await scanDirectory(directory, { cfmOnly: true });
+    // 拼接查询描述
+    const queryParts = [];
+    if (query.keyword)
+        queryParts.push(`keyword="${query.keyword}"`);
+    if (query.role)
+        queryParts.push(`role="${query.role}"`);
+    if (query.domain)
+        queryParts.push(`domain="${query.domain}"`);
+    const queryDescription = queryParts.join(", ");
+    // 过滤匹配的条目
+    const matched = scanResult.entries.filter((entry) => matchesQuery(entry, query));
+    return {
+        query: queryDescription,
+        matches: matched.length,
+        entries: matched,
+    };
+}
+/**
+ * 判断某个 CFM 条目是否匹配查询条件
+ * 所有提供的条件都必须满足（AND 逻辑）
+ */
+function matchesQuery(entry, query) {
+    const fm = entry.frontmatter;
+    if (!fm)
+        return false;
+    // 角色精确匹配
+    if (query.role) {
+        if (String(fm.role ?? "").toLowerCase() !== query.role.toLowerCase()) {
+            return false;
+        }
+    }
+    // 领域精确匹配
+    if (query.domain) {
+        if (String(fm.domain ?? "").toLowerCase() !== query.domain.toLowerCase()) {
+            return false;
+        }
+    }
+    // 关键字全文搜索
+    if (query.keyword) {
+        const kw = query.keyword.toLowerCase();
+        const searchFields = [
+            String(fm.intent ?? ""),
+            String(fm.ai_notes ?? ""),
+            String(fm.when_to_load ?? ""),
+            String(fm.domain ?? ""),
+            // 展开数组字段
+            ...(Array.isArray(fm.exports) ? fm.exports.map(String) : []),
+            ...(Array.isArray(fm.depends_on) ? fm.depends_on.map(String) : []),
+            ...(Array.isArray(fm.side_effects) ? fm.side_effects.map(String) : []),
+            // 文件路径也纳入搜索
+            entry.file,
+        ];
+        const haystack = searchFields.join(" ").toLowerCase();
+        if (!haystack.includes(kw)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"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"}