nm-agents 是做什麼的？
纯 Python 的 AI Agent 运行时内核：主循环 + 路由 + 模型管理 + 上下文 + 权限 + 工具注册 + 自进化 + 持久记忆。不附带任何业务工具，由接入方按需注册。
何时使用
- 要跑一个 agent 主循环（输入 → 记忆回灌 → 路由模型 → 调 LLM → 执行工具 → 沉淀记忆）
- 要持久记忆（跨会话决策/事实/轨迹，压缩与切模型不失忆）
- 要任务路由（本地/云端模型按信号选择）、权限校验、自进化流水线
- 纯库：工具由接入方注册
安装
pip install -e .
# 依赖: openai>=2.0, pydantic>=2.0, requests>=2.30（Python >= 3.10）
最小装配（AgentLoop）
from nm.config import HarnessConfig, DEFAULT_SYSTEM_PROMPT
from nm.agent_loop import AgentLoop
from nm.memory.memory_adapter import MemoryAdapter
from nm.context_manager import ContextManager
from nm.permission_checker import PermissionChecker
from nm.tool_registry import ToolRegistry
config = HarnessConfig(stream_output=False)
mem = MemoryAdapter("memory_store.json", "transcript.jsonl")
ctx = ContextManager(DEFAULT_SYSTEM_PROMPT, workspace_dir=".")
router = TaskRouter(model_manager) # 需先构造 ModelManager 并注册账号/分组
reg = ToolRegistry().create_default() # 只含 get_tool_detail；业务工具自行 register
perm = PermissionChecker(mode=PermissionMode.AUTO)
harness = AgentLoop(config, mem, router, reg, ctx, perm)
result = harness.run("帮我整理这些数据", user_id="user1")
run() 返回 {text, tool_calls, usage, model, turns}。
记忆 API（MemoryAdapter）
ingest(role, content, scope)/distill(scope)：对话写入 + 提炼为结构化记忆recall(scopes)：全量回灌（单块文本）recall_anchors(scopes)：锚点层（决策+事实，日常常驻 system）recall_detail(scopes)：全量细节（轨迹流水，按需回灌）capture({layer, ...})：显式捕获一条结构化记忆mark_used(ids)/stats()：读回执与统计
记忆闭环：ContextManager 压缩时通过 on_compaction 回调把被压原文沉淀为锚点；AgentLoop 切模型时补注全量细节——压缩、切模型两种失忆场景都有兜底。
配置
- 记忆默认落运行目录
.nm/（可用config_dir等显式指定，需目录可写） - LLM 端点（仅语义提取需要）：环境变量
OPENAI_BASE_URL/OPENAI_API_KEY→llm_config.json→ 本机兼容网关兜底；默认启发式提取零依赖
验证
python test_selfverify.py # 22 项断言，覆盖记忆闭环 4 场景
注意
- 权限默认
ASK，无回调时拒绝执行——接入方需提供ask_callback或改AUTO - 工具必须显式
register，未注册的工具会被拒绝 - 不包含任何网络服务入口，纯库