企业官网建设流程全解析

如何在编辑器里跑NOAA编码智能体：nooa-acp + Zed的ACP集成实战

【免费下载链接】labs-OO-AgentsNVIDIA Object Oriented Agents: the Pythonic way to build AI Agents.项目地址: https://gitcode.com/gh_mirrors/la/labs-OO-Agents

NOAA（NVIDIA Object Oriented Agents，Pythonic 方式构建 AI 智能体的开源框架）提供nooa-acp适配器包，它是 Agent Client Protocol（ACP） 服务器，让你直接在 Zed 等编辑器里驱动 NOAA 编码智能体——CodeAct 策略、仓库工具、持久 Shell、已安装技能、工作区斜杠命令和持久会话，全部开箱即用。本文将带你用 3 个步骤完成 Zed 与 NOAA 的 ACP 集成，并避开盘子里的 3 个常见坑。

🧩 什么是 nooa-acp：编辑器里的智能体服务器

nooa-acp的定位一句话就能说清：Run the NOOA coding agent inside your editor（让 NOAA 编码智能体跑进你的编辑器）。

它的架构特点很妙：

• 它直接宿主nooa_cli.coding.CodingAgent，而不是另写一套 ACP 实现。仓库指令（AGENTS.md）、编码工具、摘要能力、nooa.skills技能入口，在终端和编辑器里共享同一份代码——改一处，两边同时生效。
• 它通过 stdin/stdout 走 JSON-RPC 说 ACP 协议，诊断信息写到 stderr，因此任何"会说 ACP"的客户端都能驱动它，目前最成熟的是Zed。
• 文件编辑和终端命令会以结构化活动卡片（tool call）的形式呈现给编辑器，而不是一坨原始文本。

核心实现在这几处，感兴趣可以一窥究竟：

⚡ Zed 快速上手：3 步接入 NOAA

第 1 步：安装 nooa-acp

uv add nooa-acp # 或者：uv add "nooa[acp]"

💡注意：nooa-acp 没有默认模型。必须设置NOOA_MODEL环境变量或传--model，否则命令会以用法错误退出（见 cli.py）。

第 2 步：在 Zed 中注册外部智能体

Zed 把 ACP 智能体作为"external agents"启动。打开 Zed 设置（快捷键cmd-,），在settings.json中加入：

{ "agent_servers": { "NOOA": { "type": "custom", "command": "uvx", "args": ["nooa-acp"], "env": { "NOOA_MODEL": "nvidia_nim/nvidia/nemotron-3-super-120b-a12b", "NVIDIA_API_KEY": "nvapi-..." } } } }

如果你是从本仓库检出代码开发，可以指向工作区内的包：

uv run --project "$PWD" --package nooa-acp -- nooa-acp

第 3 步：打开项目，选择 NOOA

打开你的代码仓库，在 Zed 的智能体面板中点+菜单，选择NOOA即可开始对话。Zed 会以你的工作树（worktree）作为工作目录启动命令，因此仓库指令、项目技能与会话都会针对当前项目解析。

🔐凭据小贴士：API Key 放在env里而不是 Zed 自己的设置中——智能体是独立进程，只继承 Zed 传给它的东西。如果不想把密钥写进settings.json，可以用一个密钥管理器包装脚本作为command。

🛠 编辑器里能干什么：结构化活动、会话与斜杠命令

接入后，NOOA 在 Zed 里的表现和它的终端 TUI 几乎一致，因为底层就是同一个CodingAgent（定义见 packages/nooa-cli/src/nooa_cli/coding/agent.py）：

• 结构化活动卡片：event_bridge.py 订阅了PythonOutput、FileEdit、TerminalCommandStarted/Output/Finished等事件。Python 单元格会显示为带源码和Out[n]输出的卡片；文件编辑会渲染成diff；终端命令会流式滚动输出，就像在编辑器里长出了一个透明的终端。
• 持久会话：会话保存在<workspace>/.nooa/sessions，TUI 和 ACP 适配器共享同一份会话列表与回放元数据。关闭 Zed 再打开，历史对话可以完整回放（server.py 的_replay_session）。
• 斜杠命令：技能里声明的@slash_command方法会通过 ACP 广播给客户端，输入/command 参数即可触发，语义与原生 TUI 完全一致（prompt 分发逻辑）。
• 用量与成本：每次 LLM 响应都会向客户端发送usage_update，包含上下文占用与累计花费（event_bridge.py）。

⚠️ 避坑指南：3 个必须知道的限制

坑 1：Zed 里的远程 MCP 服务器不会传给 NOAA

这是一个已知的 Zed 限制：你在 Zed 内部完成 OAuth 认证的远程 MCP 服务器，其令牌由 Zed 自己持有，不会下传给 ACP 智能体——结果就是那个在 Zed 界面显示绿色指示灯的服务器，到 NOAA 这里只剩authenticate桩方法。本地 stdio MCP 服务器不受影响。

✅正确做法：通过 NOOA 自己的.mcp.json直接配置 MCP 服务器，让 NOAA 拥有连接和凭据，一切正常。

坑 2：打开仓库 = 执行仓库里的代码

创建会话时（session/new/session/load），NOOA 会先导入工作区的 Python 代码——这是工作区技能的工作机制，但意味着"打开文件夹"就可能执行其中的模块级代码。三条加载路径包括.agents/skills等技能根目录、<workspace>/.nooa/settings.yaml中声明的额外技能目录、以及.nooa/libs/<package>/库目录。

🛡️安全准则：只在你愿意运行其代码的仓库上打开 NOAA；处理不受信任的任务时，请使用操作系统级沙箱，或为每个工作区启动独立服务器并收紧凭据范围。

坑 3：一个 ACP 服务器进程服务多个工作区

当前 stdio 适配器把活会话宿主在自己的进程里（_runtime.py 的SessionRuntime）。若两个工作区加载同名的顶级 Python 包，会产生导入遮蔽——为这类工作区各起一个独立的 stdio 服务器即可。

📚 延伸阅读

• nooa-acp 完整文档：packages/nooa-acp/README.md
• 包清单与nooa-acp入口点定义：packages/nooa-acp/pyproject.toml
• CLI 宿主（TUI）侧的 ACP 说明：packages/nooa-cli/README.md
• 协议与运行时测试：packages/nooa-acp/tests/test_protocol.py、packages/nooa-acp/tests/test_runtime.py

总结

nooa-acp用一行uv add和一段settings.json配置，就把 NOAA 的完整编码能力——CodeAct 执行、仓库工具、技能体系、持久会话——搬进了 Zed 编辑器。它没有为 ACP 重写轮子，而是直接宿主终端宿主用的同一个CodingAgent，所以编辑器体验和终端体验天然一致。只要记住"先装包、再配 Zed、只开可信仓库"三件事，你就可以在编辑器里享受一个透明、可控、带 diff 视图的 NOAA 编码智能体了。

【免费下载链接】labs-OO-AgentsNVIDIA Object Oriented Agents: the Pythonic way to build AI Agents.项目地址: https://gitcode.com/gh_mirrors/la/labs-OO-Agents