个人旅行管家

概述

使用本技能维护用户本地、人类可读的旅行知识库，并基于该知识库回答旅行相关问题。请将系统层（personal-travel-butler/）与数据库层（travel-db/）严格分离。

数据库位置

除非用户明确指定其他数据库路径，否则默认使用相对于本技能文件夹的 ../travel-db。以 Markdown 文件为唯一事实来源；生成的索引文件仅为可重建的视图。

当从本地 Hermes 安装运行时，本技能可能通过符号链接从 ~/.hermes/skills/personal-travel-butler 指向用户的本地 personal-travel-butler 文件夹。若相对路径查找存在歧义，请向用户确认项目根目录，并以其同级的 travel-db 文件夹作为数据库路径。

使用 ../travel-db/notion-sync 实现与 Notion 的互操作性。保持该目录为扁平结构：机器应优先读取 _records.jsonl；人类用户宜浏览 _index.md；仅对需要长文本备注的记录，才单独创建详细 Markdown 文件。

核心工作流

1. 在重构前完整保留用户原始输入。
2. 从中提取地点、餐厅、菜品、指南条目、约束条件及偏好信息。
3. 基于名称、别名、城市、地址、坐标、来源 URL 及特色备注等字段，在已有 Markdown 条目中主动检索潜在重复项。
4. 在工具可用且权限允许的前提下，主动补全缺失事实：地址、坐标、营业时间、预约方式、官方链接、招牌菜、交通提示、当前状态等。
5. 完整保留原始证据来源及验证日期。禁止覆盖冲突事实；应在对应字段或条目中标注冲突说明，并标记为 needs-review。
6. 创建或更新原子化 Markdown 条目后，视需要刷新生成的索引文件及 Notion 精简镜像。
7. 在回答问题或规划行程时，须优先引用本地条目，并清晰区分本地知识与新核查的外部信息。

Hermes 使用规范

当从 Hermes 调用本技能时，切勿要求用户将 Notion Token 或凭证粘贴至聊天窗口。应通过已提供的脚本，从项目根目录的 .env 文件中读取本地 Notion 配置。

若用户询问 Notion 是否已连接：

1. 不得执行 scripts/notion_setup.py --apply。
2. 不得新建 Notion 数据库。
3. 应运行 scripts/notion_check.py --db /travel-db。
4. 若检查成功，则回复 Notion 已连接。
5. 若检查失败，则简明报告具体错误，并建议用户本地检查 .env 配置，严禁在输出中打印 Token 值。

scripts/notion_setup.py --apply 仅限首次初始化使用，且仅在 NOTION_TRAVEL_DATA_SOURCE_ID 尚未配置时调用。若该环境变量已配置，则视为初始化已完成，不应再次运行该脚本。

输入处理规则

• 文本类输入：若包含多个事实或实体不明确，先保存原始文本至 _inbox/，再将稳定实体拆分为原子化条目。
• 地点名称或地图链接：创建或更新对应地点条目，补充最新事实，并记录查询来源。
• 图像/截图：将图像存入 assets/，OCR 或提取的文字内容存入 _inbox/，再基于提取结果创建条目。
• 偏好设置：应更新 preferences/ 下的独立条目，而非将个人约束混入地点备注中。
• 行程规划请求：须先读取 preferences/、相关 places/、guides/ 和 trips/，再给出建议。

参考资料

• 创建或更新条目前，请先阅读 references/database-schema.md。
• 文本、位置及图像摄入规则详见 references/ingestion-workflow.md。
• 生成推荐或行程前，请先阅读 references/recommendation-workflow.md。
• 修改 Notion 同步文件前，请先阅读 references/notion-sync-folder-standard.md。
• 配置 Notion Token、数据源 ID 或调用实时 API 前，请先阅读 references/notion-integration.md。
• 将 Notion 属性映射至本地字段前，请先阅读 references/notion-sync-schema.md。
• 使用 scripts/create_entry.py 创建具备稳定 ID 与合法 frontmatter 的条目骨架。
• 使用 scripts/validate_db.py 检查必填字段、ID 重复、链接有效性及基础数据库完整性。
• 使用 scripts/notion_check.py 验证 Notion 同步目录结构；若凭证就绪，还可验证 Notion Schema 访问权限。
• 使用 scripts/notion_setup.py 在共享父页面下创建 Notion 旅行数据库及所需属性。
• 使用 scripts/notion_sync.py 执行“先试运行（dry-run）”的 Notion 推送/拉取/同步方案。
• scripts/notion_sync.py push|sync 默认在规划前从 Markdown 条目刷新 _records.jsonl；使用 --strict 可阻止覆盖 Notion 端已编辑内容，使用 --filter-city 或 --filter-tag 可实现选择性同步。
• 使用 scripts/notion_schema.py check|migrate 检查或为现有数据源添加可选的 Notion 列。
• 仅当需在不调用 Notion 的前提下刷新精简镜像与本地生成索引时，才使用 scripts/build_records_from_places.py --apply。
• 使用 scripts/notion_compact.py 将轻量或标准 Notion 记录保留在 _records.jsonl 中，避免额外生成 Markdown 文件。
• 当某条轻量或标准记录值得展开为详细 Markdown 文件时，使用 scripts/notion_promote.py。

命令优先使用原则

常规操作请优先使用 scripts/butler.py。仅当命令接口无法表达所需变更时，才直接编辑 Markdown 文件。

为提升弱智能体（weak-agent）可靠性：

• 新增地点时，请运行 butler.py add-place，而非手动创建 Markdown 文件。
• 发现重复条目时，请运行 butler.py update-place。
• 执行 butler.py sync --apply 前，务必先运行 butler.py sync 进行试运行。
• 除非处于无任何现有数据源的首次初始化阶段，否则严禁运行 notion_setup.py --apply。

写作规范

• 每个地点、餐厅、指南、行程或偏好记录，均应对应一个原子化 Markdown 文件。
• YAML frontmatter 应保持合法且简洁：仅使用字符串、列表、数字、布尔值或 null。
• 统一使用相对链接与路径，确保数据库兼容 Obsidian 及纯文本编辑器。
• 在证据或收件箱备注中，应保留用户原始措辞。
• 从外部信息补全内容时，须注明置信度与信息来源。
• city 字段仅保留一个标准化城市名（如 文昌 或 深圳）；省份、区县、街道或详细地址等信息应置于独立字段或正文备注中。
• 索引文件均为派生内容，不得将其视作权威记录。
• Notion 同步应保持轻量：简单记录保留在 _records.jsonl 中；仅详细记录才在 notion-sync/ 下创建独立 Markdown 文件；位于 places/、guides/、trips/ 和 preferences/ 下的 Markdown 条目，均视为精简 Notion 镜像的源材料。
• 当 NOTION_TRAVEL_DATA_SOURCE_ID 已配置时，禁止再次运行 scripts/notion_setup.py --apply；应改用 scripts/notion_check.py --db travel-db 验证现有 Notion 数据库，再用 scripts/notion_sync.py sync --db travel-db 执行同步。
• 严禁在聊天输出中粘贴、回显、摘要或存储 Notion Token。若 Token 不慎出现在聊天中，应建议用户立即轮换，并将新 Token 移入本地 .env 文件。