Ram the slack agent

Ram 是一个在 Slack 中的 AI 智能体，基于 FastAPI 构建，接入 OpenAI 兼容协议的 LLM。从我的个人使用场景出发，涵盖了搜索、代码、对话的使用场景。

下面是主要功能和特点：

• Agent Loop with Tool。主循环是一个 Agent Loop，装载了 Bash, Code, WebSearch, WebFetch 等工具。
• 搜索功能。Ram 可以使用 tavily 进行网络搜索。
• 代码开发。Ram 内置了 opencode-config 这个工作流，使用 opencode cli 的无头模式进行代码编写。
• 项目管理。Ram 提供项目管理能力，可以将 slack 的频道绑定为项目。改项目为一个代码项目，可以在这个项目中进行代码编写。
• slack 交互和 session 管理。使用 Slack 进行对话管理，每一个 thread 是一个 agent conversation。
• 国内部署友好。部署在阿里云中，可以在 2c2g 的 ecs 中工作。
• 可追踪性。Traceability 提供详细和完整的日志服务和 trace 记录。
  • 提供漂亮的 trace 界面。
  • 提供以 markdown 形式下载 trace 和消息功能。
• 保留 Prompt 历史。本项目由 AI 进行代码编写，在 docs 中记录了每次的 prompt 记录。这些项目同样也是基于 opencode-config

详细功能

Agent Loop

在任意频道或 thread 中 @Ram 即可触发 Agent Loop。LLM 自主决策：调用工具还是直接回复。Thread 历史作为多轮上下文自动传入，中间轮的 LLM 文本通过 on_message 回调实时透传到 Slack。

Web Fetch

Ram 读取任意 URL 并提取正文内容。使用 trafilatura 提取 HTML 正文，失败时降级到 markdownify 转换。

Web Search

Ram 通过 Tavily CLI 进行实时搜索，并可按需抓取搜索结果页面获取更多详情。搜索时自动注入当前日期，确保结果时效性。

Interactive Question

当 Ram 需要用户澄清时，向 Slack thread 发送 Block Kit 按钮。用户可点击选项或直接输入自由文本进行回复。

Bash Tool

在服务器上执行 shell 命令。通过 ~/.ram/config.json 的 bash_allowlist 字段进行命令白名单校验，输出截断至 50KB，支持配置超时时间。每次调用重新读取白名单，支持运行时修改。

Code Tool（OpenCode）

调用 OpenCode CLI 执行 AI 编程任务：

• run 子命令：使用 --format json 无头模式，OpenCodeJsonProxy 后台解析 NDJSON 输出并提取干净文本，自动管理 thread→session 映射。
• pr 子命令：fire-and-forget 模式，不阻塞 Agent Loop。
• 其他子命令：即时执行，等待完成后返回结果。

Code Project（项目绑定）

• 通过 /ram bind <dir> 将 Slack 频道绑定到本地代码目录。
• Ram 在 system prompt 中自动注入项目上下文，并为每个 thread 维护独立的 OpenCode session。
• /ram unbind 解绑，/ram projects 查看所有绑定项目。

Slash Commands

• /ram help — 显示帮助信息
• /ram status — 显示当前服务状态
• /ram bind <dir> — 将当前频道绑定为代码项目
• /ram unbind — 解绑当前频道
• /ram projects — 列出所有已绑定项目

Trace & Management

• 所有 LLM 调用、工具调用、Agent Run 完整写入 SQLite（ram.db），结构为四张表：conversation / agent_run / llm_call / tool_call。
• 独立的 Management 服务（端口 8001）提供只读 API，React SPA Dashboard 支持四级下钻（概览 → 对话列表 → 对话详情 → Agent Run 详情）。
• 支持以 Markdown 格式下载 trace 和消息内容。通过 SSH 隧道访问，不对外暴露端口。

下面是一个 Agent Run 中的截图。

日志服务

日志服务由阿里云的 SLS 提供。本项目的日志已经提供了完整的结构化日志信息。

HTTP 端点

• POST /api/slack/events — Slack Events API
• POST /api/slack/commands — Slash Commands
• POST /api/slack/interactions — Block Kit 交互回调

启动服务后，访问 /docs（Swagger UI）或 /redoc（ReDoc）查看完整接口文档。

项目上下文文件

AGENTS.md

本项目的核心上下文文件，由 AI 在每次功能迭代后自动维护更新，记录了完整的技术栈、质量检查命令、关键约束、实现规则、目录结构、已完成功能列表以及已知限制，是项目的唯一事实来源（Single Source of Truth）。

docs/DEPLOYMENT.md

部署指南，涵盖阿里云 ECS 实例与 OOS 参数仓库的配置流程、RAM 角色最小权限策略、run.sh 一键部署步骤说明、Management 服务的访问方式（SSH 隧道）、Nginx 反向代理配置，以及常见故障排查。

部署

Ram 部署在阿里云 ECS 上（2c2g 实例即可运行）。所有密钥从阿里云 OOS 参数仓库读取，无需 .env 文件。LLM 配置通过 ~/.ram/models.json 管理（参考 models.json.example）。

注意：仓库根目录的 models.json 是一个测试示例（SiliconFlow + Kimi-K2.5），供参考。部署时需根据自己的 LLM provider 和阿里云 OOS 参数名修改。

sudo bash run.sh

脚本自动完成依赖安装、前端构建、环境变量注入和 systemd 服务启动，无需手动配置。

详细步骤请参考 docs/DEPLOYMENT.md。

Local Development

Requirements

• Python 3.12
• A virtual environment at .venv
• opencode CLI in PATH (for Code Tool)
• tvly CLI in PATH (for Web Search tool)

Setup

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
git submodule update --init --recursive

Install pre-commit hooks

.venv/bin/pre-commit install

Run quality checks

# Lint & format
.venv/bin/ruff check src/ tests/ management/api/
.venv/bin/ruff format src/ tests/ management/api/

# Type check
.venv/bin/mypy src/ tests/ management/api/ --no-incremental

# Tests with coverage
.venv/bin/python -m pytest

TODO

如果有时间的话，想要做下面的内容：

• 记忆管理和个性刻画。
• 提升 Agent Loop 的可靠性和工具调用的可靠性。

Reference

• 在实现过程中我主要研究了 OpenCode, MIT License 对于 web_search, web_fetch, bash 的实现。
• 其它参考由 Agent 自行在网上搜索获得，具体的参考和资料均在 docs/plans 中可以获得。