Miniclaw

自托管多渠道开发协作 Agent 系统

Miniclaw 将研发请求、会话状态、模型调用与任务执行组织为可部署的协作服务。团队可以通过 HTTP API、CLI、通用 Webhook 和飞书接入，在自己的基础设施中管理服务、数据和运行配置，并按需连接外部模型与工具。

系统基于 DeepAgents、LangGraph 和 FastAPI，提供代码任务处理、角色协作、持久化会话、异步任务与运行指标。

HTTP / CLI / Webhook / 飞书
            │
     InboundMessage
            │
    会话标识与请求上下文
            │
    Agent + 中间件 + 工具
       │             │
 PostgreSQL      模型服务 / MCP

异步入口 → PostgreSQL 状态表或 Redis / arq → Worker
团队入口 → 五角色协作 → Daytona 沙箱
隔离组件 → DockerSandbox / SandboxPool
运行指标 → Prometheus → Grafana

HTTP 和 Worker 当前使用本地文件后端构建 Agent；团队沙箱入口与 Docker 隔离组件分别提供集成接口。部署时应根据工作负载选择并验证执行路径。

• Python 3.13；依赖使用 uv 或 pip 安装。
• PostgreSQL 与 Redis。
• 可访问的模型服务及 API Key。
• Docker Compose 用于容器部署；团队沙箱入口另需 Daytona 凭证。

在项目根目录准备配置：

cp .env.example .env

填写 SYC_API_KEY 和数据库密码。SYC_PG_PASSWORD、SYC_DATABASE_URL、SYC_POSTGRES_URL 中的密码应一致；连接串中的特殊字符需进行 URL 编码。通过 SYC_API_KEYS 设置 API Key 到租户的 JSON 映射。

启动 API、Worker、数据库和缓存：

docker compose -f docker-compose.prod.yml up -d --build postgres redis web worker

检查服务：

curl http://localhost:18700/healthz
curl http://localhost:18700/readyz

/healthz 检查应用是否响应；/readyz 检查应用是否已挂载连接池，不代表完整依赖探测。

需要飞书时，填写应用凭证，在飞书后台启用机器人和消息事件长连接订阅、发布应用，再启动接收进程：

docker compose -f docker-compose.prod.yml up -d --build feishu

启用监控：

docker compose -f docker-compose.prod.yml up -d prometheus grafana

Grafana 中添加 Prometheus 数据源 http://prometheus:9090 后自行配置看板。

准备可访问的 PostgreSQL 和 Redis，将 .env 的连接地址调整为实际地址：

uv sync
uv run uvicorn api.app:app --reload --port 8000

另一个终端启动队列消费者：

uv run arq tasks.worker.WorkerSettings

Windows 环境下，psycopg 异步连接需要兼容的事件循环；服务部署优先使用 Linux 容器。

提交带鉴权的开发请求：

curl -X POST http://localhost:18700/issues/secure \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_CONFIGURED_KEY" \
  -d '{"issue":"分析订单报价接口的边界条件","user_id":"developer","channel":"api","thread_id":"order-review"}'

CLI 默认连接本机 8000 端口，适用于本地服务：

uv run python main.py --session order-review "分析订单报价接口的边界条件"

提交队列任务：

curl -X POST http://localhost:18700/jobs \
  -H "Content-Type: application/json" \
  -d '{"text":"梳理订单模块的调用关系","user_id":"developer","conversation_id":"order-review"}'

用返回的 job_id 查询 GET /jobs/{job_id}。轻量后台任务使用 POST /tasks 与 GET /tasks/{task_id}。

环境变量沿用 SYC_ 前缀，数据库沿用现有名称，以兼容已有部署。切换产品名称无需迁移数据。

agent/        Agent 构建与团队任务入口
api/          HTTP 路由、契约与应用生命周期
channels/     CLI、飞书、Webhook 和会话处理
subagents/    协作角色与审查结果结构
sandbox/      Daytona / Docker 沙箱与资源管理
tasks/        后台任务、队列与 Worker
tools/        Git、测试及 MCP 工具
skills/       接口开发与测试工作规范
middleware/   请求上下文、审计、成本和并发控制
infra/        配置、数据库、缓存和模型路由
obs/          Prometheus 指标
eval/         模型回答与编码任务评估
app/          订单报价业务
tests/        自动化测试
deploy/       Prometheus 配置
scripts/      服务启动与辅助脚本

• 当前只有 /issues/secure 显式应用 API Key 鉴权，其他任务和通用 Webhook 接口应限制在可信网络或由统一网关鉴权。
• HTTP Agent 的文件写权限受到现有权限规则限制；Git 工具单独执行宿主命令。文件权限规则不等同于命令级隔离。
• 团队入口使用 Daytona，Docker 组件未自动接入 HTTP / Worker 链路；配置 runtime 前需在宿主安装对应运行时。
• 外部检索通过所配置的 MCP 服务扩展；默认工具不提供联网搜索。
• 飞书推荐使用长连接入口；回调模式的完整处理与验签需进一步验证。
• eval/run_eval.py 会调用模型并可能创建沙箱。当前输出评估与退化结果，不自动执行发版阻断。

python -m pytest tests/ -q

修改功能时添加对应测试。上线前验证数据库连接、模型访问、目标渠道、任务状态与实际执行权限，并根据工作负载调整并发和资源配额。

本项目采用 MIT License。