🧠 merco - Mercury Code

Mer(cury) + Co(de) = 默客 - 一个轻量、可拓展的 AI 编程助手，跑在你的终端里。

pip install merco && merco 就能开始。没有 Docker、没有数据库依赖--架构就是一个 Agent 循环 + 插件系统，你需要的功能全是你自己选的插件。

🪶 轻量

pip install merco       # 安装
merco setup             # 首次运行交互引导（选平台 / 填 Key / 选模型）
merco                   # 启动 REPL

一条命令安装，一条命令启动。配置文件可选--OPENAI_API_KEY 或 OPENROUTER_API_KEY 环境变量就够。底层 Python 3.12+ 原生 asyncio，uv 构建。

🔌 插件拓展

所有子系统都是插件。 8 个内置插件全部通过 pyproject.toml 的 entry_points 动态发现，零硬编码--关掉任何一个、用自己的替代、或注册全新的都行。

from merco.plugins.base import Plugin, PluginContext

class MyPlugin(Plugin):
    name = "my_plugin"
    priority = 50                    # 越大越早激活（默认 50）
    version = "1.0.0"

    async def activate(self, ctx: PluginContext) -> None:
        # ctx 暴露 20+ 子系统引用 + 一组便捷方法
        ctx.hooks.on("agent.start", self._on_start)        # 订阅事件
        ctx.register_tool(MyTool())                        # 注册工具
        ctx.register_model_provider(MyProviderInfo)         # 注入你的模型
        ctx.register_gateway(TelegramGateway())             # 注入你的网关
        ctx.add_processor("result_pipeline", MyProcessor()) # 接管管线

内置插件（按激活顺序）：

三行装上你自己的：

# 在你的 pyproject.toml 里：
[project.entry-points."merco.plugins"]
my_plugin = "my_package.my_plugin:MyPlugin"

安装即被发现。也支持目录扫描（扔一个 plugin.toml 到 ~/.config/merco/plugins/）和 merco.json 的 plugins 字段切 enabled / 传自定义 config。

扩展点速查：

🏗️ 架构一览

• 入口层 — CLI（merco REPL）/ Webhook（内置 FastAPI，port=0 自动分配）/ Cron（SchedulerPlugin 定时任务）/ Custom（你的 GatewayAdapter）。全部经 handle_inbound() 进 Runtime。
• AgentRuntime — 统一生命周期。start() 触发插件两阶段激活 + gateway/scheduler 启动；stop() 幂等收尾。
• Agent Loop — 一次 turn-loop：组装上下文 → 调 Models → 执行 Tool Calls → 写 Memory → 通过 Hooks 发事件 → 回结果。
• Models — ModelProvider ABC + ModelRegistry 唯一真源。内置 OpenAI / Anthropic / 任意 OAI-兼容端点（填 base_url）。select() 独占凭证解析，Loop 不感知 api_key。
• Tools — bash / file / edit / web / MCP / skill / task。Loop 通过统一协议调度，插件可经 ctx.register_tool 替换或新增。
• Memory — SessionStore（SQLite WAL）+ HybridRecaller（FTS5 + JSON）。Loop 写消息、读召回、自动压缩超长上下文。
• Hooks — 15+ 生命周期事件的 HookRegistry。Scheduler 订阅 conversation.turn 触发 cron、Gateway 订阅 inbound、MCP 订阅 tool.before_execute、Observability 订阅全部。Loop 不直接调 plugin，只发事件。

⚙️ 配置

最小即可跑（其余字段均有合理默认值）：

{"model": {"provider": "openai", "model": "gpt-4", "api_key": "sk-..."}}

{
  "username": "user",
  "model": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key": null,
    "base_url": null,
    "temperature": 0.7,
    "max_tokens": 4096,
    "extra_params": {},
    "headers": {},
    "request_cooldown": 0.3,
    "fallbacks": [
      {
        "provider": "anthropic",
        "model": "anthropic/claude-sonnet-4",
        "temperature": 0.7,
        "max_tokens": 4096
      }
    ]
  },

  "max_tool_calls": 50,
  "max_input_tokens": 64000,
  "compression_threshold": 0.75,

  "streaming": {
    "enabled": false,
    "think": true,
    "content": true,
    "think_transient": false,
    "render_interval": 0.05
  },

  "skills_paths": ["./.merco/skills", "~/.config/merco/skills"],
  "plugins_paths": ["./.merco/plugins", "~/.config/merco/plugins"],

  "memory": {
    "enabled": true,
    "path": "~/.merco/memory",
    "backend": "json",
    "recall_enabled": true,
    "recall_limit": 3,
    "recall_max_chars": 300
  },

  "session": {"fork_enabled": true, "fork_auto_on_compress": true},
  "sandbox_mode": "ask",
  "diff_view": "unified",
  "mcp_servers": {},
  "log_level": "INFO"
}

📋 更多

merco/
├── agents/         # AgentProfile + SubAgentManager
├── cli/            # REPL 入口（main, commands, registry, input_driver, interrupt）
├── core/           # Agent 循环 + LLM + Runtime + Config + Session
│   ├── agent.py        # turn-loop
│   ├── runtime.py      # AgentRuntime（start/stop/submit/handle_inbound）
│   ├── llm/            # ModelProvider ABC + ModelRegistry + 双 provider
│   └── pipeline.py     # RecoveryPipeline / ResultPipeline
├── gateway/        # GatewayAdapter ABC + GatewayRegistry + WebhookGateway
├── hooks/          # HookRegistry（15+ 事件）
├── mcp/            # MCP 客户端（manager / config / tool）
├── memory/         # MemoryStore + HybridRecaller + SessionStore (SQLite WAL)
├── observability/  # Observer / metrics / audit
├── plugins/        # 插件系统（base / discovery / manager / builtin/）
├── sandbox/        # ToolGuard / SecurityChecker / Snapshot
├── scheduler/      # CronScheduler
├── skills/         # SkillLoader + 内置 SKILL.md
├── tools/          # Bash / File / Web / MCP / Skill / Task / Edit
├── todo/           # TodoManager
└── utils/          # 通用工具

📖 文档

• 模块状态总览 -> docs/project-vision/references/architecture.md
• 项目进展与决策记录 -> docs/project-vision/references/progress.md
• 下一个投入方向 -> docs/project-vision/references/next-focus.md

📄 许可证

MIT