Nova-Code 使用手册

• ◆Agentic 编码循环 —— 给它一个目标，它自己读代码、改文件、跑命令，一步步把任务做完。同一轮里互相独立的工具调用以有界并发运行（默认每轮 3 个）。max_tokens 截断可自动续传（默认最多连续 3 次，可配），单次响应写不完不再是硬墙。
• ◆代码与系统工具 —— 文件 read / write / edit（文本、表格、PDF、图片都能读），glob + grep 搜索，bash（默认与上限均 3 分钟超时，run_in_background 转后台长任务），web fetch / search，向你提问。
• ◆LSP 代码智能 —— 直连语言服务器做 go-to-definition、find-references、hover、诊断、符号搜索，比 grep 更懂作用域和类型。
• ◆扩展 thinking —— 五档（off/low/medium/high/max）或显式 token 预算。
• ◆Plan 模式与子 agent —— 把庞大的调查/规划交给全新上下文的 worker，结论汇报回来，主对话保持干净。内置三种类型 + 支持自定义。
• ◆记忆、Skills、自定义命令、MCP、Hook —— 项目 / 用户级的知识与工具扩展；Shell 钩子在工具调用 / 用户提交 / 压缩等生命周期节点插入自定义逻辑。
• ◆多语言 —— 模型回复语言（language）与 TUI 界面语言（locale，内置 zh-CN / EN）分开配置，默认都跟随系统 locale。
• ◆权限与沙箱 —— 工作区信任门 + 基于规则的拦截 + OS 级文件写入隔离，三层防护。危险 bash 模式（rm -rf /、fork bomb、mkfs 等）直接拒绝，不可绕过。
• ◆可恢复会话 —— append-only 持久化，随时 --resume / --continue，/rewind 回到更早节点（含文件改动预览确认）。
• ◆国产模型深度定制 —— thinking 按各家 wire 形状映射（DeepSeek 的 output_config.effort、Kimi 的 thinking.type），请求结构对自动上下文缓存友好，错误码翻译与瞬时重试。模型按 lite/pro/max 三档配置（DeepSeek 内置默认：lite→deepseek-v4-flash-vision-exp，pro/max→deepseek-v4-pro，各档 thinking 深度不同），默认档位 pro，支持 /model 运行时切换。

环境要求：

• Node ≥ 20（仓库 .nvmrc 已固定）
• pnpm 10.28.2（packageManager 已固定）
• 交互模式需要真正的终端（TTY）渲染全屏 REPL；没有 TTY（管道 / 重定向 / CI / git hook）时不会报错，而是自动进入 headless 模式跑一轮后退出（见 §4）。

从源码运行：

pnpm install
pnpm dev                       # 启动 REPL（tsx 运行 apps/cli/src/index.ts）
pnpm dev "帮我给这个函数加单测"   # 先跑一轮 prompt，再进入 REPL
echo "总结这个 diff" | pnpm dev  # 无 TTY：headless 跑一轮后退出

第一次启动时，如果 ~/.nova/nova.config.json 里缺少 apiKey，Nova 会进入首次配置向导。它从内置 provider 模板里取一个（模板已填好 baseURL、默认档位，lite/pro/max 模型表则由 provider 的内置默认表提供），所以唯一要交互问你的就是 API key（输入时掩码）。

当前只有 DeepSeek 一个模板对外可选（Moonshot/Kimi 已内置但在内部测试期，暂从选择器隐藏；「Other provider」手填入口也暂时关闭）。既然只有一个 provider，向导会跳过选择器，直接问 DeepSeek 的 API key。它写入：

• provider: deepseek、transport: openai、baseURL: https://api.deepseek.com（DeepSeek 的 OpenAI 兼容端点）、默认档位 pro（以及 goal 配置和 key 本身）
• 模型表不写盘：lite→deepseek-v4-flash-vision-exp，pro/max→deepseek-v4-pro（三档靠 per-tier thinking 拉开梯度）来自代码里的内置默认

按 Ctrl+C 可中止向导。apiKey 已存在则跳过向导；导出了环境变量 NOVA_API_KEY 且配置里已有 models 表时同样跳过（只有环境变量、还没有 models 表时，向导仍会跑，但不再问你 key，也不会把这个 key 写进配置文件）。要接别的端点，直接手动编辑 ~/.nova/nova.config.json —— provider 与传输协议（transport）是两个独立维度：同一家供应商（如 DeepSeek）可同时有 Anthropic 兼容端点（https://api.deepseek.com/anthropic）与 OpenAI 兼容端点（https://api.deepseek.com），换协议只需改 transport + baseURL，DeepSeek 的错误翻译 / 余额探针 / 文档链接原样保留。通用档 other（通用 Anthropic 兼容端点）无内置档位表，需按 lite/pro/max 三档骨架填全，完整字段见 §20。OpenAI 兼容端点不设独立 provider：在现有供应商 profile 上把 transport 设为 "openai" 即可。

nova [prompt...]                   # 先跑一轮初始 prompt，再留在 REPL
  -p, --prompt <text>              # 无头模式：跑单轮后打印结果退出（不进入 REPL）
  -m, --model <tier>               # 临时切换模型档位（只认已配置档位名，如 lite/pro/max）
  -t, --think off|low|medium|high|max   # thinking 等级，或正整数 token 预算
      --max-turns <n>              # 单轮最大循环次数
      --cwd <dir>                   # 工具的工作目录（工作区根）
      --resume <id>                 # 恢复指定 id 的 session
  -c, --continue                  # 恢复最近一个 session
      --no-transcript             # 本次不写 transcript
      --no-pretty                 # 关闭 pretty 日志
      --output-format text|json|jsonl  # headless 输出格式（默认 text）
      --permission-mode default|acceptEdits|auto|plan  # 初始权限模式（默认 auto）
      --dangerously-skip-permissions    # 自动批准所有权限提示（无头模式等效 allow）
  -v, --version                   # 打印版本后退出

子命令（各自独立，不进 REPL）：

nova doctor                        # 体检全局配置并打印报告（同 REPL 内 /doctor）
nova mcp …                         # 管理 MCP 服务器（连接测试、认证等，见 §16）
nova plugin …                      # 安装 / 启停 / 列出插件（见 §18）
nova upgrade                       # 跑配置里的安装器升到最新版（见 §19）

要点：

• 位置参数即初始 prompt：nova 把 README 翻译成英文 会先跑这一轮，再停在 REPL 等你继续。
• -p / --prompt 是无头模式：传了这个 flag，Nova 跑一轮后直接打印结果并退出，不进入交互式 REPL。如果 stdin/stdout 不是 TTY（管道、重定向、CI），也会自动进入无头模式。用 --output-format json 可以拿到结构化 JSON。
• -m / -t / --max-turns 都是本次会话的临时覆盖，不写回配置文件。
• --cwd 决定工具的「工作区根」—— 读写权限、沙箱写入范围、工作区信任判定都以它为基准（见 §10）。
• 首次在某个目录启动会先问「是否信任这个文件夹」；headless 弹不出确认框，未信任的工作区直接失败退出（见 §10）。
• --permission-mode 启动时直接设定权限模式（REPL 内也可用 Shift+Tab 切换）。--dangerously-skip-permissions 对所有权限提示自动批准，适合无人值守场景。
• session 列表 在 REPL 内用 /resume（不带参数）的交互式选择器查看，无独立 CLI 参数。

Nova 是一个全屏 Ink/React REPL：顶部是滚动的历史区，底部是固定的输入框和实时状态行，支持流式输出、鼠标滚动与选区。

全局按键

把图片文件拖拽到终端窗口上同样有效 —— 路径会被规范化成绝对路径并当作附件插入。图片能否真的送进模型，取决于当前档位是否支持图像输入（见 §9 read）。

输入框编辑键（emacs 风格）

选择类弹窗（审批、提问、session 选择器）

• 上下移动：↑/↓，或 j/k（审批框），或 Ctrl+P/Ctrl+N（选择器）
• 确认：Enter；取消/拒绝：Esc
• 多选题用 空格 勾选
• 审批框还支持 PageUp/PageDown 滚动周围视口，方便先看清要批准的内容

@path 文件引用补全

在输入框里打 @ 开头的词，会弹出工作区文件路径补全。文件清单与 glob/grep 看到的一致：遵守 .gitignore（逐层向仓库根收集）、跳过 node_modules/.git、不含隐藏文件，最多 10000 条。

排序由具体到宽泛：文件名前缀命中 > 文件名内含 > 整条路径内含，同分则短路径优先。↑/↓ 选择、Enter 或 Tab 补全 —— 补全只替换那个 @… 词，不会提交。命令行（/ 开头）上只弹 slash 命令补全，不触发 @。

! shell 直通

以 ! 开头的一行不作为 prompt 发给模型，而是直接在 shell 里跑（输入框边框会变绿提示）。它复用 bash 工具：同样在工作区根执行、同样受 OS 沙箱约束（见 §11），输出以一张卡片贴回历史区，Esc 可中断。因为是你自己敲的命令，不走权限门。

命令跑完后，这次执行会以 <bash-input> / <bash-stdout> / <bash-stderr> 三段记录进入上下文，并立刻触发一轮模型回应 —— 所以 ! git diff 之后可以直接接「解释一下上面的改动」，模型已经看过了。这条记录标为 synthetic，历史区不会因此多出一个用户气泡（! 卡片已经展示了这次执行）；Esc 中断的命令和空的 ! 都不入上下文、也不触发回合。

它和 / 命令行一样带本地副作用，所以即使在回合运行中键入也始终排队、由 REPL 在空闲时派发 —— 不会被 queue.consumeInLoop 折进当前回合（见 §20）。

状态行

输入框下方两行实时状态：

• 第一行：模型档位 + 思考等级 + 上下文窗口、上下文占用进度条与百分比、工作区目录名、git 分支、完整 cwd。
• 第二行（用量）：账户余额（仅接 DeepSeek 官方 API 时出现；账户不可扣费时转为琥珀色）、缓存命中率、累计输入 / 输出 token。花费估算不再上状态行（价格变动频繁，过期的估算比不显示更糟），改由 /usage 查看。终端过窄时从右往左丢弃分段，余额和命中率优先保留。
  • 缓存分段给两个数字：缓存 90% 会话 99% 累计 —— 前者是本会话（从 transcript 重放，扛得住重启和 /resume）的命中率，后者是跨会话累计的命中率，/clear、换会话、重装都不归零。累计值记在 ~/.nova/usage.json（每请求批量累加、原子写，多个 nova 进程会各自并入而不是互相覆盖），而不是启动时去扫 ~/.nova/sessions/* —— 旧会话目录会被 sessionCleanup.maxAgeDays 清掉，扫出来的历史本来就不全。哪一半还没有数据就只显示另一半。

界面语言（i18n）

• settings.language 决定模型回复语言（注入 system prompt），默认 auto —— 跟随系统 locale（$LC_ALL/$LANG/$LANGUAGE，macOS 还会读 AppleLocale）。
• settings.locale 只覆盖 TUI 静态文案（菜单、提示、状态行），默认 auto 即跟随 language。内置 zh-CN 与 EN 两套文案，不认识的标签一律回落到英文。
• 两者可以不同 —— 比如中文界面 + 英文回复：{"locale": "zh-CN", "language": "en"}。改动需重启生效（语言写进 system prompt，会话中途变更会击穿前缀缓存）。

输入预测

每成功跑完一轮，Nova 会用主模型预测你下一句可能想说什么，作为输入框的灰色占位提示（默认开启，超时 8s，最多 300 字）。用 /predict on|off 开关，或在配置里调 predict。

在输入框里以 / 开头即触发。内置命令永远优先于自定义命令。

Nova 把「extended thinking」暴露成五个等级，或一个显式的 token 预算。在 DeepSeek 上，等级映射到 output_config.effort（而不是 Anthropic 的 budget_tokens）。

• 五档：off / low / medium / high / max
• 显式预算：传一个正整数（如 -t 4096），它会覆盖等级映射，直接当作 budget_tokens

思考等级是 per-tier（按档位）的属性，没有全局 thinking 配置项 —— 它写在 models.<tier>.thinking 里，切档（/model）会把当前思考等级换成该档的值。这也是 lite/pro/max 能在同一个模型 id 上拉出能力梯度的原因（DeepSeek 内置默认：lite→low、pro→high、max→max）。档位没写 thinking 时回退到 max。

设置方式：

• 启动时：nova -t high "..." 或 nova -t 4096 "..."（本次会话临时覆盖）
• 运行时：/effort high（查看用 /effort）—— 写回当前档位，本会话内生效
• 持久：改配置里该档的 models.<tier>.thinking

子 Agent

模型可以用 createSubAgent 工具把活儿派出去。子 agent 在进程内运行，带全新上下文（永远看不到父对话），工具集是父 agent 的工具减去 createSubAgent 本身 —— 所以不会递归。内置类型：

同一轮里的多个 createSubAgent 调用会并发执行（受 toolConcurrency 限制）。父 agent 只会收到每个子 agent 的最终一条消息 —— 庞大的中间调查被挡在主上下文之外。

通过 settings.subagent 配置：enabled / model / maxTurns（默认 5000）/ maxTokens（默认 32768，独立于顶层的每响应输出上限）。model 是一张按子 agent 名索引的表（如 {"plan":"max","explore":"pro"}），可给每个 agent 单独指定模型档位；解析顺序由具体到宽泛：该表的对应条目 → 内置默认（general-purpose/plan→max，explore/nova-code-guide→pro）→ 自定义 agent 自己 frontmatter 里的 model → 当前主模型；整张表省略则全部沿用默认。每个子 agent 的 transcript 落在 ~/.nova/sessions/{id}/subagents/。

自定义子 Agent 类型

除三种内置类型外，你还能用 .md 文件定义自己的子 agent 类型。文件包含 YAML frontmatter 和正文（system prompt）：

• 项目层：.nova/agents/（兼容 .claude/agents/）
• 用户层：~/.nova/agents/（兼容 ~/.claude/agents/）

Frontmatter 字段：

• /agents 列出当前可用的全部子 agent 类型及来源；/agents reload 改完文件后重新扫盘。
• /agent <name> <task> 把一项任务直接委派给指定的子 agent 类型。
• 发现目录可用 settings.subagent 的 projectDirs / userPaths / extraDirs 覆盖。
• 优先级：内置类型永远赢 → 项目层覆盖用户层 → 同层先到先得。

/plan 命令

/plan <goal> 是上面机制的一层薄封装：它让 agent 派生一个 plan 子 agent，对目标做只读调查，然后返回一份分步实现计划 —— 动手改动之前先看清楚要做什么。

下面是模型可调用的全部内置工具。标 只读 的默认自动放行；标 需批准 的默认走权限引擎询问（见 §10）。

文件与文本

搜索与发现

Web

代码智能

与用户交互

模型自己进出 plan 模式这套由 planMode.agentTools 控制（默认开）。关掉后这两个工具不再注册，plan 模式就只能靠 Shift+Tab 或 --permission-mode plan 手动进。子 agent 永远拿不到这两个工具 —— 它跑在主会话里，不该去改主会话的权限模式。

不过退出 plan 模式并不依赖模型调 exitPlanMode：只要一轮结束时还在 plan 模式，nova 自己就会弹那个确认框（planMode.approvalGate，默认开），见 §10。

计划管理：Todo（会话内，内存态）

createTodo / updateTodo / getTodoList / clearTodoList —— 把多步计划外化成一张清单，只存内存，进程退出即丢。任一时刻最多一个 todo 处于 in_progress。全部完成后清单会在 todo.autoClearDelayMs（默认 2.5s，留一拍让你看到那排 ✓）后自动清空，不指望模型自己去调 clearTodoList。

计划管理：Task（工作区内，落盘持久）

createTask / updateTask / getTaskList / clearTaskList —— 更大、值得跨会话保留的计划，落盘到工作区的 .tasks/{id}.json。支持 blockedBy 依赖关系，允许多个并行 in_progress。整份计划做完后同样会在 task.autoClearDelayMs（默认 2.5s）后自动清空并删掉对应的 .tasks/ 文件。

定时调度：Cron（会话内，落盘持久）

定时条目落盘在 ~/.nova/sessions/{id}/cron/，/resume 时重新装载并重排，/clear 时清空。只有会话活着时才会触发（没有后台守护进程）—— 到点的 tick 若正好有回合在跑，会等 REPL 空闲后立刻补跑，不重叠堆积。三个工具本身默认放行（只登记元数据），但排定的 payload 真正动手时仍在触发那一刻走完整权限门。/loop 就是基于这套机制的薄封装（见 §6）。配置见 §20 cron.*。

后台长任务

后台命令没有专门的读取工具：output_path 指向 ~/.nova/sessions/{id}/background/{命令id}.log，这是命令 stdout+stderr 的完整日志，用普通的 read / grep 跟读即可（该目录已默认放行，不会每次弹权限）。

monitor 与后台命令的分工，按「你要被通知几次」划分：只要一次（构建结束、服务起来了）用 bash + run_in_background 配一个条件满足就退出的命令；每次发生都要才用 monitor。过滤写在命令里（grep -E --line-buffered）且必须覆盖失败——只匹配成功标记的过滤器在崩溃时同样沉默，而沉默和「还在跑」无法区分。stderr 不是事件流，只进 log_path。超过 settings.monitor.maxEventsPerWindow（默认 60 条/分钟）的监听会被直接杀掉并在通知里说明。

命令结束时会由 <background-notification> 自动注入一条公告——只带 id、状态、退出原因和日志路径，不内联输出。这样输出只有一条投递通道（文件）：若通知里也内联一份，模型自己 read 过的内容就会被重复推送一遍，而且一个跑久的 dev server 结束时可能一次性往 append-only 历史里灌进上百 KB。状态和退出原因留在通知里，已经足够模型判断要不要再花一轮去读日志。

Skills 与子 Agent

工作区信任（启动前的第一道门）

在任何工具能跑起来之前，Nova 先确认你允许它访问当前这个文件夹。首次在某个目录启动时会占满屏幕弹一张确认卡片，选 Yes 才继续，选 No / Esc 直接退出。

• 信任记录写在用户全局配置 ~/.nova/nova.config.json 的 trust.trustedRoots（绝对、符号链接已解析的路径），从不写进项目内的文件 —— 所以 clone 下来的仓库无法把自己标记为可信。
• 判定是包含关系：工作区等于或位于某个已记录根之下即视为可信，因此信任仓库根即覆盖其所有子目录。
• 家目录例外：对 ~ 授予的信任只在本次会话有效，不落盘。
• headless（-p / 无 TTY）没法弹确认框，所以未信任的工作区是硬性拒绝：先交互式跑一次并信任、或手工把路径加进 trust.trustedRoots、或传 --dangerously-skip-permissions 绕过。
• 写配置失败不会中断会话（你已经同意了，本次有效，只是下次还会再问）。设 trust.enabled: false 可恢复「启动即信任」的旧行为。

权限引擎

权限引擎（@nova/safety 的 PermissionEngine）是模型与文件系统之间的一道闸门。每次工具调用按下面的顺序裁决：

1. 1危险 bash 直接拒绝。命令若匹配内置危险模式（rm -r /、fork bomb、mkfs、dd if=… of=/dev/…、重定向到块设备），立即 deny，无法绕过。
2. 2运行时放行表。你在审批时选过「Always allow this tool」的，记在内存里，本 session 内同工具直接放行。
3. 3配置规则（首个匹配生效）。按顺序遍历 permissions.rules，第一条命中的决定结果。
4. 4默认效果兜底。都没命中就用 permissions.defaultEffect（默认 ask）。
5. 5出错降级为 ask。规则求值若抛异常（坏正则等），降级为询问而非崩溃或拒绝 —— 让你始终掌握控制权。

权限模式（Shift+Tab 切换）

输入框右下角有一个权限模式指示，按 Shift+Tab 在四档间循环（bypassPermissions 仅在 --dangerously-skip-permissions 启用后才加入循环）。不指定 --permission-mode 时，启动即为 auto。它在权限引擎之前介入，临时改变写类工具的裁决倾向 —— 只影响当前会话、不写盘：

默认放行 vs 默认询问

• 默认放行（只读或仅登记元数据的）：read/glob/grep（限定在工作区内）、webfetch、websearch、askUserQuestion、lsp、loadSkill、createSubAgent、killBackground、todo 全套、task 全套（含写操作）、cron 全套（cronCreate/cronList/cronDelete）、enterPlanMode/exitPlanMode。task/cron 的写只改自己的清单 / 排程，payload 真正动手时仍走权限门；plan 两件套同理 —— 进只收权，出自带一道确认。
• 默认询问（会改文件 / 跑命令的）：write、edit、bash（前台和 run_in_background 一视同仁） —— 落到 defaultEffect（默认 ask）。
• permissions.deny（裸工具名数组）更硬一档：列进去的工具启动时从注册表摘除，模型看不到也调不了（区别于 rules 里 effect: "deny" —— 后者仍把工具报给模型、只在调用时拒）。系统提示里与这些工具绑定的那段说明也会一并消失 —— 摘掉 loadSkill 就不再注入 skills 索引，摘掉 todo 那套就不再讲清单纪律。模型不会被教着去用一个它没有的工具。

读操作被限定在工作区

read/glob/grep 的路径在裁决前会被规范化（resolve + realpath），再检查是否落在「工作区根」内：

• 工作区根 = --cwd（或当前目录）+ permissions.additionalDirectories 里列出的目录。
• .. 穿越、符号链接逃逸都会被折算成真实路径后再判断，因此 ../../etc/passwd、link→/etc 这类逃逸会被正确拦下。
• glob/grep 不带 path 时自动注入工作区根，所以无参搜索默认就在工作区内。

交互式审批

自定义权限规则

在 ~/.nova/nova.config.json 的 permissions.rules 里写规则数组，每条形如 { tool, effect, match? }：

• tool：工具名，或 "*" 匹配任意工具
• effect：allow / deny / ask
• match（可选）：对输入字段的匹配条件，支持精确值 { "command": "ls" }、正则（用 /.../ 包裹）{ "command": "/^npm test/" }、路径包含 { "path": { "within": [...] } }

示例：放行所有 npm test、拒绝带 --data 的 curl、其余一律拒绝：

{
  "permissions": {
    "defaultEffect": "ask",
    "additionalDirectories": ["/home/user/shared"],
    "rules": [
      { "tool": "bash", "effect": "allow", "match": { "command": "/^npm test/" } },
      { "tool": "bash", "effect": "deny",  "match": { "command": "/curl.*--data/" } },
      { "tool": "*",    "effect": "deny" }
    ]
  }
}

在权限引擎之上再叠一层 OS 级纵深防御：把会起子进程的工具（bash，前台和后台两条路径都算）放进操作系统沙箱里跑，把文件写入限制在工作区根内。底层是 @anthropic-ai/sandbox-runtime：macOS 用 Seatbelt（sandbox-exec），Linux 用 bubblewrap。

• 默认关闭（opt-in）。需显式设 sandbox.enabled: true 才开启（或会话内 /sandbox on）。开启后读放行；网络默认不限制（只管文件系统），但可选 network.allowedDomains / deniedDomains 收紧出站连接。
• 自动降级安全。仅 macOS / Linux 支持；不支持的平台或缺依赖（macOS 需 ripgrep；Linux 还需 bubblewrap/socat）会静默降级为不沙箱，agent 照常运行。
• 常见缓存默认放行。npm/pnpm/yarn/cargo/rustup/go/pip 等工具链缓存目录（~/.npm、~/.cache、~/Library/Caches、~/.cargo、~/.rustup、~/go、~/.local/share/pnpm、~/Library/pnpm、~/.yarn）、以及 ~/.config/gh（gh/PR 工作流下 token 刷新）已预置进白名单。显式设置 filesystem.allowWrite 会替换这组默认值。
• SDK 强制保护的危险路径。即使在工作区里也写不了：.git/hooks、.git/config、.vscode/、.idea/、.claude/{commands,agents}，以及 .gitconfig/.zshrc/.mcp.json 等 dotfile。

配置示例：

{
  "sandbox": {
    "enabled": true,
    "monitorViolations": true,        // 捕获越权写并标注到命令输出（macOS 起一个 log 监听）
    "filesystem": {
      "allowWrite": ["~/.npm", "~/.cargo", "/some/extra/dir"],  // 显式设置会替换默认缓存白名单
      "denyWrite": [".env"],           // 即使在允许根内也拒绝写
      "denyRead": ["~/.ssh"],          // 读默认放行，这里单独拒绝
      "allowGitConfig": true
    }
  }
}

历史是 append-only 的：每轮只往后追加新消息，从不改写更早的内容 —— 这既让持久化只做追加写，也让 DeepSeek 的自动上下文缓存前缀能持续存活。

max_tokens 截断自动续传：

• 当模型因 stop_reason: "max_tokens" 被截断且没有未完成的工具调用时，loop 会自动重新提示模型从断点继续 —— 长回复撞上该档 maxTokens 时不再半途而废。默认最多连续重试 3 次（maxTokensContinuations: 3），每次有实质性进展时计数器重置。设为 0 则回到旧行为：首次截断即硬停止。

auto 压缩（默认开）：

• 只在上下文窗口吃紧时触发。它不截断历史，而是往 append-only 历史里追加一条 <compacted> 摘要边界 —— 完整历史仍留在磁盘、TUI 里照旧全量渲染，只有喂给模型的视图缩短到「最后一条边界往后」。这是一次有意为之的「前缀重置」：边界之内前缀依旧稳定命中缓存，边界推进时才重置一次。可调 compact.auto.enabled / thresholdTokens / contextWindowPercent / maxSummaryTokens。
• 触发阈值默认是上下文窗口的 90%（contextWindowPercent，或用 thresholdTokens 钉死一个绝对值）。这个 90% 算的是整个请求 —— system 提示词、记忆、skills 索引、工具 schema，加上对话消息，和 /context 面板显示的口径一致。固定开销通常在一万多 token，窗口越小占比越高，所以把它计入触发判断是必要的：只按消息量算的话，128k 窗口下等阈值触发时真实请求已经超出窗口了。

手动压缩：随时 /compact，可附带关注点（如 /compact 保留关于鉴权的部分）让摘要更聚焦。

Nova 会像 CLAUDE.md 那样，把项目与用户级的记忆文件注入 system prompt。优先级与查找规则：

• 每个目录内，按 NOVA.md > CLAUDE.md > AGENTS.md 取最高优先级的那一个 —— 文件不合并。
• 项目层：从 cwd 向上递归到仓库根，每层各取一个。
• 用户层：依次找 ~/.nova/NOVA.md → ~/.claude/CLAUDE.md → ~/.config/agents/AGENTS.md，取第一个存在的。

文件名可通过 settings.memory.filenames 自定义；用户层 / 全局路径可用 memory.userPaths / memory.globalPath 覆盖。

自动记忆（agent 自维护，跨会话）

除了你手写的记忆文件，Nova 还维护一层 auto 记忆 —— agent 自己在工作中沉淀下来的事实，跨会话保留：

• 落在全局用户目录、按项目分目录：~/.nova/projects/<项目路径编码>/memory/（与 Claude Code 一致；可用 memory.auto.dir 改成工作区内路径）。里面是一个 MEMORY.md 索引，加上每条事实一个文件。
• 索引（MEMORY.md，每条一行）注入 system prompt，占很少 token；单条事实正文由 agent 按需 read。注入的索引条数上限 memory.auto.maxEntries（默认 100）。
• 这个目录归 agent 所有：其中的 read/write/edit 默认放行、不弹权限（见 §10）—— 沉淀一条学到的事实不该每次都问你。
• 默认放在全局用户目录、按项目标识分目录：记忆随项目走但不污染仓库；若想改为随项目 git 跟踪，把 memory.auto.dir 设为工作区内相对路径（如 .nova/memory）即可。用 memory.auto.enabled: false 关闭整层。

Skill 是「按需加载的专长说明书」。把 SKILL.md 放在：

• 项目层：.nova/skills/<name>/（兼容 .claude/skills/<name>/）
• 用户层：~/.nova/skills/<name>/（兼容 ~/.claude/skills/<name>/）

启动时 Nova 扫描这些目录，把每个 skill 的 name + description 索引注入 system prompt（只占很少 token），并暴露 loadSkill 工具。当某个任务匹配到某个 skill 时，模型才用 loadSkill 拉取完整正文。索引与工具是绑在一起的：skills.enabled: false、一个 skill 都没扫到、或把 loadSkill 写进 permissions.deny，索引和工具都会同时消失，不会出现「提示里列着技能、却没有工具去加载」的情况。

• 用 /skills 查看发现了哪些、各自来自哪里。
• 索引预算：默认取当前模型上下文窗口的 1%（按 4 字节 / token 折算），skills.indexBudgetFraction 可调。200k 窗口约 8000 字节，1M 窗口自动放大到 40000。想钉死一个绝对值就设 skills.maxIndexBytes，它优先于比例。
• 索引里单条描述的上限：skills.maxDescriptionBytes（默认 1536 字节，超出以 … 标记）。这只影响索引条目，SKILL.md 里的完整 description 不受影响。
• 超预算时不会丢技能，而是把条目降级成只剩名字（- name），按代价从小到大尽量多保留描述。名字还在就仍然能被 loadSkill 调起，而完整正文本来就要靠 loadSkill 拉。
• 响应大小上限：skills.maxResponseBytes（默认 16KB）。
• 单个 SKILL.md 的磁盘上限：skills.maxFileBytes（默认 1MB）。超限的文件在 stat 阶段就被跳过并 warn，不会读进内存。
• 技能目录可以是符号链接（用来在多个 checkout 之间共享同一份技能），会被正常跟随；链接指向非目录时静默忽略。

Front-matter：只有三件事会让一个 SKILL.md 被拒收 —— 缺 --- 块、缺 name（必须匹配 ^[a-z][a-z0-9-]*$）、缺 description。Nova 认得的字段：

其余字段（allowed-tools、hooks、model 等）会被解析后忽略，不会导致加载失败 —— 这样为其它 agent 运行时写的技能可以原样放进来。front-matter 走标准 YAML 子集：嵌套映射、块序列、[a, b] / {a: 1} 流式集合、| / > 块标量、折行的多行标量、# 注释都支持。

两条调用路径：

两条路都经由同一个渲染函数，模型看到的文本逐字节一致 —— 一个技能不会因为「谁调它」而表现不同。/{name} 每次调用都重新读盘，所以改完 SKILL.md 直接再敲一次就生效，不用 /commands reload（那个只在增删技能目录时才需要）。

正文里的变量与插值：按顺序做四层展开，和自定义 slash 命令用的是同一套实现。

不认识的 ${NAME} 原样保留（别的工具的变量不会被抹成空），小写的 ${name} 完全不动（JS 模板字符串示例不会被误伤）。取不到值的变量（非插件技能的 ${CLAUDE_PLUGIN_ROOT}、无会话时的 ${CLAUDE_SESSION_ID}）同样保持原样而不是变空，这样「不适用」和「解析成空」能区分开。展开顺序是变量 → 参数 → @ → !，每层的产物喂给下一层，所以 @${NOVA_SKILL_DIR}/ref.md 和 !`grep $1 file` 都能用。

除了内置命令，你可以用 .md 文件定义自己的 slash 命令：

• 项目层：.nova/commands/（兼容 .claude/commands/、.commands/）
• 用户层：~/.nova/commands/（兼容 ~/.claude/commands/）

规则：

• 每个 *.md 文件名即命令名（deploy.md → /deploy）。
• 文件前置 frontmatter 声明 description / arg hint / 参数；正文做占位符替换后，作为下一轮 prompt 发给模型。
• 正文支持的参数写法：{{name}} / {{name|默认值}}（Nova 原生）、$ARGUMENTS、$ARGUMENTS[n]（0 起）、$1..$N（1 起，$1 是第一个）、$name（取 args: 声明的具名参数，和 {{name}} 同源同值）、\$ 转义。另外还有 @路径 内嵌文件和 !`命令` 插值。
• 没被占位符消耗掉的参数会以 ARGUMENTS: ... 追加到末尾，而不是被丢掉——按 token 逐个算账：正文只写了 $1、你敲了两个词，第二个词照样会追加上去。（{{name}} 声明式参数例外：声明列表总会吃掉全部参数，所以只要 {{}} 命中过就不再追加。）
• 优先级：内置命令永远赢；项目层覆盖用户层（同名时）。
• 改了文件后用 /commands reload 重新扫盘，/commands（或 /help）查看当前注册了哪些。

通过 settings.slash 可调整开关与额外目录（projectDirs / userPaths / extraDirs）。

Nova 可在启动时连接外部 MCP 服务器，把它们的工具以 mcp__<服务器>__<工具> 的形式暴露给模型，并走正常权限引擎（默认 ask）。服务器原生的 JSON Schema 原样转发，工具契约不变。

支持两种传输：本地子进程走 stdio，远程端点走 http / sse。在 ~/.nova/nova.config.json 的 mcp.servers 下配置：

{
  "mcp": {
    "enabled": true,            // 总开关（默认 true）
    "timeoutMs": 60000,         // 单次工具调用超时
    "servers": {
      "filesystem": {           // stdio（type 默认 "stdio"）
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
        "env": { "FOO": "bar" }
      },
      "remote": {               // http / sse
        "type": "http",
        "url": "https://example.com/mcp",
        "headers": { "authorization": "Bearer …" }
      },
      "scratch": { "command": "…", "enabled": false }   // 单独跳过某个服务器
    }
  }
}

各服务器并行连接；某个连不上只会记日志并跳过 —— 不阻塞启动、不影响其它服务器。/mcp 打开一个菜单（认证 / 重连 / 登出，查看状态和工具数），/mcp tools 列出所有桥接的工具名；shell 里也有 nova mcp 子命令。

OAuth（远程服务器鉴权）

对以 401/403 挑战的远程 http/sse 服务器，Nova 支持 OAuth 2.0（authorization-code + PKCE）：

• 给该服务器加一个 oauth: {} 块（可选 scope）即启用；mcp.oauth.autoDetect（默认 true）还会把任何 401/403 的远程服务器自动标记为「需认证」，即便没写 oauth 块（用静态 Authorization 头的服务器豁免）。
• 首次在 /mcp 菜单里选 Authenticate 会打开浏览器走授权；回调由固定的本地端口接收（mcp.oauth.callbackHost/callbackPort，默认 127.0.0.1:7777）。
• token 持久化在 ~/.nova/mcp-auth/，之后的会话静默刷新，无需再次登录。

lsp 工具让模型直连语言服务器（JSON-RPC over stdio），拿到比 grep 精确得多的导航 —— 它懂作用域和类型。一个工具，六个 action：

• 坐标对模型是 1-based（行、列），内部自动转成 LSP 的 0-based。
• 工具只读，权限引擎默认放行。

语言服务器在首次 lsp 调用时按需懒启动，所以「已安装但未启动」是正常状态。用 /lsp 查看每种语言：二进制是否在 PATH（● running / ○ installed / ● not installed）以及本 session 是否已起。

在配置 lsp.servers 里可覆盖 / 扩展内置表（按 languageId 匹配；同名整条替换，未知则追加），还可调三个超时：initTimeoutMs / requestTimeoutMs / diagnosticsTimeoutMs。

插件把可复用的扩展打包成「一个目录 + 一份 manifest」，一条命令即可安装、启停、分发。纯声明式 —— 不执行任何插件代码，只是把目录里的扩展登记进来。格式兼容 Claude Code 插件。

Manifest 位于 .nova-plugin/plugin.json（优先）或 .claude-plugin/plugin.json（回退，二者不合并）。一个插件可同时贡献：

• slash 命令、子 agent、skills、生命周期 hooks —— 与你手写的 .md 扩展（§14/§15）同源，只是随插件一起分发；命令 / agent 名以 <插件名>:<名字> 命名空间化。
• MCP servers、LSP servers —— 桥接进 §16/§17 的同一套机制。
• bin/ 可执行文件 —— 其目录被加进 PATH，供 bash（及沙箱）调用。

用 nova plugin 子命令从 shell 管理（它编辑 ~/.nova/nova.config.json 的 plugins 块）：

恢复与切换

• nova -c / nova --continue：恢复最近一个 session。
• nova --resume <id>：按 id 恢复。
• REPL 内 /resume [<id>]：切到指定 session（不带参数则弹交互式列表选）。

回退（Rewind）

/rewind [<n>] 回到此前某条消息 —— 其后的对话历史与文件改动都会被丢弃，相当于一个检查点回滚。

自动清理

启动时 Nova 会删掉最近活动超过 sessionCleanup.maxAgeDays（默认 30 天）的 session 目录（按文件最新 mtime 算「最后一次使用」，不是创建时间；当前活动 session 始终受保护）。设 sessionCleanup.enabled: false 可永久保留。

版本更新

• 启动检查（只提醒，不安装）：交互启动时（限流地）比对 npm 是否有新版，有则提示 —— 从不自动安装。节流状态记在 ~/.nova/update-check.json，间隔 update.checkIntervalHours（默认 24h）；设 update.enabled: false 静音。
• 手动升级：nova upgrade 跑 update.command（默认 npm install -g @asathinkeroops/nova-code@latest --registry https://registry.npmjs.org，可改 pnpm/yarn/bun 全局安装）。默认命令显式指定 npmjs 官方源，与版本检测查询的 registry 一致——如果你的 npm 配置了未同步的镜像（npm config get registry 可查），裸命令会"成功"装回旧版。安装后 nova upgrade 会校验磁盘上的实际版本，装到旧版时会明确报错而不是宣称成功。nova --version 打印当前版本。

数据落在哪

配置文件位于 ~/.nova/nova.config.json，是一份 JSON。下面列出全部字段及默认值（来自 zod schema，每个可配项都有默认值，缺省即用默认）。

顶层与模型

permissions

planMode（plan 模式的进出）

trust（工作区信任）

思考等级（thinking）

没有顶层 thinking 配置项 —— 思考等级是 per-tier 的，写在 models.<tier>.thinking（off/low/medium/high/max；缺省回退 max）。-t/--think、/effort 是会话内覆盖，见 §7。

compact

invariants（工具不变量，dispatcher 强制）

界面与体验

pricing — 成本估算

background / queue — 后台命令与输入队列

hooks — Shell 钩子

持久化

扩展子系统