SmartLearner Research Agent

一个面向“快速学习某个方向”的研究型 Agent 框架。
它会自动发现并加载现有 SKILL.md，按主题匹配最相关的 skill，然后生成结构化学习研究包（Markdown）。

Skill 内容摘要（先看）

当前默认 skill 为 hv-analysis（横纵分析法），核心要求如下：

• 目标：做深度研究，不是简短科普；必须形成“纵向发展史 + 横向竞争格局 + 交汇判断”
• 研究流程：先联网收集信息，再写报告；优先一手来源（官方文档、GitHub、权威媒体、社区讨论）
• 纵向分析：沿时间轴还原起源、关键节点、决策逻辑、阶段划分，强调因果叙事而非流水账
• 横向分析：先判断竞品场景（无竞品/少量/充分），再按技术路线、用户口碑、生态位、趋势做对比
• 交汇洞察：把“历史路径”与“当下竞争”结合，给出最可能/最危险/最乐观三种未来剧本
• 篇幅要求：纵向 6000-15000 字、横向 3000-10000 字、交汇 1500-3000 字，总计 10000-30000 字
• 质量与合规：关键事实尽量标注来源；信息缺失需标注“待验证/暂缺”，禁止编造

说明：本项目支持 --prompt-mode skill_only，可只按 SKILL.md 约束生成。

功能

• 自动扫描技能目录中的 SKILL.md（支持多个目录）
• 基于主题做 skill 匹配与路由（触发词 + 关键词）
• 可插拔模型层：
  • --dry-run（不调用模型，先验证流程）
  • OpenAI 兼容接口（/chat/completions）
• 产出固定结构的学习包：
  • 一句话定义
  • 知识地图
  • 7天速通 + 30天深入
  • 实践项目
  • 资料清单与误区

快速开始

安装依赖（可选启用 LangGraph）

pip install langgraph langchain-core langchain-openai

1) Dry Run（先看流程）

python research_agent.py --topic "MCP Agent 架构" --goal "7天内完成可运行Demo" --dry-run

输出文件默认在 outputs/ 目录。

2) 接入真实模型（OpenAI兼容）

方式A：环境变量

set OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
set OPENAI_API_KEY=your_key
set OPENAI_MODEL=glm-4.6v
python research_agent.py --topic "多Agent协作设计"

也支持在项目根目录写 .env（程序会自动读取）：

OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
OPENAI_API_KEY=your_key
OPENAI_MODEL=glm-4.6v
OPENAI_IMAGE_URL=https://your-image-url
OPENAI_ENABLE_THINKING=true
OPENAI_THINKING_TYPE=enabled

方式B：命令行参数

python research_agent.py ^
  --topic "多Agent协作设计" ^
  --endpoint "https://open.bigmodel.cn/api/paas/v4" ^
  --api-key "your_key" ^
  --model "glm-4.6v" ^
  --image-url "https://your-image-url" ^
  --enable-thinking

3) 切换执行引擎

• --engine classic：原生 Python 串行流程（默认）
• --engine graph：LangGraph 节点编排流程

示例：

python research_agent.py --topic "AI Agent 记忆系统" --dry-run --engine graph

加载已有 skills

默认会扫描当前目录。你也可以显式添加多个技能根目录：

python research_agent.py --topic "AI Agent 记忆系统" --dry-run ^
  --skill-path "." ^
  --skill-path "C:\Users\ws\.cursor\skills-cursor"

程序会递归查找这些目录下的 SKILL.md。

设计说明（可扩展点）

• SkillRepository: 负责发现与解析 skill（front matter + 正文）
• SkillMatcher: 根据主题选择最相关的 skills
• ResearchAgent: 构建研究提示词并生成学习包
• BaseProvider: 模型接口抽象，可扩展到任意 LLM 网关

下一步建议

• 增加“研究任务分解器”（先给任务树，再逐步执行）
• 增加多阶段输出（发现 -> 验证 -> 综合 -> 交付）
• 增加引用来源校验（URL可达性、重复来源去重）
• 增加 --json 输出，方便接 UI 或工作流