v0.2.0 - Alpha 版本

注意力,是大模型的全部。
聚焦,是 NIUMA 的全部。

2017 年,《Attention is All You Need》定义了一个时代——模型的全部智能,都建立在「注意力」之上。八年后我们发现:模型从不缺注意力机制,缺的是把注意力放在对的地方。上下文越长,噪声越多,真正关键的信息反而被稀释。niuma_code 只做一件事:为上下文做减法,为注意力做加法——让模型的每一个 token,都落在最该聚焦的地方。

🔒
本地运行
数据不经第三方,隐私由你掌控
🛡️
隐私优先
API Key 本地存储,对话数据不上传
📦
v0.2.0 Alpha
持续迭代,社区驱动
💬
社区支持
GitHub Issues 直达开发者

看它如何工作

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 才有意义。

什么时候用:活儿能拆成一条条,每条都验证得了对错。 例:"/loop 给 user 接口加分页,每改完跑一次 py_compile"
  • 目标必须能拆成带验证命令的清单:"更优雅"无法验证,回边形同虚设
  • 目标里直接点明验证方式(如跑 py_compile / 某测试),规划命中率最高
  • 3 次纠不对多半是验证信息不足:把任务拆更细,比硬重试有效
  • 3 次失败不中断而是记录后继续,看完整结果等汇总里的 [!!] 标记

三步启动

下载、配置、启动,几秒钟搞定

01 下载
⬇ Download niuma.exe
Windows · 免安装 · 直接运行
02 配置
# ~/.niuma/settings.json
{
  "factories": [{
    "api_key": "your-key"
  }]
}
03 启动
$ niuma.exe
🐂 niuma_code v0.2.0 launched

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 退出程序

#tag 快捷指令

用 #标签 快速注入预定义指令,一次定义多次复用

💡

什么是 #tag

自定义标签是用户定义的快捷指令,在输入中使用 #标签名 即可展开为预设文本。

  • 输入 #zh 自动展开为「用中文回复」
  • 支持任意自定义标签,大小写不敏感
  • 标签可放在输入任意位置,解析后自动移除
  • 展开文本追加到输入末尾,供 LLM 理解
示例: #zh 冒泡排序时间复杂度 → 【用中文回复】 冒泡排序时间复杂度
⚙️

两种标签类型

系统标签控制行为模式,自定义标签注入预设指令,两者互补不冲突。

  • #plan_mode — 强制只分析不执行(优先级最高)
  • #skip_mode — 权限全跳过,工具直接执行
  • #自定义 — 用户定义的任意快捷指令
  • 同时输入 plan_mode 和 skip_mode 时以 plan_mode 为准
📋

/tag 命令管理

通过 /tag 命令添加、修改、删除和查看自定义标签。

  • /tag — 打开标签管理面板(TUI)或显示标签列表(CLI)
  • /tag add <name> <text> — 添加新标签
  • /tag mod <name> <text> — 修改已有标签
  • /tag rm <name> — 删除标签
  • /tag ls — 列出所有标签
🎯

典型使用场景

将常用指令封装为标签,提升对话效率。

  • #zh — 强制中文回复
  • #fix — 修复 bug 的标准指令
  • #review — 代码审查标准要求
  • #explain — 详细解释代码逻辑
组合使用: #plan_mode #zh 分析这个函数的性能瓶颈
💾

存储与配置

标签存储在 JSON 文件中,与 settings.json 同级目录。

  • 开发模式:./.niuma/custom_tags.json
  • 部署模式:~/.niuma/custom_tags.json
  • 简单键值对格式,key 自动小写
  • 原子写入,Windows 兼容
文件示例:
{
  "zh": "用中文回复",
  "fix": "fix the bug"
}
🔄

解析流程

输入经过三路分流,确保 LLM 理解、记忆召回、感知存储各取所需。

  • raw_input — 原始输入,供 trace 存储
  • llm_input — 标签展开后,供 LLM 理解
  • filter_input — 去掉标签前缀,供记忆召回
  • 记忆库不被标签污染,召回更精准