# Xiaoman Message Center

[简体中文](README.zh-CN.md)

A self-hosted notification relay for scheduled AI workflows. Your task generates the final content; Xiaoman authenticates, routes, delivers, retries, and audits it across QQ and Telegram.

**The relay does not call a paid LLM API.** Your ChatGPT, Cloudflare, Gmail, QQ, and Telegram accounts may still have their own plans, quotas, and limits.

## Why Xiaoman

- One stable route can deliver to one or many destinations.
- Send through REST, MCP, or Gmail plus Google Apps Script.
- Split long messages for QQ and Telegram automatically.
- Prevent duplicate delivery with optional idempotency keys.
- Retry only destinations that did not succeed.
- Review routes, destinations, and recent delivery status in the dashboard.
- Keep channel credentials in the runtime environment—not in the database or repository.

## Architecture

```text
Scheduled task / Gmail / MCP / REST
                 │
                 ▼
       authentication + validation
                 │
                 ▼
           route resolution
             │         │
             ▼         ▼
          QQ bot   Telegram bot
                 │
                 ▼
        D1 delivery audit + retry
```

## Five-minute local setup

Prerequisite: Node.js 22.13 or newer.

```sh
npm ci
cp .env.example .env.local
npm run build
npm run db:local:init
npm run dev
```

For local or standalone use, set `AUTH_MODE=basic`, choose a strong `ADMIN_BASIC_USER` and `ADMIN_BASIC_PASSWORD`, and generate independent random values for `NOTIFICATION_API_TOKEN` and `MCP_BEARER_TOKEN`. Then add at least one QQ or Telegram adapter credential.

See the [English quickstart](docs/en/quickstart.md) or [中文快速开始](docs/zh-CN/quickstart.md) before sending a real message.

## Two safe examples

- [Daily Commute Plan](examples/daily-commute/README.md): a sanitized weather and travel briefing using placeholders for all locations.
- [Daily Health Report](examples/daily-health-report/README.md): a fictional wellness summary; it is not medical advice.

Both examples include REST, MCP, and Gmail subject patterns. No production route, destination, email address, personal location, or health record is included.

## Gmail relay

The copy-paste Google Apps Script integration lives in [`integrations/google-apps-script`](integrations/google-apps-script/README.md). It stores credentials in Script Properties, uses Gmail message IDs as idempotency keys, and supports both subject formats:

```text
小慢消息中心 每日通勤计划｜2026-09-16
Xiaoman Message Center Daily Commute Plan | 2026-09-16
```

## Deployment paths

- [OpenAI Sites](docs/en/deploy-sites.md): keeps Sign in with ChatGPT and managed D1 deployment. The official product overview is available in the [OpenAI Sites documentation](https://learn.chatgpt.com/docs/sites).
- [Standalone Cloudflare](docs/en/deploy-cloudflare.md): uses the included HTTP Basic authentication mode and your own D1 database.

Sites deployment URLs are production URLs. Review the source and configuration before deploying or changing access.

## Documentation

| Topic | English | 简体中文 |
| --- | --- | --- |
| Quickstart | [Guide](docs/en/quickstart.md) | [指南](docs/zh-CN/quickstart.md) |
| Architecture | [Guide](docs/en/architecture.md) | [指南](docs/zh-CN/architecture.md) |
| Configuration | [Reference](docs/en/configuration.md) | [参考](docs/zh-CN/configuration.md) |
| Sites deployment | [Guide](docs/en/deploy-sites.md) | [指南](docs/zh-CN/deploy-sites.md) |
| Cloudflare deployment | [Guide](docs/en/deploy-cloudflare.md) | [指南](docs/zh-CN/deploy-cloudflare.md) |
| QQ and Telegram | [Guide](docs/en/channels.md) | [指南](docs/zh-CN/channels.md) |
| REST and MCP | [Reference](docs/en/api-and-mcp.md) | [参考](docs/zh-CN/api-and-mcp.md) |
| Privacy and security | [Guide](docs/en/security-and-privacy.md) | [指南](docs/zh-CN/security-and-privacy.md) |

## Development

```sh
npm run lint
npm run verify
```

Tests mock the message workflow and never send to a real QQ group or Telegram chat. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## License

[MIT](LICENSE). The name and bundled mascot assets may be used with this repository under the same license; they do not imply endorsement of a modified deployment.