Skip to main content

otter 🦦

Give an agent a computer, and it brings you shells.

轻量级本地通用 AI 助手——能写代码、读写文件、跑命令、查网页、做分析与文档,也处理日常问答。 水獭:自然界"抱着石头敲贝壳"的会用工具的动物,正是"给 agent 一台电脑"的画像。

Python License GUI Models

演示 · 能力 · 架构 · 快速开始 · 路线图

otter 在你的机器上本地运行:一个五拍循环的 Agent 引擎(停止评估 → 请求组装 → 上下文压缩 → 流式调模型 → 工具分岔),配一套为长期工作设计的基础设施——双层记忆、技能沉淀、证据归档、产物交付、中断恢复、费用预算。CLI 与桌面 GUI 同引擎。

当前为本地开发版本,接口与数据格式仍可能调整。

Demo

截图来自真实 Run,非概念稿。

对话与交付

otter 对话页

通用助手身份 · 流式回答 · 📦 产物卡片内联预览

运行历史 / 长期记忆 / 交付物

otter 运行历史页

按会话聚合的历史:完成状态 · 摘要对齐 · 普通/计划模式 · 点击行跳回会话

otter 长期记忆页

双层记忆可视化:Core 常驻注入 · Ordinary 按需读取 · 出处可溯

otter 交付物页

交付物浏览:发布历史 · 内联预览(PDF/图片/代码)· 打开/Finder/VS Code

otter 能做什么

  • 通用助手身份 — 编码、文件、命令、网页、计算、日常问答;实时信息(时间/网页)强制走工具,不凭训练记忆。
  • 多端点接入 — OpenAI 兼容协议(DeepSeek/OpenAI/Qwen/Ollama)+ Anthropic 原生 Messages API(改 base_url 自动切换)。
  • 双层记忆 — Core Memory 常驻注入,Ordinary Memory 建索引按需读取,Run 后反思更新,乐观锁防幻觉写。
  • RAG 向量检索 — 文本分片 + Embedding(任意 OpenAI 兼容端点)+ sqlite-vec 向量列,记忆与文档 QA 双场景混合检索(FTS5 词法 ∪ 向量语义,RRF 融合);未配置 Embedding 自动退纯词法。
  • 子代理两级 — explore 只读探索(上下文隔离,只回传结论);dispatch 可写执行,权限三级(none / whitelist 路径围栏 / full),写盘与主代理同走人工审批(diff 卡片可批可拒,拒绝不落地)。
  • 多角色编排 — orchestrate 一个调用=planner 分解 → worker 并行 fan-out → reviewer 汇聚核对;单 worker 失败不牵连,评审只判不做。
  • 本地 HTTP API — otter --serve(FastAPI):health/会话 CRUD/消息/Run 事件 + POST /api/chat SSE 流式(text_delta/工具事件/final 逐帧推送;断连≠取消,事件与消息全程落库可回看)。
  • 作为库嵌入 — import otter; await otter.build_engine(workspace=...) 三行起引擎,与 CLI 同一条装配路径。
  • 评估体系 — 39 任务固定集(编码/文件/命令/日常/多轮/开放/安全/子代理八类)+ 机器验收 + 回归基线对比 + LLM-judge + 一键 markdown 跑分报告(成功率/token/延迟/工具调用/失败模式分类)。
  • Plan / Act 双模式 — PLAN 只读调查并产出结构化计划,人工采纳后切执行跑。
  • Skill 体系 — 从真实 Run 提炼候选,人工确认转正;运行时 <skills> 注入,skill_read 按需取全文。
  • Evidence 归档 — 工具输出截断前全文入库(sha256),模型可随时回取原文。
  • Artifact 交付 — 文件/报告/PDF 作为可追踪交付物发布,GUI 内联预览+三通道打开;make_pdf 原生生成真 PDF。
  • 安全边界 — 权限审批三层 fail-closed(规则/会话/弹窗)、写盘 diff 确认(同目录一次放行)、可选 Seatbelt 沙箱、二进制魔数校验(防伪造 PDF)。
  • 中断恢复 — Checkpoint 记录中断边界,--resume 续跑;kill -9 也不丢状态。
  • 费用预算 — Run 级预算三段收口:60% 提醒 → 85% 收口 → 100% 硬停;Trace 分账(runs/events)事后可查每分 token 去向。
  • 上下文管理 — tiktoken 事前估算 + 滚动摘要压缩(作用于请求视图,原始历史不动)。
  • MCP 扩展 — stdio MCP Server 接入外部工具,经同一权限/执行/Trace 链路。
  • headless — -p 单任务 + --output-format stream-json NDJSON 流式输出,CI/cron 直接消费。
  • 桌面 GUI — 五页工作台:对话/历史/记忆/交付物/设置,rail 徽标提醒新事件。

量化效果

指标 值 口径
评估成功率 38/39(97%) 39 任务八类固定集,机器验收(文件/命令输出/回答实测),deepseek-v4-flash;唯一失败系评估判据问题而非引擎回归,归因见下注
平均延迟 / 步数 / 工具调用 7.0s / 4.6 步 / 3.8 次 同上,串行单任务;含 4 个多轮任务(平均 2.5 轮跑满)
单任务 token 成本 ~19.8k in / 0.9k out 厂商返回真实用量,非估算
测试 后端 230 用例 + 前端 71 断言,全绿 全离线(pytest + node)
干净安装冒烟 wheel[server] 装 → --serve → health/SSE chat 全通 独立 venv,PyPI 待发布

逐任务明细:evals/report.md。唯一失败任务 code-cli-wordcount 归因:评估判据脆弱——模型执行中自行修改了给定输入样例,验收断言仍按原样例检查导致失配;属任务定义缺陷而非引擎回归,同日已修任务定义(锁输入 + 独立判据)并复跑通过、合并入基线(档案 #53)。教训已沉淀为任务编写规范:验收断言不得依赖可变输入。另注:单轮结果,模型输出存在波动(任务集迭代期间的历史轮次为 88%/96%)。

ablation 机制对照(2026-10-02):同代码同任务集切 OTTER_COMPRESS/OTTER_MEMORY 三组对照——成功率持平(95%),但关压缩组 token in 与延迟各省 13%("压缩不免费"的直接数字);结论是两机制的收益要在长上下文/连续使用场景兑现,当前评估集(单任务平均 ~20k token、独立工作区)只测得出成本测不出收益,任务集补长任务已在计划中。明细:evals/ablation.md。

模型调用统一重试层(2026-10-02):loop/压缩/记忆反思/技能提炼的全部模型调用经 RetryingAdapter 统一包装——瞬态失败(408/429/5xx、连接/超时类)按指数退避重试(1s/2s/4s 三档带 ≤20% 抖动,防雪崩式压端点),4xx 参数/鉴权错不重试直接上抛,重试耗尽转为明确的失败语义而非异常穿透;SDK 内建重试同步关闭,避免两层叠加放大请求数。此前一条 429 就足以让几十步长任务的进度整局丢失,这是补上后的口径。

为什么自研,而不直接用 LangChain / LlamaIndex

不是"造轮子瘾"。agent 的核心竞争力在上下文工程,而框架把这层抽象掉了:

  • 滚动摘要与记忆必须逐层可控 — 什么进 system、何时压缩、保留几条近消息、Core 与 Ordinary 怎么分工,这些决策每个都直接影响任务成败;隔一层"链"抽象就调不动。otter 的请求视图组装、token 预算、双层记忆每一层都是自己的代码,行为可测、可调、可复盘。
  • 长任务可靠性是工程问题不是编排问题 — 中断恢复(Checkpoint)、审批 fail-closed、diff 确认、预算三段收口、Trace 分账,这些是和循环本体同等重要的半壁江山;框架版 agent 在这些位置往往只剩"重试一次"。
  • 验证要对着自己的循环做 — 评估 harness 直接复用引擎的 runs/events 分账数据,拿第三方链路跑分,数字对不上自己的生产行为。
  • 代价也清楚:自己维护 adapter/打包/测试这层"轮子"。对一个单人深用的本地工具,这笔账划算。

如何拼在一起

CLI(REPL / -p / cron)      桌面 GUI(pywebview)
        └──────────┬──────────┘
             AgentLoop(五拍循环)
   停止评估 → 请求组装 → 压缩 → 流式调用 → 工具分岔
        │              │                │
   工具注册表      上下文视图         模型 adapter
   (含 deferred)  (system+记忆+技能   ├─ OpenAI 兼容
        │          +摘要+计划)        └─ Anthropic 原生
        │                                ↓
  权限审批 → diff 确认 → 沙箱 → 执行      usage 记账
        │
  Trace 落库 · Evidence 归档 · Checkpoint · FILE_CHANGED/ARTIFACT 事件

Run 后:记忆反思更新 · Skill 提炼(人工确认才转正)

核心概念

概念 职责
Run 一次任务执行的完整生命周期(事件可回放)
Trace Run 实际发生了什么(模型/工具/审批/压缩全量落库)
Evidence 被截断工具输出的全文归档,可按 sha256 回取
Artifact Run 的可交付产物(文件/PDF),发布进产物面板
Memory Core(常驻事实)+ Ordinary(按需知识)双层记忆
Skill 可复用的任务方法,提炼需人工确认,运行时注入
Checkpoint 中断恢复的边界,--resume 从此续跑
Plan 只读调查后产出的结构化计划,采纳后才执行

快速开始

需要 Python 3.12+;GUI 为可选依赖(macOS 最佳)。

pip install otter-agent          # 从 PyPI(GUI 可选:pip install "otter-agent[gui]")

# 或从源码
git clone https://github.com/Zzz777-coder/otter.git && cd otter
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
cp .env.example .env             # 填入 OTTER_API_KEY
otter                      # 交互 REPL(/init /undo /plan /context 等斜杠命令)
otter --gui                # 桌面 GUI
otter -p "任务描述"         # 单任务模式
otter -p "任务" --plan     # PLAN 只读模式(调查+计划,不写文件)
otter -p "任务" --yes --output-format stream-json   # headless:NDJSON 流式(CI/cron)

支持端点:DeepSeek/OpenAI/Qwen/Ollama 等 OpenAI 兼容协议;Anthropic 原生只需 OTTER_BASE_URL=https://api.anthropic.com。配置项见 .env.example。

评估(固定任务集跑分)

39 个真实任务(编码/文件/命令/日常/多轮/开放/安全/子代理八类),机器验收——不看模型"说没说完",看文件、命令输出与最终回答实测;附回归基线对比(基线过→本次挂即标记回归,可接 CI)与 LLM-judge。单轮基线(deepseek-v4-flash,2026-09-29):成功率 38/39,平均延迟 7.0s,平均工具调用 3.8,单任务平均 ~19.8k input token;唯一失败任务归因见量化效果下注。逐任务明细见 evals/report.md。注:单轮结果,模型输出存在波动(任务集迭代期间的历史轮次为 88%/96%)。

.venv/bin/python evals/run_evals.py            # 一键全跑,报告落 evals/
.venv/bin/python evals/run_evals.py --category coding --limit 3   # 分组/抽样

作为库使用(v0.6 起)

otter 不只是 CLI:核心引擎(执行循环/工具面/持久层/记忆)可以 import otter 嵌进你自己的程序:

import asyncio
import otter

async def main():
    # workspace 显式传入:状态(.otter/ 下 db/记忆/交付物)与文件操作都以它为根
    engine = await otter.build_engine(workspace="/path/to/your/project", yes=True)
    result = await engine.run_task("跑一遍测试并总结失败原因")
    await engine.aclose()

asyncio.run(main())
  • build_engine(workspace=None, config=None, yes=False, connect_mcp=True) → Engine,一条装配路径与 CLI 完全一致;
  • 需要更细的控制时直接用公共 API 面:AgentLoop(执行核心)、Store(持久层)、Config、build_full/build_gate/make_sandbox(工具面/审批/沙箱)、build_adapter(模型接入);
  • HTTP API(otter.api.create_app,FastAPI)与桌面 GUI(otter.gui.launch_gui)为可选层,按需导入。

本地 HTTP API(v0.6 起)

otter --serve               # 127.0.0.1:8765,/docs 交互文档
curl -s localhost:8765/api/health
curl -s localhost:8765/api/conversations
# SSE 流式 chat(断连≠取消,事件与消息全程落库,可经只读端点回看):
curl -N -X POST localhost:8765/api/chat -H 'content-type: application/json' \
     -d '{"prompt":"跑一遍测试并总结失败原因","max_steps":30}'

部署:单人云服务器 + 定时任务

otter 是单用户本地工具(状态在工作区 .otter/ 内);GUI 为桌面壳不支持远程,服务器走 CLI:

# 定时无人值守:系统 cron + headless stream-json(NDJSON 落日志)
15 9 * * * cd ~/myproject && otter -p "跑测试并总结失败原因" \
    --yes --output-format stream-json >> .otter/cron.log 2>&1

部署:Docker(server 模式,无 GUI)

python -m build                                  # 产物在 dist/(镜像从 wheel 装)
docker compose up -d                             # OTTER_API_KEY 经环境变量注入
# 宿主访问 http://127.0.0.1:8765/docs;当前目录挂为工作区(状态在其 .otter/ 下)

容器只跑 server(HTTP API + SSE chat);密钥不进镜像。注意:0.0.0.0 绑定 (--serve-host / 容器默认)会把无鉴权的 API 暴露到网络,只应在受信环境使用。

多人 SaaS(每用户自带 key、Web 访问)不在当前架构内;如需请自行包 HTTP 层并做会话隔离。

开发检查

.venv/bin/python -m pytest tests/ -v    # 后端全离线(230 用例)
node tests/test_web_render.js           # 前端渲染冒烟(71 断言)
# GUI 真机探针(真实窗口 DOM 断言,非目测):
.venv/bin/otter --gui-artifact-probe    # 产物卡片 18 项
.venv/bin/otter --gui-e2e               # 真任务→diff 确认→写盘 8 项

目录结构

otter/
├── otter/
│   ├── loop.py            AgentLoop 五拍循环(核心)
│   ├── engine.py          库形态装配入口(build_engine/Engine)
│   ├── tools/             工具子系统(内置/通用/deferred/权限)
│   ├── models/            adapter 层(OpenAI 兼容 + Anthropic 原生 + 工厂)
│   ├── context/           token 估算 + 滚动摘要压缩
│   ├── memory.py          双层记忆(Core/Ordinary + FTS5)
│   ├── rag.py             RAG:分片 + Embedding + 向量列 + 混合检索 + doc_search
│   ├── subagent.py        子代理:explore 只读 + dispatch 可写(权限三级)
│   ├── orchestrator.py    多角色编排:planner/worker/reviewer + fan-out/join
│   ├── skills.py          Skill 提炼/转正/运行时注入
│   ├── evidence.py        截断前全文归档
│   ├── artifact.py        交付物系统 + make_pdf
│   ├── store.py           事件态持久化(SQLite)
│   ├── api/               本地 HTTP API(FastAPI + SSE 流式 chat)
│   ├── repl.py / __main__.py   CLI(REPL/-p/headless stream-json/--serve)
│   ├── gui.py + web/      桌面 GUI(pywebview + 自写 HTML/CSS/JS)
│   └── replan.py          领域扩展示例(默认关,OTTER_REPLAN=1 开)
├── tests/                 离线测试(后端 pytest 230 + 前端 node 71)
├── evals/                 评估任务集 + harness + 跑分报告
├── Dockerfile / compose.yaml   server 模式部署物
├── playground/            默认工作区(.otter/ 状态在内)
└── docs/assets/           截图

路线图状态

里程碑 内容 状态
M0 Loop 五拍 + bash/read/write + DeepSeek adapter + REPL ✅ 2026-09-19
M1 edit/grep/glob + 滚动摘要 + AGENTS.md + git 自动提交/undo + Plan/Act ✅ 2026-09-22
M2 权限审批 + Seatbelt 沙箱 + Checkpoint/resume + Evidence + headless ✅ 2026-09-22
M3 双层记忆 + repo map + 分层 edit format + deferred 工具 + Run 预算三段 ✅ 2026-09-22
M3.5 diff 预览 + GUI 审批卡片 + 前端冒烟测试 ✅ 2026-09-22
M4 MCP 客户端 + 子代理 + Skill Learning + Artifact + 领域扩展示例 + 打包 ✅ 2026-09-22
M-GUI v7+:pywebview+HTML;2026-09-24 增记忆页/交付物页/rail 徽标 ✅
2026-09-24 Anthropic 原生 adapter · stream-json · Skill 运行时注入 · 身份通用化(通用 AI 助手 + current_time/web_fetch/calculate) ✅
v0.6 2026-09-29 HTTP API+SSE 流式 chat · 库化(build_engine/workspace 显式传参) · 评估体系(26 任务跑分) · 可写子代理(权限三级+路径围栏) · RAG 向量检索(分片+Embedding+混合检索) · 多角色编排(planner/worker/reviewer) · Docker/compose 部署物 · 版本单源 ✅

边界

  • 单用户本地工具,不是公网多租户服务;
  • GUI 桌面壳当前以 macOS 为最佳平台;
  • 屏幕操控(Computer Use)未做,集成优先不自研;
  • Skill 候选提炼后需人工确认,绝不自动转正。

License

MIT(见 LICENSE)。

Metadata

Release files for otter-agent 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for otter-agent 0.6.0
File Size Uploaded Provenance Actions
otter_agent-0.6.0.tar.gz 338.4 kB Without provenance Details for otter_agent-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for otter-agent 0.6.0
File Interpreter ABI Platform Actions
otter_agent-0.6.0-py3-none-any.whl Python 3 none any Details for otter_agent-0.6.0-py3-none-any.whl

Total release size: 621.2 kB

Release files / otter_agent-0.6.0.tar.gz

Download URL otter_agent-0.6.0.tar.gz
Size 338.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8d874b71fa7d2efe708a301941e0fab2f94a1bf65bcc5d488974b5a99c8996a8
BLAKE2b-256 checksum
How to use checksums
0c53080a97bc2f64d2d4f65d2e2d2f0bc6a7bd1c98310401baa77dffc68602f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / otter_agent-0.6.0-py3-none-any.whl

Download URL otter_agent-0.6.0-py3-none-any.whl
Size 282.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
77c3a1f3204d6b2fa32dc90d710b50b2dd812d74af7241a670cc222ba3d284a0
BLAKE2b-256 checksum
How to use checksums
b506624c4fda7f4cb187931328450103539060b4e1e6807b526979436da79a26
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for otter-agent 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page