[navori](https://ulisescm.github.io/navori-harness/zh-cn/) · 简体中文 navori 为任何仓库安装可复现的多智能体与 SDD 工作环境：智能体、技能、钩子、权限和记忆统一版本管理，并渲染到 Claude Code、Codex、Cursor、Copilot 和 AGENTS.md。 开源 · 六种引擎 # 多智能体 harness 适用于任何代码仓库。 智能体、技能、钩子、权限和记忆统一保存在一个配置中，用一条命令即可重建。渲染到 Claude Code、Codex、Cursor、Copilot 和 AGENTS.md，同时保留你的自定义内容。 npx pnpm bun 复制 $ npx navori init pnpm dlx navori init bunx navori init [开始使用](https://ulisescm.github.io/navori-harness/zh-cn/quickstart) [在 GitHub 查看](https://github.com/UlisesCm/navori-harness) MIT Node ≥ 22.12 0 runtime deps Claude Code Codex Copilot AGENTS.md ~/your-repo · zsh · 示例 $ 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 在这条路径上设置八个站点：从一句话到提交，再将决策存回记忆。 你的提示词 ❯ 修复客服报告的登录错误 ### 你输入一句话，模型还未开始思考。 模型读取提示词之前，启动钩子已经运行。这让助手开启会话时就了解当前状态，无需每天从零开始。 - 1 接收 - 2 上下文 - 3 编排 - 4 定位 - 5 执行 - 6 保护 - 7 筛选 - 8 闭环 暂停 导览自动播放，点击站点即可跳转。 问题 ## 每个仓库都在重复造轮子 如果你同时维护多个项目并使用 AI 智能体，就会熟悉这些问题。 01 ### 每个仓库各自维护 harness 将 .claude/ 从一个项目复制到另一个项目，手动同步既费力又容易出错。 02 ### 每种引擎各自维护配置 Claude 使用 .claude/，Cursor 使用 .cursor/，Copilot 使用 .github/copilot-instructions.md。同样的意图分散在三个文件。 03 ### SDD 逐渐失效 如果无法版本管理和持续更新，技能、钩子与规格驱动开发约定就会逐渐偏离。 作用域 ## harness 不再局限于单个仓库 两个可叠加的作用域，均需主动启用。工作区在仓库配置上增加规则，同时保留仓库能力。 01 每个仓库 ### 仓库 提交到版本库的 navori.config.json 是唯一事实来源。render 据此幂等重建 CLAUDE.md、.claude/ 和 progress/，同时保留你的内容。 navori.config.json navori init 02 每个组织 ### 工作区 组织级默认值，包括质量关卡、基础分支与约定，以及 Dominio：跨仓库的持久事实，如数据模型、服务间契约和共同注意事项。 ~/.navori/workspaces// navori workspace · navori dominio 未启用就没有额外足迹：不运行对应的 init，navori 就不会在仓库外写入任何字节。 工作原理 ## 五层级联，一个事实来源 每层叠加在前一层之上，由你决定项目层面的控制程度。 - 01 ### 核心 navori 管理的基线：智能体、技能、钩子和规则块，始终存在。 navori - 02 ### 预设 面向 Next.js、NestJS、Astro、Expo、Medusa、monorepo 等技术栈的默认值。没有适合的？用 `navori preset init` 创建本地预设。 preset - 03 ### 工作区 跨仓库共享的组织规则，以及工作区 Dominio。 org - 04 ### 项目 navori.config.json 中属于本仓库的设置：质量关卡、关键区域、旧代码路径与启用的插件。 you - 05 ### 适配器 通过同一流水线渲染为 Claude Code、Codex、Cursor、Copilot 和 AGENTS.md 的原生格式。 engine 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 ``` $ 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 ``` [navori audit](https://ulisescm.github.io/navori-harness/zh-cn/docs/audit) 01 ### token 的去向 区分计费、启动与各智能体用量，让 harness 成本从猜测变为可优化的数据。 02 ### 未被执行的指令 按严重程度报告真实路由问题：忽略的技能、高成本搜索路径，以及没有发生的委派。 03 ### 三种互不可替代的来源 钩子事件日志记录 harness 行为；会话记录保存 token；宿主 OTel 事件记录权限批准与活跃技能。 04 ### 逐会话主动启用 没有提前运行 --start，就没有可审计日志，navori 也不观察任何活动。Markdown 与 JSON 报告保存在 ~/.navori/audits/；--snapshot/--compare 用于对比区间，只描述结果，不宣称改进。 命令 ## 完整生命周期，逐个命令讲解。 按实际使用时机对 CLI 注册的所有子命令分组。每个命令都有独立参考页。 ### 开始 - [navori init 在仓库中初始化 navori：检测技术栈，询问必要信息，一分钟内准备就绪。](https://ulisescm.github.io/navori-harness/zh-cn/docs/init) - [navori adopt 将手写 harness 文件纳入管理，保留原文。](https://ulisescm.github.io/navori-harness/zh-cn/docs/adopt) - [navori add 注册插件到 navori.config.json，或按技术栈推荐插件。](https://ulisescm.github.io/navori-harness/zh-cn/docs/add) - [navori remove 停用插件并清理遗留的受管理块、注入子块和脚本。](https://ulisescm.github.io/navori-harness/zh-cn/docs/remove) - [navori preset 为没有官方预设的技术栈，在 .navori/presets/ 创建本地预设。](https://ulisescm.github.io/navori-harness/zh-cn/docs/preset) - [navori configure init 后修改 navori.config.json，各部分有独立子命令。](https://ulisescm.github.io/navori-harness/zh-cn/docs/configure) ### 渲染与更新 - [navori render 从 navori.config.json 幂等重建所有配置引擎，默认预览。](https://ulisescm.github.io/navori-harness/zh-cn/docs/render) - [navori sync 将资源包变化同步到所有已配置引擎，保留你的修改。](https://ulisescm.github.io/navori-harness/zh-cn/docs/sync) - [navori update 将 navori CLI 更新到 npm 最新版本，再用新可执行文件运行 navori refresh。](https://ulisescm.github.io/navori-harness/zh-cn/docs/update) - [navori refresh 一步更新：重新检测仓库，提供配置差异，再运行 sync。](https://ulisescm.github.io/navori-harness/zh-cn/docs/refresh) - [navori migrations init 以 replace 模式采用 navori 时备份原 harness，可恢复。](https://ulisescm.github.io/navori-harness/zh-cn/docs/migrations) - [navori backup 每次 sync 或 render 修改文件前，在 ~/.navori/backups/ 创建快照。](https://ulisescm.github.io/navori-harness/zh-cn/docs/backup) ### 操作 - [navori doctor 审计项目配置、插件、漂移、不变量并建议后续步骤。](https://ulisescm.github.io/navori-harness/zh-cn/docs/doctor) - [navori status 快速查看配置、插件、漂移及后续步骤，一条命令确认当前状态。](https://ulisescm.github.io/navori-harness/zh-cn/docs/status) - [navori scan 重新检测 monorepo，将 init 后新增的工作区加入配置。](https://ulisescm.github.io/navori-harness/zh-cn/docs/scan) - [navori registry 机器上所有 navori 仓库的全局注册表，支持 render --all。](https://ulisescm.github.io/navori-harness/zh-cn/docs/registry) - [navori bench 对 render 执行 N 次计时，报告 p50/p95，在提交前发现本地回归。](https://ulisescm.github.io/navori-harness/zh-cn/docs/bench) - [navori codex 在 ~/.codex/config.toml 批准项目 Codex 钩子。项目受信任前 Codex 不加载仓库内容，包括 AGENTS.md。](https://ulisescm.github.io/navori-harness/zh-cn/docs/codex) - [navori receipt 发布前签署或校验已审查的字节内容。](https://ulisescm.github.io/navori-harness/zh-cn/docs/receipt) - [navori gate 运行项目质量关卡，完整输出写日志，stdout 仅显示紧凑结论。](https://ulisescm.github.io/navori-harness/zh-cn/docs/gate) - [navori plan 分类复杂度并校验工作计划（spec 0032）。](https://ulisescm.github.io/navori-harness/zh-cn/docs/plan) - [navori spec 分类规格 tasks.md 并校验交付结构（spec 0044）。](https://ulisescm.github.io/navori-harness/zh-cn/docs/spec) - [navori handoff orchestrator 派发下一角色前，校验 implementer handoff。](https://ulisescm.github.io/navori-harness/zh-cn/docs/handoff) - [navori master 项目主计划：管理阶段、流程、部分和闭环（spec 0034）。](https://ulisescm.github.io/navori-harness/zh-cn/docs/master) ### 观察 - [navori audit 查看 harness 真实执行：token 去向及未能遵守的指令。](https://ulisescm.github.io/navori-harness/zh-cn/docs/audit) ### 扩展 - [navori workspace 跨仓库共享配置与任务，统一默认值，一次渲染整个仓库集合。](https://ulisescm.github.io/navori-harness/zh-cn/docs/workspace) - [navori dominio 工作区知识库，保存跨仓库、不适合单个 CLAUDE.md 的权威事实。](https://ulisescm.github.io/navori-harness/zh-cn/docs/dominio) - [navori ticket 将任务作为工作区文件保存，为跨仓库工作提供统一位置。](https://ulisescm.github.io/navori-harness/zh-cn/docs/ticket) - [navori tools SessionStart 机器命令：每个会话提示一次声明 latestRelease 的工具有稳定新版本，目前为 engram。](https://ulisescm.github.io/navori-harness/zh-cn/docs/tools) [查看完整参考](https://ulisescm.github.io/navori-harness/zh-cn/docs/init) 多引擎 ## 一个配置，六种引擎。 同一 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 2026年10月12日 ### Pi 成为一等引擎，更省成本的关卡，以及明确的迁移路径 - Pi 已加入 init 向导和 configure engines，与 Claude Code 的安全守卫和钩子达到同等能力；敏感动作需输入 yes, run it 批准。要求 Pi >= 1.1.0。 - 新增 navori gate ，首行给出简要结论，完整日志保存在 .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 2026年9月29日 ### 每个 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 2026年9月23日 ### 分级计划与更可靠的 harness - 派发前由分类器决定任务所需计划级别。 - scribe 可独占仓库 Markdown，其他智能体不再修改。 - 提交、PR、代码和注释均移除 AI 归属信息。 - doctor 检查可执行文件是否匹配清单固定版本，以及 MCP 接线一致性。 - 新增 Supabase、编写技能、后台系统、rebase 与 worktree 清理技能。 #### 重要补丁 - v0.10.1 — 新增九种库技能，守卫也拦截受管理文件的绝对路径，init 提示缺少插件可执行文件。 [查看所有版本 →](https://ulisescm.github.io/navori-harness/zh-cn/releases) 快速开始 ## 三步开始高效工作 01 ### 安装 无需全局安装，使用 npx。 ``` npx navori init ``` 02 ### 初始化 回答提示，即可获得 navori.config.json 与渲染后的 harness。 ``` ? Project › my-app ? Engine › claude ? Preset › nextjs ✓ Done — 5 created ``` 03 ### 配置变化后重新渲染 编辑配置，运行 render --apply，再提交。整个过程幂等。 ``` $ vim navori.config.json $ npx navori render --apply $ git add . && git commit ``` [完整快速开始](https://ulisescm.github.io/navori-harness/zh-cn/quickstart) 常见问题 ## 你可能想了解的问题 ### 已经有手写的 .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 去向。每个智能体使用适合的模型与推理强度，判断任务用强模型，机械任务用轻模型；子智能体只返回结论，不返回全部阅读内容。 ## 接收: 你输入一句话，模型还未开始思考。 模型读取提示词之前，启动钩子已经运行。这让助手开启会话时就了解当前状态，无需每天从零开始。 ## 上下文: 四种上下文先于提示词加载 仓库规则、任务指南、适用于整个工作区的事实，以及以往会话已作出的决策。你不必再次解释这些内容。 ## 编排: 与你对话的智能体负责分配工作 它读取需求，决定如何拆分任务、由谁负责。它掌握任务全貌，使用高能力模型来判断和决策，而非阅读文件。 ## 定位: 先定位，再阅读 两个问题对应两种工具：符号在哪里、修改后影响谁，以及哪些文件包含指定文本。否则，智能体可能为了找到一个文件而打开二十个。 ## 执行: 三个专家并行工作，互不阻塞 每个专家都有独立上下文，只返回结论，不倾倒读过的全部内容。主线程保持清晰，高成本模型也无需承担阅读成本。 ## 保护: 明确智能体禁止执行的操作 钩子在每次工具执行前拦截，权限规定哪些操作直接通过、哪些需要询问、哪些禁止。藏在变量后的 `rm -rf` 会在这里被阻止。 ## 筛选: 完成必须有证据 对差异进行安全与重复检查，真正运行仓库质量关卡，并由拥有新上下文的 reviewer 给出批准或拒绝的理由。这四道检查都有可验证依据。 ## 闭环: 提交之后，决策还要保存 按仓库格式生成提交和 PR，将决定及原因写回记忆。下次会话从这里恢复上下文，形成完整闭环。 启动 harness 仓库规则 任务指南 工作区事实 既有决策 拆分并分配 符号位置与调用者 包含文本的文件 映射或调查 编写代码 发现风险 阻止破坏操作 allow · ask · deny lint · 测试 · 格式 批准或拒绝 提交与 PR 保存决策 保存的内容成为下次会话的上下文 基线：始终加载的智能体、技能和规则块。 技术栈专用技能，此处为 Next.js。 继承自组织的默认值：质量关卡、基础分支。 仓库级配置：启用的插件（engram）及其协议。