NTS MCP FS

🛡️ NTS MCP文件系统服务器

模型上下文协议的下一个事务服务器

  ](https://www.docker.com/)    

______________________________________________________________________

NTS_MCP_FS 是用于的企业级文件系统服务器实现 模型上下文协议（MCP）.

它将标准文件操作转换为 AI代理的事务操作系统与允许“盲”覆盖的基本工具不同，NTS强制执行 乐观锁定，提供了一个 持续HUD，并启用 原子脚本 通过可编程的批处理。

🚀 关键差异点

______________________________________________________________________

📦 安装与使用

先决条件： Java 25+

为什么选择Java 25+？ NTS使用 jdk.jfr.consumer 流式API改进（JDK 25），增强 jcmd 诊断命令，以及 ScopedValue 用于任务范围的上下文传播。虚拟线程（21年预览，25年生产）始终用于非阻塞I/O。Docker可用于无法升级的环境。

1.快速启动（自动集成）

构建并运行集成器，以自动配置支持的客户端（Gemini CLI、OpenCode、Codex、Claude Code、Qwen CLI、Cursor、LM Studio、Antigravity、Copilot VS Code）。

./gradlew shadowJar
java -jar app/build/libs/app-all.jar --integrate

2.手动配置

添加到您的 mcp-config.json:

{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/nts-mcp-fs/app/build/libs/app-all.jar"
      ]
    }
  }
}

3.Docker（不需要Java）

Docker消除了在本地安装Java 25+的需要。服务器在容器中运行，其中项目目录作为卷装载。

重要提示：Docker模式和根 在Docker中，您必须显式挂载目录并通过以下方式指定它们 NTS_DOCKER_ROOTS这些根 以（权力）否决 MCP客户端发送的任何根，因为客户端发送的主机路径在容器内不存在。

选项A：使用预构建图像（推荐）

docker pull ghcr.io/nefrols/nts-mcp-fs:latest

单个项目：

{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/myproject:/mnt/project",
        "-e", "NTS_DOCKER_ROOTS=/mnt/project",
        "ghcr.io/nefrols/nts-mcp-fs:latest"
      ]
    }
  }
}

多个项目：

{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/project1:/mnt/p1",
        "-v", "/home/user/project2:/mnt/p2",
        "-e", "NTS_DOCKER_ROOTS=/mnt/p1:/mnt/p2",
        "ghcr.io/nefrols/nts-mcp-fs:latest"
      ]
    }
  }
}

选项B：在本地构建

docker build -t nts-mcp-fs .
docker run -i --rm \
  -v /path/to/project:/mnt/project \
  -e NTS_DOCKER_ROOTS=/mnt/project \
  nts-mcp-fs

环境变量：

可用图像标签：

______________________________________________________________________

🎯 哲学：通过有意摩擦来训练人工智能

“我们的目标不是让代理人的工作更容易，而是让代理人的作品更可靠。”

大多数MCP服务器都针对以下方面进行了优化 便利：更少的呼叫，更短的响应，最大程度的自动化。NTS采取了相反的方法。介绍 故意摩擦 这迫使人工智能代理以手术精度工作。

问题：长期会议中的灾难性漂移

当AI代理处理复杂任务（1-2M+令牌）时，上下文摘要不可避免地会丢失细节。代理“忘记”了50条消息前读到的内容。然后：

1. 🔴 代理基于过时内存编辑第347行
2. 🔴 编辑破坏了一些东西——特工恐慌
3. 🔴 代理进入不受控制的修复循环
4. 🔴 数小时的工作在几秒钟内被摧毁

这不是一个bug，而是LLM处理长上下文的一个紧急特性。 NTS旨在防止这种故障模式。

解决方案：通过LAT强制浓缩

线路接入令牌（LAT） 它们不仅仅是一种安全功能 认知约束.

┌─────────────────────────────────────────────────────────────────┐
│  Without LAT:                                                   │
│  "I'll just read the whole file... it's only 400 lines"        │
│   → Context bloated with "just in case" data                    │
│   → Summarization drops critical details                        │
│   → Agent edits wrong line from fuzzy memory                    │
│   → Catastrophic error                                          │
├─────────────────────────────────────────────────────────────────┤
│  With LAT:                                                      │
│  "I need to edit line 47. Let me read lines 40-55."            │
│   → Agent explicitly decides what it needs                      │
│   → Token proves agent saw current state                        │
│   → Context stays clean and precise                             │
│   → Edits are surgical and verified                             │
└─────────────────────────────────────────────────────────────────┘

代理人 不能 用一个懒惰命令读取整个文件。它必须指定范围。这迫使代理人 三思而后行 --这正是防止漂移的纪律。

为什么冗长的回答很重要

每 nts_edit_file 响应包含一个完整的统一diff。这不是可选的冗长，而是 强制性验证.

--- User.java (original)
+++ User.java (modified)
@@ -15,7 +15,7 @@
     }
 
-    public String getName() {
+    public String getFullName() {
         return name;
     }

代理人看到结果 立即，在同样的回答中。不需要单独的“验证”步骤。没有机会“忘记”检查。差异就是证据。

现实世界影响

反直觉真理

在纪律上多花10%的代币可以节省100%的浪费工作。

在API调用中，2小时的代理会话成本约为5-15美元。一个破坏这项工作的灾难性错误的成本是相同的 再次 重做——再加上人工时间来诊断出了什么问题。

NTS以微观效率换取宏观可靠性。代理每次操作都会稍微努力一些，但 整个会话成功 而不是在1:45时坍塌。

🧠 高级功能深潜

1.📟 Agent HUD（平视显示器）

服务器将状态标头注入 *每* 工具响应。代理永远不会失去上下文。

[HUD tid:a1b2] Plan: Refactor Auth [✓2 ○1] → #3: Update Login | Task: 5 edits | Unlocked: 3 files
[MEMORY: Auth tokens must use RS256 | DB migration pending review]

• 任务上下文： 提醒代理活动的任务ID。
• 进度跟踪： 显示当前TODO状态（完成/待定）和 *下一个* 主动任务。
• 安全统计： 显示当前解锁编辑的文件数量。
• 代理内存： 节目 [MEMORY: ...] 线路从 nts_context HUD注释——关键提醒在上下文压缩中幸存下来。

2.📜 可编程原子批处理（脚本）

这 nts_batch_tools 不仅仅是命令列表；它是文件系统的脚本引擎。

• 原子事务： 一个请求中包含10个操作。如果第10个失败，前9个将立即回滚。该项目从未处于崩溃状态。
• 变量插值： 在步骤之间传递数据。在步骤1中创建一个文件，然后在步骤2中使用引用其路径 {{step1.path}}.
• 虚拟地址： 使用以下变量 $LAST 或 $PREV_END+1 插入与之前编辑相关的代码，而不计算行号。
• 虚拟FS上下文： 当您在步骤1中编辑文件并运行 nts_code_refactor 在步骤2中，重构看到 修改内容 从步骤1开始，而不是磁盘版本。启用复杂的链，如“编辑类”→ 在整个项目中重命名符号”。

示例脚本： 创建一个服务，重命名它，并添加一个方法

"actions": [
  { "id": "cre", "tool": "nts_file_manage", "params": { "action": "create", "path": "Temp.java", "content": "class Svc {}" } },
  { "tool": "nts_file_manage", "params": { "action": "rename", "path": "{{cre.path}}", "newName": "UserService.java" } },
  { "tool": "nts_edit_file", "params": { "path": "{{cre.path}}", "startLine": "$LAST", "operation": "insert_after", "content": "void login() {}", "accessToken": "{{cre.token}}" } }
]

*注： {{cre.path}} 自动解析为 UserService.java 在重命名步骤之后！*

3.🔒 企业安全与沙盒

• 乐观锁定（LAT）： 代理 *必须* 读取文件以获取令牌(LAT:...)在编辑之前。如果文件在外部更改，令牌将过期，外部更改将自动记录在文件历史记录中。没有更多的比赛条件。
• 智能令牌无效： 代币追踪 范围CRC 而不是文件CRC。超出令牌范围的编辑不会使其无效，只会触发重新读取您正在处理的特定行的更改。这大大减少了大文件中不必要的令牌刷新。
• 路径别名： 令牌在以下时间后仍然有效 move/rename 操作。该系统通过具有可传递解析的路径别名跟踪文件身份，甚至是像这样的链 A → B → C 保持令牌有效性。
• 严格装箱： 所有路径都被规范化并固定到项目根。无法通过 ../../.
• 基础设施保护： 自动阻止修改 .git, .env，并构建配置，除非明确允许。
• OOM保护： 防止读取会导致上下文窗口崩溃的大量文件（>10MB）。
• 结构化错误代码： 所有错误都包括机器可读代码(FILE_NOT_FOUND, TOKEN_EXPIRED等等）与人类可读的解决方案。没有更多神秘的异常-每个错误告诉你到底出了什么问题以及如何修复。

4.⏪ 状态管理：检查点和深度撤消

• 任务日志（H2数据库）： 记录每个逻辑步骤（不仅仅是文件IO）。在嵌入式H2数据库中保持不变——在服务器重启后幸存下来。
• 内存快照： 撤消存储器中的发动机使用 byte[] 快照而不是基于文件的备份，以实现更快的恢复。
• 检查点： 代理可以运行 nts_task checkpoint('pre-refactor') 安全 rollback 如果该方法失败。
• 深度撤消： 系统跟踪 文件血统.如果你搬家 FileA -> FileB 然后点击撤消，NTS知道要将内容恢复到 FileA.
• Git集成： 可以创建Git仓库作为紧急备用(git_checkpoint).

5.👁️ 外部变更跟踪

服务器会自动检测文件何时被修改 MCP之外 （按用户、linter、IDE或其他工具）。

• 基于CRC的检测： 每次读取文件都会创建一个快照。在下次访问时，如果CRC不同，则检测到更改。
• 文件历史记录： 外部更改记录在文件历史记录中，可以通过以下方式查看 nts_task journal.
• 智能提示： 当检测到外部更改时，代理会收到TIP，建议在继续操作之前查看更改，因为这些更改可能是用户有意编辑的。
• 撤消支持： 如果需要，可以通过标准撤消机制撤消外部更改。

6.💡 智能情境TIP

每个工具响应都包含智能上下文提示，指导代理完成最佳工作流程。

• 工作流程指南： 每次操作后，TIP都会建议逻辑上的下一步（例如，“令牌已准备好进行编辑→ nts_edit_file（…）”）。
• 性能提示： 大范围读取会触发建议使用基于符号的导航或grep来提高精度。
• 错误预防： 模式分析检测未使用正则表达式的查询 isRegex=true 并主动发出警告。
• 令牌管理： 当行数在编辑后发生变化时，TIP会提醒您在后续操作中使用NEW令牌。
• 重构意识： 签名更改会触发通过以下方式检查呼叫站点的建议 nts_code_navigate(action='references').
• 导入更新： 在移动/重命名Java/Kotlin文件后，TIP建议搜索需要更新的导入语句。

TIPs示例：

[WORKFLOW: Token ready for editing -> nts_edit_file(path, startLine, content, accessToken)]
[TIP: Large range read (150 lines). Consider using 'symbol' parameter for precise symbol boundaries.]
[TIP: Pattern contains regex-like characters (.*). If you intended regex search, add isRegex=true parameter.]
[TIP: Line count changed (+5). Use NEW TOKEN above for subsequent edits to this file.]

7.✅ 内置TODO系统

专用工具(nts_todo)允许代理维护基于Markdown的计划。

• 活动计划状态被输入到 平视显示器.
• 让代理一次专注于一项任务。
• 自动更新状态(todo, done, failed)在文件系统中。

8.🧭 LSP导航（树保姆）

这 nts_code_navigate 该工具提供了由Tree sitter支持的类似IDE的代码智能。

• 转到定义： 跳转到定义符号的位置。
• 查找参考文献： 查找整个项目中的所有用法。
• 悬停： 获取任何符号的类型、签名和文档。
• 列出符号： 包含所有定义的文件大纲。
• 12种语言： Java、Kotlin、JS/TS/TSX、Python、Go、Rust、C/C++、C#、PHP、HTML。
• 扩展Java支持： 枚举常量为 CONSTANT 符号、类与构造函数自动解析， kind 过滤和 brief 大文件压缩输出模式。
• 结构化处置合同： 语义操作现在返回 resolutionStatus, resolutionKind, usedFallback, safeForAutonomousEdit, candidateCount, target，以及 candidates.
• 严格模式： strict=true 拒绝回退和模糊的光标解析，而不是默默地猜测目标。
• 歧义信号： 显式返回过载或附近光标模糊，以便代理可以在进行不安全的编辑之前停止。

9. 🔄 语义重构（10个操作）

这 nts_code_refactor 该工具执行智能代码转换。

• 重命名： 字节跨度重写（UTF-8安全），具有过载感知功能 SymbolHandle 匹配。更新整个项目中的所有引用。
• 更改签名： AST重写声明和调用站点。基于动作的参数(add, remove, rename, retype, reorder)具有自动过载消歧功能。
• 提取方法： 将代码拉入一个具有安全验证（转义变量检测）和智能返回类型推理的新方法中。
• 提取变量： 通过事件归一化、平衡表达式验证和 replaceAll 支持。
• 内联： 支持AST的调用站点重写，具有参数替换、优先级安全括号和多出现支持。
• 移动： 通过静态方法引用更新、导入重新布线和实例方法安全防护来重新定位类/方法。
• 包装： 用try-catch、if块或带有转义变量范围检查的循环来包装代码。
• 删除： 语句级重写(findStatementSegment)而不是整行删除。通过签名/位置进行过载保护。
• 生成： 创建具有最终字段安全性和重复检测的getter、setter、constructor、builders、toString、equals/hashCode。
• 批次： 将多个重构操作与参数规范化和继承原子地结合起来。
• 预览模式： 申请前审查差异(preview: true).
• 平行参考搜索： 两者 nts_code_navigate 和 nts_code_refactor 使用带有预过滤的并行文件扫描，搜索深度可达15级，以获得最大覆盖范围。
• 批量集成： 成功应用响应返回 affectedFiles 为每个修改后的文件添加标记的数组——启用类似链接 refactor → edit 在 nts_batch_tools.
• 结构化验证： 语义预览/应用使机器可读 validation 元数据和 affectedFileCount.
• 无效输出回滚： 所有变异操作在应用后都会通过SyntaxChecker验证更改的文件，并在语法断裂时进行原子回滚。
• 风险元数据： 每个回复都包括 confidence （精确/混合）， riskLevel （低/中）， rewriteStrategy （语义span/hybrid_span/line_fallback），以及详细信息 validation 对象。
• 混合透明度： 混合重命名预览公开 hybridMode, semanticMatchCount, textOnlyMatchCount，以及出处，因此纯文本匹配永远不会被隐藏。

{
  "action": "rename",
  "path": "src/User.java",
  "symbol": "getName",
  "newName": "getFullName",
  "preview": true
}

预览响应公开了结构化验证和文件计数：

{
  "status": "preview",
  "affectedFileCount": 2,
  "hybridMode": false,
  "semanticMatchCount": 2,
  "validation": {
    "targetCountExpected": 2,
    "targetCountMatched": 2,
    "declarationCountUpdated": 1,
    "callSiteCountUpdated": 1,
    "astParseAfterEdit": true
  }
}

应用响应包括批处理就绪令牌：

{
  "status": "success",
  "affectedFileCount": 1,
  "affectedFiles": [
    { "path": "src/User.java", "accessToken": "LAT:...", "crc32c": "A1B2C3D4", "lineCount": 50 }
  ],
  "token": "LAT:..."
}

10. 🧠 代理上下文内存(nts_context)

这 nts_context 工具为代理提供 结构化、任务范围内存 --手动编辑内存的原生替代方案。MD文件。

• HUD注释(kind='hud_note'): 出现在中的关键提醒 每 通过HUD线路进行工具响应。生存上下文压缩和提示摘要。
• 上下文注释(kind='note'): 更广泛的发现、根本原因、用户限制——存储以供恢复，但不会在每个响应中显示。
• 重要性级别： critical > high > normal --控件显示优先级和排序。
• 快照恢复： action='snapshot' 返回完整的任务图片：TODO进度、最近修改的文件、最近5次日志操作、活动HUD注释、所有上下文注释和建议的下一步操作。专为上下文压缩后的重新定向而设计。
• CRUD API： add, read, update, delete, list --全生命周期管理。
• 上下文提示： 其他工具(nts_edit_file, nts_todo, nts_verify)通过TIP提示轻轻推动代理以保存持久的发现。

Agent discovers root cause → saves as hud_note
  → Every subsequent tool response shows: [MEMORY: Auth tokens must use RS256]
  → Context compressed after 500 messages
  → Agent calls snapshot → full picture restored in one call

11. ☕ Java开发套件

NTS提供 扩展Java支持 除了12种语言的树形图功能之外。虽然AST导航、重构和语法检查跨所有支持的语言工作，但Java生态系统获得了专门的高级工具，这些工具旨在以最小的认知负荷实现最大的代理生产力。

设计理念： 每个Java工具都在 最高抽象级别代理不管理JFR会话、解析直方图或从头开始构造Gradle命令——它声明意图（“分析此”、“构建项目”、“显示堆”）并接收可操作的结果。这减少了认知负荷，节省了令牌，并让代理专注于问题，而不是工具。

AST智能（扩展到Java）

以树保姆为基础 nts_code_navigate 和 nts_code_refactor 支持12种语言，但Java 增强的能力:

• 枚举常量提取 --枚举值显示为 CONSTANT 导航中的符号
• 构造函数感知重命名 --类重命名会自动重命名所有构造函数（Java要求构造函数名=类名）
• 导入感知移动 --移动课程通过智能TIP触发导入更新建议
• 过载消歧 --方法签名匹配使用结构化AST参数，而不是字符串启发式方法
• 符号过滤 — symbols(kind='method', brief=true) 为大型类提供紧凑的输出（将令牌保存在2000多行文件中）

Gradle构建集成(nts_gradle_task)

高级构建自动化——代理在不考虑包装脚本或平台细节的情况下说“构建”或“测试”。

• 智能后端切换： 用途 gradlew 如果存在，则回退到系统 gradle，或自动生成包装器
• 项目初始化： task='init', initType='java-application' 创建完整的项目脚手架
• 解析输出： 编译错误返回 file:line 参考文献测试结果包括通过/失败/跳过计数
• 异步支持： 长构建返回a processId --代理可以继续其他工作并通过以下方式进行轮询 nts_process

JFR分析器(nts_java_profiler)

一次通话分析 --在单个工具调用中附加到任何JVM、记录、解析并获取执行摘要。

discover → profile(focus='cpu', 30s) → analyze(focus='contention') → compare(before, after)

• 6个重点领域： cpu, cpu-time （JDK 25+）， memory, contention, gc, io，或 all
• 重新分析而不重新记录： 相同的录音，不同的焦点——节省时间和时间
• Delta比较： 使用标准化每秒速率进行分析之前/之后
• 竞争加剧： JavaMonitorEnter、Object.wait（）、ThreadPark——带有调用站点和阻塞线程排名
• 智能提示： IO数据为空的NIO服务器会收到NIO特定的建议。ZGC以最小的停顿获得了无休止的收集者笔记

内存分析器(nts_java_memory)

回答“堆上有什么？”和“正在分配什么？”——与分析器分开，因为这是根本不同的问题。

snapshot(baseline) → exercise code → snapshot(after) → compare → find leak candidates

• 即时直方图： jcmd GC.class_histogram --结果以毫秒为单位，无需录制
• 泄漏检测工作流程： 两张快照→ 比较→ 增长最快的类=泄漏候选者
• 分配压力： 基于JFR的分配记录按呼叫站点的分配率显示了顶级类型
• 自动判决： 快照比较包括自动“泄漏信号”/“无泄漏信号”结论

为什么Java受到特殊待遇

______________________________________________________________________

🛠️ 工具链：一个学科体系，而不仅仅是实用工具

NTS中的每个工具都是作为 互联学科体系它们不仅执行操作，还强制执行一个工作流，使代理保持专注、验证和可恢复。

┌─────────────────────────────────────────────────────────────────────────────┐
│                        THE NTS DISCIPLINE LOOP                              │
│                                                                             │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐          │
│   │  INIT    │────▶│  READ    │────▶│  EDIT    │────▶│  VERIFY  │          │
│   │  Task    │     │ + Token  │     │ + Token  │     │(Diff/AST)│          │
│   └──────────┘     └──────────┘     └──────────┘     └────┬─────┘          │
│        │                                                   │                │
│        │              ┌──────────┐                         │                │
│        └─────────────▶│  UNDO    │◀────────────────────────┘                │
│         (if panic)    │ Recovery │    (if wrong)                            │
│                       └──────────┘                                          │
└─────────────────────────────────────────────────────────────────────────────┘

______________________________________________________________________

🔐 nts_init --责任边界

为什么存在： 创建具有自己的撤消历史记录、检查点和令牌注册表的隔离任务。

学科角色： 特工所做的一切都会被追踪。没有“匿名”编辑。如果发生故障，任务日志会确切地知道发生了什么以及何时发生的。

任务重新激活： 如果服务器重新启动或连接中断，可以重新激活任务：

{ "taskId": "your-previous-uuid" }

这将恢复包含todos和文件历史记录的任务目录。内存状态（令牌、撤消堆栈）重新开始，但保留了磁盘持久数据（H2日志）。

连接： 所有其他工具都需要 taskId这不是官僚主义 可追溯性.

子任务（并行代理）：

当多个代理同时处理同一代码库时（例如，一个重构后端，另一个更新前端），子任务提供 独立的撤消/重做堆栈 同时共享相同的项目根。

                    ┌─────────────┐
                    │  nts_init() │  ← Parent agent
                    │  taskId: A  │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼                         ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ nts_init(        │     │ nts_init(        │
    │  parentTaskId=A) │     │  parentTaskId=A) │
    │ taskId: A:sub-x  │     │ taskId: A:sub-y  │
    │ [own undo stack] │     │ [own undo stack] │
    └────────┬────────┘     └────────┬────────┘
             │                       │
             ▼                       ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ merge → parent  │     │ rollback (fail)  │
    │ (one undo entry)│     │ (all reverted)   │
    └─────────────────┘     └─────────────────┘

生命周期：

// 1. Sub-agent creates isolated sub-task
{"parentTaskId": "A"}
→ {"taskId": "A:sub-x1b2c3d4", "isSubTask": true}

// 2. Sub-agent works using sub-taskId in all calls
{"taskId": "A:sub-x1b2c3d4", "path": "Backend.java", ...}

// 3a. On SUCCESS — merge into parent (one grouped undo entry)
{"action": "merge", "childTaskId": "A:sub-x1b2c3d4", "taskId": "A"}

// 3b. On FAILURE — rollback all sub-task edits
{"action": "rollback", "childTaskId": "A:sub-x1b2c3d4", "taskId": "A"}

关键规则：

• 子任务从父任务继承工作目录和项目根目录
• 子任务有其 拥有 撤销/重做堆栈、文件令牌、TODO计划
• 合并后，父级可以使用一个命令撤消所有子代理编辑 nts_task(action='undo')
• 仅限不同文件： 子任务是为代理编辑非重叠文件而设计的。如果两个子任务试图编辑同一文件区域，CRC令牌将阻止第二个写入器
• 不要将子任务用于简单的顺序工作流——它们会增加开销

______________________________________________________________________

📖 nts_file_read --注意力之门

为什么存在： 读取文件内容并发出 线路接入令牌（LAT）.

学科角色： 代理人必须 明确决定 它需要哪些线路。没有“只读一切”的快捷方式。

❌ read({ path: "file.java" })                    // NOT ALLOWED
✅ read({ path: "file.java", startLine: 10, endLine: 30 })  // Forced precision

连接： 这里返回的令牌是 必需的 为了 nts_edit_file.阅读→ 代币→ Edit.没有捷径。

智能TIP： 响应包括工作流提示（例如，“令牌已准备好编辑”），并建议对大范围进行基于符号的读取。

批量阅读： 在单个请求中读取多个相关文件：

{
  "bulk": [
    { "path": "UserService.java", "symbol": "createUser" },
    { "path": "UserRepository.java", "symbol": "save" },
    { "path": "User.java", "startLine": 1, "endLine": 30 }
  ]
}

每个文件在输出中都用自己的TOKEN分隔。一个文件中的错误不会影响其他文件。

______________________________________________________________________

✏️ nts_edit_file --已验证的突变

为什么存在： 应用基于行的编辑，并强制进行令牌验证。

学科角色：

1. 需要令牌 --证明代理读取当前状态
2. 响应差异 --代理立即看到发生了什么变化
3. CRC校验 --如果文件在外部更改，编辑将安全失败
4. 智能TIP --常见问题的上下文提示：

- 多行内容取代单行内容 endLine → 建议 insert_after 或范围 - 行数已更改→ 提醒在后续编辑中使用NEW标记 - 检测到签名更改→ 建议检查呼叫站点 nts_code_navigate - 重大变化→ 提醒运行测试

连接： 从以下位置消耗令牌 nts_file_read，生成新令牌以供后续编辑。监管链没有中断。

______________________________________________________________________

📁 nts_file_manage --有记忆的结构

为什么存在： 创建、删除、移动、重命名文件和目录。

学科角色：

• create 返回一个令牌——新文件可以立即编辑
• rename/move 通过路径别名传输令牌 --即使在文件被移动后，令牌仍然有效（传递链如 A → B → C 工作）
• delete 使令牌无效 --无编辑重影

连接： 适用于 nts_batch_tools 用于原子多文件重构。路径别名在整个任务中持续存在。

______________________________________________________________________

🔍 nts_file_search --有目的的发现

为什么存在： 查找文件(glob)，搜索内容(grep)，查看结构。

学科角色： grep 回报 匹配范围的令牌。代理可以搜索并立即编辑，而无需单独的读取步骤。

grep("TODO") → finds line 47 → returns TOKEN for lines 45-50
           → agent can edit lines 45-50 directly

智能TIP： grep之后，工作流提示会提醒令牌已准备好直接编辑。如果模式看起来像正则表达式，但 isRegex=false，建议启用它。

连接： 桥梁发现和行动。减少往返次数，同时保持令牌纪律。

______________________________________________________________________

⏪ nts_task --恐慌按钮

为什么存在： 撤消、重做、检查点、回滚和任务日志。

学科角色： 当代理人犯错时，它 结构化恢复 而不是不受控制的修复螺旋式上升。

checkpoint("before-risky-refactor")
  → try dangerous changes
  → if wrong: rollback("before-risky-refactor")
  → project restored in one command

连接： 这是使积极重构成为可能的安全网。代理人可以大胆，因为恢复是有保证的。

______________________________________________________________________

🔗 nts_batch_tools --原子脚本

为什么存在： 将多个工具作为单个原子事务执行。

学科角色： 复杂的操作 完全成功或完全回滚没有半分裂的州。

{
  "actions": [
    { "id": "svc", "tool": "nts_file_manage", "params": { "action": "create", "path": "Service.java" }},
    { "tool": "nts_edit_file", "params": { "path": "{{svc.path}}", "accessToken": "{{svc.token}}", ... }}
  ]
}
// If edit fails → create is rolled back → project untouched

连接： 用途 {{step.token}} 插值。令牌在步骤之间自动流动。这是纪律体系的巅峰。

______________________________________________________________________

🔄 nts_project_replace --受控大规模突变

为什么存在： 在整个项目中进行全局搜索和替换。

学科角色：

• dryRun: true 显示 应用前的所有更改
• 原子：所有文件都已更改或没有更改
• 执行前创建自动检查点

连接： 具有最大保障措施的高风险操作。

______________________________________________________________________

🧭 nts_code_navigate --语义理解

为什么存在： 转到定义、查找引用、悬停信息、符号列表。

学科角色： Agent可以理解代码结构 编辑前。减少猜测，提高精度。

结构化响应合同：

• resolutionStatus: exact, ambiguous, fallback，或 not_found
• resolutionKind：如何解析语义目标
• usedFallback：解析器是否必须降低精度
• safeForAutonomousEdit：结果是否可以安全地输入自主编辑
• candidateCount：考虑的语义候选数
• target：所选 SymbolHandle 当存在一个精确的目标时
• candidates：目标不明确时的候选摘要

扩展Java支持： 枚举常量为 CONSTANT 符号、类与构造函数自动解析， kind 过滤和 brief 大文件压缩输出模式。

连接： 返回已找到位置的令牌。导航→ 理解→ 自信地编辑。

______________________________________________________________________

🔧 nts_code_refactor --智能转型

为什么存在： 重命名符号、更改签名、生成代码、提取方法——具有自动引用更新功能。

学科角色：

• preview: true 显示 所有受影响的文件 申请前
• 语义重命名更新所有引用，而不仅仅是文本匹配
• 原子：整个重构是成功还是失败
• 返回令牌 对于所有已修改的文件--启用 refactor → edit 批量链
• 语义重构公开了机器可读的 validation 和 affectedFileCount
• 标准语义 rename 不再混合文本搜索回退，除非 hybridMode=true
• 混合重命名显式报告 semanticMatchCount, textOnlyMatchCount，以及来源
• Apply path验证语法并回滚无效输出，而不是返回错误的成功

连接： 为了精确起见，使用树保姆。与集成 nts_batch_tools 通过 {{step.affectedFiles[0].accessToken}} 插值。比手动多文件编辑更安全。

______________________________________________________________________

📋 nts_todo --焦点锚

为什么存在： 维护与HUD集成的基于Markdown的任务列表。

学科角色： 让代理人专注于 一次只做一件事HUD不断提醒下一步是什么。

[HUD] Plan: Auth Refactor [✓2 ○3] → #3: Update Login Controller

连接： 防止范围蔓延。即使在上下文摘要之后，Agent也总是知道当前的目标。

______________________________________________________________________

🔀 nts_git --版本控制集成

为什么存在： Git状态、差异、添加、提交——无需离开NTS。

学科角色：

• git_checkpoint 创建藏匿处作为紧急备用
• commit_task 根据TODO进度自动生成提交消息
• 仅限安全操作（无推/力）

连接： 与任务日志集成。提交可以引用已完成的任务。

______________________________________________________________________

📊 nts_compare_files --目视验证

为什么存在： 显示任意两个文件之间的统一差异。

学科角色： 代理可以通过显式比较前后状态来验证更改。

连接： 可用于查看批处理操作或重构的结果。

______________________________________________________________________

⚙️ nts_gradle_task --构建反馈循环

为什么存在： 使用解析后的输出运行Gradle任务（构建、测试、检查）。

学科角色： Agent会立即收到关于更改是否破坏构建的反馈。错误被解析并可操作。

连接： 关闭循环：编辑→ 构建→ Fix → 重复。

______________________________________________________________________

✅ nts_verify --多级验证

为什么存在： 从三个层面验证代码的正确性：语法、编译和测试。

学科角色：

• syntax --快速树保姆AST检查（无需构建）。编辑后立即捕获错误。
• compile --跑步 gradlew build -x test 用于编译验证。
• test --跑步 gradlew test 进行全面测试验证。

连接： 桥梁编辑和建设。代理在没有完整构建周期的情况下验证语法，仅在需要时升级到编译/测试。

______________________________________________________________________

🔍 nts_context --统一任务上下文

为什么存在： 为HUD提醒和压缩后的完整任务上下文恢复提供一个单独的位置。

学科角色：

• add/update/read/delete/list 管理任务范围的上下文条目
• kind='hud_note' 创建始终可见的HUD提醒
• kind='note' 存储更广泛的发现和恢复说明
• snapshot 当代理需要重新定向时，返回当前任务图片
• 该工具的行为类似于结构化的内部 MEMORY.MD，但使用显式操作而不是手动文件编辑

当代理由于提示摘要而丢失上下文时， snapshot 返回：

• 当前任务ID和统计信息
• TODO进度（如果处于活动状态）
• 最近修改的文件
• 最近日记账分录（最近5次操作）
• 活动HUD注释
• 所有存储的上下文注释
• 建议的下一步行动

连接： 将始终打开的提醒和恢复上下文组合到一个本机工具中。代理可以从同一个表面问“我必须记住什么？”和“我在哪里？”，而提示提示则温和地推动它，只保留持久、高价值的上下文。

______________________________________________________________________

🖥️ nts_process --后台流程管理

为什么存在： 监控和控制长时间运行的后台进程（Gradle构建、Git操作）。

学科角色： 代理可以检索日志或终止异步进程，而不会阻塞主工作流。

连接： 适用于 nts_gradle_task 和 nts_git 用于异步操作。

______________________________________________________________________

☕ Java开发套件(nts_gradle_task + nts_java_profiler + nts_java_memory)

为什么存在： Java获得了在意图级别运行的专用高级工具——“构建”、“分析30秒的CPU”、“显示堆”——所有复杂性都在内部处理。

学科角色： 代理从不管理JFR会话、解析原始直方图或构造Gradle命令行。每个工具都返回可操作的、对代理友好的输出。重新分析而不重新记录可以节省令牌。快照比较自动生成泄漏判断。生成错误会随着文件行引用而返回。

连接： 与集成 nts_context 对于持续的发现， nts_verify 用于构建反馈，以及 nts_process 用于异步构建。

______________________________________________________________________

整个系统

这些工具不是独立的实用程序。他们形成了一个 闭环纪律:

1. 任务 建立问责制
2. 阅读 吸引注意力并发行代币
3. 编辑 需要令牌并显示结果
4. 验证 验证更改（语法→ 编译→ test)
5. 任务 在需要时提供恢复
6. 批次 以原子方式实现复杂操作
7. HUD+全部 在长时间的会议中保持专注
8. 上下文 保留持久提醒，并在压缩后恢复任务图片
9. Java套件 为整个Java开发生命周期提供构建、分析和内存分析

每种工具都会强化其他工具。 “盲目编辑”是没有出路的。这门学科是建筑学。

______________________________________________________________________