食忆 Shiyi Agent

项目介绍

食忆是一款可独立部署的餐食记录与下一餐推荐 Web Agent。用户可以通过网页用自然语言记录饮食、设置偏好和禁忌、获取下一餐建议，并查看历史记录、反馈与消费统计。

系统在保存餐食或调整长期设置前会要求用户确认；推荐会优先满足预算、偏好、过敏原和饮食禁忌等明确条件。未启用模型服务时，食忆仍可使用内置规则完成记录、确认、过滤、推荐、反馈和统计。

食忆不提供疾病诊断、治疗建议或营养处方。交付包中的餐食候选数据为合成演示数据，不代表真实商家、库存、价格或营养信息。

功能特点

• 自然语言记录餐食，例如餐食名称、时间和花费。
• 下一餐推荐，支持预算、口味、过敏原和饮食禁忌条件。
• 推荐结果说明理由，支持“换一批”“选择”“拒绝”和反馈。
• 餐食历史、消费统计和个人偏好设置。
• 多轮对话与确认机制，避免未确认的信息直接写入记录。
• 单客户独立身份访问，业务数据和会话数据隔离保存。
• PostgreSQL 持久化存储、安全审计、健康检查和数据保留配置。
• 默认仅监听本机地址，可通过 HTTPS 反向代理安全地提供远程访问。

运行步骤

运行环境

请在运行设备上准备：

• Git
• Docker Engine 或 Docker Desktop
• Docker Compose v2

1. 获取食忆

Windows PowerShell：

git clone https://github.com/yyl-no/shiyi-agent.git shiyi_agent
Set-Location shiyi_agent\customer-delivery

Linux 或 macOS：

git clone https://github.com/yyl-no/shiyi-agent.git shiyi_agent
cd shiyi_agent/customer-delivery

2. 创建配置文件

Windows PowerShell：

Copy-Item .env.example .env
notepad .env

Linux 或 macOS：

cp .env.example .env
${EDITOR:-vi} .env

在打开的 .env 中，替换以下两项的示例值：

SHIYI_DATABASE_PASSWORD=请填写较长且适合URL的随机数据库密码
SHIYI_STANDALONE_AUTH_TOKEN=请填写至少32字节的随机访问令牌

可在 Windows PowerShell 中生成一个 URL 安全的随机值：

$bytes = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
[Convert]::ToBase64String($bytes).TrimEnd('=').Replace('+','-').Replace('/','_')

分别执行两次，将两次结果填入数据库密码和访问令牌。请妥善保管该文件，不要公开其中的内容。

3. 启动服务

docker compose up --build -d

4. 检查状态并打开网页

Windows PowerShell：

docker compose ps
Invoke-WebRequest http://127.0.0.1:4317/api/health/ready
Start-Process http://127.0.0.1:4317

Linux 或 macOS：

docker compose ps
curl http://127.0.0.1:4317/api/health/ready

浏览器打开 http://127.0.0.1:4317 后，在页面的认证令牌输入框中填写 SHIYI_STANDALONE_AUTH_TOKEN 的值。

5. 开始使用

可以在对话框中输入：

午饭吃了一份鸡肉饭，花了 32 元。
下一餐想吃清淡一点的，预算不超过 40 元，不要花生。
换一批推荐。
选择第二个。
查看最近的饮食记录和消费统计。

停止服务

以下命令会停止服务，但保留餐食、设置和审计数据：

docker compose down

请勿在不需要清除业务数据时执行 docker compose down --volumes。

项目结构

shiyi_agent/
├── README.md                         食忆使用说明
├── customer-delivery/                可直接部署的客户交付包
│   ├── .env.example                  配置文件模板
│   ├── .env                          本地配置文件（自行创建，不公开）
│   ├── compose.yaml                  Docker Compose 服务定义
│   ├── Dockerfile                    食忆运行容器定义
│   ├── shiyi-runtime.tgz             食忆完整运行程序
│   ├── shiyi-runtime.tgz.sha256      运行程序完整性校验文件
│   └── README.md                     交付包补充说明
└── docs/
    ├── security-and-data-governance.md  安全与数据治理说明
    ├── deployment-and-recovery.md      部署与恢复说明
    └── production-baseline.md          运行基线说明

客户实际启动的目录是 customer-delivery/。运行程序、网页界面、业务规则、技能与演示数据都已包含在其中；运行时不需要额外获取其他源码或安装构建工具。

数据与访问安全

• 默认服务地址为 127.0.0.1:4317，仅本机可访问。
• 如需外网访问，请使用 HTTPS 反向代理，并不要直接公开应用端口。
• 数据库与安全审计文件保存在 Docker 命名卷中；更新或停止容器不会自动删除。
• 请定期备份业务数据，并妥善保管访问令牌和数据库密码。
• 访问令牌变更后，请重新启动服务：

docker compose up --build -d