内容
# 🦞 龙虾
一款快速的、**单二进制文件**的个人 AI 助手 — Go语言编写，**零外部依赖**（仅标准库）。设计为核心小巧、**分层扩展** — 您自己的 LLM 提供商、技能、MCP 服务器 — 不受任何供应商限制。
龙虾连接聊天（Telegram）到 LLM，具有**原生工具调用**，在您的机器上运行真正的工具，并允许您**在任务中途进行调整**：您在它工作时发送的消息会立即被折叠，因此“不，换一种方式”会在它提交到错误路径之前生效。
> ⚠️ 龙虾有一个 `shell` 工具 — 任何可以给机器人发消息的人都可以在您的机器上运行命令。<br>
> 默认情况下，它**锁定到您的聊天 ID**；请保持这种状态。
## 三种运行方式
```sh
lobster # Telegram 机器人
lobster tui # 全屏终端聊天 — 相同的代理，无需 Telegram
lobster do "..." # 一次性 CLI：运行提示，打印答案，退出（管道有效：
# git diff | lobster do "review this"）
```
## 命令
在 Telegram 和 TUI 中均可使用：
| | |
|---|---|
| `/start` | 认识机器人，获取您的聊天 ID |
| `/setup` | 调整机器人与您的协作方式 |
| `/model` | 列出/切换模型 |
| `/goal <目标>` | 固定目标 — 代理继续工作，自动继续，直到它标记完成（`/goal clear` 停止） |
| `/workflow [名称]` | 运行已保存的多步骤工作流程（无名称 = 列出它们） |
| `/skills` | 列出已安装的技能 |
| `/sessions` | 浏览过去的对话 |
| `/schedules` | 列出已调度任务 |
| `/mcp` | 显示已连接的 MCP 服务器 |
| `/help` · `/id` · `/reset` | 帮助 · 您的聊天 ID · 新对话 |
或者直接与它对话 — 它有真正的工具并会使用它们。
## 为什么选择龙虾
- **可调整** — 在运行过程中中断和重定向代理，无需破坏它（在 Telegram 和 TUI 中均有效：只需在它工作时输入）。
- **主机上的真实工具** — `shell`（PowerShell 或 bash）、文件 I/O（`read_file`、`write_file`、`edit_file`）、后台作业。默认无限原因-动作步骤；它可以处理大型任务。
- **多代理编排** — `spawn_agents` 将大任务分配给并行子代理，每个子代理都有自己的新鲜上下文和完整的工具集。
- **目标模式** — `/goal` 固定目标；代理自动继续，直到它可验证地完成（`goal_done`）或真正需要您。
- **工作流程** — 已保存的多步骤工作流程（`~/.lobster/workflows/*.md`）；在任何时候都可以重放一个，使用 `/workflow <名称>`，或者要求代理将过程保存为一个。
- **提供者无关** — 任何 OpenAI- 或 Anthropic-兼容的端点；无需供应商锁定。
- **可扩展** — 插入[技能](#技能)和[MCP 服务器](#mcp)；它甚至可以在运行时添加它们。
- **记住您** — 持久事实加上每个对话的可搜索存档。
- **无依赖和单二进制** — `go build`，复制它到任何地方，运行。
## 安装
一行命令 — 获取您平台的预构建二进制文件（如果存在 Go，则回退到从源代码构建）：
```sh
# macOS / Linux
curl -fsSL https://yutugyutugyutug.com/install | sh
```
```powershell
# Windows (PowerShell)
irm https://yutugyutugyutug.com/install.ps1 | iex
```
<sub>（直接，无域名：`…/install.sh` → `https://raw.githubusercontent.com/aasm3535/lobster/main/install.sh`。）</sub>
然后：
```sh
lobster setup # 交互式向导（令牌，提供者，...）
lobster tui # ... 或 `lobster` 运行 Telegram 机器人
```
### 从源代码构建
需要 **Go 1.26+**。
```sh
go build -o lobster ./cmd/lobster # Windows: -o lobster.exe
./lobster setup
```
（手动配置：`cp lobster.example.json lobster.json`，填写，然后 `./lobster -config lobster.json`。）
然后给您的机器人发送消息并发送 `/start`；它会回复您的聊天 ID — 将其添加到 `auth.allowed_chats` 并重启。
## 提供者
与 **任何 OpenAI- 或 Anthropic-兼容的 API** 配合使用。通过 `type` 选择线路协议，将 `base_url` 指向端点，然后设置身份验证 — 就是这样，没有供应商特定的代码。`auth_scheme` 放置密钥（`bearer` → `Authorization: Bearer`，`x-api-key` 或 `none`）；`headers` 添加任何额外的。
```json
"provider": {
"type": "anthropic",
"base_url": "https://your-endpoint/...",
"api_key": "${LOBSTER_API_KEY}",
"model": "your-model",
"auth_scheme": "bearer"
}
```
`type` 是 `openai` 或 `anthropic`（两种协议）；`minimax` 是一个便捷的预设（Anthropic 协议 + Bearer）。示例：OpenAI (`https://api.openai.com/v1`)，Anthropic (`https://api.anthropic.com`)，或任何兼容的网关/本地服务器。
**多个模型：** 代替单个 `provider`，使用 `models` 列表 — 每个条目都是一个命名的提供者预设 — 并在运行时使用 **`/model`** 在它们之间切换（选择是每个聊天的，会话被保留）：
```json
"models": [
{ "name": "gpt", "type": "openai", "base_url": "https://api.openai.com/v1", "api_key": "${OPENAI_API_KEY}", "model": "gpt-4o-mini" },
{ "name": "claude", "type": "anthropic", "base_url": "https://api.anthropic.com", "api_key": "${ANTHROPIC_API_KEY}", "model": "claude-3-5-sonnet-latest" }
]
```
## 机密（`.env`）
将密钥保存在 `lobster.json` 之外。将其放在 **`~/.lobster/.env`**（`KEY=VALUE`，参见 [`lobster.env.example`](lobster.env.example)）。它们被加载到环境中，因此您可以在配置文件中以 `${NAME}` 引用它们，**MCP 服务器子进程会自动继承它们**。实际环境变量优先于文件。
## 技能
支持 [Agent 技能](https://www.anthropic.com/news/skills)：一个文件夹，包含一个 `SKILL.md`（名称 + 描述 + 说明）以及可选的脚本，位于 `~/.lobster/skills/` 下。模型仅在相关时看到技能的名称/描述，然后加载其余部分。要求龙虾为 X 创建技能，它会自己编写一个。
## MCP
支持 [MCP](https://modelcontextprotocol.io) 服务器（stdio）— 它们的工具与原生工具一起出现在模型中：
```json
"mcp": { "servers": [ { "name": "fs", "command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] } ] }
```
`/mcp` 列出已连接的服务器。代理也可以在运行时添加服务器。
## 记忆和个性
状态存储在 `~/.lobster/`：代理保存的关于您的持久**事实**，一个滚动对话窗口，以及一个永久的**可搜索会话存档**（`search_sessions`，`/sessions`）。它具有个性，并通过 `/setup` （语气，详细程度，您使用的技术）适应您。使用配置中的 `system` 字段完全覆盖个性。
## 访问控制
默认锁定 — 只有 `auth.allowed_chats` 中的聊天 ID 才能访问模型。`access_code` 是一个可选的共享密钥解锁；`open: true` 禁用门控（仅限本地开发）。
*（更流畅的一键式 onboarding 正在 [路线图](#路线图) 上。）*
## 配置
`lobster.json`（参见 [`lobster.example.json`](lobster.example.json)）；任何值都可以使用 `${ENV_VAR}`：
| 键 | 含义 |
|-----|---------|
| `telegram.token` | 来自 [@BotFather](https://t.me/BotFather) 的机器人令牌 |
| `provider` | `type`、`base_url`、`api_key`、`model`、`max_tokens`、`auth_scheme`、`headers` |
| `auth` | `allowed_chats`、`access_code`、`open` |
| `mcp.servers` | `{ name, command, args, env, disabled }` |
| `system` | 覆盖个性（空 = 内置） |
| `verbosity` | `quiet` · `normal` · `verbose` |
| `max_steps` | 原因-动作上限（默认 `-1` = 无限制，全自治） |
| `workflows_dir` | 已保存的工作流程（默认 `~/.lobster/workflows`） |
## 架构
```
cmd/lobster 入口点
internal/config JSON 配置 + 环境/.env + ${VAR}
internal/llm 提供者无关的聊天（OpenAI / Anthropic 协议）
internal/tools 原生工具注册表 + 内置工具（shell，文件）
internal/agent 可中断的原因-动作循环，每轮动态提示
internal/channel 通道接口 + Telegram 实现
internal/memory 持久事实 + 首选项
internal/history 滚动记录（实时上下文窗口）
internal/session 永久，可搜索的对话存档
internal/skills 代理技能（SKILL.md）
internal/workflows 已保存的多步骤工作流程（/workflow）
internal/scheduler 自我调度（代理唤醒自己）
internal/mcp MCP 客户端（JSON-RPC via stdio）
internal/bgproc 后台命令管理器
internal/setup 交互式首次运行向导
internal/gateway 接线：每个聊天代理/工具，身份验证，目标模式，编排，
Telegram 渲染器 + 终端 TUI/CLI
```
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。保持**无依赖**；在 PR 之前运行 `go build ./... && go vet ./... && go test ./...`。
## 路线图
- **一键式 onboarding** — 在后台运行它；机器人为您提供一个单独的命令，粘贴到您的终端中，自动为您开启白名单。围绕此重构访问控制。
- 除了 Telegram 之外的更多通道。
- 记忆：矢量回忆，总结压缩。
- MCP：HTTP/SSE 传输，资源和提示。
## 许可证
[MIT](LICENSE)。
