1. 项目概述：一个为Claude Code量身打造的全栈管理界面

如果你和我一样，日常开发重度依赖Anthropic的Claude Code，那你肯定也经历过在终端和编辑器之间反复横跳，手动编辑一堆YAML、JSON配置文件的日子。管理Agent、定义技能、配置MCP服务器，这些操作虽然核心，但体验上总感觉差了点意思——不够直观，也不够高效。这正是我决定动手开发 claude-ui-tool 的初衷：我需要一个统一的、可视化的Web界面，来一站式管理我的Claude Code生态。

简单来说， claude-ui-tool 是一个开源的、功能完整的全栈Web应用。它的核心目标，就是把你本地 ~/.claude 目录下的所有配置——包括Agents（智能体）、Commands（命令）、Skills（技能）、Workflows（工作流）、MCP（模型上下文协议）服务器以及全局设置——全部搬到浏览器里进行可视化管理。不仅如此，它还内置了一个功能完整的终端和一个基于WebSocket的实时聊天界面，让你无需离开这个工具，就能完成与Claude的交互和命令行操作。

这个工具非常适合两类开发者：一是像我这样，希望提升Claude Code配置和管理效率的深度用户；二是那些对Claude Code的扩展机制（如Agent、MCP）感兴趣，想通过一个直观的UI来学习和探索其内部结构的开发者。它用起来的感觉，就像给你的Claude Code装了一个“控制中心”，所有分散的配置和功能都被集中到了一个面板上，管理和调用都变得异常清晰。

2. 技术栈选型与架构设计思路

当我开始构思这个项目时，技术栈的选择直接决定了开发体验和最终产品的健壮性。我的核心诉求是： 前后端分离清晰、开发热重载高效、类型安全有保障、最终打包体积要小 。经过一番权衡，我确定了现在这个组合。

2.1 前端：Vite + React + TypeScript + Tailwind CSS

选择 Vite 作为构建工具几乎是当下React生态的默认选项了。它基于ESM的极速冷启动和HMR（热模块替换）体验，在开发阶段带来的流畅感是无可比拟的。相比于Webpack，Vite的配置更加简洁，开箱即用的体验非常好，这让我能更专注于业务逻辑而非构建配置。

React 18 配合 TypeScript 构成了前端的基础。TypeScript的强类型检查在管理Claude Code这种结构相对复杂的配置对象时，优势非常明显。它能有效避免属性名拼写错误、类型不匹配等低级问题，尤其是在处理从后端API返回的Agent或Workflow定义时，提前定义好接口类型，能让代码更加可靠。

UI层面，我选择了 Tailwind CSS 。对于一个工具类应用，快速迭代UI样式是关键。Tailwind的实用类（Utility-First）理念让我无需在HTML和CSS文件之间来回切换，直接在JSX中通过类名组合就能完成绝大多数样式编写，极大地提升了开发效率。而且它的PurgeCSS功能可以确保最终产出的CSS文件非常精简。

对于复杂的状态管理和数据获取，我引入了 TanStack Query（原React Query） 。它完美地处理了服务器状态（Server State）的缓存、更新、同步和错误重试。例如，当我在“Agents列表”页面删除一个Agent后，TanStack Query能自动在后台失效（invalidate）相关的查询，并触发UI的重新获取和渲染，我不需要手动去管理这些状态逻辑。

路由使用 React Router v6 ，它提供了声明式的路由配置和强大的嵌套路由能力，非常适合这种多页面的管理后台应用。

2.2 后端：FastAPI + Python

后端选择 FastAPI 是基于Python生态和性能的考量。FastAPI以其极快的性能（基于Starlette和Pydantic）、自动化的交互式API文档（Swagger UI）以及对Python类型提示（Type Hints）的深度支持而闻名。

Claude Code的配置文件主要是YAML和JSON格式。FastAPI配合 Pydantic 模型，可以非常优雅地实现请求/响应数据的验证、序列化和文档生成。当从前端传来一个创建Agent的请求时，Pydantic模型会自动校验字段类型和必填项，无效的请求在进入业务逻辑前就会被拦截并返回清晰的错误信息，这省去了大量手写校验代码的功夫。

处理Claude的配置文件，我用到了 python-frontmatter 和 PyYAML 库。很多Claude Code的配置（尤其是技能定义）采用了Frontmatter格式（一种在文件头部用YAML定义元数据的格式）， python-frontmatter 库能很好地解析和生成这种格式。对于纯YAML或JSON， PyYAML 和Python标准库的 json 模块就足够了。

为了实现内置的终端功能，我使用了 ptyprocess 库来创建伪终端（Pseudo-Terminal），并通过WebSocket将终端的输入输出流实时转发到前端的xterm.js实例。这是一个技术难点，但也是提升工具完整性的关键一步。

最后，为了能感知配置文件的变更并自动同步（比如用户可能在外部用编辑器修改了文件），我引入了 GitPython 来提供简单的Git状态检查和差异对比功能，虽然目前功能还比较基础，但为未来实现更智能的同步打下了基础。

注意 ：技术栈的选择没有绝对的对错，关键是匹配项目需求和团队熟悉度。我选择这个组合，是因为它在开发效率、类型安全、运行性能和现代化程度之间取得了很好的平衡。如果你的团队更熟悉Node.js后端，用Express或NestJS重写后端也是完全可行的，前后端通过清晰的API契约（OpenAPI Spec）解耦即可。

3. 核心功能模块深度解析

claude-ui-tool 的功能模块完全是围绕Claude Code的核心概念来设计的。理解这些模块，也就理解了Claude Code的扩展能力。

3.1 Agents（智能体）管理

这是工具的核心。在Claude Code中，Agent是一个定义了特定行为模式的配置单元。它通常包含名称、描述、系统提示词（System Prompt）、启用的技能（Skills）列表、可用的命令（Commands）以及相关的MCP服务器配置。

在 claude-ui-tool 的Agent编辑器里，我设计了一个多标签页的界面。 “概览” 标签用于编辑基础信息； “提示词” 标签是一个全屏的代码编辑器（基于Monaco Editor），专门用于编写和调试可能很长的系统提示词，支持语法高亮； “技能与命令” 标签则以可拖拽或复选框的方式，关联管理该Agent可用的技能和命令； “高级配置” 标签则用于处理环境变量、MCP服务器绑定等。

这里的一个关键设计是 “实时验证与保存” 。当用户在编辑器中修改YAML内容时，后端会启动一个轻量级的解析和验证流程，检查YAML语法是否正确，必要的字段是否存在。验证通过后，前端会提供一个“保存”按钮，或者可以配置为自动保存草稿到临时位置。这个功能避免了用户写了半天最后发现格式错误无法保存的糟糕体验。

3.2 Commands（命令）与 Skills（技能）管理

Commands和Skills是Claude Code中实现功能复用的两大基石。

Commands 通常是 / 开头的快捷指令，比如 /commit 可以生成Git提交信息。在管理界面中，每个Command条目都清晰展示了其触发命令、描述、关联的技能或脚本路径。编辑器允许你直接修改命令背后的执行逻辑，这些逻辑通常是一段Python脚本或Shell命令。

Skills 则更偏重于“能力”的封装。一个Skill可能包含复杂的逻辑、多个工具调用以及对特定上下文的理解。在UI中，Skill编辑器需要处理更复杂的结构，包括技能描述、输入输出参数的定义、以及实现代码本身。我在这里借鉴了函数定义的思路，让用户可以清晰地定义技能的“签名”（参数列表和类型），这对于后续在Workflow中可视化编排至关重要。

实操心得 ：区分Command和Skill有时会让人困惑。我的经验法则是：如果这个功能是一个简单的、一次性的动作或别名，适合用Command；如果它是一个需要复杂逻辑、可能被多个Agent或Workflow调用的“能力单元”，则应该抽象成Skill。在UI设计上，对Skill的编辑支持要更强大，比如需要提供更好的代码编辑和测试环境。

3.3 Workflows（工作流）可视化编排

Workflow是Claude Code中用于串联多个步骤（Step）的配置，可以实现复杂的自动化任务。 claude-ui-tool 最出彩的功能之一，就是它的 “Graph View” ，基于 React Flow 库实现。

在这个视图里，每个Skill或Command成为一个节点（Node），节点之间的连线（Edge）代表了数据或执行流程的传递。你可以从左侧的组件库中拖拽节点到画布，然后用连线将它们连接起来，形成一个有向无环图（DAG）。每个节点都可以双击进行详细配置，比如设置输入参数、选择具体的技能实现版本等。

这个可视化编辑器的价值在于，它让抽象的YAML配置变成了直观的流程图。你可以一眼看清整个工作流的逻辑脉络：哪里是分支判断，哪里是循环，数据从哪里来、到哪里去。这对于构建和调试复杂工作流来说，效率提升是数量级的。后端只需要将这个图结构序列化成Claude Code能识别的Workflow YAML配置即可。

3.4 MCP（模型上下文协议）服务器管理

MCP是Anthropic推出的一套协议，旨在让Claude这类模型能够更安全、更标准化地访问外部工具、数据和计算资源。一个MCP服务器就是一个遵循该协议的后端服务，可以为Claude提供特定的能力，比如读取数据库、调用第三方API等。

在 claude-ui-tool 的MCP管理页面，你可以添加、配置、启用或禁用不同的MCP服务器。每个服务器配置通常包括服务器类型（如SSE、Stdio）、启动命令、环境变量以及传递给Claude的上下文信息。UI会提供一个表单来简化这些配置的填写，并尝试在后台测试服务器的连接是否正常。

管理MCP服务器的难点在于其多样性和动态性。不同的服务器启动方式、通信协议可能完全不同。我的实现方式是提供一个可扩展的“适配器”层，针对常见的MCP服务器类型（如基于Stdio的本地进程）提供标准化的配置模板和健康检查机制。对于非常规的服务器，则允许高级用户通过自定义JSON配置来接入。

3.5 一体化终端与聊天界面

这是为了打造“闭环”体验而加入的功能。 内置终端 基于 xterm.js 和后台的 ptyprocess ，它不是一个简单的命令输入框，而是一个真实的、支持Vim、Tmux等复杂交互的伪终端。这意味着你可以在工具内部直接运行 claude 命令行，测试你刚配置好的Agent，而无需切换窗口。

实时聊天界面 则通过WebSocket连接到后端，后端再与Claude的API（或本地Claude Code进程）进行通信。这个聊天界面可以绑定到某个特定的Agent，这样你就可以在真实的对话环境中测试该Agent的系统提示词和技能组合是否工作如预期。

将终端和聊天集成在一起的想法，源于我自己的调试流程：经常需要先在终端触发一个命令，然后在聊天中查看Claude的响应，或者反过来。现在这两个上下文被放在同一个标签页（ /cli ）里，中间用可拖拽的分割线隔开，调试效率大大提升。

4. 项目结构详解与开发环境搭建

一个清晰的项目结构是团队协作和长期维护的基础。 claude-ui-tool 采用了经典的前后端分离目录结构。

4.1 目录结构解析

claude_agent_management/  # 项目根目录
├── backend/              # Python FastAPI 后端代码
│   ├── api/              # API路由层，按模块划分（agents.py, skills.py等）
│   ├── core/             # 核心配置、依赖、工具函数
│   ├── models/           # Pydantic数据模型定义
│   ├── services/         # 业务逻辑层，处理文件读写、Claude交互等
│   ├── main.py           # FastAPI应用入口
│   └── requirements.txt  # Python依赖列表
├── frontend/             # Vite + React 前端代码
│   ├── src/
│   │   ├── api/          # 对后端API的封装调用（使用TanStack Query）
│   │   ├── components/   # 可复用的React组件
│   │   ├── pages/        # 页面组件，与路由对应（AgentsPage, CliPage等）
│   │   ├── types/        # TypeScript类型定义
│   │   ├── utils/        # 前端工具函数
│   │   ├── App.tsx       # 根组件，定义路由
│   │   └── main.tsx      # 应用入口
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts    # Vite配置
└── start.sh              # 一键启动脚本

这种结构的好处是职责分离明确。后端专注于API和业务逻辑，前端专注于UI和交互。 api 目录下的文件是前后端通信的契约，任何接口变更都需要同步更新前后端的相关代码。

4.2 从零开始：手动搭建开发环境

虽然项目提供了便捷的 start.sh 一键脚本，但理解手动搭建过程对于故障排查和自定义部署至关重要。

后端环境准备： 首先确保你的系统安装了 Python 3.11 或更高版本 。我强烈建议使用虚拟环境来隔离项目依赖。

# 进入项目后端目录
cd claude_agent_management/backend

# 创建Python虚拟环境（以.venv命名是常见约定）
python3 -m venv .venv

# 激活虚拟环境
# 在Linux/macOS上：
source .venv/bin/activate
# 在Windows上（CMD）：
# .venv\Scripts\activate.bat
# 在Windows上（PowerShell）：
# .venv\Scripts\Activate.ps1

# 安装依赖
pip install -r requirements.txt

requirements.txt 文件是关键，它锁定了所有后端库的版本，确保环境一致性。核心依赖包括 fastapi , uvicorn[standard] , python-frontmatter , pyyaml , ptyprocess , gitpython 等。

安装完成后，启动后端服务器。这里有一个细节： uvicorn 的 --app-dir 参数指向了上一级目录（ .. ），这是因为我的 main.py 中可能以项目根目录为基准进行了一些路径操作。你需要根据你的实际入口文件位置进行调整。

# 从项目根目录启动，并指定应用目录为当前目录（.）
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000 --app-dir .

--reload 参数开启了热重载，修改代码后服务器会自动重启。 --host 0.0.0.0 允许从网络其他设备访问（仅开发环境）， --port 8000 指定了端口。

前端环境准备： 前端需要 Node.js 环境（建议LTS版本）和 npm（通常随Node.js安装）。

# 进入项目前端目录
cd ../frontend

# 安装所有npm依赖包
npm install

这个过程会根据 package.json 和 package-lock.json 下载所有依赖，包括React、Vite、Tailwind CSS、xterm.js等，可能会花费几分钟。

安装完成后，启动开发服务器：

npm run dev

Vite会启动一个开发服务器，通常运行在 http://localhost:5173 。它同样支持热模块替换，前端代码的改动会即时反映在浏览器中，无需刷新页面。

至此，你就拥有了两个并行的服务：后端API在 :8000 ，前端开发服务器在 :5173 。前端会通过配置好的代理（在 vite.config.ts 中设置）将 /api 开头的请求转发到后端，从而解决开发时的跨域问题。

4.3 一键启动脚本剖析

start.sh 脚本的本质是将上述手动步骤自动化，并处理一些边缘情况。我们来看看一个健壮的启动脚本应该包含什么：

#!/bin/bash

# 设置错误处理：任何命令失败则退出脚本
set -e

echo "启动 Claude Agent Management 全栈开发环境..."
echo "----------------------------------------"

# 1. 检查必要工具是否存在
if ! command -v python3 &> /dev/null; then
    echo "错误：未找到 python3。请先安装 Python 3.11+。"
    exit 1
fi

if ! command -v node &> /dev/null; then
    echo "错误：未找到 node。请先安装 Node.js。"
    exit 1
fi

# 2. 后端启动逻辑
echo "正在设置后端环境..."
cd backend

# 检查虚拟环境，不存在则创建
if [ ! -d ".venv" ]; then
    echo "创建Python虚拟环境..."
    python3 -m venv .venv
fi

# 激活虚拟环境（在脚本中，直接使用路径）
source .venv/bin/activate

# 检查依赖是否已安装，可根据requirements.txt的修改时间判断
if [ ! -f ".venv/installed.stamp" ] || [ requirements.txt -nt ".venv/installed.stamp" ]; then
    echo "安装/更新Python依赖..."
    pip install --upgrade pip
    pip install -r requirements.txt
    touch .venv/installed.stamp
fi

# 在后台启动后端服务器，并记录PID
echo "启动后端服务器 (端口 8000)..."
uvicorn main:app --reload --host 0.0.0.0 --port 8000 --app-dir .. > ../backend.log 2>&1 &
BACKEND_PID=$!
echo "后端进程ID: $BACKEND_PID"

# 3. 前端启动逻辑
echo -e "\n正在设置前端环境..."
cd ../frontend

# 检查node_modules是否存在
if [ ! -d "node_modules" ]; then
    echo "安装npm依赖..."
    npm install
fi

# 在后台启动前端开发服务器，并记录PID
echo "启动前端开发服务器 (端口 5173)..."
npm run dev > ../frontend.log 2>&1 &
FRONTEND_PID=$!
echo "前端进程ID: $FRONTEND_PID"

# 4. 信息提示与清理钩子
echo -e "\n----------------------------------------"
echo "启动完成！"
echo "前端访问: http://localhost:5173"
echo "后端API:  http://localhost:8000"
echo "API文档: http://localhost:8000/docs"
echo -e "\n日志文件:"
echo "  后端: backend.log"
echo "  前端: frontend.log"
echo -e "\n按 Ctrl+C 停止所有服务。"

# 捕获Ctrl+C信号，优雅地终止后台进程
trap "echo -e '\n正在停止服务...'; kill $BACKEND_PID $FRONTEND_PID 2>/dev/null; wait 2>/dev/null; echo '服务已停止。'; exit 0" INT TERM

# 保持脚本运行，等待信号
wait

这个脚本做了几件关键事情： 环境检查 、 依赖智能安装 （仅在需要时）、 后台进程管理 以及 日志重定向 。 trap 命令确保了当你按下 Ctrl+C 时，它能正确地清理后台启动的进程，避免留下“僵尸”服务。

注意事项 ：一键脚本虽好，但隐藏了细节。当遇到问题时（比如端口占用、依赖安装失败），查看 backend.log 和 frontend.log 日志文件是第一步。手动执行上述步骤，能帮你更精确地定位问题出在哪一环。

5. 前后端通信与关键API设计

对于一个全栈应用，清晰、稳定的API设计是前后端高效协作的基石。 claude-ui-tool 的API遵循RESTful风格，并使用JSON作为数据交换格式。

5.1 核心数据流与状态管理

前端（React）通过 TanStack Query 库来管理从后端获取的数据状态。TanStack Query的核心概念是“查询”（Query）和“变更”（Mutation）。

• 查询（Query） ：用于获取数据。例如，获取所有Agents的列表。TanStack Query会自动处理缓存、后台刷新、错误重试。当前端组件需要Agent列表时，它会调用一个封装好的Hook（如 useAgents() ），这个Hook内部使用TanStack Query的 useQuery 。数据一旦获取，就会被缓存，直到它被标记为“过期”（Stale）。

• 变更（Mutation） ：用于创建、更新、删除数据。例如，保存一个修改后的Agent。它会调用 useMutation ，在操作成功后，通常会去“无效化”（Invalidate）相关的查询。比如，保存Agent成功后，自动让“Agent列表”查询失效，触发一次重新获取，这样UI上的列表就会自动更新。

这种模式将服务器状态和本地UI状态分离，极大地简化了数据同步的逻辑。你不再需要手动在每次操作后去重新获取数据。

5.2 关键API端点详解

后端API围绕Claude Code的实体设计，以下是一些核心端点：

1. Agent相关 ( /api/agents )

• GET /api/agents : 列出所有Agent。后端会扫描 ~/.claude/agents/ 目录，解析每个YAML文件，返回一个包含基础信息（名称、slug、描述）的数组。
• POST /api/agents : 创建新Agent。请求体包含Agent的完整配置。后端会验证数据，生成一个唯一的slug（用于URL），然后将配置写入新的YAML文件。
• GET /api/agents/{slug} : 获取单个Agent的完整配置。
• PUT /api/agents/{slug} : 更新Agent。这里采用“全量更新”策略，即用请求体完全替换现有文件内容。这比“部分更新”（PATCH）更简单，因为配置文件的格式是自定义的。
• DELETE /api/agents/{slug} : 删除Agent，即删除对应的YAML文件。

2. 文件读写与并发处理 这里有一个重要的技术细节： 文件锁 。当多个用户或进程同时尝试读写同一个配置文件时，可能会造成数据损坏。虽然在这个单用户桌面工具中概率较低，但作为健壮的设计，必须考虑。

我的实现方案是使用一个简单的基于文件名的锁机制。在写入文件前，先尝试获取一个锁文件（如 .agent_{slug}.lock ），获取成功后再进行写入操作，写入完成后释放锁。如果获取锁失败（超时），则向客户端返回“资源忙”的错误。

# 伪代码示例
import fcntl
import os
import time

def safe_write_file(filepath, content):
    lockfile = filepath + '.lock'
    try:
        # 非阻塞方式获取锁
        with open(lockfile, 'w') as lock:
            fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
            # 获取锁成功，执行写入
            with open(filepath, 'w') as f:
                f.write(content)
            # 写入完成后，锁会随lock文件关闭而自动释放
    except BlockingIOError:
        # 获取锁失败，文件正被占用
        raise HTTPException(status_code=423, detail="文件正被其他进程编辑，请稍后重试")

3. WebSocket端点：实时通信的基石 除了REST API，两个WebSocket端点实现了实时功能：

• /ws/chat : 处理与Claude的聊天。前端建立连接后，发送用户消息，后端将消息转发给Claude API（或本地Claude进程），并将流式响应（Streaming Response）实时推回前端，实现打字机效果。
• /ws/cli : 处理终端I/O。前端xterm.js将用户输入的字符通过WebSocket发送到后端，后端通过 ptyprocess 将其写入伪终端的标准输入；同时，后端从伪终端的标准输出和标准错误读取数据，实时发送回前端显示。

WebSocket的实现比HTTP复杂，因为它需要保持长连接，并管理连接的生命周期、异常断开重连等。在FastAPI中，可以使用 WebSocket 类来方便地处理。

5.3 环境变量与配置

工具通过环境变量 CLAUDE_DIR 来定位Claude的配置目录，默认是 ~/.claude 。这提供了灵活性，比如在测试时，你可以将其指向一个临时目录，而不会污染你的真实配置。

import os
from pathlib import Path

# 获取配置目录路径
CLAUDE_HOME = Path(os.path.expanduser(os.getenv("CLAUDE_DIR", "~/.claude")))
AGENTS_DIR = CLAUDE_HOME / "agents"
SKILLS_DIR = CLAUDE_HOME / "skills"
# ... 其他目录

在开发中，你可以在启动后端前设置这个变量：

export CLAUDE_DIR=/path/to/test/claude/config
uvicorn backend.main:app --reload ...

6. 深入核心实现：终端集成与配置解析

6.1 基于xterm.js与ptyprocess的终端模拟

将一个真正的终端嵌入Web应用，是项目中技术挑战较大的部分。其核心原理是：在浏览器中通过 xterm.js 模拟一个终端界面，在服务器端通过 ptyprocess （Python的 pty 模块封装）创建一个伪终端（Pseudo-Terminal），然后用 WebSocket 在两者之间架起桥梁，双向传输输入输出流。

前端（xterm.js）侧实现要点：

1. 初始化终端 ：配置字体、行列数、主题颜色等。
2. 建立WebSocket连接 ：连接到后端的 /ws/cli 端点。
3. 绑定事件 ：
   • 将终端内的键盘输入通过WebSocket发送到后端。
   • 监听WebSocket消息，将后端传来的数据写入终端。
   • 处理终端尺寸变化（resize事件），并将新的行列数通知后端，以便调整伪终端的大小。

// 前端简化代码示例
import { Terminal } from 'xterm';
import { FitAddon } from 'xterm-addon-fit';

const term = new Terminal({ theme: { background: '#1e1e1e' } });
const fitAddon = new FitAddon();
term.loadAddon(fitAddon);
term.open(document.getElementById('terminal'));
fitAddon.fit();

const ws = new WebSocket(`ws://${location.host}/ws/cli`);

term.onData(data => ws.send(JSON.stringify({ type: 'input', data })));
term.onResize(({ cols, rows }) => ws.send(JSON.stringify({ type: 'resize', cols, rows })));

ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    if (msg.type === 'output') {
        term.write(msg.data);
    }
};

后端（FastAPI + ptyprocess）侧实现要点：

1. 创建伪终端 ：使用 ptyprocess.PtyProcess.spawn 启动一个shell（如 /bin/bash 或 zsh ）。
2. 处理WebSocket连接 ：为每个新的WebSocket连接创建一个独立的伪终端进程，避免会话混淆。
3. 双向数据泵 ：
   • 启动一个异步任务，持续从伪终端的输出流读取数据，并发送给WebSocket客户端。
   • 在WebSocket的接收处理器中，将客户端发来的输入数据写入伪终端的输入流。
   • 同样需要处理终端resize事件，调用 ptyprocess.setwinsize() 。

# 后端WebSocket处理简化示例
from fastapi import WebSocket
import asyncio
import ptyprocess
import json

async def websocket_cli_endpoint(websocket: WebSocket):
    await websocket.accept()
    # 为每个连接创建独立的pty进程
    proc = ptyprocess.PtyProcess.spawn(['/bin/bash'])
    
    async def read_from_pty_and_forward():
        while True:
            try:
                # 非阻塞读取，需要配合asyncio
                output = await asyncio.get_event_loop().run_in_executor(None, proc.read)
                if output:
                    await websocket.send_json({"type": "output", "data": output})
                else: # 进程可能已结束
                    break
            except:
                break
    
    read_task = asyncio.create_task(read_from_pty_and_forward())
    
    try:
        while True:
            data = await websocket.receive_json()
            msg_type = data.get('type')
            if msg_type == 'input':
                proc.write(data['data'])
            elif msg_type == 'resize':
                proc.setwinsize(data['rows'], data['cols'])
    except:
        pass
    finally:
        read_task.cancel()
        proc.terminate()

踩坑实录 ：pty进程的管理是难点。必须确保在WebSocket连接断开时，对应的pty进程被正确终止（ terminate() 或 kill() ），否则会导致大量的“僵尸”shell进程残留。此外，读取pty输出是阻塞IO，必须将其放到线程池中执行，以免阻塞整个异步事件循环。

6.2 配置文件的解析与持久化

Claude Code的配置文件主要是YAML，部分技能文件可能包含Frontmatter（YAML头+内容）。后端需要可靠地读写这些文件。

读取与解析：

• 对于纯YAML文件（如Agent配置），使用 yaml.safe_load() 。
• 对于包含Frontmatter的文件（如某些Skill），使用 frontmatter.load() 或 frontmatter.parse() 。这个库能聪明地将文件拆分为元数据（metadata，一个字典）和内容（content，字符串）。

写入与持久化：

• 写入前先进行 数据验证 。使用Pydantic模型定义配置的结构，利用其强大的验证能力。无效的数据根本不会进入写入流程。
• 实现 原子写入 。先写入一个临时文件，写入成功后再通过原子操作（ os.rename ）替换原文件。这可以防止在写入过程中发生崩溃导致原文件损坏。
• 备份机制 。在覆盖重要配置文件（如全局 settings.json ）前，先自动创建一个带时间戳的备份文件（如 settings.json.backup.20231027 ）。这给了用户一个“后悔药”。

import yaml
import frontmatter
from pathlib import Path
import shutil
from datetime import datetime

def save_agent_config(slug: str, config_data: dict):
    """安全地保存Agent配置"""
    file_path = AGENTS_DIR / f"{slug}.yaml"
    
    # 1. 验证数据 (假设有Pydantic模型 AgentConfig)
    # validated_config = AgentConfig(**config_data)
    
    # 2. 准备内容
    yaml_content = yaml.dump(config_data, default_flow_style=False, allow_unicode=True)
    
    # 3. 原子写入：先写临时文件
    temp_file = file_path.with_suffix('.yaml.tmp')
    try:
        temp_file.write_text(yaml_content, encoding='utf-8')
        # 4. 备份原文件（如果存在）
        if file_path.exists():
            backup_name = file_path.with_suffix(f'.yaml.backup.{datetime.now().strftime("%Y%m%d_%H%M%S")}')
            shutil.copy2(file_path, backup_name)
        # 5. 原子替换
        temp_file.rename(file_path)
    except Exception as e:
        # 清理临时文件
        if temp_file.exists():
            temp_file.unlink()
        raise e

7. 开发、调试与部署实战指南

7.1 高效的开发工作流

1. 前后端并行开发 ：利用Vite和FastAPI的热重载，修改代码后几乎立刻能在浏览器看到效果。前端代理了API请求，避免了跨域问题。
2. API契约先行 ：在实现复杂功能前，先用 OpenAPI （FastAPI自动生成）或 Postman 定义好API接口的请求响应格式。前后端开发者可以据此并行工作。
3. 利用TypeScript和Pydantic ：严格定义前后端的数据类型。这能在编译时或启动时就发现大量的接口不一致错误，而不是等到运行时。
4. 组件驱动开发 ：前端采用Storybook或类似的工具来独立开发和测试UI组件，不与后端逻辑耦合。

7.2 常见问题排查手册

在开发和使用 claude-ui-tool 的过程中，我遇到了不少典型问题，这里整理出来供你参考。

问题现象	可能原因	排查步骤与解决方案
前端页面空白，控制台报错 Failed to fetch 或网络错误。	1. 后端服务未启动。 2. 前端代理配置错误。 3. 端口被占用。	1. 检查后端进程是否运行 ( ps aux | grep uvicorn )。 2. 检查 frontend/vite.config.ts 中的 proxy 配置，确保目标地址和端口正确。 3. 使用 lsof -i :8000 或 lsof -i :5173 查看端口占用情况，终止冲突进程。
保存Agent时提示“文件被占用”或“权限不足”。	1. 文件锁未正常释放（可能是异常退出导致）。 2. 进程对 .claude 目录没有写权限。	1. 手动删除 ~/.claude/agents/ 目录下残留的 .lock 文件。 2. 检查 CLAUDE_DIR 指向的目录权限，确保运行后端进程的用户有读写权限。
内置终端无法输入或显示乱码。	1. WebSocket连接失败。 2. 伪终端进程启动失败（如默认shell路径不对）。 3. 编码问题。	1. 打开浏览器开发者工具，查看WebSocket连接状态和消息。 2. 查看后端日志 backend.log ，确认pty进程启动命令。在Linux/macOS上可能是 /bin/bash ，在Windows上需要适配为 cmd.exe 或 powershell 。 3. 确保前后端都使用UTF-8编码传输数据。
修改配置文件后，UI列表未刷新。	1. TanStack Query缓存未失效。 2. 后端文件系统监听延迟。	1. 确认执行“保存”操作后，前端代码是否调用了 queryClient.invalidateQueries({ queryKey: ['agents'] }) 来使缓存失效。 2. 在前端手动触发一次重新获取（如点击刷新按钮）。可以考虑在后端实现文件系统监听（如使用 watchdog 库），通过WebSocket主动通知前端更新。
图形化工作流编辑器连线后，保存失败。	1. React Flow的图数据序列化为YAML时出错。 2. 生成的YAML结构不符合Claude Code的Workflow规范。	1. 在后端添加更详细的验证和错误日志，打印出接收到的图数据和转换后的YAML。 2. 对比手动编写的有效Workflow YAML和工具生成的YAML，找出结构差异。确保节点、边的属性映射正确。

7.3 构建与部署

开发完成后，你需要将应用构建成可以独立部署的产品。

前端构建：

cd frontend
npm run build

Vite会将项目打包，输出到 dist 目录。这个目录包含了优化、压缩过的静态文件（HTML, JS, CSS）。

后端部署： 对于生产环境，不建议使用 --reload 。可以使用更专业的ASGI服务器，如 Uvicorn 配合 Gunicorn （多进程管理），或者 Daphne 。

# 使用Gunicorn管理多个Uvicorn worker进程
cd /path/to/project
source backend/.venv/bin/activate
gunicorn -w 4 -k uvicorn.workers.UvicornWorker backend.main:app --bind 0.0.0.0:8000

静态文件服务： 有两种常见方案：

1. 前后端分离部署 ：前端 dist 目录通过Nginx/Apache等Web服务器独立部署（例如在 https://tool.example.com ）。后端API部署在另一个域名或路径下（例如 https://api.example.com 或 https://tool.example.com/api ）。前端构建时需要配置正确的API基础URL。
2. 后端托管前端 ：将前端 dist 目录复制到后端静态文件目录，并配置FastAPI提供静态文件服务。

from fastapi.staticfiles import StaticFiles
app.mount("/", StaticFiles(directory="frontend/dist", html=True), name="static")

这样，访问根路径就会返回前端页面，而 /api 路径的请求仍由FastAPI处理。这种方式部署更简单，适合个人或小团队使用。

环境配置： 生产环境务必设置好环境变量，如 CLAUDE_DIR ，并确保运行进程的用户对该目录有适当的权限。考虑使用 .env 文件或容器环境变量来管理配置。

开发 claude-ui-tool 的过程，是一个将自身痛点转化为解决方案的典型例子。它不仅仅是一个UI外壳，更是对Claude Code扩展能力的一次深度梳理和可视化呈现。从技术实现上看，它融合了现代Web开发的诸多最佳实践：类型安全、前后端分离、实时通信、可视化交互。最让我有成就感的时刻，是看到通过图形界面拖拽几下就构建出一个复杂的工作流，并成功运行的那一刻。这证明，好的工具能真正释放底层技术的潜力。如果你也在使用Claude Code，不妨试试这个工具，或者基于它的思路构建属于你自己的管理界面。开发过程中任何问题，欢迎在项目仓库提出讨论。