docs: add comprehensive documentation structure
Expand the docs/ directory with 109 markdown files covering: Getting Started: - Installation guide (binary, source, Docker, Termux) - Quick start and configuration basics - First chat tutorial User Guide: - Complete CLI reference (9 command docs) - 11 channel setup guides (Telegram, Discord, Slack, etc.) - 9 LLM provider guides (OpenRouter, Zhipu, Anthropic, etc.) - 8 tool documentation files - Skills system documentation - Workspace customization guides - Advanced features (multi-agent, routing, security, etc.) Developer Guide: - Architecture and data flow - Building and testing - Contributing guidelines - Extension guides for tools, providers, channels, skills - API reference for all interfaces Deployment: - Docker and systemd guides - Termux for Android - SBC guides (Raspberry Pi, LicheeRV Nano, MaixCAM) - Production security checklist Operations: - Health endpoints and monitoring - Logging and device monitoring - Troubleshooting guide Tutorials: - Step-by-step guides for common use cases - Hardware control tutorial Community: - Project roadmap - Support channels - Contributing roles Includes SUMMARY.md for mdBook/GitBook navigation. Generated with [Z.ai](https://z.ai/subscribe?ic=JGTYCX7ZO7) Co-Authored-By: Z.ai GLM-5
This commit is contained in:
Kadic Mirzet
parent
7263f41cfb
commit
cfb37f1f7c
3 changed files with 147 additions and 127 deletions
51
README.md
51
README.md
|
|
@ -125,6 +125,22 @@ PicoClaw can be deployed on almost any Linux device!
|
|||
|
||||
🌟 More Deployment Cases Await！
|
||||
|
||||
---
|
||||
## 📚 Full Documentation
|
||||
|
||||
For comprehensive guides and references, see the [docs/](docs/) directory:
|
||||
|
||||
- **[Getting Started](docs/getting-started/README.md)** - Installation and quick start
|
||||
- **[User Guide](docs/user-guide/README.md)** - Complete feature documentation
|
||||
- **[Developer Guide](docs/developer-guide/README.md)** - Building and extending PicoClaw
|
||||
- **[Deployment](docs/deployment/README.md)** - Docker, systemd, SBC guides
|
||||
- **[Configuration Reference](docs/configuration/config-file.md)** - All config options
|
||||
- **[Troubleshooting](docs/operations/troubleshooting.md)** - Common issues and solutions
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 📦 Install
|
||||
|
||||
### Install with precompiled binary
|
||||
|
|
@ -824,15 +840,40 @@ Jobs are stored in `~/.picoclaw/workspace/cron/` and processed automatically.
|
|||
|
||||
PRs welcome! The codebase is intentionally small and readable. 🤗
|
||||
|
||||
Roadmap coming soon...
|
||||
### Roadmap Highlights
|
||||
|
||||
Developer group building, Entry Requirement: At least 1 Merged PR.
|
||||
| Focus Area | Goals |
|
||||
|------------|-------|
|
||||
| **Core Optimization** | Run on 64MB RAM devices with <20MB memory |
|
||||
| **Security Hardening** | Sandbox, OAuth 2.0, prompt injection defense |
|
||||
| **Connectivity** | More channels, MCP support, skill marketplace |
|
||||
| **Multi-Agent** | Model routing, swarm mode, AIEOS integration |
|
||||
| **DevEx** | Interactive CLI wizard, comprehensive docs |
|
||||
|
||||
User Groups:
|
||||
See [Full Roadmap](ROADMAP.md) and [Community Roadmap](docs/picoclaw_community_roadmap_260216.md) for details.
|
||||
|
||||
discord: <https://discord.gg/V4sAZ9XWpN>
|
||||
### Volunteer Roles
|
||||
|
||||
<img src="assets/wechat.png" alt="PicoClaw" width="512">
|
||||
We're looking for contributors in:
|
||||
- **Issue/PR Reviewers** - Help triage and merge PRs
|
||||
- **Resource Optimization** - Keep PicoClaw lightweight
|
||||
- **Security Audit** - Review and harden security
|
||||
- **Documentation** - Improve guides and tutorials
|
||||
- **CI/CD Automation** - AI-powered builds and issue triage
|
||||
|
||||
**Perks:** Exclusive AI hardware, token discounts, and more!
|
||||
|
||||
### How to Join
|
||||
|
||||
1. **Fast Track**: Merge 1+ PR → Join Developer Discord
|
||||
2. **Apply**: Email support@sipeed.com with `[Apply: PicoClaw Expert Volunteer]`
|
||||
|
||||
### Community
|
||||
|
||||
- **Discord**: <https://discord.gg/V4sAZ9XWpN>
|
||||
- **GitHub Discussions**: Share ideas and feature requests
|
||||
|
||||
<img src="assets/wechat.png" alt="PicoClaw WeChat" width="512">
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
|
|
|
|||
|
|
@ -1,122 +0,0 @@
|
|||
# Tools Configuration
|
||||
|
||||
PicoClaw's tools configuration is located in the `tools` field of `config.json`.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"web": { ... },
|
||||
"exec": { ... },
|
||||
"approval": { ... },
|
||||
"cron": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Web Tools
|
||||
|
||||
Web tools are used for web search and fetching.
|
||||
|
||||
### Brave
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `enabled` | bool | false | Enable Brave search |
|
||||
| `api_key` | string | - | Brave Search API key |
|
||||
| `max_results` | int | 5 | Maximum number of results |
|
||||
|
||||
### DuckDuckGo
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `enabled` | bool | true | Enable DuckDuckGo search |
|
||||
| `max_results` | int | 5 | Maximum number of results |
|
||||
|
||||
### Perplexity
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `enabled` | bool | false | Enable Perplexity search |
|
||||
| `api_key` | string | - | Perplexity API key |
|
||||
| `max_results` | int | 5 | Maximum number of results |
|
||||
|
||||
## Exec Tool
|
||||
|
||||
The exec tool is used to execute shell commands.
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `enable_deny_patterns` | bool | true | Enable default dangerous command blocking |
|
||||
| `custom_deny_patterns` | array | [] | Custom deny patterns (regular expressions) |
|
||||
|
||||
### Functionality
|
||||
|
||||
- **`enable_deny_patterns`**: Set to `false` to completely disable the default dangerous command blocking patterns
|
||||
- **`custom_deny_patterns`**: Add custom deny regex patterns; commands matching these will be blocked
|
||||
|
||||
### Default Blocked Command Patterns
|
||||
|
||||
By default, PicoClaw blocks the following dangerous commands:
|
||||
|
||||
- Delete commands: `rm -rf`, `del /f/q`, `rmdir /s`
|
||||
- Disk operations: `format`, `mkfs`, `diskpart`, `dd if=`, writing to `/dev/sd*`
|
||||
- System operations: `shutdown`, `reboot`, `poweroff`
|
||||
- Command substitution: `$()`, `${}`, backticks
|
||||
- Pipe to shell: `| sh`, `| bash`
|
||||
- Privilege escalation: `sudo`, `chmod`, `chown`
|
||||
- Process control: `pkill`, `killall`, `kill -9`
|
||||
- Remote operations: `curl | sh`, `wget | sh`, `ssh`
|
||||
- Package management: `apt`, `yum`, `dnf`, `npm install -g`, `pip install --user`
|
||||
- Containers: `docker run`, `docker exec`
|
||||
- Git: `git push`, `git force`
|
||||
- Other: `eval`, `source *.sh`
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"exec": {
|
||||
"enable_deny_patterns": true,
|
||||
"custom_deny_patterns": [
|
||||
"\\brm\\s+-r\\b",
|
||||
"\\bkillall\\s+python"
|
||||
],
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Approval Tool
|
||||
|
||||
The approval tool controls permissions for dangerous operations.
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `enabled` | bool | true | Enable approval functionality |
|
||||
| `write_file` | bool | true | Require approval for file writes |
|
||||
| `edit_file` | bool | true | Require approval for file edits |
|
||||
| `append_file` | bool | true | Require approval for file appends |
|
||||
| `exec` | bool | true | Require approval for command execution |
|
||||
| `timeout_minutes` | int | 5 | Approval timeout in minutes |
|
||||
|
||||
## Cron Tool
|
||||
|
||||
The cron tool is used for scheduling periodic tasks.
|
||||
|
||||
| Config | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `exec_timeout_minutes` | int | 5 | Execution timeout in minutes, 0 means no limit |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
All configuration options can be overridden via environment variables with the format `PICOCLAW_TOOLS_<SECTION>_<KEY>`:
|
||||
|
||||
For example:
|
||||
- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
|
||||
- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
|
||||
- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
|
||||
|
||||
Note: Array-type environment variables are not currently supported and must be set via the config file.
|
||||
101
docs/user-guide/tools/approval.md
Normal file
101
docs/user-guide/tools/approval.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
# Approval Tool
|
||||
|
||||
The approval tool controls permissions for sensitive operations, requiring user confirmation before executing.
|
||||
|
||||
## Overview
|
||||
|
||||
When enabled, the approval tool prompts the user to confirm dangerous operations before they are executed. This adds an extra layer of safety for operations that could modify files or execute commands.
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"approval": {
|
||||
"enabled": true,
|
||||
"write_file": true,
|
||||
"edit_file": true,
|
||||
"append_file": true,
|
||||
"exec": true,
|
||||
"timeout_minutes": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `enabled` | bool | `true` | Enable approval functionality |
|
||||
| `write_file` | bool | `true` | Require approval for file writes |
|
||||
| `edit_file` | bool | `true` | Require approval for file edits |
|
||||
| `append_file` | bool | `true` | Require approval for file appends |
|
||||
| `exec` | bool | `true` | Require approval for command execution |
|
||||
| `timeout_minutes` | int | `5` | Approval timeout in minutes |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Agent requests to perform a sensitive operation
|
||||
2. Approval tool intercepts the request
|
||||
3. User is prompted to approve or deny
|
||||
4. If approved within timeout, operation proceeds
|
||||
5. If denied or timeout, operation is cancelled
|
||||
|
||||
## Example Flow
|
||||
|
||||
```
|
||||
Agent: I need to write to config.json. Requesting approval...
|
||||
|
||||
[Approval Request]
|
||||
Operation: write_file
|
||||
Path: config.json
|
||||
Approve? (y/n): y
|
||||
|
||||
Agent: Approved. Writing to config.json...
|
||||
```
|
||||
|
||||
## Disabling Specific Approvals
|
||||
|
||||
Disable approval for specific operations:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"approval": {
|
||||
"enabled": true,
|
||||
"write_file": false,
|
||||
"exec": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This allows the agent to write files and execute commands without approval, while still requiring approval for edits and appends.
|
||||
|
||||
## Disabling All Approvals
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"approval": {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Warning**: Disabling approvals reduces safety. Use only in trusted environments.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
export PICOCLAW_TOOLS_APPROVAL_ENABLED=false
|
||||
export PICOCLAW_TOOLS_APPROVAL_TIMEOUT_MINUTES=10
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Exec Tool](exec.md)
|
||||
- [File System Tools](filesystem.md)
|
||||
- [Security Sandbox](../advanced/security-sandbox.md)
|
||||
Loading…
Add table
Reference in a new issue