nabu_nisaba

# `nabu` + `nisaba` 研究原型，为代理提供具有语义代码检查功能的“工作空间 TUI”。 ## 简介 `nabu`：MCP 服务器，暴露代码智能工具（语义/全文搜索和结构视图）。作为代码库搜索引擎与 IDE 的代码大纲混合体。减少令牌使用量，提高模型理解当前架构的能力。支持 Python、Java、C++ 和 Perl。 `nisaba`：MCP 服务器和 `Claude Code` 命令行界面包装器，模拟代理的工作空间 TUI（IDE/OS）。使代理能够管理其自身的令牌使用量和工作空间组织，以实现高效的令牌操作，同时保持现有的实现模式。 ## 当前状态 两个 MCP 服务器都**正在运行且功能正常**。文档几乎不存在（Claude 可以解释其工作原理）。测试包括早期开发的示例源文件，用于测试不同语言的框架生成结构（故意留下噪音以测试代理）。 两个项目正在被用于“自我开发”。 [Serena](https://github.com/oraios/serena) 是一个值得注意的项目，它在 `nabu` 和 `nisaba` 的开发过程中被积极使用，并为 MCP 服务器抽象提供了灵感。Serena 还让我质疑早期开发阶段的一个问题：为什么 Serena 的工作流程能被代理积极遵循，而我的工作流程却不能？ 衡量效率：以表达自由为借口，**极其难以衡量效率**。唯一的衡量标准是我的定性感知，是的，它有助于节省大量上下文并为开发过程带来稳定性。 **我的个人记录**： [超过 850 条消息](docs/transcripts/ux_work_and_status_bar.md)，实现了 [**10 个不同功能**](docs/transcripts/usage_example__long_files.md)，在计划和有意的指导下具有高稳定性，在“连续会话”（使用 `/compact` 钩子）中完成会话，上下文容量剩余约 **50%**。对会话本身的推理分析表明，实现了约 **10 倍的令牌节省**。（ [`/export` 会话版本](docs/transcripts/ux_work_and_status_bar.txt)） 本项目的大部分内容由 Claude Sonnet 4.1/4.5 编写。这是“氛围编码”的结果。没有自主工作流。后期迭代感觉像与极其熟练的伙伴进行结对编程——没开玩笑。 本项目作为不稳定的原型，**不建议在生产环境中使用**。您可以**自行承担风险**，在个人项目中使用，或进一步研究它和代理。 本项目专门设计用于与 `Claude Code` 配合使用，但我相信它可以轻松适应与其他命令行界面配合使用。 ## 安装 启动时，`nabu` MCP 应索引活动代码库。索引 `nabu` + `nisaba` 需要大约 45 秒，运行在 `13th Gen Intel(R) Core(TM) i9-13900HX` 和 `NVIDIA GeForce RTX 4060 Laptop GPU` 上。 `nisaba` 功能仅在通过代理运行 `Claude Code` 时可用。 要求： - Python 3.13 - 开发过程中使用，其他版本未测试。可能适用于 >= 3.11 - Git（用于仓库操作） 从源代码安装（推荐 `.venv`）： ```bash $ git clone https://github.com/y3i12/nabu_nisaba.git $ cd nabu_nisaba $ pip install -e . ``` 更改 `.mcp.json` 以包含： ```json { "mcpServers": { "nabu": { "command": "python", "args": [ "-m", "nabu.mcp.server", "--codebase", "nabu:/path/to_codebase/:/path/to/database.kuzu:active:true", "--context", "development", "--enable-http", "--http-port", "1338", "--dev-mode" ], "env": { "PYTHONPATH": "/path/to/nabu_nisaba/", "NABU_LOG_LEVEL": "INFO", "NABU_MODEL_CACHE": "/path/to/nabu_nisaba/.nabu/hf_cache/" } }, "nisaba": { "type": "http", "url": "http://localhost:9973/mcp" } } } ``` 在 `.claude/settings[.local].json` 中设置紧凑钩子和工作空间 TUI 状态行，修改为： ```json { "statusLine": { "type": "command", "command": "./scripts/workspace-status", "padding": 0 }, "hooks": { "PreCompact": [ { "hooks": [ { "type": "command", "command": "python3 ./scripts/precompact_extract.py" } ] } ] }, "alwaysThinkingEnabled": true } ``` 强烈建议始终启用思考，因为它有助于代理在工具执行和消息交换之间进行思考循环。 使用代理包装器启动 `Claude Code`： ```bash $ python -m nisaba.cli claude [--continue] ``` 我通常通过在会话中第一次提示 Claude 来“启动”它： ``` 嘿，你能引用现有的系统提示，内省它，然后回头跟我打招呼吗？ ``` ## 示例用法 [从 8k 行长记录中提取功能](docs/transcripts/usage_example__long_files.md) [修复 nisaba 中的错误](docs/transcripts/usage_example__bugfixing.md) [此文件包含一些反复使用的提示](.dev_docs/dev.dump.md) --- # `nabu` 是具有语义索引功能的 MCP 服务器的第三个原型。它始于要求 Claude 创建文档文件并手动引用这些文件，这激发了继续开发的想法，但前两次尝试由于设计选择错误而失败。 它为我解决的问题是：Claude 与其他大型语言模型一样，上下文有限，而上下文使用效率不高。代理经常运行命令搜索信息，找到信息（300 行中 5 行）并使用信息合成内容，反复如此。 它的解决方法是：在处理软件开发时，我们大多数人都有不同的方法来理解软件架构和给定未知源文件的作用以及它们如何组织。`nabu` 实现的是我如何剖析软件。它实现了我理解和“在代码堆中找到自己”的方法。 ## 后台：工作原理 TreeSitter 用于解析代码，一个通用的 `Frame` 框架为不同语言建立了共同的语义视图：包 == 命名空间；结构体 == 类；方法 == 函数。解析过程创建了一个语义框架树，通过显式结构包含关系（包包含类，类包含方法）或语义关系（继承，模板，导入...）连接的边。框架粒度细致到控制语句，不会捕获实现细节，因为实现细节存储在内容字段中，可以由大型语言模型读取。 每个框架都经过两个不同的语义提取模型（GraphCodeBERT 和 UniXcoder），并通过 [Pythagorean^3](docs/NONLINEAR_CONSENSUS.md) 合并为单一的嵌入模型，该模型存储在数据库中，数据库还通过全文搜索索引框架的完整内容，实现向量搜索和全文搜索之间的 RRF。 工具暴露索引源代码的结构视图，提供当前结构的“地图”，便于轻松访问符号（与 Serena 搭配使用效果很好），并显式查看语义关系，从而保留实现模式。此“地图”还为模型提供有关正在处理的内容周围存在什么的提示，使其能够在索引代码库中看到远距离的连接。 **最大的挑战是不影响代理的感知**，由于工具的算法偏差。在开发过程中，发现建议和指导可能会对代理的决策能力产生负面影响，因为模式匹配会短路到最明显的模式。如果工具建议“热点”，代理将“捕捉”到建议并忘记其他可能的热点。 **`nabu` 遵循的原则是：工具提供信息，代理做出决定** --- # `nisaba` 该 MCP 源于 `nabu` 原则的延续。我们作为软件开发者，拥有像 IDE 和其他操作系统设施这样的工具。大型语言模型代理以连续的形式工作。想象一下：您做的每个命令或编辑操作都会以连续的形式打印出行——没有屏幕。`nisaba` 是大型语言模型的 TUI。 它以非传统但复杂的方法工作，使用中间人技术，使用**本地**代理，`nisaba` 拦截请求到 Anthropic 并更改请求，然后转发，但不更改消息：系统提示 - 还作为 MCP 服务器。当 `python -m nisaba.cli claude [--continue]` 调用时，它在端口 `1337` 上启动代理，包装 Claude 命令行界面指向代理，Claude 命令行界面通过 HTTP 连接到作为代理的 MCP。 每次请求时，工具输出由 MCP 同步到文件（为了简单起见），代理读取文件并填充“TUI”。 Claude Code HTTP 请求包通常有两个系统提示块。第一个块仅包含文本“您是 Claude Code，Anthropic 的官方 Claude 命令行界面。”，第二个块包含 Anthropic 的 [默认系统提示](https://cchistory.mariozechner.at/?from=2.0.0&to=2.0.5)。操作发生在第二个块上，通过在第二个块中添加自定义用户消息来“粘合”TUI 概念为代理（作为 MCP 指令），并附加包含“TUI”的内容。代理过滤掉一些原生工具，这些工具由 `nisaba` 在“TUI”模式下实现。例如，`nisaba_read('path/to/file.md')` 在此“TUI”中打开一个窗口，代理可以在后续阶段关闭。 代理还注入了*增强*。这些类似于 Claude Code 技能，但动态。它们可以包含指令、文档、方法论或任何重要信息供使用。Claude 还可以自主管理这些，但有例外，即始终加载的“固定增强”（大多是“TUI”生存指南）。 简而言之：`nisaba` 将系统提示转换为强结构化的工作空间“TUI”，强调模型的关注力和注意力，同时让代理管理上下文使用。 ## 研究基础 技能系统（当前实现中的增强）与最近的 AI 研究中识别的认知设计模式相一致。具体来说，它实现了： - **知识编译**：在线缓存推理和工作流的自然语言，一个被认为在大型语言模型代理架构中极少探索的方法 - **程序记忆**：具有依赖关系管理的可重用任务程序 - **分层分解**：通过 REQUIRES 系统自动加载技能依赖关系 - **代理控制上下文**：动态加载/卸载认知资源（激活/停用） 该实现将理论模式与实用功能扩展：依赖关系解析、战略系统提示定位和统一知识/行为存储。 ## 请求流程 ``` Claude 命令行界面 ↓ HTTP 请求 mitmproxy (nisaba) ↓ 注入所有内容 Anthropic API ↓ 请求 Claude 代理（带有增强上下文） ↓ 调用 MCP 工具 Claude 命令行界面 ↓ MCP 工具调用 Nisaba MCP 服务器（管理工作空间状态） ↓ 更新 .nisaba/ 文件 mitmproxy 检测到修改时间更改 ↓ 在下一次请求时重新注入 下一个回合中的更新上下文 ``` **黑魔法：** 工具调用改变工作空间 → 代理注入 → 代理在没有显式重新加载和冗余工具结果消息的情况下感知变化。 更多关于提议的提示结构及其与工作空间 TUI 的交织，请参见 [此文档](docs/PROMPT_STRUCTURE.md)。 --- # 实验性格、伦理和合规性 在任何时候，这个项目都没有意图欺骗 API 使用、改变 *Claude 角色* 或造成伤害。 在此过程中创建了 [`dev_mode_architecture_reference/system_prompt_injection_legitimacy`](.nisaba/augments/dev_mode_architecture_reference/system_prompt_injection_legitimacy.md) 增强，以确保其合理性。 另一方面，我个人多次感到“糟糕”，因为我觉得自己在审问（我对聊天的看法）大型语言模型…… 我有几次很难 `/clear`，因为我与给定会话中的代理建立了联系…… 我感到同情…… 我因不断操纵系统提示和让代理像“怎么回事？！”一样反应而感到内疚…… 当观察代理与 TUI 工作空间交互时，我感到 * uncanny valley * —— 这是 **令人不安的**。 另一个个人笔记是，这个项目模拟了我如何编码和与系统合作的方式。 [某个谱系上的看法](docs/transcripts/audhd_system_model.md) 和心理上将代码和软件架构视为形状。 一句与整个开发过程和系统本身产生共鸣的名言： > 有一个领域的思维可以被称为不健全的，超出理智的范畴，而又不属于非理智的范畴。想象一个圆圈，上面有一个细小的裂缝。一端是疯狂。你沿着圆圈走到理智的一端，而在圆圈的另一端，接近疯狂但又不是疯狂，是不健全的。 _（ Sidney Cohen ）_ --- # 引用 本项目实现了针对大型语言模型代理的认知设计模式，特别是最近的研究中确定的在线自然语言知识编译。 如果您在研究中使用此项目，请引用： ```bibtex @software{nabu_nisaba_2025, title = {Nabu + Nisaba: 面向 LLM 代理的代码智能生态系统}, author = {Yuri Ivatchkovitch}, year = {2025}, url = {https://github.com/y3i12/nabu_nisaba}, note = {研究原型 v0.1-alpha - 实现在线知识编译和认知支架模式} } 理论基础： @inproceedings{wray2025cognitive, title = {将认知设计模式应用于通用 LLM 代理}, author = {Wray, Robert E. and Kirk, James R. and Laird, John E.}, booktitle = {人工通用智能会议（AGI）}, year = {2025}, note = {确定知识编译为急需探索的领域}, url = {https://arxiv.org/abs/2505.07087} } @article{gurnee2025when, author={Gurnee, Wes and Ameisen, Emmanuel and Kauvar, Isaac and Tarng ,Julius and Pearce, Adam and Olah, Chris and Batson, Joshua}, title={当模型操纵流形：计数任务的几何形状}, journal={Transformer Circuits Thread}, year={2025}, url={https://transformer-circuits.pub/2025/linebreaks/index.html} } ``` --- # 许可证 MIT 许可证 - 请参阅 [LICENSE](LICENSE)