diy-pc-ingest

初始化配置（必需）

该技能设计为共享使用。请切勿在技能代码中硬编码您的 Notion ID 或 token。

使用本技能前，请先通过 ClawHub 安装所需的依赖技能：

clawhub install notion-api-automation

1. 查阅 TOOLS.md 中的 “DIY-PC Notion Targets” 表格，获取各目标表对应的 data_source_id 和 database_id 值，并以显式 CLI 参数形式传入：

• --pcconfig-dsid、--pcconfig-dbid
• --pcinput-dsid、--pcinput-dbid
• --storage-dsid、--storage-dbid
• --enclosure-dsid、--enclosure-dbid

2. 为 notion-api-automation（即 notionctl）提供 Notion 认证凭据：

• 环境变量：NOTION_API_KEY（推荐方式）

注意事项：

• 本技能默认使用 Notion-Version 2025-09-03。

数据流说明

• 本地输入：粘贴的收据/规格说明文本在本地解析。
• 外部增强（可选）：web_search/web_fetch 可能将部分产品文本发送至外部网络服务提供商。
• Notion 写入路径：记录通过 notion-api-automation/scripts/notionctl.mjs 查询或 upsert。

安全规则：

• 若用户不希望启用外部增强，请跳过 web_search/web_fetch，仅执行本地提取。
• 使用最小权限范围的 Notion 集成权限（仅限目标 DIY_PC 数据源）。

标准 Notion 目标表

使用 data_sources 接口进行 schema 查询与数据查询，使用 pages 接口创建新行。

ID 均已在 TOOLS.md 的 “DIY-PC Notion Targets” 表格中列出，请在运行时作为 CLI 参数传入。

工作流程（A：用户粘贴原始文本）

1. 读取粘贴的文本，并按条目判断应写入的目标表：

   • エンクロージャー（机箱/外置盒）：USB/RAID/HDD 机箱/坞站、硬盘托架数量（ベイ数）、JAN 码/型号、安全移除显示名（“安全な取り外し”表示名）。
   • ストレージ（存储设备）：HDD/SSD/NVMe/SATA、容量、序列号、健康状态。
   • PCConfig：CPU/GPU/RAM/电源/主板/机箱/散热器/NIC/采集卡等。

2. 提取字段（尽力而为）。优先采用各表中已定义的日文列名。

3. 通过 web_search/web_fetch 增强规格信息，仅在可显著减少用户操作时启用（例如：托架数量、接口类型、容量、外形尺寸等），保持最小化增强；避免过度填充。

4. 仅就必要字段发起追问，以规避歧义或错误关联：

   • ストレージ：序列号缺失 → 询问序列号（或确认以“暫定/シリアル不明”创建）。
   • エンクロージャー：托架数量（ベイ数）或 USB/Thunderbolt/LAN 接口类型不明确 → 询问。
   • PCConfig：缺少唯一标识符/型号，但该字段对匹配已有记录至关重要 → 询问。

• 若某主键匹配到多条现有记录，则禁止写入，需向用户确认。

5. 使用 scripts/notion_apply_records.js 在 Notion 中搜索已有记录（自动发现模式）：

   • 通过 stdin 输入 JSONL 格式记录（每行一条）。
   • 脚本将：
     • 依据主键查找已有行（见下文）
     • 报告拟创建/更新/跳过的变更内容，但不实际执行任何修改
     • 不执行任何写入操作（无 create/update 操作）
   • 此步骤用于在真实 upsert 前预览结果。

6. 审查搜索结果并征得用户确认：

   • 展示拟创建/更新/跳过的全部变更项
   • 在执行真实 upsert 前，必须获得用户确认

7. 执行 Notion upsert，调用 scripts/notion_apply_records.js：

   • 通过 stdin 输入 JSONL 格式记录（每行一条）。
   • 脚本将：
     • 依据主键查找已有行（见下文）
     • 默认仅填充缺失字段；除非指定 overwrite=true，否则不覆盖已有值
     • 如未匹配到已有行，则新建一行

8. 输出最终结果（创建/更新/跳过数量），并附上所有新创建页面的链接。

Upsert 主键规则

• ストレージ：以 シリアル（精确匹配）为主键。若已有记录创建时未填写序列号，则允许安全降级匹配：以标题（title/name）+（可选）購入日 或 価格(円) 组合匹配，以便后续补填序列号、健康状态、扫描日期等字段。
• エンクロージャー：优先以 取り外し表示名（精确匹配），其次使用标题（title/name）。
• PCConfig：以 (Name + Purchase Date) 作为复合主键（精确匹配）。若出现多条匹配结果，则禁止写入，须向用户确认。
• 若某主键匹配到多条现有记录，则禁止写入，需向用户确认。

apply 脚本的 JSONL 输入格式

每行为一个 JSON 对象：

{"target":"enclosure","title":"RATOC RS-EC32-R5G","properties":{"種別":"USBケース","接続":"USB","ベイ数":2,"普段つないでるPC":"RECRYZEN","購入日":"2026-01-18","購入店":"PCワンズ","価格(円)":8977,"取り外し表示名":"RS-EC32-R5G","メモ":"JAN: 4949090752191"}}

可选控制字段（用于清理或手动修复）：

• page_id（或 id）：直接更新该 Notion 页面（绕过 upsert 匹配逻辑）
• archive: true：归档该页面（适用于去重场景）
• overwrite: true：允许覆盖已有字段值（包括设为 null 清空）

可选行为标志：

• mirror_to_pcconfig: true（仅适用于 target=storage）：同时为已安装组件创建或更新一条 pcconfig 记录。
  • 前提条件：必须提供 現在の接続先PC、購入日、Name

支持的目标表：enclosure | storage | pcconfig | pcinput

属性值编码规范：

• select / status：字符串名称（string name）
• rich_text：字符串（string）
• number：数字（number）
• date：YYYY-MM-DD 格式
• checkbox：布尔值（boolean）
• relation：page_id 数组（高级用法；非必要请避免使用）

注意事项

• 始终使用 Notion-Version 2025-09-03。
• 优先使用 POST /v1/data_sources/{id}/query，而非 /databases/{id}/query。
• 更新 relation schema 时，需提供 relation.data_source_id（而非 database_id）。

实现说明

• 默认 JS 实现：scripts/notion_apply_records.js
• 遗留 Python 实现（仅供参考）：scripts/_deprecated/notion_apply_records.py

Notion 工具链（推荐）

• 通过 ClawHub 安装 notion-api-automation 以调试 Notion API：clawhub install notion-api-automation
• 本技能不依赖 skills/notionkit/* 下的任何内容。
• 主要数据注入路径为 scripts/notion_apply_records.js；诊断或手动调用 API 时，请使用 skills/notion-api-automation/scripts/notionctl.mjs。