1 line
293 KiB
JSON
1 line
293 KiB
JSON
{"repo": "1420079678-ctrl/zhiyuxing-ai-assistant", "files": {"docs/usage-guide.md": {"ae16815c4abd513e54177647e0738b109a8a5ee5": {"t": 1785746500.0084815, "n": 4526, "h": "01b6c25df24f8288", "c": "# 使用说明\n\n[中文](usage-guide.md) | [English](usage-guide.en.md)\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 会结合本地知识库、会话记忆和风险规则生成演示回复\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置与当前模型匹配的密钥变量\n- 支持 `OPENAI_API_KEY`\n- 也支持 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`、`MODEL_API_KEY_ENV`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_API_KEY_ENV` | 当前模型优先读取哪个密钥变量，例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n| `CHAT_DB_PATH` | 本地 SQLite 会话库路径，默认写入 `data/zhiyuxing.db` | 否 |\n| `KNOWLEDGE_UPLOAD_DIR` | 自定义知识文档写入目录，默认写入 `data/knowledge_uploads` | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型\n\n优先推荐直接运行一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。\n\n这些脚本会自动：\n\n- 初始化 `.env`\n- 写入当前模型所需的 `OPENAI_BASE_URL`\n- 写入 `MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`\n- 尽量保留现有密钥和其他环境变量\n\n这几个脚本不是免 Key 调用，只是把模型接入配置一次写好：\n\n- `.\\setup-openai.ps1`：真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n\n如果你没有填写对应 Key，项目也不会坏掉，只是会继续运行在本地演示模式。\n\n### 3. 手动配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 4. 启动前检查\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n它会检查：\n\n- 当前模型会读取哪个 API Key\n- 当前 `.env` 是否真的能进入真实模型调用模式\n- 当前 `OPENAI_BASE_URL` 和 `MODEL_NAME` 是否存在明显错配\n- `deepseek-reasoner` 的参数兼容规则是否已处理\n\n如果已经配置了真实密钥，还可以继续执行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这会实际发起一次最小模型请求，用来验证当前 API 是否真的能被本项目正常调用。\n\n### 5. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/api/compatibility`：模型接入兼容检查\n- `/api/knowledge/search?q=关键词`：本地知识库检索\n- `/api/knowledge/documents`：列出或写入知识文档\n- `/api/session/{session_id}`：最近会话历史\n- `/api/feedback`：提交回复反馈\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n- `/project-docs/api-reference.md`：接口参考\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n当前演示模式也不是只有固定一句模板，而是会结合：\n\n- 最近会话记录\n- 本地知识库片段\n- 风险检测规则\n\n### 一键脚本是不是代表不用 API Key？\n\n不是。一键脚本只是把 `.env` 写成对应模型的推荐配置。\n\n- OpenAI 预设仍然需要 `OPENAI_API_KEY`\n- DeepSeek 预设仍然需要 `DEEPSEEK_API_KEY`\n\n如果 Key 留空，项目会自动回退到本地演示模式，所以页面仍然能返回内容，但那不是线上模型真实回复。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n先检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n再检查当前模型是不是在读取正确的密钥变量。现在项目会优先按 `MODEL_API_KEY_ENV` 读取密钥，而不是只看有没有任意一个 Key。最稳的方式是直接运行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n### 为什么明明填了 `OPENAI_API_KEY`，切到 DeepSeek 还是可能失败？\n\n因为 DeepSeek 默认应读取 `DEEPSEEK_API_KEY`，而不是只要有任意一个 Key 就算配置完成。\n\n当前项目已经补上了这层判断：\n\n- 切到 OpenAI 时，会优先读取 `OPENAI_API_KEY`\n- 切到 DeepSeek 时，会优先读取 `DEEPSEEK_API_KEY`\n- 如果你接的是其他 OpenAI 兼容供应商，可以手动设置 `MODEL_API_KEY_ENV`\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n如果你现在接的是钉钉企业内部应用，那么它通常只对对应组织内成员可用，不能像 Web 页面那样直接公开给任何人访问。\n\n### 本地对话记录存在哪里？\n\n默认会保存在仓库下的 `data/zhiyuxing.db`。如果你想切到其他路径，可以在 `.env` 里设置 `CHAT_DB_PATH`。\n\n### 能不能把自己的知识文档接进来？\n\n可以。现在项目支持通过 `POST /api/knowledge/documents` 写入自定义知识文档，写入目录默认是 `data/knowledge_uploads`，也可以通过 `KNOWLEDGE_UPLOAD_DIR` 改掉。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY_ENV` 和对应密钥，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "344df4a9f8f4952192e584faf7709304d7646bde": {"t": 1785764986.915656, "n": 4526, "h": "01b6c25df24f8288", "c": "# 使用说明\n\n[中文](usage-guide.md) | [English](usage-guide.en.md)\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 会结合本地知识库、会话记忆和风险规则生成演示回复\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置与当前模型匹配的密钥变量\n- 支持 `OPENAI_API_KEY`\n- 也支持 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`、`MODEL_API_KEY_ENV`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_API_KEY_ENV` | 当前模型优先读取哪个密钥变量，例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n| `CHAT_DB_PATH` | 本地 SQLite 会话库路径，默认写入 `data/zhiyuxing.db` | 否 |\n| `KNOWLEDGE_UPLOAD_DIR` | 自定义知识文档写入目录，默认写入 `data/knowledge_uploads` | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型\n\n优先推荐直接运行一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。\n\n这些脚本会自动：\n\n- 初始化 `.env`\n- 写入当前模型所需的 `OPENAI_BASE_URL`\n- 写入 `MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`\n- 尽量保留现有密钥和其他环境变量\n\n这几个脚本不是免 Key 调用，只是把模型接入配置一次写好：\n\n- `.\\setup-openai.ps1`：真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n\n如果你没有填写对应 Key，项目也不会坏掉，只是会继续运行在本地演示模式。\n\n### 3. 手动配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 4. 启动前检查\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n它会检查：\n\n- 当前模型会读取哪个 API Key\n- 当前 `.env` 是否真的能进入真实模型调用模式\n- 当前 `OPENAI_BASE_URL` 和 `MODEL_NAME` 是否存在明显错配\n- `deepseek-reasoner` 的参数兼容规则是否已处理\n\n如果已经配置了真实密钥，还可以继续执行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这会实际发起一次最小模型请求，用来验证当前 API 是否真的能被本项目正常调用。\n\n### 5. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/api/compatibility`：模型接入兼容检查\n- `/api/knowledge/search?q=关键词`：本地知识库检索\n- `/api/knowledge/documents`：列出或写入知识文档\n- `/api/session/{session_id}`：最近会话历史\n- `/api/feedback`：提交回复反馈\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n- `/project-docs/api-reference.md`：接口参考\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n当前演示模式也不是只有固定一句模板，而是会结合：\n\n- 最近会话记录\n- 本地知识库片段\n- 风险检测规则\n\n### 一键脚本是不是代表不用 API Key？\n\n不是。一键脚本只是把 `.env` 写成对应模型的推荐配置。\n\n- OpenAI 预设仍然需要 `OPENAI_API_KEY`\n- DeepSeek 预设仍然需要 `DEEPSEEK_API_KEY`\n\n如果 Key 留空，项目会自动回退到本地演示模式，所以页面仍然能返回内容，但那不是线上模型真实回复。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n先检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n再检查当前模型是不是在读取正确的密钥变量。现在项目会优先按 `MODEL_API_KEY_ENV` 读取密钥，而不是只看有没有任意一个 Key。最稳的方式是直接运行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n### 为什么明明填了 `OPENAI_API_KEY`，切到 DeepSeek 还是可能失败？\n\n因为 DeepSeek 默认应读取 `DEEPSEEK_API_KEY`，而不是只要有任意一个 Key 就算配置完成。\n\n当前项目已经补上了这层判断：\n\n- 切到 OpenAI 时，会优先读取 `OPENAI_API_KEY`\n- 切到 DeepSeek 时，会优先读取 `DEEPSEEK_API_KEY`\n- 如果你接的是其他 OpenAI 兼容供应商，可以手动设置 `MODEL_API_KEY_ENV`\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n如果你现在接的是钉钉企业内部应用，那么它通常只对对应组织内成员可用，不能像 Web 页面那样直接公开给任何人访问。\n\n### 本地对话记录存在哪里？\n\n默认会保存在仓库下的 `data/zhiyuxing.db`。如果你想切到其他路径，可以在 `.env` 里设置 `CHAT_DB_PATH`。\n\n### 能不能把自己的知识文档接进来？\n\n可以。现在项目支持通过 `POST /api/knowledge/documents` 写入自定义知识文档，写入目录默认是 `data/knowledge_uploads`，也可以通过 `KNOWLEDGE_UPLOAD_DIR` 改掉。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY_ENV` 和对应密钥，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "3b58546acbb22d10fe2d101b2b45769d8de787d1": {"t": 1785764988.1784043, "n": 4467, "h": "9f9d39f8814694aa", "c": "# 使用说明\n\n[中文](usage-guide.md) | [English](usage-guide.en.md)\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 会结合本地知识库、会话记忆和风险规则生成演示回复\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置与当前模型匹配的密钥变量\n- 支持 `OPENAI_API_KEY`\n- 也支持 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`、`MODEL_API_KEY_ENV`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_API_KEY_ENV` | 当前模型优先读取哪个密钥变量，例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n| `CHAT_DB_PATH` | 本地 SQLite 会话库路径，默认写入 `data/zhiyuxing.db` | 否 |\n| `KNOWLEDGE_UPLOAD_DIR` | 自定义知识文档写入目录，默认写入 `data/knowledge_uploads` | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型\n\n优先推荐直接运行一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。\n\n这些脚本会自动：\n\n- 初始化 `.env`\n- 写入当前模型所需的 `OPENAI_BASE_URL`\n- 写入 `MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`\n- 尽量保留现有密钥和其他环境变量\n\n这几个脚本不是免 Key 调用，只是把模型接入配置一次写好：\n\n- `.\\setup-openai.ps1`：真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n\n如果你没有填写对应 Key，项目也不会坏掉，只是会继续运行在本地演示模式。\n\n### 3. 手动配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 4. 启动前检查\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n它会检查：\n\n- 当前模型会读取哪个 API Key\n- 当前 `.env` 是否真的能进入真实模型调用模式\n- 当前 `OPENAI_BASE_URL` 和 `MODEL_NAME` 是否存在明显错配\n- `deepseek-reasoner` 的参数兼容规则是否已处理\n\n如果已经配置了真实密钥，还可以继续执行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这会实际发起一次最小模型请求，用来验证当前 API 是否真的能被本项目正常调用。\n\n### 5. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/api/compatibility`：模型接入兼容检查\n- `/api/knowledge/search?q=关键词`：本地知识库检索\n- `/api/knowledge/documents`：列出或写入知识文档\n- `/api/session/{session_id}`：最近会话历史\n- `/api/feedback`：提交回复反馈\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n- `/project-docs/api-reference.md`：接口参考\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n当前演示模式也不是只有固定一句模板，而是会结合：\n\n- 最近会话记录\n- 本地知识库片段\n- 风险检测规则\n\n### 一键脚本是不是代表不用 API Key？\n\n不是。一键脚本只是把 `.env` 写成对应模型的推荐配置。\n\n- OpenAI 预设仍然需要 `OPENAI_API_KEY`\n- DeepSeek 预设仍然需要 `DEEPSEEK_API_KEY`\n\n如果 Key 留空，项目会自动回退到本地演示模式，所以页面仍然能返回内容，但那不是线上模型真实回复。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n先检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n再检查当前模型是不是在读取正确的密钥变量。现在项目会优先按 `MODEL_API_KEY_ENV` 读取密钥，而不是只看有没有任意一个 Key。最稳的方式是直接运行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n### 为什么明明填了 `OPENAI_API_KEY`，切到 DeepSeek 还是可能失败？\n\n因为 DeepSeek 默认应读取 `DEEPSEEK_API_KEY`，而不是只要有任意一个 Key 就算配置完成。\n\n当前项目已经补上了这层判断：\n\n- 切到 OpenAI 时，会优先读取 `OPENAI_API_KEY`\n- 切到 DeepSeek 时，会优先读取 `DEEPSEEK_API_KEY`\n- 如果你接的是其他 OpenAI 兼容供应商，可以手动设置 `MODEL_API_KEY_ENV`\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n### 本地对话记录存在哪里？\n\n默认会保存在仓库下的 `data/zhiyuxing.db`。如果你想切到其他路径，可以在 `.env` 里设置 `CHAT_DB_PATH`。\n\n### 能不能把自己的知识文档接进来？\n\n可以。现在项目支持通过 `POST /api/knowledge/documents` 写入自定义知识文档，写入目录默认是 `data/knowledge_uploads`，也可以通过 `KNOWLEDGE_UPLOAD_DIR` 改掉。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY_ENV` 和对应密钥，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "43dcef3be7aa070bd63ed0f188b2280dd4867fc2": {"t": 1785764990.1073308, "n": 4171, "h": "679cfe80cbb1dfde", "c": "# 使用说明\n\n[中文](usage-guide.md) | [English](usage-guide.en.md)\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 会结合本地知识库、会话记忆和风险规则生成演示回复\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置与当前模型匹配的密钥变量\n- 支持 `OPENAI_API_KEY`\n- 也支持 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`、`MODEL_API_KEY_ENV`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_API_KEY_ENV` | 当前模型优先读取哪个密钥变量，例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n| `CHAT_DB_PATH` | 本地 SQLite 会话库路径，默认写入 `data/zhiyuxing.db` | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型\n\n优先推荐直接运行一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。\n\n这些脚本会自动：\n\n- 初始化 `.env`\n- 写入当前模型所需的 `OPENAI_BASE_URL`\n- 写入 `MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`\n- 尽量保留现有密钥和其他环境变量\n\n这几个脚本不是免 Key 调用，只是把模型接入配置一次写好：\n\n- `.\\setup-openai.ps1`：真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n\n如果你没有填写对应 Key，项目也不会坏掉，只是会继续运行在本地演示模式。\n\n### 3. 手动配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 4. 启动前检查\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n它会检查：\n\n- 当前模型会读取哪个 API Key\n- 当前 `.env` 是否真的能进入真实模型调用模式\n- 当前 `OPENAI_BASE_URL` 和 `MODEL_NAME` 是否存在明显错配\n- `deepseek-reasoner` 的参数兼容规则是否已处理\n\n如果已经配置了真实密钥，还可以继续执行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这会实际发起一次最小模型请求，用来验证当前 API 是否真的能被本项目正常调用。\n\n### 5. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/api/compatibility`：模型接入兼容检查\n- `/api/knowledge/search?q=关键词`：本地知识库检索\n- `/api/session/{session_id}`：最近会话历史\n- `/api/feedback`：提交回复反馈\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n当前演示模式也不是只有固定一句模板，而是会结合：\n\n- 最近会话记录\n- 本地知识库片段\n- 风险检测规则\n\n### 一键脚本是不是代表不用 API Key？\n\n不是。一键脚本只是把 `.env` 写成对应模型的推荐配置。\n\n- OpenAI 预设仍然需要 `OPENAI_API_KEY`\n- DeepSeek 预设仍然需要 `DEEPSEEK_API_KEY`\n\n如果 Key 留空，项目会自动回退到本地演示模式，所以页面仍然能返回内容，但那不是线上模型真实回复。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n先检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n再检查当前模型是不是在读取正确的密钥变量。现在项目会优先按 `MODEL_API_KEY_ENV` 读取密钥，而不是只看有没有任意一个 Key。最稳的方式是直接运行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n### 为什么明明填了 `OPENAI_API_KEY`，切到 DeepSeek 还是可能失败？\n\n因为 DeepSeek 默认应读取 `DEEPSEEK_API_KEY`，而不是只要有任意一个 Key 就算配置完成。\n\n当前项目已经补上了这层判断：\n\n- 切到 OpenAI 时，会优先读取 `OPENAI_API_KEY`\n- 切到 DeepSeek 时，会优先读取 `DEEPSEEK_API_KEY`\n- 如果你接的是其他 OpenAI 兼容供应商，可以手动设置 `MODEL_API_KEY_ENV`\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n### 本地对话记录存在哪里？\n\n默认会保存在仓库下的 `data/zhiyuxing.db`。如果你想切到其他路径，可以在 `.env` 里设置 `CHAT_DB_PATH`。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY_ENV` 和对应密钥，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "e8987d60b75a119016a27b8ae44ea149466b0017": {"t": 1785764991.5976212, "n": 3830, "h": "f05756a5402553d0", "c": "# 使用说明\n\n[中文](usage-guide.md) | [English](usage-guide.en.md)\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置与当前模型匹配的密钥变量\n- 支持 `OPENAI_API_KEY`\n- 也支持 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`、`MODEL_API_KEY_ENV`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_API_KEY_ENV` | 当前模型优先读取哪个密钥变量，例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型\n\n优先推荐直接运行一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。\n\n这些脚本会自动：\n\n- 初始化 `.env`\n- 写入当前模型所需的 `OPENAI_BASE_URL`\n- 写入 `MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`\n- 尽量保留现有密钥和其他环境变量\n\n这几个脚本不是免 Key 调用，只是把模型接入配置一次写好：\n\n- `.\\setup-openai.ps1`：真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n\n如果你没有填写对应 Key，项目也不会坏掉，只是会继续运行在本地演示模式。\n\n### 3. 手动配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 4. 启动前检查\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n它会检查：\n\n- 当前模型会读取哪个 API Key\n- 当前 `.env` 是否真的能进入真实模型调用模式\n- 当前 `OPENAI_BASE_URL` 和 `MODEL_NAME` 是否存在明显错配\n- `deepseek-reasoner` 的参数兼容规则是否已处理\n\n如果已经配置了真实密钥，还可以继续执行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这会实际发起一次最小模型请求，用来验证当前 API 是否真的能被本项目正常调用。\n\n### 5. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/api/compatibility`：模型接入兼容检查\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n### 一键脚本是不是代表不用 API Key？\n\n不是。一键脚本只是把 `.env` 写成对应模型的推荐配置。\n\n- OpenAI 预设仍然需要 `OPENAI_API_KEY`\n- DeepSeek 预设仍然需要 `DEEPSEEK_API_KEY`\n\n如果 Key 留空，项目会自动回退到本地演示模式，所以页面仍然能返回内容，但那不是线上模型真实回复。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n先检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n再检查当前模型是不是在读取正确的密钥变量。现在项目会优先按 `MODEL_API_KEY_ENV` 读取密钥，而不是只看有没有任意一个 Key。最稳的方式是直接运行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n### 为什么明明填了 `OPENAI_API_KEY`，切到 DeepSeek 还是可能失败？\n\n因为 DeepSeek 默认应读取 `DEEPSEEK_API_KEY`，而不是只要有任意一个 Key 就算配置完成。\n\n当前项目已经补上了这层判断：\n\n- 切到 OpenAI 时，会优先读取 `OPENAI_API_KEY`\n- 切到 DeepSeek 时，会优先读取 `DEEPSEEK_API_KEY`\n- 如果你接的是其他 OpenAI 兼容供应商，可以手动设置 `MODEL_API_KEY_ENV`\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY_ENV` 和对应密钥，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "d54f5f0e02a91ae009654cb4e4e191e28117f192": {"t": 1785764993.0086684, "n": 3777, "h": "f4aa55f6e6855f75", "c": "# 使用说明\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置与当前模型匹配的密钥变量\n- 支持 `OPENAI_API_KEY`\n- 也支持 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`、`MODEL_API_KEY_ENV`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_API_KEY_ENV` | 当前模型优先读取哪个密钥变量，例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型\n\n优先推荐直接运行一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。\n\n这些脚本会自动：\n\n- 初始化 `.env`\n- 写入当前模型所需的 `OPENAI_BASE_URL`\n- 写入 `MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`\n- 尽量保留现有密钥和其他环境变量\n\n这几个脚本不是免 Key 调用，只是把模型接入配置一次写好：\n\n- `.\\setup-openai.ps1`：真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1`：真实调用需要 `DEEPSEEK_API_KEY`\n\n如果你没有填写对应 Key，项目也不会坏掉，只是会继续运行在本地演示模式。\n\n### 3. 手动配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 4. 启动前检查\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n它会检查：\n\n- 当前模型会读取哪个 API Key\n- 当前 `.env` 是否真的能进入真实模型调用模式\n- 当前 `OPENAI_BASE_URL` 和 `MODEL_NAME` 是否存在明显错配\n- `deepseek-reasoner` 的参数兼容规则是否已处理\n\n如果已经配置了真实密钥，还可以继续执行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这会实际发起一次最小模型请求，用来验证当前 API 是否真的能被本项目正常调用。\n\n### 5. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/api/compatibility`：模型接入兼容检查\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n### 一键脚本是不是代表不用 API Key？\n\n不是。一键脚本只是把 `.env` 写成对应模型的推荐配置。\n\n- OpenAI 预设仍然需要 `OPENAI_API_KEY`\n- DeepSeek 预设仍然需要 `DEEPSEEK_API_KEY`\n\n如果 Key 留空，项目会自动回退到本地演示模式，所以页面仍然能返回内容，但那不是线上模型真实回复。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n先检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n再检查当前模型是不是在读取正确的密钥变量。现在项目会优先按 `MODEL_API_KEY_ENV` 读取密钥，而不是只看有没有任意一个 Key。最稳的方式是直接运行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n### 为什么明明填了 `OPENAI_API_KEY`，切到 DeepSeek 还是可能失败？\n\n因为 DeepSeek 默认应读取 `DEEPSEEK_API_KEY`，而不是只要有任意一个 Key 就算配置完成。\n\n当前项目已经补上了这层判断：\n\n- 切到 OpenAI 时，会优先读取 `OPENAI_API_KEY`\n- 切到 DeepSeek 时，会优先读取 `DEEPSEEK_API_KEY`\n- 如果你接的是其他 OpenAI 兼容供应商，可以手动设置 `MODEL_API_KEY_ENV`\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY_ENV` 和对应密钥，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "ce631a17aaaf82181757cfd3a6f988ae2e52abcc": {"t": 1785764994.329259, "n": 3367, "h": "5480f428f471debd", "c": "# 使用说明\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置与当前模型匹配的密钥变量\n- 支持 `OPENAI_API_KEY`\n- 也支持 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`、`MODEL_API_KEY_ENV`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_API_KEY_ENV` | 当前模型优先读取哪个密钥变量，例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型\n\n优先推荐直接运行一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。\n\n这些脚本会自动：\n\n- 初始化 `.env`\n- 写入当前模型所需的 `OPENAI_BASE_URL`\n- 写入 `MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`\n- 尽量保留现有密钥和其他环境变量\n\n### 3. 手动配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 4. 启动前检查\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n它会检查：\n\n- 当前模型会读取哪个 API Key\n- 当前 `.env` 是否真的能进入真实模型调用模式\n- 当前 `OPENAI_BASE_URL` 和 `MODEL_NAME` 是否存在明显错配\n- `deepseek-reasoner` 的参数兼容规则是否已处理\n\n如果已经配置了真实密钥，还可以继续执行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这会实际发起一次最小模型请求，用来验证当前 API 是否真的能被本项目正常调用。\n\n### 5. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/api/compatibility`：模型接入兼容检查\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n先检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n再检查当前模型是不是在读取正确的密钥变量。现在项目会优先按 `MODEL_API_KEY_ENV` 读取密钥，而不是只看有没有任意一个 Key。最稳的方式是直接运行：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n### 为什么明明填了 `OPENAI_API_KEY`，切到 DeepSeek 还是可能失败？\n\n因为 DeepSeek 默认应读取 `DEEPSEEK_API_KEY`，而不是只要有任意一个 Key 就算配置完成。\n\n当前项目已经补上了这层判断：\n\n- 切到 OpenAI 时，会优先读取 `OPENAI_API_KEY`\n- 切到 DeepSeek 时，会优先读取 `DEEPSEEK_API_KEY`\n- 如果你接的是其他 OpenAI 兼容供应商，可以手动设置 `MODEL_API_KEY_ENV`\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY_ENV` 和对应密钥，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "420134e583cb6a02b515fad542efc15411c78ccf": {"t": 1785764995.6247232, "n": 2136, "h": "7ceaf9c7f7770ce2", "c": "# 使用说明\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置 `OPENAI_API_KEY`\n- 也支持配置 `DEEPSEEK_API_KEY`\n- 可选配置 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `DEEPSEEK_API_KEY` | DeepSeek 密钥，未设置 `OPENAI_API_KEY` 时会回退使用 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `MODEL_PROVIDER` | 页面展示用的提供商名称，例如 `OpenAI` / `DeepSeek` | 否 |\n| `MODEL_TEMPERATURE` | 温度参数 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/docs`：Swagger 文档\n- `/project-docs/model-integration.md`：不同模型接入说明\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n\n### 如何接入 DeepSeek R1 这类不同模型？\n\n项目使用的是 OpenAI 兼容接口方式。只要修改 `.env` 中的 `OPENAI_BASE_URL`、`MODEL_NAME` 和密钥配置，就可以切换不同模型提供商。详细示例见：\n\n- [model-integration.md](model-integration.md)\n"}, "d55a58f4bc5f6a6b21368bee3ad465e5d1543926": {"t": 1785764996.8780298, "n": 1706, "h": "2f4b183b4e676d1f", "c": "# 使用说明\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置 `OPENAI_API_KEY`\n- 可选配置 `OPENAI_BASE_URL` 和 `MODEL_NAME`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果系统环境里缺少依赖，优先使用仓库虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者双击根目录的 `start-web.bat`。\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/docs`：Swagger 文档\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 为什么运行 `python -m uvicorn app:app --reload` 会报错？\n\n如果报错类似 `No module named uvicorn`，说明你用的是系统 Python，而不是项目虚拟环境。请改用：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n或者直接运行 `start-web.ps1` / `start-web.bat`。\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n"}, "4664b04ffbb37b67021899c06388c391dd338e29": {"t": 1785764998.3254688, "n": 1308, "h": "2f84c42ded09f309", "c": "# 使用说明\n\n这份文档用于说明项目的运行方式、环境变量和常见问题，方便直接启动和继续开发。\n\n## 运行模式\n\n### 1. 本地演示模式\n\n- 默认可用\n- 不要求配置 `OPENAI_API_KEY`\n- `/chat` 会返回内置的支持性建议\n- 适合先验证页面、接口和整体流程\n\n### 2. 模型调用模式\n\n- 需要配置 `OPENAI_API_KEY`\n- 可选配置 `OPENAI_BASE_URL` 和 `MODEL_NAME`\n- `/chat` 会调用 OpenAI 兼容接口返回模型回复\n- 适合继续验证真实模型能力\n\n## 环境变量\n\n可参考仓库根目录的 `.env.example`。\n\n| 变量名 | 说明 | 是否必填 |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | OpenAI 兼容接口密钥，留空时自动进入本地演示模式 | 否 |\n| `OPENAI_BASE_URL` | OpenAI 兼容接口地址 | 否 |\n| `MODEL_NAME` | 调用的模型名称 | 否 |\n| `DEMO_MODE` | 设置为 `true` 时强制使用本地演示模式 | 否 |\n\n## 本地启动\n\n### 1. 创建虚拟环境并安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n## 常用地址\n\n- `/`：Web 页面入口\n- `/chat`：对话接口\n- `/health`：健康检查\n- `/api/meta`：服务元信息与当前运行模式\n- `/docs`：Swagger 文档\n- `/project-docs/dingtalk-integration.md`：钉钉接入说明\n\n## 常见问题\n\n### 为什么没配 API Key 也能返回结果？\n\n因为项目默认支持本地演示模式。这样仓库拿下来后可以直接跑通流程，不会因为缺少密钥导致页面不可用。\n\n### 为什么配置了 API Key 还是走本地演示模式？\n\n检查 `.env` 中的 `DEMO_MODE` 是否被设置为 `true`。如果是，系统会优先使用本地演示模式。\n\n### 为什么系统环境里跑 `python -m pytest` 失败？\n\n通常是因为全局 Python 没安装测试依赖。优先使用仓库虚拟环境中的解释器，例如：\n\n```bash\n.\\.venv\\Scripts\\python -m pytest -q\n```\n\n### 钉钉是不是必须项？\n\n不是。当前项目可以作为独立 Web 服务运行，钉钉是可选的接入场景。\n"}}, "README.md": {"ae16815c4abd513e54177647e0738b109a8a5ee5": {"t": 1785746503.1947422, "n": 10723, "h": "f4e6ed056dfaa5c5", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/latest)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `下载发布包`：[Latest Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/latest)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n- `API 参考`：[docs/api-reference.md](docs/api-reference.md)\n- `受限公开后端`：[docs/public-demo.md](docs/public-demo.md)\n- `启动排障`：[docs/troubleshooting.md](docs/troubleshooting.md)\n- `Release 安装`：[docs/release-install.md](docs/release-install.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个可临时公开访问的受限后端，而不是只能在本机自测\n- 一个支持 OpenAI / DeepSeek 接入、知识检索、会话记忆和兼容性检查的工程化仓库\n\n说明：\nGitHub Pages 上的在线 Demo 主要用于公开展示页面和交互流程；完整的知识库检索、会话持久化、反馈记录和真实模型调用，需要按下文步骤本地启动后端。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `本地知识库检索`：根据问题检索内置心理支持与学习建议文档片段，增强回复内容。\n- `自定义知识文档接入`：可通过 API 把自定义 Markdown / 文本写入知识库，形成更像 RAG 项目的可扩展入口。\n- `会话记忆与持久化`：自动记录最近对话，支持继续追问、查看历史和本地 SQLite 持久化。\n- `风险识别与转介兜底`：遇到高风险表达时优先切换固定安全回复，而不是继续普通对话。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `受限公开后端体验`：可一键启动临时公网隧道，让他人直接访问真实后端接口进行体验。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 工程结构\n\n```text\nbackend/\n api/ # 路由层\n app_factory.py # FastAPI 应用装配\n chat_logic.py # 提示词、风格和 Demo 回复逻辑\n chat_service.py # 完整对话流程\n config.py # 运行配置\n runtime.py # 模型解析与兼容性检查\n schemas.py # 请求/响应模型\nservices/\n knowledge.py # 知识检索与自定义文档写入\n safety.py # 风险检测\n storage.py # SQLite 会话持久化\nstatic/ # Web 前端\ntests/ # 回归测试\n api/ # API 路由与集成测试\n services/ # chat / runtime / safety / knowledge / storage 单元测试\n conftest.py # 统一测试夹具\n```\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- SQLite\n- Markdown Knowledge Base\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### Release 压缩包安装\n\n如果你不想 clone 仓库，也不想手动配 Git，最省事的方式是直接下载 Release 压缩包：\n\n- [Latest Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/latest)\n\n优先下载：\n\n- `zhiyuxing-ai-assistant-release-v*.zip`\n\n这类压缩包里会额外包含：\n\n- `start-web.bat`\n- `doctor.bat`\n- `INSTALL.txt`\n\n完整说明见：[docs/release-install.md](docs/release-install.md)\n\n### 最简单启动方式\n\n如果你是刚 clone 下来，先进入项目根目录：\n\n```powershell\ncd zhiyuxing-ai-assistant\n```\n\n如果你只是想先把 Web 版跑起来，不想手动配虚拟环境，直接在项目根目录运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者直接双击：\n\n```text\nstart-web.bat\n```\n\n首次运行时，脚本会自动：\n\n- 创建 `.venv`\n- 安装项目依赖\n- 自动复制 `.env`\n- 检查当前模型接入配置\n- 启动 Web 服务\n\n如果别人第一次运行失败，先不要手动折腾环境，直接运行：\n\n```powershell\n.\\doctor.ps1\n```\n\n或双击：\n\n```text\ndoctor.bat\n```\n\n这个脚本会自动检查：\n\n- 是否在项目根目录\n- Python 是否安装\n- `.venv` 和依赖是否能自动补齐\n- `8000` 端口是否被占用\n- 当前模型配置是否只能走 demo mode\n\n要跑测试也不需要自己记命令，直接运行：\n\n```powershell\ncd zhiyuxing-ai-assistant\n.\\run-tests.ps1\n```\n\n或双击：\n\n```text\nrun-tests.bat\n```\n\n### 1. 手动安装依赖（进阶）\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n- `CHAT_DB_PATH`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n如果你想把“真实后端”临时分享给老师、同学或面试官，也可以启动受限公开演示：\n\n```powershell\n.\\start-public-demo.ps1\n```\n\n这个脚本会自动启动一个专用后端并建立临时公网隧道，终端里会打印一个可直接访问的公开 URL。需要注意：\n\n- 它会强制启用 `PUBLIC_DEMO_MODE=true`\n- `/chat`、`/api/meta`、`/docs` 等读接口可访问\n- `/api/knowledge/documents` 与 `/api/feedback` 等写接口会被禁止\n- 它只适合公开演示，不会发起真实模型调用\n- 链接只在你的电脑和脚本持续运行时有效\n\n更完整说明见：[docs/public-demo.md](docs/public-demo.md)\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/api/knowledge/search?q=失眠`\n- `http://127.0.0.1:8000/api/session/<session_id>`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n更推荐直接使用仓库脚本，这样不会误用系统 Python：\n\n```powershell\n.\\run-tests.ps1\n```\n\n当前测试已经按子系统拆分，不再集中在单个文件里：\n\n- `tests/api/test_api.py`\n- `tests/services/test_chat_logic.py`\n- `tests/services/test_runtime.py`\n- `tests/services/test_knowledge.py`\n- `tests/services/test_safety.py`\n- `tests/services/test_storage.py`\n\n如果只想针对某个层级回归，也可以这样运行：\n\n```bash\npython -m pytest tests/api tests/services -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /api/knowledge/search`：本地知识库检索\n- `GET /api/knowledge/documents`：列出当前知识文档\n- `POST /api/knowledge/documents`：写入自定义知识文档\n- `GET /api/session/{session_id}`：最近会话记录\n- `POST /api/feedback`：对回复提交有帮助 / 需要更具体的反馈\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成，并结合了最近会话与知识库片段。\",\n \"mode\": \"openai\",\n \"session_id\": \"sess_xxxxxxxxxxxx\",\n \"assistant_message_id\": 12,\n \"memory_messages_used\": 2,\n \"knowledge_hits\": [\n {\n \"title\": \"考试压力与恢复\",\n \"excerpt\": \"当考试焦虑已经影响睡眠时，建议同时安排线下支持和短时复习块。\",\n \"source_path\": \"knowledge_base/04-sleep-and-recovery.md\",\n \"score\": 3.8\n }\n ],\n \"safety\": {\n \"level\": \"medium\",\n \"label\": \"需要额外关注\",\n \"note\": \"检测到持续失眠、崩溃或明显耗竭相关表达，建议尽快联系线下支持资源。\",\n \"needs_human_support\": true,\n \"matched_keywords\": [\"失眠\"]\n }\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/api-reference.md](docs/api-reference.md)、\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/api-reference.en.md](docs/api-reference.en.md)、\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 将本地知识库扩展到更多高校场景\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果当前接的是钉钉`企业内部应用`，通常只有该组织内成员才能在钉钉里使用，往往还需要管理员授权。\n- 这意味着别人一般不能“直接打开你的钉钉版就用”，除非他加入该组织，或你把应用做成多组织分发 / 第三方应用。\n- 如果目标是让任何人都能直接体验，这个项目应以 Web 版为主入口，而不是把钉钉端当成唯一入口。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "2cda69c30bcdbe7da1d9a85c26212da942394801": {"t": 1785764988.896954, "n": 10326, "h": "d66b7e75d956f9f5", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `查看版本`：[v0.1.0 Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n- `API 参考`：[docs/api-reference.md](docs/api-reference.md)\n- `受限公开后端`：[docs/public-demo.md](docs/public-demo.md)\n- `启动排障`：[docs/troubleshooting.md](docs/troubleshooting.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个可临时公开访问的受限后端，而不是只能在本机自测\n- 一个支持 OpenAI / DeepSeek 接入、知识检索、会话记忆和兼容性检查的工程化仓库\n\n说明：\nGitHub Pages 上的在线 Demo 主要用于公开展示页面和交互流程；完整的知识库检索、会话持久化、反馈记录和真实模型调用，需要按下文步骤本地启动后端。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `本地知识库检索`：根据问题检索内置心理支持与学习建议文档片段，增强回复内容。\n- `自定义知识文档接入`：可通过 API 把自定义 Markdown / 文本写入知识库，形成更像 RAG 项目的可扩展入口。\n- `会话记忆与持久化`：自动记录最近对话，支持继续追问、查看历史和本地 SQLite 持久化。\n- `风险识别与转介兜底`：遇到高风险表达时优先切换固定安全回复，而不是继续普通对话。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `受限公开后端体验`：可一键启动临时公网隧道，让他人直接访问真实后端接口进行体验。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 工程结构\n\n```text\nbackend/\n api/ # 路由层\n app_factory.py # FastAPI 应用装配\n chat_logic.py # 提示词、风格和 Demo 回复逻辑\n chat_service.py # 完整对话流程\n config.py # 运行配置\n runtime.py # 模型解析与兼容性检查\n schemas.py # 请求/响应模型\nservices/\n knowledge.py # 知识检索与自定义文档写入\n safety.py # 风险检测\n storage.py # SQLite 会话持久化\nstatic/ # Web 前端\ntests/ # 回归测试\n api/ # API 路由与集成测试\n services/ # chat / runtime / safety / knowledge / storage 单元测试\n conftest.py # 统一测试夹具\n```\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- SQLite\n- Markdown Knowledge Base\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 最简单启动方式\n\n如果你是刚 clone 下来，先进入项目根目录：\n\n```powershell\ncd zhiyuxing-ai-assistant\n```\n\n如果你只是想先把 Web 版跑起来，不想手动配虚拟环境，直接在项目根目录运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者直接双击：\n\n```text\nstart-web.bat\n```\n\n首次运行时，脚本会自动：\n\n- 创建 `.venv`\n- 安装项目依赖\n- 自动复制 `.env`\n- 检查当前模型接入配置\n- 启动 Web 服务\n\n如果别人第一次运行失败，先不要手动折腾环境，直接运行：\n\n```powershell\n.\\doctor.ps1\n```\n\n或双击：\n\n```text\ndoctor.bat\n```\n\n这个脚本会自动检查：\n\n- 是否在项目根目录\n- Python 是否安装\n- `.venv` 和依赖是否能自动补齐\n- `8000` 端口是否被占用\n- 当前模型配置是否只能走 demo mode\n\n要跑测试也不需要自己记命令，直接运行：\n\n```powershell\ncd zhiyuxing-ai-assistant\n.\\run-tests.ps1\n```\n\n或双击：\n\n```text\nrun-tests.bat\n```\n\n### 1. 手动安装依赖（进阶）\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n- `CHAT_DB_PATH`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n如果你想把“真实后端”临时分享给老师、同学或面试官，也可以启动受限公开演示：\n\n```powershell\n.\\start-public-demo.ps1\n```\n\n这个脚本会自动启动一个专用后端并建立临时公网隧道，终端里会打印一个可直接访问的公开 URL。需要注意：\n\n- 它会强制启用 `PUBLIC_DEMO_MODE=true`\n- `/chat`、`/api/meta`、`/docs` 等读接口可访问\n- `/api/knowledge/documents` 与 `/api/feedback` 等写接口会被禁止\n- 它只适合公开演示，不会发起真实模型调用\n- 链接只在你的电脑和脚本持续运行时有效\n\n更完整说明见：[docs/public-demo.md](docs/public-demo.md)\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/api/knowledge/search?q=失眠`\n- `http://127.0.0.1:8000/api/session/<session_id>`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n更推荐直接使用仓库脚本，这样不会误用系统 Python：\n\n```powershell\n.\\run-tests.ps1\n```\n\n当前测试已经按子系统拆分，不再集中在单个文件里：\n\n- `tests/api/test_api.py`\n- `tests/services/test_chat_logic.py`\n- `tests/services/test_runtime.py`\n- `tests/services/test_knowledge.py`\n- `tests/services/test_safety.py`\n- `tests/services/test_storage.py`\n\n如果只想针对某个层级回归，也可以这样运行：\n\n```bash\npython -m pytest tests/api tests/services -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /api/knowledge/search`：本地知识库检索\n- `GET /api/knowledge/documents`：列出当前知识文档\n- `POST /api/knowledge/documents`：写入自定义知识文档\n- `GET /api/session/{session_id}`：最近会话记录\n- `POST /api/feedback`：对回复提交有帮助 / 需要更具体的反馈\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成，并结合了最近会话与知识库片段。\",\n \"mode\": \"openai\",\n \"session_id\": \"sess_xxxxxxxxxxxx\",\n \"assistant_message_id\": 12,\n \"memory_messages_used\": 2,\n \"knowledge_hits\": [\n {\n \"title\": \"考试压力与恢复\",\n \"excerpt\": \"当考试焦虑已经影响睡眠时，建议同时安排线下支持和短时复习块。\",\n \"source_path\": \"knowledge_base/04-sleep-and-recovery.md\",\n \"score\": 3.8\n }\n ],\n \"safety\": {\n \"level\": \"medium\",\n \"label\": \"需要额外关注\",\n \"note\": \"检测到持续失眠、崩溃或明显耗竭相关表达，建议尽快联系线下支持资源。\",\n \"needs_human_support\": true,\n \"matched_keywords\": [\"失眠\"]\n }\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/api-reference.md](docs/api-reference.md)、\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/api-reference.en.md](docs/api-reference.en.md)、\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 将本地知识库扩展到更多高校场景\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果当前接的是钉钉`企业内部应用`，通常只有该组织内成员才能在钉钉里使用，往往还需要管理员授权。\n- 这意味着别人一般不能“直接打开你的钉钉版就用”，除非他加入该组织，或你把应用做成多组织分发 / 第三方应用。\n- 如果目标是让任何人都能直接体验，这个项目应以 Web 版为主入口，而不是把钉钉端当成唯一入口。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "23b14c2dabc789999027e8f10032a8bcb041ab36": {"t": 1785764990.728488, "n": 10075, "h": "990ded4aa6d4de43", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `查看版本`：[v0.1.0 Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n- `API 参考`：[docs/api-reference.md](docs/api-reference.md)\n- `受限公开后端`：[docs/public-demo.md](docs/public-demo.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个可临时公开访问的受限后端，而不是只能在本机自测\n- 一个支持 OpenAI / DeepSeek 接入、知识检索、会话记忆和兼容性检查的工程化仓库\n\n说明：\nGitHub Pages 上的在线 Demo 主要用于公开展示页面和交互流程；完整的知识库检索、会话持久化、反馈记录和真实模型调用，需要按下文步骤本地启动后端。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `本地知识库检索`：根据问题检索内置心理支持与学习建议文档片段，增强回复内容。\n- `自定义知识文档接入`：可通过 API 把自定义 Markdown / 文本写入知识库，形成更像 RAG 项目的可扩展入口。\n- `会话记忆与持久化`：自动记录最近对话，支持继续追问、查看历史和本地 SQLite 持久化。\n- `风险识别与转介兜底`：遇到高风险表达时优先切换固定安全回复，而不是继续普通对话。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `受限公开后端体验`：可一键启动临时公网隧道，让他人直接访问真实后端接口进行体验。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 工程结构\n\n```text\nbackend/\n api/ # 路由层\n app_factory.py # FastAPI 应用装配\n chat_logic.py # 提示词、风格和 Demo 回复逻辑\n chat_service.py # 完整对话流程\n config.py # 运行配置\n runtime.py # 模型解析与兼容性检查\n schemas.py # 请求/响应模型\nservices/\n knowledge.py # 知识检索与自定义文档写入\n safety.py # 风险检测\n storage.py # SQLite 会话持久化\nstatic/ # Web 前端\ntests/ # 回归测试\n api/ # API 路由与集成测试\n services/ # chat / runtime / safety / knowledge / storage 单元测试\n conftest.py # 统一测试夹具\n```\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- SQLite\n- Markdown Knowledge Base\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 最简单启动方式\n\n如果你是刚 clone 下来，先进入项目根目录：\n\n```powershell\ncd zhiyuxing-ai-assistant\n```\n\n如果你只是想先把 Web 版跑起来，不想手动配虚拟环境，直接在项目根目录运行：\n\n```powershell\n.\\start-web.ps1\n```\n\n或者直接双击：\n\n```text\nstart-web.bat\n```\n\n首次运行时，脚本会自动：\n\n- 创建 `.venv`\n- 安装项目依赖\n- 自动复制 `.env`\n- 检查当前模型接入配置\n- 启动 Web 服务\n\n要跑测试也不需要自己记命令，直接运行：\n\n```powershell\ncd zhiyuxing-ai-assistant\n.\\run-tests.ps1\n```\n\n或双击：\n\n```text\nrun-tests.bat\n```\n\n### 1. 手动安装依赖（进阶）\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n- `CHAT_DB_PATH`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n如果你想把“真实后端”临时分享给老师、同学或面试官，也可以启动受限公开演示：\n\n```powershell\n.\\start-public-demo.ps1\n```\n\n这个脚本会自动启动一个专用后端并建立临时公网隧道，终端里会打印一个可直接访问的公开 URL。需要注意：\n\n- 它会强制启用 `PUBLIC_DEMO_MODE=true`\n- `/chat`、`/api/meta`、`/docs` 等读接口可访问\n- `/api/knowledge/documents` 与 `/api/feedback` 等写接口会被禁止\n- 它只适合公开演示，不会发起真实模型调用\n- 链接只在你的电脑和脚本持续运行时有效\n\n更完整说明见：[docs/public-demo.md](docs/public-demo.md)\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/api/knowledge/search?q=失眠`\n- `http://127.0.0.1:8000/api/session/<session_id>`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n更推荐直接使用仓库脚本，这样不会误用系统 Python：\n\n```powershell\n.\\run-tests.ps1\n```\n\n当前测试已经按子系统拆分，不再集中在单个文件里：\n\n- `tests/api/test_api.py`\n- `tests/services/test_chat_logic.py`\n- `tests/services/test_runtime.py`\n- `tests/services/test_knowledge.py`\n- `tests/services/test_safety.py`\n- `tests/services/test_storage.py`\n\n如果只想针对某个层级回归，也可以这样运行：\n\n```bash\npython -m pytest tests/api tests/services -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /api/knowledge/search`：本地知识库检索\n- `GET /api/knowledge/documents`：列出当前知识文档\n- `POST /api/knowledge/documents`：写入自定义知识文档\n- `GET /api/session/{session_id}`：最近会话记录\n- `POST /api/feedback`：对回复提交有帮助 / 需要更具体的反馈\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成，并结合了最近会话与知识库片段。\",\n \"mode\": \"openai\",\n \"session_id\": \"sess_xxxxxxxxxxxx\",\n \"assistant_message_id\": 12,\n \"memory_messages_used\": 2,\n \"knowledge_hits\": [\n {\n \"title\": \"考试压力与恢复\",\n \"excerpt\": \"当考试焦虑已经影响睡眠时，建议同时安排线下支持和短时复习块。\",\n \"source_path\": \"knowledge_base/04-sleep-and-recovery.md\",\n \"score\": 3.8\n }\n ],\n \"safety\": {\n \"level\": \"medium\",\n \"label\": \"需要额外关注\",\n \"note\": \"检测到持续失眠、崩溃或明显耗竭相关表达，建议尽快联系线下支持资源。\",\n \"needs_human_support\": true,\n \"matched_keywords\": [\"失眠\"]\n }\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/api-reference.md](docs/api-reference.md)、\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/api-reference.en.md](docs/api-reference.en.md)、\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 将本地知识库扩展到更多高校场景\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果当前接的是钉钉`企业内部应用`，通常只有该组织内成员才能在钉钉里使用，往往还需要管理员授权。\n- 这意味着别人一般不能“直接打开你的钉钉版就用”，除非他加入该组织，或你把应用做成多组织分发 / 第三方应用。\n- 如果目标是让任何人都能直接体验，这个项目应以 Web 版为主入口，而不是把钉钉端当成唯一入口。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "31967f3658110462b2c4944eec4dd26b8db241f0": {"t": 1785764992.4613962, "n": 9617, "h": "190b142ec9d37768", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `查看版本`：[v0.1.0 Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n- `API 参考`：[docs/api-reference.md](docs/api-reference.md)\n- `受限公开后端`：[docs/public-demo.md](docs/public-demo.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个可临时公开访问的受限后端，而不是只能在本机自测\n- 一个支持 OpenAI / DeepSeek 接入、知识检索、会话记忆和兼容性检查的工程化仓库\n\n说明：\nGitHub Pages 上的在线 Demo 主要用于公开展示页面和交互流程；完整的知识库检索、会话持久化、反馈记录和真实模型调用，需要按下文步骤本地启动后端。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `本地知识库检索`：根据问题检索内置心理支持与学习建议文档片段，增强回复内容。\n- `自定义知识文档接入`：可通过 API 把自定义 Markdown / 文本写入知识库，形成更像 RAG 项目的可扩展入口。\n- `会话记忆与持久化`：自动记录最近对话，支持继续追问、查看历史和本地 SQLite 持久化。\n- `风险识别与转介兜底`：遇到高风险表达时优先切换固定安全回复，而不是继续普通对话。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `受限公开后端体验`：可一键启动临时公网隧道，让他人直接访问真实后端接口进行体验。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 工程结构\n\n```text\nbackend/\n api/ # 路由层\n app_factory.py # FastAPI 应用装配\n chat_logic.py # 提示词、风格和 Demo 回复逻辑\n chat_service.py # 完整对话流程\n config.py # 运行配置\n runtime.py # 模型解析与兼容性检查\n schemas.py # 请求/响应模型\nservices/\n knowledge.py # 知识检索与自定义文档写入\n safety.py # 风险检测\n storage.py # SQLite 会话持久化\nstatic/ # Web 前端\ntests/ # 回归测试\n api/ # API 路由与集成测试\n services/ # chat / runtime / safety / knowledge / storage 单元测试\n conftest.py # 统一测试夹具\n```\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- SQLite\n- Markdown Knowledge Base\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n- `CHAT_DB_PATH`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n如果你想把“真实后端”临时分享给老师、同学或面试官，也可以启动受限公开演示：\n\n```powershell\n.\\start-public-demo.ps1\n```\n\n这个脚本会自动启动一个专用后端并建立临时公网隧道，终端里会打印一个可直接访问的公开 URL。需要注意：\n\n- 它会强制启用 `PUBLIC_DEMO_MODE=true`\n- `/chat`、`/api/meta`、`/docs` 等读接口可访问\n- `/api/knowledge/documents` 与 `/api/feedback` 等写接口会被禁止\n- 它只适合公开演示，不会发起真实模型调用\n- 链接只在你的电脑和脚本持续运行时有效\n\n更完整说明见：[docs/public-demo.md](docs/public-demo.md)\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/api/knowledge/search?q=失眠`\n- `http://127.0.0.1:8000/api/session/<session_id>`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n当前测试已经按子系统拆分，不再集中在单个文件里：\n\n- `tests/api/test_api.py`\n- `tests/services/test_chat_logic.py`\n- `tests/services/test_runtime.py`\n- `tests/services/test_knowledge.py`\n- `tests/services/test_safety.py`\n- `tests/services/test_storage.py`\n\n如果只想针对某个层级回归，也可以这样运行：\n\n```bash\npython -m pytest tests/api tests/services -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /api/knowledge/search`：本地知识库检索\n- `GET /api/knowledge/documents`：列出当前知识文档\n- `POST /api/knowledge/documents`：写入自定义知识文档\n- `GET /api/session/{session_id}`：最近会话记录\n- `POST /api/feedback`：对回复提交有帮助 / 需要更具体的反馈\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成，并结合了最近会话与知识库片段。\",\n \"mode\": \"openai\",\n \"session_id\": \"sess_xxxxxxxxxxxx\",\n \"assistant_message_id\": 12,\n \"memory_messages_used\": 2,\n \"knowledge_hits\": [\n {\n \"title\": \"考试压力与恢复\",\n \"excerpt\": \"当考试焦虑已经影响睡眠时，建议同时安排线下支持和短时复习块。\",\n \"source_path\": \"knowledge_base/04-sleep-and-recovery.md\",\n \"score\": 3.8\n }\n ],\n \"safety\": {\n \"level\": \"medium\",\n \"label\": \"需要额外关注\",\n \"note\": \"检测到持续失眠、崩溃或明显耗竭相关表达，建议尽快联系线下支持资源。\",\n \"needs_human_support\": true,\n \"matched_keywords\": [\"失眠\"]\n }\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/api-reference.md](docs/api-reference.md)、\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/api-reference.en.md](docs/api-reference.en.md)、\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 将本地知识库扩展到更多高校场景\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果当前接的是钉钉`企业内部应用`，通常只有该组织内成员才能在钉钉里使用，往往还需要管理员授权。\n- 这意味着别人一般不能“直接打开你的钉钉版就用”，除非他加入该组织，或你把应用做成多组织分发 / 第三方应用。\n- 如果目标是让任何人都能直接体验，这个项目应以 Web 版为主入口，而不是把钉钉端当成唯一入口。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "344df4a9f8f4952192e584faf7709304d7646bde": {"t": 1785764993.9364178, "n": 8689, "h": "a0d121a99e5290bd", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `查看版本`：[v0.1.0 Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n- `API 参考`：[docs/api-reference.md](docs/api-reference.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个支持 OpenAI / DeepSeek 接入、知识检索、会话记忆和兼容性检查的工程化仓库\n\n说明：\nGitHub Pages 上的在线 Demo 主要用于公开展示页面和交互流程；完整的知识库检索、会话持久化、反馈记录和真实模型调用，需要按下文步骤本地启动后端。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `本地知识库检索`：根据问题检索内置心理支持与学习建议文档片段，增强回复内容。\n- `自定义知识文档接入`：可通过 API 把自定义 Markdown / 文本写入知识库，形成更像 RAG 项目的可扩展入口。\n- `会话记忆与持久化`：自动记录最近对话，支持继续追问、查看历史和本地 SQLite 持久化。\n- `风险识别与转介兜底`：遇到高风险表达时优先切换固定安全回复，而不是继续普通对话。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 工程结构\n\n```text\nbackend/\n api/ # 路由层\n app_factory.py # FastAPI 应用装配\n chat_logic.py # 提示词、风格和 Demo 回复逻辑\n chat_service.py # 完整对话流程\n config.py # 运行配置\n runtime.py # 模型解析与兼容性检查\n schemas.py # 请求/响应模型\nservices/\n knowledge.py # 知识检索与自定义文档写入\n safety.py # 风险检测\n storage.py # SQLite 会话持久化\nstatic/ # Web 前端\ntests/ # 回归测试\n```\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- SQLite\n- Markdown Knowledge Base\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n- `CHAT_DB_PATH`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/api/knowledge/search?q=失眠`\n- `http://127.0.0.1:8000/api/session/<session_id>`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /api/knowledge/search`：本地知识库检索\n- `GET /api/knowledge/documents`：列出当前知识文档\n- `POST /api/knowledge/documents`：写入自定义知识文档\n- `GET /api/session/{session_id}`：最近会话记录\n- `POST /api/feedback`：对回复提交有帮助 / 需要更具体的反馈\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成，并结合了最近会话与知识库片段。\",\n \"mode\": \"openai\",\n \"session_id\": \"sess_xxxxxxxxxxxx\",\n \"assistant_message_id\": 12,\n \"memory_messages_used\": 2,\n \"knowledge_hits\": [\n {\n \"title\": \"考试压力与恢复\",\n \"excerpt\": \"当考试焦虑已经影响睡眠时，建议同时安排线下支持和短时复习块。\",\n \"source_path\": \"knowledge_base/04-sleep-and-recovery.md\",\n \"score\": 3.8\n }\n ],\n \"safety\": {\n \"level\": \"medium\",\n \"label\": \"需要额外关注\",\n \"note\": \"检测到持续失眠、崩溃或明显耗竭相关表达，建议尽快联系线下支持资源。\",\n \"needs_human_support\": true,\n \"matched_keywords\": [\"失眠\"]\n }\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/api-reference.md](docs/api-reference.md)、\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/api-reference.en.md](docs/api-reference.en.md)、\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 将本地知识库扩展到更多高校场景\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果当前接的是钉钉`企业内部应用`，通常只有该组织内成员才能在钉钉里使用，往往还需要管理员授权。\n- 这意味着别人一般不能“直接打开你的钉钉版就用”，除非他加入该组织，或你把应用做成多组织分发 / 第三方应用。\n- 如果目标是让任何人都能直接体验，这个项目应以 Web 版为主入口，而不是把钉钉端当成唯一入口。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "3b58546acbb22d10fe2d101b2b45769d8de787d1": {"t": 1785764995.493698, "n": 8571, "h": "0cfb4936662c2781", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `查看版本`：[v0.1.0 Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n- `API 参考`：[docs/api-reference.md](docs/api-reference.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个支持 OpenAI / DeepSeek 接入、知识检索、会话记忆和兼容性检查的工程化仓库\n\n说明：\nGitHub Pages 上的在线 Demo 主要用于公开展示页面和交互流程；完整的知识库检索、会话持久化、反馈记录和真实模型调用，需要按下文步骤本地启动后端。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `本地知识库检索`：根据问题检索内置心理支持与学习建议文档片段，增强回复内容。\n- `自定义知识文档接入`：可通过 API 把自定义 Markdown / 文本写入知识库，形成更像 RAG 项目的可扩展入口。\n- `会话记忆与持久化`：自动记录最近对话，支持继续追问、查看历史和本地 SQLite 持久化。\n- `风险识别与转介兜底`：遇到高风险表达时优先切换固定安全回复，而不是继续普通对话。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 工程结构\n\n```text\nbackend/\n api/ # 路由层\n app_factory.py # FastAPI 应用装配\n chat_logic.py # 提示词、风格和 Demo 回复逻辑\n chat_service.py # 完整对话流程\n config.py # 运行配置\n runtime.py # 模型解析与兼容性检查\n schemas.py # 请求/响应模型\nservices/\n knowledge.py # 知识检索与自定义文档写入\n safety.py # 风险检测\n storage.py # SQLite 会话持久化\nstatic/ # Web 前端\ntests/ # 回归测试\n```\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- SQLite\n- Markdown Knowledge Base\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n- `CHAT_DB_PATH`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/api/knowledge/search?q=失眠`\n- `http://127.0.0.1:8000/api/session/<session_id>`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /api/knowledge/search`：本地知识库检索\n- `GET /api/knowledge/documents`：列出当前知识文档\n- `POST /api/knowledge/documents`：写入自定义知识文档\n- `GET /api/session/{session_id}`：最近会话记录\n- `POST /api/feedback`：对回复提交有帮助 / 需要更具体的反馈\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成，并结合了最近会话与知识库片段。\",\n \"mode\": \"openai\",\n \"session_id\": \"sess_xxxxxxxxxxxx\",\n \"assistant_message_id\": 12,\n \"memory_messages_used\": 2,\n \"knowledge_hits\": [\n {\n \"title\": \"考试压力与恢复\",\n \"excerpt\": \"当考试焦虑已经影响睡眠时，建议同时安排线下支持和短时复习块。\",\n \"source_path\": \"knowledge_base/04-sleep-and-recovery.md\",\n \"score\": 3.8\n }\n ],\n \"safety\": {\n \"level\": \"medium\",\n \"label\": \"需要额外关注\",\n \"note\": \"检测到持续失眠、崩溃或明显耗竭相关表达，建议尽快联系线下支持资源。\",\n \"needs_human_support\": true,\n \"matched_keywords\": [\"失眠\"]\n }\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/api-reference.md](docs/api-reference.md)、\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/api-reference.en.md](docs/api-reference.en.md)、\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 将本地知识库扩展到更多高校场景\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "43dcef3be7aa070bd63ed0f188b2280dd4867fc2": {"t": 1785764997.4250593, "n": 7866, "h": "1b023041cfbe6645", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `查看版本`：[v0.1.0 Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个支持 OpenAI / DeepSeek 接入、知识检索、会话记忆和兼容性检查的工程化仓库\n\n说明：\nGitHub Pages 上的在线 Demo 主要用于公开展示页面和交互流程；完整的知识库检索、会话持久化、反馈记录和真实模型调用，需要按下文步骤本地启动后端。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `本地知识库检索`：根据问题检索内置心理支持与学习建议文档片段，增强回复内容。\n- `会话记忆与持久化`：自动记录最近对话，支持继续追问、查看历史和本地 SQLite 持久化。\n- `风险识别与转介兜底`：遇到高风险表达时优先切换固定安全回复，而不是继续普通对话。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- SQLite\n- Markdown Knowledge Base\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n- `CHAT_DB_PATH`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/api/knowledge/search?q=失眠`\n- `http://127.0.0.1:8000/api/session/<session_id>`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /api/knowledge/search`：本地知识库检索\n- `GET /api/session/{session_id}`：最近会话记录\n- `POST /api/feedback`：对回复提交有帮助 / 需要更具体的反馈\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成，并结合了最近会话与知识库片段。\",\n \"mode\": \"openai\",\n \"session_id\": \"sess_xxxxxxxxxxxx\",\n \"assistant_message_id\": 12,\n \"memory_messages_used\": 2,\n \"knowledge_hits\": [\n {\n \"title\": \"考试压力与恢复\",\n \"excerpt\": \"当考试焦虑已经影响睡眠时，建议同时安排线下支持和短时复习块。\",\n \"source_path\": \"knowledge_base/04-sleep-and-recovery.md\",\n \"score\": 3.8\n }\n ],\n \"safety\": {\n \"level\": \"medium\",\n \"label\": \"需要额外关注\",\n \"note\": \"检测到持续失眠、崩溃或明显耗竭相关表达，建议尽快联系线下支持资源。\",\n \"needs_human_support\": true,\n \"matched_keywords\": [\"失眠\"]\n }\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 将本地知识库扩展到更多高校场景\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "abb4ef82e2770694bebd7734efb46e023977eaa8": {"t": 1785764999.0641615, "n": 6875, "h": "8968ddf0262217ad", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n[](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n[](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant)\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 快速入口\n\n- `在线体验`：[Live Demo](https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/)\n- `查看版本`：[v0.1.0 Release](https://github.com/1420079678-ctrl/zhiyuxing-ai-assistant/releases/tag/v0.1.0)\n- `英文说明`：[README_EN.md](README_EN.md)\n- `模型接入`：[docs/model-integration.md](docs/model-integration.md)\n\n## 30 秒能看到什么\n\n- 一个可直接打开的在线 Demo，而不是只停留在方案文档\n- 一个可本地运行的 FastAPI + Web 项目，而不是只有截图\n- 一个支持 OpenAI / DeepSeek 接入和兼容性检查的工程化仓库\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 提供更适合公开展示的在线 Demo 入口\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "9817c3bae12701cc58ac61a82a085a1cb7a8d036": {"t": 1785765000.4730844, "n": 5988, "h": "7105a412f1badefe", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n在线 Demo（部署后）：`https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n也提供基于 GitHub Pages 的公开在线演示页，方便在不配置后端和 API Key 的情况下直接体验交互流程：\n\n- `https://1420079678-ctrl.github.io/zhiyuxing-ai-assistant/`\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 提供更适合公开展示的在线 Demo 入口\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "ce358b947b65585bb84c3fa9b9ec716c64e7ebea": {"t": 1785765001.8386722, "n": 5790, "h": "17ae23598318a5e6", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)、\n [ROADMAP.md](ROADMAP.md)、\n [SECURITY.md](SECURITY.md)、\n [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)、\n [docs/github-launch-kit.md](docs/github-launch-kit.md)\n\n## 路线图\n\n- 继续增强危机表达识别和更安全的引导边界\n- 继续扩展更多 OpenAI 兼容供应商的兼容检查\n- 增强多轮对话连续性与回复稳定性\n- 提供更适合公开展示的在线 Demo 入口\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "2c6fad7429330dba4165ec51b596e5e39005a406": {"t": 1785765003.1829586, "n": 5531, "h": "120c23ae3d2ebde1", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n如果这个项目对你有帮助，欢迎点一个 `Star`。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n- 其他：\n [CONTRIBUTING.md](CONTRIBUTING.md)、\n [CHANGELOG.md](CHANGELOG.md)、\n [LICENSE](LICENSE)\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "e8987d60b75a119016a27b8ae44ea149466b0017": {"t": 1785765004.553487, "n": 5344, "h": "c72064c5d015db0e", "c": "# 知愈星 AI Assistant\n\n[中文](README.md) | [English](README_EN.md)\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- 中文：\n [docs/project-report.md](docs/project-report.md)、\n [docs/usage-guide.md](docs/usage-guide.md)、\n [docs/model-integration.md](docs/model-integration.md)、\n [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- English:\n [docs/project-report.en.md](docs/project-report.en.md)、\n [docs/usage-guide.en.md](docs/usage-guide.en.md)、\n [docs/model-integration.en.md](docs/model-integration.en.md)、\n [docs/dingtalk-integration.en.md](docs/dingtalk-integration.en.md)\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "d54f5f0e02a91ae009654cb4e4e191e28117f192": {"t": 1785765005.8386726, "n": 5105, "h": "5c3fc79d7afc417f", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n需要注意：这几个脚本只是帮你一键写好模型接入配置，不是免 API Key 调用。\n\n- `.\\setup-openai.ps1` 对应 OpenAI 官方接口，真实调用需要 `OPENAI_API_KEY`\n- `.\\setup-deepseek-chat.ps1` 对应 DeepSeek Chat，真实调用需要 `DEEPSEEK_API_KEY`\n- `.\\setup-deepseek-r1.ps1` 对应 DeepSeek R1，真实调用也需要 `DEEPSEEK_API_KEY`\n\n如果运行脚本时没有填写对应 Key，项目仍然可以启动，但会自动回退到本地演示模式，不会真的调用线上模型。\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/usage-guide.md](docs/usage-guide.md)：运行模式、环境变量和常见问题说明\n- [docs/model-integration.md](docs/model-integration.md)：不同大模型的接入方式与 `.env` 配置示例\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n再次强调：这些脚本表示“项目已内置这些接入预设”，不是“这几个模型可以不填 Key 直接调用”。\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "ce631a17aaaf82181757cfd3a6f988ae2e52abcc": {"t": 1785765007.1775863, "n": 4753, "h": "08b23793d52e6a86", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | 与当前模型匹配的 API Key |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 一键配置模型接入\n\n推荐直接使用仓库根目录下一键脚本：\n\n```powershell\n.\\setup-openai.ps1\n.\\setup-deepseek-chat.ps1\n.\\setup-deepseek-r1.ps1\n```\n\n也可以双击对应的 `.bat` 文件。脚本会自动：\n\n- 不存在 `.env` 时，从 `.env.example` 复制一份\n- 按目标模型写入 `OPENAI_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`\n- 自动设置 `MODEL_API_KEY_ENV`，确保项目优先读取正确的密钥变量\n- 保留其他未切换的配置项\n\n如果想手动配置，至少需要关注：\n\n- `OPENAI_API_KEY`\n- `DEEPSEEK_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_API_KEY_ENV`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`\n\n### 3. 启动前检查兼容性\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py\n```\n\n这个检查会直接告诉你：\n\n- 当前到底会读取哪个密钥变量\n- 当前模型和 API 地址是否存在明显错配\n- `deepseek-reasoner` 这类模型是否已经按兼容规则处理\n- 当前配置是否真的可以进入真实模型调用模式\n\n如果你已经填了真实 Key，还可以追加一次最小真实探测：\n\n```powershell\n.\\.venv\\Scripts\\python scripts\\check_model_config.py --probe\n```\n\n这一步会实际发起一次极小请求，用来确认“不是看起来兼容，而是真的能调通”。\n\n### 4. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/api/compatibility`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 5. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /api/compatibility`：模型接入兼容性检查\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/usage-guide.md](docs/usage-guide.md)：运行模式、环境变量和常见问题说明\n- [docs/model-integration.md](docs/model-integration.md)：不同大模型的接入方式与 `.env` 配置示例\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 或直接运行一键脚本切换不同模型提供商。\n\n- 切到 OpenAI：运行 `.\\setup-openai.ps1`\n- 切到 DeepSeek Chat：运行 `.\\setup-deepseek-chat.ps1`\n- 切到 DeepSeek R1：运行 `.\\setup-deepseek-r1.ps1`\n- 切到其他 OpenAI 兼容供应商：运行 `scripts/setup_model_config.py` 并传入自定义 `base_url`、`model_name`、`api_key_env`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型、API 地址和接入兼容检查结果\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n需要说明的是：本项目对 `OpenAI` 和 `DeepSeek` 官方接口可以做到明确兼容；对其他“OpenAI 兼容”供应商，是否完全兼容仍取决于对方是否真的支持 Chat Completions、当前模型名和常用参数格式。仓库里新增的兼容检查接口和脚本，就是用来把这件事提前说明白，而不是等运行时报错。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "f0145da240d627254a9e6df81f4605545eda8c3b": {"t": 1785765012.1647952, "n": 3914, "h": "20ead794bf58b518", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | `OPENAI_API_KEY` |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置：\n\n- `OPENAI_API_KEY`：可留空，留空时自动进入本地演示模式\n- `DEEPSEEK_API_KEY`：可作为 DeepSeek 的密钥变量使用\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`：可选，设置为 `true` 时强制使用本地演示模式\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 4. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/usage-guide.md](docs/usage-guide.md)：运行模式、环境变量和常见问题说明\n- [docs/model-integration.md](docs/model-integration.md)：不同大模型的接入方式与 `.env` 配置示例\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 切换不同模型提供商。\n\n- 切到 OpenAI：修改 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`MODEL_NAME`\n- 切到 DeepSeek：修改 `DEEPSEEK_API_KEY`、`OPENAI_BASE_URL=https://api.deepseek.com`、`MODEL_NAME=deepseek-chat` 或 `deepseek-reasoner`\n- Web 页面支持直接下拉选择模型目标和辅导风格\n- 页面右侧会直接显示当前提供商、当前模型和 API 地址，便于确认是否接对\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "420134e583cb6a02b515fad542efc15411c78ccf": {"t": 1785765013.7817333, "n": 3892, "h": "c30405f1315ea87e", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | `OPENAI_API_KEY` |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置：\n\n- `OPENAI_API_KEY`：可留空，留空时自动进入本地演示模式\n- `DEEPSEEK_API_KEY`：可作为 DeepSeek 的密钥变量使用\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `MODEL_PROVIDER`\n- `MODEL_TEMPERATURE`\n- `DEMO_MODE`：可选，设置为 `true` 时强制使用本地演示模式\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 4. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/usage-guide.md](docs/usage-guide.md)：运行模式、环境变量和常见问题说明\n- [docs/model-integration.md](docs/model-integration.md)：不同大模型的接入方式与 `.env` 配置示例\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 接入不同大模型\n\n当前项目后端使用的是 OpenAI 兼容接口，因此可以通过修改 `.env` 切换不同模型提供商。\n\n- 切到 OpenAI：修改 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`MODEL_NAME`\n- 切到 DeepSeek：修改 `DEEPSEEK_API_KEY`、`OPENAI_BASE_URL=https://api.deepseek.com`、`MODEL_NAME=deepseek-chat` 或 `deepseek-reasoner`\n- Web 页面右侧会直接显示当前提供商、当前模型和 API 地址，便于确认是否接对\n\n如果要接 `DeepSeek-R1`，当前代码已经处理了 `deepseek-reasoner` 的参数兼容问题，不会再强行传不适合的 `temperature` 参数。\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "d55a58f4bc5f6a6b21368bee3ad465e5d1543926": {"t": 1785765015.0260725, "n": 3343, "h": "87353b60ef6961bb", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | `OPENAI_API_KEY` |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置：\n\n- `OPENAI_API_KEY`：可留空，留空时自动进入本地演示模式\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `DEMO_MODE`：可选，设置为 `true` 时强制使用本地演示模式\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n如果你的系统 Python 没装项目依赖，最稳的方式是直接使用仓库自带虚拟环境：\n\n```powershell\n.\\.venv\\Scripts\\python -m uvicorn app:app --reload\n```\n\n也可以直接运行仓库根目录下的一键脚本：\n\n```powershell\n.\\start-web.ps1\n```\n\n或双击：\n\n```text\nstart-web.bat\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 4. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/usage-guide.md](docs/usage-guide.md)：运行模式、环境变量和常见问题说明\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "bb44466ced6eefc4892faf299bca95a614301f9a": {"t": 1785765016.24262, "n": 3142, "h": "080418d1fa3f9c80", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | `OPENAI_API_KEY` |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 独立 Web 页面\n\n当前仓库默认运行的是独立 Web 页面，不需要打开钉钉即可访问和体验。\n\n\n\n### 钉钉接入场景示意\n\n下面两张图保留为钉钉平台接入场景示意，用于说明项目后续可以如何落到企业协同平台中。\n\n\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置：\n\n- `OPENAI_API_KEY`：可留空，留空时自动进入本地演示模式\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `DEMO_MODE`：可选，设置为 `true` 时强制使用本地演示模式\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 4. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/usage-guide.md](docs/usage-guide.md)：运行模式、环境变量和常见问题说明\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "4664b04ffbb37b67021899c06388c391dd338e29": {"t": 1785765017.5602515, "n": 3011, "h": "1439afe146583c61", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助服务，围绕学业压力、拖延内耗、考试与面试焦虑等高频问题，提供温和、具体、可执行的支持性建议。\n\n这个仓库的目标不是单纯展示方案，而是提供一个可以直接运行、便于继续开发、也能逐步接入钉钉等平台的完整项目基础。\n\n## 项目价值\n\n- 聚焦真实且高频的大学生使用场景，而不是泛化聊天。\n- 把“情绪支持”和“学习行动建议”放进同一轮对话，形成更完整的支持闭环。\n- 支持无密钥运行的本地演示模式，拿到仓库后可以直接启动和体验。\n- 预留模型调用和钉钉集成空间，便于后续继续做成更完整的产品。\n\n## 核心能力\n\n- `情绪支持对话`：识别压力、焦虑、拖延等常见表达，给出温和回应。\n- `学习行动建议`：把大问题拆成可立刻执行的小步骤，降低启动门槛。\n- `双运行模式`：未配置模型密钥时使用本地演示模式；配置后切换到 OpenAI 兼容模型调用模式。\n- `Web 服务化`：提供可直接访问的页面、健康检查、接口元信息和 Swagger 文档。\n- `工程基础`：包含测试、CI、环境变量说明和补充文档。\n\n## 使用场景\n\n- 学业压力大，任务很多，不知道从哪里开始\n- 长期拖延，明知道该做但迟迟启动不了\n- 考试、答辩、面试前持续紧张，难以进入准备状态\n- 情绪混乱导致学习节奏失序，需要先稳定状态再恢复行动\n\n## 运行模式\n\n| 模式 | 说明 | 需要的配置 |\n| --- | --- | --- |\n| 本地演示模式 | 使用内置规则生成支持性回复，适合本地启动、调试界面和展示流程 | 无需 API Key |\n| 模型调用模式 | 调用 OpenAI 兼容接口生成回复，适合继续做真实能力验证 | `OPENAI_API_KEY` |\n\n项目默认优先保证“拿到就能跑”。如果没有配置模型密钥，页面和 `/chat` 接口仍然可以完整返回结果。\n\n## 页面预览\n\n### 平台界面\n\n\n\n### 对话演示\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置：\n\n- `OPENAI_API_KEY`：可留空，留空时自动进入本地演示模式\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n- `DEMO_MODE`：可选，设置为 `true` 时强制使用本地演示模式\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n- `http://127.0.0.1:8000/project-docs/usage-guide.md`\n\n### 4. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口概览\n\n- `GET /`：Web 页面入口\n- `POST /chat`：对话接口\n- `GET /health`：服务健康检查\n- `GET /api/meta`：服务元信息与当前运行模式\n- `GET /docs`：Swagger 文档\n- `GET /project-docs/...`：项目补充文档\n\n### `POST /chat`\n\n请求示例：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"当前为模型调用模式。回复由配置的 OpenAI 兼容接口生成。\",\n \"mode\": \"openai\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/usage-guide.md](docs/usage-guide.md)：运行模式、环境变量和常见问题说明\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 安全边界\n\n- 项目定位是情绪支持和学习辅助，不替代专业心理诊断或治疗。\n- 当前实现强调温和、具体、避免危险引导的回复风格。\n- 如果用户出现持续失眠、严重低落或自伤相关表达，实际产品应优先引导线下求助与转介。\n\n## 钉钉接入说明\n\n- Web 页面是默认入口，便于直接访问和继续开发。\n- 钉钉是可选的真实业务接入场景，不影响项目本身独立运行。\n- 如果接入钉钉，需要根据企业内部应用、多组织分发或用户授权模式处理权限问题。\n\n## 测试与持续集成\n\n- 本地测试命令：`python -m pytest -vv`\n- 仓库已配置 GitHub Actions，在推送后自动运行基础测试\n"}, "afc56bf4f691b9cf70c9a980ffa75f108fa22ba9": {"t": 1785765019.0392504, "n": 3121, "h": "fd2002bad6bf73e0", "c": "# 知愈星 AI Assistant\n\n\n\n\n\n面向大学生场景的 AI 情绪支持与学习辅助原型项目，采用“可运行 Web Demo + FastAPI 后端 + 文档化方案说明”的方式组织，适合作为实习投递时展示 AI 应用落地、后端开发和工程化整理能力的 GitHub 项目。\n\n`技术关键词：Python / FastAPI / OpenAI SDK / Prompt Engineering / Pydantic / Pytest / GitHub Actions / DingTalk Integration Design`\n\n## 适合投递的岗位方向\n\n- Python 后端开发实习\n- AI 应用 / LLM 应用开发实习\n- 偏产品理解的技术实习\n\n## 1 分钟看点\n\n- 可以直接本地启动独立 Web Demo，不依赖钉钉组织权限。\n- 提供 `/chat`、`/health`、`/api/meta` 等接口，能快速体现后端结构。\n- 通过系统提示词约束输出风格与安全边界，体现基础 Prompt 设计意识。\n- 补充了 `pytest` 和 GitHub Actions CI，不只是“方案展示”，而是最小可运行交付。\n- 单独说明钉钉接入的权限边界，避免把平台型方案误写成“任何人都可直接使用”。\n\n## 项目定位\n\n很多大学生面临的并不只是“不会学”，而是“在焦虑、拖延、自我怀疑的状态下很难重新开始”。这个项目尝试把“情绪支持”和“学习建议”放进同一个对话闭环中，用 AI 先帮助用户稳定状态，再给出可执行的小步行动建议。\n\n当前 GitHub 版本强调的是可展示、可验证、可说明边界，而不是把作品集 Demo 包装成完整线上产品。\n\n## 这个仓库能证明什么\n\n| 能力维度 | 仓库证据 | 面试中可说明的点 |\n| --- | --- | --- |\n| AI 应用原型设计 | `/chat` 接口、系统提示词约束 | 不只是调用模型，还考虑场景、语气和边界 |\n| 后端服务开发 | `app.py`、Pydantic 请求响应模型 | 具备基础 API 设计和服务封装能力 |\n| 演示与交付意识 | `static/` 独立 Web Demo、根路由页面 | 外部评审可以直接体验，不被平台权限卡住 |\n| 工程质量 | `tests/test_app.py`、`.github/workflows/ci.yml` | 具备最小测试和持续集成意识 |\n| 平台集成边界表达 | `docs/dingtalk-integration.md` | 清楚区分“真实落地场景”和“作品集演示入口” |\n\n## 已实现与规划中\n\n| 状态 | 内容 |\n| --- | --- |\n| 已实现 | FastAPI 服务、Web Demo、`/chat` `/health` `/api/meta` 接口、基础 Prompt 约束、测试、CI、项目文档整理 |\n| 规划中 | 知识库检索、风险词识别与转介流程、对话记录存储、真实钉钉授权接入 |\n\n这种写法更适合实习投递，因为它既展示能力，也避免过度承诺。\n\n## 页面预览\n\n### 平台界面\n\n\n\n### 对话演示\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构图\n\n\n\n## 快速启动\n\n推荐使用 Python 3.13，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置：\n\n- `OPENAI_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n\n### 3. 启动服务\n\n```bash\npython -m uvicorn app:app --reload\n```\n\n启动后可访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n\n### 4. 运行测试\n\n```bash\npython -m pytest -vv\n```\n\n## 接口示例\n\n### `POST /chat`\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"这是作品集仓库中的最小可运行 Demo，用于展示项目方向与接口能力。\"\n}\n```\n\n## 文档入口\n\n- [docs/project-report.md](docs/project-report.md)：完整项目报告与方案背景\n- [docs/resume-interview-guide.md](docs/resume-interview-guide.md)：简历描述、自我介绍和投递表达\n- [docs/interview-qa.md](docs/interview-qa.md)：面试高频追问速答\n- [docs/dingtalk-integration.md](docs/dingtalk-integration.md)：钉钉权限模型与集成边界说明\n\n## 钉钉相关说明\n\n- 这个仓库默认以独立 Web Demo 作为演示入口，外部评审不需要使用个人账号权限。\n- 如果项目以钉钉企业内部应用形态部署，访问能力会受到组织、管理员授权和应用类型限制。\n- 因此钉钉更适合作为真实业务落地场景说明，而不是唯一 Demo 入口。\n"}, "9a8e295c98b319fa18b0e69ad513ff617b800870": {"t": 1785765020.462509, "n": 2974, "h": "19143fc135f71fd9", "c": "# 知愈星 AI Assistant\n\n面向大学生场景的 AI 心理支持与学习辅助助手作品集项目，聚焦“情绪支持 + 学习建议”的联动式对话体验。\n\n这个仓库的目标不是只展示一个想法，而是展示一套更适合实习投递的能力组合：\n\n- AI 应用原型设计\n- FastAPI 后端接口实现\n- Prompt 约束与安全边界设计\n- 独立 Web Demo 产品化\n- 测试与 GitHub Actions 持续集成\n\n## 项目概览\n\n很多大学生面临的问题并不只是“不会学”，而是“在焦虑、拖延、自我怀疑的状态下无法进入学习”。知愈星尝试把情绪支持与学习建议放进同一个对话闭环里，而不是把二者拆成割裂的功能模块。\n\n当前 GitHub 版本采用“可运行 Demo + 方案展示”的方式组织，既能直接运行，也能清晰体现项目思路、技术路径和工程边界。\n\n## 为什么这个仓库适合投实习\n\n### 能体现的工程能力\n\n- `AI 应用落地`：基于 OpenAI Python SDK 实现对话接口，组织系统提示词、用户输入和补充要求。\n- `后端开发`：使用 FastAPI 和 Pydantic 封装接口、请求体和响应体，具备基本服务化结构。\n- `前端演示`：补充独立 Web Demo 页面，避免项目演示被平台权限绑死。\n- `工程质量`：增加 pytest 测试和 GitHub Actions，保证基础功能可验证。\n- `方案表达`：保留项目报告、架构图、流程图和集成边界说明，适合面试展开讲述。\n\n### 能体现的产品思考\n\n- 场景聚焦在大学生高频问题，而不是泛化聊天。\n- 将“情绪识别 -> 学习建议 -> 行动拆解”作为核心闭环。\n- 明确 AI 不是专业医疗替代，保留安全边界和转介意识。\n- 区分“作品集演示入口”和“钉钉真实落地场景”，降低外部体验门槛。\n\n## 当前已实现内容\n\n- 一个可本地运行的 FastAPI 服务\n- 一个独立 Web Demo 页面\n- `/chat`、`/health`、`/api/meta` 等接口\n- 适用于大学生场景的基础系统提示词约束\n- 项目报告、流程图、架构图和钉钉权限说明文档\n- `pytest` 测试\n- GitHub Actions CI\n\n## 当前边界\n\n当前版本是作品集版本，不是完整线上产品。已经实现的部分和规划中的部分做了明确区分：\n\n- 已实现：Demo 对话流程、接口、静态页面、文档整理、测试与 CI。\n- 规划中：知识库检索、风险词识别与转介流程、对话记录存储、真实钉钉授权接入。\n\n这种表达方式更适合实习投递，因为它既展示能力，也避免过度承诺。\n\n## 页面预览\n\n### 平台界面\n\n\n\n### 对话演示\n\n\n\n## 技术栈\n\n- Python 3.13\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 架构与目录\n\n技术架构图：\n\n\n\n项目目录：\n\n```text\nzhiyuxing-ai-assistant/\n├── app.py\n├── requirements.txt\n├── requirements-dev.txt\n├── .python-version\n├── .env.example\n├── static/\n│ ├── app.js\n│ ├── index.html\n│ └── style.css\n├── tests/\n│ └── test_app.py\n└── docs/\n ├── dingtalk-integration.md\n ├── project-report.md\n ├── resume-interview-guide.md\n └── assets/\n```\n\n## 快速启动\n\n推荐使用 Python 3.13 运行本项目，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npython -m pip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置以下内容：\n\n- `OPENAI_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n\n### 3. 启动服务\n\n```bash\nuvicorn app:app --reload\n```\n\n启动后可以访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n\n## 接口示例\n\n### `POST /chat`\n\n请求体：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"这是作品集仓库中的最小可运行 Demo，用于展示项目方向与接口能力。\"\n}\n```\n\n## 实习投递辅助文档\n\n- 项目报告：[docs/project-report.md](docs/project-report.md)\n- 钉钉集成边界：[docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- 简历与面试说明：[docs/resume-interview-guide.md](docs/resume-interview-guide.md)\n\n## 钉钉集成边界\n\n- 如果项目以钉钉企业内部应用形态部署，外部评审通常无法直接进入所属组织体验。\n- 因此仓库默认提供独立 Web Demo 作为展示入口，钉钉版本作为业务落地场景保留在文档中说明。\n- 这种拆分更适合作品集展示，也更便于说明平台集成与权限隔离问题。\n\n## 测试与持续集成\n\n```bash\npython -m pytest -vv\n```\n\n仓库已配置 GitHub Actions，在推送后自动运行基础测试。\n"}, "9442197681ef3cf36a48c757b78bb7037fb6938c": {"t": 1785765022.06133, "n": 2974, "h": "6a507f979fc66f90", "c": "# 知愈星 AI Assistant\n\n知愈星是一个面向大学生场景的 AI 心理支持与学习辅助助手，围绕“情绪支持 + 学习指导”两条主线，尝试把共情式对话、行动建议和校园使用场景结合起来。\n\n这个仓库适合用作实习作品集展示，因为它同时保留了两个层面：\n\n- 一个可以本地运行、独立访问的 Web Demo；\n- 一份完整整理过的项目方案文档、流程图和界面示意；\n- 清晰体现了产品思考、接口设计、提示工程和安全边界意识。\n\n## 项目亮点\n\n- 场景聚焦：针对大学生常见的学业压力、社交焦虑、拖延和学习内耗设计对话方向。\n- 双线联动：不是只做“心理安慰”，而是把情绪支持和学习建议做成一个连续闭环。\n- 可运行展示：仓库提供 FastAPI + 原生前端页面，可直接接入 OpenAI 兼容模型进行对话测试。\n- 伦理边界明确：回复中避免诊断化表达，对高风险场景保留转介意识，不把 AI 包装成专业医疗替代。\n- 展示路径清晰：独立 Web Demo 无需进入特定钉钉组织即可体验。\n\n## 当前仓库包含什么\n\n- `app.py`：最小可运行服务，提供 Web Demo、健康检查和对话接口。\n- `static/`：独立演示页的静态前端资源。\n- `docs/project-report.md`：完整项目报告，包含定位、功能设计、创新点和技术方案。\n- `docs/dingtalk-integration.md`：钉钉集成与权限边界说明。\n- `docs/assets/`：流程图、架构图和界面示意图。\n- `requirements.txt`：运行 Demo 所需依赖。\n- `requirements-dev.txt`：测试和 CI 所需依赖。\n\n## 技术栈\n\n- Python\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 页面预览\n\n### 平台界面\n\n\n\n### 对话演示\n\n\n\n## 项目结构\n\n```text\nzhiyuxing-ai-assistant/\n├── app.py\n├── requirements.txt\n├── requirements-dev.txt\n├── .env.example\n├── static/\n│ ├── app.js\n│ ├── index.html\n│ └── style.css\n├── tests/\n│ └── test_app.py\n└── docs/\n ├── dingtalk-integration.md\n ├── project-report.md\n └── assets/\n ├── 02-project-goals-flow.png\n ├── 03-core-features-flow.png\n ├── 04-innovation-workflow.png\n ├── 05-heart-learning-loop.png\n ├── 06-practicality-flow.png\n ├── 07-technical-architecture.png\n ├── 08-service-closed-loop.png\n ├── 09-platform-overview.png\n └── 10-chat-demo.png\n```\n\n## 快速启动\n\n推荐使用 Python 3.13 运行本项目，以保持与当前本地开发和 CI 环境一致。\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置以下内容：\n\n- `OPENAI_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n\n### 3. 启动服务\n\n```bash\nuvicorn app:app --reload\n```\n\n启动后可以访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n\n## 接口示例\n\n### `POST /chat`\n\n请求体：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"这是作品集仓库中的最小可运行 Demo，用于展示项目方向与接口能力。\"\n}\n```\n\n## 文档入口\n\n- 完整项目报告见 [docs/project-report.md](docs/project-report.md)\n- 钉钉集成与权限说明见 [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- 技术架构图见 [docs/assets/07-technical-architecture.png](docs/assets/07-technical-architecture.png)\n\n## 钉钉权限边界\n\n- 如果项目以钉钉企业内部应用形态部署，外部评审通常无法直接进入所属组织体验。\n- 因此这个仓库默认提供独立 Web Demo 作为展示入口，钉钉版本作为业务落地场景保留在文档中说明。\n- 这套展示策略强调了平台集成、权限隔离和作品集可访问性的平衡，而不是把演示绑定在单一租户环境里。\n\n## 测试与持续集成\n\n```bash\npytest\n```\n\n仓库已经补充了 `.github/workflows/ci.yml`，推送后会自动执行基础测试。\n\n## 当前边界\n\n- 这个仓库不是完整线上产品，而是“可运行 Demo + 方案展示”的作品集版本。\n- 钉钉集成、知识库检索、风险词转介流程目前仍停留在方案设计或可继续扩展阶段。\n- 如果继续打磨到更强的实习投递版本，下一步最值得补的是对话记录存储、风险识别逻辑和真实钉钉授权接入。\n"}, "8c0a7bdde5bdf68860d54a9360413c8e2f419c70": {"t": 1785765023.4431534, "n": 2929, "h": "94104875ed41096b", "c": "# 知愈星 AI Assistant\n\n知愈星是一个面向大学生场景的 AI 心理支持与学习辅助助手，围绕“情绪支持 + 学习指导”两条主线，尝试把共情式对话、行动建议和校园使用场景结合起来。\n\n这个仓库适合用作实习作品集展示，因为它同时保留了两个层面：\n\n- 一个可以本地运行、独立访问的 Web Demo；\n- 一份完整整理过的项目方案文档、流程图和界面示意；\n- 清晰体现了产品思考、接口设计、提示工程和安全边界意识。\n\n## 项目亮点\n\n- 场景聚焦：针对大学生常见的学业压力、社交焦虑、拖延和学习内耗设计对话方向。\n- 双线联动：不是只做“心理安慰”，而是把情绪支持和学习建议做成一个连续闭环。\n- 可运行展示：仓库提供 FastAPI + 原生前端页面，可直接接入 OpenAI 兼容模型进行对话测试。\n- 伦理边界明确：回复中避免诊断化表达，对高风险场景保留转介意识，不把 AI 包装成专业医疗替代。\n- 展示路径清晰：独立 Web Demo 无需进入特定钉钉组织即可体验。\n\n## 当前仓库包含什么\n\n- `app.py`：最小可运行服务，提供 Web Demo、健康检查和对话接口。\n- `static/`：独立演示页的静态前端资源。\n- `docs/project-report.md`：完整项目报告，包含定位、功能设计、创新点和技术方案。\n- `docs/dingtalk-integration.md`：钉钉集成与权限边界说明。\n- `docs/assets/`：流程图、架构图和界面示意图。\n- `requirements.txt`：运行 Demo 所需依赖。\n- `requirements-dev.txt`：测试和 CI 所需依赖。\n\n## 技术栈\n\n- Python\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 页面预览\n\n### 平台界面\n\n\n\n### 对话演示\n\n\n\n## 项目结构\n\n```text\nzhiyuxing-ai-assistant/\n├── app.py\n├── requirements.txt\n├── requirements-dev.txt\n├── .env.example\n├── static/\n│ ├── app.js\n│ ├── index.html\n│ └── style.css\n├── tests/\n│ └── test_app.py\n└── docs/\n ├── dingtalk-integration.md\n ├── project-report.md\n └── assets/\n ├── 02-project-goals-flow.png\n ├── 03-core-features-flow.png\n ├── 04-innovation-workflow.png\n ├── 05-heart-learning-loop.png\n ├── 06-practicality-flow.png\n ├── 07-technical-architecture.png\n ├── 08-service-closed-loop.png\n ├── 09-platform-overview.png\n └── 10-chat-demo.png\n```\n\n## 快速启动\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置以下内容：\n\n- `OPENAI_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n\n### 3. 启动服务\n\n```bash\nuvicorn app:app --reload\n```\n\n启动后可以访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n\n## 接口示例\n\n### `POST /chat`\n\n请求体：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"当前状态里明显存在压力堆积，可以先不追求一次解决整周问题，而是把任务缩小到今天最容易开始的一步，比如先完成 20 分钟复习。\",\n \"note\": \"这是作品集仓库中的最小可运行 Demo，用于展示项目方向与接口能力。\"\n}\n```\n\n## 文档入口\n\n- 完整项目报告见 [docs/project-report.md](docs/project-report.md)\n- 钉钉集成与权限说明见 [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- 技术架构图见 [docs/assets/07-technical-architecture.png](docs/assets/07-technical-architecture.png)\n\n## 钉钉权限边界\n\n- 如果项目以钉钉企业内部应用形态部署，外部评审通常无法直接进入所属组织体验。\n- 因此这个仓库默认提供独立 Web Demo 作为展示入口，钉钉版本作为业务落地场景保留在文档中说明。\n- 这套展示策略强调了平台集成、权限隔离和作品集可访问性的平衡，而不是把演示绑定在单一租户环境里。\n\n## 测试与持续集成\n\n```bash\npytest\n```\n\n仓库已经补充了 `.github/workflows/ci.yml`，推送后会自动执行基础测试。\n\n## 当前边界\n\n- 这个仓库不是完整线上产品，而是“可运行 Demo + 方案展示”的作品集版本。\n- 钉钉集成、知识库检索、风险词转介流程目前仍停留在方案设计或可继续扩展阶段。\n- 如果继续打磨到更强的实习投递版本，下一步最值得补的是对话记录存储、风险识别逻辑和真实钉钉授权接入。\n"}, "0b4480218512582a8f7166295b21fadb3f6b4710": {"t": 1785765024.8363643, "n": 2935, "h": "424c5dc64fcd5909", "c": "# 知愈星 AI Assistant\n\n知愈星是一个面向大学生场景的 AI 心理支持与学习辅助助手，围绕“情绪支持 + 学习指导”两条主线，尝试把共情式对话、行动建议和校园使用场景结合起来。\n\n这个仓库适合用作实习作品集展示，因为它同时保留了两个层面：\n\n- 一个可以本地运行、独立访问的 Web Demo；\n- 一份完整整理过的项目方案文档、流程图和界面示意；\n- 清晰体现了产品思考、接口设计、提示工程和安全边界意识。\n\n## 项目亮点\n\n- 场景聚焦：针对大学生常见的学业压力、社交焦虑、拖延和学习内耗设计对话方向。\n- 双线联动：不是只做“心理安慰”，而是把情绪支持和学习建议做成一个连续闭环。\n- 可运行展示：仓库提供 FastAPI + 原生前端页面，可直接接入 OpenAI 兼容模型进行对话测试。\n- 伦理边界明确：回复中避免诊断化表达，对高风险场景保留转介意识，不把 AI 包装成专业医疗替代。\n- 展示路径清晰：独立 Web Demo 不依赖评审进入你的钉钉组织即可体验。\n\n## 当前仓库包含什么\n\n- `app.py`：最小可运行服务，提供 Web Demo、健康检查和对话接口。\n- `static/`：独立演示页的静态前端资源。\n- `docs/project-report.md`：完整项目报告，包含定位、功能设计、创新点和技术方案。\n- `docs/dingtalk-integration.md`：钉钉集成与权限边界说明。\n- `docs/assets/`：流程图、架构图和界面示意图。\n- `requirements.txt`：运行 Demo 所需依赖。\n- `requirements-dev.txt`：测试和 CI 所需依赖。\n\n## 技术栈\n\n- Python\n- FastAPI\n- OpenAI Python SDK\n- Pydantic\n- python-dotenv\n- Pytest\n- GitHub Actions\n\n## 页面预览\n\n### 平台界面\n\n\n\n### 对话演示\n\n\n\n## 项目结构\n\n```text\nzhiyuxing-ai-assistant/\n├── app.py\n├── requirements.txt\n├── requirements-dev.txt\n├── .env.example\n├── static/\n│ ├── app.js\n│ ├── index.html\n│ └── style.css\n├── tests/\n│ └── test_app.py\n└── docs/\n ├── dingtalk-integration.md\n ├── project-report.md\n └── assets/\n ├── 02-project-goals-flow.png\n ├── 03-core-features-flow.png\n ├── 04-innovation-workflow.png\n ├── 05-heart-learning-loop.png\n ├── 06-practicality-flow.png\n ├── 07-technical-architecture.png\n ├── 08-service-closed-loop.png\n ├── 09-platform-overview.png\n └── 10-chat-demo.png\n```\n\n## 快速启动\n\n### 1. 安装依赖\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npip install -r requirements.txt -r requirements-dev.txt\n```\n\n### 2. 配置环境变量\n\n```powershell\nCopy-Item .env.example .env\n```\n\n在 `.env` 中配置以下内容：\n\n- `OPENAI_API_KEY`\n- `OPENAI_BASE_URL`\n- `MODEL_NAME`\n\n### 3. 启动服务\n\n```bash\nuvicorn app:app --reload\n```\n\n启动后可以访问：\n\n- `http://127.0.0.1:8000/`\n- `http://127.0.0.1:8000/api/meta`\n- `http://127.0.0.1:8000/health`\n- `http://127.0.0.1:8000/docs`\n\n## 接口示例\n\n### `POST /chat`\n\n请求体：\n\n```json\n{\n \"message\": \"这周压力很大，感觉完全学不进去。\",\n \"system_hint\": \"给出温和且可执行的建议\"\n}\n```\n\n返回示例：\n\n```json\n{\n \"reply\": \"我能感觉到你现在有点被压力压住了。我们先不要急着把一整周的问题一次解决，可以先挑今天最小的一件事开始，比如只完成 20 分钟复习...\",\n \"note\": \"这是作品集仓库中的最小可运行 Demo，用于展示项目方向与接口能力。\"\n}\n```\n\n## 文档入口\n\n- 完整项目报告见 [docs/project-report.md](docs/project-report.md)\n- 钉钉集成与权限说明见 [docs/dingtalk-integration.md](docs/dingtalk-integration.md)\n- 技术架构图见 [docs/assets/07-technical-architecture.png](docs/assets/07-technical-architecture.png)\n\n## 钉钉权限边界\n\n- 如果项目以钉钉企业内部应用形态部署，外部评审通常不能直接进入你的组织体验。\n- 因此这个仓库默认提供独立 Web Demo 作为展示入口，钉钉版本作为业务落地场景保留在文档中说明。\n- 面试时可以强调：你考虑了平台集成、权限隔离和作品集可访问性，而不是把演示绑死在个人租户里。\n\n## 测试与持续集成\n\n```bash\npytest\n```\n\n仓库已经补充了 `.github/workflows/ci.yml`，推送后会自动执行基础测试。\n\n## 当前边界\n\n- 这个仓库不是完整线上产品，而是“可运行 Demo + 方案展示”的作品集版本。\n- 钉钉集成、知识库检索、风险词转介流程目前仍停留在方案设计或可继续扩展阶段。\n- 如果继续打磨到更强的实习投递版本，下一步最值得补的是对话记录存储、风险识别逻辑和真实钉钉授权接入。\n"}, "12d3eba28be566a12caf9fb3a687171aca5f2824": {"t": 1785765035.1491416, "n": 439, "h": "4776824d49d8d13b", "c": "# src 目录说明\n\n当前仓库是 **展示版（showcase repo）**，暂未包含完整业务源码。\n\n如果你后续要把这个仓库升级成“可运行版”，建议从下面这个结构开始：\n\n```text\nsrc/\n├── app.py # 最小可运行入口\n├── prompts/ # Prompt 模板\n├── services/ # LLM 调用、心理引导、学习建议等服务\n├── routers/ # 接口路由\n├── schemas/ # 请求/响应结构\n└── utils/ # 工具函数\n```\n\n## 最低可运行建议\n你至少可以先补一个最简单的 demo：\n- 用户输入一句话\n- 调用大模型 API\n- 返回心理支持/学习建议回复\n\n这样 GitHub 仓库就会从“作品展示”升级为“有演示能力的项目仓库”。\n"}}}} |