@zooique/memora 2.0.3 → 3.0.1

package/dist/memory/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,iCAAiC;AACjC,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAoEhD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY;;CAAyB,CAAC;AAInD;;;;;GAKG;AACH,eAAO,MAAM,aAAa;IACxB,uCAAuC;;IAEvC,yDAAyD;;IAEzD,qCAAqC;;IAErC,2BAA2B;;IAE3B,2BAA2B;;IAE3B,+BAA+B;;IAE/B,iDAAiD;;IAEjD,8CAA8C;;CAEtC,CAAC;AASX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;IAC3B,wBAAwB;;IAExB,oBAAoB;;IAEpB,8BAA8B;;IAE9B,oBAAoB;;IAEpB,sBAAsB;;CAEd,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,cAAc;IACzB,eAAe;;IAEf,aAAa;;IAEb,eAAe;;IAEf,gBAAgB;;IAEhB,aAAa;;IAEb,gBAAgB;;CAER,CAAC;AAIX;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gCAAgC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;CACpC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAInE;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,kEAAmE,CAAC;AAE9F;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAmGhD;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACxB,kDAAkD;;IAElD,qEAAqE;;IAErE,0CAA0C;;IAE1C,sDAAsD;;IAEtD,gCAAgC;;IAEhC,0BAA0B;;CAElB,CAAC;AAIX;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,oDAAoD;AACpD,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/memory/types.js

@@ -1,58 +1,83 @@
 /**
- * 记忆类型定义 — 基元驱动模型
- *
- * 设计哲学：万物皆是记忆，用 source 开放字符串替代封闭枚举
- * 详见 ADR-004 · 记忆统一模型
+ * 记忆类型定义 — 基元驱动模型：记忆即轮次摘要（memory-as-summary），source 以开放字符串承载溯源标签（替代封闭枚举）
  */
 import { configError } from '../utils/errors.js';
-/** 默认记忆权重（parseMemory 的默认值行为） */
-export const DEFAULT_MEMORY_SCORE = 0.5;
+import { isPlainObject } from '../utils/objects.js';
+/**
+ * round-summary 摘要类型取值集合（单一真源：运行时校验与类型声明均从此派生）。
+ * 新增取值只改此处——若类型与运行时校验集双写，类型扩展会静默漏掉校验集，
+ * 导致新类型摘要被兜底为 'general'（行为漂移无编译报错）。
+ */
+export const SUMMARY_TYPES = ['preference', 'fact', 'decision', 'intent', 'general'];
 /**
- * 记忆解析器 — 验证原始数据并转换为 Memory 类型
+ * 记忆解析器 — 验证原始数据并转换为 Memory
+ * 校验：非空对象、字段类型、ISO 8601 日期
  *
- * 提供与原 MemorySchema.parse() 等效的运行时验证能力：
- * - 非空对象检查
- * - 字段类型验证（string/number）
- * - ISO 8601 日期格式验证
- * - score 范围检查（0-1）
- * - 默认值填充（score = 0.5）
+ * **白名单构造**：返回值只含 Memory 接口声明的字段，源对象上的任何未知字段（如旧档残留的
+ * `score`）一律剥离——宿主读旧档经此函数即完成数据层清洗，无需另写迁移脚本。
  *
  * @param raw - 原始数据（通常来自 JSON 解析或数据库查询）
- * @returns 验证通过的 Memory 对象
+ * @returns 验证通过的 Memory 对象（仅白名单字段，未知字段已剥离）
  * @throws Error 当数据不符合 Memory 接口定义时
  */
 export function parseMemory(raw) {
     if (raw === null || typeof raw !== 'object') {
-        throw configError('Memory 解析失败', '输入必须是非空对象', ['检查数据源（JSON 文件 / 数据库查询）是否返回了有效对象']);
+        throw configError('Memory 解析失败', '输入必须是非空对象', [
+            '检查数据源（JSON 文件 / 数据库查询）是否返回了有效对象',
+        ]);
     }
     const obj = raw;
     // 验证必需的 string 字段
     const stringFields = ['id', 'content', 'source', 'name'];
     for (const field of stringFields) {
         if (typeof obj[field] !== 'string') {
-            throw configError('Memory 解析失败', `${field} 必须是字符串`, [`检查数据源中 ${field} 字段的类型（当前为 ${typeof obj[field]}）`]);
+            throw configError('Memory 解析失败', `${field} 必须是字符串`, [
+                `检查数据源中 ${field} 字段的类型（当前为 ${typeof obj[field]}）`,
+            ]);
         }
     }
     // 验证 ISO 8601 日期字段
     const dateFields = ['createdAt', 'accessedAt'];
     for (const field of dateFields) {
         if (typeof obj[field] !== 'string' || isNaN(Date.parse(obj[field]))) {
-            throw configError('Memory 解析失败', `${field} 必须是有效的 ISO 8601 日期字符串`, [`检查数据源中 ${field} 字段的格式（当前值: ${JSON.stringify(obj[field])}）`]);
+            throw configError('Memory 解析失败', `${field} 必须是有效的 ISO 8601 日期字符串`, [
+                `检查数据源中 ${field} 字段的格式（当前值: ${JSON.stringify(obj[field])}）`,
+            ]);
         }
     }
-    // 验证 score 字段（可选，有默认值）
-    // Number.isFinite 同时排除 NaN/Infinity（对齐 zod z.number() 行为）
-    if (obj.score !== undefined && obj.score !== null) {
-        if (typeof obj.score !== 'number' || !Number.isFinite(obj.score) || obj.score < 0 || obj.score > 1) {
-            throw configError('Memory 解析失败', `score 必须是 0-1 之间的数字（当前值: ${String(obj.score)}）`, ['将 score 调整为 0-1 之间的有效数字']);
-        }
-    }
-    // 验证可选的 deletedAt 字段
+    // 验证可选的 deletedAt 字段（null 视为未删除并归一为 undefined：
+    // JSON 落盘可能出现 null，而 deletedAt?: string 不允许 null——否则消费方判
+    // `deletedAt === undefined` 会因 null !== undefined 把活跃记忆误判为已删除）
     if (obj.deletedAt !== undefined && obj.deletedAt !== null) {
         if (typeof obj.deletedAt !== 'string' || isNaN(Date.parse(obj.deletedAt))) {
             throw configError('Memory 解析失败', `deletedAt 必须是有效的 ISO 8601 日期字符串（当前值: ${JSON.stringify(obj.deletedAt)}）`, ['检查数据源中 deletedAt 字段的格式']);
         }
     }
+    // 验证可选语义字段的类型（运行时校验与类型声明同源）：不可信磁盘 JSON 的非法值
+    // （如 summaryType: 'bogus' / isModified: 'yes'）靠 as 断言透传会致
+    // round-summary 分轨召回与编辑标记消费行为漂移（无编译报错）。
+    if (obj.metadata !== undefined && !isPlainObject(obj.metadata)) {
+        throw configError('Memory 解析失败', `metadata 必须是对象（当前为 ${typeof obj.metadata}）`, [
+            '检查数据源中 metadata 字段的类型',
+        ]);
+    }
+    if (obj.summaryType !== undefined && !SUMMARY_TYPES.includes(obj.summaryType)) {
+        throw configError('Memory 解析失败', `summaryType 必须是合法摘要类型之一：${SUMMARY_TYPES.join(' / ')}（当前为 ${JSON.stringify(obj.summaryType)}）`, ['检查数据源中 summaryType 字段的取值']);
+    }
+    if (obj.sessionName !== undefined && typeof obj.sessionName !== 'string') {
+        throw configError('Memory 解析失败', `sessionName 必须是字符串（当前为 ${typeof obj.sessionName}）`, ['检查数据源中 sessionName 字段的类型']);
+    }
+    if (obj.roundId !== undefined && typeof obj.roundId !== 'string') {
+        throw configError('Memory 解析失败', `roundId 必须是字符串（当前为 ${typeof obj.roundId}）`, [
+            '检查数据源中 roundId 字段的类型',
+        ]);
+    }
+    if (obj.isModified !== undefined && typeof obj.isModified !== 'boolean') {
+        throw configError('Memory 解析失败', `isModified 必须是布尔值（当前为 ${typeof obj.isModified}）`, ['检查数据源中 isModified 字段的类型']);
+    }
+    if (obj.supersededBy !== undefined && typeof obj.supersededBy !== 'string') {
+        throw configError('Memory 解析失败', `supersededBy 必须是字符串（当前为 ${typeof obj.supersededBy}）`, ['检查数据源中 supersededBy 字段的类型']);
+    }
     return {
         id: obj.id,
         content: obj.content,
@@ -60,76 +85,49 @@ export function parseMemory(raw) {
         name: obj.name,
         createdAt: obj.createdAt,
         accessedAt: obj.accessedAt,
-        score: obj.score ?? DEFAULT_MEMORY_SCORE,
-        deletedAt: obj.deletedAt,
+        deletedAt: obj.deletedAt ?? undefined,
+        metadata: obj.metadata,
+        summaryType: obj.summaryType,
+        sessionName: obj.sessionName,
+        roundId: obj.roundId,
+        isModified: obj.isModified,
+        supersededBy: obj.supersededBy,
     };
 }
+// ─── source 标签约定（非枚举，仅为当前使用的约定） ──────
 /**
- * 兼容性别名 — 保持原有测试代码 (MemorySchema.parse(...)) 无需修改
- */
-export const MemorySchema = { parse: parseMemory };
-// ─── source 标签约定（非枚举，仅为泊文当前使用的约定） ──────
-/**
- * 泊文当前使用的 source 标签约定
+ * 当前使用的 source 标签约定；source 是开放字符串，新增来源无需改代码，存储时指定即可
  *
- * 注意：source 是开放字符串，新增来源无需改代码
- * 只需在存储时指定 source 字符串即可
+ * persona / rule / skill / work-projection 为残留兼容标签：对应内容不归记忆库管理
+ * （角色包内容由角色包管理，作品投影落项目目录 projections/），标签保留用于
+ * typo 检测（sourceValidation.ts：KNOWN_SOURCES 集合）与存量行/外部导入识别；
+ * 它们不出现在 GOVERNANCE_SOURCES 中（治理系统只治理实际写入记忆库的 source）。
  */
 export const SOURCE_LABELS = {
-    /** 角色人格（agent-config/personas/*.md） */
+    /** 角色人格（角色包 content/persona.md）— 残留兼容标签，不写入记忆库 */
     PERSONA: 'persona',
-    /** 创作规则（agent-config/rules/*.md + .memora/rules/*.md） */
+    /** 创作规则（角色包 content/rules.md + .memora/rules/*.md）— 残留兼容标签，不写入记忆库 */
     RULE: 'rule',
-    /** 技能定义（agent-config/skills/*.md） */
+    /** 技能定义（角色包 skills/ 目录）— 残留兼容标签，不写入记忆库 */
     SKILL: 'skill',
-    /** 对话洞察（每轮问答结束后 LLM 提取） */
-    INSIGHT: 'insight',
-    /** 用户画像（每轮问答中 LLM 实时提取） */
-    PROFILE: 'profile',
-    /** 作品投影（Agent 读取用户作品时生成的概要） */
+    /** 作品投影（读取用户作品时生成的概要）— 残留兼容标签，作品落项目目录 projections/ */
     WORK_PROJECTION: 'work-projection',
-    /** 内容护栏规则（configDir/rules/guardrails/ 下的规则文件） */
-    GUARDRAIL: 'guardrail',
-    /** 未知来源（inferSource 兜底值，文件路径未匹配已知目录时的默认标签） */
+    /** 轮次摘要（每轮对话后生成的溯源式摘要，记忆即摘要） */
+    ROUND_SUMMARY: 'round-summary',
+    /** 未知来源（未被已知标签覆盖时的兜底值） */
     UNKNOWN: 'unknown',
 };
+// ─── round-summary 规范 ID 构造（单一真源） ────────────────
 /**
- * weight 四档离散值常量（LLM 输出约束）
- *
- * 设计理由（ADR-014 §4）：
- * - 离散值比连续浮点稳定，LLM 输出可预测
- * - 0.5 兜底避免 LLM 失败时关系数据缺失
- */
-export const RELATION_WEIGHTS = {
-    /** 几乎无关（LLM 明确判断无关系） */
-    NONE: 0.0,
-    /** 弱相关（关系存在但强度低） */
-    WEAK: 0.3,
-    /** 未判断（代码默认兜底，LLM 失败或未输出时） */
-    UNDEFINED: 0.5,
-    /** 强相关（关系明确且强度高） */
-    STRONG: 0.7,
-    /** 确定关系（矛盾/等价等强关系） */
-    CERTAIN: 1.0,
-};
-/**
- * 预设关系类型建议值（非枚举，仅作约定）
- *
- * 注意：type 是开放字符串，新增关系类型无需改代码
- * 只需在存储时指定 type 字符串即可
+ * round-summary 记忆的规范 ID：`{source}:{sessionName}:{roundId}`。
+ * 读写/过滤侧一律经本函数构造，禁止散落 `round-summary:` 字面量——
+ * 溯源标签变更只需同步 SOURCE_LABELS，此处自动跟随。
  */
-export const RELATION_TYPES = {
-    /** 矛盾（双向对称） */
-    CONTRADICTS: 'contradicts',
-    /** 支持（有向） */
-    SUPPORTS: 'supports',
-    /** 时间先后（有向） */
-    FOLLOWS: 'follows',
-    /** 细化/演化（有向） */
-    REFINES: 'refines',
-    /** 因果（有向） */
-    CAUSED: 'caused',
-    /** 泛相关（双向对称） */
-    RELATED: 'related',
-};
+export function roundSummaryMemoryId(sessionName, roundId) {
+    return `${SOURCE_LABELS.ROUND_SUMMARY}:${sessionName}:${roundId}`;
+}
+/** 会话级前缀（定位某会话的全部摘要记忆），与 roundSummaryMemoryId 同源 */
+export function roundSummarySessionPrefix(sessionName) {
+    return `${SOURCE_LABELS.ROUND_SUMMARY}:${sessionName}:`;
+}
 //# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

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

package/dist/project-search/projectSearchProvider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 项目搜索集成入口：带超时保护的加载包装，组合宿主自定义实现。
+ * 搜索失败时不抛异常、不中断对话流程（30s 超时防卡死 Agent 主循环）；
+ * 但**失败不再降级为「空结果」**——二者必须可区分，见 `safeSearchProjectText` 的注释。
+ */
+import type { IProjectSearchProvider, ProjectFileSearchOptions, ProjectFileSearchResult, ProjectTextSearchOptions, ProjectTextSearchResult } from '../project-search/types.js';
+/**
+ * 带超时和错误处理的按文件名搜索包装：超时或失败时不抛异常。
+ *
+ * **为什么失败不返回空数组**（name 模式同 content）：`[]` 与「真零命中」在调用侧
+ * **逐字同形**，于是「搜索坏了」被当成「项目里没有」——扁平数组返回正是这类
+ * 假阴性的温床（返回 `ProjectFileSearchResult` 对象，放宽/截断/失败各有载体）。
+ * 失败→上报 `failed: true`（**不是** error：不置错、不重试，只在文案里如实说明检索未完成），
+ * 由调用方分流表述。
+ */
+export declare function safeSearchProjectFiles(provider: IProjectSearchProvider, options?: ProjectFileSearchOptions): Promise<ProjectFileSearchResult>;
+/**
+ * 带超时和错误处理的按内容搜索包装：超时或失败时不抛异常。
+ *
+ * **为什么失败不返回空数组**：`[]` 与「真零命中」在调用侧**逐字同形**，
+ * 于是「搜索坏了」被当成「项目里没有」——这是本仓最隐蔽的一类假阴性（ripgrep 用 exit 2 与 1
+ * 区分这两态）。失败→上报 `failed: true`（**不是** error，对齐
+ * "no results is not an error"：不置错、不重试，只在文案里如实说明检索未完成），由调用方分流表述。
+ *
+ * 注：`safeSearchProjectFiles`（name 模式）与 content 同一套元信息载体
+ * （`ProjectFileSearchResult` + 失败→`failed: true`）。
+ */
+export declare function safeSearchProjectText(provider: IProjectSearchProvider, options: ProjectTextSearchOptions): Promise<ProjectTextSearchResult>;
+//# sourceMappingURL=projectSearchProvider.d.ts.map

package/dist/project-search/projectSearchProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectSearchProvider.d.ts","sourceRoot":"","sources":["../../src/project-search/projectSearchProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACV,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,2BAA2B,CAAC;AAKnC;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,sBAAsB,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,uBAAuB,CAAC,CAkBlC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAkBlC"}

package/dist/project-search/projectSearchProvider.js

@@ -0,0 +1,57 @@
+/** 项目搜索超时时间（毫秒） */
+const PROJECT_SEARCH_TIMEOUT_MS = 30_000;
+/**
+ * 带超时和错误处理的按文件名搜索包装：超时或失败时不抛异常。
+ *
+ * **为什么失败不返回空数组**（name 模式同 content）：`[]` 与「真零命中」在调用侧
+ * **逐字同形**，于是「搜索坏了」被当成「项目里没有」——扁平数组返回正是这类
+ * 假阴性的温床（返回 `ProjectFileSearchResult` 对象，放宽/截断/失败各有载体）。
+ * 失败→上报 `failed: true`（**不是** error：不置错、不重试，只在文案里如实说明检索未完成），
+ * 由调用方分流表述。
+ */
+export async function safeSearchProjectFiles(provider, options) {
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('项目文件搜索超时（30s）')), PROJECT_SEARCH_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([provider.searchFiles(options), timeoutPromise]);
+    }
+    catch {
+        // 失败不抛异常，但**不再伪装成可信的零命中**
+        return { matches: [], truncated: false, failed: true };
+    }
+    finally {
+        // 成功/失败均清理超时定时器，防残留定时器拖住进程
+        clearTimeout(timer);
+    }
+}
+/**
+ * 带超时和错误处理的按内容搜索包装：超时或失败时不抛异常。
+ *
+ * **为什么失败不返回空数组**：`[]` 与「真零命中」在调用侧**逐字同形**，
+ * 于是「搜索坏了」被当成「项目里没有」——这是本仓最隐蔽的一类假阴性（ripgrep 用 exit 2 与 1
+ * 区分这两态）。失败→上报 `failed: true`（**不是** error，对齐
+ * "no results is not an error"：不置错、不重试，只在文案里如实说明检索未完成），由调用方分流表述。
+ *
+ * 注：`safeSearchProjectFiles`（name 模式）与 content 同一套元信息载体
+ * （`ProjectFileSearchResult` + 失败→`failed: true`）。
+ */
+export async function safeSearchProjectText(provider, options) {
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('项目内容搜索超时（30s）')), PROJECT_SEARCH_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([provider.searchText(options), timeoutPromise]);
+    }
+    catch {
+        // 失败不抛异常，但**不再伪装成可信的零命中**
+        return { matches: [], truncated: false, failed: true };
+    }
+    finally {
+        // 成功/失败均清理超时定时器，防残留定时器拖住进程
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=projectSearchProvider.js.map

package/dist/project-search/projectSearchProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectSearchProvider.js","sourceRoot":"","sources":["../../src/project-search/projectSearchProvider.ts"],"names":[],"mappings":"AAaA,mBAAmB;AACnB,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAAgC,EAChC,OAAkC;IAElC,IAAI,KAAgD,CAAC;IACrD,MAAM,cAAc,GAAG,IAAI,OAAO,CAA0B,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QACxE,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC,EACxC,yBAAyB,CAC1B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;QAC1B,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACzD,CAAC;YAAS,CAAC;QACT,2BAA2B;QAC3B,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAgC,EAChC,OAAiC;IAEjC,IAAI,KAAgD,CAAC;IACrD,MAAM,cAAc,GAAG,IAAI,OAAO,CAA0B,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QACxE,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC,EACxC,yBAAyB,CAC1B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;QAC1B,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACzD,CAAC;YAAS,CAAC;QACT,2BAA2B;QAC3B,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/project-search/terms.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 构造内容搜索的放宽词表（显式片段优先）
+ *
+ * @param query 原始查询串（LLM 传入，可能多词/含分隔符）
+ * @returns 去重后的词表；**不含**整串本身（整串是「精确优先」那一轮用的，重复下发无意义）
+ *
+ * @example
+ * buildSearchTerms('技术栈 FastAPI Next.js PostgreSQL')
+ *   // → ['技术', 'FastAPI', 'Next.js', 'PostgreSQL']   （无 next / js 碎片）
+ * buildSearchTerms('核心|愿景')
+ *   // → ['核心', '愿景']   （分隔符写法与空格写法同解，见分词 SSOT）
+ */
+export declare function buildSearchTerms(query: string): string[];
+//# sourceMappingURL=terms.d.ts.map

package/dist/project-search/terms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terms.d.ts","sourceRoot":"","sources":["../../src/project-search/terms.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAsBxD"}

package/dist/project-search/terms.js

@@ -0,0 +1,68 @@
+/**
+ * 项目内容搜索的「放宽词表」构造 —— 显式片段优先
+ *
+ * 用途：`search_project mode=content` 采用「精确优先 + 零命中回退」——先按整串字面量搜，
+ * 整串零命中才用本函数产出的词表做一次 OR 放宽。词表由内核产出、宿主执行（判定留在宿主）。
+ *
+ * 为什么不能直接复用 `extractKeywords(query)`——实测反例：
+ * ```
+ * extractKeywords("技术栈 FastAPI Next.js PostgreSQL")
+ *   → ["技术","fastapi","next.js","postgresql","next","js"]
+ *                                          ^^^^^^ ^^^^  原查询中不存在的碎片
+ * ```
+ * 根因：`extractKeywords` 的英文补充 `input.match(/[a-z]{2,}/gi)` 在 `.` 处切断 `Next.js`；
+ * 而碎片 `js` 会命中一切 `JSON` / `Node.js` 写法 —— 实测 20 条放宽命中里 **10 条纯靠 `js` 命中**
+ * （假阴性换成假阳性，同样违反诚实化）。本词表把「空白分隔的片段」当一等公民，碎片噪声 10/20 → 0/20。
+ *
+ * 不变量（测试断言对象）：
+ *   1. 空白分隔片段是一等公民：**不含 CJK 的片段原样保留**（`Next.js` 仍是 `Next.js`，不二次切分）；
+ *   2. 含 CJK 的片段走内核分词 SSOT（`extractKeywords`），**不新造第二套分词器**；
+ *   3. 词表中**不得出现原查询里不存在的 ASCII 碎片**（`next` / `js`）。
+ */
+import { extractKeywords } from '../memory/keywordsTouch.js';
+/** 含 CJK（汉字/扩展区 + CJK 标点 + 全角形式）的片段 → 需分词；其余（ASCII、拉丁扩展）原样保留 */
+const CONTAINS_CJK = /[\u3400-\u9fff\u3000-\u303f\uff00-\uffef]/;
+/**
+ * 最短词长（对齐 `extractKeywords` 自己的 `length >= 2` 守卫，同一标准不再造第二条）
+ *
+ * 为什么必须挡单字符 ASCII 片段：`"a b"` 会产出 `a|b` 级正则，命中几乎每一行 —— 放宽变成噪声。
+ */
+const MIN_TERM_LEN = 2;
+/**
+ * 构造内容搜索的放宽词表（显式片段优先）
+ *
+ * @param query 原始查询串（LLM 传入，可能多词/含分隔符）
+ * @returns 去重后的词表；**不含**整串本身（整串是「精确优先」那一轮用的，重复下发无意义）
+ *
+ * @example
+ * buildSearchTerms('技术栈 FastAPI Next.js PostgreSQL')
+ *   // → ['技术', 'FastAPI', 'Next.js', 'PostgreSQL']   （无 next / js 碎片）
+ * buildSearchTerms('核心|愿景')
+ *   // → ['核心', '愿景']   （分隔符写法与空格写法同解，见分词 SSOT）
+ */
+export function buildSearchTerms(query) {
+    const terms = [];
+    const seen = new Set();
+    // 大小写不敏感去重（匹配本就是大小写不敏感的），但**保留首次出现的写法**供文案展示
+    // （`Next.js` 比 `next.js` 更像原查询；`TODO todo` 不应产出两条等价分支）
+    const push = (term) => {
+        const key = term.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        terms.push(term);
+    };
+    for (const segment of query.split(/\s+/).filter(Boolean)) {
+        if (CONTAINS_CJK.test(segment)) {
+            // 含 CJK：交给内核分词原语（标点/分隔符由它切）
+            for (const term of extractKeywords(segment))
+                push(term);
+        }
+        else if (segment.length >= MIN_TERM_LEN) {
+            // 纯 ASCII / 拉丁扩展：原样保留，不二次切分（保 `Next.js` 完整）
+            push(segment);
+        }
+    }
+    return terms;
+}
+//# sourceMappingURL=terms.js.map

package/dist/project-search/terms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terms.js","sourceRoot":"","sources":["../../src/project-search/terms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,gEAAgE;AAChE,MAAM,YAAY,GAAG,2CAA2C,CAAC;AAEjE;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,6CAA6C;IAC7C,uDAAuD;IACvD,MAAM,IAAI,GAAG,CAAC,IAAY,EAAQ,EAAE;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC1B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,CAAC;IAEF,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/B,4BAA4B;YAC5B,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,OAAO,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,OAAO,CAAC,MAAM,IAAI,YAAY,EAAE,CAAC;YAC1C,4CAA4C;YAC5C,IAAI,CAAC,OAAO,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/project-search/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 项目搜索提供者接口定义：让 memora 内核具备可注入的「项目内搜索」能力。
+ * 宿主实现 IProjectSearchProvider 注入自定义实现（VS Code 宿主用 workspace.findFiles /
+ * findTextInFiles，等价 IDE 全局搜索 Ctrl+Shift+F）。接口注入，遵循 IWebSearchProvider
+ * 模式；零依赖。
+ */
+/** 按文件名 glob 命中的文件 */
+export interface ProjectFileMatch {
+    /** 文件相对项目根的路径 */
+    path: string;
+}
+/** 按内容全文命中的文件（含行级定位，供后续 read_file 精读） */
+export interface ProjectTextMatch {
+    /** 文件相对项目根的路径 */
+    path: string;
+    /** 命中行号（1 起；宿主可不提供） */
+    line?: number;
+    /** 命中行预览片段（去控制字符 + 限长，防上下文注入） */
+    preview?: string;
+}
+/**
+ * 按内容搜索的**结果对象**（三态通道）
+ *
+ * 为什么不是一个 `ProjectTextMatch[]`：截断/失败/放宽都是**关于本次检索本身**的元信息，
+ * 挂在逐条命中上时**零命中就没有载体**（空数组承载不了任何字段）——于是「没搜到」与
+ * 「没搜完」与「搜索坏了」在调用侧逐字同形。返回对象让这三态各自可见（对齐 ripgrep
+ * 的 exit 0/1/2：有匹配 / 可信的零 / 出错了）。
+ */
+export interface ProjectTextSearchResult {
+    /** 命中列表（零命中也可能是 "没搜完" 或 "搜索失败"，须结合下方标记判断，勿单独采信） */
+    matches: ProjectTextMatch[];
+    /** 检索被截断：零命中或少量命中都**不代表"不存在"** */
+    truncated: boolean;
+    /** 截断主因：`results` 结果达上限 / `files` 扫描达文件上限（二者可同时成立时以 `results` 为停因） */
+    truncatedBy?: 'results' | 'files';
+    /**
+     * 实际参与匹配的文件数（宿主**上报的数据**，不是内核常量——内核从不扫描；
+     * 宿主内部预算量不得提升为内核常量，只能以结果对象数据上报）
+     */
+    scannedFiles?: number;
+    /**
+     * 只检索了**前一部分**（文件过大，后半段未覆盖）的文件数；`> 0` 时"零命中"不等于"不存在"
+     *
+     * 注意语义：这些文件**参与了检索**（不是被跳过），只是覆盖面不完整——故不叫 "skipped"。
+     */
+    partialReadFiles?: number;
+    /**
+     * 读取失败（权限不足 / 已被删除 / 悬空链接 / IO 错误）而**完全未参与检索**的文件数
+     *
+     * 与 `partialReadFiles` 区分：前者"看了但没看全"，后者"根本没看上"——两者都是"零命中不等于不存在"的
+     * 依据，但补救动作不同（部分读 → 换更具体的关键词或 read_file 精读；读取失败 → 可重试）。
+     */
+    unreadableSkipped?: number;
+    /** 某文件命中数曾被"单文件上限"截断（结果条数**不完整**） */
+    perFileCapped?: boolean;
+    /** 检索自身失败（超时/抛错）≠ 真零命中——与 `matches: []` **正交**，须分流表述 */
+    failed?: boolean;
+    /** 整串未精确命中、已放宽为分词匹配 → 结果**非精确**命中 */
+    relaxed?: boolean;
+    /**
+     * 放宽时**实际使用**的词（文案"已按 … 放宽"的**唯一取值来源**）
+     *
+     * ⚠️ 调用方**不得**改用自己下发的那份 `terms`——那样就有两份副本需要保持一致（双轨镜像）；
+     * 唯一真值 = 宿主回报的这个字段。
+     */
+    termsUsed?: string[];
+}
+/**
+ * 按文件名搜索的结果对象（与 content 模式同构的两轮语义）
+ *
+ * 扁平 `ProjectFileMatch[]` 无法区分零命中的两种语义——空数组承载不了任何标志，
+ * 「真零命中」与「放宽过的零命中」在调用侧逐字同形。与 `ProjectTextSearchResult`
+ * 同构：放宽/截断都是**关于本次检索本身**的元信息，返回对象让各态各自可见
+ * （对齐 ripgrep 的 exit 0/1/2：有匹配 / 可信的零 / 出错了）。
+ */
+export interface ProjectFileSearchResult {
+    /** 命中列表（零命中也可能是"没搜完"或"搜索失败"，须结合标记判断，勿单独采信） */
+    matches: ProjectFileMatch[];
+    /** 整串 glob 未精确命中、已放宽为名称子串匹配 → 结果**非精确**命中 */
+    relaxed?: boolean;
+    /**
+     * 放宽时**实际使用**的词（文案"已按 … 放宽"的**唯一取值来源**）
+     *
+     * ⚠️ 调用方**不得**改用自己下发的那份 `terms`——那样就有两份副本需要保持一致（双轨镜像）；
+     * 唯一真值 = 宿主回报的这个字段。
+     */
+    termsUsed?: string[];
+    /** 检索被截断（findFiles 达 maxResults 上限） */
+    truncated?: boolean;
+    /** 截断主因：`results` 结果达上限 / `files` 扫描达文件上限（name 模式下仅 results） */
+    truncatedBy?: 'results' | 'files';
+    /** 检索自身失败（超时/抛错）≠ 真零命中 —— 与 `matches: []` **正交**，须分流表述 */
+    failed?: boolean;
+}
+/** 按文件名搜索的选项 */
+export interface ProjectFileSearchOptions {
+    /** 文件名 glob（如匹配 src 目录下全部 TS 文件）；省略时列出项目全部文件（受 maxResults 限制） */
+    query?: string;
+    /** 限定目录/文件 glob（可选，如仅搜 src 目录） */
+    include?: string;
+    /** 排除 glob（可选，如排除 node_modules 目录） */
+    exclude?: string;
+    /** 返回结果数量上限 */
+    maxResults?: number;
+    /**
+     * 放宽词表（由内核分词 SSOT 产出，见 `buildSearchTerms`）；宿主**仅在整串/原样 glob 零命中时**才启用，
+     * 未提供则不放宽。放宽的**判定**留在宿主（只有宿主知道扫了多少、有没有扫完）。
+     * name 与 content 共用（两模式同一放宽设施，无第二套节奏）。
+     */
+    terms?: string[];
+}
+/** 按内容全文搜索的选项 */
+export interface ProjectTextSearchOptions extends ProjectFileSearchOptions {
+    /** 内容查询词（宿主按**字面量**匹配；宿主自行决定大小写与转义，内核不假定正则语义） */
+    pattern: string;
+}
+/**
+ * 项目搜索提供者接口：宿主实现并注入 AgentOptions.projectSearchProvider 提供
+ * 「在项目（当前工作区）中搜索文件」能力；未注入时内核不暴露 search_project 工具给 LLM。
+ */
+export interface IProjectSearchProvider {
+    /**
+     * 按文件名 glob 搜索项目文件，返回命中列表 + **本次检索的元信息**（放宽/截断）
+     *
+     * 实现约定（宿主侧）：① 先按 `query` 原样作 glob 精确匹配（保会写 glob 的用法）；
+     * ② 零命中且 `query` 无 glob 元字符、且 `terms` 非空时，才用 `terms` 按名称子串做一次
+     * OR 放宽，并置 `relaxed` + 回填 `termsUsed`；③ 截断**必须回报**（宁少勿假）。
+     */
+    searchFiles(options?: ProjectFileSearchOptions): Promise<ProjectFileSearchResult>;
+    /**
+     * 按内容全文搜索项目文件（等价全局搜索内容），返回命中文件及行预览 + **本次检索的元信息**
+     *
+     * 实现约定（宿主侧）：① 先按 `pattern` 整串匹配（精确优先）；② 整串零命中且 `terms` 非空时，
+     * 才用 `terms` 做一次 OR 放宽，并置 `relaxed` + 回填 `termsUsed`；③ 截断/跳过/失败等事实
+     * **必须回报**（宁少勿假：报告"没搜完"好过让调用方把"没搜到"当成"不存在"）。
+     */
+    searchText(options: ProjectTextSearchOptions): Promise<ProjectTextSearchResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/project-search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/project-search/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sBAAsB;AACtB,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,WAAW,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAClC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,gBAAgB;AAChB,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,iBAAiB;AACjB,MAAM,WAAW,wBAAyB,SAAQ,wBAAwB;IACxE,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAClF;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACjF"}

package/dist/project-search/types.js

@@ -0,0 +1,8 @@
+/**
+ * 项目搜索提供者接口定义：让 memora 内核具备可注入的「项目内搜索」能力。
+ * 宿主实现 IProjectSearchProvider 注入自定义实现（VS Code 宿主用 workspace.findFiles /
+ * findTextInFiles，等价 IDE 全局搜索 Ctrl+Shift+F）。接口注入，遵循 IWebSearchProvider
+ * 模式；零依赖。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/project-search/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/project-search/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}