# 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` 或更短的名字