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>
145 lines
5.8 KiB
Markdown
145 lines
5.8 KiB
Markdown
# 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__.py`
|
||
- `packages/core/agent/__init__.py`
|
||
- `packages/core/llm/__init__.py`
|
||
- `packages/core/transport/__init__.py`
|
||
- `packages/core/context/__init__.py`
|
||
- `packages/core/skills/__init__.py`
|
||
- `packages/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, SystemMessage
|
||
- `tests/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` — OpenAICompatProvider
|
||
- `tests/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, ToolResult
|
||
- `packages/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, runLoop
|
||
- `packages/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, AgentRequest
|
||
- `packages/core/transport/stdio.py` — StdioTransport
|
||
- `tests/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
|
||
```
|
||
|
||
## 风险与待确认项
|
||
|
||
1. **OpenAI API Key**：测试需要 mock，不需要真实 key；手动测试需要用户提供
|
||
2. **stdio JSON-RPC 协议细节**：具体消息格式需要在 T07 实现时细化
|
||
3. **Python 包命名**：`packages.core` 是否合适？考虑改为 `ai_coding_assistant` 或更短的名字
|