EmoAgent

本文件是 EmoAgent 项目的入口说明，用于快速了解项目目标、当前文件结构、V0 规划结构和后续审查入口。

项目目标

EmoAgent V0 计划基于 LangGraph 构建一个故事智能体 CLI 原型。用户输入自然语言 query 后，系统先判断是否为故事生成请求；若是，则进入故事生成链路，完成 query 理解、主题簇路由和故事事件生成；若不是，则提示未触发故事链路，并给出普通聊天回复。

当前文件树

E:\Pycharm-pro\my_project\EmoAgent
├─ AGENTS.md
│  └─ 项目级协作规则，约束中文文档、UTF-8、禁止批量删除、README 文件树维护、文件顶部说明和 Skill 扩展入口。
├─ README.md
│  └─ 项目入口说明，记录项目目标、当前文件树、V0 规划结构和审查入口。
├─ pyproject.toml
│  └─ Python 项目元信息、依赖声明、CLI 入口和 pytest 配置。
├─ .env.example
│  └─ OpenAI-compatible LLM、主题树路径和 topN 等环境变量模板。
├─ .gitignore
│  └─ Git 忽略规则，排除本地密钥、虚拟环境、缓存和构建产物。
├─ .github/
│  └─ ISSUE_TEMPLATE/
│     ├─ bug.md
│     │  └─ Bug / 故障 issue 模板，用于记录可复现错误和接口兼容性问题。
│     └─ task.md
│        └─ 任务 / 需求 issue 模板，用于沉淀后续开发事项和验收标准。
├─ scripts/
│  └─ check_openai_compat.py
│     └─ OpenAI SDK 直连诊断脚本，用于绕过 LangChain 检查中转站与模型是否可用。
└─ docs/
   ├─ emotion_factor_tree.json
   │  └─ 情感因子树数据基线，包含八类 emotion 下的主题簇、元素统计和 LLM 标注字段。
   └─ superpowers/
      ├─ plans/
      │  └─ 2026-05-27-story-agent-v0-implementation.md
      │     └─ Story Agent V0 实现计划，按 TDD 拆分工程脚手架、schema、主题树服务、Agent、workflow 和 CLI。
      └─ specs/
         └─ 2026-05-27-langgraph-story-agent-design.md
            └─ LangGraph 故事智能体 V0 设计文档。
   └─ github_issues/
      └─ initial_issues.md
         └─ 首批 GitHub Issues 草稿，用于在 connector 权限不足时手动创建 issue。
├─ src/
│  └─ emoagent/
│     ├─ __init__.py
│     │  └─ Python 包入口，提供版本等轻量元信息。
│     ├─ cli.py
│     │  └─ CLI 入口，支持单次 query 和交互式运行。
│     ├─ config.py
│     │  └─ `.env` 与环境变量配置加载。
│     ├─ schemas.py
│     │  └─ Pydantic 结构化数据模型。
│     ├─ agents/
│     │  ├─ __init__.py
│     │  │  └─ Agent 子包入口。
│     │  ├─ base.py
│     │  │  └─ Base Agent，负责故事检测和非故事普通回复。
│     │  ├─ query_understand.py
│     │  │  └─ Query Understand Agent，抽取 StoryMessage。
│     │  ├─ theme_router.py
│     │  │  └─ Theme Router Agent，选择情感主题簇。
│     │  └─ event_generation.py
│     │     └─ Event Generation Agent，生成主题引入理由和故事帧。
│     ├─ services/
│     │  ├─ __init__.py
│     │  │  └─ 服务层子包入口。
│     │  ├─ llm.py
│     │  │  └─ ChatOpenAI 初始化服务。
│     │  ├─ skills.py
│     │  │  └─ V0 SkillRegistry 和 StoryDetectionSkill。
│     │  └─ theme_tree.py
│     │     └─ 情感因子树读取、候选压缩和 cluster 回填。
│     ├─ workflow/
│     │  ├─ __init__.py
│     │  │  └─ 工作流子包入口。
│     │  ├─ graph.py
│     │  │  └─ LangGraph 节点、边和条件路由构建。
│     │  └─ state.py
│     │     └─ 工作流状态定义。
│     └─ prompts/
│        ├─ story_detection.md
│        │  └─ 故事意图检测 prompt。
│        ├─ query_understand.md
│        │  └─ query 结构化理解 prompt。
│        ├─ theme_router.md
│        │  └─ 主题簇选择 prompt。
│        └─ event_generation.md
│           └─ 故事事件帧生成 prompt。
└─ tests/
   ├─ test_cli.py
   │  └─ CLI 参数与输出边界测试，使用 fake runner 避免真实 LLM。
   ├─ test_config.py
   │  └─ `.env` 与环境变量配置加载测试。
   ├─ test_schemas.py
   │  └─ Pydantic schema 测试。
   ├─ test_skills.py
   │  └─ SkillRegistry 与故事检测测试，使用假模型。
   ├─ test_theme_tree.py
   │  └─ 真实情感因子树读取和 topN 裁剪测试。
   └─ test_workflow_smoke.py
      └─ LangGraph 工作流形状冒烟测试，使用 fake nodes。

快速开始

当前机器如果已安装 uv，推荐：

uv sync --extra dev

当前机器如果没有 uv，可以使用 Python/pip：

python -m pip install -e ".[dev]"

复制 .env.example 为 .env，填写：

OPENAI_API_KEY=
OPENAI_BASE_URL=
OPENAI_MODEL=

单次运行：

python -m emoagent.cli "Generate a happy story about a puppy running on the lawn."

交互式运行：

python -m emoagent.cli

运行测试：

python -m pytest -v

绕过 LangChain、直接用 OpenAI SDK 测试中转站：

uv run python scripts/check_openai_compat.py --model gpt-4o

V0 工作流

base_agent
  ├─ 非故事请求 -> normal_chat -> end
  └─ 故事请求 -> query_understand -> theme_router -> event_generation -> end

审查入口

• 项目协作规则：AGENTS.md
• GitHub Issue 草稿：docs/github_issues/initial_issues.md
• V0 实现计划：docs/superpowers/plans/2026-05-27-story-agent-v0-implementation.md
• V0 设计文档：docs/superpowers/specs/2026-05-27-langgraph-story-agent-design.md
• 情感因子树数据：docs/emotion_factor_tree.json

GitHub Issue 维护流程

后续开发建议从 GitHub Issue 开始：

1. 使用 .github/ISSUE_TEMPLATE/task.md 或 .github/ISSUE_TEMPLATE/bug.md 创建 issue。
2. 在 issue 中写清背景、待办、验收标准和相关文件。
3. 开发分支建议使用 feat/issue-<id>-short-name 或 fix/issue-<id>-short-name。
4. 提交、PR 或最终说明中引用 issue 编号，保证需求、代码和测试结果能互相追溯。