import { Context } from 'cordis'; import Schema from 'schemastery'; /** * 插件配置(全部可选:零必填是硬契约 —— 不写任何 config,插件必须完整可用)。 * * 路径默认值刻意**不写进 schema.default**:schema 默认值会被宿主在保存表单时 * 落成真实字符串,而 `~/.dsh/tlmemory.db` 是「当前用户主目录」的语义, * 写成字面量会把 A 机器的绝对路径带到 B 机器。默认值由 MemoryDB 在打开库时按 * `os.homedir()` 现算(src/db.ts:148)。 */ interface Config { dbPath?: string; serverPort?: number; maxRecallCount?: number; enableAutoReflection?: boolean; /** M3 compaction 间隔:每累计 N 次静默沉淀触发一轮强化衰减 + 矛盾检测(默认 20) */ compactionInterval?: number; /** * 记忆归并开关(1.1.0):开启后每轮 compaction 额外把「同主题多句话」折叠成一条摘要。 * 归并产物是父子结构且可回滚(merges 表 + revert),因此默认开启。 */ enableAutoMerge?: boolean; /** * 自动进化开关(1.3.0):开启后每轮 compaction 还会把同一父目录下的近义目录 * (`/部署运维/` ↔ `/运维部署/`)合并成一棵,纯确定性、零 LLM 成本、可回滚。 */ enableAutoEvolve?: boolean; /** * 人审开关(1.3.0):默认 **false** —— 沉淀直接入库、矛盾自动淘汰,全程无审核。 * 打开后恢复老行为:疑似指令式规则 / 近似重复进「待确认区」,矛盾旧条降级待确认。 */ requireReview?: boolean; } /** * 插件配置 schema。 * * 字段顺序 = 设置页渲染顺序;描述文本直接当面板提示用(客户端读 schema 投影)。 */ declare const Config: Schema; type MemoryScope = 'global' | 'project'; type MemoryCategory = 'preference' | 'architecture' | 'lesson'; /** * 工程记忆作用域的对外摘要(GET /api/projects 的条目)。 * * tree_type 在生产环境是 `repo:<12位sha256>` 这样不可读的哈希,因此这里把 * 「可读工程名 + 物理根目录」一并带出,供看板的工程下拉框直接呈现。 * 名字来源优先级:用户手工命名(is_manual) > 装配时自动登记(.git 根目录名) > scope 原文。 */ interface ProjectSummary { /** 作用域标识,即 SQLite 中的 tree_type(例如 repo:1a2b3c4d5e6f) */ scope: string; /** 可读工程名(默认取 .git 根目录的 basename) */ name: string; /** 工程根目录绝对路径;未登记过则为 null */ root: string | null; /** * 所属**宿主工作区**名称(来自 DSH 工作区登记表 `storages/workspace.json`)。 * * 与 `name` 的区别:`name` 是可被用户手工重命名的工程显示名,`workspaceName` 是 * 宿主侧的工作区标题 —— 前者改过之后,后者仍能说明「这个工程到底属于哪个工作区」。 * 工程不属于任何已登记工作区(或宿主登记表不可读)时为 null。 */ workspaceName: string | null; /** 该作用域下的全部节点数(含分类目录) */ nodeCount: number; /** 该作用域下的记忆叶子数(真正可阅读的条目) */ leafCount: number; /** 该作用域下最近一次写入时间戳(毫秒) */ updatedAt: number; } interface MemoryNode { id: string; tree_type: string; parent_id: string | null; path: string; name: string; is_leaf: number; content: string | null; keywords: string | null; /** * 四大物理分区(1.4.0):'core' | 'work' | 'rp' | 'lore'。 * 由 partition.ts 的 derivePartition 从「树类型 + 路径前缀」推导,写入时落库、 * 存量迁移时回填。它是 rp/lore 与 work 之间**检索层面的硬隔离**, * 而不是靠调用方自觉传 tree_type。 */ scope: string; /** 角色 id(仅 rp/lore 有意义;其余分区恒为空串)。多角色共库时的隔离键 */ char_id: string; /** * Trigram 检索标签串(空格分隔,每词 ≥3 字)。 * 与 keywords 的分工:keywords 是历史上沉淀链路产出的关键词(可能是 2 字短词), * tags 是**专为 trigram 索引**准备的长词标签,参与 bm25 加权(权重高于正文)。 * 两者都进 FTS,但只有 tags 会给到最高列权重。 */ tags: string | null; reinforce_count: number; is_pinned: number; /** 来源标记:'auto'(静默沉淀)/'manual'(看板/工具手工),审计与撤回的基础 */ source: string; /** 审核状态:'pending' 为待确认区(不参与召回),'confirmed' 为正常入库 */ status: string; /** * 注入指示器:最近一次「被真实召回并注入系统提示词切片」的时间戳(毫秒)。 * 单调只增,且**唯一写入点是 MemoryRecallEngine.recall()** —— 因此它是判定 * 「自动调用/注入链路是否生效」的确定性标记;未注入过为 0。 * 不要用 reinforce_count 做这个判定:它同时被重沉淀、去重强化与衰减改写。 */ last_injected_at: number; /** * 归并折叠指针(1.1.0):非空表示本节点已被折叠进该父节点(status 同时为 'merged')。 * 来源叶子原文保留、退出召回,可通过 merges 审计表整次回滚。 */ merged_into?: number | null; created_at: number; updated_at: number; } interface SearchOptions { treeType?: string; pathPrefix?: string; limit?: number; /** * 分区过滤(1.4.0):限定命中的 scope 集合。 * 未传时由调用方(工具层 / tlrp 桥接层)按当前运行模式折算成默认集合, * 存储层不猜模式 —— 那样会把宿主语义漏进数据库。 */ partitions?: string[]; /** * 角色过滤:非空时只返回 char_id 等于该值或为空的记录(通用记录对任何角色可见)。 * 空串或 undefined 表示不按角色过滤。 */ charId?: string; } interface SearchResult extends MemoryNode { score: number; bm25_rank: number; } /** * 提炼条目的作用域依据(v0.8.2 契约新增)。 * * 为什么必须由模型显式声明:写路径的安全默认是「归属当前项目」, * 只有**跨工程通用**的用户偏好 / 习惯才允许离开项目树进入 global。 * 旧契约只给了 `tree` 一个字段,模型把「看起来通用的工具链经验」直接判成 * global,于是项目内的部署 / 运维 / 踩坑结论被记进全局树(用户侧表现为 * 「本应记录到本项目记忆的内容,实际被记录到了全局记忆」)。 * 现在 global 需要显式证据:`tree_basis` 缺失或不等于 'cross-project-preference' * 时,条目按 project 处理。 */ type ReflectionTreeBasis = 'cross-project-preference' | 'project-specific'; interface RawReflectionItem { tree: 'global' | 'project'; /** global 的必要条件(见 ReflectionTreeBasis);缺失即按 project 落库 */ tree_basis?: ReflectionTreeBasis | string; path_segments: string[]; name: string; content: string; keywords: string[]; } interface ReflectionResponse { reflections: RawReflectionItem[]; } /** tlmemory_save 工具入参 */ interface SaveMemoryArgs { tree_scope: 'global' | 'project'; path_segments: string[]; rule_name: string; content: string; keywords: string[]; /** * 分区(1.4.0,可选):显式声明落哪个分区。 * 省略时由路径前缀推导(/rp/firefly/… → rp,/lore/… → lore,/work/… → work), * 再退到树类型(global → core,repo:* → work)。显式值与路径前缀冲突时以路径为准, * 因为路径是用户在调用里逐字写下的、最不可能被误判的证据。 */ scope?: string; /** 角色 id(1.4.0,可选):rp/lore 分区必须给,否则记录对所有角色可见 */ char_id?: string; /** Trigram 标签(1.4.0,可选):每词 ≥3 字,省略时回落 keywords */ tags?: string[]; } /** tlmemory_query 工具入参 */ interface QueryMemoryArgs { query: string; /** 树作用域(历史字段,保留兼容):all / global / project */ scope?: 'all' | 'global' | 'project'; limit?: number; /** 分区过滤(1.4.0):core / work / rp / lore 的任意组合,逗号分隔或数组 */ partitions?: string | string[]; /** 角色过滤(1.4.0):限定时只返回本角色与无主记录 */ char_id?: string; } /** 会话事件统一信封 */ interface SessionEventEnvelope { type: string; seq: number; time: number; data: T; } /** 轮次跟踪器结算产出:无感静默沉淀的输入素材 */ interface TurnTrackItem { turn: number; /** 本轮真实人类输入(source.kind === 'user' 的消息文本聚合) */ userText: string; /** 本轮全部助手可见文本(assistant/message 的 text 块聚合) */ assistantText: string; /** * M2 干活信号:本轮助手消息中是否出现过工具调用块(tool_use 系)。 * 写路径门控用它决定是否值得付费调用 LLM 提炼 —— 没干活且没有决策表述的 * 回合直接跳过,LLM 成本从「每回合一次」降为「有价值的回合才一次」。 */ hasToolActivity: boolean; } declare module 'cordis' { interface Events { /** * 宿主会话事件流(firehose):轮次/步骤生命周期、消息与工具事件均经此发布。 * 根上下文监听器可观察到全部会话;监听器抛错由宿主捕获隔离,绝不阻断提交。 */ 'session/event'(session: unknown, event: SessionEventEnvelope): void; } interface Context { logger?: { info: (...args: unknown[]) => void; warn: (...args: unknown[]) => void; error: (...args: unknown[]) => void; }; tools?: { register: (tool: unknown) => () => void; }; systemPrompt?: { section: (section: { name: string; order: number; text: string | ((context: unknown) => string); complete?: boolean; }) => () => void; variable: (name: string, provider: (context: unknown) => string | undefined) => () => void; }; llm?: { stream: (options: { messages: Array<{ role: string; content: string | Array<{ type: string; text: string; }>; source?: { kind: string; plugin?: string; }; }>; provider?: string; model?: string; system?: string; maxTokens?: number; sessionId?: string; purpose?: string; temperature?: number; signal?: AbortSignal; }) => AsyncIterable<{ type: string; delta?: string; text?: string; content?: string; }>; }; } } /** 归并候选:一条可被折叠的叶子(已排除 pin / pending / 已折叠 / 空内容) */ interface MergeCandidate { id: string; tree_type: string; path: string; name: string; content: string; keywords: string; } /** 一次归并的落库结果 */ interface MergeRecord { mergeId: number; summaryNodeId: string; sourceIds: string[]; summary: string; } /** 工程清单自愈维护的改动明细(供日志与测试断言) */ interface ProjectMaintenance { /** 被清理掉的工程 scope(含「零记忆工程」与「不属于宿主合法工作区的孤儿工程」) */ purgedScopes: string[]; /** 因与其他工程重名而被改名的工程 */ renamed: Array<{ scope: string; from: string; to: string; }>; } /** * 孤儿工程归并的判定选项(v0.6.6 作用域防漂移)。 * * 归并语义:白名单之外的孤儿 scope(如宿主以用户主目录 `C:\Users\ZhuanZ` 启动时 * 误建并误存的工程)**不删除、不隐藏,而是把它的全部记忆迁入合法工作区** —— * 这是「第一铁律(有记忆的工程绝不隐藏)」在防漂移场景下的演进形态: * 「有记忆的孤儿绝不孤立存在」。 */ interface OrphanMergeOptions { /** 豁免:该 scope 即使不在白名单也不迁移(宿主当前合法工程由调用方保证合法后再传) */ keepScope?: string | null; /** * 兜底迁移目标:孤儿既不在白名单、工程名也无法对齐到任何工作区标题时, * 迁入该 scope(通常取宿主当前合法工作区或白名单首位)。 * 传 null 表示无从判定兜底目标 —— 此类孤儿本轮跳过,绝不清空其记忆。 */ fallbackScope?: string | null; /** 白名单判定:返回 true 的 scope 视为合法,原样保留不迁移;null 表示关闭判定 */ isScopeAllowed?: ((scope: string) => boolean) | null; /** 工作区标题(小写)→ 权威 scope 投影:工程名与标题同名(同名对齐)的孤儿迁入对应权威 scope */ titleToScope?: ReadonlyMap | null; } /** 单个孤儿 scope 的归并结果(供日志与测试断言) */ interface OrphanMergeResult { /** 被归并的源 scope(迁移完成后不复存在) */ from: string; /** 迁移目标 scope */ to: string; /** 迁移的节点总数(含目录骨架) */ movedNodes: number; /** 与目标树同位冲突而按「取大合并」收敛的叶子数 */ mergedLeaves: number; } /** * 工程清理的判定选项。 * * `isScopeAllowed` 是宿主工作区白名单的投影:传 null 表示「无从判定」(宿主登记表 * 不可读)→ 关闭白名单过滤,只按「零记忆」清理。 * * **第一铁律(v0.6.5 起):白名单只用来清理「空壳」,绝不用来隐藏「有记忆的工程」。** * 因此白名单过滤的适用条件是「该作用域在库里**一个节点都没有**」;只要还存着节点, * 无论它的 scope 是否在 `workspace.json` 名单里,都**绝不允许**被剔除 —— 上一版按 * scope 无条件剔除,把 hash 规范化口径变更后「名字对得上、hash 对不上」的存量工程 * (连同其真实记忆)整棵树删掉了,用户侧表现为「看板下拉框空掉、记忆归零」。 * * 清理路径由此收敛为两类: * 1. 零节点 + 不在名单内 → 剔除(「以用户主目录启动」产生的空登记、宿主已删除的 * 历史目录留下的空记录); * 2. 在名单内(或按工程名对齐到某个合法工作区)但**没有任何记忆叶子**且不是当前 * 活跃工作区 → 剔除(零记忆不占位)。 * * `workspaceTitles` 是宿主合法工作区标题集合,用于「同名对齐」:登记名与某个工作区 * 同名(忽略大小写)的存量 scope 视同属于该工作区,不再被判成孤儿(详见 * WorkspaceRegistry.alignTitleByName)。 */ interface ProjectPruneOptions { keepScope?: string | null; isScopeAllowed?: ((scope: string) => boolean) | null; /** 宿主合法工作区标题集合(用于「工程名 == 工作区名」的存量数据对齐) */ workspaceTitles?: Iterable | null; } declare class MemoryDB { private db; constructor(dbPath?: string); private migrate; /** * P1-7 事务包裹辅助:多语句写序列(建目录链 + 建叶子 + 后代重写 + 剪枝)必须是 * 单一原子单元 —— 单条语句原子,但语句序列不原子, * 「自身已改 path、后代未重写」的间隙崩溃会永久断裂物化路径链且无自愈手段。 * 仅顶层写入口(upsertLeaf / createLeaf / updateNode)使用;驱动层的 transaction * 用 SAVEPOINT 支持嵌套(见 sqlite.ts),内部辅助方法即使误套也不会毁掉外层原子性。 */ private withTransaction; /** * Trigram 标签归一化(唯一入口)。 * * 为什么必须在这里强约束而不是靠调用方自觉: * FTS5 trigram 分词器的索引粒度是 3 个字符,**少于 3 字符的 token 根本进不了倒排**。 * 调用方(尤其是模型)习惯写「流萤 萨姆」这种 2 字人名当标签,那样等于没打标签, * 检索时只能掉进 LIKE 兜底(全表扫)。所以这里主动把短标签丢掉(它们仍会留在 * keywords 列里被 LIKE 兜底覆盖),只保留能真正进索引的长词,并按出现顺序去重。 */ private normalizeTags; /** * 沿物化路径递归构建目录节点并在末端挂载/强化原子断言叶子。 * 同 (tree_type, path, name) 冲突时执行强化:reinforce_count + 1 并更新内容与关键词。 */ upsertLeaf(treeType: string, pathSegments: string[], name: string, content: string, keywords: string[], options?: { source?: string; status?: string; /** Trigram 标签(空格分隔的 ≥3 字词),最高列权重 */ tags?: string[] | string; /** 显式分区;缺省从路径推导 */ scope?: string; /** 角色隔离键(rp/lore 必给) */ charId?: string; /** 置顶:RP 态每轮无条件注入的常驻记忆 */ pinned?: boolean; }): MemoryNode; /** * 手工新增记忆叶子(看板「新建记忆」表单提交入口)。 * 与 upsertLeaf(静默沉淀链路)的三点差异: * 1. content 保留完整 Markdown 原文,不做 80 字原子化截断; * 2. 名称 / 路径分段走 sanitizeManualName(保留空格等可读字符)而非严格白名单; * 3. 同 (tree_type, path, name) 冲突时覆盖内容但不递增强化计数(手工纠错语义)。 * 空标题 / 空正文 / 空作用域直接抛错,由服务端转译为 400。 */ createLeaf(treeType: string, pathSegments: string[] | string, name: string, content: string, keywords?: string[]): MemoryNode; /** * 查找或创建分类目录节点(不递增强化计数)。 * 与 upsertDirectory 的差异:目录已存在时直接复用,避免手工编辑路径 * 反复触发 ON CONFLICT 强化分支导致目录 reinforce_count 虚增。 */ private ensureDirectory; private upsertNode; /** * FTS5 Trigram 全文检索:BM25 排序,输出 score(越高越相关)与 bm25_rank。 * P1-3 打分模型: * - is_pinned = 1 的记忆在 SQL 层强制排在未置顶记忆之前(置顶语义落地); * - reinforce_count 纳入最终得分(score + min(count, 10) * REINFORCE_WEIGHT), * 让「召回即强化」的高频记忆在长期使用中自然获得更高权重, * 召回侧的每轮 reinforce 写入从此有了真实的排序收益。 */ search(query: string, options?: SearchOptions): SearchResult[]; /** * 短词(<3 字符)LIKE 回退检索:Trigram 索引无法命中的最小粒度问题在此兜底。 * score 给固定基线(LIKE 无相关性排序语义),按强化计数与更新时间排序。 */ private searchByLike; /** * 置顶记忆读取(RP 态每轮无条件注入)。 * * 与 search 的分工:这里**不做相关性筛选**,只按分区与角色取 pinned=1 的行。 * 它服务的是「必须每轮都在场」的信息(当前角色的核心羁绊、用户画像)。 * 一旦让这类信息参与检索,措辞稍变就会消失 —— 那正是人设崩坏的起点。 */ listPinned(partitions?: string[], charId?: string, limit?: number): MemoryNode[]; /** 分区统计:scope × char_id 的节点 / 叶子 / 置顶计数(取证与看板共用) */ partitionStats(): Array<{ scope: string; char_id: string; total: number; leaves: number; pinned: number; }>; getAllNodes(treeType?: string): MemoryNode[]; /** 精确作用域取节点(scope 即 tree_type 原文,例如 'global' / 'repo:1a2b3c4d5e6f') */ getNodesByScope(scope: string): MemoryNode[]; /** * 取工程树节点。传入 scope 时收敛到该工程;省略时返回**全部非全局**作用域, * 由调用方(看板下拉框)自行聚焦到所选工程。 */ getProjectNodes(scope?: string): MemoryNode[]; /** * 按**物理分区**取节点(core / work / rp / lore),与 tree_type 正交。 * * 为什么不能复用 getAllNodes:`tree_type` 是工程维度(repo: / global),而 * `scope` 是记忆用途维度 —— 角色记忆(rp/lore)刻意落在 global 树下以便跨工程可见, * 因此「rp 分区」在 tree_type 上根本不存在,只能按 scope 列过滤。 * * charId 传空串表示**不限角色**(core/work 没有角色归属);传具体值则包含该角色 * 的条目与共享层(char_id = '')的条目,与检索侧 `appendPartitionFilter` 同一口径。 */ getNodesByPartition(scope: string, charId?: string, limit?: number): MemoryNode[]; /** * 工程名唯一性查询:返回除 excludeScope 之外**占用该工程名**(忽略大小写)的工程。 * * 为什么必须唯一:看板下拉框以工程名作为人的唯一线索,两个同名工程在界面上完全 * 无法区分;且 findProjectScope 按名字解析时只能取其一(重名即歧义)。因此 * 「注册」「重命名」两条写路径都必须先过这道闸。 */ findProjectNameOwner(name: string, excludeScope?: string): { scope: string; name: string; } | null; /** 登记表里是否存在该 scope(用于「当前活跃工程登记项是否在位」的判定) */ hasProject(scope: string): boolean; /** * 为工程作用域解析**不与他人重名**的工程名。 * * 场景:两个不同路径的仓库目录同名(两台机器上的 TLToolBox、monorepo 里多个 * 同名子包、目录改名后遗留的旧 scope),basename 天然撞车。此时给后来者追加 * scope 短标识(如 `TLToolBox (a1b2c3)`),既保住人类可读前缀,又保证全局唯一。 * * 自愈性:短标识是按需追加的 —— 冲突方被清理后再次调用会自动摘掉后缀, * 因此本函数幂等,可安全地在每次登记/兜底时重算。 */ private resolveUniqueProjectName; /** * 自动登记工程作用域(宿主装配时调用)。 * 1. 若该 scope 已被用户手工命名(is_manual=1),保留用户命名不覆盖; * 2. 自动命名必须全局唯一 —— 与他人重名时自动追加 scope 短标识(见 resolveUniqueProjectName)。 */ registerProject(scope: string, name: string, root?: string | null): void; /** * 手工命名工程作用域:把历史遗留的 repo: 改成可读名字。 * 置 is_manual=1 后自动登记不再覆盖。 * **唯一性闸门**:目标名字若已被其它工程占用则拒绝(返回 false), * 由服务端转译为 409 并带上占用者名字,杜绝「看板出现两个同名工程」。 */ renameProject(scope: string, name: string): boolean; /** * 清理「没有任何记忆文件」的工程(看板里不再堆积历史遗留的空工程)。 * * 判定的关键点: * 1. **有记忆的工程绝不剔除(第一铁律)**:只要该作用域在 nodes 里还有行 —— 哪怕 * 只剩空目录骨架 —— 就不参与白名单剔除。白名单的职责是清理**空壳登记**,不是 * 隐藏用户的记忆。v0.6.3 曾按「scope 是否在名单内」无条件剔除,配合 hash 规范化 * 口径变更,把「名字对得上、hash 对不上」的存量工程连同真实记忆整棵删掉, * 这是「记忆看板归零」的事故根因,此处是修复点。 * 2. 以**叶子节点**(is_leaf=1,即真正的记忆文件)为准判断「零记忆」,而不是 nodes * 总行数 —— 删除最后一条记忆时 deleteNode 只删子树、不剪父目录,若按 nodes 计数, * 该工程会残留一串空目录骨架而永远不算「空」; * 3. 清理是**连带**的:既然该工程已无记忆,其空目录骨架与登记项一并删除, * 否则 listProjects 仍会从 nodes 里把它们聚合回清单(删了等于没删); * 4. **豁免 keepScope(宿主当前正在打开的合法工作区)**:它是「当前工程就绪、可随时 * 新建沉淀」的心智锚点 —— 看板需要它常驻下拉框(标记为 0 条)以便随时切入空树后 * 新建,因此零记忆也不清理(见 server 的 GET /api/projects 展示保证); * 5. **同名对齐**:登记名与某个合法工作区标题同名的 scope 视同属于该工作区, * 与名单内作用域同等待遇(解决 hash 口径变更后存量工程的归属识别)。 * * 候选集取「登记表 scope ∪ nodes 里出现过的 scope」的并集,覆盖 * 「只登记过没写过」与「只写过没登记过(历史库)」两种遗留形态。 * 返回被清理的 scope 列表;幂等,可安全重复调用。 */ pruneEmptyProjects(options?: ProjectPruneOptions): string[]; /** * 孤儿工程热归并(v0.6.6 作用域防漂移核心):把白名单之外 scope 的**全部记忆** * 迁入合法工作区,随后删除源 scope 的节点树与登记项。 * * 为什么必须先归并再收紧展示:v0.6.5 的「有记忆的工程绝不隐藏」让误存进 * `C:\Users\ZhuanZ` 的记忆作为幽灵工程在看板常驻 —— 铁律本身没错,错在记忆 * 的归属。归并是铁律的演进:记忆一条不少,但家要搬回合法工作区。 * * 迁移算法(单事务、幂等): * 1. 候选 = `projects` 登记表 ∪ `nodes` 出现过的 scope(排除 global 与 keepScope); * 2. 目标解析:scope 在白名单 → 原样保留;否则工程名与某工作区标题同名(同名对齐) * → 迁入该工作区的权威 scope;再否则 → 迁入 fallbackScope(无从判定则跳过, * 绝不清空记忆); * 3. 逐节点重建:按物化路径深度升序(父目录先于子节点),parent_id 按新旧 id * 映射重挂;目录已存在即复用;叶子同位冲突按「reinforce_count 取大、is_pinned * 取或、content/keywords 新者胜、pending→confirmed 单向升级、created_at 取早、 * updated_at 取晚」收敛 —— 与 UNIQUE(tree_type, path, name) 约束天然兼容; * 4. 删除源 scope 全部节点(trg_nodes_ad 触发器同步清 FTS5)与登记项; * 目标 scope 的登记项由调用方(index/server)负责补齐可读名。 * * FTS5 全程由触发器自动重索引,无需手工重建。 */ mergeOrphanScopes(options?: OrphanMergeOptions): OrphanMergeResult[]; /** * 把单个源 scope 的记忆树整体迁入目标 scope(仅供 mergeOrphanScopes 在事务内调用)。 * 源树为空(零节点)时仍删除其登记项,返回 movedNodes=0 的结果。 */ private mergeSingleScope; /** * 某个作用域下的节点总数(含空目录骨架)。 * 供服务端判定「这个工程到底有没有数据」—— 有数据的工程绝不在清单里被隐藏。 */ countNodes(scope: string): number; /** * 同名工程自愈:历史库可能已存在重名(新登记已由 registerProject 拦截)。 * 同一名字(忽略大小写)被多个 scope 持有时,按 * 「手工命名 > 记忆条数多 > 最近更新」选出保留原名者,其余追加 scope 短标识。 * 返回改动明细;幂等(重名消失后不再改动)。 */ normalizeDuplicateNames(): Array<{ scope: string; from: string; to: string; }>; /** * 工程清单自愈维护:先清理「零节点空壳」与「名单内零记忆工程」(豁免宿主当前活跃的 * 合法工作区),再消除同名工程。幂等,可在插件启动与每次清单读取前安全重复调用。 * * **有记忆的工程永远不会被这里清掉** —— 白名单只作用于空壳,详见 pruneEmptyProjects。 * keepScope 传宿主当前工程 scope;isScopeAllowed 传宿主工作区白名单判定; * workspaceTitles 传宿主工作区标题集合(供存量数据「同名对齐」)。 */ maintainProjects(options?: ProjectPruneOptions): ProjectMaintenance; /** * 列出所有工程作用域:以「库里真实存在的记忆记录」为准(按 tree_type 去重聚合), * 并补上仅在登记表中存在、尚无记忆的已登记工程(含宿主当前工程)。 * * `workspaceNames` 是宿主工作区白名单的「scope → 工作区标题」投影,用于给每条 * 清单项带上 `workspaceName`,让看板能显示「工程名 [工作区名] (N条)」;传 null * 表示无从判定(宿主登记表不可读),此时 workspaceName 一律为 null。 * * 注意:本方法只做聚合、不改数据,也**不做任何过滤** —— 过滤与归属补全由调用方 * (server 的 GET /api/projects)负责,且必须以「有记忆的工程绝不隐藏」为前提。 */ listProjects(workspaceNames?: ReadonlyMap | null): ProjectSummary[]; /** * 把「工程名或 scope 原文」解析为确定的 scope。 * 依次尝试:scope 原文命中登记表 → scope 原文在 nodes 中存在 → 登记名匹配(忽略大小写)。 * 解析不出来返回 null,由调用方决定 404 还是回退全量。 */ findProjectScope(nameOrScope: string): string | null; /** * 人工剪枝:删除指定节点并级联移除其全部后代(沿 parent_id 外键链递归收敛), * 每行删除均经 trg_nodes_ad 触发器同步清理 FTS5 索引,杜绝孤立句柄残留。 * P2-8:非法 id(非整数 / 非正数)直接返回 false —— 此前 Number('abc') 得到 NaN * 并被当作参数绑定,驱动抛错后被服务端转成 500,错误语义失真。校验先于驱动执行, * 与底层引擎对 NaN 的具体绑定策略无关。 */ deleteNode(id: string): boolean; /** 读取单个节点(编辑保存回显与服务端 404 判定共用) */ getNode(id: string): MemoryNode | null; /** * 在线编辑记忆节点(看板详情抽屉「保存」入口)。 * 支持 title(标题)、content(正文)与 path(目录迁移)的任意组合; * 更新语句命中 trg_nodes_au 触发器,FTS5 分词索引自动同步重建。 * 目录迁移时同步修正全部后代节点的物化路径前缀,并剪枝遗留的空目录链。 * 返回更新后的完整节点;目标 id 不存在返回 null;同目录同名冲突抛 Error。 */ updateNode(id: string, patch: { title?: string; content?: string; path?: string; }): MemoryNode | null; /** 自底向上剪枝零子代目录链:迁移 / 重命名遗留的空目录逐层收敛删除 */ private pruneEmptyDirectoryChain; /** * M1 待确认区审核:把节点状态在 confirmed / pending 之间切换(看板「确认 / * 拒绝」入口),语义校验不通过的沉淀条目经用户确认后重新进入召回。 * 非法状态值与不存在的 id 返回 false(→ 服务端 400 / 404 语义)。 */ setStatus(id: string, status: string): boolean; /** * 自动淘汰:旧结论被新结论推翻时,不再进「待确认区」等人审,而是直接退出召回。 * * 语义与归并(merged)区分开:merged 是「多条合成一条摘要」,superseded 是 * 「这一条被那一条取代」。两者都保留原文、看板可见,`merged_into` 记录取代者 id, * 因此可以逐条 `restoreSuperseded` 回滚,不需要人工审核环节。 * * 自我取代、跨树取代、id 非法一律拒绝(返回 false),避免把记忆写成环或串树。 */ supersede(oldId: string, newId: string, reason?: string): boolean; /** 撤销自动淘汰:恢复 confirmed 与召回资格(`merges` 审计行同时标记已回滚) */ restoreSuperseded(id: string): boolean; /** * 召回强化:命中的记忆叶子断言计数 +1(记忆被检索调用即视为被强化)。 * 供召回引擎在最终命中集合上调用;非法 id 自动过滤,全非法输入零开销返回。 */ reinforceByIds(ids: Array): void; /** * 注入指示器刷新(行为检测取证用,**全库唯一写入点**)。 * * 为什么需要它:`reinforce_count` 虽是「读取面写副作用」,却同时被 * `upsertNode` 的 ON CONFLICT 重沉淀分支、`extractor` 的近似去重强化 * (两者都 +1)以及 `decayStaleReinforce`(减半)改写,因此**增减都不能 * 单独归因于注入**,用它判定会出现假阳性与假阴性。 * * 本方法只做一件事:把「该叶子断言此刻被真实召回并注入系统提示词切片」这一 * 事实写成一个**单调、只增不减**的时间戳。判定方式因此从「增量比较」变成 * 「是否晚于某个时刻」,对衰减、重沉淀、去重强化全都免疫。 * * 仅接受 `is_leaf = 1` 的行(目录节点不进召回,也不该留下注入痕迹); * 真值取 `max(现值, now)`,保证即使系统时钟回拨也不会退化为非单调。 * * @param ids 命中的叶子节点 id(允许混入非法值,自动过滤) * @returns 实际刷新的行数 */ markInjected(ids: Array): number; /** * M3 强化衰减:长期未被命中(updated_at 早于衰减窗口)的叶子记忆 * reinforce_count 减半(下限 1)。updated_at 由召回强化与沉淀写入共同刷新, * 因此该条件等价于「超过衰减窗口没有任何触碰」。返回受影响行数。 */ decayStaleReinforce(olderThanMs: number): number; /** * M3 矛盾检测批量取数:取指定时间点之后入库的 auto 来源、confirmed 状态的 * 记忆叶子(compaction 的「本批新记忆」)。 */ listLeavesCreatedSince(sinceTs: number, limit?: number): MemoryNode[]; /** * 归并候选全集(跨所有树):只取「可折叠」的叶子 —— 已确认、未 pin、未折叠、内容非空。 * 折叠状态由 status='merged' 表达,因此这里用 `merged_into IS NULL` 之外还要排 status。 */ listMergeCandidates(): MergeCandidate[]; /** 某棵树已存在的全部路径(去重),供提炼期做路径归一,避免继续制造近义路径 */ listDistinctPaths(treeType: string): string[]; /** 归并审计记录(按时间倒序);reverted_at 非空表示该次归并已被撤销 */ listMergeRecords(limit?: number): Array<{ id: number; tree_type: string; summary_node_id: number; source_ids: string[]; summary: string; created_at: number; reverted_at: number | null; }>; /** * 执行一次归并(父子结构): * 1. 校验全部来源 id 都是「同树、已确认、未折叠、未 pin」的叶子 —— 任一不满足则整次放弃; * 2. 插入父节点(is_leaf=1,正常参与召回),路径取簇内公共路径; * 3. 来源叶子置 status='merged' + merged_into=父节点 id(原文保留,退出召回); * 4. 写 merges 审计行。 * 全程单事务:不允许「父节点已建、来源未折叠」的中间态。 */ applyMerge(input: { treeType: string; path: string; name: string; summary: string; keywords: string; sourceIds: string[]; reinforceCount?: number; }): MergeRecord | null; /** * 撤销一次归并:来源叶子恢复 confirmed、解除 merged_into,父节点删除(含 FTS 行, * 由 AFTER DELETE 触发器维护)。merges 行保留并写 reverted_at 作为审计痕迹。 * @returns 恢复的叶子数;记录不存在 / 已撤销过时返回 null */ revertMerge(mergeId: number): { restored: number; removedSummary: boolean; } | null; /** * 自动进化 · 目录层归并:同一父目录下、名字近义的两个目录合成一个。 * * 为什么需要:记忆沉淀时路径由模型给出,同一主题会被切成 `/部署运维/` 与 * `/运维部署/`、`/配置/` 与 `/配置规约/` 这样的近义兄弟目录,树越用越散。 * 归并只是**改挂父节点 + 重写子树路径**,不动任何 content,也不产生新节点, * 因此零 LLM 成本、可重复执行、随时可由用户手工再拆开。 * * 冲突处理:目标目录下已存在同名子目录时跳过该对,避免把两棵同名子树叠在一起 * 触发 `UNIQUE (tree_type, path, name)`。 */ mergeSimilarDirectories(floor?: number): { mergedDirs: number; movedNodes: number; }; close(): void; private rowToNode; } /** * 提炼时注入的**项目身份**(v0.8.2):让提示词里的「当前仓库」有确定的指代对象。 * * 旧提示词只写「project:当前仓库专有…」,却从不告诉模型「当前仓库」是哪一个 —— * 模型手里只有一段对话文本,于是凡是像通用经验的条目(Docker / WSL / nginx 之类的 * 运维细节)一律被判成 global。给出工程名与根目录后,「这条结论属于本项目吗」才有 * 可判定的依据。 */ interface ReflectionProjectContext { /** 可读工程名(宿主工作区标题或仓库目录名) */ name?: string; /** 工程根目录(绝对路径) */ root?: string; /** 作用域 tree_type(repo:) */ scope?: string; } declare class MemoryExtractor { private ctx; private db; /** * 是否保留「待确认区」人审环节(1.3.0 起默认关闭)。 * * 默认关闭 = 自动进化:沉淀直接 confirmed 入库,矛盾由 compaction 自动淘汰。 * 只有在设置页显式打开 `requireReview` 时才回到「疑似指令式规则 / 近似重复」 * 先进 pending 等人裁定的老行为。 */ private reviewEnabled?; constructor(ctx: Context, db: MemoryDB, /** * 是否保留「待确认区」人审环节(1.3.0 起默认关闭)。 * * 默认关闭 = 自动进化:沉淀直接 confirmed 入库,矛盾由 compaction 自动淘汰。 * 只有在设置页显式打开 `requireReview` 时才回到「疑似指令式规则 / 近似重复」 * 先进 pending 等人裁定的老行为。 */ reviewEnabled?: (() => boolean) | undefined); private reviewEnabledNow; /** * 无感静默沉淀入口:由轮次结束后台任务调用。 * 全程 try-catch:LLM 未就绪 / 流中断 / JSON 畸形 / 单条失败均静默降级, * 保证任何异常都到不了事件循环,也不影响宿主后续会话。 */ extractAndConsolidate(turnItem: TurnTrackItem, projectScope: string, options?: { signal?: AbortSignal; route?: { provider: string; model: string; }; sessionId?: string; /** 当前会话所属项目身份:提示词里 global / project 判定的唯一指代对象 */ project?: ReflectionProjectContext; }): Promise; /** * 路径归一(1.1.0):新条目若与同树既有路径**逐段近义**(同深度、逐段 Dice ≥ 0.6), * 直接复用既有路径分段 —— 不再制造「部署运维 / 部署与运维」这类近义兄弟路径。 * * 只做归一、不做新建:没有任何近义既有路径时原样返回模型给的分段。 * 失败静默回退(路径归一属于质量优化,不允许阻断入库)。 */ private reuseExistingPath; private passesEitherGate; private processSingleReflection; } declare class MemoryCompactor { private ctx; private db; /** * 每累计多少次沉淀触发一轮 compaction(Config.compactionInterval)。 * * 允许传取值函数:设置页改完阈值要立即生效,做成常量就等于把装配期快照 * 固化进实例(本仓库 0.8.2 的白名单事故同型)。 */ private interval; /** 归并执行器(缺省表示不启用归并,单测与嵌入式用法不受影响) */ private consolidator?; /** 自动归并开关读取器(Config.enableAutoMerge) */ private mergeEnabled?; /** 是否保留人审(Config.requireReview):关闭时矛盾直接淘汰旧条目,不进待确认区 */ private reviewEnabled?; /** 自动进化开关读取器(Config.enableAutoEvolve):目录层近义合并 */ private evolveEnabled?; private sedimentCount; private lastCompactionAt; constructor(ctx: Context, db: MemoryDB, /** * 每累计多少次沉淀触发一轮 compaction(Config.compactionInterval)。 * * 允许传取值函数:设置页改完阈值要立即生效,做成常量就等于把装配期快照 * 固化进实例(本仓库 0.8.2 的白名单事故同型)。 */ interval?: number | (() => number), /** 归并执行器(缺省表示不启用归并,单测与嵌入式用法不受影响) */ consolidator?: { consolidate: () => Promise<{ applied: Array<{ sourceIds: string[]; }>; }>; } | undefined, /** 自动归并开关读取器(Config.enableAutoMerge) */ mergeEnabled?: (() => boolean) | undefined, /** 是否保留人审(Config.requireReview):关闭时矛盾直接淘汰旧条目,不进待确认区 */ reviewEnabled?: (() => boolean) | undefined, /** 自动进化开关读取器(Config.enableAutoEvolve):目录层近义合并 */ evolveEnabled?: (() => boolean) | undefined); /** 当前阈值:支持运行期动态读取,非法值兜底为 1(至少每次沉淀都检查) */ private intervalNow; /** * 沉淀计数:每完成一次提炼调度后调用。达到阈值即复位并返回 true * (调用方应在提炼链尾部串行执行一轮 compaction)。 */ noteSedimented(): boolean; /** * 执行一轮 compaction:先跑确定性衰减(恒可执行),再尝试 LLM 矛盾检测 * (ctx.llm 未就绪时静默跳过 —— 衰减不受影响,语义校验等下一轮)。 * 全程静默降级,绝不抛错。 */ compact(): Promise; /** 归并开关:运行期回读配置,非法/缺省视为开启(与 CONFIG_DEFAULTS 一致) */ private mergeEnabledNow; /** 人审开关:缺省关闭(1.3.0 起「自动进化、不审核」是默认行为) */ private reviewEnabledNow; /** 自动进化开关:缺省开启 */ private evolveEnabledNow; /** * 矛盾检测:取本批新入库的 auto 记忆,经确定性近邻检索组装候选对, * 一次 LLM 调用批量判定,互斥的旧条目降级 pending。 * @returns 降级入待确认区的旧记忆条数 */ private detectConflicts; /** 流式收集 LLM 输出(与 extractor 同一套流消费约定) */ private streamLlm; /** 解析 LLM 的矛盾判定输出:畸形输出一律收敛为空结果 */ private parseConflictResponse; } /** 一个待归并簇(dry-run 与执行共用同一结构) */ interface MergeCluster { treeType: string; /** 父节点路径:簇内路径分段的公共前缀 */ path: string; sources: Array<{ id: string; name: string; content: string; }>; /** LLM 归纳出的父节点名称(dry-run 未调 LLM 时为空) */ name: string; /** LLM 归纳出的摘要(dry-run 未调 LLM 时为空) */ summary: string; keywords: string; } /** 一轮归并的结果 */ interface ConsolidateReport { dryRun: boolean; /** 聚类出的簇(已按条数倒序,受 limit 截断) */ clusters: MergeCluster[]; /** 实际落库的归并(dry-run 恒为空) */ applied: MergeRecord[]; /** 被跳过的簇及原因(供日志与工具返回说明) */ skipped: Array<{ path: string; reason: string; }>; /** 摘要是否由 LLM 生成(false 表示 LLM 不可用,此时不落库) */ summarized: boolean; } /** 字符二元组 Dice 系数(与 extractor.nameSimilarity 同构,但不做「子串即 1」短路) */ declare function diceCoefficient(a: string, b: string): number; /** 两条物化路径是否近义:段数相同且逐段 Dice ≥ PATH_SEGMENT_FLOOR */ declare function pathsAreSimilar(a: string, b: string): boolean; /** * 保守聚类:并查集两条边 —— 路径逐段近义,或「名称相似 + 关键词重叠 ≥ 2」。 * 纯函数,同一输入必得同一输出(供 dry-run 与执行共用,也便于单测)。 */ declare function clusterCandidates(candidates: readonly MergeCandidate[], limit?: number): MergeCluster[]; interface ConsolidatorOptions { /** 自动归并开关(运行期读取,供设置页改值即时生效) */ enabled?: () => boolean; /** 单轮簇数上限 */ limit?: number; } declare class MemoryConsolidator { private ctx; private db; private options; constructor(ctx: Context, db: MemoryDB, options?: ConsolidatorOptions); private enabledNow; /** * 执行一轮归并。 * @param options.dryRun true 时只聚类 + 生成摘要预览,**不写库**(用户确认前的唯一形态) */ consolidate(options?: { dryRun?: boolean; limit?: number; }): Promise; /** 撤销一次归并;返回 null 表示记录不存在或已撤销 */ revert(mergeId: number): { restored: number; removedSummary: boolean; } | null; /** 一次 LLM 调用归纳全部簇;不可用或输出非法时返回 null(调用方据此跳过本轮) */ private summarize; } /** MCP 规范文本内容块(与 dsh-llm 的 TextBlock 逐字段一致) */ interface ToolTextBlock { type: "text"; text: string; } /** MCP/DSH 规范工具返回信封:content 恒为数组 */ interface ToolResultEnvelope { content: ToolTextBlock[]; } /** * 把任意 execute 产出规范化为 MCP/DSH 规范信封。 * * 这是全插件唯一的工具返回出口:content 恒为「至少一个 text 块」的数组, * text 恒为字符串(字符串原样透传,其余类型 JSON 序列化)。 */ declare function toToolResult(result: unknown): ToolResultEnvelope; /** * 最终护栏:把任何候选值收敛为合法 ContentBlock[](宿主 render 的返回类型契约)。 * * 无论输入是信封、块数组、裸字符串、裸对象、null 还是畸形结构,返回值恒为 * 非空数组且元素恒为 { type: 'text', text: string } —— 从根上杜绝宿主 * `content.some is not a function`。 */ declare function toContentBlocks(candidate: unknown): ToolTextBlock[]; /** * 工程作用域解析器:给定宿主会话对象(可能为 undefined)返回写入用的 tree_type。 * * v0.6.6 作用域防漂移:解析实现由插件装配层(src/index.ts)提供,必须完成 * 「会话工作区 → 白名单校验 → 降级合法工作区」的完整防线;本文件只负责把 * 宿主 execute 上下文里的 session 线索提取出来交给它,绝不自行猜测 scope。 */ type ScopeResolver = (session?: unknown) => string; /** * 归并执行器的最小接口:tools 只依赖这两个方法,不依赖 consolidator 的完整实现 * (单测可以塞替身,避免为了测工具注册而拉起 LLM)。 */ interface MemoryConsolidatorLike { consolidate(options?: { dryRun?: boolean; limit?: number; }): Promise; revert(mergeId: number): { restored: number; removedSummary: boolean; } | null; } declare function registerMemoryTools(ctx: Context, db: MemoryDB, resolveCurrentScope?: ScopeResolver, consolidator?: MemoryConsolidatorLike): () => void; declare class MemoryRecallEngine { private db; constructor(db: MemoryDB); /** * 双轨召回:项目记忆与全局记忆分别经 FTS5 检索后合流, * 项目命中叠加作用域偏置,按加权分数降序去重截断。 * 用户输入为长句时,FTS5 Trigram 短语匹配要求完整连续子串、几乎必然零命中, * 因此先执行查询候选展开(整句 / 标点切分 token / 中英文段 / 中文滑窗子串), * 再跨候选聚合加权去重,保证长句输入同样能命中语义相关的记忆断言。 */ recall(query: string, projectScope: string, maxCount?: number): SearchResult[]; /** 将召回记忆格式化为受控 XML 标签包裹的同步注入文本,空结果返回空串 */ formatPromptBlock(memories: SearchResult[]): string; } /** * 工程作用域(SQLite tree_type)的规范算法:`repo:` + 规范化路径 sha256 前 12 位。 * * 收敛为单一实现是硬性要求 —— 历史记忆库的 tree_type 由它决定,任何一处算法漂移 * 都会让既有记忆「找不到家」。`resolveProjectIdentity` 与工作区白名单必须逐字节一致。 */ declare function projectScopeOf(root: string): string; /** 宿主合法工作区白名单(不可变视图) */ interface WorkspaceRegistry { /** 合法工作区 scope → 工作区标题(DSH 里展示的名字;仅权威 hash,不含历史别名) */ readonly scopes: ReadonlyMap; /** 合法工作区根目录(已规范化,小写用于跨平台比较) */ readonly roots: ReadonlySet; /** 合法工作区标题集合(原样大小写,供「工程名与工作区同名」的存量数据对齐) */ readonly titles: ReadonlySet; /** * 该 scope 是否属于宿主已登记工作区。 * **包含历史 hash 别名** —— 老版本算出的 scope 同样算数,避免存量记忆被判孤儿。 */ has(scope: string): boolean; /** 取所属工作区标题(含别名);未登记返回 null */ nameOf(scope: string): string | null; /** * 「同名对齐」容错:工程名与某个合法工作区标题同名(忽略大小写与首尾空白)时, * 返回该工作区标题,否则 null。 * * 解决的是存量数据的归属问题:宿主从别的目录启动时,插件可能把工程登记成 * `名称=my-dsh-plugins、scope=别的 hash` 的形态;仅凭 scope 判断会把它当孤儿, * 而它其实明确指向某个已登记工作区。 */ alignTitleByName(projectName: string): string | null; } /** 解析 DSH 家目录:优先环境变量(测试与多 profile 场景),否则 `~/.dsh` */ declare function resolveDshHome(): string; /** 宿主工作区登记表的物理路径 */ declare function workspaceRegistryPath(dshHome?: string): string; declare function loadWorkspaceRegistry(dshHome?: string): WorkspaceRegistry | null; /** 宿主当前所在工程的身份(由装配层注入,用于 /api/projects 标记默认选中项) */ interface CurrentProject { scope: string; name: string; root: string; } /** * 服务启动结果: * - bound 成功绑定端口; * - delegated 端口已被前序 tlmemory 实例监听,健康探测确认同名进程后本实例复用之; * - failed 连续端口重试后仍无法绑定(已打印 EADDRINUSE 排查指引)。 */ type ServerStartOutcome = 'bound' | 'delegated' | 'failed'; /** 端口是否落在浏览器 / fetch 共同封禁的禁区(导出供单测与排查复用) */ declare function isFetchForbiddenPort(port: number): boolean; declare class MemoryServer { private db; private port; private logger?; private currentProject?; /** * 宿主合法工作区白名单的来源(默认读 DSH 的 `$DSH_HOME/storages/workspace.json`)。 * * 传入 null 表示**关闭白名单过滤**:工程清单只按「零记忆」清理,不按工作区归属。 * 该形态仅供不依赖 DSH 宿主环境的嵌入式用例(单测直接构造本服务,用合成 scope * 验证登记/命名契约)使用;插件装配(src/index.ts)永远传入真实读取器, * 因此线上所有清单读取都经过工作区白名单校验。 */ private workspaceRegistryProvider; private server; private wss; private clients; private readonly distPath; constructor(db: MemoryDB, port?: number, logger?: { info: (...args: unknown[]) => void; warn: (...args: unknown[]) => void; error: (...args: unknown[]) => void; } | undefined, currentProject?: CurrentProject | undefined, /** * 宿主合法工作区白名单的来源(默认读 DSH 的 `$DSH_HOME/storages/workspace.json`)。 * * 传入 null 表示**关闭白名单过滤**:工程清单只按「零记忆」清理,不按工作区归属。 * 该形态仅供不依赖 DSH 宿主环境的嵌入式用例(单测直接构造本服务,用合成 scope * 验证登记/命名契约)使用;插件装配(src/index.ts)永远传入真实读取器, * 因此线上所有清单读取都经过工作区白名单校验。 */ workspaceRegistryProvider?: (() => WorkspaceRegistry | null) | null); /** * 取宿主合法工作区白名单;读取器抛错或不可用一律视为「无从判定」(返回 null), * 调用方据此关闭过滤 —— 绝不因读取失败把用户的工程当孤儿清空。 */ private workspaceRegistry; /** * 工程清单(已按宿主工作区白名单附带 workspaceName)。 * 所有返回清单的端点统一走这里,避免某一条响应缺字段。 * * 归属补全分两步: * 1. scope 命中工作区(含历史 hash 别名)→ 用该工作区的标题; * 2. scope 认不出来、但**工程名与某工作区同名** → 视同属于该工作区(存量数据对齐)。 */ private projectList; /** * 清单项是否允许呈现给看板。 * * v0.6.6 展示口径收紧:**只呈现归属明确的工程** —— scope 命中工作区白名单, * 或工程名与某工作区同名(同名对齐)。名单外孤儿的 `nodeCount > 0` 存活通道 * 被移除 —— 那正是 ZhuanZ 幽灵工程逆向存活的机制。 * * 与「第一铁律」的关系:记忆绝不被删除,但孤儿 scope 的记忆在读取清单**之前** * 已被 mergeOrphanScopes 整体迁入合法工作区(归并优先),因此收紧不会造成 * 「看板下拉框空掉、记忆归零」—— 无处可迁(registry 为 null 无从判定)时 * 归并不生效,本过滤器也同步关闭,维持旧行为。 */ private isProjectVisible; /** * 工作区标题(小写)→ 权威 scope 投影:孤儿归并的同名对齐线索。 * registry 为 null 时返回 null(无从判定)。 */ private titleToScopeOf; /** * 孤儿记忆的兜底降落点:宿主当前工程合法时优先用它,否则取白名单首位。 * registry 为 null 时返回 null(无从判定,不迁移)。 */ private fallbackScopeOf; get actualPort(): number; /** * 零配置自启(异步):按配置端口尝试绑定;若 EADDRINUSE 则先做健康探测 —— * 确认是前序 tlmemory 实例(同名进程)时直接复用、不再重复绑定(多宿主并存 * 场景自动收敛,无需任何手工开关);确认是无关进程时自动顺延 +1 端口重试; * 连续重试仍失败则打印明确的 EADDRINUSE 解决指引。 */ start(): Promise; /** * 单次尝试:在指定端口上完成整套运行时装配(HTTP + WS upgrade + 安全校验)。 * 绑定成功后还会自检实际端口是否落在浏览器/fetch 封禁的禁区 * (port 传 0 时 OS 可能派发禁区端口),命中则立即释放并回报 'unsafe-port'。 */ private listenOnce; /** * 端口被占时的同名进程探测:向 127.0.0.1:/api/health 发一次短超时 GET。 * 响应携带 service:'tlmemory'(新版本)或 ok:true(兼容旧版本健康响应)即认定 * 是前序 tlmemory 实例在岗;探测超时/失败/非本服务响应一律返回 false。 */ private probeTlmemoryPeer; broadcastHits(treeType: string, hitNodeIds: string[]): void; notifyTreeChanged(treeType: string): void; private handleHttp; /** * P2-9:读取 JSON 请求体并按**字节**计数(此前按 UTF-16 code unit 计数, * 中文正文下与真实字节上限差 3 倍)。tooLarge=true 表示超过上限, * 由调用方回 413 并销毁连接 —— 超限请求不得伪装成「缺字段 400」。 */ private readJsonBody; /** * 工程重名冲突的可读提示(两个重命名端点共用)。 * * 为什么只提「另一个工程」而不回显对方名字:唯一性是**按名字查得**的 * (findProjectNameOwner 用 lower(name) 匹配),所以冲突对方的名字必然与所求 * 名字相同 —— 回显只会变成「已被工程「X」占用」而 X 就是用户刚输入的那个名字, * 徒增困惑。这里改为点明冲突性质与下一步动作。 */ private nameConflictMessage; /** * 解析 ?project= / ?scope= 里的工程标识为确定 scope。 * * 先走登记表 / 节点的常规解析(findProjectScope);解析不出来时,若它正是 * **宿主当前工程的 scope 或名字**,则视为合法并指向当前工程。 * * 为什么还要这层兜底:当前工程的登记项平时由 keepScope 豁免保留,但多宿主并存时 * 另一宿主的维护周期可能清掉它(对方不知道我们的活跃 scope)。此时看板在自己工程上 * 取树仍必须拿到**空树而不是 404**,否则「新建第一条记忆」的入口就断了。 * * 注意顺序:常规解析优先,所以当前工程的名字若被另一个**有记忆**的工程占用, * 仍然解析到那个工程(不劫持),只有真的无从解析时才兜底到当前工程。 */ private resolveProjectScopeParam; /** * readJsonBody 的统一入口:超限时回 413 并**保持连接语义**(不做任何强断), * 返回 null 表示调用方必须立即终止处理。 * * 413 投递可靠性加固(2026-09-16,实测数据见 tests/p2-fixes.spec.ts): * 曾经的实现是 `res.end(..., () => req.destroy())`,意图「超限客户端不值得继续占用」, * 但这会让**响应字节与对端仍在途的请求体赛跑**:TCP 语义下 destroy() 在接收缓冲仍有 * 未读数据时发出的是 RST 而非 FIN,RST 会让对端内核直接丢弃接收缓冲 —— 客户端因此 * 拿到 ECONNRESET 而不是 413。压测实测(40×300KB / 20×8MB / 并发 24×600KB): * 旧实现 300KB 失败 8/40,8MB 失败 20/20,并发 600KB 失败 24/24; * 仅去掉 req.destroy() 后 300KB 与 600KB 全通,但 8MB 仍失败 15/20 * —— 因为 `Connection: close` 会让 Node 在响应 finish 时立即 `destroySoon()`, * 与客户端在途请求体同样产生 RST; * 本实现(不强断、不声明 Connection: close)三个场景全部 0 失败。 * 代价与兜底:超限请求体的剩余字节会被继续消费并丢弃(readJsonBody 在超限后即停止 * 累积,内存占用仍严格封顶在 MAX_BODY_BYTES),连接资源由 Node 的 requestTimeout / * keepAliveTimeout 兜底回收,不再由本方法手工强断。 */ private readBodyOr413; private serveStatic; /** * 「工程不存在 / 作用域失效」时的容错响应体(v0.6.5)。 * * 契约要点: * - **HTTP 200 而不是 404**:看板把 404 当作链路错误,会让整块记忆区归零; * 未知工程在语义上等价于「这棵树是空的」,应当按空态渲染并给出可读提示。 * - `data` 与 `nodes` **同时**给出空数组:`data` 是看板既有字段,`nodes` 是本次 * 新增的显式别名,任何一侧的消费者都能拿到规范的空列表而无需判空。 * - `message` 携带可读原因(含用户填写的工程标识),便于前端直接展示。 */ private emptyTreePayload; private sendJson; stop(): void; } declare class TurnTracker { private currentTurn; private userTexts; private assistantTexts; private toolActivity; private readonly maxBufferChars; constructor(maxBufferChars?: number); /** 轮次开启:记录当前 turn;若上一个轮次未正常结算,防御式清空残留缓冲 */ onTurnStart(turn: number): void; /** * 人类输入进入本轮缓冲。sourceKind 必须为 'user',其余来源一律忽略 * (保证注入上下文/系统通知不会被误当作待沉淀的用户意图)。 */ addUserMessage(content: unknown, sourceKind: unknown): void; /** 助手可见文本进入本轮缓冲(assistant/message 事件驱动),并累计干活信号 */ addAssistantMessage(content: unknown): void; /** * 轮次结算:仅 reason.kind === 'completed' 且素材达到最低门槛时产出 * TurnTrackItem;其余结局(aborted/error/blocked/max-tokens/interrupted) * 一律清空缓冲返回 null —— 中断轮次不具备沉淀价值,严禁半成品入记忆库。 * 无论产出与否,调用后缓冲必然清空,保证下一轮从零开始。 */ endTurn(turn: number, reasonKind: string): TurnTrackItem | null; /** 插件卸载 / 会话翻篇时的兜底清理 */ reset(): void; } declare const name = "tlmemory"; declare const inject: string[]; /** 工程身份三元组:不可读的 scope 哈希 + 可读工程名 + 物理根目录 */ interface ProjectIdentity { scope: string; name: string; root: string; } /** * 解析当前进程所在的工程身份。 * * 工作区根目录来源优先级:显式入参(DSH 会话传入的 workspaceDir)> * 环境变量 DSH_WORKSPACE_DIR > 从 process.cwd() 向上回溯 .git 根目录。 * * scope 仍是「repo 根目录绝对路径」的 sha256 前 12 位,与历史版本逐字节一致(算法已 * 收敛到 workspaces.ts 的 projectScopeOf,与工作区白名单共用同一实现)—— 这样既有 * 记忆库的 tree_type 不会因为本次改造发生漂移;额外带出根目录 basename 作为可读工程名, * 交给 db.registerProject 落库,看板下拉框才能显示 * my-dsh-plugins / TLToolBox 这类人类可读的名字,杜绝裸哈希 repo: 充当展示名。 */ declare function resolveProjectIdentity(workspaceDir?: string): ProjectIdentity; declare function apply(ctx: Context, config: Config): () => void; export { Config, type ConsolidateReport, type CurrentProject, type MemoryCategory, MemoryCompactor, MemoryConsolidator, MemoryDB, MemoryExtractor, type MemoryNode, MemoryRecallEngine, type MemoryScope, MemoryServer, type MergeCluster, type OrphanMergeOptions, type OrphanMergeResult, type ProjectIdentity, type ProjectPruneOptions, type ProjectSummary, type QueryMemoryArgs, type RawReflectionItem, type ReflectionResponse, type SaveMemoryArgs, type ScopeResolver, type SearchOptions, type SearchResult, type ToolResultEnvelope, type ToolTextBlock, type TurnTrackItem, TurnTracker, type WorkspaceRegistry, apply, clusterCandidates, diceCoefficient, inject, isFetchForbiddenPort, loadWorkspaceRegistry, name, pathsAreSimilar, projectScopeOf, registerMemoryTools, resolveDshHome, resolveProjectIdentity, toContentBlocks, toToolResult, workspaceRegistryPath };