98d113883e
Design covers: agent loop, LLM provider abstraction, transport layer, context management, skill system, tool registry. P0 plan targets the minimum viable loop: user input → LLM streaming → tool call → output. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
5.8 KiB
5.8 KiB
AI Coding Assistant — P0 实现计划
日期：2026-05-12 基于：
docs/plans/2026-05-12-ai-coding-assistant-design.md（已批准） 范围：P0 — 核心 agent loop + OpenAI 兼容 provider + stdio transport
目标
跑通最小闭环：用户输入 → LLM 流式响应 → 工具调用 → 输出
前置条件
- Python 3.12+ 环境
- 依赖：httpx, pytest, pytest-asyncio, respx, pydantic
任务清单
Batch 1：项目脚手架 + 消息模型 + LLM Provider 抽象
T01: 初始化项目结构
- 修改目标：创建 Python 包结构、pyproject.toml、基础配置
- 涉及文件：
pyproject.toml— 项目元数据、依赖、pytest 配置packages/core/__init__.pypackages/core/agent/__init__.pypackages/core/llm/__init__.pypackages/core/transport/__init__.pypackages/core/context/__init__.pypackages/core/skills/__init__.pypackages/core/tools/__init__.py
- 验证方式：
pip install -e .成功，python -c "import packages.core"无报错 - 完成判定：包可安装、可导入
T02: 实现消息模型（messages.py）
- 修改目标：定义 Agent 内部消息类型和 LLM API 消息类型
- 涉及文件：
packages/core/agent/messages.py— AgentMessage, UserMessage, AssistantMessage, ToolResultMessage, SystemMessagetests/core/agent/test_messages.py— 消息模型序列化/反序列化测试
- 验证方式：
pytest tests/core/agent/test_messages.py通过 - 完成判定：所有消息类型可正确创建、序列化为 dict、从 dict 反序列化
T03: 实现 LLM Provider 抽象接口（llm/base.py）
- 修改目标：定义 LLMProvider ABC、StreamChunk、ToolDef 类型
- 涉及文件：
packages/core/llm/base.py— LLMProvider, StreamChunk, ToolDef, Message 等类型tests/core/llm/test_base.py— 类型构造测试
- 验证方式：
pytest tests/core/llm/test_base.py通过 - 完成判定：抽象接口可被正确继承，类型可正确构造
Batch 2：OpenAI 兼容 Provider + 工具系统基础
T04: 实现 OpenAI 兼容 Provider
- 修改目标：实现 stream_chat、convert_messages、convert_tools
- 涉及文件：
packages/core/llm/openai_compat.py— OpenAICompatProvidertests/core/llm/test_openai_compat.py— 使用 respx mock HTTP 测试
- 验证方式：
pytest tests/core/llm/test_openai_compat.py通过 - 完成判定：
- 流式调用返回正确的 StreamChunk 序列（content + tool_call + done）
- AgentMessage → OpenAI Message 转换正确
- ToolDef → OpenAI tool 格式转换正确
- 错误重试逻辑（指数退避，最多 3 次）
T05: 实现工具系统基础（tools/base.py）
- 修改目标：定义 Tool 基类、ToolRegistry、ToolResult
- 涉及文件：
packages/core/tools/base.py— Tool ABC, ToolRegistry, ToolResultpackages/core/tools/builtin/echo.py— 内置 echo 工具（用于测试）tests/core/tools/test_base.py— 注册、查找、执行测试
- 验证方式：
pytest tests/core/tools/test_base.py通过 - 完成判定：工具可注册、可按名查找、可执行并返回 ToolResult
Batch 3：Agent Loop + Transport + 端到端闭环
T06: 实现 Agent Loop 核心（agent/loop.py）
- 修改目标：实现 runLoop 主循环（流式响应 + 工具调用 + follow-up）
- 涉及文件：
packages/core/agent/loop.py— AgentLoop, AgentConfig, runLooppackages/core/agent/hooks.py— Hook 定义（P0 仅定义接口，默认实现）tests/core/agent/test_loop.py— 使用 mock provider 测试循环逻辑
- 验证方式：
pytest tests/core/agent/test_loop.py通过 - 完成判定：
- 单轮对话：用户输入 → LLM 响应 → 结束
- 多轮工具调用：LLM 返回 tool_call → 执行工具 → 结果回传 → 继续
- follow-up 消息处理
- 错误处理：LLM 调用失败返回错误事件
T07: 实现 stdio Transport
- 修改目标：实现 Transport ABC + stdio JSON-RPC 传输
- 涉及文件：
packages/core/transport/base.py— Transport ABC, AgentEvent, AgentRequestpackages/core/transport/stdio.py— StdioTransporttests/core/transport/test_stdio.py— subprocess 集成测试
- 验证方式：
pytest tests/core/transport/test_stdio.py通过 - 完成判定：
- stdin 接收 JSON-RPC 请求
- stdout 输出 JSON-RPC 响应/通知
- 事件流式输出（token / tool_call / tool_result / done / error）
T08: 实现入口 CLI + 端到端测试
- 修改目标：创建 CLI 入口，串联所有模块，跑通最小闭环
- 涉及文件：
packages/core/__main__.py— CLI 入口packages/core/cli.py— 参数解析、配置加载tests/core/test_e2e.py— 端到端测试（mock LLM server）
- 验证方式：
pytest tests/core/test_e2e.py通过python -m packages.core --help输出帮助信息- 手动测试：
echo '{"method":"chat","params":{"message":"hello"}}' | python -m packages.core --provider openai-compat --model gpt-4o可获得流式响应
- 完成判定：
- CLI 可启动
- 端到端闭环：输入 → LLM 流式输出 → 工具调用 → 结果输出
- 优雅退出（Ctrl+C / EOF）
依赖关系
T01 → T02 → T03 → T04 → T06
↘ T05 → T06
T03 → T07
T06 + T07 → T08
风险与待确认项
- OpenAI API Key：测试需要 mock，不需要真实 key；手动测试需要用户提供
- stdio JSON-RPC 协议细节：具体消息格式需要在 T07 实现时细化
- Python 包命名：
packages.core是否合适？考虑改为ai_coding_assistant或更短的名字