QQ AI Chat Bot

English | 简体中文

A QQ chat bot built with Koishi, OneBot, LLBot, PMHQ, and ChatLuna.

Production Deploy

Production runs on km6 as one active server instance for the full PMHQ, LLBot, and Koishi stack. Deployment is maintained in deploy/README.md.

/opt/qqbot/app       active application instance
/opt/qqbot/data      runtime data and caches
/opt/qqbot/shared    env files and server-maintained configuration

Deploy from the local checkout:

cd ~/code/qqbot
deploy/deploy.sh km6

Runtime Boundary

The repository is a source, build, and runtime workspace.

Keep generated outputs and local runtime state out of Git:

build/
dist/
.tmp/
.runtime/
data/koishi.db
data/logs/
node_modules/

If a file is generated every time by build, test, dev, or runtime commands and is safe to regenerate, ignore it instead of repeatedly cleaning it by hand.

Local Development

The checkout expects a sibling ChatLuna checkout:

~/code/qqbot
~/code/chatluna

Install dependencies and verify the workspace from ~/code/qqbot:

pnpm install
pnpm typecheck
pnpm test
pnpm build

pnpm build writes runtime artifacts to dist/. dist/ is ignored and should not be committed.

For frontend-only admin changes, run both pnpm admin:typecheck and pnpm admin:build. Runtime backend, shared runtime types, Admin API contract, or managed env key changes used by koishi.yml require pnpm build.

Runtime Commands

Developer-local runtime:

pnpm start:local

Server-style runtime from this checkout:

pnpm start:server

Startup performs a preflight check for linked ChatLuna packages and built runtime artifacts. It does not run a build implicitly.

Environment Files

Use the templates as ownership boundaries:

.env.example          developer-local template; copy to .env.local
.env.server.example   server runtime template; copy to the server .env.server

Keep secrets in local env files. Do not commit .env.local, .env.server, .runtime/, or runtime databases.

Important runtime values:

ONEBOT_WS_ENDPOINT=ws://127.0.0.1:3001
KOISHI_HOST=127.0.0.1
KOISHI_PORT=5140
SQLITE_PATH=./data/koishi.db
LLBOT_RUNTIME_DIR=./.runtime/llbot
LLONEBOT_DATA_DIR=./.runtime/llonebot

Server voice input is intentionally disabled by default. If voice output is enabled on the server, QQ_VOICE_TTS_BASE_URL must point to a Tailnet-reachable TTS service, not 127.0.0.1 on the server.

Independent Admin Workspace

The Koishi process serves the standalone SPA directly at /; the SPA uses the same-origin /api/admin/v1 runtime API and has no Koishi Console dependency. The official Console required by ChatLuna Agent lives at the internal /koishi-console path with its WebSocket API at /koishi-console/status. Bot-owned HTTP routes such as /api/**, campus binding pages, and Storage remain owned by their respective plugins.

/intelligence/agent is the permanent ChatLuna Agent management surface and exposes four modules: MCP, Tools, Skills, and Plugin. Tools owns the runtime registry, scoped access, and file/shell boundaries. The Plugin module follows the Codex manifest capability-package model, where a package declares its MCP servers, Skills, and Tools; Computer is the built-in Plugin for file, terminal, and desktop backends. Sub-Agent management is closed for now, and Skill writes explicitly deny Sub-Agent access. Agent writes are delegated to the upstream runtime service, whose canonical document is ${CHATLUNA_AGENT_DATA_DIR}/agents/config.json; managed environment saves do not mirror or overwrite that document.

Configure the browser-facing origin explicitly before startup:

QQBOT_ADMIN_ORIGIN=https://actual-admin-origin.example
QQBOT_ADMIN_SSH_ORIGIN=http://127.0.0.1:5140

QQBOT_ADMIN_ORIGIN must match the Tailnet browser Origin. QQBOT_ADMIN_SSH_ORIGIN must match the browser Origin produced by the SSH local forward. The API validates both Hosts on every request and both Origins on every mutation. Production binds Koishi to loopback and publishes the admin workspace through its Tailnet-only Tailscale Serve endpoint. Console applies the same Host, loopback transport, and Tailscale identity checks, so only local access, SSH tunnels, and the controlled Tailnet endpoint can reach it; public Cloudflare bind hosts are rejected. Secret fields only expose whether a value is configured.

Runtime Helpers

Current runtime helpers are direct workspace scripts:

scripts/run-koishi-with-env.sh
scripts/podman-pmhq-service.sh
scripts/run-llbot-host.sh
scripts/verify-qqbot-host-runtime.sh
scripts/server-recover-qq-login.sh
scripts/run-voice-tts-local.sh
scripts/publish-voice-tts-tailnet.sh

These scripts are direct runtime helpers for this workspace.

Testing Policy

Test maintenance follows docs/testing-policy.md. Keep tests focused on stable user behavior, runtime contracts, artifact shape, and ownership boundaries.