注意力,是大模型的全部。
聚焦,是 NIUMA 的全部。
2017 年,《Attention is All You Need》定义了一个时代——模型的全部智能,都建立在「注意力」之上。八年后我们发现:模型从不缺注意力机制,缺的是把注意力放在对的地方。上下文越长,噪声越多,真正关键的信息反而被稀释。niuma_code 只做一件事:为上下文做减法,为注意力做加法——让模型的每一个 token,都落在最该聚焦的地方。
看它如何工作
IDE 编排运行模式实机录屏,一分钟感受 niuma_code 的聚焦体验
为什么选择 niuma_code
不是 Claude Code 的替代品,而是让它更聚焦的补充增强工具
harness 自主对话
默认模式,无需任何命令。LLM 在工具循环里自主探索、 边想边做、步数不定,把任务一口气跑完。
- tool_use 工具循环:LLM 自主决定读文件 / 改代码 / 跑命令,直到完成
- API 错误自动重试,流式渲染 + ESC 取消 + 超长自动压缩
- 适合边界模糊、难以预先拆解的任务,LLM 自主判断何时收尾
loop 工程化编排
/loop <目标> 进入目标导向自循环:
先拆带验证命令的清单,再顺序执行、逐个验证、失败自纠。
- 规划 → 执行 → 验证 → 失败回边重试(3-strike,回灌失败原因不重蹈覆辙)
- 双闸正交:MAX_ROUNDS=20 任务硬闸 + MAX_RETRIES=3 单任务自纠
- 每一轮内部调用 harness 跑单步,适合可分解、可验证的工程任务
TUI 全屏模式
基于 prompt_toolkit 全屏界面,输入框固定底部, LLM 流式输出时可随时追加新消息,不被冲走。
- 5 个模态浮层:模型设置、消息队列、上下文切换、对话管理、权限确认
- 鼠标拖拽选区高亮、滚轮浏览、左键自动复制、Ctrl+滚轮缩放字体
- 实时状态栏:思考预览、输入/输出 token 计数、压缩进度与 ESC 取消
IDE 编排运行模式
全屏代码编辑器,用 Python 原生语法编写编排脚本, 把 LLM 调用编排进可控的脚本流程。
- 注入 llm_call / llm_confirm / llm_judge 函数,编排可控的 LLM 调用流程
- F5 预览(AST 静态分析展开步骤),F6 编排运行(无人值守,工具权限自动放行)
- 安全沙箱执行 + 危险 import 黑名单拦截(os/subprocess/socket 等),黑名单是无人值守模式的唯一兜底;F6 复用主对话链路真实运行
多 Provider 路由
通过 settings.json 配置多个 API 端点, 按模型自动路由到对应 provider,同会话内自由切换。
- 每个 provider 声明 base_url / api_key / 支持的模型列表
- #tag 或 /model 切换模型,请求自动命中正确端点
- 三层配置叠加(用户级 / 项目级 / 项目本地),后者覆盖前者
多上下文并行
把单一对话扩展为 N 个并行上下文,各自独立维护 历史、token 计数与压缩状态,互不污染。
- LRU 淘汰,默认上限 5(max_contexts 可配),淘汰即归档可恢复
- /context 可视化弹框切换;离开时后台异步生成摘要
- /messages 按对话单元多选,删除 / 移位 / LLM 摘要合并
代码知识图谱
基于 tree-sitter 解析代码结构,构建符号定义、 调用与依赖关系图谱,让 LLM 先精确定位再读行。
- 4 个只读检索工具:定位符号、查文件依赖、查引用、查调用
- 返回 文件路径:行号 与签名,取代 grep 全文大海捞针
- 三因子决策按需重建,避免每次启动全量解析
子 Agent 并行调研
只读子 agent 并行工具执行,在隔离上下文中调研后 回传摘要,主上下文保持清爽。
- 多个子 agent 并行执行只读工具,互不阻塞
- 隔离上下文调研,仅回传摘要,不污染主对话
- 归属默认自主对话范式,按需调用而非独立模式
感知驱动记忆
基于 memory-palace 的持久化记忆,把运行过程中的事件 实时转写为记忆,跨会话积累经验。
- 10 种感知事件:眼/身/舌/鼻/果等,实时写入而非对话结束才提取
- fact 三元组 + 对话摘要,四层检索 + 贝叶斯衰减
- 下次对话自动检索注入 system prompt,召回位置稳定
果感知奖励追踪
追踪任务目标的完整生命周期,按完成质量计算奖励分数, 作为感知事件实时写入记忆。
- OutcomeTracker 按任务目标全生命周期计算 0.0~1.0 奖励分数
- 奖励分数沉淀为记忆的复用价值评估信号
- 10 种感知事件之一,与读/写/工具调用等联动
两种模式怎么用好
说不清步骤、想边做边看就直接说(harness);能列成一条条带验证的清单就用 /loop
用好 harness 的关键
harness 没有重新规划的回边,开头喂得越清,自主探索跑得越准。
- 一次把约束说全:目标 + 禁碰的文件/函数 + 验收标准,别中途改需求
- 边界模糊但目标明确时最合适;步骤越清晰,它收敛得越快
- 善用控制点:ESC 随时止损、超长自动压缩、API 错误已自动重试
- 它"声称完成"不等于真完成——关键改动后自己跑一次测试/编译确认
用好 loop 的关键
回边能否自纠,全看"验证"这一环——目标可验证,3-strike 才有意义。
- 目标必须能拆成带验证命令的清单:"更优雅"无法验证,回边形同虚设
- 目标里直接点明验证方式(如跑 py_compile / 某测试),规划命中率最高
- 3 次纠不对多半是验证信息不足:把任务拆更细,比硬重试有效
- 3 次失败不中断而是记录后继续,看完整结果等汇总里的 [!!] 标记
三步启动
下载、配置、启动,几秒钟搞定
settings.json 完整参数
配置文件路径:~/.niuma/settings.json
factories — 多 Provider API 配置,每个 provider 声明 base_url / api_key / 支持的模型列表,按模型名自动路由
{
"factories": [
{
"base_url": "https://api.anthropic.com", // Anthropic 官方端点
"api_key": "sk-ant-xxx", // 必填,三个字段缺一不可
"options": ["claude-sonnet-4-6", "claude-opus-4-8"] // 该 provider 支持的模型
},
{
"base_url": "https://your-proxy.example.com", // Anthropic 兼容代理端点
"api_key": "sk-proxy-xxx",
"options": ["claude-sonnet-4-6"] // 该端点支持的模型
}
]
}
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| base_url | string | — | API 端点地址(必填)API endpoint URL (required) |
| api_key | string | — | API 密钥(必填)API key (required) |
| options | string[] | [] | 该 provider 支持的模型名列表,如 ["claude-sonnet-4-6", "claude-opus-4-8"]Supported model names for this provider |
llm — 模型、effort 级别、thinking budget 与上下文管理配置
{
"llm": {
"default_model": "claude-sonnet-4-6", // /model 切换的默认值
"default_effort": "high", // 决定 thinking_budget_high 生效
"max_contexts": 5, // 并行上下文上限,超出后 LRU 淘汰
"resume_latest_context": true, // 启动时恢复上次 active 上下文
"options": [ // 模型 → effort 映射表
{"claude-sonnet-4-6": ["low", "medium", "high"]},
{"claude-opus-4-8": ["low", "medium", "high", "max"]}
],
"thinking_budget_low": "0", // 0 = 禁用 extended thinking
"thinking_budget_medium": "0",
"thinking_budget_high": "10000", // high effort 使用此 budget
"thinking_budget_max": "20000" // max effort 使用此 budget(最深推理)
}
}
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| default_model | string | "claude-sonnet-4-6" | 默认模型(会话级固定,/model 可切换)Default model (fixed per session, switchable via /model) |
| default_effort | string | "high" | 默认 effort 级别(low/medium/high/max),控制 thinking budget 深度Default effort level — controls thinking budget depth |
| max_contexts | integer | 5 | 活跃对话上下文上限,达上限后 LRU 淘汰最久未活跃者(归档保留,可 /context 恢复)Max active parallel contexts; LRU evicts the oldest when exceeded |
| resume_latest_context | boolean | true | 启动时是否恢复上次 active 上下文;false = 每次新建空上下文Resume last active context on startup; false = start fresh |
| options | object[] | [] | 每个模型支持的 effort 组合,如 [{"claude-sonnet-4-6": ["low","medium","high"]}],用于 /model 切换校验Model→effort mapping, used to validate /model switches |
| thinking_budget_low | string/int | "0" | low effort 的 thinking budget token 数(0 = 禁用 extended thinking)Thinking token budget for low effort (0 = disabled) |
| thinking_budget_medium | string/int | "0" | medium effort 的 thinking budget token 数Thinking token budget for medium effort |
| thinking_budget_high | string/int | "10000" | high effort 的 thinking budget token 数Thinking token budget for high effort |
| thinking_budget_max | string/int | "20000" | max effort 的 thinking budget token 数(最深推理)Thinking token budget for max effort (deepest reasoning) |
env — 环境变量,直接写入 os.environ,控制人格、调试、网络、权限等行为
{
"env": {
"PERSONA_NAME": "niuma", // AI 人格名,注入 system prompt
"MODEL_BACKGROUND": "claude-haiku-4-5", // 后台任务模型(记忆提取、压缩等)
"LANG": "zh", // 界面语言(zh/en),同时控制 LLM 应答语言
"TEMPERATURE_ZERO": "true", // 注意:所有值都是字符串
"API_TIMEOUT": "30", // 流式停滞超时(单位:秒)
"API_ROUND_MAX": "120", // 单轮墙钟硬上限(单位:秒)
"API_STALL_MAX_RETRIES": "2", // 流式停滞自动重试次数
"PERMISSION_MODE": "auto", // auto=白名单+确认 / manual=仅白名单 / skip=全放行
"ALLOWED_TOOLS": "" // 白名单工具(逗号分隔),空=内置默认
}
}
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| PERSONA_NAME | string | "niuma" | AI 人格名称,注入 system prompt 中的角色名Persona name injected into the system prompt |
| MODEL_BACKGROUND | string | "claude-haiku-4-5" | 后台任务模型(记忆提取、对话压缩等辅助调用)Background model for memory extraction, compression, etc. |
| LANG | string | "en" | 界面语言(zh=中文 / en=英文),同时控制 LLM 应答语言UI language (zh/en), also controls LLM response language |
| TEMPERATURE_ZERO | string(bool) | "true" | 固定 temperature=0(确定性输出);false = 使用模型默认温度Fix temperature=0 for deterministic output; false = use model default |
| API_TIMEOUT | string/int | "30" | API 流式响应停滞阈值(秒),超过此时间无任何事件则判定连接异常Streaming stall timeout in seconds — no events for this long triggers reconnect |
| API_ROUND_MAX | string/int | "120" | 单轮请求墙钟硬上限(秒),防止 thinking-only 长响应独占工作线程Wall-clock hard limit per turn in seconds — kills stale streams |
| API_STALL_MAX_RETRIES | string/int | "2" | 流式停滞自动重试次数上限Max retries on stream stall before giving up |
| PERMISSION_MODE | string | "auto" | 权限模式:auto(白名单+确认)/ manual(仅白名单)/ skip(全跳过)Permission mode: auto (whitelist+confirm) / manual (whitelist only) / skip (allow all) |
| ALLOWED_TOOLS | string | "" | 白名单工具列表(逗号分隔),为空时使用内置默认列表(含 read_file、write_file、execute_bash 等)Comma-separated tool whitelist; empty = use built-in defaults |
compact — 上下文压缩配置,对话过长时自动压缩保留关键信息
{
"compact": {
// ── 对话中同步压缩(阻塞主循环,等压缩完才继续) ──
"inline_trigger": 0.8, // token 占 MAX_TOKENS 80% 时触发
"inline_keep_ratio": 0.4, // 压缩后保留最新 40% 消息
// ── 答完后异步压缩(不阻塞,后台静默执行) ──
"idle_trigger": 0.5, // token 占 MAX_TOKENS 50% 时触发
"idle_keep_ratio": 0.4, // 压缩后保留最新 40% 消息
// ── LLM 摘要输出上限 ──
"max_summary_tokens": 4096 // 生成摘要的最大 token 数
}
}
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| inline_trigger | float | 0.8 | 对话中同步压缩触发阈值(占 MAX_TOKENS 比例),达到后阻塞主循环压缩Inline compression trigger ratio — blocks main loop when reached |
| inline_keep_ratio | float | 0.4 | 对话中压缩保留最新消息比例(0.4 = 保留 40%,其余由 LLM 压缩为摘要)Ratio of recent messages kept after inline compression |
| idle_trigger | float | 0.5 | 答完后异步压缩触发阈值(占 MAX_TOKENS 比例),达到后后台压缩,不阻塞Idle compression trigger ratio — runs async after reply completes |
| idle_keep_ratio | float | 0.4 | 答完后压缩保留最新消息比例Ratio of recent messages kept after idle compression |
| max_summary_tokens | integer | 4096 | LLM 摘要最大输出 token 数(压缩时生成摘要的上限)Max output tokens for LLM-generated compression summaries |
memory_palace — 记忆宫殿 LLM 配置,独立于 llm 块,单独解析
// 基础模式:纯规则提取(无需 LLM,零成本)
{
"memory_palace": {
"enable_v9": false, // 关闭 V9,降级为 V8 传统模式
"llm_enabled": false // 关闭 LLM 增强
}
}
// 完整模式:LLM 增强提取(三个字段缺一不可,否则降级为纯规则)
{
"memory_palace": {
"enable_v9": true,
"llm_enabled": true, // 开启后必须填写下方三字段
"base_url": "https://api.anthropic.com",
"api_key": "sk-ant-xxx",
"model": "claude-haiku-4-5" // 建议用轻量模型,节省 token
}
}
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| enable_v9 | boolean | true | 启用 V9 记忆能力层(感知驱动记忆),false = 降级为 V8 传统模式Enable V9 perception-driven memory; false = legacy V8 mode |
| llm_enabled | boolean | false | 记忆提取是否启用 LLM 增强(true = 用 LLM 提取更高质量 fact,false = 纯规则模式)Enable LLM-enhanced memory extraction; false = rule-based only |
| base_url | string | "" | 记忆 LLM 的 API 端点(三字段 base_url/api_key/model 缺一即降级纯规则模式)Memory LLM API endpoint (all three fields required, or falls back to rule-based) |
| api_key | string | "" | 记忆 LLM 的 API 密钥Memory LLM API key |
| model | string | "" | 记忆 LLM 使用的模型名(建议用轻量模型如 haiku)Model for memory LLM (recommend a lightweight model like haiku) |
memory_quality — 记忆质量门控阈值,控制记忆的写入过滤和召回精度
{
"memory_quality": {
"min_store_importance": 0.4, // 写入门控:fact importance 低于此值不入库
"min_recall_score": 0.35, // 召回门控:score 低于此值不注入 prompt
"dedup_threshold": 0.3 // 去重阈值:Jaccard 相似度高于此视为重复
}
}
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| min_store_importance | float | 0.4 | 写入侧卡口:fact 自评 importance 低于此值不入库,源头拦截低价值噪音(0.4 拦截"随意提及",保留"bug/问题"及以上)Write gate: facts scoring below this importance are discarded at extraction |
| min_recall_score | float | 0.35 | 召回侧卡口:召回 score 低于此值不注入 prompt,过滤低相关度噪音Recall gate: memories scoring below this are not injected into the prompt |
| dedup_threshold | float | 0.3 | 去重阈值:Jaccard 字符相似度高于此值视为重复,保留最新条目Dedup threshold: Jaccard similarity above this = duplicate, keeps newest |
所有可用命令
使用斜杠命令快速操作
| 命令 | 说明 |
|---|---|
| /ide | 进入全屏代码编辑器 |
| /context | 多上下文管理(new/rename/switch/del) |
| /help | 显示帮助信息 |
| /copy | 复制最近回复到剪贴板 |
| /resume | 继续未完成任务 |
| /clear | 清空对话上下文 |
| /restart | 重启 niuma |
| /model | 查看/切换模型 |
| /quit | 退出程序 |