Metadata-Version: 2.4
Name: otter-agent
Version: 0.6.0
Summary: Otter — 轻量本地通用 AI 助手:编码/文件/命令/网页/日常,OpenAI 兼容 + Anthropic 原生,双层记忆与 Skill
Author: Zzz777-coder
License-Expression: MIT
Project-URL: Homepage, https://github.com/Zzz777-coder/otter
Project-URL: Issues, https://github.com/Zzz777-coder/otter/issues
Keywords: agent,coding-agent,cli,llm,deepseek,anthropic,ai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.50
Requires-Dist: aiosqlite>=0.20
Requires-Dist: rich>=13.0
Requires-Dist: mcp>=1.0
Requires-Dist: httpx2>=2
Requires-Dist: tiktoken>=0.7
Requires-Dist: sqlite-vec>=0.1.6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: fastapi>=0.115; extra == "dev"
Provides-Extra: gui
Requires-Dist: pywebview>=5; extra == "gui"
Requires-Dist: pillow>=10; extra == "gui"
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn>=0.30; extra == "server"
Provides-Extra: pdf
Requires-Dist: fpdf2>=2.8; extra == "pdf"
Dynamic: license-file

<div align="center">

# otter 🦦

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

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

![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)
![GUI](https://img.shields.io/badge/GUI-pywebview-47848F)
![Models](https://img.shields.io/badge/Models-OpenAI%E5%85%BC%E5%AE%B9%20%7C%20Anthropic%E5%8E%9F%E7%94%9F-blue)

[演示](#demo) · [能力](#otter-能做什么) · [架构](#如何拼在一起) · [快速开始](#快速开始) · [路线图](#路线图状态)

</div>

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

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

## Demo

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

### 对话与交付

<p align="center">
  <img src="docs/assets/otter-chat.png" width="88%" alt="otter 对话页" />
</p>

<p align="center"><sub>通用助手身份 · 流式回答 · 📦 产物卡片内联预览</sub></p>

<details open>
<summary><strong>运行历史 / 长期记忆 / 交付物</strong></summary>

<p align="center">
  <img src="docs/assets/otter-runs.png" width="88%" alt="otter 运行历史页" />
</p>

<p align="center"><sub>按会话聚合的历史:完成状态 · 摘要对齐 · 普通/计划模式 · 点击行跳回会话</sub></p>

<p align="center">
  <img src="docs/assets/otter-memory.png" width="88%" alt="otter 长期记忆页" />
</p>

<p align="center"><sub>双层记忆可视化:Core 常驻注入 · Ordinary 按需读取 · 出处可溯</sub></p>

<p align="center">
  <img src="docs/assets/otter-artifacts.png" width="88%" alt="otter 交付物页" />
</p>

<p align="center"><sub>交付物浏览:发布历史 · 内联预览(PDF/图片/代码)· 打开/Finder/VS Code</sub></p>

</details>

## 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](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](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/打包/测试这层"轮子"。对一个单人深用的本地工具,这笔账划算。

## 如何拼在一起

```text
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 最佳)。

```bash
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
```

```bash
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](evals/report.md)。注:单轮结果,模型输出存在波动(任务集迭代期间的历史轮次为 88%/96%)。

```bash
.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` 嵌进你自己的程序:

```python
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 起)

```bash
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:

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

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

```bash
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 层并做会话隔离。

## 开发检查

```bash
.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 项
```

## 目录结构

```text
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](LICENSE))。
