Osc-7/macchiatoBot

# macchiatoBot English | [中文](README_zh.md) macchiatoBot 是一个具备长期运行能力、高并发和远程控制功能的 LLM agent 框架。daemon 拥有会话、调度、IPC、工具执行、权限、内存以及前端集成；CLI、Feishu、MCP 和自动化任务都通过该共享 runtime 进入。 本仓库目前发布了两个可安装的组件： | 包 | 角色 | 命令 | |---|---|---| | `macchiato-bot` | 用于云端/开发/本地机器人的完整助手 runtime | `macchiato`, `macchiato-daemon`, `macchiato-remote`, `macchiato-dashboard` | | `macchiato-remote` | 用于将一个授权的本地工作区暴露给 bot daemon 的轻量级 worker | `macchiato-remote` | 在代码检出中，根目录下的 `main.py` 和 `automation_daemon.py` 文件是打包入口点周围的轻量级兼容性垫片。 ## Runtime 结构 ``` CLI / Feishu / MCP / automation trigger | v Automation IPC + Core Gateway + task queue | v KernelScheduler + CorePool | v AgentKernel - tool execution - permission checks - path and remote-workspace routing - context compression | v AgentCore - prompt assembly - LLM provider routing - memory recall - tool-calling loop ``` 简而言之：`AgentCore` 负责思考，`AgentKernel` 负责执行，而自动化 daemon 保持长期运行的进程、会话、队列和 IPC 的稳定性。 ### 架构原则 - **Daemon 优先的 runtime**：长期运行的状态属于 `macchiato-daemon` / `automation_daemon.py`，而不是属于各个独立的 CLI 调用。 - **前端适配器保持轻量**：CLI、Feishu、MCP 和自动化任务解析特定通道的输入，然后将工作交给 daemon IPC 或任务队列。 - **推理与执行分离**：`AgentCore` 构建 prompt 并与 LLM 通信；`AgentKernel` 执行工具、检查权限、路由路径并压缩上下文。 - **远程工作区是一种路由模式**：远程模式改变了选定工具的运行位置；它不是第二个 agent 堆栈。 - **发布提交保持小巧**：runtime 架构更改在发布提交处理版本控制和打包之前，会作为常规的功能/修复提交落地。 ### 层级映射 | 层级 | 主要模块 | 负责内容 | 不应负责的内容 | |---|---|---|---| | Frontend | `src/frontend/*`, 根目录垫片 | 通道解析、显示、回调 | Agent 状态，直接工具执行 | | Automation | `src/system/automation/*` | IPC、队列、任务定义、会话注册、调度 | LLM prompt 细节 | | Kernel | `src/system/kernel/*` | 核心池、内核请求、终端 shell、摘要 | Provider 选择细节 | | Agent runtime | `src/agent_core/agent/*`, `src/agent_core/llm/*`, `src/agent_core/context/*` | Agent 循环、prompt、provider、内存/上下文状态 | 前端传输细节 | | Tools | `src/agent_core/tools/*`, `src/system/tools/*`, `src/agent_core/mcp/*` | 工具定义、验证、执行、MCP 代理 | 发布打包 | | Remote worker | `src/macchiato_remote/*`, `src/agent_core/remote/*` | 远程协议、worker 注册、工作区路由 | 完整的 bot daemon 状态 | ### 工具边界 工具通过 registry 暴露给 LLM，但内核仍然是可见性、权限检查、路径授予、本地与远程路由以及大结果处理的权威。这使得 LLM 循环保持简单：它请求工具调用；内核决定如何安全地执行它们。 ### 运行时状态 生成的状态不纳入版本控制： | 路径 | 用途 | |---|---| | `data/` | 持久化应用数据、会话、自动化仓库 | | `logs/` | daemon 和网关日志 | | `.macchiato/` | 本地命令/任务运行时状态 | | `dist/`, `build/`, `*.egg-info/` | 包构建输出 | | `.venv/`, `.pytest_cache/`, `__pycache__/` | 本地开发产物 | 有关更详细的设计说明和贡献位置规则，请参阅 [docs/architecture.md](docs/architecture.md)。 ## 仓库映射 ``` src/ ├── agent_core/ # Agent loop, prompts, memory, LLM providers, core tools ├── system/ │ ├── automation/ # Daemon runtime, IPC, queue, scheduler, repositories │ ├── kernel/ # AgentKernel, KernelScheduler, CorePool, terminal │ └── tools/ # App-level tools and tool registry assembly ├── frontend/ # CLI, Feishu, MCP, Canvas, Shuiyuan adapters ├── macchiato_bot_cli/ # Packaged CLI and daemon entrypoints └── macchiato_remote/ # Remote worker protocol, CLI, runtime packages/macchiato-remote/ └── pyproject.toml # Worker-only PyPI package built from src/macchiato_remote ``` ## 从代码检出快速开始 ``` uv sync --all-groups cp config/config.example.yaml config/config.yaml cp .env.example .env ``` 在 `.env` 中填写 provider 密钥，然后启动 daemon： ``` uv run automation_daemon.py ``` 在另一个终端中，启动一个前端： ``` uv run main.py uv run main.py "schedule a meeting tomorrow at 3pm" uv run feishu_ws_gateway.py ``` `source init.sh` 是可选的。它会运行 `uv sync`，导出 `PYTHONPATH`，并为当前 shell 加载 `.env`。 ## 已安装的命令 安装 `macchiato-bot` 后，请使用： ``` macchiato-daemon macchiato macchiato "schedule a meeting tomorrow at 3pm" macchiato-dashboard macchiato-remote status ``` 默认情况下，`macchiato-dashboard` 监听 `http://127.0.0.1:8765`，用于配置编辑和内核状态/会话操作（生成/取消/终止）。 **公开暴露**：合并到你现有的 Nginx `:80` 站点中（与 `/remote/` 相同）： - `/login` — 登录页面 - `/console/` — Web 控制台 请参阅 [deploy/nginx/README.md](deploy/nginx/README.md)。在 `dashboard_auth.yaml` 中配置白名单；在纯 HTTP 上使用 `secure_cookies: false`。 仪表盘功能 (v1)： - 实时配置编辑器，带有更改统计信息以及备份/还原功能（自动保存也会创建备份） - 内核概览（活跃核心 / 队列 / token 使用量 / 对话轮数） - 会话操作（会话列表、快速选择、切换、清除上下文、生成/取消/终止） - 模型操作（列出可用的 provider 并切换活动模型） CLI 是一个 IPC 客户端。如果 daemon 没有运行，它会直接退出，而不是启动一个私有的 agent 进程。 ## 常用斜杠命令 CLI 和 Feishu 通过 daemon IPC 共享相同的斜杠命令界面： - `/help` - `/model`, `/model list`, `/model ` - `/session`, `/session whoami`, `/session list` - `/session new [id]`, `/session switch `, `/session delete ` - `/remote-use [path]` - `/remote-status` - `/remote-release` 或 `/cloud-use` ## 远程工作区 远程工作区模式允许云端托管的 daemon 在另一台机器上经用户授权的文件夹中进行操作。完整的 bot 保留在 daemon 主机上；本地机器仅运行 `macchiato-remote`，它为该授权的工作区暴露 bash/文件能力。 请阅读 [docs/remote-workspace.md](docs/remote-workspace.md) 中的设置、登录模式、权限配置文件和故障排除说明。 ## 配置 主配置文件位于 `config/config.yaml`；从 `config/config.example.yaml` 开始。Provider 片段位于 `config/llm/providers.d/*.yaml` 下。 重要区域： | 键 | 用途 | |---|---| | `llm.*` | 活跃 provider、视觉 provider、provider 片段、请求默认值 | | `agent.*` | 迭代限制、子 agent 上限、工作集大小 | | `tools.*` | 核心工具暴露和基于模板的工具集 | | `memory.*` | 工作内存、召回策略、持久化内存 | | `automation.jobs` | 由 daemon 管理的计划任务 | | `command_tools.*` | Bash 启用、工作区隔离、可写根目录 | | `file_tools.*` | 文件读/写/修改控制 | | `mcp.*` | 外部 MCP 服务器配置 | | `feishu.*` | Feishu 应用和网关设置 | ## 开发 ``` uv sync --all-groups uv run pytest tests/ -v --tb=short black --check src/ tests/ isort --check-only src/ tests/ ``` 专题文档： - [架构](docs/architecture.md) - [远程工作区](docs/remote-workspace.md) - [Feishu 集成](docs/feishu.md) - [部署 / systemd](deploy/README.md) - [发布流程](deploy/RELEASING.md) - [开发指南](AGENTS.md) ## 许可证 MIT

标签：LLM Agent, SOC Prime, 人工智能, 任务调度, 多智能体框架, 并发架构, 开发工具, 用户模式Hook绕过, 逆向工具