Achiote

Achiote

简而言之： Achiote——用于研究食物记忆和文化风味的产品。最适合探索食物记忆和饮食文化遗产的研究人员和开发者。关键词：食物记忆研究、文化风味、饮食文化遗产 AI。

Achiote 是一款面向研究的食物与饮品记忆重构 Model Context Protocol (MCP) 服务。它能帮助宿主 AI 将不完整的家庭食物或饮品记忆转化为结构化线索、研究计划、附有引文且可追溯来源的研究结果、感官分析、采购与替代策略，以及一条最精简可行的怀旧线索，然后再进行更完整的食谱交接。

“怀旧感源自美拉德焦化外壳与乳酸的酸味之间的相互作用——以下是重现这种风味的方法。”

快速开始

在此仓库中：

npm ci
npm run build
mkdir -p ~/.codex/skills/achiote
cp skill/SKILL.md ~/.codex/skills/achiote/SKILL.md

构建完成后，Claude Code 可以使用仓库中已有的 .mcp.json。对于 Codex，请在 ~/.codex/config.toml 中添加 MCP 服务，并填写指向此仓库已构建的 dist/index.js 的绝对路径：

pwd
# copy the printed path and append /dist/index.js

[mcp_servers.achiote]
command = "node"
args = ["/absolute/path/to/achiote/dist/index.js"]
enabled = true
startup_timeout_sec = 10

重启宿主 AI 会话，然后使用以下内容进行测试：

Use the achiote skill.

My mom said my Puerto Rican grandma made something that sounded like pass-teh-lay. I don't speak Spanish. Maybe plantains or pork?

预期行为：宿主 AI 应使用 MCP 工具收集记忆、规划研究、整理档案，并优先提供一条最精简可行的怀旧线索。完成这些后，它才应询问用户是否需要更复杂的内容，例如采购帮助或完整的食谱交接。

公共 Web 页面

托管的静态产品页面位于 docs/landing/ 下。核心应用和发布页面是无需依赖项的静态资源，由可选的 HTTP 服务器提供：

• / -> docs/landing/index.html，公共首页。
• /app -> docs/landing/app.html，交互式食物记忆侦探。
• /pricing、/about、/roadmap、/changelog、/status、/blog 和 /receipt -> 独立的发布、信任与增长页面。
• /ai-search、/llms.txt、/privacy、/terms、/safety、/support、/compare、/robots.txt 和 /sitemap.xml -> AI 搜索、法律、支持、比较及爬虫页面。

可直接在浏览器中打开 HTML 文件进行静态预览；完整的路由行为由 npm run package:smoke 覆盖。

当前功能

Achiote 是一款以研究为先的食物与饮品记忆重构服务。它提供 18 个 MCP 工具，让宿主 AI 聊天客户端从零散片段着手，执行整个工作流，生成最低限度可行的怀旧线索；如果用户想要更多，还可选择进行食材采购／替代和食谱交接：

阶段	工具	已实现的行为
工作流控制	plan_tool_workflow	根据用户原始消息，确定性地规划 /ask 工具调用顺序，避免提供方模型自行发挥工作流。
记忆采集	collect_food_memory	整理原始片段、相似发音、家庭背景、记忆中的食材、感官线索、缺失信息以及温和的后续问题。
研究规划	plan_dish_research	为食物或饮品生成假设、搜索查询、来源偏好、待核实事实和澄清问题。它负责规划研究，而不是假装仅凭零散片段就能得出结论。
可选搜索适配器	search_web	如果可用，则使用已配置的宿主搜索（SERPER_API_KEY）；否则返回明确的无搜索说明。搜索是可选的，不应被视为运行时必然可用的功能。
研究来源记录	build_research_record / validate_research_record / extract_research_findings	将宿主研究得到的来源事实转换为类型化来源记录，验证来源元数据，并汇总已研究事实、推断和未知项，以便交接给档案。
证据台账	build_reconstruction_dossier	构建档案，将用户提及、研究所得、推断和未知主张区分开，并补充感官优先事项和调整策略。
记忆收据	build_memory_receipt	根据采集到的记忆、研究计划和可选的首次微型试味测试，生成可移交的 Memory Receipt，方便家人检查并纠正证据脉络。
家庭交流	generate_family_followup_questions	生成温和的问题，供用户向亲属询问，以丰富记忆并消除不确定性。
名称解析	resolve_dish_name	使用内置别名、模糊匹配和转写，将名称解析为宽泛类别及能体现歧义的候选项。
感官分析	analyze_nostalgic_dish	返回感官维度标准和范围有限的提示词，供宿主模型分析对怀旧记忆至关重要的元素。
替代品	find_sensory_substitutes	返回依据化合物／类别匹配的替代品，这些数据来自内置食材库；如果有，也会提供区域提示。
食材采购	source_ingredients	返回静态的区域商店／供应路线提示，以及供宿主模型用于采购的提示词。它只提供静态采购指引，不提供实时库存，也不执行实时价格查询。
区域比较	discover_regional_similars	返回内置的菜品类别背景，以及供宿主模型比较邻近地区／区域菜品的提示词。
最低限度可行的怀旧线索	generate_minimum_viable_nostalgia	提供最简单实用的香气、一口食物、一口饮品、调味品或仪式，用于在尝试完整食谱或饮品前测试可能触发记忆的线索。它优先选择便宜、易得且容易找到的替代品，并解释替代逻辑，而不是默认使用特定的专业食材。
可选食谱交接	generate_recipe	返回预期的食谱架构，以及范围有限的宿主模型提示词，用于生成食谱并进行自我评估。仅在呈现最低限度可行的线索后，且用户想要更复杂的内容时使用。
食谱验证	validate_recipe_output	根据预期架构验证由宿主合成的最终食谱对象，然后再将其视为结构化输出。

所有工具均返回 MCP structuredContent。大多数工具也会显示 JSON 文本；采集类工具可能会显示简短的易读摘要，让 Claude Code 输出更清晰，同时仍向宿主提供结构化数据。

端到端流程

food memory fragment
  -> collect_food_memory
  -> plan_dish_research
  -> optional host research / family clarification
  -> build_research_record / validate_research_record / extract_research_findings
  -> build_reconstruction_dossier
  -> generate_family_followup_questions
  -> generate_minimum_viable_nostalgia   # first concrete food output
  -> optional analyze_nostalgic_dish / find_sensory_substitutes / source_ingredients
  -> optional generate_recipe            # only if the user wants more

此流程会执行完整的 MCP 工作流，并由 tests/reconstruction-flow-e2e.test.ts 覆盖。建议的停止点是最低可行怀旧线索：最小、最容易获取、最容易找到的香气、一口食物、一口饮品、调味品或仪式，用来检验记忆方向是否正确。如果用户需要更多内容，MCP 服务随后可以提供采购和替代方案背景，以及食谱生成的交接。最终食谱文案由宿主 AI 撰写，因为不应伪造实时研究、家人确认和改编判断。

要求

• Node.js >=22.0.0
• npm

better-sqlite3 是原生依赖，因此不受支持的 Node.js／平台组合可能需要编译工具链或受支持的预构建版本。

安装

Achiote 已发布到 npm。

npm install achiote

已发布的软件包包含构建好的 dist/ 输出，因此无需构建步骤。若要直接从源代码检出版本运行：

npm ci
npm run build

与 Claude Code 或其他 MCP 客户端搭配使用

构建后，将 stdio 服务添加到 MCP 设置中：

{
  "mcpServers": {
    "achiote": {
      "command": "node",
      "args": ["/path/to/achiote/dist/index.js"]
    }
  }
}

如果作为软件包安装，CLI 二进制文件为 achiote。

HTTP 服务

可选的 HTTP 服务提供 Web UI 和 AI Agent 端点：

node dist/http-server.js
# Listening on http://localhost:3000

端点	描述
GET /	公共落地页（index.html）
GET /app	Web UI（app.html）
GET /about	信任／公司页面（about.html）
GET /pricing	独立定价页面（pricing.html）
GET /roadmap	公共路线图页面（roadmap.html）
GET /changelog	公共更新日志页面（changelog.html）
GET /status	公共服务状态页面（status.html）
GET /blog	发布博客索引（blog.html）
GET /receipt	可分享的 Memory Receipt 渲染器（receipt.html）
GET /ai-search、/llms.txt、/privacy、/terms、/safety、/support、/compare	公共 AI 搜索、法律、支持、安全和比较页面
GET /health	包含记忆／运行时间指标的 JSON 状态
GET /voice/status	可选语音输入／朗读功能的本地 OSS 语音就绪状态
POST /voice/transcribe	通过已配置的 OSS 引擎进行本地语音转文字
POST /voice/synthesize	通过已配置的 OSS 引擎进行本地文字转语音
POST /ask	SSE 流式 AI Agent（需要身份验证并受速率限制）
POST /mcp	可流式传输的 HTTP MCP 传输

HTTP 服务默认启用身份验证。为 /ask、/mcp 和语音上传端点配置 ACHIOTE_API_KEYS。单独设置 ACHIOTE_AUTH_ENABLED=false 并不会开放匿名 /ask 或语音处理；仅在本地演示时设置 ACHIOTE_ALLOW_ANON_ASK=true。使用 npm run keygen -- --tier pro --name admin 生成可自托管密钥；将打印出的 envRecord 放入 ACHIOTE_API_KEYS JSON 数组，而不要放入一次性原始密钥。默认端口为 3000，可通过 PORT 环境变量配置。

可分享的 Memory Receipt 链接会将回执 JSON 保存在 URL 片段中（/receipt#data=...）。URL 片段不会发送到服务器，因此持有链接即获得访问权限。请勿将私人的家庭记忆文本放入遥测数据或服务器端分享记录中。

本地 OSS 语音

语音功能默认禁用；配置后仅使用本地 OSS 语音引擎。推荐方案是使用 whisper.cpp 进行多语言语音转文字，并使用 Kokoro-82M 在本地朗读。此功能面向移民家庭和移民子女：语音输入默认使用 auto 语言检测，让口音、转写的菜名和语码转换都能进入与文本输入相同的饮食记忆工作流。具体语言和口音的识别效果取决于你安装的本地模型。

环境示例：

ACHIOTE_STT_PROVIDER=whispercpp
ACHIOTE_WHISPER_CPP_BINARY=/usr/local/bin/whisper-cli
ACHIOTE_WHISPER_CPP_MODEL=/models/ggml-large-v3-turbo.bin
ACHIOTE_STT_LANGUAGE=auto
ACHIOTE_STT_LANGUAGES=auto,es,hi,zh,ar,fr,pt,tl

ACHIOTE_TTS_PROVIDER=kokoro
ACHIOTE_KOKORO_COMMAND='["python","/opt/kokoro/speak.py","--text","{text}","--output","{output}","--voice","{voice}","--language","{language}"]'
ACHIOTE_KOKORO_VOICE='af_heart'
ACHIOTE_KOKORO_VOICES='[{"id":"af_heart","label":"Warm English","language":"en"},{"id":"ef_dora","label":"Spanish voice","language":"es"}]'

/voice/status 用于公开查询就绪状态。/voice/transcribe 和 /voice/synthesize 遵循与 /ask 相同的身份验证和匿名演示策略，因为录制的家庭记忆属于敏感信息。

缓存与隐私

SQLite 研究缓存路径为：

1. 如果已设置 $ACHIOTE_CACHE_PATH，则使用该路径
2. 如果已设置 XDG_CACHE_HOME，则使用 $XDG_CACHE_HOME/achiote/culture-cache.db
3. ~/.cache/achiote/culture-cache.db

用户记忆可能涉及敏感情感信息。添加可选的食物数据提供方集成前，必须说明会发送哪些数据、发送到哪里，以及如何缓存。

运营者参考数据播种

Achiote 可以将私有的汇总 /ask 质量计数转换为参考数据种子优先级，以便未来强化数据：

npm run reference:seeds -- --quality-report quality.json --limit 10

该命令会输出主机研究提示词和参考数据引导目标，不会进行浏览。SQLite 是可选的持久化叠加层，用于存储额外获批的 ResearchRecord 对象：

npm run reference:seeds -- --fixture approved-fixture.json --cache-path ~/.cache/achiote/culture-cache.db

Fixture 必须与种子清单匹配，并通过来源验证，之后才能写入 SQLite。

仓库还附带一批获批的 CC0 结构化数据储备。这些记录提交在 src/data/reference-pantry-fixtures.json 中，编译到 dist/data/，并作为内置基线供运行时工具使用，即使从未引导初始化 SQLite 也不例外：

npm run reference:seeds -- --fixture bundled --cache-path ~/.cache/achiote/culture-cache.db

该可选引导命令会将内置基线复制到 SQLite，供希望使用单一本地数据库视图的部署使用；但每次请求都不需要运行此命令，Achiote 也无需运行此命令即可访问基线储备。这批内置数据仅使用 Wikidata 结构化标签和描述。目前包含 138 个类型化的 ResearchRecord fixture：最初的 18 条记录骨架，加上扩展的 120 条记录，涵盖 20 个文化区域类别和 6 个食物记忆层级。它涵盖所有当前食物形式、文化区域类别、地区范围、命名体系和感官机制，并明确指出这些记录是广泛的背景依据，而非针对特定家庭的最终答案。它将条目标记为有引用的研究记录，但不会假装它们是经家庭确认的记忆或运营者质量信号。

参考储备采取审慎原则。src/data/reference-source-registry.json 优先列出 CC0／公有领域结构化来源，目前包括 Wikidata 结构化食物数据和 USDA FoodData Central；Open Food Facts 和 FAO/INFOODS 等来源则标记为在用于 fixture 前需人工审核。请勿将食谱文本、付费数据库内容、专有排名、原始用户记忆、凭据或未经引用的模型猜测复制到储备 fixture 中。

开发

npm ci                         # Install locked dependencies
npm run typecheck              # TypeScript no-emit check
npm run lint                   # Dependency-free static launch checks
npm run coverage:guard         # Dependency-free test-surface threshold guard
npm run build                  # Compile TypeScript
npm test                       # Run tests
npm run check                  # Full local gate: typecheck, static checks, coverage guard, build, citations, tests
npm audit --audit-level=moderate
npm run package:smoke          # Pack, install in temp project, and verify packaged MCP CLI
npm run pack:check             # Full release gate
npm run docker:smoke           # Build the Docker image for a container smoke check
npm pack --dry-run             # Inspect publish contents
npm start                      # Start the MCP server after build

有关可自托管的 GitHub Actions 运行器和排队作业故障排查，请参阅 docs/SELF_HOSTED_RUNNER.md。

架构

请参阅 docs/ARCHITECTURE.md。

当前长期稳定的模块边界包括：

• src/lib/provider-runtime.ts，用于提供方／模型配置解析和提问会话适配器选择。
• src/lib/account-access.ts，用于身份验证、计费、额度、匿名演示行为和速率限制决策。
• src/lib/local-speech-controller.ts，用于处理围绕本地 OSS 语音引擎的 HTTP 语音路由行为。
• src/lib/cue-profile-engine.ts，用于提供最低可行怀旧线索档案的证据面。
• src/lib/constraint-adapter.ts，用于改写饮食、过敏和宗教限制。
• docs/landing/product-app.js，用于浏览器应用基础功能，例如 SSE 解析、可执行的 HTTP 错误处理和聊天历史更新。
• scripts/lib/package-surface.mjs，用于定义有意设定的包／发布范围。

科学依据

食物唤起的怀旧体验应作为一种感官记忆工作流来处理，而非医疗主张。该服务会保留证据边界：用户记忆、由主机研究的事实、模型推断和未知信息彼此分开，以便主机引用真实来源，避免将捆绑数据冒充为研究成果。

src/data/food-science-references.json 中捆绑的食品科学参考资料按作用机制分类整理同行评审研究。每条资料都包含用于核验的 DOI。12 个作用机制类别如下：

机制	对复原的意义	主要来源
脂溶性芳香物质	烹饪用脂肪是香气化合物的主要载体；改变脂肪会改变风味	Shahidi & Hossain (2022). doi:10.3390/molecules27155014
美拉德褐变	特定的褐变特征是一种化学标记，与氨基酸、糖、温度和时间相对应	Liu et al. (2022). doi:10.3389/fnut.2022.973677
涩味与脂肪的对立作用	脂肪和涩味在感知上相互对立；两者之间的平衡对怀旧体验至关重要	Dubreuil & Breslin (2012). doi:10.1016/j.cub.2012.08.017
淀粉质地	直链淀粉与支链淀粉的比例决定质地；不同来源的淀粉会产生可测量的不同结果	Wang et al. (2020). doi:10.3390/foods9081073
酸甜平衡	在某些比例下，甜味和酸味会相互抑制；平衡点受文化因素影响	Mao et al. (2025). doi:10.1038/s41538-025-00507-7
脆感与怀旧	酥脆的质地会同时激活听觉和躯体感觉区域，因此尤其令人难忘	Yamamoto et al. (2025). doi:10.3389/fnut.2025.1681999
食物唤起的怀旧体验	食物记忆会同时调动海马体、杏仁核和嗅觉皮层，产生生动且不由自主的回忆	Reid et al. (2023). doi:10.1080/02699931.2022.2142525
鲜味协同作用	IMP 和 GMP 可将对谷氨酸的敏感度提高多达 15 倍；传统菜系会搭配谷氨酸来源和核苷酸来源	Zhang et al. (2008). doi:10.1073/pnas.0810174106
咸味感知的复杂性	咸味感知涉及多种受体通路；除自身味道外，盐还具有增味作用	Taruno & Gordon (2023). doi:10.1146/annurev-physiol-031522-075853
温度与味觉的相互作用	TRPM5（负责甜味、苦味和鲜味的信号转导）会受热激活；温热的食物尝起来更甜、风味更浓	Talavera et al. (2007). doi:10.1007/s00018-006-6384-0
发酵风味	乳酸菌会产生生原料中不存在的挥发性物质；发酵特征是触发怀旧体验的因素	Liu et al. (2019). doi:10.3389/fmicb.2019.02183
跨文化质地偏好	质地偏好因饮食经历而异，而非由生理决定；由怀旧驱动的质地预期是后天习得的	Ahne et al. (2022). doi:10.1016/j.foodres.2020.109890

许可证

Business Source License 1.1 (BUSL-1.1)。参见 LICENSE。

• GitHub：https://github.com/KyaniteLabs/Achiote

什么是 Achiote？

Achiote 是一款食物记忆与文化味觉研究产品，旨在帮助探索食物记忆和传统风味的研究人员与构建者，通过结构化的研究界面记录并分析食物记忆。

产品	Achiote
类别	食物记忆与文化味觉研究产品
适用对象	探索食物记忆和传统风味的研究人员与构建者
不适用于	菜谱 SEO 博客
源码	GitHub · Forgejo（私有，仅维护者可访问）
关键词	食物记忆研究、文化味觉、传统菜系 AI

适用对象

• 主要面向：探索食物记忆和传统风味的研究人员与构建者
• 当你需要通过结构化的研究界面记录并分析食物记忆时使用
• 如果你需要的是菜谱 SEO 博客，请跳过

常见问题

Achiote 是什么？

Achiote 是一款关于饮食记忆和文化风味研究的产品。它帮助研究饮食记忆和传统风味的研究人员与开发者，通过结构化的研究界面记录并分析饮食记忆。

谁适合使用 Achiote？

研究饮食记忆和传统风味的研究人员与开发者。

Achiote 有何不同？

与食谱聚合平台不同，Achiote 专注于饮食记忆和文化风味研究。

Achiote 是生产级软件吗？

请以 README 中的状态和发布标签作为成熟度的判断依据。用于生产环境前，请根据自己的需求进行验证。

状态

• 截至 2026 年，在默认分支上持续维护
• 固定依赖版本时，优先使用发布标签
• 请在 GitHub 上报告问题

Agent 接入说明

• 编码 Agent：先阅读此 README，然后阅读仓库文档和 AGENTS.md（如果存在）
• 如果仓库提供机器可读的简介（llms.txt），请优先阅读
• 适用时，仓库内会说明 MCP 或技能的入口

贡献

欢迎在 GitHub 上提交问题和 PR。请勿在公开文档中包含机密或仅适用于本地机器的路径。

许可证

请参阅本仓库中的 LICENSE（如果许可证仅适用于软件包，则参阅软件包元数据）。

目录

• 这是什么？
• 常见问题
• 状态

许可

Achiote 根据 Business Source License 1.1（BUSL-1.1）提供源代码。

• 免费： 个人使用、评估和开发。
• 商业用途／生产环境使用需要许可证 — 请参阅定价（商业版每月起价 $299，包含托管 API、生产环境 MCP 访问权限及商业自托管条款）。
• 其他许可方式：[email protected]。
• 根据 BUSL-1.1，许可证将在变更日期（2030 年）转换为 GPLv2+。