氛寸 · Fēn Cùn
别人帮你挑香水，氛寸帮你用好香水
一个基于实时情境的个人 「用香决策」Agent：
从你已有的香柜里，告诉你此刻——喷哪瓶、喷多少、喷在哪、能留多久、要注意什么，以及为什么。
它解决什么
站在香柜前，你从不缺香水——缺的是「今天到底用哪瓶、怎么用得恰到好处」的那个判断。
- 「今天喷哪瓶」是入口：你的香柜 × 此刻情境 → 最合适的一瓶，不认同可一键换成任意一瓶，用法即时重算。
- 「这瓶怎么用」是灵魂：喷量档位 / 喷洒位置 / 社交距离 / 留香区间 / 风险提示。
| 传统香水 App | 氛寸 |
|---|
| 解决的问题 | 买之前——挑哪瓶 | 买之后——今天用哪瓶、怎么用 |
| 输入 | 喜好、预算、评论 | 你已有的香柜 × 实时天气 × 场合 |
| 输出 | 种草、购买链接 | 可执行的用香建议 + 明确裁决 + 为什么 |
核心能力
- 🎯 今日之选 + 怎么用 — 自动感知实时天气与此刻时段，从你的香柜打分推一瓶，附完整分寸建议。
- ⚖️ 不迁就的裁决 —
good / caution / avoid 三档。真不合适就先说「今天不建议这瓶」，再告诉你坚持要用时怎么补救。
- 💬 自然语言场景 — 输入「去前任婚礼」「第一次见投资人」，DeepSeek 解析出场合、正式度、关系张力、是否饭局，喂进打分与用法。
- 🔔 发现型钩子 — 不等你问：常喷的那瓶今天会翻车（急性天气 / 反季 / 场合预警），搁置已久的那瓶今天正合适。
- 🔁 反馈闭环 — 答一句「今天，刚好吗」，个人偏移按瓶收敛：嫌冲就少喷，答「刚好」就记住这套配置；高温天答「淡了」归因给天气，不冤枉香水。
- 🔂 轮换有度 — 昨天刚喷的今天自然让位，久置的自然浮起，兑现「今天喷哪瓶每天不一样」。
- 📖 香历 — 采纳或反馈的每一瓶自动落进月历（色点 = 当日主香调），点开任一天是当日快照，可补一句话手记。无香的日子留白。
- 🪞 演示香柜 — 第一次打开就是满配：六瓶示例香水与近一个月的穿香记录，推荐、预警、香历、画像全部有内容可看；加进你自己的第一瓶，它就整体退场。
- 🌗 昼夜双主题 — 「明韵 / 暗香」两套设计语言，默认明韵，右上角随时切，不跟系统深浅色走。
它怎么想
决策权在规则引擎，表达权在 LLM。 匹配打分、喷量与留香判定全部由确定性规则计算，可解释、可复现、有单测；DeepSeek 只做两件事——听懂自然语言场景、把规则算好的事实翻成人话。天气永远来自和风天气 API，由服务端代理按坐标网格缓存 30 分钟。LLM 的输出还要过一道数字白名单：事实里没给过的数字（比如编造的「留香 6.2 小时」）整段拦下、退回规则模板。DeepSeek 超时，规则引擎照样出推荐。
香柜、反馈与香历都存在浏览器 localStorage，服务端不保存用户数据；目前没有账号与云同步，「我的」页可导出 / 导入 JSON 备份。
flowchart TD
Lib["🗄️ 你的香柜<br/>localStorage 持久化"]
Weather["🌤️ 和风天气 API<br/>实时温 / 湿 / 风"]
Scene["💬 自然语言场景<br/>DeepSeek 解析意图"]
Ctx["📍 此刻情境<br/>季节 · 体感 · 时段 · 场合"]
Engine["⚙️ 规则引擎<br/>确定性打分 · 可解释"]
Pick["🎯 今日之选<br/>喷量 · 位置 · 距离 · 留香 · 裁决"]
LLM["✍️ DeepSeek<br/>把事实翻成人话"]
Out["💡 有温度的解读"]
Tpl["📄 模板兜底<br/>LLM 挂了也不白屏"]
Weather --> Ctx
Scene --> Ctx
Lib --> Engine
Ctx --> Engine
Engine --> Pick
Pick --> LLM --> Out
Pick -. 降级 .-> Tpl
打分公式
src/lib/scoring.ts：
score = ( 0.38·季节匹配 + 0.19·时段匹配 + 0.43·场合贴合 ) ← 线性主项，权重归一
× 天气乘子 W ∈ [0.7, 1.3] ← 闷热压厚重、寒冷奖暖香
× 质量微调 Q ∈ [0.96, 1.04] ← 社区口碑只作轻推，不替你挑瓶
× 个人偏移（按瓶偏好 · 场合差评） ← 你的反馈收敛而来，正负双向、按月衰减
× 场景压制（规避项 · 张力与正式度） ← 「别太甜 / 别太冲」硬降权，高张力先压存在感
rank = score × 轮换新鲜度 F(d) × 换瓶隐式差评 ← 只动排序，不动裁决与展示
每一项的取值范围、成因与领域依据见领域规则手册 §6.4。
四条戒律
- 不伪精确 — 留香 / 喷量 / 社交距离只给区间与档位，绝不给「6.2 小时」这类无法验证的假数字；证据不足就明说降级。
- 不过度设计 — 不上向量库、不引重后端；规则引擎在浏览器本地毫秒出结果。同一个概念只留一处判据。
- 轻冷启动 — 搜名秒加建香柜，不逼用户先填问卷；搜索、扩展目录、手动记一瓶与示例香柜共同保证进门就能用。
- 有反馈闭环 — 每次推荐都能被评价、被修正。每个反馈入口都要有明确、可测试的消费路径；兑现不了的入口直接删掉。
技术栈
| 层 | 选型 | 说明 |
|---|
| 框架 | Next.js 16.3（App Router）+ React 19.2 + TypeScript 6 | 一仓库承载前端与轻后端 |
| 后端 | Route Handlers | 代理和风 / DeepSeek，保护 key + 缓存 + 限流 + 降级 |
| 样式 | Tailwind v4（CSS-first @theme token，无 UI 库） | 昼夜双主题、自持字体 |
| 决策 | 确定性规则引擎（纯 TS） | 前端本地打分，可解释可单测 |
| 检索 | MiniSearch 7（自定义中英文分词） | 搜名 / 品牌 / 香调秒加 |
| 状态 | Zustand 5 + localStorage | 香柜与反馈持久化，storage 适配层可替换 |
| 语义 | DeepSeek（deepseek-v4-flash） | 场景解析（json_object + zod 校验）+ 自然语言解读 |
| 天气 | 和风天气 QWeather | 服务端调用 + 30 分钟网格缓存 |
| 校验 / 部署 | zod · Vercel | 入参校验、GitHub 自动部署 |
数据
香水数据来自 ledecanteur（Fragrantica 社区数据），每一款都带真实社区投票：扩散、留香、四季与日夜分布、带强度的香调、前中后调。
原始 13.2 万款按投票数 ≥ 50 筛得 3.67 万款，再分两层：主目录取热度 Top 1500 做全中文精选（香名 89.0% 有中文名），随首屏加载；其余进扩展集，搜索索引懒加载、详情按分片取。两层合并成一张榜单，再搜不到还有手动记一瓶兜底。没有可靠中文名的 165 款保留英文——错的中文名比英文更糟。
完整管线、分层账目与中文化口径见数据工程。
本地运行
需要 Node 24。
npm install
cp .env.example .env.local # 各项 key 的用途与申请入口见文件内注释
npm run dev # http://localhost:3000
没有 key 也能跑：天气走「季节 + 时段」降级，解读走规则模板。提交前跑一遍：
npm run lint && npm test && npm run build
数据管线（可选，仓库已含构建产物，需自备 ledecanteur/perfumes.jsonl）：
npm run extract:terms # 流式抽取精选子集与词表
npm run build:data # 应用中文映射 + 预计算 → public/data/perfumes.min.json
npm run build:ext # 全量扩展集：搜索索引 + 64 详情分片 → public/data/ext*
门面素材需先起生产服务器，next dev 的调试悬浮球会入镜：
npm run build && npx next start -p 3100
SHOT_BASE=http://localhost:3100 npm run shot # README 截图 → .scratch/shots/
SHOT_BASE=http://localhost:3100 npm run og # 分享卡片与 PWA 图标 → public/
两个脚本用无头浏览器拍站点自己的页面，目前只从 Windows 的固定路径找 Chrome 或 Edge（scripts/shot.mjs 的 CHROME_CANDIDATES），换平台要先改这份清单。
目录结构
src/
app/ 今日 / 香柜(library) / 香历(journal) / 我的(profile) 四页 + API 路由
api/context/ 和风天气代理（保护 key + 网格缓存 + 降级）
api/explain/ DeepSeek 解读（只翻译规则事实，失败降级模板）
api/parse-intent/ DeepSeek 场景解析（zod 校验，降级关键词启发式）
components/ AppProvider / 推荐卡 / 情境栏 / 发现型钩子 / 搜索添加 / 手动记一瓶 …
lib/ types · scoring(打分) · usage(用法) · recommend(编排)
· occasion-priors(场合先验) · format(档位话术单一出处)
· journal(香历) · perfumes(统一搜索 + 扩展目录) · catalog(目录加载)
· numguard(数字白名单) · nudges(发现型钩子) · demo(演示香柜)
· season · hooks · store · ratelimit
scripts/ 零依赖数据构建管线 + 截图 / 分享素材 / 依赖审计门禁
data/zh-map/ 英文→中文映射（accords / notes / brands / names）
docs/ 产品方案 · 领域规则手册 · 数据工程 · 声音与文案 · 迭代实录 · 截图
文档
- 产品方案 — 定位、用户、产品模型、关键决策、指标与路线图。
- 领域规则手册 — 每条打分与用法规则的领域依据，逐条标了证据等级。
- 数据工程 — 13.2 万 → 3.67 万 → 中文映射的完整管线。
- 声音与文案 — 术语、语气与表达边界。改用户可见的字之前先读它。
- 迭代实录 — 上线后每一轮迭代的动因、取舍与沉淀下来的纪律。
参与 · 许可
