heuristics

用途

Heuristics 是一个“源到记忆”（Source-to-Memory Ingestion）的轻量级工作流技能，目标是把用户提供的文件或文件夹转化为有用的 historian 记忆。它本身不新增 TypeScript 工具、知识图谱子系统或持久化摄取管道，而是利用当前智能体已有的文件与 MCP 能力提取源内容，再使用 @historian 记忆工具，只保存值得长期保留的知识。

必需输入

用户必须提供至少一个文件或文件夹路径。如果没有提供路径，应先询问路径，再做其他任何事。

可选输入包括：包含或排除的文件 glob 或扩展名；如果已知的首选记忆类型；处理全部文件还是仅处理选定文件；是否跳过体积大或低信号的文件。

必需的第一步

在提取或保存内容之前，先让 @historian 列出可用记忆类型：

@historian list all memory types available

把返回的类型名作为保存记忆时的主要 memoryType 取值。如果没有类型适合某个文件，则跳过该文件并说明原因。

提取路由

针对每个用户提供的路径，先枚举候选文件。除非用户明确要求包含，否则跳过生成目录、依赖目录、缓存目录和二进制构建输出目录。默认跳过的常见文件夹包括：.git/、node_modules/、dist/、build/、.next/、coverage/，以及 .cache/、.turbo/、.parcel-cache/ 等缓存文件夹。

文本与代码文件

对文本类文件直接读取：Markdown、TXT、RST、YAML、TOML、JSON、XML、CSV、TSV，源代码与配置文件，以及用户明确要求摄取的日志。应提取可长期保留的事实、决策、约定、问题、偏好或可复用模式。除非整个文件本身就是一份简洁的事实来源，否则不要保存原始完整文件。

文档文件

对于 PDF、DOCX、PPTX、XLSX、HTML、EPUB 等文档格式：如果存在 markitdown，则用它把文件转换为 Markdown；如果 markitdown 不可用或失败，则用当前可用的最佳 LLM 或文件读取方法提取；如果提取仍不可靠，则跳过该文件并报告失败。markitdown 是可选项，当存在 LLM 提取路径时，绝不应要求用户先安装它。

图像与截图

对于 PNG、JPG、JPEG、WEBP、GIF、HEIC、SVG 及类截图文件：如果有视觉 MCP，则使用它；对含文字的截图优先采用面向 OCR 的提取；对示意图、白板或视觉笔记优先采用通用图像分析。如果没有视觉 MCP，则在可能时使用 LLM 提取，否则跳过并报告图像提取不可用。

混合文件夹

对于文件夹，按提取路由对文件分组，优先处理信号最强的文件。智能体可根据文件夹规模、文件大小和上下文预算决定分块与批大小，没有固定上限。

分类规则

把每个提取项对照 memory_list_types 返回的可用记忆类型进行分类。除非项目定义了更好的自定义类型，否则使用以下启发式规则：架构选择、系统权衡、所选技术归为 architectural-decision；UI/UX 选择、视觉方向、交互决策归为 design-decision；可复用的经验或发现归为 learning；用户陈述的工作方式或个人偏好归为 user-preference；团队或项目约定归为 project-preference 或 conventions-pattern；已知缺陷、风险、缺口或限制归为 issue；可复用的实现模式归为 recurring-pattern；一般性的可长期保留的项目知识归为 context。如果多个文件描述同一概念，应合并为一条记忆，而不是创建重复项。

持久化工作流

对每个有用的提取项：当内容可能与现有知识重复或需要更新时，用 memory_recall 搜索已有记忆；如果存在相关记忆，通过 memory_remember 使用其 filePath 进行更新；如果没有相关记忆，则用 memory_remember 创建新记忆。标题应简洁、具描述性，不要在标题中包含记忆类型。在记忆正文中添加源路径，使保存的知识保持可追溯。

示例 historian 请求：

@historian remember this as a learning: Title: markitdown-is-optional-for-source-ingestion Content: Source ingestion should use markitdown when available, but fall back to LLM extraction when it is not installed. Source: docs/ingestion-notes.md

不应存储的内容

跳过不属于长期项目记忆的内容：没有决策或发现的临时日志；可从别处获取的复制来的供应商文档；生成的构建产物；没有提取出经验、决策、约定或问题的原始源文件；密钥、凭据、令牌或私人个人数据。如果文件包含密钥，不要保存密钥；如有必要，只保存一条脱敏的 issue 记忆，例如“示例 env 文件包含看起来真实的令牌”。

最终报告

处理完成后，报告一张紧凑的表格：

Source	Extraction	Memory type	Result
path/to/file.pdf	markitdown	context	saved: title
path/to/screen.png	vision OCR	issue	saved: title
path/to/vendor.js	skipped	-	generated or low-signal

同时报告：发现的记忆类型；跳过的文件及原因；任何提取失败。

示例提示

Use heuristics to ingest ./docs into historian memories.

Use heuristics on ./research and only save architectural decisions and issues.

Use heuristics to extract these screenshots into memory: ./notes/*.png

Use heuristics to ingest ./meeting-notes, use markitdown if available, otherwise extract with LLM judgement.

成功标准

只有满足以下条件，工作流才算完成：用户提供的路径已被枚举；已先通过 @historian 检查可用记忆类型；每个文件都被提取、跳过或失败并给出明确原因；有用知识已被分类到某个可用记忆类型；有用知识已通过 @historian 的 memory_remember 保存；最终报告把每个处理过的源映射到其提取方法、记忆类型和结果。