docs: comprehensive documentation update for Ruflo integration
- Updated README.md with complete feature documentation: * Added Hermes Agent × Claude Code × Ruflo × Opencode branding * Comprehensive feature list (24/7 bot, self-learning, voice I/O, self-evolve) * Multi-agent swarm system (9 agent roles, 3 topologies) * Plugin system (16 extension points) * Hook system (pre/post tool/AI/session) * Enhanced memory backend (JSON + LRU) * Full feature comparison table vs Hermes/Claude/Ruflo * Architecture diagrams * Usage examples for all commands - Updated package.json: * Bumped version to 2.0.0 * Added comprehensive metadata (author, license, repository) * Added keywords for discoverability * Added support/funding links - Added INSTALLATION.md: * Complete setup guide (5-minute quick start) * Detailed installation steps (Node.js, ffmpeg, Python, Vosk) * Telegram bot configuration * Webhook setup (ngrok + domain) * Systemd service installation * Troubleshooting section * Advanced setup (Docker, multiple instances, SSL) - Added CREDITS.md: * Core project credits (Hermes Agent, Claude Code, Ruflo, Opencode) * Technology libraries (grammy, Express, Winston, Vosk, etc.) * Special thanks to NousResearch, Anthropic, RuvNet * Third-party license attribution - Added CONTRIBUTING.md: * How to contribute (bugs, features, docs, tests) * Development guidelines (code style, commit messages) * Architecture guidelines (plugins, hooks, agents) * Testing requirements * Security guidelines * Bug report and feature request templates * PR process and code review All documentation now reflects the complete Ruflo integration with 1,977 lines of new code.
This commit is contained in:
admin
461
CONTRIBUTING.md
Normal file
461
CONTRIBUTING.md
Normal file
@@ -0,0 +1,461 @@
|
||||
# Contributing to zCode CLI X
|
||||
|
||||
Thank you for your interest in contributing to zCode CLI X! This document provides guidelines and instructions for contributing.
|
||||
|
||||
## 🌟 How to Contribute
|
||||
|
||||
### Types of Contributions
|
||||
|
||||
We welcome many types of contributions:
|
||||
|
||||
- **Bug Reports** — Found a bug? Let us know!
|
||||
- **Feature Requests** — Have an idea? Share it!
|
||||
- **Code Changes** — Fix bugs, add features, improve performance
|
||||
- **Documentation** — Improve README, add examples, fix typos
|
||||
- **Tests** — Add test coverage for new features
|
||||
- **Community Support** — Help others in issues and discussions
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start for Contributors
|
||||
|
||||
### 1. Fork & Clone
|
||||
|
||||
```bash
|
||||
# Fork the repo on GitHub, then clone:
|
||||
git clone https://github.rommark.dev/admin/zCode-CLI-X.git
|
||||
cd zCode-CLI-X
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 3. Run Smoke Tests
|
||||
|
||||
```bash
|
||||
# Verify everything works
|
||||
node test-ruflo-smoke.mjs
|
||||
|
||||
# Should show: 53/53 tests passing
|
||||
```
|
||||
|
||||
### 4. Make Changes
|
||||
|
||||
Follow the guidelines below, then:
|
||||
|
||||
```bash
|
||||
# Test your changes
|
||||
npm test
|
||||
|
||||
# Commit with descriptive message
|
||||
git commit -m "feat: add new feature"
|
||||
```
|
||||
|
||||
### 5. Push & Create PR
|
||||
|
||||
```bash
|
||||
git push origin main
|
||||
|
||||
# Create pull request on GitHub
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Development Guidelines
|
||||
|
||||
### Code Style
|
||||
|
||||
- **JavaScript** — Use ES modules (`import`/`export`)
|
||||
- **Naming** — `camelCase` for variables/functions, `PascalCase` for classes
|
||||
- **Comments** — JSDoc for public APIs, inline comments for complex logic
|
||||
- **Error handling** — Always handle errors, never ignore them
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```bash
|
||||
feat: add new feature
|
||||
fix: bug fix
|
||||
docs: documentation changes
|
||||
style: formatting, missing semicolons (no code change)
|
||||
refactor: code refactoring
|
||||
test: adding or updating tests
|
||||
chore: maintenance tasks (not user-facing)
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
feat: add multi-agent swarm support
|
||||
fix: resolve memory backend eviction bug
|
||||
docs: update installation instructions
|
||||
refactor: simplify plugin loading logic
|
||||
test: add smoke tests for hook system
|
||||
```
|
||||
|
||||
### Branch Naming
|
||||
|
||||
```bash
|
||||
feat/new-feature
|
||||
fix/bug-fix
|
||||
docs/update-readme
|
||||
refactor/code-improvement
|
||||
test/add-tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Guidelines
|
||||
|
||||
### Plugin System
|
||||
|
||||
When adding new plugins:
|
||||
|
||||
1. **Define extension point** in `src/plugins/ExtensionPoints.js`
|
||||
2. **Implement plugin** extending `BasePlugin` in `src/plugins/Plugin.js`
|
||||
3. **Register in PluginManager** — Add to extension point routing
|
||||
4. **Document** — Add to CREDITS.md or docs
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
// src/plugins/MyPlugin.js
|
||||
import { BasePlugin } from './Plugin.js';
|
||||
|
||||
export class MyPlugin extends BasePlugin {
|
||||
name = 'my-plugin';
|
||||
|
||||
async initialize() {
|
||||
console.log('MyPlugin initialized');
|
||||
}
|
||||
|
||||
async shutdown() {
|
||||
console.log('MyPlugin shut down');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Hook System
|
||||
|
||||
When adding new hooks:
|
||||
|
||||
1. **Define hook type** in `src/bot/hooks.js`
|
||||
2. **Register hook** with priority order
|
||||
3. **Document** — Add to README.md
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
// src/bot/hooks.js
|
||||
export const HOOK_TYPES = {
|
||||
TOOL_PRE: 'tool.pre',
|
||||
TOOL_POST: 'tool.post',
|
||||
AI_PRE: 'ai.pre',
|
||||
AI_POST: 'ai.post',
|
||||
// Add your custom hooks here
|
||||
MY_CUSTOM_HOOK: 'my.custom.hook'
|
||||
};
|
||||
```
|
||||
|
||||
### Agent System
|
||||
|
||||
When adding new agent roles:
|
||||
|
||||
1. **Add to agents/index.js** — Define agent type
|
||||
2. **Update system prompt** — Add agent description
|
||||
3. **Document** — Add to README.md feature comparison table
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
// src/agents/index.js
|
||||
export const AGENT_TYPES = {
|
||||
coder: {
|
||||
id: 'coder',
|
||||
name: 'Coder',
|
||||
description: 'Implementation, debugging, refactoring'
|
||||
},
|
||||
// Add your new agent here
|
||||
analyst: {
|
||||
id: 'analyst',
|
||||
name: 'Data Analyst',
|
||||
description: 'Data analysis, visualization, insights'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Run Smoke Tests
|
||||
|
||||
```bash
|
||||
node test-ruflo-smoke.mjs
|
||||
```
|
||||
|
||||
**Coverage**:
|
||||
- ✅ PluginSystem: 10 tests
|
||||
- ✅ HookSystem: 4 tests
|
||||
- ✅ AgentSystem: 9 tests
|
||||
- ✅ SwarmCoordinator: 12 tests
|
||||
- ✅ AgentOrchestrator: 4 tests
|
||||
- ✅ MemoryBackend: 14 tests
|
||||
- **Total**: 53 tests
|
||||
|
||||
### Add New Tests
|
||||
|
||||
When adding new features, add tests:
|
||||
|
||||
```javascript
|
||||
// test-my-feature.mjs
|
||||
import { test } from 'node:test';
|
||||
import assert from 'node:assert';
|
||||
|
||||
test('my feature works', async () => {
|
||||
const result = await myFunction();
|
||||
assert.strictEqual(result, expected);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
### README.md
|
||||
|
||||
Update README when:
|
||||
- Adding new features
|
||||
- Changing configuration options
|
||||
- Updating installation steps
|
||||
- Adding new agents/tools
|
||||
|
||||
### Architecture.md
|
||||
|
||||
Update ARCHITECTURE.md when:
|
||||
- Changing system architecture
|
||||
- Adding new components
|
||||
- Modifying message flows
|
||||
|
||||
### CREDITS.md
|
||||
|
||||
Update CREDITS.md when:
|
||||
- Adding new dependencies
|
||||
- Acknowledging new contributors
|
||||
- Updating third-party licenses
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Guidelines
|
||||
|
||||
### Never Commit Secrets
|
||||
|
||||
**DO**:
|
||||
```bash
|
||||
# Use environment variables
|
||||
ZAI_API_KEY=${ZAI_API_KEY}
|
||||
TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
|
||||
```
|
||||
|
||||
**DON'T**:
|
||||
```bash
|
||||
# Hardcoded secrets in code
|
||||
const API_KEY = 'abc123'; // NEVER DO THIS
|
||||
```
|
||||
|
||||
### Validate User Input
|
||||
|
||||
Always validate and sanitize user input:
|
||||
```javascript
|
||||
// Validate Telegram user ID
|
||||
if (!/^\d+$/.validate(userId)) {
|
||||
throw new Error('Invalid user ID');
|
||||
}
|
||||
```
|
||||
|
||||
### Protect Sensitive Files
|
||||
|
||||
Never modify these files via self-evolve:
|
||||
- `SelfEvolveTool.js` — The safety system itself
|
||||
- `stt.py` — Voice recognition bridge
|
||||
- `.env` — Environment variables
|
||||
- `package.json` — Dependencies
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Bug Reports
|
||||
|
||||
When reporting a bug:
|
||||
|
||||
1. **Search existing issues** — Make sure it's not already reported
|
||||
2. **Provide reproduction steps** — How to trigger the bug
|
||||
3. **Include logs** — `journalctl --user -u zcode -f`
|
||||
4. **Specify environment** — Node version, OS, configuration
|
||||
5. **Expected vs actual behavior** — What should happen vs what does
|
||||
|
||||
**Example**:
|
||||
```
|
||||
**Bug**: Bot crashes on voice message
|
||||
|
||||
**Steps to reproduce**:
|
||||
1. Send voice message to bot
|
||||
2. Bot crashes with error
|
||||
|
||||
**Expected**: Bot transcribes voice and responds
|
||||
**Actual**: Bot crashes with "Vosk model not found"
|
||||
|
||||
**Environment**:
|
||||
- Node.js: v20.10.0
|
||||
- OS: Ubuntu 24.04
|
||||
- Vosk model: ~/vosk-models/vosk-model-small-0.15
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Feature Requests
|
||||
|
||||
When requesting a feature:
|
||||
|
||||
1. **Describe the use case** — Why do you need this?
|
||||
2. **Provide examples** — How would you use it?
|
||||
3. **Consider alternatives** — What existing features could work?
|
||||
4. **Estimate impact** — How many users would benefit?
|
||||
|
||||
**Example**:
|
||||
```
|
||||
**Feature**: Add support for custom AI models
|
||||
|
||||
**Use case**: I want to use my own fine-tuned model
|
||||
**Example**: `/model use my-custom-model-v2`
|
||||
**Alternatives**: Currently using Z.AI GLM-5.1
|
||||
**Impact**: Would help users with specific model requirements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📄 Pull Request Process
|
||||
|
||||
### Before Submitting
|
||||
|
||||
1. ✅ **Run all tests** — `npm test` should pass
|
||||
2. ✅ **Update documentation** — README, ARCHITECTURE, CREDITS
|
||||
3. ✅ **Add tests for new features** — Test coverage > 80%
|
||||
4. ✅ **Follow code style** — Consistent formatting
|
||||
5. ✅ **Write descriptive commit messages** — Conventional Commits
|
||||
|
||||
### PR Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of changes
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Documentation update
|
||||
- [ ] Refactoring
|
||||
- [ ] Test addition
|
||||
|
||||
## Testing
|
||||
- [ ] Tests added/updated
|
||||
- [ ] Smoke tests passing
|
||||
- [ ] Manual testing done
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows project style
|
||||
- [ ] Documentation updated
|
||||
- [ ] No breaking changes
|
||||
- [ ] Self-review done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Code Review
|
||||
|
||||
### Reviewers Will Check
|
||||
|
||||
- **Functionality** — Does it work as expected?
|
||||
- **Security** — Any vulnerabilities?
|
||||
- **Performance** — Any bottlenecks?
|
||||
- **Testing** — Adequate test coverage?
|
||||
- **Documentation** — Is it documented?
|
||||
- **Style** — Follows project conventions?
|
||||
|
||||
### Review Process
|
||||
|
||||
1. Automated checks (tests, linting)
|
||||
2. Core team review (1-2 reviewers)
|
||||
3. Address feedback
|
||||
4. Merge to main
|
||||
|
||||
---
|
||||
|
||||
## 🌍 Community Guidelines
|
||||
|
||||
### Be Respectful
|
||||
|
||||
- Treat everyone with respect
|
||||
- Provide constructive feedback
|
||||
- Accept constructive criticism
|
||||
- Focus on ideas, not people
|
||||
|
||||
### Be Helpful
|
||||
|
||||
- Help new contributors
|
||||
- Share knowledge
|
||||
- Answer questions
|
||||
- Document well
|
||||
|
||||
### Be Patient
|
||||
|
||||
- Code review takes time
|
||||
- Feedback is for improvement
|
||||
- Iteration is normal
|
||||
- Quality over speed
|
||||
|
||||
---
|
||||
|
||||
## 📞 Getting Help
|
||||
|
||||
### Channels
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.rommark.dev/admin/zCode-CLI-X/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.rommark.dev/admin/zCode-CLI-X/discussions)
|
||||
- **Telegram**: [@zcode_bot](https://t.me/zcode_bot) (ask questions)
|
||||
|
||||
### FAQ
|
||||
|
||||
**Q: How do I set up the development environment?**
|
||||
A: Follow [INSTALLATION.md](./INSTALLATION.md)
|
||||
|
||||
**Q: What's the best way to start contributing?**
|
||||
A: Look for "good first issue" labels on GitHub
|
||||
|
||||
**Q: How long does code review take?**
|
||||
A: Usually 1-3 days, depending on complexity
|
||||
|
||||
**Q: Can I work on an existing issue?**
|
||||
A: Yes! Comment "I'm working on this" to claim it
|
||||
|
||||
---
|
||||
|
||||
## 📜 License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE).
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Thank You!
|
||||
|
||||
Thank you for contributing to zCode CLI X! Your contributions make this project better for everyone.
|
||||
|
||||
**Questions?** Open an issue or start a discussion!
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Contributions welcome!** 🚀
|
||||
*Let's build the ultimate agentic coding assistant together*
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user