本项目是一个可本地运行的 AI 助手 Gateway，按 “Gateway + Connectors + Skills + Runtime” 方式组织，采用 Ports & Adapters（Hexagonal）架构。Gateway 只做控制平面（control plane），管理会话、渠道、工具与事件，不直接耦合业务逻辑。默认安全策略遵循 OpenClaw 思路：

• DM（私聊）视为不可信输入
• 默认 pairing + allowlist
• 明确配置后才允许公开 DM

目标：在团队常用 IM 渠道中对话，Gateway 统一接入、路由、执行工具、回写结果，避免灰产式个人号自动化。

• 飞书、钉钉、腾讯会议：以“工具/技能”方式调用（Agent 主动调用，不作为聊天入口）。
• QQ botpy：支持作为官方群/频道入口（官方 SDK），不支持个人号加好友私聊。
• 剪映/CapCut：占位 Skill，仅定义接口规范与配置项。

不支持个人号微信/QQ 的模拟登录或抓包协议等灰产方案。

• Domain：Message / ToolCall / ToolResult / Event / Session
• Ports：ConnectorPort / SkillPort / StoragePort / LLMPort / EventBusPort
• Adapters：QQ(botpy)、Feishu、DingTalk webhook、Tencent Meeting、SQLite
• Strategy：路由策略、DM policy（pairing/open/closed）
• Command：Skill 执行统一封装
• Registry/Factory：ConnectorRegistry / SkillRegistry / LLMProviderFactory（多厂商 LLM 适配）/ SkillsRegistry
• 依赖注入：FastAPI Depends + Container

Runtime 流程： Inbound Event -> Normalize Message -> AuthZ(allowlist/pairing) -> Router -> AgentSession -> Planner -> ToolCalls -> Executor -> Reply -> Outbound

1. 安装依赖

python -m venv .venv
source .venv/bin/activate
pip install -e .

2. 配置环境变量

cp .env.example .env

3. 配置 LLM（必须）

LLM_PROVIDER=ollama   # openai | gemini | ollama | dashscope
LLM_MODEL=llama3

4. 选择示例 workspace

WORKSPACE_ID=demo
WORKSPACE_ROOT=./workspaces

5. 启动 Gateway

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

6. 本地 mock 测试（HTTP）

curl -X POST http://127.0.0.1:8000/connectors/mock/send \
  -H 'content-type: application/json' \
  -d '{"id":"1","timestamp":"2025-01-01T00:00:00Z","channel":"mock","chat_id":"c1","sender_id":"u1","sender_display":"u1","text":"/help","mentions":[],"attachments":[]}'

7. WebSocket 聊天入口

ws://127.0.0.1:8000/ws

发送消息（JSON）：

{"type":"chat.message","request_id":"r1","chat_id":"c1","sender_id":"u1","text":"你好，帮我用 dingtalk 发送"}

服务端会通过 WS 返回 chat.reply。

• 默认 DM_POLICY=pairing：陌生私聊进入配对流程，生成短码，管理员审批后进入 allowlist。
• 明确配置后才允许开放 DM：DM_POLICY=open 且 ALLOW_FROM 包含 * 或指定用户列表。
• CLI 支持：

python -m app.cli approve <channel> <code>
python -m app.cli revoke <channel> <user_id>
python -m app.cli doctor

SOUL 是 “Who You Are” 的模板文件（人格/记忆），作为系统上下文注入每次对话。
默认位置：<workspace>/SOUL.md（或 templates/SOUL.md 作为备选）。

当 SOUL 文件发生变化或执行 reload 时，下一次回复的元数据会标记 soul_changed=true（日志可追踪版本）。

Skills 是“教模型如何用工具”的指令文档，与可执行 Tool/Command 分离。
每个 skill 是一个目录，包含 SKILL.md，支持 YAML frontmatter：

---
name: DingTalk Sender
description: How to send message to DingTalk
skillKey: skill-dingtalk
tags: [dingtalk, webhook]
tools: [dingtalk_send]
requires:
  env: [DINGTALK_WEBHOOK_URL]
---
这里是 Markdown 指令内容

字段说明：

• skillKey: 可选，默认目录名；也可放在 metadata.skillKey
• tags: 用于关键词匹配
• tools: 关联可执行工具名（可选）
• requires: 依赖校验（env/connectors）

加载顺序与优先级：workspace > managed > bundled（同 key 取最高优先级）

• Bundled：<repo>/bundled_skills/*
• Managed：~/.yourbot/skills/*
• Workspace：<workspace>/skills/*

通过 .env 配置（支持嵌套字段，__ 分隔）：

SKILLS__ALLOW_BUNDLED=true
SKILLS__LOAD__WATCH=false
SKILLS__LOAD__EXTRA_DIRS=./extra_skills

单个 skill 入口配置：

SKILLS__ENTRIES__skill-dingtalk__ENABLED=false
SKILLS__ENTRIES__skill-dingtalk__ENV__DINGTALK_WEBHOOK_URL=...

• SKILLS__LOAD__WATCH=true 开启轮询监听
• HTTP：
  • POST /admin/reload/skills
  • POST /admin/reload/soul
• 管理接口默认仅允许 localhost；如设置 ADMIN_TOKEN，需携带 x-admin-token

CLI 示例：

python -m app.cli skills list
python -m app.cli skills reload
python -m app.cli soul show
python -m app.cli soul reload

不要在 SKILL.md 中写真实 secret，使用环境变量或 secretRef 占位字段。

所有聊天统一走 WebSocket /ws，协议版本 EasyBotWS/1.0。
消息类型可扩展：chat.message / chat.reply / error。

内置 run_code_sandbox 工具，默认用 Docker 镜像执行 Python 代码（禁网、限资源）。
配置：

SANDBOX_DOCKER_IMAGE=python:3.11-slim
SANDBOX_TIMEOUT_SECONDS=10
SANDBOX_MEMORY_MB=256
SANDBOX_CPU_QUOTA=0.5
SANDBOX_NETWORK_ENABLED=false

提示：需要宿主机已安装并运行 Docker。

支持 computer_use 工具（OpenAI computer-use-preview），用于让模型操作浏览器。
依赖 Playwright（可选安装）：

pip install -e .[browser]
python -m playwright install chromium

启用配置：

ENABLE_COMPUTER_USE=true
OPENAI_API_KEY=...
COMPUTER_USE_MODEL=computer-use-preview
COMPUTER_USE_MAX_STEPS=20
COMPUTER_USE_ALLOW_DOMAINS=example.com,openai.com

支持 OpenAI / Gemini / Ollama / DashScope（OpenAI 兼容模式）。\n

• OpenAI:

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini
OPENAI_API_KEY=...

• Gemini:

LLM_PROVIDER=gemini
LLM_MODEL=gemini-1.5-flash
GEMINI_API_KEY=...

• Ollama:

LLM_PROVIDER=ollama
LLM_MODEL=llama3
OLLAMA_BASE_URL=http://127.0.0.1:11434

• DashScope:

LLM_PROVIDER=dashscope
LLM_MODEL=qwen-plus
DASHSCOPE_API_KEY=...

可作为聊天入口（官方群/频道），支持 allowlist：

pip install qq-botpy

ENABLE_QQ=true
QQ_APP_ID=...
QQ_TOKEN=...
QQ_SECRET=...
QQ_ALLOW_USERS=123,456
QQ_ALLOW_GROUPS=789

说明：官方机器人不能添加好友私聊，只能在频道/群内互动。

支持加载自定义 connector 模块（用于你自建方案）。
模块必须提供 get_connector() 返回实现 ConnectorPort 的实例。
注意：本项目不提供任何非官方协议实现（如 NapCat），请自行承担合规与安全风险。
配置：

ENABLE_CUSTOM_CONNECTORS=true
CONNECTORS_EXTRA_MODULES=your_pkg.your_connector

• 作为工具调用：feishu_send 技能。
• 启用：

FEISHU_APP_ID=...
FEISHU_APP_SECRET=...

• 仅需 Webhook 发送消息，注意频率限制与安全设置（签名）。
• 启用：

DINGTALK_WEBHOOK_URL=...
DINGTALK_SIGN_SECRET=...
DINGTALK_RATE_LIMIT_PER_MIN=20

• 基础 Host：https://api.meeting.qq.com
• MVP 实现 create_meeting。
• 启用：

TENCENT_MEETING_APP_ID=...
TENCENT_MEETING_SDK_ID=...
TENCENT_MEETING_SECRET=...

• 仅提供 placeholder skill 与配置项：

CAPCUT_APP_ID=...
CAPCUT_APP_SECRET=...

• 后续可实现 CapCutAdapter + CapCutSkill，遵循统一 Skill 规范。

app/
  core/              # Domain models + Ports
  runtime/           # router / planner / executor / runtime
  connectors/        # qq_botpy / feishu / mock
  skills/            # dingtalk_send / tencent_meeting_create / echo / help
  storage/           # sqlite adapter
  security/          # pairing / allowlist / rate limit
  config/            # settings
  cli/               # approve / revoke / doctor
  tests/

pytest

• 不要泄露 webhook/token/secret。
• 如需开放私聊，确保 DM_POLICY=open 且 ALLOW_FROM 不为 * 时做白名单控制。
• 钉钉自定义机器人有频率限制，请保持限流配置。