docs: add ralph-runner Claude Skill
- SKILL.md: Complete documentation for Ralph automation - scripts/status.sh: Check project and Ralph status - scripts/start.sh: Start Ralph loop with options - scripts/commit.sh: Git commit helper - README.md: Skill usage guide Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
zly
313
.claude/skills/ralph-runner/SKILL.md
Normal file
313
.claude/skills/ralph-runner/SKILL.md
Normal file
@@ -0,0 +1,313 @@
|
||||
---
|
||||
name: ralph-runner
|
||||
description: "BtToxin Pipeline development with Ralph autonomous AI agent. Actions: start, monitor, stop, status, commit, push. Features: 16-task concurrency, genome/protein analysis, i18n support, Docker deployment, CRISPR-Cas预留. Domain: bttiaw.hzau.edu.cn"
|
||||
---
|
||||
|
||||
# Ralph Runner - BtToxin Pipeline Development
|
||||
|
||||
Autonomous AI-powered development using Ralph for the BtToxin Pipeline project.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Check if Ralph is installed:
|
||||
|
||||
```bash
|
||||
which ralph || ls ~/.local/bin/ralph-claude-code/ralph_loop.sh
|
||||
```
|
||||
|
||||
If Ralph is not installed, install it:
|
||||
|
||||
```bash
|
||||
~/.local/bin/claude-switch/tools/ralph-install-external.sh
|
||||
```
|
||||
|
||||
Verify Ralph project files exist:
|
||||
|
||||
```bash
|
||||
ls -la PROMPT.md @fix_plan.md specs/requirements.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Skill
|
||||
|
||||
When user requests BtToxin Pipeline development (implement, build, fix, add, create), follow this workflow:
|
||||
|
||||
### Step 1: Check Current Project Status
|
||||
|
||||
```bash
|
||||
# Check git status
|
||||
git status
|
||||
|
||||
# Check Ralph status
|
||||
ralph --status
|
||||
|
||||
# View current task list
|
||||
cat @fix_plan.md
|
||||
```
|
||||
|
||||
### Step 2: Start Ralph Loop
|
||||
|
||||
**Recommended: With monitoring dashboard**
|
||||
```bash
|
||||
ralph --monitor
|
||||
```
|
||||
|
||||
**Without monitoring (background process)**
|
||||
```bash
|
||||
ralph
|
||||
```
|
||||
|
||||
**With call limit**
|
||||
```bash
|
||||
ralph --monitor --calls 50 # Limit to 50 calls per hour
|
||||
```
|
||||
|
||||
### Step 3: Monitor Progress
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
ralph --status
|
||||
|
||||
# View logs
|
||||
tail -f logs/ralph.log
|
||||
|
||||
# Check response analysis
|
||||
cat status.json | jq .
|
||||
```
|
||||
|
||||
### Step 4: Manual Operations (when needed)
|
||||
|
||||
**Commit changes**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat(module): descriptive message"
|
||||
```
|
||||
|
||||
**Push to remote**
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
**Reset Ralph circuit breaker**
|
||||
```bash
|
||||
ralph --reset-circuit
|
||||
```
|
||||
|
||||
**Check circuit breaker status**
|
||||
```bash
|
||||
ralph --circuit-status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ralph Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Set provider (glm, minimax, local, etc.)
|
||||
export CLAUDE_PROVIDER=minimax
|
||||
|
||||
# Set model
|
||||
export CLAUDE_MODEL=MiniMax-M2.1
|
||||
|
||||
# Set max iterations
|
||||
export RALPH_MAX_ITERATIONS=20
|
||||
```
|
||||
|
||||
### Ralph Home Directory
|
||||
|
||||
- **Commands**: `~/.local/bin/`
|
||||
- **Templates**: `~/.ralph/templates/`
|
||||
- **Scripts**: `~/.ralph/`
|
||||
|
||||
---
|
||||
|
||||
## Ralph Project Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `PROMPT.md` | Ralph development instructions (REQUIRED) |
|
||||
| `@fix_plan.md` | Prioritized task list |
|
||||
| `specs/requirements.md` | Technical specifications |
|
||||
| `@AGENT.md` | Build/test/deploy commands |
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: Start New Development Session
|
||||
|
||||
```bash
|
||||
# 1. Pull latest changes
|
||||
git pull
|
||||
|
||||
# 2. Check Ralph status
|
||||
ralph --status
|
||||
|
||||
# 3. Start monitoring
|
||||
ralph --monitor
|
||||
```
|
||||
|
||||
### Workflow 2: Review Completed Work
|
||||
|
||||
```bash
|
||||
# 1. Check git log
|
||||
git log --oneline -10
|
||||
|
||||
# 2. View changed files
|
||||
git diff HEAD~1
|
||||
|
||||
# 3. Check @fix_plan.md progress
|
||||
grep -E '^\[.\]' @fix_plan.md | wc -l
|
||||
```
|
||||
|
||||
### Workflow 3: Continue After Interruption
|
||||
|
||||
```bash
|
||||
# 1. Check status
|
||||
ralph --status
|
||||
|
||||
# 2. Resume if needed
|
||||
ralph # or ralph --monitor
|
||||
```
|
||||
|
||||
### Workflow 4: Emergency Stop
|
||||
|
||||
```bash
|
||||
# Ctrl+C to stop monitoring
|
||||
# Or kill process
|
||||
pkill -f ralph_loop.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Guidelines
|
||||
|
||||
### Current Development Priority
|
||||
|
||||
Based on @fix_plan.md, current priorities are:
|
||||
|
||||
1. **P0 - Frontend i18n**: ✅ Completed (vue-i18n, navigation, pages)
|
||||
2. **P0 - Upload Enhancement**: ✅ Completed (single file, genome/protein toggle)
|
||||
3. **P0 - Task Status**: ✅ Completed (queue status, progress)
|
||||
4. **P1 - FastAPI Backend**: Next focus
|
||||
5. **P1 - Concurrency Control**: Next focus
|
||||
6. **P2 - Docker Deployment**: Later focus
|
||||
|
||||
### Completed Features
|
||||
|
||||
- [x] Vue 3 frontend with Element Plus
|
||||
- [x] vue-i18n (Chinese/English)
|
||||
- [x] Navigation bar (Home, About, Submit, Status, Tool Guide)
|
||||
- [x] File upload (.fna/.fa/.fasta/.faa)
|
||||
- [x] Single file restriction
|
||||
- [x] Genome/Protein toggle
|
||||
- [x] Task status pages
|
||||
- [x] Tool Info page (Shoter methodology, no Digger mentioned)
|
||||
|
||||
### Pending Features
|
||||
|
||||
- [ ] FastAPI backend (main.py, tasks.py)
|
||||
- [ ] 16 concurrent task limit
|
||||
- [ ] Redis task queue
|
||||
- [ ] API endpoints (/api/tasks, /api/tasks/{id})
|
||||
- [ ] Docker deployment
|
||||
- [ ] Traefik configuration
|
||||
- [ ] CRISPR-Cas预留 (crispr_cas/ directory)
|
||||
|
||||
---
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
Ralph follows these testing rules:
|
||||
|
||||
1. **Testing effort**: ~20% of total effort
|
||||
2. **Priority**: Implementation > Documentation > Tests
|
||||
3. **Coverage**: 85% for new code
|
||||
4. **Focus**: Core functionality first
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Prompt file 'PROMPT.md' not found"
|
||||
|
||||
```bash
|
||||
# Ensure you're in the project directory
|
||||
cd /vol1/1000/docker_server/traefik/web/zly
|
||||
ls -la PROMPT.md
|
||||
```
|
||||
|
||||
### "Ralph not installed"
|
||||
|
||||
```bash
|
||||
# Install Ralph
|
||||
~/.local/bin/claude-switch/tools/ralph-install-external.sh
|
||||
```
|
||||
|
||||
### Ralph stuck in loop
|
||||
|
||||
```bash
|
||||
# Reset circuit breaker
|
||||
ralph --reset-circuit
|
||||
|
||||
# Check circuit status
|
||||
ralph --circuit-status
|
||||
```
|
||||
|
||||
### tmux session lost
|
||||
|
||||
```bash
|
||||
# List sessions
|
||||
tmux list-sessions
|
||||
|
||||
# Reconnect
|
||||
tmux attach -t ralph-watch
|
||||
|
||||
# Or create new session
|
||||
tmux new -s ralph-watch
|
||||
ralph-monitor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
web/zly/
|
||||
├── PROMPT.md # Ralph instructions
|
||||
├── @fix_plan.md # Task list
|
||||
├── @AGENT.md # Build commands
|
||||
├── specs/
|
||||
│ └── requirements.md # Tech specs
|
||||
├── frontend/ # Vue 3 SPA
|
||||
│ ├── src/
|
||||
│ │ ├── locales/ # i18n files
|
||||
│ │ ├── views/ # Pages
|
||||
│ │ └── components/ # Components
|
||||
│ └── package.json
|
||||
├── web/backend/ # FastAPI (to be built)
|
||||
├── scripts/ # Pipeline scripts
|
||||
├── docker/ # Docker configs
|
||||
└── external_dbs/ # BtToxin database
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Targets
|
||||
|
||||
| Target | URL | Status |
|
||||
|--------|-----|--------|
|
||||
| Development | localhost:5173/8000 | ✅ Frontend ready |
|
||||
| Test | bttiaw.hzau.edu.cn | 🔄 In progress |
|
||||
| Production | bttiaw.hzau.edu.cn | ⏳ Pending |
|
||||
|
||||
---
|
||||
|
||||
## Key Contacts
|
||||
|
||||
- **Project**: BtToxin Pipeline
|
||||
- **Domain**: bttiaw.hzau.edu.cn
|
||||
- **Maintainer**: Claude Code with Ralph
|
||||
Reference in New Issue
Block a user