NaumiAgent

能阅读、执行、记忆、协作并自我改进的本地 Agent 系统。

当前状态

naumi 默认启动新一代 Node Terminal UI，并以当前目录作为工作区；启动失败时自动回退到 Textual TUI。主界面聚焦对话与执行时间线，工具、权限、任务和运行状态通过结构化卡片持续更新。旧 Prompt Toolkit CLI 已退出公共入口，但实现代码继续保留。

核心能力包括：

多模型路由：通过 LiteLLM 统一调用模型，已接入 OpenAI-compatible Chat、OpenAI Responses、Anthropic Messages 与 Google GenAI 原生协议，支持 fast/capable/reasoning tier、模型发现与能力校验后的思考强度。
工具执行：文件读写、代码执行、shell、Web、浏览器、记忆、任务、调度等工具走统一权限与预算控制。
会话与记忆：SQLite 会话历史、Chroma 长期记忆、上下文压缩、/resume 与 /history 恢复链路。
运行态面板：/todo、/tasks、/runtime 汇总 todo、subagent、后台任务、浏览器任务和 hook 状态。
持续目标与自我演进：/goal 跨轮次保持工作方向，/goal pursue 复用 /pursue 启动自主循环；/self-review、/evolve、/forge 支持源码审查、自我修改和工具锻造。
多界面：Node Terminal UI、Textual fallback、REST API/WebSocket 和原生 Mac Workbench。
跨平台终端：适配 macOS Terminal/iTerm2、Kitty、WezTerm、常见 Linux 终端与 Windows Terminal；启动时协商颜色、Unicode、高级键盘协议和动画能力，异常退出会恢复光标、raw mode 与备用屏幕。

快速开始

安装

一键安装（推荐）

正式签名通道启用后，可以像 Claude Code 一样直接安装平台二进制，不再克隆源码，也不要求本机预装 Git、Python 或 Node。当前 v0.1.214 是未签名的内部预览版，必须显式固定版本：

curl -fsSL https://github.com/JesstLe/NaumiAgent-Releases/releases/download/v0.1.214/install.sh \
  | NAUMI_VERSION=0.1.214 bash

安装脚本会自动：

识别 macOS/Linux 与 x64/arm64；
从只包含 Release assets 的发行仓下载编译后端和编译 Terminal UI；
在解压前强制校验 SHA-256；
安装到不可变版本目录，再切换 ~/.local/bin/naumi；
保留旧版本目录，下载或校验失败不会破坏当前版本。

Windows PowerShell 使用同一发行版本：

$env:NAUMI_VERSION = "0.1.214"
irm https://github.com/JesstLe/NaumiAgent-Releases/releases/download/v0.1.214/install.ps1 | iex

源码仓已经设为 private；发行包的门禁会拒绝 Naumi 自有 .py/.js、测试、文档和 Git 元数据。冻结/编译会提高逆向成本，但任何本地二进制都不能承诺绝对不可逆。正式 GA 仍以 macOS Developer ID + notarization 和 Windows Authenticode 签名为前置门禁；签名前只发布 prerelease。

安装完成后直接运行：

naumi

首次启动会进入交互式引导，询问模型 API Key、模型提供商和权限模式，自动生成不含密钥的 .naumi/config.yaml；工作区直接使用启动 naumi 时所在的目录。模型密钥保存在系统凭据库中；已经设置 NAUMI_MODELS__API_KEY 的环境不会重复保存。旧项目的根目录 config.yaml 仍会被兼容读取，不会被自动复制或删除。

网络搜索默认无需搜索引擎 API Key：系统会依次尝试免 Key 搜索，并在失败时自动回退到浏览器搜索。Brave 是可选增强项，.naumi/config.yaml 只保存安全引用：

search:
  provider_order: [brave, duckduckgo, browser]
  brave:
    enabled: true
    api_key_ref: "{env:BRAVE_SEARCH_API_KEY}"
    country: CN          # 可选
    search_lang: zh-hans # 可选
    ui_lang: zh-CN       # 可选
    safesearch: moderate
    spellcheck: true
    freshness: null      # pd / pw / pm / py / 日期范围
    timeout_seconds: 10

macOS/Linux 可在启动前执行 export BRAVE_SEARCH_API_KEY='...'；PowerShell 使用 $env:BRAVE_SEARCH_API_KEY='...'。不要把真实 token 直接写进 YAML，配置校验会拒绝明文密钥。未设置该变量时自动跳过 Brave，不会阻塞基本搜索。

需要更换 provider、模型或过期密钥时，运行：

naumi configure

自动化环境可使用 --non-interactive --provider <name>，并通过环境变量复用现有凭据；需要更新密钥时使用 --api-key-stdin 从标准输入传入，避免密钥进入 shell history。

首次使用持久 Agent 任务前，显式初始化 Runtime payload 系统密钥：

naumi runtime-key init
naumi runtime-key status

init 幂等且不会静默轮换已有密钥；命令只显示非敏感 key ID，不会打印密钥。CI/容器可由 secret manager 注入 NAUMI_RUNTIME_PAYLOAD_KEY，无需访问系统凭据库。

配置完成后可以先运行纯本地诊断；显式增加 --live 才会发送一次最多 8 token 的真实模型请求：

naumi doctor
naumi doctor --live

实时诊断会区分 provider/model/API Base 混配、401 凭据失效、404 模型或地址错误、429 限流和连接超时，并且不会显示模型响应正文或服务端原始错误。

本地开发安装

uv sync --extra dev
# 或
pip install -e ".[dev]"

Windows 源码开发初始化

以下流程只面向拥有私有源码仓权限的开发者。Windows 原生开发使用 Python/uv，并通过 Git for Windows Bash 保持 Agent 的 Bash 命令语义；Node.js 20+ 用于源码态新 Terminal UI。普通用户应使用上一节的二进制安装器。先用隐藏输入保存 Kimi 密钥到当前 Windows 用户环境：

$kimiKey = Read-Host "Kimi API Key" -MaskInput
[Environment]::SetEnvironmentVariable("NAUMI_MODELS__API_KEY", $kimiKey, "User")
Remove-Variable kimiKey

重新打开 PowerShell，然后运行幂等初始化脚本：

powershell -ExecutionPolicy Bypass -File scripts/windows/setup.ps1

初始化完成后，可在 PowerShell 中直接启动新版终端 UI：

naumi

naumiagent 作为 Windows 早期版本的兼容别名继续可用，默认行为与 naumi 相同；naumiagent --tui 显式启动 Textual。脚本会检查 Python 3.12+、uv、可选 Node.js 20+ 与 Git Bash，创建 .venv 和无密钥的本地 .naumi/config.yaml，并验证配置。若 Git Bash 不在标准 Git for Windows 目录，可设置 NAUMI_GIT_BASH 指向 bin\bash.exe。脚本不会覆盖已有的现代配置；若发现旧根目录 config.yaml，会继续使用旧配置而不生成竞争副本。

新版 UI 必须运行在交互式 TTY 中，重定向或管道启动不会输出全屏控制序列。设置 NO_COLOR=1 可关闭语义色，FORCE_COLOR=1 可显式开启；设置 NAUMI_REDUCE_MOTION=1 可关闭工作动画。高级键盘协议只在已知支持的 Kitty、 WezTerm、Ghostty 和 foot 中启用，其他终端继续使用可移植按键序列。

配置

如果你选择跳过引导，可以手动配置：

mkdir -p .naumi
cp config.yaml.example .naumi/config.yaml
export NAUMI_MODELS__API_KEY=your-key

默认模型配置面向 Kimi Coding API：

models:
  provider: "kimi"
  default_model: "openai/kimi-for-coding"
  fast_model: "openai/kimi-for-coding"
  reasoning_model: "openai/kimi-for-coding"
  reasoning_effort: auto
  temperature: 1.0
  api_base: "https://api.kimi.com/coding/v1"

首次引导不再询问或永久保存工作区。交互式执行 naumi、naumi chat 或 fallback TUI 时，启动命令所在目录会成为本轮工作区；即使旧配置保存了另一个绝对 workspace_root，新会话也不会跳回旧项目。workspace_root 仍保留给 API、部署等非交互高级场景；bypass 模式不受工作区边界限制，可以显式操作其他目录。

项目配置、provider 目录和运行数据分别建议放在 .naumi/config.yaml、 .naumi/providers.json 和 .naumi/data/；密钥只放系统凭据库或环境变量。支持思考强度的模型需要在 provider catalog 的 capabilities.reasoning 或 models.model_info 中声明真实可用档位，NaumiAgent 不会盲目透传未验证值。完整配置见模型、Provider 与思考强度配置。

Google AI Studio 可在 .naumi/providers.json 中声明 apiFormat: "google_genai"、 X-Goog-Api-Key 的系统凭据/环境变量引用和 /models 动态发现；文本、系统消息、工具回合、流式输出与 usage 均走原生 Gemini transport，不需要伪装成 OpenAI 协议。

启动

# 推荐：直接启动新一代终端 UI
naumi

# 等价的对话入口
naumi chat

# 等价的源码启动方式
python -m naumi_agent.main

# 显式启动新一代 Node 终端 UI
naumi ui

# 显式启动 Textual TUI fallback
naumi tui

# 单任务执行
naumi run "检查这个项目的测试风险"

# REST API 服务
naumi serve

naumi、naumi chat 与 naumi ui 都优先使用 Node.js 20+ 的新 Terminal UI；Node 缺失、版本过旧、资源缺失或 UI 异常退出时，只自动回退一次到 Textual。naumi --tui、naumi chat --tui 与弃用别名 naumi ui --legacy 也会直接进入 Textual，推荐统一使用 naumi tui。旧 Prompt Toolkit CLI 源码、测试与必要依赖仍保留，但不再注册 --classic 公共入口。

如果需要查看 LiteLLM 可选 provider 的启动 warning，可显式打开：

NAUMI_SHOW_STARTUP_WARNINGS=1 naumi chat

常用斜杠命令

类别	命令	用途
基础	`/help` `/keybindings` `/style` `/doctor` `/model`	查看帮助、快捷键、主题、typed 本地健康诊断与模型配置
模型	`/models` `/effort` `/reasoning`	发现模型、切换模型思考强度、显示或隐藏思考文本
文件	`/glob` `/grep` `/read` `/write` `/edit`	通过 Agent 工具路径搜索、读取和修改文件
会话	`/history` `/resume` `/load <id>` `/new` `/clear`	查看、恢复、加载、保存新开或清空当前会话
调试	`/copy <all	last
Harness	`/harness status` `/harness eval … --repeat 5` `/harness baseline <suite>` `/harness baseline promote …` `/harness baseline compare …` `/harness explain` `/harness replay`	实时显示 Candidate 评测/保存进度，在 typed 状态页查看 Baseline，以理由和最终确认引导晋升，再比较、解释并安全回放运行
反馈	`/feedback <category> <scope> <topic> <摘要>`	将用户纠正或缺陷报告脱敏写入不可执行候选；偏好、取消和赞扬不会计为缺陷
候选审阅	`/evolution [list	detail ]`
单 Lane 评测回执	`/evolution evaluation <comparison-id>`	从 H5a/H5c/归因权威事实签发并显示明确非最终的 before/after 回执
结构化反思	`/evolution reflection <decision-input-id>`	从 Decision/Resolution 生成非向量、非自动注入、可撤销的结构化经验
撤销反思	`/evolution reflection-revoke <reflection-id> <reason>`	以 append-only 回执停用 Reflection；normal 确认，bypass 直接执行
Promotion 输入	`/evolution promotion-input <reflection-id>`	从 active accepted Reflection 冻结不可执行的审查输入；不审批、不合并、不发布
Promotion Package	`/evolution promotion-package <promotion-input-id> [target-branch]`	绑定目标分支、审批事实和可签名摘要；只读 Git，不审批、不执行发布
Promotion 审批要求	`/evolution approval-requirement <promotion-package-id>`	冻结审批角色、签名门、技术门与有效期；不创建交互、不作出审批
Promotion 角色审批	`/evolution approval-request <requirement-id> <role>`	通过 HAR-10.6 持久交互冻结角色回答；未验证身份/签名不计入最终 quorum，不执行 Git 或发布
Promotion 审批主体	`/evolution approval-principal <register	rotate
Promotion 审批签名	`/evolution approval-signature <prepare	submit
任务	`/todo` `/tasks` `/task` `/task-reply` `/task-abort`	管理 todo、subagent、后台/browser 任务和人工接管
运行态	`/runtime [分区]` `/team` `/background` `/schedule`	查看运行态、团队协议、后台任务和调度提醒
浏览器	`/browse` `/autobrowse` `/browser-state` `/bdaemon`	浏览器操作、本地浏览器 daemon 和 SoM 调试
分析	`/chaos` `/scale` `/state` `/graph` `/self-review`	架构、扩展性、状态、图谱和源码自审查
持续目标	`/goal [目标	子命令] /goal pursue /pursue <目标> /pursue status\|resume\|reconcile …`
自进化	`/evolve <描述>` `/evolve-history` `/forge`	现有自我修改、进化历史和工具锻造能力

命令补全来自 src/naumi_agent/cli/completer.py。输入 / 可查看全部命令，输入关键词可模糊匹配，例如 hs 可匹配 /history。/histroy 也会被容错映射到 /history。

架构

src/naumi_agent/
├── orchestrator/     # ReAct 引擎、Planner、运行模式、subagent 调度
├── model/            # LiteLLM 模型路由、流式响应、工具调用历史修复
├── tools/            # 文件、浏览器、代码沙箱、网络、记忆、自进化等工具
├── tasks/            # todo/task 工具与 SQLite 存储
├── agents/           # 子 Agent、消息总线、团队协议
├── safety/           # 权限、预算、guardrails
├── memory/           # 会话持久化、长期记忆、上下文压缩
├── streaming/        # 事件总线
├── cli/              # 保留的 Prompt Toolkit legacy 实现与共享命令后端
├── tui/              # Textual TUI fallback
├── ui/               # Node terminal UI bridge、协议、共享渲染组件
├── api/              # FastAPI REST + WebSocket
└── config/           # pydantic-settings + YAML 配置

开发

# Lint
uv run ruff check src tests

# 格式化
uv run ruff format src tests

# 测试
uv run pytest tests -q

# 类型检查
uv run mypy src/naumi_agent --ignore-missing-imports

日常改动建议优先跑与修改路径相关的 targeted tests。全量测试会覆盖更多外部集成和浏览器路径，耗时更长。

Docker

cp .env.example .env
# 编辑 .env，填入 NAUMI_MODELS__API_KEY
mkdir -p workspace
docker compose up --build

启动后访问 http://127.0.0.1:8080/docs。完整部署说明见 docs/deployment.md。

文档

License

MIT

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
.naumi		.naumi
.vscode		.vscode
apps		apps
assets		assets
deploy		deploy
docker		docker
docs		docs
frontend		frontend
packaging		packaging
scripts		scripts
src/naumi_agent		src/naumi_agent
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
config.yaml.example		config.yaml.example
docker-compose.yaml		docker-compose.yaml
naumi-bin		naumi-bin
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

NaumiAgent

当前状态

快速开始

安装

一键安装（推荐）

本地开发安装

Windows 源码开发初始化

配置

启动

常用斜杠命令

架构

开发

Docker

文档

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

NaumiAgent

当前状态

快速开始

安装

一键安装（推荐）

本地开发安装

Windows 源码开发初始化

配置

启动

常用斜杠命令

架构

开发

Docker

文档

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages