furbon/navlyn
GitHub: furbon/navlyn
Navlyn 是一款基于 Roslyn/MSBuild 的 C#/.NET 语义代码导航 CLI 与 MCP 服务器，通过提供编译器级的只读符号证据，帮助 AI 编码代理和开发者精准定位代码目标、避免错误编辑。
Stars: 1 | Forks: 0
# Navlyn
日本語: [`README_ja.md`](README_ja.md)
**在编码代理（coding agents）修改错误的符号（symbol）之前，为其提供以 C# 为先的 .NET 语义证据（只读），并拥有由 Roslyn 支持的 Visual Basic 支持。**
编码代理已经非常擅长修改代码。在 C# 仓库以及 Roslyn 支持的 .NET 源代码（例如 Visual Basic）中，困难的部分在于确保代理修改的是*正确*的代码：正确的重载、分部声明（partial declaration）、目标框架（target framework）、依赖注入（DI）路径、路由处理程序（route handler）、公共 API 范围以及相关的测试。
文本搜索可以找到 `PaymentService`。Navlyn 会询问 Roslyn 和 MSBuild，确认 `PaymentService` 在此工作区中究竟是什么，返回确定性的 JSON，并为代理提供一个稳定的目标，供其在调查期间持续使用。
将 Navlyn 视为一种**以 C# 为先的编辑预检（edit preflight）**：
1. 解析用户所指的确切符号；
2. 仅读取重要的有限源代码和关系；
3. 在 Navlyn 之外使用常规工具进行编辑；
4. 在代理继续操作之前检查实际的 diff。
Navlyn 以以下形式发布：
- `navlyn`：一个 CLI，适用于 shell、CI、脚本和代理循环；
- `navlyn-mcp`：一个独立的 stdio MCP 服务器，适用于支持 MCP 的编码代理和编辑器。
两者都是本地、只读且仅基于事实的。Navlyn 不会编辑文件、运行任意 shell 命令、调用网络、上传源代码或维护托管索引。
Navlyn 的示例和定位始终保持以 C# 为先，但相同的 Roslyn/MSBuild 命令系列也支持 Visual Basic 项目和源文件（`.vbproj` / `.vb`）。
## 它为何存在
在成熟的 C# 代码库中，代理的失败通常不是“糟糕的代码生成”失败。它们是**错误的上下文失败**：
- 文本匹配指向了错误的重载或名称相似的类型；
- 多目标项目在不同的目标框架下具有不同的符号；
- 分部类型、生成的文件、链接的文件或条件编译分支改变了真实的情况；
- 重要的边界完全不是文本层面的，而是 DI 注册、ASP.NET 路由、MediatR 处理、EF 模型结构或相关的测试；
- 代理读取了过多的仓库内容，反而丢失了它所需要的信号。
Navlyn 将这些枯燥但高价值的调查步骤打包为基于 Roslyn/MSBuild 的 JSON。它不会让 LLM 去猜测你代码库的结构。
## 快速开始
对于个人安装：
```
dotnet tool install --global navlyn
dotnet tool install --global navlyn-mcp
```
对于为团队、CI 任务或代理工作区固定版本的仓库本地工具清单：
```
dotnet new tool-manifest
dotnet tool install navlyn --version 0.6.0
dotnet tool install navlyn-mcp --version 0.6.0
dotnet tool restore
```
在你自己的 C# 仓库或 Visual Basic 项目中，以下是最先有用的命令：
```
navlyn doctor --workspace path/to/YourRepo.slnx
navlyn resolve-target --workspace path/to/YourRepo.slnx --query PaymentService --assume-kind NamedType
navlyn edit-preflight --workspace path/to/YourRepo.slnx --query PaymentService --assume-kind NamedType --goal modify --change-kind behavior
# 从 resolve-target 或 edit-preflight 中复制 candidateId，然后在 Navlyn 外部编辑：
navlyn post-edit-guard --workspace path/to/YourRepo.slnx --candidate-id sym:v1:... --fail-on-risk high
```
对于 MCP 客户端，请从狭窄的 reader profile 开始：
```
{
"command": "navlyn-mcp",
"args": ["--workspace", "path/to/navlyn.workspace.json", "--tool-profile", "reader"]
}
```
可复制的设置结构位于 [`docs/navlyn-client-setup.md`](docs/navlyn-client-setup.md) 中。如需引导式的首次运行，请使用 [`docs/navlyn-first-10-minutes.md`](docs/navlyn-first-10-minutes.md)。
## 核心循环
**1. 锚定目标。**
`resolve-target` 会尽可能将模糊的意图转换为选定的源代码目标，如果无法做到，则提供备选方案和原因代码。后续命令可以重用返回的 `candidateId`，因此调查将始终绑定在同一个 Roslyn 符号上，而不是随后的文本匹配。
**2. 收集足够的证据。**
根据问题使用 `symbol-source`、`references`、`about`、`impact` 或 `context-pack`。`edit-preflight` 将常见的编辑规划路径封装在一个信封中：目标锚点、有限源代码、有限上下文、相关测试、置信度、已知未知项以及下一个防护命令。
**3. 验证 diff。**
使用常规工具进行编辑后，`post-edit-guard`、`wrong-symbol-guard` 或 `review-diff --profile evidence` 会将实际的 Git diff 与预期目标进行比较，并返回机器可读的风险信号。
不要将每个 Navlyn 命令作为清单来运行。当每次调用都能回答一个语义问题时，Navlyn 的作用最强。
## 之前 / 之后
如果没有 Navlyn，代理可能会运行 `rg PaymentService`，打开第一个看似合理的文件，错过第二个目标框架或构造函数路径，并使用错误的上下文进行编辑。
使用 Navlyn 时，第一步是生成目标信封：
```
{
"confidence": "high",
"candidateCount": 1,
"selectedTarget": {
"name": "PaymentService",
"kind": "NamedType",
"path": "src/Billing/PaymentService.cs",
"line": 14,
"column": 21
},
"candidateId": "sym:v1:...",
"selector": {
"project": "Billing.Api(net10.0)",
"targetFramework": "net10.0"
},
"recommendedNextActions": [
{ "command": "definition", "candidateId": "sym:v1:..." },
{ "command": "references", "candidateId": "sym:v1:..." },
{ "command": "about", "candidateId": "sym:v1:..." }
]
}
```
这不是运行时证明。它是代理在修改代码之前可以重复使用的稳定源代码级锚点。
## 何时使用 Navlyn
当文本足够时，请首先使用常规的文件读取和 `rg`。当 C# 或 Visual Basic 语义、项目上下文或 diff 证据会改变答案时，请选用 Navlyn。
| 任务 | 首个 Navlyn 调用 | 停止条件 |
| --- | --- | --- |
| 从近似名称识别符号 | `resolve-target --query PaymentService --assume-kind NamedType` | 你拥有一个高置信度的 `candidateId`，或者候选列表显示用户必须澄清。 |
| 检查一个已知的 C# 或 Visual Basic 文件 | `outline --file src/Billing/PaymentService.cs` 或 MCP `navlyn_file_outline` | 大纲或返回的 `candidateId` 回答了问题。 |
| 检查所选符号的关系 | `references --candidate-id sym:v1:... --group-by file --limit 50` | 返回的关系事实回答了问题。 |
| 规划非简单的编辑 | `edit-preflight --candidate-id sym:v1:... --goal modify` | 代理拥有锚点、有限证据、已知未知项和编辑后防护命令。 |
| 审查实际的 Git diff | `review-diff --profile evidence` | 变更的符号、诊断、影响、相关测试和警告可用。 |
| 事后检查编辑 | `post-edit-guard --candidate-id sym:v1:... --fail-on-risk high` | 防护通过，或者在进一步编辑之前已理解不匹配之处。 |
## 你能得到什么
- **针对模糊意图的确切锚点**：`resolve-target` 和 `find` 返回置信度、备选方案、原因代码和可重用的 `candidateId` 值。
- **文件优先的语义读取**：勾勒一个 C# 或 Visual Basic 文件的大纲，检查选定的源代码切片，然后仅在需要时请求边界。
- **工作区事实**：项目、目标框架、包、诊断、测试关系、生成代码策略和仓库结构。
- **源代码关系**：定义、引用、使用类型、调用者、调用、实现、类型层次结构、相关文件、入口点和静态影响。
- **.NET 应用程序证据**：ASP.NET Core 路由/身份验证、DI 注册和消费者、选项/配置、MediatR 处理程序、EF Core 模型事实、包使用情况和框架入口点。
- **审查证据**：变更的符号、诊断、静态影响、公共 API 事实、相关测试和有限的 review-pack 信号。
- **代理防护栏**：`edit-preflight`、`post-edit-guard`、`wrong-symbol-guard`、变更意图、移交和用于避免错误符号的置信度账本。
- **自动化规范**：stdout 上的确定性 JSON、stderr 上的诊断、基于 1 的位置、尽可能使用相对于仓库的 `/` 路径、文档化的契约、模式和高价值输出的黄金快照。
## 面向代理的 MCP
`navlyn-mcp` 为代理提供了以 C# 为先的 .NET 语义工具（包括 Visual Basic 源代码支持），而无需为 Navlyn 提供编辑界面，也无需要求代理组合 shell 命令。从狭窄开始，仅在任务需要时扩展。
| Profile | 用途 |
| --- | --- |
| `reader` | 设置检查、文件大纲、符号解析、有限源代码和选定符号的边界。这是默认设置。 |
| `edit` | 编辑前证据、相关测试、影响、有限上下文、移交/置信度包以及编辑后防护。 |
| `review` | 实际的 Git diff、PR 审查证据、公共 API 事实、相关测试和防护检查。 |
| `full` | 适用于需要每个 MCP 工具的客户端的兼容模式，包括 `navlyn_batch`。 |
边界被刻意保持简单：仅限 stdio、只读、仅限本地、没有任意文件服务器、没有编辑工具、没有 shell 执行。参见 [`docs/navlyn-mcp-server.md`](docs/navlyn-mcp-server.md)。
## Navlyn 的定位
| 工具 | 用途 | Navlyn 的工作 |
| --- | --- | --- |
| `rg` 和文件读取 | 注释、字符串、Markdown、配置、快速文本探测 | 当文本有歧义时的 C# 或 Visual Basic 符号标识、项目上下文和源代码级关系。 |
| LSP / IDE | 交互式编辑、重命名、转到定义、编辑器诊断 | 为代理、CI、脚本和 MCP 客户端提供稳定的 JSON 事实。 |
| Roslyn API / 分析器 | 构建自定义编译器工具 | 无需编写分析器即可随时运行的只读工作流。 |
| 通用代码搜索 MCP | 跨语言或文本级别的存储库搜索 | C# 和 Visual Basic MSBuild/Roslyn 事实：目标框架、符号、引用、DI、路由、测试和审查证据。 |
| 面向编辑的 MCP 服务器 | 从一个客户端检查和修改代码 | 没有编辑界面的客户端中立证据。 |
| CI 审查机器人 | 发布评论或通过/失败检查 | 在决定要说什么之前，人类或代理可以检查的本地审查事实。 |
| 托管代码搜索 | 跨仓库托管索引 | 仓库本地分析，无需将源代码发送到托管服务。 |
## 运行仓库演示
在此仓库中执行 `dotnet restore navlyn.slnx` 后：
```
dotnet run --framework net10.0 --no-launch-profile --project navlyn -- resolve-target --workspace navlyn.slnx --project "Navlyn.CommandLine(net10.0)" --query CheckCommand --assume-kind NamedType --limit 5
dotnet run --framework net10.0 --no-launch-profile --project navlyn -- edit-preflight --workspace navlyn.slnx --project "Navlyn.CommandLine(net10.0)" --query CheckCommand --assume-kind NamedType --goal modify --change-kind behavior
dotnet run --framework net10.0 --no-launch-profile --project navlyn -- review-diff --workspace navlyn.slnx --base HEAD --head HEAD --profile compact --symbol-limit 3 --impact-limit 3 --diagnostic-limit 3 --related-test-limit 3
```
第一个命令将一个模糊名称锚定到此仓库中的 C# 符号。第二个命令为该目标构建编辑预检证据。第三个命令显示显式 Git 范围的审查信封；将引用替换为 PR 引用，或者在脏分支上省略它们。
更多演示：[`docs/navlyn-demo-walkthroughs.md`](docs/navlyn-demo-walkthroughs.md)。
## 信任边界
Navlyn 报告有限的源代码级证据。它不证明运行时行为、不执行测试、不扫描密钥、不决定 SemVer、不发布审查评论，也不取代人类的判断。
它也不能替代普通的阅读。如果问题涉及注释、字符串、Markdown 部分、生成的工件或非 Roslyn 源文件，请使用 `rg` 或直接读取文件。
已知限制记录在 [`docs/navlyn-limitations.md`](docs/navlyn-limitations.md) 中。性能和缓存预热行为记录在 [`docs/navlyn-performance.md`](docs/navlyn-performance.md) 中。
## 文档导航
- [`docs/navlyn-first-10-minutes.md`](docs/navlyn-first-10-minutes.md)：成功完成首次 CLI/MCP 运行的最短路径。
- [`docs/navlyn-client-setup.md`](docs/navlyn-client-setup.md)：安装结构和客户端配置。
- [`docs/navlyn-agent-recipes.md`](docs/navlyn-agent-recipes.md)：面向任务的 CLI/MCP 方法。
- [`docs/navlyn-positioning.md`](docs/navlyn-positioning.md)：针对搜索、LSP、分析器、MCP 服务器和审查机器人的类别定位。
- [`docs/navlyn-mcp-server.md`](docs/navlyn-mcp-server.md)：MCP profile、工具、资源、新鲜度和边界。
- [`docs/navlyn-cli-commands.md`](docs/navlyn-cli-commands.md)：完整的公共 CLI 契约和 JSON 行为。
- [`docs/navlyn-performance.md`](docs/navlyn-performance.md)：性能模型和测量命令。
- [`docs/navlyn-development-workflow.md`](docs/navlyn-development-workflow.md)：贡献者验证、脚本和工作流指导。
## 许可证
Navlyn 根据 MIT 许可证授权。参见 [`LICENSE`](LICENSE)。
标签：macOS, MCP, Roslyn, 代码导航, 多人体追踪, 开发辅助工具, 文档结构分析