# basic-open-agent

**Repository Path**: chutianshu1981/basic-open-agent

## Basic Information

- **Project Name**: basic-open-agent
- **Description**: 基础通用ai agent 底座
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Platform

基于 Claude Agent SDK 的通用 AI Agent 应用底座。

## 项目定位

提供一个可扩展的 AI Agent 服务层，通过 Web API 暴露 Agent 能力。后续可接入多种 Agent 实现（Claude、OpenAI、本地模型等），支持工具调用、多轮对话、会话管理等。

## 技术栈

### Web API 服务

| 层级 | 技术 |
|------|------|
| Python 版本 | 3.14 |
| 包管理 | pdm + uv |
| Web 框架 | FastAPI |
| Agent SDK |  Claude Agent SDK |
| 配置 | Pydantic Settings |
| 日志 | structlog |
| 测试 | pytest + pytest-asyncio |

### 鸿蒙 HAP 客户端

| 层级 | 技术 |
|------|------|
| 目标系统 | HarmonyOS NEXT 6.0+ |
| SDK API | API 12+（目标 API 20） |
| 开发语言 | ArkTS |
| UI 框架 | ArkUI（声明式 UI） |
| 状态管理 | ArkUI V2 装饰器（`@ObservedV2` / `@ComponentV2`） |
| 应用模型 | Stage 模型 |
| 构建工具 | Hvigor |
| 包管理 | ohpm |
| 编译运行 | ArkCompiler |
| IDE | DevEco Studio |

## 项目结构

```
basic-open-agent/
├── codes/                       # 各子项目代码目录
│   ├── web-api-service/         # Python Web API 服务 (Loop-1)
│   └── harmonyos-client/        # 鸿蒙 App 客户端 (Loop-2+)
├── docs/                        # 项目文档
│   ├── architecture.md          # 系统架构文档
│   ├── requirements/            # 需求文档
│   │   └── loop-1-chat-mvp.md   # Loop-1 需求
│   └── plans/                   # 实现计划
│       ├── loop-00-01-索引.md          # 计划总览与导航
│       ├── loop-00-02-开发环境搭建.md   # 环境准备
│       └── loop-01-*.md                # Loop-1 实现计划（9 个任务拆分）
├── AGENTS.md
├── .gitignore
├── README.md
└── pdm.lock
```

## 子项目说明

### codes/web-api-service/

Python FastAPI 实现的 Web API 服务，提供 OpenAI 兼容的 Chat Completions API。

- **技术栈**: Python 3.14, FastAPI, openai, Pydantic v2
- **当前状态**: Loop-1 MVP 开发中
- **API 端点**: `/v1/chat/completions`
- **详细文档**: `docs/requirements/loop-1-chat-mvp.md`

### codes/harmonyos-client/

鸿蒙 HarmonyOS NEXT 原生应用客户端（HAP）。

- **技术栈**: ArkTS, ArkUI, Hvigor, ohpm
- **目标系统**: HarmonyOS NEXT 6.0+ (API 12+)
- **当前状态**: 待开发 (Loop-2)
- **功能规划**: 对话界面、多轮会话历史、设置管理、网络请求与后端 API 对接

## 开发循环

本项目采用文档驱动开发，每个循环包含：
1. **需求文档** (`docs/requirements/`) — 定义本轮要做什么
2. **架构文档** (`docs/architecture.md`) — 描述系统设计与接口契约
3. **实现计划** (`docs/plans/`) — 细粒度任务分解
4. **编码实现** — 按 plan 逐步执行
5. **验收测试** — 验证需求满足度

---

## 当前循环: Loop-1 (MVP — 基础问答服务)

- 状态: 📋 文档评审完成，准备编码
- 目标: 实现 `codes/web-api-service/`，提供 `/v1/chat/completions` 端点
- 详细计划见: `docs/plans/loop-00-01-索引.md`

## 快速开始 (Loop-1 完成后)

```bash
cd codes/web-api-service

# 安装依赖
pdm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 ANTHROPIC_API_KEY 和 API_AUTH_TOKEN

# 运行开发服务器
pdm run dev

# 运行测试
pdm run test
```

## 测试 API

```bash
# 健康检查
curl http://localhost:8000/health

# 问答请求
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-27b-q5km.gguf",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```