메뉴
HugAgentOS 前端开发规范。当需要新增或修改前端代码（组件、Store、Hook、API调用、样式等）时使用此 skill， 确保组件结构、状态管理、样式命名、类型安全等与项目现有规范保持一致。
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/ZJU-REAL/HugAgentOS --skill hugagent-frontend-dev명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
设计并创建一个子智能体，或改进一个已有的子智能体。当用户说"帮我建一个负责 X 的智能体"、"我想要个专门做 Y 的助手"、"把这套活儿交给一个专门的智能体"、"改一下我那个智能体的职责/能力/语气"、或问"这个智能体该怎么设计"时，务必使用本技能。它教你怎么切职责、怎么写 system_prompt、绑哪些能力、参数怎么定，然后通过 create_agent / edit_agent 工具落库。
从零攒一个插件包，或把一个 web 链接上的插件下载下来导入。当用户说"照着这个网页做个插件"、"把我这几个技能打包成插件"、"帮我做一个插件"、"这个链接的插件帮我装上"、或需要把一组配套的技能与工具打成可安装可卸载的整体时，务必使用本技能。它教你插件包的目录结构、plugin.json 怎么写、怎么自检、怎么通过 import_plugin 工具落库。
HugAgentOS 后端开发规范。当需要新增或修改后端代码（API路由、服务层、数据库模型、MCP工具等）时使用此 skill， 确保代码风格、分层架构、错误处理、响应格式等与项目现有规范保持一致。
SOC 직업 분류 기준
SKILL.md 표시 중
| name | hugagent-frontend-dev |
| description | HugAgentOS 前端开发规范。当需要新增或修改前端代码（组件、Store、Hook、API调用、样式等）时使用此 skill， 确保组件结构、状态管理、样式命名、类型安全等与项目现有规范保持一致。 |
本 skill 定义了 HugAgentOS 项目前端（React + TypeScript + Ant Design + Zustand）的开发规范与流程。 所有前端代码变更必须遵守以下规范。
templates/)| 文件 | 用途 |
|---|---|
component.tsx | React 组件模板（Props + Hooks + 错误处理） |
store.ts | Zustand Store 模板（CRUD + localStorage 持久化） |
hook.ts | 自定义 Hook 模板（初始化 + 清理 + abort） |
css-module.css | CSS 样式模板（.jx- 前缀 + 响应式） |
references/)| 文件 | 内容 |
|---|---|
ui-design-spec.md | UI 设计规范（颜色系统、字体排版、图标、圆角、间距、组件规范、Ant Design 主题映射） |
icon-assets.md | 图标资产清单（全部 SVG 图标索引、使用方式、分类说明） |
component-tree.md | 完整组件树 |
css-variables.md | CSS 变量、命名规则、常用尺寸、样式模式（与 UI 设计规范对齐） |
api-patterns.md | API 调用模式（authFetch、SSE） |
sse-events.md | SSE 事件类型详解（run_started/content/thinking/tool_call/tool_result/tool_pending/batch_confirm/file_confirm/meta/error + [DONE]） |
assets/)| 目录 | 内容 |
|---|---|
assets/icons/ | 通用 UI 图标（30 个 SVG：logo、导航、操作按钮、场景图标等） |
assets/mcp-icons/ | MCP 工具库图标（12 个 SVG：互联网、数据、报告、知识等） |
scripts/)| 文件 | 用途 |
|---|---|
scaffold_component.sh | 一键生成新组件（.tsx + .css + index.ts） |
模板中
${ComponentName}/${componentName}/${group}为占位符，使用时替换。
src/frontend/src/
├── main.tsx # 入口：按路径分发应用壳
├── App.tsx # 主聊天应用（用户端）
├── ApiDocApp.tsx # /api-docs 开放 API 文档
├── SharePreviewApp.tsx # ?share= 分享预览页
├── types.ts # 共享 TypeScript 类型
├── api.ts # API 客户端（信封解包）
├── storage.ts # localStorage 工具 + defaultCatalog
│
├── components/ # 组件组（每组 index.ts barrel export）
│ ├── chat/ # ChatArea, InputArea, MessageBubble, PromptHubPanel
│ ├── agent/ # 子智能体
│ ├── apidoc/ # 开放 API 文档
│ ├── automation/ # 定时任务/自动化
│ ├── batch/ # 批量执行
│ ├── canvas/ # 画布产物
│ ├── catalog/ # CatalogPanel（能力中心）
│ ├── citation/ # CitationBadge, CitationHtmlBlock, CitationMarkdownBlock
│ ├── common/ # AuthExpiredModal, ImagePreview 等
│ ├── docs/ # DocsPanel（版本说明/能力介绍）
│ ├── file/ # FileAttachmentCard
│ ├── kb/ # 知识库（CreateKBModal, ReindexModal 等）
│ ├── lab/ # 实验室（技能蒸馏等）
│ ├── memory/ # 记忆中心
│ ├── myspace/ # 我的空间
│ ├── projects/ # 项目空间
│ ├── settings/ # SettingsModal（含记忆 L1/L2/L3 Tab）
│ ├── share/ # 分享
│ ├── sidebar/ # Sidebar
│ └── tool/ # ToolOutputRenderer, ToolResultPanel
│
├── hooks/ # 7 个自定义 Hook
│ ├── useChatInit.ts # 认证、Catalog、会话、消息初始化
│ ├── useChatActions.ts # 聊天 CRUD、重命名、导出
│ ├── useStreaming.ts # SSE 流式处理、文件上传、发送逻辑、断线续播
│ ├── usePlanMode.ts # Plan 模式
│ ├── usePageConfig.ts # 页面配置
│ ├── useDelayedFlag.ts # 延迟标志位
│ └── useStallDetector.ts # 流式停滞检测
│
├── stores/ # 18 个 Zustand Store
│ ├── authStore.ts # 认证状态
│ ├── chatStore.ts # 聊天会话、消息、activeRun
│ ├── catalogStore.ts # Catalog（技能、智能体、MCP、知识库）
│ ├── uiStore.ts # UI 面板、搜索、筛选、pending confirm 队列
│ ├── settingsStore.ts # 记忆、排序、偏好
│ ├── fileStore.ts # 文件上传
│ ├── kbStore.ts # 知识库管理
│ ├── agentStore.ts # 子智能体
│ ├── automationStore.ts / automationChatStore.ts # 自动化
│ ├── batchStore.ts # 批量执行（pendingConfirm）
│ ├── canvasStore.ts # 画布
│ ├── editionStore.ts # CE/EE 门控（消费 /v1/meta/edition）
│ ├── modelCapabilitiesStore.ts # 模型能力探测
│ ├── mySpaceStore.ts # 我的空间
│ ├── pageConfigStore.ts # 页面配置
│ ├── projectStore.ts # 项目空间
│ └── skillDistillStore.ts # 技能蒸馏
│
├── utils/ # 20+ 工具模块
│ ├── citations.ts # 引用解析与去重
│ ├── constants.ts # 工具名称、快捷场景、能力卡片
│ ├── export.ts # PDF 导出
│ ├── fileParser.ts # 文件解析、OSS 上传
│ ├── history.ts # 话题推断、日期分组
│ ├── highlight.ts # 代码高亮
│ ├── markdown.ts # Markdown 渲染
│ ├── segments.ts # 消息分段（thinking/tool/text）
│ ├── apiError.ts / avatar.ts / confirmDelete.ts / date.ts / fileIcon.ts /
│ │ folderTree.ts / iconLibrary.ts / pageConfigDefaults.ts / roles.ts /
│ │ scroll.ts / xlsxRange.ts / codeExecParser.ts / codeExecUtils.ts
│ └── index.ts # Barrel export
│
├── styles/ # 18 个 CSS 模块
│ ├── variables.css # CSS 自定义属性（颜色、阴影）
│ ├── common.css # 全局工具类
│ ├── chat.css / sidebar.css / catalog.css / tool.css
│ ├── automation.css / automation-timeline.css / batch（并入相关文件）
│ ├── canvas.css / config.css / mcp.css / myspace.css / plan.css
│ └── projects.css / search-modal.css / settings.css / skill-distill.css / team-folder.css
核心原则： 按功能分组，每组有 index.ts barrel export。
import React, { useState, useMemo, useCallback, useRef } from 'react';
import { Button, Input, message } from 'antd';
import { useChatStore } from '../../stores';
import type { ChatMessage } from '../../types';
import './styles.css'; // 如有独立样式
// 1. Props 接口（以 Props 结尾）
interface MyComponentProps {
chatId: string;
onClose: () => void;
items?: SomeItem[];
}
// 2. 函数式组件（named export）
export function MyComponent({ chatId, onClose, items = [] }: MyComponentProps) {
// 3. Hooks 在顶层调用
const { store, currentChatId } = useChatStore();
const [loading, setLoading] = useState(false);
const inputRef = useRef<HTMLInputElement>(null);
// 4. useMemo 用于派生状态
const filteredItems = useMemo(() => {
return items.filter(item => item.active);
}, [items]);
// 5. useCallback 用于稳定引用
const handleSubmit = useCallback(async () => {
setLoading(true);
try {
await someApiCall();
message.success('操作成功');
} catch (e) {
message.error(`操作失败：${(e as Error).message}`);
} finally {
setLoading(false);
}
}, [chatId]);
// 6. Early return 处理空状态
if (!items.length) {
return <div className="jx-empty">暂无数据</div>;
}
// 7. JSX 渲染
return (
<div className="jx-myComponent">
{filteredItems.map(item => (
<div key={item.id} className="jx-myComponent-item">
{item.name}
</div>
))}
<Button onClick={handleSubmit} loading={loading}>提交</Button>
</div>
);
}
export function），非 default exportProps 结尾useMemo 缓存计算，useCallback 稳定函数引用message.error() 提示用户index.ts 中 exportimport { create } from 'zustand';
// 1. 定义 State 接口（状态 + Actions）
interface MyState {
// 状态字段
items: Item[];
loading: boolean;
selectedId: string | null;
// Actions
setItems: (items: Item[]) => void;
setLoading: (loading: boolean) => void;
selectItem: (id: string | null) => void;
fetchItems: () => Promise<void>;
}
// 2. 创建 Store
export const useMyStore = create<MyState>((set, get) => ({
// 初始状态
items: [],
loading: false,
selectedId: null,
// 简单 setter
setItems: (items) => set({ items }),
setLoading: (loading) => set({ loading }),
selectItem: (id) => set({ selectedId: id }),
// 异步操作
fetchItems: async () => {
set({ loading: true });
try {
const data = await getItemsApi();
set({ items: data });
} catch (e) {
console.error('Failed to fetch items:', e);
} finally {
set({ loading: false });
}
},
}));
// 在组件中（自动订阅 re-render）
const { items, loading, fetchItems } = useMyStore();
// 在回调/事件中（不触发 re-render，用于读取最新值）
const currentItems = useMyStore.getState().items;
// 复杂更新（使用 updater 函数）
useChatStore.getState().updateStore((prev) => ({
chats: { ...prev.chats, [id]: updatedChat },
order: [id, ...prev.order.filter(x => x !== id)],
}));
set()，复杂逻辑用 get() 读取当前值localStorage 保存expandedToolCalls: Set<string>）// Hook 命名以 use 开头
export function useMyFeature(apiUrl: string) {
const { someState } = useSomeStore();
const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
// useEffect 按关注点分离
useEffect(() => {
// 初始化逻辑
return () => {
// 清理
if (timerRef.current) clearTimeout(timerRef.current);
};
}, []);
useEffect(() => {
// 响应依赖变化
}, [someState, apiUrl]);
// 返回对象（函数 + refs）
return {
doSomething,
timerRef,
};
}
规则：
hooks/ 目录hooks/index.ts 中 barrel export// 信封类型
interface ApiEnvelope<T> {
code: number;
message: string;
data: T;
trace_id?: string;
timestamp?: number;
}
// 带认证的 fetch
export async function authFetch(url: string, init?: RequestInit): Promise<Response> {
const headers = new Headers(init?.headers || {});
const token = getAuthToken();
if (token) headers.set('Authorization', `Bearer ${token}`);
const response = await fetch(url, { ...init, headers });
if (response.status === 401) onUnauthorized?.(loginUrl);
return response;
}
// 使用示例
const r = await authFetch(`${apiUrl}/v1/catalog`);
const { code, data } = await r.json();
authFetch()/v1/ 前缀code 字段，取 data// 面板导航
export type PanelKey =
| 'chat' | 'skills' | 'agents' | 'mcp' | 'kb' | 'docs'
| 'app_center' | 'settings' | 'share_records' | 'my_space'
| 'ability_center' | 'lab' | 'projects' | 'project_detail';
// 聊天消息
export interface ChatMessage {
role: ChatRole;
content: string;
isMarkdown?: boolean;
ts: number;
messageId?: string;
toolCalls?: ToolCall[];
thinking?: ThinkingBlock[];
segments?: MessageSegment[];
citations?: CitationItem[];
followUpQuestions?: string[];
attachments?: Array<{ name: string; mime_type?: string; file_id?: string; download_url?: string }>;
}
// Catalog 项
export interface CatalogItemBase {
id: string;
name: string;
desc: string;
enabled: boolean;
tags?: string[];
detail?: string;
}
types.tsinterface 而非 type（除非需要联合类型）any，必要时用 unknown + 类型守卫type = 'a' | 'b' | 'c' 字面量联合完整设计规范: 参见
references/ui-design-spec.md，包含颜色系统、字体排版、图标、圆角、间距等全部视觉标准。
/* 所有类名以 .jx- 为前缀 */
.jx-chatArea { }
.jx-chatArea-header { } /* Element: 连字符 */
.jx-chatArea-content { }
.jx-chatArea--empty { } /* Modifier: 双连字符 */
:root {
/* 主色 — 蓝色系 */
--color-primary: #126DFF;
--color-primary-hover: #3C87FF;
--color-primary-active: #0862F3;
--color-primary-bg: #DBE9FF;
--color-primary-light: #EBF2FF;
/* 文字 */
--color-text: #262626; /* 标题/强调 */
--color-text-secondary: #4D4D4D; /* 正文内容 */
--color-text-tertiary: #808080; /* 次要信息 */
--color-text-placeholder: #B3B3B3; /* 置灰/说明 */
/* 边框与填充 */
--color-border: #E3E6EA;
--color-fill: #D8DBE2;
--color-bg-gray: #F5F6F7;
/* 语义色 */
--color-success: #02B589;
--color-warning: #F8AB42;
--color-error: #FC5D5D;
/* 圆角 */
--radius-xs: 4px; /* 标签 */
--radius-sm: 8px; /* 按钮、输入框 */
--radius-md: 12px; /* 卡片 */
--radius-lg: 20px; /* 弹窗 */
/* 间距 (4px 基准) */
--space-xs: 4px; --space-sm: 8px;
--space-md: 16px; --space-lg: 20px; --space-xl: 40px;
/* 字体 */
--font-family: "PingFang SC", "Microsoft YaHei", "微软雅黑", sans-serif;
--font-family-number: "DingTalk Sans", "PingFang SC", "Microsoft YaHei", sans-serif;
}
.jx- 前缀-，修饰符用 --styles/ 对应文件中ui-design-spec.md 第 13 节）// useStreaming.ts 中的 SSE 事件处理模式（详见 references/sse-events.md）
const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');
let sseBuffer = '';
// 事件类型处理（注意：没有 text/done 事件！）
// 'run_started' → 首帧，记录 run_id/message_id 到 chatStore.activeRun（断线续播用）
// 'content' → 文本 delta 增量，追加到消息内容（兼容别名 ai_message/text/delta）
// 'thinking' → 思考过程，追加到 thinking segments
// 'tool_call' → 工具调用，追加到 toolCalls 数组 + segments（兼容 tool_use/tool_start）
// 'tool_result' → 工具结果，更新对应 toolCall 的 output/status + citations（兼容 tool_end）
// 'tool_pending' → 工具等待批复，UI 进入 pending 态
// 'batch_confirm' → 批量计划确认 → batchStore.setPendingConfirm 弹确认框
// 'file_confirm' → /myspace 写确认 → uiStore.enqueuePendingConfirm（流不结束，带外 POST 批复）
// 'follow_up' → 追问建议 follow_up_questions
// 'meta' → message_id、citations、workspace_files、artifacts
// 'error' → 抛错终止
// 'end' / 'data: [DONE]' → 流结束；心跳是 SSE 注释行（15s）
断线续播：run_started 给出的 run_id 可用 GET /v1/chats/stream/{run_id} 重新跟随后台 run。
// 并行处理：解析内容 + 上传到 OSS
const promise = Promise.all([
parseFileContent(file, apiUrl), // 二进制 → 后端解析，文本 → FileReader
uploadFileToOSS(file, apiUrl, chatId), // FormData → /v1/file/upload
]).then(([content, { file_id, download_url }]) => ({
name: file.name,
content,
file_id,
download_url,
mime_type: file.type,
}));
// 存储键命名规范
export const STORAGE_KEY = 'hugagent_ui_chat_history_v2'; // 聊天数据
export const ENABLE_KEY = 'hugagent_ui_enabled_catalog_v1'; // Catalog 状态
// ID 生成
export function nowId(prefix = 'chat') {
const d = new Date();
const pad = (n: number) => String(n).padStart(2, '0');
return `${prefix}_${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
}
// Store 中自动保存
setStore: (store) => {
set({ store });
saveChatStore(store); // → localStorage.setItem(STORAGE_KEY, JSON.stringify(store))
},
// catalogStore.ts
toggleItem: async (kind, itemId, enabled) => {
const { catalog } = get();
// 1. 先更新本地状态（乐观）
const updated = {
...catalog,
[kind]: catalog[kind].map(item =>
item.id === itemId ? { ...item, enabled } : item,
),
};
set({ catalog: updated });
saveCatalog(updated);
// 2. 后端同步（最大努力）
try {
await updateCatalogItem(kind, itemId, enabled);
} catch (e) {
console.error('Sync failed:', e);
}
},
const filteredList = useMemo(() => {
return list
.filter(item => matchesFilter(item, filter))
.sort((a, b) => b.updatedAt - a.updatedAt);
}, [list, filter]);
# SPA 路由回退
location / {
try_files $uri $uri/ /index.html;
}
# API 代理（支持 SSE）
location /api/ {
proxy_pass http://backend:${BACKEND_PORT}/;
client_max_body_size 50m;
proxy_buffering off; # SSE 必须关闭缓冲
proxy_cache off;
proxy_read_timeout 300s;
}
# 静态资源（长期缓存）
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable" always;
}
# index.html（不缓存）
location = /index.html {
add_header Cache-Control "no-store, no-cache, must-revalidate" always;
}
# 完整重建（慢但保证正确）
docker-compose up -d --build frontend
# 本地构建 + 热替换（快，需要 Node 20+）
cd src/frontend
npm run build
docker cp dist/. hugagent-frontend:/usr/share/nginx/html/
docker exec hugagent-frontend nginx -s reload
# 前端 lint
cd src/frontend && npm run lint
authFetch().jx- 前缀--color-primary 等），禁止硬编码色值--radius-xs/sm/md/lg）--space-xs/sm/md/lg/xl）message.error()index.ts 中 barrel exportany）npm run lint 通过