Agent Lab · 智能体开发练习室

简体中文 | English

第一版实现阶段 1「需求澄清」：选择需求 → 与需求方 Agent 访谈 → 记录和编辑笔记 → 总结 Agent 生成带证据的需求文档。阶段 3「技术方案设计」已提供流程画布、步骤列表和方案评审；阶段 5「智能体开发」尚未实现。

启动

cd D:\Codex\Projects\agent-learning
.\start.ps1

访问 http://127.0.0.1:4190 。启动脚本优先使用项目虚拟环境，其次使用工作区父目录 .venv。新环境需要 Python 3.11+：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\start.ps1

模型配置

所有真实 Agent 统一连接 DeepSeek-V4.1-Flash，官方地址固定为 https://api.deepseek.com，请求模型 ID 为 deepseek-flash。根据 DeepSeek 官方文档，该 ID 当前由 DeepSeek-V4.1-Flash-1017 提供服务，产品名称不直接作为 API 请求 ID。

在项目根目录将 .env.example 复制为 .env，然后填写：

DEEPSEEK_API_KEY=你的密钥

配置优先级为 DEEPSEEK_API_KEY 进程环境变量 > 本项目 .env。每次请求重新读取；填写后刷新页面即可，无需重启。不会读取其他项目的密钥，也不再使用 OPENAI_API_KEY、OPENAI_BASE_URL、MODEL_NAME。密钥不会进入 LangGraph state、浏览器响应或会话数据库。.env 已忽略提交，.env.example 是空模板。

• 真实模型：需求方由模型扮演，正常回复只披露被问到的事实。总结 Agent 只获得公开开场、实际对话和笔记，不获得隐藏场景设定。API 调用会把这些材料发送至配置的服务商并产生费用。
• 离线演示：不联网、不调用模型，按关键词匹配固定场景事实。用于体验 UI 和验证流程，不代表自由对话能力。
• 两种模式均经过同一张 LangGraph。未配置密钥时仍可启动服务和使用离线演示；页面明确显示“待填写 API Key”。
• 模型超时为 120 秒，不自动重复请求。请求失败时保留用户问题与重试 ID，不伪造需求方回复；刷新后可重试同一问题。聊天请求带幂等 ID；相同输入版本不会重复生成文档。

使用

1. 选择需求场景：提供售后服务、内部 IT 支持、设备售后排查和销售跟进 4 个通用练习场景。
2. 主动提问，逐步明确目标、范围、流程、数据、权限、验收与约束。可展开通用提示。
3. 在右侧保存笔记，也可点击消息旁「记笔记」引用原话。笔记支持分类、编辑和删除；未保存草稿保存在浏览器本地。生成文档前自动保存笔记草稿。
4. 至少完成一轮对话后生成文档。模型区分已确认、待确认与冲突；个人笔记不自动视为业务承诺。
5. 点击 M/N 来源查看生成时的证据快照，人工复核后点击「确认定稿」，或「继续补充澄清」。定稿不代表真实业务方签字验收；导出包含完整来源附录的 Markdown。继续澄清后会提示旧文档过期，可生成新版本并切换查看。
6. 左侧恢复历史练习；刷新页面会恢复当前练习。数据保存在 data/practice.sqlite3，备份该文件前建议先停止服务。
7. 最近练习每条记录右侧可点击「删除」，确认后删除该次对话、笔记、文档版本和 LangGraph checkpoints，并清除当前浏览器的对应草稿。删除当前练习会回到场景选择页；删除其他练习不影响当前工作。此操作不可撤销，已导出的文件不受影响。
8. 点击左侧第 1、3、5 阶段或顶部「阶段指南」，查看本阶段目标、任务清单、示例问题、交付物和完成标准。条目可展开，支持切换阶段及 Esc 关闭；手机上通过顶部入口查看。指南不调用模型、不读取场景答案、不自动判定完成，等待模型回复时也可以阅读。第 3 阶段可通过「进入技术方案设计」使用画布与评审，第 5 阶段仍仅开放指南。

实现结构

• graph.py：LangGraph StateGraph、状态类型、循环路由、人工中断、持久化恢复与实际执行轨迹。
• models.py：所有 Agent 共用的 DeepSeek 调用层，只读取本项目或显式 DeepSeek 环境变量。
• schemas.py：需求条目与总结的 Pydantic 结构、公共异常和分类。
• scenarios.py：公开场景与服务端隐藏业务设定。
• agents.py：需求方和总结角色逻辑、独立来源校验、Markdown 导出。
• app.py：FastAPI、输入校验和每场会话串行协调；storage.py：SQLite 会话读写。图节点调用存储层记录对话、笔记与文档。
• web/：无需构建的 HTML / CSS / JavaScript 界面；动态文本使用 textContent 渲染。
• tests/：接口、证据、失败恢复、持久化等测试。

这是两个角色按用户操作协作的系统，不是两个模型自动互相聊天。练习者掌握提问与生成时机；总结不会替代业务确认。模型仍可能误判语义，来源 ID 校验只能保证来源存在，不能证明内容与证据完全一致。

LangGraph 主图与子图

主图负责等待输入、调度两个真实编译的子图和人工审阅：

• 需求澄清子图：用户问题记录、需求方回复、回复校验与记录，以及用户笔记保存。
• 文档生成子图：读取实际对话与笔记、总结、来源校验、Markdown 生成与草稿保存。

子图直接以编译后的 StateGraph 注册到主图，继承父图 checkpointer；不是仅在图片中分组。

需求澄清子图图片 · 文档生成子图图片

流程与状态

通用练习题库

题库覆盖客户服务、IT 支持、设备售后排查和销售跟进。所有人物、接口、规模及验收数字均为教学设定，不代表任何企业的实际业务。隐藏事实不会通过题库接口下发。

流程为：载入练习 → 等待用户 → 记录问题 → 需求方 Agent → 校验并记录回复 → 等待用户。 用户选择生成文档时，从同一图状态读取对话与笔记 → 总结 Agent → 来源校验 → 生成 Markdown → 保存草稿 → 人工审阅。 审阅可以继续补充，也可以定稿结束。记录和保存属于图内确定性节点，无需额外模型调用。

AsyncSqliteSaver 将图状态持久化到同一个 SQLite 文件；await_user 与 human_review 用 interrupt() 暂停，接口通过同一会话 ID 和 Command(resume=...) 继续。已有练习在首次操作时接入新图，保留历史对话与文档。旧文档仍支持导出。

查看 工作流图与节点说明，重新生成原生图片：

..\.venv\Scripts\python.exe render_graph.py

图片通过 LangGraph 原生 draw_mermaid_png() 生成，仅图拓扑发送给 Mermaid 渲染服务，不发送对话、笔记或密钥。LangGraph 人工中断文档。

默认只监听本机，不提供多用户认证；不要直接暴露到公网。按单进程启动，避免绕过会话级内存锁。每次练习最多 50 轮对话、60 条笔记；不支持后台任务、流式输出和浏览器断开后的任务状态查询。若请求中途断开，先刷新查看是否已保存，再重试。

验证

..\.venv\Scripts\python.exe -m pytest -q

技术方案设计练习（阶段 3）

从左侧「技术方案设计」在当前页面切换，自动关联当前练习；阶段指南按钮独立保留。已定稿需求文档旁也可点击「进入技术方案设计」。/design 保留为兼容地址。选择已定稿需求版本后，从开始和结束节点自行搭建流程。

• 画布：拖动节点调整位置，从圆点拖到目标节点建立连线；也可依次点击连接点。步骤列表同步编辑，连线条件可用自然语言。
• 配置：执行方式、输入输出、工具与知识来源、异常处理、Agent 归属、设计理由。Shift 点击画布节点或勾选列表可批量分配 Agent。
• 保存：浏览器草稿保留未保存编辑；显式保存写入 SQLite。修订号防止其他页面覆盖；冲突时可下载当前 JSON 草稿备份。
• 评审：保存后选择整个方案或当前节点，向技术负责人提问。真实模式调用相同 DeepSeek 配置；离线演示明确只检查字段与图连接。评审建议不会自动改图。
• 决策：填写理由后选择采纳、暂缓或不采纳，写入个人决策记录；采纳后自行修改相关步骤。导出 Markdown 保留节点、连线、决策和版本化评审记录。

方案按练习 ID 和需求版本独立存储，固定引用选定的需求快照；需求更新时显示提示，不自动迁移设计。删除练习同时删除其方案。当前不执行真实业务工具，也不含案例推演或自动生成方案功能。

design.py 定义方案契约和 LangGraph 评审流程（结构检查 → 技术负责人 Agent）；web/design.* 提供独立编辑页面。所有本地扩展题库仍保存在忽略提交的 data/ 下。