fn-ui-server

基于 @anthropic-ai/claude-agent-sdk 封装的 HTTP / SSE 代理服务，安装后全局提供 fn 命令，一行启动 Claude Agent 服务。

特性

• 全局 fn 命令，fn start 一键启动
• 基于 @anthropic-ai/claude-agent-sdk，完整支持 Claude Code 能力
• SSE 流式输出，逐 token 实时推送
• 多轮对话（session 续接）
• 支持 Skills（Markdown 技能文件）
• 支持 MCP 服务器（全局配置 + 请求级动态注入）
• 内置 Admin 管理界面（/admin）
• 零配置 npx 启动

前置条件

• Node.js >= 18
• 已安装并登录 Claude Code CLI

# 验证 claude CLI 是否可用
claude --version

安装

方式一：npx（推荐，无需安装）

npx fn-ui-server start

方式二：全局安装（获得 fn 命令）

npm install -g fn-ui-server

fn start

方式三：项目依赖

npm install fn-ui-server

{
  "scripts": {
    "ai": "fn start"
  }
}

服务默认监听 3100 端口，启动后访问 http://localhost:3100。

fn 命令

fn start              # 启动服务
fn start --port 8080  # 指定端口
fn --version          # 查看版本
fn --help             # 查看帮助

环境变量

支持在项目根目录创建 .env 文件，启动时自动读取。

| 变量 | 默认值 | 说明 | |------|--------|------| | FN_PORT | 3100 | 监听端口 | | CLAUDE_CWD | process.cwd() | Claude 工作目录（指向你的项目） | | CLAUDE_MODEL | (claude 默认) | 模型名，如 sonnet、opus、claude-sonnet-4-6 | | CLAUDE_SKILLS_DIR | ~/.claude/skills | Skills 扫描目录 | | CLAUDE_MCP_CONFIG | ~/.claude/mcp_servers.json | MCP 全局配置文件路径 | | ANTHROPIC_API_KEY | — | API Key（使用 API Key 认证时填写） | | CLAUDE_PATH | (SDK 自动查找) | 手动指定 claude 二进制路径（SDK 内置 binary 无法运行时使用） | | FN_UI_DIST | (包内置) | 自定义前端 UI 静态文件目录 | | FN_ADMIN_DIST | (包内置) | 自定义 Admin 静态文件目录 |

# 示例
CLAUDE_CWD=/path/to/my-project \
CLAUDE_MODEL=sonnet \
FN_PORT=3100 \
fn start

编程调用（库模式）

import { startServer } from 'fn-ui-server'

startServer()

直接使用 ClaudeRunner 构建自定义流：

import { ClaudeRunner } from 'fn-ui-server/runner'

const runner = new ClaudeRunner({
  message: '帮我分析这段代码',
  cwd: '/path/to/project',
  mode: 'agent',
})

runner.on('event', (e) => console.log(e))
runner.on('end', () => console.log('done'))
runner.run()

API

POST /api/chat

发送消息，以 SSE 流的形式返回 Claude 响应。

请求体

{
  "message": "帮我优化这个组件的样式",   // 必填
  "session_id": "xxx",                    // 可选，续接已有 session
  "model": "sonnet",                      // 可选，覆盖环境变量
  "cwd": "/path/to/project",             // 可选，覆盖环境变量
  "mode": "agent",                        // 可选，agent（默认）| ask
  "images": ["https://...", "data:..."], // 可选，图片 URL 或 base64
  "skills": ["code-review"],             // 可选，传 "all" 加载全部 Skills
  "mcpServers": {                        // 可选，请求级 MCP 配置
    "my-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "db.sqlite"]
    }
  },
  "requirePermission": false             // 可选，true 时工具调用需用户逐一审批
}

SSE 事件格式

每行格式为 event: <type>\ndata: <JSON>\n\n，结束时推送 data: [DONE]\n\n。

| event | 关键字段 | 说明 | |-------|----------|------| | text_delta | text | 逐 token 文本片段 | | tool_start | toolName, input | Claude 开始调用工具 | | tool_done | toolName, result | 工具调用完成 | | permission_request | permissionId, toolName | 等待用户审批（requirePermission 模式）| | done | session_id, cost_usd | 本轮完成 | | error | error | 出错信息 |

curl 示例

curl -N -X POST http://localhost:3100/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好，用中文介绍一下自己"}'

其他端点

| 方法 | 路径 | 说明 | |------|------|------| | GET | /api/sessions | 列出最近 50 个 session | | DELETE | /api/sessions/:id | 删除指定 session | | POST | /api/sessions/:id/fork | Fork 当前会话 | | POST | /api/permission/:id | 响应工具审批请求 | | GET | /api/models | 模型列表 | | GET | /api/skills | Skills 列表 | | GET | /api/mcp | 当前 MCP 配置 | | PUT | /api/mcp | 更新 MCP 配置 | | POST | /api/mcp/reload | 热重载 MCP 配置 | | GET | /api/agents | Subagent 列表 | | PUT | /api/agents | 更新 Subagent 定义 | | GET | /api/system-prompt | 全局系统提示词 | | PUT | /api/system-prompt | 更新全局系统提示词 | | GET | /api/hooks/log | Hook 审计日志 | | POST | /api/feedback | 提交反馈 | | GET | /health | 健康检查 |

Skills

在 ~/.claude/skills/ 下放置 Markdown 文件即可定义 Skill：

~/.claude/skills/
├── code-review.md      # 单文件形式
└── pdf/
    └── SKILL.md        # 目录形式

请求时通过 skills 字段启用：

{ "message": "帮我 review 代码", "skills": ["code-review"] }
{ "message": "...", "skills": "all" }

MCP 服务器

全局配置（对所有对话生效）：创建 ~/.claude/mcp_servers.json：

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
    },
    "remote-api": {
      "type": "http",
      "url": "https://mcp.example.com",
      "headers": { "Authorization": "Bearer TOKEN" }
    }
  }
}

请求级配置（仅对单次对话生效）：通过请求体 mcpServers 字段传入，与全局配置合并。

常见问题

Q: 启动后 /api/chat 没有响应？

确认 claude 命令在 PATH 中可用：

claude --version

如果 claude 命令可用但仍报 spawn Unknown system error 错误（常见于 macOS），是 SDK 内置 native binary 无法运行。可通过 CLAUDE_PATH 指定系统已安装的 claude 路径绕过：

# 找到系统 claude 的实际路径
which claude   # 如果是 alias，执行: type claude

# 指定路径启动（替换为实际路径）
CLAUDE_PATH=/Users/你的用户名/.claude/local/claude fn start
# 或
CLAUDE_PATH=$(which claude) npx fn-ui-server start

Q: 如何保留多轮对话上下文？

将上一次响应 done 事件中的 session_id 在下次请求时回传即可。

Q: 如何切换项目目录？

CLAUDE_CWD=/path/to/your-project fn start

License

MIT