1. 项目缘起从“盲人摸象”到“全局掌控”最近几个月我的开发工作流几乎被 Anthropic 的 Claude Code CLI 接管了。我得承认终端确实很酷那种敲击命令、看着字符流滚动的感觉充满了极客范儿。但当我开始用它来处理一些真正复杂的任务比如重构一个包含几十个微服务、数千个文件的大型代码仓库时问题就来了。整个过程就像在玩一个没有地图、没有指南针的“盲盒”游戏。最让我头疼的是状态管理。Claude Code 的工作方式本质上是在后台启动一个或多个“智能体”每个智能体都具备特定的“技能”。这些技能可能来自官方库也可能是我自己写的或者从 GitHub 上找来的。它们以 Markdown 文件的形式散落在项目根目录下的.claude文件夹里。我需要某个功能时就得手动去这个文件夹里翻找对应的.md文件把它复制或移动到合适的位置不需要时又得把它删掉或移走。这还不算完每个技能文件里可能还有一堆配置参数需要调整。想象一下当你同时协调五六个智能体每个智能体又加载了七八个技能而你需要临时禁用某个有问题的技能或者调整某个技能的优先级时那种在命令行和文件管理器之间反复横跳、手动编辑配置的体验简直是一场灾难。效率断崖式下跌而且极其容易出错一个手滑可能就破坏了整个工作流。另一个痛点是对执行过程缺乏“可见性”。在终端里你看到的是一行行输出但智能体内部到底在调用哪个技能各个技能之间是如何协作或依赖的当前上下文中加载了哪些代码文件这些信息要么被淹没在海量的日志里要么就根本没有直观的呈现。当一次代码扫描或重构任务因为路径错误而失败时排查问题就像大海捞针。我需要一个能让我“看见”整个智能体系统运行状态的控制面板一个能让我直观地进行编排和管理的界面而不是在黑暗中摸索。正是这种强烈的“摩擦感”驱使我动手构建了 Claude Code Agents UI。我的核心目标非常明确告别“盲目”的终端执行进入一个能够清晰“看见”并高效“管理”智能体能力的新阶段。2. 核心设计思路构建一个可视化的智能体控制平面这个项目的核心定位不是一个简单的“皮肤”或者“美化工具”而是一个完整的可视化控制平面。我把它想象成现代云计算中的 Kubernetes Dashboard 或者 AWS Management Console只不过服务的对象是 Claude Code 智能体。它的设计哲学是“集中管理、直观操作、状态可视”。2.1 技术栈选型为什么是 Nuxt 3 和 VueFlow在技术选型上我主要考虑了前端开发的效率、交互的复杂性以及项目的可维护性。首先我选择了Nuxt 3作为全栈框架。原因有几个第一它对 Vue 3 提供了开箱即用的最佳实践集成包括文件路由、服务器端渲染、API 路由等能让我快速搭建起一个结构清晰的应用。第二Nuxt 3 的“全栈”能力很重要。这个 UI 工具需要与本地文件系统、Claude Code CLI 进程进行深度交互这意味着需要后端逻辑。使用 Nuxt 3我可以在同一个项目里用server/api目录轻松创建 API 端点来处理文件读写、进程调用等操作避免了额外维护一个独立后端服务的复杂度。第三其开发体验和构建性能都非常出色对于这样一个需要快速迭代的个人工具项目来说再合适不过。其次对于最关键的关系可视化部分我选择了VueFlow。这是一个基于 Vue 3 的流程图/节点图库。我需要将智能体、技能、命令之间的复杂关系用图形化的方式呈现出来。VueFlow 提供了丰富的节点、边类型以及拖拽、连线、缩放、布局等交互功能并且与 Vue 3 的响应式系统结合得非常好。我可以轻松地将后端获取的智能体元数据映射成不同类型的节点比如圆形代表智能体矩形代表技能菱形代表命令并用有向边表示它们之间的调用或依赖关系。这比纯文本的依赖描述要直观一万倍。2.2 架构概览前后端如何协同工作整个应用采用前后端分离的架构但得益于 Nuxt 3它们被整合在同一个代码库中部署和运行都非常简单。前端部分主要由几个核心视图构成仪表盘总览所有活跃的智能体、系统资源消耗和最近活动。智能体管理面板列表显示所有可用的智能体支持创建、启动、停止、配置。技能市场/仓库一个可以浏览、搜索、导入技能的中心。支持从 GitHub 仓库 URL 直接导入也支持管理本地技能文件。关系图视图使用 VueFlow 渲染的交互式画布是调试和理解多智能体系统的核心。实时监控面板显示当前会话的 Token 使用量、预估成本、执行日志流。后端部分则通过 Nuxt 的 Server API 实现提供了一系列关键接口文件系统接口用于扫描.claude目录读取/写入技能和配置文件。这是实现“符号链接管理”和“仓库扫描”的基础。进程管理接口用于启动、停止 Claude Code CLI 进程并与其标准输入输出进行交互实现前端对智能体的控制。元数据解析接口解析技能 Markdown 文件提取其名称、描述、输入输出参数、依赖关系等信息供前端展示和构图使用。成本计算接口对接 Anthropic 的 API 使用记录或从 CLI 日志中解析实时计算和汇总 Token 消耗与费用。前后端通过 RESTful API 或 WebSocket用于实时日志和状态更新进行通信。前端发起一个“启用技能A”的操作后端会执行“在对应智能体的技能目录中创建指向技能A文件的符号链接”这一具体动作。3. 关键功能实现与深度解析3.1 动态技能管理符号链接的妙用这是解决“技能文件散落”痛点的核心设计。传统的做法是直接复制物理文件这会导致多个智能体引用同一技能时磁盘上存在多份副本更新和维护极其困难。我的解决方案是使用符号链接作为技能的“开关”。具体实现流程如下中央技能库在应用内部或用户指定的一个全局目录维护一个所有可用技能的“仓库”。每个技能在这里都有一份唯一的物理文件。智能体技能目录每个 Claude Code 智能体在.claude/agents/[agent_name]/skills/目录下都有一个属于自己的技能目录。启用技能当用户在 UI 上为一个智能体“启用”某个技能时后端不会复制文件而是在该智能体的技能目录中创建一个指向中央技能库中对应文件的符号链接。禁用技能当用户“禁用”该技能时后端仅删除这个符号链接而中央技能库的源文件毫发无损。这样做带来的巨大优势一致性所有智能体使用的都是同一份技能源文件。当你修复了中央库里的一个技能 Bug所有引用了该技能的智能体在下一次启动时都会自动生效无需逐个更新。空间高效避免了文件冗余尤其当你有几十个技能和多个智能体时节省的空间和带来的管理清晰度是质的飞跃。状态管理原子化启用/禁用操作变得极其轻量和快速就是创建/删除一个链接几乎是瞬间完成。这为 UI 上实现实时、无延迟的技能切换提供了可能。安全隔离即使某个智能体的技能目录被误操作清空也不会影响中央技能库和其他智能体。注意在 Windows 系统上需要确保以管理员权限运行该工具或者启用开发者模式以支持创建符号链接。在代码中我使用 Node.js 的fs.symlink方法并做好了跨平台兼容性处理。3.2 仓库扫描与上下文锚定Claude Code 智能体在处理任务时其“上下文”至关重要。如果它引用了项目中不存在的文件路径或者对项目结构理解错误就很容易生成无法编译或运行的代码。为了解决这个问题我设计了一个“仓库扫描与导入管理”工作流。这个工作流的目标是自动分析项目代码库提取出关键的文件和模块信息并将其作为“已知事实”或“基础上下文”提供给智能体从而“锚定”它的认知减少幻觉和路径错误。实现步骤用户指定根目录用户在 UI 上选择或输入需要扫描的代码仓库根路径。智能文件过滤后端启动一个扫描进程。为了避免扫描node_modules,.git,dist等无关目录我预设了一套忽略规则同时也允许用户通过.claudeignore文件类似.gitignore进行自定义。结构化分析扫描不仅仅是列出文件。我会用轻量级的解析器比如针对package.json,import/require语句来分析项目依赖提取主要的库和框架。入口文件识别main.tsx,App.vue,index.js等。模块导出关系尝试构建一个简单的文件依赖图。目录结构理清src/components,src/utils,tests/等标准结构的含义。生成上下文摘要将分析结果整理成一份结构化的 Markdown 摘要。这份摘要会描述“这是一个基于 React TypeScript 的项目入口是src/main.tsx使用了 Redux 进行状态管理核心业务逻辑在src/features/目录下工具函数位于src/lib/。”注入智能体将这份生成的摘要文件作为一项特殊的“只读技能”或“基础上下文文件”链接到智能体的工作目录中。这样智能体在开始任何任务前都已经对项目有了一个基本正确的认知框架。实操心得这个功能极大地提升了智能体生成代码的“落地率”。尤其是在接手一个陌生项目时先让 UI 工具扫描一遍再让智能体基于这个扫描结果去工作它提出的修改建议和生成的代码在文件路径和模块引用上准确了很多很少再出现“找不到模块”这种低级错误。3.3 关系可视化用 VueFlow 绘制智能体图谱当系统里有多个智能体每个智能体又有多个技能技能之间可能存在调用链时纯文本的列表根本无法理清头绪。可视化依赖关系图成了刚需。我是如何用 VueFlow 实现这一点的数据建模首先我需要定义“节点”和“边”的数据结构。一个节点至少包含id,type(如 ‘agent‘, ’skill‘, ’command‘),label,data(存储详细信息)。一条边包含source(源节点id),target(目标节点id),label(描述关系如 ‘uses‘, ’triggers‘)。元数据提取从技能 Markdown 文件的 YAML 前端元数据或特定注释块中解析出该技能的依赖项。例如一个code-review技能可能依赖于read-file和static-analysis技能。这些依赖关系就是构建图的边。图布局计算将提取出的节点和边数据传递给 VueFlow。我选择了Dagre布局算法它是一种专门用于有向无环图的层级布局算法能让整个图从上到下、从左到右有序排列非常清晰。交互设计点击高亮点击一个节点高亮显示与之直接相连的所有节点和边快速看清其影响范围。拖拽与缩放允许用户自由拖动节点到更舒服的位置或缩放画布来查看全局或细节。面板联动点击图上的一个技能节点右侧面板会自动显示该技能的详细描述、配置参数和源代码预览。动态更新当用户在 UI 上启用或禁用一个技能时关系图会实时更新。新启用的技能节点会出现在图中并建立其依赖边被禁用的节点则会变灰或隐藏。这个功能带来的最大价值是“可调试性”。有一次一个代码生成任务失败了日志提示某个函数未定义。在关系图中我一眼就看到负责生成该代码的智能体其调用的一个“工具函数生成”技能依赖于另一个“项目结构感知”技能而后者被我不小心禁用了。重新启用后问题立刻解决。没有这张图我可能要在日志和配置文件里排查半天。3.4 实时成本追踪让每一次调用都心中有数使用 Claude 这类大模型 API成本是一个无法回避的问题。在终端里执行一个长时间的重构任务你心里是没底的不知道它已经“烧”了多少钱。因此我最近集成了实时 Token 与成本追踪功能。实现原理日志流捕获Claude Code CLI 在与 Anthropic API 通信时会在日志中输出每个请求的 Token 使用情况prompt_tokens,completion_tokens。我的后端进程会实时捕获这些日志行。日志解析通过正则表达式或结构化的日志解析库从每行日志中提取出model(使用的模型如 claude-3-5-sonnet)、prompt_tokens、completion_tokens和total_tokens。成本计算维护一个模型价格表例如claude-3-5-sonnet: $3/1M input tokens, $15/1M output tokens。根据提取的 Token 数量和模型类型实时计算本次请求的成本单位通常是美元。数据聚合与展示前端通过 WebSocket 接收这些实时计算出的成本数据并更新到监控面板上。面板会展示本次会话总成本从任务开始到现在的累计花费。实时速率估算的“每分钟烧钱速度”。Token 消耗堆叠图直观展示输入 Token 和输出 Token 随时间的消耗情况。按模型拆分显示不同模型各自的消耗和成本方便优化模型选型。注意事项这个功能目前还处于“早期体验”阶段因为准确捕获所有 API 调用日志有一定挑战性特别是当 CLI 工具更新时日志格式可能会变化。我的策略是提供灵活的日志解析规则配置让用户可以自己适配。但即使是一个大概的成本估算也足以让我在运行一个大型重构前心里有个预期避免出现“天价账单”的惊吓。4. 从零开始搭建与使用指南4.1 环境准备与项目启动假设你已经安装了 Node.js (版本 18) 和 Git并且已经在本地配置好了 Claude Code CLI确保claude命令可以在终端中运行。第一步克隆仓库并安装依赖打开你的终端执行以下命令git clone https://github.com/Ngxba/claude-code-agents-ui.git cd claude-code-agents-ui npm install这个过程会下载项目代码并安装所有必要的依赖包包括 Nuxt 3、VueFlow 及其相关组件。第二步配置环境变量项目根目录下可能需要一个.env文件来配置一些关键路径。最关键的通常是你的 Claude Code 项目工作区根目录。你可以复制提供的示例文件cp .env.example .env然后编辑.env文件设置如下的变量# 你的主要代码项目所在的根目录路径Claude Code 会在这里寻找 .claude 文件夹 CLAUDE_WORKSPACE_ROOT/path/to/your/code/projects # 可选指定一个全局技能库的路径如果不设置会使用应用内默认位置 GLOBAL_SKILLS_REPO/path/to/your/custom/skills第三步启动开发服务器运行以下命令启动应用npm run dev如果一切顺利终端会输出本地服务器的访问地址通常是http://localhost:3000。用浏览器打开这个地址你就能看到 Claude Code Agents UI 的界面了。提示首次启动时应用可能会尝试扫描你配置的CLAUDE_WORKSPACE_ROOT目录。如果目录很大初始加载可能会稍慢请耐心等待。4.2 核心工作流演示管理一个代码审查任务让我们通过一个实际场景——为一个开源项目添加代码审查——来走一遍核心流程。场景你刚克隆了一个 Vue.js 的开源项目想用 Claude Code 智能体帮你快速熟悉代码并审查近期提交。步骤 1连接并扫描仓库在 UI 的“仓库管理”页面点击“扫描新仓库”。在弹出的文件选择器中导航到你刚克隆的 Vue.js 项目根目录选择它。工具开始后台扫描。完成后主仪表盘会显示这个新仓库并列出分析出的关键信息这是一个 Vue 3 Vite TypeScript 项目主入口是src/main.ts路由配置在src/router等。步骤 2创建并配置智能体转到“智能体”页面点击“新建智能体”。给它起个名字比如vue-project-reviewer。在配置面板中将“基础上下文”关联到上一步扫描生成的“项目摘要”。这能确保智能体对这个 Vue 项目有基本认知。在“模型选择”中根据任务复杂度和成本考虑选择claude-3-haiku更快更便宜或claude-3-5-sonnet更强更贵。步骤 3从市场添加技能点击“技能市场”标签页。这里会列出内置的、以及从你配置的 GitHub 技能库同步过来的所有可用技能。在搜索框输入review找到“代码审查”、“安全检查”、“依赖漏洞分析”等技能。点击“代码审查”技能卡片上的“添加到智能体”按钮选择你刚创建的vue-project-reviewer智能体。关键一步回到vue-project-reviewer智能体的详情页。在“已加载技能”列表里你会看到“代码审查”技能。注意它的状态可能默认是“未启用”灰色。点击旁边的开关图标启用它。此时后端会在该智能体的.claude/skills/目录下创建指向中央技能库的符号链接。步骤 4可视化与依赖检查进入“关系图”视图。在画布上你应该能看到vue-project-reviewer智能体节点以及连接到它的“代码审查”技能节点。点击“代码审查”节点右侧面板会显示其详情。你可能会发现它依赖“文件读取”和“语法解析”两个基础技能。如果这两个技能还没被启用关系图上可能会用虚线或警告色显示。你可以直接在图上点击这两个依赖技能节点并在右侧面板中启用它们。系统会自动解决依赖关系。步骤 5执行任务与监控在智能体详情页的“对话”或“任务”面板输入你的指令“请审查src/components/目录下最近一周修改的所有.vue文件重点检查代码风格和潜在的逻辑错误。”点击“运行”。此时UI 会启动后端的 Claude Code CLI 进程并将你的指令和配置好的上下文、技能一起发送过去。切换到“监控”面板。在这里你可以实时看到日志流智能体思考、调用技能、输出结果的每一步。Token 消耗输入和输出的 Token 数实时增长以及估算的成本。技能调用链可视化面板会高亮显示当前正在活跃的智能体和技能节点。步骤 6分析结果与迭代任务完成后审查结果会以 Markdown 格式呈现在对话历史中。如果你对结果不满意比如觉得审查不够深入你可以回到“技能管理”为智能体启用“深度静态分析”或“复杂度计算”等更高级的技能。调整智能体的指令使其更具体。所有操作都在图形界面上完成无需再触碰终端或配置文件。这个工作流将原本分散在终端、文件管理器和编辑器中的操作整合到了一个统一的、可视化的界面中大大提升了复杂 AI 智能体工作流的可控性和效率。5. 常见问题与故障排查实录在实际开发和使用的过程中我踩过不少坑。这里把一些典型问题和解决方法记录下来希望能帮你节省时间。5.1 技能启用失败提示“无效的符号链接”问题现象在 UI 上点击启用某个技能按钮转圈后变回禁用状态控制台或日志显示创建符号链接失败。排查思路检查文件权限这是最常见的原因。确保运行此 UI 工具的用户账户对中央技能库的源文件以及目标智能体的.claude/skills/目录都有读写权限。在 Linux/macOS 上可以用ls -la命令查看。检查路径是否存在确认中央技能库里的源.md文件确实存在。有时从 GitHub 导入可能会因为网络问题导致文件下载不完整。Windows 系统特殊处理在 Windows 上创建符号链接可能需要管理员权限或者需要启用“开发者模式”。可以尝试以管理员身份运行你的终端和开发服务器。如果不行在项目配置中可以尝试将链接策略从symlink回退到copy虽然失去了实时同步的优点但能保证功能可用。查看后端日志启动服务时加上DEBUG*环境变量或者直接查看 Nuxt 服务器端的日志输出通常会有更详细的错误信息。我的解决方案在代码中增加了更健壮的错误处理。在创建符号链接前先检查目标目录是否存在并尝试创建如果符号链接创建失败则自动回退到复制文件模式并在 UI 上给用户一个提示“已使用文件副本模式技能更新需手动同步”。5.2 关系图加载缓慢或卡顿问题现象当项目中有大量智能体和技能时VueFlow 画布渲染变得很慢拖动和缩放卡顿。排查思路节点数量检查是否一次性加载了所有历史智能体和技能。对于大型项目这可能导致节点数超过数百个。数据复杂度每个节点携带的data对象是否过于庞大比如把整个技能文件的源码都塞进去了。布局计算Dagre 布局算法在节点数很多时计算量会增大。优化措施分页/懒加载初始只加载活跃的或最近使用的智能体及其直接关联的技能。提供搜索或筛选功能按需加载其他部分。简化节点数据关系图主要用于查看拓扑结构不需要展示全部细节。将技能的详细内容移到右侧面板节点只保留id,type,label等核心信息。使用 Web Worker将 Dagre 布局的计算任务放到 Web Worker 中避免阻塞主线程导致界面卡顿。提供视图过滤器在图上增加筛选按钮例如“只显示启用的技能”、“隐藏命令节点”等让用户可以聚焦在当前关心的部分。5.3 实时日志和成本数据不更新问题现象监控面板上的日志流停止了Token 计数也不再增长但智能体任务似乎还在后台运行。排查思路WebSocket 连接状态这是最可能的原因。打开浏览器的开发者工具切换到“网络”标签页查看 WebSocket 连接是否断开状态码 101 Switching Protocols 之后又出现关闭帧。后端进程异常负责捕获 CLI 日志和计算成本的后端服务可能挂掉了。检查 Nuxt 服务器的终端输出是否有错误。Claude CLI 日志格式变化Anthropic 更新了 Claude Code CLI可能导致日志输出格式微调使得我们的正则表达式解析失败从而无法提取 Token 数据。解决步骤刷新页面最简单的方法重建 WebSocket 连接。检查后端 API手动访问一下后端提供的日志流 API 端点如http://localhost:3000/api/logs/stream看是否能收到数据。查看原始日志找到 Claude Code CLI 生成的原始日志文件通常在你运行claude命令的目录下检查其最新内容格式是否与解析规则匹配。如果不匹配需要更新后端的解析逻辑。实现心跳与重连在前端 WebSocket 客户端增加心跳检测机制连接断开时自动尝试重连并提示用户。5.4 从 GitHub 导入技能失败问题现象在技能市场输入 GitHub 仓库 URL点击导入后长时间无反应或提示失败。排查思路网络问题无法访问 GitHub.com或者仓库是私有的且没有提供正确的访问令牌。仓库结构不符工具期望导入的仓库有一个固定的结构例如技能文件必须放在/skills目录下并且是.md格式。如果仓库结构不符合预期解析会失败。速率限制频繁调用 GitHub API 可能导致触及其速率限制。应对策略提供详细的错误反馈在 UI 上明确告知用户失败原因是“网络超时”、“仓库未找到”还是“权限不足”。支持多种导入方式除了 GitHub URL增加“上传本地 ZIP 文件”和“指定本地文件夹路径”的选项。缓存机制对成功导入的远程技能仓库进行本地缓存避免重复下载。同时提供“强制更新”按钮来获取最新内容。离线模式允许用户完全在离线环境下使用本地已有的技能库工作。5.5 与不同版本的 Claude Code CLI 兼容性问题问题现象UI 上的某些功能如启动特定类型的智能体、使用某个新技能在升级或降级 Claude Code CLI 后失效。根本原因Claude Code CLI 本身在快速迭代其命令行参数、配置文件格式、技能规范、甚至进程通信方式都可能发生变化。缓解方案版本检测与提示在应用启动时尝试运行claude --version命令获取 CLI 版本号并在 UI 上显示。如果检测到已知的不兼容版本向用户发出警告。抽象配置层不要将 CLI 的命令行参数硬编码在前端。而是通过一个后端的“适配器”模块来生成命令。这个适配器模块可以根据检测到的 CLI 版本选择不同的参数组合。技能元数据版本化在技能文件的 YAML 头信息中增加一个min_cli_version字段。UI 在加载技能时会检查当前 CLI 版本是否满足要求不满足则禁用该技能并提示用户升级。提供回退机制对于核心的“运行任务”功能确保至少有一种最基础的、兼容性最好的调用方式例如使用最稳定的旧版参数作为保底。开发这类与快速演进的底层工具深度集成的 UI兼容性是一个长期的挑战。保持关注 Claude Code 的官方更新日志并鼓励社区用户反馈问题是维持工具可用的关键。
