Skip to content

Commit dce5aeb

Browse files
imguoguoclaude
imguoguo
and
claude
committed
docs: initialize PicoClaw documentation site with Docusaurus
- Bilingual (EN/ZH) Docusaurus 3.7.0 site with i18n support - English documentation: intro, getting started, installation, configuration, chat channels (11), providers, migration guide, contributing, roadmap - Chinese translations: intro, getting started, installation, configuration overview, all 11 channel pages (migrated from main repo) - GitHub Actions workflow for automatic GitHub Pages deployment - Custom landing page with hero section and feature cards - PicoClaw brand colors (Go blue #00ADD8) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
0 parents  commit dce5aeb

75 files changed

Lines changed: 26308 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.devcontainer/devcontainer.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"name": "PicoClaw Docs",
3+
"image": "mcr.microsoft.com/devcontainers/javascript-node:1-20",
4+
"forwardPorts": [3000],
5+
"portsAttributes": {
6+
"3000": {
7+
"label": "Docusaurus Dev Server",
8+
"onAutoForward": "openPreview"
9+
}
10+
},
11+
"postCreateCommand": "npm install",
12+
"customizations": {
13+
"vscode": {
14+
"extensions": [
15+
"unifiedjs.vscode-mdx",
16+
"DavidAnson.vscode-markdownlint",
17+
"esbenp.prettier-vscode",
18+
"streetsidesoftware.code-spell-checker"
19+
],
20+
"settings": {
21+
"editor.defaultFormatter": "esbenp.prettier-vscode",
22+
"editor.formatOnSave": true,
23+
"files.insertFinalNewline": true
24+
}
25+
}
26+
}
27+
}

‎.github/workflows/deploy.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
# Allow only one concurrent deployment, skip runs queued between the run in-progress and latest queued.
15+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
16+
concurrency:
17+
group: "pages"
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
name: Build Docusaurus
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout repository
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Setup Node.js
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: 20
34+
cache: npm
35+
36+
- name: Install dependencies
37+
run: npm ci
38+
39+
- name: Build website
40+
run: npm run build
41+
42+
- name: Upload Pages artifact
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: build
46+
47+
deploy:
48+
name: Deploy to GitHub Pages
49+
needs: build
50+
runs-on: ubuntu-latest
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Production build
5+
build/
6+
7+
# Generated files
8+
.docusaurus/
9+
.cache-loader/
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# PicoClaw Documentation
2+
3+
This repository contains the source for the [PicoClaw documentation site](https://sipeed.github.io/picoclaw_docs/).
4+
5+
## Development with GitHub Codespaces (Recommended)
6+
7+
The easiest way to contribute — no local setup required.
8+
9+
1. Fork this repository
10+
2. Click **Code → Codespaces → Create codespace on main**
11+
3. Wait for the container to build and dependencies to install automatically
12+
4. Run the dev server:
13+
14+
```bash
15+
# English (default)
16+
npm start
17+
18+
# Chinese
19+
npm run start:zh
20+
```
21+
22+
> **Note:** Docusaurus dev server only serves one locale at a time. Use `npm start` for English or `npm run start:zh` for Chinese. Visiting `/zh-Hans/...` while running `npm start` will return 404.
23+
24+
The preview will open automatically in your browser. The dev server supports hot reload, so changes to docs are reflected instantly.
25+
26+
## Local Development
27+
28+
```bash
29+
npm install
30+
31+
# English (default)
32+
npm start
33+
34+
# Chinese
35+
npm run start:zh
36+
```
37+
38+
Open [http://localhost:3000](http://localhost:3000) to view the site.
39+
40+
## Build
41+
42+
```bash
43+
npm run build
44+
```
45+
46+
## Deploy
47+
48+
This site automatically deploys to GitHub Pages on every push to `main` via GitHub Actions.
49+
50+
To enable deployment in a new repository:
51+
1. Go to **Settings → Pages**
52+
2. Set **Source** to **GitHub Actions**
53+
3. Push to `main`
54+
55+
## Contributing
56+
57+
Content is sourced from and synchronized with the main [sipeed/picoclaw](https://github.com/sipeed/picoclaw) repository.
58+
59+
To update documentation, open a PR with the updated Markdown files.
60+
61+
## Structure
62+
63+
```
64+
docs/ English documentation (default locale)
65+
i18n/zh-Hans/ Chinese documentation
66+
src/ Custom React pages and CSS
67+
static/img/ Images and assets
68+
```

‎docs/channels/dingtalk.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
id: dingtalk
3+
title: DingTalk (钉钉)
4+
---
5+
6+
# DingTalk
7+
8+
DingTalk integration uses Stream Mode, so no public IP is needed.
9+
10+
## Setup
11+
12+
### 1. Create a Bot
13+
14+
- Go to [Open Platform](https://open.dingtalk.com/)
15+
- Create an internal app
16+
- Copy **Client ID** and **Client Secret**
17+
18+
### 2. Configure
19+
20+
```json
21+
{
22+
"channels": {
23+
"dingtalk": {
24+
"enabled": true,
25+
"client_id": "YOUR_CLIENT_ID",
26+
"client_secret": "YOUR_CLIENT_SECRET",
27+
"allow_from": []
28+
}
29+
}
30+
}
31+
```
32+
33+
| Field | Type | Description |
34+
| --- | --- | --- |
35+
| `client_id` | string | DingTalk app Client ID |
36+
| `client_secret` | string | DingTalk app Client Secret |
37+
| `allow_from` | array | List of allowed DingTalk user IDs (empty = allow all) |
38+
39+
### 3. Run
40+
41+
```bash
42+
picoclaw gateway
43+
```

‎docs/channels/discord.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
id: discord
3+
title: Discord
4+
---
5+
6+
# Discord
7+
8+
## Setup
9+
10+
### 1. Create a Bot
11+
12+
- Go to [discord.com/developers/applications](https://discord.com/developers/applications)
13+
- Create an application → Bot → Add Bot
14+
- Copy the bot token
15+
16+
### 2. Enable Intents
17+
18+
- In Bot settings, enable **MESSAGE CONTENT INTENT**
19+
- (Optional) Enable **SERVER MEMBERS INTENT** for member-based allow lists
20+
21+
### 3. Get Your User ID
22+
23+
- Discord Settings → Advanced → enable **Developer Mode**
24+
- Right-click your avatar → **Copy User ID**
25+
26+
### 4. Configure
27+
28+
```json
29+
{
30+
"channels": {
31+
"discord": {
32+
"enabled": true,
33+
"token": "YOUR_BOT_TOKEN",
34+
"allow_from": ["YOUR_USER_ID"],
35+
"mention_only": false
36+
}
37+
}
38+
}
39+
```
40+
41+
| Field | Type | Description |
42+
| --- | --- | --- |
43+
| `enabled` | bool | Enable/disable the channel |
44+
| `token` | string | Bot token from Discord Developer Portal |
45+
| `allow_from` | array | List of allowed user IDs (empty = allow all) |
46+
| `mention_only` | bool | Only respond when @-mentioned |
47+
48+
### 5. Invite the Bot
49+
50+
- OAuth2 → URL Generator
51+
- Scopes: `bot`
52+
- Bot Permissions: `Send Messages`, `Read Message History`
53+
- Open the generated invite URL and add the bot to your server
54+
55+
### 6. Run
56+
57+
```bash
58+
picoclaw gateway
59+
```
60+
61+
## Mention-Only Mode
62+
63+
Set `"mention_only": true` to make the bot respond only when @-mentioned. Useful for shared servers where you want the bot to be less intrusive.

‎docs/channels/feishu.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
id: feishu
3+
title: Feishu / Lark (飞书)
4+
---
5+
6+
# Feishu / Lark
7+
8+
## Setup
9+
10+
### 1. Create a Feishu App
11+
12+
- Go to [Feishu Open Platform](https://open.feishu.cn/)
13+
- Create a custom app
14+
- Note the **App ID** and **App Secret**
15+
16+
### 2. Configure Permissions
17+
18+
In your app settings, add the following bot permissions:
19+
- `im:message:receive_v1`
20+
- `im:message`
21+
22+
### 3. Enable Message Events
23+
24+
- Add an **Encrypt Key** and **Verification Token** in Event Subscription settings
25+
- Subscribe to the `im.message.receive_v1` event
26+
27+
### 4. Configure PicoClaw
28+
29+
```json
30+
{
31+
"channels": {
32+
"feishu": {
33+
"enabled": true,
34+
"app_id": "cli_xxx",
35+
"app_secret": "YOUR_APP_SECRET",
36+
"encrypt_key": "YOUR_ENCRYPT_KEY",
37+
"verification_token": "YOUR_VERIFICATION_TOKEN",
38+
"allow_from": []
39+
}
40+
}
41+
}
42+
```
43+
44+
| Field | Type | Description |
45+
| --- | --- | --- |
46+
| `app_id` | string | Feishu app ID (starts with `cli_`) |
47+
| `app_secret` | string | Feishu app secret |
48+
| `encrypt_key` | string | Event encryption key |
49+
| `verification_token` | string | Event verification token |
50+
| `allow_from` | array | Allowed user open IDs |
51+
52+
### 5. Run
53+
54+
```bash
55+
picoclaw gateway
56+
```
57+
58+
:::note
59+
Full Feishu documentation is available in Chinese in the repository at `docs/channels/feishu/README.zh.md`.
60+
:::

‎docs/channels/index.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
id: index
3+
title: Chat Channels
4+
sidebar_label: Overview
5+
---
6+
7+
# Chat Channels
8+
9+
Connect PicoClaw to messaging platforms through its **gateway** mode.
10+
11+
```bash
12+
picoclaw gateway
13+
```
14+
15+
## Supported Channels
16+
17+
| Channel | Difficulty | Notes |
18+
| --- | --- | --- |
19+
| **Telegram** | Easy | Recommended. Supports voice transcription with Groq. |
20+
| **Discord** | Easy | Bot token + intents. Supports mention-only mode. |
21+
| **Slack** | Easy | Socket mode, no public IP needed. |
22+
| **QQ** | Easy | Official QQ bot API (AppID + AppSecret). |
23+
| **DingTalk** | Medium | Stream mode, no public IP needed. |
24+
| **WeCom Bot** | Medium | Group chat via webhook. |
25+
| **WeCom App** | Hard | Private chat, more features, requires HTTPS. |
26+
| **Feishu** | Hard | Enterprise collaboration platform. |
27+
| **LINE** | Hard | Requires HTTPS webhook. |
28+
| **OneBot** | Medium | Compatible with NapCat/Go-CQHTTP. |
29+
| **MaixCam** | Easy | Hardware-integrated AI camera. |
30+
31+
## How It Works
32+
33+
1. Configure one or more channels in `~/.picoclaw/config.json` under the `channels` key
34+
2. Set `"enabled": true` for each channel you want to use
35+
3. Run `picoclaw gateway` to start listening
36+
4. The gateway handles all channels concurrently
37+
38+
## Access Control
39+
40+
All channels support the `allow_from` field to restrict access to specific users:
41+
42+
```json
43+
{
44+
"channels": {
45+
"telegram": {
46+
"enabled": true,
47+
"token": "YOUR_TOKEN",
48+
"allow_from": ["123456789"]
49+
}
50+
}
51+
}
52+
```
53+
54+
Set `allow_from` to an empty array `[]` to allow all users.

0 commit comments

Comments
 (0)