liukunup/ai-software-engineer repository overview

# 克隆仓库
git clone https://github.com/liukunup-ai/ai-software-engineer.git
cd ai-software-engineer

# 创建虚拟环境并安装依赖
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 启动服务（使用启动脚本）
./start.sh

# 或直接使用 uvicorn
cd app
uvicorn main:app --host 0.0.0.0 --port 8007 --reload

# 使用 Makefile 构建并运行
make build
make run

# 或使用 Docker 命令
docker build -f docker/Dockerfile -t ai-software-engineer:latest .
docker run -d \
  --name ai-worker \
  -e NODE_MODE=standalone \
  -p 8007:8007 \
  ai-software-engineer:latest

# 配置环境变量
export REGISTER_URL=http://master-node:8000
export REGISTER_KEY=your-secret-key
export NODE_NAME=worker-01

# 使用启动脚本
./start.sh --register http://master-node:8000 --key your-secret-key

# 或使用 Docker Compose
docker-compose up -d

├── Ubuntu 24.04 LTS
├── Python 3.12
├── Node.js 22.x
├── Docker CLI
├── Git
├── curl, wget
├── vim, tree
└── 其他常用 CLI 工具

# GitHub Copilot (可选安装)
gh copilot suggest "your task"
gh copilot explain "complex command"

# OpenAI Codex (可选安装)
codex help

# Claude Code (可选安装)
claude-code help

# Cursor (可选安装)
cursor help

# Alibaba Qoder (可选安装)
qoder help

# Tencent Codebuddy (可选安装)
tencent-codebuddy help

# OpenCode (可选安装)
opencode help

# 本地开发（不使用 Docker）
./start.sh

# 使用 Makefile（Docker）
make build
make run

# 自定义参数
./start.sh --port 8080 --register http://master:8000 --key secret

# Standalone
docker run -d \
  --name ai-standalone \
  -e NODE_MODE=standalone \
  -e ALLOWED_COMMANDS=echo,date,ls,python3,node \
  -p 8007:8007 \
  ai-software-engineer:latest

# Worker
docker run -d \
  --name ai-worker \
  -e NODE_MODE=worker \
  -e REGISTER_URL=http://master:8000 \
  -e REGISTER_KEY=your-key \
  -e NODE_NAME=worker-1 \
  -e NODE_HOST=192.168.1.100 \
  -e NODE_PORT=8007 \
  -p 8007:8007 \
  ai-software-engineer:latest

version: '3.8'

services:
  ai-software-engineer:
    image: ai-software-engineer:latest
    container_name: ai-software-engineer
    restart: unless-stopped
    ports:
      - "8007:8007"
    environment:
      NODE_MODE: worker  # 或 standalone
      REGISTER_URL: http://localhost:8000
      REGISTER_KEY: key
      NODE_NAME: ai-software-engineer
      NODE_HOST: 127.0.0.1
      NODE_PORT: 8007
      HEARTBEAT_INTERVAL: 30
      ALLOWED_COMMANDS: echo,date,ls
      COMMAND_TIMEOUT: 15

docker-compose -f docker/docker-compose.yml up -d

# 部署
kubectl apply -f docker/k8s-deployment.yaml

# 扩容
kubectl scale deployment ai-worker --replicas=10

# 查看状态
kubectl get pods -l app=ai-worker

# 查看所有可用命令
make help

# 构建完整镜像（包含所有 AI 工具）
make build

# 强制重新构建（不使用缓存）
make build-no-cache

# 构建最小化镜像（仅必要工具）
make build-minimal

# 指定镜像名称和标签
make build IMAGE_NAME=myorg/ai-worker IMAGE_TAG=v1.0

# 选择性安装 AI 工具
docker build \
  --build-arg INSTALL_GITHUB_COPILOT=true \
  --build-arg INSTALL_OPENAI_CODEX=false \
  --build-arg INSTALL_CURSOR=false \
  --build-arg INSTALL_ALIBABA_QODER=true \
  -f docker/Dockerfile \
  -t ai-software-engineer:custom .

# 指定 Python 和 Node.js 版本
docker build \
  --build-arg PYTHON_VERSION=3.12 \
  --build-arg NODE_VERSION=22.x \
  -f docker/Dockerfile \
  -t ai-software-engineer:latest .

curl http://localhost:8007/healthz

{
  "status": "healthy",
  "mode": "standalone",
  "node_name": "dev-node",
  "allowed_commands": ["echo", "date", "ls", "python3"],
  "command_timeout": 15.0
}

{
  "status": "healthy",
  "mode": "worker",
  "node_name": "worker-01",
  "node_id": "123e4567-e89b-12d3-a456-426614174000",
  "register_url": "http://master:8000",
  "allowed_commands": ["echo", "date", "ls", "python3"],
  "command_timeout": 15.0
}

# 执行 echo 命令
curl -X POST http://localhost:8007/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "echo",
    "args": ["Hello", "World"]
  }'

{
  "command": "echo",
  "args": ["Hello", "World"],
  "exit_code": 0,
  "stdout": "Hello World\n",
  "stderr": "",
  "duration_ms": 12.5
}

# 更新命令白名单
curl -X POST http://localhost:8007/config/commands \
  -H "Content-Type: application/json" \
  -d '{
    "commands": ["echo", "date", "ls", "pwd", "python3", "node"]
  }'

# 更新命令超时
curl -X POST http://localhost:8007/config/timeout \
  -H "Content-Type: application/json" \
  -d '{
    "timeout": 30.0
  }'

// 命令不在白名单
{
  "detail": "Command 'rm' is not allowed"
}

// 命令执行失败
{
  "detail": "Command 'invalid_cmd' not found"
}
{
  "detail": "命令执行超时"
}

// 命令未找到
{
  "detail": "命令未找到，请检查容器或系统中是否已安装"

# .env 文件（Worker 模式）
NODE_MODE=worker
REGISTER_URL=http://192.168.1.100:8000
REGISTER_KEY=my-secret-key-2024
NODE_NAME=worker-prod-01
NODE_HOST=192.168.1.101
NODE_PORT=8007
NODE_DESC=Production Worker Node
NODE_TAGS=production,gpu,high-memory
HEARTBEAT_INTERVAL=30
ALLOWED_COMMANDS=echo,date,ls,pwd,cat,python3,node,npm,git
COMMAND_TIMEOUT=30
LOG_LEVEL=info
AISE_ENV=production

# .env 文件（Standalone 模式）
NODE_MODE=standalone
NODE_NAME=dev-node
ALLOWED_COMMANDS=echo,date,ls,pwd,python3,node
COMMAND_TIMEOUT=15
PORT=8007
LOG_LEVEL=debug
RELOAD=true
AISE_ENV=dev

ai-software-engineer/
├── 📄 README.md                     # 项目文档（本文件）
├── 📄 GETTING_STARTED.zh-CN.md      # 快速开始指南
├── 📄 LICENSE                       # 开源许可证
├── 📄 Makefile                      # 构建自动化
├── 📄 requirements.txt              # Python 依赖
├── 🚀 start.sh                      # 启动脚本
├── 🚀 start.ps1                     # PowerShell 启动脚本
│
├── 📁 app/                          # FastAPI 应用
│   ├── __init__.py
│   └── main.py                      # 主程序入口
│
├── 📁 docker/                       # Docker 相关文件
│   ├── Dockerfile                   # Docker 镜像定义
│   ├── docker-compose.yml           # Docker Compose 配置
│   ├── entrypoint.sh                # 容器入口脚本
│   ├── k8s-deployment.yaml          # Kubernetes 部署配置
│   ├── .env.example                 # 环境变量示例
│   └── 📁 scripts/                  # AI 工具安装脚本
│       ├── install-github-copilot.sh
│       ├── install-openai-codex.sh
│       ├── install-claude-code.sh
│       ├── install-cursor.sh
│       ├── install-opencode.sh
│       ├── install-alibaba-qoder.sh
│       └── install-tencent-codebuddy.sh
│
└── 📁 docs/                         # 文档目录（预留）

# 进入容器
docker exec -it ai-worker bash

# 认证 GitHub
gh auth login

# 使用 Copilot
gh copilot suggest "create a REST API with Python FastAPI"
gh copilot explain "docker run -it --rm -v \$(pwd):/app ubuntu bash"
---

## 🎓 使用教程

### AI 工具配置

#### GitHub Copilot

```bash
# 进入容器
docker exec -it ai-worker bash

# 认证 GitHub
gh auth login

# 使用 Copilot
gh copilot suggest "create a REST API with Python FastAPI"
gh copilot explain "docker run -it --rm -v \$(pwd):/app ubuntu bash"

# 本地开发（热重载）
./start.sh --no-reload=false

# 或使用 Docker（代码热加载）
docker run -it --rm \
  -e NODE_MODE=standalone \
  -e RELOAD=true \
  -v $(pwd)/app:/app \
  -p 8007:8007 \
  ai-software-engineer:latest

# 查看日志
docker logs -f ai-worker
tail -f ai-software-engineer.log

# 使用 Kubernetes
kubectl apply -f docker/k8s-deployment.yaml
kubectl get pods -w

# 扩容到 10 个副本
kubectl scale deployment ai-worker --replicas=10

# 滚动更新
kubectl set image deployment/ai-worker \
  worker=ai-software-engineer:v2.0

# 查看状态
kubectl rollout status deployment/ai-worker

echo, date, ls, pwd, cat, python3, node, npm, git status, docker ps

rm, shutdown, reboot, dd, mkfs, fdisk

curl, wget, apt, yum  # 仅在必要时添加

docker run -d \
  --name ai-worker \
  --user 1000:1000 \
  --read-only \
  --security-opt=no-new-privileges \
  --cpus=2 \
  --memory=4g \
  -e NODE_MODE=standalone \
  -p 8007:8007 \
  ai-software-engineer:latest

# 测试 Standalone 模式
./start.sh --test-mode

# 测试健康检查
curl http://localhost:8007/healthz

# 测试命令执行
curl -X POST http://localhost:8007/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "echo", "args": ["test"]}'

# 测试配置更新
curl -X POST http://localhost:8007/config/commands \
  -H "Content-Type: application/json" \
  -d '{"commands": ["echo", "date", "ls", "pwd"]}'

# 构建并测试
make build
make run
make health-check

# 查看容器状态
docker ps --filter "name=ai-worker"

# 本地开发日志
tail -f ai-software-engineer.log

# Docker 容器日志
docker logs -f ai-worker
docker logs --tail 100 ai-worker

# Kubernetes 日志
kubectl logs -f deployment/ai-worker
kubectl logs -l app=ai-worker --tail=100

# 容器资源使用
docker stats ai-worker

# Kubernetes 资源使用
kubectl top pods -l app=ai-worker

# 检查后端连接
curl $REGISTER_URL/healthz

# 验证配置
docker logs ai-worker | grep "后端地址"

# 检查网络连接
docker exec ai-worker curl -v $REGISTER_URL/healthz

# 方法1: 重启时添加命令到白名单
docker run -d \
  -e ALLOWED_COMMANDS=echo,date,ls,your-command \
  ...

# 方法2: 运行时更新白名单
curl -X POST http://localhost:8007/config/commands \
  -H "Content-Type: application/json" \
  -d '{"commands": ["echo", "date", "ls", "your-command"]}'
  -d '{"commands": ["echo", "date", "ls", "your-command"]}'

# 查看详细日志
docker logs ai-worker

# 检查端口占用
lsof -i :8007

# 使用不同端口
docker run -d -p 8008:8007 ...

# 查找占用端口的进程
lsof -i :8007
netstat -anp | grep 8007

# 修改启动端口
./start.sh --port 8008

# 1. Fork 项目
# 2. 克隆仓库
git clone https://github.com/your-username/ai-software-engineer.git

# 3. 创建特性分支
git checkout -b feature/amazing-feature

# 4. 提交更改
git commit -m "feat: Add amazing feature"

# 5. 推送到分支
git push origin feature/amazing-feature

# 6. 创建 Pull Request