每个仓库各自维护 harness
将 .claude/ 从一个项目复制到另一个项目，手动同步既费力又容易出错。
开源 · 六种引擎
多智能体 harness 适用于任何代码仓库。
智能体、技能、钩子、权限和记忆统一保存在一个配置中，用一条命令即可重建。渲染到 Claude Code、Codex、Cursor、Copilot 和 AGENTS.md，同时保留你的自定义内容。
$
npx navori init
MIT
Node ≥ 22.12
0 runtime deps
Claude Code
$ navori init --recommended
✓ stack: Next.js · pnpm
✓ engines: claude · codex
✓ plugins: engram · gh
→ 正在渲染受管理资源
✓ CLAUDE.md · AGENTS.md
✓ .claude/ agents · skills · hooks
✓ .claude/settings.json 权限
✓ 完成 — 创建 34 个 · 覆盖 0 个
29 命令 13 预设 5 插件 6 引擎 8 智能体 66 技能
MIT Node ≥ 22.12 零运行时依赖
v0.12.2
一次会话的结构
跟随提示词走完整个 harness
没有 harness，模型只能独自决定如何处理你的请求。navori 在这条路径上设置八个站点：从一句话到提交，再将决策存回记忆。
你的提示词
修复客服报告的登录错误
你输入一句话，模型还未开始思考。
模型读取提示词之前，启动钩子已经运行。这让助手开启会话时就了解当前状态，无需每天从零开始。
导览自动播放，点击站点即可跳转。
问题
每个仓库都在重复造轮子
如果你同时维护多个项目并使用 AI 智能体，就会熟悉这些问题。
每种引擎各自维护配置
Claude 使用 .claude/，Cursor 使用 .cursor/，Copilot 使用 .github/copilot-instructions.md。同样的意图分散在三个文件。
SDD 逐渐失效
如果无法版本管理和持续更新，技能、钩子与规格驱动开发约定就会逐渐偏离。
作用域
harness 不再局限于单个仓库
两个可叠加的作用域，均需主动启用。工作区在仓库配置上增加规则，同时保留仓库能力。
每个仓库
仓库
提交到版本库的 navori.config.json 是唯一事实来源。render 据此幂等重建 CLAUDE.md、.claude/ 和 progress/，同时保留你的内容。
navori.config.json
navori init 每个组织
工作区
组织级默认值，包括质量关卡、基础分支与约定，以及 Dominio：跨仓库的持久事实，如数据模型、服务间契约和共同注意事项。
~/.navori/workspaces/<org>/
navori workspace · navori dominio 未启用就没有额外足迹：不运行对应的 init，navori 就不会在仓库外写入任何字节。
工作原理
五层级联，一个事实来源
每层叠加在前一层之上，由你决定项目层面的控制程度。
- navori
核心
navori 管理的基线：智能体、技能、钩子和规则块，始终存在。
- preset
预设
面向 Next.js、NestJS、Astro、Expo、Medusa、monorepo 等技术栈的默认值。没有适合的？用 `navori preset init` 创建本地预设。
- org
工作区
跨仓库共享的组织规则，以及工作区 Dominio。
- you
项目
navori.config.json 中属于本仓库的设置：质量关卡、关键区域、旧代码路径与启用的插件。
- engine
适配器
通过同一流水线渲染为 Claude Code、Codex、Cursor、Copilot 和 AGENTS.md 的原生格式。
navori.config.json
source of truth
{
"$schema": "https://ulisescm.github.io/navori-harness/schema/navori.config.v1.json",
"name": "your-app",
"engines": ["claude", "codex"],
"preset": "nextjs",
"branchBase": "main",
"commits": "conventional-es",
"qualityGate": {
"full": "pnpm lint && pnpm test"
},
"plugins": {
"engram": { "enabled": true },
"codegraph": { "enabled": true },
"tgrep": { "enabled": true },
"gh": { "enabled": true }
},
"project": {
"criticalAreas": ["auth", "billing"],
"legacyPaths": ["src/legacy"]
},
"audit": { "mode": "always" }
} 交互演示
查看每一层的作用
点击层级即可高亮它生成的内容。适配器将结果转换为各引擎的原生格式。
选择一层，查看它添加的内容。
引擎适配器 → .claude/ + CLAUDE.md
output
CLAUDE.md
- idioma-rol · formato-respuesta · tipado-fuerte · cierre-sesion core
- engram-protocol project
.claude/agents/
- orchestrator · implementer · reviewer · scout · … core
.claude/skills/
- verify-before-done · debug-failure core
- nextjs-app-router · nextjs-data-fetching preset
.claude/settings.json
- permisos + hooks base core
- hooks de plugins (engram, gh) project
.claude/hooks/quality-gate-pre-commit.sh
- qualityGate.fast heredado workspace
progress/
- current.md · history.md core
工具箱
navori 教智能体如何使用工具
每个插件包含技能、协议块、权限与 doctor 检查。启用需要的插件后，harness 就知道何时使用、何时无需使用。
acli 外部 Jira
使用正确账户，通过 acli 读写任务。任务接收从原始工单开始，无需手动粘贴描述。
codegraph 搜索 按结构搜索
本地仓库 AST 图：符号在哪里、谁调用它、修改后影响什么。一次查询替代多轮文本搜索与文件阅读。
engram 上下文 持久记忆
决策、根因与约定在会话结束和上下文压缩之后仍然保留。下周无需重新解释上周决定的事情。
gh 外部 GitHub
通过 gh 管理 issue、PR 与检查。智能体读取任务，按仓库格式创建 PR，并理解失败的 CI。
tgrep 搜索 按内容搜索
仓库的三元组索引，查找包含指定文本的文件，保留退出码契约，无需适配机器上的搜索引擎。
navori 生成 harness，不替智能体运行 grep、测试或 linter。它规定使用什么工具及遵循什么规则，实际执行由对应角色负责。
可观测性
能够审计自身的 harness
写规则容易，确认是否执行很难。navori audit 回答两个问题：token 花在哪里，哪些指令没有得到遵守。
$ navori audit --session latest◇ navori-harness · 2026-09-12 ─────────╮│ 1 sesiones · 19 agentes ││ facturable 2.3M tok ││ arranque 346k tok ││ hallazgos 1 alto · 3 medio │╰──────────────────────────────────────╯→ report.md · report.json
token 的去向
区分计费、启动与各智能体用量，让 harness 成本从猜测变为可优化的数据。
未被执行的指令
按严重程度报告真实路由问题：忽略的技能、高成本搜索路径，以及没有发生的委派。
三种互不可替代的来源
钩子事件日志记录 harness 行为；会话记录保存 token；宿主 OTel 事件记录权限批准与活跃技能。
逐会话主动启用
没有提前运行 --start，就没有可审计日志，navori 也不观察任何活动。Markdown 与 JSON 报告保存在 ~/.navori/audits/；--snapshot/--compare 用于对比区间，只描述结果，不宣称改进。
命令
完整生命周期，逐个命令讲解。
按实际使用时机对 CLI 注册的所有子命令分组。每个命令都有独立参考页。
开始
渲染与更新
- navori render 从 navori.config.json 幂等重建所有配置引擎，默认预览。
- navori sync 将资源包变化同步到所有已配置引擎，保留你的修改。
- navori update 将 navori CLI 更新到 npm 最新版本，再用新可执行文件运行 navori refresh。
- navori refresh 一步更新：重新检测仓库，提供配置差异，再运行 sync。
- navori migrations init 以 replace 模式采用 navori 时备份原 harness，可恢复。
- navori backup 每次 sync 或 render 修改文件前，在 ~/.navori/backups/ 创建快照。
操作
- navori doctor 审计项目配置、插件、漂移、不变量并建议后续步骤。
- navori status 快速查看配置、插件、漂移及后续步骤，一条命令确认当前状态。
- navori scan 重新检测 monorepo，将 init 后新增的工作区加入配置。
- navori registry 机器上所有 navori 仓库的全局注册表，支持 render --all。
- navori bench 对 render 执行 N 次计时，报告 p50/p95，在提交前发现本地回归。
- navori codex 在 ~/.codex/config.toml 批准项目 Codex 钩子。项目受信任前 Codex 不加载仓库内容，包括 AGENTS.md。
- navori receipt 发布前签署或校验已审查的字节内容。
- navori gate 运行项目质量关卡，完整输出写日志，stdout 仅显示紧凑结论。
- navori plan 分类复杂度并校验工作计划（spec 0032）。
- navori spec 分类规格 tasks.md 并校验交付结构（spec 0044）。
- navori handoff orchestrator 派发下一角色前，校验 implementer handoff。
- navori master 项目主计划：管理阶段、流程、部分和闭环（spec 0034）。
多引擎
一个配置，六种引擎。
同一 harness 通过同一流水线生成各引擎原生格式。增加引擎只需声明式适配表，无需重写。
可用
Claude Code
.claude/
智能体 · 技能 · 钩子 · 带权限的 settings.json
Codex
.codex/ + .agents/skills/
自定义智能体 · 技能 · 钩子 · MCP 服务器
AGENTS.md
AGENTS.md
通用规范 · Cursor、Codex、Gemini 和 Copilot 均可读取
可用
Cursor
.cursor/rules/
.mdc 规则 · 项目上下文
可用
Copilot
.github/copilot-instructions.md
工作区指令
Pi
.pi/
扩展、智能体和钩子 · 需要 Pi >= 1.1.0
最新变化
逐版本了解变化
用清晰语言解释升级带来的变化。
- v0.12
Pi 成为一等引擎，更省成本的关卡，以及明确的迁移路径
- Pi 已加入 init 向导和 configure engines，与 Claude Code 的安全守卫和钩子达到同等能力；敏感动作需输入 yes, run it 批准。要求 Pi >= 1.1.0。
- 新增 navori gate <fast|full>，首行给出简要结论，完整日志保存在 .navori/state/gate/。qualityGate.scoped 只检查差异涉及内容，qualityGate.nativeHooks 避免重复执行。
- navori update 查询 npm，经确认安装最新 CLI，再运行原 update 所做的 navori refresh。没有兼容别名；脚本若以前用 update 刷新 harness，应改用 refresh。
- 破坏性移除：navori global、launchd 收集器、doctor --json 的 globalScope 以及 jscpd、semgrep 插件。运行 navori render --apply 清理属于 navori 的资源，再用 doctor 检查遗留内容。
- 最低 Node >= 22.12。progress/current.md 新增容量上限，钩子阻止智能体提交使其超限，doctor 给出警告；harnessVersion 作为防回滚下限。
重要补丁
- v0.12.1 — 修复计划分类、证据和升级流程，改善主计划，并新增 Codex 批准与配置控制。Codex 集成仍在验证中。
- v0.12.2 — 开发循环更快：门禁按内容标识复用结果并运行目标仓库的门禁，测试套件更快、钩子更轻。scribe 可并行运行（需主动启用），Codex 调度按会话隔离，当全局 CLAUDE.md 超出上下文上限或使用过时的工作区路径时，doctor 会发出警告。同时修复了进度上限、超限规格的完成、Pi 计划门禁诊断、CLI shebang 以及 reviewer 的真实 PR 基线。
- v0.11
每个 checkout 独立保存状态，并提供引导式主计划
- 临时状态按 checkout 存于引擎无关的 .navori/state/handoffs/。plan gate、plan check、receipt check 从此读取计划与收据，旧 .claude/progress/ 仅作为读取后备。需要关注这一迁移。
- Codex 向操作能力对等推进，但仍部分完成：默认权限、已校验钩子输出、交叉审查权限及建议式 plan-gate。
- 新增 master-plan 技能，通过独立规格引导大型工作分阶段执行。
- 新增 RabbitMQ 的 amqplib、适用于含 @mantine/core 仓库的 Mantine 模式，以及 Python 的 fastapi、pytest 技能，并检测 Python 开发依赖。
- pre-commit、semgrep、jscpd 不再对其他仓库的提交运行锚点仓库关卡；init 可推断已注册工作区。jscpd 仅阻止新增重复，并修复链接检查、收据、tailwind-v4 激活、插件额外变量与 init 共存。
重要补丁
- v0.11.1 — Claude 优先：不再生成 Claude Code 原生已有的内容；audit 支持区间和快照比较；新增搜索路由守卫、无法判定关卡时确认、Pi 支持和每日版本通知。
- v0.11.2 — Codex 对等能力（spec 0041）在 0.160.0 实测并给出保证表：角色与派发守卫、multi-agent V2 dispatch 文件、发布及 general-purpose 的拒绝式确认、master-plan/context-intake、tgrep 守卫和 Bash 重复失败建议。按本地目录 sol/luna/astra 自动解析模型；doctor 检查 worktree 信任和旧全局 navori；修复 navori:if 与孤立输出清理。
- v0.11.3 — 规格支持功能交付：spec classify/check、sdd.deliveries、交付/里程碑/任务、每 PR 一次 full，master-plan 同规则拆分。sync 可逐文件处理无标记文件，--accept-new-files 配合差异保留/接受；workspaceHarness 增加 root。tools 提示外部工具更新，doctor 警告 engram < 3.0.0。audit 关联 review/receipt，衡量可用性、分组与任务效率。钩子阻止丢弃未提交整树，publisher 不改写历史，plan-gate 要求确认并给出恢复步骤。Codex 的 AGENTS.md 更小，新增 engram 写入守卫，不再降低渲染模型。
- v0.10
分级计划与更可靠的 harness
- 派发前由分类器决定任务所需计划级别。
- scribe 可独占仓库 Markdown，其他智能体不再修改。
- 提交、PR、代码和注释均移除 AI 归属信息。
- doctor 检查可执行文件是否匹配清单固定版本，以及 MCP 接线一致性。
- 新增 Supabase、编写技能、后台系统、rebase 与 worktree 清理技能。
重要补丁
- v0.10.1 — 新增九种库技能，守卫也拦截受管理文件的绝对路径，init 提示缺少插件可执行文件。
快速开始
三步开始高效工作
安装
无需全局安装，使用 npx。
npx navori init
初始化
回答提示，即可获得 navori.config.json 与渲染后的 harness。
? Project › my-app ? Engine › claude ? Preset › nextjs ✓ Done — 5 created
配置变化后重新渲染
编辑配置，运行 render --apply，再提交。整个过程幂等。
$ vim navori.config.json $ npx navori render --apply $ git add . && git commit
常见问题
你可能想了解的问题
已经有手写的 .claude/ 怎么办？
navori 可以共存。init 检测现有 harness，只添加带标记的受管理块，保留自定义内容。要纳管某个文件，可用 navori adopt 包装，原文保持不变。已有编排或 SDD 时，可用 blocks.exclude 排除对应规则块，避免相互竞争。
目前支持哪些引擎？
六种均已提供：Claude Code（.claude/）、原生 Codex（智能体、技能、钩子和 MCP）、通用 AGENTS.md、Cursor（.cursor/rules/）、Copilot，以及 Pi（.pi/ 扩展、智能体和钩子，需要 Pi >= 1.1.0）。它们共享渲染流水线，修复可同时覆盖所有引擎。
使用 navori 必须安装 Claude Code 吗？
不需要。navori 是脚手架工具，生成 harness 后即可退出。它运行于 Node 22.12+，能够渲染六种不同引擎。
会改动多少内容？能回滚吗？
render 默认预览，不带 --apply 就不写入磁盘。真正写入前，通过 navori backup 保留可恢复快照，并使用原子写入。仓库外的操作都需明确启用：没有 global init 就没有全局层；没有 --start 就没有审计。
新版本发布后怎样更新项目？
运行 npx navori@latest sync，只更新受管理块，保留你的代码。使用 --interactive 逐块处理手动改动；navori refresh 可先说明将发生的变化。
多智能体 harness 的运行成本高吗？
通常低于预期，也无需只凭感觉判断：navori audit 会显示真实会话的 token 去向。每个智能体使用适合的模型与推理强度，判断任务用强模型，机械任务用轻模型；子智能体只返回结论，不返回全部阅读内容。