Her Next Step Agent｜她的下一步

一个面向女性成长场景的长期陪伴型 Agent。它不替用户做人生决定，而是帮助用户：

• 梳理当下处境与真实需求；
• 在财经、公共生活、历史、住房与个人成长问题上获得可靠解释；
• 把模糊愿望拆成可执行目标；
• 保存经用户明确同意的长期记忆；
• 在后续对话中持续复盘和调整下一步。

当前版本：v0.1.0，local-first 原型。

核心架构

flowchart LR
    U[用户] --> UI[Gradio UI]
    UI --> S[Companion Service]
    S --> A[OpenAI Agent]
    A --> T[Domain Tools]
    S --> CS[(Conversation Session DB)]
    T --> DB[(Explicit Memory & Goal DB)]
    A --> W[Optional Web Search]

本项目刻意将两种记忆分开：

• Conversation Session DB：保存某个对话线程的上下文。
• Domain DB：只保存用户明确允许保存的事实、目标与复盘。

这样后续可以独立实现“清空聊天”“删除某条记忆”“迁移目标”和数据审计。

v0.1 能力

• OpenAI Agents SDK Agent loop
• Responses API 路径
• 可选 Web Search
• SQLite 持久化对话 Session
• 独立的长期记忆、目标和复盘表
• Gradio 交互界面
• 仅在明确同意后写入长期记忆
• 基础危机关键词兜底
• API Key 与数据库默认不提交 Git

技术栈

• Python 3.11+
• openai-agents==0.18.3
• gradio==6.20.0
• Pydantic Settings
• SQLite

快速启动

1. 创建环境

macOS / Linux：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

也可使用 uv：

uv venv
source .venv/bin/activate
uv sync

2. 配置环境变量

cp .env.example .env

编辑 .env：

OPENAI_API_KEY=your_api_key
OPENAI_DEFAULT_MODEL=gpt-5.4-mini
ENABLE_WEB_SEARCH=true
APP_SECRET_SALT=replace-with-a-long-random-string

生成随机 salt：

python -c "import secrets; print(secrets.token_urlsafe(32))"

3. 启动

python app.py

4. 测试

PYTHONPATH=src python -m unittest discover -s tests -v

测试不调用模型 API，只验证身份映射和领域数据库。

Profile alias 与 Thread

Profile alias 会通过带 salt 的 SHA-256 映射成内部用户 ID。它只是原型标识，不是身份认证。

Thread 用于区分不同对话：

• main
• finance
• housing-decision
• weekly-review

同一用户、同一线程会复用之前的对话 Session。

公开部署前必须接入真正的登录系统，否则知道 alias 的人可能访问同一份资料。

长期记忆规则

允许保存：

• 学习偏好
• 长期目标
• 用户主动要求记住的重要约束
• 经用户明确确认的背景信息

默认不保存：

• 密码、API Key、证件信息
• 精确金融账户信息
• 未经同意的敏感个人信息
• 一时情绪或短期琐事

GitHub 初始化

git init
git add .
git commit -m "feat: bootstrap companion agent v0.1"
git branch -M main
git remote add origin https://github.com//her-next-step-agent.git
git push -u origin main

使用 GitHub CLI：

gh repo create her-next-step-agent --public --source=. --remote=origin --push

Hugging Face Spaces

创建 Gradio Space 后，在 Space Settings → Secrets 中配置：

• OPENAI_API_KEY
• OPENAI_DEFAULT_MODEL
• APP_SECRET_SALT

公开 Demo 不应保存真实用户的精确财务、身份或健康信息。上线前至少需要：

1. 登