[navori](https://ulisescm.github.io/navori-harness/zh-cn/deep-dive) · 简体中文 了解 navori 的内部能力：多智能体编排、按角色分配模型、engram 持久记忆、组织工作区、标准与关卡，适用于生产代码和旧系统迁移。 深入了解 # navori 的内部能力 逐层解析。 navori 是一个具有 明确主张的 harness，面向已经在生产环境运行、存在旧依赖及未完成迁移的真实代码。它把 Claude Code 组织成遵守标准、共享记忆与跨仓库规范的团队。下面逐层解释它为何适合作为基础。 还不熟悉这些术语： harness, 技能或 SDD? [先查看简明术语表 ↓](https://ulisescm.github.io/navori-harness/zh-cn/deep-dive#glossary) 开始之前 ## 简明术语表 点击术语，用一句话理解含义。 Harness + 围绕 AI 助手的规则、智能体和自动化体系，让它按照团队期望工作，而非自行其是。 智能体 / 子智能体 + 负责特定角色（探索、编写、审查）的助手。主智能体把工作分配给专门的子智能体。 技能 + 完成具体任务的可复用指南，例如如何创建接口、如何验证完成；智能体按需加载。 钩子 + 在固定时机触发的自动化，如每次提交前运行测试，无需人为记住。 质量关卡 + 判定变更完成前必须通过的命令，如 lint 与测试。 SDD + 规格驱动开发：规则写在代码旁并随版本管理，可用一条命令更新，而非仅存于个人脑中。 预设 + 按技术栈打包的配置，如 Vite + React、NestJS 或 monorepo。navori 检测技术栈并选择对应预设。 Engram + 持久记忆，保存决策与经验，使助手能在下次会话恢复。 受管理块 + CLAUDE.md 中标记为 managed by navori 的片段，可更新而不覆盖周围的自定义内容。 legacyPaths + 你标记的旧代码目录，智能体会谨慎处理，不强加新规则。 01 · 编排 ## 一支智能体团队， 协作完成任务。 主智能体 直接承担 orchestrator 角色 ，作为会话中心拆分任务。子智能体并行工作，只返回结论。每个角色都有严格职责与合适的模型。 点击卡片，了解每个角色的职责 ↓ ### 编排者 opus main · orchestrator 负责拆分任务、分配工作，并把结果整合为完整方案。 ### 侦察者 sonnet 只读 通过搜索代码映射一个区域，或回答一个明确问题。 ### 审计者 sonnet 分析 / 只读 在任何人改代码前，研究复杂工单或深入审计模块。 ### 架构师 opus 设计 / 只读 探索备选方案，按项目适配程度推荐；始终参与二级和三级任务。 ### 实施者 sonnet 写入 接受一个明确限定的任务，并把代码工作完成。 ### 审查者 sonnet 质量关卡 审查并批准或拒绝，不修改代码。 ### 发布者 haiku git/gh 草拟提交，创建 Pull Request，并发布 Jira/GitHub 评论。 ### 文档员 haiku 文档 唯一编写 Markdown 的角色，将已验证证据整理为目标文档。 ### 编排者 opus 由主智能体直接承担这个角色，而非另建子智能体。它读取任务，决定如何拆分，并行启动执行者，最后将结果整合为一致的解决方案。使用能力最强的模型（opus），因为它的职责是推理与决策，而非阅读文件。 ### 角色与模型：时间及 token 效率 haiku 发布与文档 publisher · scribe 机械任务使用快速、低成本模型。 sonnet 阅读、编写与审计 scout · implementer · reviewer · auditor 平衡质量和成本。 opus 决策与设计 orchestrator · architect 把强能力用在需要判断之处。 全部可在 config.models中配置。让强模型负责决策，让轻模型快速探索。架构师使用最高推理强度（xhigh），只参与二级和三级任务，因此成本有界。级别由 classify确定，而非模型自行判断。 复杂任务中的 orchestrator ``` orchestrator › splits the ticket into 3 subtasks ├─ scout → map the module (own context · sonnet) ├─ scout → how is it validated? (own context · sonnet) └─ implementer → applies the change → quality gate ✓ (sonnet) └─ reviewer → approves against CLAUDE.md (sonnet) orchestrator › synthesizes and delegates the commit → publisher (haiku) ``` ### 派工前先按风险确定计划级别 orchestrator 使用 navori plan classify ，按可验证信号计算 0–10 复杂度分数，选择对应级别，而非凭聊天中的笼统描述。 级别 适用情况 产物 0 复杂度 ≤ 3，最多一个非平凡文件，且没有关键区域的最低级别要求。 无需独立计划；classify 确认可直接执行的豁免。 1 常见情况，大多数计划任务属于此级别。 简单工作计划（plan-simple 技能）：目标、带命令与期望输出的 A 标准、范围外事项、文件、进度和决策。 2 复杂度 ≥ 8，或涉及关键区域、资金/凭据/个人信息、多仓库、新依赖、共享契约或迁移。 高级工作计划（plan-advanced 技能）；架构师探索并推荐选项，用户先选择，再形成结论。 3 用户已接受规格。 specs//{requirements,design,tasks}.md；架构师编写 design.md，不另建工作计划。 由 PreToolUse 钩子限制派发 implementer ，任务必须携带通过 navori plan check的工作计划，或由 classify 确认的零级豁免。连续两次审查拒绝（CHANGES_REQUESTED）后，第三次派发前必须补充更高级别产物；二级或三级则直接交由用户决定，而非继续尝试。 02 · 真实环境 ## 面向生产， 立足真实代码。 多数工具假设仓库干净且从零开始。navori 关注团队现实：生产代码、旧依赖与进行中的迁移。通过 init 选择工作环境，从而决定智能体如何工作。 ### init 时选择项目模式 选择全新项目（快速推进）、生产项目（防止回归）或旧系统迁移（维护新旧兼容），从而决定智能体工作方式。 ### 智能体遵守 legacyPaths 标记旧代码目录后，orchestrator、implementer 和 reviewer 会遵守差异化规则，不对无权改动的旧代码强加新约定。 ### 迁移前先审计 面对结构迁移，如旧后端到新后端、单体到微服务，先分析根因、影响区域与兼容性，再编写代码。 ### 理解迁移的技能 verify-before-done、debug-failure 与 review-diff 能识别新旧代码共存时的不一致状态，减少半完成迁移中代价最高的错误。 navori init — 项目模式 ``` ? What terrain are you on? greenfield — new code, move fast › production — in production, guard regressions migration — legacy migration, watch legacy↔new compatibility → legacyPaths: [ "src/old-api", "legacy/" ] the orchestrator, implementer, and reviewer treat those paths with different rules. ``` 03 · 效率 ## 减少 token 从设计开始。 编排也管理上下文成本。繁重工作在独立窗口和独立模型中执行，只返回必要结论，主线程因此保持清晰。 ### 各子智能体上下文隔离 每个子智能体在独立窗口运行，只返回结论。orchestrator 的线程不会堆满读取的文件。 ### 按角色分配模型 阅读和探索使用轻模型，决策与审查使用强模型，避免让高成本模型承担文件阅读。 ### 按片段阅读 Scout 只读相关片段，不读取全部文件。它负责定位，而非复制整库。 ### 按需加载技能 技能目录用索引引用，只有任务需要时才加载完整内容。 ### 精简受管理块 规范排序与去重保持 CLAUDE.md 简洁，避免复制与逐会话累积的噪声。 ### 对比 没有 harness 单线程读取整份文件，将全部内容堆入上下文，逐轮携带直到窗口耗尽。 使用 navori 子智能体并行探索并返回结论，orchestrator 基于摘要推理。Engram 把需要长期记住的内容保存在上下文窗口外。 04 · 记忆 ## Engram： 持久保存记忆。 LLM 上下文是临时的，会话关闭后就会遗忘。navori 默认启用 Engram，使决策、已查明根因的错误与约定可跨会话保存、找回，并在上下文压缩后继续存在。 - 会话结束和上下文压缩之后仍然保留。 - mem_save 保存决策、已查明根因的错误和约定；mem_search 在启动时找回。 - 协议注入 orchestrator，主动保存，无需提醒。 - navori 默认始终启用。无需重复解释上周的上下文。 今天的会话 · 下周的会话 ``` # today — after fixing a bug mem_save "The 360 report breaks if languages[] is empty. Root cause: missing guard in report.py. Fix: default []." # next week — new session, context at zero mem_search "360 report languages" → recalls the decision, the root cause, and the fix. You don't re-explain it. ``` 05 · 组织扩展 ## 一个工作区， 覆盖所有仓库。 管理十五个仓库时，无需维护十五套标准。工作区提供跨仓库层，统一定义组织质量关卡、基础分支与约定，由各仓库继承。团队切换项目时仍采用同一工作方式。 - 跨仓库配置位于 ~/.navori/workspaces/.json，不属于某个单独仓库。 - 组织级默认值：质量关卡、基础分支和共享约定。 - 任务以可版本管理的文件保存在工作区内。 - workspace render 一次将标准应用到所有已注册仓库。 组织标准应用到每个仓库 ``` $ navori workspace init acme $ navori workspace set-default acme \ --branch-base main --commits conventional-es $ navori workspace add-repo acme ./web-app $ navori workspace add-repo acme ./api-core … 13 more repos $ navori workspace render acme ✓ 15 repos rendered with the same standard ``` 06 · 保护机制 ## 用标准和关卡 保护工作成果。 拥有写入权限的智能体需要约束。navori 将简单性、严格类型、安全与质量关卡作为 harness 的必要组成，并与其余配置一同版本管理。 ### 简单优先 写代码前先问：是否最简单，六个月后是否可读，是否沿用现有模式？避免以后无人理解的技巧。 ### 禁止 any 使用 unknown、类型收窄与显式类型。唯一例外为带原因的 // justified any: ，只作最后手段，不作便捷捷径。 ### 防御性钩子 guard-destructive 拦截危险命令；quality-gate 在每次提交前运行 lint 与测试。 ### deny / ask 权限 敏感操作被阻止，或需要明确确认。使用多层防御，而非单一屏障。 07 · 差异 ## 为什么选 navori， 它与通用脚手架有何不同。 给 AI 助手指令有很多方式，但很少能长期适应真实团队及有历史的仓库。以下能力展示 navori 的不同之处。 ### 无需复制 .claude/ 版本化事实来源与幂等渲染，让跨仓库配置可以扩展并持续更新，避免手动复制目录。 ### 持续维护而非静态模板 检测真实技术栈，包括 Mantine、Redux、NestJS 和 pnpm monorepo，组合适合的预设。标准通过版本管理和一条更新命令持续维护。 ### 重视生产与旧系统 很多工具假设仓库从零开始；navori 关注真实运行的代码、旧依赖和进行中的迁移。 ### 功能齐备且相互连接 持久记忆、安全与重复关卡、多智能体编排、跨仓库标准均已连通，无需照着 README 手动拼装。 08 · 团队协作 ## 加入一个 已经使用 navori 的仓库。 每个仓库只需提交一次配置，团队随后遵循它。无需手写 harness，也无需在项目间复制 .claude/ 。以下是每位成员加入项目时运行的命令。 01 ### 准备前置条件 需要 Node.js 22.12+、Claude Code，以及使用持久记忆时的 engram 可执行文件。第三步的 doctor 会准确说明缺少什么。 ``` node --version # v22.12 or higher # Claude Code installed on your machine ``` 02 ### 克隆并重建 harness 仓库已有唯一事实来源 navori.config.json。一条命令就能为全队一致地重建所有已配置引擎，重复运行也不会产生变化。 ``` $ git clone && cd $ npx navori render --apply ✓ configured engines rebuilt from the config ``` 03 ### 使用 doctor 验证 doctor 确认一切已更新；若缺少 engram 等工具，会给出准确安装命令，无需猜测。 ``` $ npx navori doctor ◇ All good — nothing pending. ⇡ engram — missing from PATH: brew install gentleman-programming/tap/engram \ && claude plugin install engram ``` 04 ### 正常开始工作 打开 Claude Code，即可使用相同智能体、技能、质量关卡与团队记忆。配置更新后运行 sync，同步规则并保留代码。 ``` # already productive with the team's harness # when the repo config changes: $ npx navori@latest sync ``` 团队成员只需： clone → npx navori render --apply → npx navori doctor 即可使用相同 harness 开始工作。 ## 从理论 一分钟落地到仓库。 一条采用命令就能生成这些内容，之后配置变化时重新渲染即可。 [查看快速开始](https://ulisescm.github.io/navori-harness/zh-cn/quickstart) [命令参考](https://ulisescm.github.io/navori-harness/zh-cn/docs/init) 致谢 ## 站在巨人的 肩膀上。 navori 集成了优秀工具，也从开源项目与标准中吸收想法。每项成果的贡献属于其原作者。 ### 基础工具 - [Claude Code ↗ Anthropic navori 为其生成配置的智能体运行时。](https://claude.com/claude-code) - [engram ↗ Gentleman-Programming 通过 MCP 提供跨会话持久记忆。](https://github.com/Gentleman-Programming/engram) - [GitHub CLI ↗ GitHub 在终端管理 issue 与 PR。](https://cli.github.com/) - [Atlassian CLI ↗ Atlassian 将 Jira 工单作为工作来源。](https://developer.atlassian.com/cloud/acli/) - [codegraph ↗ colbymchenry 通过 MCP 查询代码图，定位和衡量影响，无需读取整份文件。](https://github.com/colbymchenry/codegraph) ### 思想与标准 - [AGENTS.md ↗ 通用智能体指令规范，是多引擎的基线。](https://agents.md/) - [Claude Code 子智能体 ↗ 在隔离上下文中运行 orchestrator 与执行者的模式。](https://docs.claude.com/en/docs/claude-code/sub-agents) - 规格驱动开发 将技能、规则与约定作为仓库一部分进行版本管理。 ### 启发本项目的开源项目 navori 借鉴了这些项目，其中 codegraph 同时作为插件集成。逐项目说明见 docs/inspiration.md. - [gentle-ai ↗ Gentleman-Programming 支持 SDD、持久记忆与按任务复杂度自然路由的生态配置器。](https://github.com/Gentleman-Programming/gentle-ai) - [gstack ↗ garrytan 角色串联技能、宿主自动检测及独立配置，以及跨模型审查。](https://github.com/garrytan/gstack) - [harness-sdd ↗ betta-tech EARS 表述、需求与测试追踪，以及用文件系统表达规格状态机。](https://github.com/betta-tech/harness-sdd) - [ejemplo-harness-subagentes ↗ betta-tech Orchestrator/Implementer/Reviewer 模式与磁盘状态，聊天仅传递引用。](https://github.com/betta-tech/ejemplo-harness-subagentes) - [superpowers ↗ obra 子智能体驱动开发：每项任务使用新的智能体，规格清楚到初级开发者也能执行。](https://github.com/obra/superpowers) - [ponytail ↗ DietrichGebert 防止过度设计的决策阶梯：方案保持简单，阅读保持认真。](https://github.com/DietrichGebert/ponytail) - [codegraph ↗ colbymchenry 通过预索引代码图获取精确上下文，替代反复搜索与阅读。](https://github.com/colbymchenry/codegraph) - [graphify ↗ Graphify-Labs 确定性的代码与文档知识图，像受管理资源一样提交到仓库。](https://github.com/Graphify-Labs/graphify) - [caveman ↗ JuliusBrussee 把 token 效率作为贯穿技能：简洁同时保持技术准确。](https://github.com/JuliusBrussee/caveman) - [Goose ↗ Agentic AI Foundation 可移植的 YAML 配方，让团队和 CI/CD 共享工作流。](https://goose-docs.ai/) - [Pi ↗ Earendil 优先基本构件，以按需技能与可扩展性替代内置工作流。](https://pi.dev/) 使用的技术 [clack](https://github.com/bombshell-dev/clack)[citty](https://github.com/unjs/citty)[zod](https://zod.dev/)[Astro](https://astro.build/)[Tailwind CSS](https://tailwindcss.com/) ## 编排者 由主智能体直接承担这个角色，而非另建子智能体。它读取任务，决定如何拆分，并行启动执行者，最后将结果整合为一致的解决方案。使用能力最强的模型（opus），因为它的职责是推理与决策，而非阅读文件。 ## 侦察者 在重构或大型功能开始前，orchestrator 让它映射模块：文件、关系与流程入口；也可调查决策所需的事实，如当前登录如何校验。它只读相关片段，把发现写入独立文件，返回地图或明确答案，不进行无边界探索，也不倾倒文件内容。 ## 审计者 它负责三类任务：实施前审计工单，确认根因、受影响区域和拆分计划；无工单时在重构前审计漏洞、性能、架构问题与边界场景；或在新上下文中质疑规格设计。它不编辑生产代码，而是将报告或结论写入磁盘，让 implementer 有据可依。 ## 架构师 所有二级高级工作计划和三级完整规格均需要架构师。它至少探索现有模式、扩展和新抽象三条路径，为不合适的方案给出简明证据，按项目标准推荐，而非默认挑选最便宜的方案。它不独自决定，也不拆分任务：先给出推荐和选项，由用户选择，再由 orchestrator 制定计划。始终启用最高模型与推理强度（opus、xhigh），专注比较方案与权衡。 ## 实施者 从 orchestrator 接收清晰子任务，按照仓库规则（CLAUDE.md）实施，只有 lint 和测试等质量关卡通过后才报告完成。中等能力模型（sonnet）平衡代码质量与成本。 ## 审查者 按照项目规则与质量关卡审查 implementer 的工作，给出具体的批准或拒绝理由。这是在代码继续流转前的严格第二意见，因此需要有判断能力的模型。 ## 发布者 工作获批后，它按仓库 Conventional 格式撰写提交信息和 PR 标题、说明。联网前检查 git/gh；发布信息性评论前先给出草稿。工作机械且范围明确，轻量模型即可。 ## 文档员 启用 harness.scribeOwnsMarkdown 时，只有它可以编辑 .md 文件：将其他智能体的结构化证据转换为 Markdown 报告，或按 markdownRequest 撰写文档，并使用独立提交。它不调查、不虚构结论，只整理证据已支持的内容。