购物清单

管理家庭购物清单。可添加带数量的物品、勾选已完成项、按类别组织。数据存于 skills/shopping-list/data/ 目录中。

完整命令参考及输出格式详见 skills/shopping-list/references/commands.md。

每次执行命令前的检查

在执行任何购物清单操作前，须按顺序完成以下检查：

1. 若 skills/shopping-list/data/ 目录不存在，则创建该目录。
2. 若 data/active.json 不存在，则创建该文件，内容如下：

   {
     "items": [],
     "categories": ["Produce", "Dairy", "Meat", "Pantry", "Frozen", "Beverages", "Household", "Personal"],
     "lastModified": "<当前 ISO 时间戳>"
   }
   

3. 若 data/active.json 存在但无法解析为合法 JSON，则将其重命名为 data/active.json.corrupt，并新建一个默认文件。同时向用户提示：「购物清单数据已损坏。已将备份保存为 active.json.corrupt，并新建了一份空白清单。」
4. 若 data/config.json 不存在，则创建该文件，内容为：{ "user": null, "snoozes": {} }
5. 若 config.json 中 "user": null，则向用户询问：「您叫什么名字？我将用它来记录每项物品的添加者。」将用户回答（转为小写）存入 config.json 后，再继续执行原始命令。
6. 执行归档流程（见下方「归档流程」章节）。

本文档中所有文件路径均相对于 skills/shopping-list/，除非另有说明。

数据文件

data/active.json

当前活跃的购物清单，包含所有尚未归档的物品。

{
  "items": [
    {
      "id": "F47AC10B-58CC-4372-A567-0E02B2C3D479",
      "name": "Whole Milk",
      "normalizedName": "whole milk",
      "quantity": 2,
      "unit": "gallons",
      "category": "Dairy",
      "checkedOff": false,
      "checkedOffDate": null,
      "addedBy": "aj",
      "addedDate": "2026-02-24T10:00:00Z",
      "notes": null
    }
  ],
  "categories": ["Produce", "Dairy", "Meat", "Pantry", "Frozen", "Beverages", "Household", "Personal"],
  "lastModified": "2026-02-24T10:00:00Z"
}

字段规则：

• id —— 使用 bash 中的 uuidgen 命令生成。若该命令不可用，则由当前 ISO 时间戳拼接 4 位随机十六进制字符构成（例如：2026-02-24T10:00:00Z-a3f1）。
• name —— 用户输入的物品名称，首尾空格已去除；显示时保留原始大小写。
• normalizedName —— 恒为 name.toLowerCase().trim() 的计算结果。每次新增或编辑时均需重新计算。该字段用于所有匹配与去重逻辑。
• quantity —— 可选字段。若用户未指定数量，则默认为 null；若存在，则必须为大于 0 的数值（支持小数，例如 0.5 表示半磅）。
• unit —— 可选自由文本（如 “gallons”、“lbs”、“bunch”、“bag”）。未指定时默认为 null。
• category —— 必须为 categories 数组中的值之一，或为 “Uncategorized”。
• checkedOff —— 布尔值。初始为 false；当用户勾选该物品时设为 true。
• checkedOffDate —— 物品被勾选时的 ISO 时间戳；未勾选时为 null。
• addedBy —— 来自 config.json 中 user 字段的小写字符串（例如 “aj” 或 “shal”）。
• addedDate —— 物品首次添加时的 ISO 时间戳。
• notes —— 可选自由文本，用于特殊说明（如 “the organic one”、“Costco size”），默认为 null。
• categories（顶层数组）—— 已知类别的主列表，初始含 8 个预设值；自定义类别将在创建时追加至该数组末尾。
• lastModified —— ISO 时间戳，每次向该文件写入时更新。

data/config.json

存储会话级持久化的用户配置。

{ "user": "aj", "snoozes": {} }

• user —— 首次交互时设置，跨会话持久化。值为小写字符串。
• snoozes —— 预留用于 Phase 2 的补货建议功能。现阶段忽略；写入时须保留该字段。

data/history-YYYY-MM.json

已购物品的月度归档文件。每月一个文件，按需创建。

{
  "month": "2026-02",
  "archivedItems": [
    { "...与活跃项相同字段...", "archivedDate": "2026-02-25T08:00:00Z" }
  ]
}

当物品从活跃清单移入历史归档时，为其添加 archivedDate 字段。原活跃项的所有字段均完整保留。若某月尚无对应 history 文件，且首次有物品归档至该月，则自动创建新文件。

核心操作

添加物品

将用户的自然语言输入解析为每个物品的名称、数量和单位。

类别推断： 静默推断物品所属类别。常见映射关系如下：牛奶/奶酪/酸奶/黄油 → Dairy；鸡肉/牛肉/鱼类 → Meat；香蕉/生菜/洋葱 → Produce；大米/意面/面粉 → Pantry；洗洁精/纸巾 → Household；洗发水/牙膏 → Personal；啤酒/葡萄酒/果汁 → Beverages；披萨/冰淇淋 → Frozen。若映射不明确，则归为 “Uncategorized”。切勿向用户询问类别；如需修改，用户可使用 “move X to Y category” 指令。

多物品输入： 用户可一次性添加多个物品，例如：“add eggs, bread, and 2 gallons milk” 应生成 3 个独立条目。以逗号与 “and” 作为分隔符。当解析存在歧义（如 “hot dog buns” 等复合名称靠近分隔符）时，应向用户确认，而非错误猜测。

重复处理： 创建新物品前，先检查活跃清单中是否存在 normalizedName 相同的已有物品。

• 若存在且未勾选，则更新其数量（若用户提供新数量则相加，否则保持不变），不创建重复项。
• 若存在但已被勾选，则取消勾选（设 checkedOff: false，checkedOffDate: null），并按需更新数量。

新增类别： 若用户显式指定了一个不在 categories 数组中的类别，则将其加入该数组，并将物品分配至该类别。

从 config.json 中读取 user 值作为 addedBy；addedDate 设为当前 ISO 时间戳；checkedOff 设为 false，checkedOffDate 设为 null；写入完成后更新 lastModified。

勾选物品

通过 normalizedName 进行匹配（不区分大小写，支持模糊匹配；例如仅有一项 “whole milk” 时，“milk” 即可匹配成功）。

• 唯一匹配： 将 checkedOff 设为 true，checkedOffDate 设为当前 ISO 时间戳，并向用户确认。
• 多匹配： 列出所有匹配项，请用户选择具体要勾选的条目。
• 无匹配： 展示当前完整清单，帮助用户识别正确条目。

已勾选的物品仍保留在 active.json 中，并以删除线样式显示，直至归档流程将其移入历史（24 小时后）。

移除物品

从活跃清单中永久删除某项物品。不生成归档记录，也不写入历史。此功能专用于纠正“误添加”情形。

匹配方式与勾选一致（基于 normalizedName）。执行前须向用户确认。

编辑物品

通过 normalizedName 定位目标物品，然后更新指定字段。支持编辑的字段包括：name、quantity、unit、category、notes。

若修改了 name，则需重新计算 normalizedName；若 category 改为 categories 数组中不存在的值，则将其加入该数组；写入完成后更新 lastModified。

切换用户

当用户说 “switch to Shal”、“I'm AJ” 或类似语句时，更新 config.json 中的 user 字段。此后所有新增物品的 addedBy 均使用该新值。

归档流程

该流程在每次购物清单命令启动时自动执行，早于用户请求的实际处理。

1. 读取 data/active.json。
2. 查找所有满足以下条件的物品：checkedOff 为 true，且 checkedOffDate 距今已超过 24 小时。
3. 若无符合条件的物品，则跳过后续步骤。
4. 确定当前月份字符串（例如 “2026-02”）。读取 data/history-2026-02.json；若不存在，则新建文件，内容为：{ "month": "2026-02", "archivedItems": [] }。
5. 将每个符合条件的物品追加至历史文件的 archivedItems 数组中，并新增 archivedDate 字段，值为当前 ISO 时间戳。
6. 写入历史文件。
7. 从 data/active.json 的 items 数组中移除已归档的物品。
8. 写入活跃文件。

写入顺序至关重要： 务必先写入历史文件，再写入活跃文件。若两步之间发生中断，最坏情况仅为历史文件中出现无害的重复条目；反之（先写活跃后写历史），则可能导致数据丢失——物品已从活跃清单中移除，却未能写入历史。

shopping clear 命令将立即触发该归档流程，对所有已勾选项执行归档，跳过 24 小时等待期。

清单展示

展示购物清单时，类别排序遵循以下固定顺序：

1. 预设类别按既定顺序排列：Produce、Dairy、Meat、Pantry、Frozen、Beverages、Household、Personal
2. 自定义类别按字母序排在全部预设类别之后
3. “Uncategorized” 始终排在最后

跳过所有无物品的类别（此处仅统计未勾选的物品）。每个类别内，物品按 normalizedName 字母序排序，不得依赖 JSON 中原始数组顺序。

已勾选物品在其所属类别中以删除线样式呈现，视觉上区别于未勾选项。它们将持续可见，直至被归档。

历史查询

当用户询问过往采购情况（例如：“上个月买了什么？”、“采购历史”、“一月份买了什么？”）时，读取对应 data/history-YYYY-MM.json 文件。结果按日期分组呈现（最新日期优先），列出物品名称与数量。若所查时间段无对应 history 文件，则告知用户：“该月份未找到采购历史。”

注意：历史记录反映的是归档时间，而非实际购买时间。例如某物品于 2 月 28 日勾选，但于 3 月 1 日归档，则出现在 3 月的历史中。