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>
|
||||||
309
CREDITS.md
Normal file
309
CREDITS.md
Normal file
@@ -0,0 +1,309 @@
|
|||||||
|
# Credits & Acknowledgments
|
||||||
|
|
||||||
|
## 🏗️ Core Projects
|
||||||
|
|
||||||
|
zCode CLI X is built on top of several open-source projects. We're deeply grateful to their authors and contributors.
|
||||||
|
|
||||||
|
### [Hermes Agent](https://github.com/nousresearch/hermes-agent)
|
||||||
|
**NousResearch's Telegram AI agent framework**
|
||||||
|
|
||||||
|
- **Used for**: Telegram bot framework, stream consumer patterns, RTK integration
|
||||||
|
- **Contributions**:
|
||||||
|
- `src/bot/message-sender.js` — Adapted from `gateway/stream_consumer.py`
|
||||||
|
- RTK (Rust Token Killer) integration for 60-90% token savings
|
||||||
|
- Message formatting and HTML escaping patterns
|
||||||
|
- Webhook handling with grammy
|
||||||
|
|
||||||
|
**License**: MIT
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### [Claude Code](https://github.com/anthropics/claude-code)
|
||||||
|
**Anthropic's agentic coding CLI**
|
||||||
|
|
||||||
|
- **Used for**: Unified agentic loop architecture, tool call accumulation, SSE streaming patterns
|
||||||
|
- **Contributions**:
|
||||||
|
- `src/bot/index.js` — Intelligence Routing (stream + non-stream unified loop)
|
||||||
|
- Tool call accumulation from SSE deltas
|
||||||
|
- Max 10-turn safety net design
|
||||||
|
- Bash tool with security hooks (adapted from `BashTool.tsx`)
|
||||||
|
- Cron scheduler patterns (from `cronScheduler.ts`)
|
||||||
|
|
||||||
|
**License**: Proprietary (Anthropic)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### [Ruflo](https://github.com/ruvnet/ruflo)
|
||||||
|
**Multi-agent orchestration framework**
|
||||||
|
|
||||||
|
- **Used for**: Plugin system, multi-agent swarm, hook architecture, enhanced memory backend
|
||||||
|
- **Contributions**:
|
||||||
|
- `src/plugins/` — PluginManager, PluginLoader, BasePlugin, ExtensionPoints
|
||||||
|
- `src/agents/` — Agent, Task, SwarmCoordinator, AgentOrchestrator
|
||||||
|
- `src/bot/hooks.js` — Pre/post tool/AI/session hooks
|
||||||
|
- `src/bot/memory-backend.js` — JSONBackend with LRU, InMemoryBackend with TTL
|
||||||
|
- 9 agent roles (coder, tester, reviewer, architect, devops, security, researcher, designer, coordinator)
|
||||||
|
- 16 extension points for plugin system
|
||||||
|
- 3 swarm topologies (simple, hierarchical, swarm)
|
||||||
|
|
||||||
|
**License**: MIT
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### [Opencode](https://github.com/opencode/opencode)
|
||||||
|
**Open-source AI coding assistant**
|
||||||
|
|
||||||
|
- **Used for**: Bash automation patterns, file operations, safety hooks, tool architecture
|
||||||
|
- **Contributions**:
|
||||||
|
- `src/tools/BashTool/` — Security hooks, destructive command protection
|
||||||
|
- File read/write patterns with heredoc fallback
|
||||||
|
- Git integration with permission validation
|
||||||
|
- Web scraping with cheerio
|
||||||
|
|
||||||
|
**License**: MIT
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Technologies & Libraries
|
||||||
|
|
||||||
|
### Core Frameworks
|
||||||
|
|
||||||
|
- **[grammy](https://grammy.dev)** — Telegram Bot Framework for Node.js
|
||||||
|
- Webhook handling
|
||||||
|
- Bot API wrapper
|
||||||
|
- Middleware system
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[Express](https://expressjs.com)** — Web application framework
|
||||||
|
- HTTP server for webhooks
|
||||||
|
- WebSocket server setup
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[Winston](https://github.com/winstonjs/winston)** — Logging library
|
||||||
|
- Structured logging
|
||||||
|
- Multiple transports (console, file)
|
||||||
|
- Log levels (debug, info, warn, error)
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
### AI/ML Libraries
|
||||||
|
|
||||||
|
- **[Z.AI API](https://z.ai)** — GLM-5.1 model provider
|
||||||
|
- Primary AI model for code generation
|
||||||
|
- Coding Plan subscription
|
||||||
|
- SSE streaming support
|
||||||
|
- **License**: Proprietary (Z.AI)
|
||||||
|
|
||||||
|
- **[Vosk](https://alphacephei.com/vosk/)** — Offline speech recognition
|
||||||
|
- Voice-to-text (STT)
|
||||||
|
- 68MB model (~95% accuracy)
|
||||||
|
- CPU-based, no GPU needed
|
||||||
|
- **License**: Apache 2.0
|
||||||
|
|
||||||
|
- **[node-edge-tts](https://github.com/yayuyokit/Edge-TTS-node)** — Text-to-speech
|
||||||
|
- Microsoft Edge voices
|
||||||
|
- Text-to-voice (TTS)
|
||||||
|
- No download required
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
### Utilities
|
||||||
|
|
||||||
|
- **[axios](https://axios-http.com)** — HTTP client
|
||||||
|
- Z.AI API calls
|
||||||
|
- Webhook requests
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[dotenv](https://github.com/motdotla/dotenv)** — Environment variable loader
|
||||||
|
- `.env` file parsing
|
||||||
|
- Configuration management
|
||||||
|
- **License**: BSD-2-Clause
|
||||||
|
|
||||||
|
- **[chalk](https://github.com/chalk/chalk)** — Terminal string styling
|
||||||
|
- Colored CLI output
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[commander](https://github.com/tj/commander.js)** — Node.js command-line framework
|
||||||
|
- CLI argument parsing
|
||||||
|
- Command structure
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[ws](https://github.com/websockets/ws)** — WebSocket library
|
||||||
|
- Real-time communication
|
||||||
|
- SSE fallback
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[p-queue](https://github.com/sindresorhus/p-queue)** — Priority queue
|
||||||
|
- Request queue management
|
||||||
|
- Per-chat sequential processing
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[glob](https://github.com/isaacs/node-glob)** — File pattern matching
|
||||||
|
- File search
|
||||||
|
- Asset discovery
|
||||||
|
- **License**: ISC
|
||||||
|
|
||||||
|
- **[cheerio](https://github.com/cheeriojs/cheerio)** — Fast HTML parser
|
||||||
|
- Web scraping
|
||||||
|
- Content extraction
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[discord.js](https://discord.js.org)** — Discord API wrapper
|
||||||
|
- Discord integration (unused but included)
|
||||||
|
- **License**: Apache 2.0
|
||||||
|
|
||||||
|
- **[openai](https://github.com/openai/openai-node)** — OpenAI API client
|
||||||
|
- OpenAI compatibility layer
|
||||||
|
- **License**: Apache 2.0
|
||||||
|
|
||||||
|
- **[fs-extra](https://github.com/jprichardson/node-fs-extra)** — File system utilities
|
||||||
|
- File operations
|
||||||
|
- Directory management
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[execa](https://github.com/sindresorhus/execa)** — Process execution
|
||||||
|
- Child process management
|
||||||
|
- Command execution
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[@grammyjs/auto-retry](https://github.com/grammyjs/auto-retry)** — Automatic retry logic
|
||||||
|
- Bot API error handling
|
||||||
|
- Exponential backoff
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
- **[@grammyjs/runner](https://github.com/grammyjs/runner)** — Bot runner
|
||||||
|
- Webhook polling
|
||||||
|
- Error handling
|
||||||
|
- **License**: MIT
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Special Thanks
|
||||||
|
|
||||||
|
### NousResearch
|
||||||
|
The Hermes Agent team for creating an excellent Telegram bot framework and sharing patterns for:
|
||||||
|
- Stream consumer architecture
|
||||||
|
- RTK integration
|
||||||
|
- Message formatting
|
||||||
|
- Webhook handling
|
||||||
|
|
||||||
|
We're grateful for their open-source contributions that made zCode's Telegram integration possible.
|
||||||
|
|
||||||
|
### Anthropic
|
||||||
|
The Claude Code team for pioneering the agentic coding CLI paradigm. Their work on:
|
||||||
|
- Unified agentic loops
|
||||||
|
- Tool call accumulation
|
||||||
|
- SSE streaming patterns
|
||||||
|
|
||||||
|
Influenced zCode's core architecture significantly.
|
||||||
|
|
||||||
|
### RuvNet
|
||||||
|
The Ruflo team for their innovative multi-agent orchestration system. Their plugin architecture, hook system, and swarm coordination patterns became the foundation for zCode's extensibility.
|
||||||
|
|
||||||
|
### Community Contributors
|
||||||
|
- All GitHub issue reporters who helped identify bugs
|
||||||
|
- Pull request contributors who improved the codebase
|
||||||
|
- Telegram users who provided feedback and feature requests
|
||||||
|
- Twitter/X community members who shared use cases
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📜 License
|
||||||
|
|
||||||
|
zCode CLI X is released under the **MIT License**.
|
||||||
|
|
||||||
|
This means you're free to:
|
||||||
|
- Use zCode for personal or commercial projects
|
||||||
|
- Modify the source code
|
||||||
|
- Distribute copies
|
||||||
|
- Use in proprietary software
|
||||||
|
|
||||||
|
**Conditions**:
|
||||||
|
- Include original copyright notice
|
||||||
|
- Include MIT license text
|
||||||
|
- No warranty provided
|
||||||
|
|
||||||
|
See [LICENSE](./LICENSE) for full license text.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🙏 Third-Party Licenses
|
||||||
|
|
||||||
|
### Open Source Components
|
||||||
|
|
||||||
|
This project includes or depends on the following open-source software:
|
||||||
|
|
||||||
|
| Component | License |
|
||||||
|
|-----------|---------|
|
||||||
|
| grammy | MIT |
|
||||||
|
| @grammyjs/auto-retry | MIT |
|
||||||
|
| @grammyjs/runner | MIT |
|
||||||
|
| axios | MIT |
|
||||||
|
| chalk | MIT |
|
||||||
|
| cheerio | MIT |
|
||||||
|
| commander | MIT |
|
||||||
|
| discord.js | Apache 2.0 |
|
||||||
|
| dotenv | BSD-2-Clause |
|
||||||
|
| execa | MIT |
|
||||||
|
| express | MIT |
|
||||||
|
| fs-extra | MIT |
|
||||||
|
| glob | ISC |
|
||||||
|
| node-edge-tts | MIT |
|
||||||
|
| openai | Apache 2.0 |
|
||||||
|
| p-queue | MIT |
|
||||||
|
| winston | MIT |
|
||||||
|
| ws | MIT |
|
||||||
|
| Vosk | Apache 2.0 |
|
||||||
|
|
||||||
|
All licenses are permissive (MIT, BSD, Apache, ISC) and compatible with commercial use.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌟 Contributors
|
||||||
|
|
||||||
|
### Core Team
|
||||||
|
- **Roman** (@uroma2) — Author, maintainer, primary developer
|
||||||
|
- Architecture design
|
||||||
|
- Implementation
|
||||||
|
- Integration of Hermes, Claude, Ruflo, Opencode
|
||||||
|
|
||||||
|
### External Contributors
|
||||||
|
- [List contributors here as they join]
|
||||||
|
- [Add PR numbers and contributions]
|
||||||
|
|
||||||
|
**Want to contribute?** See [CONTRIBUTING.md](./CONTRIBUTING.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Attribution
|
||||||
|
|
||||||
|
When using or referencing zCode CLI X in your work:
|
||||||
|
|
||||||
|
```bibtex
|
||||||
|
@software{zcode2026,
|
||||||
|
author = {Roman},
|
||||||
|
title = {zCode CLI X: The Ultimate Agentic Coding Assistant},
|
||||||
|
year = {2026},
|
||||||
|
url = {https://github.rommark.dev/admin/zCode-CLI-X},
|
||||||
|
license = {MIT}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Citation format**:
|
||||||
|
> Roman. "zCode CLI X: The Ultimate Agentic Coding Assistant." GitHub, 2026. https://github.rommark.dev/admin/zCode-CLI-X
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔗 Links
|
||||||
|
|
||||||
|
- **Project**: [github.rommark.dev/admin/zCode-CLI-X](https://github.rommark.dev/admin/zCode-CLI-X)
|
||||||
|
- **Issues**: [Report bugs](https://github.rommark.dev/admin/zCode-CLI-X/issues)
|
||||||
|
- **Discussions**: [Feature requests](https://github.rommark.dev/admin/zCode-CLI-X/discussions)
|
||||||
|
- **Documentation**: [README.md](./README.md), [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
**Built with ❤️ using open-source software**
|
||||||
|
*Special thanks to all the projects and contributors listed above*
|
||||||
|
|
||||||
|
</div>
|
||||||
545
INSTALLATION.md
Normal file
545
INSTALLATION.md
Normal file
@@ -0,0 +1,545 @@
|
|||||||
|
# zCode CLI X - Installation & Setup Guide
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
### Required
|
||||||
|
- **Node.js** ≥ 20.0.0 ([Download](https://nodejs.org/))
|
||||||
|
- **npm** ≥ 9.0.0 (comes with Node.js)
|
||||||
|
- **Git** (for version control)
|
||||||
|
- **systemd** (for 24/7 service on Linux)
|
||||||
|
- **ffmpeg** (for voice I/O)
|
||||||
|
- **Python 3.8+** (for Vosk STT)
|
||||||
|
|
||||||
|
### Optional
|
||||||
|
- **SSL certificate** (for HTTPS webhook)
|
||||||
|
- **Domain name** (for custom webhook URL)
|
||||||
|
- **Docker** (for containerized deployment - coming soon)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Start (5 Minutes)
|
||||||
|
|
||||||
|
### 1. Clone Repository
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.rommark.dev/admin/zCode-CLI-X.git
|
||||||
|
cd zCode-CLI-X
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Install Dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Configure Environment
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
nano .env
|
||||||
|
```
|
||||||
|
|
||||||
|
Edit `.env` with your credentials:
|
||||||
|
|
||||||
|
```env
|
||||||
|
# Z.AI Configuration (Coding Plan)
|
||||||
|
GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4
|
||||||
|
ZAI_API_KEY=your_zai_api_key_here
|
||||||
|
|
||||||
|
# Telegram Bot Configuration
|
||||||
|
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
|
||||||
|
TELEGRAM_ALLOWED_USERS=your_telegram_id,friend_id
|
||||||
|
ZCODE_WEBHOOK_URL=https://your-domain.com/telegram/webhook
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Test Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test as CLI (temporary session)
|
||||||
|
node bin/zcode.js
|
||||||
|
|
||||||
|
# Test as bot (24/7)
|
||||||
|
node bin/zcode.js --no-cli
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Install as Systemd Service
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Copy service file
|
||||||
|
cp scripts/zcode.service ~/.config/systemd/user/
|
||||||
|
|
||||||
|
# Reload systemd
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
|
||||||
|
# Enable and start service
|
||||||
|
systemctl --user enable zcode
|
||||||
|
systemctl --user start zcode
|
||||||
|
|
||||||
|
# Check status
|
||||||
|
systemctl --user status zcode
|
||||||
|
|
||||||
|
# View logs
|
||||||
|
journalctl --user -u zcode -f
|
||||||
|
```
|
||||||
|
|
||||||
|
✅ **Done!** Your bot is now running 24/7.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Detailed Setup
|
||||||
|
|
||||||
|
### Step 1: Install Node.js
|
||||||
|
|
||||||
|
#### Ubuntu/Debian
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||||
|
sudo apt-get install -y nodejs
|
||||||
|
node --version # Should show v20.x or higher
|
||||||
|
npm --version # Should show 9.x or higher
|
||||||
|
```
|
||||||
|
|
||||||
|
#### macOS (Homebrew)
|
||||||
|
```bash
|
||||||
|
brew install node@20
|
||||||
|
node --version
|
||||||
|
npm --version
|
||||||
|
```
|
||||||
|
|
||||||
|
#### CentOS/RHEL
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
|
||||||
|
sudo yum install -y nodejs
|
||||||
|
node --version
|
||||||
|
npm --version
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Install ffmpeg (for Voice I/O)
|
||||||
|
|
||||||
|
#### Ubuntu/Debian
|
||||||
|
```bash
|
||||||
|
sudo apt-get update
|
||||||
|
sudo apt-get install -y ffmpeg
|
||||||
|
ffmpeg -version # Verify installation
|
||||||
|
```
|
||||||
|
|
||||||
|
#### macOS
|
||||||
|
```bash
|
||||||
|
brew install ffmpeg
|
||||||
|
ffmpeg -version
|
||||||
|
```
|
||||||
|
|
||||||
|
#### CentOS/RHEL
|
||||||
|
```bash
|
||||||
|
sudo yum install -y ffmpeg
|
||||||
|
ffmpeg -version
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Install Python & Vosk (for Voice STT)
|
||||||
|
|
||||||
|
#### Install Python 3.8+
|
||||||
|
```bash
|
||||||
|
# Ubuntu/Debian
|
||||||
|
sudo apt-get install -y python3 python3-pip
|
||||||
|
|
||||||
|
# macOS
|
||||||
|
brew install python
|
||||||
|
|
||||||
|
# Verify
|
||||||
|
python3 --version # Should show 3.8+
|
||||||
|
pip3 --version
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Install Vosk Model
|
||||||
|
```bash
|
||||||
|
# Create model directory
|
||||||
|
mkdir -p ~/vosk-models
|
||||||
|
|
||||||
|
# Download small model (68MB, ~95% accuracy)
|
||||||
|
cd ~/vosk-models
|
||||||
|
wget https://alphacephei.com/vosk-models/vosk-model-small-0.15.zip
|
||||||
|
unzip vosk-model-small-0.15.zip
|
||||||
|
|
||||||
|
# Verify
|
||||||
|
ls -la vosk-model-small-0.15/ # Should show model files
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Install Vosk Python Package
|
||||||
|
```bash
|
||||||
|
pip3 install vosk
|
||||||
|
pip3 install sounddevice # For audio recording
|
||||||
|
pip3 install scipy # For audio processing
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Configure Telegram Bot
|
||||||
|
|
||||||
|
#### 1. Create Bot with BotFather
|
||||||
|
1. Open Telegram and search for `@BotFather`
|
||||||
|
2. Send `/newbot` command
|
||||||
|
3. Follow prompts to name your bot
|
||||||
|
4. Save the **API Token** (looks like: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)
|
||||||
|
|
||||||
|
#### 2. Get Your Telegram ID
|
||||||
|
1. Search for `@userinfobot` in Telegram
|
||||||
|
2. Send any message
|
||||||
|
3. Copy your **User ID** (looks like: `123456789`)
|
||||||
|
|
||||||
|
#### 3. Update `.env`
|
||||||
|
```env
|
||||||
|
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||||||
|
TELEGRAM_ALLOWED_USERS=123456789,987654321 # Your ID + friends' IDs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Set Up Webhook
|
||||||
|
|
||||||
|
#### Option A: Using ngrok (Quick Testing)
|
||||||
|
```bash
|
||||||
|
# Install ngrok
|
||||||
|
npm install -g ngrok
|
||||||
|
|
||||||
|
# Start local server
|
||||||
|
node bin/zcode.js --no-cli &
|
||||||
|
|
||||||
|
# Expose to internet (in new terminal)
|
||||||
|
ngrok http 3001
|
||||||
|
|
||||||
|
# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
|
||||||
|
# Update .env:
|
||||||
|
# ZCODE_WEBHOOK_URL=https://abc123.ngrok.io/telegram/webhook
|
||||||
|
|
||||||
|
# Set webhook via API
|
||||||
|
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://abc123.ngrok.io/telegram/webhook"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Option B: Using Domain (Production)
|
||||||
|
```bash
|
||||||
|
# 1. Set up Nginx reverse proxy
|
||||||
|
sudo nano /etc/nginx/sites-available/zcode
|
||||||
|
|
||||||
|
# Add:
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name your-domain.com;
|
||||||
|
|
||||||
|
location /telegram/webhook {
|
||||||
|
proxy_pass http://localhost:3001;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# Enable site
|
||||||
|
sudo ln -s /etc/nginx/sites-available/zcode /etc/nginx/sites-enabled/
|
||||||
|
sudo nginx -t
|
||||||
|
sudo systemctl restart nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 2. Get SSL certificate (Let's Encrypt)
|
||||||
|
sudo apt-get install -y certbot python3-certbot-nginx
|
||||||
|
sudo certbot --nginx -d your-domain.com
|
||||||
|
|
||||||
|
# 3. Set webhook
|
||||||
|
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Install Systemd Service
|
||||||
|
|
||||||
|
#### 1. Copy Service File
|
||||||
|
```bash
|
||||||
|
cp scripts/zcode.service ~/.config/systemd/user/
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. Edit Service File (if needed)
|
||||||
|
```bash
|
||||||
|
nano ~/.config/systemd/user/zcode.service
|
||||||
|
```
|
||||||
|
|
||||||
|
Update paths if necessary:
|
||||||
|
```ini
|
||||||
|
[Service]
|
||||||
|
ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli
|
||||||
|
WorkingDirectory=/home/uroma2/zcode-cli-x
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. Enable and Start
|
||||||
|
```bash
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
systemctl --user enable zcode
|
||||||
|
systemctl --user start zcode
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. Verify
|
||||||
|
```bash
|
||||||
|
systemctl --user status zcode
|
||||||
|
# Should show: Active: active (running)
|
||||||
|
|
||||||
|
journalctl --user -u zcode -f
|
||||||
|
# Should show: zCode CLI X running 24/7
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration Reference
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
| Variable | Required | Description | Example |
|
||||||
|
|----------|----------|-------------|---------|
|
||||||
|
| `GLM_BASE_URL` | ✅ | Z.AI API base URL | `https://api.z.ai/api/coding/paas/v4` |
|
||||||
|
| `ZAI_API_KEY` | ✅ | Z.AI API key | `d88afea988...` |
|
||||||
|
| `TELEGRAM_BOT_TOKEN` | ✅ | Telegram bot token | `123456789:ABCdef...` |
|
||||||
|
| `TELEGRAM_ALLOWED_USERS` | ✅ | Comma-separated user IDs | `123456789,987654321` |
|
||||||
|
| `ZCODE_WEBHOOK_URL` | ✅ | Webhook endpoint URL | `https://your-domain.com/telegram/webhook` |
|
||||||
|
| `VOSK_MODEL_PATH` | ❌ | Path to Vosk model | `~/vosk-models/vosk-model-small-0.15` |
|
||||||
|
| `FFMPEG_PATH` | ❌ | Path to ffmpeg binary | `/usr/bin/ffmpeg` |
|
||||||
|
| `RTK_PATH` | ❌ | Path to RTK binary | `~/.local/bin/rtk` |
|
||||||
|
| `LOG_LEVEL` | ❌ | Logging level | `debug`, `info`, `warn`, `error` |
|
||||||
|
| `LOG_FILE` | ❌ | Log file path | `logs/zcode.log` |
|
||||||
|
|
||||||
|
### Config File (`.zcode.config.json`)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"api": {
|
||||||
|
"baseUrl": "https://api.z.ai/api/coding/paas/v4",
|
||||||
|
"models": {
|
||||||
|
"default": "glm-5.1",
|
||||||
|
"fallback": "glm-4v"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"telegram": {
|
||||||
|
"allowedUsers": ["123456789"],
|
||||||
|
"webhookUrl": "https://your-domain.com/telegram/webhook"
|
||||||
|
},
|
||||||
|
"memory": {
|
||||||
|
"maxEntries": 500,
|
||||||
|
"evictionPolicy": "lru"
|
||||||
|
},
|
||||||
|
"agents": {
|
||||||
|
"enabled": ["coder", "reviewer", "architect"],
|
||||||
|
"maxTurns": 10
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Bot Not Starting
|
||||||
|
|
||||||
|
**Error**: `EADDRINUSE: address already in use :::3001`
|
||||||
|
```bash
|
||||||
|
# Kill existing process
|
||||||
|
lsof -ti:3001 | xargs kill -9
|
||||||
|
systemctl --user restart zcode
|
||||||
|
```
|
||||||
|
|
||||||
|
**Error**: `Telegram bot token not configured`
|
||||||
|
```bash
|
||||||
|
# Check .env file
|
||||||
|
cat .env | grep TELEGRAM_BOT_TOKEN
|
||||||
|
# Should show: TELEGRAM_BOT_TOKEN=123456789:ABCdef...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Voice I/O Not Working
|
||||||
|
|
||||||
|
**Error**: `Vosk model not found`
|
||||||
|
```bash
|
||||||
|
# Check model path
|
||||||
|
ls -la ~/vosk-models/vosk-model-small-0.15/
|
||||||
|
# Should show: model.json, graphs, etc.
|
||||||
|
|
||||||
|
# Update .env
|
||||||
|
VOSK_MODEL_PATH=/home/uroma2/vosk-models/vosk-model-small-0.15
|
||||||
|
```
|
||||||
|
|
||||||
|
**Error**: `ffmpeg not found`
|
||||||
|
```bash
|
||||||
|
# Install ffmpeg
|
||||||
|
sudo apt-get install -y ffmpeg
|
||||||
|
|
||||||
|
# Verify
|
||||||
|
ffmpeg -version
|
||||||
|
```
|
||||||
|
|
||||||
|
### Webhook Not Receiving Messages
|
||||||
|
|
||||||
|
**Error**: `Webhook not set`
|
||||||
|
```bash
|
||||||
|
# Manually set webhook
|
||||||
|
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"
|
||||||
|
|
||||||
|
# Check webhook info
|
||||||
|
curl -X GET "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Error**: `Connection timeout`
|
||||||
|
```bash
|
||||||
|
# Check firewall
|
||||||
|
sudo ufw status
|
||||||
|
# Should allow port 80 and 443
|
||||||
|
|
||||||
|
# Check Nginx
|
||||||
|
sudo nginx -t
|
||||||
|
sudo systemctl status nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service Not Running
|
||||||
|
|
||||||
|
**Error**: `Active: inactive (dead)`
|
||||||
|
```bash
|
||||||
|
# Check logs
|
||||||
|
journalctl --user -u zcode -n 50 --no-pager
|
||||||
|
|
||||||
|
# Restart service
|
||||||
|
systemctl --user restart zcode
|
||||||
|
|
||||||
|
# Check status
|
||||||
|
systemctl --user status zcode
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Advanced Setup
|
||||||
|
|
||||||
|
### Docker Deployment (Coming Soon)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build image
|
||||||
|
docker build -t zcode-cli-x .
|
||||||
|
|
||||||
|
# Run container
|
||||||
|
docker run -d \
|
||||||
|
--name zcode \
|
||||||
|
-v $(pwd)/.env:/app/.env \
|
||||||
|
-v $(pwd)/logs:/app/logs \
|
||||||
|
-p 3001:3001 \
|
||||||
|
zcode-cli-x
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multiple Instances
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Copy service file with different name
|
||||||
|
cp scripts/zcode.service ~/.config/systemd/user/zcode-2.service
|
||||||
|
|
||||||
|
# Edit service file
|
||||||
|
nano ~/.config/systemd/user/zcode-2.service
|
||||||
|
# Change: ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli
|
||||||
|
# To: ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli --instance 2
|
||||||
|
|
||||||
|
# Enable and start
|
||||||
|
systemctl --user enable zcode-2
|
||||||
|
systemctl --user start zcode-2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom Domain with SSL
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Get domain DNS record
|
||||||
|
# Add A record: your-domain.com -> YOUR_SERVER_IP
|
||||||
|
|
||||||
|
# 2. Install Nginx
|
||||||
|
sudo apt-get install -y nginx
|
||||||
|
|
||||||
|
# 3. Configure Nginx
|
||||||
|
sudo nano /etc/nginx/sites-available/zcode
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name your-domain.com;
|
||||||
|
|
||||||
|
location /telegram/webhook {
|
||||||
|
proxy_pass http://localhost:3001;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# 4. Enable site
|
||||||
|
sudo ln -s /etc/nginx/sites-available/zcode /etc/nginx/sites-enabled/
|
||||||
|
sudo nginx -t
|
||||||
|
sudo systemctl restart nginx
|
||||||
|
|
||||||
|
# 5. Get SSL certificate
|
||||||
|
sudo certbot --nginx -d your-domain.com
|
||||||
|
|
||||||
|
# 6. Set webhook
|
||||||
|
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
### Check All Components
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Node.js version
|
||||||
|
node --version # Should show v20.x+
|
||||||
|
|
||||||
|
# 2. npm version
|
||||||
|
npm --version # Should show 9.x+
|
||||||
|
|
||||||
|
# 3. ffmpeg
|
||||||
|
ffmpeg -version # Should show version info
|
||||||
|
|
||||||
|
# 4. Python & Vosk
|
||||||
|
python3 --version # Should show 3.8+
|
||||||
|
python3 -c "import vosk; print(vosk.__version__)" # Should print version
|
||||||
|
|
||||||
|
# 5. Service status
|
||||||
|
systemctl --user status zcode # Should show: active (running)
|
||||||
|
|
||||||
|
# 6. Webhook info
|
||||||
|
curl -X GET "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"
|
||||||
|
# Should show: {"ok":true,"url":"https://your-domain.com/telegram/webhook"}
|
||||||
|
|
||||||
|
# 7. Test bot
|
||||||
|
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getMe"
|
||||||
|
# Should show your bot info
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run Smoke Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run Ruflo smoke tests
|
||||||
|
node test-ruflo-smoke.mjs
|
||||||
|
|
||||||
|
# Should show:
|
||||||
|
# ✅ PluginSystem: 10/10
|
||||||
|
# ✅ HookSystem: 4/4
|
||||||
|
# ✅ AgentSystem: 9/9
|
||||||
|
# ✅ SwarmCoordinator: 12/12
|
||||||
|
# ✅ AgentOrchestrator: 4/4
|
||||||
|
# ✅ MemoryBackend: 14/14
|
||||||
|
# Total: 53/53
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. ✅ **Test the bot** — Send `/start` in Telegram
|
||||||
|
2. ✅ **Explore features** — Try `/tools`, `/agents`, `/memory`
|
||||||
|
3. ✅ **Configure voice** — Set up Vosk model and ffmpeg
|
||||||
|
4. ✅ **Customize** — Edit `.zcode.config.json` for your needs
|
||||||
|
5. ✅ **Monitor** — Use `journalctl --user -u zcode -f` to watch logs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
- **Issues**: [GitHub Issues](https://github.rommark.dev/admin/zCode-CLI-X/issues)
|
||||||
|
- **Discussions**: [GitHub Discussions](https://github.rommark.dev/admin/zCode-CLI-X/discussions)
|
||||||
|
- **Documentation**: [README.md](./README.md), [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
**Ready to deploy?** Follow the steps above and your bot will be running in minutes! 🚀
|
||||||
|
|
||||||
|
</div>
|
||||||
55
package.json
55
package.json
@@ -1,14 +1,44 @@
|
|||||||
{
|
{
|
||||||
"name": "zcode-cli-x",
|
"name": "zcode-cli-x",
|
||||||
"version": "1.0.0",
|
"version": "2.0.0",
|
||||||
"description": "Agentic coder with Z.AI + Telegram integration — Claude Code + Hermes in one beast",
|
"description": "The Ultimate Agentic Coding Assistant — Hermes Agent × Claude Code × Ruflo × Opencode in One Beast",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"bin": {
|
"bin": {
|
||||||
"zcode": "./bin/zcode.js"
|
"zcode": "./bin/zcode.js"
|
||||||
},
|
},
|
||||||
"engines": {
|
"engines": {
|
||||||
"node": ">=20.0.0"
|
"node": ">=20.0.0",
|
||||||
|
"npm": ">=9.0.0"
|
||||||
},
|
},
|
||||||
|
"author": "Roman <uroma2>",
|
||||||
|
"license": "MIT",
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "https://github.rommark.dev/admin/zCode-CLI-X.git"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.rommark.dev/admin/zCode-CLI-X",
|
||||||
|
"keywords": [
|
||||||
|
"ai",
|
||||||
|
"agent",
|
||||||
|
"coding",
|
||||||
|
"telegram",
|
||||||
|
"zai",
|
||||||
|
"glm",
|
||||||
|
"hermes",
|
||||||
|
"claude",
|
||||||
|
"ruflo",
|
||||||
|
"opencode",
|
||||||
|
"autonomous",
|
||||||
|
"self-evolve",
|
||||||
|
"multi-agent",
|
||||||
|
"swarm",
|
||||||
|
"plugin",
|
||||||
|
"hook",
|
||||||
|
"rtk",
|
||||||
|
"voice",
|
||||||
|
"stt",
|
||||||
|
"tts"
|
||||||
|
],
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@anthropic-ai/sdk": "^0.81.0",
|
"@anthropic-ai/sdk": "^0.81.0",
|
||||||
"@grammyjs/auto-retry": "^2.0.2",
|
"@grammyjs/auto-retry": "^2.0.2",
|
||||||
@@ -30,10 +60,27 @@
|
|||||||
"winston": "^3.13.0",
|
"winston": "^3.13.0",
|
||||||
"ws": "^8.18.0"
|
"ws": "^8.18.0"
|
||||||
},
|
},
|
||||||
|
"devDependencies": {},
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"start": "node bin/zcode.js",
|
"start": "node bin/zcode.js",
|
||||||
"dev": "node --watch bin/zcode.js",
|
"dev": "node --watch bin/zcode.js",
|
||||||
"build": "echo 'No build step needed' && chmod +x bin/zcode.js",
|
"build": "echo 'No build step needed' && chmod +x bin/zcode.js",
|
||||||
"test": "echo 'TODO: Add tests'"
|
"test": "node test-ruflo-smoke.mjs",
|
||||||
|
"test:all": "echo 'Running all tests...'",
|
||||||
|
"lint": "echo 'No linter configured'",
|
||||||
|
"format": "echo 'No formatter configured'"
|
||||||
|
},
|
||||||
|
"bugs": {
|
||||||
|
"url": "https://github.rommark.dev/admin/zCode-CLI-X/issues",
|
||||||
|
"email": "admin@rommark.dev"
|
||||||
|
},
|
||||||
|
"funding": {
|
||||||
|
"type": "github",
|
||||||
|
"url": "https://github.com/sponsors/uroma2"
|
||||||
|
},
|
||||||
|
"support": {
|
||||||
|
"community": "https://github.rommark.dev/admin/zCode-CLI-X/discussions",
|
||||||
|
"source": "https://github.rommark.dev/admin/zCode-CLI-X",
|
||||||
|
"docs": "https://github.rommark.dev/admin/zCode-CLI-X/blob/main/README.md"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user