本地智能体开发-完整对话记录#

消息 ID： om_x100b5688bb0018a0c3886348fad79d1

💬 完整对话记录#

问题#

我要创建一个本地智能体，在开发这个智能体时需要用python 创建本地服务，并且需要持续开发，我需要用git 来管理代码和持续开发，把整个过程系统梳理下，如果有遗漏补充下

📋 本地智能体开发系统架构#

一、项目结构设计#

local-agent/
├── src/
│   ├── main.py              # 入口文件
│   ├── agent/               # 智能体核心
│   │   ├── __init__.py
│   │   ├── base.py          # 基类
│   │   ├── handlers.py      # 处理器
│   │   └── tools.py         # 工具集
│   ├── api/                 # API 层
│   │   ├── __init__.py
│   │   ├── routes.py        # 路由定义
│   │   └── schemas.py       # Pydantic 模型
│   └── utils/               # 工具函数
│       ├── __init__.py
│       └── logger.py        # 日志配置
├── tests/
│   ├── __init__.py
│   ├── test_agent.py
│   └── test_api.py
├── configs/
│   └── config.yaml          # 配置文件
├── docs/
│   ├── API.md               # API 文档
│   └── DEPLOYMENT.md        # 部署文档
├── scripts/
│   ├── setup.sh             # 安装脚本
│   └── deploy.sh            # 部署脚本
├── logs/                    # 日志目录
├── .gitignore
├── .env.example
├── requirements.txt
├── pyproject.toml           # 项目配置
├── README.md
└── LICENSE

二、技术栈选择#

组件	推荐方案	说明
Python 版本	3.11+	新特性支持
Web 框架	FastAPI	高性能、异步、自动文档
ASGI 服务器	uvicorn	开发/生产环境
数据验证	Pydantic v2	类型安全
测试框架	pytest	现代化测试
代码格式化	black	自动格式化
代码检查	ruff	快速 linter
依赖管理	poetry	项目级依赖管理
版本控制	git	分布式版本控制
远程仓库	GitHub/GitLab	代码托管
部署方式	systemd 或 Docker	生产环境

三、开发流程（Git 工作流）#

main (生产环境)
  ↓
develop (开发环境)
  ↓
feature/xxx (功能分支)

标准流程：

初始化

git init
git add .
git commit -m "feat: initial commit"

创建开发分支
```
git checkout -b feature/xxx
```

开发 + 提交

git add .
git commit -m "feat: add xxx feature"

创建 Pull Request
- 推送到远程
- 提交 PR 到 develop
- 代码审查
- 合并
打标签发布
```
git tag v1.0.0
git push origin v1.0.0
```

四、自动化工具链#

工具	用途	命令
black	代码格式化	`black src/`
ruff	代码检查	`ruff check src/`
pytest	运行测试	`pytest`
pytest-cov	测试覆盖率	`pytest --cov=src`
pre-commit	Git 钩子	`pre-commit install`

.pre-commit-config.yaml 示例：

repos:
  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml

五、开发环境配置#

requirements.txt：

fastapi==0.109.0
uvicorn[standard]==0.27.0
pydantic==2.5.3
pydantic-settings==2.1.0
python-dotenv==1.0.0
pytest==7.4.4
pytest-cov==4.1.0
black==23.12.1
ruff==0.1.9

pyproject.toml：

[tool.poetry]
name = "local-agent"
version = "0.1.0"
description = "Local AI Agent"
authors = ["Administrator"]

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.109.0"
uvicorn = {extras = ["standard"], version = "^0.27.0"}

[tool.black]
line-length = 100
target-version = ['py311']

[tool.ruff]
line-length = 100
select = ["E", "F", "I"]
ignore = ["E501"]

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]

六、服务配置（systemd）#

/etc/systemd/system/local-agent.service：

[Unit]
Description=Local AI Agent Service
After=network.target

[Service]
Type=simple
User=Administrator
WorkingDirectory=/home/username/local-agent
Environment="PATH=/home/username/.local/bin:/usr/bin"
ExecStart=/usr/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable local-agent
sudo systemctl start local-agent
sudo systemctl status local-agent

七、日志管理#

src/utils/logger.py：

import logging
from pathlib import Path

LOG_DIR = Path("logs")
LOG_DIR.mkdir(exist_ok=True)

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

file_handler = logging.FileHandler(LOG_DIR / "agent.log")
file_handler.setLevel(logging.INFO)

console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)

formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
file_handler.setFormatter(formatter)
console_handler.setFormatter(formatter)

logger.addHandler(file_handler)
logger.addHandler(console_handler)

八、CI/CD（可选）#

GitHub Actions 示例：

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install poetry
      - run: poetry install
      - run: poetry run black --check src/
      - run: poetry run ruff check src/
      - run: poetry run pytest

九、持续开发建议#

每日开发流程

# 1. 拉取最新代码
git pull origin develop

# 2. 创建功能分支
git checkout -b feature/your-feature

# 3. 开发 + 测试
python main.py
pytest

# 4. 代码检查
black src/
ruff check src/

# 5. 提交 + 推送
git add .
git commit -m "feat: xxx"
git push origin feature/your-feature

定期维护
- 每周合并 feature 分支到 develop
- 每月打标签发布
- 定期更新依赖
监控
- 日志文件监控
- 服务状态检查
- 错误告警

📊 总结#

方面	说明
项目结构	清晰分层（agent/api/utils）
技术栈	FastAPI + uvicorn + pytest
Git 工作流	feature 分支 + PR 合并
自动化	pre-commit + black + ruff
部署	systemd 服务
日志	文件 + 控制台双输出
CI/CD	GitHub Actions（可选）

🚀 下一步#

需要我帮你：

创建项目骨架（生成所有文件）
配置开发环境（requirements.txt、pyproject.toml）
配置 Git 仓库（.gitignore、pre-commit）
创建 systemd 服务（部署脚本）

请回复序号（1、2、3 或 4），我将立即执行。

需要我继续帮你创建本地智能体项目吗？