heuristics

启发式规则：将来源内容摄取为记忆

目标

将用户提供的文件或文件夹转化为有用的历史记录记忆。

这项技能是一种轻量级工作流。它不会新增 TypeScript 工具、知识图谱子系统或持久化摄取管线。使用当前 Agent 的文件和 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 等文档格式：

1. 如果可用，请使用 markitdown 将文件转换为 Markdown。
2. 如果 markitdown 不可用或转换失败，请使用效果最佳的大模型或文件读取方法提取内容。
3. 如果提取仍不可靠，则跳过该文件并报告失败原因。

markitdown 是可选工具。如果有大模型提取途径可用，切勿要求用户先安装它才开始处理。

图像和屏幕截图

对于 PNG、JPG、JPEG、WEBP、GIF、HEIC、SVG 和类似屏幕截图的文件：

1. 有可用的视觉 MCP 时，使用它。
2. 对于包含文本的屏幕截图，优先采用面向 OCR 的提取方式。
3. 对于图表、白板或视觉笔记，优先采用通用图像分析。
4. 如果没有可用的视觉 MCP，则尽可能使用大模型提取；否则跳过，并报告无法提取图像内容。

混合文件夹

对于文件夹，按提取方式对文件分组，并优先处理信号最强的文件。Agent 可根据文件夹大小、文件大小和上下文预算决定分块方式和批次大小。不设固定上限。

分类规则

根据可用的记忆类型 memory_list_types 对每条提取的内容进行分类。

除非项目定义了更合适的自定义类型，否则使用以下启发式规则：

来源内容	可能的记忆类型
架构选择、系统权衡、选定的技术	architectural-decision
UI/UX 选择、视觉方向、交互决策	design-decision
可复用的经验或发现	learning
用户陈述的工作风格或个人偏好	user-preference
团队／项目约定	project-preference 或 conventions-pattern
已知错误、风险、缺口或限制	issue
可复用的实现模式	recurring-pattern
通用且持久有用的项目知识	context

如果多个文件描述同一概念，应将它们合并为一条记忆，而不是创建重复内容。

持久化工作流

对于每项有用的提取内容：

1. 当内容可能与现有知识重复或需要更新现有知识时，使用 memory_recall 搜索现有记忆。
2. 如果存在相关记忆，通过其 filePath 使用 memory_remember 更新。
3. 如果不存在相关记忆，则使用 memory_remember 创建新记忆。
4. 使用简洁、描述性标题。标题中不要包含记忆类型。
5. 在记忆正文中添加来源路径，以便保存的知识可追溯。

历史记录员请求示例：

@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

不应保存的内容

跳过不属于持久项目记忆的内容：

• 没有决策或发现的临时日志
• 可从其他地方获取的供应商文档副本
• 生成的构建产物
• 未提取出经验教训、决策、约定或问题的原始源文件
• 密钥、凭据、令牌或私人个人数据

如果文件包含密钥，不要保存密钥。仅在有用时保存经过脱敏的问题记忆，例如“示例 env 文件中包含看起来像真实令牌的内容”。

最终报告

处理完成后，报告一个简洁的表格：

来源	提取方式	记忆类型	结果
path/to/file.pdf	markitdown	context	已保存：title
path/to/screen.png	视觉 OCR	issue	已保存：title
path/to/vendor.js	已跳过	-	生成内容或信号较弱

另请报告：

• 发现的记忆类型
• 跳过的文件及原因
• 任何提取失败

提示词示例

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.

成功标准

只有满足以下条件，工作流才算完成：

1. 已枚举用户提供的路径。
2. 已先通过 @historian 检查可用的记忆类型。
3. 每个文件都已提取、跳过或标记为失败，并说明明确原因。
4. 有用知识已归类到可用的记忆类型。
5. 有用知识已通过 @historian 使用 memory_remember 保存。
6. 最终报告将每个已处理的来源与其提取方式、记忆类型和结果对应起来。