# LamA - Lambda Agent

**Repository Path**: zqhcoding/lama

## Basic Information

- **Project Name**: LamA - Lambda Agent
- **Description**: A react agent powered by Λ-Lang
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LamA — Lambda Agent

```
  ░█▓░░     Λ-gent
  █▒░█▒     <model> · <provider>
  █▒░█▒     <cwd>
```

LamA 是一个基于 [Λ-Lang](https://gitee.com/zqhcoding/alang) 的 **ReAct 风格**终端 AI 代理，支持多 LLM 提供商、9 个内置工具、16 种 TUI 组件和安全的沙箱执行。

## 特性

- **ReAct 循环** — Thought → Action → Observation → finish，可配置最大步数
- **多 LLM 提供商** — OpenAI 兼容 API、Ollama（自动识别 `/v1/chat/completions`）
- **9 个内置工具** — Bash、Read、Write、Edit、EditSearchReplace、Glob、Grep、WebFetch、WebSearch
- **安全优先** — SSRF 防护（拦截私有 IP）、预批准域名/文件/命令、破坏操作需用户确认
- **计划模式**（`/plan`）— 只读模式，仅允许 Read、Glob、Grep
- **配置系统** — 优先级：环境变量 `LAMA_CONFIG_PATH` > 项目 `.lama.json` > 全局 `~/.config/lama/lama.json`
- **丰富 TUI** — 16 种组件（Markdown、代码高亮、表格、滚动框、多行输入等），支持语法高亮和斜杠命令弹出菜单
- **Web UI** — 内置 HTTP 服务器，支持 SSE 实时流、CLI+浏览器同步交互、聊天专用组件渲染
- **17 个斜杠命令** — `/cache`、`/clear`、`/compact`、`/diff`、`/exit`、`/help`、`/history`、`/init`、`/model`、`/new`、`/plan`、`/rename`、`/resume`、`/retry`、`/status`、`/strategy`、`/undo`
- **多模型策略系统** — 11 种可插拔策略通过 `strategy_mgr.al` 路由：`basic`（单模型，默认）、`serial_failover`（有序故障转移）、`dual_backup`（主 + 显式备用）、`ensemble_vote`（并行投票）、`reviewer`（生成+审核+优化）、`task_router`（分类路由）、`speculative_race`（快速模型竞速）、`consensus_check`（Jaccard 一致性检测）、`refine_chain`（草稿→优化→润色流水线）、`cost_cascade`（低成本→高质量升级）、`moa`（模型混合，分层聚合）。运行时通过 `/strategy` 切换或在 `config.multiModel` 中配置
- **上下文窗口管理** — 近似 token 计数（字符数/4 启发式），当使用量超过 `compactThreshold`% 的 `contextWindow` 时自动压缩，支持模型特定上下文限制
- **OpenCode 插件模式**（`--opencode`）— 作为子进程与 OpenCode IDE 集成；统一 `/opencode-hook` V1 事件端点支持 50+ 钩子类型，Web UI 中结构化事件卡片渲染，自动允许权限，Shell 环境变量注入
- **会话持久化** — 基于哈希的会话 ID，存储于 `~/.config/lama/sessions/<id>.json`，支持保存/加载/列表/删除
- **客户端响应缓存** — LRU 文件缓存（200 条，1 小时 TTL），djb2 哈希键，减少重复 LLM 调用
- **服务端缓存追踪** — OpenAI `cached_tokens` 和 Anthropic `cache_*` 统计数据
- **Token 用量追踪** — 每次会话的提示/补全/请求数追踪，通过 `/status` 查看
- **对话压缩**（`/compact`）— 利用 LLM 将对话摘要为 3 条消息
- **AGENTS.md 生成**（`/init`）— 通过探索代码库自动创建项目指南
- **交互式模型切换**（`/model`）— 键盘导航弹出窗口切换提供商/模型
- **多引擎网页搜索** — 备用链：Bing CN → 360 → Sogou，纯 A-Lang 实现，支持域名过滤
- **HTML 转 Markdown** — 纯 A-Lang 实现的 WebFetch 结果转换器
- **增强旋转动画** — 显示推理步骤序号、总步数和已用时间，并在长时间输出中实现逐行渐显效果
- **键盘中断** — 按 Ctrl-C 或 ESC 可干净地取消正在进行的代理回合
- **SEARCH/REPLACE 差异编辑** — 支持多行上下文的精确编辑工具，输出变更摘要（`+X -Y 行`），适用于精确代码修改
- **Git 集成** — `/diff` 命令显示工作区变更；每次工具调用后自动显示 Git 变更作为观察结果
- **Markdown 渲染** — 助手输出支持语法高亮的代码块、标题样式和内联格式（加粗、斜体、行内代码）
- **结构化日志** — 内置 `logging` 模块，支持层级 Logger、文件/终端输出、可配级别（DEBUG→CRITICAL），关键代理流程全覆盖 DEBUG/INFO/WARNING/ERROR
- **调试日志** — 设置 `LAMA_DEBUG=true` 环境变量可记录完整 LLM 事务到 `~/.config/lama/transaction.json`
- **首次运行自动配置** — 首次启动自动生成默认 `.lama.json`
- **24-bit 真彩色** — 全 UI 使用 RGB 语义调色板

## 使用示例

![LamA Demo](docs/lama_demo_v0.1.png)

## 快速开始

```bash
./lama
```

配置文件路径（按优先级从低到高，首个存在的生效）：

| 优先级 | 范围 | 路径 |
|--------|------|------|
| 1 | 环境 | `LAMA_CONFIG_PATH` 环境变量 |
| 2 | 项目 | 当前目录下的 `.lama.json` |
| 3 | 全局 | Linux: `~/.config/lama/lama.json` |
| 3 | 全局 | macOS: `~/.config/lama/lama.json` 或 `~/Library/Application Support/lama/lama.json` |
| 3 | 全局 | Windows: `%APPDATA%/lama/lama.json` |

完整配置示例：

```json
{
  "defaultProvider": "ollama",
  "defaultModel": "qwen3:8b",
  "temperature": 0.0,
  "topP": 1.0,
  "maxTokens": 8192,
  "stop": ["Observation:"],
  "maxSteps": 15,
  "systemPrompt": "",
  "contextWindow": 32000,
  "compactThreshold": 75,
  "multiModel": {
    "strategy": "basic"
  },
  "logging": {
    "enabled": false,
    "file": "/tmp/lama.log",
    "level": "DEBUG"
  },
  "providers": {
    "ollama": {
      "type": "ollama",
      "baseURL": "http://localhost:11434",
      "models": {
        "qwen3:8b": { "name": "qwen3:8b", "contextWindow": 32768 }
      }
    },
    "xxx": {
      "type": "openai",
      "baseURL": "http://xxx.xxx/v1",
      "apiKey": "sk-xxx-xxx",
      "models": {
        "xxx": { "name": "xxx" }
      }
    }
  }
}
```

### HTTP 服务器 / Web UI

LamA 可以提供 Web UI，镜像所有 CLI 交互能力。CLI 和浏览器保持同步——代理事件同时流向两者。

在配置中添加 `httpServer` 以启用：

```json
{
  "httpServer": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 8321
  }
}
```

**默认值：**
- `enabled`: `false` — 未显式启用时不启动 HTTP 服务器
- `host`: `127.0.0.1` — 仅本机可访问（不对外暴露）
- `port`: `8321`

**使用方法：**

1. 在配置中启用 `httpServer`（`~/.config/lama/lama.json` 或 `.lama.json`）
2. 启动 LamA：`./lama`
3. 在浏览器打开 `http://127.0.0.1:8321`
4. 通过网页输入框交互——功能与 CLI 一致
5. CLI 和浏览器实时同步显示同一对话

**注意事项：**
- HTTP 服务器默认绑定 `127.0.0.1` — 仅本机可访问
- 将 `host` 改为 `0.0.0.0` 会对外暴露（无内置认证，请谨慎使用）
- 网页输入在 CLI 输入间隙处理——不会并发执行代理回合
- SSE 支持自动重连；刷新页面后从 `/state` 端点恢复历史对话

### OpenCode 插件模式

LamA 可以作为 [OpenCode](https://opencode.ai) IDE 的子进程运行，提供完整的 V1 钩子事件可观测性和拦截能力。

```bash
./lama --opencode
```

此模式执行以下操作：
1. 将插件（`plugins/opencode/`）以 `file://` URL 形式注册到 OpenCode 配置中
2. 在后台启动 LamA 的 HTTP 服务器（无头模式，无 TUI）
3. 启动 OpenCode，通过统一 `/opencode-hook` 端点连接到 LamA
4. 在 OpenCode 退出时清理 LamA 子进程

**架构：**

- **统一钩子端点**（`POST /opencode-hook`）— 所有 50+ 种 V1 事件类型通过单一端点传输；钩子携带观察数据或可变输出用于拦截
- **拦截钩子** — LamA 可修改 OpenCode 行为：自动允许 `permission.ask`、注入 `shell.env` 覆盖、修改 `chat.params`/`chat.headers`/`chat.message` 负载
- **流式文本缓冲区** — `message.part.delta` 事件被累积并在安全超时（3 秒）后刷新，实现实时渲染
- **结构化 Web UI** — OpenCode 事件以可折叠卡片形式呈现，具有类型特定样式（工具调用、命令、文件变更、权限、LSP 诊断、会话生命周期）
- **丰富事件路由** — `runner.OnOpenCodeEvent()` 将 50+ 种钩子类型映射到 LamA 事件系统：工具调用 → Action/Observation 事件、错误 → Error 事件、会话生命周期 → Thought 徽章

**配置：**

插件由 `lama --opencode` 包装脚本自动注册，无需手动设置。

**注意事项：**
- `lama --opencode` 自动启动 HTTP 服务器；无需设置标准的 `httpServer` 配置
- OpenCode 插件（`plugins/opencode/index.js`）是标准的 OpenCode V1 插件，通过 `file://` URL 加载
- `/opencode-hook` 请求有 5 秒超时；失败时优雅处理（输出保持不变）

### 结构化日志

LamA 内置结构化日志模块（`stdlib/logging.al`），覆盖所有关键代理流程，按严重程度分级：

| 级别 | 关键事件 |
|------|----------|
| `INFO` | AgentTurn 开始/结束、LLM API 调用、工具调度、会话保存/加载、命令调度、Web 输入、SSE 流、配置变更 |
| `WARNING` | 工具超时、HTTP 404、LLM API 重试、配置保存失败、安全限制触发 |
| `ERROR` | LLM 网络/空响应、未捕获异常 |
| `DEBUG` | 步骤执行、SSE 推送、HTTP 轮询、Sink 广播、事件发送 |

**配置：**

```json
{
  "logging": {
    "enabled": true,
    "file": "/tmp/lama.log",
    "level": "DEBUG"
  }
}
```

| 字段 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `enabled` | bool | `false` | 开启/关闭日志输出。关闭时完全静默。 |
| `file` | string | stdout | 日志文件路径。不设置时输出到终端。 |
| `level` | string | `"DEBUG"` | 最低输出级别：`"DEBUG"`、`"INFO"`、`"WARNING"`、`"ERROR"`、`"CRITICAL"` |

**覆盖范围：** 日志覆盖完整的请求生命周期——Web 输入 → 命令调度 → LLM API 调用 → 工具调度 → SSE 推送 → 会话持久化。模块级事件（sink 广播、SSE 流、轮询）记录为 DEBUG 级别。

## 项目结构

```
lama/
├── lama                   # 启动脚本
├── repl.al                # 主 REPL 循环
├── agent/
│   ├── agent_handler.al   # 标准代理模式的 Web 处理器
│   ├── core.al            # ReAct 代理循环
│   ├── commands.al        # 17 个斜杠命令处理器
│   ├── context.al         # 上下文窗口管理与自动压缩
│   ├── llm.al             # LLM API 客户端
│   ├── prompt.al          # 系统提示词组装
│   ├── strategy_mgr.al    # 多模型策略管理器（11 种策略）
│   ├── strategies/        # 策略实现
│   │   ├── base.al        # 策略基类
│   │   ├── basic.al       # 单模型，无故障转移
│   │   ├── serial_failover.al  # 有序模型故障转移
│   │   ├── dual_backup.al      # 主模型 + 显式备用
│   │   ├── ensemble_vote.al    # 并行多模型投票
│   │   ├── reviewer.al         # 生成 + 审核 + 优化
│   │   ├── task_router.al      # 分类路由到最佳模型
│   │   ├── speculative_race.al # 快速模型竞速主模型
│   │   ├── consensus_check.al  # Jaccard 一致性检测
│   │   ├── refine_chain.al     # 草稿 → 优化 → 润色流水线
│   │   ├── cost_cascade.al     # 低成本 → 高质量升级
│   │   └── moa.al              # 模型混合（分层聚合）
│   ├── ui.al              # 终端输出函数（已弃用，改为 shim）
│   ├── sink.al            # 输出 sink 抽象 + Broadcast 注册
│   ├── events.al          # 事件类型常量 + 工厂函数
│   ├── chat_widget.al     # 聊天专用组件类型（ChatMessage、ThinkingIndicator 等）
│   ├── tui_sink.al        # TUI 输出 sink（通过事件进行 ANSI 渲染）
│   ├── http_server/       # Web UI HTTP 服务器模块
│   │   ├── handler.al     # WebHandler 基类（策略模式）
│   │   ├── server.al      # HTTP 处理（SSE + 输入端点）
│   │   ├── sse_sink.al    # SSE 输出 sink（JSON 事件流）
│   │   ├── wakeup.al      # Web 输入唤醒 ReadTextarea
│   │   ├── web_base.al    # 共享基础 HTML/CSS/JS 常量
│   │   └── web.al         # 内嵌 HTML/CSS/JS 字符串常量
│   ├── banner.al          # 启动横幅生成器
│   ├── _config.al         # 多源配置系统
│   ├── session.al         # 会话持久化
│   ├── response_cache.al  # LRU 响应缓存
│   ├── mode.al            # 计划模式单例
│   ├── cmd_list.al        # 命令注册表（用于弹出菜单）
│   ├── usage.al           # Token 用量追踪
│   ├── debug.al           # LLM 事务调试日志
│   ├── status.al          # 旋转动画协程（增强版，含步骤信息）
│   ├── interrupt.al       # 键盘中断监控协程
│   ├── style.al           # 24-bit 调色板与符号
│   ├── prompts/           # 10 个模块化系统提示片段
│   └── tui/               # TUI 组件库（16 种组件）
│       ├── tui.al         # 终端状态管理器
│       ├── input.al       # 多行输入文本框
│       ├── layout_mgr.al  # 布局管理器（滚动缓冲 + 覆盖层）
│       ├── widget.al      # 组件工厂
│       ├── layout.al      # 布局引擎
│       ├── render.al      # ANSI 渲染管线
│       ├── ansi.al        # ANSI 转义码常量
│       ├── style.al       # TUI 样式工具
│       ├── markdown.al    # 基于 Token 的 Markdown 解析器
│       ├── code_tokenizer.al # 代码语法标记器
│       ├── model_select.al   # 交互式模型选择弹出窗口
│       └── TUI_README.md  # TUI 模块文档
├── tools/
│   ├── tools.al           # 9 个工具实现
│   └── _utils/
│       ├── preapproved.al # 预批准域名/文件/命令
│       ├── html_to_md.al  # HTML 转 Markdown 转换器
│       ├── web_search.al  # 多引擎网页搜索
│       └── cache.al       # 通用 LRU 缓存
├── plugins/
│   └── opencode/          # OpenCode V1 插件集成
│       ├── index.js       # V1 钩子定义（50+ 事件类型）
│       ├── package.json   # 插件清单
│       ├── opencode_handler.al  # OpenCode 模式 WebHandler
│       ├── runner.al      # 事件路由 → LamA 事件系统
│       └── web_opencode.al      # 结构化事件卡片 Web UI
├── tests/                 # 43 个测试套件
│   ├── strategies/        # 11 个策略专用测试
│   └── test_*.al          # 32 个模块/集成测试
└── docs/                  # 文档与截图
```

## 斜杠命令

| 命令 | 描述 |
|---------|------|
| `/cache` | 显示缓存统计或清除响应缓存 |
| `/clear` | 清空对话历史 |
| `/compact` | 通过 LLM 压缩对话上下文 |
| `/diff` | 显示工作区 Git 变更差异 |
| `/exit` | 退出程序 |
| `/help` | 显示可用命令 |
| `/history` | 显示对话历史 |
| `/init` | 创建/刷新 AGENTS.md |
| `/model` | 显示或切换当前模型 |
| `/new` | 开始新对话 |
| `/plan` | 切换只读计划模式 |
| `/rename` | 重命名当前会话 |
| `/resume` | 恢复之前的会话 |
| `/retry` | 重试上一个用户查询 |
| `/status` | 显示 Token 用量和状态 |
| `/strategy` | 显示或切换多模型策略 |
| `/undo` | 撤销上一个代理回合 |

## 工具

| 工具 | 描述 | 安全性 |
|------|------|--------|
| Bash | 执行 Shell 命令 | 需 y/N 确认（除非预批准） |
| Read | 读取文件内容 | 无限制 |
| Write | 创建/覆盖文件 | 需 y/N 确认（除非预批准） |
| Edit | 文件中精确替换字符串 | 需 y/N 确认（除非预批准） |
| EditSearchReplace | 多行上下文感知的 SEARCH/REPLACE，输出变更摘要 | 需 y/N 确认（除非预批准） |
| Glob | 按名称模式搜索文件 | 无限制 |
| Grep | 按正则表达式搜索内容 | 无限制 |
| WebFetch | HTTP GET 并转换为 Markdown | SSRF 防护，LRU 缓存 |
| WebSearch | 多引擎网页搜索 | 域名过滤 |

## 许可证

Apache 2.0