mirror of
https://github.com/cexll/myclaude.git
synced 2026-02-05 02:30:26 +08:00
3ef288bfaa
## Overview Complete implementation of enterprise-level workflow features including multi-backend execution (Codex/Claude/Gemini), GitHub issue-to-PR automation, hooks system, and comprehensive documentation. ## Major Changes ### 1. Multi-Backend Support (codeagent-wrapper) - Renamed codex-wrapper → codeagent-wrapper - Backend interface with Codex/Claude/Gemini implementations - Multi-format JSON stream parser (auto-detects backend) - CLI flag: --backend codex|claude|gemini (default: codex) - Test coverage: 89.2% **Files:** - codeagent-wrapper/backend.go - Backend interface - codeagent-wrapper/parser.go - Multi-format parser - codeagent-wrapper/config.go - CLI parsing with backend selection - codeagent-wrapper/executor.go - Process execution - codeagent-wrapper/logger.go - Async logging - codeagent-wrapper/utils.go - Utilities ### 2. GitHub Workflow Commands - /gh-create-issue - Create structured issues via guided dialogue - /gh-implement - Issue-to-PR automation with full dev lifecycle **Files:** - github-workflow/commands/gh-create-issue.md - github-workflow/commands/gh-implement.md - skills/codeagent/SKILL.md ### 3. Hooks System - UserPromptSubmit hook for skill activation - Pre-commit example with code quality checks - merge_json operation in install.py for settings.json merging **Files:** - hooks/skill-activation-prompt.sh|.js - hooks/pre-commit.sh - hooks/hooks-config.json - hooks/test-skill-activation.sh ### 4. Skills System - skill-rules.json for auto-activation - codeagent skill for multi-backend wrapper **Files:** - skills/skill-rules.json - skills/codeagent/SKILL.md - skills/codex/SKILL.md (updated) ### 5. Installation System - install.py: Added merge_json operation - config.json: Added "gh" module - config.schema.json: Added op_merge_json schema ### 6. CI/CD - GitHub Actions workflow for testing and building **Files:** - .github/workflows/ci.yml ### 7. Comprehensive Documentation - Architecture overview with ASCII diagrams - Codeagent-wrapper complete usage guide - GitHub workflow detailed examples - Hooks customization guide **Files:** - docs/architecture.md (21KB) - docs/CODEAGENT-WRAPPER.md (9KB) - docs/GITHUB-WORKFLOW.md (9KB) - docs/HOOKS.md (4KB) - docs/enterprise-workflow-ideas.md - README.md (updated with doc links) ## Test Results - All tests passing ✅ - Coverage: 89.2% - Security scan: 0 issues (gosec) ## Breaking Changes - codex-wrapper renamed to codeagent-wrapper - Default backend: codex (documented in README) ## Migration Guide Users with codex-wrapper installed should: 1. Run: python3 install.py --module dev --force 2. Update shell aliases if any 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
503 lines
21 KiB
Markdown
503 lines
21 KiB
Markdown
# System Architecture
|
|
|
|
## Overview
|
|
|
|
Multi-agent AI development system with Claude Code as orchestrator and pluggable execution backends.
|
|
|
|
## High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ User │
|
|
└──────────────────┬──────────────────────────────────────────┘
|
|
│
|
|
│ /dev, /gh-implement, etc.
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Claude Code (Orchestrator) │
|
|
│ ┌─────────────────────────────────────────────────────────┐│
|
|
│ │ - Planning & context gathering ││
|
|
│ │ - Requirements clarification ││
|
|
│ │ - Task breakdown ││
|
|
│ │ - Verification & reporting ││
|
|
│ └─────────────────────────────────────────────────────────┘│
|
|
└──────────────────┬──────────────────────────────────────────┘
|
|
│
|
|
│ via codeagent-wrapper
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Codeagent-Wrapper (Execution Layer) │
|
|
│ ┌──────────────────────────────────────────────────────────┤
|
|
│ │ Backend Interface │
|
|
│ ├──────────────┬──────────────┬──────────────┐ │
|
|
│ │ Codex │ Claude │ Gemini │ │
|
|
│ │ Backend │ Backend │ Backend │ │
|
|
│ └──────────────┴──────────────┴──────────────┘ │
|
|
│ │
|
|
│ ┌──────────────────────────────────────────────────────────┤
|
|
│ │ Features: │
|
|
│ │ - Multi-backend execution │
|
|
│ │ - JSON stream parsing │
|
|
│ │ - Session management │
|
|
│ │ - Parallel task execution │
|
|
│ │ - Timeout handling │
|
|
│ └──────────────────────────────────────────────────────────┘
|
|
└──────────────────┬──────────────────────────────────────────┘
|
|
│
|
|
│ CLI invocations
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ AI CLI Backends │
|
|
│ ┌──────────────┬──────────────┬──────────────┐ │
|
|
│ │ Codex CLI │ Claude CLI │ Gemini CLI │ │
|
|
│ │ │ │ │ │
|
|
│ │ Code editing │ Reasoning │ Fast proto │ │
|
|
│ └──────────────┴──────────────┴──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Component Architecture
|
|
|
|
### 1. Orchestrator Layer (Claude Code)
|
|
|
|
**Responsibilities:**
|
|
- User interaction and requirements gathering
|
|
- Context analysis and exploration
|
|
- Task planning and breakdown
|
|
- Workflow coordination
|
|
- Verification and reporting
|
|
|
|
**Key Workflows:**
|
|
```
|
|
/dev
|
|
├── Requirements clarification (AskUserQuestion)
|
|
├── Codex analysis (Task tool → Explore agent)
|
|
├── Dev plan generation (Task tool → dev-plan-generator)
|
|
├── Parallel execution (codeagent-wrapper --parallel)
|
|
├── Coverage validation (≥90%)
|
|
└── Completion summary
|
|
|
|
/gh-implement <issue>
|
|
├── Issue analysis (gh issue view)
|
|
├── Clarification (if needed)
|
|
├── Development (codeagent-wrapper or /dev)
|
|
├── Progress updates (gh issue comment)
|
|
└── PR creation (gh pr create)
|
|
```
|
|
|
|
### 2. Execution Layer (Codeagent-Wrapper)
|
|
|
|
**Architecture:**
|
|
|
|
```go
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Main Entry Point │
|
|
│ - Parse CLI arguments │
|
|
│ - Detect mode (new/resume/parallel) │
|
|
│ - Select backend │
|
|
└──────────────────┬──────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Backend Selection │
|
|
│ func SelectBackend(name string) Backend │
|
|
│ ┌──────────────┬──────────────┬──────────────┐ │
|
|
│ │ CodexBackend │ ClaudeBackend│ GeminiBackend│ │
|
|
│ └──────────────┴──────────────┴──────────────┘ │
|
|
└──────────────────┬──────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Executor │
|
|
│ func RunCodexTask(cfg *Config) (string, error) │
|
|
│ ┌──────────────────────────────────────────────────────┤
|
|
│ │ 1. Build command args via Backend.BuildArgs() │
|
|
│ │ 2. Start process with timeout │
|
|
│ │ 3. Stream stdout/stderr │
|
|
│ │ 4. Parse JSON stream via ParseJSONStream() │
|
|
│ │ 5. Extract session ID │
|
|
│ │ 6. Handle signals (SIGINT, SIGTERM) │
|
|
│ └──────────────────────────────────────────────────────┘
|
|
└──────────────────┬──────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Parser │
|
|
│ func ParseJSONStream(r io.Reader) (string, string) │
|
|
│ ┌──────────────────────────────────────────────────────┤
|
|
│ │ Detects format: │
|
|
│ │ - Codex: {"type":"thread.started","thread_id":...} │
|
|
│ │ - Claude: {"type":"...","subtype":"result"} │
|
|
│ │ - Gemini: {"type":"...","role":"assistant"} │
|
|
│ │ │
|
|
│ │ Extracts: │
|
|
│ │ - Agent messages │
|
|
│ │ - Session IDs │
|
|
│ └──────────────────────────────────────────────────────┘
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Backend Interface:**
|
|
|
|
```go
|
|
type Backend interface {
|
|
Name() string
|
|
Command() string
|
|
BuildArgs(cfg *Config, targetArg string) []string
|
|
}
|
|
|
|
// Codex: codex e --skip-git-repo-check -C <workdir> --json <task>
|
|
// Claude: claude -p --dangerously-skip-permissions --output-format stream-json --verbose <task>
|
|
// Gemini: gemini -o stream-json -y -p <task>
|
|
```
|
|
|
|
**Key Files:**
|
|
- `main.go` - Entry point and orchestration
|
|
- `config.go` - CLI argument parsing
|
|
- `backend.go` - Backend interface and implementations
|
|
- `executor.go` - Process execution and stream handling
|
|
- `parser.go` - JSON stream parsing (multi-format)
|
|
- `logger.go` - Async logging with ring buffer
|
|
- `utils.go` - Helper functions
|
|
|
|
### 3. Hooks System
|
|
|
|
**Architecture:**
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Claude Code Events │
|
|
│ UserPromptSubmit │ PostToolUse │ Stop │
|
|
└──────────────────┬──────────────────────────────────────┘
|
|
│
|
|
│ reads
|
|
▼
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ .claude/settings.json │
|
|
│ { │
|
|
│ "hooks": { │
|
|
│ "UserPromptSubmit": [ │
|
|
│ { │
|
|
│ "hooks": [ │
|
|
│ { │
|
|
│ "type": "command", │
|
|
│ "command": "$CLAUDE_PROJECT_DIR/hooks/..." │
|
|
│ } │
|
|
│ ] │
|
|
│ } │
|
|
│ ] │
|
|
│ } │
|
|
│ } │
|
|
└──────────────────┬──────────────────────────────────────┘
|
|
│
|
|
│ executes
|
|
▼
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Hook Scripts │
|
|
│ ┌────────────────────────────────────────────────────┐ │
|
|
│ │ skill-activation-prompt.sh │ │
|
|
│ │ - Reads skills/skill-rules.json │ │
|
|
│ │ - Matches user prompt against triggers │ │
|
|
│ │ - Injects skill suggestions │ │
|
|
│ └────────────────────────────────────────────────────┘ │
|
|
│ ┌────────────────────────────────────────────────────┐ │
|
|
│ │ pre-commit.sh │ │
|
|
│ │ - Validates staged files │ │
|
|
│ │ - Runs tests │ │
|
|
│ │ - Formats code │ │
|
|
│ └────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 4. Skills System
|
|
|
|
**Structure:**
|
|
|
|
```
|
|
skills/
|
|
├── codex/
|
|
│ └── SKILL.md # Codex CLI integration
|
|
├── codeagent/
|
|
│ └── SKILL.md # Multi-backend wrapper
|
|
├── gemini/
|
|
│ └── SKILL.md # Gemini CLI integration
|
|
└── skill-rules.json # Auto-activation rules
|
|
```
|
|
|
|
**skill-rules.json Format:**
|
|
|
|
```json
|
|
{
|
|
"rules": [
|
|
{
|
|
"trigger": {
|
|
"pattern": "implement|build|create feature",
|
|
"type": "regex"
|
|
},
|
|
"skill": "codeagent",
|
|
"priority": 1,
|
|
"suggestion": "Use codeagent skill for code implementation"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
### Example: /dev Workflow
|
|
|
|
```
|
|
1. User: /dev "add user authentication"
|
|
│
|
|
▼
|
|
2. Claude Code:
|
|
│ ├─ Clarifies requirements (AskUserQuestion)
|
|
│ ├─ Analyzes codebase (Explore agent)
|
|
│ └─ Generates dev-plan.md
|
|
│
|
|
▼
|
|
3. Claude Code invokes: codeagent-wrapper --parallel <<EOF
|
|
---TASK---
|
|
id: auth_backend_1701234567
|
|
workdir: /project/backend
|
|
---CONTENT---
|
|
implement JWT authentication in @src/auth
|
|
|
|
---TASK---
|
|
id: auth_frontend_1701234568
|
|
workdir: /project/frontend
|
|
dependencies: auth_backend_1701234567
|
|
---CONTENT---
|
|
implement login form consuming /api/auth
|
|
|
|
---TASK---
|
|
id: auth_tests_1701234569
|
|
workdir: /project
|
|
dependencies: auth_backend_1701234567, auth_frontend_1701234568
|
|
---CONTENT---
|
|
add integration tests for auth flow
|
|
EOF
|
|
│
|
|
▼
|
|
4. Codeagent-Wrapper:
|
|
│ ├─ Parses parallel config
|
|
│ ├─ Topological sort (resolves dependencies)
|
|
│ ├─ Executes tasks concurrently:
|
|
│ │ ├─ Task 1: codex e --json "implement JWT..."
|
|
│ │ ├─ Task 2: waits for Task 1, then codex e --json "implement login..."
|
|
│ │ └─ Task 3: waits for Tasks 1&2, then codex e --json "add tests..."
|
|
│ └─ Aggregates results
|
|
│
|
|
▼
|
|
5. Claude Code:
|
|
│ ├─ Validates coverage (≥90%)
|
|
│ ├─ Runs final tests
|
|
│ └─ Reports summary
|
|
│
|
|
▼
|
|
6. User receives:
|
|
✅ Authentication implemented
|
|
📊 Coverage: 92%
|
|
📁 Files modified: 8
|
|
🧪 Tests: 24 passed
|
|
```
|
|
|
|
## Module System
|
|
|
|
Installation system uses modular architecture:
|
|
|
|
```
|
|
config.json
|
|
├── dev module (enabled)
|
|
│ ├── merge_dir: dev-workflow → ~/.claude
|
|
│ ├── copy_file: memorys/CLAUDE.md
|
|
│ ├── copy_file: skills/codex/SKILL.md
|
|
│ └── run_command: install codeagent-wrapper binary
|
|
│
|
|
├── gh module (enabled)
|
|
│ ├── merge_dir: github-workflow → ~/.claude
|
|
│ ├── copy_file: skills/codeagent/SKILL.md
|
|
│ ├── copy_dir: hooks → ~/.claude/hooks
|
|
│ └── merge_json: hooks-config.json → settings.json
|
|
│
|
|
└── essentials module (enabled)
|
|
└── merge_dir: development-essentials → ~/.claude
|
|
```
|
|
|
|
**Installation Flow:**
|
|
|
|
```bash
|
|
python3 install.py --module dev,gh
|
|
|
|
1. Load config.json
|
|
2. Validate against config.schema.json
|
|
3. Select modules: dev, gh
|
|
4. Execute operations:
|
|
├─ dev:
|
|
│ ├─ Merge dev-workflow/commands → ~/.claude/commands
|
|
│ ├─ Copy CLAUDE.md → ~/.claude/CLAUDE.md
|
|
│ ├─ Copy codex skill → ~/.claude/skills/codex/
|
|
│ └─ Run install.sh (compile codeagent-wrapper)
|
|
│
|
|
└─ gh:
|
|
├─ Merge github-workflow/commands → ~/.claude/commands
|
|
├─ Copy codeagent skill → ~/.claude/skills/codeagent/
|
|
├─ Copy hooks → ~/.claude/hooks
|
|
└─ Merge hooks-config.json → ~/.claude/settings.json
|
|
5. Write installed_modules.json
|
|
6. Log to install.log
|
|
```
|
|
|
|
## Parallel Execution Engine
|
|
|
|
**Algorithm:**
|
|
|
|
```
|
|
1. Parse task config (---TASK--- delimited format)
|
|
2. Build dependency graph
|
|
3. Topological sort (detect cycles)
|
|
4. Execute in layers:
|
|
Layer 0: Tasks with no dependencies
|
|
Layer 1: Tasks depending only on Layer 0
|
|
Layer 2: Tasks depending on Layers 0-1
|
|
...
|
|
5. Within each layer: unlimited concurrency
|
|
6. On failure: skip dependent tasks, continue others
|
|
7. Aggregate results
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```
|
|
Tasks:
|
|
A (no deps)
|
|
B (no deps)
|
|
C (depends on A)
|
|
D (depends on A, B)
|
|
E (depends on D)
|
|
|
|
Execution:
|
|
Layer 0: A, B (parallel)
|
|
Layer 1: C (waits for A), D (waits for A, B)
|
|
Layer 2: E (waits for D)
|
|
|
|
Timeline:
|
|
t=0: Start A, B
|
|
t=1: A completes
|
|
t=2: B completes, start C, D
|
|
t=3: C completes
|
|
t=4: D completes, start E
|
|
t=5: E completes
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
1. **No credential storage** - Uses existing CLI auth
|
|
2. **Sandbox execution** - Tasks run in specified workdir
|
|
3. **Timeout enforcement** - Prevents runaway processes
|
|
4. **Signal handling** - Graceful shutdown on Ctrl+C
|
|
5. **Input validation** - Sanitizes task configs
|
|
|
|
## Performance Characteristics
|
|
|
|
| Operation | Complexity | Notes |
|
|
|-----------|------------|-------|
|
|
| Backend selection | O(1) | Map lookup |
|
|
| Task parsing | O(n) | Linear scan |
|
|
| Topological sort | O(V+E) | Kahn's algorithm |
|
|
| Parallel execution | O(depth) | Depth of dependency graph |
|
|
| JSON parsing | O(n) | Streaming parser |
|
|
|
|
## Extensibility
|
|
|
|
### Adding New Backend
|
|
|
|
1. Implement `Backend` interface:
|
|
```go
|
|
type NewBackend struct{}
|
|
|
|
func (NewBackend) Name() string { return "new" }
|
|
func (NewBackend) Command() string { return "new-cli" }
|
|
func (NewBackend) BuildArgs(cfg *Config, targetArg string) []string {
|
|
return []string{"--json", targetArg}
|
|
}
|
|
```
|
|
|
|
2. Register in `config.go`:
|
|
```go
|
|
backendRegistry = map[string]Backend{
|
|
"codex": CodexBackend{},
|
|
"claude": ClaudeBackend{},
|
|
"gemini": GeminiBackend{},
|
|
"new": NewBackend{},
|
|
}
|
|
```
|
|
|
|
3. Add JSON format detection in `parser.go`:
|
|
```go
|
|
if hasKey(obj, "new_specific_field") {
|
|
// Parse new backend format
|
|
}
|
|
```
|
|
|
|
### Adding New Hook
|
|
|
|
1. Create script in `hooks/`:
|
|
```bash
|
|
#!/bin/bash
|
|
# hooks/my-custom-hook.sh
|
|
echo "Hook executed"
|
|
```
|
|
|
|
2. Register in `.claude/settings.json`:
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"UserPromptSubmit": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "$CLAUDE_PROJECT_DIR/hooks/my-custom-hook.sh"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Adding New Skill
|
|
|
|
1. Create `skills/my-skill/SKILL.md`:
|
|
```markdown
|
|
---
|
|
name: my-skill
|
|
description: My custom skill
|
|
---
|
|
|
|
# My Custom Skill
|
|
|
|
Usage instructions...
|
|
```
|
|
|
|
2. Add activation rule in `skills/skill-rules.json`:
|
|
```json
|
|
{
|
|
"rules": [
|
|
{
|
|
"trigger": {"pattern": "my keyword", "type": "regex"},
|
|
"skill": "my-skill",
|
|
"priority": 1
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Further Reading
|
|
|
|
- [Codeagent-Wrapper Guide](./CODEAGENT-WRAPPER.md)
|
|
- [GitHub Workflow Guide](./GITHUB-WORKFLOW.md)
|
|
- [Hooks Documentation](./HOOKS.md)
|
|
- [README](../README.md)
|