qiniu
diff --git a/‎docs/codeagent-v0.1-en.md
Lines changed: 265 additions & 0 deletions b/‎docs/codeagent-v0.1-en.md
Lines changed: 265 additions & 0 deletions
diff --git a/‎docs/codeagent-v0.2-en.md
Lines changed: 71 additions & 0 deletions b/‎docs/codeagent-v0.2-en.md
Lines changed: 71 additions & 0 deletions
@@ -0,0 +1,265 @@
+# Code Agent System Design v0.1
+
+## Project Overview
+
+Code Agent is an automated code generation system developed in Go that receives `/code` commands through GitHub Webhooks, automatically generates code for Issues, and creates Pull Requests.
+
+## System Architecture
+
+```
+GitHub Issue (/code) → Webhook → Code Agent → Temporary Repository → Claude Code Container → PR
+```
+
+## Core Workflow
+
+### 1. Webhook Reception and Parsing
+
+- Listen for GitHub Issue comment events
+- Detect `/code` command triggers
+- Parse Issue content and context information
+
+### 2. Temporary Repository Preparation
+
+- Clone target repository to temporary directory
+- Create new branch (e.g., `Code-agent/issue-123`)
+- Generate initial commit: "Code-agent has received information, preparing to implement target issue"
+- Push branch and create PR
+
+### 3. Claude Code Execution
+
+- Mount temporary directory to Claude Code container
+- Pass Issue description and requirements as prompts
+- Execute automated code generation and modification
+- Implement functionality based on Issue requirements
+
+### 4. Result Processing
+
+- Parse Claude Code output and generated code
+- Commit changes with descriptive messages
+- Push to remote branch
+- Update PR description with implementation details
+
+## Technical Implementation
+
+### Directory Structure
+
+```
+/tmp/codeagent/
+├── repos/
+│   └── owner-repo-issue-123/
+│       ├── .git/
+│       └── [repository files]
+└── sessions/
+    └── claude-session-123/
+        └── [Claude execution context]
+```
+
+### Key Components
+
+#### 1. Webhook Handler
+- **File**: `internal/webhook/handler.go`
+- **Functionality**: Process GitHub webhook events
+- **Trigger Detection**: Parse comments for `/code` commands
+
+#### 2. Workspace Manager
+- **File**: `internal/workspace/manager.go`
+- **Functionality**: Manage temporary Git repositories
+- **Operations**: Clone, branch creation, cleanup
+
+#### 3. GitHub Client
+- **File**: `internal/github/client.go`
+- **Functionality**: GitHub API interactions
+- **Operations**: PR creation, commit pushing, status updates
+
+#### 4. Code Execution Engine
+- **File**: `internal/code/claude.go`
+- **Functionality**: Claude Code container management
+- **Operations**: Container creation, prompt execution, result parsing
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# GitHub Configuration
+GITHUB_TOKEN=your_github_token
+WEBHOOK_SECRET=your_webhook_secret
+
+# Claude Configuration  
+CLAUDE_API_KEY=your_claude_api_key
+
+# System Configuration
+WORKSPACE_PATH=/tmp/codeagent
+```
+
+### Config File (config.yaml)
+
+```yaml
+github:
+  token: "${GITHUB_TOKEN}"
+  webhook_secret: "${WEBHOOK_SECRET}"
+
+code:
+  provider: "claude"
+  claude:
+    api_key: "${CLAUDE_API_KEY}"
+    model: "claude-3-sonnet-20240229"
+
+workspace:
+  base_path: "/tmp/codeagent"
+  cleanup_after_hours: 24
+
+server:
+  port: 8888
+  host: "0.0.0.0"
+```
+
+## Key Features
+
+### 1. Automated Issue Processing
+- Parse Issue requirements automatically
+- Generate appropriate code solutions
+- Create PR with implementation
+
+### 2. Git Repository Management
+- Temporary workspace isolation
+- Automatic branch management
+- Clean commit history
+
+### 3. Claude Code Integration
+- Container-based execution
+- Context-aware code generation
+- Error handling and retry logic
+
+### 4. GitHub Integration
+- Real-time webhook processing
+- PR status updates
+- Automatic cleanup
+
+## Error Handling
+
+### Common Scenarios
+
+1. **GitHub API Rate Limits**
+   - Implement exponential backoff
+   - Queue requests when limit exceeded
+   - Graceful degradation
+
+2. **Claude Code Failures**
+   - Retry mechanism with different prompts
+   - Fallback to simpler implementations
+   - Error reporting in PR comments
+
+3. **Git Operation Failures**
+   - Repository state validation
+   - Conflict resolution strategies
+   - Workspace cleanup on failure
+
+4. **Resource Management**
+   - Disk space monitoring
+   - Process timeout handling
+   - Memory usage optimization
+
+## Security Considerations
+
+### 1. Webhook Security
+- Signature verification for all incoming requests
+- IP allowlisting for GitHub webhooks
+- Rate limiting to prevent abuse
+
+### 2. Code Execution Security
+- Containerized execution environment
+- Resource limits (CPU, memory, disk)
+- Network isolation
+
+### 3. Repository Access
+- Token scope limitation
+- Read-only access where possible
+- Audit logging for all operations
+
+## Deployment
+
+### Docker Deployment
+
+```dockerfile
+FROM golang:1.21-alpine AS builder
+WORKDIR /app
+COPY . .
+RUN go build -o codeagent ./cmd/codeagent
+
+FROM alpine:latest
+RUN apk --no-cache add ca-certificates git
+WORKDIR /root/
+COPY --from=builder /app/codeagent .
+CMD ["./codeagent"]
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: codeagent
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: codeagent
+  template:
+    metadata:
+      labels:
+        app: codeagent
+    spec:
+      containers:
+      - name: codeagent
+        image: codeagent:latest
+        ports:
+        - containerPort: 8888
+        env:
+        - name: GITHUB_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: github-secrets
+              key: token
+        volumeMounts:
+        - name: workspace
+          mountPath: /tmp/codeagent
+      volumes:
+      - name: workspace
+        emptyDir: {}
+```
+
+## Future Enhancements
+
+### v0.2 Planned Features
+- Multi-language support (Python, JavaScript, etc.)
+- Advanced prompt engineering
+- Code quality validation
+- Integration testing automation
+
+### v0.3 Roadmap
+- Multiple AI provider support (OpenAI, Gemini)
+- Custom code templates
+- Advanced context understanding
+- Performance optimizations
+
+## Monitoring and Logging
+
+### Metrics Collection
+- Request processing time
+- Success/failure rates
+- Resource usage statistics
+- GitHub API usage tracking
+
+### Log Levels
+- **DEBUG**: Detailed execution flow
+- **INFO**: Key operation milestones
+- **WARN**: Recoverable errors
+- **ERROR**: Critical failures requiring attention
+
+### Health Checks
+- `/health` endpoint for load balancer
+- Database connectivity checks
+- External service availability
+- Resource utilization monitoring
@@ -0,0 +1,71 @@
+# 1. Background
+CodeAgent is a tool that assists with code development on GitHub.
+
+# 2. Process Flow
+We can understand CodeAgent as a real "person" who, by understanding the descriptions/problems in GitHub Issues, creates Pull Requests, and then modifies code based on reviewers' suggestions until the Pull Request is merged.
+
+1. Preparation Phase
+    - Host machine prerequisites
+        - claude-code (npm install -g @anthropic-ai/claude-code) 
+        - gemini-cli (npm install -g @google/gemini-cli)
+    - Complete claude-code and gemini-cli authentication (to obtain authentication files)
+
+2. Startup Phase
+    - Triggered by Issue Assignment or /code command
+    - Prepare code:
+        - Pull from RepoInfo in webhook, skip if already pulled
+        - git worktree add ./issue-${id}-${timestamp} -b codeagent/issue-${id}-${timestamp} 
+    - Start container 
+        - Mount code directory as workspace -v `issue-${id}-${timestamp}`:/workspace
+        - Mount authentication information:
+            - gemini-cli auth info at: `~/.gemini:~/.gemini`
+        - Mount tools -v /user/local/bin/gemini:/user/local/bin/gemini
+      - Start gemini/claude (may be wrapped codeagent in the future)
+    - Code layer exposes external interfaces
+        - Input / Output interfaces
+3. Interaction Phase
+    - Interaction 1
+        - Input: This is the Issue content ${issue}, organize a modification plan based on the Issue content
+        - Output: Comment the output content as the first comment in the PR
+    - Interaction 2: 
+        - Input: Modify code according to issue content
+        - After output completion, comment the output to GitHub in format: <details><summary>Session Name</summary>$output</details>
+        - Submit commit & push
+    - Review comment:
+        - Input: issue comment        
+        - After output completion, comment the output to GitHub: <details><summary>Session Name</summary>$output</details>
+      - Submit commit & push
+4. Completion Phase
+    - Trigger action: merge/close PR
+    - Clean up session (if possible)
+    - Close container
+    - git worktree del ./issue-${id}-${timestamp} 
+    - Close issue
+  
+# 3. Specification Definition
+
+1. Create a code object through a startup command
+   
+```golang
+// Create PR first -> PR ID
+// Create a code object
+// 1. Start container using agent tools, need to implement gemini / claude
+// code ,err := agent.Create(repo)
+
+// Enter interactive mode, send messages through Prompt
+res, err := code.Prompt(message)
+out, err := io.ReadAll(res.out)
+
+code, err := agent.Resume(workspace)
+// Receive review comment, find code through PR ID
+res, err := code.Prompt(comment)
+
+// End:
+// Close PR
+// Call code.Close()
+// 1. Clean up session (if possible)
+// 2. Close container
+// 3. Clean up workspace: git worktree del ./issue-${id}-${timestamp}
+// code.Close()
+// Close issue
+```