Rodrigo Rodriguez (Pragmatismo)
fde61592ab
- Document email-read-pixel in parameters.md - Add Email Read Tracking section to email-api.md - Include all 4 tracking endpoints with examples - Add database schema for sent_email_tracking - Include privacy considerations (GDPR/LGPD)
290 lines
No EOL
7.5 KiB
Markdown
290 lines
No EOL
7.5 KiB
Markdown
# BotBook Development Prompt Guide
|
|
|
|
**Version:** 6.1.0
|
|
**Purpose:** LLM context for BotBook documentation development
|
|
|
|
---
|
|
|
|
## Official Icons - MANDATORY
|
|
|
|
**NEVER generate icons with LLM. ALWAYS use official SVG icons from `src/assets/icons/`.**
|
|
|
|
### Available Icons
|
|
|
|
| Icon | File | Usage |
|
|
|------|------|-------|
|
|
| Logo | `gb-logo.svg` | Main GB branding |
|
|
| Bot | `gb-bot.svg` | Bot/assistant representation |
|
|
| Analytics | `gb-analytics.svg` | Charts, metrics, dashboards |
|
|
| Calendar | `gb-calendar.svg` | Scheduling, events |
|
|
| Chat | `gb-chat.svg` | Conversations, messaging |
|
|
| Compliance | `gb-compliance.svg` | Security, auditing |
|
|
| Designer | `gb-designer.svg` | Workflow automation |
|
|
| Drive | `gb-drive.svg` | File storage, documents |
|
|
| Mail | `gb-mail.svg` | Email functionality |
|
|
| Meet | `gb-meet.svg` | Video conferencing |
|
|
| Paper | `gb-paper.svg` | Document editing |
|
|
| Research | `gb-research.svg` | Search, investigation |
|
|
| Sources | `gb-sources.svg` | Knowledge bases |
|
|
| Tasks | `gb-tasks.svg` | Task management |
|
|
| Chart | `gb-chart.svg` | Data visualization |
|
|
| Check | `gb-check.svg` | Success, completion |
|
|
| Database | `gb-database.svg` | Data storage |
|
|
| Folder | `gb-folder.svg` | File organization |
|
|
| Gear | `gb-gear.svg` | Settings |
|
|
| Globe | `gb-globe.svg` | Web, internet |
|
|
| Lightbulb | `gb-lightbulb.svg` | Ideas, tips |
|
|
| Lock | `gb-lock.svg` | Security |
|
|
| Note | `gb-note.svg` | Notes, comments |
|
|
| Package | `gb-package.svg` | Packages, modules |
|
|
| Palette | `gb-palette.svg` | Themes, styling |
|
|
| Rocket | `gb-rocket.svg` | Launch, deploy |
|
|
| Search | `gb-search.svg` | Search functionality |
|
|
| Signal | `gb-signal.svg` | Connectivity |
|
|
| Target | `gb-target.svg` | Goals, objectives |
|
|
| Tree | `gb-tree.svg` | Hierarchy, structure |
|
|
| Warning | `gb-warning.svg` | Alerts, cautions |
|
|
|
|
### Usage in Documentation
|
|
|
|
```markdown
|
|
<!-- Reference icons in docs -->
|
|
|
|
|
|
<!-- Or with HTML for sizing -->
|
|
<img src="../assets/icons/gb-analytics.svg" alt="Analytics" width="24">
|
|
```
|
|
|
|
### Icon Guidelines
|
|
|
|
- All icons use `stroke="currentColor"` for CSS theming
|
|
- ViewBox: `0 0 24 24`
|
|
- Stroke width: `1.5`
|
|
- Rounded line caps and joins
|
|
- Consistent with GB brand identity
|
|
|
|
**DO NOT:**
|
|
- Generate new icons with AI/LLM
|
|
- Use emoji or unicode symbols as icons
|
|
- Use external icon libraries (FontAwesome, etc.)
|
|
- Create inline SVG diagrams when an official icon exists
|
|
|
|
---
|
|
|
|
## Project Overview
|
|
|
|
BotBook is the **mdBook-based documentation** for the General Bots platform. It provides comprehensive guides, tutorials, and API references for users and developers.
|
|
|
|
### Workspace Position
|
|
|
|
```
|
|
botbook/ # THIS PROJECT - Documentation
|
|
botserver/ # Main server (source of truth)
|
|
botlib/ # Shared library
|
|
botui/ # Web/Desktop UI
|
|
botapp/ # Desktop app
|
|
botmodels/ # Data models visualization
|
|
botplugin/ # Browser extension
|
|
```
|
|
|
|
### What BotBook Provides
|
|
|
|
- **User Guides**: Getting started, installation, quick start
|
|
- **BASIC Reference**: Keywords, syntax, examples
|
|
- **API Documentation**: REST endpoints, WebSocket
|
|
- **Configuration**: Settings, environment variables
|
|
- **Architecture**: System design, components
|
|
|
|
---
|
|
|
|
## Structure
|
|
|
|
```
|
|
botbook/
|
|
├── book.toml # mdBook configuration
|
|
├── src/
|
|
│ ├── SUMMARY.md # Table of contents
|
|
│ ├── README.md # Introduction
|
|
│ ├── chapter-01/ # Run and Talk (Quick Start)
|
|
│ ├── chapter-02/ # Package System
|
|
│ ├── chapter-03/ # Knowledge Base
|
|
│ ├── chapter-04-gbui/ # UI System
|
|
│ ├── chapter-05-gbtheme/ # Theming
|
|
│ ├── chapter-06-gbdialog/ # BASIC Dialogs
|
|
│ ├── chapter-07-gbapp/ # Applications
|
|
│ ├── chapter-08-config/ # Configuration
|
|
│ ├── chapter-09-api/ # REST API
|
|
│ ├── chapter-10-api/ # WebSocket API
|
|
│ ├── chapter-11-features/ # Feature Modules
|
|
│ ├── chapter-12-auth/ # Authentication
|
|
│ ├── chapter-13-community/ # Contributing
|
|
│ ├── chapter-14-migration/ # Migration Guide
|
|
│ ├── appendix-*/ # Reference materials
|
|
│ └── assets/ # Images, diagrams
|
|
├── i18n/ # Translations
|
|
│ ├── src-cn/ # Chinese
|
|
│ ├── src-ja/ # Japanese
|
|
│ └── src-pt/ # Portuguese
|
|
└── book/ # Generated output
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation Rules
|
|
|
|
### CRITICAL REQUIREMENTS
|
|
|
|
```
|
|
- All documentation MUST match actual source code
|
|
- Extract real keywords from botserver/src/basic/keywords/
|
|
- Reference real models from botserver/src/shared/models.rs
|
|
- Use actual examples from botserver/templates/
|
|
- Version numbers must be 6.1.0
|
|
- No placeholder content - only verified features
|
|
```
|
|
|
|
### Writing Style
|
|
|
|
```
|
|
- Beginner-friendly, instructional tone
|
|
- Practical examples that work
|
|
- Step-by-step instructions
|
|
- Clear headings and structure
|
|
- Use mdBook admonitions for tips/warnings
|
|
```
|
|
|
|
### Code Examples
|
|
|
|
```markdown
|
|
<!-- For BASIC examples -->
|
|
```bas
|
|
TALK "Hello, world!"
|
|
name = HEAR
|
|
TALK "Welcome, " + name
|
|
```
|
|
|
|
<!-- For configuration -->
|
|
```csv
|
|
name,value
|
|
server_port,8080
|
|
llm-url,http://localhost:8081
|
|
```
|
|
|
|
<!-- For Rust (only in gbapp chapter) -->
|
|
```rust
|
|
use botlib::prelude::*;
|
|
```
|
|
```
|
|
|
|
---
|
|
|
|
## Building Documentation
|
|
|
|
```bash
|
|
# Install mdBook
|
|
cargo install mdbook
|
|
|
|
# Build documentation
|
|
cd botbook
|
|
mdbook build
|
|
|
|
# Serve locally with hot reload
|
|
mdbook serve --open
|
|
|
|
# Build specific language
|
|
mdbook build --dest-dir book-pt src-pt
|
|
```
|
|
|
|
---
|
|
|
|
## Chapter Content Guidelines
|
|
|
|
### Chapter 1: Run and Talk
|
|
- Quick start (5 minutes to running bot)
|
|
- Bootstrap process explanation
|
|
- First conversation walkthrough
|
|
- Session management basics
|
|
|
|
### Chapter 2: Package System
|
|
- .gbai folder structure
|
|
- .gbot configuration
|
|
- .gbdialog scripts
|
|
- .gbkb knowledge bases
|
|
- .gbtheme customization
|
|
|
|
### Chapter 6: BASIC Dialogs
|
|
- Keyword reference (from source)
|
|
- TALK, HEAR, SET, GET
|
|
- Control flow (IF, FOR, WHILE)
|
|
- Tool creation
|
|
- LLM integration
|
|
|
|
### Chapter 8: Configuration
|
|
- config.csv format
|
|
- Environment variables
|
|
- Database configuration
|
|
- Service settings
|
|
|
|
---
|
|
|
|
## Source Code References
|
|
|
|
When documenting features, verify against actual source:
|
|
|
|
| Topic | Source Location |
|
|
|-------|-----------------|
|
|
| BASIC Keywords | `botserver/src/basic/keywords/` |
|
|
| Database Models | `botserver/src/shared/models.rs` |
|
|
| API Routes | `botserver/src/core/urls.rs` |
|
|
| Configuration | `botserver/src/core/config/` |
|
|
| Bootstrap | `botserver/src/core/bootstrap/` |
|
|
| Templates | `botserver/templates/` |
|
|
|
|
---
|
|
|
|
## Diagram Guidelines
|
|
|
|
For SVG diagrams in `src/assets/`:
|
|
|
|
```
|
|
- Transparent background
|
|
- Dual-theme support (light/dark CSS)
|
|
- Width: 1040-1400px
|
|
- Font: Arial, sans-serif
|
|
- Colors: Blue #4A90E2, Orange #F5A623, Purple #BD10E0, Green #7ED321
|
|
```
|
|
|
|
---
|
|
|
|
## Translation Workflow
|
|
|
|
1. English is source of truth (`src/`)
|
|
2. Translations in `src-{lang}/`
|
|
3. Keep structure identical
|
|
4. Update `book.toml` for each language
|
|
5. Build separately per language
|
|
|
|
---
|
|
|
|
## Quality Checklist
|
|
|
|
Before committing documentation:
|
|
|
|
- [ ] All code examples tested and working
|
|
- [ ] Version numbers are 6.1.0
|
|
- [ ] Links are valid (relative paths)
|
|
- [ ] Images have alt text
|
|
- [ ] SUMMARY.md is updated
|
|
- [ ] mdbook build succeeds without errors
|
|
- [ ] Content matches actual source code
|
|
|
|
---
|
|
|
|
## Rules
|
|
|
|
- **Accuracy**: Must match botserver source code
|
|
- **Completeness**: No placeholder sections
|
|
- **Clarity**: Accessible to BASIC enthusiasts
|
|
- **Version**: Always reference 6.1.0
|
|
- **Examples**: Only working, tested code
|
|
- **Structure**: Follow mdBook conventions |