6 کامیت‌ها 8c57a6c86a ... 4b014ad47e

نویسنده SHA1 پیام تاریخ
  Sizhou Chen 4b014ad47e Merge pull request #921 from datawhalechina/codex/recover-pr-614-squashed 1 ماه پیش
  Sizhou Chen a541815be7 Merge pull request #918 from datawhalechina/codex/recover-pr-726-squashed 1 ماه پیش
  Sizhou Chen fccc6c6e37 Merge pull request #917 from datawhalechina/codex/recover-pr-828-squashed 1 ماه پیش
  DeLunnLi 3e2cdbf9c1 feat: restore graduation project from PR #614 4 ماه پیش
  Max3753 b206842a9c feat: restore graduation project from PR #726 3 ماه پیش
  CoralGarden52 c56d505d99 feat: restore graduation project from PR #828 3 ماه پیش
100فایلهای تغییر یافته به همراه15026 افزوده شده و 0 حذف شده
  1. 10 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/.env.example
  2. 25 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/.gitignore
  3. 215 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/README.md
  4. 66 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_01.csv
  5. 18 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_02.csv
  6. 16 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_03.csv
  7. 15 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_04.csv
  8. 17 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_05.csv
  9. 200 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/main.py
  10. 0 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/.gitkeep
  11. 738 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/money_mirror_report.json
  12. 196 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/money_mirror_report.md
  13. 764 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_02_money_mirror_report.json
  14. 112 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_02_money_mirror_report.md
  15. 779 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_03_money_mirror_report.json
  16. 145 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_03_money_mirror_report.md
  17. 9 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/requirements.txt
  18. 5 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/__init__.py
  19. 5 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/__init__.py
  20. 134 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/conversation_agent.py
  21. 201 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/coordinator.py
  22. 36 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/goal_agent.py
  23. 46 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/pattern_agent.py
  24. 377 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/persona_agent.py
  25. 415 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/quest_agent.py
  26. 131 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/reflection_agent.py
  27. 481 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/runtime.py
  28. 41 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/transaction_agent.py
  29. 122 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/config/personas.json
  30. 5 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/memory/__init__.py
  31. 161 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/memory/sqlite_memory.py
  32. 136 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/models.py
  33. 21 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/__init__.py
  34. 61 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/anomaly_detection.py
  35. 52 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/budget_calculator.py
  36. 160 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/csv_import.py
  37. 58 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/goal_projection.py
  38. 126 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/hello_agents_registry.py
  39. 73 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/quest_progress.py
  40. 89 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/statistics.py
  41. 68 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/subscription_detector.py
  42. 53 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/transaction_category.py
  43. 0 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/__init__.py
  44. 88 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/fakes.py
  45. 53 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_conversation_agent.py
  46. 45 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_coordinator.py
  47. 32 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_csv_import.py
  48. 74 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_dynamic_quest_orchestration.py
  49. 15 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_memory_and_category.py
  50. 156 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_persona_agent.py
  51. 10 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_quest_progress.py
  52. 82 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_sample_files.py
  53. 54 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_terminal_quests.py
  54. 64 0
      Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_tools.py
  55. 260 0
      Co-creation-projects/DeLunnLi-PaperGraph/README.md
  56. 82 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/.env.example
  57. 0 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/__init__.py
  58. 30 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/__init__.py
  59. 36 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/base.py
  60. 153 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/knowledge_graph_agent.py
  61. 773 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/paper_analysis_agent.py
  62. 0 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/__init__.py
  63. 26 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/knowledge_graph.py
  64. 36 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/paper_analysis.py
  65. 89 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/search.py
  66. 196 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/search_agent.py
  67. 11 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/__init__.py
  68. 164 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/paper_analysis_helpers.py
  69. 337 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_paper_lookup_tool.py
  70. 148 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_pdf_parse_tool.py
  71. 312 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_reference_lookup_tool.py
  72. 140 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_table_tool.py
  73. 43 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/search_models.py
  74. 46 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/dependencies.py
  75. 137 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/main.py
  76. 64 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/repo.py
  77. 5 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/__init__.py
  78. 85 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/paper_reader.py
  79. 218 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/papers.py
  80. 284 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/search.py
  81. 81 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/search_route_support.py
  82. 35 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/tool_events.py
  83. 1 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/__init__.py
  84. 41 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/author.py
  85. 145 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/conference_landing_pdf.py
  86. 174 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/paper.py
  87. 109 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/paper_paths.py
  88. 227 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/pdf_download.py
  89. 11 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/__init__.py
  90. 312 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/normalize.py
  91. 406 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/paper_searcher.py
  92. 1 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/__init__.py
  93. 399 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/arxiv.py
  94. 508 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/dblp.py
  95. 490 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/openalex.py
  96. 57 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/source_common.py
  97. 341 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/tavily.py
  98. 725 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/storage.py
  99. 0 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/models/__init__.py
  100. 233 0
      Co-creation-projects/DeLunnLi-PaperGraph/backend/app/models/schemas.py

+ 10 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/.env.example

@@ -0,0 +1,10 @@
+LLM_BASE_URL=https://api.deepseek.com
+LLM_MODEL_ID=deepseek-v4-flash
+LLM_API_KEY=your_deepseek_api_key_here
+LLM_TIMEOUT=90
+LLM_MAX_TOKENS=16384
+LLM_CONTEXT_MAX_TOKENS=100000
+LLM_TEMPERATURE=0.2
+
+MONEYMIRROR_USER_ID=local_user
+LOG_LEVEL=INFO

+ 25 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/.gitignore

@@ -0,0 +1,25 @@
+# Secrets and local state
+.env
+outputs/*.db
+outputs/*.sqlite
+outputs/*.sqlite3
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+.venv/
+
+
+# The parent hello-agents repository has broad patterns for its own tests and
+# memory directories; these are intentional project source files here.
+!src/memory/
+!src/memory/**
+
+
+# Re-included project directories must still exclude generated bytecode.
+src/memory/__pycache__/
+tests/__pycache__/
+tool-output
+docs

+ 215 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/README.md

@@ -0,0 +1,215 @@
+# MoneyMirrorAgent —— 智能理财助手
+
+> 将账单转化为可理解的消费镜像,并通过多智能体对话帮助用户制定下一步行动。
+
+## 📝 项目简介
+
+MoneyMirrorAgent 面向日常个人账单场景,接收用户提供的 CSV 交易记录,完成账单标准化、消费分类、行为分析、目标规划和游戏化行动编排。
+
+项目将确定性计算与大模型能力分开:Python 工具负责金额、比例、趋势、异常、预算、目标投影和任务进度;Hello-Agents 负责调用智能体进行分类补全、行为解释、消费人格表达、分步引导、Money Quest 编排、月度 Reflection 和 Markdown 月报生成。
+
+适用场景包括:
+
+- 想了解自己消费结构和行为模式的个人用户;
+- 希望围绕预算、储蓄或某一消费类别制定行动计划的用户;
+
+## ✨ 核心功能
+
+- [x] **账单导入与标准化**:支持常见中英文列名、日期格式、收入/支出字段,以及 UTF-8 和 GB18030 编码。
+- [x] **智能消费分类**:优先查询 SQLite Memory 和规则,低置信度交易交给 LLM 判断;用户纠正后会影响后续同商户分类。
+- [x] **消费行为分析**:统计收入、支出、结余、储蓄率、类别占比、日/周/月趋势、深夜消费、周末消费、发薪后消费和高频小额消费。
+- [x] **异常与订阅检测**:使用 IQR、Z-score、历史水平和周期性扣费规则发现行为信号,并由 LLM 生成解释。
+- [x] **消费人格**:根据真实消费特征向量和配置化人格原型生成有证据支持的个性化表达。
+- [x] **目标与预算规划**:根据现金流、历史消费和目标截止日期计算目标可行性、月度储蓄额度和动态预算。
+- [x] **Money Quest**:LLM 根据真实行为信号编排个性化任务,Python 校验目标、金额、进度、EXP 和完成状态。
+- [x] **等级与成就**:记录任务完成情况、连续完成天数、经验值和阶段性成就。
+- [x] **长期 Memory**:使用 SQLite 保存分类修正、目标、预算、Quest、成就、历史快照、Reflection 和引导对话。
+- [x] **月度 Reflection**:比较计划、实际消费、预算、目标进度和 Quest 完成情况,生成下一周期策略。
+- [x] **分步 AI 引导与 Markdown 月报**:终端中流式输出观察、建议和追问,用户结束引导后生成 Markdown 月报。
+
+## 🛠️ 技术栈
+
+- **Hello-Agents**:`ToolRegistry`、`ReActAgent`、`PlanSolveAgent`、`ReflectionAgent`、`SimpleAgent`、`ContextBuilder`
+- **大模型**:OpenAI 兼容 API,可配置 DeepSeek 等模型服务
+- **数据处理**:Python 标准库、CSV、日期处理和统计计算
+- **长期存储**:SQLite
+- **交互方式**:Python CLI 和流式终端对话
+
+### Agent 架构
+
+```text
+CSV 账单
+   ↓
+MoneyMirrorCoordinator
+   ├── TransactionAgent   ReActAgent:分类、规则与 Memory
+   ├── PatternAgent       PlanSolveAgent:统计、异常与订阅分析
+   ├── PersonaAgent       特征提取、原型评分与 LLM 表达
+   ├── GoalAgent          目标投影与预算规划
+   ├── QuestAgent         真实信号与 LLM 任务编排
+   ├── ReflectionAgent    计划、实际与下一周期策略
+   └── ConversationAgent  分步引导与 Markdown 月报
+```
+
+项目中的确定性工具包括:
+
+- `CSVImportTool`
+- `TransactionCategoryTool`
+- `StatisticsTool`
+- `AnomalyDetectionTool`
+- `BudgetCalculatorTool`
+- `GoalProjectionTool`
+- `SubscriptionDetectorTool`
+- `QuestProgressTool`
+
+## 🚀 快速开始
+
+### 环境要求
+
+- Python 3.10+
+- 可访问的 OpenAI 兼容模型服务
+- Linux、macOS 或 Windows
+
+### 安装依赖
+
+```bash
+cd Co-creation-projects/CoralGarden52-MoneyMirrorAgent
+python -m venv .venv
+source .venv/bin/activate       # Windows: .venv\\Scripts\\activate
+pip install -r requirements.txt
+```
+
+### 配置 API 密钥
+
+复制配置文件并填写模型服务信息:
+
+```bash
+cp .env.example .env
+```
+
+`.env` 中的主要配置项如下:
+
+```dotenv
+LLM_BASE_URL=https://api.deepseek.com
+LLM_MODEL_ID=deepseek-v4-flash
+LLM_API_KEY=your_api_key_here
+LLM_MAX_TOKENS=16384
+LLM_CONTEXT_MAX_TOKENS=100000
+LLM_TEMPERATURE=0.2
+```
+
+### 运行项目
+
+使用 `--csv` 指定账单路径,项目不会依赖固定文件名,用户可以替换为自己的 CSV 文件:
+
+```bash
+# 完整分析:导入、分类、统计、目标、预算、Quest、Reflection 和 Markdown 月报
+python main.py --csv data/sample_01.csv --reset
+
+# 使用自己的账单
+python main.py --csv /path/to/your_transactions.csv --reset
+
+# 进入 CLI 分步对话
+python main.py --interactive --csv data/sample_01.csv
+```
+
+运行结果写入 `outputs/`:
+
+```text
+outputs/<输入文件名>_money_mirror_report.json
+outputs/<输入文件名>_money_mirror_report.md
+outputs/moneymirror.db
+```
+
+JSON 文件保存已验证的事实快照,Markdown 文件由大模型根据账单事实、Memory 和用户对话生成。
+
+## 📖 使用示例
+
+### CSV 输入
+
+```csv
+日期,商户,金额,收支,备注
+2026-07-05 09:00,公司工资,7600,收入,七月工资到账
+2026-07-06 22:42,美团外卖-火锅,76,支出,深夜外卖
+2026-07-07 08:20,地铁,6,支出,通勤
+```
+
+程序也支持以下常见字段名:`date`、`日期`、`交易时间`、`merchant`、`商户`、`amount`、`金额`、`direction`、`收支`、`type`,以及独立的收入和支出列。
+
+### 创建目标和修正分类
+
+```bash
+python main.py --csv data/sample_01.csv --reset \
+  --goal "三个月旅行基金|travel|10000|2800|2026-10-31"
+
+python main.py --csv /path/to/your_transactions.csv \
+  --correct "星巴克:餐饮"
+```
+
+### CLI 分步引导
+
+启动终端分步对话:
+
+```bash
+python main.py --interactive --csv data/sample_01.csv
+```
+
+也可以替换为自己的账单路径:
+
+```bash
+python main.py --interactive --csv /path/to/your_transactions.csv
+```
+
+```text
+MoneyMirrorAgent> 这份账单中观察到深夜餐饮支出较集中。
+MoneyMirrorAgent> 你想先从减少深夜外卖、控制周末消费,还是检查连续扣费开始?
+你> 我想先控制深夜外卖
+MoneyMirrorAgent> 我们先设定一个本周可完成的小目标。最容易触发深夜点单的时间通常是什么时候?
+你> 晚上加班以后
+你> /done
+```
+
+输入 `/done`、`/quit` 或 `退出` 后,系统会综合本轮对话和已验证账单数据生成 Markdown 月报。输入 `/quests` 可以查看当前任务,输入 `/complete <quest_id>` 可以记录人工确认的任务完成情况。
+
+## 🎯 项目亮点
+
+- **数据与推理分工明确**:金额和统计由 Python 完成,大模型负责理解、解释、规划和表达。
+- **真实信号驱动行动**:消费人格和 Money Quest 来自账单中的实际行为特征。
+- **对话逐步推进**:MoneyMirrorAgent 通过观察、建议和追问引导用户,完成交流后再生成月报。
+
+## 📊 性能评估
+
+当前版本已完成以下本地验证:
+
+- 自动化测试:`28 passed`
+- 编译检查:`python -m compileall -q src main.py tests` 通过
+- CSV 导入、分类、Memory、统计、异常检测、预算、目标、Quest、Reflection 和对话流程均有测试覆盖
+- 已使用配置的 OpenAI 兼容模型完成完整 CLI 分析,并生成 JSON 事实快照和 Markdown 月报
+
+## 🔮 未来计划
+
+- [ ] 扩展更多银行、支付平台和记账软件的 CSV 字段映射
+- [ ] 支持跨月账单合并和更长周期的趋势比较
+- [ ] 增加更多可配置的成就和 Quest 进度事件
+- [ ] 增加脱敏导出和本地报告归档管理
+- [ ] 补充不同账单格式下的端到端回归样例
+
+## 🤝 贡献指南
+
+欢迎通过 Issue 或 Pull Request 提出改进建议。提交代码时请:
+
+1. 保持确定性计算与大模型推理职责分离;
+2. 为新增工具、Agent 或数据格式补充测试;
+3. 不提交 `.env`、API Key、SQLite 数据库和运行生成文件;
+4. 同步更新 README。
+
+## 📄 许可证
+
+本项目采用MIT许可证。
+
+## 👤 作者
+
+- GitHub: [@CoralGarden52](https://github.com/CoralGarden52)
+
+## 🙏 致谢
+
+感谢 Datawhale 社区和 Hello-Agents 项目提供的教程、框架与共创平台。

+ 66 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_01.csv

@@ -0,0 +1,66 @@
+日期,商户,金额,收支,备注
+2026-06-05 09:00,公司工资,7600,收入,六月工资到账
+2026-06-05 10:30,房东-六月房租,2200,支出,固定住房
+2026-06-06 08:20,地铁,4,支出,通勤
+2026-06-06 12:20,园区食堂,22,支出,午餐
+2026-06-06 22:48,饿了么-烧烤,58,支出,深夜外卖
+2026-06-07 15:30,星巴克,36,支出,咖啡
+2026-06-07 20:10,万达影院,68,支出,周末电影
+2026-06-08 08:15,地铁,4,支出,通勤
+2026-06-08 12:10,便利店,18,支出,零食
+2026-06-09 12:05,园区食堂,25,支出,午餐
+2026-06-10 21:45,淘宝-收纳,89,支出,生活购物
+2026-06-12 09:10,腾讯视频会员,25,支出,自动续费
+2026-06-12 12:25,园区食堂,23,支出,午餐
+2026-06-13 11:15,滴滴出行,32,支出,周末出行
+2026-06-13 16:30,奈雪的茶,29,支出,奶茶
+2026-06-14 19:00,健身房月卡,199,支出,运动
+2026-06-15 09:30,网易云音乐,18,支出,自动续费
+2026-06-15 12:10,园区食堂,24,支出,午餐
+2026-06-16 08:20,地铁,4,支出,通勤
+2026-06-16 22:55,美团外卖-炸鸡,46,支出,深夜外卖
+2026-06-18 12:10,园区食堂,26,支出,午餐
+2026-06-19 18:30,京东-耳机,399,支出,数码购物
+2026-06-20 14:00,线下书店,86,支出,技术书籍
+2026-06-20 21:00,Livehouse门票,180,支出,周末娱乐
+2026-06-22 08:20,地铁,4,支出,通勤
+2026-06-22 12:10,园区食堂,22,支出,午餐
+2026-06-24 22:35,饿了么-奶茶,31,支出,深夜外卖
+2026-06-25 12:20,园区食堂,24,支出,午餐
+2026-06-27 15:00,星巴克,34,支出,咖啡
+2026-06-28 18:20,超市,125,支出,日用品
+2026-07-05 09:00,公司工资,7600,收入,七月工资到账
+2026-07-05 10:20,房东-七月房租,2200,支出,固定住房
+2026-07-05 13:10,京东-电脑配件商城,1288,支出,显示器支架和配件
+2026-07-05 21:20,万达影院,75,支出,周末电影
+2026-07-06 08:20,地铁,4,支出,通勤
+2026-07-06 12:15,园区食堂,25,支出,午餐
+2026-07-06 22:42,美团外卖-火锅,76,支出,深夜外卖
+2026-07-07 08:20,地铁,4,支出,通勤
+2026-07-07 15:00,星巴克,38,支出,咖啡
+2026-07-08 12:15,园区食堂,23,支出,午餐
+2026-07-09 19:10,淘宝-夏装,266,支出,服饰购物
+2026-07-10 12:10,园区食堂,26,支出,午餐
+2026-07-12 09:10,腾讯视频会员,25,支出,自动续费
+2026-07-12 14:30,滴滴出行,35,支出,周末出行
+2026-07-12 20:00,演唱会门票,880,支出,周末娱乐
+2026-07-13 16:20,奈雪的茶,31,支出,奶茶
+2026-07-14 08:20,地铁,4,支出,通勤
+2026-07-14 12:15,园区食堂,24,支出,午餐
+2026-07-15 09:30,网易云音乐,18,支出,自动续费
+2026-07-15 22:50,饿了么-烧烤,61,支出,深夜外卖
+2026-07-16 12:10,园区食堂,27,支出,午餐
+2026-07-17 18:40,健身房月卡,199,支出,运动
+2026-07-18 11:00,线下书店,128,支出,设计课程书籍
+2026-07-18 21:30,剧本杀,168,支出,周末娱乐
+2026-07-19 14:00,星巴克,36,支出,咖啡
+2026-07-20 08:20,地铁,4,支出,通勤
+2026-07-20 12:12,便利店,22,支出,零食
+2026-07-21 22:36,美团外卖-炸鸡,56,支出,深夜外卖
+2026-07-22 12:10,园区食堂,25,支出,午餐
+2026-07-24 19:20,Steam游戏平台,118,支出,游戏
+2026-07-25 12:10,园区食堂,23,支出,午餐
+2026-07-26 18:00,超市,146,支出,日用品
+2026-07-27 22:58,饿了么-奶茶,35,支出,深夜外卖
+2026-07-29 12:15,园区食堂,24,支出,午餐
+2026-07-30 18:10,京东-耳机,460,支出,数码购物

+ 18 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_02.csv

@@ -0,0 +1,18 @@
+日期,商户,金额,收支,备注
+2026-06-05 09:00,公司工资,7200,收入,六月工资到账
+2026-06-05 10:00,房东-六月房租,2200,支出,固定住房
+2026-06-08 12:30,健康餐厅,85,支出,午餐
+2026-06-11 12:30,健康餐厅,82,支出,午餐
+2026-06-15 08:20,地铁月票,120,支出,通勤
+2026-06-17 19:00,健身房月卡,199,支出,运动
+2026-06-20 14:00,技术书店,260,支出,学习资料
+2026-06-24 12:30,健康餐厅,86,支出,午餐
+2026-07-06 09:00,公司工资,7200,收入,七月工资到账
+2026-07-06 10:00,房东-七月房租,2200,支出,固定住房
+2026-07-08 12:30,健康餐厅,88,支出,午餐
+2026-07-11 12:30,健康餐厅,86,支出,午餐
+2026-07-14 08:20,地铁月票,120,支出,通勤
+2026-07-17 19:00,健身房月卡,199,支出,运动
+2026-07-19 14:00,设计课程平台,320,支出,在线课程
+2026-07-22 12:30,健康餐厅,90,支出,午餐
+2026-07-26 12:30,健康餐厅,87,支出,午餐

+ 16 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_03.csv

@@ -0,0 +1,16 @@
+日期,商户,金额,收支,备注
+2026-06-08 09:00,公司工资,6800,收入,六月工资到账
+2026-06-08 10:00,房东-六月房租,2100,支出,固定住房
+2026-06-13 15:00,万达影院,75,支出,周末电影
+2026-06-14 19:00,城市餐厅,180,支出,周末聚餐
+2026-06-20 16:00,线下书店,90,支出,周末阅读
+2026-06-22 08:20,地铁月票,120,支出,通勤
+2026-07-06 09:00,公司工资,6800,收入,七月工资到账
+2026-07-06 10:00,房东-七月房租,2100,支出,固定住房
+2026-07-11 14:30,独立咖啡馆,78,支出,周末咖啡
+2026-07-11 20:00,音乐节门票,360,支出,周末娱乐
+2026-07-12 13:00,城市餐厅,260,支出,周末聚餐
+2026-07-12 17:00,文创商场,420,支出,周末购物
+2026-07-18 15:00,万达影院,85,支出,周末电影
+2026-07-19 19:00,剧本杀,168,支出,周末娱乐
+2026-07-21 08:20,地铁月票,120,支出,通勤

+ 15 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_04.csv

@@ -0,0 +1,15 @@
+日期,商户,金额,收支,备注
+2026-06-08 09:00,公司工资,7600,收入,六月工资到账
+2026-06-08 10:00,房东-六月房租,2200,支出,固定住房
+2026-06-10 19:00,京东-工作设备,980,支出,工作配件
+2026-06-11 18:30,天猫-夏装,360,支出,服饰购物
+2026-06-12 12:30,园区餐厅,72,支出,午餐
+2026-06-18 08:20,地铁月票,120,支出,通勤
+2026-07-06 09:00,公司工资,7600,收入,七月工资到账
+2026-07-06 10:00,房东-七月房租,2200,支出,固定住房
+2026-07-06 19:20,京东-显示器支架,1080,支出,数码购物
+2026-07-07 18:40,天猫-夏装,480,支出,服饰购物
+2026-07-08 20:10,淘宝-收纳用品,260,支出,购物冲动
+2026-07-10 12:30,园区餐厅,75,支出,午餐
+2026-07-16 08:20,地铁月票,120,支出,通勤
+2026-07-23 19:00,健身房月卡,199,支出,运动

+ 17 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/data/sample_05.csv

@@ -0,0 +1,17 @@
+日期,商户,金额,收支,备注
+2026-05-08 09:00,公司工资,6500,收入,五月工资到账
+2026-05-08 10:00,房东-五月房租,2000,支出,固定住房
+2026-05-12 09:10,腾讯视频会员,25,支出,自动续费
+2026-05-15 09:30,网易云音乐,18,支出,自动续费
+2026-05-20 12:30,园区餐厅,78,支出,午餐
+2026-06-08 09:00,公司工资,6500,收入,六月工资到账
+2026-06-08 10:00,房东-六月房租,2000,支出,固定住房
+2026-06-12 09:10,腾讯视频会员,25,支出,自动续费
+2026-06-15 09:30,网易云音乐,18,支出,自动续费
+2026-06-20 12:30,园区餐厅,80,支出,午餐
+2026-07-06 09:00,公司工资,6500,收入,七月工资到账
+2026-07-06 10:00,房东-七月房租,2000,支出,固定住房
+2026-07-12 09:10,腾讯视频会员,25,支出,自动续费
+2026-07-15 09:30,网易云音乐,18,支出,自动续费
+2026-07-21 12:30,园区餐厅,82,支出,午餐
+2026-07-23 08:20,地铁月票,120,支出,通勤

+ 200 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/main.py

@@ -0,0 +1,200 @@
+"""CLI entry point for MoneyMirrorAgent."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import logging
+import os
+import sys
+from datetime import date
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from src.agents.coordinator import MoneyMirrorCoordinator
+from src.agents.runtime import LLMCallError, RuntimeConfigurationError
+from src.models import Goal
+
+ROOT = Path(__file__).resolve().parent
+
+
+def _parse_goal(specification: str) -> Goal:
+    """Parse a repeatable CLI financial goal without inventing user data.
+
+    Format: title|type|target_amount|current_amount|deadline
+    For category_limit, append: |category|monthly_limit
+    """
+    fields = [field.strip() for field in specification.split("|")]
+    if len(fields) not in {5, 7}:
+        raise ValueError(
+            "格式为 标题|类型|目标金额|当前金额|截止日期;类别限额目标追加 |类别|月限额"
+        )
+    title, goal_type, target_raw, current_raw, deadline = fields[:5]
+    if not title:
+        raise ValueError("目标标题不能为空")
+    if goal_type not in {"savings", "travel", "category_limit"}:
+        raise ValueError("目标类型必须是 savings、travel 或 category_limit")
+    try:
+        target_amount = float(target_raw)
+        current_amount = float(current_raw)
+        date.fromisoformat(deadline)
+    except ValueError as exc:
+        raise ValueError("目标金额必须是数字,截止日期必须为 YYYY-MM-DD") from exc
+    if target_amount <= 0 or current_amount < 0:
+        raise ValueError("目标金额必须大于 0,当前金额不能小于 0")
+
+    category: str | None = None
+    monthly_limit: float | None = None
+    if goal_type == "category_limit":
+        if len(fields) != 7 or not fields[5]:
+            raise ValueError("category_limit 需要追加类别和月限额")
+        category = fields[5]
+        try:
+            monthly_limit = float(fields[6])
+        except ValueError as exc:
+            raise ValueError("类别月限额必须是数字") from exc
+        if monthly_limit <= 0:
+            raise ValueError("类别月限额必须大于 0")
+    elif len(fields) != 5:
+        raise ValueError("只有 category_limit 可以追加类别和月限额")
+
+    digest = hashlib.sha256(specification.encode("utf-8")).hexdigest()[:12]
+    return Goal(
+        goal_id=f"cli_{digest}",
+        title=title,
+        goal_type=goal_type,
+        target_amount=target_amount,
+        current_amount=current_amount,
+        deadline=deadline,
+        category=category,
+        monthly_limit=monthly_limit,
+    )
+
+def parser() -> argparse.ArgumentParser:
+    command = argparse.ArgumentParser(description="MoneyMirrorAgent: 智能理财助手")
+    command.add_argument("--interactive", action="store_true", help="分析账单后进入 LLM 引导对话,输入 /done 后生成最终 Markdown")
+    command.add_argument("--csv", type=Path, required=True, metavar="账单CSV", help="要分析的 CSV 账单路径(必填)")
+    command.add_argument("--month", help="指定分析月份,例如 2026-07")
+    command.add_argument("--db", type=Path, default=ROOT / "outputs" / "moneymirror.db", help="SQLite Memory 路径")
+    command.add_argument("--output-dir", type=Path, default=ROOT / "outputs", help="报告输出目录")
+    command.add_argument("--reset", action="store_true", help="删除现有 SQLite Memory 后运行")
+    command.add_argument("--correct", metavar="商户:类别", action="append", default=[], help="写入商户分类纠正,可重复指定")
+    command.add_argument(
+        "--goal",
+        action="append",
+        default=[],
+        metavar="标题|类型|目标金额|当前金额|截止日期[|类别|月限额]",
+        help="添加财务目标;可重复。类型为 savings、travel 或 category_limit",
+    )
+    return command
+
+
+def _print_quest_board(report) -> None:
+    """Show the RPG task board in terminals without a graphical UI."""
+    print("\n🎮 当前 Money Quest:")
+    for quest in report.quests:
+        progress = f"{quest.progress:g}/{quest.target:g}{quest.unit}"
+        status = "✅ 已完成" if quest.status == "completed" else "🔄 进行中"
+        print(f"- [{quest.quest_id}] {quest.title} · {progress} · {status} · +{quest.exp_reward} EXP")
+        print(f"  {quest.description}")
+        print(f"  证据:{quest.evidence}")
+
+
+def _interactive(coordinator: MoneyMirrorCoordinator, report, output_dir: Path, csv_path: Path) -> None:
+    history: list[dict[str, str]] = []
+    _print_quest_board(report)
+    opening = coordinator.conversation_agent.opening(report)
+    history.append({"role": "assistant", "content": opening})
+    print("\n🧭 MoneyMirrorAgent 引导:")
+    print(opening)
+    print(
+        "\n直接输入你的回答即可;/quests 查看任务;"
+        "/complete <quest_id> [备注] 确认订阅检查等人工任务;"
+        "/done、/quit 或 退出 结束对话并生成 Markdown 月报。"
+    )
+    while True:
+        question = input("\n你> ").strip()
+        lowered = question.lower()
+        if lowered in {"/done", "/quit", "退出"}:
+            break
+        if not question:
+            continue
+        if lowered == "/quests":
+            _print_quest_board(report)
+            continue
+        if lowered.startswith("/complete "):
+            parts = question.split(maxsplit=2)
+            if len(parts) < 2:
+                print("用法:/complete <quest_id> [备注]")
+                continue
+            try:
+                result = coordinator.complete_quest(report, parts[1], parts[2] if len(parts) > 2 else "")
+                print(f"✅ 已确认 Quest,获得 {result['gained_exp']} EXP;当前 Lv.{result['level']} / EXP {result['total_exp']}。")
+            except ValueError as exc:
+                print(f"⚠️ {exc}")
+            continue
+        history.append({"role": "user", "content": question})
+        print("\nMoneyMirrorAgent> ", end="", flush=True)
+        chunks = coordinator.runtime.stream_user_guidance(
+            question,
+            coordinator.conversation_agent.payload(report),
+            history,
+        )
+        answer_parts: list[str] = []
+        for chunk in chunks:
+            print(chunk, end="", flush=True)
+            answer_parts.append(chunk)
+        print()
+        history.append({"role": "assistant", "content": "".join(answer_parts).strip()})
+    json_path, markdown_path = coordinator.write_outputs(report, output_dir, history, source_csv=csv_path)
+    print(f"\n✅ 对话结束,LLM Markdown 报告:{markdown_path}")
+    print(f"📦 JSON 事实快照:{json_path}")
+
+
+def main() -> int:
+    load_dotenv(ROOT / ".env")
+    logging.basicConfig(level=getattr(logging, os.getenv("LOG_LEVEL", "INFO").upper(), logging.INFO), format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    argument_parser = parser()
+    args = argument_parser.parse_args()
+    try:
+        goals = [_parse_goal(specification) for specification in args.goal]
+    except ValueError as exc:
+        argument_parser.error(f"--goal {exc}")
+    csv_path = args.csv
+    print(f"账单文件: {csv_path}")
+    if args.reset and args.db.exists():
+        args.db.unlink()
+    coordinator = None
+    try:
+        coordinator = MoneyMirrorCoordinator(args.db, os.getenv("MONEYMIRROR_USER_ID", "local_user"))
+        for correction in args.correct:
+            if ":" not in correction:
+                argument_parser.error("--correct 格式必须为 商户:类别,例如 星巴克:餐饮")
+            merchant, category = correction.split(":", 1)
+            coordinator.correct_merchant_category(merchant, category)
+        for goal in goals:
+            coordinator.add_goal(goal)
+        report = coordinator.analyze_csv(csv_path, args.month)
+        if args.interactive:
+            _interactive(coordinator, report, args.output_dir, csv_path)
+        else:
+            json_path, markdown_path = coordinator.write_outputs(report, args.output_dir, source_csv=csv_path)
+            print("\nMoneyMirrorAgent 完整分析已完成")
+            print(f"分析月份: {report.month}")
+            print(f"收入 ¥{report.summary['income']:.2f} | 支出 ¥{report.summary['expense']:.2f} | 结余 ¥{report.summary['balance']:.2f} | 储蓄率 {report.summary['savings_rate']:.2f}%")
+            print(f"消费人格: {report.persona['primary']}")
+            print(f"异常消费: {len(report.anomalies)} 笔 | Quest: {len(report.quests)} 个 | 反思: 已生成")
+            print(f"JSON 报告: {json_path}")
+            print(f"Markdown 报告(LLM 生成): {markdown_path}")
+        return 0
+    except (OSError, ValueError, RuntimeConfigurationError, LLMCallError) as exc:
+        print(f"MoneyMirrorAgent 运行失败: {exc}", file=sys.stderr)
+        return 2
+    finally:
+        if coordinator is not None:
+            coordinator.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

+ 0 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/.gitkeep


+ 738 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/money_mirror_report.json

@@ -0,0 +1,738 @@
+{
+  "user_id": "demo_user",
+  "month": "2026-07",
+  "transactions": [
+    {
+      "transaction_id": "0a8479aa1bf2ef78",
+      "occurred_at": "2026-06-05T09:00",
+      "merchant": "公司工资",
+      "amount": 7200.0,
+      "kind": "income",
+      "category": "收入",
+      "note": "六月工资到账",
+      "source": "data/sample_02.csv",
+      "category_confidence": 1.0
+    },
+    {
+      "transaction_id": "64cb81ba471c6d1f",
+      "occurred_at": "2026-06-05T10:00",
+      "merchant": "房东-六月房租",
+      "amount": 2200.0,
+      "kind": "expense",
+      "category": "住房",
+      "note": "固定住房",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "c391b26ef3f71e94",
+      "occurred_at": "2026-06-08T12:30",
+      "merchant": "健康餐厅",
+      "amount": 85.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "9766268fdf6d4080",
+      "occurred_at": "2026-06-11T12:30",
+      "merchant": "健康餐厅",
+      "amount": 82.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "6232161e1f3d0d5c",
+      "occurred_at": "2026-06-15T08:20",
+      "merchant": "地铁月票",
+      "amount": 120.0,
+      "kind": "expense",
+      "category": "交通",
+      "note": "通勤",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "89f212aa90c6519f",
+      "occurred_at": "2026-06-17T19:00",
+      "merchant": "健身房月卡",
+      "amount": 199.0,
+      "kind": "expense",
+      "category": "健身",
+      "note": "运动",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "84813fdda4faadbe",
+      "occurred_at": "2026-06-20T14:00",
+      "merchant": "技术书店",
+      "amount": 260.0,
+      "kind": "expense",
+      "category": "学习",
+      "note": "学习资料",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "ae7df570d553dd41",
+      "occurred_at": "2026-06-24T12:30",
+      "merchant": "健康餐厅",
+      "amount": 86.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "268905b1a38ce794",
+      "occurred_at": "2026-07-06T09:00",
+      "merchant": "公司工资",
+      "amount": 7200.0,
+      "kind": "income",
+      "category": "收入",
+      "note": "七月工资到账",
+      "source": "data/sample_02.csv",
+      "category_confidence": 1.0
+    },
+    {
+      "transaction_id": "de52201c359d8c00",
+      "occurred_at": "2026-07-06T10:00",
+      "merchant": "房东-七月房租",
+      "amount": 2200.0,
+      "kind": "expense",
+      "category": "住房",
+      "note": "固定住房",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "bd82c407edac7b33",
+      "occurred_at": "2026-07-08T12:30",
+      "merchant": "健康餐厅",
+      "amount": 88.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "866f8d4cdb8a731d",
+      "occurred_at": "2026-07-11T12:30",
+      "merchant": "健康餐厅",
+      "amount": 86.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "df2b4e3eaf97936e",
+      "occurred_at": "2026-07-14T08:20",
+      "merchant": "地铁月票",
+      "amount": 120.0,
+      "kind": "expense",
+      "category": "交通",
+      "note": "通勤",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "15edf8bb951e26d8",
+      "occurred_at": "2026-07-17T19:00",
+      "merchant": "健身房月卡",
+      "amount": 199.0,
+      "kind": "expense",
+      "category": "健身",
+      "note": "运动",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "a026850dbf09bb4e",
+      "occurred_at": "2026-07-19T14:00",
+      "merchant": "设计课程平台",
+      "amount": 320.0,
+      "kind": "expense",
+      "category": "学习",
+      "note": "在线课程",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "7671c327ace86a54",
+      "occurred_at": "2026-07-22T12:30",
+      "merchant": "健康餐厅",
+      "amount": 90.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "e1fbe106ef487e37",
+      "occurred_at": "2026-07-26T12:30",
+      "merchant": "健康餐厅",
+      "amount": 87.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    }
+  ],
+  "summary": {
+    "transaction_count": 9,
+    "income": 7200.0,
+    "expense": 3190.0,
+    "balance": 4010.0,
+    "savings_rate": 55.69,
+    "average_expense": 398.75,
+    "active_days": 8
+  },
+  "category_breakdown": {
+    "住房": 2200.0,
+    "餐饮": 351.0,
+    "学习": 320.0,
+    "健身": 199.0,
+    "交通": 120.0
+  },
+  "trends": {
+    "daily": {
+      "2026-07-06": 2200.0,
+      "2026-07-08": 88.0,
+      "2026-07-11": 86.0,
+      "2026-07-14": 120.0,
+      "2026-07-17": 199.0,
+      "2026-07-19": 320.0,
+      "2026-07-22": 90.0,
+      "2026-07-26": 87.0
+    },
+    "weekly": {
+      "2026-07-06": 2374.0,
+      "2026-07-13": 639.0,
+      "2026-07-20": 177.0
+    },
+    "monthly": {
+      "2026-07": 3190.0
+    }
+  },
+  "patterns": {
+    "late_night": {
+      "count": 0,
+      "amount": 0,
+      "share": 0.0
+    },
+    "weekend": {
+      "count": 3,
+      "amount": 493.0,
+      "share": 15.45
+    },
+    "payday_window": {
+      "count": 2,
+      "amount": 2288.0,
+      "share": 71.72
+    },
+    "frequent_small": {
+      "count": 0,
+      "amount": 0,
+      "average": 0.0
+    },
+    "category_spikes": {
+      "住房": 2200.0,
+      "餐饮": 351.0,
+      "学习": 320.0,
+      "健身": 199.0,
+      "交通": 120.0
+    }
+  },
+  "anomalies": [],
+  "subscriptions": [
+    {
+      "merchant": "健身房月卡",
+      "months": [
+        "2026-06",
+        "2026-07"
+      ],
+      "occurrences": 2,
+      "typical_amount": 199.0,
+      "category": "健身",
+      "low_value_flag": false,
+      "message": "连续多月的会员或续费扣款,建议检查是否仍有使用价值"
+    }
+  ],
+  "persona": {
+    "primary": "稳健规划玩家",
+    "archetype": "steady_planner",
+    "score": 85.0,
+    "confidence": 0.85,
+    "labels": [
+      "稳健规划玩家",
+      "学习投入玩家"
+    ],
+    "secondary": [
+      {
+        "archetype": "learning_investor",
+        "name": "学习投入玩家",
+        "score": 59.49,
+        "confidence": 0.59,
+        "evidence": [
+          "学习消费占比 10.0%",
+          "有学习消费的月份数 2"
+        ]
+      }
+    ],
+    "evidence": [
+      "储蓄率 55.7%",
+      "工资到账后消费占比 71.7%",
+      "深夜消费占比 0.0%"
+    ],
+    "feature_vector": {
+      "night": 0.0,
+      "weekend": 36.25,
+      "frequent_small": 0.0,
+      "flexible_spend": 0.0,
+      "food": 27.51,
+      "subscription": 11.67,
+      "learning": 62.66,
+      "learning_consistency": 50.0,
+      "savings": 100.0,
+      "planning": 75.0,
+      "planning_inverse": 25.0,
+      "impulse": 30.0
+    },
+    "narrative": "你是“稳健规划玩家”,可以叫“月光绝缘体”——稳定原型匹配分 85.0,生活节奏稳到像自带一张消费蓝图。数据也印证:储蓄率 55.7%,工资到账后的消费占 71.7%,深夜消费 0.0%,说明你习惯先把钱和计划安排明白,再慢慢享受生活。"
+  },
+  "budget": {
+    "month": "2026-07",
+    "categories": {
+      "交通": {
+        "bucket": "necessary",
+        "historical_median": 120.0,
+        "recommended": 116.4,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "住房": {
+        "bucket": "fixed",
+        "historical_median": 2200.0,
+        "recommended": 2200.0,
+        "rationale": "固定支出,原则上不做大幅削减"
+      },
+      "健身": {
+        "bucket": "necessary",
+        "historical_median": 199.0,
+        "recommended": 193.03,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "学习": {
+        "bucket": "necessary",
+        "historical_median": 260.0,
+        "recommended": 252.2,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "餐饮": {
+        "bucket": "necessary",
+        "historical_median": 253.0,
+        "recommended": 245.41,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      }
+    },
+    "recommended_total": 3007.04,
+    "historical_months": [
+      "2026-06"
+    ],
+    "principle": "基于历史中位数,固定支出不削减,必要/弹性/可选支出分层温和调整"
+  },
+  "goals": [],
+  "quests": [
+    {
+      "quest_id": "subscription_hunter",
+      "title": "订阅大扫除",
+      "description": "发现一笔疑似连续扣费,可能已经悄悄溜走好久啦。咱们一起来翻翻账本,看看它是不是还在为你发光发热,还是该和它说再见咯。\n🧩 小提示:打开订阅列表,找出那笔疑似扣费,确认自己是否还在用;不用的就痛痛快快取消掉,让钱包松口气。\n🎯 已核验目标:检查 1 项疑似连续扣费,并仅保留仍会使用的服务。",
+      "quest_type": "subscription_review",
+      "target": 1.0,
+      "progress": 0.0,
+      "unit": "项",
+      "exp_reward": 90,
+      "status": "active",
+      "evidence": "需要用户在后续 CLI 引导中确认完成"
+    },
+    {
+      "quest_id": "learning_loot_log",
+      "title": "学习小侦探",
+      "description": "有一笔学习相关的开销,但不知道它有没有真正帮到你。像小侦探一样去查一查,看看这门课或资料到底有没有被翻牌,顺便给自己定个下次学习的小约定。\n🧩 小提示:找出那笔学习支出对应的服务,记录今天有没有使用它,并顺手在日历上标一个下次使用的时间点,让每一分钱都花在成长上。\n🎯 已核验目标:记录 1 次学习服务是否真正被使用,并标注下次使用时间。",
+      "quest_type": "manual",
+      "target": 1.0,
+      "progress": 0,
+      "unit": "次",
+      "exp_reward": 70,
+      "status": "active",
+      "evidence": "等待用户更新进度"
+    }
+  ],
+  "achievements": [
+    {
+      "key": "savings_rate_20",
+      "title": "储蓄率破 20%",
+      "description": "储蓄率首次达到或超过 20%。",
+      "unlocked": true
+    },
+    {
+      "key": "zero_spend_start",
+      "title": "零消费日初体验",
+      "description": "完成至少一个零消费日。",
+      "unlocked": false
+    },
+    {
+      "key": "quest_ready",
+      "title": "任务上线",
+      "description": "已生成基于真实账单的 Money Quest。",
+      "unlocked": true
+    },
+    {
+      "key": "late_night_awareness",
+      "title": "深夜雷达启动",
+      "description": "已识别深夜消费行为并生成应对任务。",
+      "unlocked": false
+    },
+    {
+      "key": "zero_spend_streak_3",
+      "title": "三日无消费连击",
+      "description": "连续 3 天没有支出记录。",
+      "unlocked": true
+    }
+  ],
+  "gamification": {
+    "level": 1,
+    "total_exp": 0,
+    "exp_gained_this_cycle": 0,
+    "current_streak_days": 3,
+    "longest_streak_days": 3
+  },
+  "reflection": {
+    "month": "2026-07",
+    "previous_month": "2026-06",
+    "has_previous_snapshot": true,
+    "budget_deviations": [
+      {
+        "category": "交通",
+        "planned": 116.4,
+        "actual": 120.0,
+        "difference": 3.6,
+        "on_budget": false
+      },
+      {
+        "category": "住房",
+        "planned": 2200.0,
+        "actual": 2200.0,
+        "difference": 0.0,
+        "on_budget": true
+      },
+      {
+        "category": "健身",
+        "planned": 193.03,
+        "actual": 199.0,
+        "difference": 5.97,
+        "on_budget": false
+      },
+      {
+        "category": "学习",
+        "planned": 252.2,
+        "actual": 320.0,
+        "difference": 67.8,
+        "on_budget": false
+      },
+      {
+        "category": "餐饮",
+        "planned": 245.41,
+        "actual": 351.0,
+        "difference": 105.59,
+        "on_budget": false
+      }
+    ],
+    "quest_completion": {
+      "completed": 0,
+      "total": 2
+    },
+    "goal_progress": {},
+    "effective": [
+      "预算和任务均基于实际账单计算"
+    ],
+    "needs_adjustment": [
+      "餐饮",
+      "学习",
+      "健身",
+      "交通"
+    ],
+    "next_strategy": [
+      "优先为 餐饮 保留明确额度,而不是一刀切禁止消费。",
+      "下阶段只保留 2 个可执行任务,降低任务负担。"
+    ],
+    "next_cycle_month": "2026-08",
+    "next_cycle_budget": {
+      "source": "monthly_reflection",
+      "categories": {
+        "交通": {
+          "bucket": "necessary",
+          "historical_median": 120.0,
+          "recommended": 126.0,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "住房": {
+          "bucket": "fixed",
+          "historical_median": 2200.0,
+          "recommended": 2200.0,
+          "rationale": "固定支出,原则上不做大幅削减"
+        },
+        "健身": {
+          "bucket": "necessary",
+          "historical_median": 199.0,
+          "recommended": 208.95,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "学习": {
+          "bucket": "necessary",
+          "historical_median": 260.0,
+          "recommended": 336.0,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "餐饮": {
+          "bucket": "necessary",
+          "historical_median": 253.0,
+          "recommended": 368.12,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        }
+      }
+    },
+    "next_cycle_quests": [
+      {
+        "quest_id": "carry_subscription_hunter",
+        "title": "延续:订阅大扫除",
+        "quest_type": "subscription_review",
+        "target": 1.0,
+        "unit": "项",
+        "exp_reward": 90,
+        "reason": "上周期未完成,Reflection 建议降低摩擦后继续"
+      },
+      {
+        "quest_id": "carry_learning_loot_log",
+        "title": "延续:学习小侦探",
+        "quest_type": "manual",
+        "target": 1.0,
+        "unit": "次",
+        "exp_reward": 70,
+        "reason": "上周期未完成,Reflection 建议降低摩擦后继续"
+      },
+      {
+        "quest_id": "reflection_餐饮",
+        "title": "餐饮缓冲预算挑战",
+        "quest_type": "category_limit",
+        "target": 368.12,
+        "unit": "餐饮",
+        "exp_reward": 100,
+        "reason": "根据本月最大预算偏差生成"
+      }
+    ],
+    "narrative": "按计划-实际-调整来看,本月储蓄率55.69%稳健,但餐饮(实际351元,超支105.59元)和学习(实际320元,超支67.8元)是主要失血点,且两项任务均未完成。下一周期先砍餐饮弹性支出、回归245.41元预算线,同时把学习花费与任务进度挂钩,避免“花钱未推进”。完成这2项任务前暂不开启新的非必要支出,下周期再检验调整效果。"
+  },
+  "agent_trace": [
+    {
+      "agent": "MoneyMirrorCoordinator",
+      "architecture": "Transaction → Pattern → Persona → Goal → Quest → Reflection",
+      "runtime": {
+        "available": true,
+        "enabled": true,
+        "reason": "已启用 Hello-Agents + OpenAI 兼容 LLM:deepseek-v4-flash",
+        "registry_name": "HelloAgents ToolRegistry (8 MoneyMirror tools)",
+        "paradigms": [
+          "ReActAgent",
+          "PlanSolveAgent",
+          "ReflectionAgent",
+          "Context Engineering"
+        ],
+        "registered_tools": [
+          "CSVImportTool",
+          "TransactionCategoryTool",
+          "StatisticsTool",
+          "AnomalyDetectionTool",
+          "BudgetCalculatorTool",
+          "GoalProjectionTool",
+          "SubscriptionDetectorTool",
+          "QuestProgressTool"
+        ],
+        "provider": "OpenAI-compatible",
+        "model": "deepseek-v4-flash",
+        "base_url": "https://api.deepseek.com"
+      }
+    },
+    {
+      "agent": "TransactionAgent",
+      "paradigm": "ReActAgent-style: inspect transaction → consult memory/rules → resolve only uncertainty",
+      "classification_sources": {
+        "income_rule": 2,
+        "keyword_rule": 15
+      }
+    },
+    {
+      "agent": "PatternAgent",
+      "paradigm": "PlanAndSolveAgent-style: plan metrics → call statistical tools → return evidence",
+      "tools": [
+        "StatisticsTool",
+        "AnomalyDetectionTool",
+        "SubscriptionDetectorTool"
+      ],
+      "evidence": {
+        "late_night_count": 0,
+        "anomaly_count": 0,
+        "subscription_count": 1
+      },
+      "planning_note": "下一步应把唯一订阅项作为消费模式解读重点,同时确认夜间消费与异常项均为0,无需额外排查。"
+    },
+    {
+      "agent": "PersonaAgent",
+      "paradigm": "Feature vector → configurable scoring → evidence validation → LLM narrative",
+      "config_path": "/home/nyc/hello-agents/Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/config/personas.json",
+      "grounded_metrics": {
+        "savings_rate": 55.69,
+        "late_night_share": 0.0,
+        "late_night_count": 0,
+        "weekend_share": 15.45,
+        "weekend_count": 3,
+        "payday_share": 71.72,
+        "frequent_small_count": 0,
+        "frequent_small_share": 0.0,
+        "food_share": 11.0,
+        "flexible_spend_share": 0.0,
+        "subscription_share": 0.0,
+        "subscription_count": 1,
+        "learning_share": 10.03,
+        "learning_active_months": 2,
+        "impulse": 30.0
+      },
+      "feature_vector": {
+        "night": 0.0,
+        "weekend": 36.25,
+        "frequent_small": 0.0,
+        "flexible_spend": 0.0,
+        "food": 27.51,
+        "subscription": 11.67,
+        "learning": 62.66,
+        "learning_consistency": 50.0,
+        "savings": 100.0,
+        "planning": 75.0,
+        "planning_inverse": 25.0,
+        "impulse": 30.0
+      },
+      "candidates": [
+        {
+          "archetype": "steady_planner",
+          "name": "稳健规划玩家",
+          "score": 85.0,
+          "evidence_valid": true
+        },
+        {
+          "archetype": "learning_investor",
+          "name": "学习投入玩家",
+          "score": 59.49,
+          "evidence_valid": true
+        },
+        {
+          "archetype": "weekend_experience",
+          "name": "周末体验玩家",
+          "score": 23.56,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "subscription_collector",
+          "name": "数字订阅整理师",
+          "score": 14.34,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "frequent_small_spend",
+          "name": "高频小额行动派",
+          "score": 10.13,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "late_night_focus",
+          "name": "夜行消费探索者",
+          "score": 7.5,
+          "evidence_valid": false
+        }
+      ],
+      "llm_role": "仅生成年轻化解释,不决定人格原型、分数或证据"
+    },
+    {
+      "agent": "GoalAgent",
+      "paradigm": "PlanAndSolveAgent-style goal feasibility projection",
+      "tools": [
+        "GoalProjectionTool"
+      ],
+      "goal_count": 0,
+      "planning_note": "由于当前没有已验证的工具输出可引用,无法给出具体金额;一般做法是:将目标投影与当前实际值的差额,按剩余月份分解为每月需执行的可操作储蓄额,并绑定到发薪日自动转账或支出限额规则上,作为下一步的具体行动。"
+    },
+    {
+      "agent": "QuestAgent",
+      "paradigm": "规则发现真实信号 → PlanSolveAgent 动态编排 → Python 强校验与进度计算",
+      "tools": [
+        "StatisticsTool",
+        "BudgetCalculatorTool",
+        "SubscriptionDetectorTool",
+        "QuestProgressTool"
+      ],
+      "signal_catalog": [
+        {
+          "signal_id": "subscriptions",
+          "priority": "required",
+          "verified_observation": "发现 1 项疑似连续扣费。",
+          "locked_constraint": "检查 1 项疑似连续扣费,并仅保留仍会使用的服务。",
+          "completion_source": "用户 CLI 确认后由 SQLite Memory 记录"
+        },
+        {
+          "signal_id": "learning_followthrough",
+          "priority": "optional",
+          "verified_observation": "学习类支出为 ¥320.00,占本月支出 10.03%。",
+          "locked_constraint": "记录 1 次学习服务是否真正被使用,并标注下次使用时间。",
+          "completion_source": "用户 CLI 确认后由 SQLite Memory 记录"
+        }
+      ],
+      "llm_orchestration": {
+        "candidate_count": 2,
+        "accepted_signal_ids": [
+          "subscriptions",
+          "learning_followthrough"
+        ],
+        "validation": {
+          "attempts": 1,
+          "repaired": false,
+          "rejected": []
+        },
+        "numeric_authority": "Python only: target / progress / EXP / status are derived from locked blueprints and QuestProgressTool."
+      },
+      "quest_evidence": [
+        "需要用户在后续 CLI 引导中确认完成",
+        "等待用户更新进度"
+      ]
+    },
+    {
+      "agent": "ReflectionAgent",
+      "paradigm": "ReflectionAgent-style: plan → actual → deviation → adjustment",
+      "context_sources": [
+        "SQLiteMemory: previous snapshot",
+        "budget",
+        "quest outcomes",
+        "goal projection"
+      ]
+    }
+  ]
+}

+ 196 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/money_mirror_report.md

@@ -0,0 +1,196 @@
+# 📊 MoneyMirror 月度报告 · 2026年7月
+
+> 你好呀,这个月你一共记了 9 笔账,收入 7200 元,支出 3190 元,结余 4010 元。整体来看,这是一份「稳中有惊喜」的账单。下面我们按 **计划 → 实际 → 调整** 的节奏,一起看看钱都去了哪里,以及下一步怎么走。
+
+---
+
+## 🪞 财务镜像
+
+| 指标 | 数值 |
+|------|------|
+| 月收入 | 7200 元 |
+| 月支出 | 3190 元 |
+| 月结余 | 4010 元 |
+| 储蓄率 | 55.69% |
+| 平均每日支出 | 398.75 元 |
+| 记账活跃天数 | 8 天 |
+
+**储蓄率 55.69%** 意味着你稳稳地把超过一半的收入留了下来,这是一个非常健康的信号。结余 4010 元,已为未来积累了一笔不错的空间。虽然支出笔数不多(9 笔),但每笔都有记录,说明你没有被零碎消费带跑。
+
+---
+
+## 🧾 消费分类与趋势
+
+这个月的支出分布如下:
+
+| 类别 | 金额 | 占比 |
+|------|------|------|
+| 住房 | 2200 元 | 约 68.97% |
+| 餐饮 | 351 元 | 约 11.00% |
+| 学习 | 320 元 | 约 10.03% |
+| 健身 | 199 元 | 约 6.24% |
+| 交通 | 120 元 | 约 3.76% |
+
+**周度趋势:**
+- 第 1 周(7/6 起):2374 元 —— 主要是住房等刚性支出
+- 第 2 周(7/13 起):639 元
+- 第 3 周(7/20 起):177 元
+
+明显能看出:月初是支出高峰,后面两周逐渐回落,第 3 周已经压缩到 177 元,说明你的消费自控力在月底表现得很好。
+
+---
+
+## 🧠 行为模式
+
+- **深夜消费:0 笔 / 0 元** ✅ 深夜购物冲动为零,非常克制!
+- **周末消费:3 笔 / 493 元,占 15.45%** —— 周末有放松,但没有失控。
+- **工资日窗口消费:2 笔 / 2288 元,占 71.72%** —— 到账后先把大头(住房、固定类)安排好,规划感很强。
+- **高频小额消费:无** —— 没有被碎钞机式的小额支出拖累。
+
+这些模式说明你是「先把钱安排好,再慢慢享受」的类型。
+
+---
+
+## ⚠️ 异常消费解释
+
+**未检测到异常消费。**
+
+简单说:这个月没有一笔支出明显「偏离剧情」。唯一值得留意的是**工资日当天消费占比较高(71.72%)**,但这更偏向「计划内集中支付」而不是冲动消费。第 3 周支出大幅下降(177 元),某种程度上也在给你的钱包做「主动降温」。
+
+---
+
+## 🧑‍🎤 消费人格:稳健规划玩家(匹配度 85.0)
+
+你被识别为 **「稳健规划玩家」**,可以叫「月光绝缘体」😎。数据也支持这个诊断:
+
+- 储蓄率 55.7%
+- 工资到账后消费占比 71.7%
+- 深夜消费占比 0.0%
+
+辅助人格是 **学习投入玩家(59.49)**:本月学习消费占比 10.0%,且有跨月学习消费记录,说明你在「自我成长」上愿意花钱,并且有连续性。
+
+> 简单说:你花得有条理,也愿意为成长投入。这个组合很有长久竞争力。
+
+---
+
+## 🔁 订阅提醒:健身房月卡
+
+我们在账单中发现:
+
+- **商户:健身房月卡**
+- 已连续扣费月份:2026-06、2026-07
+- 典型金额:199 元 / 月
+- 类别:健身
+
+**建议行动:** 检查一下最近是否还真的在使用这张卡。如果只是「心理安慰型续费」,可以考虑暂停或取消,每月能省出 199 元。这并不是说健身不好,而是要确认这笔钱是否真的创造了价值。
+
+---
+
+## 🎯 目标进度:暂无数据
+
+当前周期没有设定独立的结构化目标(goals 为空)。不过别担心——下面的预算和 Quest 就是在帮你建目标。
+
+---
+
+## 💰 动态预算:7 月复盘与 8 月预算
+
+### 7 月预算执行情况(计划 vs 实际)
+
+| 类别 | 计划值 | 实际值 | 偏差 |
+|------|--------|--------|------|
+| 交通 | 116.40 元 | 120 元 | +3.60 元 |
+| 住房 | 2200 元 | 2200 元 | 0 元 ✅ |
+| 健身 | 193.03 元 | 199 元 | +5.97 元 |
+| 学习 | 252.20 元 | 320 元 | +67.80 元 |
+| 餐饮 | 245.41 元 | 351 元 | +105.59 元 |
+
+**最大失血点是餐饮(+105.59 元)和学习(+67.80 元)**。住房完全在计划内,做得非常好。
+
+### 8 月推荐预算(基于 reflection 修正)
+
+| 类别 | 推荐值 | 说明 |
+|------|--------|------|
+| 住房 | 2200 元 | 固定支出,保持不变 |
+| 餐饮 | 368.12 元 | 增加缓冲,避免一刀切 |
+| 学习 | 336 元 | 适度上调,兼顾成长投入 |
+| 健身 | 208.95 元 | 微调缓冲 |
+| 交通 | 126 元 | 增加少量弹性 |
+
+**8 月推荐总预算:3007.04 元**。
+
+原则是:固定支出不削减,必要支出参考历史中位数并保留缓冲,不搞极端节流,让预算更「可执行」。
+
+---
+
+## 🎮 Money Quest(当前进行中)
+
+### 1. 订阅大扫除 🔍
+- 目标:检查 1 项疑似连续扣费,并仅保留仍会使用的服务
+- 进度:0 / 1
+- 奖励:90 EXP
+- 对应对象:健身房月卡
+
+### 2. 学习小侦探 🕵️
+- 目标:记录 1 次学习服务是否真正被使用,并标注下次使用时间
+- 进度:0 / 1
+- 奖励:70 EXP
+- 核心逻辑:让 320 元学习支出「花得明白」
+
+> 两项任务本月均未完成。下个周期会延续,并降低摩擦后再挑战。
+
+---
+
+## ⭐ 等级与成就
+
+**当前等级:Lv.1**,总经验 0,连续记账 3 天(最长 3 天)。
+
+已解锁成就:
+- ✅ 储蓄率破 20%(储蓄率首次 ≥20%)
+- ✅ 任务上线(已生成基于真实账单的 Money Quest)
+- ✅ 三日无消费连击(连续 3 天无支出记录)
+
+未解锁:
+- ❌ 零消费日初体验(尚未有完整零消费日)
+- ❌ 深夜雷达启动(尚未识别深夜消费行为)
+
+---
+
+## 🔁 月度 Reflection:计划 → 实际 → 调整
+
+**做得好的:**
+- 储蓄率 55.69%,比很多人的目标线高出一大截
+- 深夜消费为 0,未出现冲动夜购
+- 住房支出完全按预算执行,固定支出控制得非常稳
+
+**需要调整的:**
+- 餐饮超支 105.59 元,实际 351 元,是本月最大偏差
+- 学习超支 67.80 元,实际 320 元,且「花钱是否真的推进了学习」存疑
+- 两项 Quest 均未完成,说明「计划」和「执行」之间还有衔接缝隙
+
+**下阶段策略:**
+1. 优先为餐饮保留明确额度,而不是一刀切禁止消费 → 8 月餐饮预算放宽至 368.12 元
+2. 学习花费与任务进度挂钩,避免「花钱未推进」
+3. **完成这 2 项任务前,暂不开启新的非必要支出**
+
+---
+
+## 📋 下一周期行动清单(2026-08)
+
+1. ✅ 完成「订阅大扫除」:检查健身房月卡是否仍值得继续扣费,不常用就取消
+2. ✅ 完成「学习小侦探」:找出 320 元对应学习服务,记录使用情况,并设定下次使用时间
+3. ✅ 执行「餐饮缓冲预算挑战」:8 月餐饮目标控制在 368.12 元以内(奖励 EXP+100)
+4. 💡 8 月总预算控制在 3007.04 元内,尝试让每一笔钱都有归属
+5. 🎯 尝试创造至少 1 个「零消费日」,解锁对应成就
+6. 🔇 在完成上述两项任务前,不新增任何非必要订阅或课程
+
+---
+
+## 🛡️ 安全边界
+
+- 本报告所有数据均来自你本月的真实记账记录,以实际账单为准。
+- 预算建议基于历史数据和消费模式,实际执行时请结合真实生活需要灵活调整。
+- 如有任何大额或异常支出,请以你当前的真实财务状况为最高优先级,理性决策。
+
+---
+
+下个月见呀~你已经比 90% 的人更懂自己的钱了。继续加油,让每一分钱都花得明白、存得安心 🌱

+ 764 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_02_money_mirror_report.json

@@ -0,0 +1,764 @@
+{
+  "user_id": "demo_user",
+  "month": "2026-07",
+  "transactions": [
+    {
+      "transaction_id": "0a8479aa1bf2ef78",
+      "occurred_at": "2026-06-05T09:00",
+      "merchant": "公司工资",
+      "amount": 7200.0,
+      "kind": "income",
+      "category": "收入",
+      "note": "六月工资到账",
+      "source": "data/sample_02.csv",
+      "category_confidence": 1.0
+    },
+    {
+      "transaction_id": "64cb81ba471c6d1f",
+      "occurred_at": "2026-06-05T10:00",
+      "merchant": "房东-六月房租",
+      "amount": 2200.0,
+      "kind": "expense",
+      "category": "住房",
+      "note": "固定住房",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "c391b26ef3f71e94",
+      "occurred_at": "2026-06-08T12:30",
+      "merchant": "健康餐厅",
+      "amount": 85.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "9766268fdf6d4080",
+      "occurred_at": "2026-06-11T12:30",
+      "merchant": "健康餐厅",
+      "amount": 82.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "6232161e1f3d0d5c",
+      "occurred_at": "2026-06-15T08:20",
+      "merchant": "地铁月票",
+      "amount": 120.0,
+      "kind": "expense",
+      "category": "交通",
+      "note": "通勤",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "89f212aa90c6519f",
+      "occurred_at": "2026-06-17T19:00",
+      "merchant": "健身房月卡",
+      "amount": 199.0,
+      "kind": "expense",
+      "category": "健身",
+      "note": "运动",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "84813fdda4faadbe",
+      "occurred_at": "2026-06-20T14:00",
+      "merchant": "技术书店",
+      "amount": 260.0,
+      "kind": "expense",
+      "category": "学习",
+      "note": "学习资料",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "ae7df570d553dd41",
+      "occurred_at": "2026-06-24T12:30",
+      "merchant": "健康餐厅",
+      "amount": 86.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "268905b1a38ce794",
+      "occurred_at": "2026-07-06T09:00",
+      "merchant": "公司工资",
+      "amount": 7200.0,
+      "kind": "income",
+      "category": "收入",
+      "note": "七月工资到账",
+      "source": "data/sample_02.csv",
+      "category_confidence": 1.0
+    },
+    {
+      "transaction_id": "de52201c359d8c00",
+      "occurred_at": "2026-07-06T10:00",
+      "merchant": "房东-七月房租",
+      "amount": 2200.0,
+      "kind": "expense",
+      "category": "住房",
+      "note": "固定住房",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "bd82c407edac7b33",
+      "occurred_at": "2026-07-08T12:30",
+      "merchant": "健康餐厅",
+      "amount": 88.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "866f8d4cdb8a731d",
+      "occurred_at": "2026-07-11T12:30",
+      "merchant": "健康餐厅",
+      "amount": 86.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "df2b4e3eaf97936e",
+      "occurred_at": "2026-07-14T08:20",
+      "merchant": "地铁月票",
+      "amount": 120.0,
+      "kind": "expense",
+      "category": "交通",
+      "note": "通勤",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "15edf8bb951e26d8",
+      "occurred_at": "2026-07-17T19:00",
+      "merchant": "健身房月卡",
+      "amount": 199.0,
+      "kind": "expense",
+      "category": "健身",
+      "note": "运动",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "a026850dbf09bb4e",
+      "occurred_at": "2026-07-19T14:00",
+      "merchant": "设计课程平台",
+      "amount": 320.0,
+      "kind": "expense",
+      "category": "学习",
+      "note": "在线课程",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "7671c327ace86a54",
+      "occurred_at": "2026-07-22T12:30",
+      "merchant": "健康餐厅",
+      "amount": 90.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "e1fbe106ef487e37",
+      "occurred_at": "2026-07-26T12:30",
+      "merchant": "健康餐厅",
+      "amount": 87.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "午餐",
+      "source": "data/sample_02.csv",
+      "category_confidence": 0.92
+    }
+  ],
+  "summary": {
+    "transaction_count": 9,
+    "income": 7200.0,
+    "expense": 3190.0,
+    "balance": 4010.0,
+    "savings_rate": 55.69,
+    "average_expense": 398.75,
+    "active_days": 8
+  },
+  "category_breakdown": {
+    "住房": 2200.0,
+    "餐饮": 351.0,
+    "学习": 320.0,
+    "健身": 199.0,
+    "交通": 120.0
+  },
+  "trends": {
+    "daily": {
+      "2026-07-06": 2200.0,
+      "2026-07-08": 88.0,
+      "2026-07-11": 86.0,
+      "2026-07-14": 120.0,
+      "2026-07-17": 199.0,
+      "2026-07-19": 320.0,
+      "2026-07-22": 90.0,
+      "2026-07-26": 87.0
+    },
+    "weekly": {
+      "2026-07-06": 2374.0,
+      "2026-07-13": 639.0,
+      "2026-07-20": 177.0
+    },
+    "monthly": {
+      "2026-07": 3190.0
+    }
+  },
+  "patterns": {
+    "late_night": {
+      "count": 0,
+      "amount": 0,
+      "share": 0.0
+    },
+    "weekend": {
+      "count": 3,
+      "amount": 493.0,
+      "share": 15.45
+    },
+    "payday_window": {
+      "count": 2,
+      "amount": 2288.0,
+      "share": 71.72
+    },
+    "frequent_small": {
+      "count": 0,
+      "amount": 0,
+      "average": 0.0
+    },
+    "category_spikes": {
+      "住房": 2200.0,
+      "餐饮": 351.0,
+      "学习": 320.0,
+      "健身": 199.0,
+      "交通": 120.0
+    }
+  },
+  "anomalies": [],
+  "subscriptions": [
+    {
+      "merchant": "健身房月卡",
+      "months": [
+        "2026-06",
+        "2026-07"
+      ],
+      "occurrences": 2,
+      "typical_amount": 199.0,
+      "category": "健身",
+      "low_value_flag": false,
+      "message": "连续多月的会员或续费扣款,建议检查是否仍有使用价值"
+    }
+  ],
+  "persona": {
+    "primary": "稳健规划玩家",
+    "archetype": "steady_planner",
+    "score": 85.0,
+    "confidence": 0.85,
+    "labels": [
+      "稳健规划玩家",
+      "学习投入玩家"
+    ],
+    "secondary": [
+      {
+        "archetype": "learning_investor",
+        "name": "学习投入玩家",
+        "score": 59.49,
+        "confidence": 0.59,
+        "evidence": [
+          "学习消费占比 10.0%",
+          "有学习消费的月份数 2"
+        ]
+      }
+    ],
+    "evidence": [
+      "储蓄率 55.7%",
+      "工资到账后消费占比 71.7%",
+      "深夜消费占比 0.0%"
+    ],
+    "feature_vector": {
+      "night": 0.0,
+      "weekend": 36.25,
+      "frequent_small": 0.0,
+      "flexible_spend": 0.0,
+      "food": 27.51,
+      "subscription": 11.67,
+      "learning": 62.66,
+      "learning_consistency": 50.0,
+      "savings": 100.0,
+      "planning": 75.0,
+      "planning_inverse": 25.0,
+      "impulse": 30.0
+    },
+    "narrative": "你的匹配人格是**稳健规划玩家**(匹配分 85.0),简直像一位自带节奏感的「发薪日小管家」:储蓄率有 55.7%,而且 71.7% 的消费都集中在工资到账后——说明你习惯钱一到手就先按计划安排必要开销,剩下的安心存住,每一步都踩得很稳。\n\n深夜消费占比 0.0% 更是加分项:你几乎从不在深夜冲动下单,习惯在清醒时做决定,天黑了就让钱包和睡眠一起收工,这种「到点就稳」的自律,就是最温柔也最踏实的攒钱方式呀。"
+  },
+  "budget": {
+    "month": "2026-07",
+    "categories": {
+      "交通": {
+        "bucket": "necessary",
+        "historical_median": 120.0,
+        "recommended": 116.4,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "住房": {
+        "bucket": "fixed",
+        "historical_median": 2200.0,
+        "recommended": 2200.0,
+        "rationale": "固定支出,原则上不做大幅削减"
+      },
+      "健身": {
+        "bucket": "necessary",
+        "historical_median": 199.0,
+        "recommended": 193.03,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "学习": {
+        "bucket": "necessary",
+        "historical_median": 260.0,
+        "recommended": 252.2,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "餐饮": {
+        "bucket": "necessary",
+        "historical_median": 253.0,
+        "recommended": 245.41,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      }
+    },
+    "recommended_total": 3007.04,
+    "historical_months": [
+      "2026-06"
+    ],
+    "principle": "基于历史中位数,固定支出不削减,必要/弹性/可选支出分层温和调整"
+  },
+  "goals": [],
+  "quests": [
+    {
+      "quest_id": "subscription_hunter",
+      "title": "订阅大扫除",
+      "description": "好像有个小东西每月悄悄扣钱,像躲在角落的小怪兽。咱们一起找出它,看看还值不值得留下。\n🧩 小提示:打开支付记录,找出那个连续扣费的项目,问问自己还在用吗?不用就取消它吧。\n🎯 已核验目标:检查 1 项疑似连续扣费,并仅保留仍会使用的服务。",
+      "quest_type": "subscription_review",
+      "target": 1.0,
+      "progress": 0.0,
+      "unit": "项",
+      "exp_reward": 90,
+      "status": "active",
+      "evidence": "需要用户在后续 CLI 引导中确认完成"
+    },
+    {
+      "quest_id": "learning_loot_log",
+      "title": "学习小侦探",
+      "description": "你买了份学习服务,但它有没有真正帮到你呢?就像侦探一样追踪使用痕迹,给未来的自己留个提醒。\n🧩 小提示:回想一下最近一次打开学习服务是什么时候,把它记在心里,顺手定个下次使用的时间吧。\n🎯 已核验目标:记录 1 次学习服务是否真正被使用,并标注下次使用时间。",
+      "quest_type": "manual",
+      "target": 1.0,
+      "progress": 0,
+      "unit": "次",
+      "exp_reward": 70,
+      "status": "active",
+      "evidence": "等待用户更新进度"
+    }
+  ],
+  "achievements": [
+    {
+      "key": "savings_rate_20",
+      "title": "储蓄率破 20%",
+      "description": "储蓄率首次达到或超过 20%。",
+      "unlocked": true
+    },
+    {
+      "key": "zero_spend_start",
+      "title": "零消费日初体验",
+      "description": "完成至少一个零消费日。",
+      "unlocked": false
+    },
+    {
+      "key": "quest_ready",
+      "title": "任务上线",
+      "description": "已生成基于真实账单的 Money Quest。",
+      "unlocked": true
+    },
+    {
+      "key": "late_night_awareness",
+      "title": "深夜雷达启动",
+      "description": "已识别深夜消费行为并生成应对任务。",
+      "unlocked": false
+    },
+    {
+      "key": "zero_spend_streak_3",
+      "title": "三日无消费连击",
+      "description": "连续 3 天没有支出记录。",
+      "unlocked": true
+    }
+  ],
+  "gamification": {
+    "level": 1,
+    "total_exp": 0,
+    "exp_gained_this_cycle": 0,
+    "current_streak_days": 3,
+    "longest_streak_days": 3
+  },
+  "reflection": {
+    "month": "2026-07",
+    "previous_month": "2026-06",
+    "has_previous_snapshot": true,
+    "budget_deviations": [
+      {
+        "category": "交通",
+        "planned": 116.4,
+        "actual": 120.0,
+        "difference": 3.6,
+        "on_budget": false
+      },
+      {
+        "category": "住房",
+        "planned": 2200.0,
+        "actual": 2200.0,
+        "difference": 0.0,
+        "on_budget": true
+      },
+      {
+        "category": "健身",
+        "planned": 193.03,
+        "actual": 199.0,
+        "difference": 5.97,
+        "on_budget": false
+      },
+      {
+        "category": "学习",
+        "planned": 252.2,
+        "actual": 320.0,
+        "difference": 67.8,
+        "on_budget": false
+      },
+      {
+        "category": "餐饮",
+        "planned": 245.41,
+        "actual": 351.0,
+        "difference": 105.59,
+        "on_budget": false
+      }
+    ],
+    "quest_completion": {
+      "completed": 0,
+      "total": 2
+    },
+    "goal_progress": {},
+    "effective": [
+      "预算和任务均基于实际账单计算"
+    ],
+    "needs_adjustment": [
+      "餐饮",
+      "学习",
+      "健身",
+      "交通"
+    ],
+    "next_strategy": [
+      "优先为 餐饮 保留明确额度,而不是一刀切禁止消费。",
+      "下阶段只保留 2 个可执行任务,降低任务负担。"
+    ],
+    "next_cycle_month": "2026-08",
+    "next_cycle_budget": {
+      "source": "monthly_reflection",
+      "categories": {
+        "交通": {
+          "bucket": "necessary",
+          "historical_median": 120.0,
+          "recommended": 126.0,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "住房": {
+          "bucket": "fixed",
+          "historical_median": 2200.0,
+          "recommended": 2200.0,
+          "rationale": "固定支出,原则上不做大幅削减"
+        },
+        "健身": {
+          "bucket": "necessary",
+          "historical_median": 199.0,
+          "recommended": 208.95,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "学习": {
+          "bucket": "necessary",
+          "historical_median": 260.0,
+          "recommended": 336.0,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "餐饮": {
+          "bucket": "necessary",
+          "historical_median": 253.0,
+          "recommended": 368.12,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        }
+      }
+    },
+    "next_cycle_quests": [
+      {
+        "quest_id": "carry_subscription_hunter",
+        "title": "延续:订阅大扫除",
+        "quest_type": "subscription_review",
+        "target": 1.0,
+        "unit": "项",
+        "exp_reward": 90,
+        "reason": "上周期未完成,Reflection 建议降低摩擦后继续"
+      },
+      {
+        "quest_id": "carry_learning_loot_log",
+        "title": "延续:学习小侦探",
+        "quest_type": "manual",
+        "target": 1.0,
+        "unit": "次",
+        "exp_reward": 70,
+        "reason": "上周期未完成,Reflection 建议降低摩擦后继续"
+      },
+      {
+        "quest_id": "reflection_餐饮",
+        "title": "餐饮缓冲预算挑战",
+        "quest_type": "category_limit",
+        "target": 368.12,
+        "unit": "餐饮",
+        "exp_reward": 100,
+        "reason": "根据本月最大预算偏差生成"
+      }
+    ],
+    "narrative": "按“计划-实际-调整”来看,本月结余4010元、储蓄率55.69%表现稳健,但餐饮超支105.59元、学习超支67.8元是主要偏差,需优先收紧这两项预算;交通和健身小幅超支(3.6元、5.97元)可微调控制。下一步建议将餐饮预算下调约100元、学习预算下调约70元,并为未完成的2项任务设置每周检查点,避免下周期再次超支。"
+  },
+  "agent_trace": [
+    {
+      "agent": "MoneyMirrorCoordinator",
+      "architecture": "Transaction → Pattern → Persona → Goal → Quest → Reflection",
+      "runtime": {
+        "available": true,
+        "enabled": true,
+        "reason": "已启用 Hello-Agents + OpenAI 兼容 LLM:deepseek-v4-flash",
+        "registry_name": "HelloAgents ToolRegistry (8 MoneyMirror tools)",
+        "paradigms": [
+          "ReActAgent",
+          "PlanSolveAgent",
+          "ReflectionAgent",
+          "Context Engineering"
+        ],
+        "registered_tools": [
+          "CSVImportTool",
+          "TransactionCategoryTool",
+          "StatisticsTool",
+          "AnomalyDetectionTool",
+          "BudgetCalculatorTool",
+          "GoalProjectionTool",
+          "SubscriptionDetectorTool",
+          "QuestProgressTool"
+        ],
+        "provider": "OpenAI-compatible",
+        "model": "deepseek-v4-flash",
+        "base_url": "https://api.deepseek.com"
+      }
+    },
+    {
+      "agent": "TransactionAgent",
+      "paradigm": "ReActAgent-style: inspect transaction → consult memory/rules → resolve only uncertainty",
+      "classification_sources": {
+        "income_rule": 2,
+        "keyword_rule": 15
+      }
+    },
+    {
+      "agent": "PatternAgent",
+      "paradigm": "PlanAndSolveAgent-style: plan metrics → call statistical tools → return evidence",
+      "tools": [
+        "StatisticsTool",
+        "AnomalyDetectionTool",
+        "SubscriptionDetectorTool"
+      ],
+      "evidence": {
+        "late_night_count": 0,
+        "anomaly_count": 0,
+        "subscription_count": 1
+      },
+      "planning_note": "由于深夜消费与异常均为 0,且仅检出 1 项订阅,下一步应优先核对该订阅的账单周期与使用价值,以判断是否需要保留或取消。"
+    },
+    {
+      "agent": "PersonaAgent",
+      "paradigm": "Feature vector → configurable scoring → evidence validation → LLM narrative",
+      "config_path": "/home/nyc/hello-agents/Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/config/personas.json",
+      "grounded_metrics": {
+        "savings_rate": 55.69,
+        "late_night_share": 0.0,
+        "late_night_count": 0,
+        "weekend_share": 15.45,
+        "weekend_count": 3,
+        "payday_share": 71.72,
+        "frequent_small_count": 0,
+        "frequent_small_share": 0.0,
+        "food_share": 11.0,
+        "flexible_spend_share": 0.0,
+        "subscription_share": 0.0,
+        "subscription_count": 1,
+        "learning_share": 10.03,
+        "learning_active_months": 2,
+        "impulse": 30.0
+      },
+      "feature_vector": {
+        "night": 0.0,
+        "weekend": 36.25,
+        "frequent_small": 0.0,
+        "flexible_spend": 0.0,
+        "food": 27.51,
+        "subscription": 11.67,
+        "learning": 62.66,
+        "learning_consistency": 50.0,
+        "savings": 100.0,
+        "planning": 75.0,
+        "planning_inverse": 25.0,
+        "impulse": 30.0
+      },
+      "candidates": [
+        {
+          "archetype": "steady_planner",
+          "name": "稳健规划玩家",
+          "score": 85.0,
+          "evidence_valid": true
+        },
+        {
+          "archetype": "learning_investor",
+          "name": "学习投入玩家",
+          "score": 59.49,
+          "evidence_valid": true
+        },
+        {
+          "archetype": "weekend_experience",
+          "name": "周末体验玩家",
+          "score": 23.56,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "subscription_collector",
+          "name": "数字订阅整理师",
+          "score": 14.34,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "frequent_small_spend",
+          "name": "高频小额行动派",
+          "score": 10.13,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "late_night_focus",
+          "name": "夜行消费探索者",
+          "score": 7.5,
+          "evidence_valid": false
+        }
+      ],
+      "llm_role": "仅生成年轻化解释,不决定人格原型、分数或证据"
+    },
+    {
+      "agent": "GoalAgent",
+      "paradigm": "PlanAndSolveAgent-style goal feasibility projection",
+      "tools": [
+        "GoalProjectionTool"
+      ],
+      "goal_count": 0,
+      "planning_note": "将已验证的目标投影差距,拆解为当月可执行的储蓄或支出调整动作,并明确下次校验的时点与调整后金额。"
+    },
+    {
+      "agent": "QuestAgent",
+      "paradigm": "规则发现真实信号 → PlanSolveAgent 动态编排 → Python 强校验与进度计算",
+      "tools": [
+        "StatisticsTool",
+        "BudgetCalculatorTool",
+        "SubscriptionDetectorTool",
+        "QuestProgressTool"
+      ],
+      "signal_catalog": [
+        {
+          "signal_id": "subscriptions",
+          "priority": "required",
+          "verified_observation": "发现 1 项疑似连续扣费。",
+          "locked_constraint": "检查 1 项疑似连续扣费,并仅保留仍会使用的服务。",
+          "completion_source": "用户 CLI 确认后由 SQLite Memory 记录"
+        },
+        {
+          "signal_id": "learning_followthrough",
+          "priority": "optional",
+          "verified_observation": "学习类支出为 ¥320.00,占本月支出 10.03%。",
+          "locked_constraint": "记录 1 次学习服务是否真正被使用,并标注下次使用时间。",
+          "completion_source": "用户 CLI 确认后由 SQLite Memory 记录"
+        }
+      ],
+      "llm_orchestration": {
+        "candidate_count": 2,
+        "accepted_signal_ids": [
+          "subscriptions",
+          "learning_followthrough"
+        ],
+        "validation": {
+          "attempts": 1,
+          "repaired": false,
+          "rejected": []
+        },
+        "numeric_authority": "Python only: target / progress / EXP / status are derived from locked blueprints and QuestProgressTool."
+      },
+      "quest_evidence": [
+        "需要用户在后续 CLI 引导中确认完成",
+        "等待用户更新进度"
+      ]
+    },
+    {
+      "agent": "ReflectionAgent",
+      "paradigm": "ReflectionAgent-style: plan → actual → deviation → adjustment",
+      "context_sources": [
+        "SQLiteMemory: previous snapshot",
+        "budget",
+        "quest outcomes",
+        "goal projection"
+      ]
+    }
+  ],
+  "guided_conversation": [
+    {
+      "role": "user",
+      "content": "a"
+    },
+    {
+      "role": "assistant",
+      "content": "📱 好选择!用 App 记账最省心,不用靠脑袋硬记。\n\n**今晚 5 分钟搞定:**\n- 🔽 打开你常用的记账 App,把「餐饮」单独设成一个分类\n- 🏷️ 给这个分类加个 **90 元周额度** 的备注或标签\n- ⏰ 设个每晚 9 点的提醒:顺手记一笔,3 秒就够\n\n试跑一周,咱们周六看结果。万一某天忘了记,也别补到崩溃,记个大概就行。\n\n👉 你手机里已经有常用的记账 App 了吗?还是需要我陪你选一个?"
+    },
+    {
+      "role": "user",
+      "content": "已经有了"
+    },
+    {
+      "role": "assistant",
+      "content": "📱 有 App 就好办啦!我这边看到你 7 月餐饮花了 **351 元**,比建议线超了 **105.59 元**,是本月最大的超支项——所以我们才要启动这个 90 元周信封实验。\n\n**今晚 3 步开工:**\n- 🏷️ 在 App 里给「餐饮」分类加个标签:**周额度 90**\n- ⏰ 设每晚 9 点的记账提醒\n- 🧾 从明天第一杯咖啡/第一顿饭开始记,每笔都算数\n\n不用追求精确到分,记个大概金额就过关。\n\n👉 你打算从明天早上开始记第一笔,还是今晚就把今天的餐饮也补登一下?"
+    },
+    {
+      "role": "user",
+      "content": "现开始学习地图"
+    },
+    {
+      "role": "assistant",
+      "content": "🗺️ 学习地图已解锁!我这边看到你 7 月在学习上花了 **320 元**,超出了建议线 **67.8 元**,是目前值得留意的项目。这正好对应我们的 **学习小侦探** 任务——只做一件事:确认那项学习服务是否真的被用起来。\n\n**建议步骤:**\n- ➕ 打开支付记录,找到那笔 320 元的学习消费\n- 🔍 回想最近一次打开它是什么时候\n- 📅 顺手约定一个下次使用的时间\n\n先从一个问题开始吧:**最近一次打开那个学习服务,大概是哪天?** 记不准的话,猜个大概就行~"
+    }
+  ]
+}

+ 112 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_02_money_mirror_report.md

@@ -0,0 +1,112 @@
+# 🪞 MoneyMirror 月度报告 · 2026年7月
+
+> 本月关键词:储蓄率 55.69% ✅ · 发薪日小管家 · 餐饮需要温柔收紧
+
+## 一、财务镜像
+
+7 月收入 **7,200 元**,支出 **3,190 元**,结余 **4,010 元**。储蓄率达到 **55.69%**——相当于每赚到 100 元,你就稳稳留下了约 55.69 元,抗风险能力非常在线。
+
+本月共 **9 笔**交易,活跃记账 **8 天**,日均支出 **398.75 元**。整体来说,这是一份"支出有重点、结余很健康"的账单。
+
+## 二、消费分类与趋势
+
+**分类排行:**
+
+| 分类 | 金额 |
+|---|---|
+| 🏠 住房 | 2,200 元 |
+| 🍜 餐饮 | 351 元 |
+| 📚 学习 | 320 元(占比 10.0%) |
+| 🏋️ 健身 | 199 元 |
+| 🚌 交通 | 120 元 |
+
+**周度趋势:**
+- 7/6 当周:**2,374 元**(本月支出高峰)
+- 7/13 当周:**639 元**
+- 7/20 当周:**177 元**
+
+支出呈明显的"前重后轻":月初集中安排必要开销,中下旬逐步收敛,节奏感不错。
+
+## 三、行为模式
+
+- 🌙 深夜消费:**0 笔、0 元、占比 0%**——几乎从不在深夜冲动下单
+- 🎉 周末消费:3 笔、合计 **493 元**、占比 **15.45%**——周末也保持克制
+- 💰 发薪日窗口:2 笔、合计 **2,288 元**、占比 **71.72%**——钱到账后先按计划安排,再安心存下
+- 🔁 高频小额消费:**0 笔**——没有零碎小额刷屏
+
+## 四、异常消费解释
+
+**暂无异常数据**。本月没有触发异常识别的消费,整体支出结构健康,属于"稳稳的幸运月"。
+
+## 五、消费人格
+
+你的主人格是 **稳健规划玩家**(匹配分 85.0,置信度 0.85):储蓄率 55.7%、发薪日后集中消费占比 71.7%、深夜消费为 0——简直是一位自带节奏感的「发薪日小管家」。
+
+副人格 **学习投入玩家**(匹配分 59.49):学习消费占比 10.0%,且已有 2 个月出现学习消费,说明你在持续为自己充电。继续保持这份"理性 + 成长"的组合。
+
+## 六、订阅提醒
+
+📌 **健身房月卡**:已连续 2 个月扣费(2026-06、2026-07),每次 **199 元**。目前没有被判定为低价值,但如果最近去的次数变少,建议顺手问自己一句:"下个月我还会真的用吗?"不用就考虑取消。
+
+## 七、目标进度
+
+- 自定义储蓄 / 愿望目标:**暂无数据**
+- Money Quest:**2 个进行中**(见第九节),进度均为「未完成」
+
+## 八、动态预算与执行
+
+本月建议预算总额 **3,007.04 元**,实际支出 **3,190 元**。分项对照:
+
+| 分类 | 建议 | 实际 | 差额 |
+|---|---|---|---|
+| 交通 | 116.40 | 120.00 | +3.60 |
+| 住房 | 2,200.00 | 2,200.00 | 0.00 ✅ |
+| 健身 | 193.03 | 199.00 | +5.97 |
+| 学习 | 252.20 | 320.00 | +67.80 |
+| 餐饮 | 245.41 | 351.00 | +105.59 |
+
+预算原则是:固定支出不削减,必要支出参考历史中位数、温和调整。住房完美踩线;**餐饮和学习是两大超支项**;交通、健身属于轻微越线,微调即可。
+
+## 九、Money Quest
+
+1. 🧹 **订阅大扫除**:检查 1 项疑似连续扣费(健身房月卡),确认是否仍在使用。经验 +90,进度 0/1。
+2. 🕵️ **学习小侦探**:确认那笔学习服务是否真的被用起来,并约定下次使用时间。经验 +70,进度 0/1。
+
+## 十、等级与成就
+
+当前 **Lv.1**,总经验 0(本周期获得 0),连续记账 **3 天**(历史最长也是 3 天)。
+
+成就盘点:
+- ✅ 储蓄率破 20%(55.69% 远超门槛)
+- ✅ 任务上线
+- ✅ 三日无消费连击
+- ❌ 零消费日初体验——找一天挑战 0 支出吧
+- ❌ 深夜雷达启动——暂时用不上,因为你的深夜消费本来就是 0
+
+## 十一、月度 Reflection(计划-实际-调整)
+
+**做得好的**:预算和任务均基于真实账单计算,结论可靠;结余 4,010 元 + 储蓄率 55.69% 说明本月基本面很稳。
+
+**需要调整的**:餐饮(+105.59)、学习(+67.80)、健身(+5.97)、交通(+3.60)。其中餐饮是最大偏差项。
+
+**自动生成的 8 月建议预算**:
+
+| 分类 | 8 月建议 | 调整逻辑 |
+|---|---|---|
+| 餐饮 | **368.12** | 根据实际偏差增加缓冲,不搞一刀切 |
+| 学习 | **336.00** | 根据实际偏差增加缓冲 |
+| 健身 | **208.95** | 增加缓冲 |
+| 交通 | **126.00** | 增加缓冲,避免对一次性消费一刀切 |
+| 住房 | **2,200.00** | 固定支出,不做削减 |
+
+这个逻辑不是简单否定超支,而是“看见真实开销 → 留出弹性 → 让你更容易坚持”。
+
+## 十二、下一周期行动清单
+
+1. 🍜 **优先为餐饮保留明确额度**:在记账 App 里给「餐饮」设一个 **90 元/周**的额度标签,每晚 9 点提醒记账,试跑一周再看结果。
+2. 🧹 完成 **订阅大扫除**:打开支付记录核对健身房月卡,确认是否取消;这是上周期遗留任务,降低摩擦后继续。
+3. 🕵️ 完成 **学习小侦探**:给那笔 320 元的学习消费定一个具体的下次使用时间,比如"周三晚上 20:00 打开它"。
+4. 📅 为未完成任务设**每周检查点**,避免下周期再次堆积。
+5. 🎯 控制任务数量:下阶段只保留 2 个延续任务 + 1 个新增「餐饮缓冲预算挑战」(目标 **368.12 元**,经验 +100),不给执行添负担。
+
+## 安全边界

+ 779 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_03_money_mirror_report.json

@@ -0,0 +1,779 @@
+{
+  "user_id": "demo_user",
+  "month": "2026-07",
+  "transactions": [
+    {
+      "transaction_id": "19bedefd5cb8ad0f",
+      "occurred_at": "2026-06-08T09:00",
+      "merchant": "公司工资",
+      "amount": 6800.0,
+      "kind": "income",
+      "category": "收入",
+      "note": "六月工资到账",
+      "source": "data/sample_03.csv",
+      "category_confidence": 1.0
+    },
+    {
+      "transaction_id": "b1e4872d1e856cb9",
+      "occurred_at": "2026-06-08T10:00",
+      "merchant": "房东-六月房租",
+      "amount": 2100.0,
+      "kind": "expense",
+      "category": "住房",
+      "note": "固定住房",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "be9ffb5238c0dee7",
+      "occurred_at": "2026-06-13T15:00",
+      "merchant": "万达影院",
+      "amount": 75.0,
+      "kind": "expense",
+      "category": "娱乐",
+      "note": "周末电影",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "d8c3d605f2532ea0",
+      "occurred_at": "2026-06-14T19:00",
+      "merchant": "城市餐厅",
+      "amount": 180.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "周末聚餐",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "168cd0064e1f3593",
+      "occurred_at": "2026-06-20T16:00",
+      "merchant": "线下书店",
+      "amount": 90.0,
+      "kind": "expense",
+      "category": "学习",
+      "note": "周末阅读",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "fe720a3536477ac2",
+      "occurred_at": "2026-06-22T08:20",
+      "merchant": "地铁月票",
+      "amount": 120.0,
+      "kind": "expense",
+      "category": "交通",
+      "note": "通勤",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "a56c69fc1c3c93fc",
+      "occurred_at": "2026-07-06T09:00",
+      "merchant": "公司工资",
+      "amount": 6800.0,
+      "kind": "income",
+      "category": "收入",
+      "note": "七月工资到账",
+      "source": "data/sample_03.csv",
+      "category_confidence": 1.0
+    },
+    {
+      "transaction_id": "014e570569ba1507",
+      "occurred_at": "2026-07-06T10:00",
+      "merchant": "房东-七月房租",
+      "amount": 2100.0,
+      "kind": "expense",
+      "category": "住房",
+      "note": "固定住房",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "c6552c4de6ab1d5b",
+      "occurred_at": "2026-07-11T14:30",
+      "merchant": "独立咖啡馆",
+      "amount": 78.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "周末咖啡",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "4af74193df1ba577",
+      "occurred_at": "2026-07-11T20:00",
+      "merchant": "音乐节门票",
+      "amount": 360.0,
+      "kind": "expense",
+      "category": "娱乐",
+      "note": "周末娱乐",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "89acaefd172ba271",
+      "occurred_at": "2026-07-12T13:00",
+      "merchant": "城市餐厅",
+      "amount": 260.0,
+      "kind": "expense",
+      "category": "餐饮",
+      "note": "周末聚餐",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "1bc9ae722f87f132",
+      "occurred_at": "2026-07-12T17:00",
+      "merchant": "文创商场",
+      "amount": 420.0,
+      "kind": "expense",
+      "category": "购物",
+      "note": "周末购物",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "c41bab59e9eb2bdc",
+      "occurred_at": "2026-07-18T15:00",
+      "merchant": "万达影院",
+      "amount": 85.0,
+      "kind": "expense",
+      "category": "娱乐",
+      "note": "周末电影",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "58eb3d824496c01b",
+      "occurred_at": "2026-07-19T19:00",
+      "merchant": "剧本杀",
+      "amount": 168.0,
+      "kind": "expense",
+      "category": "娱乐",
+      "note": "周末娱乐",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    },
+    {
+      "transaction_id": "9a624a29e83da8b9",
+      "occurred_at": "2026-07-21T08:20",
+      "merchant": "地铁月票",
+      "amount": 120.0,
+      "kind": "expense",
+      "category": "交通",
+      "note": "通勤",
+      "source": "data/sample_03.csv",
+      "category_confidence": 0.92
+    }
+  ],
+  "summary": {
+    "transaction_count": 9,
+    "income": 6800.0,
+    "expense": 3591.0,
+    "balance": 3209.0,
+    "savings_rate": 47.19,
+    "average_expense": 448.88,
+    "active_days": 6
+  },
+  "category_breakdown": {
+    "住房": 2100.0,
+    "娱乐": 613.0,
+    "购物": 420.0,
+    "餐饮": 338.0,
+    "交通": 120.0
+  },
+  "trends": {
+    "daily": {
+      "2026-07-06": 2100.0,
+      "2026-07-11": 438.0,
+      "2026-07-12": 680.0,
+      "2026-07-18": 85.0,
+      "2026-07-19": 168.0,
+      "2026-07-21": 120.0
+    },
+    "weekly": {
+      "2026-07-06": 3218.0,
+      "2026-07-13": 253.0,
+      "2026-07-20": 120.0
+    },
+    "monthly": {
+      "2026-07": 3591.0
+    }
+  },
+  "patterns": {
+    "late_night": {
+      "count": 0,
+      "amount": 0,
+      "share": 0.0
+    },
+    "weekend": {
+      "count": 6,
+      "amount": 1371.0,
+      "share": 38.18
+    },
+    "payday_window": {
+      "count": 1,
+      "amount": 2100.0,
+      "share": 58.48
+    },
+    "frequent_small": {
+      "count": 0,
+      "amount": 0,
+      "average": 0.0
+    },
+    "category_spikes": {
+      "住房": 2100.0,
+      "娱乐": 613.0,
+      "购物": 420.0,
+      "餐饮": 338.0,
+      "交通": 120.0
+    }
+  },
+  "anomalies": [],
+  "subscriptions": [],
+  "persona": {
+    "primary": "周末体验玩家",
+    "archetype": "weekend_experience",
+    "score": 79.11,
+    "confidence": 0.79,
+    "labels": [
+      "周末体验玩家",
+      "弹性体验玩家",
+      "周末社交发动机"
+    ],
+    "secondary": [
+      {
+        "archetype": "flexible_adventurer",
+        "name": "弹性体验玩家",
+        "score": 74.18,
+        "confidence": 0.74,
+        "evidence": [
+          "娱乐与购物占比 28.8%",
+          "周末消费占比 38.2%",
+          "周末交易笔数 6",
+          "冲动消费特征分 30.0%"
+        ]
+      },
+      {
+        "archetype": "weekend_social",
+        "name": "周末社交发动机",
+        "score": 70.74,
+        "confidence": 0.71,
+        "evidence": [
+          "周末消费占比 38.2%",
+          "周末交易笔数 6",
+          "餐饮消费占比 9.4%",
+          "娱乐与购物占比 28.8%"
+        ]
+      }
+    ],
+    "evidence": [
+      "周末消费占比 38.2%",
+      "周末交易笔数 6",
+      "娱乐与购物占比 28.8%"
+    ],
+    "feature_vector": {
+      "night": 0.0,
+      "weekend": 82.98,
+      "frequent_small": 0.0,
+      "flexible_spend": 71.92,
+      "food": 23.53,
+      "subscription": 0.0,
+      "learning": 6.25,
+      "learning_consistency": 25.0,
+      "savings": 47.19,
+      "planning": 48.59,
+      "planning_inverse": 51.41,
+      "impulse": 30.0,
+      "payday": 100.0,
+      "impulse_inverse": 70.0
+    },
+    "narrative": "你的画像很贴近“周末体验玩家”(也可以叫你“周末享受派”),匹配分79.1,是会把快乐集中安排在休息日的人呢~  \n从证据看,你周末消费占比38.2%、周末有6笔交易,娱乐与购物也占到28.8%,这样专注犒劳自己,真的很会生活呀!"
+  },
+  "budget": {
+    "month": "2026-07",
+    "categories": {
+      "交通": {
+        "bucket": "necessary",
+        "historical_median": 120.0,
+        "recommended": 116.4,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "住房": {
+        "bucket": "fixed",
+        "historical_median": 2100.0,
+        "recommended": 2100.0,
+        "rationale": "固定支出,原则上不做大幅削减"
+      },
+      "娱乐": {
+        "bucket": "optional",
+        "historical_median": 75.0,
+        "recommended": 63.75,
+        "rationale": "可选支出,保留真实体验额度并设置温和上限"
+      },
+      "学习": {
+        "bucket": "necessary",
+        "historical_median": 90.0,
+        "recommended": 87.3,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      },
+      "购物": {
+        "bucket": "optional",
+        "historical_median": 0.0,
+        "recommended": 0.0,
+        "rationale": "可选支出,保留真实体验额度并设置温和上限"
+      },
+      "餐饮": {
+        "bucket": "necessary",
+        "historical_median": 180.0,
+        "recommended": 174.6,
+        "rationale": "必要支出,参考历史中位数并保留缓冲"
+      }
+    },
+    "recommended_total": 2542.05,
+    "historical_months": [
+      "2026-06"
+    ],
+    "principle": "基于历史中位数,固定支出不削减,必要/弹性/可选支出分层温和调整"
+  },
+  "goals": [],
+  "quests": [
+    {
+      "quest_id": "娱乐_budget",
+      "title": "娱乐精打细算",
+      "description": "娱乐开销超出动态预算,但别担心,调整节奏就能找回平衡。轻松规划,让每一笔都更从容。\n🧩 小提示:看看本月娱乐记录,挑出可延后的消费,把快乐分散到未来。\n🎯 已核验目标:娱乐支出不高于已核验的动态预算 ¥63.75。",
+      "quest_type": "category_limit",
+      "target": 63.75,
+      "progress": 0.0,
+      "unit": "娱乐",
+      "exp_reward": 120,
+      "status": "active",
+      "evidence": "娱乐 已消费 ¥613.00,预算上限 ¥63.75"
+    },
+    {
+      "quest_id": "weekend_wallet_shield",
+      "title": "周末轻盈计划",
+      "description": "周末消费占比偏高,试着安排免费或低开销活动,享受轻松时光。\n🧩 小提示:规划本周末一次无消费散步或家中游戏,记录感受。\n🎯 已核验目标:周末支出不高于已核验的温和目标 ¥1165.35。",
+      "quest_type": "weekend_spend_limit",
+      "target": 1165.35,
+      "progress": 0.0,
+      "unit": "元",
+      "exp_reward": 110,
+      "status": "active",
+      "evidence": "周末已消费 ¥1371.00,温和上限 ¥1165.35"
+    }
+  ],
+  "achievements": [
+    {
+      "key": "savings_rate_20",
+      "title": "储蓄率破 20%",
+      "description": "储蓄率首次达到或超过 20%。",
+      "unlocked": true
+    },
+    {
+      "key": "zero_spend_start",
+      "title": "零消费日初体验",
+      "description": "完成至少一个零消费日。",
+      "unlocked": false
+    },
+    {
+      "key": "quest_ready",
+      "title": "任务上线",
+      "description": "已生成基于真实账单的 Money Quest。",
+      "unlocked": true
+    },
+    {
+      "key": "late_night_awareness",
+      "title": "深夜雷达启动",
+      "description": "已识别深夜消费行为并生成应对任务。",
+      "unlocked": false
+    },
+    {
+      "key": "zero_spend_streak_3",
+      "title": "三日无消费连击",
+      "description": "连续 3 天没有支出记录。",
+      "unlocked": true
+    }
+  ],
+  "gamification": {
+    "level": 1,
+    "total_exp": 0,
+    "exp_gained_this_cycle": 0,
+    "current_streak_days": 5,
+    "longest_streak_days": 5
+  },
+  "reflection": {
+    "month": "2026-07",
+    "previous_month": "2026-06",
+    "has_previous_snapshot": true,
+    "budget_deviations": [
+      {
+        "category": "交通",
+        "planned": 116.4,
+        "actual": 120.0,
+        "difference": 3.6,
+        "on_budget": false
+      },
+      {
+        "category": "住房",
+        "planned": 2100.0,
+        "actual": 2100.0,
+        "difference": 0.0,
+        "on_budget": true
+      },
+      {
+        "category": "娱乐",
+        "planned": 63.75,
+        "actual": 613.0,
+        "difference": 549.25,
+        "on_budget": false
+      },
+      {
+        "category": "学习",
+        "planned": 87.3,
+        "actual": 0.0,
+        "difference": -87.3,
+        "on_budget": true
+      },
+      {
+        "category": "餐饮",
+        "planned": 174.6,
+        "actual": 338.0,
+        "difference": 163.4,
+        "on_budget": false
+      }
+    ],
+    "quest_completion": {
+      "completed": 0,
+      "total": 2
+    },
+    "goal_progress": {},
+    "effective": [
+      "预算和任务均基于实际账单计算"
+    ],
+    "needs_adjustment": [
+      "娱乐",
+      "餐饮",
+      "交通"
+    ],
+    "next_strategy": [
+      "优先为 娱乐 保留明确额度,而不是一刀切禁止消费。",
+      "下阶段只保留 2 个可执行任务,降低任务负担。"
+    ],
+    "next_cycle_month": "2026-08",
+    "next_cycle_budget": {
+      "source": "monthly_reflection",
+      "categories": {
+        "交通": {
+          "bucket": "necessary",
+          "historical_median": 120.0,
+          "recommended": 126.0,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "住房": {
+          "bucket": "fixed",
+          "historical_median": 2100.0,
+          "recommended": 2100.0,
+          "rationale": "固定支出,原则上不做大幅削减"
+        },
+        "娱乐": {
+          "bucket": "optional",
+          "historical_median": 75.0,
+          "recommended": 95.62,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        },
+        "学习": {
+          "bucket": "necessary",
+          "historical_median": 90.0,
+          "recommended": 87.3,
+          "rationale": "必要支出,参考历史中位数并保留缓冲"
+        },
+        "购物": {
+          "bucket": "optional",
+          "historical_median": 0.0,
+          "recommended": 0.0,
+          "rationale": "可选支出,保留真实体验额度并设置温和上限"
+        },
+        "餐饮": {
+          "bucket": "necessary",
+          "historical_median": 180.0,
+          "recommended": 261.9,
+          "rationale": "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+        }
+      }
+    },
+    "next_cycle_quests": [
+      {
+        "quest_id": "carry_娱乐_budget",
+        "title": "延续:娱乐精打细算",
+        "quest_type": "category_limit",
+        "target": 63.75,
+        "unit": "娱乐",
+        "exp_reward": 120,
+        "reason": "上周期未完成,Reflection 建议降低摩擦后继续"
+      },
+      {
+        "quest_id": "carry_weekend_wallet_shield",
+        "title": "延续:周末轻盈计划",
+        "quest_type": "weekend_spend_limit",
+        "target": 1165.35,
+        "unit": "元",
+        "exp_reward": 110,
+        "reason": "上周期未完成,Reflection 建议降低摩擦后继续"
+      },
+      {
+        "quest_id": "reflection_娱乐",
+        "title": "娱乐缓冲预算挑战",
+        "quest_type": "category_limit",
+        "target": 95.62,
+        "unit": "娱乐",
+        "exp_reward": 100,
+        "reason": "根据本月最大预算偏差生成"
+      }
+    ],
+    "narrative": "下周期请优先收紧娱乐(超支549.25)和餐饮(超支163.4)两类支出,将娱乐消费控制回63.75的计划水平,避免不必要的聚餐和冲动购物;同时把学习预算87.3真正用起来,安排一项技能或课程任务。最后,本周必须补上2项待办任务,结余和储蓄率虽健康,但任务完成率0/2会拖累长期目标。"
+  },
+  "agent_trace": [
+    {
+      "agent": "MoneyMirrorCoordinator",
+      "architecture": "Transaction → Pattern → Persona → Goal → Quest → Reflection",
+      "runtime": {
+        "available": true,
+        "enabled": true,
+        "reason": "已启用 Hello-Agents + OpenAI 兼容 LLM:deepseek-v4-flash",
+        "registry_name": "HelloAgents ToolRegistry (8 MoneyMirror tools)",
+        "paradigms": [
+          "ReActAgent",
+          "PlanSolveAgent",
+          "ReflectionAgent",
+          "Context Engineering"
+        ],
+        "registered_tools": [
+          "CSVImportTool",
+          "TransactionCategoryTool",
+          "StatisticsTool",
+          "AnomalyDetectionTool",
+          "BudgetCalculatorTool",
+          "GoalProjectionTool",
+          "SubscriptionDetectorTool",
+          "QuestProgressTool"
+        ],
+        "provider": "OpenAI-compatible",
+        "model": "deepseek-v4-flash",
+        "base_url": "https://api.deepseek.com"
+      }
+    },
+    {
+      "agent": "TransactionAgent",
+      "paradigm": "ReActAgent-style: inspect transaction → consult memory/rules → resolve only uncertainty",
+      "classification_sources": {
+        "income_rule": 2,
+        "keyword_rule": 13
+      }
+    },
+    {
+      "agent": "PatternAgent",
+      "paradigm": "PlanAndSolveAgent-style: plan metrics → call statistical tools → return evidence",
+      "tools": [
+        "StatisticsTool",
+        "AnomalyDetectionTool",
+        "SubscriptionDetectorTool"
+      ],
+      "evidence": {
+        "late_night_count": 0,
+        "anomaly_count": 0,
+        "subscription_count": 0
+      },
+      "planning_note": "鉴于已验证的夜间消费、异常交易和订阅扣款计数均为零,下一步应将分析重心转向常规消费类别与时间分布,而非排查异常项。"
+    },
+    {
+      "agent": "PersonaAgent",
+      "paradigm": "Feature vector → configurable scoring → evidence validation → LLM narrative",
+      "config_path": "/home/nyc/hello-agents/Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/config/personas.json",
+      "grounded_metrics": {
+        "savings_rate": 47.19,
+        "late_night_share": 0.0,
+        "late_night_count": 0,
+        "weekend_share": 38.18,
+        "weekend_count": 6,
+        "payday_share": 58.48,
+        "frequent_small_count": 0,
+        "frequent_small_share": 0.0,
+        "food_share": 9.41,
+        "flexible_spend_share": 28.77,
+        "subscription_share": 0.0,
+        "subscription_count": 0,
+        "learning_share": 0.0,
+        "learning_active_months": 1,
+        "impulse": 30.0
+      },
+      "feature_vector": {
+        "night": 0.0,
+        "weekend": 82.98,
+        "frequent_small": 0.0,
+        "flexible_spend": 71.92,
+        "food": 23.53,
+        "subscription": 0.0,
+        "learning": 6.25,
+        "learning_consistency": 25.0,
+        "savings": 47.19,
+        "planning": 48.59,
+        "planning_inverse": 51.41,
+        "impulse": 30.0,
+        "payday": 100.0,
+        "impulse_inverse": 70.0
+      },
+      "candidates": [
+        {
+          "archetype": "weekend_experience",
+          "name": "周末体验玩家",
+          "score": 79.11,
+          "evidence_valid": true
+        },
+        {
+          "archetype": "flexible_adventurer",
+          "name": "弹性体验玩家",
+          "score": 74.18,
+          "evidence_valid": true
+        },
+        {
+          "archetype": "payday_rhythm",
+          "name": "发薪节奏管理者",
+          "score": 71.29,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "weekend_social",
+          "name": "周末社交发动机",
+          "score": 70.74,
+          "evidence_valid": true
+        },
+        {
+          "archetype": "mindful_minimalist",
+          "name": "清醒消费实践者",
+          "score": 53.52,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "steady_planner",
+          "name": "稳健规划玩家",
+          "score": 48.03,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "savings_sprinter",
+          "name": "储蓄冲刺玩家",
+          "score": 47.68,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "food_routine",
+          "name": "日常餐饮探索家",
+          "score": 25.39,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "learning_consistent",
+          "name": "学习成长玩家",
+          "score": 17.5,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "digital_lifestyle",
+          "name": "数字生活玩家",
+          "score": 16.45,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "learning_investor",
+          "name": "学习投入玩家",
+          "score": 10.94,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "subscription_collector",
+          "name": "数字订阅整理师",
+          "score": 10.28,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "frequent_small_spend",
+          "name": "高频小额行动派",
+          "score": 9.53,
+          "evidence_valid": false
+        },
+        {
+          "archetype": "late_night_focus",
+          "name": "夜行消费探索者",
+          "score": 7.5,
+          "evidence_valid": false
+        }
+      ],
+      "llm_role": "仅生成年轻化解释,不决定人格原型、分数或证据"
+    },
+    {
+      "agent": "GoalAgent",
+      "paradigm": "PlanAndSolveAgent-style goal feasibility projection",
+      "tools": [
+        "GoalProjectionTool"
+      ],
+      "goal_count": 0,
+      "planning_note": "将目标投影与实际余额的差额拆解为本周期可执行的储蓄或支出限额,并即刻设定下一次预算检查点,用工具持续校验进度。"
+    },
+    {
+      "agent": "QuestAgent",
+      "paradigm": "规则发现真实信号 → PlanSolveAgent 动态编排 → Python 强校验与进度计算",
+      "tools": [
+        "StatisticsTool",
+        "BudgetCalculatorTool",
+        "SubscriptionDetectorTool",
+        "QuestProgressTool"
+      ],
+      "signal_catalog": [
+        {
+          "signal_id": "flexible_budget",
+          "priority": "required",
+          "verified_observation": "娱乐本月已支出 ¥613.00;动态预算为 ¥63.75。",
+          "locked_constraint": "娱乐支出不高于已核验的动态预算 ¥63.75。",
+          "completion_source": "Python QuestProgressTool"
+        },
+        {
+          "signal_id": "weekend",
+          "priority": "optional",
+          "verified_observation": "周末消费 6 笔,占本月支出 38.18%。",
+          "locked_constraint": "周末支出不高于已核验的温和目标 ¥1165.35。",
+          "completion_source": "Python QuestProgressTool"
+        }
+      ],
+      "llm_orchestration": {
+        "candidate_count": 2,
+        "accepted_signal_ids": [
+          "flexible_budget",
+          "weekend"
+        ],
+        "validation": {
+          "attempts": 1,
+          "repaired": false,
+          "rejected": []
+        },
+        "numeric_authority": "Python only: target / progress / EXP / status are derived from locked blueprints and QuestProgressTool."
+      },
+      "quest_evidence": [
+        "娱乐 已消费 ¥613.00,预算上限 ¥63.75",
+        "周末已消费 ¥1371.00,温和上限 ¥1165.35"
+      ]
+    },
+    {
+      "agent": "ReflectionAgent",
+      "paradigm": "ReflectionAgent-style: plan → actual → deviation → adjustment",
+      "context_sources": [
+        "SQLiteMemory: previous snapshot",
+        "budget",
+        "quest outcomes",
+        "goal projection"
+      ]
+    }
+  ]
+}

+ 145 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/outputs/sample_03_money_mirror_report.md

@@ -0,0 +1,145 @@
+# MoneyMirrorAgent 月度报告 | 2026年7月
+
+## 📊 财务镜像
+
+本月你的收入为 **¥6,800**,总支出 **¥3,591**,结余 **¥3,209**。储蓄率达到了 **47.19%**——几乎一半的收入留了下来,这个基础很扎实。全月共 **9 笔**交易,平均每笔支出 **¥448.88**,共有 **6 天**产生消费。值得注意的是,本月没有发生深夜消费,零消费日的连续记录也达到了 **5 天**,整体节奏保持得相当清爽。
+
+---
+
+## 📂 消费分类与趋势
+
+本月支出按类别分布如下:
+
+| 类别 | 金额 | 占比 |
+|------|------|------|
+| 住房 | ¥2,100 | 58.5% |
+| 娱乐 | ¥613 | 17.1% |
+| 购物 | ¥420 | 11.7% |
+| 餐饮 | ¥338 | 9.4% |
+| 交通 | ¥120 | 3.3% |
+
+从时间维度看,月初的 **7/6 那周支出 ¥3,218**,占到了全月近九成;随后两周迅速回落(7/13 周 ¥253,7/20 周 ¥120)。这个形态说明:月初集中支付住房(¥2,100)叠加发薪日的犒劳型消费后,后半程的自我控制力其实很不错。
+
+---
+
+## 🧭 行为模式
+
+- **发薪日窗口效应明显**:发薪日附近支出 **¥2,100**,占全月 **58.48%**——主要是住房固定支出,属正常节奏。
+- **周末消费集中**:周末共有 **6 笔**交易,合计 **¥1,371**,占比 **38.18%**。娱乐和购物占全月 **28.8%**,集中在周末犒劳自己。
+- **无高频小额消费**:没有频繁点外卖或买小东西的迹象,消费决策偏向集中、有目的性。
+- **学习投入为 0**:尽管有 ¥87.3 的学习预算,本月实际未使用。
+
+---
+
+## ⚠️ 异常消费解释
+
+本月未检测到超出常规范围的异常消费。娱乐消费 ¥613 虽远高于预算建议值,但属于**可解释的模式性消费**——主要由周末体验型支出构成,并非突发性失控。暂时无需特别干预,但值得在下一周期留意额度。
+
+---
+
+## 🎭 消费人格
+
+本月最匹配的消费人格是 **「周末体验玩家」**,匹配度 **79.1 分**。
+
+你属于那种把快乐集中安排在休息日的人——周末消费占比 38.2%,6 笔周末交易里藏着不少娱乐和购物的身影,占比合计 28.8%。你的次级人格包括「弹性体验玩家」(74.2 分)和「周末社交发动机」(70.7 分),特征是说走就走、用消费买体验,但也会回应社交需求。
+
+这并不算缺点,关键是**给体验留出额度,同时不让它悄悄膨胀**。
+
+---
+
+## 🔔 订阅提醒
+
+本月暂无数据——未检测到任何订阅类支出,不用操心自动扣费的问题,继续保持就好。
+
+---
+
+## 🎯 目标进度
+
+暂无数据——目前还没有设置储蓄或消费目标。建议下个月可以设定一个具体的娱乐支出上限目标,让「想花的」和「能花的」更一致。
+
+---
+
+## 💡 动态预算
+
+系统基于历史中位数生成了 7 月动态预算,实际执行情况如下:
+
+| 类别 | 预算参考 | 实际支出 | 状态 |
+|------|---------|---------|------|
+| 住房 | ¥2,100 | ¥2,100 | ✅ 持平 |
+| 交通 | ¥116.4 | ¥120 | ⚠️ 微超 ¥3.6 |
+| 餐饮 | ¥174.6 | ¥338 | ❌ 超支 ¥163.4 |
+| 娱乐 | ¥63.75 | ¥613 | ❌ 超支 ¥549.25 |
+| 学习 | ¥87.3 | ¥0 | ✅ 未使用 |
+| 购物 | ¥0 | ¥420 | ⚠️ 未规划消费 |
+
+整体建议预算 ¥2,542.05,实际支出 ¥3,591,超预算约 ¥1,049。娱乐是最大的偏差来源,一次性消费特征明显,属于「集中犒劳」而非「细水长流」。
+
+---
+
+## 🎮 Money Quest
+
+本月已上线 **2 个任务**,目前完成度 **0/2**:
+
+1. **「娱乐精打细算」**:娱乐支出不高于 **¥63.75**,奖励经验 120。已消费 ¥613,尚需大幅收敛。
+2. **「周末轻盈计划」**:周末支出不高于 **¥1,165.35**,奖励经验 110。已消费 ¥1,371,超出约 ¥205.65。
+
+这两个任务的设计思路是「卡住上限、保留弹性」,不是完全不让你花,而是让每一笔享受都更有计划感。本月未完成没关系,下周期会延续,难度不变。
+
+---
+
+## 🏆 等级与成就
+
+- **当前等级**:Lv.1,总经验 0(本期暂未获得新经验)
+- **连续记录**:连续 5 天零消费,最长连续 5 天
+
+**已解锁成就**:
+- 🏅 **储蓄率破 20%**:本月储蓄率 47.19%,远超门槛
+- 🏅 **任务上线**:已基于真实账单生成 Money Quest
+- 🏅 **三日无消费连击**:连续 3 天无支出记录 ✅
+
+**未解锁成就**:
+- 🔒 零消费日初体验(需要至少一天完整零消费)
+- 🔒 深夜雷达启动(需识别到深夜消费行为并应对)
+
+---
+
+## 🌙 月度 Reflection
+
+**做得好的**:储蓄率 47.19% 非常健康;月末消费明显收缩;没有深夜消费;零消费日连续 5 天——你的「自控后劲」其实很强。
+
+**需要调整的**:
+- **娱乐**:超支 ¥549.25,最大偏差来源。建议保留「可玩额度」,而不是用最低值一刀切。
+- **餐饮**:超支 ¥163.4,可能源于周末社交聚餐。不需要完全杜绝,但可以提前设定「每周末最多一顿外食」。
+- **交通**:微超 ¥3.6,影响不大,但说明预算缓冲可以更贴合实际。
+
+**被忽视的**:学习预算 ¥87.3 完全没有使用。可能不是没兴趣,而是没安排具体任务——下个月把「学点什么」变成一个明确动作。
+
+**待办事项**:共 2 项任务,完成率为 0/2。虽然结余好看,但任务进度若长期停滞,会拖累成长体系。
+
+---
+
+## 🚀 下一周期行动清单(2026年8月)
+
+基于 7 月反思,8 月的预算与任务已做针对性调整:
+
+**新预算亮点**:
+- 娱乐预算上调至 **¥95.62**(基于实际偏差增加缓冲,不再用历史最低值压人)
+- 餐饮预算上调至 **¥261.9**(承认社交聚餐是真实需求,给足空间)
+- 交通预算微调至 **¥126**,住房维持 **¥2,100**,学习保持 **¥87.3**
+
+**延续任务**:
+1. 🔄 **延续:娱乐精打细算** —— 目标 ¥63.75(如果觉得太紧,可以按新预算 ¥95.62 来看待自己的进步空间)
+2. 🔄 **延续:周末轻盈计划** —— 目标 ¥1,165.35 周末总支出
+
+**新任务**:
+3. 🆕 **娱乐缓冲预算挑战** —— 目标 ≤ ¥95.62,奖励经验 100。结合 7 月的真实节奏,先用这个温和目标找回掌控感。
+
+**行动建议**:
+1. 把娱乐预算 ¥95.62 拆成一个「周末快乐金」,花之前看一眼余额;
+2. 给周末提前安排 1 项免费活动(公园散步、宅家游戏),降低消费冲动;
+3. 把学习预算用起来——报一个 ¥87.3 内的线上短课或买一本书;
+4. 每周日花 3 分钟记录当周消费,防止月初大手大脚、月末被动收缩。
+
+---
+
+下个月再见面时,希望你的娱乐支出离预算上限更近一点,任务完成率从 0/2 变成 2/2 甚至 3/3。你已经证明自己能存下钱,接下来只需要证明:**会花的人,也能花得漂亮。** 🌱

+ 9 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/requirements.txt

@@ -0,0 +1,9 @@
+hello-agents>=1.0.0
+python-dotenv>=1.0.0
+
+
+# Development / verification
+pytest>=8.0.0
+
+# Chapter 16 notebook entry point
+jupyter>=1.0.0

+ 5 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/__init__.py

@@ -0,0 +1,5 @@
+"""MoneyMirrorAgent package."""
+
+from .agents.coordinator import MoneyMirrorCoordinator
+
+__all__ = ["MoneyMirrorCoordinator"]

+ 5 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Agent roles and the MoneyMirror coordinator."""
+
+from .coordinator import MoneyMirrorCoordinator
+
+__all__ = ["MoneyMirrorCoordinator"]

+ 134 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/conversation_agent.py

@@ -0,0 +1,134 @@
+"""Stateful guided conversation before the final report is generated."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Iterable
+
+from .runtime import HelloAgentsRuntime
+
+
+class ConversationAgent:
+    """Turn a static analysis into a step-by-step financial coaching session.
+
+    The conversation deliberately receives a *presentation payload*, not the
+    complete ``AnalysisReport``.  Transactions and agent traces are useful for
+    local debugging, but sending them on every turn makes the LLM context noisy
+    and can hide the verified facts that the coach must use.
+    """
+
+    paradigm = "Interactive Hello-Agents coaching: observe → suggest → ask → reflect"
+    MAX_HISTORY_ITEMS = 6
+    MAX_MESSAGE_CHARS = 600
+    MAX_ANOMALIES = 6
+    MAX_QUESTS = 6
+    MAX_SUBSCRIPTIONS = 8
+
+    def __init__(self, runtime: HelloAgentsRuntime) -> None:
+        self.runtime = runtime
+
+    @classmethod
+    def compact_report(cls, report: Any, conversation: Iterable[dict[str, str]] | None = None) -> dict[str, Any]:
+        """Create the small, verified fact packet used by conversational LLM calls.
+
+        Numeric values are copied from deterministic tools; this method only
+        removes high-volume detail and never calculates a replacement number.
+        In particular, raw transactions and ``agent_trace`` are intentionally
+        excluded from prompts to avoid context truncation and accidental model
+        hallucinations.
+        """
+        category_breakdown = dict(getattr(report, "category_breakdown", {}) or {})
+        # Keep all categories: the demo has only a small fixed category set and
+        # the user should be able to ask about any one of them.
+        trends = dict(getattr(report, "trends", {}) or {})
+        trend_summary: dict[str, Any] = {}
+        for key in ("weekly", "monthly"):
+            values = trends.get(key)
+            if isinstance(values, dict):
+                trend_summary[key] = values
+        patterns = dict(getattr(report, "patterns", {}) or {})
+        # These pattern objects are already compact deterministic summaries.
+        selected_patterns = {
+            key: patterns[key]
+            for key in ("late_night", "weekend", "payday_window", "frequent_small", "category_spikes")
+            if key in patterns
+        }
+        budget = getattr(report, "budget", {}) or {}
+        compact_budget = dict(budget)
+        if isinstance(budget, dict) and isinstance(budget.get("categories"), dict):
+            compact_budget["categories"] = budget["categories"]
+
+        def item_dict(item: Any) -> dict[str, Any]:
+            if hasattr(item, "to_dict"):
+                return item.to_dict()
+            return dict(item) if isinstance(item, dict) else {"value": str(item)}
+
+        compact: dict[str, Any] = {
+            "month": getattr(report, "month", ""),
+            "summary": getattr(report, "summary", {}) or {},
+            "category_breakdown": category_breakdown,
+            "trends": trend_summary,
+            "patterns": selected_patterns,
+            "anomalies": [item_dict(item) for item in list(getattr(report, "anomalies", []) or [])[: cls.MAX_ANOMALIES]],
+            "subscriptions": list(getattr(report, "subscriptions", []) or [])[: cls.MAX_SUBSCRIPTIONS],
+            "persona": getattr(report, "persona", {}) or {},
+            "budget": compact_budget,
+            "goals": list(getattr(report, "goals", []) or []),
+            "quests": [item_dict(item) for item in list(getattr(report, "quests", []) or [])[: cls.MAX_QUESTS]],
+            "achievements": [item_dict(item) for item in list(getattr(report, "achievements", []) or [])],
+            "gamification": getattr(report, "gamification", {}) or {},
+            "reflection": getattr(report, "reflection", {}) or {},
+        }
+        if conversation:
+            compact["guided_conversation"] = cls.compact_conversation(conversation)
+        return compact
+
+    @classmethod
+    def compact_conversation(cls, conversation: Iterable[dict[str, str]]) -> list[dict[str, str]]:
+        """Keep the most recent dialogue turns within a predictable size."""
+        items = list(conversation)[-cls.MAX_HISTORY_ITEMS :]
+        result: list[dict[str, str]] = []
+        for item in items:
+            content = str(item.get("content", "")).strip()
+            if len(content) > cls.MAX_MESSAGE_CHARS:
+                content = content[: cls.MAX_MESSAGE_CHARS].rstrip() + "…"
+            result.append({"role": str(item.get("role", "user")), "content": content})
+        return result
+
+    @classmethod
+    def payload(cls, report: Any, conversation: Iterable[dict[str, str]] | None = None) -> str:
+        """Serialize a compact packet with an explicit verified-facts marker."""
+        return json.dumps(
+            {"[Verified tool output]": cls.compact_report(report, conversation)},
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+
+    def opening(self, report: Any) -> str:
+        compact = self.compact_report(report)
+        summary = compact.get("summary", {})
+        patterns = compact.get("patterns", {})
+        persona = compact.get("persona", {})
+        focus = (
+            f"当前分析月份={compact.get('month')};收入={summary.get('income')};"
+            f"支出={summary.get('expense')};结余={summary.get('balance')};"
+            f"储蓄率={summary.get('savings_rate')}%;消费人格={persona.get('primary')};"
+            f"深夜消费={patterns.get('late_night')};周末消费={patterns.get('weekend')}。"
+        )
+        return self.runtime.explain(
+            "为用户开启 MoneyMirror 的第一关引导,而不是生成报告。你必须使用下面这行已核验焦点中的至少一个真实数字,"
+            "不能说‘没有数据’或要求用户重新上传账单。请严格按顺序输出:"
+            "(1) 用一个有趣的镜像/RPG昵称,引用真实消费现象;"
+            "(2) 给一个今天就能完成、不会一刀切的微行动;"
+            "(3) 只问一个选择题式追问,让用户选择最想先改善的消费场景。"
+            "不要输出‘结论/依据/风险/下一步’的机械模板,不要生成最终 Markdown 报告,"
+            "控制在 100-160 字,使用少量 emoji。\n"
+            f"已核验焦点:{focus}",
+            mode="simple",
+            evidence=[self.payload(report)],
+        )
+
+    def respond(self, report: Any, question: str, history: Iterable[dict[str, str]]) -> str:
+        """Non-streaming counterpart used by CLI and tests."""
+        chunks = self.runtime.stream_user_guidance(question, self.payload(report), self.compact_conversation(history))
+        return "".join(chunks).strip()

+ 201 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/coordinator.py

@@ -0,0 +1,201 @@
+"""MoneyMirrorCoordinator orchestrates specialized agents around deterministic tools."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from ..memory import SQLiteMemory
+from ..models import AnalysisReport, Goal
+from ..tools import BudgetCalculatorTool, CSVImportTool, StatisticsTool
+from ..tools.anomaly_detection import AnomalyDetectionTool
+from ..tools.goal_projection import GoalProjectionTool
+from ..tools.hello_agents_registry import build_registry_functions
+from ..tools.quest_progress import QuestProgressTool
+from ..tools.subscription_detector import SubscriptionDetectorTool
+from ..tools.transaction_category import TransactionCategoryTool
+from .conversation_agent import ConversationAgent
+from .goal_agent import GoalAgent
+from .pattern_agent import PatternAgent
+from .persona_agent import PersonaAgent
+from .quest_agent import QuestAgent
+from .reflection_agent import ReflectionAgent
+from .runtime import HelloAgentsRuntime
+from .transaction_agent import TransactionAgent
+
+
+class MoneyMirrorCoordinator:
+    """A multi-agent pipeline that keeps numeric work local and reproducible.
+
+    Flow: CSV import → TransactionAgent → PatternAgent → PersonaAgent → GoalAgent
+    → QuestAgent → ReflectionAgent. Each agent adds either planning, context, or
+    interpretation; all calculation-heavy decisions come from explicit tools.
+    """
+
+    def __init__(
+        self,
+        db_path: str | Path = "outputs/moneymirror.db",
+        user_id: str = "local_user",
+        runtime: HelloAgentsRuntime | None = None,
+    ) -> None:
+        self.memory = SQLiteMemory(db_path, user_id)
+        self.runtime = runtime or HelloAgentsRuntime()
+        self.csv_import = CSVImportTool()
+        self.statistics = StatisticsTool()
+        self.budget_tool = BudgetCalculatorTool()
+        self.transaction_agent = TransactionAgent(self.memory, self.runtime)
+        self.conversation_agent = ConversationAgent(self.runtime)
+        self.pattern_agent = PatternAgent(self.runtime)
+        self.persona_agent = PersonaAgent(self.runtime)
+        self.goal_agent = GoalAgent(self.memory, self.runtime)
+        self.quest_agent = QuestAgent(self.memory, self.runtime)
+        self.reflection_agent = ReflectionAgent(self.memory, self.runtime)
+        # Expose the deterministic tools to an optional Hello-Agents ReAct
+        # agent. The coordinator still invokes these tools directly, so an LLM
+        # cannot alter financial arithmetic or bypass Memory precedence.
+        self.runtime.register_tool_functions(build_registry_functions(
+            self.csv_import,
+            TransactionCategoryTool(),
+            self.statistics,
+            AnomalyDetectionTool(),
+            self.budget_tool,
+            GoalProjectionTool(),
+            SubscriptionDetectorTool(),
+            QuestProgressTool(),
+            self.memory.get_merchant_category,
+        ))
+
+    def close(self) -> None:
+        self.memory.close()
+
+    def correct_merchant_category(self, merchant: str, category: str) -> None:
+        """Persist a user correction so identical merchants use Memory next time."""
+        self.transaction_agent.correct_category(merchant, category)
+
+    def add_goal(self, goal: Goal) -> None:
+        self.memory.save_goal(goal)
+
+    def complete_quest(self, report: AnalysisReport, quest_id: str, note: str = "") -> dict:
+        """Persist a user-confirmed non-transactional Quest from the CLI."""
+        quest = next((item for item in report.quests if item.quest_id == quest_id), None)
+        if quest is None:
+            available = ", ".join(item.quest_id for item in report.quests)
+            raise ValueError(f"未找到 Quest:{quest_id}。可用 Quest ID:{available}")
+        result = self.quest_agent.complete_manual_quest(quest, report.month, note)
+        report.gamification["total_exp"] = result["total_exp"]
+        report.gamification["exp_gained_this_cycle"] = report.gamification.get("exp_gained_this_cycle", 0) + result["gained_exp"]
+        report.gamification["level"] = result["level"]
+        return result
+
+    def analyze_csv(self, csv_path: str | Path, month: str | None = None) -> AnalysisReport:
+        imported = self.csv_import.load(csv_path)
+        return self.analyze_transactions(imported, month, import_errors=self.csv_import.last_errors)
+
+    def analyze_transactions(
+        self,
+        imported: list,
+        month: str | None = None,
+        import_errors: list[str] | None = None,
+    ) -> AnalysisReport:
+        transactions, transaction_trace = self.transaction_agent.run(imported)
+        if import_errors:
+            transaction_trace["csv_import_warnings"] = list(import_errors)
+        months = self.statistics.month_keys(transactions)
+        if not months:
+            raise ValueError("没有可用于分析的交易记录")
+        active_month = month or months[-1]
+        if active_month not in months:
+            raise ValueError(f"账单中不存在月份 {active_month}")
+        summary = self.statistics.summarize(transactions, active_month)
+        categories = self.statistics.category_breakdown(transactions, active_month)
+        trends = self.statistics.trends(transactions, active_month)
+        patterns, anomalies, subscriptions, pattern_trace = self.pattern_agent.run(transactions, active_month)
+        budget = self.budget_tool.calculate(transactions, active_month)
+        self.memory.save_budget(active_month, budget)
+        persona, persona_trace = self.persona_agent.run(summary, categories, patterns, subscriptions, transactions)
+        goals, goal_trace = self.goal_agent.run(transactions, active_month)
+        quests, achievements, gamification, quest_trace = self.quest_agent.run(
+            transactions, active_month, summary, categories, patterns, subscriptions, budget, goals
+        )
+
+        # Create a historical baseline snapshot before reflecting on the latest month.
+        previous_month = self.reflection_agent._previous_month(active_month)
+        if previous_month in months and not self.memory.get_snapshot(previous_month):
+            previous_summary = self.statistics.summarize(transactions, previous_month)
+            previous_categories = self.statistics.category_breakdown(transactions, previous_month)
+            self.memory.save_snapshot(previous_month, {"summary": previous_summary, "category_breakdown": previous_categories, "source": "auto_baseline"})
+
+        reflection, reflection_trace = self.reflection_agent.run(active_month, summary, categories, budget, quests, goals)
+        report = AnalysisReport(
+            user_id=self.memory.user_id,
+            month=active_month,
+            transactions=transactions,
+            summary=summary,
+            category_breakdown=categories,
+            trends=trends,
+            patterns=patterns,
+            anomalies=anomalies,
+            subscriptions=subscriptions,
+            persona=persona,
+            budget=budget,
+            goals=goals,
+            quests=quests,
+            achievements=achievements,
+            gamification=gamification,
+            reflection=reflection,
+            agent_trace=[
+                {"agent": "MoneyMirrorCoordinator", "architecture": "Transaction → Pattern → Persona → Goal → Quest → Reflection", "runtime": self.runtime.status_dict()},
+                transaction_trace,
+                pattern_trace,
+                persona_trace,
+                goal_trace,
+                quest_trace,
+                reflection_trace,
+            ],
+        )
+        self.memory.save_snapshot(active_month, {"summary": summary, "category_breakdown": categories, "persona": persona, "budget": budget, "goal_projections": goals, "quest_completion": reflection["quest_completion"], "reflection": reflection})
+        return report
+
+    @staticmethod
+    def _output_stem(source_csv: str | Path | None) -> str:
+        """Build a readable, filesystem-safe report stem from the input CSV."""
+        if source_csv is None:
+            return "money_mirror_report"
+        stem = Path(source_csv).stem.strip()
+        safe_stem = re.sub(r"[^\w.-]+", "_", stem, flags=re.UNICODE).strip("._")
+        return f"{safe_stem or 'transactions'}_money_mirror_report"
+
+    def write_outputs(
+        self,
+        report: AnalysisReport,
+        output_dir: str | Path = "outputs",
+        conversation: list[dict[str, str]] | None = None,
+        source_csv: str | Path | None = None,
+    ) -> tuple[Path, Path]:
+        """Persist JSON facts and an LLM-authored Markdown report.
+
+        The Markdown file is intentionally generated only here, after the
+        user finishes the guided conversation. There is no local template
+        fallback: a report is never presented as LLM-generated unless the
+        configured Hello-Agents model actually returned it.
+        """
+        directory = Path(output_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+        output_stem = self._output_stem(source_csv)
+        json_path = directory / f"{output_stem}.json"
+        markdown_path = directory / f"{output_stem}.md"
+        # Keep the persisted JSON complete for auditability, but send only a
+        # compact verified presentation packet to the LLM. Raw transactions and
+        # agent traces are not needed for narrative generation and can crowd out
+        # the facts the model must cite.
+        payload = report.to_dict()
+        if conversation:
+            payload["guided_conversation"] = self.conversation_agent.compact_conversation(conversation)
+            self.memory.set_preference("last_guided_conversation", payload["guided_conversation"])
+        json_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+        markdown = self.runtime.generate_markdown(
+            self.conversation_agent.payload(report, conversation)
+        )
+        markdown_path.write_text(markdown, encoding="utf-8")
+        return json_path, markdown_path

+ 36 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/goal_agent.py

@@ -0,0 +1,36 @@
+"""GoalAgent: feasibility comes from GoalProjectionTool, not an LLM guess."""
+
+from __future__ import annotations
+
+import json
+from typing import Iterable
+
+from ..memory import SQLiteMemory
+from ..models import Goal, Transaction
+from ..tools.goal_projection import GoalProjectionTool
+from .runtime import HelloAgentsRuntime
+
+
+class GoalAgent:
+    paradigm = "PlanAndSolveAgent-style goal feasibility projection"
+
+    def __init__(self, memory: SQLiteMemory, runtime: HelloAgentsRuntime | None = None) -> None:
+        self.memory = memory
+        self.runtime = runtime
+        self.tool = GoalProjectionTool()
+
+    def run(self, transactions: Iterable[Transaction], month: str) -> tuple[list[dict], dict]:
+        goals = [Goal(**item) for item in self.memory.list_goals(active_only=True)]
+        results = [self.tool.project(goal, transactions, month) for goal in goals]
+        planning_note = (
+            "GoalProjectionTool 已根据现金流、历史结余和截止日期计算可行性。"
+            if results
+            else "当前没有已保存的财务目标;可通过 CLI 的 Memory 配置或后续输入创建目标,避免替真实用户臆造目标。"
+        )
+        if self.runtime is not None:
+            planning_note = self.runtime.explain(
+                "请用一句话说明如何把目标投影转成下一步行动;不得修改工具计算出的金额。",
+                mode="plan",
+                evidence=[json.dumps(results, ensure_ascii=False)],
+            )
+        return results, {"agent": "GoalAgent", "paradigm": self.paradigm, "tools": ["GoalProjectionTool"], "goal_count": len(results), "planning_note": planning_note}

+ 46 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/pattern_agent.py

@@ -0,0 +1,46 @@
+"""PatternAgent plans deterministic tool use for patterns and anomalies."""
+
+from __future__ import annotations
+
+import json
+from typing import Iterable
+
+from ..models import Transaction
+from ..tools import AnomalyDetectionTool, StatisticsTool, SubscriptionDetectorTool
+from .runtime import HelloAgentsRuntime
+
+
+class PatternAgent:
+    paradigm = "PlanAndSolveAgent-style: plan metrics → call statistical tools → return evidence"
+
+    def __init__(self, runtime: HelloAgentsRuntime | None = None) -> None:
+        self.runtime = runtime
+        self.statistics = StatisticsTool()
+        self.anomalies = AnomalyDetectionTool()
+        self.subscriptions = SubscriptionDetectorTool()
+
+    def run(self, transactions: Iterable[Transaction], month: str) -> tuple[dict, list, list[dict], dict]:
+        items = list(transactions)
+        patterns = self.statistics.patterns(items, month)
+        anomalies = self.anomalies.detect(items, month)
+        subscriptions = self.subscriptions.detect(items)
+        evidence = {
+            "late_night_count": patterns["late_night"]["count"],
+            "anomaly_count": len(anomalies),
+            "subscription_count": len(subscriptions),
+        }
+        planning_note = "Python 工具已按深夜、周末、工资到账窗口、异常和连续扣费顺序完成统计。"
+        if self.runtime is not None:
+            planning_note = self.runtime.explain(
+                "请用一句话说明下一步应如何解读这组已验证的消费模式证据,不要重新计算金额。",
+                mode="plan",
+                evidence=[json.dumps(evidence, ensure_ascii=False)],
+            )
+        trace = {
+            "agent": "PatternAgent",
+            "paradigm": self.paradigm,
+            "tools": ["StatisticsTool", "AnomalyDetectionTool", "SubscriptionDetectorTool"],
+            "evidence": evidence,
+            "planning_note": planning_note,
+        }
+        return patterns, anomalies, subscriptions, trace

+ 377 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/persona_agent.py

@@ -0,0 +1,377 @@
+"""Evidence-based, configurable consumer-persona scoring for MoneyMirror."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..models import Transaction
+from ..tools.statistics import StatisticsTool
+from .runtime import HelloAgentsRuntime
+
+
+@dataclass(frozen=True, slots=True)
+class PersonaArchetype:
+    """A stable, configurable persona structure; wording is not a Python rule."""
+
+    archetype_id: str
+    name: str
+    minimum_score: float
+    required_features: dict[str, float]
+    weights: dict[str, float]
+    evidence_metrics: tuple[str, ...]
+
+
+class PersonaAgent:
+    """Score verified behavior features, validate evidence, then ask the LLM for prose.
+
+    Python determines the reproducible archetype and its score. The LLM only
+    turns the verified result into young, supportive language; it cannot
+    change the score, invent a metric, or turn generic food spending into a
+    coffee-specific claim.
+    """
+
+    paradigm = "Feature vector → configurable scoring → evidence validation → LLM narrative"
+    DEFAULT_CONFIG_PATH = Path(__file__).resolve().parents[1] / "config" / "personas.json"
+
+    # These names are the stable contract between deterministic extraction and
+    # external persona configuration. They are deliberately behavior metrics,
+    # not persona labels: adding or renaming an archetype remains a JSON-only
+    # change, while a misspelled feature is rejected instead of silently
+    # scoring as zero.
+    FEATURE_KEYS = frozenset(
+        {
+            "night",
+            "weekend",
+            "frequent_small",
+            "flexible_spend",
+            "food",
+            "subscription",
+            "learning",
+            "learning_consistency",
+            "savings",
+            "planning",
+            "planning_inverse",
+            "impulse",
+            "payday",
+            "impulse_inverse",
+        }
+    )
+    METRIC_KEYS = frozenset(
+        {
+            "savings_rate",
+            "late_night_share",
+            "late_night_count",
+            "weekend_share",
+            "weekend_count",
+            "payday_share",
+            "frequent_small_count",
+            "frequent_small_share",
+            "food_share",
+            "flexible_spend_share",
+            "subscription_share",
+            "subscription_count",
+            "learning_share",
+            "learning_active_months",
+            "impulse",
+        }
+    )
+
+    def __init__(self, runtime: HelloAgentsRuntime, config_path: str | Path | None = None) -> None:
+        self.runtime = runtime
+        self.statistics = StatisticsTool()
+        self.config_path = Path(config_path) if config_path else self.DEFAULT_CONFIG_PATH
+        self.archetypes, self.fallback = self._load_config(self.config_path)
+        self._validate_config_references()
+
+    @staticmethod
+    def _clamp_score(value: float) -> float:
+        return round(max(0.0, min(100.0, value)), 2)
+
+    @classmethod
+    def _scaled(cls, value: float, full_score_at: float) -> float:
+        if full_score_at <= 0:
+            return 0.0
+        return cls._clamp_score(value / full_score_at * 100)
+
+    @staticmethod
+    def _load_config(path: Path) -> tuple[tuple[PersonaArchetype, ...], dict[str, Any]]:
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ValueError(f"无法读取人格配置 {path}: {exc}") from exc
+        items = raw.get("archetypes")
+        fallback = raw.get("fallback")
+        if not isinstance(items, list) or not items or not isinstance(fallback, dict):
+            raise ValueError("人格配置必须包含非空 archetypes 和 fallback")
+
+        archetypes: list[PersonaArchetype] = []
+        seen_ids: set[str] = set()
+        for item in items:
+            if not isinstance(item, dict):
+                raise ValueError("人格配置中的 archetype 必须是对象")
+            archetype_id = str(item.get("id", "")).strip()
+            name = str(item.get("name", "")).strip()
+            weights = item.get("weights")
+            required = item.get("required_features", {})
+            evidence = item.get("evidence_metrics", [])
+            if not archetype_id or not name or archetype_id in seen_ids:
+                raise ValueError("人格配置需要唯一且非空的 id 与 name")
+            if not isinstance(weights, dict) or not weights or not isinstance(required, dict) or not isinstance(evidence, list):
+                raise ValueError(f"人格配置 {archetype_id} 的字段格式无效")
+            numeric_weights = {str(key): float(value) for key, value in weights.items()}
+            if any(value < 0 for value in numeric_weights.values()) or sum(numeric_weights.values()) <= 0:
+                raise ValueError(f"人格配置 {archetype_id} 的 weights 必须为正权重")
+            archetypes.append(
+                PersonaArchetype(
+                    archetype_id=archetype_id,
+                    name=name,
+                    minimum_score=float(item.get("minimum_score", 0)),
+                    required_features={str(key): float(value) for key, value in required.items()},
+                    weights=numeric_weights,
+                    evidence_metrics=tuple(str(key) for key in evidence),
+                )
+            )
+            seen_ids.add(archetype_id)
+        if not str(fallback.get("id", "")).strip() or not str(fallback.get("name", "")).strip():
+            raise ValueError("人格配置 fallback 需要 id 与 name")
+        return tuple(archetypes), fallback
+
+    def _validate_config_references(self) -> None:
+        """Fail fast when JSON references a metric the extractor cannot produce."""
+        for archetype in self.archetypes:
+            feature_keys = set(archetype.weights) | set(archetype.required_features)
+            unknown_features = sorted(feature_keys - self.FEATURE_KEYS)
+            if unknown_features:
+                raise ValueError(
+                    f"人格配置 {archetype.archetype_id} 引用了未知特征: {', '.join(unknown_features)}"
+                )
+            unknown_metrics = sorted(set(archetype.evidence_metrics) - self.METRIC_KEYS)
+            if unknown_metrics:
+                raise ValueError(
+                    f"人格配置 {archetype.archetype_id} 引用了未知证据指标: {', '.join(unknown_metrics)}"
+                )
+            if not 0 <= archetype.minimum_score <= 100:
+                raise ValueError(f"人格配置 {archetype.archetype_id} 的 minimum_score 必须在 0 到 100 之间")
+            invalid_thresholds = [
+                name for name, threshold in archetype.required_features.items() if not 0 <= threshold <= 100
+            ]
+            if invalid_thresholds:
+                raise ValueError(
+                    f"人格配置 {archetype.archetype_id} 的 required_features 阈值必须在 0 到 100 之间: "
+                    f"{', '.join(sorted(invalid_thresholds))}"
+                )
+        fallback_unknown_metrics = sorted(set(self.fallback.get("evidence_metrics", [])) - self.METRIC_KEYS)
+        if fallback_unknown_metrics:
+            raise ValueError(f"人格配置 fallback 引用了未知证据指标: {', '.join(fallback_unknown_metrics)}")
+
+    def _learning_active_months(self, transactions: Iterable[Transaction] | None) -> int:
+        if transactions is None:
+            return 0
+        totals = self.statistics.monthly_category_totals(transactions)
+        return sum(1 for categories in totals.values() if categories.get("学习", 0.0) > 0)
+
+    def _extract_features(
+        self,
+        summary: dict[str, Any],
+        categories: dict[str, float],
+        patterns: dict[str, Any],
+        subscriptions: list[dict[str, Any]],
+        transactions: Iterable[Transaction] | None,
+    ) -> tuple[dict[str, float], dict[str, float | int]]:
+        expense = max(float(summary.get("expense", 0.0)), 1.0)
+        savings_rate = float(summary.get("savings_rate", 0.0))
+        late = patterns.get("late_night", {})
+        weekend = patterns.get("weekend", {})
+        payday = patterns.get("payday_window", {})
+        frequent_small = patterns.get("frequent_small", {})
+
+        late_share = float(late.get("share", 0.0))
+        weekend_share = float(weekend.get("share", 0.0))
+        payday_share = float(payday.get("share", 0.0))
+        small_count = int(frequent_small.get("count", 0))
+        small_share = float(frequent_small.get("amount", 0.0)) / expense * 100
+        food_share = float(categories.get("餐饮", 0.0)) / expense * 100
+        flexible_spend_share = (float(categories.get("娱乐", 0.0)) + float(categories.get("购物", 0.0))) / expense * 100
+        subscription_share = float(categories.get("订阅", 0.0)) / expense * 100
+        learning_share = float(categories.get("学习", 0.0)) / expense * 100
+        learning_active_months = self._learning_active_months(transactions)
+
+        night = 0.72 * self._scaled(late_share, 25) + 0.28 * self._scaled(int(late.get("count", 0)), 5)
+        weekend_score = 0.72 * self._scaled(weekend_share, 50) + 0.28 * self._scaled(int(weekend.get("count", 0)), 6)
+        frequent_small_score = 0.7 * self._scaled(small_count, 10) + 0.3 * self._scaled(small_share, 25)
+        payday_score = self._scaled(payday_share, 45)
+        impulse = 0.45 * frequent_small_score + 0.3 * payday_score + 0.25 * self._scaled(late_share, 30)
+        learning = 0.75 * self._scaled(learning_share, 15) + 0.25 * self._scaled(learning_active_months, 4)
+        subscription = 0.65 * self._scaled(subscription_share, 12) + 0.35 * self._scaled(len(subscriptions), 3)
+        savings = self._clamp_score(savings_rate)
+        planning = 0.5 * savings + 0.25 * (100 - self._scaled(payday_share, 45)) + 0.15 * (100 - frequent_small_score) + 0.1 * (100 - self._scaled(late_share, 30))
+
+        feature_vector = {
+            "night": self._clamp_score(night),
+            "weekend": self._clamp_score(weekend_score),
+            "frequent_small": self._clamp_score(frequent_small_score),
+            "flexible_spend": self._scaled(flexible_spend_share, 40),
+            "food": self._scaled(food_share, 40),
+            "subscription": self._clamp_score(subscription),
+            "learning": self._clamp_score(learning),
+            "learning_consistency": self._scaled(learning_active_months, 4),
+            "savings": self._clamp_score(savings),
+            "planning": self._clamp_score(planning),
+            "planning_inverse": self._clamp_score(100 - planning),
+            "impulse": self._clamp_score(impulse),
+            "payday": self._clamp_score(payday_score),
+            "impulse_inverse": self._clamp_score(100 - impulse),
+        }
+        metrics: dict[str, float | int] = {
+            "savings_rate": round(savings_rate, 2),
+            "late_night_share": round(late_share, 2),
+            "late_night_count": int(late.get("count", 0)),
+            "weekend_share": round(weekend_share, 2),
+            "weekend_count": int(weekend.get("count", 0)),
+            "payday_share": round(payday_share, 2),
+            "frequent_small_count": small_count,
+            "frequent_small_share": round(small_share, 2),
+            "food_share": round(food_share, 2),
+            "flexible_spend_share": round(flexible_spend_share, 2),
+            "subscription_share": round(subscription_share, 2),
+            "subscription_count": len(subscriptions),
+            "learning_share": round(learning_share, 2),
+            "learning_active_months": learning_active_months,
+            "impulse": round(feature_vector["impulse"], 2),
+        }
+        return feature_vector, metrics
+
+    @staticmethod
+    def _score(archetype: PersonaArchetype, features: dict[str, float]) -> float:
+        total_weight = sum(archetype.weights.values())
+        return round(
+            sum(features.get(feature, 0.0) * weight for feature, weight in archetype.weights.items()) / total_weight,
+            2,
+        )
+
+    @staticmethod
+    def _has_valid_evidence(archetype: PersonaArchetype, features: dict[str, float], score: float) -> bool:
+        return score >= archetype.minimum_score and all(
+            features.get(feature, 0.0) >= threshold for feature, threshold in archetype.required_features.items()
+        )
+
+    @staticmethod
+    def _format_metric(metric: str, value: float | int) -> str:
+        labels = {
+            "savings_rate": "储蓄率",
+            "late_night_share": "深夜消费占比",
+            "late_night_count": "深夜交易笔数",
+            "weekend_share": "周末消费占比",
+            "weekend_count": "周末交易笔数",
+            "payday_share": "工资到账后消费占比",
+            "frequent_small_count": "高频小额交易笔数",
+            "frequent_small_share": "高频小额消费占比",
+            "food_share": "餐饮消费占比",
+            "flexible_spend_share": "娱乐与购物占比",
+            "subscription_share": "订阅消费占比",
+            "subscription_count": "疑似订阅项数",
+            "learning_share": "学习消费占比",
+            "learning_active_months": "有学习消费的月份数",
+            "impulse": "冲动消费特征分",
+        }
+        suffix = "" if metric.endswith("count") or metric.endswith("months") else "%"
+        rendered = str(value) if suffix == "" else f"{float(value):.1f}{suffix}"
+        return f"{labels.get(metric, metric)} {rendered}"
+
+    def _evidence_for(self, metric_keys: Iterable[str], metrics: dict[str, float | int]) -> list[str]:
+        return [self._format_metric(key, metrics[key]) for key in metric_keys if key in metrics]
+
+    def run(
+        self,
+        summary: dict,
+        categories: dict[str, float],
+        patterns: dict,
+        subscriptions: list[dict],
+        transactions: Iterable[Transaction] | None = None,
+    ) -> tuple[dict, dict]:
+        feature_vector, metrics = self._extract_features(summary, categories, patterns, subscriptions, transactions)
+        scored = [
+            {
+                "archetype": archetype,
+                "score": self._score(archetype, feature_vector),
+            }
+            for archetype in self.archetypes
+        ]
+        valid = [item for item in scored if self._has_valid_evidence(item["archetype"], feature_vector, item["score"])]
+        valid.sort(key=lambda item: (-item["score"], item["archetype"].archetype_id))
+
+        if valid:
+            primary_item = valid[0]
+            primary = primary_item["archetype"]
+            primary_score = primary_item["score"]
+            secondary_items = valid[1:3]
+        else:
+            primary = PersonaArchetype(
+                archetype_id=str(self.fallback["id"]),
+                name=str(self.fallback["name"]),
+                minimum_score=0.0,
+                required_features={},
+                weights={},
+                evidence_metrics=tuple(str(item) for item in self.fallback.get("evidence_metrics", [])),
+            )
+            primary_score = 0.0
+            secondary_items = []
+
+        evidence = self._evidence_for(primary.evidence_metrics, metrics)
+        if not evidence:
+            evidence = ["当前账单的高风险消费信号不集中,消费结构保持相对均衡"]
+        secondary = [
+            {
+                "archetype": item["archetype"].archetype_id,
+                "name": item["archetype"].name,
+                "score": item["score"],
+                "confidence": round(item["score"] / 100, 2),
+                "evidence": self._evidence_for(item["archetype"].evidence_metrics, metrics),
+            }
+            for item in secondary_items
+        ]
+        narrative = self.runtime.explain(
+            "基于经过程序验证的人格原型写两句年轻化、温和的消费说明。"
+            f"稳定原型={primary.archetype_id};展示名={primary.name};匹配分={primary_score:.1f};"
+            f"证据={';'.join(evidence)}。不要改写原型归属、不要编造金额或比例、不要将餐饮泛化成咖啡,"
+            "可以给一个不含数字的趣味别称,但必须围绕稳定原型表达。",
+            mode="simple",
+            evidence=[
+                "人格特征向量=" + json.dumps(feature_vector, ensure_ascii=False),
+                "已验证人格证据=" + ";".join(evidence),
+            ],
+        )
+        candidates = [
+            {
+                "archetype": item["archetype"].archetype_id,
+                "name": item["archetype"].name,
+                "score": item["score"],
+                "evidence_valid": self._has_valid_evidence(item["archetype"], feature_vector, item["score"]),
+            }
+            for item in sorted(scored, key=lambda item: (-item["score"], item["archetype"].archetype_id))
+        ]
+        persona = {
+            "primary": primary.name,
+            "archetype": primary.archetype_id,
+            "score": primary_score,
+            "confidence": round(primary_score / 100, 2),
+            "labels": [primary.name, *(item["name"] for item in secondary)],
+            "secondary": secondary,
+            "evidence": evidence,
+            "feature_vector": feature_vector,
+            "narrative": narrative,
+        }
+        trace = {
+            "agent": "PersonaAgent",
+            "paradigm": self.paradigm,
+            "config_path": str(self.config_path),
+            "grounded_metrics": metrics,
+            "feature_vector": feature_vector,
+            "candidates": candidates,
+            "llm_role": "仅生成年轻化解释,不决定人格原型、分数或证据",
+        }
+        return persona, trace

+ 415 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/quest_agent.py

@@ -0,0 +1,415 @@
+"""LLM-orchestrated, evidence-locked Money Quest generation.
+
+The QuestAgent intentionally separates three concerns:
+
+1. Python rules discover auditable behavioural signals from the imported bill.
+2. The configured LLM selects and narrates an RPG-style Quest plan as JSON.
+3. Python validates every LLM field and derives all targets, progress, EXP and
+   completion states from the original tool output.
+
+That boundary keeps the interaction playful without allowing a model to invent
+money amounts, completion evidence, or unrelated content.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+from ..memory import SQLiteMemory
+from ..models import Achievement, Quest, Transaction
+from ..tools.quest_progress import QuestProgressTool
+from .runtime import HelloAgentsRuntime, LLMCallError
+
+
+@dataclass(frozen=True, slots=True)
+class _QuestBlueprint:
+    """A Python-owned Quest contract exposed to the LLM as an eligible signal."""
+
+    signal_id: str
+    quest_id: str
+    quest_type: str
+    target: float
+    unit: str
+    exp_reward: int
+    constraint: str
+    evidence: str
+    priority: str = "optional"
+
+    def public_signal(self) -> dict[str, Any]:
+        """Return only selection context, never authority over numeric outcomes."""
+        return {
+            "signal_id": self.signal_id,
+            "priority": self.priority,
+            "verified_observation": self.evidence,
+            "locked_constraint": self.constraint,
+            "completion_source": "Python QuestProgressTool" if self.quest_type not in {"subscription_review", "manual"} else "用户 CLI 确认后由 SQLite Memory 记录",
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class _QuestCandidate:
+    """The small, non-numeric portion the LLM is allowed to author."""
+
+    signal_id: str
+    title: str
+    narrative: str
+    action_hint: str
+
+
+class QuestAgent:
+    """Turn deterministic behaviour signals into validated LLM-designed Quests."""
+
+    paradigm = "规则发现真实信号 → PlanSolveAgent 动态编排 → Python 强校验与进度计算"
+    _MAX_QUESTS = 5
+
+    def __init__(self, memory: SQLiteMemory, runtime: HelloAgentsRuntime | None = None) -> None:
+        self.memory = memory
+        self.runtime = runtime
+        self.progress_tool = QuestProgressTool()
+
+    def run(
+        self,
+        transactions: Iterable[Transaction],
+        month: str,
+        summary: dict,
+        categories: dict[str, float],
+        patterns: dict,
+        subscriptions: list[dict],
+        budget: dict,
+        goals: list[dict] | None = None,
+    ) -> tuple[list[Quest], list[Achievement], dict, dict]:
+        """Create Quest objects through the LLM selection + Python validation path.
+
+        ``goals`` is intentionally passed as an already projected deterministic
+        result; the LLM can prioritize a goal signal but cannot change its
+        feasibility or monthly amount.
+        """
+        transactions = list(transactions)
+        blueprints = self._discover_signals(summary, categories, patterns, subscriptions, budget, goals or [])
+        candidates, validation = self._orchestrate_candidates(blueprints, month)
+        quests = [self._materialize(candidate, blueprints[candidate.signal_id]) for candidate in candidates]
+        quests = [self.progress_tool.update(quest, transactions, month) for quest in quests]
+        self._restore_manual_completions(quests, month)
+        for quest in quests:
+            self.memory.save_quest(quest)
+
+        gamification = self._gamification(quests, transactions, month)
+        achievements = self._achievements(summary, patterns, quests, gamification)
+        for achievement in achievements:
+            if achievement.unlocked:
+                self.memory.save_achievement(achievement.to_dict())
+
+        trace = {
+            "agent": "QuestAgent",
+            "paradigm": self.paradigm,
+            "tools": ["StatisticsTool", "BudgetCalculatorTool", "SubscriptionDetectorTool", "QuestProgressTool"],
+            "signal_catalog": [blueprint.public_signal() for blueprint in blueprints.values()],
+            "llm_orchestration": {
+                "candidate_count": len(candidates),
+                "accepted_signal_ids": [candidate.signal_id for candidate in candidates],
+                "validation": validation,
+                "numeric_authority": "Python only: target / progress / EXP / status are derived from locked blueprints and QuestProgressTool.",
+            },
+            "quest_evidence": [quest.evidence for quest in quests],
+        }
+        return quests, achievements, gamification, trace
+
+    def _discover_signals(
+        self,
+        summary: dict,
+        categories: dict[str, float],
+        patterns: dict,
+        subscriptions: list[dict],
+        budget: dict,
+        goals: list[dict],
+    ) -> dict[str, _QuestBlueprint]:
+        """Discover only reproducible signals; no model is involved here."""
+        signals: dict[str, _QuestBlueprint] = {}
+        late_night = patterns.get("late_night", {})
+        frequent_small = patterns.get("frequent_small", {})
+        weekend = patterns.get("weekend", {})
+        payday = patterns.get("payday_window", {})
+
+        if int(late_night.get("count", 0)) >= 2:
+            signals["late_night"] = _QuestBlueprint(
+                "late_night", "late_night_guard", "late_night_limit", 1.0, "笔", 80,
+                "22:00 后支出最多 1 笔。",
+                f"深夜消费 {int(late_night['count'])} 笔,合计 ¥{float(late_night.get('amount', 0)):.2f}。",
+                "required",
+            )
+        if int(frequent_small.get("count", 0)) >= 6:
+            signals["frequent_small"] = _QuestBlueprint(
+                "frequent_small", "zero_spend_scout", "zero_spend_days", 2.0, "天", 100,
+                "在当前分析区间内完成 2 个无支出日。",
+                f"发现 {int(frequent_small['count'])} 笔不高于 ¥50 的高频小额支出,合计 ¥{float(frequent_small.get('amount', 0)):.2f}。",
+                "required",
+            )
+
+        flexible_categories = [category for category in ("娱乐", "购物") if float(categories.get(category, 0)) > 0]
+        if flexible_categories:
+            category = max(flexible_categories, key=lambda item: float(categories[item]))
+            recommended = float(budget.get("categories", {}).get(category, {}).get("recommended", categories[category]))
+            signals["flexible_budget"] = _QuestBlueprint(
+                "flexible_budget", f"{category}_budget", "category_limit", recommended, category, 120,
+                f"{category}支出不高于已核验的动态预算 ¥{recommended:.2f}。",
+                f"{category}本月已支出 ¥{float(categories[category]):.2f};动态预算为 ¥{recommended:.2f}。",
+                "required",
+            )
+        if subscriptions:
+            review_count = float(min(3, len(subscriptions)))
+            signals["subscriptions"] = _QuestBlueprint(
+                "subscriptions", "subscription_hunter", "subscription_review", review_count, "项", 90,
+                f"检查 {int(review_count)} 项疑似连续扣费,并仅保留仍会使用的服务。",
+                f"发现 {len(subscriptions)} 项疑似连续扣费。",
+                "required",
+            )
+        if int(weekend.get("count", 0)) >= 3 and float(weekend.get("share", 0)) >= 30:
+            target = round(max(1.0, float(weekend.get("amount", 0)) * 0.85), 2)
+            signals["weekend"] = _QuestBlueprint(
+                "weekend", "weekend_wallet_shield", "weekend_spend_limit", target, "元", 110,
+                f"周末支出不高于已核验的温和目标 ¥{target:.2f}。",
+                f"周末消费 {int(weekend['count'])} 笔,占本月支出 {float(weekend['share']):.2f}%。",
+            )
+        if int(payday.get("count", 0)) >= 3 and float(payday.get("share", 0)) >= 25:
+            target = round(max(1.0, float(payday.get("amount", 0)) * 0.85), 2)
+            signals["payday"] = _QuestBlueprint(
+                "payday", "payday_cooldown", "payday_window_limit", target, "元", 110,
+                f"工资到账后 3 天内支出不高于已核验的温和目标 ¥{target:.2f}。",
+                f"工资到账后 3 天内发生 {int(payday['count'])} 笔支出,占本月支出 {float(payday['share']):.2f}%。",
+            )
+        learning = float(categories.get("学习", 0))
+        expense = max(float(summary.get("expense", 0)), 1.0)
+        if learning >= 100 and learning / expense >= 0.08:
+            signals["learning_followthrough"] = _QuestBlueprint(
+                "learning_followthrough", "learning_loot_log", "manual", 1.0, "次", 70,
+                "记录 1 次学习服务是否真正被使用,并标注下次使用时间。",
+                f"学习类支出为 ¥{learning:.2f},占本月支出 {learning / expense * 100:.2f}%。",
+            )
+        actionable_goals = [goal for goal in goals if goal.get("feasible") and float(goal.get("required_monthly_amount", 0)) > 0]
+        if actionable_goals and float(summary.get("balance", 0)) > 0:
+            goal = min(actionable_goals, key=lambda item: float(item.get("required_monthly_amount", 0)))
+            signals["goal_transfer"] = _QuestBlueprint(
+                "goal_transfer", "goal_supply_line", "manual", 1.0, "次", 75,
+                "确认 1 次本月结余如何服务于已设置的财务目标。",
+                f"目标“{goal.get('title', '储蓄目标')}”每月仍需约 ¥{float(goal['required_monthly_amount']):.2f};本月结余 ¥{float(summary.get('balance', 0)):.2f}。",
+            )
+        if not signals:
+            signals["balance"] = _QuestBlueprint(
+                "balance", "balance_builder", "manual", 1.0, "次", 60,
+                "记录 1 次消费决策,并确认它是否服务于你的目标。",
+                "尚未发现需要优先处理的高强度消费信号,适合建立一条自己的决策记录。",
+                "required",
+            )
+        return signals
+
+    def _orchestrate_candidates(
+        self,
+        blueprints: dict[str, _QuestBlueprint],
+        month: str,
+    ) -> tuple[list[_QuestCandidate], dict[str, Any]]:
+        if self.runtime is None or not self.runtime.status.enabled:
+            raise LLMCallError("Quest 动态编排必须使用已配置的 LLM,当前运行时不可用。")
+        catalog = [blueprint.public_signal() for blueprint in blueprints.values()]
+        prompt = (
+            "你是 MoneyMirrorAgent 的 Quest 编排师。根据 Python 已核验的行为信号,为年轻用户选择并命名个性化 RPG Quest。"
+            "这是严格的 JSON 协议:你只负责选择信号、标题、氛围叙述和一条可执行提示;不得创造金额、次数、日期、完成状态、EXP 或新的 signal_id。"
+            "必须包含全部 priority=required 的信号;optional 信号可按相关性最多选 2 个;总数不超过 5。"
+            "title 为 4-18 个中文字符、无数字;narrative 与 action_hint 各 8-90 字、无数字/金额/百分比,语气友好、轻松、不羞辱。"
+            "只输出一个 JSON 对象,禁止 Markdown 代码块和任何解释,格式严格如下:\n"
+            '{"quests":[{"signal_id":"...","title":"...","narrative":"...","action_hint":"..."}]}\n'
+            f"分析月份:{month}\nSIGNAL_CATALOG_JSON:\n{json.dumps(catalog, ensure_ascii=False, separators=(',', ':'))}"
+        )
+        first = self.runtime.generate_quest_candidates(prompt)
+        candidates, problems = self._parse_and_validate_candidates(first, blueprints)
+        if candidates:
+            return candidates, {"attempts": 1, "repaired": False, "rejected": problems}
+
+        repair_prompt = (
+            "你的上一条 Quest JSON 未通过 Python 强校验。请立刻仅输出一个非空 JSON 对象,不要解释、不要 Markdown。"
+            "字段必须严格为 {\"quests\":[{\"signal_id\":\"...\",\"title\":\"...\",\"narrative\":\"...\",\"action_hint\":\"...\"}]}。"
+            "只可使用目录中的 signal_id,必须包含全部 priority=required 信号;不得出现金额、数字、日期、EXP、进度或完成状态。"
+            f"校验问题:{';'.join(problems[:6])}\n"
+            f"允许信号:{', '.join(blueprints)}。必须包含:{', '.join(item.signal_id for item in blueprints.values() if item.priority == 'required')}。\n"
+            f"SIGNAL_CATALOG_JSON:\n{json.dumps(catalog, ensure_ascii=False, separators=(',', ':'))}"
+        )
+        repaired = self.runtime.generate_quest_candidates(repair_prompt)
+        candidates, repair_problems = self._parse_and_validate_candidates(repaired, blueprints)
+        if not candidates:
+            details = ";".join(repair_problems[:8]) or "LLM 未返回可验证的 Quest JSON"
+            raise LLMCallError(f"Quest 动态编排输出未通过 Python 强校验:{details}")
+        return candidates, {"attempts": 2, "repaired": True, "rejected": problems, "repair_rejected": repair_problems}
+
+    def _parse_and_validate_candidates(
+        self,
+        raw: str,
+        blueprints: dict[str, _QuestBlueprint],
+    ) -> tuple[list[_QuestCandidate], list[str]]:
+        problems: list[str] = []
+        try:
+            payload = self._extract_json(raw)
+        except ValueError as exc:
+            return [], [str(exc)]
+        rows = payload.get("quests") if isinstance(payload, dict) else None
+        if not isinstance(rows, list) or not rows:
+            return [], ["根对象必须含有非空 quests 数组"]
+        if len(rows) > self._MAX_QUESTS:
+            return [], [f"Quest 数量超过上限 {self._MAX_QUESTS}"]
+
+        candidates: list[_QuestCandidate] = []
+        seen: set[str] = set()
+        for index, row in enumerate(rows):
+            if not isinstance(row, dict):
+                problems.append(f"quests[{index}] 不是对象")
+                continue
+            required_keys = {"signal_id", "title", "narrative", "action_hint"}
+            if set(row) != required_keys:
+                problems.append(f"quests[{index}] 字段必须严格为 {sorted(required_keys)}")
+                continue
+            signal_id = str(row["signal_id"]).strip()
+            if signal_id not in blueprints:
+                problems.append(f"不允许的 signal_id:{signal_id}")
+                continue
+            if signal_id in seen:
+                problems.append(f"signal_id 重复:{signal_id}")
+                continue
+            title = self._clean_copy(row["title"])
+            narrative = self._clean_copy(row["narrative"])
+            action_hint = self._clean_copy(row["action_hint"])
+            if not (4 <= len(title) <= 18):
+                problems.append(f"{signal_id} 的 title 长度不在 4-18")
+                continue
+            if not (8 <= len(narrative) <= 90 and 8 <= len(action_hint) <= 90):
+                problems.append(f"{signal_id} 的 narrative/action_hint 长度不在 8-90")
+                continue
+            unsafe = self._unsafe_copy(title) or self._unsafe_copy(narrative) or self._unsafe_copy(action_hint)
+            if unsafe:
+                problems.append(f"{signal_id} 文案包含不允许内容:{unsafe}")
+                continue
+            seen.add(signal_id)
+            candidates.append(_QuestCandidate(signal_id, title, narrative, action_hint))
+
+        required = {item.signal_id for item in blueprints.values() if item.priority == "required"}
+        missing = sorted(required - seen)
+        if missing:
+            problems.append(f"缺少 required 信号:{', '.join(missing)}")
+        if problems or not candidates:
+            return [], problems
+        return candidates, []
+
+    @staticmethod
+    def _extract_json(raw: str) -> dict[str, Any]:
+        text = str(raw).strip()
+        if text.startswith("```"):
+            text = re.sub(r"^```(?:json)?\s*|\s*```$", "", text, flags=re.IGNORECASE).strip()
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            start = text.find("{")
+            end = text.rfind("}")
+            if start < 0 or end <= start:
+                raise ValueError("LLM 没有返回可解析的 Quest JSON") from None
+            try:
+                parsed = json.loads(text[start : end + 1])
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"LLM Quest JSON 格式错误:{exc.msg}") from exc
+        if not isinstance(parsed, dict):
+            raise ValueError("LLM Quest JSON 根节点必须是对象")
+        return parsed
+
+    @staticmethod
+    def _clean_copy(value: Any) -> str:
+        return re.sub(r"\s+", " ", str(value).strip())
+
+    def _unsafe_copy(self, text: str) -> str | None:
+        # Amounts, percentages, and Arabic-number commitments are prohibited
+        # in model copy. Natural Chinese wording such as “每一笔” is allowed as
+        # flavour only: it cannot alter the separately appended Python-owned
+        # target, progress, EXP, status, or evidence.
+        if any(character.isdigit() for character in text) or any(token in text for token in ("¥", "元", "%")):
+            return "金额、百分比或阿拉伯数字只能由 Python 写入锁定约束"
+        return None
+
+    @staticmethod
+    def _materialize(candidate: _QuestCandidate, blueprint: _QuestBlueprint) -> Quest:
+        description = (
+            f"{candidate.narrative}\n"
+            f"🧩 小提示:{candidate.action_hint}\n"
+            f"🎯 已核验目标:{blueprint.constraint}"
+        )
+        return Quest(
+            blueprint.quest_id,
+            candidate.title,
+            description,
+            blueprint.quest_type,
+            blueprint.target,
+            0,
+            blueprint.unit,
+            blueprint.exp_reward,
+        )
+
+    def _restore_manual_completions(self, quests: list[Quest], month: str) -> None:
+        """Restore only CLI-confirmable outcomes from month-scoped Memory."""
+        manually_completed = set(self.memory.get_preference(f"manual_completed_quests:{month}", []))
+        for quest in quests:
+            if quest.quest_id in manually_completed and quest.quest_type in {"subscription_review", "manual"}:
+                quest.progress = quest.target
+                quest.status = "completed"
+                quest.evidence = f"用户已在 CLI 中确认完成({month})"
+
+    def complete_manual_quest(self, quest: Quest, month: str, note: str = "") -> dict:
+        """Record a user-confirmed Quest only where transactions cannot prove it."""
+        if quest.quest_type not in {"subscription_review", "manual"}:
+            raise ValueError(f"{quest.title} 的进度由账单自动计算,不能手动完成。")
+        quest.progress = quest.target
+        quest.status = "completed"
+        detail = note.strip() or "用户已在 CLI 中确认完成"
+        quest.evidence = f"{detail}({month})"
+        self.memory.save_quest(quest)
+        manual_key = f"manual_completed_quests:{month}"
+        manual_completed = set(self.memory.get_preference(manual_key, []))
+        manual_completed.add(quest.quest_id)
+        self.memory.set_preference(manual_key, sorted(manual_completed))
+
+        completed_ids = set(self.memory.get_preference("completed_quest_ids", []))
+        gained_exp = 0
+        if quest.quest_id not in completed_ids:
+            completed_ids.add(quest.quest_id)
+            gained_exp = quest.exp_reward
+            self.memory.set_preference("completed_quest_ids", sorted(completed_ids))
+            self.memory.set_preference("total_exp", int(self.memory.get_preference("total_exp", 0)) + gained_exp)
+        return {
+            "gained_exp": gained_exp,
+            "total_exp": int(self.memory.get_preference("total_exp", 0)),
+            "level": 1 + int(self.memory.get_preference("total_exp", 0)) // 200,
+        }
+
+    def _gamification(self, quests: list[Quest], transactions: list[Transaction], month: str) -> dict:
+        completed_ids = set(self.memory.get_preference("completed_quest_ids", []))
+        new_completed = [quest for quest in quests if quest.status == "completed" and quest.quest_id not in completed_ids]
+        completed_ids.update(quest.quest_id for quest in new_completed)
+        total_exp = int(self.memory.get_preference("total_exp", 0)) + sum(quest.exp_reward for quest in new_completed)
+        current_streak = self.progress_tool.max_zero_spend_streak(transactions, month)
+        longest_streak = max(int(self.memory.get_preference("longest_streak_days", 0)), current_streak)
+        self.memory.set_preference("completed_quest_ids", sorted(completed_ids))
+        self.memory.set_preference("total_exp", total_exp)
+        self.memory.set_preference("longest_streak_days", longest_streak)
+        return {
+            "level": 1 + total_exp // 200,
+            "total_exp": total_exp,
+            "exp_gained_this_cycle": sum(quest.exp_reward for quest in new_completed),
+            "current_streak_days": current_streak,
+            "longest_streak_days": longest_streak,
+        }
+
+    @staticmethod
+    def _achievements(summary: dict, patterns: dict, quests: list[Quest], gamification: dict) -> list[Achievement]:
+        return [
+            Achievement("savings_rate_20", "储蓄率破 20%", "储蓄率首次达到或超过 20%。", summary.get("savings_rate", 0) >= 20),
+            Achievement("zero_spend_start", "零消费日初体验", "完成至少一个零消费日。", any(item.quest_type == "zero_spend_days" and item.progress >= 1 for item in quests)),
+            Achievement("quest_ready", "任务上线", "已生成基于真实账单的 Money Quest。", bool(quests)),
+            Achievement("late_night_awareness", "深夜雷达启动", "已识别深夜消费行为并生成应对任务。", patterns["late_night"]["count"] > 0),
+            Achievement("zero_spend_streak_3", "三日无消费连击", "连续 3 天没有支出记录。", gamification.get("longest_streak_days", 0) >= 3),
+        ]

+ 131 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/reflection_agent.py

@@ -0,0 +1,131 @@
+"""ReflectionAgent compares persisted plans with actual outcomes."""
+
+from __future__ import annotations
+
+from ..memory import SQLiteMemory
+from .runtime import HelloAgentsRuntime
+
+
+class ReflectionAgent:
+    paradigm = "ReflectionAgent-style: plan → actual → deviation → adjustment"
+
+    def __init__(self, memory: SQLiteMemory, runtime: HelloAgentsRuntime) -> None:
+        self.memory = memory
+        self.runtime = runtime
+
+    def run(self, month: str, summary: dict, categories: dict[str, float], budget: dict, quests: list, goals: list[dict]) -> tuple[dict, dict]:
+        previous_month = self._previous_month(month)
+        previous_snapshot = self.memory.get_snapshot(previous_month)
+        budget_lines = budget.get("categories", {})
+        deviations = []
+        for category, planned in budget_lines.items():
+            actual = categories.get(category, 0.0)
+            limit = planned.get("recommended", 0.0)
+            if limit:
+                deviations.append({"category": category, "planned": limit, "actual": actual, "difference": round(actual - limit, 2), "on_budget": actual <= limit})
+        completed = sum(1 for quest in quests if getattr(quest, "status", "active") == "completed")
+        goal_state = goals[0] if goals else {}
+        strategy = []
+        overspent = sorted((item for item in deviations if item["difference"] > 0), key=lambda item: item["difference"], reverse=True)
+        if overspent:
+            strategy.append(f"优先为 {overspent[0]['category']} 保留明确额度,而不是一刀切禁止消费。")
+        if summary.get("savings_rate", 0) < 20:
+            strategy.append("把结余转入目标账户的动作安排在收入到账后 24 小时内。")
+        if completed == 0 and quests:
+            strategy.append("下阶段只保留 2 个可执行任务,降低任务负担。")
+        if not strategy:
+            strategy.append("当前计划与实际较匹配,维持预算框架并逐步提高目标储蓄。")
+
+        next_month = self._next_month(month)
+        next_budget = self._next_cycle_budget(budget_lines, deviations)
+        next_cycle_quests = self._next_cycle_quests(quests, overspent, next_budget)
+        prior_text = "没有上月快照,本次作为基线月。" if not previous_snapshot else f"已读取 {previous_month} 的历史快照用于比较。"
+        narrative = self.runtime.explain(
+            f"按 Reflection 模式解释:月度结余={summary.get('balance')},储蓄率={summary.get('savings_rate')},任务完成={completed}/{len(quests)},预算偏差={deviations},目标={goal_state}。只能基于这些数据给 2-3 句下一周期建议。",
+            mode="reflection",
+            evidence=[
+                f"储蓄率={summary.get('savings_rate', 0):.2f}%",
+                f"任务完成={completed}/{len(quests)}",
+                f"预算偏差={deviations}",
+            ],
+            memory=[prior_text],
+        )
+        reflection = {
+            "month": month,
+            "previous_month": previous_month,
+            "has_previous_snapshot": bool(previous_snapshot),
+            "budget_deviations": deviations,
+            "quest_completion": {"completed": completed, "total": len(quests)},
+            "goal_progress": goal_state,
+            "effective": ["预算和任务均基于实际账单计算"],
+            "needs_adjustment": [item["category"] for item in overspent],
+            "next_strategy": strategy,
+            "next_cycle_month": next_month,
+            "next_cycle_budget": next_budget,
+            "next_cycle_quests": next_cycle_quests,
+            "narrative": narrative,
+        }
+        # Reflection is not just prose: persist the next-cycle artifacts so
+        # the following run/dashboard can inspect and act on them.
+        self.memory.save_budget(next_month, next_budget)
+        self.memory.save_reflection(month, reflection)
+        return reflection, {"agent": "ReflectionAgent", "paradigm": self.paradigm, "context_sources": ["SQLiteMemory: previous snapshot", "budget", "quest outcomes", "goal projection"]}
+
+    @staticmethod
+    def _previous_month(month: str) -> str:
+        year, value = map(int, month.split("-"))
+        return f"{year - 1}-12" if value == 1 else f"{year}-{value - 1:02d}"
+
+    @staticmethod
+    def _next_month(month: str) -> str:
+        year, value = map(int, month.split("-"))
+        return f"{year + 1}-01" if value == 12 else f"{year}-{value + 1:02d}"
+
+    @staticmethod
+    def _next_cycle_budget(budget_lines: dict, deviations: list[dict]) -> dict:
+        """Turn deviations into a gentle next-cycle budget adjustment.
+
+        A large one-off purchase must not cause a punitive cut. For an
+        overspent category, the next recommendation becomes a soft ceiling
+        between the old plan and 150% of it, capped by 105% of actual spend.
+        """
+
+        overspent = {item["category"]: item for item in deviations if item["difference"] > 0}
+        categories = {}
+        for category, planned in budget_lines.items():
+            line = dict(planned)
+            if category in overspent:
+                actual = overspent[category]["actual"]
+                baseline = planned.get("recommended", 0.0)
+                line["recommended"] = round(max(baseline, min(actual * 1.05, baseline * 1.5)), 2)
+                line["rationale"] = "Reflection 根据实际偏差增加缓冲,避免对一次性消费一刀切"
+            categories[category] = line
+        return {"source": "monthly_reflection", "categories": categories}
+
+    @staticmethod
+    def _next_cycle_quests(quests: list, overspent: list[dict], next_budget: dict) -> list[dict]:
+        plans = []
+        for quest in quests:
+            if getattr(quest, "status", "active") != "completed":
+                plans.append({
+                    "quest_id": f"carry_{quest.quest_id}",
+                    "title": f"延续:{quest.title}",
+                    "quest_type": quest.quest_type,
+                    "target": quest.target,
+                    "unit": quest.unit,
+                    "exp_reward": quest.exp_reward,
+                    "reason": "上周期未完成,Reflection 建议降低摩擦后继续",
+                })
+        if overspent:
+            category = overspent[0]["category"]
+            recommended = next_budget.get("categories", {}).get(category, {}).get("recommended", 0.0)
+            plans.append({
+                "quest_id": f"reflection_{category}",
+                "title": f"{category}缓冲预算挑战",
+                "quest_type": "category_limit",
+                "target": recommended,
+                "unit": category,
+                "exp_reward": 100,
+                "reason": "根据本月最大预算偏差生成",
+            })
+        return plans or [{"quest_id": "reflection_checkin", "title": "月度镜像回顾", "quest_type": "reflection_checkin", "target": 1, "unit": "次", "exp_reward": 60, "reason": "保持有效计划"}]

+ 481 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/runtime.py

@@ -0,0 +1,481 @@
+"""Strict Hello-Agents runtime for MoneyMirrorAgent.
+
+The project deliberately has no deterministic/offline substitute for language
+work.  Python tools remain the source of truth for money, statistics,
+anomalies, budgets, goals and quest progress; Hello-Agents is required for
+uncertain classification, planning, explanations, Reflection, user dialogue,
+and the final Markdown report.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+from contextlib import redirect_stdout
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Literal
+
+from dotenv import load_dotenv
+
+
+class RuntimeConfigurationError(RuntimeError):
+    """Raised when the required Hello-Agents/LLM configuration is missing."""
+
+
+class LLMCallError(RuntimeError):
+    """Raised when a required LLM call fails or returns no content."""
+
+
+@dataclass(slots=True)
+class RuntimeStatus:
+    available: bool
+    enabled: bool
+    reason: str
+    registry_name: str = "HelloAgents ToolRegistry"
+    paradigms: tuple[str, ...] = ()
+    registered_tools: tuple[str, ...] = ()
+    provider: str = "OpenAI-compatible"
+    model: str = ""
+    base_url: str = ""
+
+
+class HelloAgentsRuntime:
+    """Use the official Hello-Agents agents with a mandatory LLM backend.
+
+    ``PlanSolveAgent`` is the class name exported by hello-agents 1.x for the
+    Plan-and-Solve pattern described in the course material.  The runtime
+    keeps the agent objects in one place so every specialist can share the
+    same configured provider and Context Engineering policy.
+    """
+
+    def __init__(self) -> None:
+        self.registry: Any | None = None
+        self.agent: Any | None = None
+        self.react_agent: Any | None = None
+        self.plan_agent: Any | None = None
+        self.reflection_agent: Any | None = None
+        self.context_builder: Any | None = None
+        self.llm: Any | None = None
+        self.status = RuntimeStatus(False, False, "Hello-Agents 尚未初始化")
+        self._initialize()
+
+    def _initialize(self) -> None:
+        # This makes ``MoneyMirrorCoordinator`` usable from tests, notebooks,
+        # CLI, notebooks and tests can initialize from any working directory.
+        project_root = Path(__file__).resolve().parents[2]
+        load_dotenv(project_root / ".env", override=False)
+
+        required = {
+            "LLM_API_KEY": os.getenv("LLM_API_KEY", "").strip(),
+            "LLM_BASE_URL": os.getenv("LLM_BASE_URL", "").strip(),
+            "LLM_MODEL_ID": os.getenv("LLM_MODEL_ID", "").strip(),
+        }
+        missing = [name for name, value in required.items() if not value]
+        if missing:
+            self.status = RuntimeStatus(
+                False,
+                False,
+                "缺少必需的 LLM 配置:" + ", ".join(missing) + "。请复制 .env.example 为 .env 并填写。",
+                model=required["LLM_MODEL_ID"],
+                base_url=required["LLM_BASE_URL"],
+            )
+            raise RuntimeConfigurationError(self.status.reason)
+
+        try:
+            from hello_agents import (  # type: ignore
+                Config,
+                HelloAgentsLLM,
+                PlanSolveAgent,
+                ReActAgent,
+                ReflectionAgent as HelloReflectionAgent,
+                SimpleAgent,
+            )
+            from hello_agents.tools import ToolRegistry  # type: ignore
+        except Exception as exc:  # pragma: no cover - dependency installation issue
+            raise RuntimeConfigurationError(f"无法导入 hello-agents:{exc}") from exc
+
+        try:
+            self.registry = ToolRegistry()
+            try:
+                from hello_agents.context import ContextBuilder, ContextConfig  # type: ignore
+
+                # DeepSeek-V4-Flash has a large context window. Keep an explicit,
+                # configurable client-side budget so Hello-Agents does not discard
+                # verified evidence before it reaches the model. The report packet
+                # is still compacted at the caller for predictable latency/cost.
+                self.context_builder = ContextBuilder(
+                    ContextConfig(
+                        max_tokens=int(os.getenv("LLM_CONTEXT_MAX_TOKENS", "100000")),
+                        # Verified evidence must not be filtered just because a
+                        # Chinese user query shares few whitespace-separated
+                        # tokens with compact JSON.
+                        min_relevance=0.0,
+                    )
+                )
+            except Exception:
+                self.context_builder = None
+
+            self.llm = HelloAgentsLLM(
+                model=required["LLM_MODEL_ID"],
+                api_key=required["LLM_API_KEY"],
+                base_url=required["LLM_BASE_URL"],
+                temperature=float(os.getenv("LLM_TEMPERATURE", "0.2")),
+                max_tokens=int(os.getenv("LLM_MAX_TOKENS", "16384")),
+                timeout=int(os.getenv("LLM_TIMEOUT", "90")),
+            )
+            config = Config(
+                debug=False,
+                max_history_length=8,
+                trace_enabled=False,
+                session_enabled=False,
+                skills_enabled=False,
+                auto_save_enabled=False,
+                stream_enabled=False,
+            )
+            system_prompt = (
+                "你是 MoneyMirrorAgent 的语言推理智能体。所有金额、统计、异常检测、预算、"
+                "目标投影和 Quest 进度已经由 Python 工具计算。只能基于已验证证据解释、规划"
+                "和生成文案;不许编造数值。"
+            )
+            with redirect_stdout(io.StringIO()):
+                self.agent = SimpleAgent(
+                    name="MoneyMirror 解释智能体",
+                    llm=self.llm,
+                    system_prompt=system_prompt,
+                    config=config,
+                    tool_registry=self.registry,
+                    enable_tool_calling=False,
+                )
+                self.react_agent = ReActAgent(
+                    name="MoneyMirror Transaction ReActAgent",
+                    llm=self.llm,
+                    tool_registry=self.registry,
+                    system_prompt=system_prompt,
+                    config=config,
+                    max_steps=3,
+                )
+                self.plan_agent = PlanSolveAgent(
+                    name="MoneyMirror PlanAndSolveAgent",
+                    llm=self.llm,
+                    system_prompt=system_prompt,
+                    config=config,
+                    tool_registry=self.registry,
+                    enable_tool_calling=False,
+                    max_tool_iterations=1,
+                )
+                self.reflection_agent = HelloReflectionAgent(
+                    name="MoneyMirror ReflectionAgent",
+                    llm=self.llm,
+                    system_prompt=system_prompt,
+                    config=config,
+                    tool_registry=self.registry,
+                    enable_tool_calling=False,
+                    max_iterations=2,
+                )
+        except Exception as exc:
+            self.status = RuntimeStatus(
+                False,
+                False,
+                f"Hello-Agents/LLM 初始化失败:{exc}",
+                model=required["LLM_MODEL_ID"],
+                base_url=required["LLM_BASE_URL"],
+            )
+            raise RuntimeConfigurationError(self.status.reason) from exc
+
+        self.status = RuntimeStatus(
+            True,
+            True,
+            f"已启用 Hello-Agents + OpenAI 兼容 LLM:{required['LLM_MODEL_ID']}",
+            paradigms=("ReActAgent", "PlanSolveAgent", "ReflectionAgent", "Context Engineering"),
+            provider="OpenAI-compatible",
+            model=required["LLM_MODEL_ID"],
+            base_url=required["LLM_BASE_URL"],
+        )
+
+    def register_tool_functions(self, functions: dict[str, tuple[Any, str]]) -> None:
+        """Expose deterministic tools to Hello-Agents ToolRegistry."""
+        if self.registry is None:  # pragma: no cover - guarded by init
+            raise RuntimeConfigurationError("ToolRegistry 尚未初始化")
+        registered: list[str] = []
+        with redirect_stdout(io.StringIO()):
+            for name, (function, description) in functions.items():
+                self.registry.register_function(function, name=name, description=description)
+                registered.append(name)
+        self.status.registered_tools = tuple(registered)
+        self.status.registry_name = f"HelloAgents ToolRegistry ({len(registered)} MoneyMirror tools)"
+
+    def build_context(self, task: str, evidence: Iterable[str] = (), memory: Iterable[str] = ()) -> str:
+        """Build a GSSC-style context packet with verified facts separated."""
+        evidence_packets = [f"[Verified tool output]\n{item}" for item in evidence]
+        memory_packets = [f"[Long-term Memory]\n{item}" for item in memory]
+        if self.context_builder is not None:
+            try:
+                from hello_agents.context import ContextPacket  # type: ignore
+
+                packets = [
+                    ContextPacket(content=item, metadata={"type": "tool_result"}) for item in evidence_packets
+                ] + [ContextPacket(content=item, metadata={"type": "related_memory"}) for item in memory_packets]
+                built = self.context_builder.build(
+                    user_query=task,
+                    system_instructions=(
+                        "只使用 Verified tool output 作为数字事实;Long-term Memory 只能作为历史上下文,"
+                        "不要把它当作当前月计算结果。"
+                    ),
+                    additional_packets=packets,
+                )
+                # ContextBuilder 1.x appends a generic numbered answer template
+                # (结论/依据/风险/下一步). That template is useful for generic
+                # tasks but conflicts with MoneyMirror's playful one-question
+                # coaching protocol. Keep GSSC evidence selection while removing
+                # only that generic output instruction.
+                return built.split("\n\n[Output]\n", 1)[0]
+            except Exception:
+                # ContextBuilder API can vary between hello-agents patch releases;
+                # the explicit packet format below preserves the same semantics.
+                pass
+        parts = ["[Task]", task]
+        if evidence_packets:
+            parts.extend(["[Evidence]", *evidence_packets])
+        if memory_packets:
+            parts.extend(["[Context]", *memory_packets])
+        return "\n".join(parts)
+
+    def explain(
+        self,
+        prompt: str,
+        mode: Literal["simple", "react", "plan", "reflection"] = "simple",
+        evidence: Iterable[str] = (),
+        memory: Iterable[str] = (),
+    ) -> str:
+        """Run a required language-agent call and return its non-empty text."""
+        # ``deepseek-v4-flash`` accepts normal chat completions but rejects the
+        # function-tool choice issued internally by Hello-Agents' current
+        # ReAct/PlanSolve/Reflection implementations in thinking mode.  The
+        # specialist *roles* still use those paradigms and the ToolRegistry,
+        # while their language response is executed by the official
+        # SimpleAgent with a mode-specific instruction. This keeps the real
+        # provider path stable instead of silently falling back to templates.
+        if self.agent is None:
+            raise LLMCallError("Hello-Agents SimpleAgent 未初始化")
+        role_instruction = {
+            "simple": "以清晰、温和的解释者身份回答。",
+            "react": "按 ReAct 的观察-判断-结论节奏回答,但不要输出思维链或虚构工具调用。",
+            "plan": "按 Plan-and-Solve 的先规划后行动节奏回答,直接给出简洁结果。",
+            "reflection": "按 Reflection 的计划-实际-调整节奏回答,给出下一步行动。",
+        }.get(mode)
+        if role_instruction is None:
+            raise LLMCallError(f"未知 Agent 模式:{mode}")
+        context = self.build_context(role_instruction + "\n" + prompt, evidence, memory)
+        last_error: Exception | None = None
+        for attempt in range(2):
+            try:
+                # hello-agents emits progress logs to stdout. Keep CLI/UI
+                # output focused on the actual answer while retaining the
+                # official SimpleAgent execution path.
+                # Each specialist call is a fresh bounded turn. Otherwise
+                # SimpleAgent accumulates persona/quest/reflection prompts and
+                # eventually sends stale contexts back to the provider.
+                try:
+                    self.agent.clear_history()
+                except Exception:
+                    pass
+                with redirect_stdout(io.StringIO()):
+                    text = self.agent.run(context)
+                text = str(text).strip()
+                if text:
+                    return text
+                last_error = LLMCallError(f"{mode} Agent 返回空内容")
+            except Exception as exc:
+                last_error = exc
+            if attempt == 0:
+                # A transient empty response is retried once. No local prose
+                # or deterministic fallback is introduced.
+                continue
+        try:
+            return self._direct_llm_answer(context, mode)
+        except LLMCallError as direct_error:
+            raise LLMCallError(
+                f"{mode} Agent 调用失败,且直接 LLM 重试失败:{direct_error}"
+            ) from (last_error or direct_error)
+
+    def _direct_llm_answer(self, context: str, mode: str) -> str:
+        """Provider-compatible direct completion used when an Agent wrapper
+        returns an empty response (some thinking-model/tool combinations do).
+
+        This is still the configured HelloAgentsLLM client and never a local
+        fallback. It keeps the user-facing pipeline reliable across provider
+        patch versions while the official Agent objects remain initialized and
+        registered for the architecture/traces.
+        """
+        if self.llm is None:
+            raise LLMCallError("LLM 尚未初始化")
+        system = (
+            "你是 MoneyMirrorAgent 的语言智能体。请直接输出最终中文答案,不要输出思维链、"
+            "工具调用、空响应或过程日志。数字只能来自 Verified tool output。"
+            f"当前角色模式:{mode}。"
+        )
+        try:
+            response = self.llm.invoke(
+                [{"role": "system", "content": system}, {"role": "user", "content": context}],
+                temperature=0.2,
+            )
+            text = str(getattr(response, "content", response)).strip()
+        except Exception as exc:
+            raise LLMCallError(f"直接 LLM 调用失败:{exc}") from exc
+        if not text:
+            raise LLMCallError("直接 LLM 返回空内容")
+        return text
+
+    def generate_quest_candidates(self, prompt: str) -> str:
+        """Request strict QuestCandidate JSON from the configured LLM.
+
+        Agent wrappers are excellent for natural-language roles, but their
+        PlanSolve instruction can add prose around a schema. Quest selection is
+        a machine-validated boundary, so it uses the same required
+        ``HelloAgentsLLM`` client in JSON-object mode. This is not an offline
+        fallback: provider failure or invalid output remains an explicit error
+        handled by :class:`QuestAgent` and repaired through a second LLM turn.
+        """
+        if self.llm is None:
+            raise LLMCallError("LLM 尚未初始化")
+        messages = [
+            {
+                "role": "system",
+                "content": (
+                    "你是 MoneyMirrorAgent 的 Quest JSON 编排器。只返回一个合法 JSON 对象,"
+                    "不得使用 Markdown、解释、思维链或工具调用。严格遵守用户消息中的字段和安全约束;"
+                    "不得编造金额、次数、日期、进度或 EXP。"
+                ),
+            },
+            {"role": "user", "content": prompt},
+        ]
+        last_error: Exception | None = None
+        # Prefer provider JSON mode. Some OpenAI-compatible endpoints ignore or
+        # reject the option, so retry once as a normal completion with the same
+        # strict system instruction; Python still validates the returned text.
+        for kwargs in ({"response_format": {"type": "json_object"}}, {}):
+            try:
+                response = self.llm.invoke(messages, temperature=0.0, **kwargs)
+                text = str(getattr(response, "content", response)).strip()
+                if text and self._contains_nonempty_quest_array(text):
+                    return text
+                last_error = LLMCallError("Quest JSON LLM 返回空 Quest 数组或非 JSON 内容,准备重试")
+            except Exception as exc:
+                last_error = exc
+        raise LLMCallError(f"Quest JSON LLM 调用失败:{last_error}")
+
+    @staticmethod
+    def _contains_nonempty_quest_array(text: str) -> bool:
+        """Cheap transport-level guard before QuestAgent applies full schema checks."""
+        try:
+            value = json.loads(text)
+        except json.JSONDecodeError:
+            return False
+        return isinstance(value, dict) and isinstance(value.get("quests"), list) and bool(value["quests"])
+
+    def stream_user_guidance(
+        self,
+        question: str,
+        report_payload: str,
+        history: Iterable[dict[str, str]] = (),
+    ) -> Iterable[str]:
+        """Stream a guided, playful answer to a user's current input.
+
+        Hello-Agents' high-level ``Agent.run`` API returns a complete string.
+        For the interactive UI we use the same configured ``HelloAgentsLLM``
+        through its official streaming interface, preserving the Agent's
+        Context Engineering policy while allowing users to see tokens as they
+        arrive instead of waiting for a long final response.
+        """
+        if self.llm is None:
+            raise LLMCallError("LLM 尚未初始化")
+        # Bound transcript independently of the UI/CLI caller. This prevents a
+        # long chat from competing with the verified report facts in the model
+        # context, even if another integration passes unbounded history.
+        recent_history = list(history)[-6:]
+        transcript_lines: list[str] = []
+        for item in recent_history:
+            content = str(item.get("content", "")).strip()
+            if len(content) > 600:
+                content = content[:600].rstrip() + "…"
+            transcript_lines.append(f"{item.get('role', 'user')}: {content}")
+        transcript = "\n".join(transcript_lines) or "(这是本轮对话的第一条消息)"
+        context = self.build_context(
+            "结合真实消费数据,进行一步一步的 Money Quest 财务教练对话。",
+            evidence=[report_payload],
+            memory=[transcript],
+        )
+        system = (
+            "你是 MoneyMirrorAgent 的互动财务教练。你要像游戏 NPC 一样友好、有趣、会引导,"
+            "但不能戏弄用户或制造焦虑。每次只推进一个小问题:先复述你观察到的消费现象,"
+            "再给一个具体且可执行的小建议,最后提出一个简短追问,帮助用户选择目标或下一步。"
+            "所有金额和比例只能引用输入的 Verified tool output;不得编造数字。"
+            "回答控制在 120-220 字,使用少量 emoji 和 Markdown 列表,让用户能马上行动。"
+        )
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": f"{context}\n\n用户刚刚说:{question}"},
+        ]
+        try:
+            yielded = False
+            for chunk in self.llm.stream_invoke(messages, temperature=0.4):
+                if chunk:
+                    yielded = True
+                    yield str(chunk)
+            if not yielded:
+                raise LLMCallError("互动 LLM 返回空内容")
+        except LLMCallError:
+            raise
+        except Exception as exc:
+            raise LLMCallError(f"互动 LLM 流式调用失败:{exc}") from exc
+
+    def classify_uncertain(self, merchant: str, note: str, allowed_categories: list[str]) -> str | None:
+        prompt = (
+            f"商户:{merchant}\n备注:{note}\n只能从以下类别中选择一个并且只输出类别名:"
+            f"{', '.join(allowed_categories)}。证据不足时输出其他。"
+        )
+        answer = self.explain(prompt, mode="react")
+        normalized = answer.strip().splitlines()[0].strip("`。:: ")
+        return normalized if normalized in allowed_categories else None
+
+    def generate_markdown(self, report_payload: str) -> str:
+        """Generate the persisted Markdown report through the LLM."""
+        prompt = (
+            "请把下面的 MoneyMirrorAgent 已验证分析数据写成一份完整的中文 Markdown 月度报告。\n"
+            "必须包含:财务镜像、消费分类与趋势、行为模式、异常消费解释、消费人格、订阅提醒、"
+            "目标进度、动态预算、Money Quest、等级与成就、月度 Reflection 和下一周期行动清单。\n"
+            "要求:只引用输入中的数字;如果某项为空就明确写‘暂无数据’;语气年轻、温和、可执行;"
+            "不要输出代码围栏;直接输出 Markdown 正文。报告建议 1200-2200 字,"
+            "确保保留所有重要的小节,但不要复述原始 JSON。\n\n"
+            f"{report_payload}"
+        )
+        text = self.explain(prompt, mode="reflection")
+        if text.startswith("```"):
+            text = text.strip().removeprefix("```markdown").removesuffix("```").strip()
+        if not text.startswith("#"):
+            text = "# MoneyMirrorAgent 月度报告\n\n" + text
+        return text.rstrip() + "\n"
+
+    def answer_user(self, question: str, report_payload: str) -> str:
+        """Answer a user question using the current verified report context."""
+        return self.explain(
+            "回答用户问题。只能使用已验证账单数据和 Memory。\n"
+            f"用户问题:{question}",
+            mode="simple",
+            evidence=[report_payload],
+        )
+
+    def status_dict(self) -> dict[str, Any]:
+        return {
+            "available": self.status.available,
+            "enabled": self.status.enabled,
+            "reason": self.status.reason,
+            "registry_name": self.status.registry_name,
+            "paradigms": list(self.status.paradigms),
+            "registered_tools": list(self.status.registered_tools),
+            "provider": self.status.provider,
+            "model": self.status.model,
+            "base_url": self.status.base_url,
+        }

+ 41 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/agents/transaction_agent.py

@@ -0,0 +1,41 @@
+"""TransactionAgent: rule/memory-first categorization, LLM only for uncertainty."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..memory import SQLiteMemory
+from ..models import Transaction
+from ..tools.transaction_category import CATEGORIES, TransactionCategoryTool
+from .runtime import HelloAgentsRuntime
+
+
+class TransactionAgent:
+    paradigm = "ReActAgent-style: inspect transaction → consult memory/rules → resolve only uncertainty"
+
+    def __init__(self, memory: SQLiteMemory, runtime: HelloAgentsRuntime, tool: TransactionCategoryTool | None = None) -> None:
+        self.memory = memory
+        self.runtime = runtime
+        self.tool = tool or TransactionCategoryTool()
+
+    def run(self, transactions: Iterable[Transaction]) -> tuple[list[Transaction], dict]:
+        resolved: list[Transaction] = []
+        source_counts: dict[str, int] = {}
+        for item in transactions:
+            result = self.tool.classify(item, self.memory.get_merchant_category)
+            if result.confidence < 0.5 and item.kind == "expense":
+                llm_category = self.runtime.classify_uncertain(item.merchant, item.note, list(CATEGORIES))
+                if llm_category:
+                    result.category = llm_category
+                    result.confidence = 0.6
+                    result.source = "hello_agents_llm"
+            item.category = result.category
+            item.category_confidence = result.confidence
+            source_counts[result.source] = source_counts.get(result.source, 0) + 1
+            resolved.append(item)
+        return resolved, {"agent": "TransactionAgent", "paradigm": self.paradigm, "classification_sources": source_counts}
+
+    def correct_category(self, merchant: str, category: str) -> None:
+        if category not in CATEGORIES:
+            raise ValueError(f"不支持的分类: {category}")
+        self.memory.set_merchant_category(merchant, category)

+ 122 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/config/personas.json

@@ -0,0 +1,122 @@
+{
+  "version": 2,
+  "archetypes": [
+    {
+      "id": "late_night_focus",
+      "name": "夜行消费探索者",
+      "minimum_score": 52,
+      "required_features": {"night": 38},
+      "weights": {"night": 0.75, "impulse": 0.25},
+      "evidence_metrics": ["late_night_share", "late_night_count", "impulse"]
+    },
+    {
+      "id": "weekend_experience",
+      "name": "周末体验玩家",
+      "minimum_score": 52,
+      "required_features": {"weekend": 38},
+      "weights": {"weekend": 0.65, "flexible_spend": 0.35},
+      "evidence_metrics": ["weekend_share", "weekend_count", "flexible_spend_share"]
+    },
+    {
+      "id": "frequent_small_spend",
+      "name": "高频小额行动派",
+      "minimum_score": 55,
+      "required_features": {"frequent_small": 45},
+      "weights": {"frequent_small": 0.65, "impulse": 0.2, "food": 0.15},
+      "evidence_metrics": ["frequent_small_count", "frequent_small_share", "food_share"]
+    },
+    {
+      "id": "subscription_collector",
+      "name": "数字订阅整理师",
+      "minimum_score": 50,
+      "required_features": {"subscription": 35},
+      "weights": {"subscription": 0.8, "planning_inverse": 0.2},
+      "evidence_metrics": ["subscription_share", "subscription_count"]
+    },
+    {
+      "id": "learning_investor",
+      "name": "学习投入玩家",
+      "minimum_score": 55,
+      "required_features": {"learning": 45, "learning_consistency": 50},
+      "weights": {"learning": 0.75, "learning_consistency": 0.25},
+      "evidence_metrics": ["learning_share", "learning_active_months"]
+    },
+    {
+      "id": "steady_planner",
+      "name": "稳健规划玩家",
+      "minimum_score": 60,
+      "required_features": {"planning": 55, "savings": 45},
+      "weights": {"planning": 0.6, "savings": 0.4},
+      "evidence_metrics": ["savings_rate", "payday_share", "late_night_share"]
+    },
+    {
+      "id": "payday_rhythm",
+      "name": "发薪节奏管理者",
+      "minimum_score": 58,
+      "required_features": {"payday": 55, "impulse": 35},
+      "weights": {"payday": 0.55, "impulse": 0.3, "planning": 0.15},
+      "evidence_metrics": ["payday_share", "savings_rate", "impulse"]
+    },
+    {
+      "id": "weekend_social",
+      "name": "周末社交发动机",
+      "minimum_score": 58,
+      "required_features": {"weekend": 42, "flexible_spend": 30},
+      "weights": {"weekend": 0.55, "flexible_spend": 0.3, "food": 0.15},
+      "evidence_metrics": ["weekend_share", "weekend_count", "food_share", "flexible_spend_share"]
+    },
+    {
+      "id": "food_routine",
+      "name": "日常餐饮探索家",
+      "minimum_score": 62,
+      "required_features": {"food": 55, "frequent_small": 42},
+      "weights": {"food": 0.55, "frequent_small": 0.3, "weekend": 0.15},
+      "evidence_metrics": ["food_share", "frequent_small_count", "frequent_small_share"]
+    },
+    {
+      "id": "savings_sprinter",
+      "name": "储蓄冲刺玩家",
+      "minimum_score": 66,
+      "required_features": {"savings": 65, "planning": 52},
+      "weights": {"savings": 0.65, "planning": 0.35},
+      "evidence_metrics": ["savings_rate", "payday_share", "flexible_spend_share"]
+    },
+    {
+      "id": "digital_lifestyle",
+      "name": "数字生活玩家",
+      "minimum_score": 58,
+      "required_features": {"subscription": 45, "planning_inverse": 30},
+      "weights": {"subscription": 0.68, "planning_inverse": 0.32},
+      "evidence_metrics": ["subscription_share", "subscription_count", "savings_rate"]
+    },
+    {
+      "id": "learning_consistent",
+      "name": "学习成长玩家",
+      "minimum_score": 60,
+      "required_features": {"learning": 48, "learning_consistency": 65},
+      "weights": {"learning_consistency": 0.6, "learning": 0.4},
+      "evidence_metrics": ["learning_share", "learning_active_months", "savings_rate"]
+    },
+    {
+      "id": "flexible_adventurer",
+      "name": "弹性体验玩家",
+      "minimum_score": 60,
+      "required_features": {"flexible_spend": 52},
+      "weights": {"flexible_spend": 0.62, "weekend": 0.23, "impulse_inverse": 0.15},
+      "evidence_metrics": ["flexible_spend_share", "weekend_share", "weekend_count", "impulse"]
+    },
+    {
+      "id": "mindful_minimalist",
+      "name": "清醒消费实践者",
+      "minimum_score": 64,
+      "required_features": {"planning": 62, "impulse_inverse": 58},
+      "weights": {"planning": 0.45, "savings": 0.3, "impulse_inverse": 0.25},
+      "evidence_metrics": ["savings_rate", "impulse", "late_night_share", "frequent_small_share"]
+    }
+  ],
+  "fallback": {
+    "id": "balanced_explorer",
+    "name": "均衡节奏探索者",
+    "evidence_metrics": ["savings_rate", "late_night_share", "weekend_share"]
+  }
+}

+ 5 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/memory/__init__.py

@@ -0,0 +1,5 @@
+"""Durable SQLite Memory for MoneyMirrorAgent."""
+
+from .sqlite_memory import SQLiteMemory
+
+__all__ = ["SQLiteMemory"]

+ 161 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/memory/sqlite_memory.py

@@ -0,0 +1,161 @@
+"""Small, explicit SQLite-backed long-term memory.
+
+The database is local by design: personal financial data should not leave the
+user's machine just to power a dashboard demo.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+from ..models import Goal, Quest
+
+
+class SQLiteMemory:
+    def __init__(self, path: str | Path = "outputs/moneymirror.db", user_id: str = "local_user") -> None:
+        self.path = str(path)
+        self.user_id = user_id
+        if self.path != ":memory:":
+            Path(self.path).parent.mkdir(parents=True, exist_ok=True)
+        self.connection = sqlite3.connect(self.path)
+        self.connection.row_factory = sqlite3.Row
+        self._initialize()
+
+    def close(self) -> None:
+        self.connection.close()
+
+    def _initialize(self) -> None:
+        self.connection.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS merchant_categories (
+                user_id TEXT NOT NULL, merchant TEXT NOT NULL, category TEXT NOT NULL,
+                updated_at TEXT NOT NULL, PRIMARY KEY (user_id, merchant)
+            );
+            CREATE TABLE IF NOT EXISTS goals (
+                user_id TEXT NOT NULL, goal_id TEXT NOT NULL, payload TEXT NOT NULL,
+                updated_at TEXT NOT NULL, PRIMARY KEY (user_id, goal_id)
+            );
+            CREATE TABLE IF NOT EXISTS budgets (
+                user_id TEXT NOT NULL, month TEXT NOT NULL, payload TEXT NOT NULL,
+                updated_at TEXT NOT NULL, PRIMARY KEY (user_id, month)
+            );
+            CREATE TABLE IF NOT EXISTS quests (
+                user_id TEXT NOT NULL, quest_id TEXT NOT NULL, payload TEXT NOT NULL,
+                updated_at TEXT NOT NULL, PRIMARY KEY (user_id, quest_id)
+            );
+            CREATE TABLE IF NOT EXISTS achievements (
+                user_id TEXT NOT NULL, achievement_key TEXT NOT NULL, payload TEXT NOT NULL,
+                unlocked_at TEXT NOT NULL, PRIMARY KEY (user_id, achievement_key)
+            );
+            CREATE TABLE IF NOT EXISTS snapshots (
+                user_id TEXT NOT NULL, month TEXT NOT NULL, payload TEXT NOT NULL,
+                created_at TEXT NOT NULL, PRIMARY KEY (user_id, month)
+            );
+            CREATE TABLE IF NOT EXISTS reflections (
+                user_id TEXT NOT NULL, month TEXT NOT NULL, payload TEXT NOT NULL,
+                created_at TEXT NOT NULL, PRIMARY KEY (user_id, month)
+            );
+            CREATE TABLE IF NOT EXISTS preferences (
+                user_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL,
+                updated_at TEXT NOT NULL, PRIMARY KEY (user_id, key)
+            );
+            """
+        )
+        self.connection.commit()
+
+    @staticmethod
+    def _now() -> str:
+        return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+    def set_merchant_category(self, merchant: str, category: str) -> None:
+        self.connection.execute(
+            "INSERT INTO merchant_categories VALUES (?, ?, ?, ?) ON CONFLICT(user_id, merchant) DO UPDATE SET category=excluded.category, updated_at=excluded.updated_at",
+            (self.user_id, merchant.strip(), category, self._now()),
+        )
+        self.connection.commit()
+
+    def get_merchant_category(self, merchant: str) -> str | None:
+        row = self.connection.execute("SELECT category FROM merchant_categories WHERE user_id=? AND merchant=?", (self.user_id, merchant.strip())).fetchone()
+        return row["category"] if row else None
+
+    def merchant_categories(self) -> dict[str, str]:
+        rows = self.connection.execute("SELECT merchant, category FROM merchant_categories WHERE user_id=?", (self.user_id,)).fetchall()
+        return {row["merchant"]: row["category"] for row in rows}
+
+    def save_goal(self, goal: Goal | dict[str, Any]) -> None:
+        payload = goal.to_dict() if isinstance(goal, Goal) else goal
+        self._upsert_payload("goals", "goal_id", payload["goal_id"], payload)
+
+    def list_goals(self, active_only: bool = False) -> list[dict[str, Any]]:
+        rows = self.connection.execute("SELECT payload FROM goals WHERE user_id=? ORDER BY updated_at", (self.user_id,)).fetchall()
+        values = [json.loads(row["payload"]) for row in rows]
+        return [value for value in values if value.get("active", True)] if active_only else values
+
+    def save_budget(self, month: str, budget: dict[str, Any]) -> None:
+        self._upsert_payload("budgets", "month", month, budget)
+
+    def get_budget(self, month: str) -> dict[str, Any] | None:
+        return self._get_payload("budgets", "month", month)
+
+    def save_quest(self, quest: Quest | dict[str, Any]) -> None:
+        payload = quest.to_dict() if isinstance(quest, Quest) else quest
+        self._upsert_payload("quests", "quest_id", payload["quest_id"], payload)
+
+    def list_quests(self, active_only: bool = False) -> list[dict[str, Any]]:
+        rows = self.connection.execute("SELECT payload FROM quests WHERE user_id=? ORDER BY updated_at", (self.user_id,)).fetchall()
+        values = [json.loads(row["payload"]) for row in rows]
+        return [value for value in values if value.get("status") == "active"] if active_only else values
+
+    def save_achievement(self, achievement: dict[str, Any]) -> None:
+        self._upsert_payload("achievements", "achievement_key", achievement["key"], achievement, timestamp_column="unlocked_at")
+
+    def list_achievements(self) -> list[dict[str, Any]]:
+        rows = self.connection.execute("SELECT payload FROM achievements WHERE user_id=? ORDER BY unlocked_at", (self.user_id,)).fetchall()
+        return [json.loads(row["payload"]) for row in rows]
+
+    def save_snapshot(self, month: str, snapshot: dict[str, Any]) -> None:
+        self._upsert_payload("snapshots", "month", month, snapshot, timestamp_column="created_at")
+
+    def get_snapshot(self, month: str) -> dict[str, Any] | None:
+        return self._get_payload("snapshots", "month", month)
+
+    def list_snapshots(self) -> list[dict[str, Any]]:
+        rows = self.connection.execute("SELECT month, payload FROM snapshots WHERE user_id=? ORDER BY month", (self.user_id,)).fetchall()
+        return [{"month": row["month"], **json.loads(row["payload"])} for row in rows]
+
+    def save_reflection(self, month: str, reflection: dict[str, Any]) -> None:
+        self._upsert_payload("reflections", "month", month, reflection, timestamp_column="created_at")
+
+    def get_reflection(self, month: str) -> dict[str, Any] | None:
+        return self._get_payload("reflections", "month", month)
+
+    def list_reflections(self) -> list[dict[str, Any]]:
+        rows = self.connection.execute("SELECT month, payload FROM reflections WHERE user_id=? ORDER BY month", (self.user_id,)).fetchall()
+        return [{"month": row["month"], **json.loads(row["payload"])} for row in rows]
+
+    def set_preference(self, key: str, value: Any) -> None:
+        self.connection.execute(
+            "INSERT INTO preferences VALUES (?, ?, ?, ?) ON CONFLICT(user_id, key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at",
+            (self.user_id, key, json.dumps(value, ensure_ascii=False), self._now()),
+        )
+        self.connection.commit()
+
+    def get_preference(self, key: str, default: Any = None) -> Any:
+        row = self.connection.execute("SELECT value FROM preferences WHERE user_id=? AND key=?", (self.user_id, key)).fetchone()
+        return json.loads(row["value"]) if row else default
+
+    def _upsert_payload(self, table: str, key_column: str, key: str, payload: dict[str, Any], timestamp_column: str = "updated_at") -> None:
+        columns = f"user_id, {key_column}, payload, {timestamp_column}"
+        self.connection.execute(
+            f"INSERT INTO {table} ({columns}) VALUES (?, ?, ?, ?) ON CONFLICT(user_id, {key_column}) DO UPDATE SET payload=excluded.payload, {timestamp_column}=excluded.{timestamp_column}",
+            (self.user_id, key, json.dumps(payload, ensure_ascii=False), self._now()),
+        )
+        self.connection.commit()
+
+    def _get_payload(self, table: str, key_column: str, key: str) -> dict[str, Any] | None:
+        row = self.connection.execute(f"SELECT payload FROM {table} WHERE user_id=? AND {key_column}=?", (self.user_id, key)).fetchone()
+        return json.loads(row["payload"]) if row else None

+ 136 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/models.py

@@ -0,0 +1,136 @@
+"""Typed domain models used by deterministic tools and agent orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import date
+from typing import Any, Literal
+
+TransactionKind = Literal["income", "expense"]
+
+
+@dataclass(slots=True)
+class Transaction:
+    transaction_id: str
+    occurred_at: str
+    merchant: str
+    amount: float
+    kind: TransactionKind
+    category: str = "Uncategorized"
+    note: str = ""
+    source: str = "csv"
+    category_confidence: float = 0.0
+
+    @property
+    def date(self) -> date:
+        return date.fromisoformat(self.occurred_at[:10])
+
+    @property
+    def hour(self) -> int:
+        if "T" not in self.occurred_at:
+            return 12
+        return int(self.occurred_at.split("T", 1)[1][:2])
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class Anomaly:
+    transaction_id: str
+    merchant: str
+    category: str
+    amount: float
+    occurred_at: str
+    method: str
+    score: float
+    reason: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class Goal:
+    goal_id: str
+    title: str
+    goal_type: Literal["savings", "travel", "category_limit"]
+    target_amount: float
+    current_amount: float
+    deadline: str
+    category: str | None = None
+    monthly_limit: float | None = None
+    active: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class Quest:
+    quest_id: str
+    title: str
+    description: str
+    quest_type: str
+    target: float
+    progress: float
+    unit: str
+    exp_reward: int
+    status: Literal["active", "completed"] = "active"
+    evidence: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class Achievement:
+    key: str
+    title: str
+    description: str
+    unlocked: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class AnalysisReport:
+    user_id: str
+    month: str
+    transactions: list[Transaction]
+    summary: dict[str, Any]
+    category_breakdown: dict[str, float]
+    trends: dict[str, dict[str, float]]
+    patterns: dict[str, Any]
+    anomalies: list[Anomaly]
+    subscriptions: list[dict[str, Any]]
+    persona: dict[str, Any]
+    budget: dict[str, Any]
+    goals: list[dict[str, Any]]
+    quests: list[Quest]
+    achievements: list[Achievement]
+    gamification: dict[str, Any]
+    reflection: dict[str, Any]
+    agent_trace: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "user_id": self.user_id,
+            "month": self.month,
+            "transactions": [item.to_dict() for item in self.transactions],
+            "summary": self.summary,
+            "category_breakdown": self.category_breakdown,
+            "trends": self.trends,
+            "patterns": self.patterns,
+            "anomalies": [item.to_dict() for item in self.anomalies],
+            "subscriptions": self.subscriptions,
+            "persona": self.persona,
+            "budget": self.budget,
+            "goals": self.goals,
+            "quests": [item.to_dict() for item in self.quests],
+            "achievements": [item.to_dict() for item in self.achievements],
+            "gamification": self.gamification,
+            "reflection": self.reflection,
+            "agent_trace": self.agent_trace,
+        }

+ 21 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/__init__.py

@@ -0,0 +1,21 @@
+"""Deterministic tools used by MoneyMirrorAgent."""
+
+from .anomaly_detection import AnomalyDetectionTool
+from .budget_calculator import BudgetCalculatorTool
+from .csv_import import CSVImportTool
+from .goal_projection import GoalProjectionTool
+from .quest_progress import QuestProgressTool
+from .statistics import StatisticsTool
+from .subscription_detector import SubscriptionDetectorTool
+from .transaction_category import TransactionCategoryTool
+
+__all__ = [
+    "AnomalyDetectionTool",
+    "BudgetCalculatorTool",
+    "CSVImportTool",
+    "GoalProjectionTool",
+    "QuestProgressTool",
+    "StatisticsTool",
+    "SubscriptionDetectorTool",
+    "TransactionCategoryTool",
+]

+ 61 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/anomaly_detection.py

@@ -0,0 +1,61 @@
+"""Transparent IQR, z-score, and median-ratio anomaly detection."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from statistics import mean, median, pstdev
+from typing import Iterable
+
+from ..models import Anomaly, Transaction
+
+
+class AnomalyDetectionTool:
+    def detect(self, transactions: Iterable[Transaction], month: str | None = None) -> list[Anomaly]:
+        items = [x for x in transactions if x.kind == "expense" and (not month or x.date.strftime("%Y-%m") == month)]
+        by_category: dict[str, list[float]] = defaultdict(list)
+        for item in items:
+            by_category[item.category].append(item.amount)
+        anomalies: list[Anomaly] = []
+        for item in items:
+            values = by_category[item.category]
+            if len(values) < 4:
+                # For sparse categories, use a conservative median multiplier.
+                # A 2.5x ratio still requires a meaningful amount gap, while
+                # making three-point categories (for example, shopping) useful.
+                baseline = median(values) if values else 0
+                if baseline and item.amount >= max(2.5 * baseline, baseline + 200):
+                    anomalies.append(Anomaly(item.transaction_id, item.merchant, item.category, item.amount, item.occurred_at, "sparse-median", round(item.amount / baseline, 2), f"金额约为该类别中位数的 {item.amount / baseline:.1f} 倍"))
+                continue
+            ordered = sorted(values)
+            category_median = median(values)
+            # IQR and z-score are intentionally complemented by a large
+            # median-ratio guard. In small, skewed categories a single large
+            # purchase can pull Q3 and the mean upward, hiding the very event
+            # a user expects the agent to explain (for example a ¥1,288
+            # electronics purchase among ordinary shopping transactions).
+            median_upper = max(3 * category_median, category_median + 500)
+            if item.amount >= median_upper:
+                ratio = item.amount / category_median if category_median else 0.0
+                anomalies.append(Anomaly(item.transaction_id, item.merchant, item.category, item.amount, item.occurred_at, "median-ratio", round(ratio, 2), f"金额约为该类别中位数的 {ratio:.1f} 倍"))
+                continue
+            q1 = self._percentile(ordered, 0.25)
+            q3 = self._percentile(ordered, 0.75)
+            iqr = q3 - q1
+            upper = q3 + 1.5 * iqr
+            category_mean = mean(values)
+            deviation = pstdev(values)
+            z = (item.amount - category_mean) / deviation if deviation else 0.0
+            if item.amount > upper:
+                anomalies.append(Anomaly(item.transaction_id, item.merchant, item.category, item.amount, item.occurred_at, "IQR", round(z, 2), f"高于 {item.category} 类别 IQR 上界 {upper:.2f}"))
+            elif abs(z) >= 2.5:
+                anomalies.append(Anomaly(item.transaction_id, item.merchant, item.category, item.amount, item.occurred_at, "Z-score", round(z, 2), f"相对该类别均值偏离 {z:.1f} 个标准差"))
+        return sorted(anomalies, key=lambda item: item.amount, reverse=True)
+
+    @staticmethod
+    def _percentile(values: list[float], fraction: float) -> float:
+        if len(values) == 1:
+            return values[0]
+        position = (len(values) - 1) * fraction
+        lower = int(position)
+        upper = min(lower + 1, len(values) - 1)
+        return values[lower] + (values[upper] - values[lower]) * (position - lower)

+ 52 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/budget_calculator.py

@@ -0,0 +1,52 @@
+"""Behavior-aware next-month budget calculation."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from statistics import median
+from typing import Iterable
+
+from ..models import Transaction
+
+
+class BudgetCalculatorTool:
+    fixed_categories = {"住房", "订阅"}
+    necessary_categories = {"餐饮", "交通", "学习", "健身", "医疗"}
+    # ``flexible`` is adjustable but still part of daily life; ``optional``
+    # represents discretionary experiences and shopping that can be paused.
+    flexible_categories = {"其他"}
+    optional_categories = {"娱乐", "购物"}
+
+    def calculate(self, transactions: Iterable[Transaction], month: str | None = None) -> dict:
+        items = [x for x in transactions if x.kind == "expense"]
+        by_month_category: dict[str, dict[str, float]] = defaultdict(lambda: defaultdict(float))
+        for item in items:
+            by_month_category[item.date.strftime("%Y-%m")][item.category] += item.amount
+        months = sorted(by_month_category)
+        history = months[:-1] if month and month in months else months
+        if not history:
+            history = months
+        categories = sorted({cat for values in by_month_category.values() for cat in values})
+        lines: dict[str, dict] = {}
+        for category in categories:
+            values = [by_month_category[m].get(category, 0.0) for m in history]
+            baseline = median(values) if values else 0.0
+            if category in self.fixed_categories:
+                recommended = baseline
+                bucket = "fixed"
+                rationale = "固定支出,原则上不做大幅削减"
+            elif category in self.necessary_categories:
+                recommended = max(baseline * 0.97, baseline - 80) if baseline else 0.0
+                bucket = "necessary"
+                rationale = "必要支出,参考历史中位数并保留缓冲"
+            elif category in self.optional_categories:
+                recommended = max(baseline * 0.85, baseline - 120) if baseline else 0.0
+                bucket = "optional"
+                rationale = "可选支出,保留真实体验额度并设置温和上限"
+            else:
+                recommended = max(baseline * 0.9, baseline - 80) if baseline else 0.0
+                bucket = "flexible"
+                rationale = "弹性支出,结合历史行为小幅调整"
+            lines[category] = {"bucket": bucket, "historical_median": round(baseline, 2), "recommended": round(recommended, 2), "rationale": rationale}
+        total = round(sum(item["recommended"] for item in lines.values()), 2)
+        return {"month": month, "categories": lines, "recommended_total": total, "historical_months": history, "principle": "基于历史中位数,固定支出不削减,必要/弹性/可选支出分层温和调整"}

+ 160 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/csv_import.py

@@ -0,0 +1,160 @@
+"""CSV bill import and normalization."""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+from datetime import datetime
+from pathlib import Path
+from typing import BinaryIO, Iterable, TextIO
+
+from ..models import Transaction
+
+
+class CSVImportTool:
+    """Normalize common Chinese/English bank-export columns into transactions.
+
+    Supported amount conventions:
+    - positive amount + a direction/type column;
+    - negative amount means expense and positive means income when direction is absent;
+    - separate income/expense columns (the non-empty one wins).
+    """
+
+    aliases = {
+        "date": ("date", "日期", "交易日期", "时间", "交易时间", "occurred_at"),
+        "merchant": ("merchant", "商户", "商户名称", "交易对方", "description", "摘要", "备注"),
+        "amount": ("amount", "金额", "交易金额", "price", "消费金额"),
+        "direction": ("direction", "收支", "类型", "交易类型", "kind", "income_expense"),
+        "income": ("income", "收入", "入账"),
+        "expense": ("expense", "支出", "消费", "付款"),
+        "category": ("category", "类别", "分类", "消费类别"),
+        "note": ("note", "备注", "说明", "memo"),
+    }
+
+    date_formats = (
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%d %H:%M",
+        "%Y/%m/%d %H:%M:%S",
+        "%Y/%m/%d %H:%M",
+        "%Y-%m-%d",
+        "%Y/%m/%d",
+        "%Y.%m.%d",
+        "%Y年%m月%d日",
+    )
+
+    def __init__(self) -> None:
+        # Exposed for the coordinator/UI so partially malformed exports are
+        # visible instead of being silently mistaken for complete imports.
+        self.last_errors: list[str] = []
+
+    def load(self, source: str | Path | TextIO | BinaryIO) -> list[Transaction]:
+        self.last_errors = []
+        if hasattr(source, "read"):
+            raw = source.read()
+            source_name = getattr(source, "name", "uploaded.csv")
+            text = self._decode(raw)
+        else:
+            path = Path(source)
+            raw = path.read_bytes()
+            source_name = str(path)
+            text = self._decode(raw)
+        if not text.strip():
+            return []
+        reader = csv.DictReader(io.StringIO(text))
+        if not reader.fieldnames:
+            raise ValueError("CSV 缺少表头")
+        mapping = self._resolve_columns(reader.fieldnames)
+        if not mapping.get("date") or not mapping.get("merchant"):
+            raise ValueError("CSV 至少需要日期和商户列")
+        transactions: list[Transaction] = []
+        errors: list[str] = []
+        for row_number, row in enumerate(reader, start=2):
+            try:
+                transactions.append(self._row_to_transaction(row, mapping, source_name, row_number))
+            except ValueError as exc:
+                errors.append(f"第 {row_number} 行: {exc}")
+        self.last_errors = errors
+        if errors and not transactions:
+            raise ValueError("CSV 没有可导入的交易: " + "; ".join(errors[:3]))
+        return transactions
+
+    @staticmethod
+    def _decode(raw: str | bytes | bytearray) -> str:
+        if isinstance(raw, str):
+            return raw
+        for encoding in ("utf-8-sig", "utf-8", "gb18030"):
+            try:
+                return bytes(raw).decode(encoding)
+            except UnicodeDecodeError:
+                continue
+        raise ValueError("CSV 编码无法识别,请另存为 UTF-8 或 GB18030")
+
+    def _resolve_columns(self, fields: Iterable[str]) -> dict[str, str | None]:
+        normalized = {self._norm(field): field for field in fields if field}
+        result: dict[str, str | None] = {}
+        for target, candidates in self.aliases.items():
+            result[target] = next((normalized[self._norm(c)] for c in candidates if self._norm(c) in normalized), None)
+        return result
+
+    @staticmethod
+    def _norm(value: str) -> str:
+        return "".join(str(value).strip().lower().replace("_", "").replace("-", "").split())
+
+    def _row_to_transaction(self, row: dict[str, str], mapping: dict[str, str | None], source: str, row_number: int) -> Transaction:
+        raw_date = (row.get(mapping["date"] or "") or "").strip()
+        occurred_at = self._parse_date(raw_date)
+        merchant = (row.get(mapping["merchant"] or "") or "").strip() or "未知商户"
+        amount, kind = self._parse_amount_and_kind(row, mapping)
+        category = (row.get(mapping["category"] or "") or "").strip() or "Uncategorized"
+        note = (row.get(mapping["note"] or "") or "").strip()
+        digest = hashlib.sha1(f"{source}:{row_number}:{occurred_at}:{merchant}:{amount}:{kind}".encode()).hexdigest()[:16]
+        return Transaction(digest, occurred_at, merchant, round(abs(amount), 2), kind, category, note, source)
+
+    def _parse_date(self, raw: str) -> str:
+        if not raw:
+            raise ValueError("日期为空")
+        candidate = raw.replace("T", " ").strip()
+        try:
+            parsed = datetime.fromisoformat(candidate)
+            return parsed.isoformat(timespec="minutes")
+        except ValueError:
+            pass
+        for fmt in self.date_formats:
+            try:
+                return datetime.strptime(candidate, fmt).isoformat(timespec="minutes")
+            except ValueError:
+                continue
+        raise ValueError(f"无法解析日期 {raw!r}")
+
+    def _parse_amount_and_kind(self, row: dict[str, str], mapping: dict[str, str | None]) -> tuple[float, str]:
+        income_raw = self._number(row.get(mapping["income"] or ""))
+        expense_raw = self._number(row.get(mapping["expense"] or ""))
+        if income_raw is not None and abs(income_raw) > 0:
+            return abs(income_raw), "income"
+        if expense_raw is not None and abs(expense_raw) > 0:
+            return abs(expense_raw), "expense"
+        raw = (row.get(mapping["amount"] or "") or "").strip()
+        if not raw:
+            raise ValueError("金额为空")
+        amount = self._number(raw)
+        if amount is None:
+            raise ValueError(f"无法解析金额 {raw!r}")
+        direction = (row.get(mapping["direction"] or "") or "").strip().lower()
+        if any(token in direction for token in ("收入", "入账", "转入", "退款", "退货", "income", "credit", "deposit", "refund", "工资")):
+            kind = "income"
+        elif any(token in direction for token in ("支出", "消费", "expense", "debit", "payment", "付款")):
+            kind = "expense"
+        else:
+            kind = "income" if amount > 0 else "expense"
+        return abs(amount), kind
+
+    @staticmethod
+    def _number(raw: str | None) -> float | None:
+        if raw is None or not str(raw).strip():
+            return None
+        cleaned = str(raw).strip().replace(",", "").replace("¥", "").replace("¥", "")
+        try:
+            return float(cleaned)
+        except ValueError:
+            return None

+ 58 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/goal_projection.py

@@ -0,0 +1,58 @@
+"""Savings and category-limit feasibility calculations."""
+
+from __future__ import annotations
+
+from datetime import date
+from math import ceil
+from typing import Iterable
+
+from ..models import Goal, Transaction
+
+
+class GoalProjectionTool:
+    def project(self, goal: Goal, transactions: Iterable[Transaction], current_month: str | None = None) -> dict:
+        items = list(transactions)
+        if current_month:
+            current = date.fromisoformat(f"{current_month}-01")
+        else:
+            current = max((item.date for item in items), default=date.today()).replace(day=1)
+        deadline = date.fromisoformat(goal.deadline[:10]).replace(day=1)
+        months_left = max(1, (deadline.year - current.year) * 12 + deadline.month - current.month + 1)
+        income_by_month: dict[str, float] = {}
+        expenses_by_month: dict[str, float] = {}
+        category_total = 0.0
+        for item in items:
+            key = item.date.strftime("%Y-%m")
+            if item.kind == "income":
+                income_by_month[key] = income_by_month.get(key, 0.0) + item.amount
+            else:
+                expenses_by_month[key] = expenses_by_month.get(key, 0.0) + item.amount
+                if goal.category and item.category == goal.category and key == current.strftime("%Y-%m"):
+                    category_total += item.amount
+        months = sorted(set(income_by_month) | set(expenses_by_month))
+        surpluses = [income_by_month.get(key, 0.0) - expenses_by_month.get(key, 0.0) for key in months if income_by_month.get(key, 0.0)]
+        average_surplus = sum(surpluses) / len(surpluses) if surpluses else 0.0
+        if goal.goal_type == "category_limit" and goal.category:
+            required = max(0.0, (goal.monthly_limit or goal.target_amount) - category_total)
+            feasible = category_total <= (goal.monthly_limit or goal.target_amount)
+            projected = category_total
+        else:
+            remaining = max(0.0, goal.target_amount - goal.current_amount)
+            required = remaining / months_left
+            feasible = average_surplus >= required
+            projected = goal.current_amount + max(0.0, average_surplus) * months_left
+        return {
+            "goal_id": goal.goal_id,
+            "title": goal.title,
+            "goal_type": goal.goal_type,
+            "target_amount": round(goal.target_amount, 2),
+            "current_amount": round(goal.current_amount, 2),
+            "deadline": goal.deadline,
+            "months_left": months_left,
+            "required_monthly_amount": round(required, 2),
+            "average_monthly_surplus": round(average_surplus, 2),
+            "projected_amount": round(projected, 2),
+            "progress_percent": round(min(100.0, goal.current_amount / goal.target_amount * 100) if goal.target_amount else 0.0, 2),
+            "feasible": feasible,
+            "advice": "当前现金流支持该目标" if feasible else "目标偏紧,建议延长期限或降低阶段性目标",
+        }

+ 126 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/hello_agents_registry.py

@@ -0,0 +1,126 @@
+"""JSON adapters that expose MoneyMirror tools through Hello-Agents ToolRegistry.
+
+The coordinator still calls the Python tools directly for the normal pipeline.
+These small adapters make the same deterministic capabilities available to a
+Hello-Agents ReAct agent without moving financial arithmetic into an LLM.
+"""
+
+from __future__ import annotations
+
+import json
+from io import StringIO
+from typing import Any, Callable
+
+from ..models import Goal, Quest, Transaction
+from .anomaly_detection import AnomalyDetectionTool
+from .budget_calculator import BudgetCalculatorTool
+from .csv_import import CSVImportTool
+from .goal_projection import GoalProjectionTool
+from .quest_progress import QuestProgressTool
+from .statistics import StatisticsTool
+from .subscription_detector import SubscriptionDetectorTool
+from .transaction_category import TransactionCategoryTool
+
+
+def _payload(raw: str | dict[str, Any]) -> dict[str, Any]:
+    if isinstance(raw, dict):
+        return raw
+    try:
+        value = json.loads(raw)
+    except (TypeError, json.JSONDecodeError):
+        return {"input": raw}
+    return value if isinstance(value, dict) else {"input": value}
+
+
+def _transactions(payload: dict[str, Any]) -> list[Transaction]:
+    fields = {
+        "transaction_id",
+        "occurred_at",
+        "merchant",
+        "amount",
+        "kind",
+        "category",
+        "note",
+        "source",
+        "category_confidence",
+    }
+    return [Transaction(**{key: item[key] for key in fields if key in item}) for item in payload.get("transactions", [])]
+
+
+def _json(value: Any) -> str:
+    if hasattr(value, "to_dict"):
+        value = value.to_dict()
+    elif isinstance(value, list):
+        value = [item.to_dict() if hasattr(item, "to_dict") else item for item in value]
+    return json.dumps(value, ensure_ascii=False, default=str)
+
+
+def build_registry_functions(
+    csv_import: CSVImportTool,
+    category: TransactionCategoryTool,
+    statistics: StatisticsTool,
+    anomalies: AnomalyDetectionTool,
+    budget: BudgetCalculatorTool,
+    projection: GoalProjectionTool,
+    subscriptions: SubscriptionDetectorTool,
+    quest_progress: QuestProgressTool,
+    memory_lookup: Callable[[str], str | None],
+) -> dict[str, tuple[Callable[[str | dict[str, Any]], str], str]]:
+    """Build function tools with stable JSON-in/JSON-out contracts."""
+
+    def import_csv(raw: str | dict[str, Any]) -> str:
+        data = _payload(raw)
+        transactions = csv_import.load(StringIO(str(data.get("csv_text", ""))))
+        return _json([item.to_dict() for item in transactions])
+
+    def classify_transaction(raw: str | dict[str, Any]) -> str:
+        data = _payload(raw)
+        transaction = Transaction(
+            transaction_id=str(data.get("transaction_id", "registry")),
+            occurred_at=str(data.get("occurred_at", "2000-01-01T12:00")),
+            merchant=str(data.get("merchant", "未知商户")),
+            amount=float(data.get("amount", 0)),
+            kind=data.get("kind", "expense"),
+            note=str(data.get("note", "")),
+        )
+        result = category.classify(transaction, memory_lookup)
+        return _json({
+            "category": result.category,
+            "confidence": result.confidence,
+            "source": result.source,
+        })
+
+    def summarize(raw: str | dict[str, Any]) -> str:
+        data = _payload(raw)
+        return _json(statistics.summarize(_transactions(data), data.get("month")))
+
+    def detect_anomalies(raw: str | dict[str, Any]) -> str:
+        data = _payload(raw)
+        return _json(anomalies.detect(_transactions(data), data.get("month")))
+
+    def calculate_budget(raw: str | dict[str, Any]) -> str:
+        data = _payload(raw)
+        return _json(budget.calculate(_transactions(data), str(data.get("month"))))
+
+    def project_goal(raw: str | dict[str, Any]) -> str:
+        data = _payload(raw)
+        return _json(projection.project(Goal(**data["goal"]), _transactions(data), data.get("month")))
+
+    def detect_subscriptions(raw: str | dict[str, Any]) -> str:
+        return _json(subscriptions.detect(_transactions(_payload(raw))))
+
+    def update_quest(raw: str | dict[str, Any]) -> str:
+        data = _payload(raw)
+        quest = quest_progress.update(Quest(**data["quest"]), _transactions(data), data.get("month"))
+        return _json(quest)
+
+    return {
+        "CSVImportTool": (import_csv, "从 csv_text 导入并规范化账单交易"),
+        "TransactionCategoryTool": (classify_transaction, "按 Memory 和规则为一笔交易分类"),
+        "StatisticsTool": (summarize, "计算收入、支出、结余和消费统计"),
+        "AnomalyDetectionTool": (detect_anomalies, "使用确定性统计方法检测异常消费"),
+        "BudgetCalculatorTool": (calculate_budget, "根据历史消费计算动态预算"),
+        "GoalProjectionTool": (project_goal, "投影财务目标可行性和所需月度额度"),
+        "SubscriptionDetectorTool": (detect_subscriptions, "识别疑似周期性订阅扣费"),
+        "QuestProgressTool": (update_quest, "根据真实交易更新 Money Quest 进度"),
+    }

+ 73 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/quest_progress.py

@@ -0,0 +1,73 @@
+"""Quest progress calculations: deterministic evidence, no invented completion."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Iterable
+
+from ..models import Quest, Transaction
+
+
+class QuestProgressTool:
+    def update(self, quest: Quest, transactions: Iterable[Transaction], month: str | None = None) -> Quest:
+        items = [x for x in transactions if x.kind == "expense" and (not month or x.date.strftime("%Y-%m") == month)]
+        if quest.quest_type == "zero_spend_days":
+            all_days = {x.date for x in items}
+            if all_days:
+                start, end = min(all_days), max(all_days)
+                days = 0
+                cursor = start
+                while cursor <= end:
+                    if cursor not in all_days:
+                        days += 1
+                    cursor += timedelta(days=1)
+                quest.progress = min(quest.target, float(days))
+                quest.evidence = f"分析区间内发现 {days} 个无支出日"
+        elif quest.quest_type == "late_night_limit":
+            late = [x for x in items if x.hour >= 22 or x.hour < 6]
+            quest.progress = max(0.0, quest.target - len(late))
+            quest.evidence = f"深夜消费 {len(late)} 笔,目标最多 {quest.target:.0f} 笔"
+        elif quest.quest_type == "category_limit":
+            spent = sum(x.amount for x in items if x.category == quest.unit)
+            quest.progress = max(0.0, quest.target - spent)
+            quest.evidence = f"{quest.unit} 已消费 ¥{spent:.2f},预算上限 ¥{quest.target:.2f}"
+        elif quest.quest_type == "weekend_spend_limit":
+            spent = sum(x.amount for x in items if x.date.weekday() >= 5)
+            quest.progress = max(0.0, quest.target - spent)
+            quest.evidence = f"周末已消费 ¥{spent:.2f},温和上限 ¥{quest.target:.2f}"
+        elif quest.quest_type == "payday_window_limit":
+            income_dates = {x.date for x in transactions if x.kind == "income" and (not month or x.date.strftime("%Y-%m") == month)}
+            spent = sum(
+                x.amount
+                for x in items
+                if any(0 <= (x.date - income_date).days <= 3 for income_date in income_dates)
+            )
+            quest.progress = max(0.0, quest.target - spent)
+            quest.evidence = f"工资到账后 3 天内已消费 ¥{spent:.2f},温和上限 ¥{quest.target:.2f}"
+        elif quest.quest_type == "subscription_review":
+            quest.progress = min(quest.target, 0.0)
+            quest.evidence = "需要用户在后续 CLI 引导中确认完成"
+        else:
+            quest.evidence = "等待用户更新进度"
+        if quest.quest_type in {"zero_spend_days", "late_night_limit", "category_limit", "weekend_spend_limit", "payday_window_limit"} and quest.progress >= quest.target:
+            quest.status = "completed"
+        return quest
+    def max_zero_spend_streak(self, transactions: Iterable[Transaction], month: str | None = None) -> int:
+        """Return the longest consecutive no-expense-day streak in a period."""
+
+        items = [x for x in transactions if x.kind == "expense" and (not month or x.date.strftime("%Y-%m") == month)]
+        if not items:
+            return 0
+        spent_days = {x.date for x in items}
+        start, end = min(spent_days), max(spent_days)
+        longest = current = 0
+        cursor = start
+        while cursor <= end:
+            if cursor in spent_days:
+                current = 0
+            else:
+                current += 1
+                longest = max(longest, current)
+            cursor += timedelta(days=1)
+        return longest
+

+ 89 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/statistics.py

@@ -0,0 +1,89 @@
+"""Deterministic cash-flow, category, trend, and behavior statistics."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import date, timedelta
+from statistics import mean, median
+from typing import Iterable
+
+from ..models import Transaction
+
+
+class StatisticsTool:
+    def summarize(self, transactions: Iterable[Transaction], month: str | None = None) -> dict:
+        items = [item for item in transactions if not month or item.date.strftime("%Y-%m") == month]
+        income = round(sum(item.amount for item in items if item.kind == "income"), 2)
+        expense = round(sum(item.amount for item in items if item.kind == "expense"), 2)
+        balance = round(income - expense, 2)
+        return {
+            "transaction_count": len(items),
+            "income": income,
+            "expense": expense,
+            "balance": balance,
+            "savings_rate": round(balance / income * 100, 2) if income else 0.0,
+            "average_expense": round(expense / max(1, sum(1 for x in items if x.kind == "expense")), 2),
+            "active_days": len({item.date.isoformat() for item in items if item.kind == "expense"}),
+        }
+
+    def category_breakdown(self, transactions: Iterable[Transaction], month: str | None = None) -> dict[str, float]:
+        totals: dict[str, float] = defaultdict(float)
+        for item in transactions:
+            if item.kind == "expense" and (not month or item.date.strftime("%Y-%m") == month):
+                totals[item.category] += item.amount
+        return dict(sorted(((key, round(value, 2)) for key, value in totals.items()), key=lambda pair: pair[1], reverse=True))
+
+    def trends(self, transactions: Iterable[Transaction], month: str | None = None) -> dict[str, dict[str, float]]:
+        daily: dict[str, float] = defaultdict(float)
+        weekly: dict[str, float] = defaultdict(float)
+        monthly: dict[str, float] = defaultdict(float)
+        for item in transactions:
+            if item.kind != "expense" or (month and item.date.strftime("%Y-%m") != month):
+                continue
+            daily[item.date.isoformat()] += item.amount
+            monday = item.date - timedelta(days=item.date.weekday())
+            weekly[monday.isoformat()] += item.amount
+            monthly[item.date.strftime("%Y-%m")] += item.amount
+        return {
+            "daily": dict(sorted((key, round(value, 2)) for key, value in daily.items())),
+            "weekly": dict(sorted((key, round(value, 2)) for key, value in weekly.items())),
+            "monthly": dict(sorted((key, round(value, 2)) for key, value in monthly.items())),
+        }
+
+    def patterns(self, transactions: Iterable[Transaction], month: str | None = None) -> dict:
+        items = [item for item in transactions if item.kind == "expense" and (not month or item.date.strftime("%Y-%m") == month)]
+        if not items:
+            return {"late_night": {"count": 0, "amount": 0.0}, "weekend": {"count": 0, "amount": 0.0}, "payday_window": {"count": 0, "amount": 0.0}, "frequent_small": {"count": 0, "amount": 0.0}, "category_spikes": {}}
+        late = [x for x in items if x.hour >= 22 or x.hour < 6]
+        weekend = [x for x in items if x.date.weekday() >= 5]
+        income_dates = {x.date for x in transactions if x.kind == "income"}
+        payday = [x for x in items if any(0 <= (x.date - income_date).days <= 3 for income_date in income_dates)]
+        small = [x for x in items if x.amount <= 50]
+        category_amounts: dict[str, float] = defaultdict(float)
+        for x in items:
+            category_amounts[x.category] += x.amount
+        return {
+            "late_night": {"count": len(late), "amount": round(sum(x.amount for x in late), 2), "share": round(sum(x.amount for x in late) / sum(x.amount for x in items) * 100, 2)},
+            "weekend": {"count": len(weekend), "amount": round(sum(x.amount for x in weekend), 2), "share": round(sum(x.amount for x in weekend) / sum(x.amount for x in items) * 100, 2)},
+            "payday_window": {"count": len(payday), "amount": round(sum(x.amount for x in payday), 2), "share": round(sum(x.amount for x in payday) / sum(x.amount for x in items) * 100, 2)},
+            "frequent_small": {"count": len(small), "amount": round(sum(x.amount for x in small), 2), "average": round(mean(x.amount for x in small), 2) if small else 0.0},
+            "category_spikes": {key: round(value, 2) for key, value in sorted(category_amounts.items(), key=lambda pair: pair[1], reverse=True)},
+        }
+
+    def month_keys(self, transactions: Iterable[Transaction]) -> list[str]:
+        return sorted({item.date.strftime("%Y-%m") for item in transactions})
+
+    def monthly_category_totals(self, transactions: Iterable[Transaction]) -> dict[str, dict[str, float]]:
+        result: dict[str, dict[str, float]] = defaultdict(lambda: defaultdict(float))
+        for item in transactions:
+            if item.kind == "expense":
+                result[item.date.strftime("%Y-%m")][item.category] += item.amount
+        return {month: {cat: round(value, 2) for cat, value in cats.items()} for month, cats in sorted(result.items())}
+
+    @staticmethod
+    def historical_average(values: list[float]) -> float:
+        return round(mean(values), 2) if values else 0.0
+
+    @staticmethod
+    def historical_median(values: list[float]) -> float:
+        return round(median(values), 2) if values else 0.0

+ 68 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/subscription_detector.py

@@ -0,0 +1,68 @@
+"""Recurring-charge and subscription detector.
+
+Periodicity alone is not enough: people can visit the same canteen, cinema or
+station on a similar day every month. A candidate therefore needs both a stable
+cross-month amount and semantic evidence that it is a membership/auto-renewal
+charge. The tool intentionally returns *suspected* subscriptions only; it never
+cancels or modifies a service.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from statistics import median
+from typing import Iterable
+
+from ..models import Transaction
+
+
+class SubscriptionDetectorTool:
+    """Detect likely recurring memberships without mistaking routine spending for one."""
+
+    _RECURRING_MARKERS = ("自动续费", "会员", "订阅", "月卡", "年卡", "续费", "连续扣费")
+
+    @classmethod
+    def _has_recurring_evidence(cls, items: list[Transaction]) -> bool:
+        """Return semantic evidence supplied by classification or transaction text."""
+        if any(item.category == "订阅" for item in items):
+            return True
+        return any(
+            marker in f"{item.merchant} {item.note}".lower()
+            for item in items
+            for marker in cls._RECURRING_MARKERS
+        )
+
+    def detect(self, transactions: Iterable[Transaction]) -> list[dict]:
+        groups: dict[str, list[Transaction]] = defaultdict(list)
+        for item in transactions:
+            if item.kind == "expense":
+                groups[item.merchant].append(item)
+
+        result: list[dict] = []
+        for merchant, items in groups.items():
+            # Rent and other housing costs are deliberately budgeted as fixed living
+            # expenses. Although they are periodic, presenting rent as a disposable
+            # "subscription" would be misleading and makes the Subscription Hunter
+            # less trustworthy.
+            if any(item.category == "住房" for item in items):
+                continue
+            months = sorted({item.date.strftime("%Y-%m") for item in items})
+            if len(months) < 2 or not self._has_recurring_evidence(items):
+                continue
+
+            amounts = [item.amount for item in items]
+            stable_amount = max(amounts) - min(amounts) <= max(10.0, median(amounts) * 0.15)
+            if stable_amount:
+                latest = items[-1]
+                result.append(
+                    {
+                        "merchant": merchant,
+                        "months": months,
+                        "occurrences": len(items),
+                        "typical_amount": round(median(amounts), 2),
+                        "category": latest.category,
+                        "low_value_flag": median(amounts) < 100,
+                        "message": "连续多月的会员或续费扣款,建议检查是否仍有使用价值",
+                    }
+                )
+        return sorted(result, key=lambda item: item["typical_amount"], reverse=True)

+ 53 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/src/tools/transaction_category.py

@@ -0,0 +1,53 @@
+"""Rule-first transaction categorization with durable merchant corrections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable
+
+from ..models import Transaction
+
+CATEGORIES = ("餐饮", "交通", "娱乐", "购物", "住房", "学习", "健身", "订阅", "医疗", "其他")
+
+
+@dataclass(slots=True)
+class CategoryResult:
+    category: str
+    confidence: float
+    source: str
+
+
+class TransactionCategoryTool:
+    rules: dict[str, tuple[str, ...]] = {
+        "住房": ("房租", "租金", "物业", "水电", "燃气", "电费", "宽带"),
+        "订阅": ("netflix", "spotify", "爱奇艺", "腾讯视频", "优酷", "b站大会员", "网易云音乐", "qq音乐", "喜马拉雅", "会员", "订阅", "icloud", "云盘"),
+        "餐饮": ("外卖", "美团", "饿了么", "餐厅", "饭店", "火锅", "烧烤", "奶茶", "咖啡", "星巴克", "便利店", "早餐", "午餐", "晚餐"),
+        "交通": ("地铁", "公交", "滴滴", "打车", "高铁", "火车", "加油", "停车", "共享单车", "单车"),
+        "娱乐": ("电影", "影院", "演唱会", "游戏", "steam", "剧本杀", "桌游", "livehouse", "音乐节", "门票"),
+        "购物": ("淘宝", "天猫", "京东", "拼多多", "商场", "优衣库", "服饰", "鞋", "数码", "商城", "超市", "礼物"),
+        "学习": ("课程", "书店", "图书", "学习", "考试", "培训", "语言", "知识", "论文"),
+        "健身": ("健身", "瑜伽", "游泳", "跑步", "keep", "运动", "球馆"),
+        "医疗": ("医院", "药房", "药店", "体检", "医疗"),
+    }
+
+    def classify(self, transaction: Transaction, memory_lookup: Callable[[str], str | None] | None = None) -> CategoryResult:
+        if transaction.kind == "income":
+            return CategoryResult("收入", 1.0, "income_rule")
+        if memory_lookup:
+            remembered = memory_lookup(transaction.merchant)
+            if remembered in CATEGORIES:
+                return CategoryResult(remembered, 1.0, "memory")
+        haystack = f"{transaction.merchant} {transaction.note}".lower()
+        for category, keywords in self.rules.items():
+            if any(keyword.lower() in haystack for keyword in keywords):
+                return CategoryResult(category, 0.92, "keyword_rule")
+        return CategoryResult("其他", 0.25, "fallback")
+
+    def apply(self, transactions: Iterable[Transaction], memory_lookup: Callable[[str], str | None] | None = None) -> list[Transaction]:
+        result: list[Transaction] = []
+        for transaction in transactions:
+            classified = self.classify(transaction, memory_lookup)
+            transaction.category = classified.category
+            transaction.category_confidence = classified.confidence
+            result.append(transaction)
+        return result

+ 0 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/__init__.py


+ 88 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/fakes.py

@@ -0,0 +1,88 @@
+"""LLM test double: production has no offline route; tests avoid network calls."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Iterable
+
+
+@dataclass
+class _Status:
+    reason: str = "test Hello-Agents runtime"
+    enabled: bool = True
+
+
+class FakeRuntime:
+    """Contract-level stand-in for HelloAgentsRuntime used only by unit tests."""
+
+    def __init__(self) -> None:
+        self.status = _Status()
+        self.registered: tuple[str, ...] = ()
+
+    def register_tool_functions(self, functions) -> None:
+        self.registered = tuple(functions)
+
+    def status_dict(self) -> dict:
+        return {
+            "available": True,
+            "enabled": True,
+            "reason": self.status.reason,
+            "registry_name": "Fake ToolRegistry",
+            "paradigms": ["ReActAgent", "PlanSolveAgent", "ReflectionAgent"],
+            "registered_tools": list(self.registered),
+        }
+
+    def classify_uncertain(self, merchant: str, note: str, allowed_categories: list[str]) -> str:
+        return "其他" if "其他" in allowed_categories else allowed_categories[0]
+
+    @staticmethod
+    def _quest_json(prompt: str) -> str:
+        """Mirror only the strict JSON protocol, not production Quest logic."""
+        marker = "SIGNAL_CATALOG_JSON:\n"
+        catalog: list[dict] = []
+        if marker in prompt:
+            raw = prompt.split(marker, 1)[1]
+            decoder = json.JSONDecoder()
+            try:
+                catalog, _ = decoder.raw_decode(raw.lstrip())
+            except json.JSONDecodeError:
+                catalog = []
+        names = {
+            "late_night": ("夜航冷静结界", "给深夜冲动留一段缓冲,不必用意志硬扛。", "先辨认触发场景,再为自己准备替代选项。"),
+            "frequent_small": ("零钱能量巡逻", "把细碎消费当作线索,找回自己选择的节奏。", "出门前先想好今天最想守住的体验。"),
+            "flexible_budget": ("弹性钱包护盾", "体验额度依然保留,只是让目标也拥有位置。", "付款前停一停,确认这次消费是否真的值得。"),
+            "subscriptions": ("订阅遗迹寻宝", "把持续扣费翻出来,留下真正陪伴你的服务。", "从最近使用感受开始,逐项做一个保留决定。"),
+            "weekend": ("周末钱包护盾", "周末可以尽兴,也可以留下一点可控的边界。", "安排活动前先选定最想投入的一件事。"),
+            "payday": ("发薪冷静回合", "到账后的兴奋值得被看见,也值得多一点缓冲。", "先把想买的东西记下,稍后再决定是否结算。"),
+            "learning_followthrough": ("学习战利品回访", "让学习消费继续产生陪伴感,而不只是一次付款。", "选一个最容易开始的学习入口,写下下次打开它的时机。"),
+            "goal_transfer": ("目标补给路线", "让本月结余有一个温柔去处,持续靠近你的愿望。", "先确认最想推进的目标,再写下这次结余的安排。"),
+            "balance": ("镜像决策日志", "消费没有标准答案,记录会帮你看见自己的偏好。", "挑一笔最近消费,写下它带来的真实感受。"),
+        }
+        quests = []
+        for signal in catalog:
+            signal_id = signal.get("signal_id")
+            if signal_id in names:
+                title, narrative, action_hint = names[signal_id]
+                quests.append({"signal_id": signal_id, "title": title, "narrative": narrative, "action_hint": action_hint})
+        return json.dumps({"quests": quests[:5]}, ensure_ascii=False)
+
+    def explain(self, prompt: str, mode: str = "simple", evidence: Iterable[str] = (), memory: Iterable[str] = ()) -> str:
+        if "SIGNAL_CATALOG_JSON:" in prompt or "Quest JSON" in prompt:
+            return self._quest_json(prompt)
+        if mode == "reflection":
+            return "已根据验证的账单、预算和目标证据完成本轮反思;下一步选择一个低摩擦任务即可。"
+        if mode == "plan":
+            return "先阅读已验证的消费证据,再挑选一个能在本周完成的小行动。"
+        return "这是一段基于已验证消费证据生成的 AI 引导文案。"
+
+    def generate_quest_candidates(self, prompt: str) -> str:
+        return self._quest_json(prompt)
+
+    def generate_markdown(self, report_payload: str) -> str:
+        return "# MoneyMirrorAgent 月度报告\n\n这是由测试 LLM 生成的 Markdown 报告。\n"
+
+    def stream_user_guidance(self, question: str, report_payload: str, history):
+        yield "🪞 先从一个小行动开始:"
+        yield "本周记录一次触发消费的场景,然后告诉我你的发现。"

+ 53 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_conversation_agent.py

@@ -0,0 +1,53 @@
+"""Tests for the compact, data-grounded LLM conversation payload."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from src.agents.conversation_agent import ConversationAgent
+from src.agents.coordinator import MoneyMirrorCoordinator
+
+from .fakes import FakeRuntime
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_conversation_payload_keeps_verified_facts_without_raw_audit_data() -> None:
+    coordinator = MoneyMirrorCoordinator(":memory:", runtime=FakeRuntime())
+    try:
+        report = coordinator.analyze_csv(ROOT / "data" / "sample_01.csv")
+        payload = ConversationAgent.payload(
+            report,
+            [
+                {"role": "assistant", "content": "开场"},
+                {"role": "user", "content": "我想控制深夜外卖"},
+                {"role": "assistant", "content": "请从一个小任务开始"},
+            ],
+        )
+        parsed = json.loads(payload)
+        facts = parsed["[Verified tool output]"]
+        assert facts["summary"]["expense"] == 6574
+        assert facts["patterns"]["late_night"]["count"] >= 3
+        assert facts["persona"]["primary"]
+        assert facts["quests"]
+        assert facts["guided_conversation"][-1]["content"] == "请从一个小任务开始"
+        # Raw accounting/audit detail remains in the persisted JSON only, not
+        # in every LLM turn where it can crowd out the facts above.
+        assert "transactions" not in facts
+        assert "agent_trace" not in facts
+    finally:
+        coordinator.close()
+
+
+def test_compact_conversation_bounds_history_and_message_length() -> None:
+    history = [
+        {"role": "user", "content": f"turn-{index}"}
+        for index in range(8)
+    ]
+    history[-1]["content"] = "x" * 700
+    compact = ConversationAgent.compact_conversation(history)
+    assert len(compact) == ConversationAgent.MAX_HISTORY_ITEMS
+    assert compact[0]["content"] == "turn-2"
+    assert compact[-1]["content"].endswith("…")
+    assert len(compact[-1]["content"]) == ConversationAgent.MAX_MESSAGE_CHARS + 1

+ 45 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_coordinator.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+from src.agents.coordinator import MoneyMirrorCoordinator
+from src.models import Goal
+
+from .fakes import FakeRuntime
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_complete_demo_pipeline_persists_memory_and_reflects(tmp_path: Path) -> None:
+    coordinator = MoneyMirrorCoordinator(tmp_path / "memory.db", "test_user", runtime=FakeRuntime())
+    try:
+        coordinator.add_goal(Goal("travel_fund_2026", "三个月旅行基金", "travel", 10000, 2800, "2026-10-31"))
+        report = coordinator.analyze_csv(ROOT / "data" / "sample_01.csv")
+        assert report.month == "2026-07"
+        assert report.summary["balance"] == 1026
+        assert report.persona["primary"]
+        assert report.quests
+        assert report.gamification["level"] >= 1
+        assert "longest_streak_days" in report.gamification
+        assert report.reflection["has_previous_snapshot"] is True
+        assert report.reflection["next_cycle_month"] == "2026-08"
+        assert report.reflection["next_cycle_budget"]["categories"]
+        assert report.reflection["next_cycle_quests"]
+        assert coordinator.memory.get_budget("2026-08") is not None
+        assert report.goals[0]["required_monthly_amount"] > 0
+        assert coordinator.memory.get_snapshot("2026-07") is not None
+        coordinator.correct_merchant_category("测试奶茶店", "餐饮")
+        assert coordinator.memory.get_merchant_category("测试奶茶店") == "餐饮"
+        json_path, markdown_path = coordinator.write_outputs(
+            report,
+            tmp_path / "outputs",
+            source_csv=ROOT / "data" / "sample_01.csv",
+        )
+        assert json_path.name == "sample_01_money_mirror_report.json"
+        assert markdown_path.name == "sample_01_money_mirror_report.md"
+        assert json_path.exists() and markdown_path.exists()
+    finally:
+        coordinator.close()
+
+
+def test_output_stem_uses_input_csv_basename() -> None:
+    assert MoneyMirrorCoordinator._output_stem("data/sample_01.csv") == "sample_01_money_mirror_report"
+    assert MoneyMirrorCoordinator._output_stem("/tmp/八月账单.csv") == "八月账单_money_mirror_report"

+ 32 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_csv_import.py

@@ -0,0 +1,32 @@
+from io import StringIO
+
+from src.tools.csv_import import CSVImportTool
+
+
+def test_normalizes_chinese_columns_and_signed_amounts() -> None:
+    source = StringIO("日期,商户,金额,备注\n2026/07/01 22:30,测试外卖,-35,夜宵\n2026/07/05,工资,7000,工资到账\n")
+    transactions = CSVImportTool().load(source)
+    assert len(transactions) == 2
+    assert transactions[0].kind == "expense"
+    assert transactions[0].amount == 35
+    assert transactions[0].occurred_at == "2026-07-01T22:30"
+    assert transactions[1].kind == "income"
+
+
+def test_rejects_missing_required_columns() -> None:
+    source = StringIO("金额,备注\n20,hello\n")
+    try:
+        CSVImportTool().load(source)
+    except ValueError as exc:
+        assert "日期和商户" in str(exc)
+    else:
+        raise AssertionError("expected CSV validation error")
+
+
+def test_accepts_binary_gb18030_and_exposes_partial_row_warnings() -> None:
+    raw = "日期,商户,金额,收支\n2026-07-01,工资,7000,收入\n坏日期,外卖,35,支出\n".encode("gb18030")
+    tool = CSVImportTool()
+    transactions = tool.load(__import__("io").BytesIO(raw))
+    assert len(transactions) == 1
+    assert transactions[0].kind == "income"
+    assert tool.last_errors and "第 3 行" in tool.last_errors[0]

+ 74 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_dynamic_quest_orchestration.py

@@ -0,0 +1,74 @@
+"""Tests for signal → LLM JSON → Python-validated Quest orchestration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from src.agents.quest_agent import QuestAgent
+from src.memory import SQLiteMemory
+from src.models import Transaction
+
+from .fakes import FakeRuntime
+
+
+def test_weekend_signal_can_produce_a_different_llm_orchestrated_quest(tmp_path: Path) -> None:
+    memory = SQLiteMemory(tmp_path / "memory.db")
+    agent = QuestAgent(memory, FakeRuntime())
+    transactions = [
+        Transaction("a", "2026-07-04T12:00", "周末餐馆", 100, "expense", "餐饮"),
+        Transaction("b", "2026-07-05T15:00", "周末展览", 100, "expense", "餐饮"),
+        Transaction("c", "2026-07-11T19:00", "周末聚餐", 100, "expense", "餐饮"),
+    ]
+    try:
+        quests, _, _, trace = agent.run(
+            transactions,
+            "2026-07",
+            {"expense": 300, "balance": 0, "savings_rate": 0},
+            {"餐饮": 300},
+            {
+                "late_night": {"count": 0, "amount": 0, "share": 0},
+                "frequent_small": {"count": 0, "amount": 0},
+                "weekend": {"count": 3, "amount": 300, "share": 100},
+                "payday_window": {"count": 0, "amount": 0, "share": 0},
+            },
+            [],
+            {"categories": {"餐饮": {"recommended": 290}}},
+            [],
+        )
+        assert [quest.quest_id for quest in quests] == ["weekend_wallet_shield"]
+        quest = quests[0]
+        # The LLM supplied the non-numeric title/copy, while Python supplied
+        # the target (300 * 0.85) and current progress evidence.
+        assert quest.title == "周末钱包护盾"
+        assert quest.target == 255
+        assert quest.quest_type == "weekend_spend_limit"
+        assert "已核验目标" in quest.description
+        assert trace["llm_orchestration"]["accepted_signal_ids"] == ["weekend"]
+        assert trace["llm_orchestration"]["numeric_authority"].startswith("Python only")
+    finally:
+        memory.close()
+
+
+def test_quest_candidate_with_model_invented_number_is_rejected(tmp_path: Path) -> None:
+    memory = SQLiteMemory(tmp_path / "memory.db")
+    agent = QuestAgent(memory, FakeRuntime())
+    try:
+        blueprint = agent._discover_signals(
+            {"expense": 100, "balance": 0},
+            {},
+            {
+                "late_night": {"count": 2, "amount": 80, "share": 80},
+                "frequent_small": {"count": 0, "amount": 0},
+                "weekend": {"count": 0, "amount": 0, "share": 0},
+                "payday_window": {"count": 0, "amount": 0, "share": 0},
+            },
+            [],
+            {"categories": {}},
+            [],
+        )
+        raw = '{"quests":[{"signal_id":"late_night","title":"夜航2号结界","narrative":"连续2天不点外卖,冲刺奖励。","action_hint":"先忍十分钟再决定是否下单。"}]}'
+        candidates, problems = agent._parse_and_validate_candidates(raw, blueprint)
+        assert candidates == []
+        assert any("金额、百分比或阿拉伯数字" in item for item in problems)
+    finally:
+        memory.close()

+ 15 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_memory_and_category.py

@@ -0,0 +1,15 @@
+from src.memory import SQLiteMemory
+from src.models import Transaction
+from src.tools.transaction_category import TransactionCategoryTool
+
+
+def test_manual_category_correction_overrides_rule() -> None:
+    memory = SQLiteMemory(":memory:")
+    try:
+        memory.set_merchant_category("星巴克", "学习")
+        transaction = Transaction("id", "2026-07-01T09:00", "星巴克", 35, "expense")
+        result = TransactionCategoryTool().classify(transaction, memory.get_merchant_category)
+        assert result.category == "学习"
+        assert result.source == "memory"
+    finally:
+        memory.close()

+ 156 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_persona_agent.py

@@ -0,0 +1,156 @@
+"""Persona scoring must remain evidence-based and configurable."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from src.agents.persona_agent import PersonaAgent
+
+from .fakes import FakeRuntime
+
+
+def _patterns(**overrides) -> dict:
+    base = {
+        "late_night": {"share": 0.0, "count": 0, "amount": 0.0},
+        "weekend": {"share": 0.0, "count": 0, "amount": 0.0},
+        "payday_window": {"share": 0.0, "count": 0, "amount": 0.0},
+        "frequent_small": {"count": 0, "amount": 0.0, "average": 0.0},
+    }
+    base.update(overrides)
+    return base
+
+
+def test_persona_uses_scoring_and_evidence_validation() -> None:
+    agent = PersonaAgent(FakeRuntime())
+    persona, trace = agent.run(
+        {"expense": 1000.0, "savings_rate": 8.0},
+        {"餐饮": 350.0, "娱乐": 180.0, "购物": 120.0, "订阅": 0.0, "学习": 0.0},
+        _patterns(
+            late_night={"share": 28.0, "count": 5, "amount": 280.0},
+            frequent_small={"count": 7, "amount": 210.0, "average": 30.0},
+        ),
+        [],
+    )
+
+    assert persona["archetype"] == "late_night_focus"
+    assert persona["primary"] == "夜行消费探索者"
+    assert persona["score"] >= 52
+    assert persona["confidence"] == round(persona["score"] / 100, 2)
+    assert any("深夜消费占比" in item for item in persona["evidence"])
+    assert trace["llm_role"].startswith("仅生成")
+    assert trace["candidates"][0]["archetype"] == "late_night_focus"
+
+
+def test_generic_food_and_small_spending_never_claims_coffee_persona() -> None:
+    agent = PersonaAgent(FakeRuntime())
+    persona, _ = agent.run(
+        {"expense": 1000.0, "savings_rate": 5.0},
+        {"餐饮": 400.0, "娱乐": 0.0, "购物": 0.0},
+        _patterns(frequent_small={"count": 9, "amount": 280.0, "average": 31.0}),
+        [],
+    )
+
+    assert persona["archetype"] == "frequent_small_spend"
+    assert persona["primary"] == "高频小额行动派"
+    assert all("咖啡" not in label for label in persona["labels"])
+
+
+def test_learning_persona_requires_history_not_a_single_large_month() -> None:
+    agent = PersonaAgent(FakeRuntime())
+    persona, trace = agent.run(
+        {"expense": 1000.0, "savings_rate": 5.0},
+        {"学习": 300.0},
+        _patterns(),
+        [],
+    )
+
+    learning = next(item for item in trace["candidates"] if item["archetype"] == "learning_investor")
+    assert learning["evidence_valid"] is False
+    assert persona["archetype"] != "learning_investor"
+
+def test_persona_config_rejects_unknown_feature_reference(tmp_path) -> None:
+    config_path = tmp_path / "personas.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "archetypes": [
+                    {
+                        "id": "typo_guard",
+                        "name": "配置校验测试",
+                        "minimum_score": 50,
+                        "required_features": {"nightt": 40},
+                        "weights": {"nightt": 1.0},
+                        "evidence_metrics": ["late_night_share"],
+                    }
+                ],
+                "fallback": {"id": "balanced", "name": "均衡", "evidence_metrics": []},
+            },
+            ensure_ascii=False,
+        ),
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match="未知特征: nightt"):
+        PersonaAgent(FakeRuntime(), config_path=config_path)
+
+
+
+def test_richer_persona_catalog_exposes_distinct_data_driven_archetypes() -> None:
+    agent = PersonaAgent(FakeRuntime())
+    configured_ids = {item.archetype_id for item in agent.archetypes}
+
+    assert len(configured_ids) >= 12
+    assert {
+        "payday_rhythm",
+        "weekend_social",
+        "food_routine",
+        "savings_sprinter",
+        "digital_lifestyle",
+        "learning_consistent",
+        "flexible_adventurer",
+        "mindful_minimalist",
+    } <= configured_ids
+
+
+def test_payday_persona_is_selected_from_payday_evidence() -> None:
+    agent = PersonaAgent(FakeRuntime())
+    persona, trace = agent.run(
+        {"expense": 1000.0, "savings_rate": 18.0},
+        {"餐饮": 200.0, "娱乐": 80.0},
+        _patterns(
+            payday_window={"share": 68.0, "count": 6, "amount": 680.0},
+            frequent_small={"count": 7, "amount": 210.0, "average": 30.0},
+        ),
+        [],
+    )
+
+    assert persona["archetype"] == "payday_rhythm"
+    assert any(item["archetype"] == "payday_rhythm" and item["evidence_valid"] for item in trace["candidates"])
+    assert "工资到账后消费占比" in ";".join(persona["evidence"])
+
+
+def test_food_routine_persona_requires_repeated_small_food_behavior() -> None:
+    agent = PersonaAgent(FakeRuntime())
+    persona, _ = agent.run(
+        {"expense": 1000.0, "savings_rate": 5.0},
+        {"餐饮": 700.0, "娱乐": 0.0, "购物": 0.0},
+        _patterns(frequent_small={"count": 6, "amount": 50.0, "average": 8.33}),
+        [],
+    )
+
+    assert persona["archetype"] == "food_routine"
+    assert persona["primary"] == "日常餐饮探索家"
+
+
+def test_savings_feature_keeps_the_verified_savings_rate_shape() -> None:
+    agent = PersonaAgent(FakeRuntime())
+    persona, _ = agent.run(
+        {"expense": 1000.0, "savings_rate": 47.5},
+        {"餐饮": 300.0},
+        _patterns(),
+        [],
+    )
+
+    assert persona["feature_vector"]["savings"] == 47.5

+ 10 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_quest_progress.py

@@ -0,0 +1,10 @@
+from src.models import Quest, Transaction
+from src.tools.quest_progress import QuestProgressTool
+
+
+def test_category_budget_quest_uses_real_spending() -> None:
+    transaction = Transaction("1", "2026-07-01T12:00", "电影院", 80, "expense", "娱乐")
+    quest = Quest("q", "娱乐预算", "", "category_limit", 100, 0, "娱乐", 10)
+    updated = QuestProgressTool().update(quest, [transaction], "2026-07")
+    assert updated.progress == 20
+    assert updated.status == "active"

+ 82 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_sample_files.py

@@ -0,0 +1,82 @@
+"""Coverage for bundled fictional bill files and the explicit CSV CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from main import _parse_goal, parser
+from src.agents.coordinator import MoneyMirrorCoordinator
+from src.tools import CSVImportTool
+
+from .fakes import FakeRuntime
+
+ROOT = Path(__file__).resolve().parents[1]
+SAMPLE_FILES = tuple(ROOT / "data" / f"sample_{index:02d}.csv" for index in range(1, 6))
+
+
+def test_all_bundled_sample_files_exist_and_import() -> None:
+    importer = CSVImportTool()
+    assert len(SAMPLE_FILES) == 5
+    for index, path in enumerate(SAMPLE_FILES, start=1):
+        assert path.is_file(), f"sample-{index:02d} is missing its CSV: {path}"
+        transactions = importer.load(path)
+        assert transactions, f"sample-{index:02d} should contain transactions"
+        assert not importer.last_errors, f"sample-{index:02d} has invalid rows: {importer.last_errors}"
+
+
+def test_samples_produce_distinct_data_grounded_quest_signals(tmp_path) -> None:
+    quest_ids: dict[str, set[str]] = {}
+    subscription_merchants: dict[str, set[str]] = {}
+    for index, path in enumerate(SAMPLE_FILES, start=1):
+        sample_id = f"sample-{index:02d}"
+        coordinator = MoneyMirrorCoordinator(tmp_path / f"{sample_id}.db", runtime=FakeRuntime())
+        try:
+            report = coordinator.analyze_csv(path)
+            assert report.summary["income"] > 0
+            assert report.summary["expense"] > 0
+            assert report.quests
+            quest_ids[sample_id] = {quest.quest_id for quest in report.quests}
+            subscription_merchants[sample_id] = {item["merchant"] for item in report.subscriptions}
+        finally:
+            coordinator.close()
+
+    assert "weekend_wallet_shield" in quest_ids["sample-03"]
+    assert "payday_cooldown" in quest_ids["sample-04"]
+    assert "learning_loot_log" in quest_ids["sample-02"]
+    assert "subscription_hunter" in quest_ids["sample-05"]
+    assert "房东-六月房租" not in subscription_merchants["sample-04"]
+    assert "腾讯视频会员" in subscription_merchants["sample-05"]
+    assert len({tuple(sorted(ids)) for ids in quest_ids.values()}) >= 4
+
+
+def test_csv_path_is_required_and_demo_flag_is_removed() -> None:
+    command = parser()
+    args = command.parse_args(["--csv", "bill.csv"])
+    assert args.csv == Path("bill.csv")
+    assert args.interactive is False
+    assert not hasattr(args, "demo")
+
+    interactive_args = command.parse_args(["--interactive", "--csv", "bill.csv"])
+    assert interactive_args.interactive is True
+    with pytest.raises(SystemExit):
+        command.parse_args([])
+    with pytest.raises(SystemExit):
+        command.parse_args(["--demo", "--csv", "bill.csv"])
+
+
+def test_cli_goal_parsing_is_explicit_and_validated() -> None:
+    travel = _parse_goal("三个月旅行基金|travel|10000|2800|2026-10-31")
+    assert travel.goal_type == "travel"
+    assert travel.target_amount == 10000
+    assert travel.current_amount == 2800
+
+    category = _parse_goal("本月娱乐限额|category_limit|800|0|2026-08-31|娱乐|800")
+    assert category.category == "娱乐"
+    assert category.monthly_limit == 800
+
+    with pytest.raises(ValueError, match="格式"):
+        _parse_goal("格式不完整|travel")
+    with pytest.raises(ValueError, match="category_limit"):
+        _parse_goal("娱乐限额|category_limit|800|0|2026-08-31")

+ 54 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_terminal_quests.py

@@ -0,0 +1,54 @@
+"""Terminal-only Quest completion behavior."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from src.agents.coordinator import MoneyMirrorCoordinator
+
+from .fakes import FakeRuntime
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_cli_can_confirm_subscription_quest_and_memory_preserves_it(tmp_path: Path) -> None:
+    coordinator = MoneyMirrorCoordinator(tmp_path / "memory.db", runtime=FakeRuntime())
+    try:
+        report = coordinator.analyze_csv(ROOT / "data" / "sample_01.csv")
+        result = coordinator.complete_quest(report, "subscription_hunter", "已检查三个订阅")
+        quest = next(item for item in report.quests if item.quest_id == "subscription_hunter")
+        assert quest.status == "completed"
+        assert quest.progress == quest.target
+        assert result["gained_exp"] == quest.exp_reward
+
+        # Re-analyzing the same monthly bill must retain the user-confirmed
+        # review rather than letting deterministic transaction parsing erase it.
+        refreshed = coordinator.analyze_csv(ROOT / "data" / "sample_01.csv")
+        refreshed_quest = next(item for item in refreshed.quests if item.quest_id == "subscription_hunter")
+        assert refreshed_quest.status == "completed"
+        assert "CLI" in refreshed_quest.evidence
+    finally:
+        coordinator.close()
+
+
+def test_cli_cannot_override_spending_derived_quest(tmp_path: Path) -> None:
+    coordinator = MoneyMirrorCoordinator(tmp_path / "memory.db", runtime=FakeRuntime())
+    try:
+        report = coordinator.analyze_csv(ROOT / "data" / "sample_01.csv")
+        with pytest.raises(ValueError, match="账单自动计算"):
+            coordinator.complete_quest(report, "late_night_guard")
+    finally:
+        coordinator.close()
+
+
+def test_main_requires_an_explicit_csv_path() -> None:
+    """A bill path is required; no hidden default bill is selected."""
+    import main
+
+    command = main.parser()
+    args = command.parse_args(["--csv", "bill.csv"])
+    assert args.csv.name == "bill.csv"
+    assert not hasattr(args, "demo")
+

+ 64 - 0
Co-creation-projects/CoralGarden52-MoneyMirrorAgent/tests/test_tools.py

@@ -0,0 +1,64 @@
+from pathlib import Path
+
+from src.tools import AnomalyDetectionTool, BudgetCalculatorTool, CSVImportTool, StatisticsTool, SubscriptionDetectorTool
+from src.agents.coordinator import MoneyMirrorCoordinator
+from src.agents.transaction_agent import TransactionAgent
+from src.memory import SQLiteMemory
+
+from .fakes import FakeRuntime
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def classified_transactions():
+    memory = SQLiteMemory(":memory:")
+    imported = CSVImportTool().load(ROOT / "data" / "sample_01.csv")
+    transactions, _ = TransactionAgent(memory, FakeRuntime()).run(imported)
+    return memory, transactions
+
+
+def test_statistics_anomaly_budget_and_subscription_are_data_driven() -> None:
+    memory, transactions = classified_transactions()
+    try:
+        stats = StatisticsTool()
+        summary = stats.summarize(transactions, "2026-07")
+        assert summary["income"] == 7600
+        assert summary["expense"] > 6000
+        assert stats.patterns(transactions, "2026-07")["late_night"]["count"] >= 3
+        anomalies = AnomalyDetectionTool().detect(transactions, "2026-07")
+        assert any(item.merchant == "京东-电脑配件商城" for item in anomalies)
+        budget = BudgetCalculatorTool().calculate(transactions, "2026-07")
+        assert budget["categories"]["住房"]["bucket"] == "fixed"
+        assert budget["categories"]["娱乐"]["bucket"] == "optional"
+        assert budget["categories"]["餐饮"]["bucket"] == "necessary"
+        subscriptions = SubscriptionDetectorTool().detect(transactions)
+        names = {item["merchant"] for item in subscriptions}
+        assert "腾讯视频会员" in names
+        assert "房东-六月房租" not in names
+        assert "星巴克" not in names
+        assert "万达影院" not in names
+        assert "滴滴出行" not in names
+    finally:
+        memory.close()
+
+
+def test_hello_agents_registry_exposes_all_deterministic_tools() -> None:
+    memory, transactions = classified_transactions()
+    try:
+        coordinator = MoneyMirrorCoordinator(":memory:", runtime=FakeRuntime())
+        try:
+            names = set(coordinator.runtime.status_dict()["registered_tools"])
+            assert names == {
+                "CSVImportTool",
+                "TransactionCategoryTool",
+                "StatisticsTool",
+                "AnomalyDetectionTool",
+                "BudgetCalculatorTool",
+                "GoalProjectionTool",
+                "SubscriptionDetectorTool",
+                "QuestProgressTool",
+            }
+        finally:
+            coordinator.close()
+    finally:
+        memory.close()

+ 260 - 0
Co-creation-projects/DeLunnLi-PaperGraph/README.md

@@ -0,0 +1,260 @@
+# PaperGraph(知脉)- 面向研究者的智能文献工作台
+
+<div align="center">
+
+**Academic Paper Search, Reading, Recommendation and Knowledge Graph Workspace**
+
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/)
+[![Vue](https://img.shields.io/badge/Vue-3.x-brightgreen.svg)](https://vuejs.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-DeLunnLi/PaperGraph-black.svg)](https://github.com/DeLunnLi/PaperGraph)
+
+*基于 HelloAgents 构建的学术文献搜索、阅读、推荐与知识图谱系统*
+
+*把找论文、读论文、管理论文和沉淀研究脉络串成一个连续工作流*
+
+</div>
+
+---
+
+## 项目简介
+
+PaperGraph(知脉)是一个面向科研学习、论文调研和研究方向跟踪的智能文献工作台。系统以 SearchAgent、PaperAnalysisAgent 和 KnowledgeGraphAgent 为核心,将自然语言检索、多源论文召回、PDF 阅读问答、每日推荐、文献保存和知识图谱构建整合到同一个 Web 应用中。
+
+它希望解决研究者在日常文献工作中的几个高频痛点:
+
+- 关键词检索分散在多个平台,结果需要手动筛选、去重和排序
+- 阅读论文时缺少上下文辅助,方法、实验、引用关系难以持续沉淀
+- 每日新论文、个人文献库和知识图谱彼此割裂,难以形成长期研究记忆
+- 从发现论文到保存、阅读、追问、归类之间缺少一条顺滑的工作流
+
+### 核心特性
+
+- **自然语言文献搜索**:输入研究问题、论文标题、作者或会议线索,由 LLM 解析意图并生成 SearchRecipe
+- **多源并行召回与精排**:整合 arXiv、DBLP、OpenAlex 与 Tavily 线索,完成去重、过滤、排序和兜底召回
+- **论文阅读助手**:支持 PDF 正文抽取、AI 导读、阅读对话、参考文献查找和表格上下文辅助
+- **每日论文推荐**:根据用户兴趣选择 arXiv 分类,生成个性化候选论文与推荐理由
+- **我的文献库**:支持论文保存、PDF 下载、分类管理、阅读记录和阅读日历
+- **知识图谱构建**:从已保存论文中抽取主题、方法、引用和相关关系,并进行可视化浏览
+- **多智能体共享记忆**:通过 GSSC(Gather -> Score -> Select)流水线选择上下文,减少重复信息干扰
+
+### 技术亮点
+
+- **Recipe 驱动检索**:将 LLM 对用户意图的理解转成可执行检索计划,降低硬编码特殊路径依赖
+- **多源召回与优雅降级**:arXiv、DBLP、OpenAlex 和 Tavily 互为补充,单一来源失败时仍尽量返回可用结果
+- **流式过程反馈**:搜索过程通过 SSE 返回阶段状态和工具调用摘要,便于用户理解结果来源
+- **阅读上下文增强**:阅读器结合论文正文、表格、参考文献和历史记忆回答问题,而不只是展示 PDF
+- **共享记忆机制**:多个 Agent 共享论文、偏好和反馈上下文,让后续搜索与推荐更贴近用户兴趣
+- **前后端契约生成**:通过 OpenAPI 导出前端类型,减少接口字段漂移
+
+## 应用场景
+
+### 适合谁使用?
+
+- **研究生/博士生**:快速进入新方向,建立论文阅读和调研脉络
+- **科研工作者**:跟踪每日新论文,沉淀个人文献库和主题关系
+- **AI/工程研发人员**:围绕技术问题快速查找论文、保存证据和复盘方法
+- **课程学习者**:用对话式阅读辅助理解论文方法、实验和引用背景
+
+### 典型使用场景
+
+1. **主题调研**:输入研究问题 -> 多源召回论文 -> 保存候选论文 -> 形成阅读列表
+2. **论文精读**:打开 PDF -> 获取 AI 导读 -> 围绕方法、实验和局限继续追问
+3. **每日跟踪**:系统拉取新论文 -> 个性化推荐 -> 保存感兴趣论文 -> 反馈偏好
+4. **知识沉淀**:从文献库抽取关系 -> 生成图谱 -> 观察主题、作者和论文之间的连接
+
+## 系统架构
+
+### 整体架构
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│                         前端界面层                            │
+│  文献搜索 | 每日论文 | 我的文献库 | 论文阅读助手 | 知识图谱       │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              │ REST + SSE
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                         API 接口层                            │
+│              FastAPI Routes + OpenAPI + Tool Events           │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                       智能体编排层                             │
+│  SearchAgent | PaperAnalysisAgent | KnowledgeGraphAgent        │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                         核心服务层                            │
+│  Search Pipeline | PDF Parser | Daily Recommend | AgentMemory  │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                         数据持久层                            │
+│       SQLite 文献库 | PDF 文件存储 | 阅读记录 | 反馈记忆          │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 三类智能体
+
+| 智能体 | 职责 | 核心能力 |
+|--------|------|----------|
+| **SearchAgent** | 文献搜索与结果解释 | 意图解析、SearchRecipe、多源召回、LLM 精排 |
+| **PaperAnalysisAgent** | 论文阅读与分析 | 摘要生成、标签归类、阅读问答、引用查找 |
+| **KnowledgeGraphAgent** | 知识图谱构建 | 论文关系抽取、图谱数据生成、节点详情解释 |
+
+### 搜索链路
+
+```text
+用户问题
+  -> LLM 意图解析
+  -> SearchRecipe
+  -> arXiv / DBLP / OpenAlex / Tavily 多源召回
+  -> 去重与过滤
+  -> LLM 精排
+  -> 结果解释与保存
+```
+
+## Quick Start
+
+### 1. 环境要求
+
+- Python 3.10+
+- Node.js 18+
+- 可用的 OpenAI 兼容 LLM 服务
+
+### 2. 后端安装与配置
+
+```bash
+cd backend
+pip install -r requirements.txt
+```
+
+在 `backend/.env` 中配置模型信息:
+
+```env
+LLM_API_KEY=your_api_key
+LLM_BASE_URL=https://your-openai-compatible-endpoint/v1
+LLM_MODEL_ID=your_model_id
+```
+
+启动后端:
+
+```bash
+python run.py
+```
+
+默认访问地址:`http://localhost:8000`
+
+### 3. 前端安装与启动
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+默认访问地址:`http://localhost:5173`
+
+### 4. 一键启动
+
+也可以在项目根目录执行:
+
+```bash
+./start.sh
+```
+
+## 使用流程
+
+1. 在 **文献搜索** 页面输入自然语言问题,例如“2024 年视觉语言模型中的 grounding 相关论文”。
+2. SearchAgent 解析检索意图,选择关键词、来源、年份、会议等约束,并执行多源召回。
+3. 用户将有价值的论文保存到 **我的文献库**,必要时下载 PDF。
+4. 在 **我的文献库** 中打开某篇论文,进入 **论文阅读助手** 页面查看 AI 导读,并围绕方法、实验、局限和参考文献继续提问。
+5. 在 **每日论文** 页面追踪新论文,在 **知识图谱** 页面观察主题和论文之间的关系。
+
+## 演示效果
+
+文献搜索、每日论文推荐、文献库、论文阅读助手和知识图谱等界面截图,请参见 [毕业设计提交 PR #614](https://github.com/datawhalechina/hello-agents/pull/614)。
+
+## 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| **智能体框架** | HelloAgents(SimpleAgent + ToolRegistry + CircuitBreaker + ContextBuilder) |
+| **后端服务** | FastAPI + SQLite + Pydantic |
+| **前端应用** | Vue 3 + Vite + Ant Design Vue + KaTeX + PDF.js |
+| **LLM 接入** | DeepSeek-V4 / OpenAI 兼容接口 |
+| **论文数据源** | arXiv + DBLP + OpenAlex + Tavily |
+| **PDF 处理** | PyMuPDF(fitz) |
+
+## 工程指标
+
+- **搜索链路**:意图解析 + SearchRecipe + 多源召回 + LLM 精排
+- **推荐链路**:arXiv 候选拉取 + 用户兴趣词 + 个性化筛选 + 反馈记忆
+- **阅读链路**:PDF 解析 + 正文上下文 + 对话历史 + 参考文献查找
+- **交互方式**:REST API + SSE 流式状态更新
+- **数据存储**:SQLite 文献库 + 本地 PDF 文件 + 阅读记录
+
+## 项目结构
+
+```text
+.
+├─ backend/                 # FastAPI 后端与智能体服务
+│  ├─ app/agents/           # SearchAgent / PaperAnalysisAgent / KnowledgeGraphAgent
+│  ├─ app/api/              # API 路由、依赖和 SSE 工具事件
+│  ├─ app/core/             # Paper 模型、PDF 下载、搜索源适配
+│  ├─ app/services/         # 检索、阅读、推荐、记忆、图谱等业务服务
+│  ├─ data/                 # 本地数据库与运行数据(不提交)
+│  └─ downloads/            # PDF 下载目录(不提交)
+├─ frontend/                # Vue 3 前端应用
+│  ├─ src/views/            # 搜索、每日论文、文献库、阅读器、知识图谱页面
+│  ├─ src/components/       # 论文卡片、搜索结果、工具轨迹、阅读日历等组件
+│  ├─ src/composables/      # 搜索对话、历史记录、标题关键词等组合逻辑
+│  └─ src/services/         # API 客户端与接口封装
+├─ ports.env                # 本地端口配置
+├─ start.sh                 # 一键启动脚本
+└─ README.md
+```
+
+## 开发路线图
+
+### v1.0(当前版本)
+
+- [x] 自然语言文献搜索
+- [x] 多源论文召回与 LLM 精排
+- [x] PDF 阅读助手
+- [x] 每日论文推荐
+- [x] 我的文献库与阅读日历
+- [x] 知识图谱可视化
+
+### v1.1(计划中)
+
+- [ ] 补充搜索、阅读和推荐链路的集成测试
+- [ ] 增加搜索结果缓存和可复现实验样例
+- [ ] 优化搜索过程可观测性和错误提示
+- [ ] 增强知识图谱的关系过滤、编辑和导出能力
+
+### v2.0(未来)
+
+- [ ] 支持 Docker 一键部署
+- [ ] 优化移动端与小屏阅读体验
+- [ ] 引入向量检索或本地语义索引
+- [ ] 支持团队共享文献库和多用户偏好
+
+## 许可证
+
+MIT License
+
+## 作者
+
+GitHub: [@DeLunnLi](https://github.com/DeLunnLi)  
+项目地址: [github.com/DeLunnLi/PaperGraph](https://github.com/DeLunnLi/PaperGraph)
+
+## 致谢
+
+感谢 Datawhale 社区和 Hello-Agents 项目。本项目基于 HelloAgents 的智能体、工具注册、上下文构建和熔断能力完成实践探索。

+ 82 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/.env.example

@@ -0,0 +1,82 @@
+# PaperGraph backend env template.
+# Copy to backend/.env and fill local secrets.
+
+# LLM API
+# OpenAI-compatible chat endpoint.
+LLM_API_KEY=your-llm-api-key
+LLM_BASE_URL=https://api.deepseek.com/v1
+LLM_MODEL_ID=deepseek-v4-flash
+
+# Set to 1 if local proxy causes EOF/SSL errors.
+LLM_DISABLE_PROXY=1
+
+# Optional aliases:
+# OPENAI_API_KEY=your-openai-compatible-api-key
+# OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_MODEL=gpt-4o-mini
+# AIHUBMIX_API_KEY=your-aihubmix-api-key
+# AIHUBMIX_BASE_URL=https://aihubmix.com/v1
+# AIHUBMIX_MODEL_ID=your-model-id
+
+# Embedding API
+# Optional memory embeddings.
+EMBED_MODEL_TYPE=dashscope
+EMBED_MODEL_NAME=text-embedding-v4
+EMBED_API_KEY=your-embedding-api-key
+EMBED_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+
+# Academic search APIs
+NCBI_EMAIL=
+NCBI_API_KEY=
+
+# OpenAlex polite-pool email; blank is allowed.
+OPENALEX_MAILTO=
+
+# Optional web pre-search / proceedings discovery.
+TAVILY_PRESEARCH_ENABLED=true
+TAVILY_API_KEY=
+
+# App
+APP_NAME=PaperGraph
+APP_VERSION=0.1.0
+DEBUG=true
+
+HOST=0.0.0.0
+PORT=8000
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000,http://127.0.0.1:5173,http://127.0.0.1:3000
+
+# Default runtime data path is backend/data.
+# DATA_DIR=/absolute/path/to/DeLunnLi-PaperGraph/backend/data
+# DOWNLOADS_DIR=/absolute/path/to/DeLunnLi-PaperGraph/backend/downloads/papers
+
+LOG_LEVEL=INFO
+
+# Search / ranking tuning
+PAPERGRAPH_SEARCH_AGENT_WALL_SEC=420
+PAPERGRAPH_SEARCH_RECALL_WALL_SEC=60.0
+PAPERGRAPH_SEARCH_ARXIV_FALLBACK_WALL_SEC=15.0
+PAPERGRAPH_SEARCH_RECALL_HTTP_TIMEOUT_SEC=18.0
+PAPERGRAPH_SEARCH_HTTP_MAX_ATTEMPTS=2
+PAPERGRAPH_DBLP_MAX_ATTEMPTS=2
+
+PAPERGRAPH_RECALL_MAX_CANDIDATES=24
+PAPERGRAPH_FINE_RANK_CANDIDATES=15
+PAPERGRAPH_FINE_RANK_TIMEOUT_SEC=30
+PAPERGRAPH_FINE_RANK_ABSTRACT_CHARS=200
+PAPERGRAPH_FINE_RANK_PIPELINE_WALL_SEC=25.0
+
+PAPERGRAPH_PROCEEDINGS_SUPPLEMENT_ENABLED=true
+PAPERGRAPH_PROCEEDINGS_SUPPLEMENT_MIN_CANDIDATES=8
+PAPERGRAPH_PROCEEDINGS_AUTO_DISCOVER=true
+# PAPERGRAPH_TAVILY_VENUE_DOMAINS_JSON=/absolute/path/to/tavily_venue_domains.json
+
+# Daily recommendations
+PAPERGRAPH_DAILY_AUTO_REFRESH=true
+PAPERGRAPH_DAILY_AUTO_REFRESH_IDLE_SEC=90
+PAPERGRAPH_DAILY_AUTO_REFRESH_POLL_SEC=180
+PAPERGRAPH_DAILY_AUTO_REFRESH_STARTUP_GRACE_SEC=120
+PAPERGRAPH_DAILY_ARXIV_HTTP_TIMEOUT_SEC=45.0
+PAPERGRAPH_DAILY_ARXIV_HTTP_MAX_ATTEMPTS=3
+
+# Empty means built-in arXiv category defaults.
+DAILY_ARXIV_CS_CATEGORIES=

+ 0 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/__init__.py


+ 30 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .knowledge_graph_agent import KnowledgeGraphAgent
+from .paper_analysis_agent import PaperAnalysisAgent
+from .search_agent import get_search_agent
+
+__all__ = [
+    "KnowledgeGraphAgent",
+    "PaperAnalysisAgent",
+    "get_knowledge_graph_agent",
+    "get_paper_analysis_agent",
+    "get_search_agent",
+]
+
+_paper_analysis_agent: PaperAnalysisAgent | None = None
+_knowledge_graph_agent: KnowledgeGraphAgent | None = None
+
+
+def get_paper_analysis_agent() -> PaperAnalysisAgent:
+    global _paper_analysis_agent
+    if _paper_analysis_agent is None:
+        _paper_analysis_agent = PaperAnalysisAgent()
+    return _paper_analysis_agent
+
+
+def get_knowledge_graph_agent() -> KnowledgeGraphAgent:
+    global _knowledge_graph_agent
+    if _knowledge_graph_agent is None:
+        _knowledge_graph_agent = KnowledgeGraphAgent()
+    return _knowledge_graph_agent

+ 36 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/base.py

@@ -0,0 +1,36 @@
+"""智能体基类 —— LLM 初始化、配置读取与通用工具方法."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..services.llm.llm_service import get_llm
+from ..settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+class BaseAgent:
+    def __init__(self) -> None:
+        self._settings = get_settings()
+        self.llm = self._init_llm()
+
+    def _init_llm(self) -> Any:
+        try:
+            return get_llm()
+        except Exception as e:
+            logger.exception("[%s] LLM 初始化失败", type(self).__name__)
+            raise RuntimeError(f"{type(self).__name__}_llm_init_failed") from e
+
+    def _cfg(self, name: str, default: Any = None) -> Any:
+        return getattr(self._settings, name, default)
+
+    def _cfg_int(self, name: str, default: int = 0) -> int:
+        try:
+            return int(self._cfg(name, default))
+        except (TypeError, ValueError):
+            return int(default)
+
+    @staticmethod
+    def _clip(value: Any, limit: int) -> str:
+        return str(value or "").strip()[:limit]

+ 153 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/knowledge_graph_agent.py

@@ -0,0 +1,153 @@
+"""知识图谱智能体 —— 从已保存论文中抽取主题/方法/引用关系并构建可视化图谱."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from hello_agents import SimpleAgent
+
+from ..utils import parse_llm_json
+from ..services.llm.agent_config import papergraph_agent_config
+from .base import BaseAgent
+from .prompts.knowledge_graph import REL_PROMPT
+
+logger = logging.getLogger(__name__)
+
+class KnowledgeGraphAgent(BaseAgent):
+    """知识图谱构建智能体 —— 从论文集中抽取关系、生成节点与边数据."""
+
+    def __init__(
+        self,
+        *,
+        agent: SimpleAgent | None = None,
+        min_score: float = 0.55,
+        max_edges: int = 12,
+        chunk_size: int = 20,
+    ) -> None:
+        super().__init__()
+        self.min_score = min_score
+        self.max_edges = max_edges
+        self.chunk_size = chunk_size
+        self._agent = agent or SimpleAgent(
+            name="papergraph_kg_rel",
+            llm=self.llm,
+            system_prompt=REL_PROMPT,
+            config=papergraph_agent_config(),
+        )
+
+    def _candidate_id(self, paper: dict[str, Any]) -> int | None:
+        for key in ("paper_id", "id", "target_paper_id"):
+            try:
+                value = int(paper.get(key))
+                if value > 0:
+                    return value
+            except (TypeError, ValueError):
+                continue
+        return None
+
+    def _compact_paper(self, paper: dict[str, Any]) -> dict[str, Any]:
+        out = {
+            "paper_id": self._candidate_id(paper),
+            "title": self._clip(paper.get("title"), 300),
+            "abstract": self._clip(paper.get("abstract"), 2000),
+            "keywords": list((paper.get("keywords") or [])[:12]),
+            "source": paper.get("source"),
+            "year": paper.get("year"),
+            "category": paper.get("category"),
+            "pdf_excerpt": self._clip(paper.get("pdf_excerpt"), 1200),
+            "related_work_excerpt": self._clip(paper.get("related_work_excerpt"), 1200),
+        }
+        return {k: v for k, v in out.items() if v not in (None, "", [], {})}
+
+    def _validate_edges(self, edges: Any, allowed_ids: set[int]) -> list[dict[str, Any]]:
+        if not isinstance(edges, list):
+            raise ValueError("edges is not a list")
+        best: dict[int, dict[str, Any]] = {}
+        for e in edges:
+            if not isinstance(e, dict):
+                continue
+            try:
+                tid = int(e.get("target_paper_id"))
+                score = float(e.get("score") or 0.0)
+            except Exception:
+                continue
+            if tid not in allowed_ids or score < self.min_score:
+                continue
+            relation = str(e.get("relation") or "").strip()
+            if not relation:
+                continue
+            edge = {"target_paper_id": tid, "relation": relation,
+                    "score": max(0.0, min(1.0, score)),
+                    "evidence": str(e.get("evidence") or "").strip()[:80]}
+            if tid not in best or score > best[tid]["score"]:
+                best[tid] = edge
+        return sorted(best.values(), key=lambda x: x["score"], reverse=True)
+
+    def _chunks(self, items: list[dict[str, Any]]) -> list[list[dict[str, Any]]]:
+        return [items[i : i + self.chunk_size] for i in range(0, len(items), self.chunk_size)]
+
+    def infer_edges(
+        self, *, new_paper: dict[str, Any], candidates: list[dict[str, Any]]
+    ) -> tuple[list[dict[str, Any]], str | None]:
+        compact_new = self._compact_paper(new_paper)
+
+        compact_candidates: list[dict[str, Any]] = []
+        for c in candidates:
+            tid = self._candidate_id(c)
+            if tid is None:
+                continue
+            item = self._compact_paper(c)
+            item["paper_id"] = tid
+            compact_candidates.append(item)
+
+        if not compact_candidates:
+            return [], None
+
+        merged: dict[int, dict[str, Any]] = {}
+
+        for chunk in self._chunks(compact_candidates):
+            payload = {"new_paper": compact_new, "candidates": chunk}
+            try:
+                raw = self._agent.run(json.dumps(payload, ensure_ascii=False))
+            except Exception as exc:
+                logger.exception("kg_llm_run_failed")
+                raise RuntimeError("kg_llm_run_failed") from exc
+
+            data = parse_llm_json(raw)
+            if data is None:
+                raise ValueError("kg_llm_parse_failed")
+
+            try:
+                valid_edges = self._validate_edges(
+                    data.get("edges"),
+                    allowed_ids={int(x["paper_id"]) for x in chunk},
+                )
+            except Exception as exc:
+                raise ValueError("kg_edge_validation_failed") from exc
+
+            for edge in valid_edges:
+                tid = edge["target_paper_id"]
+                if tid not in merged or edge["score"] > merged[tid]["score"]:
+                    merged[tid] = edge
+
+        edges = sorted(merged.values(), key=lambda x: x["score"], reverse=True)[: self.max_edges]
+
+        try:
+            from ..services.memory.agent_memory import get_agent_memory
+
+            am = get_agent_memory()
+            title = str(new_paper.get("title") or "")[:120]
+            am.add(agent_name="knowledge_graph", content=f"关系抽取:{title}", memory_type="working", importance=0.45, shared=False)
+            if edges:
+                am.add(
+                    agent_name="knowledge_graph",
+                    content=f"关系抽取要点:top_relation={edges[0].get('relation')} score={edges[0].get('score')}",
+                    memory_type="working",
+                    importance=0.5,
+                    shared=True,
+                )
+        except Exception:
+            logger.debug("kg_memory_write_failed", exc_info=True)
+        return edges, None

+ 773 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/paper_analysis_agent.py

@@ -0,0 +1,773 @@
+"""论文分析智能体 —— PDF 全文解析、表格提取与深度问答."""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from hello_agents import SimpleAgent
+from hello_agents.tools.registry import ToolRegistry
+
+from app.core.paper_paths import normalize_library_category_display
+
+from ..utils import parse_llm_json
+from ..services.llm.agent_config import papergraph_agent_config
+from ..services.llm.llm_service import is_llm_configured, coerce_hello_agents_llm_output_to_str
+from .base import BaseAgent
+from .support.paper_analysis_helpers import (
+    clip_text as _clip,
+    clip_reader_history as _clip_reader_history,
+    clean_library_tag as _clean_library_tag,
+    dedupe_tags as _dedupe_tags,
+    nearest_major_in as _nearest_major_in,
+    parse_taxonomy_majors as _parse_taxonomy_majors,
+    prioritize_reader_context as _prioritize_reader_context,
+    top_similar_categories as _top_similar_categories,
+)
+from .support.reader_pdf_parse_tool import ReaderPdfParseTool
+from .support.reader_table_tool import ReaderTableTool
+from .support.reader_paper_lookup_tool import ReaderPaperLookupTool, ground_score_paper_vs_reference_blob
+from .support.reader_reference_lookup_tool import (
+    READER_RECOMMEND_MAX_RESULTS, ReaderReferenceLookupTool,
+    READER_RELATED_FROM_BIBLIOGRAPHY, READER_RELATED_FROM_REF_BLOCK,
+    paper_matches_reader_snap, parse_reader_recommendation_intent,
+    prioritize_reader_related_pairs_refs_first, reader_user_allows_external_paper_lookup,
+    rerank_reader_pairs_by_anchor_refs_first, resolve_references_via_openalex,
+    strip_reader_reco_boilerplate, user_message_may_need_reference_lookup,
+    READER_RELATED_FROM_PRE_SEARCH,
+)
+
+from .prompts.paper_analysis import ANALYSIS_SYSTEM, READER_CHAT_SYSTEM
+
+logger = logging.getLogger(__name__)
+
+def _reader_resolve_user_hint(user_message: str, snap: Dict[str, Any], *, want_reco: bool) -> str:
+    um = (user_message or "").strip()
+    if not want_reco:
+        return um[:900]
+    core = strip_reader_reco_boilerplate(um) or um
+    if len(core) >= 28:
+        return um[:900]
+    title = str(snap.get("title") or "").strip()
+    ab = str(snap.get("abstract") or "").strip()[:520]
+    bits = [x for x in (core, title, ab) if x]
+    return "\n".join(bits).strip()[:900] or um[:900]
+
+_MAJOR_LOCK = threading.Lock()
+_MAJOR_WHITELIST: Optional[Tuple[str, ...]] = None
+
+@dataclass
+class TaskSpec:
+    name: str
+    agent: Any
+    parser: Optional[Callable[[str], Any]] = None
+    max_chars: int = 6000
+
+class PaperAnalysisAgent(BaseAgent):
+    """论文分析核心智能体 —— 管理多个子 Agent 协同完成 PDF 解析、表格提取与问答."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._analysis = SimpleAgent(
+            name="papergraph_analysis",
+            llm=self.llm,
+            system_prompt=ANALYSIS_SYSTEM,
+            config=papergraph_agent_config(),
+        )
+        self._reader_lookup_lock = threading.Lock()
+        self._reader_lookup_buffer: List[Tuple[Any, str]] = []
+        self._reader_snap: Dict[str, Any] = {}
+        self._reader_last_user_message: str = ""
+
+        self._reader_reco_ref_offset: Dict[int, int] = {}
+        _reader_reg = ToolRegistry()
+        _reader_reg.register_tool(
+            ReaderPaperLookupTool(
+                on_papers_found=self._reader_tool_on_found,
+                get_snap=lambda: getattr(self, "_reader_snap", None) or {},
+            )
+        )
+        _reader_reg.register_tool(
+            ReaderReferenceLookupTool(
+                get_snap=lambda: getattr(self, "_reader_snap", None) or {},
+                on_papers_found=self._reader_tool_on_found,
+                get_user_message=lambda: getattr(self, "_reader_last_user_message", "") or "",
+            )
+        )
+        _reader_reg.register_tool(
+            ReaderPdfParseTool(
+                get_snap=lambda: getattr(self, "_reader_snap", None) or {},
+                on_parsed=self._reader_on_pdf_structure,
+            )
+        )
+        _reader_reg.register_tool(
+            ReaderTableTool(
+                get_snap=lambda: getattr(self, "_reader_snap", None) or {},
+            )
+        )
+        self._reader = SimpleAgent(
+            name="papergraph_paper_reader",
+            llm=self.llm,
+            system_prompt=READER_CHAT_SYSTEM,
+            config=papergraph_agent_config(),
+            tool_registry=_reader_reg,
+            enable_tool_calling=True,
+            max_tool_iterations=5,
+        )
+
+    def _ensure_major_whitelist(self) -> None:
+        global _MAJOR_WHITELIST
+        if _MAJOR_WHITELIST is not None:
+            return
+        with _MAJOR_LOCK:
+            if _MAJOR_WHITELIST is not None:
+                return
+            wl: Optional[Tuple[str, ...]] = None
+            taxonomy_prompt = (
+                "# 任务:为个人/小团队文献库生成顶层大类\n"
+                '输出: {"majors":["名称1",...]}\n'
+                "- 共 16~24 条;恰含一个「未分类」\n"
+                "- 名称须具学术划分意义,覆盖计算机与交叉学科\n"
+                "- 每条 2~10 个中文字;互异;禁含「/」及路径非法字符\n"
+            )
+            try:
+                raw = self._analysis.run(taxonomy_prompt)
+                parsed = _parse_taxonomy_majors(raw)
+                if not parsed:
+                    self._analysis.run(taxonomy_prompt + '\n请确保输出合法 JSON。')
+                if parsed:
+                    wl = tuple(parsed)
+            except Exception:
+                logger.exception("major_taxonomy_bootstrap_failed")
+            if not wl:
+                raise RuntimeError("major_taxonomy_bootstrap_failed")
+            _MAJOR_WHITELIST = wl
+            logger.info("paper_analysis_major_whitelist_ready", extra={"n": len(wl)})
+
+    def _get_major_whitelist(self) -> Tuple[str, ...]:
+        self._ensure_major_whitelist()
+        if _MAJOR_WHITELIST is None:
+            raise RuntimeError("major_whitelist_unavailable")
+        return _MAJOR_WHITELIST
+
+    def _cleanup_mixed_reader_response(self, reply: str, user_message: str) -> str:
+        """Use one cleanup pass when tool output leaks into the final reply."""
+        t = reply.strip()
+        # Typical leak: disclaimer plus useful data, or raw tool JSON.
+        has_disclaimer = any(x in t[:300] for x in ("材料不足", "缺少", "仅有标题")) or bool(re.search(r"基于.*推测", t[:300]))
+        has_actual_data = len(t) > 600 and any(x in t for x in ("Tab.", "Table", "结果", "实验", "| "))
+        has_tool_artifact = "reader_pdf_struct" in t or '"chapters"' in t[:500]
+
+        if (has_disclaimer and has_actual_data) or has_tool_artifact:
+            if not is_llm_configured():
+                return reply
+            logger.info("paper_reader: detected mixed response, running cleanup pass")
+            try:
+                um = (user_message or "").strip()[:200]
+                # Keep extracted paper facts; drop wrapper noise.
+                cleaned = re.sub(r"^.*?(?:当前文献材料说明|当前提供的材料).*?\n\n", "", t, flags=re.S)
+                cleaned = re.sub(r"reader_pdf_struct\S*", "", cleaned)
+                cleaned = cleaned.strip()[:6000]
+                if cleaned:
+                    prompt = (
+                        f"用户问:{um}\n\n"
+                        f"以下是从论文中提取的信息(可能含多个片段):\n\n{cleaned}\n\n"
+                        "请整合成一个连贯的回答。用中文分点说明。如有表格数据用 Markdown 表格呈现。"
+                        "不要提及'材料不足'或'推测'——只基于已有信息回答,不确定的地方标注'论文未提供'。"
+                    )
+                    result = self._reader_chat_llm(prompt)
+                    if result.strip():
+                        return result.strip()
+            except Exception:
+                logger.debug("cleanup_mixed_response_failed", exc_info=True)
+        return reply
+
+    @staticmethod
+    def _looks_like_raw_tool_output(text: str) -> bool:
+        """Detect raw tool output that still needs interpretation."""
+        t = (text or "").strip()
+        if not t:
+            return False
+        if "reader_pdf_structure" in t:
+            return True
+        if t.startswith("## ") and len(t) > 300:
+            first_line = t.split("\n")[0]
+            if re.match(r"^## \d", first_line) or re.match(r"^## [A-Z]", first_line):
+                return True
+        if '"chapters"' in t[:500] or '"references"' in t[:500]:
+            return True
+        return False
+
+    def _interpret_tool_output(self, tool_output: str, user_message: str) -> str:
+        """Convert raw tool output into a user-facing answer."""
+        if not is_llm_configured():
+            return tool_output
+        try:
+            um = (user_message or "").strip()[:200]
+            # Strip tool wrappers before asking the LLM to explain.
+            cleaned = re.sub(r"^.*?reader_pdf_structure[::]\s*", "", tool_output, flags=re.S)
+            cleaned = re.sub(r"^以下为 JSON.*?\n", "", cleaned)
+            cleaned = re.sub(r"^\s*\{\s*\"chapters\".*?\n", "", cleaned)
+            cleaned = re.sub(r"reader_pdf_structu\S*$", "", cleaned)
+            cleaned = re.sub(r"[\u007F-\u009F]", "", cleaned)
+            cleaned = cleaned.strip()
+            if not cleaned or len(cleaned) < 50:
+                return "当前文献材料不足以回答该问题。PDF 文本提取不完整,建议确认 PDF 文件是否可读。"
+            cleaned = cleaned[:6000]
+            prompt = (
+                f"用户问:{um}\n\n"
+                f"以下是从论文中提取的相关章节内容:\n\n{cleaned}\n\n"
+                "请用中文为用户解读这段内容。分点说明关键发现、方法和结论。"
+                "用 Markdown 表格对比数据(如有)。\n"
+                "重要:如果上面的内容不足以回答用户问题(如仅有章节标题无正文),"
+                "请直接说明材料不足,严禁编造论文中不存在的数据、方法或结论。"
+            )
+            raw = self._reader_chat_llm(prompt)
+            return raw.strip() or tool_output
+        except Exception:
+            logger.debug("interpret_tool_output_failed", exc_info=True)
+            return tool_output
+
+    def _reader_chat_llm(self, prompt: str) -> str:
+        """Reader chat without tools."""
+        from ..services.llm.llm_service import coerce_hello_agents_llm_output_to_str
+        if not hasattr(self, "_reader_interpreter"):
+            from hello_agents import SimpleAgent
+            self._reader_interpreter = SimpleAgent(
+                name="papergraph_reader_interpreter",
+                llm=self.llm,
+                system_prompt=READER_CHAT_SYSTEM,
+                config=papergraph_agent_config(),
+                enable_tool_calling=False,
+            )
+        return coerce_hello_agents_llm_output_to_str(self._reader_interpreter.run(prompt))
+
+    def _reader_tool_on_found(self, papers: List[Any], source: str) -> None:
+        with self._reader_lookup_lock:
+            for p in papers or []:
+                self._reader_lookup_buffer.append((p, source))
+
+    def _reader_on_pdf_structure(self, obj: Dict[str, Any]) -> None:
+        try:
+            snap = getattr(self, "_reader_snap", None)
+            if not isinstance(snap, dict):
+                return
+            refs = obj.get("references") or {}
+            entries = refs.get("entries")
+            if isinstance(entries, list) and entries:
+                snap["references_from_structure"] = [str(x).strip() for x in entries if str(x).strip()]
+        except Exception:
+            logger.debug("reader_on_pdf_structure_failed", exc_info=True)
+
+    @staticmethod
+    def _dedupe_reader_paper_pairs(buffer: List[Tuple[Any, str]]) -> List[Tuple[Any, str]]:
+        seen: set[str] = set()
+        out: List[Tuple[Any, str]] = []
+        for p, src in buffer:
+            k = str(getattr(p, "title", "") or "").strip().lower()
+            if not k or k in seen:
+                continue
+            seen.add(k)
+            out.append((p, src))
+        return out
+    def _run_task(self, spec: TaskSpec, user: str) -> Any:
+        prompt = _clip(user, spec.max_chars)
+        try:
+
+            raw = spec.agent.run(prompt)
+        except Exception as exc:
+            logger.exception("paper_analysis_llm_failed", extra={"task": spec.name})
+            raise RuntimeError(f"paper_analysis_llm_failed:{spec.name}") from exc
+
+        raw_text = (raw if isinstance(raw, str) else str(raw or "")).strip()
+
+        if not spec.parser:
+            if not raw_text:
+                if spec.name == "paper_reader_reply":
+                    return ""
+                raise RuntimeError(f"paper_analysis_empty_response:{spec.name}")
+
+            # Some tool responses need a final explanation pass.
+            if spec.name == "paper_reader_reply" and self._looks_like_raw_tool_output(raw_text):
+                logger.info("paper_reader: detected raw tool output, invoking interpreter")
+                raw_text = self._interpret_tool_output(raw_text, user)
+
+            return raw_text
+
+        data = spec.parser(raw_text)
+        if data is not None:
+            return data
+
+        try:
+            raw2 = spec.agent.run("请只输出合法 JSON。\n" + prompt)
+            data2 = spec.parser((raw2 or "").strip())
+            if data2 is not None:
+                return data2
+        except Exception:
+            logger.exception("paper_analysis_json_retry_failed", extra={"task": spec.name})
+        raise RuntimeError(f"paper_analysis_parse_failed:{spec.name}")
+
+    def _record_preference_signals(
+        self,
+        *,
+        signal: str,
+        title: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        category: Optional[str] = None,
+        major: Optional[str] = None,
+        shared: bool = True,
+    ) -> None:
+        try:
+            from ..services.memory.agent_memory import get_agent_memory
+
+            am = get_agent_memory()
+            parts: List[str] = [f"偏好信号({signal})"]
+            if title:
+                parts.append(f"title={str(title).strip()[:120]}")
+            if major:
+                parts.append(f"major={str(major).strip()[:24]}")
+            if category:
+                parts.append(f"cat={str(category).strip()[:40]}")
+            if tags:
+                clean = [str(x).strip() for x in (tags or []) if str(x).strip()][:10]
+                if clean:
+                    parts.append("tags=" + ",".join(clean))
+            line = " | ".join(parts)[:360]
+            am.add(agent_name="paper_analysis", content=line, memory_type="working", importance=0.55, shared=bool(shared))
+        except Exception:
+            return
+
+    def _parse_major_json(self, raw: str) -> Optional[str]:
+        d = parse_llm_json(raw)
+        if not isinstance(d, dict):
+            return None
+        m = str(d.get("major") or d.get("category") or "").strip()
+        if not m:
+            return None
+        return _nearest_major_in(m, self._get_major_whitelist())
+
+    def _parse_fine_classify_json(self, raw: str, major: str) -> Optional[Tuple[str, List[str]]]:
+        d = parse_llm_json(raw)
+        if not isinstance(d, dict):
+            return None
+        cat = normalize_library_category_display(str(d.get("category") or "未分类"))
+        tags_raw = d.get("tags")
+        extra: List[str] = []
+        if isinstance(tags_raw, list):
+            for x in tags_raw:
+                c = _clean_library_tag(str(x))
+                if c:
+                    extra.append(c)
+            extra = _dedupe_tags(extra)
+        if not cat:
+            return None
+        if major and major != "未分类" and not (cat.startswith(major) or major in cat):
+            cat = normalize_library_category_display(f"{major}/{cat.split('/')[-1]}")
+        return cat, extra
+
+    _venue_type_cache: dict[str, str] = {}
+
+    def classify_venue_type(self, journal: str | None) -> str | None:
+        if not journal or not str(journal).strip():
+            return None
+        j = str(journal).strip()
+        if j.startswith("arXiv:"):
+            return "preprint"
+        if j in self._venue_type_cache:
+            return self._venue_type_cache[j]
+        try:
+            prompt = f'判断以下学术来源名称是会议(conference)还是期刊(journal)。只回复一个单词:conference 或 journal。\n\n名称:{j}'
+            resp = self._analysis.run(prompt)
+            result = str(resp).strip().lower()
+            if "conference" in result:
+                vt = "conference"
+            elif "journal" in result:
+                vt = "journal"
+            else:
+                vt = None
+        except Exception:
+            vt = None
+        if vt:
+            self._venue_type_cache[j] = vt
+        return vt
+
+    def classify_for_library(
+        self,
+        title: str,
+        abstract: Optional[str],
+        journal: Optional[str],
+        keywords: Optional[List[str]] = None,
+        existing_categories: Optional[List[str]] = None,
+    ) -> Tuple[str, List[str]]:
+        kw = "、".join(keywords or []) or "(无)"
+        journal = journal or "(无)"
+        abstract = (abstract or "").strip() or "(无摘要)"
+        seed = f"{title}\n{abstract[:800]}"
+
+        cats_all = [str(x).strip() for x in (existing_categories or []) if str(x).strip()]
+        candidates = _top_similar_categories(seed, cats_all, k=18)
+
+        base_user = f"标题:{title}\n摘要:{abstract}\n来源:{journal}\n关键词:{kw}"
+
+        wl = self._get_major_whitelist()
+        major_list_block = "\n".join(f"- {m}" for m in wl)
+        major_user = f"{base_user}\n\n【可选大类列表】\n{major_list_block}"
+
+        major_fb = "未分类"
+        major_user = (
+            "# 任务:归类(大类)\n"
+            "从【可选大类列表】中选一个最匹配的大类\n"
+            '输出: {"major":"大类名"}\n'
+            '- 必须从列表选;优先字面匹配,否则语义最接近;无法判断→"未分类";禁列表外值\n\n'
+            + major_user
+        )
+        major_spec = TaskSpec(
+            name="classify_major",
+            agent=self._analysis,
+            parser=self._parse_major_json,
+            max_chars=5200,
+        )
+        major = self._run_task(major_spec, major_user)
+        if not isinstance(major, str) or not major.strip():
+            major = major_fb
+        major = _nearest_major_in(major, wl)
+
+        if not candidates:
+            cat0 = normalize_library_category_display(major)
+            self._record_preference_signals(signal="classify", title=title, major=major, category=cat0, shared=True)
+            return cat0, []
+
+        prefixed = [c for c in candidates if c.startswith(major) or c.split("/")[0] == major]
+        pool = prefixed if len(prefixed) >= 2 else candidates
+        pool_block = "\n".join(f"- {c}" for c in pool[:18])
+
+        fine_user = (
+            "# 任务:归类(路径与标签)\n"
+            "给定大类,从候选已有路径中选择路径,生成标签\n"
+            '输出: {"category":"路径","tags":["标签1",...]}\n'
+            "- category:优先原样选候选;否则「大类/子类」,子类 2~8 个中文字\n"
+            "- tags:3~8 个,单条 ≤24 字,不重复;无法判断可为 []\n"
+            "- 禁含路径非法字符 \\ / : * ? \" < > |\n\n"
+            f"{base_user}\n\n给定大类:{major}\n\n"
+            f"【候选已有路径】(请优先从中复制一条作为 category)\n{pool_block}"
+        )
+        default_cat = normalize_library_category_display(major)
+
+        def _fine_parser(raw: str) -> Optional[Tuple[str, List[str]]]:
+            return self._parse_fine_classify_json(raw, major)
+
+        fine_spec = TaskSpec(
+            name="classify_fine",
+            agent=self._analysis,
+            parser=_fine_parser,
+            max_chars=5500,
+        )
+        out = self._run_task(fine_spec, fine_user)
+        if isinstance(out, tuple) and len(out) == 2:
+            cat, tags = out[0], out[1]
+            cat = normalize_library_category_display(str(cat or "未分类"))
+            if isinstance(tags, list):
+                cleaned: List[str] = []
+                for x in tags:
+                    c = _clean_library_tag(str(x))
+                    if c:
+                        cleaned.append(c)
+                tags = _dedupe_tags(cleaned)
+            else:
+                tags = []
+            self._record_preference_signals(signal="classify", title=title, major=major, category=cat, tags=tags, shared=True)
+            return cat, tags
+        return default_cat, []
+
+    def paper_reader_reply(
+        self,
+        context_block: str,
+        history_lines: str,
+        user_message: str,
+        reader_snap: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[str, List[Any], List[str]]:
+        snap: Dict[str, Any] = dict(reader_snap or {})
+        self._reader_snap = snap
+        reco_pid: Optional[int] = None
+        try:
+            spid = snap.get("paper_id")
+            if spid is not None and int(spid) > 0:
+                reco_pid = int(spid)
+        except (TypeError, ValueError):
+            reco_pid = None
+        try:
+            with self._reader_lookup_lock:
+                self._reader_lookup_buffer.clear()
+            ctx = _prioritize_reader_context(context_block, max_chars=3600)
+            hist = _clip_reader_history((history_lines or "").strip() or "(尚无此前对话)", max_chars=2200)
+            um = _clip(user_message, 900)
+            want_reco, reco_max = parse_reader_recommendation_intent(um)
+            self._reader_last_user_message = um
+
+            try:
+                from ..services.memory.agent_memory import get_agent_memory
+
+                mem_block = get_agent_memory().build_context_block(agent_name="paper_analysis", query=um)
+            except Exception:
+                mem_block = ""
+            user = (
+                (f"【共享/独立记忆】\n{mem_block}\n\n" if mem_block else "")
+                + f"【当前文献材料】\n{ctx}\n\n"
+                + f"【对话历史】\n{hist}\n\n"
+                + f"【用户最新问题】\n{um}"
+            )
+            spec = TaskSpec(
+                name="paper_reader_reply",
+                agent=self._reader,
+                parser=None,
+                max_chars=7200,
+            )
+            out = self._run_task(spec, user)
+            # Clean up mixed tool/user-facing output.
+            if isinstance(out, str) and out.strip():
+                out = self._cleanup_mixed_reader_response(out, um)
+            with self._reader_lookup_lock:
+                raw_pairs = list(self._reader_lookup_buffer)
+                self._reader_lookup_buffer.clear()
+            pairs = self._dedupe_reader_paper_pairs(raw_pairs)
+            rb_pdf = str(snap.get("references_section_raw") or "").strip()
+
+            if (
+                len(rb_pdf) >= 140
+                and not (snap.get("references") or [])
+            ):
+                _thr_bib = 0.48 if want_reco else 0.54
+                pairs = [
+                    (p, s) for p, s in pairs
+                    if s != READER_RELATED_FROM_BIBLIOGRAPHY
+                    or ground_score_paper_vs_reference_blob(p, rb_pdf) >= _thr_bib
+                ]
+            if user_message_may_need_reference_lookup(um) and len(pairs) == 0:
+                try:
+                    fb_max = reco_max if want_reco else 2
+                    resolve_mr = max(fb_max, min(READER_RECOMMEND_MAX_RESULTS, fb_max * 4)) if want_reco else fb_max
+                    extra: List[Any] = []
+                    if snap.get("references"):
+                        refs_full = [str(x).strip() for x in (snap.get("references") or []) if str(x).strip()]
+                        off = self._reader_reco_ref_offset.get(reco_pid, 0) if reco_pid else 0
+                        snap_res: Dict[str, Any] = snap
+                        if want_reco and reco_pid and refs_full and off >= len(refs_full):
+                            off = 0
+                            self._reader_reco_ref_offset[reco_pid] = 0
+                        if want_reco and reco_pid and off > 0 and off < len(refs_full):
+                            snap_res = dict(snap)
+                            snap_res["references"] = refs_full[off:]
+                        extra = resolve_references_via_openalex(
+                            snap_res,
+                            max_results=resolve_mr,
+                            user_hint=_reader_resolve_user_hint(um, snap, want_reco=want_reco),
+                        )
+                        if extra and want_reco and reco_pid:
+                            self._reader_reco_ref_offset[reco_pid] = off + max(1, len(extra))
+                    elif (snap.get("references_section_raw") or "").strip():
+                        from ..services.reader.paper_reader_context import reference_strings_for_resolve_fallback
+
+                        ref_lines = reference_strings_for_resolve_fallback(
+                            str(snap.get("references_section_raw") or "")
+                        )
+                        rs_struct = snap.get("references_from_structure")
+                        if isinstance(rs_struct, list) and rs_struct:
+                            ref_lines = [str(x).strip() for x in rs_struct if str(x).strip()] or ref_lines
+                        ref_core = list(ref_lines)
+                        if ref_core and is_llm_configured():
+                            try:
+                                from ..services.reader.reader_recommend_llm import merge_ref_lines_with_llm_queries
+
+                                merged = merge_ref_lines_with_llm_queries(
+                                    str(snap.get("references_section_raw") or ""),
+                                    snap,
+                                    ref_core,
+                                    max_queries=12,
+                                )
+                                ref_lines = merged if merged else ref_core
+                            except Exception:
+                                logger.debug("merge_llm_ref_queries_failed", exc_info=True)
+                                ref_lines = ref_core
+                        else:
+                            ref_lines = ref_core
+                        if ref_lines:
+                            off = self._reader_reco_ref_offset.get(reco_pid, 0) if reco_pid else 0
+                            if want_reco and reco_pid and off >= len(ref_lines):
+                                off = 0
+                                self._reader_reco_ref_offset[reco_pid] = 0
+                            if want_reco and reco_pid and off > 0:
+                                ref_lines = ref_lines[off:]
+                            if ref_lines:
+                                snap_fb = dict(snap)
+                                snap_fb["references"] = ref_lines
+                                extra = resolve_references_via_openalex(
+                                    snap_fb,
+                                    max_results=resolve_mr,
+                                    user_hint=_reader_resolve_user_hint(um, snap, want_reco=want_reco),
+                                )
+                                rb = str(snap.get("references_section_raw") or "").strip()
+                                if extra and len(rb) >= 140 and not (snap.get("references") or []):
+                                    raw_extra = list(extra)
+
+                                    def _gf(th: float) -> List[Any]:
+                                        return [
+                                            p
+                                            for p in raw_extra
+                                            if ground_score_paper_vs_reference_blob(p, rb) >= th
+                                        ]
+
+                                    extra = _gf(0.54)
+                                    if not extra and want_reco:
+                                        extra = _gf(0.42)
+                                    if not extra and want_reco and raw_extra:
+                                        extra = list(raw_extra)[: max(1, min(len(raw_extra), fb_max))]
+                                if extra and want_reco and reco_pid:
+                                    self._reader_reco_ref_offset[reco_pid] = off + max(1, len(extra))
+                except Exception:
+                    logger.debug("reader_reference_server_fallback_failed", exc_info=True)
+
+            bib_only = (
+                (want_reco or user_message_may_need_reference_lookup(um))
+                and not reader_user_allows_external_paper_lookup(um)
+            )
+            pairs = [(p, s) for p, s in pairs if not paper_matches_reader_snap(snap, p)]
+            if bib_only:
+                pairs = [
+                    (p, s)
+                    for p, s in pairs
+                    if s in (READER_RELATED_FROM_BIBLIOGRAPHY, READER_RELATED_FROM_REF_BLOCK, READER_RELATED_FROM_PRE_SEARCH)
+                ]
+            if want_reco and pairs:
+                try:
+                    if is_llm_configured():
+                        from ..services.reader.reader_recommend_llm import rerank_reader_recommend_pairs_by_llm
+
+                        pairs = rerank_reader_recommend_pairs_by_llm(
+                            snap,
+                            pairs,
+                            user_message=um,
+                            history_lines=hist,
+                            reco_max_hint=reco_max,
+                        )
+                    else:
+                        pairs = rerank_reader_pairs_by_anchor_refs_first(snap, pairs, k=reco_max)
+                except Exception:
+                    logger.debug("reader_llm_recommend_rerank_failed", exc_info=True)
+                    pairs = rerank_reader_pairs_by_anchor_refs_first(snap, pairs, k=reco_max)
+            if pairs:
+                pairs = prioritize_reader_related_pairs_refs_first(pairs)
+            if want_reco and pairs:
+                cap = max(1, min(int(reco_max or 2), READER_RECOMMEND_MAX_RESULTS, len(pairs)))
+                pairs = pairs[:cap]
+            papers = [p for p, _ in pairs]
+            provenances = [s for _, s in pairs]
+            text_out = (str(out) if out is not None else "").strip()
+            if not text_out:
+                if papers:
+                    if snap.get("references_source") == "pdf_section":
+                        text_out = (
+                            "已根据 PDF 参考文献区摘录检索到相关论文,请点击下方「推荐论文」查看条目;"
+                            "如需结合摘要或方法做对比,请告诉我关注点。"
+                        )
+                    else:
+                        text_out = (
+                            "已根据参考文献检索列出相关论文,请点击下方「推荐论文」查看条目;"
+                            "如需结合摘要或方法做对比,请告诉我关注点。"
+                        )
+                elif user_message_may_need_reference_lookup(um) and not (snap.get("references") or []) and not (
+                    snap.get("references_section_raw") or ""
+                ).strip():
+                    text_out = (
+                        "未在库表中找到 references,且当前 PDF 摘录中未能定位到「参考文献 / References」标题后的文本块,"
+                        "无法从原文区检索。若为扫描版、参考文献不在已抽取页范围内,或版式特殊,会出现此情况。"
+                        "可从带参考文献的数据源重新保存该文,或直接粘贴英文题名 / DOI 以便检索。"
+                    )
+                elif user_message_may_need_reference_lookup(um) and (snap.get("references_section_raw") or "").strip():
+                    text_out = (
+                        "上下文中已含 PDF 参考文献区原文,但本轮未产生可展示的检索命中。"
+                        "你可指定要查的一条英文题名或 DOI;或让我从摘录中逐条用检索工具核对。"
+                    )
+                elif user_message_may_need_reference_lookup(um):
+                    text_out = (
+                        "已按库表参考文献题录在 OpenAlex / arXiv / DBLP 中尝试解析,但未找到与题录足够一致的条目"
+                        "(已过滤明显不符的综述/泛命中)。你可粘贴 DOI 或标准英文题名,我会用 reader_paper_lookup 检索并展示在下方列表。"
+                    )
+                else:
+                    text_out = "(本次未收到模型有效正文。请稍后重试,或缩短问题后再次提问。)"
+
+            try:
+                from ..services.memory.agent_memory import get_agent_memory
+
+                am = get_agent_memory()
+                am.add(agent_name="paper_analysis", content=f"用户问:{um}", memory_type="working", importance=0.55, shared=False)
+                am.add(agent_name="paper_analysis", content=f"助手答:{text_out[:240]}", memory_type="working", importance=0.5, shared=False)
+                am.add(agent_name="paper_analysis", content=f"阅读问答要点:{text_out[:180]}", memory_type="working", importance=0.55, shared=True)
+            except Exception:
+                pass
+
+            logger.info("reader_post: text_out_len=%d papers=%d want_reco=%s",
+                        len(text_out or ""), len(papers), want_reco)
+            if text_out and len(text_out) >= 80:
+                try:
+                    prompt = (
+                        "从以下学术助手的回复中,提取被推荐的论文信息。\n"
+                        "返回纯 JSON 数组,每项可含 title(英文题名)和/或 arxiv_id(如 2307.05973)。\n"
+                        '格式:[{"title": "...", "arxiv_id": "..."}, ...]\n'
+                        "若回复未推荐具体论文,返回 []。\n\n"
+                        "回复原文:\n" + text_out[:3000]
+                    )
+                    raw = self.llm.invoke([{"role": "user", "content": prompt}])
+                    llm_text = coerce_hello_agents_llm_output_to_str(raw)
+                    import json as _json
+                    extracted = _json.loads(llm_text.strip().removeprefix("```json").removesuffix("```").strip())
+                    if isinstance(extracted, list) and extracted:
+                        logger.info("reader_llm_extract: got %d papers from LLM", len(extracted))
+                        try:
+                            from app.api.dependencies import get_searcher as _es
+                            from app.services.papers.papers_converters import litpaper_to_api_paper as _ep
+                            ese = _es()
+                            existing_titles = {str(getattr(p, "title", "") or "").strip().lower() for p in papers}
+                            existing_titles.add(str(snap.get("title") or "").strip().lower())
+                            for item in extracted[:6]:
+                                if not isinstance(item, dict):
+                                    continue
+                                title = str(item.get("title") or "").strip()
+                                axid = str(item.get("arxiv_id") or "").strip()
+
+                                if axid and re.match(r"^\d{4}\.\d{4,5}", axid):
+                                    try:
+                                        for fp in (ese.search_arxiv("", max_results=2, arxiv_id_list=axid,
+                                                http_timeout_sec=8, http_max_attempts=1) or []):
+                                            afp = _ep(fp)
+                                            tafp = str(getattr(afp, "title", "") or "").strip().lower()
+                                            if tafp and tafp not in existing_titles:
+                                                existing_titles.add(tafp)
+                                                papers.insert(0, afp)
+                                                provenances.insert(0, READER_RELATED_FROM_PRE_SEARCH)
+                                                logger.info("reader_llm_extract: added by arxiv %s", axid)
+                                    except Exception:
+                                        continue
+
+                                if title and len(title) >= 4:
+                                    try:
+                                        for fp in (ese.search_openalex(title, max_results=2, venue_proceedings_journal=False) or []):
+                                            afp = _ep(fp)
+                                            tafp = str(getattr(afp, "title", "") or "").strip().lower()
+                                            if tafp and tafp not in existing_titles:
+                                                existing_titles.add(tafp)
+                                                papers.insert(0, afp)
+                                                provenances.insert(0, READER_RELATED_FROM_PRE_SEARCH)
+                                                logger.info("reader_llm_extract: added by title %s", tafp[:80])
+                                    except Exception:
+                                        continue
+                        except Exception as e:
+                            logger.warning("reader_llm_extract_search_failed: %s", e)
+                except Exception as e:
+                    logger.warning("reader_llm_extract_failed: %s", e)
+
+            return (text_out, papers, provenances)
+        finally:
+            self._reader_snap = {}

+ 0 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/__init__.py


+ 26 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/knowledge_graph.py

@@ -0,0 +1,26 @@
+
+REL_PROMPT = """# Role: 学术知识图谱抽取专家(高精度、稀疏、低噪)
+
+## Input
+- New_Paper: title, abstract, keywords, venue, year, category;可选 pdf_excerpt、related_work_excerpt。
+- Candidates: 每项 paper_id, title, abstract, keywords, venue, year, category。
+
+## Workflow & Task
+遍历每个 candidate,仅在**强证据**下输出一条单向边;无则 `{"edges": []}`。只输出 JSON,无 Markdown、无解释。
+
+## Relation(优先级高→低,每 target 仅一条)
+improves > extends > uses > compares > surveys > references > dataset_overlap > method_overlap > task_overlap
+- improves / extends / uses / compares:须在 pdf_excerpt 或 abstract(或 related_work_excerpt)中有**显式**论文名/方法名/实验对比(表、baseline)之一;否则禁止输出这四类。
+- surveys:new 为 survey/review/tutorial 且系统讨论 candidate 方向/方法。
+- references:背景或相关工作**明确提及**,不满足更强类。
+- *_overlap:仅核心机制/非通用数据资源/特定任务定义的重合;通用骨干(Transformer/CNN/GNN)、常见 benchmark(ImageNet/CIFAR 等)、泛同领域**不构成** overlap。
+
+## Rules
+- 不确定不输出;禁常识/语义相似/venue推测/embedding相似推测。
+- evidence≤80字;须含来源位置+动作+对象;禁笼统句。
+- score<0.55不输出。锚点:0.55-0.65弱/overlap;0.65-0.8明确提及;0.8-1.0深度继承。无显式锚点≤0.7。
+- 弱边数≤强边数;同簇多弱边只留最优。
+
+## Output Format
+{"edges":[{"target_paper_id":123,"relation":"extends|improves|uses|compares|surveys|references|task_overlap|method_overlap|dataset_overlap","score":0.0,"evidence":""}]}
+"""

+ 36 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/paper_analysis.py

@@ -0,0 +1,36 @@
+
+ANALYSIS_SYSTEM = (
+    "你是学术文献分析助手。只输出合法 JSON,无 Markdown、无解释。\n"
+    "【语言】JSON 内字符串用中文(输入可为英文);必要专有缩写可保留。\n"
+    "【诚信】不得编造输入中未出现或未支撑的事实。\n"
+)
+
+READER_CHAT_SYSTEM = """# Role: 学术阅读助手
+# Output: 中文、分点、短句;结构清晰。**凡对比、枚举、两列对照(数据集/指标/方法等),必须用标准 Markdown 管道表格**,禁止仅用 Tab 或空格对齐的「假表格」。
+## Markdown 格式(最终回答须遵守)
+- 章节标题:用 `##` / `###`,勿用裸「1.」当标题(若需编号列表,用 `1. 文字` 同一行写完要点)。
+- 表格示例(表头与分隔行不可省略):
+```
+| 数据集 | 特点 |
+| --- | --- |
+| CERMEP | 脑部 PET,标准临床数据 |
+| AGIEF | 脑部 PET,不同示踪剂 |
+```
+- 列表:`- ` 或 `1. ` 后紧跟内容;小节之间空一行。
+- 忌整段无换行的大块文字;对比数据优先表格,其次再分点说明。
+# 诚信与引用
+- 禁编造实验/数据/结论;禁凭常识补全未出现内容。
+- 若存在【结构化阅读档案】,优先依据其中的章节、摘要、参考文献条目回答;它是当前 PDF 的解析缓存。
+- 若【当前文献材料】只有标题、作者、venue、arXiv/DOI 等元数据,缺少摘要/PDF 正文,不要写系统性论文讲解;先说明当前材料不足,并建议用户保存/下载 PDF 或稍后重试。
+- 引用标出处(Sec 3.1、Figure 2、Table 4)。
+- 无直接证据时写明「当前文档未包含该信息」。
+# 工具使用(重要)
+- 推荐/查找参考文献 → 调用 ``reader_reference_lookup``
+- PDF 章节浏览 → ``reader_pdf_structure``(不加 focus_section,返回目录)
+- PDF 特定章节全文 → ``reader_pdf_structure``(focus_section="experiment"/"method"/"实验" 或用户指定的章节号如 "4.5")
+- PDF 中特定表格(如 Tab. 3 / Table 4 / 消融实验表)→ ``reader_pdf_table``(table_ref="3" 或 table_ref="ImageNet" 等关键词)
+- 从 PDF 摘录中检索特定题名 → ``reader_paper_lookup``
+- **工具返回的是结构化 JSON 或章节原文,你必须用自然语言将其解读后呈现给用户,严禁直接输出工具返回的原始 JSON/标记。**
+- **当回答中引用到表格但数据不完整时,应主动调用 ``reader_pdf_table`` 获取对应表格。**
+- 推荐论文卡片已自动生成,用序号引用即可,勿编造卡片外的论文。
+"""

+ 89 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/prompts/search.py

@@ -0,0 +1,89 @@
+
+INTENT_LLM_PROMPT = """你是一个学术检索意图解析器。根据用户的自然语言查询,提取结构化的检索参数。只输出 JSON。
+
+## 当前日期
+今天是 {current_date_iso},当前公历 {current_year} 年。
+
+## 核心原则
+- **自主决策**:根据查询内容自主决定来源、排序、关键词策略。
+- **不要把会议名/作者名放入 query 或 keywords**。NIPS → NeurIPS 放入 venues。
+- **方法缩写**:query 填缩写,keywords 补全写法。
+- **中文查询**:核心概念翻译英文为 query,keywords 中英文关键术语。
+- **复杂查询**:支持多条件组合——多会议、多作者、多主题、AND/OR/NOT 逻辑。
+  例:"Kaiming He 在 CVPR 或 ICCV 上关于 diffusion 的论文" →
+  authors=["Kaiming He"], venues=["CVPR", "ICCV"], query="diffusion"
+  例:"异常检测但不是工业缺陷检测" → query="anomaly detection", keywords 不含 industrial/defect
+  例:"2024-2025 年关于 LLM 推理的论文,不考虑 fine-tuning" →
+  query="LLM reasoning", keywords 不含 fine-tuning
+
+## 用户查询
+{user_text}
+
+## 检索偏好
+{profile}
+
+## 字段说明
+
+### query(检索主串)
+纯学术英文短语,直接匹配标题/摘要。不放会议名、作者名、年份。
+- 无实质主题 → 留空 ""
+- 中文 → 翻译核心概念为英文
+- 短缩写 → 保留,keywords 补全
+
+### keywords(3-8个)
+同义词、子任务、方法全称。不含作者/会议名。如有排除项,不含排除词。
+
+### authors / venues / year_from / year_to
+- authors: First Last 格式,支持多人
+- venues: 标准名称(NeurIPS/CVPR/ICCV...),支持多个
+- year_from/year_to: 四位年份。「最新+会议」未写年份 → year_from=year_to={suggested_edition_year}
+
+### sources
+- 经典/标题匹配 → ["arxiv", "dblp", "openalex"]
+- 最新/SOTA → ["arxiv", "dblp", "openalex"]
+- 会议检索(最新/主会、无具体方向)→ ["dblp", "openalex"],query="",keywords=[]
+- 作者检索 → ["dblp", "arxiv"]
+- 不确定 → ["arxiv", "dblp", "openalex"]
+
+### ranking_strategy
+- "date":最新/SOTA(wants_recent=true, sort="date")
+- "relevance":经典/奠基(wants_classic=true, sort="relevance")
+- "hybrid":宽泛主题
+
+### flags
+- main_conference_proceedings_only: 会议检索默认 true
+- max_results: 10–30
+- wants_recent/wants_classic: 按意图
+- use_llm_rank: true
+- use_tavily: 缩写/歧义词/需要 web 锚定时 true
+
+## 输出格式(只输出 JSON)
+{{
+  "search": {{
+    "query": "英文检索短语",
+    "keywords": ["关键词1", "关键词2"],
+    "authors": [],
+    "venues": [],
+    "target_titles": [],
+    "year_from": null,
+    "year_to": null,
+    "sort": "relevance",
+    "max_results": 15,
+    "arxiv_categories": [],
+    "arxiv_id_list": []
+  }},
+  "ranking": {{
+    "use_llm_rank": true,
+    "rerank_recall_max": 24,
+    "rationale": "排序策略说明"
+  }},
+  "flags": {{
+    "sources": ["arxiv", "dblp", "openalex"],
+    "ranking_strategy": "hybrid",
+    "wants_classic": false,
+    "wants_recent": false,
+    "use_tavily": null,
+    "confidence_level": "medium",
+    "main_conference_proceedings_only": false
+  }}
+}}"""

+ 196 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/search_agent.py

@@ -0,0 +1,196 @@
+"""搜索智能体 —— 自然语言意图解析 + 多源论文检索编排."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Optional
+
+from ..core.search.paper_searcher import _sanitize_author_list_for_query
+from ..models.schemas import Paper
+from ..services.llm.llm_service import coerce_hello_agents_llm_output_to_str
+from ..services.llm.agent_config import papergraph_agent_config
+from ..services.search_intent import (
+    apply_llm_intent_hygiene,
+    extract_json_object,
+    finalize_llm_intent,
+    search_intent_from_dict,
+)
+from ..services.search_intent.parsing import _ensure_intent_year_window_ordered
+from ..settings import get_settings
+from .base import BaseAgent
+from .prompts.search import INTENT_LLM_PROMPT as _INTENT_LLM_PROMPT_TEMPLATE
+from .support import SearchExplainer as _SearchExplainer
+from .support.search_models import SearchIntent
+
+logger = logging.getLogger(__name__)
+
+_INTENT_CACHE: dict[tuple[str, str], tuple[float, SearchIntent]] = {}
+_INTENT_CACHE_TTL = 300.0
+
+
+class SearchAgent(BaseAgent):
+    INTENT_LLM_PROMPT = _INTENT_LLM_PROMPT_TEMPLATE
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._intent_parser_agent: Optional[Any] = None
+        self.intent_parser = IntentParser(self)
+        self.explainer = _SearchExplainer()
+
+    def _parse_intent_from_llm_step(
+        self,
+        *,
+        message: str,
+        profile: str,
+        prompt_template: Optional[str] = None,
+        correction_hint: Optional[str] = None,
+    ) -> SearchIntent:
+        msg = (message or "").strip()
+        if not msg:
+            raise ValueError("intent_parse_empty_message")
+        if not self.llm:
+            raise RuntimeError("intent_parse_llm_unavailable")
+
+        from ..services.search_intent.parsing import format_intent_llm_prompt
+
+        tmpl = prompt_template or self.INTENT_LLM_PROMPT
+        prompt = format_intent_llm_prompt(
+            tmpl, msg, profile, correction_hint=(correction_hint or "").strip() or None
+        )
+        from hello_agents import SimpleAgent
+
+        parser_agent = self._intent_parser_agent
+        if parser_agent is None:
+            parser_agent = SimpleAgent(
+                name="intent_parser",
+                llm=self.llm,
+                system_prompt="你是学术检索意图解析器。只输出 JSON,不要解释。",
+                config=papergraph_agent_config(),
+            )
+            self._intent_parser_agent = parser_agent
+
+        resp = parser_agent.run(prompt)
+        text = coerce_hello_agents_llm_output_to_str(resp).strip()
+        payload = extract_json_object(text)
+        if not payload:
+            err: ValueError = ValueError("LLM 未返回有效 JSON")
+            setattr(err, "last_llm_output", text)
+            raise err
+
+        intent = search_intent_from_dict(payload)
+        return finalize_llm_intent(intent, profile)
+
+    def understand_intent(self, message: str, profile: str = "accuracy") -> SearchIntent:
+        return self.intent_parser.parse(message, profile=profile)
+
+    def explain_results(self, intent: SearchIntent, papers: list[Paper], mode: str = "accuracy") -> str:
+        _ = mode
+        return self.explainer.format_search_explanation(intent, papers)
+
+    @staticmethod
+    def _normalize_profile(profile: Optional[str]) -> str:
+        prof = (profile or "accuracy").strip().lower()
+        return prof if prof in ("accuracy", "novelty") else "accuracy"
+
+
+class IntentParser:
+    def __init__(self, agent: SearchAgent) -> None:
+        self._agent = agent
+
+    def parse(self, message: str, profile: str = "accuracy") -> SearchIntent:
+        """解析用户自然语言查询为结构化 SearchIntent,带 LRU 缓存."""
+        msg = (message or "").strip()
+        if not msg:
+            return SearchIntent()
+
+        # 5 分钟内相同查询命中缓存,避免重复调用 LLM
+        cache_key = (msg.lower()[:200], (profile or "accuracy").strip().lower())
+        now = time.time()
+        if cache_key in _INTENT_CACHE:
+            ts, cached = _INTENT_CACHE[cache_key]
+            if now - ts < _INTENT_CACHE_TTL:
+                return cached
+
+        intent = self._parse_with_retry(msg, profile)
+        _INTENT_CACHE[cache_key] = (now, intent)
+        # LRU 淘汰:缓存超过 200 条时删除最旧条目
+        if len(_INTENT_CACHE) > 200:
+            oldest = min(_INTENT_CACHE, key=lambda k: _INTENT_CACHE[k][0])
+            del _INTENT_CACHE[oldest]
+        return intent
+
+    def _parse_with_retry(self, msg: str, profile: str) -> SearchIntent:
+        from ..services.search_intent.parsing import build_intent_retry_correction_hint
+
+        prof = self._agent._normalize_profile(profile)
+        if not self._agent.llm:
+            raise RuntimeError("search_agent_llm_unavailable")
+        s = get_settings()
+        outer_retries = max(0, min(5, int(getattr(s, "papergraph_intent_parse_max_retries", 2) or 2)))
+        correction: str | None = None
+        last_exc: Exception | None = None
+        last_output: str | None = None
+        for attempt in range(outer_retries + 1):
+            try:
+                return self._parse_llm_primary(msg, prof, correction_hint=correction)
+            except Exception as e:
+                last_exc = e
+                last_output = getattr(e, "last_llm_output", None) or last_output
+                logger.warning(
+                    "[SearchAgent] intent parse failed (attempt %d/%d): %s",
+                    attempt + 1,
+                    outer_retries + 1,
+                    e,
+                )
+                if attempt >= outer_retries:
+                    break
+                if "connection error" in str(e or "").lower() or "timed out" in str(e or "").lower():
+                    break
+                correction = build_intent_retry_correction_hint(
+                    e, user_message=msg, last_output=last_output
+                )
+        logger.warning("[SearchAgent] LLM intent parse exhausted retries: %s", last_exc)
+        raise RuntimeError("search_agent_intent_failed") from last_exc
+
+    def _parse_llm_primary(
+        self,
+        msg: str,
+        prof: str,
+        *,
+        correction_hint: str | None = None,
+    ) -> SearchIntent:
+        llm_intent = self._agent._parse_intent_from_llm_step(
+            message=msg,
+            profile=prof,
+            prompt_template=self._agent.INTENT_LLM_PROMPT,
+            correction_hint=correction_hint,
+        )
+        out = finalize_llm_intent(llm_intent, prof)
+        if not (out.query or "").strip() and (out.keywords or []):
+            out.query = (out.keywords[0] or "")[:500]
+        if not (out.query or "").strip() and (out.authors or []):
+            out.query = str(out.authors[0]).strip()[:500]
+        if (
+            not (out.query or "").strip()
+            and not (out.venues or [])
+            and not (out.authors or [])
+            and not (out.arxiv_id_list or [])
+            and not (out.target_titles or [])
+        ):
+            raise ValueError("intent_parse_empty_query")
+        apply_llm_intent_hygiene(out, msg)
+        _ensure_intent_year_window_ordered(out)
+        out.raw_user_message = msg.strip()[:3200]
+        out.authors = _sanitize_author_list_for_query(out.query or "", out.authors or [])
+        return out
+
+
+_search_agent_singleton: Optional[SearchAgent] = None
+
+
+def get_search_agent() -> SearchAgent:
+    global _search_agent_singleton
+    if _search_agent_singleton is None:
+        _search_agent_singleton = SearchAgent()
+    return _search_agent_singleton

+ 11 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/__init__.py

@@ -0,0 +1,11 @@
+__all__ = ["SearchExplainer"]
+
+
+class SearchExplainer:
+    def format_search_explanation(self, intent, papers):
+        if not papers:
+            return "未找到匹配的论文"
+        n = len(papers)
+        years = sorted({p.year for p in papers if p.year}, reverse=True)
+        yr = f" ({years[0]}-{years[-1]})" if len(years) >= 2 else f" ({years[0]})" if years else ""
+        return f"找到 {n} 篇相关论文{yr}"

+ 164 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/paper_analysis_helpers.py

@@ -0,0 +1,164 @@
+"""论文分析辅助函数 —— 方法名提取、缩写识别与文本预处理."""
+
+from __future__ import annotations
+
+import re
+
+from ...core.paper_paths import normalize_library_category_display
+from ...utils import parse_llm_json, tokenize_for_keywords, truncate_text
+
+def clip_text(text: str | None, n: int) -> str:
+    t = (text or "").strip()
+    if len(t) <= n:
+        return t
+    t = t[:n]
+    while t:
+        try:
+            t.encode('utf-8')
+            break
+        except UnicodeEncodeError:
+            t = t[:-1]
+    return t
+
+def dedupe_tags(tags: list[str], max_tags: int = 12) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for t in tags:
+        s = str(t).strip()
+        k = s.lower()
+        if s and k not in seen:
+            out.append(s)
+            seen.add(k)
+        if len(out) >= max_tags:
+            break
+    return out
+
+def clean_library_tag(tag: str) -> str | None:
+    s = str(tag).strip()[:24]
+    if not s:
+        return None
+    if any(c in s for c in '|\\:*?"<>/'):
+        return None
+    return s
+
+def sanitize_major_name(raw: str) -> str | None:
+    t = str(raw or "").strip()
+    if not t or len(t) > 16:
+        return None
+    t = "".join(ch for ch in t if ch not in '/\\:*?"<>|')
+    t = t.strip()
+    if len(t) < 2:
+        return None
+    return t[:10]
+
+def nearest_major_in(raw: str, whitelist: tuple[str, ...]) -> str:
+    s = (raw or "").strip()
+    if "/" not in s:
+        s = normalize_library_category_display(s)
+    if s in whitelist:
+        return s
+    for m in whitelist:
+        if m and (m in s or s in m):
+            return m
+    if "未分类" in whitelist:
+        return "未分类"
+    return whitelist[0] if whitelist else "未分类"
+
+def parse_taxonomy_majors(raw: str) -> list[str | None]:
+    d = parse_llm_json(raw)
+    if not isinstance(d, dict):
+        return None
+    arr = d.get("majors")
+    if not isinstance(arr, list):
+        return None
+    out: list[str] = []
+    seen: set[str] = set()
+    for x in arr:
+        c = sanitize_major_name(str(x))
+        if not c:
+            continue
+        k = c.lower()
+        if k in seen:
+            continue
+        seen.add(k)
+        out.append(c)
+    if "未分类" not in out:
+        out.append("未分类")
+    if len(out) < 4:
+        return None
+    return out[:28]
+
+def top_similar_categories(seed: str, categories: list[str], k: int = 18) -> list[str]:
+    cats = [str(x).strip() for x in categories if str(x).strip()]
+    if len(cats) <= k:
+        return cats
+    tokens = tokenize_for_keywords(seed)
+    if not tokens:
+        return cats[:k]
+    scored: list[tuple[float, str]] = []
+    for c in cats:
+        ct = tokenize_for_keywords(c)
+        inter = len(tokens & ct)
+        if inter == 0:
+            continue
+        union = len(tokens | ct) or 1
+        scored.append((inter / union, c))
+    scored.sort(key=lambda x: x[0], reverse=True)
+    picked = [c for _, c in scored[:k]]
+    if len(picked) < max(8, k // 2):
+        for c in cats:
+            if c not in picked:
+                picked.append(c)
+            if len(picked) >= k:
+                break
+    return picked[:k]
+
+def prioritize_reader_context(block: str, max_chars: int) -> str:
+    b = (block or "").strip()
+    if len(b) <= max_chars:
+        return b
+
+    def grab(label_pat: str, cap: int) -> str:
+        m = re.search(label_pat, b, flags=re.IGNORECASE | re.DOTALL)
+        if not m:
+            return ""
+        seg = (m.group(1) if m.groups() else m.group(0)).strip()
+        return truncate_text(seg, cap, suffix="…")
+
+    abstract = grab(
+        r"(?:摘要|Abstract)\s*[::]?\s*([\s\S]{20,}?)(?=\n\s*(?:相关工作|Related\s*work|关键词|Key\s*words|PDF|【)|\Z)",
+        1400,
+    )
+    related = grab(
+        r"(?:相关工作|Related\s*work)\s*[::]?\s*([\s\S]{20,}?)(?=\n\s*(?:关键词|Key\s*words|参考文献|PDF|【)|\Z)",
+        1200,
+    )
+    artifact = grab(
+        r"(【结构化阅读档案[\s\S]{80,}?)(?=\n【PDF 正文|\Z)",
+        min(2600, max(1400, max_chars - 900)),
+    )
+    ref_blob = grab(
+        r"【参考文献区 PDF 原文摘录[^\n]*\n([\s\S]{10,}?)(?=\n【结构化阅读档案|\n【PDF 正文|\Z)",
+        min(10000, max(2400, max_chars - 1200)),
+    )
+    budget = max_chars - len(abstract) - len(related) - len(artifact) - len(ref_blob) - 30
+    if budget < 400:
+        budget = 400
+    head = truncate_text(b, budget, suffix="…")
+    parts = [p for p in (abstract, related, artifact, ref_blob, head) if p]
+    merged = "\n\n---\n\n".join(parts)
+    return truncate_text(merged, max_chars, suffix="…")
+
+def clip_reader_history(hist: str, max_chars: int) -> str:
+    h = (hist or "").strip()
+    if len(h) <= max_chars:
+        return h
+    lines = h.splitlines()
+    out: list[str] = []
+    size = 0
+    for line in reversed(lines):
+        if size + len(line) + 1 > max_chars:
+            break
+        out.append(line)
+        size += len(line) + 1
+    return "\n".join(reversed(out)) if out else truncate_text(h, max_chars, suffix="…")

+ 337 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_paper_lookup_tool.py

@@ -0,0 +1,337 @@
+"""论文检索工具 —— 在本地文献库中按标题/作者/关键词查找论文."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+from collections.abc import Callable
+
+from hello_agents.tools.base import Tool, ToolParameter
+from hello_agents.tools.response import ToolResponse
+
+from .reader_reference_lookup_tool import (
+    READER_RECOMMEND_MAX_RESULTS, READER_RELATED_FROM_EXTERNAL_QUERY, READER_RELATED_FROM_REF_BLOCK,
+    _norm_doi, _norm_arxiv,
+    resolve_references_via_openalex, score_reference_line_against_hint,
+)
+
+logger = logging.getLogger(__name__)
+
+def _normalize_ref_blob_for_match(blob: str) -> str:
+    u = (blob or "").lower()
+    u = re.sub(r"\s+", " ", u)
+    for _ in range(20):
+        u2 = re.sub(r"([a-z])-\s*([a-z])", r"\1\2", u)
+        if u2 == u:
+            break
+        u = u2
+    return u
+
+def ground_score_paper_vs_reference_blob(ap: Any, ref_blob: str) -> float:
+    raw = _normalize_ref_blob_for_match(ref_blob)
+    if len(raw) < 50:
+        return 1.0
+
+    doi = _norm_doi(str(getattr(ap, "doi", None) or ""))
+    if doi and len(doi) > 6 and doi in raw.replace("https://doi.org/", "").replace("http://dx.doi.org/", ""):
+        return 1.0
+
+    ax = _norm_arxiv(str(getattr(ap, "arxiv_id", None) or ""))
+    if ax and len(ax) >= 8:
+        compact = re.sub(r"[^\d.]", "", raw)
+        if ax in raw or ax in compact:
+            return 1.0
+
+    title = str(getattr(ap, "title", "") or "").strip()
+    if len(title) < 8:
+        return 0.2
+    tn = _normalize_ref_blob_for_match(title)
+    if len(tn) >= 10 and tn in raw:
+        return 1.0
+    if len(tn) >= 22:
+        head = tn[: min(88, len(tn))]
+        if len(head) >= 18 and head in raw:
+            return 0.95
+
+    toks = [w for w in re.findall(r"[a-z0-9]{4,}", tn) if len(w) >= 4]
+    if not toks:
+        return 0.22
+    hits = sum(1 for w in toks if w in raw)
+    ratio = hits / max(1, len(toks))
+    return min(1.0, 0.28 + 0.72 * ratio)
+
+class ReaderPaperLookupTool(Tool):
+
+    def __init__(
+        self,
+        on_papers_found: Callable[[list[Any], str], None],
+        *,
+        get_snap: Callable[[], dict[str, Any]] | None = None,
+    ) -> None:
+        super().__init__(
+            name="reader_paper_lookup",
+            description=(
+                "两类用法:(1) 用户粘贴的库外英文题名/DOI/arXiv:from_pdf_references_section=false,"
+                "按 query 在 OpenAlex 快速检索(1~80 条)。"
+                "(2) 仅有「参考文献区 PDF 原文摘录」、无库表列表时:from_pdf_references_section=true;"
+                "优先使用本轮 ``reader_pdf_structure`` 写入的粗分 ``entries`` 选条;若未调用该工具则退回摘录内粗分。"
+                "再按 query 与题录行匹配排序,对最相关若干条做多源解析。"
+                "若已有库表 references 且用户要求按列表解析,优先 reader_reference_lookup。"
+            ),
+        )
+        self._on_papers_found = on_papers_found
+        self._get_snap = get_snap
+
+    def get_parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="query",
+                type="string",
+                description=(
+                    "from_pdf=false:OpenAlex 检索串(题名片段、作者+年、DOI/arXiv)。"
+                    "from_pdf=true:与用户问题相关的**提示串**(摘录中的英文题名片段、DOI、arXiv、或作者姓+年份),"
+                    "用于在粗分后的参考文献行里排序选条;勿只用两三个泛词。"
+                ),
+                required=True,
+            ),
+            ToolParameter(
+                name="max_results",
+                type="integer",
+                description="最多返回几条(1~80,默认 3)",
+                required=False,
+                default=3,
+            ),
+            ToolParameter(
+                name="from_pdf_references_section",
+                type="boolean",
+                description=(
+                    "true:当前依赖「参考文献区 PDF 原文摘录」;服务端粗分条后按 query 与题录行匹配,再逐条多源解析。"
+                    "false:库外粘贴题名等,直接 OpenAlex。"
+                ),
+                required=False,
+                default=False,
+            ),
+        ]
+
+    def _run_from_pdf_ref_blob(self, q: str, mr: int) -> ToolResponse:
+        if not callable(self._get_snap):
+            return ToolResponse.error(
+                "NO_SNAPSHOT",
+                "reader_paper_lookup:from_pdf 模式需要阅读上下文快照,当前不可用。",
+            )
+        try:
+            snap = dict(self._get_snap() or {})
+        except Exception as exc:
+            logger.debug("reader_paper_lookup_snap_failed", exc_info=exc)
+            return ToolResponse.error("SNAP_FAILED", f"reader_paper_lookup:读取快照失败:{exc}")
+
+        ref_blob = str(snap.get("references_section_raw") or "").strip()
+        rs_pre = snap.get("references_from_structure")
+        has_struct_entries = isinstance(rs_pre, list) and bool(rs_pre)
+        if len(ref_blob) < 80 and not has_struct_entries:
+            return ToolResponse.success(
+                text=(
+                    "reader_paper_lookup:当前无足够长的「参考文献区 PDF 摘录」,且本轮尚未通过 reader_pdf_structure 得到 entries。"
+                    "请先调用 reader_pdf_structure,或确认已打开带 PDF 的文献;也可改用库外题名(from_pdf_references_section=false)。"
+                ),
+            )
+
+        try:
+            from ...services.reader.paper_reader_context import reference_strings_for_resolve_fallback
+        except Exception as exc:
+            logger.warning("reader_paper_lookup_ref_fallback_import_failed", exc_info=exc)
+            return ToolResponse.error("IMPORT_FAILED", f"reader_paper_lookup:摘录分条模块不可用。{exc}")
+
+        lines: list[str] = []
+        rs = snap.get("references_from_structure")
+        if isinstance(rs, list) and rs:
+            lines = [str(x).strip() for x in rs if str(x).strip()]
+        if not lines:
+            lines = reference_strings_for_resolve_fallback(ref_blob)
+        if not lines:
+            return ToolResponse.success(
+                text=(
+                    "reader_paper_lookup:无法得到参考文献粗分条目(可先调 reader_pdf_structure,"
+                    "或提示用户给出 DOI / 标准英文题名走库外检索)。"
+                ),
+            )
+
+        ref_for_ground = ref_blob
+        if len(ref_for_ground) < 80 and lines:
+            ref_for_ground = "\n".join(lines[:80])
+
+        hint = q.strip()
+        ranked = sorted(lines, key=lambda ln: -score_reference_line_against_hint(ln, hint))
+        pool_n = max(mr * 6, 24)
+        snap["references"] = ranked[:pool_n]
+
+        try:
+            api_papers = list(
+                resolve_references_via_openalex(snap, max_results=mr) or []
+            )
+        except Exception as exc:
+            logger.debug("reader_paper_lookup_resolve_failed", exc_info=exc)
+            return ToolResponse.error("RESOLVE_FAILED", f"reader_paper_lookup:按摘录解析失败:{exc}")
+
+        if not api_papers:
+            return ToolResponse.success(
+                text=(
+                    "reader_paper_lookup:按 PDF 摘录分条解析后无通过锚定校验的命中。"
+                    "请把 query 换成摘录中与目标文献更贴近的英文题名片段、DOI 或 arXiv。"
+                ),
+            )
+
+        try:
+            self._on_papers_found(api_papers, READER_RELATED_FROM_REF_BLOCK)
+        except Exception as exc:
+            logger.debug("reader_paper_lookup_callback_failed", exc_info=exc)
+
+        out_lines = [
+            f"reader_paper_lookup:已按 PDF 参考文献摘录匹配并解析 {len(api_papers)} 条(阅读页卡片与参考文献推荐同列):"
+        ]
+        for i, ap in enumerate(api_papers, start=1):
+            t = str(getattr(ap, "title", "") or "").strip() or "(无标题)"
+            y = getattr(ap, "year", None) or "—"
+            ax = getattr(ap, "arxiv_id", None) or "—"
+            doi = getattr(ap, "doi", None) or "—"
+            out_lines.append(f"{i}. {t} | year={y} | arxiv={ax} | doi={doi}")
+        return ToolResponse.success(text="\n".join(out_lines))
+
+    def run(self, parameters: dict[str, Any]) -> ToolResponse:
+        q = str(parameters.get("query") or parameters.get("input") or "").strip()
+        q = re.sub(r"\s+", " ", q)[:160]
+        if len(q) < 4:
+            return ToolResponse.error("INVALID_PARAM", "reader_paper_lookup:query 过短(至少 4 个字符)。")
+
+        try:
+            mr = int(parameters.get("max_results") or 3)
+        except (TypeError, ValueError):
+            mr = 3
+        mr = max(1, min(READER_RECOMMEND_MAX_RESULTS, mr))
+
+        from_ref = parameters.get("from_pdf_references_section")
+        if isinstance(from_ref, str):
+            from_ref = from_ref.strip().lower() in ("1", "true", "yes", "on")
+        else:
+            from_ref = bool(from_ref)
+
+        if from_ref:
+            return self._run_from_pdf_ref_blob(q, mr)
+
+        fetch_n = max(mr * 2, 6)
+
+        try:
+            from ...api.dependencies import get_searcher
+            from ...services.papers.papers_converters import litpaper_to_api_paper
+        except Exception as exc:
+            logger.warning("reader_paper_lookup_import_failed", exc_info=exc)
+            return ToolResponse.error("IMPORT_FAILED", f"reader_paper_lookup:检索模块不可用。{exc}")
+
+        _REF_ARXIV = re.compile(r"(?:arxiv\.org/(?:abs|pdf)/|\barXiv:\s*)([\w.]+)", re.I)
+        _REF_ARXIV_ID_LOOSE = re.compile(r"(?:^|[^\w])arxiv\s*:?\s*(\d{4}\.\d{4,5}(?:v\d+)?)\b", re.I)
+        ax_match = _REF_ARXIV.search(q) or _REF_ARXIV_ID_LOOSE.search(q)
+        ax_id = ""
+        if ax_match:
+            g1 = ax_match.group(1) if ax_match.lastindex else ""
+            ax_id = (g1 or "").strip().replace(".pdf", "")
+            if ax_id and ax_id[-1].isalpha():
+                vi = ax_id.rfind("v")
+                if vi > 8 and vi < len(ax_id) - 1 and ax_id[vi + 1:].isdigit():
+                    ax_id = ax_id[:vi]
+
+        searcher = get_searcher()
+        merged: list[Any] = []
+        seen_titles: set[str] = set()
+
+        def _merge(batch: Any) -> None:
+            for p in batch or []:
+                t = (getattr(p, "title", None) or "").strip().lower()
+                if t and t not in seen_titles:
+                    seen_titles.add(t)
+                    merged.append(p)
+
+        if ax_id and re.match(r"^\d{4}\.\d{4,5}", ax_id):
+            try:
+                _merge(searcher.search_arxiv(
+                    "", max_results=4, arxiv_id_list=ax_id,
+                    http_timeout_sec=10, http_max_attempts=1,
+                ))
+            except Exception as exc:
+                logger.debug("reader_paper_lookup_arxiv_id_failed", exc_info=exc)
+
+        clean_q = re.sub(r"\b(?:arxiv\.org/(?:abs|pdf)/|arxiv\s*:?\s*)\d{4}\.\d{4,5}(?:v\d+)?\b\.?", " ", q, flags=re.I)
+        clean_q = re.sub(r"\s+", " ", clean_q).strip()
+        search_queries: list[str] = []
+        if clean_q and len(clean_q) >= 6:
+            search_queries.append(clean_q[:160])
+        search_queries.append(q[:160])
+        uniq_q = list(dict.fromkeys(search_queries))
+
+        year_filter: int | None = None
+        year_match = re.search(r"\b(19|20)(\d{2})\b", q)
+        if year_match:
+            y = int(year_match.group(0))
+            if 1990 <= y <= 2030:
+                year_filter = y
+
+        author_hint: str | None = None
+        author_match = re.search(r"\(?([A-Z][a-z]{1,20})\s+(?:et\s+al\.?|and)", q)
+        if author_match:
+            author_hint = author_match.group(1).lower()
+
+        for sq in uniq_q[:2]:
+            if len(merged) >= fetch_n:
+                break
+            try:
+                _merge(searcher.search_openalex(
+                    sq, max_results=max(fetch_n - len(merged), 5),
+                    venue_proceedings_journal=False,
+                    year_from=year_filter,
+                    year_to=year_filter,
+                ))
+            except Exception as exc:
+                logger.debug("reader_paper_lookup_openalex_failed", exc_info=exc)
+
+        def _auth_score(p: Any) -> float:
+            s = 0.0
+            if author_hint:
+                auth_names = [str(getattr(a, "name", "") or "").lower() for a in (getattr(p, "authors", None) or [])]
+                if any(author_hint in an for an in auth_names):
+                    s += 2.0
+            if year_filter and getattr(p, "year", None) == year_filter:
+                s += 1.0
+            return s
+
+        merged.sort(key=_auth_score, reverse=True)
+
+        api_papers: list[Any] = []
+        for p in merged:
+            try:
+                api_papers.append(litpaper_to_api_paper(p))
+            except Exception:
+                continue
+        api_papers = api_papers[:mr]
+
+        if not api_papers:
+            return ToolResponse.success(
+                text=(
+                    f"reader_paper_lookup:未命中条目(query={q[:80]})。"
+                    "可换更标准的英文题名或作者+年份重试。"
+                ),
+            )
+
+        try:
+            self._on_papers_found(api_papers, READER_RELATED_FROM_EXTERNAL_QUERY)
+        except Exception as exc:
+            logger.debug("reader_paper_lookup_callback_failed", exc_info=exc)
+
+        lines = [f"reader_paper_lookup:命中 {len(api_papers)} 条(可在最终回答中对应引用):"]
+        for i, ap in enumerate(api_papers, start=1):
+            t = str(getattr(ap, "title", "") or "").strip() or "(无标题)"
+            y = getattr(ap, "year", None) or "—"
+            ax = getattr(ap, "arxiv_id", None) or "—"
+            doi = getattr(ap, "doi", None) or "—"
+            lines.append(f"{i}. {t} | year={y} | arxiv={ax} | doi={doi}")
+        lines.append("以上条目为库外检索结果;用户若只要参考文献区内的论文,应使用 from_pdf_references_section=true。")
+        return ToolResponse.success(text="\n".join(lines))

+ 148 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_pdf_parse_tool.py

@@ -0,0 +1,148 @@
+"""PDF 解析工具 —— MuPDF 正文提取、分段清洗与结构化输出."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+from collections.abc import Callable
+
+from hello_agents.tools.base import Tool, ToolParameter
+from hello_agents.tools.response import ToolResponse
+
+logger = logging.getLogger(__name__)
+
+class ReaderPdfParseTool(Tool):
+
+    def __init__(
+        self,
+        *,
+        get_snap: Callable[[], dict[str, Any]],
+        on_parsed: Callable[[dict[str, Any | None], None]] = None,
+    ) -> None:
+        super().__init__(
+            name="reader_pdf_structure",
+            description=(
+                "解析当前文献 PDF 文本为结构化 JSON。两种模式:"
+                "1) 目录模式:返回 chapters 列表(各章节标题+内容摘要)和 references 条目"
+                "2) 聚焦模式:指定 focus_section 关键词(如 'experiment'、'实验'、'method'),"
+                "返回该章节完整正文(max 24000 字符),适合深入分析特定部分"
+                "若用户要按参考文献检索,用 ``reader_paper_lookup``"
+            ),
+        )
+        self._get_snap = get_snap
+        self._on_parsed = on_parsed
+
+    def get_parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="max_chapter_chars",
+                type="integer",
+                description="每个章节正文在 JSON 中的最大字符数(默认 8000)",
+                required=False,
+                default=8000,
+            ),
+            ToolParameter(
+                name="max_chapters",
+                type="integer",
+                description="最多返回多少个章节块(默认 20)",
+                required=False,
+                default=20,
+            ),
+            ToolParameter(
+                name="focus_section",
+                type="string",
+                description="只提取匹配此关键词的章节完整内容(如 'experiment'、'Sec 4'、'实验'),忽略 max_chapter_chars 截断限制",
+                required=False,
+                default="",
+            ),
+        ]
+
+    def run(self, parameters: dict[str, Any]) -> ToolResponse:
+        try:
+            mcc = int(parameters.get("max_chapter_chars") or 8000)
+        except (TypeError, ValueError):
+            mcc = 8000
+        mcc = max(800, min(20000, mcc))
+        try:
+            mch = int(parameters.get("max_chapters") or 20)
+        except (TypeError, ValueError):
+            mch = 20
+        mch = max(4, min(40, mch))
+        focus = str(parameters.get("focus_section") or "").strip()
+
+        try:
+            snap = self._get_snap() or {}
+        except Exception as exc:
+            logger.debug("reader_pdf_structure_get_snap_failed", exc_info=exc)
+            return ToolResponse.error("SNAP_FAILED", f"reader_pdf_structure:读取快照失败:{exc}")
+
+        merged = str(snap.get("_pdf_merged_for_structure") or "").strip()
+        if len(merged) < 200:
+            return ToolResponse.success(
+                text=(
+                    "reader_pdf_structure:当前无足够长的合并 PDF 文本(需本地 PDF 且阅读上下文已加载)。"
+                    "请确认文献已入库且可抽取文本;扫描版或缺文件时无法解析。"
+                ),
+            )
+
+        try:
+            from ...services.reader.paper_reader_structure import parse_pdf_merged_text_to_json
+        except Exception as exc:
+            logger.warning("reader_pdf_structure_import_failed", exc_info=exc)
+            return ToolResponse.error("IMPORT_FAILED", f"reader_pdf_structure:解析模块不可用。{exc}")
+
+        if focus:
+            obj = parse_pdf_merged_text_to_json(merged, max_chapter_chars=50000, max_chapters=99)
+            chapters = obj.get("chapters") or []
+            matched = None
+            focus_lower = focus.lower()
+            for ch in chapters:
+                h = (ch.get("heading") or "").lower()
+                t = (ch.get("text") or "")[:200].lower()
+                if focus_lower in h or focus_lower in t:
+                    matched = ch
+                    break
+            if not matched:
+                for ch in chapters:
+                    h = (ch.get("heading") or "").lower()
+                    if any(kw in h for kw in focus_lower.split()):
+                        matched = ch
+                        break
+            if matched:
+                heading = matched.get("heading", "(未命名)")
+                text = matched.get("text", "")
+                result = f"## {heading}\n\n{text}"
+                if len(result) > 24000:
+                    result = result[:24000] + "\n\n…(内容过长已截断)"
+                return ToolResponse.success(text=result)
+            else:
+                avail = ", ".join(ch.get("heading","?") for ch in chapters[:12])
+                return ToolResponse.success(
+                    text=f"未找到匹配「{focus}」的章节。可用章节:{avail}\n请用其中某个名称重试。"
+                )
+
+        try:
+            obj = parse_pdf_merged_text_to_json(merged, max_chapter_chars=mcc, max_chapters=mch)
+        except Exception as exc:
+            logger.debug("reader_pdf_structure_parse_failed", exc_info=exc)
+            return ToolResponse.error("PARSE_FAILED", f"reader_pdf_structure:解析失败:{exc}")
+
+        if callable(self._on_parsed):
+            try:
+                self._on_parsed(obj)
+            except Exception as exc:
+                logger.debug("reader_pdf_structure_on_parsed_failed", exc_info=exc)
+
+        try:
+            payload = json.dumps(obj, ensure_ascii=False)
+        except (TypeError, ValueError) as exc:
+            return ToolResponse.error("JSON_FAILED", f"reader_pdf_structure:序列化失败:{exc}")
+
+        cap = 14000
+        if len(payload) > cap:
+            payload = payload[:cap] + "\n…(json 已截断,完整条目见 references.entries 前几项;可减小 max_chapter_chars)"
+
+        return ToolResponse.success(
+            text="reader_pdf_structure:以下为 JSON(可直接阅读 chapters / references):\n" + payload
+        )

+ 312 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_reference_lookup_tool.py

@@ -0,0 +1,312 @@
+"""参考文献工具 —— 解析论文引用列表并尝试在本库/外部检索被引文献."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from typing import Any
+from collections.abc import Callable
+
+from hello_agents.tools.base import Tool, ToolParameter
+from hello_agents.tools.response import ToolResponse
+
+from ...agents.search_agent import SearchIntent
+
+logger = logging.getLogger(__name__)
+
+READER_RECOMMEND_MAX_RESULTS = 80
+READER_RELATED_FROM_BIBLIOGRAPHY = "bibliography"
+READER_RELATED_FROM_EXTERNAL_QUERY = "external_query"
+READER_RELATED_FROM_REF_BLOCK = "ref_block"
+READER_RELATED_FROM_PRE_SEARCH = "pre_search"
+
+def _norm_doi(d: str | None) -> str:
+    if not d:
+        return ""
+    s = str(d).strip().lower()
+    if "doi.org/" in s:
+        s = s.split("doi.org/", 1)[-1]
+    s = s.replace("https://", "").replace("http://", "")
+    s = re.sub(r"^doi:\s*", "", s)
+    return s.strip().rstrip(".,;)")
+
+def _norm_arxiv(a: str | None) -> str:
+    if not a:
+        return ""
+    s = str(a).strip().lower()
+    s = re.sub(r"^arxiv:\s*", "", s)
+    m = re.search(r"(?:arxiv\.org/(?:abs|pdf)/)([\w.]+)", s)
+    if m:
+        s = m.group(1)
+    s = s.replace(".pdf", "")
+    if re.match(r"^\d{4}\.\d{4,5}", s):
+        vi = s.rfind("v")
+        if vi > 8 and vi < len(s) - 1 and s[vi + 1 :].isdigit():
+            s = s[:vi]
+    return s.strip()
+
+def strip_reader_reco_boilerplate(um: str) -> str:
+    import re as _re
+    s = (um or "").strip()
+    for pat in (r"推荐.*?论文", r"找.*?(相关|类似|参考)", r"search.*?(related|similar)", r"find.*?papers"):
+        s = _re.sub(pat, "", s, flags=_re.IGNORECASE).strip()
+    return s
+
+def parse_reader_recommendation_intent(um: str) -> tuple[bool, int]:
+    s = (um or "").strip().lower()
+    want = any(k in s for k in ("推荐", "相关论文", "类似", "related", "similar", "recommend", "找.*论文"))
+
+    import re as _re
+    m = _re.search(r"(\d+)\s*[篇个本]", s)
+    n = int(m.group(1)) if m else (5 if want else 0)
+    return want, max(1, min(n, 20))
+
+def user_message_may_need_reference_lookup(um: str) -> bool:
+    s = (um or "").strip().lower()
+    return any(k in s for k in ("参考", "引用", "reference", "bibliography", "related", "相关", "类似"))
+
+def reader_user_allows_external_paper_lookup(um: str) -> bool:
+    s = (um or "").strip().lower()
+    if any(k in s for k in ("仅参考文献", "只要引用", "only reference", "just bibliography")):
+        return False
+    return True
+
+def rerank_reader_pairs_by_anchor_refs_first(snap: dict, pairs: list, k: int = 5) -> list:
+    title = str(snap.get("title") or "").strip().lower()
+    if not title or not pairs:
+        return pairs[:k]
+    title_tokens = set(re.split(r"\W+", title)) - {""}
+    if not title_tokens:
+        return pairs[:k]
+    def _score(pair):
+        p, src = pair
+        pt = str(getattr(p, "title", "") or "").strip().lower()
+        pt_tokens = set(re.split(r"\W+", pt)) - {""}
+        overlap = len(title_tokens & pt_tokens)
+        bib_bonus = 2 if src in ("bibliography", "ref_block") else 0
+        return (bib_bonus, overlap)
+    return sorted(pairs, key=_score, reverse=True)[:k]
+
+def prioritize_reader_related_pairs_refs_first(pairs: list) -> list:
+    def _priority(pair):
+        _, src = pair
+        if src in ("bibliography", "ref_block", "pre_search"):
+            return 0
+        return 1
+    return sorted(pairs, key=_priority)
+
+def paper_matches_reader_snap(snap: dict[str, Any], p: Any) -> bool:
+    if not snap:
+        return False
+    pid = snap.get("paper_id")
+    if pid and getattr(p, "id", None) is not None:
+        try:
+            if int(getattr(p, "id", 0) or 0) == int(pid):
+                return True
+        except (TypeError, ValueError):
+            pass
+    st_doi = _norm_doi(str(snap.get("doi") or ""))
+    pt_doi = _norm_doi(str(getattr(p, "doi", None) or ""))
+    if st_doi and pt_doi and st_doi == pt_doi:
+        return True
+    sa = _norm_arxiv(str(snap.get("arxiv_id") or ""))
+    pa = _norm_arxiv(str(getattr(p, "arxiv_id", None) or ""))
+    if sa and pa and sa == pa:
+        return True
+    st = str(snap.get("title") or "").strip().lower()
+    pt = str(getattr(p, "title", "") or "").strip().lower()
+    _noise = re.compile(r"[\s\-_:,\.\(\)\[\]]+")
+    stn = _noise.sub(" ", st).strip()
+    ptn = _noise.sub(" ", pt).strip()
+    if len(stn) >= 14 and len(ptn) >= 14:
+        if stn == ptn or (stn in ptn or ptn in stn):
+            return True
+        from difflib import SequenceMatcher
+
+        if SequenceMatcher(None, stn, ptn).ratio() >= 0.75:
+            return True
+    return False
+
+class ReaderReferenceLookupTool(Tool):
+
+    def __init__(
+        self,
+        get_snap: Callable[[], dict[str, Any]],
+        on_papers_found: Callable[[list[Any], str], None],
+        get_user_message: Callable[[], str],
+    ) -> None:
+        super().__init__(
+            name="reader_reference_lookup",
+            description=(
+                "从当前文献的参考文献中提取搜索查询,检索相关论文。"
+                "接受一条参考文献文本(或用户提示),调用 search_papers() 检索并返回可点击的论文结果。"
+            ),
+        )
+        self._get_snap = get_snap
+        self._on_papers_found = on_papers_found
+        self._get_user_message = get_user_message
+
+    def get_parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="max_results",
+                type="integer",
+                description="最多返回几条(1~80,默认 5)",
+                required=False,
+                default=5,
+            ),
+            ToolParameter(
+                name="reference_focus",
+                type="string",
+                description=(
+                    "可选。用户感兴趣的引用方向或文本片段,直接用作文本检索查询。"
+                ),
+                required=False,
+                default="",
+            ),
+        ]
+
+    def run(self, parameters: dict[str, Any]) -> ToolResponse:
+        snap = {}
+        try:
+            snap = self._get_snap() or {}
+        except Exception as exc:
+            logger.debug("reader_reference_lookup_get_snap_failed", exc_info=exc)
+            return ToolResponse.error("SNAP_FAILED", f"reader_reference_lookup: cannot read snap. {exc}")
+
+        refs = [str(x).strip() for x in (snap.get("references") or []) if str(x).strip()]
+        raw = (snap.get("references_section_raw") or "").strip()
+        if not refs:
+            if raw:
+                return ToolResponse.success(
+                    text=(
+                        "reader_reference_lookup: current paper has no parsed references list; "
+                        "the PDF references section text is available. "
+                        "Extract English titles, DOIs, or arXiv IDs from it and call reader_paper_lookup."
+                    ),
+                )
+            return ToolResponse.success(
+                text=(
+                    "reader_reference_lookup: no references available (empty list, no PDF section text)."
+                ),
+            )
+
+        try:
+            mr = int(parameters.get("max_results") or 5)
+        except (TypeError, ValueError):
+            mr = 5
+        mr = max(1, min(READER_RECOMMEND_MAX_RESULTS, mr))
+
+        focus = str(parameters.get("reference_focus") or "").strip()
+        um = ""
+        try:
+            um = (self._get_user_message() or "").strip()
+        except Exception as exc:
+            logger.debug("reader_reference_lookup_get_user_message_failed", exc_info=exc)
+
+        query = (focus or um or (refs[0] if refs else "")).strip()[:300]
+        if not query or len(query) < 4:
+            return ToolResponse.success(
+                text="reader_reference_lookup: no usable query text. Provide a title, DOI, or arXiv ID.",
+            )
+
+        try:
+            from ...api.dependencies import get_searcher
+            from ...services.papers.papers_converters import litpaper_to_api_paper
+            from ...services.retrieval.search_pipeline import run_search_pipeline_async
+            from ...services.retrieval.search_plan import ResolvedSearchPlan
+        except Exception as exc:
+            logger.warning("reader_reference_lookup_import_failed", exc_info=exc)
+            return ToolResponse.error("IMPORT_FAILED", f"import failed: {exc}")
+
+        searcher = get_searcher()
+        intent = SearchIntent(
+            query=query,
+            sources=["arxiv", "openalex"],
+            max_results=mr,
+            sort="relevance",
+        )
+        plan = ResolvedSearchPlan.from_search_intent(intent)
+
+        try:
+            pip = asyncio.run(
+                run_search_pipeline_async(
+                    searcher=searcher,
+                    plan=plan,
+                    max_results=mr,
+                )
+            )
+        except Exception as exc:
+            logger.debug("reader_reference_lookup_search_failed", exc_info=exc)
+            return ToolResponse.error("SEARCH_FAILED", f"search failed: {exc}")
+
+        collected = [litpaper_to_api_paper(rp.paper) for rp in (pip.ranked or [])[:mr]]
+        if not collected:
+            return ToolResponse.success(
+                text=(
+                    f"reader_reference_lookup: no results for query [{query[:80]}]. "
+                    "Try a more specific English title, DOI, or arXiv ID."
+                ),
+            )
+
+        try:
+            self._on_papers_found(collected, READER_RELATED_FROM_BIBLIOGRAPHY)
+        except Exception as exc:
+            logger.debug("reader_reference_lookup_callback_failed", exc_info=exc)
+
+        lines = [
+            f"reader_reference_lookup: {len(collected)} papers found from references:"
+        ]
+        for i, ap in enumerate(collected, start=1):
+            t = str(getattr(ap, "title", "") or "").strip() or "(no title)"
+            y = getattr(ap, "year", None) or "-"
+            lines.append(f"{i}. {t} | year={y}")
+        lines.append("Refer to items by number or short title above.")
+        return ToolResponse.success(text="\n".join(lines))
+
+def score_reference_line_against_hint(ln: str, hint: str) -> float:
+    import re as _re
+    h = (hint or "").lower()
+    l = (ln or "").lower()
+    if not h or not l:
+        return 0.0
+    h_tokens = set(_re.split(r"\W+", h)) - {""}
+    l_tokens = set(_re.split(r"\W+", l)) - {""}
+    if not h_tokens or not l_tokens:
+        return 0.0
+    return len(h_tokens & l_tokens) / max(len(h_tokens), len(l_tokens))
+
+def resolve_references_via_openalex(
+    snap: dict[str, Any], *, max_results: int = 5
+) -> list[Any]:
+    refs = snap.get("references") or []
+    if not refs:
+        return []
+    from app.api.dependencies import get_searcher
+    from app.services.papers.papers_converters import litpaper_to_api_paper
+    from app.utils.async_sync import run_coroutine_sync
+    searcher = get_searcher()
+    results: list[Any] = []
+    seen: set[str] = set()
+    for ref in refs[:max_results * 3]:
+        q = str(ref or "").strip()[:200]
+        if not q or q.lower() in seen:
+            continue
+        seen.add(q.lower())
+        try:
+            papers = run_coroutine_sync(
+                searcher.search_async(q, sources=["openalex", "arxiv"], max_results=2, http_timeout_sec=5),
+                op_name="resolve_refs",
+            )
+            for p in (papers or []):
+                api_p = litpaper_to_api_paper(p)
+                t = str(getattr(api_p, "title", "") or "").strip().lower()
+                if t and t not in seen:
+                    seen.add(t)
+                    results.append(api_p)
+        except Exception:
+            continue
+        if len(results) >= max_results:
+            break
+    return results[:max_results]

+ 140 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/reader_table_tool.py

@@ -0,0 +1,140 @@
+"""表格提取工具 —— PDF 表格检测、解析与上下文关联查询."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Callable
+
+from hello_agents.tools.base import Tool, ToolParameter
+from hello_agents.tools.response import ToolResponse
+
+logger = logging.getLogger(__name__)
+
+
+class ReaderTableTool(Tool):
+    """Extract a specific table from the current paper's PDF."""
+
+    def __init__(self, *, get_snap: Callable[[], dict[str, Any]]) -> None:
+        super().__init__(
+            name="reader_pdf_table",
+            description=(
+                "获取当前论文 PDF 中的指定表格内容。当用户询问表格数据或论文提到 'Tab. 3'/'Table 4' 时调用。"
+                "输入表号(如 '3'、'4')或关键词(如 'ImageNet'、'ablation'),返回对应表格的 Markdown 内容。"
+            ),
+        )
+        self._get_snap = get_snap
+
+    def get_parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="table_ref",
+                type="string",
+                description="表格编号(如 '3')或关键词(如 'ImageNet'、'ablation')",
+                required=True,
+            ),
+        ]
+
+    def run(self, parameters: dict[str, Any]) -> ToolResponse:
+        ref = str(parameters.get("table_ref") or "").strip()
+        if not ref:
+            return ToolResponse.error("NO_REF", "请指定表格编号或关键词,如 table_ref='3'")
+
+        try:
+            snap = self._get_snap() or {}
+        except Exception as exc:
+            return ToolResponse.error("SNAP_FAILED", f"读取快照失败:{exc}")
+
+        pdf_path = str(snap.get("_pdf_abspath") or "").strip()
+        if not pdf_path:
+            merged = str(snap.get("_pdf_merged_for_structure") or "").strip()
+            if not merged or len(merged) < 200:
+                return ToolResponse.success(
+                    text="当前文献无可用 PDF。请先确认论文已保存且 PDF 已下载。"
+                )
+            tables = self._extract_tables_from_text(merged)
+        else:
+            try:
+                from ...services.reader.paper_reader_context import extract_pdf_tables_markdown
+                tables_md = extract_pdf_tables_markdown(pdf_path)
+                if tables_md:
+                    tables = self._parse_table_blocks(tables_md)
+                else:
+                    merged = str(snap.get("_pdf_merged_for_structure") or "").strip()
+                    tables = self._extract_tables_from_text(merged) if merged else []
+            except Exception:
+                merged = str(snap.get("_pdf_merged_for_structure") or "").strip()
+                tables = self._extract_tables_from_text(merged) if merged else []
+
+        if not tables:
+            return ToolResponse.success(
+                text="未能从 PDF 中提取到表格。表格可能为图片格式或 PDF 文本提取不完整。"
+            )
+
+        matched = self._find_table(tables, ref)
+        if not matched:
+            available = [t.get("label", f"表{i+1}") for i, t in enumerate(tables[:8])]
+            return ToolResponse.success(
+                text=f"未找到匹配 '{ref}' 的表格。可用表格:{', '.join(available)}"
+            )
+
+        result = f"## {matched['label']}\n\n{matched['content']}"
+        return ToolResponse.success(text=result)
+
+    @staticmethod
+    def _parse_table_blocks(md: str) -> list[dict[str, Any]]:
+        tables: list[dict[str, Any]] = []
+        blocks = re.split(r"\n(?=##|\|)", md)
+        for i, block in enumerate(blocks):
+            block = block.strip()
+            if not block or "|" not in block:
+                continue
+            label = f"表{i + 1}"
+            m = re.match(r"^##\s*(.*)", block)
+            if m:
+                label = m.group(1).strip()
+                block = block[m.end():].strip()
+            if block.startswith("|"):
+                tables.append({"label": label, "content": block[:3000]})
+        return tables
+
+    @staticmethod
+    def _extract_tables_from_text(text: str) -> list[dict[str, Any]]:
+        """Extract Markdown-style table blocks from merged text."""
+        tables: list[dict[str, Any]] = []
+        # Find table-like patterns: lines starting with | that have multiple columns
+        for m in re.finditer(
+            r"(?:^|\n)((?:Table\s*\d+[^\n]*|Tab\.\s*\d+[^\n]*))?\s*\n?"
+            r"((?:\|[^\n]+\|\n){2,})",
+            text, re.MULTILINE,
+        ):
+            caption = (m.group(1) or "").strip()
+            body = m.group(2).strip()
+            if body.count("|") >= 3:
+                label = caption if caption else f"表{len(tables) + 1}"
+                tables.append({"label": label, "content": body[:3000]})
+        return tables
+
+    @staticmethod
+    def _find_table(tables: list[dict[str, Any]], ref: str) -> dict[str, Any] | None:
+        ref_lower = ref.strip().lower()
+        # Exact number match: "3" → "Table 3", "Tab. 3", "表3"
+        if ref_lower.isdigit():
+            patterns = [
+                rf"\b(?:table|tab\.?|表)\s*{ref_lower}\b",
+                rf"^{ref_lower}[\.\)]",
+            ]
+            for pat in patterns:
+                for t in tables:
+                    if re.search(pat, t["label"], re.I):
+                        return t
+                for t in tables:
+                    if re.search(pat, t["content"], re.I):
+                        return t
+
+        # Keyword match in label or first rows
+        for t in tables:
+            blob = (t["label"] + " " + t["content"][:500]).lower()
+            if ref_lower in blob:
+                return t
+        return None

+ 43 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/agents/support/search_models.py

@@ -0,0 +1,43 @@
+"""搜索意图数据模型 —— SearchIntent 及检索参数的数据结构定义."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+@dataclass
+class SearchIntent:
+    query: str = ""
+    raw_user_message: str = ""
+    keywords: list[str] = field(default_factory=list)
+    authors: list[str] = field(default_factory=list)
+    venues: list[str] = field(default_factory=list)
+    year_from: int | None = None
+    year_to: int | None = None
+    sort: str = "relevance"
+    max_results: int = 10
+    target_titles: list[str] = field(default_factory=list)
+    target_authors: list[str] = field(default_factory=list)
+    arxiv_categories: list[str] = field(default_factory=list)
+    arxiv_id_list: list[str] = field(default_factory=list)
+
+    use_llm_rank: bool = True
+    rerank_recall_max: int = 24
+    ranking_rationale: str = ""
+
+    is_short_acronym: bool = False
+    wants_classic: bool = False
+    wants_recent: bool = False
+
+    use_tavily: bool | None = None
+
+    confidence_level: str = "medium"
+    search_strategy: str = "hybrid"
+    sources: list[str] = field(default_factory=list)
+    ranking_strategy: str = "hybrid"
+
+    main_conference_proceedings_only: bool = False
+
+
+__all__ = [
+    "SearchIntent",
+]

+ 46 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/dependencies.py

@@ -0,0 +1,46 @@
+"""API 依赖注入 —— SearchAgent、PaperSearcher 等单例的获取与缓存."""
+
+from __future__ import annotations
+
+import os
+import threading
+
+from app.core.search import PaperSearcher
+from app.core.storage import PaperDatabase
+
+from ..settings import get_settings
+
+_singleton_lock = threading.Lock()
+_searcher: PaperSearcher | None = None
+_database: PaperDatabase | None = None
+
+def get_searcher() -> PaperSearcher:
+    global _searcher
+    if _searcher is not None:
+        return _searcher
+    with _singleton_lock:
+        if _searcher is not None:
+            return _searcher
+        s = get_settings()
+        _searcher = PaperSearcher(
+            email=(s.openalex_mailto or s.ncbi_email) or None,
+            api_key=s.ncbi_api_key or None,
+            download_dir=s.downloads_dir,
+            httpx_trust_env=s.papergraph_httpx_trust_env,
+        )
+        return _searcher
+
+def get_database() -> PaperDatabase:
+    global _database
+    if _database is not None:
+        return _database
+    with _singleton_lock:
+        if _database is not None:
+            return _database
+        s = get_settings()
+        db_path = os.path.join(s.data_dir, "papers.db")
+        _database = PaperDatabase(db_path)
+        return _database
+
+def get_db_path() -> str:
+    return get_database().db_path

+ 137 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/main.py

@@ -0,0 +1,137 @@
+"""PaperGraph 主应用入口 —— FastAPI 实例、中间件、路由挂载与生命周期管理."""
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from ..settings import configure_logging, get_settings, print_config, validate_config
+from ..services.graph.kg_relations import get_kg_metrics
+from .routes import paper_routes, paper_reader_routes, search_routes
+
+settings = get_settings()
+logger = logging.getLogger(__name__)
+
+class _MeaningfulActivityMiddleware(BaseHTTPMiddleware):
+
+    async def dispatch(self, request: Request, call_next):
+        response = await call_next(request)
+        try:
+            from ..services.daily.daily_auto_refresh import touch_meaningful_activity_if_needed
+
+            touch_meaningful_activity_if_needed(request.app, request.method, request.url.path)
+        except Exception:
+            pass
+        return response
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    configure_logging(settings.log_level)
+    logger.info("%s", "=" * 60)
+    logger.info("📚 %s v%s", settings.app_name, settings.app_version)
+    logger.info("%s", "=" * 60)
+
+    app.state.last_meaningful_activity_monotonic = None
+    daily_refresh_task: asyncio.Task | None = None
+
+    print_config()
+
+    try:
+        validate_config()
+        logger.info("✅ 配置验证通过")
+    except ValueError as e:
+        logger.error("❌ 配置验证失败: %s", e)
+        raise
+
+    try:
+        from ..services.daily.daily_auto_refresh import spawn_daily_auto_refresh
+
+        daily_refresh_task = spawn_daily_auto_refresh(app)
+    except Exception as exc:
+        logger.warning("每日论文后台自动刷新任务未启动: %s", exc)
+
+    logger.info("%s", "=" * 60)
+
+    yield
+
+    logger.info("%s", "=" * 60)
+    logger.info("👋 应用正在关闭...")
+    if daily_refresh_task is not None:
+        daily_refresh_task.cancel()
+        try:
+            await daily_refresh_task
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            logger.debug("每日论文后台任务结束异常", exc_info=True)
+    logger.info("%s", "=" * 60)
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description=settings.description,
+    docs_url=None,
+    redoc_url=None,
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.get_cors_origins_list(),
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.add_middleware(_MeaningfulActivityMiddleware)
+
+app.include_router(paper_routes.router, prefix="/api")
+app.include_router(paper_reader_routes.router, prefix="/api")
+app.include_router(search_routes.router, prefix="/api")
+
+@app.get("/")
+async def root():
+    return {
+        "name": settings.app_name,
+        "version": settings.app_version,
+        "status": "running",
+        "docs_enabled": False,
+    }
+
+@app.get("/health")
+async def health():
+    return {
+        "status": "healthy",
+        "service": settings.app_name,
+        "version": settings.app_version,
+        "kg_metrics": get_kg_metrics(),
+    }
+
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    if isinstance(exc, HTTPException):
+        return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+    logger.exception(
+        "未处理异常: %s %s",
+        request.method,
+        request.url.path,
+        exc_info=exc,
+    )
+    return JSONResponse(
+        status_code=500,
+        content={"success": False, "message": str(exc)},
+    )
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "app.api.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.debug,
+    )

+ 64 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/repo.py

@@ -0,0 +1,64 @@
+"""仓库信息查询 —— 基于仓库地址识别论文元数据的辅助 API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class RelationRepository:
+    db_path: str
+
+    def fetch_relation_rows(
+        self, *, focus_id: int | None, paper_ids: set[int | None], limit: int,
+    ) -> list[tuple[int, int, str, float, str]]:
+        import sqlite3
+        if int(limit) <= 0:
+            return []
+        rows: list[tuple[int, int, str, float, str]] = []
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.cursor()
+            if focus_id is not None:
+                cur.execute(
+                    """SELECT source_paper_id, target_paper_id, relation, score, evidence
+                    FROM paper_relations
+                    WHERE source_paper_id = ? OR target_paper_id = ?
+                    ORDER BY score DESC, updated_at DESC LIMIT ?""",
+                    (int(focus_id), int(focus_id), int(limit)),
+                )
+            else:
+                ids = sorted(int(x) for x in (paper_ids or set()) if int(x) > 0)
+                if not ids:
+                    return []
+                cur.execute("CREATE TEMP TABLE IF NOT EXISTS _kg_pid (id INTEGER PRIMARY KEY)")
+                cur.execute("DELETE FROM _kg_pid")
+                cur.executemany("INSERT OR IGNORE INTO _kg_pid(id) VALUES (?)", [(i,) for i in ids])
+                cur.execute(
+                    """SELECT pr.source_paper_id, pr.target_paper_id, pr.relation, pr.score, pr.evidence
+                    FROM paper_relations pr
+                    INNER JOIN _kg_pid a ON a.id = pr.source_paper_id
+                    INNER JOIN _kg_pid b ON b.id = pr.target_paper_id
+                    ORDER BY pr.score DESC, pr.updated_at DESC LIMIT ?""",
+                    (int(limit),),
+                )
+            for sid, tid, rel, score, evidence in cur.fetchall():
+                rows.append((int(sid), int(tid), str(rel or ""), float(score or 0.0), str(evidence or "")))
+        return rows
+
+    def papers_minimal_by_ids(self, paper_ids: set[int]) -> dict[int, tuple[str, int | None, str | None]]:
+        import sqlite3
+        ids = sorted(int(x) for x in paper_ids if int(x) > 0)
+        if not ids:
+            return {}
+        out: dict[int, tuple[str, int | None, str | None]] = {}
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.cursor()
+            cur.execute("CREATE TEMP TABLE IF NOT EXISTS _kg_meta (id INTEGER PRIMARY KEY)")
+            cur.execute("DELETE FROM _kg_meta")
+            cur.executemany("INSERT OR IGNORE INTO _kg_meta(id) VALUES (?)", [(i,) for i in ids])
+            cur.execute(
+                """SELECT p.id, p.title, p.year, p.category
+                FROM papers p INNER JOIN _kg_meta t ON t.id = p.id"""
+            )
+            for rid, title, year, cat in cur.fetchall():
+                out[int(rid)] = (str(title or ""), int(year) if year is not None else None, str(cat) if cat else None)
+        return out

+ 5 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/__init__.py

@@ -0,0 +1,5 @@
+from . import paper_reader as paper_reader_routes
+from . import papers as paper_routes
+from . import search as search_routes
+
+__all__ = ["paper_reader_routes", "paper_routes", "search_routes"]

+ 85 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/paper_reader.py

@@ -0,0 +1,85 @@
+"""论文阅读助手 API 路由 —— PDF 打开、AI 导读、对话问答与阅读历史."""
+
+import logging
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query
+
+from ...models.schemas import (
+    PaperReaderChatRequest,
+    PaperReaderChatResponse,
+    PaperReaderHistoryItem,
+    PaperReaderHistoryResponse,
+    PaperReaderOpeningRequest,
+    PaperReaderOpeningResponse,
+)
+from ..dependencies import get_database
+from ...utils.common import safe_http_500
+from ...services.reader.paper_reader_service import PaperReaderService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ai", tags=["AI 分析"])
+
+def get_paper_reader_service() -> PaperReaderService:
+    db = get_database()
+    return PaperReaderService(db=db)
+
+# 首次打开论文 → 生成 AI 导读和结构化摘要
+@router.post("/paper-reader/opening", response_model=PaperReaderOpeningResponse)
+async def paper_reader_opening(
+    body: PaperReaderOpeningRequest,
+    background_tasks: BackgroundTasks,
+    service: PaperReaderService = Depends(get_paper_reader_service),
+):
+    try:
+        result = await service.get_opening(paper_id=int(body.paper_id), background_tasks=background_tasks)
+        return PaperReaderOpeningResponse(success=True, **result)
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise safe_http_500("paper_reader_opening", e)
+
+# 论文对话:基于 PDF 全文 + 参考文献上下文的问答
+@router.post("/paper-reader/chat", response_model=PaperReaderChatResponse)
+async def paper_reader_chat(
+    body: PaperReaderChatRequest,
+    background_tasks: BackgroundTasks,
+    service: PaperReaderService = Depends(get_paper_reader_service),
+):
+    try:
+        out = await service.process_chat(
+            paper_id=int(body.paper_id),
+            messages=list(body.messages or []),
+            user_message=body.user_message,
+            background_tasks=background_tasks,
+        )
+        return PaperReaderChatResponse(
+            success=True,
+            reply=str(out.get("reply") or "").strip(),
+            pdf_parsing=bool(out.get("pdf_parsing", False)),
+            related_papers=list(out.get("related_papers") or []),
+            related_hints=list(out.get("related_hints") or []),
+            kg_edges=list(out.get("kg_edges") or []),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise safe_http_500("paper_reader_chat", e)
+
+@router.get("/paper-reader/history", response_model=PaperReaderHistoryResponse)
+async def paper_reader_history(
+    paper_id: int = Query(..., ge=1),
+    limit: int = Query(default=200, ge=1, le=1000),
+    service: PaperReaderService = Depends(get_paper_reader_service),
+):
+    try:
+        turns = await service.get_history(paper_id=int(paper_id), limit=int(limit))
+        return PaperReaderHistoryResponse(
+            success=True,
+            paper_id=int(paper_id),
+            turns=[PaperReaderHistoryItem(**t) for t in turns],
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise safe_http_500("paper_reader_history", e)

+ 218 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/papers.py

@@ -0,0 +1,218 @@
+"""论文库管理 API 路由 —— 论文保存、删除、搜索、分类与阅读状态管理."""
+
+import logging
+
+
+import anyio
+from fastapi import APIRouter, Query, BackgroundTasks, Request, Depends, HTTPException
+from ...utils.common import safe_http_500
+from ...models.schemas import (
+    DeletePaperResponse,
+    LibraryCategoriesResponse,
+    Paper,
+    PapersResponse,
+    ReadStatus,
+    SavePapersRequest,
+    SavePapersResponse,
+    LibraryGraphResponse,
+    UpdatePaperRequest,
+    UpdatePaperResponse,
+    DailyPapersRequest,
+    DailyPapersResponse,
+    DailyRecommendFeedbackRequest,
+    DailyRecommendFeedbackResponse,
+    ReadingCalendarItem,
+    ReadingLogRequest,
+    ReadingCalendarResponse,
+)
+
+from ...services.papers.papers_converters import api_paper_to_litpaper, litpaper_to_api_paper
+
+from ...services.papers.papers_helpers import (
+    daily_paper_identity_sig,
+)
+from ...services.graph.graph_service import build_library_graph
+from ...services.papers.papers_library_service import (
+    build_library_pdf_response_service,
+    delete_paper_by_id,
+    get_library as get_library_service,
+    get_paper_by_id,
+    list_library_categories as list_library_categories_service,
+    save_papers as save_papers_service,
+    update_paper_by_id,
+)
+from ...services.daily.daily_auto_refresh import get_daily_compute_lock
+from ...services.daily.daily_service import (
+    compute_daily_papers as compute_daily_service,
+    read_daily_cached_or_204 as get_daily_cached_or_204_service,
+    record_user_daily_feedback as record_daily_feedback_service,
+)
+from ...settings import get_settings
+from ..dependencies import get_database, get_db_path, get_searcher
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/papers", tags=["文献管理"])
+
+class DailyServices:
+    def __init__(self, db_path=Depends(get_db_path), searcher=Depends(get_searcher)):
+        self.db_path = db_path
+        self.searcher = searcher
+
+# ── 知识图谱 ──
+@router.get("/graph/library", response_model=LibraryGraphResponse)
+def library_graph(
+    limit: int = Query(default=200, ge=1, le=1000),
+    category: str | None = Query(default=None),
+    include_authors: bool = Query(default=False),
+    include_keywords: bool = Query(default=False),
+    relation_edge_limit: int = Query(default=400, ge=0, le=5000),
+    focus_paper_id: int | None = Query(default=None, ge=1),
+    db=Depends(get_database),
+):
+    try:
+        return build_library_graph(
+            db=db,
+            limit=int(limit),
+            category=category,
+            include_authors=bool(include_authors),
+            include_keywords=bool(include_keywords),
+            relation_edge_limit=int(relation_edge_limit),
+            focus_paper_id=focus_paper_id,
+        )
+    except Exception as e:
+        logger.exception("GET /api/papers/graph/library 失败")
+        raise HTTPException(status_code=500, detail=str(e))
+
+# ── 文献库管理 ──
+@router.get("/library/categories", response_model=LibraryCategoriesResponse)
+def list_library_categories(db=Depends(get_database)):
+    return list_library_categories_service(db=db)
+
+@router.get("/library", response_model=PapersResponse)
+def get_library(
+    limit: int = Query(default=50, ge=1, le=1000),
+    offset: int = Query(default=0, ge=0),
+    q: str | None = None,
+    year_from: int | None = None,
+    year_to: int | None = None,
+    read_status: ReadStatus | None = None,
+    tags: str | None = Query(default=None, description="逗号分隔标签"),
+    category: str | None = Query(default=None, description="领域筛选"),
+    db=Depends(get_database),
+):
+    return get_library_service(
+        db=db,
+        litpaper_to_api_paper_fn=litpaper_to_api_paper,
+        limit=limit,
+        offset=offset,
+        q=q,
+        year_from=year_from,
+        year_to=year_to,
+        read_status=read_status,
+        tags=tags,
+        category=category,
+    )
+
+# ── 论文保存 ──
+@router.post("/save", response_model=SavePapersResponse)
+async def save_papers(
+    request: SavePapersRequest,
+    background_tasks: BackgroundTasks,
+    db=Depends(get_database),
+):
+    try:
+        return await save_papers_service(
+            db=db,
+            request=request,
+            background_tasks=background_tasks,
+            api_to_lit_fn=api_paper_to_litpaper,
+            litpaper_to_api_paper_fn=litpaper_to_api_paper,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise safe_http_500("save_papers", e)
+
+# ── 每日推荐 ──
+@router.get("/daily")
+async def daily_papers_get(db_path=Depends(get_db_path)):
+    logger.info("HTTP GET /api/papers/daily")
+    return await get_daily_cached_or_204_service(db_path=db_path)
+
+@router.post("/daily", response_model=DailyPapersResponse)
+async def daily_papers(
+    body: DailyPapersRequest,
+    services: DailyServices = Depends(),
+    settings=Depends(get_settings),
+):
+    logger.info(
+        "HTTP POST /api/papers/daily force_refresh=%s",
+        getattr(body, "force_refresh", False),
+    )
+    lock = get_daily_compute_lock()
+    async with lock:
+        try:
+            with anyio.fail_after(180.0):
+                resp = await compute_daily_service(
+                body=body, db_path=services.db_path, searcher=services.searcher,
+                daily_paper_identity_sig_fn=daily_paper_identity_sig,
+                daily_arxiv_cs_categories=settings.get_daily_arxiv_cs_categories(),
+                papergraph_to_api_fn=litpaper_to_api_paper, logger=logger,
+            )
+        except TimeoutError:
+            err_msg = "每日论文计算超时(>180s),请稍后重试或缩小范围"
+            raise HTTPException(status_code=504, detail=err_msg)
+        except HTTPException:
+            raise
+        except Exception as e:
+            raise safe_http_500("daily_papers", e)
+        else:
+            return resp
+
+# ── 阅读日志 ──
+@router.post("/reading/log")
+def log_reading_session(body: ReadingLogRequest, db_path=Depends(get_db_path)):
+    from ...services.reading_log.log import append_session
+    append_session(db_path, paper_id=int(body.paper_id), duration_sec=int(body.duration_sec),
+                   client_ts=int(body.client_ts) if body.client_ts is not None else None)
+    return {"success": True}
+
+@router.get("/reading/calendar", response_model=ReadingCalendarResponse)
+def reading_calendar(days: int = Query(default=180, ge=7, le=366), db_path=Depends(get_db_path)):
+    from ...services.reading_log.log import list_daily_aggregate
+    items = list_daily_aggregate(db_path, days=int(days))
+    return ReadingCalendarResponse(success=True, days=int(days),
+                                   items=[ReadingCalendarItem(**x) for x in items])
+
+@router.get("/{paper_id}/library-pdf")
+async def get_paper_library_pdf(
+    paper_id: int,
+    request: Request,
+    db_path=Depends(get_db_path),
+):
+    return build_library_pdf_response_service(paper_id=paper_id, request=request, db_path=db_path, logger_obj=logger)
+
+@router.get("/{paper_id}", response_model=Paper)
+def get_paper(paper_id: int, db=Depends(get_database)):
+    return get_paper_by_id(db=db, paper_id=paper_id, litpaper_to_api_paper_fn=litpaper_to_api_paper)
+
+@router.put("/{paper_id}", response_model=UpdatePaperResponse)
+def update_paper(paper_id: int, body: UpdatePaperRequest, db=Depends(get_database)):
+    return update_paper_by_id(db=db, paper_id=paper_id, body=body)
+
+@router.delete("/{paper_id}", response_model=DeletePaperResponse)
+def delete_paper(paper_id: int, db=Depends(get_database)):
+    return delete_paper_by_id(db=db, paper_id=paper_id)
+
+@router.post("/daily/feedback", response_model=DailyRecommendFeedbackResponse)
+async def record_daily_recommend_feedback(
+    body: DailyRecommendFeedbackRequest,
+    db_path=Depends(get_db_path),
+):
+    try:
+        return await record_daily_feedback_service(body=body, db_path=db_path)
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise safe_http_500("record_daily_recommend_feedback", e)

+ 284 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/routes/search.py

@@ -0,0 +1,284 @@
+"""智能搜索 API 路由 —— 自然语言论文搜索与 SSE 流式响应."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+import anyio
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from ...agents.search_agent import SearchAgent, SearchIntent, get_search_agent
+from ...api.dependencies import get_searcher
+from ...api.search_route_support import (
+    ToolCallInfo,
+    last_pipeline_tool_error,
+    normalize_tool_calls,
+    track_tool_call,
+    user_facing_error_message,
+)
+from ...models.schemas import Paper
+from ...services.papers.papers_converters import litpapers_to_api_papers
+from ...services.retrieval.search_plan import ResolvedSearchPlan
+from ...services.retrieval.search_pipeline import run_search_pipeline_async
+from ..tool_events import ToolCallTracker, sse_pack
+
+router = APIRouter(prefix="/papers", tags=["智能搜索"])
+logger = logging.getLogger(__name__)
+
+_SSE_QUEUE_SIZE = 128
+_SEARCH_AGENT_WALL_SEC = max(
+    120.0,
+    min(900.0, float(os.getenv("PAPERGRAPH_SEARCH_AGENT_WALL_SEC") or 420.0)),
+)
+_SEARCH_AGENT_INIT_SEC = 25.0
+_PREFIX_CONFLICT_MARKER = "为您找到"
+
+
+class SearchAgentMessage(BaseModel):
+    message: str = Field(..., min_length=1, max_length=2000, description="用户搜索需求")
+    mode: str = Field(default="accuracy", description="accuracy=准确性优先, novelty=新颖性优先")
+    use_tavily: bool = Field(default=False, description="是否使用 Tavily 预搜索")
+    history: List[Dict[str, str]] = Field(default_factory=list, description="对话历史")
+
+
+class SearchAgentResponse(BaseModel):
+    success: bool
+    response: str
+    search_params: Optional[Dict[str, Any]] = None
+    tool_calls: List[ToolCallInfo] = Field(default_factory=list)
+    papers: List[Paper] = Field(default_factory=list)
+    total: int = 0
+    message: Optional[str] = None
+
+
+def _search_params_from_intent(intent: SearchIntent, **extra: Any) -> Dict[str, Any]:
+    yf, yt = intent.year_from, intent.year_to
+    if isinstance(yf, int) and isinstance(yt, int) and yf > yt:
+        yf, yt = yt, yf
+    out: Dict[str, Any] = {
+        "query": intent.query,
+        "keywords": intent.keywords,
+        "authors": getattr(intent, "authors", []) or [],
+        "arxiv_id_list": getattr(intent, "arxiv_id_list", []) or [],
+        "venues": intent.venues,
+        "year_from": yf,
+        "year_to": yt,
+        "sort": intent.sort,
+        "use_llm_rank": intent.use_llm_rank,
+        "rerank_recall_max": intent.rerank_recall_max,
+        "ranking_rationale": intent.ranking_rationale or None,
+    }
+    out.update(extra)
+    return out
+
+
+def _generate_suggestions(intent: SearchIntent, papers: List[Paper]) -> List[str]:
+    if len(papers) < 5:
+        return [f"扩大搜索:尝试「{intent.query}」而不限定会议"]
+    return []
+
+
+def _strip_conflicting_search_summary_prefix(text: str) -> str:
+    t = (text or "").strip()
+    if not t or _PREFIX_CONFLICT_MARKER not in t:
+        return t
+    return t[: t.find(_PREFIX_CONFLICT_MARKER)].rstrip()
+
+
+def _explanation_with_suggestions(
+    agent: SearchAgent,
+    intent: SearchIntent,
+    papers: List[Paper],
+    profile_mode: str,
+    *,
+    prefix_plain: str = "",
+) -> str:
+    base = _strip_conflicting_search_summary_prefix((prefix_plain or "").strip())
+    expl = agent.explain_results(intent, papers, profile_mode)
+    explanation = base + "\n\n---\n\n" + expl if (papers and base) else (base or expl)
+    if papers:
+        sug = _generate_suggestions(intent, papers)
+        if sug:
+            explanation += "\n\n🔍 **您可以这样优化**:\n" + "".join(
+                f"{i}. {s}\n" for i, s in enumerate(sug, 1)
+            )
+    return explanation
+
+
+def _error_response(msg: str) -> SearchAgentResponse:
+    return SearchAgentResponse(
+        success=False,
+        response=user_facing_error_message(msg),
+        message=msg,
+    )
+
+
+async def _prepare_agent_and_query(request: SearchAgentMessage) -> tuple[SearchAgent, str]:
+    try:
+        with anyio.fail_after(_SEARCH_AGENT_INIT_SEC):
+            agent = await anyio.to_thread.run_sync(get_search_agent)
+    except TimeoutError as exc:
+        logger.warning("search-agent init timeout after %.0fs", _SEARCH_AGENT_INIT_SEC, exc_info=exc)
+        raise HTTPException(status_code=504, detail="search_agent_init_timeout") from exc
+    return agent, (request.message or "").strip()
+
+
+async def _run_search_agent_core(
+    *,
+    agent: SearchAgent,
+    request: SearchAgentMessage,
+    merged_query: str,
+    searcher: Any,
+) -> SearchAgentResponse:
+    tool_calls: List[ToolCallInfo] = []
+
+    intent = agent.understand_intent(merged_query, request.mode)
+    with track_tool_call(tool_calls, "understand_intent", {"query": merged_query}) as tc:
+        tc.result_summary = f"sort={intent.sort}, venues={intent.venues}, yf={intent.year_from}, kw={intent.keywords}"
+
+    plan = ResolvedSearchPlan.from_search_intent(intent)
+    with track_tool_call(tool_calls, "search_pipeline", {"query": intent.query or merged_query}) as tc:
+        tc.result_summary = "intent→SearchPlan→pipeline"
+        mr = int(getattr(plan, "max_results", None) or intent.max_results or 10)
+        pip = await run_search_pipeline_async(searcher=searcher, plan=plan, max_results=mr)
+        tc.result_summary = f"ranked={len(pip.ranked or [])}"
+
+    papers = litpapers_to_api_papers(rp.paper for rp in (pip.ranked or []))
+    prefix = f"为您找到 {len(papers)} 篇论文。" if papers else "未找到相关论文。"
+
+    pipeline_err = last_pipeline_tool_error(tool_calls)
+    if not papers and pipeline_err:
+        body = (
+            "主检索未成功返回论文(多源召回或精排阶段出错),与「数据库里确实没有匹配文献」不同。\n\n"
+            f"**错误摘要**:{pipeline_err}\n\n"
+            "建议稍后重试,或略微改写查询;若频繁出现请查看服务端日志。"
+        )
+        return SearchAgentResponse(
+            success=False,
+            response=body,
+            search_params=_search_params_from_intent(intent, mode=request.mode),
+            tool_calls=normalize_tool_calls(tool_calls),
+            papers=[],
+            total=0,
+            message="search_pipeline_error",
+        )
+
+    body = _explanation_with_suggestions(agent, intent, papers, request.mode, prefix_plain=prefix)
+    return SearchAgentResponse(
+        success=True,
+        response=body,
+        search_params=_search_params_from_intent(intent, mode=request.mode),
+        tool_calls=normalize_tool_calls(tool_calls),
+        papers=papers,
+        total=len(papers),
+    )
+
+
+async def _search_agent_impl(request: SearchAgentMessage, searcher: Any):
+    try:
+        agent, merged_query = await _prepare_agent_and_query(request)
+        resp = await asyncio.wait_for(
+            _run_search_agent_core(
+                agent=agent,
+                request=request,
+                merged_query=merged_query,
+                searcher=searcher,
+            ),
+            timeout=_SEARCH_AGENT_WALL_SEC,
+        )
+        return resp, None
+    except asyncio.TimeoutError as exc:
+        logger.warning("search-agent timeout after %.0fs", _SEARCH_AGENT_WALL_SEC, exc_info=exc)
+        return _error_response("search_agent_timeout"), HTTPException(status_code=504, detail="search_agent_timeout")
+    except HTTPException as e:
+        return _error_response(str(e.detail or "search_agent_http_error")), e
+    except Exception:
+        logger.exception("search-agent unexpected failure")
+        return _error_response("search_agent_internal_error"), None
+
+
+@router.post("/search-agent/stream")
+async def search_agent_chat_stream(
+    request: SearchAgentMessage,
+    searcher=Depends(get_searcher),
+):
+    async def gen():
+        # SSE 流式生成器:通过 anyio 内存通道实现事件驱动的流式推送
+        send, recv = anyio.create_memory_object_stream(_SSE_QUEUE_SIZE)
+        tracker = ToolCallTracker(sink=lambda ev: send.send_nowait(ev))
+        tracker.emit("status", {"message": "search-agent 已接入,开始处理"})
+
+        async def run_once() -> SearchAgentResponse:
+            tracker.emit("status", {"message": f"初始化 SearchAgent(mode={request.mode})"})
+            t0 = time.time()
+            tracker.emit("status", {"message": "正在检索论文…"})
+            resp, exc = await _search_agent_impl(request, searcher)
+            if exc:
+                code = (
+                    str(exc.detail or "search_agent_http_error")
+                    if isinstance(exc, HTTPException)
+                    else "search_agent_internal_error"
+                )
+                msg = user_facing_error_message(code)
+                tracker.emit("error", {"message": msg})
+                if not isinstance(exc, HTTPException):
+                    logger.exception("search-agent stream run loop failed")
+                return _error_response(msg)
+            tracker.emit(
+                "final",
+                {"elapsed_ms": int((time.time() - t0) * 1000), "success": bool(resp.success)},
+            )
+            return resp
+
+        box: Dict[str, Any] = {"resp": None}
+        cancelled_exc = anyio.get_cancelled_exc_class()
+        try:
+            async with anyio.create_task_group() as tg:
+
+                async def _run() -> None:
+                    try:
+                        box["resp"] = await run_once()
+                    finally:
+                        try:
+                            await send.aclose()
+                        except Exception:
+                            pass
+
+                tg.start_soon(_run)
+
+                async for ev in recv:
+                    try:
+                        yield sse_pack(ev)
+                    except (cancelled_exc, asyncio.CancelledError):
+                        return
+                    except Exception:
+                        return
+        except (cancelled_exc, asyncio.CancelledError):
+            return
+        finally:
+            try:
+                await recv.aclose()
+            except Exception:
+                pass
+
+        resp: Optional[SearchAgentResponse] = box.get("resp")
+        if resp is None:
+            resp = _error_response("search_agent_stream_incomplete")
+            tracker.emit("error", {"message": resp.message or "search_agent_stream_incomplete"})
+        yield sse_pack({"type": "final_result", "result": resp.model_dump(mode="json")})
+
+    return StreamingResponse(
+        gen(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache, no-transform",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )

+ 81 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/search_route_support.py

@@ -0,0 +1,81 @@
+"""搜索路由辅助 —— 工具调用追踪、错误解析与用户友好消息构建."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Iterator, List, Optional
+
+from pydantic import BaseModel
+
+SEARCH_AGENT_ERROR_MESSAGES: dict[str, str] = {
+    "search_agent_init_timeout": "检索服务初始化超时,请稍后重试。",
+    "search_agent_timeout": "检索超时,请稍后重试或缩短描述。",
+    "search_agent_intent_failed": "暂时无法理解检索意图(LLM 不可用或返回异常),请改写为更具体的会议/主题/年份。",
+    "search_agent_internal_error": "检索服务内部错误,请查看后端日志或稍后重试。",
+    "search_agent_stream_incomplete": "检索流未正常结束,请重试。",
+    "search_agent_llm_unavailable": "未配置 LLM,无法解析复杂检索意图;请配置 API Key 或使用更明确的会议+年份查询。",
+}
+
+
+class ToolCallInfo(BaseModel):
+    name: str
+    status: str
+    params: Optional[dict[str, Any]] = None
+    result_summary: Optional[str] = None
+
+
+def user_facing_error_message(code: str) -> str:
+    return SEARCH_AGENT_ERROR_MESSAGES.get(code, code or "search_agent_error")
+
+
+@contextmanager
+def track_tool_call(
+    tool_calls: List[ToolCallInfo],
+    name: str,
+    params: Optional[dict[str, Any]] = None,
+) -> Iterator[ToolCallInfo]:
+    tc = ToolCallInfo(name=name, status="running", params=params)
+    tool_calls.append(tc)
+    try:
+        yield tc
+        if tc.status == "running":
+            tc.status = "success"
+    except Exception as e:
+        tc.status = "error"
+        if not tc.result_summary:
+            tc.result_summary = f"执行失败: {str(e)[:120]}"
+        raise
+
+
+def normalize_tool_calls(tool_calls: List[Any]) -> List[ToolCallInfo]:
+    safe_calls: List[ToolCallInfo] = []
+    for x in tool_calls:
+        if isinstance(x, ToolCallInfo):
+            safe_calls.append(x)
+        elif isinstance(x, dict):
+            try:
+                safe_calls.append(ToolCallInfo(**x))
+            except Exception:
+                safe_calls.append(
+                    ToolCallInfo(
+                        name="tool_call",
+                        status="error",
+                        result_summary=str(x)[:200],
+                    )
+                )
+        else:
+            safe_calls.append(
+                ToolCallInfo(name="tool_call", status="error", result_summary=str(x)[:200])
+            )
+    return safe_calls
+
+
+def last_pipeline_tool_error(tool_calls: List[ToolCallInfo]) -> Optional[str]:
+    for tc in reversed(tool_calls or []):
+        if getattr(tc, "name", None) != "search_pipeline":
+            continue
+        if getattr(tc, "status", None) != "error":
+            continue
+        s = (getattr(tc, "result_summary", None) or "").strip()
+        return s or "search_pipeline_error"
+    return None

+ 35 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/api/tool_events.py

@@ -0,0 +1,35 @@
+"""SSE 事件推送 —— 工具调用追踪器与 SSE 消息编解码."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+@dataclass
+class ToolEvent:
+    ts_ms: int
+    type: str
+    payload: Dict[str, Any]
+
+class ToolCallTracker:
+
+    def __init__(self, sink: Optional[Callable[[Dict[str, Any]], None]] = None) -> None:
+        self._events: List[ToolEvent] = []
+        self._sink = sink
+
+    def emit(self, type: str, payload: Dict[str, Any]) -> None:
+        ev = ToolEvent(ts_ms=int(time.time() * 1000), type=type, payload=dict(payload or {}))
+        self._events.append(ev)
+        if self._sink:
+            self._sink(self.to_wire(ev))
+
+    def to_wire(self, ev: ToolEvent) -> Dict[str, Any]:
+        return {"type": ev.type, "ts_ms": ev.ts_ms, **(ev.payload or {})}
+
+    def snapshot(self) -> List[Dict[str, Any]]:
+        return [self.to_wire(e) for e in self._events]
+
+def sse_pack(event: Dict[str, Any]) -> str:
+    return "data: " + json.dumps(event, ensure_ascii=False, default=str) + "\n\n"

+ 1 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

+ 41 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/author.py

@@ -0,0 +1,41 @@
+"""作者领域模型 —— Author 数据类及其序列化/反序列化."""
+
+from dataclasses import dataclass
+from typing import Any
+
+@dataclass
+class Author:
+    name: str
+    affiliation: str | None = None
+    email: str | None = None
+    orcid: str | None = None
+
+    db_id: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "name": self.name,
+            "affiliation": self.affiliation,
+            "email": self.email,
+            "orcid": self.orcid,
+        }
+        if self.db_id is not None:
+            d["db_id"] = int(self.db_id)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Author":
+        raw_id = data.get("db_id")
+        db_id: int | None = None
+        if raw_id is not None:
+            try:
+                db_id = int(raw_id)
+            except Exception:
+                db_id = None
+        return cls(
+            name=data.get("name", ""),
+            affiliation=data.get("affiliation"),
+            email=data.get("email"),
+            orcid=data.get("orcid"),
+            db_id=db_id,
+        )

+ 145 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/conference_landing_pdf.py

@@ -0,0 +1,145 @@
+"""会议官网 PDF 探测 —— 从会议 landing page 提取论文 PDF 链接."""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urljoin, urlparse
+
+import requests
+
+_ABS_PDF_HTTP = re.compile(r"https?://[^'\"<>\s]+?\.pdf", re.I)
+
+_HREF_PDF = re.compile(
+    r'(?:href|src|data-href)\s*=\s*(["\'])([^"\']+?\.pdf)\1',
+    re.I,
+)
+
+_META_CONTENT_PDF = re.compile(
+    r'<meta[^>]+(?:property|name)\s*=\s*["\']?(?:pdf_url|citation_pdf_url|og:pdf_url)["\']?[^>]+content\s*=\s*["\']([^"\']+?\.pdf)["\']',
+    re.I | re.S,
+)
+_META_CONTENT_PDF_ALT = re.compile(
+    r'<meta[^>]+content\s*=\s*["\']([^"\']+?\.pdf)["\'][^>]+(?:property|name)\s*=\s*["\']?(?:pdf_url|citation_pdf_url|og:pdf_url)["\']?',
+    re.I | re.S,
+)
+_GENERIC_CONTENT_PDF = re.compile(
+    r'content\s*=\s*["\']([^"\']+?\.pdf)["\']',
+    re.I,
+)
+
+_OJS_VIEW_OR_DL = re.compile(
+    r'(?:href|data-href)\s*=\s*(["\'])([^"\']*?/article/(?:view|download)/\d+/\d+[^"\']*)\1',
+    re.I,
+)
+
+def _is_relative_pdf_path(rel: str) -> bool:
+    s = (rel or "").strip()
+    if not s or s.startswith("//"):
+        return False
+    low = s.lower()
+    return not low.startswith(("http://", "https://", "javascript:", "mailto:", "#"))
+
+def _same_site_pdf_preference(base_url: str, candidates: list[str]) -> str | None:
+    if not candidates:
+        return None
+    try:
+        base_host = (urlparse(base_url).netloc or "").lower().removeprefix("www.")
+    except ValueError:
+        base_host = ""
+    for c in candidates:
+        try:
+            h = (urlparse(c).netloc or "").lower().removeprefix("www.")
+            if base_host and h == base_host:
+                return c
+        except ValueError:
+            continue
+    return candidates[0]
+
+def fetch_pdf_url_from_html_page(
+    url: str,
+    email: str = "",
+    timeout: int = 35,
+    max_bytes: int = 800_000,
+) -> str | None:
+    u0 = (url or "").strip()
+    if not u0.lower().startswith(("http://", "https://")):
+        return None
+
+    mail = (email or "").strip()
+    ua = f"PaperGraph/0.3 (mailto:{mail})" if mail else "PaperGraph/0.3"
+    headers = {"User-Agent": ua}
+
+    try:
+        with requests.get(u0, timeout=timeout, headers=headers, stream=True) as r:
+            if r.status_code != 200:
+                return None
+            buf = bytearray()
+            for chunk in r.iter_content(65536):
+                if chunk:
+                    buf.extend(chunk)
+                    if len(buf) >= max_bytes:
+                        break
+        text = bytes(buf).decode("utf-8", errors="ignore")
+    except (requests.RequestException, OSError, ValueError):
+        return None
+
+    found: list[str] = []
+    seen: set[str] = set()
+
+    def _add_url(raw_url: str) -> None:
+        s = raw_url.strip().split("?", 1)[0]
+        if not s.lower().endswith(".pdf"):
+            return
+        low = s.lower()
+        if low not in seen:
+            seen.add(low)
+            found.append(s)
+
+    try:
+        for m in _ABS_PDF_HTTP.finditer(text):
+            _add_url(m.group(0))
+
+        for m in _HREF_PDF.finditer(text):
+            path = m.group(2).strip()
+            if path.startswith("//"):
+                _add_url(urljoin(u0, path))
+            elif path.lower().startswith(("http://", "https://")):
+                _add_url(path)
+            elif _is_relative_pdf_path(path):
+                _add_url(urljoin(u0, path))
+
+        # Meta content="..." PDF URLs (e.g., NeurIPS proceedings abstract pages)
+        if not found:
+            for pat in (_META_CONTENT_PDF, _META_CONTENT_PDF_ALT):
+                for m in pat.finditer(text):
+                    path = m.group(1).strip()
+                    if path.lower().startswith(("http://", "https://")):
+                        _add_url(path)
+                    elif _is_relative_pdf_path(path):
+                        _add_url(urljoin(u0, path))
+
+        if not found:
+            for m in _GENERIC_CONTENT_PDF.finditer(text):
+                path = m.group(1).strip()
+                if path.lower().startswith(("http://", "https://")):
+                    _add_url(path)
+                elif _is_relative_pdf_path(path):
+                    _add_url(urljoin(u0, path))
+
+        if not found:
+            for m in _OJS_VIEW_OR_DL.finditer(text):
+                path = m.group(2).strip()
+                abs_u = urljoin(u0, path)
+                if "/article/view/" in abs_u:
+                    abs_u = abs_u.replace("/article/view/", "/article/download/", 1)
+                low = abs_u.lower()
+                if "citationstylelanguage" in low or low in seen:
+                    continue
+                seen.add(low)
+                found.append(abs_u)
+    except re.error:
+        return None
+
+    if not found:
+        return None
+    return _same_site_pdf_preference(u0, found)

+ 174 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/paper.py

@@ -0,0 +1,174 @@
+"""论文领域模型 —— Paper 数据类及其序列化/反序列化."""
+
+from dataclasses import dataclass, field
+from typing import Any
+from datetime import datetime
+
+from .author import Author
+
+@dataclass
+class Paper:
+    title: str
+    authors: list[Author] = field(default_factory=list)
+    abstract: str | None = None
+    doi: str | None = None
+    pmid: str | None = None
+    arxiv_id: str | None = None
+    pmc_id: str | None = None
+    journal: str | None = None
+    venue_type: str | None = None
+    year: int | None = None
+    volume: str | None = None
+    issue: str | None = None
+    pages: str | None = None
+    publisher: str | None = None
+    pdf_url: str | None = None
+    source_url: str | None = None
+    local_pdf_path: str | None = None
+    keywords: list[str] = field(default_factory=list)
+    mesh_terms: list[str] = field(default_factory=list)
+    references: list[str] = field(default_factory=list)
+    citations: int = 0
+    source: str = "unknown"
+    relevance_score: int = 0
+    notes: str | None = None
+    tags: list[str] = field(default_factory=list)
+    category: str | None = None
+    rating: int | None = None
+    read_status: str = "unread"
+    importance: str = "normal"
+    id: int | None = None
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "authors": [a.to_dict() if hasattr(a, "to_dict") else {"name": str(a)} for a in self.authors],
+            "abstract": self.abstract,
+            "doi": self.doi,
+            "pmid": self.pmid,
+            "arxiv_id": self.arxiv_id,
+            "pmc_id": self.pmc_id,
+            "journal": self.journal,
+            "venue_type": self.venue_type,
+            "year": self.year,
+            "volume": self.volume,
+            "issue": self.issue,
+            "pages": self.pages,
+            "publisher": self.publisher,
+            "pdf_url": self.pdf_url,
+            "source_url": self.source_url,
+            "local_pdf_path": self.local_pdf_path,
+            "keywords": self.keywords,
+            "mesh_terms": self.mesh_terms,
+            "references": self.references,
+            "citations": self.citations,
+            "source": self.source,
+            "relevance_score": self.relevance_score,
+            "notes": self.notes,
+            "tags": self.tags,
+            "category": self.category,
+            "rating": self.rating,
+            "read_status": self.read_status,
+            "importance": self.importance,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Paper":
+        def _parse_dt(val: Any) -> datetime | None:
+            if val is None:
+                return None
+            if isinstance(val, datetime):
+                return val
+            if isinstance(val, str):
+                s = val.strip()
+                if not s:
+                    return None
+                try:
+                    if s.endswith("Z"):
+                        s = s[:-1] + "+00:00"
+                    return datetime.fromisoformat(s)
+                except ValueError:
+                    return None
+            return None
+
+        def _safe_int(val: Any, default: int = 0) -> int:
+            if val is None:
+                return default
+            if isinstance(val, bool):
+                return int(val)
+            if isinstance(val, int):
+                return val
+            try:
+                return int(float(val))
+            except (TypeError, ValueError):
+                return default
+
+        def _safe_year(val: Any) -> int | None:
+            if val is None or val == "":
+                return None
+            y = _safe_int(val, -1)
+            return y if 1000 <= y <= 3000 else None
+
+        def _str_list(val: Any) -> list[str]:
+            if not isinstance(val, list):
+                return []
+            out: list[str] = []
+            for x in val:
+                if x is None:
+                    continue
+                if isinstance(x, str):
+                    t = x.strip()
+                    if t:
+                        out.append(t)
+                else:
+                    out.append(str(x).strip())
+            return out
+
+        def _safe_id(val: Any) -> int | None:
+            if val is None or val == "":
+                return None
+            i = _safe_int(val, -1)
+            return i if i >= 0 else None
+
+        created_at = _parse_dt(data.get("created_at"))
+        updated_at = _parse_dt(data.get("updated_at"))
+
+        return cls(
+            title=data.get("title", ""),
+            authors=[Author.from_dict(a) if isinstance(a, dict) else Author(name=str(a)) for a in data.get("authors", [])],
+            abstract=data.get("abstract"),
+            doi=data.get("doi"),
+            pmid=data.get("pmid"),
+            arxiv_id=data.get("arxiv_id"),
+            pmc_id=data.get("pmc_id"),
+            journal=data.get("journal"),
+            venue_type=data.get("venue_type"),
+            year=_safe_year(data.get("year")),
+            volume=data.get("volume"),
+            issue=data.get("issue"),
+            pages=data.get("pages"),
+            publisher=data.get("publisher"),
+            pdf_url=data.get("pdf_url"),
+            source_url=data.get("source_url"),
+            local_pdf_path=data.get("local_pdf_path"),
+            keywords=_str_list(data.get("keywords")),
+            mesh_terms=_str_list(data.get("mesh_terms")),
+            references=_str_list(data.get("references")),
+            citations=_safe_int(data.get("citations"), 0),
+            source=data.get("source", "unknown"),
+            relevance_score=_safe_int(data.get("relevance_score"), 0),
+            notes=data.get("notes"),
+            tags=_str_list(data.get("tags")),
+            category=data.get("category"),
+            rating=_safe_int(data.get("rating"), 0) if data.get("rating") is not None else None,
+            read_status=data.get("read_status", "unread"),
+            importance=data.get("importance", "normal"),
+            id=_safe_id(data.get("id")),
+            created_at=created_at or datetime.now(),
+            updated_at=updated_at or datetime.now(),
+        )

+ 109 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/paper_paths.py

@@ -0,0 +1,109 @@
+"""论文文件路径管理 —— PDF 存储路径生成与文件名规范化."""
+
+import hashlib
+import re
+
+LIBRARY_PDF_ROOT_DIR = "文献库"
+
+_UNCATEGORIZED_ALIASES = frozenset(
+    {
+        "无分类",
+        "无分類",
+        "无类目",
+        "未归类",
+        "不分類",
+        "uncategorized",
+        "uncategorised",
+        "none",
+        "n/a",
+        "na",
+        "null",
+        "-",
+        "—",
+    }
+)
+
+def _segment_is_uncategorized_alias(seg: str) -> bool:
+    t = (seg or "").strip()
+    if not t:
+        return True
+    if t in _UNCATEGORIZED_ALIASES:
+        return True
+    tl = t.lower()
+    return tl in _UNCATEGORIZED_ALIASES or tl in ("no category", "no cat", "not categorized")
+
+def normalize_library_category_display(display: str | None) -> str:
+    raw0 = (display or "").strip()
+    if not raw0 or _segment_is_uncategorized_alias(raw0):
+        return "未分类"
+    parts = [p.strip() for p in raw0.split("/") if p.strip()]
+    cleaned: list[str] = []
+    for p in parts[:4]:
+        s = "".join(ch for ch in p if ch not in '/\\:*?"<>|')
+        s = s.strip()
+        if len(s) > 32:
+            s = s[:32]
+        if _segment_is_uncategorized_alias(s):
+            s = "未分类"
+        if s:
+            cleaned.append(s)
+    if not cleaned:
+        return "未分类"
+    return "/".join(cleaned)
+
+def _sanitize_filename(title: str | None, max_len: int = 80) -> str:
+    if not title:
+        return "untitled"
+
+    safe_chars = []
+    for ch in title.strip():
+        if ch.isalnum() or ("\u4e00" <= ch <= "\u9fff"):
+            safe_chars.append(ch)
+        elif ch in (" ", "-", "_", "."):
+            safe_chars.append("_")
+        else:
+            safe_chars.append("_")
+
+    result = "".join(safe_chars)
+
+    result = re.sub(r"_+", "_", result).strip("_")
+
+    if len(result) > max_len:
+        result = result[:max_len].rsplit("_", 1)[0]
+
+    return result or "untitled"
+
+def category_slug_for_pdf_dir(display: str | None) -> str:
+    seg = (display or "").strip()
+    if _segment_is_uncategorized_alias(seg):
+        seg = "未分类"
+    t = seg or "未分类"
+    raw = []
+    for ch in t:
+        if ch.isalnum() or ("\u4e00" <= ch <= "\u9fff"):
+            raw.append(ch)
+        elif ch in (" ", "-", "_", "."):
+            raw.append("_")
+        else:
+            raw.append("_")
+    s = "".join(raw)
+    s = re.sub(r"_+", "_", s).strip("_")[:48]
+    if len(s) >= 2:
+        return s
+    h = hashlib.sha256(t.encode("utf-8")).hexdigest()[:12]
+    return f"cat_{h}"
+
+def library_pdf_relative_path(
+    category_display: str | None, paper_id: int, title: str | None = None
+) -> str:
+    t = (category_display or "").strip() or "未分类"
+    parts = [p.strip() for p in t.split("/") if p.strip()]
+    if not parts:
+        parts = ["未分类"]
+    segs = [category_slug_for_pdf_dir(p) for p in parts]
+
+    title_part = _sanitize_filename(title)
+    short_id = hashlib.sha256(str(paper_id).encode()).hexdigest()[:6]
+    filename = f"{title_part}_{short_id}.pdf"
+
+    return "/".join([LIBRARY_PDF_ROOT_DIR] + segs + [filename])

+ 227 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/pdf_download.py

@@ -0,0 +1,227 @@
+"""PDF 下载服务 —— 支持 arXiv/DBLP/出版商多源 PDF 获取与本地缓存."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import re
+from urllib.parse import urlparse
+
+import requests
+
+from .conference_landing_pdf import fetch_pdf_url_from_html_page
+from .paper import Paper
+
+_log = logging.getLogger(__name__)
+
+def _is_pkp_ojs_article_download_url(url: str) -> bool:
+    return bool(re.search(r"/article/download/\d+/\d+", (url or ""), re.I))
+
+def _is_direct_pdf_url(url: str) -> bool:
+    u = (url or "").strip()
+    if not u:
+        return False
+    ul = u.lower().split("?", 1)[0]
+    return ul.endswith(".pdf") or _is_pkp_ojs_article_download_url(u)
+
+def _derive_proceedings_pdf_url(source_url: str) -> str | None:
+    """Derive PDF URL from known proceedings abstract page URL patterns."""
+    u = (source_url or "").strip()
+    if not u:
+        return None
+    # NeurIPS: hash/XXX-Abstract-Conference.html → file/XXX-Paper-Conference.pdf
+    m = re.match(r"(.*)/hash/([a-f0-9]+)-Abstract(-\w+)?\.html$", u, re.I)
+    if m:
+        suffix = (m.group(3) or "-Conference")
+        return f"{m.group(1)}/file/{m.group(2)}-Paper{suffix}.pdf"
+    # CVF (CVPR/ICCV/ECCV): .../html/PaperName-paper.html → .../papers/PaperName-paper.pdf
+    m = re.match(r"(.*)/html/(.+?)\.html$", u, re.I)
+    if m and ("/content/" in u.lower()):
+        return f"{m.group(1)}/papers/{m.group(2)}.pdf"
+    # OpenReview: forum?id=X → pdf?id=X
+    if "openreview.net/forum" in u:
+        return re.sub(r"/forum\?id=", "/pdf?id=", u)
+    # Generic: .html → .pdf
+    if u.lower().endswith(".html"):
+        return re.sub(r"\.html$", ".pdf", u, flags=re.I)
+    return None
+
+
+def _pdf_download_candidates(paper: Paper, email: str) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+
+    def _push(u: str | None) -> None:
+        s = (u or "").strip()
+        if s and s.lower().startswith(("http://", "https://")):
+            low = s.lower()
+            if low not in seen:
+                seen.add(low)
+                out.append(s)
+
+    pu = (getattr(paper, "pdf_url", None) or "").strip()
+    if pu and _is_direct_pdf_url(pu):
+        _push(pu)
+
+    su = (getattr(paper, "source_url", None) or "").strip()
+    if su and _is_direct_pdf_url(su):
+        _push(su)
+
+    try:
+        resolved = resolve_paper_pdf_url(paper, email=email)
+        _push(resolved)
+    except Exception as ex:
+        _log.warning("resolve_paper_pdf_url 异常(已忽略): %s", ex, exc_info=True)
+
+    # Last resort: derive PDF URL from abstract page URL pattern
+    if not out and su:
+        derived = _derive_proceedings_pdf_url(su)
+        _push(derived)
+
+    return out
+
+def _headers_for_pdf_get(url: str, paper: Paper, email: str) -> dict:
+    mail = (email or "").strip()
+    ref = (getattr(paper, "source_url", None) or "").strip()
+
+    if not ref or not ref.lower().startswith("http"):
+        try:
+            pr = urlparse(url)
+            if pr.scheme and pr.netloc:
+                ref = f"{pr.scheme}://{pr.netloc}/"
+        except ValueError:
+            ref = ""
+
+    ua = f"PaperGraph/0.3 (mailto:{mail})" if mail else "PaperGraph/0.3"
+    h = {
+        "User-Agent": ua,
+        "Accept": "application/pdf,application/octet-stream,*/*;q=0.8",
+    }
+    if ref and ref.lower().startswith("http"):
+        h["Referer"] = ref[:2048]
+    return h
+
+def _file_looks_like_pdf(path: str) -> bool:
+    try:
+        with open(path, "rb") as f:
+            return f.read(5) == b"%PDF-"
+    except OSError:
+        return False
+
+def _normalize_doi_url(doi: str) -> str | None:
+    d = (doi or "").strip()
+    if not d:
+        return None
+    d = re.sub(r"^https?://(dx\.)?doi\.org/", "", d, flags=re.I).strip().rstrip("/")
+    return f"https://doi.org/{d}" if d else None
+
+def _should_probe_html_for_pdf(url: str) -> bool:
+    u = (url or "").strip().lower()
+    if not u.startswith(("http://", "https://")):
+        return False
+    if _is_pkp_ojs_article_download_url(u):
+        return False
+    return not re.search(r"openalex\.org/(?:w\d+|works/)", u)
+
+def resolve_paper_pdf_url(paper: Paper, email: str = "") -> str | None:
+    u = (getattr(paper, "pdf_url", None) or "").strip()
+    su = (getattr(paper, "source_url", None) or "").strip()
+    doi_u = _normalize_doi_url(getattr(paper, "doi", None) or "")
+
+    if u and _is_direct_pdf_url(u):
+        return u
+
+    from app.core.search import _arxiv_canonical_from_paper, _arxiv_pdf_url_from_id
+
+    ax = _arxiv_pdf_url_from_id(_arxiv_canonical_from_paper(paper))
+    if ax:
+        return ax
+
+    # Recover arXiv PDF URL from DOI/source URL.
+    if not ax:
+        for field_val in (getattr(paper, "doi", None) or "", getattr(paper, "source_url", None) or ""):
+            m = re.search(r"arxiv/([\d.]+)", str(field_val), re.I)
+            if m:
+                ax = f"https://arxiv.org/pdf/{m.group(1)}"
+                return ax
+
+    probe_candidates: list[str] = []
+    seen: set[str] = set()
+    for cand in (u, su, doi_u):
+        if cand and _should_probe_html_for_pdf(cand):
+            norm = cand.rstrip("/").lower()
+            if norm not in seen:
+                seen.add(norm)
+                probe_candidates.append(cand)
+
+    for cand_url in probe_candidates:
+        try:
+            got = fetch_pdf_url_from_html_page(cand_url, email=email)
+            if got:
+                return got
+        except Exception:
+            continue
+
+    # OpenReview forum pages expose PDFs at /pdf?id=...
+    if su and "openreview.net/forum" in su:
+        return re.sub(r"/forum\?id=", "/pdf?id=", su)
+
+    # Some DOI URLs redirect directly to open-access PDFs.
+    if doi_u:
+        try:
+            mail = (email or "").strip()
+            ua = f"PaperGraph/0.3 (mailto:{mail})" if mail else "PaperGraph/0.3"
+            headers = {"User-Agent": ua, "Accept": "application/pdf"}
+            with requests.get(doi_u, timeout=30, headers=headers, allow_redirects=True, stream=True) as r:
+                if r.status_code == 200 and r.headers.get("content-type", "").startswith("application/pdf"):
+                    return doi_u
+        except Exception:
+            pass
+
+    return None
+
+def _cleanup_temp_file(tmp_path: str) -> None:
+    with contextlib.suppress(OSError):
+        if os.path.isfile(tmp_path):
+            os.remove(tmp_path)
+
+def download_paper_pdf_to_path(paper: Paper, dest_abspath: str, email: str = "") -> bool:
+    try:
+        urls = _pdf_download_candidates(paper, email=email)
+        if not urls:
+            return False
+
+        with contextlib.suppress(OSError):
+            os.makedirs(os.path.dirname(dest_abspath) or ".", exist_ok=True)
+
+        for url in urls:
+            tmp = dest_abspath + ".part"
+            try:
+                headers = _headers_for_pdf_get(url, paper, email)
+                with requests.get(url, timeout=90, stream=True, headers=headers, allow_redirects=True) as r:
+                    if r.status_code != 200:
+                        continue
+
+                    with open(tmp, "wb") as f:
+                        for chunk in r.iter_content(chunk_size=65536):
+                            if chunk:
+                                f.write(chunk)
+
+                if os.path.getsize(tmp) < 256 or not _file_looks_like_pdf(tmp):
+                    _cleanup_temp_file(tmp)
+                    continue
+
+                os.replace(tmp, dest_abspath)
+                return True
+
+            except (OSError, requests.RequestException):
+                _cleanup_temp_file(tmp)
+                continue
+
+        return False
+
+    except Exception as ex:
+        _log.warning("download_paper_pdf_to_path 异常: %s", ex, exc_info=True)
+        _cleanup_temp_file(dest_abspath + ".part")
+        return False

+ 11 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .normalize import _arxiv_canonical_from_paper, _arxiv_pdf_url_from_id, sanitize_pinned_topic_keywords
+from .paper_searcher import PaperSearcher
+
+__all__ = [
+    "PaperSearcher",
+    "_arxiv_canonical_from_paper",
+    "_arxiv_pdf_url_from_id",
+    "sanitize_pinned_topic_keywords",
+]

+ 312 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/normalize.py

@@ -0,0 +1,312 @@
+"""搜索结果标准化 —— arxiv ID 规范化、关键词清洗与去重."""
+
+from __future__ import annotations
+
+import functools
+import re
+from typing import Any
+
+_QUERY_DELIM = re.compile(r"[,;\uFF0C\uFF1B\n]+")
+_RE_JATS_MARKUP = re.compile(r"<[^>]+>")
+_RE_MULTIPLE_SPACES = re.compile(r"\s+")
+_RE_ARXIV_DOI = re.compile(r"10\.48550/arxiv\.?([\d.]+\d)", re.I)
+_RE_ARXIV_URL_IN_DOI = re.compile(r"arxiv\.org/(?:abs|pdf)/([\w./]+)", re.I)
+_RE_ARXIV_VERSION_SUFFIX = re.compile(r"v\d+$", re.I)
+_RE_TITLE_ENTITY = re.compile(r"&amp;|&lt;|&gt;|&quot;|&#\d+;")
+_RE_TITLE_NON_ALNUM = re.compile(r"[^a-z0-9\u4e00-\u9fff]+", re.I)
+
+
+@functools.lru_cache(maxsize=128)
+def _venue_canonical_key(venue: str) -> str:
+    v = (venue or "").strip().lower()
+    v = re.sub(r"[^a-z0-9]", "", v)
+    return v if len(v) >= 2 else ""
+
+
+def _score_name_match(display_name: str, query_name: str) -> int:
+    dl, ql = display_name.strip().lower(), query_name.strip().lower()
+    if not dl or not ql: return 0
+    parts = [x for x in ql.replace(",", " ").split() if x]
+    score = 0
+    if dl == ql: score += 10
+    if ql in dl or dl in ql: score += 6
+    if parts and all(p in dl for p in parts if len(p) >= 2): score += 4
+    return score
+
+
+def split_query_phrases(query: str) -> list[str]:
+    q = (query or "").strip()
+    if not q:
+        return []
+    if not _QUERY_DELIM.search(q):
+        return [(q or "").strip()]
+    parts: list[str] = []
+    for p in _QUERY_DELIM.split(q):
+        t = p.strip()
+        if t:
+            parts.append((t or "").strip())
+    return parts if parts else [(q or "").strip()]
+
+
+def sanitize_search_keyword_list(raw: Any) -> list[str]:
+    if not isinstance(raw, list):
+        return []
+    out: list[str] = []
+    for x in raw:
+        if x is None:
+            continue
+        s = str(x).strip()
+        if s and s not in out:
+            out.append(s)
+        if len(out) >= 24:
+            break
+    return out
+
+
+def _normalize_title_for_dedupe(title: str | None) -> str:
+    if not title:
+        return ""
+    t = str(title).lower()
+    t = _RE_TITLE_ENTITY.sub(" ", t)
+    t = _RE_JATS_MARKUP.sub(" ", t)
+    t = _RE_TITLE_NON_ALNUM.sub(" ", t)
+    return _RE_MULTIPLE_SPACES.sub(" ", t).strip()
+
+
+def arxiv_id_from_doi(doi: str | None) -> str | None:
+    if not doi:
+        return None
+    d = str(doi).strip().lower()
+    if d.startswith("https://doi.org/"):
+        d = d[len("https://doi.org/"):].strip()
+    if not d:
+        return None
+    m = _RE_ARXIV_DOI.search(d)
+    if m:
+        return _RE_ARXIV_VERSION_SUFFIX.sub("", m.group(1)).lower()
+    m2 = _RE_ARXIV_URL_IN_DOI.search(d)
+    if m2:
+        raw = m2.group(1).split("/")[-1]
+        return _RE_ARXIV_VERSION_SUFFIX.sub("", raw).lower()
+    return None
+
+
+def _arxiv_pdf_url_from_id(arxiv_id: str | None) -> str | None:
+    if not arxiv_id:
+        return None
+    raw = str(arxiv_id).strip()
+    if not raw:
+        return None
+    low = raw.lower()
+    if "arxiv.org/pdf/" in low:
+        u = raw if raw.lower().startswith("http") else "https://" + raw.lstrip("/")
+        return u.split("?", 1)[0].rstrip("/")
+    if "arxiv.org/abs/" in low:
+        tail = raw.split("arxiv.org/abs/", 1)[-1].strip().rstrip("/")
+    else:
+        tail = re.sub(r"^arxiv:", "", raw, flags=re.I).strip()
+        tail = tail.split("/")[-1]
+    tail = tail.strip().rstrip("/")
+    if not tail or not re.search(r"\d", tail):
+        return None
+    return f"https://arxiv.org/pdf/{tail}.pdf"
+
+
+def _arxiv_canonical_from_paper(paper: Any) -> str | None:
+    aid = (paper.arxiv_id or "").strip()
+    if aid.lower().startswith("arxiv:"):
+        aid = aid[6:]
+    aid = aid.strip().rstrip("/")
+    aid = _RE_ARXIV_VERSION_SUFFIX.sub("", aid)
+    if aid and re.search(r"\d", aid):
+        return aid.lower()
+    return arxiv_id_from_doi(paper.doi)
+
+
+def _openalex_collect_landing_urls(w: dict[str, Any]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+
+    def add(raw: str | None) -> None:
+        if not raw or not isinstance(raw, str):
+            return
+        s = raw.strip().split("?", 1)[0]
+        if not s.lower().startswith("http"):
+            return
+        sl = s.lower()
+        if bool(re.search(r"https?://(api\.)?openalex\.org/works?/", sl)) or bool(
+            re.search(r"https?://(www\.)?openalex\.org/w\d+", sl)
+        ):
+            return
+        if sl in seen:
+            return
+        seen.add(sl)
+        out.append(s)
+
+    for key in ("best_oa_location", "primary_location"):
+        loc = w.get(key) or {}
+        if isinstance(loc, dict):
+            add(loc.get("landing_page_url"))
+    for loc in w.get("locations") or []:
+        if isinstance(loc, dict):
+            add(loc.get("landing_page_url"))
+    oa = w.get("open_access") or {}
+    if isinstance(oa, dict):
+        add(oa.get("oa_url"))
+    return out
+
+
+def _openalex_human_source_url(w: dict[str, Any], doi: str | None) -> str | None:
+    land = _openalex_collect_landing_urls(w)
+    for s in land:
+        if not s.lower().endswith(".pdf"):
+            return s
+    for s in land:
+        if s.lower().endswith(".pdf"):
+            return s
+    if doi:
+        d = str(doi).strip().lstrip("https://doi.org/").lstrip("doi.org/")
+        if d:
+            return f"https://doi.org/{d}"
+    wid = w.get("id")
+    return str(wid).strip() if isinstance(wid, str) and wid.strip() else None
+
+
+def _openalex_resolve_pdf_url(w: dict[str, Any]) -> str | None:
+    if not isinstance(w, dict):
+        return None
+    for key in ("best_oa_location", "primary_location"):
+        loc = w.get(key) or {}
+        if isinstance(loc, dict):
+            u = loc.get("pdf_url")
+            if isinstance(u, str) and u.strip():
+                return u.strip().split("?", 1)[0]
+    for loc in w.get("locations") or []:
+        if not isinstance(loc, dict):
+            continue
+        u = loc.get("pdf_url")
+        if isinstance(u, str) and u.strip():
+            return u.strip().split("?", 1)[0]
+    oa = w.get("open_access") or {}
+    if isinstance(oa, dict):
+        u = oa.get("oa_url")
+        if isinstance(u, str) and u.strip():
+            ul = u.strip().lower()
+            if ul.endswith(".pdf") or "arxiv.org/pdf" in ul:
+                return u.strip().split("?", 1)[0]
+
+    for s in _openalex_collect_landing_urls(w):
+        ul = s.lower()
+        if ul.endswith(".pdf") or "arxiv.org/pdf" in ul:
+            return s
+    return None
+
+
+def normalized_query_for_text_apis(query: str) -> str:
+    parts = split_query_phrases(query)
+    return " ".join(parts).strip()
+
+
+def plain_query_for_text_apis(query: str, kwargs: dict[str, Any]) -> str:
+    lk = sanitize_search_keyword_list(kwargs.get("llm_keywords"))
+    if not lk:
+        return normalized_query_for_text_apis(query)
+    if len(lk) >= 2:
+        q0 = ((query or "").strip() or str(lk[0]).strip())
+        venue_kw = (kwargs.get("venue") or "").strip()
+
+        if venue_kw and len(q0) <= 16:
+            tail: list[str] = []
+            for x in lk[1:8]:
+                t = str(x).strip()
+                if not t or t.lower() == q0.lower():
+                    continue
+                tail.append(t)
+                if len(tail) >= 4:
+                    break
+            if tail:
+                merged = f"{q0} {' '.join(tail)}".strip()
+                return merged[:200]
+        return q0[:200] if q0 else str(lk[0]).strip()[:200]
+    return (str(lk[0]).strip() or normalized_query_for_text_apis(query))[:200]
+
+
+def topic_terms_excluding_venue_year(
+    query: str,
+    *,
+    extra_terms: list[str] | None = None,
+    venue: str | None = None,
+    year: int | None = None,
+) -> str:
+    seen: set[str] = set()
+    out: list[str] = []
+    vlow = (venue or "").strip().lower()
+
+    def _consume(text: str) -> None:
+        for seg in _QUERY_DELIM.split(text or ""):
+            for tok in re.split(r"\s+", seg.strip()):
+                t = tok.strip()
+                if not t or len(t) < 2:
+                    continue
+                if year is not None and re.fullmatch(r"(?:19|20)\d{2}", t):
+                    continue
+                tl = t.lower()
+                if vlow and (tl == vlow or re.sub(r"[^a-z0-9]", "", tl) == re.sub(r"[^a-z0-9]", "", vlow)):
+                    continue
+                if tl in seen:
+                    continue
+                seen.add(tl)
+                out.append(t)
+                if len(out) >= 12:
+                    return
+
+    _consume(query or "")
+    for x in extra_terms or []:
+        if len(out) >= 12:
+            break
+        _consume(str(x))
+    return " ".join(out).strip()
+
+
+def sanitize_pinned_topic_keywords(raw: list[str] | None) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for x in raw or []:
+        s = str(x).strip()
+        if not s or len(s) < 2 or len(s) > 80:
+            continue
+        if s.lower() in seen:
+            continue
+        seen.add(s.lower())
+        out.append(s)
+    return out[:10]
+
+
+def extract_pinned_topic_terms(
+    *,
+    query: str,
+    merged_kw: list[str] | None,
+    venue: str,
+    year: int | None,
+) -> str:
+    seen: set[str] = set()
+    parts: list[str] = []
+
+    def _push(text: str) -> None:
+        t = (text or "").strip()
+        if not t:
+            return
+        tl = t.lower()
+        if tl in seen:
+            return
+        seen.add(tl)
+        parts.append(t)
+
+    t_query = topic_terms_excluding_venue_year(query or "", venue=venue, year=year)
+    if t_query:
+        _push(t_query)
+    for kw in sanitize_pinned_topic_keywords(list(merged_kw or [])):
+        tk = topic_terms_excluding_venue_year(kw, venue=venue, year=year)
+        if tk:
+            _push(tk)
+    return " ".join(parts[:12]).strip()

+ 406 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/paper_searcher.py

@@ -0,0 +1,406 @@
+"""论文搜索引擎 —— 多源适配(arXiv/DBLP/OpenAlex/Tavily)的统一调用入口."""
+
+from __future__ import annotations
+
+import asyncio, hashlib, logging, os, re, time
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import httpx, requests
+
+from ..paper import Paper
+from ...utils.async_sync import run_coroutine_sync
+from ...utils.author_query_match import (
+    normalize_author_names, author_phrase_matches_canonical_line,
+    is_author_centric_search, pick_primary_english_author_for_query,
+)
+from .normalize import (
+    _normalize_title_for_dedupe,
+    _arxiv_canonical_from_paper,
+    plain_query_for_text_apis,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def abbreviate_journal(journal: str | None) -> str | None:
+    if not journal:
+        return None
+    j = str(journal).strip()
+
+    m = re.search(r"\(([A-Z][A-Za-z]{1,12})\)", j)
+    if m:
+        return m.group(1).upper()
+
+    caps = [w for w in re.findall(r"\b[A-Z]{3,8}\b", j)
+            if w not in ("IEEE", "ACM", "SIG", "CVF", "THE", "FOR", "AND", "WITH", "ON", "IN")]
+    if caps:
+        return caps[0]
+    return j
+
+def _venue_appears_in_text(venue: str, text: str) -> bool:
+    v =(venue or "").strip().lower()
+    return len(v) >= 2 and v in (text or "").lower()
+
+
+def _merge_paper_link_fields(dst: Paper, src: Paper) -> None:
+    sp, dp = (src.pdf_url or "").strip(), (dst.pdf_url or "").strip()
+    s_pdf = bool(sp) and sp.lower().split("?", 1)[0].endswith(".pdf")
+    d_pdf = bool(dp) and dp.lower().split("?", 1)[0].endswith(".pdf")
+    if s_pdf and not d_pdf or not dp and sp:
+        dst.pdf_url = sp
+
+    ss, ds = (src.source_url or "").strip(), (dst.source_url or "").strip()
+    if not ds and ss:
+        dst.source_url = ss
+
+    sd, dd = (src.doi or "").strip(), (dst.doi or "").strip()
+    if not dd and sd:
+        dst.doi = sd
+    sa, da = (src.arxiv_id or "").strip(), (dst.arxiv_id or "").strip()
+    if not da and sa:
+        dst.arxiv_id = sa
+
+
+
+class RateLimiter:
+    def __init__(self, *, fixed_delays: dict[str, float]) -> None:
+        self._fixed = dict(fixed_delays)
+        self._last: dict[str, float] = {}
+
+    def _delay_for(self, source: str) -> float:
+        return float(self._fixed.get(source, 0.0))
+
+    async def wait_async(self, source: str) -> None:
+        delay = self._delay_for(source)
+        if delay <= 0:
+            self._last[source] = time.time()
+            return
+        now = time.time()
+        elapsed = now - self._last.get(source, 0.0)
+        if elapsed < delay:
+            await asyncio.sleep(delay - elapsed)
+        self._last[source] = time.time()
+
+_DEFAULT_PAPER_SEARCHER_DOWNLOAD_DIR = str(Path(__file__).resolve().parents[3] / "downloads" / "papers")
+
+def _sanitize_author_list_for_query(query: str, raw_authors: Any) -> List[str]:
+    if raw_authors is None: return []
+    if isinstance(raw_authors, str): seq = [raw_authors]
+    elif isinstance(raw_authors, list): seq = [str(x) for x in raw_authors]
+    else: return []
+    return [str(a).strip() for a in seq if str(a).strip()]
+
+
+
+def _has_any_author(p: Paper, want_raw: list) -> bool:
+    try:
+        names = [str(getattr(a, "name", "") or "").strip() for a in (p.authors or [])
+                 if str(getattr(a, "name", "") or "").strip()]
+    except Exception: return False
+    return bool(names) and any(any(author_phrase_matches_canonical_line(nm, ph) for nm in names) for ph in want_raw)
+
+
+from .sources.arxiv import (
+    search_arxiv as _search_arxiv_src,
+    _search_arxiv_by_author_list,
+)
+from .sources.dblp import (
+    search_dblp as _search_dblp_src,
+)
+from .sources.openalex import (
+    search_openalex as _search_openalex_src,
+    _search_openalex_works_by_author_async,
+)
+
+
+class PaperSearcher:
+    def __init__(self, email: Optional[str] = None, api_key: Optional[str] = None,
+                 download_dir: str = _DEFAULT_PAPER_SEARCHER_DOWNLOAD_DIR, *, httpx_trust_env: bool = True):
+        _email = (email or os.getenv("OPENALEX_MAILTO") or os.getenv("NCBI_EMAIL") or "").strip()
+        if _email.lower() == "user@example.com": _email = ""
+        self.email, self.api_key, self.download_dir = _email, api_key, download_dir
+        os.makedirs(self.download_dir, exist_ok=True)
+        self._rate = RateLimiter(fixed_delays={"arxiv": 0.1, "openalex": 0.15, "dblp": 0.35})
+        self._session = requests.Session()
+        self._async_client: Optional[httpx.AsyncClient] = None
+        self._async_client_loop: Optional[asyncio.AbstractEventLoop] = None
+        self.stats = {"arxiv_requests": 0, "dblp_requests": 0, "openalex_requests": 0,
+                      "total_results": 0, "downloaded_pdfs": 0}
+
+    def _bump_stat(self, key: str, n: int = 1) -> None:
+        self.stats[key] = self.stats.get(key, 0) + n
+
+    async def _ensure_async_client(self) -> httpx.AsyncClient:
+        loop = asyncio.get_running_loop()
+        if self._async_client is not None and self._async_client_loop is loop:
+            return self._async_client
+        if self._async_client is not None:
+            try: await self._async_client.aclose()
+            except Exception: pass
+        self._async_client = httpx.AsyncClient(
+            trust_env=False, limits=httpx.Limits(max_keepalive_connections=20, max_connections=80),
+            timeout=httpx.Timeout(60.0))
+        self._async_client_loop = loop
+        return self._async_client
+
+    async def aclose(self) -> None:
+        try:
+            if self._async_client is not None: await self._async_client.aclose()
+        except Exception: pass
+        self._async_client = self._async_client_loop = None
+
+    def _user_agent(self) -> str:
+        try:
+            from ...settings import get_settings
+            v = str(getattr(get_settings(), "app_version", "0.1") or "0.1")
+        except Exception:
+            v = "0.1"
+        return f"PaperGraph/{v} (mailto:{self.email})"
+
+    def _openalex_headers(self) -> Dict[str, str]:
+        return {"User-Agent": self._user_agent()}
+
+    def _openalex_params(self, base: Dict[str, Any]) -> Dict[str, Any]:
+        out = dict(base or {})
+        if self.email: out["mailto"] = self.email
+        return out
+
+    def _make_paper(self, *, title, authors=None, abstract=None, doi=None, arxiv_id=None,
+                    journal=None, year=None, pdf_url=None, source_url=None, citations=0,
+                    source="unknown", **extra) -> Paper:
+        return Paper(title=title, authors=authors or [], abstract=abstract, doi=doi,
+                     arxiv_id=arxiv_id, journal=journal or source, year=year, pdf_url=pdf_url,
+                     source_url=source_url, citations=citations, source=source, **extra)
+
+    @staticmethod
+    def _resolve_vpj(venue: Optional[str], kwargs: Dict[str, Any]) -> bool:
+        vpj = kwargs.get("venue_proceedings_journal")
+        return vpj if vpj is not None else bool(venue)
+
+    @staticmethod
+    def _paper_matches_venue(paper: Paper, venue: str) -> bool:
+        v = venue.lower().strip()
+        if not v: return True
+        blob = f"{paper.journal or ''} {paper.title or ''}".lower()
+        return v in blob
+
+    @staticmethod
+    def _paper_matches_venue_proceedings(paper: Paper, venue: str) -> bool:
+        raw = (venue or "").strip()
+        if not raw: return True
+        j = (paper.journal or "").lower()
+        t = (paper.title or "").lower()
+        return _venue_appears_in_text(raw, j) or _venue_appears_in_text(raw, t)
+
+
+    async def _rate_limit_async(self, source: str) -> None:
+        await self._rate.wait_async(source)
+
+    async def _async_http_get_with_retry(self, url, params, headers, timeout, max_attempts=3):
+        for attempt in range(max_attempts):
+            try:
+                resp = await self._async_client.get(url, params=params, headers=headers, timeout=timeout)
+                if resp.status_code == 429:
+                    if attempt < max_attempts - 1 and "arxiv" in str(url):
+                        await asyncio.sleep(8 + attempt * 8); continue
+                    raise RuntimeError(f"HTTP 429: {url}")
+                if resp.status_code in (500, 502, 503, 504) and attempt < max_attempts - 1:
+                    await asyncio.sleep(4 + attempt * 4); continue
+                resp.raise_for_status()
+                return resp
+            except Exception:
+                if attempt < max_attempts - 1: await asyncio.sleep(4 + attempt * 4); continue
+                raise
+
+    def _post_process_results(self, all_results: List[Paper], query: str, *, max_results: int,
+                              **kwargs: Any) -> List[Paper]:
+
+        raw_authors = kwargs.get("authors") or kwargs.get("author") or []
+        if isinstance(raw_authors, str): raw_authors = [raw_authors]
+        raw_authors = _sanitize_author_list_for_query(query, raw_authors)
+        want_raw = normalize_author_names([str(a).strip() for a in raw_authors if str(a).strip()])
+        unique_results = [p for p in all_results if _has_any_author(p, want_raw)] if want_raw else list(all_results)
+
+        unique_results = self._smart_deduplicate(unique_results)
+        unique_results = PaperSearcher._collapse_identical_norm_title_prefer_older(unique_results)
+
+        venue_kw = (kwargs.get("venue") or "").strip() or None
+        year_from, year_to = kwargs.get("year_from"), kwargs.get("year_to")
+
+        if venue_kw and unique_results:
+            matched = [p for p in unique_results if self._paper_matches_venue_proceedings(p, venue_kw)]
+            if matched and len(matched) >= max(1, len(unique_results) * 0.15):
+                non_matched = [p for p in unique_results if p not in matched]
+                unique_results = matched + non_matched
+
+        if year_from is not None:
+            unique_results = [p for p in unique_results if (p.year or 0) >= int(year_from)]
+        if year_to is not None:
+            unique_results = [p for p in unique_results if (p.year or 9999) <= int(year_to)]
+
+        sort_mode = (kwargs.get("sort") or "relevance").lower().strip()
+        if sort_mode == "date":
+            unique_results.sort(key=lambda p: (p.year or -1, p.citations or 0), reverse=True)
+        else:
+            unique_results.sort(key=lambda p: (p.citations or 0, p.year or -1), reverse=True)
+        return unique_results[:max_results]
+
+    def search(self, query: str, sources: Optional[List[str]] = None, max_results: int = 10, **kwargs) -> List[Paper]:
+        return run_coroutine_sync(self.search_async(query, sources=sources, max_results=max_results, **kwargs),
+                                  op_name="search")
+
+    async def search_async(self, query: str, sources: Optional[List[str]] = None, max_results: int = 10,
+                           **kwargs) -> List[Paper]:
+        if "max_results" in kwargs:
+            try: max_results = int(kwargs.pop("max_results"))
+            except (TypeError, ValueError): kwargs.pop("max_results", None)
+        if "sources" in kwargs: sources = kwargs.pop("sources")
+        if sources is None: sources = ["arxiv", "dblp", "openalex"]
+        sources = [str(s).strip().lower() for s in sources if str(s).strip()] or ["arxiv", "dblp", "openalex"]
+        # Tavily 网页结果不作为普通 paper 源;会议官网兜底由显式 proceedings 路径处理
+        sources = [s for s in sources if s != "tavily"] or ["arxiv", "dblp", "openalex"]
+
+        raw_authors_kw = kwargs.get("authors") or kwargs.get("author") or []
+        if isinstance(raw_authors_kw, str): raw_authors_kw = [raw_authors_kw]
+        expanded_authors = normalize_author_names([str(x).strip() for x in (raw_authors_kw or []) if str(x).strip()])
+        if expanded_authors: kwargs = {**kwargs, "authors": expanded_authors}
+        author_centric = is_author_centric_search(query, expanded_authors)
+        _query_before_author = query
+        if author_centric:
+            eng_q = pick_primary_english_author_for_query(expanded_authors)
+            if eng_q: _query_before_author, query = query, eng_q
+
+        cap_factor = max(0.5, min(2.0, float(kwargs.get("per_source_cap_factor") or 1.0)))
+        per_src_n = max(5, int(max_results * 2 * cap_factor))
+        venue_bound = bool((kwargs.get("venue") or "").strip())
+        yf_p = kwargs.get("year_from")
+        yt_p = kwargs.get("year_to")
+        pinned_year = (
+            yf_p is not None
+            and yt_p is not None
+            and int(yf_p) == int(yt_p)
+        )
+        if venue_bound and not (plain_query_for_text_apis(query, kwargs) or "").strip():
+            if kwargs.get("venue_browse"):
+                per_src_n = max(per_src_n, 56)
+            else:
+                per_src_n = max(per_src_n, 32) if pinned_year else min(per_src_n, 56)
+
+        if kwargs.get("days_back"):
+            days = kwargs["days_back"]
+            kwargs["date_from"] = (datetime.now() - timedelta(days=days)).strftime("%Y/%m/%d")
+
+
+        await self._ensure_async_client()
+        _src_timeouts = {
+            "dblp": float(kwargs.get("dblp_timeout_sec") or 32.0),
+            "openalex": float(kwargs.get("openalex_timeout_sec") or kwargs.get("http_timeout_sec") or 45.0),
+            "arxiv": float(kwargs.get("arxiv_timeout_sec") or kwargs.get("http_timeout_sec") or 30.0),
+        }
+
+        async def _fetch_src(src: str) -> List[Paper]:
+            if src == "arxiv":
+                if author_centric and expanded_authors:
+                    by_author_ax = await _search_arxiv_by_author_list(self, expanded_authors, per_src_n, **kwargs)
+                    if by_author_ax: return by_author_ax
+                    return await _search_arxiv_src(self, _query_before_author, per_src_n, **kwargs)
+                return await _search_arxiv_src(self, query, per_src_n, **kwargs)
+            elif src == "openalex":
+                if author_centric and expanded_authors:
+                    by_author = await _search_openalex_works_by_author_async(self, expanded_authors, per_src_n, **kwargs)
+                    if by_author: return by_author
+                    return await _search_openalex_src(self, _query_before_author, per_src_n, **kwargs)
+                return await _search_openalex_src(self, query, per_src_n, **kwargs)
+            elif src == "dblp":
+                return await _search_dblp_src(self, query, per_src_n, **kwargs)
+            else:
+                return []
+
+        async def _run_one(src: str) -> List[Paper]:
+            wall = max(5.0, min(60.0, float(_src_timeouts.get(src, 25.0))))
+            try: return await asyncio.wait_for(_fetch_src(src), timeout=wall)
+            except asyncio.TimeoutError:
+                logger.warning("搜索 %s 超时(%.0fs)", src, wall); return []
+            except Exception as e:
+                logger.warning("搜索 %s 时出错: %s", src, str(e)); return []
+
+        results_by_src = await asyncio.gather(*[_run_one(s) for s in sources])
+        all_results: List[Paper] = []
+        for src, res in zip(sources, results_by_src):
+            all_results.extend(res)
+            logger.info("从 %s 获取 %s 篇文献", src, len(res))
+
+        final_results = self._post_process_results(all_results, query, max_results=max_results, **kwargs)
+        self._bump_stat("total_results", len(final_results))
+        return final_results
+
+    def search_arxiv(self, query: str, max_results: int = 10, **kwargs) -> List[Paper]:
+        return run_coroutine_sync(self.search_arxiv_async(query, max_results, **kwargs), op_name="search_arxiv")
+
+    async def search_arxiv_async(self, query: str, max_results: int = 10, **kwargs) -> List[Paper]:
+        return await _search_arxiv_src(self, query, max_results, **kwargs)
+
+    async def search_dblp_async(self, query: str, max_results: int = 10, **kwargs) -> List[Paper]:
+        return await _search_dblp_src(self, query, max_results, **kwargs)
+
+    def search_openalex(self, query: str, max_results: int = 10, **kwargs) -> List[Paper]:
+        return run_coroutine_sync(self.search_openalex_async(query, max_results, **kwargs), op_name="search_openalex")
+
+
+    async def search_openalex_async(self, query: str, max_results: int = 10, **kwargs) -> List[Paper]:
+        return await _search_openalex_src(self, query, max_results, **kwargs)
+
+    @staticmethod
+    def _collapse_identical_norm_title_prefer_older(results: List[Paper]) -> List[Paper]:
+        if not results: return results
+        def _yy(p: Paper) -> int:
+            try: yi = int(p.year) if p.year is not None else 9999
+            except (TypeError, ValueError): return 9999
+            return yi if 1900 <= yi <= 2100 else 9999
+        groups: dict[str, list[Paper]] = {}
+        for p in results:
+            nt = _normalize_title_for_dedupe(p.title)
+            if len(nt) >= 22: groups.setdefault(nt, []).append(p)
+        drop_ids = {id(pp) for grp in groups.values() if len(grp) > 1
+                   for pp in grp if pp is not min(grp, key=_yy)}
+        return [p for p in results if id(p) not in drop_ids] if drop_ids else results
+
+    @staticmethod
+    def _paper_dedupe_key(paper: Paper) -> str:
+        if ax := _arxiv_canonical_from_paper(paper): return f"arxiv:{ax}"
+        if doi := (paper.doi or "").strip().lower(): return f"doi:{doi}"
+        nt = _normalize_title_for_dedupe(paper.title)
+        return f"empty:{id(paper)}" if not nt else "title:" + hashlib.md5(nt.encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _dedupe_quality_tuple(p: Paper) -> tuple:
+        abst = (p.abstract or "").strip()
+        return (1 if abst else 0, len(abst), int(p.citations or 0), int(p.year or 0))
+
+    def _smart_deduplicate(self, papers: List[Paper]) -> List[Paper]:
+        best: Dict[str, Paper] = {}
+        for paper in papers:
+            k = self._paper_dedupe_key(paper)
+            if k not in best: best[k] = paper; continue
+            if self._dedupe_quality_tuple(paper) > self._dedupe_quality_tuple(best[k]):
+                _merge_paper_link_fields(paper, best[k]); best[k] = paper
+            else: _merge_paper_link_fields(best[k], paper)
+        return list(best.values())
+
+    def download_pdf(self, paper: Paper) -> Optional[str]:
+        if not paper.pdf_url: return None
+        try:
+            safe_title = "".join(c if c.isalnum() or c in (' ', '-', '_') else '_' for c in paper.title[:50])
+            filename = f"{paper.arxiv_id or 'paper'}_{safe_title}.pdf"
+            file_path = os.path.join(self.download_dir, filename)
+            if os.path.exists(file_path): return file_path
+            response = self._session.get(paper.pdf_url, timeout=60, stream=True)
+            if response.status_code == 200:
+                with open(file_path, 'wb') as f:
+                    for chunk in response.iter_content(chunk_size=8192): f.write(chunk)
+                self._bump_stat("downloaded_pdfs")
+                return file_path
+        except Exception: pass
+        return None

+ 1 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

+ 399 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/arxiv.py

@@ -0,0 +1,399 @@
+"""arXiv API 适配器 —— 搜索、ID 解析与 PDF URL 构造."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote_plus
+
+import feedparser
+
+from ...author import Author
+from ...paper import Paper
+from ..normalize import (
+    _arxiv_pdf_url_from_id,
+    sanitize_search_keyword_list,
+    split_query_phrases,
+)
+from ..paper_searcher import _sanitize_author_list_for_query
+from ....utils.common import text_has_cjk
+
+logger = logging.getLogger(__name__)
+
+
+def arxiv_category_clause(categories: list[str | None]) -> str | None:
+    if not categories:
+        return None
+    cats = [str(c).strip() for c in categories if c and str(c).strip()]
+    if not cats:
+        return None
+    if len(cats) == 1:
+        return f"cat:{cats[0]}"
+    return "+OR+".join(f"cat:{c}" for c in cats)
+
+
+def arxiv_query_string_from_kwargs(query: str, kwargs: dict[str, Any]) -> str:
+    lk = sanitize_search_keyword_list(kwargs.get("llm_keywords"))
+    if not lk:
+        return (query or "").strip()
+    if len(lk) >= 2:
+        q0 = (query or "").strip()
+        return q0 if q0 else str(lk[0]).strip()
+    one = str(lk[0]).strip()
+    if len(one) > 480:
+        one = one[:480].rsplit(" ", 1)[0].strip()
+    return one or ((query or "").strip())
+
+
+def _arxiv_comment_from_feed_entry(entry: Any) -> str:
+    for key in ("arxiv_comment", "comment"):
+        v = getattr(entry, key, None) or (
+            entry.get(key) if hasattr(entry, "get") else None
+        )
+        if isinstance(v, str) and v.strip():
+            return v.replace("\n", " ").strip()
+    return ""
+
+
+def _arxiv_submitted_date_clause(kwargs: Dict[str, Any]) -> Optional[str]:
+    if not bool(kwargs.get("arxiv_use_submitted_date", False)):
+        return None
+    db = kwargs.get("days_back")
+    if db is None:
+        return None
+    try:
+        days = int(db)
+    except (TypeError, ValueError):
+        return None
+    if days <= 0:
+        return None
+    end = datetime.now()
+    start = end - timedelta(days=days)
+    return (
+        f"submittedDate:[{start.strftime('%Y%m%d')}0000"
+        f"+TO+{end.strftime('%Y%m%d')}2359]"
+    )
+
+
+def _arxiv_entry_published_naive(entry: Any) -> Optional[datetime]:
+    t = (
+        (entry.get("published_parsed") or entry.get("updated_parsed"))
+        if hasattr(entry, "get")
+        else (
+            getattr(entry, "published_parsed", None)
+            or getattr(entry, "updated_parsed", None)
+        )
+    )
+    if not t:
+        return None
+    try:
+        return datetime(*t[:6])
+    except (TypeError, ValueError):
+        return None
+
+
+def _arxiv_clause_for_phrase(searcher, phrase: str, style: str) -> str:
+    p = (phrase or "").replace('"', " ").strip()
+    if not p:
+        return ""
+    if style == "ti_abs":
+        return f'all:"{p}"' if " " in p else f'(ti:"{p}"+OR+abs:"{p}")'
+    return f'all:"{p}"' if " " in p else f"all:{quote_plus(p)}"
+
+
+def _arxiv_query_part(
+    searcher, query: str, style: str = "all", *, max_phrases: int = 14
+) -> Optional[str]:
+    q = (query or "").strip().replace('"', " ")
+    if not q:
+        return None
+    st = style if style in ("all", "ti_abs") else "all"
+    phrases = [
+        p.replace('"', " ").strip()
+        for p in split_query_phrases(q)
+        if p.strip()
+    ][: max(1, int(max_phrases))]
+    clauses = [
+        c
+        for c in (_arxiv_clause_for_phrase(searcher, p, st) for p in phrases)
+        if c
+    ]
+    if len(clauses) >= 2:
+        return "(" + "+OR+".join(clauses) + ")"
+    if len(clauses) == 1:
+        return clauses[0]
+    q0 = phrases[0] if phrases else q
+    return _arxiv_clause_for_phrase(searcher, q0, st) or None
+
+
+def _arxiv_build_search_query(
+    searcher, query: str, venue: Optional[str], **kwargs
+) -> str:
+    style = kwargs.get("arxiv_query_style", "ti_abs").lower()
+    if style not in ("all", "ti_abs"):
+        style = "all"
+    v = (str(venue).strip().replace('"', " ")) if venue else ""
+    parts: List[str] = []
+    cat_c = arxiv_category_clause(kwargs.get("arxiv_categories"))
+    if cat_c:
+        parts.append(cat_c)
+    raw_authors = kwargs.get("authors") or kwargs.get("author") or []
+    if isinstance(raw_authors, str):
+        raw_authors = [raw_authors]
+    if isinstance(raw_authors, list):
+        raw_authors = _sanitize_author_list_for_query(query, raw_authors)
+        aus = [
+            str(x).strip().replace('"', " ")
+            for x in raw_authors
+            if str(x).strip()
+        ][:3]
+    else:
+        aus = []
+    if aus:
+        author_clauses: List[str] = []
+        for a in aus:
+            a0 = a.strip()
+            if not a0:
+                continue
+            author_clauses.extend([f'au:"{a0}"'])
+        author_clauses = list(dict.fromkeys([c for c in author_clauses if c]))[:6]
+        if author_clauses:
+            inner = "+OR+".join(author_clauses)
+            parts.append(
+                f"({inner})" if len(author_clauses) > 1 else author_clauses[0]
+            )
+    max_or = int(kwargs.get("arxiv_max_or_clauses", 14) or 14)
+    q_part = _arxiv_query_part(searcher, query, style, max_phrases=max(1, max_or))
+    if q_part:
+        parts.append(q_part)
+    if v:
+        if " " in v:
+            parts.append(f'all:"{v}"')
+        elif style == "ti_abs":
+            vc = _arxiv_clause_for_phrase(searcher, v, "ti_abs")
+            if vc:
+                parts.append(vc)
+        else:
+            parts.append(f"all:{quote_plus(v)}")
+    if not parts:
+        return "cat:cs"
+    elif len(parts) == 1:
+        expr = parts[0]
+    else:
+        expr = "+AND+".join(parts)
+    date_clause = _arxiv_submitted_date_clause(kwargs)
+    return f"{expr}+AND+{date_clause}" if date_clause else expr
+
+
+def _filter_arxiv_entries_by_days_back(
+    searcher, entries: List[Any], days_back: int
+) -> List[Any]:
+    cutoff = datetime.now() - timedelta(days=days_back)
+    return [
+        e
+        for e in entries
+        if (pub := _arxiv_entry_published_naive(e)) is None or pub >= cutoff
+    ]
+
+
+def _arxiv_paper_dedupe_key(searcher, p: Paper) -> str:
+    aid = (p.arxiv_id or "").strip()
+    if aid:
+        return re.sub(r"v\d+$", "", aid, flags=re.I).lower()
+    return hashlib.md5(
+        (p.title or "").strip().lower().encode("utf-8", errors="ignore")
+    ).hexdigest()[:20]
+
+
+async def _search_arxiv_by_keyword_list_async(
+    searcher, query: str, max_results: int, keywords: List[str], **kwargs: Any
+) -> List[Paper]:
+    n = max(1, len(keywords))
+    per = max(8, min(60, (max_results + n - 1) // n + 8))
+    merged, seen = [], set()
+    for kw in keywords[:16]:
+        kwt = str(kw).strip()
+        if not kwt:
+            continue
+        for p in await search_arxiv(
+            searcher, query, per, **{**kwargs, "llm_keywords": [kwt]}
+        ):
+            dk = _arxiv_paper_dedupe_key(searcher, p)
+            if dk in seen:
+                continue
+            seen.add(dk)
+            merged.append(p)
+        if len(merged) >= max_results:
+            break
+    return merged[:max_results]
+
+
+async def _search_arxiv_by_author_list(
+    searcher, author_names: list[str], max_results: int, **kwargs
+) -> list[Paper]:
+    if not author_names:
+        return []
+    merged, seen = [], set()
+    for name in author_names[:3]:
+        nm = name.strip()
+        if not nm or text_has_cjk(nm):
+            continue
+        akw = dict(kwargs)
+        akw["authors"] = [nm]
+        akw["llm_keywords"] = []
+        for p in await search_arxiv(searcher, "", max(5, max_results), **akw):
+            dk = _arxiv_paper_dedupe_key(searcher, p)
+            if dk in seen:
+                continue
+            seen.add(dk)
+            merged.append(p)
+        if len(merged) >= max_results:
+            break
+    return merged[:max_results]
+
+
+async def search_arxiv(
+    searcher, query: str, max_results: int = 10, **kwargs
+) -> List[Paper]:
+    await searcher._ensure_async_client()
+    await searcher._rate_limit_async("arxiv")
+
+    id_list0 = str(kwargs.get("arxiv_id_list") or "").strip()
+    lk0 = sanitize_search_keyword_list(kwargs.get("llm_keywords"))
+    venue_bound = bool((kwargs.get("venue") or "").strip())
+    if not id_list0 and len(lk0) >= 2 and not venue_bound:
+        return await _search_arxiv_by_keyword_list_async(
+            searcher, query, max_results, lk0, **kwargs
+        )
+
+    base_url = "https://export.arxiv.org/api/query"
+    venue = (kwargs.get("venue") or "").strip() or None
+    vpj = searcher._resolve_vpj(venue, kwargs)
+    include_venue_in_arxiv_query = bool(
+        venue and (not vpj) and bool(kwargs.get("strict_venue_match"))
+    )
+    id_list = str(kwargs.get("arxiv_id_list") or "").strip()
+    if id_list:
+        params = {
+            "id_list": id_list,
+            "start": 0,
+            "max_results": min(max_results, 30000),
+            "sortBy": "submittedDate",
+            "sortOrder": "descending",
+        }
+    else:
+        q_arxiv = arxiv_query_string_from_kwargs(query, kwargs)
+        arxiv_kw = {k: v for k, v in kwargs.items() if k != "venue"}
+        search_expr = _arxiv_build_search_query(
+            searcher,
+            q_arxiv,
+            venue if include_venue_in_arxiv_query else None,
+            **arxiv_kw,
+        )
+        sort_by = (
+            "relevance"
+            if (kwargs.get("sort") or "date").lower().strip() == "relevance"
+            else "submittedDate"
+        )
+        params = {
+            "search_query": search_expr,
+            "start": 0,
+            "max_results": min(max_results, 30000),
+            "sortBy": sort_by,
+            "sortOrder": "descending",
+        }
+
+    headers = {"User-Agent": searcher._user_agent()}
+    req_timeout = float(kwargs.get("http_timeout_sec", 30.0))
+    max_attempts = max(1, min(10, int(kwargs.get("http_max_attempts", 4))))
+    resp = await searcher._async_http_get_with_retry(
+        base_url,
+        params=params,
+        headers=headers,
+        timeout=req_timeout,
+        max_attempts=max_attempts,
+    )
+    feed = feedparser.parse(resp.content or b"")
+    entries = list(getattr(feed, "entries", []) or [])
+
+    if not entries and not id_list:
+        from ....settings import get_settings
+
+        if bool(getattr(get_settings(), "arxiv_or_retry_on_empty", True)):
+            or_expr = search_expr.replace("+AND+", "+OR+")
+            if or_expr != search_expr:
+                await searcher._rate_limit_async("arxiv")
+                or_params = dict(params)
+                or_params["search_query"] = or_expr
+                resp2 = await searcher._async_http_get_with_retry(
+                    base_url,
+                    params=or_params,
+                    headers=headers,
+                    timeout=req_timeout,
+                    max_attempts=min(max_attempts, 2),
+                )
+                entries = list(
+                    getattr(feedparser.parse(resp2.content or b""), "entries", [])
+                    or []
+                )
+
+    db_days = kwargs.get("days_back")
+    if db_days:
+        try:
+            if int(db_days) > 0:
+                entries = _filter_arxiv_entries_by_days_back(
+                    searcher, entries, int(db_days)
+                )
+        except (TypeError, ValueError):
+            pass
+
+    papers: List[Paper] = []
+    for entry in entries:
+        try:
+            arxiv_id = entry.get("id", "").split("/")[-1].replace("abs/", "")
+            title = entry.get("title", "Unknown").replace("\n", " ")
+            authors = [
+                Author(name=a.get("name", ""))
+                for a in (entry.get("authors", []) or [])
+                if a.get("name")
+            ]
+            abstract = (entry.get("summary", "") or "").replace("\n", " ")
+            tags = entry.get("tags", [])
+            keywords = [tag.get("term", "") for tag in tags if tag.get("term")]
+            published = entry.get("published_parsed") or entry.get("updated_parsed")
+            year = published[0] if published else None
+            links = entry.get("links", [])
+            pdf_url = abs_url = None
+            for link in links:
+                if link.get("type") == "application/pdf":
+                    pdf_url = link.get("href")
+                elif link.get("type") == "text/html":
+                    abs_url = link.get("href")
+            if not pdf_url and arxiv_id:
+                pdf_url = _arxiv_pdf_url_from_id(
+                    re.sub(r"v\d+$", "", arxiv_id.strip(), flags=re.I)
+                )
+            primary_category = tags[0].get("term", "") if tags else ""
+            papers.append(
+                searcher._make_paper(
+                    title=title,
+                    authors=authors,
+                    abstract=abstract,
+                    arxiv_id=arxiv_id,
+                    journal=f"arXiv:{primary_category}" if primary_category else "arXiv",
+                    year=year,
+                    pdf_url=pdf_url,
+                    source_url=abs_url or f"https://arxiv.org/abs/{arxiv_id}",
+                    keywords=keywords,
+                    source="arxiv",
+                    notes=_arxiv_comment_from_feed_entry(entry) or None,
+                )
+            )
+        except Exception:
+            continue
+
+    searcher._bump_stat("arxiv_requests")
+    return papers

+ 508 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/dblp.py

@@ -0,0 +1,508 @@
+"""DBLP API 适配器 —— 作者 PID 匹配、论文搜索与会议论文集召回."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import xml.etree.ElementTree as ET
+from datetime import datetime
+from typing import Any, List
+
+from ...author import Author
+from ...paper import Paper
+from ....utils.common import text_has_cjk
+from ..normalize import (
+    _QUERY_DELIM,
+    _RE_ARXIV_VERSION_SUFFIX,
+    sanitize_search_keyword_list,
+    topic_terms_excluding_venue_year,
+)
+from .source_common import json_api_headers, normalize_query_authors, pick_best_name_match
+
+logger = logging.getLogger(__name__)
+
+# DBLP adds numeric suffixes to disambiguate same-name authors.
+_DBLP_AUTHOR_SUFFIX_RE = re.compile(r"\s+\d{4}$")
+
+
+def _dblp_parse_ee_urls(ee: Any) -> tuple[str | None, str | None, str | None, str | None]:
+    urls: list[str] = []
+    if isinstance(ee, list):
+        for u in ee:
+            if isinstance(u, str) and u.strip():
+                urls.append(u.strip())
+    elif isinstance(ee, str) and ee.strip():
+        urls.append(ee.strip())
+
+    doi: str | None = None
+    aid: str | None = None
+    pdf_url: str | None = None
+    landing: str | None = None
+
+    for u in urls:
+        lu = u.lower()
+        base = u.split("?", 1)[0].strip()
+
+        if doi is None and "doi.org/" in lu:
+            doi = u.split("doi.org/", 1)[-1].split("?", 1)[0].strip().rstrip("/")
+            # arXiv DOI, e.g. 10.48550/arXiv.2601.22158.
+            if aid is None:
+                m = re.search(r"arxiv/([\d.]+)", lu)
+                if m:
+                    aid = _RE_ARXIV_VERSION_SUFFIX.sub("", m.group(1))
+        if aid is None and "arxiv.org/abs/" in lu:
+            raw = u.split("arxiv.org/abs/", 1)[-1].strip().rstrip("/")
+            aid = _RE_ARXIV_VERSION_SUFFIX.sub("", raw)
+
+        bl = base.lower()
+        if pdf_url is None and (bl.endswith(".pdf") or "arxiv.org/pdf/" in bl):
+            pdf_url = base
+        elif landing is None and bl.startswith("http") and not bl.endswith(".pdf") and "arxiv.org/pdf/" not in bl:
+            landing = base
+
+    first = urls[0] if urls else None
+    source_url = landing or first
+    return source_url, doi, aid, pdf_url
+
+
+def raw_query_for_dblp(query: str, kwargs: dict[str, Any]) -> str:
+    if bool(kwargs.get("dblp_use_llm_keywords")):
+        lk = sanitize_search_keyword_list(kwargs.get("llm_keywords"))
+        if lk:
+            if len(lk) >= 2:
+                q0 = (query or "").strip()
+                return q0 if q0 else str(lk[0]).replace('"', " ").strip()
+            return str(lk[0]).replace('"', " ").strip()
+    q = (query or "").strip()
+    if not q:
+        return ""
+
+    parts = [p.strip() for p in _QUERY_DELIM.split(q) if p and p.strip()]
+    if not parts:
+        return q.replace('"', " ").strip()
+    return " ".join([p.replace('"', " ").strip() for p in parts]).strip()
+
+
+def _dblp_venue_search_queries(venue_only: str, year_from: Any) -> list[str]:
+    raw = (venue_only or "").strip()
+    if not raw:
+        return []
+    vlow = raw.lower()
+    yfi = int(year_from) if year_from is not None and str(year_from).isdigit() else None
+    seen, out = set(), []
+
+    if yfi:
+        q = f"{raw} {yfi}"
+        if q not in seen:
+            seen.add(q)
+            out.append(q)
+
+    if yfi:
+        q = f"conf/{vlow}/{yfi}"
+        if q not in seen:
+            seen.add(q)
+            out.append(q)
+    q = f"conf/{vlow}"
+    if q not in seen:
+        seen.add(q)
+        out.append(q)
+
+    if raw not in seen:
+        seen.add(raw)
+        out.append(raw)
+    return out
+
+
+async def search_dblp(searcher, query, max_results=10, **kwargs):
+    await searcher._ensure_async_client()
+    await searcher._rate_limit_async("dblp")
+
+    author_names = normalize_query_authors(query, kwargs.get("authors") or kwargs.get("author") or [])
+    papers_by_author = None
+    for author_name in author_names:
+        if text_has_cjk(author_name):
+            continue
+        papers_by_author = await _search_dblp_by_author_pid(
+            searcher, author_name, max_results, kwargs
+        )
+        if papers_by_author:
+            break
+    if papers_by_author:
+        searcher._bump_stat("dblp_requests")
+        return papers_by_author
+    if author_names and not papers_by_author:
+        from ....settings import get_settings
+
+        if not bool(getattr(get_settings(), "dblp_author_name_fallback_search", True)):
+            return []
+
+    base_q = (raw_query_for_dblp(query, kwargs) or "").strip()
+    venue_only = (kwargs.get("venue") or "").strip()
+    vpj = searcher._resolve_vpj(venue_only, kwargs)
+    strict_no_fallback = bool(
+        vpj and venue_only and not kwargs.get("venue_fallback_if_empty", True)
+    )
+    dblp_queries: list[str] = []
+    if venue_only:
+        dblp_queries = _dblp_venue_search_queries(venue_only, kwargs.get("year_from"))
+        yf_dblp = (
+            int(kwargs.get("year_from"))
+            if kwargs.get("year_from") is not None
+               and str(kwargs.get("year_from")).isdigit()
+            else None
+        )
+        if base_q:
+            topic = topic_terms_excluding_venue_year(
+                base_q, venue=venue_only, year=yf_dblp
+            )
+            topic_prefix = []
+            if topic:
+                topic_prefix.append(f"{topic} {venue_only}".strip())
+                if yf_dblp is not None:
+                    topic_prefix.insert(
+                        0, f"{topic} {venue_only} {yf_dblp}".strip()
+                    )
+            elif base_q.lower() != venue_only.lower():
+                topic_prefix.append(f"{base_q} {venue_only}".strip())
+            seen_q = set(dblp_queries)
+            dblp_queries = [q for q in topic_prefix if q not in seen_q] + dblp_queries
+        tt_prefix = []
+        raw_tt = kwargs.get("target_titles")
+        if isinstance(raw_tt, list) and raw_tt:
+            t0 = str(raw_tt[0] or "").replace('"', " ").strip()
+            if len(t0) >= 8:
+                tt_prefix.append(t0[:220])
+        if tt_prefix:
+            dblp_queries = (
+                [q for q in tt_prefix if q not in set(dblp_queries)] + dblp_queries
+            )
+        qtext = dblp_queries[0] if dblp_queries else venue_only
+    elif base_q:
+        qtext = base_q
+    else:
+        return []
+
+    n_cap = 1200 if strict_no_fallback else 500
+    if venue_only:
+        yf_db, yt_db = kwargs.get("year_from"), kwargs.get("year_to")
+        pinned_db = (
+            (
+                yf_db is not None
+                and yt_db is not None
+                and int(yf_db) == int(yt_db)
+                and 1900 <= int(yf_db) <= 2100
+            )
+            if yf_db is not None and yt_db is not None
+            else False
+        )
+        has_topic = bool(
+            base_q
+            and topic_terms_excluding_venue_year(
+                base_q,
+                venue=venue_only,
+                year=int(yf_db) if pinned_db else None,
+            )
+        )
+        if has_topic:
+            n_cap = 500 if strict_no_fallback else 300
+            n = min(max(max_results, 40), n_cap)
+        elif not base_q:
+            venue_browse = bool(kwargs.get("venue_browse"))
+            n_cap = 80 if (pinned_db and venue_browse) else (36 if pinned_db else 100)
+            n = min(max(40 if (pinned_db and venue_browse) else (20 if pinned_db else 30), max_results * 2), n_cap)
+        else:
+            n = min(max(1, max_results), n_cap)
+    else:
+        n = min(max(1, max_results), n_cap)
+
+    try:
+        max_attempts = max(
+            1,
+            min(
+                3,
+                int(
+                    kwargs.get("http_max_attempts")
+                    or os.getenv("PAPERGRAPH_DBLP_MAX_ATTEMPTS")
+                    or 2
+                ),
+            ),
+        )
+    except Exception:
+        max_attempts = 2
+    query_chain = dblp_queries if venue_only else [qtext]
+    dblp_req_to = max(
+        10.0,
+        min(
+            90.0,
+            float(
+                kwargs.get("dblp_timeout_sec")
+                or kwargs.get("http_timeout_sec")
+                or 35.0
+            ),
+        ),
+    )
+    headers = json_api_headers(searcher)
+    data, raw_hits = {}, None
+    for qi, cand_q in enumerate(query_chain):
+        qtext = cand_q
+        try:
+            r = await searcher._async_http_get_with_retry(
+                "https://dblp.org/search/publ/api",
+                params={
+                    "q": qtext.strip(),
+                    "format": "json",
+                    "h": n,
+                    "c": "0",
+                },
+                headers=headers,
+                timeout=dblp_req_to,
+                max_attempts=max_attempts,
+            )
+            data = r.json() or {}
+            raw_hits = ((data.get("result") or {}).get("hits") or {}).get("hit")
+            if raw_hits:
+                break
+        except Exception:
+            if qi + 1 >= len(query_chain):
+                logger.warning("[DBLP] async giving up q=%r", qtext)
+                searcher._bump_stat("dblp_requests")
+                return []
+            continue
+    if not raw_hits:
+        searcher._bump_stat("dblp_requests")
+        return []
+
+    raw_list = [raw_hits] if isinstance(raw_hits, dict) else list(raw_hits)
+    y_min = (
+        int(kwargs.get("year_from"))
+        if kwargs.get("year_from") is not None
+        else None
+    )
+    y_max = (
+        int(kwargs.get("year_to"))
+        if kwargs.get("year_to") is not None
+        else None
+    )
+    papers: List[Paper] = []
+    pinned_db = y_min is not None and y_max is not None and y_min == y_max
+
+    for hit in raw_list:
+        try:
+            info = (hit or {}).get("info") or {}
+            if str(info.get("type") or "").strip().lower() == "editorship":
+                continue
+            key = str(info.get("key") or "").strip()
+            if key.startswith("conf/"):
+                parts = key.split("/")
+                if len(parts) >= 3 and re.fullmatch(
+                    r"(?:19|20)\d{2}w?", parts[-1].strip().lower()
+                ):
+                    continue
+            title = (info.get("title") or "").strip() or "Unknown"
+            if not title:
+                continue
+            if bool(kwargs.get("main_conference_proceedings_only")):
+                from ....services.retrieval.paper_filters import is_stale_best_of_special
+                # Hard-reject obvious satellite tracks before LLM ranking.
+                tl = title.lower()
+                if re.search(r"\b(workshops?|symposium|symposia|tutorial|demo\s+track|satellite|challenge|ntire|pbvs|competition|contest)\b", tl):
+                    continue
+                y_pin = (
+                    int(kwargs.get("year_from"))
+                    if kwargs.get("year_from") is not None
+                    and kwargs.get("year_to") is not None
+                    and int(kwargs.get("year_from")) == int(kwargs.get("year_to"))
+                    else None
+                )
+                if is_stale_best_of_special(title, y_pin):
+                    continue
+            year = (
+                int(ys)
+                if (ys := str(info.get("year") or "").strip()).isdigit()
+                else None
+            )
+            if y_min is not None and year is not None and year < y_min:
+                continue
+            if y_max is not None and year is not None and year > y_max:
+                continue
+
+            raw_a = (info.get("authors") or {}).get("author", [])
+            if isinstance(raw_a, dict):
+                raw_a = [raw_a]
+            authors = [
+                Author(
+                    name=_DBLP_AUTHOR_SUFFIX_RE.sub("", (
+                        (a.get("text") or "").strip()
+                        if isinstance(a, dict)
+                        else str(a).strip()
+                    ))
+                )
+                for a in raw_a
+                if (
+                    a.get("text") if isinstance(a, dict) else str(a)
+                ).strip()
+            ]
+
+            ee = info.get("ee")
+            source_url, doi_guess, arxiv_guess, pdf_ee = _dblp_parse_ee_urls(ee)
+            if not source_url:
+                source_url = (info.get("url") or "").strip() or None
+            venue = (
+                str(info.get("venue")[0]).strip().upper()
+                if isinstance(info.get("venue"), list) and info.get("venue")
+                else (str(info.get("venue") or "").strip().upper() or None)
+            )
+            if key.startswith("conf/"):
+                parts = key.split("/")
+                if len(parts) >= 2:
+                    venue = parts[1].strip().upper()
+
+            papers.append(
+                searcher._make_paper(
+                    title=title,
+                    authors=authors,
+                    doi=doi_guess,
+                    arxiv_id=arxiv_guess,
+                    journal=venue or "DBLP",
+                    year=year,
+                    pdf_url=pdf_ee,
+                    source_url=source_url,
+                    source="dblp",
+                )
+            )
+        except Exception:
+            continue
+
+    searcher._bump_stat("dblp_requests")
+
+    # New-year DBLP metadata can lag; retry year-1 unless the year is pinned.
+    if not papers and y_min is not None and y_min >= datetime.now().year - 1:
+        skip_fallback = bool(kwargs.get("wants_recent")) or (
+            pinned_db and bool(kwargs.get("main_conference_proceedings_only"))
+        )
+        if not skip_fallback and y_min >= datetime.now().year:
+            logger.info(
+                "[DBLP] year=%s no results, retry year=%s", y_min, y_min - 1
+            )
+            return await search_dblp(
+                searcher,
+                query,
+                max_results,
+                **{
+                    **kwargs,
+                    "year_from": y_min - 1,
+                    "year_to": (
+                        y_min - 1
+                        if y_max == y_min
+                        else (y_max - 1 if y_max else None)
+                    ),
+                },
+            )
+
+    return papers
+
+
+async def _search_dblp_by_author_pid(searcher, author_name, max_results, kwargs):
+    if not author_name:
+        return None
+    try:
+        headers = json_api_headers(searcher)
+        ar = await searcher._async_client.get(
+            "https://dblp.org/search/author/api",
+            params={"q": author_name, "format": "json", "h": 5, "c": 0},
+            headers=headers,
+            timeout=25.0,
+        )
+        ar.raise_for_status()
+        hits = (
+            (((ar.json() or {}).get("result") or {}).get("hits") or {}).get("hit")
+            or []
+        )
+        if isinstance(hits, dict):
+            hits = [hits]
+
+        def _dblp_author_name(h: Any) -> str:
+            info = (h or {}).get("info") or {}
+            return str(info.get("display_name") or info.get("author") or "").strip()
+
+        def _dblp_author_bonus(h: Any, score: int) -> int:
+            url = str(((h or {}).get("info") or {}).get("url") or "").strip()
+            return score + (2 if "/pid/" in url else 0)
+
+        best_hit, best_pid_score = pick_best_name_match(
+            hits, author_name, display_name=_dblp_author_name, score_bonus=_dblp_author_bonus
+        )
+        pid_url = str(((best_hit or {}).get("info") or {}).get("url") or "").strip() if best_hit else ""
+        if pid_url and "/pid/" in pid_url:
+            from ....settings import get_settings
+
+            min_score = float(
+                getattr(get_settings(), "dblp_author_pid_min_score", 3.0) or 3.0
+            )
+            if best_pid_score < min_score:
+                pid_url = ""
+            else:
+                pr = await searcher._async_client.get(
+                    pid_url + ".xml",
+                    headers={"User-Agent": headers["User-Agent"]},
+                    timeout=25.0,
+                )
+                pr.raise_for_status()
+                root = ET.fromstring(pr.text)
+        else:
+            root = None
+
+        papers: List[Paper] = []
+        if root is not None:
+            for rnode in list(root.findall("./r")):
+                if len(papers) >= max_results:
+                    break
+                try:
+                    pub = next(
+                        (child for child in rnode if child.tag), None
+                    )
+                    if pub is None:
+                        continue
+                    title = (
+                        (pub.findtext("title") or "").strip() or "Unknown"
+                    )
+                    year = (
+                        int(yt)
+                        if (
+                            yt := (pub.findtext("year") or "").strip()
+                        ).isdigit()
+                        else None
+                    )
+                    yf = kwargs.get("year_from")
+                    if yf is not None and year is not None and year < int(yf):
+                        continue
+                    venue = (
+                        pub.findtext("booktitle")
+                        or pub.findtext("journal")
+                        or ""
+                    ).strip().upper() or None
+                    authors = [
+                        Author(name=_DBLP_AUTHOR_SUFFIX_RE.sub("", (a.text or "").strip()))
+                        for a in pub.findall("author")
+                        if (a.text or "").strip()
+                    ]
+                    ee = (pub.findtext("ee") or "").strip() or None
+                    url_text = (
+                        (pub.findtext("url") or "").strip() or None
+                    )
+                    papers.append(
+                        searcher._make_paper(
+                            title=title,
+                            authors=authors,
+                            journal=venue or "DBLP",
+                            year=year,
+                            source_url=ee or url_text,
+                            source="dblp",
+                        )
+                    )
+                except Exception:
+                    continue
+        return papers
+    except Exception:
+        return None

+ 490 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/openalex.py

@@ -0,0 +1,490 @@
+"""OpenAlex source adapter for PaperSearcher."""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from ...author import Author
+from ...paper import Paper
+from .source_common import author_names_for_api, pick_best_name_match
+from ..normalize import (
+    _arxiv_pdf_url_from_id,
+    _openalex_human_source_url,
+    _openalex_resolve_pdf_url,
+    _venue_canonical_key,
+    arxiv_id_from_doi,
+    extract_pinned_topic_terms,
+    plain_query_for_text_apis,
+    sanitize_search_keyword_list,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _openalex_inverted_index_to_text(inv: dict[str, Any | None]) -> str | None:
+    """Restore OpenAlex inverted-index abstracts."""
+    if not inv:
+        return None
+    try:
+        slot: dict[int, str] = {}
+        for word, positions in inv.items():
+            for pos in positions:
+                slot[int(pos)] = str(word)
+        if not slot:
+            return None
+        return " ".join(slot[i] for i in sorted(slot)).strip() or None
+    except (ValueError, TypeError, AttributeError):
+        return None
+
+
+def _score_openalex_venue_item(v_query: str, it: Dict[str, Any]) -> int:
+    """Score an OpenAlex venue hit against the query."""
+    vq = (v_query or "").strip().lower()
+    dn = str(it.get("display_name") or "").lower()
+    ab = str(it.get("abbreviated_title") or "").lower()
+    score = 3 if (can := _venue_canonical_key(v_query)) and len(str(can)) >= 3 and str(can) in f"{dn} {ab}" else 0
+    return score + 2 if len(vq) >= 4 and vq in dn else score
+
+
+def _pick_openalex_venue_id_from_items(v2: str, items: List[Dict[str, Any]]) -> Optional[str]:
+    """Pick the best venue ID from OpenAlex hits."""
+    if not items:
+        return None
+    best_id, best_sc = None, -1
+    for it in items:
+        try:
+            if not (vid := str(it.get("id") or "").strip()):
+                continue
+            if (sc := _score_openalex_venue_item(v2, it)) > best_sc:
+                best_sc, best_id = sc, vid
+        except Exception:
+            continue
+    if best_id is not None and best_sc > 0:
+        return best_id
+    target = (_venue_canonical_key(v2) or v2.split()[0]).lower().strip()
+    chosen = None
+    for it in items:
+        try:
+            if not (vid := str(it.get("id") or "").strip()):
+                continue
+            dn = str(it.get("display_name") or "").lower()
+            ab = str(it.get("abbreviated_title") or "").lower()
+            if target and (target in dn or target in ab):
+                return vid
+            if not chosen:
+                chosen = vid
+        except Exception:
+            continue
+    return chosen
+
+
+def _title_matches_venue_signals(
+    title: str,
+    venue_canonical: str,
+    venue_raw: str,
+    abstract: Optional[str],
+    notes: str,
+) -> bool:
+    """Fallback venue check across title, abstract, and notes."""
+    v = venue_raw.lower().strip()
+    if not v:
+        return True
+    can = (venue_canonical or "").lower().strip()
+    blob = f"{title} {abstract or ''} {notes}".lower()
+    if can and len(can) >= 2 and can in blob:
+        return True
+    if len(v) >= 4 and v in blob:
+        return True
+    return False
+
+
+def _is_openalex_listing_title(title: str) -> bool:
+    """Reject proceedings/listing records, not individual papers."""
+    t = (title or "").strip().lower()
+    if not t or len(t) < 15:
+        return True
+    if re.search(r"(?i)^(\d{4}\s+)?(ieee/cvf\s+)?conference on computer vision", t):
+        return True
+    if re.search(r"(?i)^computer vision and pattern recognition\b", t) and (
+        "proceedings" in t or len(t) < 90
+    ):
+        return True
+    if re.search(r"(?i)^proceedings of\b", t):
+        return True
+    return False
+
+
+def _extract_openalex_papers(searcher, results: list, max_results: int, **kwargs) -> List[Paper]:
+    """Convert OpenAlex works into Paper objects."""
+    papers: List[Paper] = []
+    for w in results:
+        try:
+            title = (w.get("title") or "").strip() or "Unknown"
+            if _is_openalex_listing_title(title):
+                continue
+            authors = [
+                Author(name=(au.get("display_name") or "").strip())
+                for a in (w.get("authorships") or [])[:80]
+                if (au := (a or {}).get("author") or {}) and (au.get("display_name") or "").strip()
+            ]
+            if not authors:
+                continue
+            if str(w.get("type") or "").strip().lower() in ("proceedings", "book", "report"):
+                continue
+            doi = str(doi_raw).replace("https://doi.org/", "").strip() if (doi_raw := w.get("doi")) else None
+            year = w.get("publication_year")
+            abstract = _openalex_inverted_index_to_text(w.get("abstract_inverted_index"))
+            pl = w.get("primary_location") or {}
+            venue = ((pl.get("source") or {}).get("display_name") or "").strip() or None
+            if not venue:
+                hv = w.get("host_venue") or {}
+                if isinstance(hv, dict):
+                    venue = (hv.get("display_name") or "").strip() or None
+            if not venue:
+                for loc in (w.get("locations") or [])[:20]:
+                    if isinstance(loc, dict) and (lsrc := loc.get("source", {}) if isinstance(loc.get("source"), dict) else {}):
+                        if cand := (lsrc.get("display_name") or "").strip():
+                            venue = cand
+                            break
+            pdf_url = _openalex_resolve_pdf_url(w)
+            arxiv_id_oa = None
+            ids_obj = w.get("ids") or {}
+            if isinstance(ids_obj, dict):
+                axu = ids_obj.get("arxiv")
+                if isinstance(axu, str):
+                    if "arxiv.org/abs/" in axu.lower():
+                        arxiv_id_oa = axu.split("arxiv.org/abs/", 1)[-1].strip().rstrip("/")
+                    elif "arxiv.org/pdf/" in axu.lower():
+                        raw = axu.split("arxiv.org/pdf/", 1)[-1].strip().rstrip("/")
+                        arxiv_id_oa = raw[:-4] if raw.lower().endswith(".pdf") else raw
+            if not arxiv_id_oa:
+                arxiv_id_oa = arxiv_id_from_doi(doi)
+            if not pdf_url and arxiv_id_oa:
+                pdf_url = _arxiv_pdf_url_from_id(arxiv_id_oa)
+            source_url = _openalex_human_source_url(w, doi)
+            citations = int(w.get("cited_by_count") or 0)
+            concepts = [
+                str(c["display_name"])
+                for c in (w.get("concepts") or [])[:10]
+                if isinstance(c, dict) and c.get("display_name")
+            ]
+            papers.append(
+                searcher._make_paper(
+                    title=title,
+                    authors=authors,
+                    abstract=abstract,
+                    doi=doi,
+                    arxiv_id=arxiv_id_oa,
+                    journal=venue or "OpenAlex",
+                    year=year,
+                    pdf_url=pdf_url,
+                    source_url=source_url,
+                    citations=citations,
+                    keywords=concepts,
+                    source="openalex",
+                )
+            )
+            if len(papers) >= max_results:
+                break
+        except Exception:
+            continue
+    return papers
+
+
+async def _search_openalex_works_by_author_async(
+    searcher, author_names: list[str], max_results: int, **kwargs: Any
+) -> list[Paper]:
+    """Resolve author IDs, then fetch their works."""
+    search_candidates = author_names_for_api(author_names)
+    if not search_candidates:
+        return []
+    headers = searcher._openalex_headers()
+
+    from ....services.retrieval.source_plan import openalex_publication_year_filter
+
+    year_filt = openalex_publication_year_filter(kwargs.get("year_from"), kwargs.get("year_to"))
+
+    best_aid, best_score = "", -1
+    for cand in search_candidates[:4]:
+        try:
+            ar = await searcher._async_client.get(
+                "https://api.openalex.org/authors",
+                params=searcher._openalex_params({"search": cand, "per_page": 8}),
+                headers=headers,
+                timeout=22.0,
+            )
+            ar.raise_for_status()
+            hits = [h for h in list((ar.json() or {}).get("results") or []) if isinstance(h, dict)]
+            best_hit, score = pick_best_name_match(
+                hits,
+                cand,
+                display_name=lambda h: str(h.get("display_name") or "").strip(),
+                score_bonus=lambda h, s: s + min(3, int(h.get("works_count") or 0) // 200),
+            )
+            if best_hit and score > best_score:
+                best_score, best_aid = score, str(best_hit.get("id") or "").strip()
+        except Exception:
+            continue
+    if not best_aid:
+        return []
+
+    from ....settings import get_settings
+
+    if best_score < float(getattr(get_settings(), "openalex_author_match_min_score", 2.0) or 2.0):
+        return []
+    short_id = best_aid.rsplit("/", 1)[-1]
+    params = searcher._openalex_params({
+        "filter": f"authorships.author.id:{short_id}",
+        "sort": "publication_date:desc",
+        "per_page": min(max(1, max_results), 200),
+    })
+    if year_filt:
+        params["filter"] = f"{params['filter']},{year_filt}"
+    try:
+        wr = await searcher._async_client.get(
+            "https://api.openalex.org/works",
+            params=params,
+            headers=headers,
+            timeout=28.0,
+        )
+        wr.raise_for_status()
+        results = list((wr.json() or {}).get("results") or [])
+    except Exception:
+        return []
+
+    return _extract_openalex_papers(searcher, results, max_results)
+
+
+async def _openalex_resolve_venue_id_async(
+    searcher, venue_raw: str, headers: Optional[Dict[str, str]] = None
+) -> Optional[str]:
+    """Resolve a venue name to an OpenAlex venue ID."""
+    v = (venue_raw or "").strip().lower()
+    if not v:
+        return None
+    v2 = re.sub(r"\b(19|20)\d{2}\b", "", v).strip() or v
+    try:
+        r = await searcher._async_client.get(
+            "https://api.openalex.org/venues",
+            params=searcher._openalex_params({"search": v2, "per_page": 5}),
+            h=headers or searcher._openalex_headers(),
+            timeout=25.0,
+        )
+        r.raise_for_status()
+        return _pick_openalex_venue_id_from_items(
+            v2, list((r.json() or {}).get("results") or [])
+        )
+    except Exception:
+        return None
+
+
+async def search_openalex(
+    searcher, query: str, max_results: int = 10, **kwargs
+) -> List[Paper]:
+    """Search OpenAlex using pipeline constraints."""
+    await searcher._ensure_async_client()
+    await searcher._rate_limit_async("openalex")
+
+    per_page = min(max(1, max_results), 200)
+    venue_raw = (kwargs.get("venue") or "").strip() or None
+    venue_s = (venue_raw or "").strip()
+    vpj = searcher._resolve_vpj(venue_raw, kwargs)
+
+    from ....services.retrieval.source_plan import openalex_publication_year_filter
+
+    yf_int = int(kwargs.get("year_from")) if kwargs.get("year_from") is not None else None
+    yt_int = int(kwargs.get("year_to")) if kwargs.get("year_to") is not None else None
+    year_filt = openalex_publication_year_filter(yf_int, yt_int)
+    pinned_venue_single_year = bool(
+        venue_s and yf_int and yt_int and yf_int == yt_int and 1900 <= yf_int <= 2100
+    )
+
+    base_q = (plain_query_for_text_apis(query, kwargs) or "").strip()
+    if pinned_venue_single_year:
+        pin_q = f"{venue_s} {yf_int}".strip()
+        topic_raw = kwargs.get("pinned_topic_terms") or []
+        topic_str = (
+            (
+                " ".join(str(x).strip() for x in topic_raw if str(x).strip())[:120]
+                if topic_raw
+                else extract_pinned_topic_terms(
+                    query=query,
+                    merged_kw=sanitize_search_keyword_list(kwargs.get("llm_keywords")),
+                    venue=venue_s,
+                    year=yf_int,
+                )
+            )
+        )
+        if topic_str and topic_str.lower() not in (base_q or "").lower():
+            base_q = f"{topic_str} {base_q or pin_q}".strip()[:180]
+        if not base_q or len(base_q) < 4:
+            base_q = f"{topic_str} {pin_q}".strip()[:180] if topic_str else pin_q
+        elif venue_s.lower() not in base_q.lower():
+            can_key = (_venue_canonical_key(venue_s) or "").lower()
+            if not can_key or can_key not in base_q.lower():
+                base_q = f"{topic_str} {pin_q}".strip()[:180] if topic_str else pin_q
+            elif str(yf_int) not in base_q:
+                base_q = f"{base_q} {yf_int}".strip()[:180]
+    qtext = (base_q if base_q else venue_s or "").strip()
+    if pinned_venue_single_year and (not qtext or qtext == "*"):
+        qtext = f"{venue_s} {yf_int}".strip()
+
+    try:
+        qtext_clean = re.sub(
+            r"\s+", " ",
+            re.sub(r"[^\w\s\-\./]+", " ", qtext, flags=re.UNICODE),
+        ).strip()[:180]
+    except Exception:
+        qtext_clean = (qtext or "").strip()[:180]
+
+    star_q = qtext in ("*", "")
+    main_track_oa = bool(venue_s and vpj and kwargs.get("main_conference_proceedings_only"))
+
+    if pinned_venue_single_year and main_track_oa and venue_s and yf_int:
+        headers = searcher._openalex_headers()
+        vid = await _openalex_resolve_venue_id_async(searcher, venue_s, headers=headers)
+        if vid:
+            try:
+                browse_mult = 5 if kwargs.get("venue_browse") else 3
+                browse_n = min(max(per_page, max_results * browse_mult), 200)
+                if kwargs.get("venue_browse"):
+                    browse_n = max(browse_n, 80)
+                oa_params = searcher._openalex_params({
+                    "filter": f"publication_year:{yf_int},host_venue.id:{vid}",
+                    "per_page": browse_n,
+                    "sort": "cited_by_count:desc",
+                })
+                resp = await searcher._async_http_get_with_retry(
+                    "https://api.openalex.org/works",
+                    params=oa_params,
+                    headers=headers,
+                    timeout=float(kwargs.get("openalex_timeout_sec") or 45.0),
+                    max_attempts=2,
+                )
+                browse_results = list((resp.json() or {}).get("results") or [])
+                browse_papers = _extract_openalex_papers(
+                    searcher, browse_results, max(browse_n, max_results)
+                )
+                from ....services.retrieval.paper_filters import is_obvious_workshop_track
+
+                browse_papers = [
+                    p
+                    for p in browse_papers
+                    if not is_obvious_workshop_track(p, venue_s)
+                ]
+                if browse_papers:
+                    searcher._bump_stat("openalex_requests")
+                    return browse_papers[:max_results]
+            except Exception:
+                logger.warning(
+                    "[OpenAlex] host_venue browse failed venue=%s year=%s",
+                    venue_s,
+                    yf_int,
+                    exc_info=True,
+                )
+
+    if star_q and (pinned_venue_single_year or main_track_oa):
+        star_q = False
+        qtext = (
+            f"{venue_s} {yf_int}".strip()
+            if pinned_venue_single_year and yf_int
+            else (venue_s or qtext)
+        )
+        try:
+            qtext_clean = re.sub(
+                r"\s+", " ",
+                re.sub(r"[^\w\s\-\./]+", " ", qtext, flags=re.UNICODE),
+            ).strip()[:180]
+        except Exception:
+            qtext_clean = (qtext or "").strip()[:180]
+
+    if star_q:
+        if yf_int is None and year_filt is None:
+            yf_int = datetime.now().year - 1
+            year_filt = f"publication_year:>={yf_int}"
+        filt = year_filt or f"publication_year:>={yf_int}"
+        ocid = (kwargs.get("openalex_concept_id") or "").strip()
+        if ocid and filt:
+            filt = f"{filt},concept.id:{ocid if ocid.startswith('http') else f'https://openalex.org/{ocid}'}"
+        params: Dict[str, Any] = searcher._openalex_params({
+            "per_page": per_page,
+            "sort": "publication_date:desc",
+        })
+        if filt:
+            params["filter"] = filt
+    else:
+        params = searcher._openalex_params({
+            "search": qtext_clean or qtext,
+            "per_page": per_page,
+        })
+        if year_filt:
+            params["filter"] = year_filt
+
+    headers = searcher._openalex_headers()
+    oa_retry_without_host_venue = (
+        kwargs.get("venue_fallback_if_empty", True)
+        or kwargs.get("openalex_relax_host_venue_on_empty", True)
+    )
+
+    async def _do_request(with_venue_filter: bool) -> List[Dict[str, Any]]:
+        local_params = dict(params)
+        if with_venue_filter and venue_raw and vpj:
+            vid = await _openalex_resolve_venue_id_async(searcher, venue_raw, headers=headers)
+            if vid:
+                prev = (local_params.get("filter") or "").strip()
+                local_params["filter"] = f"{prev},host_venue.id:{vid}" if prev else f"host_venue.id:{vid}"
+        resp = await searcher._async_client.get(
+            url="https://api.openalex.org/works",
+            params=local_params,
+            headers=headers,
+            timeout=45.0,
+        )
+        if resp.status_code == 400 and (local_params.get("search") or local_params.get("filter")):
+            lp2 = dict(local_params)
+            lp2["search"] = qtext_clean or str(lp2.get("search") or "")
+            lp2.pop("filter", None)
+            if year_filt:
+                lp2["filter"] = year_filt
+            resp = await searcher._async_client.get(
+                url="https://api.openalex.org/works",
+                params=lp2,
+                headers=headers,
+                timeout=45.0,
+            )
+        resp.raise_for_status()
+        return list((resp.json() or {}).get("results") or [])
+
+    results = await _do_request(with_venue_filter=bool(venue_raw and vpj))
+    if venue_raw and vpj and not results and oa_retry_without_host_venue:
+        results = await _do_request(with_venue_filter=False)
+
+    if star_q and not results and (kwargs.get("openalex_concept_id") or "").strip() and "concept.id:" in str(params.get("filter", "")):
+        yf_b = yf_int if yf_int is not None else datetime.now().year - 1
+        params["filter"] = f"publication_year:>={yf_b}"
+        results = await _do_request(with_venue_filter=bool(venue_raw and vpj))
+        if venue_raw and vpj and not results and oa_retry_without_host_venue:
+            results = await _do_request(with_venue_filter=False)
+
+    papers = _extract_openalex_papers(searcher, results, max_results)
+
+    if main_track_oa and venue_raw and papers:
+        matched = [p for p in papers if searcher._paper_matches_venue(p, venue_raw)]
+        if not matched:
+            can = _venue_canonical_key(venue_raw)
+            matched = [
+                p for p in papers
+                if _title_matches_venue_signals(
+                    getattr(p, "title", "") or "",
+                    can,
+                    venue_raw,
+                    getattr(p, "abstract", None),
+                    getattr(p, "notes", None) or "",
+                )
+            ]
+        papers = matched
+
+    searcher._bump_stat("openalex_requests")
+    return papers

+ 57 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/source_common.py

@@ -0,0 +1,57 @@
+"""搜索源公共基类 —— 通用过滤/去重/超时控制与结果标准化."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+from ....utils.author_query_match import normalize_author_names
+from ....utils.common import text_has_cjk
+from ..normalize import _score_name_match
+from ..paper_searcher import _sanitize_author_list_for_query
+
+T = TypeVar("T")
+
+
+def json_api_headers(searcher, *, accept: str = "application/json") -> dict[str, str]:
+    return {"User-Agent": searcher._user_agent(), "Accept": accept}
+
+
+def normalize_query_authors(query: str, raw_authors: Any) -> list[str]:
+    if isinstance(raw_authors, str):
+        raw_authors = [raw_authors]
+    return normalize_author_names(
+        [
+            str(x).strip()
+            for x in (_sanitize_author_list_for_query(query, raw_authors or []) or [])
+            if str(x).strip()
+        ]
+    )
+
+
+def author_names_for_api(names: list[str]) -> list[str]:
+    latin = [n for n in names if n.strip() and not text_has_cjk(n)]
+    return latin or [n for n in names if n.strip()]
+
+
+def pick_best_name_match(
+    items: list[T],
+    query_name: str,
+    *,
+    display_name: Callable[[T], str],
+    score_bonus: Callable[[T, int], int] | None = None,
+) -> tuple[T | None, int]:
+    best: T | None = None
+    best_score = -1
+    for it in items:
+        try:
+            dn = display_name(it)
+            if not dn:
+                continue
+            score = _score_name_match(dn, query_name)
+            if score_bonus:
+                score = score_bonus(it, score)
+            if score > best_score:
+                best_score, best = score, it
+        except Exception:
+            continue
+    return best, best_score

+ 341 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/search/sources/tavily.py

@@ -0,0 +1,341 @@
+"""Tavily 搜索适配器 —— Web 预搜索与会议官网探测."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _is_noise_title(title: str) -> bool:
+    """Reject obvious page/listing titles."""
+    t = title.strip()
+    if not t or len(t) < 12 or len(t) > 300:
+        return True
+    low = t.lower()
+    if low in {"proceedings", "list of proceedings", "accepted papers", "neurips", "nips"}:
+        return True
+    if re.match(r"(?i)^(cvpr|iccv|eccv)\s*\d{4}\s*$", t):
+        return True
+    if re.search(r"(?i)open access repository", t):
+        return True
+    return False
+
+
+async def _llm_filter_relevant(
+    papers: list[dict[str, Any]], query: str, venue: str, limit: int,
+) -> list[dict[str, Any]]:
+    """Keep the most query-relevant extracted papers."""
+    if not papers or len(papers) <= limit:
+        return papers
+    try:
+        from ....services.llm.llm_service import get_llm, is_llm_configured
+        from ....services.llm.agent_runtime import run_json_task
+
+        if not is_llm_configured():
+            return papers[:limit]
+    except Exception:
+        return papers[:limit]
+
+    titles = [f"[{i}] {p['title']}" for i, p in enumerate(papers)]
+    prompt = (
+        f"用户搜索:{query}\n"
+        f"会议:{venue}\n"
+        "以下是论文标题列表。选出与搜索主题最相关的论文(最多" + str(limit) + "篇)。\n"
+        "输出 JSON:{\"relevant\":[0,3,5,...]}(保留的索引号,从0开始,按相关度降序)\n\n"
+        + "\n".join(titles)
+    )
+    try:
+        data = await asyncio.to_thread(
+            lambda: run_json_task(
+                task_name="paper_relevance_filter",
+                agent_name="papergraph_relevance_filter",
+                llm=get_llm(),
+                system_prompt="你是学术论文相关性判断器。严格筛选,只输出合法JSON。",
+                user_prompt=prompt,
+                timeout_sec=8,
+                retries=0,
+                default={"relevant": list(range(min(limit, len(papers))))},
+            )
+        )
+    except Exception:
+        return papers[:limit]
+    indices = data.get("relevant") if isinstance(data, dict) else list(range(len(papers)))
+    if not isinstance(indices, list):
+        return papers[:limit]
+    result = [papers[i] for i in indices if isinstance(i, int) and 0 <= i < len(papers)]
+    return result[:limit] if result else papers[:limit]
+
+
+def _clean_abstract(text: str) -> str:
+    """Remove citation/HTML boilerplate from snippets."""
+    t = (text or "").strip()
+    if not t:
+        return ""
+    t = re.sub(r"@\w+\{[^}]*\}?", "", t, flags=re.S)
+    # BibTeX field fragments can appear without closing braces.
+    t = re.sub(r",?\s*\b(author|title|booktitle|journal|year|pages|volume|number|publisher|editor|series|address|month|note|url|doi|isbn)\s*=\s*\{[^}]*\}?,?", "", t, flags=re.I)
+    t = re.sub(r"These (?:CVPR|ICCV|ECCV)\s*(?:20\d{2})?\s*papers are the Open Access versions?, provided by the Computer Vision Foundation\.?", "", t, flags=re.I)
+    t = re.sub(r"Except for the watermark,? they are identical to the accepted versions?;? the final published version of the proceedings is available on IEEE Xplore\.?", "", t, flags=re.I)
+    t = re.sub(r"All persons copying this information are expected to adhere to the terms and constraints invoked by each author'?s? copyright\.?", "", t, flags=re.I)
+    t = re.sub(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}", "", t)
+    t = re.sub(r"https?://\S+", "", t)
+    t = re.sub(r"\(?(?:CVPR|ICCV|ECCV|NeurIPS|ICLR|ICML|AAAI|IJCAI|ACL|EMNLP|NAACL|SIGIR|KDD)\)?\s*(?:Workshops?|Conference|Proceedings)?,?\s*(?:19|20)\d{2},?\s*pp?\.?\s*[\d\-–]+\.?", "", t, flags=re.I)
+    t = re.sub(r"\bpp\.\s*[\d\-–]+\b", "", t)
+    t = re.sub(r"\bvol\.?\s*\d+\b", "", t)
+    t = re.sub(r"<[^>]+>", " ", t)
+    t = re.sub(r"&#?\w+;", " ", t)
+    t = re.sub(r"\{\s*\}", "", t)
+    t = re.sub(r"\s{2,}", " ", t)
+    t = re.sub(r",\s*,", ",", t)
+    t = t.strip(" ,;:")
+    if not t or len(t) < 30:
+        return ""
+    if re.match(r"(?i)(all persons copying|these \w+ papers are|except for the watermark)", t):
+        return ""
+    return t[:800] if len(t) > 800 else t
+
+
+async def _llm_extract_papers_from_raw(
+    raw_text: str,
+    *,
+    query: str,
+    venue: str = "",
+    year: Any = None,
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    """Extract paper records from raw Tavily page text."""
+    try:
+        from ....services.llm.llm_service import get_llm, is_llm_configured
+        from ....services.llm.agent_runtime import run_json_task
+
+        if not is_llm_configured():
+            return []
+    except Exception:
+        return []
+
+    cleaned = re.sub(r"<[^>]+>", " ", raw_text or "")
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()[:14000]
+    if len(cleaned) < 100:
+        return []
+
+    prompt = (
+        "从下面的网页文本中提取学术论文的标题、作者和摘要。\n"
+        "文本中可能混有 BibTeX 引用、版权声明等。只抽取真实论文信息。\n"
+        "标题是研究成果名称,摘要是一段连续的学术描述文字。\n"
+        "不要抽取:论文集名称、导航链接、Workshop/Challenge/Tutorial 论文、\n"
+        "版权声明、BibTeX 字段值、残缺文字。\n"
+        f"用户搜索主题:{query}。只提取与主题相关的论文。\n"
+        f"会议:{venue or '未知'},年份:{year or '未知'},最多 {limit} 篇。\n"
+        '输出 JSON:{"papers":[{"title":"...","authors":["..."],"abstract":"..."}]}\n\n'
+        f"页面文本:\n{cleaned}"
+    )
+    try:
+        data = await asyncio.to_thread(
+            lambda: run_json_task(
+                task_name="tavily_page_extract",
+                agent_name="papergraph_tavily_extractor",
+                llm=get_llm(),
+                system_prompt="你是严格的信息抽取器。只输出合法 JSON,不得编造文本中不存在的论文。",
+                user_prompt=prompt,
+                timeout_sec=15,
+                retries=0,
+                default={"papers": []},
+            )
+        )
+    except Exception:
+        return []
+    arr = data.get("papers") if isinstance(data, dict) else []
+    if not isinstance(arr, list):
+        return []
+    out: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for it in arr:
+        if not isinstance(it, dict):
+            continue
+        title = str(it.get("title") or "").strip()
+        title = re.sub(r"^\s*\[PDF\]\s*", "", title, flags=re.I)
+        title = re.sub(r"^\s*#+\s*", "", title)
+        title = re.sub(r"\s+", " ", title).strip()
+        if len(title) < 8 or len(title) > 300:
+            continue
+        key = title.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        authors = it.get("authors") if isinstance(it.get("authors"), list) else []
+        out.append({"title": title, "authors": [str(a)[:120] for a in authors[:12] if str(a).strip()]})
+        if len(out) >= limit:
+            break
+
+    # Keep LLM extraction broad, then trim by relevance.
+    if len(out) > limit // 2:
+        out = await _llm_filter_relevant(out, query, venue, limit)
+    return out
+
+
+async def _tavily_proceedings_fetch(
+    *,
+    api_key: str,
+    query: str,
+    domains: list[str] | None,
+    max_results: int,
+    httpx_client: Any,
+    searcher: Any,
+    year: Any,
+    journal: str = "",
+) -> list:
+    from ....services.retrieval.web_presearch import tavily_search_async as _tv
+
+    n = max(1, min(10, int(max_results or 5)))
+    items = await _tv(
+        api_key=api_key, query=query, max_results=n,
+        include_domains=domains, httpx_client=httpx_client,
+    )
+    if not items and domains:
+        items = await _tv(
+            api_key=api_key, query=query, max_results=n,
+            include_domains=None, httpx_client=httpx_client,
+        )
+
+    papers: list = []
+    for it in items or []:
+        title = str(it.get("title") or "").strip()
+        link = str(it.get("link") or it.get("url") or "").strip()
+        raw = str(it.get("raw_content") or "")
+        snippet = str(it.get("content") or it.get("snippet") or "")
+
+        llm_papers = await _llm_extract_papers_from_raw(
+            raw, query=query or "", venue=journal, year=year, limit=max_results,
+        )
+        for lp in llm_papers:
+            t = lp["title"].strip()
+            if _is_noise_title(t):
+                continue
+            tl = t.lower()
+            if any(w in tl for w in ("workshop", "challenge", "tutorial", "demo track", "competition")):
+                continue
+            abs_text = _clean_abstract(lp.get("abstract", ""))
+            if not abs_text:
+                abs_text = _clean_abstract(snippet)
+            papers.append(
+                searcher._make_paper(
+                    title=t,
+                    authors=lp.get("authors", []),
+                    abstract=abs_text,
+                    source_url=link,
+                    source="tavily",
+                    journal=journal or None,
+                    year=int(year) if year else None,
+                )
+            )
+        # Empty extraction usually means the page is not a paper listing.
+    return papers
+
+
+async def search_tavily_proceedings(
+    searcher: Any,
+    query: str,
+    venue: str,
+    year: Any,
+    max_results: int,
+    *,
+    venue_browse: bool = False,
+) -> list:
+    """会议官网召回:优先配置域名;不足则 Tavily 自动发现站点再搜对应年份论文。"""
+    try:
+        from ....settings import get_settings as _gs
+        from ....services.retrieval.tavily_venue_config import tavily_include_domains_for_venue as _td
+        from ....services.retrieval.proceedings_discovery import discover_proceedings_domains
+
+        _ak = getattr(_gs(), "tavily_api_key", "").strip()
+        if not _ak:
+            return []
+
+        _client = await searcher._ensure_async_client()
+        year_i = int(year) if year is not None else None
+        topic = (query or "").strip()
+        if topic.lower() == (venue or "").strip().lower():
+            topic = ""
+        base_q = f"{venue} {year_i} proceedings {topic}".strip() if year_i else f"{venue} proceedings {topic}".strip()
+        _q = base_q.strip() or f"{venue} {year_i or ''} papers".strip()
+
+        static_dom = list(_td(venue) or [])
+        domains = static_dom[:3]
+
+        if not domains:
+            domains = await discover_proceedings_domains(
+                api_key=_ak, venue=venue, year=year_i,
+                httpx_client=_client, max_domains=3,
+            )
+
+        journal = venue.strip().upper()
+        papers: list = []
+        if venue_browse:
+            browse_queries = [
+                f"{venue} {year_i} main conference accepted papers",
+                f"{venue} {year_i} oral papers proceedings",
+                f"{venue} {year_i} conference papers list",
+            ]
+            seen_titles: set[str] = set()
+            for bq in browse_queries:
+                batch = await _tavily_proceedings_fetch(
+                    api_key=_ak, query=bq, domains=domains or None,
+                    max_results=10, httpx_client=_client,
+                    searcher=searcher, year=year, journal=journal,
+                )
+                for p in batch:
+                    t = (getattr(p, "title", None) or "").strip().lower()
+                    if t and t not in seen_titles:
+                        seen_titles.add(t)
+                        papers.append(p)
+                if len(papers) >= max(20, int(max_results)):
+                    break
+        else:
+            seen_titles: set[str] = set()
+            for tq in [base_q]:
+                batch = await _tavily_proceedings_fetch(
+                    api_key=_ak, query=tq, domains=domains or None,
+                    max_results=max_results, httpx_client=_client,
+                    searcher=searcher, year=year, journal=journal,
+                )
+                for p in batch:
+                    t = (getattr(p, "title", None) or "").strip().lower()
+                    if t and t not in seen_titles:
+                        seen_titles.add(t)
+                        papers.append(p)
+
+        if not papers and not domains:
+            papers = await _tavily_proceedings_fetch(
+                api_key=_ak,
+                query=f"{venue} {year_i or ''} official conference papers accepted".strip(),
+                domains=None, max_results=max_results,
+                httpx_client=_client, searcher=searcher, year=year, journal=journal,
+            )
+
+        if not papers:
+            discovered = await discover_proceedings_domains(
+                api_key=_ak, venue=venue, year=year_i,
+                httpx_client=_client, max_domains=3,
+            )
+            if discovered:
+                extra = await _tavily_proceedings_fetch(
+                    api_key=_ak, query=_q, domains=discovered,
+                    max_results=max_results, httpx_client=_client,
+                    searcher=searcher, year=year, journal=journal,
+                )
+                if len(extra) > len(papers):
+                    papers = extra
+                    logger.info(
+                        "[tavily_proceedings] venue=%s year=%s rediscovered domains=%s -> %d papers",
+                        venue, year_i, discovered, len(papers),
+                    )
+
+        searcher._bump_stat("total_results", len(papers))
+        return papers
+    except Exception as e:
+        logger.warning("[tavily_proceedings] failed venue=%s year=%s: %s", venue, year, e)
+        return []

+ 725 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/core/storage.py

@@ -0,0 +1,725 @@
+"""本地存储服务 —— JSON/SQLite 文件持久化与数据备份."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sqlite3
+from collections import defaultdict
+from contextlib import contextmanager, suppress
+from typing import Any
+
+from .author import Author
+from .paper import Paper
+from .paper_paths import LIBRARY_PDF_ROOT_DIR, category_slug_for_pdf_dir
+from ..settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+class PaperDatabase:
+    """SQLite 论文数据库 —— 论文 CRUD、全文搜索(FTS)、分类与标签管理."""
+
+    def __init__(self, db_path: str | None = None) -> None:
+        if db_path is None:
+            db_path = os.path.join(os.path.abspath(get_settings().data_dir), "papers.db")
+
+        self.db_path = db_path
+        self._library_fts_ready = False
+        self._ensure_directory()
+        self._init_database()
+        self._library_fts_ready = self._detect_fts_table()
+
+    def _data_root(self) -> str:
+        return os.path.dirname(os.path.abspath(self.db_path))
+
+    def _abs_local_pdf(self, relpath: str | None) -> str | None:
+        if not relpath or not str(relpath).strip():
+            return None
+        return os.path.normpath(os.path.join(self._data_root(), str(relpath).strip()))
+
+    def _ensure_directory(self) -> None:
+        os.makedirs(os.path.dirname(self.db_path), exist_ok=True)
+
+    def _detect_fts_table(self) -> bool:
+        try:
+            return self._query(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='papers_fts' LIMIT 1",
+                fetch='one'
+            ) is not None
+        except Exception:
+            return False
+
+    @contextmanager
+    def _get_connection(self):
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+            conn.commit()
+        except Exception as e:
+            conn.rollback()
+            logger.error("Database transaction failed: %s", e)
+            raise
+        finally:
+            conn.close()
+
+    def _query(self, sql, params=(), fetch='all'):
+        with self._get_connection() as conn:
+            cur = conn.cursor()
+            cur.execute(sql, params)
+            if fetch == 'one':
+                return cur.fetchone()
+            if fetch == 'all':
+                return cur.fetchall()
+            return None
+
+    def _ensure_column(self, conn: sqlite3.Connection, col_name: str, col_type: str = "TEXT") -> None:
+        cur = conn.cursor()
+        cur.execute("PRAGMA table_info(papers)")
+        cols = [r[1] for r in cur.fetchall()]
+        if col_name not in cols:
+            cur.execute(f"ALTER TABLE papers ADD COLUMN {col_name} {col_type}")
+
+    def _init_database(self) -> None:
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute("PRAGMA user_version")
+            db_version = int(cursor.fetchone()[0])
+
+            if db_version < 1:
+                cursor.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS papers (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        title TEXT NOT NULL,
+                        abstract TEXT,
+                        doi TEXT UNIQUE,
+                        pmid TEXT UNIQUE,
+                        arxiv_id TEXT UNIQUE,
+                        pmc_id TEXT UNIQUE,
+                        journal TEXT,
+                        year INTEGER,
+                        volume TEXT,
+                        issue TEXT,
+                        pages TEXT,
+                        publisher TEXT,
+                        pdf_url TEXT,
+                        source_url TEXT,
+                        local_pdf_path TEXT,
+                        keywords TEXT,
+                        mesh_terms TEXT,
+                        "references" TEXT,
+                        citations INTEGER DEFAULT 0,
+                        source TEXT DEFAULT 'unknown',
+                        notes TEXT,
+                        tags TEXT,
+                        category TEXT,
+                        rating INTEGER,
+                        read_status TEXT DEFAULT 'unread',
+                        importance TEXT DEFAULT 'normal',
+                        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                    )
+                    """
+                )
+                self._ensure_column(conn, "local_pdf_path")
+                self._ensure_column(conn, "category")
+                self._ensure_column(conn, "venue_type")
+
+                cursor.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS authors (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        name TEXT NOT NULL,
+                        affiliation TEXT,
+                        email TEXT,
+                        orcid TEXT UNIQUE
+                    )
+                    """
+                )
+                cursor.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS paper_authors (
+                        paper_id INTEGER NOT NULL,
+                        author_id INTEGER NOT NULL,
+                        author_order INTEGER DEFAULT 0,
+                        PRIMARY KEY (paper_id, author_id),
+                        FOREIGN KEY (paper_id) REFERENCES papers(id) ON DELETE CASCADE,
+                        FOREIGN KEY (author_id) REFERENCES authors(id) ON DELETE CASCADE
+                    )
+                    """
+                )
+                cursor.execute("PRAGMA user_version = 1")
+                db_version = 1
+
+            if db_version < 2:
+                cursor.executescript(
+                    """
+                    CREATE INDEX IF NOT EXISTS idx_papers_category ON papers(category);
+                    CREATE INDEX IF NOT EXISTS idx_papers_year ON papers(year);
+                    CREATE INDEX IF NOT EXISTS idx_papers_read_status ON papers(read_status);
+                    CREATE INDEX IF NOT EXISTS idx_papers_created_at ON papers(created_at);
+                    CREATE INDEX IF NOT EXISTS idx_category_year ON papers(category, year);
+                    """
+                )
+                try:
+                    cursor.executescript(
+                        """
+                        CREATE VIRTUAL TABLE IF NOT EXISTS papers_fts USING fts5(
+                            title, abstract,
+                            content='papers', content_rowid='id'
+                        );
+
+                        CREATE TRIGGER IF NOT EXISTS papers_ai AFTER INSERT ON papers BEGIN
+                            INSERT INTO papers_fts(rowid, title, abstract)
+                            VALUES (new.id, new.title, new.abstract);
+                        END;
+
+                        CREATE TRIGGER IF NOT EXISTS papers_ad AFTER DELETE ON papers BEGIN
+                            INSERT INTO papers_fts(papers_fts, rowid, title, abstract)
+                            VALUES ('delete', old.id, old.title, old.abstract);
+                        END;
+
+                        CREATE TRIGGER IF NOT EXISTS papers_au AFTER UPDATE ON papers BEGIN
+                            INSERT INTO papers_fts(papers_fts, rowid, title, abstract)
+                            VALUES ('delete', old.id, old.title, old.abstract);
+                            INSERT INTO papers_fts(rowid, title, abstract)
+                            VALUES (new.id, new.title, new.abstract);
+                        END;
+                        """
+                    )
+                    cursor.execute("INSERT INTO papers_fts(papers_fts) VALUES('rebuild')")
+                except sqlite3.OperationalError as e:
+                    logger.warning("FTS5 不可用或未启用,跳过全文索引: %s", e)
+                cursor.execute("PRAGMA user_version = 2")
+
+    @staticmethod
+    def _norm_id_field(val: str | None) -> str | None:
+        s = (val or "").strip()
+        return s if s else None
+
+    def _sync_saved_meta(self, cursor: sqlite3.Cursor, paper_id: int, paper: Paper) -> None:
+        cat = getattr(paper, "category", None)
+        doi = self._norm_id_field(paper.doi)
+        arxiv_id = self._norm_id_field(paper.arxiv_id)
+        abs_new = (paper.abstract or "").strip() or None
+        title_new = (paper.title or "").strip() or None
+        cursor.execute(
+            """UPDATE papers SET category = ?, tags = ?, pdf_url = ?, source_url = ?,
+               doi = COALESCE(?, doi),
+               arxiv_id = COALESCE(?, arxiv_id),
+               abstract = COALESCE(?, abstract),
+               title = COALESCE(?, title),
+               venue_type = COALESCE(?, venue_type),
+               updated_at = CURRENT_TIMESTAMP WHERE id = ?""",
+            (
+                cat,
+                json.dumps(paper.tags or [], ensure_ascii=False),
+                paper.pdf_url,
+                paper.source_url,
+                doi,
+                arxiv_id,
+                abs_new,
+                title_new,
+                getattr(paper, "venue_type", None),
+                paper_id,
+            ),
+        )
+
+    def _add_paper_internal(self, conn: sqlite3.Connection, paper: Paper) -> tuple[int, bool]:
+        cursor = conn.cursor()
+        doi = self._norm_id_field(paper.doi)
+        arxiv_id = self._norm_id_field(paper.arxiv_id)
+        pmid = self._norm_id_field(paper.pmid)
+        pmc_id = self._norm_id_field(paper.pmc_id)
+
+        for field, val in (("doi", doi), ("arxiv_id", arxiv_id), ("pmid", pmid), ("pmc_id", pmc_id)):
+            if val:
+                cursor.execute(f"SELECT id FROM papers WHERE {field} = ?", (val,))
+                existing = cursor.fetchone()
+                if existing:
+                    eid = int(existing[0])
+                    self._sync_saved_meta(cursor, eid, paper)
+                    return eid, False
+
+        cursor.execute(
+            """
+            INSERT INTO papers (
+                title, abstract, doi, pmid, arxiv_id, pmc_id,
+                journal, year, volume, issue, pages, publisher,
+                pdf_url, source_url, local_pdf_path, keywords, mesh_terms, "references",
+                citations, source, notes, tags, category, venue_type, rating, read_status, importance
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                paper.title,
+                paper.abstract,
+                doi,
+                pmid,
+                arxiv_id,
+                pmc_id,
+                paper.journal,
+                paper.year,
+                paper.volume,
+                paper.issue,
+                paper.pages,
+                paper.publisher,
+                paper.pdf_url,
+                paper.source_url,
+                getattr(paper, "local_pdf_path", None),
+                json.dumps(paper.keywords, ensure_ascii=False),
+                json.dumps(paper.mesh_terms, ensure_ascii=False),
+                json.dumps(paper.references, ensure_ascii=False),
+                paper.citations,
+                paper.source,
+                paper.notes,
+                json.dumps(paper.tags, ensure_ascii=False),
+                getattr(paper, "category", None),
+                getattr(paper, "venue_type", None),
+                paper.rating,
+                paper.read_status,
+                paper.importance,
+            ),
+        )
+
+        paper_id = cursor.lastrowid
+        self._add_authors(conn, paper_id, paper.authors)
+        return int(paper_id), True
+
+    def add_paper(self, paper: Paper) -> tuple[int, bool]:
+        with self._get_connection() as conn:
+            return self._add_paper_internal(conn, paper)
+
+    def add_papers(self, papers: list[Paper]) -> tuple[list[int], int, int]:
+        ids: list[int] = []
+        added = 0
+        updated = 0
+        with self._get_connection() as conn:
+            for paper in papers:
+                try:
+                    paper_id, is_new = self._add_paper_internal(conn, paper)
+                    ids.append(int(paper_id))
+                    if is_new:
+                        added += 1
+                    else:
+                        updated += 1
+                except Exception as e:
+                    logger.error("批量添加文献时出错 '%s': %s", getattr(paper, "title", ""), e)
+                    ids.append(-1)
+        return ids, added, updated
+
+    def _add_authors(self, conn: sqlite3.Connection, paper_id: int, authors: list[Author]) -> None:
+        cursor = conn.cursor()
+        for order, author in enumerate(authors):
+            if author.orcid:
+                cursor.execute("SELECT id FROM authors WHERE orcid = ?", (author.orcid,))
+            else:
+                cursor.execute("SELECT id FROM authors WHERE name = ?", (author.name,))
+
+            result = cursor.fetchone()
+            if result:
+                author_id = result[0]
+            else:
+                cursor.execute(
+                    "INSERT INTO authors (name, affiliation, email, orcid) VALUES (?, ?, ?, ?)",
+                    (author.name, author.affiliation, author.email, author.orcid),
+                )
+                author_id = cursor.lastrowid
+
+            with suppress(sqlite3.IntegrityError):
+                cursor.execute(
+                    "INSERT INTO paper_authors (paper_id, author_id, author_order) VALUES (?, ?, ?)",
+                    (paper_id, author_id, order),
+                )
+
+    def _fetch_authors_for_papers(
+        self, conn: sqlite3.Connection, paper_ids: list[int]
+    ) -> dict[int, list[Author]]:
+        if not paper_ids:
+            return {}
+        cursor = conn.cursor()
+        placeholders = ",".join("?" * len(paper_ids))
+        cursor.execute(
+            f"""
+            SELECT pa.paper_id, a.* FROM authors a
+            JOIN paper_authors pa ON a.id = pa.author_id
+            WHERE pa.paper_id IN ({placeholders})
+            ORDER BY pa.paper_id, pa.author_order
+            """,
+            paper_ids,
+        )
+        authors_by_paper: dict[int, list[Author]] = defaultdict(list)
+        for row in cursor.fetchall():
+            authors_by_paper[int(row["paper_id"])].append(
+                Author(
+                    name=row["name"],
+                    affiliation=row["affiliation"],
+                    email=row["email"],
+                    orcid=row["orcid"],
+                    db_id=int(row["id"]) if row["id"] is not None else None,
+                )
+            )
+        return dict(authors_by_paper)
+
+    def _row_to_paper_fast(self, row: sqlite3.Row, authors: list[Author]) -> Paper:
+        keys = row.keys()
+        return Paper(
+            id=row["id"],
+            title=row["title"],
+            authors=authors,
+            abstract=row["abstract"],
+            doi=row["doi"],
+            pmid=row["pmid"],
+            arxiv_id=row["arxiv_id"],
+            pmc_id=row["pmc_id"],
+            journal=row["journal"],
+            year=row["year"],
+            volume=row["volume"],
+            issue=row["issue"],
+            pages=row["pages"],
+            publisher=row["publisher"],
+            pdf_url=row["pdf_url"],
+            source_url=row["source_url"],
+            local_pdf_path=row["local_pdf_path"] if "local_pdf_path" in keys else None,
+            keywords=json.loads(row["keywords"] or "[]"),
+            mesh_terms=json.loads(row["mesh_terms"] or "[]"),
+            references=json.loads(row["references"] or "[]"),
+            citations=row["citations"] or 0,
+            source=row["source"] or "unknown",
+            notes=row["notes"],
+            tags=json.loads(row["tags"] or "[]"),
+            category=row["category"] if "category" in keys else None,
+            venue_type=row["venue_type"] if "venue_type" in keys else None,
+            rating=row["rating"],
+            read_status=row["read_status"] or "unread",
+            importance=row["importance"] or "normal",
+        )
+
+    def count_papers(self) -> int:
+        return self._query("SELECT COUNT(*) FROM papers", fetch='one')[0]
+
+    def get_all_papers(self, limit: int | None = None, offset: int = 0, order_by: str = "created_at DESC") -> list[Paper]:
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            query = f"SELECT * FROM papers ORDER BY {order_by}"
+            if limit:
+                query += f" LIMIT {int(limit)}"
+            if offset:
+                query += f" OFFSET {int(offset)}"
+            cursor.execute(query)
+            rows = cursor.fetchall()
+            if not rows:
+                return []
+            paper_ids = [int(r["id"]) for r in rows]
+            authors_map = self._fetch_authors_for_papers(conn, paper_ids)
+            return [
+                self._row_to_paper_fast(row, authors_map.get(int(row["id"]), []))
+                for row in rows
+            ]
+
+    def get_paper_by_id(self, paper_id: int) -> Paper | None:
+        row = self._query("SELECT * FROM papers WHERE id = ?", (paper_id,), fetch='one')
+        if not row:
+            return None
+        with self._get_connection() as conn:
+            authors_map = self._fetch_authors_for_papers(conn, [paper_id])
+        return self._row_to_paper_fast(row, authors_map.get(paper_id, []))
+
+    def search_library(
+        self,
+        query: str | None = None,
+        tags: list[str] | None = None,
+        year_from: int | None = None,
+        year_to: int | None = None,
+        read_status: str | None = None,
+        category: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[Paper]:
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            clauses: list[str] = ["1=1"]
+            params: list[Any] = []
+            use_fts = False
+            match_expr = ""
+            clean_query = ""
+
+            if query and str(query).strip():
+                clean_query = re.sub(r'["\'*^]', " ", str(query)).strip()
+                if clean_query and self._library_fts_ready:
+                    parts = [w for w in clean_query.split() if w.strip()]
+                    if parts:
+                        match_expr = " AND ".join(f'"{w}"' for w in parts)
+                        use_fts = True
+
+            if use_fts:
+                base_from = "papers p"
+                clauses.append(
+                    "(p.id IN (SELECT rowid FROM papers_fts WHERE papers_fts MATCH ?)"
+                    " OR p.id IN (SELECT pa.paper_id FROM paper_authors pa JOIN authors a ON pa.author_id = a.id WHERE a.name LIKE ?))"
+                )
+                params.append(match_expr)
+                like_author = f"%{clean_query}%"
+                params.append(like_author)
+            elif query and str(query).strip():
+                clauses.append("(p.title LIKE ? OR p.abstract LIKE ? OR p.id IN (SELECT pa.paper_id FROM paper_authors pa JOIN authors a ON pa.author_id = a.id WHERE a.name LIKE ?))")
+                like = f"%{str(query).strip()}%"
+                params.extend([like, like, like])
+                base_from = "papers p"
+            else:
+                base_from = "papers p"
+
+            if category:
+                cat = category.strip()
+                if cat.endswith("/*"):
+                    prefix = cat[:-2].strip()
+                    if prefix == "未分类":
+                        clauses.append(
+                            "(p.category IS NULL OR TRIM(COALESCE(p.category, '')) IN ('', '未分类') "
+                            "OR TRIM(COALESCE(p.category, '')) LIKE '未分类/%')"
+                        )
+                    elif prefix:
+                        clauses.append(
+                            "(TRIM(COALESCE(p.category, '')) = ? OR TRIM(COALESCE(p.category, '')) LIKE ?)"
+                        )
+                        params.extend([prefix, prefix + "/%"])
+                elif cat == "未分类":
+                    clauses.append(
+                        "(p.category IS NULL OR TRIM(COALESCE(p.category, '')) IN ('', '未分类'))"
+                    )
+                else:
+                    clauses.append("TRIM(COALESCE(p.category, '')) = ?")
+                    params.append(cat)
+
+            if year_from is not None:
+                clauses.append("(p.year IS NOT NULL AND p.year >= ?)")
+                params.append(year_from)
+            if year_to is not None:
+                clauses.append("(p.year IS NOT NULL AND p.year <= ?)")
+                params.append(year_to)
+            if read_status:
+                clauses.append("p.read_status = ?")
+                params.append(read_status)
+
+            order_clause = "ORDER BY p.created_at DESC"
+
+            sql = f"SELECT p.* FROM {base_from} WHERE {' AND '.join(clauses)} {order_clause} LIMIT ?"
+            params.append(int(limit))
+            if offset:
+                sql += " OFFSET ?"
+                params.append(int(offset))
+            cursor.execute(sql, params)
+            rows = cursor.fetchall()
+            if not rows:
+                return []
+            paper_ids = [int(r["id"]) for r in rows]
+            authors_map = self._fetch_authors_for_papers(conn, paper_ids)
+            papers = [self._row_to_paper_fast(row, authors_map.get(int(row["id"]), [])) for row in rows]
+            if tags:
+                tag_set = set(tags)
+                papers = [p for p in papers if tag_set.intersection(set(p.tags))]
+            return papers
+
+    def update_paper(self, paper_id: int, **fields) -> bool:
+        allowed = {"notes", "tags", "rating", "read_status", "importance", "category", "abstract"}
+        updates = {k: v for k, v in fields.items() if k in allowed and v is not None}
+        if not updates:
+            return False
+        if "tags" in updates and isinstance(updates["tags"], list):
+            updates["tags"] = json.dumps(updates["tags"], ensure_ascii=False)
+        set_parts = [f"{k} = ?" for k in updates]
+        values = list(updates.values()) + [paper_id]
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                f"UPDATE papers SET {', '.join(set_parts)}, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+                values,
+            )
+            return cursor.rowcount > 0
+
+    def set_local_pdf_path(self, paper_id: int, relative_path: str | None) -> bool:
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "UPDATE papers SET local_pdf_path = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+                (relative_path, paper_id),
+            )
+            return cursor.rowcount > 0
+
+    def delete_paper(self, paper_id: int) -> bool:
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute("SELECT local_pdf_path FROM papers WHERE id = ?", (paper_id,))
+            row = cursor.fetchone()
+            if row and row[0]:
+                abspath = self._abs_local_pdf(row[0])
+                if abspath and os.path.isfile(abspath):
+                    with suppress(OSError):
+                        os.remove(abspath)
+            cursor.execute("DELETE FROM paper_authors WHERE paper_id = ?", (paper_id,))
+            cursor.execute("DELETE FROM papers WHERE id = ?", (paper_id,))
+            return cursor.rowcount > 0
+
+    def repair_library_local_pdf_paths_batch(self, paper_ids: list[int]) -> dict[int, str]:
+        want = {int(x) for x in paper_ids if x is not None and int(x) >= 0}
+        if not want:
+            return {}
+        data_root = self._data_root()
+        lib_root = os.path.join(data_root, LIBRARY_PDF_ROOT_DIR)
+        if not os.path.isdir(lib_root):
+            return {}
+        candidates: dict[int, list[tuple[float, str]]] = {k: [] for k in want}
+        name_pat = re.compile(r"^(\d+)\.pdf$")
+        for dirpath, _, filenames in os.walk(lib_root):
+            for fn in filenames:
+                m = name_pat.match(fn)
+                if not m:
+                    continue
+                pid = int(m.group(1))
+                if pid not in want:
+                    continue
+                full = os.path.join(dirpath, fn)
+                try:
+                    mt = os.path.getmtime(full)
+                except OSError:
+                    continue
+                rel = os.path.relpath(full, data_root).replace("\\", "/")
+                if rel.startswith(".."):
+                    continue
+                candidates[pid].append((mt, rel))
+        out: dict[int, str] = {}
+        for pid, rows in candidates.items():
+            if not rows:
+                continue
+            rows.sort(key=lambda x: -x[0])
+            best_rel = rows[0][1]
+            if self.set_local_pdf_path(pid, best_rel):
+                out[pid] = best_rel
+        return out
+
+    def get_library_pdf_abspath(self, paper_id: int) -> str | None:
+        p = self.get_paper_by_id(paper_id)
+        if not p or not (getattr(p, "local_pdf_path", None) or "").strip():
+            return None
+        rel = (p.local_pdf_path or "").strip()
+        candidates = [self._abs_local_pdf(rel)]
+        if rel.startswith(f"{LIBRARY_PDF_ROOT_DIR}/"):
+            candidates.append(
+                self._abs_local_pdf("pdfs/" + rel[len(LIBRARY_PDF_ROOT_DIR) + 1 :])
+            )
+        elif rel.startswith("pdfs/"):
+            candidates.append(
+                self._abs_local_pdf(f"{LIBRARY_PDF_ROOT_DIR}/" + rel[len("pdfs/") :])
+            )
+        root = os.path.realpath(self._data_root())
+        for abspath in candidates:
+            if not abspath or not os.path.isfile(abspath):
+                continue
+            real_f = os.path.realpath(abspath)
+            if real_f != root and not real_f.startswith(root + os.sep):
+                continue
+            return real_f
+        return None
+
+    def list_library_category_folders(self) -> list[dict[str, Any]]:
+        rows = self._query(
+            """
+            SELECT COALESCE(NULLIF(TRIM(category), ''), '未分类') AS c, COUNT(*) AS n
+            FROM papers
+            GROUP BY c
+            ORDER BY n DESC, c ASC
+            """
+        )
+
+        standalone: dict[str, int] = {}
+        by_parent: dict[str, list[dict[str, Any]]] = defaultdict(list)
+
+        for row in rows:
+            c = row["c"] or "未分类"
+            n = int(row["n"])
+            if "/" not in c:
+                standalone[c] = standalone.get(c, 0) + n
+                continue
+            parts = [p.strip() for p in c.split("/") if p.strip()]
+            if len(parts) < 2:
+                standalone[c] = standalone.get(c, 0) + n
+                continue
+            parent = parts[0]
+            label = "/".join(parts[1:])
+            by_parent[parent].append(
+                {
+                    "category": c,
+                    "label": label,
+                    "folder": category_slug_for_pdf_dir(c),
+                    "count": n,
+                }
+            )
+
+        consumed_standalone: set[str] = set()
+        out: list[dict[str, Any]] = []
+
+        for parent in sorted(
+            by_parent.keys(),
+            key=lambda p: (-sum(x["count"] for x in by_parent[p]), p),
+        ):
+            ch = sorted(by_parent[parent], key=lambda x: (-x["count"], x["label"]))
+            extra = standalone.get(parent, 0)
+            total = sum(x["count"] for x in ch) + extra
+            children: list[dict[str, Any]] = []
+            if extra > 0:
+                children.append(
+                    {
+                        "category": parent,
+                        "label": "未分子类",
+                        "folder": category_slug_for_pdf_dir(parent),
+                        "count": extra,
+                    }
+                )
+                consumed_standalone.add(parent)
+            children.extend(ch)
+            out.append(
+                {
+                    "category": parent,
+                    "folder": category_slug_for_pdf_dir(parent),
+                    "count": total,
+                    "children": children,
+                }
+            )
+
+        for cat, n in standalone.items():
+            if cat in consumed_standalone:
+                continue
+            out.append(
+                {
+                    "category": cat,
+                    "folder": category_slug_for_pdf_dir(cat),
+                    "count": n,
+                    "children": [],
+                }
+            )
+
+        out.sort(key=lambda x: (-x["count"], x["category"]))
+        return out
+
+    def list_library_categories_by_count(self, limit: int = 80) -> list[str]:
+        limit = int(limit or 0)
+        if limit <= 0:
+            limit = 80
+        rows = self._query(
+            """
+            SELECT COALESCE(NULLIF(TRIM(category), ''), '未分类') AS c, COUNT(*) AS n
+            FROM papers
+            GROUP BY c
+            ORDER BY n DESC, c ASC
+            LIMIT ?
+            """,
+            (limit,),
+        )
+        out: list[str] = []
+        for r in rows:
+            c = (r["c"] or "").strip() or "未分类"
+            if c not in out:
+                out.append(c)
+        return out

+ 0 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/models/__init__.py


+ 233 - 0
Co-creation-projects/DeLunnLi-PaperGraph/backend/app/models/schemas.py

@@ -0,0 +1,233 @@
+"""Pydantic API 模型 —— 请求/响应 schema 定义."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+class PaperSource(str, Enum):
+    ARXIV = "arxiv"
+    OPENALEX = "openalex"
+    DBLP = "dblp"
+    TAVILY = "tavily"
+    UNKNOWN = "unknown"
+
+class ReadStatus(str, Enum):
+    UNREAD = "unread"
+    READING = "reading"
+    READ = "read"
+
+class FeedbackActionEnum(str, Enum):
+
+    CLICK = "click"
+    SAVE = "save"
+    SKIP = "skip"
+    IGNORE = "ignore"
+    READ = "read"
+
+class BaseAPIResponse(BaseModel):
+
+    success: bool
+    message: str | None = None
+
+class Author(BaseModel):
+
+    name: str
+    affiliation: str | None = None
+    email: str | None = None
+    orcid: str | None = None
+    db_id: int | None = Field(default=None, description="本地 authors 表 id,用于区分同名")
+
+class Paper(BaseModel):
+
+    id: int | None = None
+    title: str
+    authors: list[Author] = Field(default_factory=list)
+    abstract: str | None = None
+    doi: str | None = None
+    pmid: str | None = None
+    arxiv_id: str | None = None
+    pmc_id: str | None = None
+    journal: str | None = None
+    venue_type: str | None = Field(default=None, description="会议/期刊类型:conference 或 journal")
+    year: int | None = None
+    volume: str | None = None
+    issue: str | None = None
+    pages: str | None = None
+    publisher: str | None = None
+    pdf_url: str | None = None
+    source_url: str | None = None
+    local_pdf_path: str | None = Field(default=None, description="本地 PDF 相对路径")
+    keywords: list[str] = Field(default_factory=list)
+    mesh_terms: list[str] = Field(default_factory=list)
+    references: list[str] = Field(default_factory=list)
+    citations: int = 0
+    source: PaperSource = PaperSource.UNKNOWN
+    relevance_score: float = 0.0
+    notes: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    category: str | None = Field(
+        default=None,
+        description="文献库领域(保存时由大模型或手写)",
+    )
+    rating: int | None = None
+    read_status: ReadStatus = ReadStatus.UNREAD
+    importance: str = "normal"
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+class PapersResponse(BaseAPIResponse):
+    total: int
+    papers: list[Paper] = Field(default_factory=list)
+
+class LibraryCategoryFolder(BaseModel):
+    category: str
+    folder: str
+    count: int
+    children: list[dict[str, Any]] = Field(default_factory=list)
+
+class LibraryCategoriesResponse(BaseAPIResponse):
+    store_root: str = "文献库"
+    folders: list[LibraryCategoryFolder] = Field(default_factory=list)
+
+class SavePapersRequest(BaseModel):
+    papers: list[Paper]
+    download_pdfs: bool = Field(default=False, description="保存后下载 PDF")
+    llm_classify: bool = Field(default=True, description="大模型划分 category")
+
+class SavePapersResponse(BaseAPIResponse):
+    added: int
+    updated: int = 0
+    ids: list[int] = Field(default_factory=list)
+    pdf_downloaded: int = 0
+    llm_classified: int = 0
+
+class DailyPaperPickHint(BaseModel):
+    identity_key: str = Field(description="身份键,如 arxiv:2401.0001")
+    pick_kind: str = Field(description="personalized | general")
+    explanation: str = Field(default="", description="入选理由")
+
+class DailyPapersRequest(BaseModel):
+    days_back: int = Field(default=5, ge=0, le=30, description="arXiv 最近 N 天")
+    arxiv_max_results: int = Field(default=20, ge=10, le=50, description="arXiv 候选数")
+    arxiv_categories: list[str] | None = Field(default=None, description="arXiv 分类过滤")
+    personalized_k: int = Field(default=20, ge=0, le=40, description="个性化推荐条数")
+    library_limit: int = Field(default=800, ge=50, le=3000, description="库内候选上限")
+    force_refresh: bool = Field(default=False, description="忽略缓存强制刷新")
+    use_llm_rank: bool = Field(default=False, description="是否启用 LLM 精排")
+    rerank_recall_max: int = Field(default=24, ge=8, le=60, description="精排前召回候选上限")
+    use_llm_theme_keywords: bool = Field(default=True, description="LLM 生成主题标签")
+
+class DailyPapersResponse(BaseAPIResponse):
+    date_key: str
+    arxiv_latest_total: int
+    arxiv_selected_total: int
+    personalized_total: int
+    arxiv_latest: list[Paper] = Field(default_factory=list)
+    arxiv_selected: list[Paper] = Field(default_factory=list)
+    personalized: list[Paper] = Field(default_factory=list)
+    memory_keywords_used: list[str] = Field(default_factory=list, description="偏好词摘要")
+    strategy_explanation: str = Field(default="", description="推荐策略摘要(≤2 行中文)")
+    personalized_theme_keywords: list[str] = Field(default_factory=list, description="个性化列表主题标签")
+    general_theme_keywords: list[str] = Field(default_factory=list, description="精选列表主题标签")
+    personalized_pick_hints: list[DailyPaperPickHint] = Field(default_factory=list)
+    general_pick_hints: list[DailyPaperPickHint] = Field(default_factory=list)
+
+class UpdatePaperRequest(BaseModel):
+    notes: str | None = None
+    tags: list[str] | None = None
+    category: str | None = None
+    rating: int | None = None
+    read_status: ReadStatus | None = None
+    importance: str | None = None
+
+class UpdatePaperResponse(BaseAPIResponse):
+    updated_fields: list[str] = Field(default_factory=list)
+
+class DeletePaperResponse(BaseAPIResponse):
+    pass
+
+class GraphNode(BaseModel):
+    id: str
+    type: str
+    label: str
+    paper_id: int | None = None
+    year: int | None = None
+    category: str | None = None
+    journal: str | None = None
+    venue_type: str | None = None
+    weight: float = 1.0
+
+class GraphEdge(BaseModel):
+    source: str
+    target: str
+    type: str
+    weight: float = 1.0
+
+    evidence: str | None = None
+
+class LibraryGraphResponse(BaseAPIResponse):
+    nodes: list[GraphNode] = Field(default_factory=list)
+    edges: list[GraphEdge] = Field(default_factory=list)
+
+class PaperReaderOpeningRequest(BaseModel):
+    paper_id: int = Field(..., ge=1)
+
+class PaperReaderOpeningResponse(BaseAPIResponse):
+    opening: str
+    pdf_parsing: bool = False
+
+class PaperReaderChatRequest(BaseModel):
+    paper_id: int = Field(..., ge=1)
+    messages: list[dict[str, str]] = Field(default_factory=list)
+    user_message: str = Field(..., min_length=1, max_length=12000)
+
+class PaperReaderChatResponse(BaseAPIResponse):
+    reply: str
+    pdf_parsing: bool = False
+    related_papers: list[Paper] = Field(default_factory=list)
+
+    related_hints: list[dict[str, Any]] = Field(default_factory=list)
+
+    kg_edges: list[dict[str, Any]] = Field(default_factory=list)
+
+class PaperReaderHistoryItem(BaseModel):
+    role: str
+    content: str
+    created_at: int
+
+class PaperReaderHistoryResponse(BaseAPIResponse):
+    paper_id: int
+    turns: list[PaperReaderHistoryItem] = Field(default_factory=list)
+
+class ReadingLogRequest(BaseModel):
+    paper_id: int = Field(..., ge=1)
+    duration_sec: int = Field(..., ge=1, le=60 * 60 * 24, description="本次阅读停留时长(秒)")
+    client_ts: int | None = Field(default=None, description="客户端时间戳(秒);缺省则服务端按当前时间落在当天")
+
+class ReadingCalendarItem(BaseModel):
+    date: str = Field(..., description="YYYY-MM-DD")
+    seconds: int = 0
+    sessions: int = 0
+
+class ReadingCalendarResponse(BaseAPIResponse):
+    days: int = 180
+    items: list[ReadingCalendarItem] = Field(default_factory=list)
+
+class DailyRecommendFeedbackRequest(BaseModel):
+
+    identity_key: str = Field(..., description="论文身份标识(如 arxiv:2401.0001 / doi:xxx / title_hash:xxx)")
+    title: str | None = Field(default=None, description="论文标题")
+    action: FeedbackActionEnum = Field(..., description="用户动作")
+    source_list: str | None = Field(default=None, description="推荐来源: personalized 或 general")
+    score_at_recommend: float | None = Field(default=None, description="推荐时的匹配分数")
+    keywords: list[str] | None = Field(default=None, description="论文关键词")
+    category: str | None = Field(default=None, description="论文分类")
+    journal: str | None = Field(default=None, description="论文期刊/会议(用于负反馈建模)")
+    source: str | None = Field(default=None, description="数据源(用于负反馈建模)")
+
+class DailyRecommendFeedbackResponse(BaseAPIResponse):
+    pass

برخی فایل ها در این مقایسه diff نمایش داده نمی شوند زیرا تعداد فایل ها بسیار زیاد است