NovaAgent · 企业级通用 Agent 框架

从 0 到 1"集百家之长"造的 agent 框架：LangChain 1.x + LangGraph 1.x 底座，自研多模式路由、双层记忆、反思循环、零依赖可观测层与 MCP 工具生态。设计过程文档化：每个模块都有"调研 → 选型 → 设计 → 实现 → 测试 → 反思"的完整记录（见 docs/）。

能力总览

能力	实现	对标来源
核心	LangGraph 状态图：记忆加载 → 路由 → 模式执行 → 反思 → 记忆沉淀；durable execution（checkpoint 三级降级 Redis/SQLite/内存）	LangGraph 官方 big architecture
模式区分	`fast`（直答，低延迟）/ `standard`（ReAct+工具）/ `deep`（计划→执行→反思）/ `auto`（LLM 路由，规则前置省钱）；模式差异收敛在一张注册表上	Claude Code plan/act、OpenManus PlanningAgent
记忆系统	短期=thread checkpoint；长期=语义记忆（提取→对账→打分→淘汰）+ agent 自主 remember 工具	Mem0/Letta/Zep + LangGraph memory-agent
监控	structlog 日志 + Prometheus 指标（token/成本/延迟/成功率）+ 每运行 JSONL trace + 成本账本；LangSmith/Langfuse 可插拔	OpenHands 事件溯源、WorkBuddy 成本治理
工具系统	沙箱文件/Python 执行/搜索/HTTP + MCP 一键接入（官方 adapters）；工具硬化（异常→信息，绝不击穿图）	MCP（Linux 基金会标准）
安全	权限引擎（deny>ask>allow 规则 + 四种权限模式，ask→interrupt 人工批准）+ 命令安全三层纵深（语法分解 / 语义复审 / 隔离执行，绕过率 35%→0%）+ Hooks（PreToolUse 等事件 JSON 契约）+ API key 强制 + 限流 + PII 脱敏	Claude Code permissions/hooks、OpenHands 安全分析器、Codex 沙箱
接口	FastAPI（异步 SSE 流式 + 会话管理 + resume + 目标模式）+ Vue 工作台（目标/审批/插件/轨迹/用量）+ CLI	—
提示词	版本化注册表（v1 基线 / v2 结构化默认 / v3 极简 / v4 源码学法版）+ 评测脚本 + 真实模型跑分报告	Claude Code/OpenManus 提示词风格

快速开始

# 依赖（Python 3.11+）
pip install -e ".[dev]"

# 配置：复制样例并填入模型 key（anthropic 兼容端点或 ollama 均可）
cp .env.example .env

# 交互式对话
python -m nova_agent.cli chat

# 起 API 服务（:8000 业务 / :9100 metrics）
python -m nova_agent.cli serve

代码用法

from nova_agent.core.graph import NovaAgent

agent = NovaAgent()                      # 默认 v4 提示词 + 记忆 + checkpoint
result = agent.run("帮我调研主流向量数据库并写对比报告",
                   thread_id="u1-s1", user_id="u1")   # mode="auto" 路由
print(result.output, result.mode, result.cost_usd)

for kind, payload in agent.stream("你好", thread_id="u1-s1"):
    if kind == "token":
        print(payload, end="", flush=True)

架构一图

L5 接口      CLI · FastAPI(SSE) · /metrics
L4 可观测    structlog · prometheus · JSONL trace · 成本账本
L3 能力      记忆(短期/长期) · 工具(内置+MCP) · 提示词(版本化) · 安全(HITL/PII)
L2 运行时    StateGraph: load_memory→router→(fast|standard|deep)→reflect→save_memory
             模式节点内: create_agent + middleware(Retry/TodoList/Summarization/HITL)
L1 基础设施  Config · LLM工厂(多供应商) · Redis/SQLite · Embeddings

状态图与模式说明详见 docs/02-核心架构设计.md。

项目结构

src/nova_agent/
├── config/       # 唯一的 env 读取点
├── llm/          # 模型工厂：角色化(primary/fast)、实例缓存、多供应商
├── core/         # 状态定义、模式注册表、图装配 + NovaAgent 门面
├── nodes/        # router / mode / reflect / memory 节点
├── memory/       # short_term(checkpointer) / long_term(store+向量) / extractor
├── tools/        # builtin(沙箱) / mcp_loader / registry(硬化)
├── prompts/      # PromptSet 版本注册表（v1/v2/v3/v4，默认 v4）
├── safety/       # 权限引擎 / Hooks / 命令审计(command_audit) / LLM 语义复审 / HITL / PII 脱敏
├── observability/# logging/metrics/trace/cost/callbacks
└── api/          # FastAPI + SSE
tests/            # 319 个测试（假模型，零 API 成本）
scripts/          # smoke_test.py / eval_prompts.py / eval_command_safety.py / maturity_check.py
eval/             # 评测原始数据 report.json
docs/             # 00 调研 → 22 命令安全 的完整设计档案

验证

python -m pytest tests -q                 # 319 passed
python scripts/maturity_check.py --fast   # 快速档 3/3（纯静态，无外部依赖，~52s）
python scripts/maturity_check.py          # 完整档 5/6（提示词评测环受 GLM 周配额阻塞）
python scripts/eval_command_safety.py     # 命令安全评测（绕过率 / 误报率双指标）
python scripts/smoke_test.py              # 全图冒烟
python scripts/eval_prompts.py            # 提示词评测（需 .env 配 key）

命令安全实测（34 条语料 / eval/command_safety.json）：整串前缀匹配基线绕过率 35.0% → 分解式裁决 0.0%，两者误报率均为 0.0%；升级手段触发面 L2 语义复审 5.9%、L3 隔离执行 14.7%。详见 docs/22。

真实模型评测结论（GLM-4.7 / GLM-5-Turbo，多轮）：路由准确率 v1 80% → v2 90%；反思缺陷检出率 v1 0% → v2 100%；v3 极简实验（H5/H6）无增益（详见 docs/06）。此后按源码学法产出 v4 并经评测无退化后转正为默认版（docs/17 / docs/19）；工具任务成败由模型方差主导（方法论教训见 docs/06）。

完整智能体子系统（对标 Claude Code / pi / DeepSeek harness）

会话事件流："Model-visible means logged"——append-only JSONL（workspace/sessions/）为唯一事实源，消息历史/工具轨迹/权限审计全部投影而来；GET /v1/threads/{id}/events 审计回放
会话分叉：POST /v1/threads/{id}/fork——事件流复制 + 检查点播种（pi 会话树语义）
计划批准门：deep 模式计划 → interrupt → approve/revise（CC plan mode 语义）
权限审批：ask 在 ToolNode 执行点 interrupt——resume 只恢复工具执行，model 不重跑；fail-closed
子代理：.nova/agents/*.md（frontmatter: name/description/tools/model）→ task 工具；独立上下文隔离 + 工具白名单 + 同一轮真并行（coroutine 化）；内置 explore/researcher
Hooks：.nova/settings.json 的 hooks 字段；PreToolUse/PostToolUse/Stop/SessionStart；exit 2 拦截、JSON decision 契约
Skills：.nova/skills/<name>/SKILL.md 渐进加载；模型自主触发（load_skill）+ /命令 直通；内置 deep-analysis/code-review
消息队列：busy 会话新消息入服务端持久队列（FIFO 自动排空，断线不丢；Codex 学法）
double-texting 主动通道：运行中 steer 注入（下一次模型调用边界进入当前 turn，Claude Code 语义）+ ⏹ 打断（模型/工具两级边界 fail-closed，进度已保存）；结构化 steer（mid-run 切 dry-run / 切 permission_mode——run 级权限视图，规则共享模式隔离；白名单 deny-by-default）；未消费注入自动回落排队（注入是快，排队是达）
任务计划文件系统（v1.9.5→1.10.0 计划可视化：📋 抽屉展示 todos+计划文件，运行结束自动刷新）：plan_read/plan_write 持久 task_plan/progress + todos 跨 turn 恢复注入（长任务压缩/新轮不丢，docs/33）
真实环境验收（v1.10.3）：路由评测 95%/真工具调用/deep 审批链/飞轮闭环全过（seeway 网关，glm-5.3+glm-5.2）
模型人格探针（v1.10.2）：多模型网关套壳/人格污染自动化检测（频率化采样，polluted 挡发布；docs/34）
混合记忆检索（v1.9.4）：dense+BM25+同义扩展，recall@3 0.812→1.000（零依赖，docs/32）+数据飞轮（v1.10.1）：低置信 miss 自动积累 → LLM 蒸馏同义提案 → 人批准热生效
前端产品化（v1.9.2）：代码块高亮+复制（本地 vendor）/消息操作（复制·重新生成·从此分叉）/live 状态徽标/会话搜索重命名/用量柱状图/Esc 打断/智能吸底/移动端侧栏抽屉化
结构化审批：五响应类型——批准/改参放行/自由回复不放行/总是允许（会话级记住，风险上限 ≤medium，deny 永远终局）/拒绝 + dry-run 预演（推理照走工具零执行）
权限：Bash(git *)、write_file(src/**) gitignore 风格规则；default/acceptEdits/plan/bypassPermissions；ask 走 ToolNode 级 interrupt（fail-closed）；SSRF 防护（http_get 私网黑名单）；多租户（.nova/api_keys.json key→user_id+专属 RPM）
上下文压缩：双层——图级 RemoveMessage+LLM 摘要写回持久层（checkpoint 有界）+ 节点视图级 [COMPACTED]；任务锚点与近窗保留
bash 工具：git/构建工具等任意命令（30s 超时、环境 hygiene、权限审查）；执行后端可插拔（NOVA_EXEC_BACKEND=local|docker，docker 断网+资源限制+自动回退）
命令安全三层纵深：L1 语法层——引号感知分解 &&/||/;/|、解包 bash -c、提取 $(...)、剥离环境变量与 env/nohup 修饰词，逐子命令独立裁决取最严（挡住 cd /tmp && rm -rf / 类绕过）；L2 语义层——工具入参内联 security_risk 自标注 + 仅在静态层认输时触发的 LLM 复审（只能升不能降、失败即从严、可关）；L3 隔离层——按"看不清要执行什么"丢进断网容器（而非按"风险高"，后者会静默架空用户批准）
子代理可观测：流式 subagent_progress 逐步事件（step/节点/工具/累计 token）+ token 预算（NOVA_SUBAGENT_TOKEN_CAP 默认 200k，超限中断但交付已完成部分；budget_enforced 标记预算是否真正生效）
ZCode 级工具面：edit_file（str_replace 唯一匹配编辑）/ grep·glob_files / 后台任务（run/status/stop）/ 持久 REPL / ask_user（interrupt 提问）/ computer use（截屏·鼠标·键盘·剪贴板，pyautogui 可选）/ browser（playwright 无头，可选）——控制类默认 ask 审批
插件市场：nova plugin install <git-url>（安装即权限告知：申请的工具需 --yes 确认，未知工具明示忽略）
会话导出与树：export 离线 HTML 审计报告；tree 谱系导航；fork-at 从任意历史点重来
成本预算：per-user 日预算（超限 429 到次日 + Retry-After；/v1/usage 附余量）
防失控护栏：子代理派生/并发/工具调用三上限 + 嵌套 token 计入根预算（CC/Codex 学法）
rewind：回退到任意历史落点继续（事件流保留全史）；KV-cache 纪律：前缀时间粗化到小时、禁用工具遮蔽而非删除（Manus 学法）
事件订阅：POST /v1/events/{token} webhook 唤醒 agent 推进（能力令牌鉴权，治理全继承；Cursor Subscriptions 学法）
cron 后台任务：.nova/cron.json + nova cron run / nova cron daemon（全新 agent 无历史执行 + append-only 执行历史；hermes 语义）
supervisor 拓扑：mode=team——任务分解（Roo orchestrator 委派五要素）→ 子代理线程池真并行 → 结果综合
多租户：.nova/api_keys.json（key→user_id+专属 RPM，fail-closed）
技能自生成 + Playbook：单会话 skillgen 自动沉淀 + 跨会话 Playbook 提案（新技能/更新/项目规则三类，人批准后生效——数据飞轮）

部署

# 本地（dev：无 key 可跑）
python -m nova_agent.cli serve

# 生产（Docker Compose：app + redis + prometheus）
NOVA_API_KEY=你的key NOVA_PRIMARY_API_KEY=模型key docker compose up --build

生产安全默认：NOVA_ENV != dev 时未配置 NOVA_API_KEY 服务拒绝启动；所有 /v1/* 走 Bearer 鉴权 + 限流；/health 豁免。

文档索引（设计档案）

文档	内容
00-市面调研报告	LangGraph/OpenManus/OpenHands/CrewAI/AutoGen/MetaGPT/Mem0/Letta/Zep/Claude Code/MCP 实地调研 + 十大可借鉴设计
01-技术选型	为什么是 LangChain+LangGraph：对比矩阵 + 不选它们的代价
02-核心架构设计	五层架构、状态图、模式区分、风险对策
03-记忆系统	双层记忆、对账/淘汰策略、测试结果、局限
04-监控可观测	四件套设计、零侵入接入、trace 实证
05-工具与安全	沙箱工具、MCP、硬化护栏、HITL
06-提示词工程与评测	v1/v2 假设、五组实验、三轮数据、方法论教训
07-测试与反思	测试分层、13 个测试逼出的 bug、诚实复盘
08-源码级提示词调研	OpenManus/SWE-agent/Aider/LangGraph 官方模板提示词逐字对比与采纳决策
09-企业化加固	差距分析→闭环记录、安全默认链路、WorkBuddy 能力映射
10-架构升级	DeepSeek harness/pi/hermes 一手调研 + 六大子系统 + interrupt 安全实测
11-Harness级架构	事件流/计划门/并行/分叉/cron/执行后端/技能自生成七系统
12-独立评审与修复闭环	独立评审 38/60 → 三大缺陷修复 + 两个经典 bug
13-工程纵深补完	SSRF/allowed-tools/持久压缩/会话树/supervisor/cron daemon/多租户/Docker 加固/TTFT/规模验证
14-ZCode级工具面	edit_file/grep/后台任务/REPL/ask_user/computer/browser 七组工具
15-五维度审计与修复	记忆/工具/子代理/思维链/权限五维审计 → 7 缺陷修复
16-成熟产品标准循环	六环载体核对 + v1.0.0 成熟度自评
17-提示词写法学法	Codex/pi/Roo 一手提示词源码学法 → v4 落地与评测
18-源码学法第二轮	switch_mode/评审契约/argumentHint + 事件流驱动前端
19-标准循环运转记录	检索质量实证（语义 1.0 vs 词面 0.75）/apply_patch/v4 转正/一键门禁
20-插件系统与记忆分层	插件启停/四层记忆/用量聚合/前端柔和大版本
21-下一步优化方案	v1.1 规划：质量门禁/插件生态/安全纵深/体验打磨（含验收标准）
22-命令安全与密钥治理	命令三层防线复盘 / 重复实现回退教训 / 密钥 hash+轮换
23-目标模式	Goal Mode 自主循环：自评→步进→完成审计→预算→可恢复（真实模型实测通过）
24-供应商怪癖垫片	畸形 tool args 静默断路器：传输层修复 + 实测闭环
25-插件市场与会话导出	git 安装插件（权限告知）/ HTML 审计报告 / 门禁抗抖
26-预算与会话树	per-user 日预算（429 到次日）/ 会话树与任意点分叉 / Mermaid
27-护栏与缓存纪律	防失控四护栏（嵌套 token 计入根预算）/ KV-cache 前缀纪律 / 2026 标杆对照
28-Playbook沉淀	跨会话提炼流程→三类提案→人批准生效（数据飞轮）
29-事件驱动订阅	webhook 能力令牌唤醒 agent（治理全继承）；2026 Top5 收官
30-队列与结构化审批	线程持久输入队列/审批四响应（edit 改参放行）/dry-run 预演
31-double-texting-steer	steer 注入（模型边界送达）/interrupt 两级打断/流式 busy 补齐/送达矩阵
32-记忆检索混合层	dense+BM25+同义扩展/归一化教训/混合门禁 @3≥0.95
33-任务计划文件系统	plan 文件持久工作状态/todos 写回外层/contextvar 泄漏教训
34-模型人格探针	网关套壳陷阱/概率性拒绝归因/探针矩阵与成熟度接线
22-命令安全纵深与子代理可观测	三层命令防御选型与实测（35%→0%）/子代理流式与预算/三个静默失效缺陷复盘

路线图

见 docs/21-下一步优化方案（按两周迭代排列，每项带验收标准）。

已完成：docs/21 规划 21 项中的 19 项（+A2 v4 E4/E5 补评：v4 reflect=v2，验收通过不触发回退，详见 CHANGELOG 1.12.0）；i18n（D4）明示不做。1.12.0（2026-09-08）minor 升级，合并 A2 闭环 + E2 灰度清单 + 模型默认切换（glm-5.2/5.3 → gpt-5.6-luna）。

待办（2 项，均受环境阻塞）：

A3 评测定时化进 CI —— 需 .git 仓库与模型 key（CI secrets）
C2 Windows Docker 后端实测 —— 需 Docker Desktop

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
.nova/skills/auto		.nova/skills/auto
deploy		deploy
docs		docs
eval		eval
research/prompts		research/prompts
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
README.md		README.md
USAGE.md		USAGE.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
pytest_v4.txt		pytest_v4.txt
pytest_z.txt		pytest_z.txt
server.log		server.log

Navigation Menu

Repository files navigation

NovaAgent · 企业级通用 Agent 框架

能力总览

快速开始

代码用法

架构一图

项目结构

验证

完整智能体子系统（对标 Claude Code / pi / DeepSeek harness）

部署

文档索引（设计档案）

路线图

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

NovaAgent · 企业级通用 Agent 框架

能力总览

快速开始

代码用法

架构一图

项目结构

验证

完整智能体子系统（对标 Claude Code / pi / DeepSeek harness）

部署

文档索引（设计档案）

路线图

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages