From c58323a13ac86a8f3ad48d6dd5b669f3c851489a Mon Sep 17 00:00:00 2001
From: xiami762 <>
Date: Wed, 27 May 2026 14:36:43 +0800
Subject: [PATCH 1/4] feat(webui): add custom device access wizard
 (API/WebCLI/Syslog)

Extend Device Integration with custom device onboarding for API, WebCLI,
and syslog modes, including types, panel UI, and tests. Document a third
web2cli capture path when CLI requirements are already specified.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .flocks/plugins/skills/web2cli/SKILL.md       |   5 +-
 .../CustomDeviceAccessPanel.tsx               | 449 ++++++++++++++++++
 .../DeviceIntegration/customDevice.test.ts    |  85 ++++
 .../pages/DeviceIntegration/customDevice.ts   | 143 ++++++
 .../pages/DeviceIntegration/index.test.tsx    | 238 ++++++++++
 webui/src/pages/DeviceIntegration/index.tsx   | 105 +++-
 webui/src/types/index.ts                      |  23 +
 7 files changed, 1032 insertions(+), 16 deletions(-)
 create mode 100644 webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx
 create mode 100644 webui/src/pages/DeviceIntegration/customDevice.test.ts
 create mode 100644 webui/src/pages/DeviceIntegration/customDevice.ts
 create mode 100644 webui/src/pages/DeviceIntegration/index.test.tsx

diff --git a/.flocks/plugins/skills/web2cli/SKILL.md b/.flocks/plugins/skills/web2cli/SKILL.md
index 27fe5685f..cccdbb34c 100644
--- a/.flocks/plugins/skills/web2cli/SKILL.md
+++ b/.flocks/plugins/skills/web2cli/SKILL.md
@@ -133,8 +133,9 @@ print(js("window.__apiCapture.config.captureMode"))
 
 ### 4. 明确需要捕获的功能/操作
 
-- 要求用户手动操作要捕获的页面动作，例如查询、翻页、筛选、提交表单、点击按钮、导出数据。
-- 或者请求用户描述需要 hook 的操作或功能，便于你直接去页面代替用户执行
+- 方式 1：要求用户手动操作要捕获的页面动作，例如查询、翻页、筛选、提交表单、点击按钮、导出数据。
+- 方式 2：请求用户描述需要 hook 的操作或功能，你直接去页面代替用户执行
+- 方式 3：用户之前已经描述了需要的 CLI功能，你直接去页面代替用户执行
 
 需要确认捕获是否开始时：
 
diff --git a/webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx b/webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx
new file mode 100644
index 000000000..c20b8e616
--- /dev/null
+++ b/webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx
@@ -0,0 +1,449 @@
+import { useEffect, useMemo, useState, type InputHTMLAttributes, type TextareaHTMLAttributes } from 'react';
+import { ChevronLeft, Loader2, MessageSquare, RefreshCw, Route, Workflow, X } from 'lucide-react';
+import { useNavigate } from 'react-router-dom';
+import { useToast } from '@/components/common/Toast';
+import SessionChat from '@/components/common/SessionChat';
+import { useSessionChat } from '@/hooks/useSessionChat';
+import { toolAPI } from '@/api/tool';
+import type {
+  APIServiceSummary,
+  CustomDeviceAccessMode,
+  CustomDeviceApiDraft,
+  CustomDeviceWebCliDraft,
+} from '@/types';
+import {
+  buildCustomDevicePrompt,
+  buildCustomDeviceSessionContext,
+  buildCustomDeviceWelcomeMessage,
+  findTemplateForCustomDevice,
+} from './customDevice';
+
+type PanelView = 'details' | 'rex' | 'guide';
+
+const EMPTY_API_DRAFT: CustomDeviceApiDraft = {
+  accessMode: 'api',
+  deviceName: '',
+  vendorName: '',
+  version: '',
+  baseUrl: '',
+  docsUrl: '',
+  capabilities: '全部 API',
+};
+
+const EMPTY_WEBCLI_DRAFT: CustomDeviceWebCliDraft = {
+  accessMode: 'webcli',
+  deviceName: '',
+  vendorName: '',
+  version: '',
+  productUrl: '',
+  targetInterfaces: '',
+  authHint: '',
+};
+
+function FieldLabel({ label, required = false }: { label: string; required?: boolean }) {
+  return (
+    <label className="block text-xs font-medium text-zinc-600 mb-1.5">
+      {label}
+      {required && <span className="text-red-500 ml-0.5">*</span>}
+    </label>
+  );
+}
+
+function TextInput(props: InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <input
+      {...props}
+      className={`w-full rounded-lg border border-zinc-200 bg-white px-3 py-2 text-sm text-zinc-900 focus:border-blue-300 focus:outline-none focus:ring-2 focus:ring-blue-100 ${
+        props.className ?? ''
+      }`}
+    />
+  );
+}
+
+function TextArea(props: TextareaHTMLAttributes<HTMLTextAreaElement>) {
+  return (
+    <textarea
+      {...props}
+      className={`w-full rounded-lg border border-zinc-200 bg-white px-3 py-2 text-sm text-zinc-900 focus:border-blue-300 focus:outline-none focus:ring-2 focus:ring-blue-100 ${
+        props.className ?? ''
+      }`}
+    />
+  );
+}
+
+function validateDraft(draft: CustomDeviceApiDraft | CustomDeviceWebCliDraft): string | null {
+  if (!draft.deviceName.trim()) return '请填写设备产品名';
+  if (!draft.vendorName.trim()) return '请填写厂商名称';
+
+  if (draft.accessMode === 'api') {
+    if (!draft.baseUrl.trim()) return '请填写 Base URL';
+    return null;
+  }
+
+  if (!draft.productUrl.trim()) return '请填写产品 URL';
+  if (!draft.targetInterfaces.trim()) return '请填写需要获取的接口或页面行为';
+  return null;
+}
+
+export default function CustomDeviceAccessPanel({
+  mode,
+  onClose,
+  onBack,
+  onRefreshTemplates,
+  onTemplateMatched,
+}: {
+  mode: CustomDeviceAccessMode;
+  onClose: () => void;
+  onBack: () => void;
+  onRefreshTemplates: () => Promise<APIServiceSummary[]>;
+  onTemplateMatched: (template: APIServiceSummary) => void;
+}) {
+  const navigate = useNavigate();
+  const toast = useToast();
+  const isSyslog = mode === 'syslog';
+  const [view, setView] = useState<PanelView>(isSyslog ? 'guide' : 'details');
+  const [apiDraft, setApiDraft] = useState<CustomDeviceApiDraft>(EMPTY_API_DRAFT);
+  const [webcliDraft, setWebcliDraft] = useState<CustomDeviceWebCliDraft>(EMPTY_WEBCLI_DRAFT);
+  const [submitting, setSubmitting] = useState(false);
+  const [refreshing, setRefreshing] = useState(false);
+
+  const draft = mode === 'api' ? apiDraft : mode === 'webcli' ? webcliDraft : null;
+  const title = useMemo(() => {
+    if (mode === 'api') return '自定义设备 API 接入';
+    if (mode === 'webcli') return '自定义设备 WebCLI 接入';
+    return '自定义设备 Syslog 接入';
+  }, [mode]);
+
+  const { sessionId, createAndSend, reset } = useSessionChat({
+    title: draft?.deviceName.trim() ? `${title}：${draft.deviceName.trim()}` : title,
+    category: 'entity-config',
+    contextMessage: buildCustomDeviceSessionContext(mode),
+    welcomeMessage: buildCustomDeviceWelcomeMessage(mode),
+  });
+
+  useEffect(() => reset, [reset]);
+
+  const handleSubmitToRex = async () => {
+    if (!draft) return;
+    const error = validateDraft(draft);
+    if (error) {
+      toast.error(error);
+      return;
+    }
+    setSubmitting(true);
+    try {
+      await createAndSend({ text: buildCustomDevicePrompt(draft) });
+      setView('rex');
+      toast.success('已提交给 Rex，请继续完成插件生成');
+    } catch {
+      toast.error('提交给 Rex 失败');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleRefreshTemplates = async () => {
+    if (!draft) return;
+    setRefreshing(true);
+    try {
+      await toolAPI.refresh();
+      const matched = findTemplateForCustomDevice(await onRefreshTemplates(), draft.deviceName);
+      if (matched) {
+        toast.success('已找到新的设备模板，继续填写接入配置');
+        onTemplateMatched(matched);
+        return;
+      }
+      toast.info('已刷新设备模板，暂未找到同名设备，请继续在 Rex 中完善插件');
+    } catch {
+      toast.error('刷新设备模板失败');
+    } finally {
+      setRefreshing(false);
+    }
+  };
+
+  const renderApiForm = () => (
+    <div className="space-y-4">
+      <div className="grid grid-cols-2 gap-3">
+        <div>
+          <FieldLabel label="设备产品名" required />
+          <TextInput
+            aria-label="设备产品名"
+            value={apiDraft.deviceName}
+            onChange={(e) => setApiDraft((prev) => ({ ...prev, deviceName: e.target.value }))}
+            placeholder="例如：自定义堡垒机"
+          />
+        </div>
+        <div>
+          <FieldLabel label="厂商名称" required />
+          <TextInput
+            aria-label="厂商名称"
+            value={apiDraft.vendorName}
+            onChange={(e) => setApiDraft((prev) => ({ ...prev, vendorName: e.target.value }))}
+            placeholder="例如：Acme Security"
+          />
+        </div>
+      </div>
+
+      <div>
+        <FieldLabel label="产品版本" />
+        <TextInput
+          aria-label="产品版本"
+          value={apiDraft.version}
+          onChange={(e) => setApiDraft((prev) => ({ ...prev, version: e.target.value }))}
+          placeholder="例如：v3.2.1"
+        />
+      </div>
+
+      <div>
+        <FieldLabel label="Base URL" required />
+        <TextInput
+          aria-label="Base URL"
+          value={apiDraft.baseUrl}
+          onChange={(e) => setApiDraft((prev) => ({ ...prev, baseUrl: e.target.value }))}
+          placeholder="例如：https://device.example.com/api"
+        />
+      </div>
+
+      <div>
+        <FieldLabel label="API 文档链接" />
+        <TextInput
+          aria-label="API 文档链接"
+          value={apiDraft.docsUrl}
+          onChange={(e) => setApiDraft((prev) => ({ ...prev, docsUrl: e.target.value }))}
+          placeholder="例如：https://device.example.com/openapi"
+        />
+        <p className="mt-1 text-[11px] text-zinc-400">没有公开链接也没关系，提交后可在 Rex 对话中继续上传 API 文档。</p>
+      </div>
+
+      <div>
+        <FieldLabel label="期望接入的能力范围" />
+        <TextArea
+          aria-label="期望接入的能力范围"
+          value={apiDraft.capabilities}
+          onChange={(e) => setApiDraft((prev) => ({ ...prev, capabilities: e.target.value }))}
+          placeholder="默认全部 API，可选定需要的 API"
+          rows={3}
+        />
+        <p className="mt-1 text-[11px] text-zinc-400">默认全部 API；如果你只想接特定接口，可以在这里指定需要的 API。</p>
+      </div>
+    </div>
+  );
+
+  const renderWebCliForm = () => (
+    <div className="space-y-4">
+      <div className="grid grid-cols-2 gap-3">
+        <div>
+          <FieldLabel label="设备产品名" required />
+          <TextInput
+            aria-label="设备产品名"
+            value={webcliDraft.deviceName}
+            onChange={(e) => setWebcliDraft((prev) => ({ ...prev, deviceName: e.target.value }))}
+            placeholder="例如：自定义态势平台"
+          />
+        </div>
+        <div>
+          <FieldLabel label="厂商名称" required />
+          <TextInput
+            aria-label="厂商名称"
+            value={webcliDraft.vendorName}
+            onChange={(e) => setWebcliDraft((prev) => ({ ...prev, vendorName: e.target.value }))}
+            placeholder="例如：Acme Security"
+          />
+        </div>
+      </div>
+
+      <div>
+        <FieldLabel label="产品版本" />
+        <TextInput
+          aria-label="产品版本"
+          value={webcliDraft.version}
+          onChange={(e) => setWebcliDraft((prev) => ({ ...prev, version: e.target.value }))}
+          placeholder="例如：2026.05"
+        />
+      </div>
+
+      <div>
+        <FieldLabel label="产品 URL" required />
+        <TextInput
+          aria-label="产品 URL"
+          value={webcliDraft.productUrl}
+          onChange={(e) => setWebcliDraft((prev) => ({ ...prev, productUrl: e.target.value }))}
+          placeholder="例如：https://device.example.com"
+        />
+      </div>
+
+      <div>
+        <FieldLabel label="需要获取的接口或页面行为" required />
+        <TextArea
+          aria-label="需要获取的接口或页面行为"
+          value={webcliDraft.targetInterfaces}
+          onChange={(e) => setWebcliDraft((prev) => ({ ...prev, targetInterfaces: e.target.value }))}
+          placeholder="例如：抓取告警列表接口、资产详情接口，以及“封禁 IP”按钮对应请求"
+          rows={5}
+        />
+      </div>
+
+      <div>
+        <FieldLabel label="认证/权限提示" />
+        <TextArea
+          aria-label="认证/权限提示"
+          value={webcliDraft.authHint}
+          onChange={(e) => setWebcliDraft((prev) => ({ ...prev, authHint: e.target.value }))}
+          placeholder="例如：需要管理员角色；接口依赖 Cookie + X-CSRF-Token"
+          rows={3}
+        />
+      </div>
+    </div>
+  );
+
+  return (
+    <div className="fixed inset-y-0 right-0 flex items-start justify-end z-40 pointer-events-none">
+      <div
+        className="pointer-events-auto bg-white shadow-2xl border-l border-zinc-200 flex flex-col"
+        style={{ width: 520, marginTop: 64, height: 'calc(100vh - 64px)' }}
+      >
+        <div className="flex items-center justify-between px-5 py-4 border-b border-zinc-100 flex-shrink-0">
+          <div className="flex items-center gap-2.5 min-w-0">
+            <button
+              onClick={onBack}
+              className="p-1.5 rounded-lg hover:bg-zinc-100 text-zinc-500 hover:text-zinc-700 transition-colors flex-shrink-0"
+            >
+              <ChevronLeft className="w-4 h-4" />
+            </button>
+            <div className={`w-9 h-9 rounded-xl flex items-center justify-center flex-shrink-0 ${
+              isSyslog ? 'bg-emerald-50' : 'bg-blue-50'
+            }`}>
+              {mode === 'api' ? <MessageSquare className="w-4 h-4 text-blue-500" /> : null}
+              {mode === 'webcli' ? <Route className="w-4 h-4 text-blue-500" /> : null}
+              {mode === 'syslog' ? <Workflow className="w-4 h-4 text-emerald-600" /> : null}
+            </div>
+            <div className="min-w-0">
+              <h3 className="text-sm font-semibold text-zinc-900 truncate">{title}</h3>
+              <p className="text-xs text-zinc-400 mt-0.5">
+                {mode === 'api' && '提供 API 文档，生成可复用的 device 插件'}
+                {mode === 'webcli' && '提供产品 URL 和目标接口，生成 CLI 并集成到 skill'}
+                {mode === 'syslog' && 'Syslog 仅支持在工作流集成页面配置'}
+              </p>
+            </div>
+          </div>
+          <button onClick={onClose} className="p-1.5 rounded-lg hover:bg-zinc-100 text-zinc-400 hover:text-zinc-600 flex-shrink-0">
+            <X className="w-4 h-4" />
+          </button>
+        </div>
+
+        <div className="flex-1 min-h-0 overflow-y-auto px-5 py-4">
+          {isSyslog ? (
+            <div className="space-y-4">
+              <div className="rounded-xl border border-emerald-100 bg-emerald-50 px-4 py-3">
+                <p className="text-sm font-medium text-emerald-800">Syslog 目前只能在工作流中使用</p>
+                <p className="text-xs text-emerald-700 mt-1.5 leading-relaxed">
+                  你可以在工作流详情页的 Integration 标签中配置监听协议、主机、端口、日志格式和 inputKey，
+                  然后让设备把日志转发到对应地址。
+                </p>
+              </div>
+
+              <div className="rounded-xl border border-zinc-100 px-4 py-3 space-y-2">
+                <p className="text-xs font-semibold text-zinc-400 uppercase tracking-wide">配置要求</p>
+                <ul className="text-sm text-zinc-600 space-y-1.5 list-disc pl-5">
+                  <li>选择 UDP 或 TCP 协议，并确认工作流监听地址可从设备侧访问。</li>
+                  <li>设置监听端口、日志格式和输入键名，确保工作流节点能消费 `syslog_message` 或自定义 inputKey。</li>
+                  <li>在设备上配置 Syslog 转发地址后，再到工作流执行历史中确认是否收到数据。</li>
+                </ul>
+              </div>
+            </div>
+          ) : view === 'details' ? (
+            <div className="space-y-4">
+              <div className="rounded-xl border border-zinc-100 bg-zinc-50 px-4 py-3">
+                <p className="text-sm font-medium text-zinc-800">提交给 Rex 前请准备好接入资料</p>
+                <p className="text-xs text-zinc-500 mt-1.5 leading-relaxed">
+                  提交后会直接进入 Rex 对话。
+                  {mode === 'api'
+                    ? '你可以继续补充 API 文档链接、上传文档文件或说明接口细节。插件生成完成后，再点击底部“刷新设备模板”继续接入。'
+                    : '你可以继续补充页面操作、抓包目标和认证方式。最终结果应当是 CLI 集成到 skill 中。'}
+                </p>
+              </div>
+              {mode === 'api' ? renderApiForm() : renderWebCliForm()}
+            </div>
+          ) : (
+            <div className="h-full min-h-[420px] -mx-5 -my-4">
+              <div className="px-5 py-3 border-b border-zinc-100 bg-zinc-50">
+                <p className="text-xs text-zinc-500 leading-relaxed">
+                  {mode === 'api'
+                    ? '与 Rex 协作生成插件后，回到此处点击“刷新设备模板”。如果已生成同名 device 插件，页面会自动跳转到设备配置面板。若 API 文档不便粘贴，可直接在当前对话中上传。'
+                    : '与 Rex 协作完成后，请确认 CLI 已生成并集成到 skill 中。这里不会生成设备模板，也不需要刷新设备模板。'}
+                </p>
+              </div>
+              <SessionChat
+                sessionId={sessionId}
+                live={!!sessionId}
+                className="h-[calc(100%-61px)]"
+                placeholder="继续补充接口说明、认证细节或调试信息"
+                emptyText="Rex 准备中..."
+                onCreateAndSend={!sessionId ? (text, imageParts) => createAndSend({ text, imageParts }) : undefined}
+              />
+            </div>
+          )}
+        </div>
+
+        <div className="border-t border-zinc-100 px-5 py-4 flex-shrink-0">
+          {isSyslog ? (
+            <div className="flex items-center justify-between gap-2">
+              <button
+                onClick={onBack}
+                className="px-4 py-2 text-sm rounded-lg border border-zinc-200 text-zinc-600 hover:bg-zinc-50 transition-colors"
+              >
+                返回选择方式
+              </button>
+              <button
+                onClick={() => {
+                  onClose();
+                  navigate('/workflows');
+                }}
+                className="px-4 py-2 text-sm rounded-lg bg-emerald-600 text-white hover:bg-emerald-700 transition-colors"
+              >
+                前往工作流列表
+              </button>
+            </div>
+          ) : (
+            <div className="flex items-center justify-between gap-2">
+              <div className="flex items-center gap-2">
+                <button
+                  onClick={view === 'details' ? onBack : () => setView('details')}
+                  className="px-4 py-2 text-sm rounded-lg border border-zinc-200 text-zinc-600 hover:bg-zinc-50 transition-colors"
+                >
+                  {view === 'details' ? '返回选择方式' : '返回资料填写'}
+                </button>
+                {mode === 'api' && view === 'rex' && (
+                  <button
+                    onClick={() => void handleRefreshTemplates()}
+                    disabled={refreshing}
+                    className="inline-flex items-center gap-1.5 px-4 py-2 text-sm rounded-lg border border-zinc-200 text-zinc-600 hover:bg-zinc-50 disabled:opacity-50 transition-colors"
+                  >
+                    {refreshing ? <Loader2 className="w-3.5 h-3.5 animate-spin" /> : <RefreshCw className="w-3.5 h-3.5" />}
+                    刷新设备模板
+                  </button>
+                )}
+              </div>
+              {view === 'details' ? (
+                <button
+                  onClick={() => void handleSubmitToRex()}
+                  disabled={submitting}
+                  className="inline-flex items-center gap-1.5 px-4 py-2 text-sm rounded-lg bg-red-600 text-white hover:bg-red-700 disabled:opacity-50 transition-colors"
+                >
+                  {submitting ? <Loader2 className="w-3.5 h-3.5 animate-spin" /> : <MessageSquare className="w-3.5 h-3.5" />}
+                  提交给 Rex
+                </button>
+              ) : (
+                <span className="text-xs text-zinc-400">
+                  {mode === 'api'
+                    ? '已进入 Rex 对话，可继续补充文档与需求'
+                    : '已进入 Rex 对话，可继续补充抓包目标并完成 CLI skill 集成'}
+                </span>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/webui/src/pages/DeviceIntegration/customDevice.test.ts b/webui/src/pages/DeviceIntegration/customDevice.test.ts
new file mode 100644
index 000000000..6b464206a
--- /dev/null
+++ b/webui/src/pages/DeviceIntegration/customDevice.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import type { APIServiceSummary, CustomDeviceApiDraft, CustomDeviceWebCliDraft } from '@/types';
+import {
+  buildCustomDevicePrompt,
+  buildCustomDeviceServiceId,
+  buildCustomDeviceVendorKey,
+  findTemplateForCustomDevice,
+} from './customDevice';
+
+describe('customDevice helpers', () => {
+  it('builds api prompt with device plugin constraints', () => {
+    const draft: CustomDeviceApiDraft = {
+      accessMode: 'api',
+      deviceName: 'Acme Guard',
+      vendorName: 'Acme Security',
+      version: 'v3.2.1',
+      baseUrl: 'https://device.example.com/api',
+      docsUrl: 'https://device.example.com/openapi',
+      capabilities: '全部 API',
+    };
+
+    const prompt = buildCustomDevicePrompt(draft);
+
+    expect(prompt).toContain('设备产品名：Acme Guard');
+    expect(prompt).toContain('API 文档链接：https://device.example.com/openapi');
+    expect(prompt).toContain('integration_type: device');
+    expect(prompt).toContain('~/.flocks/plugins/tools/device/<plugin_id>/');
+    expect(prompt).toContain('`name` 必须精确使用产品名：`Acme Guard`');
+    expect(prompt).toContain('`service_id` 建议使用：`acme_guard_device`');
+    expect(prompt).toContain('tool-builder skill');
+  });
+
+  it('builds webcli prompt with browser capture guidance', () => {
+    const draft: CustomDeviceWebCliDraft = {
+      accessMode: 'webcli',
+      deviceName: 'Acme Portal',
+      vendorName: 'Acme Security',
+      version: '',
+      productUrl: 'https://portal.example.com',
+      targetInterfaces: '告警列表和资产详情',
+      authHint: 'Cookie + CSRF Token',
+    };
+
+    const prompt = buildCustomDevicePrompt(draft);
+
+    expect(prompt).toContain('接入方式：WebCLI');
+    expect(prompt).toContain('产品 URL：https://portal.example.com');
+    expect(prompt).toContain('需要获取的接口/页面行为：告警列表和资产详情');
+    expect(prompt).toContain('browser-use / web2cli');
+    expect(prompt).toContain('web2cli skill');
+    expect(prompt).toContain('CLI');
+    expect(prompt).toContain('skill');
+  });
+
+  it('sanitizes vendor key and service id', () => {
+    expect(buildCustomDeviceVendorKey('Acme Security CN')).toBe('acme_security_cn');
+    expect(buildCustomDeviceServiceId('Acme Guard')).toBe('acme_guard_device');
+  });
+
+  it('finds matching template by exact or partial name', () => {
+    const templates: APIServiceSummary[] = [
+      {
+        id: 'existing_v1',
+        name: 'Existing Device',
+        enabled: true,
+        status: 'unknown',
+        tool_count: 1,
+        verify_ssl: false,
+        integration_type: 'device',
+      },
+      {
+        id: 'acme_guard_device_v1',
+        name: 'Acme Guard',
+        enabled: true,
+        status: 'unknown',
+        tool_count: 2,
+        verify_ssl: false,
+        integration_type: 'device',
+      },
+    ];
+
+    expect(findTemplateForCustomDevice(templates, 'Acme Guard')?.id).toBe('acme_guard_device_v1');
+    expect(findTemplateForCustomDevice(templates, 'Acme')?.id).toBe('acme_guard_device_v1');
+  });
+});
diff --git a/webui/src/pages/DeviceIntegration/customDevice.ts b/webui/src/pages/DeviceIntegration/customDevice.ts
new file mode 100644
index 000000000..de7ea4557
--- /dev/null
+++ b/webui/src/pages/DeviceIntegration/customDevice.ts
@@ -0,0 +1,143 @@
+import type {
+  APIServiceSummary,
+  CustomDeviceAccessMode,
+  CustomDeviceApiDraft,
+  CustomDeviceWebCliDraft,
+} from '@/types';
+
+function sanitizeSlug(value: string, fallback: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return normalized || fallback;
+}
+
+export function buildCustomDeviceVendorKey(vendorName: string): string {
+  return sanitizeSlug(vendorName, 'custom_vendor');
+}
+
+export function buildCustomDeviceServiceId(deviceName: string): string {
+  const base = sanitizeSlug(deviceName, 'custom_device');
+  return base.endsWith('_device') ? base : `${base}_device`;
+}
+
+function buildApiDeviceRequirements(deviceName: string, vendorName: string): string {
+  const vendorKey = buildCustomDeviceVendorKey(vendorName);
+  const serviceId = buildCustomDeviceServiceId(deviceName);
+  return [
+    '请严格遵循当前项目的 device 插件契约，不要生成普通 api 工具后就停止。',
+    '最终产物必须落到 `~/.flocks/plugins/tools/device/<plugin_id>/` 目录。',
+    '必须生成 `_provider.yaml`，并满足以下要求：',
+    `- \`name\` 必须精确使用产品名：\`${deviceName}\``,
+    `- \`vendor\` 建议使用：\`${vendorKey}\``,
+    `- \`service_id\` 建议使用：\`${serviceId}\``,
+    '- 必须包含 `integration_type: device`',
+    '- 必须声明 `version`、`credential_fields`、`description`、`description_cn`',
+    '- `credential_fields` 只定义运行时需要用户填写的字段，不能把真实凭据写进插件文件',
+    '- 至少生成一个可被设备页识别的 device YAML/script 工具，必要时补充 `.handler.py`',
+    '- 新建工具默认启用，并确保工具刷新后能出现在设备接入页',
+    '完成后请提醒用户在设备页点击“刷新设备模板”。',
+  ].join('\n');
+}
+
+function buildWebCliSkillRequirements(deviceName: string, vendorName: string): string {
+  const vendorKey = buildCustomDeviceVendorKey(vendorName);
+  return [
+    '请严格遵循当前项目的 web2cli skill 流程，不要只停留在临时抓包或一次性脚本。',
+    '最终结果应当生成可复用 CLI，并将 CLI 集成到 skill 中供后续调用。',
+    '请优先遵循 `web2cli` skill 中的捕获、导出、生成 CLI、沉淀到 skill 的完整流程。',
+    `建议使用厂商标识：\`${vendorKey}\`，产品名：\`${deviceName}\`，保证 skill/CLI 命名清晰可追踪。`,
+    '不要把用户在表单里填写的账号、密码、Token、Cookie 直接硬编码到 CLI 或 skill 中。',
+    '最终产物应包含清晰的 skill 使用入口、CLI 调用说明，以及必要的认证状态保存方式。',
+    '不要把结果伪装成 device 插件，也不要要求用户回到设备页刷新模板。',
+  ].join('\n');
+}
+
+export function buildCustomDeviceSessionContext(mode: CustomDeviceAccessMode): string {
+  if (mode === 'api') {
+    return [
+      '你是 Flocks 的自定义设备接入助手。',
+      '目标是把用户描述的 API 能力接入为可在“设备接入”页面出现的 device 插件，而不是普通 API 服务。',
+      '你必须先阅读并参考项目中现有 device 插件结构，例如 `.flocks/plugins/tools/device/*/_provider.yaml` 与对应 YAML/script handler。',
+      '不要把用户在表单里填写的账号、密码、Token、Cookie 直接写入插件；这些都应该通过 `credential_fields` 暴露为设备实例配置项。',
+      '本次接入方式是 API 接入。',
+      '你必须先读取并使用 tool-builder skill，再开始生成插件。',
+      '用户会提供 API 文档链接或后续上传文档文件，请根据文档盘点接口后生成 device 插件。',
+      '优先选择 YAML-HTTP；如存在签名、登录换 token、复杂预处理，则使用 YAML-Script + handler。',
+      '虽然参考 tool-builder skill，但最终输出目录和插件结构必须符合 device 插件规范。',
+    ].join('\n');
+  }
+  if (mode === 'webcli') {
+    return [
+      '你是 Flocks 的自定义设备接入助手。',
+      '本次接入方式是 WebCLI 接入。',
+      '你必须先读取并使用 web2cli skill，再开始捕获与转换流程。',
+      '用户会提供产品 URL 和需要获取的接口/页面行为。你可以使用 web2cli 思路抓取接口，但最终结果应当是 CLI 集成到 skill 中。',
+      '不要只留下临时 CLI 或抓包产物；最终结果必须是可复用 CLI + skill 集成入口。',
+    ].join('\n');
+  }
+  return [
+    '本次是 Syslog 引导，不需要创建 device 插件。',
+  ].join('\n');
+}
+
+export function buildCustomDeviceWelcomeMessage(mode: CustomDeviceAccessMode): string {
+  if (mode === 'api') {
+    return '请补充 API 文档链接或直接上传文档文件，并说明目标能力，我会用 tool-builder skill 帮你生成可在设备页使用的 device 插件。';
+  }
+  if (mode === 'webcli') {
+    return '请补充产品 URL、目标接口和认证提示，我会用 web2cli skill 帮你生成 CLI 并集成到 skill 中。';
+  }
+  return 'Syslog 方式不在这里创建插件，请前往工作流集成页面配置。';
+}
+
+export function buildCustomDevicePrompt(
+  draft: CustomDeviceApiDraft | CustomDeviceWebCliDraft,
+): string {
+  const header = [
+    `设备产品名：${draft.deviceName}`,
+    `厂商名称：${draft.vendorName}`,
+    draft.version ? `产品版本：${draft.version}` : '',
+    '',
+  ].filter(Boolean);
+
+  if (draft.accessMode === 'api') {
+    return [
+      ...header,
+      buildApiDeviceRequirements(draft.deviceName, draft.vendorName),
+      '',
+      '接入方式：API',
+      `Base URL：${draft.baseUrl}`,
+      `期望能力范围：${draft.capabilities.trim() || '全部 API'}`,
+      draft.docsUrl.trim() ? `API 文档链接：${draft.docsUrl.trim()}` : '',
+      '',
+      '必须先读取并使用 tool-builder skill，再根据 API 文档盘点接口并生成 device 插件。',
+      '请根据 API 文档盘点接口并生成 device 插件。若当前没有完整文档，请在后续 Rex 对话中继续索取或等待用户上传文档文件，不要假设接口细节。',
+    ].filter(Boolean).join('\n');
+  }
+
+  return [
+    ...header,
+    buildWebCliSkillRequirements(draft.deviceName, draft.vendorName),
+    '',
+    '接入方式：WebCLI',
+    `产品 URL：${draft.productUrl}`,
+    `需要获取的接口/页面行为：${draft.targetInterfaces}`,
+    draft.authHint.trim() ? `认证/权限提示：${draft.authHint.trim()}` : '',
+    '',
+    '必须先读取并使用 web2cli skill，再执行捕获、导出与转换流程。',
+    '请使用 browser-use / web2cli 思路分析页面请求，并把结果生成 CLI 后集成到 skill 中，而不是只保留临时脚本。',
+  ].filter(Boolean).join('\n');
+}
+
+export function findTemplateForCustomDevice(
+  templates: APIServiceSummary[],
+  deviceName: string,
+): APIServiceSummary | undefined {
+  const normalized = deviceName.trim().toLowerCase();
+  if (!normalized) return undefined;
+  return templates.find((template) => template.name.trim().toLowerCase() === normalized)
+    ?? templates.find((template) => template.name.trim().toLowerCase().includes(normalized));
+}
diff --git a/webui/src/pages/DeviceIntegration/index.test.tsx b/webui/src/pages/DeviceIntegration/index.test.tsx
new file mode 100644
index 000000000..23bec36e9
--- /dev/null
+++ b/webui/src/pages/DeviceIntegration/index.test.tsx
@@ -0,0 +1,238 @@
+import React from 'react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import DeviceIntegrationPage from './index';
+
+const mocks = vi.hoisted(() => ({
+  toastSuccess: vi.fn(),
+  toastError: vi.fn(),
+  toastInfo: vi.fn(),
+  navigate: vi.fn(),
+  createAndSend: vi.fn().mockResolvedValue('session-1'),
+  resetSession: vi.fn(),
+  listDevices: vi.fn(),
+  listGroups: vi.fn(),
+  updateGroup: vi.fn(),
+  createDevice: vi.fn(),
+  updateDevice: vi.fn(),
+  deleteDevice: vi.fn(),
+  testDevice: vi.fn(),
+  listApiServices: vi.fn(),
+  getServiceMetadata: vi.fn(),
+  listTools: vi.fn(),
+  setToolEnabled: vi.fn(),
+  refreshTools: vi.fn(),
+}));
+
+vi.mock('react-router-dom', () => ({
+  useNavigate: () => mocks.navigate,
+}));
+
+vi.mock('@/components/common/Toast', () => ({
+  useToast: () => ({
+    success: mocks.toastSuccess,
+    error: mocks.toastError,
+    info: mocks.toastInfo,
+  }),
+}));
+
+vi.mock('@/components/common/PageHeader', () => ({
+  default: ({
+    title,
+    description,
+    action,
+  }: {
+    title: string;
+    description?: string;
+    action?: React.ReactNode;
+  }) => (
+    <div>
+      <h1>{title}</h1>
+      {description && <p>{description}</p>}
+      <div>{action}</div>
+    </div>
+  ),
+}));
+
+vi.mock('@/components/common/LoadingSpinner', () => ({
+  default: () => <div>loading</div>,
+}));
+
+vi.mock('../Tool/components/ToolDetailModal', () => ({
+  default: () => null,
+}));
+
+vi.mock('@/components/common/SessionChat', () => ({
+  default: ({ sessionId }: { sessionId?: string | null }) => (
+    <div>SessionChat:{sessionId ?? 'pending'}</div>
+  ),
+}));
+
+vi.mock('@/hooks/useSessionChat', () => ({
+  useSessionChat: () => ({
+    sessionId: 'session-1',
+    loading: false,
+    error: null,
+    create: vi.fn().mockResolvedValue('session-1'),
+    createAndSend: mocks.createAndSend,
+    retry: vi.fn(),
+    reset: mocks.resetSession,
+  }),
+}));
+
+vi.mock('@/api/device', () => ({
+  deviceAPI: {
+    list: (...args: unknown[]) => mocks.listDevices(...args),
+    listGroups: (...args: unknown[]) => mocks.listGroups(...args),
+    updateGroup: (...args: unknown[]) => mocks.updateGroup(...args),
+    create: (...args: unknown[]) => mocks.createDevice(...args),
+    update: (...args: unknown[]) => mocks.updateDevice(...args),
+    delete: (...args: unknown[]) => mocks.deleteDevice(...args),
+    test: (...args: unknown[]) => mocks.testDevice(...args),
+  },
+}));
+
+vi.mock('@/api/provider', () => ({
+  providerAPI: {
+    listApiServices: (...args: unknown[]) => mocks.listApiServices(...args),
+    getServiceMetadata: (...args: unknown[]) => mocks.getServiceMetadata(...args),
+  },
+}));
+
+vi.mock('@/api/tool', () => ({
+  toolAPI: {
+    list: (...args: unknown[]) => mocks.listTools(...args),
+    setEnabled: (...args: unknown[]) => mocks.setToolEnabled(...args),
+    refresh: (...args: unknown[]) => mocks.refreshTools(...args),
+  },
+}));
+
+function buildTemplate(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'existing_device_v1',
+    name: 'Existing Device',
+    enabled: true,
+    status: 'unknown',
+    tool_count: 1,
+    verify_ssl: false,
+    integration_type: 'device',
+    vendor: 'threatbook',
+    ...overrides,
+  };
+}
+
+describe('DeviceIntegrationPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.listDevices.mockResolvedValue({ data: [] });
+    mocks.listGroups.mockResolvedValue({
+      data: [{ id: 'default', name: '默认机房', sort_order: 0, created_at: 0, updated_at: 0 }],
+    });
+    mocks.listApiServices.mockResolvedValue({ data: [buildTemplate()] });
+    mocks.getServiceMetadata.mockResolvedValue({ data: { credential_schema: [] } });
+    mocks.listTools.mockResolvedValue({ data: [] });
+    mocks.refreshTools.mockResolvedValue({ data: { ok: true } });
+  });
+
+  it('shows custom device option and access modes', async () => {
+    const user = userEvent.setup();
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
+    await user.click(screen.getByRole('button', { name: /自定义设备/ }));
+
+    expect(screen.getByText('API 接入')).toBeInTheDocument();
+    expect(screen.getByText('WebCLI 接入')).toBeInTheDocument();
+    expect(screen.getByText('Syslog 接入')).toBeInTheDocument();
+  });
+
+  it('submits api draft to Rex with device plugin prompt', async () => {
+    const user = userEvent.setup();
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
+    await user.click(screen.getByRole('button', { name: /自定义设备/ }));
+    await user.click(screen.getByRole('button', { name: /API 接入/ }));
+
+    await user.type(screen.getByLabelText('设备产品名'), 'Acme Guard');
+    await user.type(screen.getByLabelText('厂商名称'), 'Acme Security');
+    await user.type(screen.getByLabelText('Base URL'), 'https://device.example.com/api');
+    await user.type(screen.getByLabelText('API 文档链接'), 'https://device.example.com/openapi');
+    expect(screen.queryByLabelText('API 文档内容')).toBeNull();
+    expect(screen.queryByLabelText('认证方式')).toBeNull();
+    expect(screen.queryByText('Rex 对话')).toBeNull();
+    await user.click(screen.getByRole('button', { name: /提交给 Rex/ }));
+
+    await waitFor(() => expect(mocks.createAndSend).toHaveBeenCalledTimes(1));
+    const arg = mocks.createAndSend.mock.calls[0][0];
+    expect(arg.text).toContain('Acme Guard');
+    expect(arg.text).toContain('https://device.example.com/openapi');
+    expect(arg.text).toContain('integration_type: device');
+    expect(arg.text).toContain('~/.flocks/plugins/tools/device/<plugin_id>/');
+    expect(arg.text).toContain('期望能力范围：全部 API');
+    expect(arg.text).toContain('tool-builder skill');
+    expect(await screen.findByText('SessionChat:session-1')).toBeInTheDocument();
+  });
+
+  it('shows webcli form without login hint field', async () => {
+    const user = userEvent.setup();
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
+    await user.click(screen.getByRole('button', { name: /自定义设备/ }));
+    await user.click(screen.getByRole('button', { name: /WebCLI 接入/ }));
+
+    expect(screen.queryByLabelText('登录说明')).toBeNull();
+    expect(screen.getByText('产品 URL')).toBeInTheDocument();
+    expect(screen.getByLabelText('产品 URL')).toBeInTheDocument();
+    expect(screen.getByLabelText('需要获取的接口或页面行为')).toBeInTheDocument();
+  });
+
+  it('refreshes templates and enters device config when matching template appears', async () => {
+    const user = userEvent.setup();
+    mocks.listApiServices
+      .mockResolvedValueOnce({ data: [buildTemplate()] })
+      .mockResolvedValueOnce({
+        data: [
+          buildTemplate(),
+          buildTemplate({
+            id: 'acme_guard_device_v1',
+            name: 'Acme Guard',
+            vendor: 'acme_security',
+            description_cn: '自定义接入设备',
+          }),
+        ],
+      });
+
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
+    await user.click(screen.getByRole('button', { name: /自定义设备/ }));
+    await user.click(screen.getByRole('button', { name: /API 接入/ }));
+    await user.type(screen.getByLabelText('设备产品名'), 'Acme Guard');
+    await user.type(screen.getByLabelText('厂商名称'), 'Acme Security');
+    await user.type(screen.getByLabelText('Base URL'), 'https://device.example.com/api');
+    await user.type(screen.getByLabelText('API 文档链接'), 'https://device.example.com/openapi');
+    await user.click(screen.getByRole('button', { name: /提交给 Rex/ }));
+
+    await user.click(screen.getByRole('button', { name: /刷新设备模板/ }));
+
+    await waitFor(() => expect(mocks.refreshTools).toHaveBeenCalledTimes(1));
+    expect(await screen.findByText('填写配置')).toBeInTheDocument();
+    expect(screen.getByText('acme_guard_device_v1')).toBeInTheDocument();
+  });
+
+  it('redirects syslog flow to workflows page', async () => {
+    const user = userEvent.setup();
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
+    await user.click(screen.getByRole('button', { name: /自定义设备/ }));
+    await user.click(screen.getByRole('button', { name: /Syslog 接入/ }));
+    expect(screen.queryByRole('button', { name: /新建工作流/ })).toBeNull();
+    await user.click(screen.getByRole('button', { name: /前往工作流列表/ }));
+
+    expect(mocks.navigate).toHaveBeenCalledWith('/workflows');
+  });
+});
diff --git a/webui/src/pages/DeviceIntegration/index.tsx b/webui/src/pages/DeviceIntegration/index.tsx
index 64be900af..015eede39 100644
--- a/webui/src/pages/DeviceIntegration/index.tsx
+++ b/webui/src/pages/DeviceIntegration/index.tsx
@@ -10,9 +10,10 @@ import LoadingSpinner from '@/components/common/LoadingSpinner';
 import { useToast } from '@/components/common/Toast';
 import { providerAPI } from '@/api/provider';
 import { deviceAPI, type DeviceIntegration, type DeviceGroup } from '@/api/device';
-import type { APIServiceSummary, APIServiceCredentialField, Tool } from '@/types';
+import type { APIServiceSummary, APIServiceCredentialField, CustomDeviceAccessMode, Tool } from '@/types';
 import { toolAPI } from '@/api/tool';
 import ToolDetailModal from '../Tool/components/ToolDetailModal';
+import CustomDeviceAccessPanel from './CustomDeviceAccessPanel';
 
 // ============================================================================
 // Vendor catalog
@@ -126,14 +127,16 @@ function ActiveCard({ device, vendorKey, selected, onClick }: {
 // Add device wizard panel (step 1: vendor, step 2: product)
 // ============================================================================
 
-function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSelect, onClose }: {
+function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSelect, onSelectCustom, onClose }: {
   templates: APIServiceSummary[];
   instanceCounts: Record<string, number>;
   initialVendor?: DeviceVendor;
   onSelect: (template: APIServiceSummary) => void;
+  onSelectCustom: (mode: CustomDeviceAccessMode) => void;
   onClose: () => void;
 }) {
   const [selectedVendor, setSelectedVendor] = useState<DeviceVendor | null>(initialVendor ?? null);
+  const [showCustomModes, setShowCustomModes] = useState(false);
 
   // Distinct vendor keys from the live template list. Templates whose YAML
   // omits `vendor` are bucketed under the special "(未指定)" key so they
@@ -179,6 +182,8 @@ function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSele
     return templates.filter((t) => (t.vendor || '__unspecified__') === selectedVendor.id);
   }, [templates, selectedVendor]);
 
+  const inModeSelection = showCustomModes && !selectedVendor;
+
   return (
     <div className="fixed inset-y-0 right-0 flex items-start justify-end z-40 pointer-events-none">
       <div
@@ -188,9 +193,12 @@ function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSele
         {/* Header */}
         <div className="flex items-center justify-between px-5 py-4 border-b border-zinc-100 flex-shrink-0">
           <div className="flex items-center gap-2.5">
-            {selectedVendor && (
+            {(selectedVendor || inModeSelection) && (
               <button
-                onClick={() => setSelectedVendor(null)}
+                onClick={() => {
+                  setSelectedVendor(null);
+                  setShowCustomModes(false);
+                }}
                 className="p-1.5 rounded-lg hover:bg-zinc-100 text-zinc-500 hover:text-zinc-700 transition-colors"
               >
                 <ChevronLeft className="w-4 h-4" />
@@ -198,20 +206,20 @@ function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSele
             )}
             <div>
               <h3 className="text-sm font-semibold text-zinc-900">
-                {selectedVendor ? `选择 ${selectedVendor.nameCn} 设备` : '添加设备'}
+                {selectedVendor ? `选择 ${selectedVendor.nameCn} 设备` : inModeSelection ? '选择接入方式' : '添加设备'}
               </h3>
               <div className="flex items-center gap-1.5 mt-0.5">
                 {/* Breadcrumb */}
-                <span className={`text-[10px] font-medium px-1.5 py-0.5 rounded-full ${!selectedVendor ? 'bg-blue-100 text-blue-700' : 'bg-zinc-100 text-zinc-500'}`}>
-                  1 选择厂商
+                <span className={`text-[10px] font-medium px-1.5 py-0.5 rounded-full ${!selectedVendor && !inModeSelection ? 'bg-blue-100 text-blue-700' : 'bg-zinc-100 text-zinc-500'}`}>
+                  1 选择厂商 / 自定义
                 </span>
                 <ChevronRight className="w-2.5 h-2.5 text-zinc-300" />
-                <span className={`text-[10px] font-medium px-1.5 py-0.5 rounded-full ${selectedVendor ? 'bg-blue-100 text-blue-700' : 'bg-zinc-100 text-zinc-400'}`}>
-                  2 选择设备
+                <span className={`text-[10px] font-medium px-1.5 py-0.5 rounded-full ${selectedVendor || inModeSelection ? 'bg-blue-100 text-blue-700' : 'bg-zinc-100 text-zinc-400'}`}>
+                  2 选择设备 / 方式
                 </span>
                 <ChevronRight className="w-2.5 h-2.5 text-zinc-300" />
                 <span className="text-[10px] font-medium px-1.5 py-0.5 rounded-full bg-zinc-100 text-zinc-400">
-                  3 填写配置
+                  3 填写资料 / 配置
                 </span>
               </div>
             </div>
@@ -223,11 +231,27 @@ function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSele
 
         {/* Content */}
         <div className="flex-1 overflow-y-auto p-5">
-          {!selectedVendor ? (
+          {!selectedVendor && !inModeSelection ? (
             /* Step 1: Vendor selection */
             <>
-              <p className="text-xs text-zinc-400 mb-4">选择设备所属厂商，共 {availableVendors.length} 家</p>
+              <p className="text-xs text-zinc-400 mb-4">选择设备所属厂商，或创建自定义设备接入</p>
               <div className="grid grid-cols-2 gap-3">
+                <button
+                  onClick={() => setShowCustomModes(true)}
+                  className="flex flex-col items-center gap-2.5 p-5 rounded-xl border border-dashed border-blue-200 bg-blue-50/40 hover:border-blue-300 hover:bg-blue-50 transition-all duration-150 group"
+                >
+                  <div className="w-12 h-12 rounded-2xl flex items-center justify-center text-lg font-bold bg-blue-100 text-blue-700">
+                    自
+                  </div>
+                  <div className="text-center">
+                    <p className="text-sm font-semibold text-zinc-800">自定义设备</p>
+                    <p className="text-xs text-zinc-400">API / WebCLI / Syslog</p>
+                    <p className="text-[10px] text-blue-600 mt-0.5 font-medium">
+                      创建新的接入方式
+                    </p>
+                  </div>
+                  <ChevronRight className="w-3.5 h-3.5 text-blue-400 transition-colors" />
+                </button>
                 {availableVendors.map((vendor) => {
                   const count = vendorTotalCounts[vendor.id] ?? 0;
                   const productCount = templates.filter(
@@ -256,6 +280,44 @@ function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSele
                 })}
               </div>
             </>
+          ) : inModeSelection ? (
+            <>
+              <p className="text-xs text-zinc-400 mb-4">请选择自定义设备的接入方式</p>
+              <div className="space-y-3">
+                {[
+                  {
+                    key: 'api' as const,
+                    title: 'API 接入',
+                    desc: '设备提供 API 能力时使用。需要提供 API 文档，最终生成可复用的 device 插件。',
+                  },
+                  {
+                    key: 'webcli' as const,
+                    title: 'WebCLI 接入',
+                    desc: '设备没有开放 API 时使用。提供产品 URL 和需要获取的接口，由浏览器抓取后生成 CLI 并集成到 skill。',
+                  },
+                  {
+                    key: 'syslog' as const,
+                    title: 'Syslog 接入',
+                    desc: '目前只能在工作流中使用。设备页会引导你前往工作流集成页面完成监听配置。',
+                  },
+                ].map((mode) => (
+                  <button
+                    key={mode.key}
+                    onClick={() => onSelectCustom(mode.key)}
+                    className="w-full text-left flex items-start gap-3 px-4 py-4 rounded-xl border border-zinc-100 bg-white hover:border-blue-200 hover:bg-blue-50/30 transition-all group"
+                  >
+                    <div className="w-9 h-9 rounded-xl bg-zinc-50 group-hover:bg-blue-50 flex items-center justify-center flex-shrink-0 transition-colors">
+                      <Plug className="w-4 h-4 text-zinc-400 group-hover:text-blue-500 transition-colors" />
+                    </div>
+                    <div className="flex-1 min-w-0">
+                      <p className="text-sm font-medium text-zinc-800 leading-snug">{mode.title}</p>
+                      <p className="text-xs text-zinc-400 mt-1 leading-relaxed">{mode.desc}</p>
+                    </div>
+                    <ChevronRight className="w-4 h-4 text-zinc-300 group-hover:text-blue-400 flex-shrink-0 mt-2 transition-colors" />
+                  </button>
+                ))}
+              </div>
+            </>
           ) : (
             /* Step 2: Product selection */
             <>
@@ -901,6 +963,7 @@ function GroupBanner({ group, onRenamed }: {
 type PanelMode =
   | { kind: 'wizard'; initialVendor?: DeviceVendor }
   | { kind: 'add'; template: APIServiceSummary }
+  | { kind: 'custom'; mode: CustomDeviceAccessMode }
   | { kind: 'edit'; device: DeviceIntegration }
   | null;
 
@@ -915,7 +978,7 @@ export default function DeviceIntegrationPage() {
 
   const currentGroup: DeviceGroup | undefined = groups[0];
 
-  const fetchData = useCallback(async (silent = false) => {
+  const fetchData = useCallback(async (silent = false): Promise<APIServiceSummary[]> => {
     if (!silent) setLoading(true);
     else setRefreshing(true);
     try {
@@ -924,11 +987,14 @@ export default function DeviceIntegrationPage() {
         providerAPI.listApiServices(),
         deviceAPI.listGroups(),
       ]);
+      const nextTemplates = (tplRes.data || []).filter((s) => s.integration_type === 'device');
       setDevices(devRes.data || []);
-      setTemplates((tplRes.data || []).filter((s) => s.integration_type === 'device'));
+      setTemplates(nextTemplates);
       setGroups(grpRes.data || []);
+      return nextTemplates;
     } catch {
       toast.error('加载失败');
+      return [];
     } finally {
       setLoading(false);
       setRefreshing(false);
@@ -1123,7 +1189,18 @@ export default function DeviceIntegrationPage() {
           instanceCounts={instanceCounts}
           initialVendor={panel.initialVendor}
           onSelect={(tpl) => setPanel({ kind: 'add', template: tpl })}
+          onSelectCustom={(mode) => setPanel({ kind: 'custom', mode })}
+          onClose={() => setPanel(null)}
+        />
+      )}
+
+      {panel?.kind === 'custom' && (
+        <CustomDeviceAccessPanel
+          mode={panel.mode}
           onClose={() => setPanel(null)}
+          onBack={() => setPanel({ kind: 'wizard' })}
+          onRefreshTemplates={() => fetchData(true)}
+          onTemplateMatched={(template) => setPanel({ kind: 'add', template })}
         />
       )}
 
diff --git a/webui/src/types/index.ts b/webui/src/types/index.ts
index 09efff15b..51ac892bc 100644
--- a/webui/src/types/index.ts
+++ b/webui/src/types/index.ts
@@ -262,6 +262,29 @@ export interface APIServiceMetadata {
   verify_ssl?: boolean;
 }
 
+export type CustomDeviceAccessMode = 'api' | 'webcli' | 'syslog';
+
+export interface CustomDeviceBaseDraft {
+  accessMode: CustomDeviceAccessMode;
+  deviceName: string;
+  vendorName: string;
+  version: string;
+}
+
+export interface CustomDeviceApiDraft extends CustomDeviceBaseDraft {
+  accessMode: 'api';
+  baseUrl: string;
+  docsUrl: string;
+  capabilities: string;
+}
+
+export interface CustomDeviceWebCliDraft extends CustomDeviceBaseDraft {
+  accessMode: 'webcli';
+  productUrl: string;
+  targetInterfaces: string;
+  authHint: string;
+}
+
 export interface MCPServerConfig {
   type: 'stdio' | 'sse';
   url?: string;

From 38d8239c7e5616465fb3db84f8bfb45b4a994657 Mon Sep 17 00:00:00 2001
From: xiami762 <>
Date: Wed, 27 May 2026 18:00:47 +0800
Subject: [PATCH 2/4] feat(webui,web2cli): align WebCLI custom device with
 device plugin flow

Require skill integration first, then optional device plugin packaging for
security devices. Add cli-in-device reference, tighten session prompts and
provider description guidance, and update custom device access UI/tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .flocks/plugins/skills/web2cli/SKILL.md       |  21 +-
 .../web2cli/references/cli-in-device.md       | 254 ++++++++++++++++++
 .../CustomDeviceAccessPanel.tsx               |  81 ++----
 .../DeviceIntegration/customDevice.test.ts    |  13 +-
 .../pages/DeviceIntegration/customDevice.ts   |  66 +++--
 .../pages/DeviceIntegration/index.test.tsx    |  64 +++--
 webui/src/pages/DeviceIntegration/index.tsx   |   4 +-
 7 files changed, 403 insertions(+), 100 deletions(-)
 create mode 100644 .flocks/plugins/skills/web2cli/references/cli-in-device.md

diff --git a/.flocks/plugins/skills/web2cli/SKILL.md b/.flocks/plugins/skills/web2cli/SKILL.md
index cccdbb34c..2dd74535c 100644
--- a/.flocks/plugins/skills/web2cli/SKILL.md
+++ b/.flocks/plugins/skills/web2cli/SKILL.md
@@ -325,9 +325,25 @@ uv run python .flocks/plugins/skills/web2cli/scripts/generate-cli.py \
 
 推荐先查看 `"$CAPTURE_ROOT/${CAPTURE_NAME}_verify.json"`，再用生成的 CLI 以默认参数执行一次，确认固定输出列与认证状态都正确。
 
-### 11. CLI 工具集成到skill
+### 11. 将 WebCLI 能力沉淀为最终产物
 
-将 CLI 按 `references/cli-in-skill.md` 集成为 skill；
+分为基础层和可选增强层：
+
+#### 基础要求：必须集成到 skill
+
+- 所有 `web2cli` 结果都必须先按 `references/cli-in-skill.md` 集成为可长期维护的 skill / CLI 资产
+- 这是必选步骤，因为认证失效、浏览器恢复、重新抓包、CLI 参数说明和日常排障都依赖 skill 文档入口
+- `references/browser-workflow.md` 必须记录浏览器连接检查、登录步骤、state 保存位置和认证恢复流程
+
+#### CLI 放置原则
+
+- 主 CLI 的落点是二选一：要么放在 skill 的 `scripts/`，要么放在 `tools/device/<plugin_id>/` 下
+- 通用网站、查询等场景：优先放在 skill 的 `scripts/`
+- 安全设备接入：按 `references/cli-in-device.md` 将能力整理成 `tools/device/<plugin_id>/` 下的 `_provider.yaml`、工具 YAML 和 handler
+- 不要同时维护两份独立演进的主 CLI，避免能力漂移和认证逻辑分叉
+- 无论主 CLI 放在哪，skill 集成都始终是必选
+
+不要只停留在一次性 CLI 或临时抓包结果；最终都要沉淀成可长期维护的资产。
 
 ### 12. summary并关闭浏览器 tab
 
@@ -384,4 +400,5 @@ else:
 - 登录状态失效：重新登录后再次执行保存状态命令。
 
 ## Reference
+- references/cli-in-device.md 在 skill 集成完成后，将 WebCLI 能力进一步封装为 device 插件
 - references/cli-in-skill.md 将生成的 CLI 集成到 skill 中使用
diff --git a/.flocks/plugins/skills/web2cli/references/cli-in-device.md b/.flocks/plugins/skills/web2cli/references/cli-in-device.md
new file mode 100644
index 000000000..30747c6f0
--- /dev/null
+++ b/.flocks/plugins/skills/web2cli/references/cli-in-device.md
@@ -0,0 +1,254 @@
+# 生成后的 WebCLI 如何接入 Device 插件
+
+> 本文说明：`web2cli` 已经抓到页面请求、并整理出可复用调用逻辑后，怎样把它沉淀成可在设备页识别、配置和调用的 device 插件。
+
+## 结论
+
+`cli-in-device.md` 不是 `cli-in-skill.md` 的替代物，而是安全设备场景下的进一步封装：
+
+- 所有 `web2cli` 结果都必须先完成 skill 集成
+- 如果目标是安全设备接入，再继续按本文档额外生成 device 插件
+- 最终交付关系是：`skill` 必选，`device 插件` 为安全设备场景下的额外交付
+
+## 何时使用
+
+在以下场景调用本文档：
+
+- 当前任务明确来自“设备接入”页面，目标是把某个安全设备或安全产品接入到设备管理体系
+- 最终产物需要出现在设备页，并允许用户填写实例配置、刷新模板、按 `device_id` 调用
+- 当前 WebCLI 抓到的能力属于安全设备能力，而不是单纯给 skill 复用的站点操作脚本
+
+不优先使用本文档的场景：
+
+- 只是想保留一个可复用 CLI 供 agent 在 skill 中调用
+- 目标不是设备接入，而是某个通用网站的操作自动化、查询脚本或内部工具
+- 暂时只需要沉淀浏览器经验、CLI 参数和认证恢复流程，不需要设备页识别
+
+如果当前任务来自“设备接入”页面，并且目标是安全设备接入，WebCLI 在完成 skill 集成后，还应当额外生成标准 device 插件：
+
+```text
+$HOME/.flocks/plugins/tools/device/<plugin_id>/
+├── _provider.yaml
+├── <domain>.yaml
+├── <name>.handler.py
+├── <name>_cli.py        # 可选，仅用于调试/回归
+└── _test.yaml           # 可选，最小验证样例
+```
+
+其中：
+
+- `_provider.yaml`：决定设备页是否能识别该模板，以及用户创建实例时需要填写哪些字段
+- `<domain>.yaml`：定义可调用工具、参数和 action
+- `<name>.handler.py`：设备运行时入口，负责读取配置、认证、发请求、清洗结果
+- `<name>_cli.py`：只作为调试入口保留，不作为设备运行时主路径
+
+认证默认规则：
+
+- 自定义 CLI / WebCLI 默认认证方式为 `auth-state`
+- 默认认证状态文件：`~/.flocks/browser/<name>/auth-state.json`
+- 优先使用 `auth_state_path` 指向 `~/.flocks/browser/<name>/auth-state.json`
+- 只有在目标站点确实还依赖额外字段时，才补充 `auth_state_json`、`cookie`、`csrf_token`、`access_token`
+- 不要把 `cookie` 或 `token` 设计成和 `auth-state` 并列的多个默认入口
+
+## 命名约定
+
+- 插件目录：`$HOME/.flocks/plugins/tools/device/<plugin_id>/`
+- `plugin_id`：推荐使用稳定产品名加版本，例如 `<name>_v1_0_0`
+- `service_id`：推荐使用稳定能力标识，例如 `<name>_device`
+- handler 文件：`<name>.handler.py`
+- 可选 CLI 文件：`<name>_cli.py`
+
+约定说明：
+
+- `<name>` 用产品或系统的稳定标识，不用一次性任务名
+- 目录名可以带版本；`service_id` 要尽量稳定，避免和临时抓包任务绑定
+- Python 文件名统一用 `_`
+
+## 最小 `_provider.yaml`
+
+至少包含以下字段：
+
+```yaml
+name: Acme Portal
+vendor: acme_security
+service_id: acme_portal_device
+version: "1.0.0"
+integration_type: device
+description: >
+  Acme Portal WebCLI-backed device integration for alert listing and asset
+  detail queries. Configure Base URL and the required login state fields
+  separately in the credentials form.
+description_cn: >
+  Acme Portal 的 WebCLI 设备接入模板，支持告警列表和资产详情查询。
+  请在设备配置中分别填写 Base URL 与所需登录态字段。
+credential_fields:
+  - key: base_url
+    label: Base URL
+    storage: config
+    config_key: base_url
+    input_type: url
+    required: true
+  - key: auth_state_path
+    label: Auth State Path
+    storage: config
+    config_key: auth_state_path
+    input_type: text
+    default: "~/.flocks/browser/acme-portal/auth-state.json"
+  - key: cookie
+    label: Cookie
+    storage: secret
+    config_key: cookie
+    secret_id: acme_portal_cookie
+    input_type: password
+  - key: csrf_token
+    label: CSRF Token
+    storage: secret
+    config_key: csrf_token
+    secret_id: acme_portal_csrf_token
+    input_type: password
+defaults:
+  timeout: 30
+  category: custom
+notes: |
+  WebCLI 设备建议优先复用稳定隐藏接口，不建议把浏览器自动化作为默认运行时。
+  若返回 401/403、跳转登录页或 CSRF 失效，应先按认证失效处理。
+```
+
+注意：
+
+- 必须包含 `integration_type: device`
+- `description` 用英文，`description_cn` 用中文
+- 只把运行时真正需要用户填写的字段放进 `credential_fields`
+- 不要把真实 cookie、token、密码、auth state JSON 写进插件文件
+- 默认先放 `auth_state_path`，并指向 `~/.flocks/browser/<name>/auth-state.json`；`cookie`、`csrf_token`、`access_token` 只有在实际站点需要时再补
+
+## 最小工具 YAML
+
+MVP 阶段推荐一个分组工具 + 多个 action：
+
+```yaml
+name: acme_portal_ops
+description: >
+  Acme Portal grouped device tool. Use the action parameter to query alerts,
+  assets, and other WebCLI-backed operations.
+description_cn: >
+  Acme Portal 分组设备工具。通过 action 参数调用告警、资产和其他 WebCLI 能力。
+category: custom
+enabled: true
+requires_confirmation: false
+provider: acme_portal_device
+inputSchema:
+  type: object
+  properties:
+    action:
+      type: string
+      enum: [list_alerts, get_asset_detail]
+      description: 统一业务动作名，不要暴露内部实现来源。
+    alert_id:
+      type: string
+      description: 查询资产详情时可选使用的关联标识。
+  required: [action]
+handler:
+  type: script
+  script_file: acme_portal.handler.py
+  function: handle
+```
+
+规则：
+
+- `provider` 必须与 `_provider.yaml.service_id` 一致
+- 高风险写操作必须设置 `requires_confirmation: true`
+- 对外 action 用统一业务语义，不要命名成 `webcli_get_alerts`、`api_get_alerts`
+
+## 最小 handler 结构
+
+MVP 阶段优先单文件 handler，不强制拆 client 模块：
+
+```python
+from __future__ import annotations
+
+from typing import Any
+
+from flocks.config.config_writer import ConfigWriter
+from flocks.tool.registry import ToolContext, ToolResult
+
+SERVICE_ID = "acme_portal_device"
+
+
+def _service_config() -> dict[str, Any]:
+    raw = ConfigWriter.get_api_service_raw(SERVICE_ID)
+    return raw if isinstance(raw, dict) else {}
+
+
+async def handle(ctx: ToolContext, action: str, **params: Any) -> ToolResult:
+    cfg = _service_config()
+    if action == "list_alerts":
+        return ToolResult(success=True, output={"items": [], "source": "webcli_api"})
+    if action == "get_asset_detail":
+        return ToolResult(success=True, output={"item": None, "source": "webcli_api"})
+    return ToolResult(success=False, error=f"Unsupported action: {action}")
+```
+
+要求：
+
+- 通过 `ConfigWriter.get_api_service_raw(SERVICE_ID)` 读取当前设备实例配置
+- handler 内部负责认证头构造、分页、超时、重试和响应归一化
+- CLI 可选保留，但不要让设备运行时通过 subprocess 调 CLI
+
+## 组合 API / WebCLI / 处理逻辑
+
+同一设备可以混合多种能力来源，但对外仍然是统一 action：
+
+- `api`：正式 API，可直接调用
+- `webcli_api`：WebCLI 抓到的隐藏接口
+- `process`：本地字段归一化、过滤、聚合、补全
+- `composed`：先调一种来源，再补另一种来源，最后统一输出
+
+推荐选择顺序：
+
+1. 正式 API 稳定可用时，优先正式 API
+2. 正式 API 缺能力但 WebCLI 接口稳定时，用 `webcli_api`
+3. 需要字段清洗、补全、排序、聚合时，在 handler 内增加 `process`
+4. 需要多个来源补齐同一业务结果时，用 `composed`
+5. 必须验证码、强动态页面或人工交互时，只记录为 browser fallback，不放进默认设备运行时
+
+示例 action 映射：
+
+```yaml
+list_alerts: webcli_api
+get_asset_detail: composed
+list_users: api
+normalize_alert: process
+```
+
+这里的映射可以写进 handler 常量、注释、`notes` 或单独的设计文档，但不要把“来源类型”直接暴露给最终用户。
+
+## 认证失败处理
+
+出现以下情况时，优先按认证失效处理：
+
+- 返回 `401` 或 `403`
+- 返回内容出现 `Unauthorized`、`login`、未登录、无权限
+- Cookie / CSRF / access token 明显过期
+- `auth_state_path` 已存在，但接口仍跳转登录页
+
+处理原则：
+
+1. 不要无限重试
+2. 提示用户重新登录并更新设备配置中的认证字段
+3. 如果保留了 CLI，可用 CLI 做一次最小验证
+4. 验证通过后，再让用户回到设备页点击“刷新设备模板”
+
+## `_test.yaml` 建议
+
+如果该 WebCLI 设备已经有最小可验证动作，建议补一个 `_test.yaml`，至少覆盖：
+
+- 一个低风险读操作
+- 最小必填参数
+- 成功时的关键字段断言
+
+这样后续更新 handler 或认证逻辑时更容易回归验证。
+
+## 一句话原则
+
+`web2cli` 生成的 CLI 是中间产物；只有在“安全设备接入”场景下，才把它整理成标准 device 插件，让设备页能识别、配置并调用。
diff --git a/webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx b/webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx
index c20b8e616..1b053844a 100644
--- a/webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx
+++ b/webui/src/pages/DeviceIntegration/CustomDeviceAccessPanel.tsx
@@ -1,12 +1,10 @@
 import { useEffect, useMemo, useState, type InputHTMLAttributes, type TextareaHTMLAttributes } from 'react';
-import { ChevronLeft, Loader2, MessageSquare, RefreshCw, Route, Workflow, X } from 'lucide-react';
+import { ChevronLeft, Loader2, MessageSquare, Route, Workflow, X } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
 import { useToast } from '@/components/common/Toast';
 import SessionChat from '@/components/common/SessionChat';
 import { useSessionChat } from '@/hooks/useSessionChat';
-import { toolAPI } from '@/api/tool';
 import type {
-  APIServiceSummary,
   CustomDeviceAccessMode,
   CustomDeviceApiDraft,
   CustomDeviceWebCliDraft,
@@ -15,7 +13,6 @@ import {
   buildCustomDevicePrompt,
   buildCustomDeviceSessionContext,
   buildCustomDeviceWelcomeMessage,
-  findTemplateForCustomDevice,
 } from './customDevice';
 
 type PanelView = 'details' | 'rex' | 'guide';
@@ -27,7 +24,7 @@ const EMPTY_API_DRAFT: CustomDeviceApiDraft = {
   version: '',
   baseUrl: '',
   docsUrl: '',
-  capabilities: '全部 API',
+  capabilities: '',
 };
 
 const EMPTY_WEBCLI_DRAFT: CustomDeviceWebCliDraft = {
@@ -89,14 +86,10 @@ export default function CustomDeviceAccessPanel({
   mode,
   onClose,
   onBack,
-  onRefreshTemplates,
-  onTemplateMatched,
 }: {
   mode: CustomDeviceAccessMode;
   onClose: () => void;
   onBack: () => void;
-  onRefreshTemplates: () => Promise<APIServiceSummary[]>;
-  onTemplateMatched: (template: APIServiceSummary) => void;
 }) {
   const navigate = useNavigate();
   const toast = useToast();
@@ -105,9 +98,9 @@ export default function CustomDeviceAccessPanel({
   const [apiDraft, setApiDraft] = useState<CustomDeviceApiDraft>(EMPTY_API_DRAFT);
   const [webcliDraft, setWebcliDraft] = useState<CustomDeviceWebCliDraft>(EMPTY_WEBCLI_DRAFT);
   const [submitting, setSubmitting] = useState(false);
-  const [refreshing, setRefreshing] = useState(false);
 
   const draft = mode === 'api' ? apiDraft : mode === 'webcli' ? webcliDraft : null;
+  const isRexView = !isSyslog && view === 'rex';
   const title = useMemo(() => {
     if (mode === 'api') return '自定义设备 API 接入';
     if (mode === 'webcli') return '自定义设备 WebCLI 接入';
@@ -142,23 +135,10 @@ export default function CustomDeviceAccessPanel({
     }
   };
 
-  const handleRefreshTemplates = async () => {
-    if (!draft) return;
-    setRefreshing(true);
-    try {
-      await toolAPI.refresh();
-      const matched = findTemplateForCustomDevice(await onRefreshTemplates(), draft.deviceName);
-      if (matched) {
-        toast.success('已找到新的设备模板，继续填写接入配置');
-        onTemplateMatched(matched);
-        return;
-      }
-      toast.info('已刷新设备模板，暂未找到同名设备，请继续在 Rex 中完善插件');
-    } catch {
-      toast.error('刷新设备模板失败');
-    } finally {
-      setRefreshing(false);
-    }
+  const handleOpenSession = () => {
+    if (!sessionId) return;
+    const params = new URLSearchParams({ session: sessionId });
+    navigate(`/sessions?${params.toString()}`);
   };
 
   const renderApiForm = () => (
@@ -321,7 +301,7 @@ export default function CustomDeviceAccessPanel({
               <h3 className="text-sm font-semibold text-zinc-900 truncate">{title}</h3>
               <p className="text-xs text-zinc-400 mt-0.5">
                 {mode === 'api' && '提供 API 文档，生成可复用的 device 插件'}
-                {mode === 'webcli' && '提供产品 URL 和目标接口，生成 CLI 并集成到 skill'}
+                {mode === 'webcli' && '提供产品 URL 和目标接口，生成可在设备页使用的 WebCLI device 插件'}
                 {mode === 'syslog' && 'Syslog 仅支持在工作流集成页面配置'}
               </p>
             </div>
@@ -331,7 +311,7 @@ export default function CustomDeviceAccessPanel({
           </button>
         </div>
 
-        <div className="flex-1 min-h-0 overflow-y-auto px-5 py-4">
+        <div className={isRexView ? 'flex-1 min-h-0 overflow-hidden' : 'flex-1 min-h-0 overflow-y-auto px-5 py-4'}>
           {isSyslog ? (
             <div className="space-y-4">
               <div className="rounded-xl border border-emerald-100 bg-emerald-50 px-4 py-3">
@@ -358,25 +338,25 @@ export default function CustomDeviceAccessPanel({
                 <p className="text-xs text-zinc-500 mt-1.5 leading-relaxed">
                   提交后会直接进入 Rex 对话。
                   {mode === 'api'
-                    ? '你可以继续补充 API 文档链接、上传文档文件或说明接口细节。插件生成完成后，再点击底部“刷新设备模板”继续接入。'
-                    : '你可以继续补充页面操作、抓包目标和认证方式。最终结果应当是 CLI 集成到 skill 中。'}
+                    ? '你可以继续补充 API 文档链接、上传文档文件或说明接口细节。插件生成完成后，可返回设备页继续后续配置。'
+                    : '你可以继续补充页面操作、抓包目标和认证方式。最终结果应当是可在设备页识别的 WebCLI device 插件；如果需要，也可以额外保留 CLI 作为调试入口。'}
                 </p>
               </div>
               {mode === 'api' ? renderApiForm() : renderWebCliForm()}
             </div>
           ) : (
-            <div className="h-full min-h-[420px] -mx-5 -my-4">
-              <div className="px-5 py-3 border-b border-zinc-100 bg-zinc-50">
+            <div className="flex h-full min-h-0 flex-col">
+              <div className="flex-shrink-0 px-5 py-3 border-b border-zinc-100 bg-zinc-50">
                 <p className="text-xs text-zinc-500 leading-relaxed">
                   {mode === 'api'
-                    ? '与 Rex 协作生成插件后，回到此处点击“刷新设备模板”。如果已生成同名 device 插件，页面会自动跳转到设备配置面板。若 API 文档不便粘贴，可直接在当前对话中上传。'
-                    : '与 Rex 协作完成后，请确认 CLI 已生成并集成到 skill 中。这里不会生成设备模板，也不需要刷新设备模板。'}
+                    ? '与 Rex 协作生成插件后，可返回设备页查看是否已出现对应 device 插件。若 API 文档不便粘贴，可直接在当前对话中上传。'
+                    : '与 Rex 协作完成后，请确认 WebCLI device 插件已生成。完成后可返回设备页继续查看和配置；CLI 仅作为可选调试入口保留。'}
                 </p>
               </div>
               <SessionChat
                 sessionId={sessionId}
                 live={!!sessionId}
-                className="h-[calc(100%-61px)]"
+                className="flex-1 min-h-0"
                 placeholder="继续补充接口说明、认证细节或调试信息"
                 emptyText="Rex 准备中..."
                 onCreateAndSend={!sessionId ? (text, imageParts) => createAndSend({ text, imageParts }) : undefined}
@@ -385,7 +365,7 @@ export default function CustomDeviceAccessPanel({
           )}
         </div>
 
-        <div className="border-t border-zinc-100 px-5 py-4 flex-shrink-0">
+        <div className="border-t border-zinc-100 px-4 py-2.5 flex-shrink-0">
           {isSyslog ? (
             <div className="flex items-center justify-between gap-2">
               <button
@@ -405,40 +385,33 @@ export default function CustomDeviceAccessPanel({
               </button>
             </div>
           ) : (
-            <div className="flex items-center justify-between gap-2">
-              <div className="flex items-center gap-2">
+            <div className="flex items-center justify-between gap-1.5">
+              <div className="flex items-center gap-1.5">
                 <button
                   onClick={view === 'details' ? onBack : () => setView('details')}
-                  className="px-4 py-2 text-sm rounded-lg border border-zinc-200 text-zinc-600 hover:bg-zinc-50 transition-colors"
+                  className="px-3.5 py-2 text-sm rounded-lg border border-zinc-200 text-zinc-600 hover:bg-zinc-50 transition-colors"
                 >
                   {view === 'details' ? '返回选择方式' : '返回资料填写'}
                 </button>
-                {mode === 'api' && view === 'rex' && (
+                {view === 'rex' && sessionId && (
                   <button
-                    onClick={() => void handleRefreshTemplates()}
-                    disabled={refreshing}
-                    className="inline-flex items-center gap-1.5 px-4 py-2 text-sm rounded-lg border border-zinc-200 text-zinc-600 hover:bg-zinc-50 disabled:opacity-50 transition-colors"
+                    onClick={handleOpenSession}
+                    className="inline-flex items-center gap-1.5 px-3.5 py-2 text-sm rounded-lg border border-zinc-200 text-zinc-600 hover:bg-zinc-50 transition-colors"
                   >
-                    {refreshing ? <Loader2 className="w-3.5 h-3.5 animate-spin" /> : <RefreshCw className="w-3.5 h-3.5" />}
-                    刷新设备模板
+                    <MessageSquare className="w-3.5 h-3.5" />
+                    前往会话列表查看
                   </button>
                 )}
               </div>
-              {view === 'details' ? (
+              {view === 'details' && (
                 <button
                   onClick={() => void handleSubmitToRex()}
                   disabled={submitting}
-                  className="inline-flex items-center gap-1.5 px-4 py-2 text-sm rounded-lg bg-red-600 text-white hover:bg-red-700 disabled:opacity-50 transition-colors"
+                  className="inline-flex items-center gap-1.5 px-3.5 py-2 text-sm rounded-lg bg-red-600 text-white hover:bg-red-700 disabled:opacity-50 transition-colors"
                 >
                   {submitting ? <Loader2 className="w-3.5 h-3.5 animate-spin" /> : <MessageSquare className="w-3.5 h-3.5" />}
                   提交给 Rex
                 </button>
-              ) : (
-                <span className="text-xs text-zinc-400">
-                  {mode === 'api'
-                    ? '已进入 Rex 对话，可继续补充文档与需求'
-                    : '已进入 Rex 对话，可继续补充抓包目标并完成 CLI skill 集成'}
-                </span>
               )}
             </div>
           )}
diff --git a/webui/src/pages/DeviceIntegration/customDevice.test.ts b/webui/src/pages/DeviceIntegration/customDevice.test.ts
index 6b464206a..4a732adca 100644
--- a/webui/src/pages/DeviceIntegration/customDevice.test.ts
+++ b/webui/src/pages/DeviceIntegration/customDevice.test.ts
@@ -27,10 +27,13 @@ describe('customDevice helpers', () => {
     expect(prompt).toContain('~/.flocks/plugins/tools/device/<plugin_id>/');
     expect(prompt).toContain('`name` 必须精确使用产品名：`Acme Guard`');
     expect(prompt).toContain('`service_id` 建议使用：`acme_guard_device`');
+    expect(prompt).toContain('`description` / `description_cn` 会直接展示在设备接入页、概览页和 Hub 列表');
+    expect(prompt).toContain('更长的兼容性、版本差异、使用限制和调试说明优先写进 `notes`');
     expect(prompt).toContain('tool-builder skill');
+    expect(prompt).toContain('返回设备页查看是否已经出现对应 device 插件');
   });
 
-  it('builds webcli prompt with browser capture guidance', () => {
+  it('builds webcli prompt with device plugin constraints', () => {
     const draft: CustomDeviceWebCliDraft = {
       accessMode: 'webcli',
       deviceName: 'Acme Portal',
@@ -48,8 +51,12 @@ describe('customDevice helpers', () => {
     expect(prompt).toContain('需要获取的接口/页面行为：告警列表和资产详情');
     expect(prompt).toContain('browser-use / web2cli');
     expect(prompt).toContain('web2cli skill');
-    expect(prompt).toContain('CLI');
-    expect(prompt).toContain('skill');
+    expect(prompt).toContain('integration_type: device');
+    expect(prompt).toContain('~/.flocks/plugins/tools/device/<plugin_id>/');
+    expect(prompt).toContain('`service_id` 建议使用：`acme_portal_device`');
+    expect(prompt).toContain('`auth_state_path`');
+    expect(prompt).toContain('`api`、`webcli_api`、`process`、`composed`');
+    expect(prompt).toContain('返回设备页查看是否已经出现对应 WebCLI device 插件');
   });
 
   it('sanitizes vendor key and service id', () => {
diff --git a/webui/src/pages/DeviceIntegration/customDevice.ts b/webui/src/pages/DeviceIntegration/customDevice.ts
index de7ea4557..f1731c492 100644
--- a/webui/src/pages/DeviceIntegration/customDevice.ts
+++ b/webui/src/pages/DeviceIntegration/customDevice.ts
@@ -23,11 +23,10 @@ export function buildCustomDeviceServiceId(deviceName: string): string {
   return base.endsWith('_device') ? base : `${base}_device`;
 }
 
-function buildApiDeviceRequirements(deviceName: string, vendorName: string): string {
+function buildBaseDevicePluginRequirements(deviceName: string, vendorName: string): string[] {
   const vendorKey = buildCustomDeviceVendorKey(vendorName);
   const serviceId = buildCustomDeviceServiceId(deviceName);
   return [
-    '请严格遵循当前项目的 device 插件契约，不要生成普通 api 工具后就停止。',
     '最终产物必须落到 `~/.flocks/plugins/tools/device/<plugin_id>/` 目录。',
     '必须生成 `_provider.yaml`，并满足以下要求：',
     `- \`name\` 必须精确使用产品名：\`${deviceName}\``,
@@ -35,33 +34,59 @@ function buildApiDeviceRequirements(deviceName: string, vendorName: string): str
     `- \`service_id\` 建议使用：\`${serviceId}\``,
     '- 必须包含 `integration_type: device`',
     '- 必须声明 `version`、`credential_fields`、`description`、`description_cn`',
+    '- `description` / `description_cn` 会直接展示在设备接入页、概览页和 Hub 列表，不能留空，也不能写成“自定义设备插件”这类泛化占位文案',
+    '- `description` 用英文、`description_cn` 用中文；都要明确说明：这是哪个产品/版本、提供什么能力、主要认证方式，以及用户需要填写哪些关键连接信息',
+    '- 首段先写 1 到 3 句高密度摘要；更长的兼容性、版本差异、使用限制和调试说明优先写进 `notes`',
+    '- 如果这是某个产品的特殊版本或兼容变体，必须在描述中写清楚差异点，避免与同系列标准插件混淆',
     '- `credential_fields` 只定义运行时需要用户填写的字段，不能把真实凭据写进插件文件',
     '- 至少生成一个可被设备页识别的 device YAML/script 工具，必要时补充 `.handler.py`',
     '- 新建工具默认启用，并确保工具刷新后能出现在设备接入页',
-    '完成后请提醒用户在设备页点击“刷新设备模板”。',
+  ];
+}
+
+function buildBaseDeviceSessionContext(): string[] {
+  return [
+    '你是 Flocks 的自定义设备接入助手。',
+    '你必须先阅读并参考项目中现有 device 插件结构，例如 `.flocks/plugins/tools/device/*/_provider.yaml` 与对应 YAML/script handler。',
+    '请重点参考现有 `_provider.yaml` 中 `description`、`description_cn`、`notes` 的写法，因为这些内容会直接影响设备页展示效果。',
+    '不要把用户在表单里填写的账号、密码、Token、Cookie 直接写入插件；这些都应该通过 `credential_fields` 暴露为设备实例配置项。',
+  ];
+}
+
+function buildApiDeviceRequirements(deviceName: string, vendorName: string): string {
+  return [
+    '请严格遵循当前项目的 device 插件契约，不要生成普通 api 工具后就停止。',
+    ...buildBaseDevicePluginRequirements(deviceName, vendorName),
+    '完成后请提醒用户返回设备页查看是否已经出现对应 device 插件，并继续后续配置。',
   ].join('\n');
 }
 
-function buildWebCliSkillRequirements(deviceName: string, vendorName: string): string {
-  const vendorKey = buildCustomDeviceVendorKey(vendorName);
+function buildWebCliDeviceRequirements(deviceName: string, vendorName: string): string {
   return [
     '请严格遵循当前项目的 web2cli skill 流程，不要只停留在临时抓包或一次性脚本。',
-    '最终结果应当生成可复用 CLI，并将 CLI 集成到 skill 中供后续调用。',
-    '请优先遵循 `web2cli` skill 中的捕获、导出、生成 CLI、沉淀到 skill 的完整流程。',
-    `建议使用厂商标识：\`${vendorKey}\`，产品名：\`${deviceName}\`，保证 skill/CLI 命名清晰可追踪。`,
-    '不要把用户在表单里填写的账号、密码、Token、Cookie 直接硬编码到 CLI 或 skill 中。',
-    '最终产物应包含清晰的 skill 使用入口、CLI 调用说明，以及必要的认证状态保存方式。',
-    '不要把结果伪装成 device 插件，也不要要求用户回到设备页刷新模板。',
+    'WebCLI 接入必须先按 `references/cli-in-skill.md` 沉淀到 skill 中；这是必选步骤，用于承载 CLI 使用说明、浏览器恢复和认证失效处理。',
+    '如果目标是安全设备接入，还必须在 skill 集成完成后，再额外生成可在设备页识别、配置和调用的标准 device 插件。',
+    '请优先遵循 `web2cli` skill 中的捕获、导出、生成 CLI 的完整流程，再把沉淀出的能力包装为长期资产。',
+    ...buildBaseDevicePluginRequirements(deviceName, vendorName),
+    '- 自定义 CLI / WebCLI 默认认证方式为 `auth-state`；默认保存位置为 `~/.flocks/browser/<name>/auth-state.json`，优先使用 `auth_state_path`',
+    '- `auth_state_json`、`cookie`、`csrf_token`、`access_token` 仅作为补充或兜底字段，不要和 `auth-state` 并列设计成多个默认认证入口',
+    '- skill 集成始终必选；CLI 主脚本默认放在 skill 的 `scripts/` 中，如设备运行时确有需要，可额外在 device 插件目录下保留适配层',
+    '- MVP 阶段优先生成单文件 handler；CLI 可以作为调试入口保留，但不应作为设备运行时主路径',
+    '运行时能力设计要求：',
+    '- 对外暴露统一业务 action，例如 `list_alerts`、`get_asset_detail`，不要把内部实现暴露成“API 版 / WebCLI 版”动作名',
+    '- handler 内部允许按 `api`、`webcli_api`、`process`、`composed` 四类来源编排，但对外返回统一结构',
+    '- 如果正式 API 稳定可用，优先正式 API；正式 API 缺能力时，再使用 WebCLI 抓到的隐藏接口',
+    '- 只有必须页面交互、验证码或强动态状态时，才记录为 browser fallback，不要作为默认设备运行时主路径',
+    '- 高风险写操作必须设置 `requires_confirmation: true`',
+    '完成后请提醒用户返回设备页查看是否已经出现对应 WebCLI device 插件，并继续后续配置。',
   ].join('\n');
 }
 
 export function buildCustomDeviceSessionContext(mode: CustomDeviceAccessMode): string {
   if (mode === 'api') {
     return [
-      '你是 Flocks 的自定义设备接入助手。',
+      ...buildBaseDeviceSessionContext(),
       '目标是把用户描述的 API 能力接入为可在“设备接入”页面出现的 device 插件，而不是普通 API 服务。',
-      '你必须先阅读并参考项目中现有 device 插件结构，例如 `.flocks/plugins/tools/device/*/_provider.yaml` 与对应 YAML/script handler。',
-      '不要把用户在表单里填写的账号、密码、Token、Cookie 直接写入插件；这些都应该通过 `credential_fields` 暴露为设备实例配置项。',
       '本次接入方式是 API 接入。',
       '你必须先读取并使用 tool-builder skill，再开始生成插件。',
       '用户会提供 API 文档链接或后续上传文档文件，请根据文档盘点接口后生成 device 插件。',
@@ -71,11 +96,12 @@ export function buildCustomDeviceSessionContext(mode: CustomDeviceAccessMode): s
   }
   if (mode === 'webcli') {
     return [
-      '你是 Flocks 的自定义设备接入助手。',
+      ...buildBaseDeviceSessionContext(),
       '本次接入方式是 WebCLI 接入。',
       '你必须先读取并使用 web2cli skill，再开始捕获与转换流程。',
-      '用户会提供产品 URL 和需要获取的接口/页面行为。你可以使用 web2cli 思路抓取接口，但最终结果应当是 CLI 集成到 skill 中。',
-      '不要只留下临时 CLI 或抓包产物；最终结果必须是可复用 CLI + skill 集成入口。',
+      '用户会提供产品 URL 和需要获取的接口/页面行为。你可以使用 web2cli 思路抓取接口，但必须先完成 skill 集成；如果目标是安全设备接入，再额外生成 device 插件。',
+      '自定义 CLI 默认复用 `auth-state`；只有在站点确实需要补充 header、cookie 或 token 时，才额外暴露对应字段。',
+      'MVP 阶段优先生成单文件 script handler；可复用 CLI 只作为调试/回归入口，不作为设备运行时主路径。',
     ].join('\n');
   }
   return [
@@ -88,7 +114,7 @@ export function buildCustomDeviceWelcomeMessage(mode: CustomDeviceAccessMode): s
     return '请补充 API 文档链接或直接上传文档文件，并说明目标能力，我会用 tool-builder skill 帮你生成可在设备页使用的 device 插件。';
   }
   if (mode === 'webcli') {
-    return '请补充产品 URL、目标接口和认证提示，我会用 web2cli skill 帮你生成 CLI 并集成到 skill 中。';
+    return '请补充产品 URL、目标接口和认证提示，我会用 web2cli skill 先生成并集成 CLI/skill 资产；如果是安全设备接入，再额外生成 device 插件。默认使用 auth-state。';
   }
   return 'Syslog 方式不在这里创建插件，请前往工作流集成页面配置。';
 }
@@ -120,7 +146,7 @@ export function buildCustomDevicePrompt(
 
   return [
     ...header,
-    buildWebCliSkillRequirements(draft.deviceName, draft.vendorName),
+    buildWebCliDeviceRequirements(draft.deviceName, draft.vendorName),
     '',
     '接入方式：WebCLI',
     `产品 URL：${draft.productUrl}`,
@@ -128,7 +154,7 @@ export function buildCustomDevicePrompt(
     draft.authHint.trim() ? `认证/权限提示：${draft.authHint.trim()}` : '',
     '',
     '必须先读取并使用 web2cli skill，再执行捕获、导出与转换流程。',
-    '请使用 browser-use / web2cli 思路分析页面请求，并把结果生成 CLI 后集成到 skill 中，而不是只保留临时脚本。',
+    '请使用 browser-use / web2cli 思路分析页面请求，并先完成 skill 集成；如果当前目标是安全设备接入，再把结果整理成 device 插件，不要只保留临时脚本。',
   ].filter(Boolean).join('\n');
 }
 
diff --git a/webui/src/pages/DeviceIntegration/index.test.tsx b/webui/src/pages/DeviceIntegration/index.test.tsx
index 01a133798..ae480a1db 100644
--- a/webui/src/pages/DeviceIntegration/index.test.tsx
+++ b/webui/src/pages/DeviceIntegration/index.test.tsx
@@ -210,22 +210,34 @@ describe('DeviceIntegrationPage', () => {
     expect(screen.getByLabelText('需要获取的接口或页面行为')).toBeInTheDocument();
   });
 
-  it('refreshes templates and enters device config when matching template appears', async () => {
+  it('submits webcli draft to Rex with skill-first device prompt', async () => {
     const user = userEvent.setup();
-    mocks.listApiServices
-      .mockResolvedValueOnce({ data: [buildTemplate()] })
-      .mockResolvedValueOnce({
-        data: [
-          buildTemplate(),
-          buildTemplate({
-            id: 'acme_guard_device_v1',
-            name: 'Acme Guard',
-            vendor: 'acme_security',
-            description_cn: '自定义接入设备',
-          }),
-        ],
-      });
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
+    await user.click(screen.getByRole('button', { name: /自定义设备/ }));
+    await user.click(screen.getByRole('button', { name: /WebCLI 接入/ }));
+
+    await user.type(screen.getByLabelText('设备产品名'), 'Acme Portal');
+    await user.type(screen.getByLabelText('厂商名称'), 'Acme Security');
+    await user.type(screen.getByLabelText('产品 URL'), 'https://portal.example.com');
+    await user.type(screen.getByLabelText('需要获取的接口或页面行为'), '告警列表和资产详情');
+    await user.type(screen.getByLabelText('认证/权限提示'), 'Cookie + CSRF Token');
+    await user.click(screen.getByRole('button', { name: /提交给 Rex/ }));
+
+    await waitFor(() => expect(mocks.createAndSend).toHaveBeenCalledTimes(1));
+    const arg = mocks.createAndSend.mock.calls[0][0];
+    expect(arg.text).toContain('接入方式：WebCLI');
+    expect(arg.text).toContain('https://portal.example.com');
+    expect(arg.text).toContain('references/cli-in-skill.md');
+    expect(arg.text).toContain('integration_type: device');
+    expect(arg.text).toContain('~/.flocks/plugins/tools/device/<plugin_id>/');
+    expect(arg.text).toContain('默认认证方式为 `auth-state`');
+    expect(await screen.findByText('SessionChat:session-1')).toBeInTheDocument();
+  });
 
+  it('hides refresh action and rex footer hint in chat view', async () => {
+    const user = userEvent.setup();
     render(<DeviceIntegrationPage />);
 
     await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
@@ -237,11 +249,27 @@ describe('DeviceIntegrationPage', () => {
     await user.type(screen.getByLabelText('API 文档链接'), 'https://device.example.com/openapi');
     await user.click(screen.getByRole('button', { name: /提交给 Rex/ }));
 
-    await user.click(screen.getByRole('button', { name: /刷新设备模板/ }));
+    await screen.findByText('SessionChat:session-1');
+    expect(screen.queryByRole('button', { name: /刷新设备模板/ })).toBeNull();
+    expect(screen.queryByText(/已进入 Rex 对话/)).toBeNull();
+  });
+
+  it('navigates to the matching session from rex chat view', async () => {
+    const user = userEvent.setup();
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByRole('button', { name: /立即添加设备/ }));
+    await user.click(screen.getByRole('button', { name: /自定义设备/ }));
+    await user.click(screen.getByRole('button', { name: /API 接入/ }));
+    await user.type(screen.getByLabelText('设备产品名'), 'Acme Guard');
+    await user.type(screen.getByLabelText('厂商名称'), 'Acme Security');
+    await user.type(screen.getByLabelText('Base URL'), 'https://device.example.com/api');
+    await user.click(screen.getByRole('button', { name: /提交给 Rex/ }));
+
+    await screen.findByText('SessionChat:session-1');
+    await user.click(screen.getByRole('button', { name: /前往会话列表查看/ }));
 
-    await waitFor(() => expect(mocks.refreshTools).toHaveBeenCalledTimes(1));
-    expect(await screen.findByText('填写配置')).toBeInTheDocument();
-    expect(screen.getByText('acme_guard_device_v1')).toBeInTheDocument();
+    expect(mocks.navigate).toHaveBeenCalledWith('/sessions?session=session-1');
   });
 
   it('redirects syslog flow to workflows page', async () => {
diff --git a/webui/src/pages/DeviceIntegration/index.tsx b/webui/src/pages/DeviceIntegration/index.tsx
index aa0a51ed1..19719d9a6 100644
--- a/webui/src/pages/DeviceIntegration/index.tsx
+++ b/webui/src/pages/DeviceIntegration/index.tsx
@@ -300,7 +300,7 @@ function AddDeviceWizardPanel({ templates, instanceCounts, initialVendor, onSele
                   {
                     key: 'webcli' as const,
                     title: 'WebCLI 接入',
-                    desc: '设备没有开放 API 时使用。提供产品 URL 和需要获取的接口，由浏览器抓取后生成 CLI 并集成到 skill。',
+                    desc: '设备没有开放 API 时使用。先生成并集成 skill/CLI 资产；如果是安全设备场景，再额外生成可在设备页使用的 device 插件。',
                   },
                   {
                     key: 'syslog' as const,
@@ -1213,8 +1213,6 @@ export default function DeviceIntegrationPage() {
           mode={panel.mode}
           onClose={() => setPanel(null)}
           onBack={() => setPanel({ kind: 'wizard' })}
-          onRefreshTemplates={() => fetchData(true)}
-          onTemplateMatched={(template) => setPanel({ kind: 'add', template })}
         />
       )}
 

From e2cc2aafc0a962082878b5664727c527bb5b5080 Mon Sep 17 00:00:00 2001
From: xiami762 <>
Date: Mon, 1 Jun 2026 18:30:22 +0800
Subject: [PATCH 3/4] feat(device,web2cli): reveal persisted secrets and
 streamline CLI docs

Add an explicit credentials endpoint so the device UI can show full
masked secrets on demand. Update web2cli to document cookie/auth-state
defaults and replace the spec-generation step with cli-requirements.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .flocks/plugins/skills/web2cli/SKILL.md       |  74 +++----------
 .../web2cli/references/cli-in-device.md       |  13 ++-
 .../web2cli/references/cli-requirements.md    | 101 ++++++++++++++++++
 flocks/server/routes/device.py                |  10 ++
 flocks/tool/device/__init__.py                |   2 +
 flocks/tool/device/models.py                  |   4 +
 flocks/tool/device/secrets.py                 |   4 +-
 tests/server/routes/test_device_routes.py     |  51 +++++++++
 webui/src/api/device.ts                       |   7 ++
 .../pages/DeviceIntegration/index.test.tsx    |  88 +++++++++++++++
 webui/src/pages/DeviceIntegration/index.tsx   |  43 +++++++-
 11 files changed, 329 insertions(+), 68 deletions(-)
 create mode 100644 .flocks/plugins/skills/web2cli/references/cli-requirements.md

diff --git a/.flocks/plugins/skills/web2cli/SKILL.md b/.flocks/plugins/skills/web2cli/SKILL.md
index 2dd74535c..0ba30d6ef 100644
--- a/.flocks/plugins/skills/web2cli/SKILL.md
+++ b/.flocks/plugins/skills/web2cli/SKILL.md
@@ -51,16 +51,15 @@ mkdir -p "$CAPTURE_ROOT/captures"
 - 浏览器内存中的原始捕获数据：`window.__capturedRequests`
 - 导出的接口抓包 JSON：`$CAPTURE_ROOT/captures/${CAPTURE_NAME}_api.json`
 - 浏览器认证状态：`$CAPTURE_ROOT/auth-state.json`
-- 操作适配规格：`$CAPTURE_ROOT/web2cli-spec.json`
 - 站点自适应 Hook（仅当 base 失败时创建）：`$CAPTURE_ROOT/hook.js`
-- 生成的 CLI 工具：`$CAPTURE_ROOT/<normalized_capture_name>_cli.py`，`generate-cli.py` 会把 `-` 等非 Python 模块名字符替换为 `_`
+- 生成的 CLI 工具：`$CAPTURE_ROOT/<normalized_capture_name>_cli.py`，文件名中的 `-` 等非 Python 模块名字符需替换为 `_`
 - 生成的验证材料：`$CAPTURE_ROOT/${CAPTURE_NAME}_verify.json`
-- 生成的接口文档：`$CAPTURE_ROOT/${CAPTURE_NAME}_api.md`
+- 生成的接口文档：`$CAPTURE_ROOT/cli-reference.md`
 - 生成的 Postman 集合：`$CAPTURE_ROOT/${CAPTURE_NAME}_postman.json`
 
 ## 标准流程
 
-> 按照以下 1-12 的操作流程完成任务
+> 按照以下 1-11 的操作流程完成任务
 
 ### 1. 打开浏览器或创建 Tab
 
@@ -256,66 +255,23 @@ jq -r '.[].method' "$CAPTURE_ROOT/captures/${CAPTURE_NAME}_api.json" | sort | un
 jq '.[] | select(.method == "POST") | {url: .url, body: .requestBody}' "$CAPTURE_ROOT/captures/${CAPTURE_NAME}_api.json"
 ```
 
-### 8. 生成 web2cli-spec 规格
+### 8. CLI 工具生成
 
-先基于 `"$CAPTURE_ROOT/captures/${CAPTURE_NAME}_api.json"` 生成中间契约层 `web2cli-spec.json`。
+根据 `references/cli-requirements.md` 的要求，基于抓包结果、认证状态和用户目标，生成 CLI、验证材料和接口文档。
 
-```bash
-uv run python .flocks/plugins/skills/web2cli/scripts/generate-spec.py \
-  "$CAPTURE_ROOT/captures/${CAPTURE_NAME}_api.json" \
-  --base-url "https://example.com" \
-  --output "$CAPTURE_ROOT/web2cli-spec.json"
-```
-
-`web2cli-spec.json` 是抓包结果到最终 CLI 之间的可编辑契约，包含：
-
-- 目标站点与命令名
-- 鉴权策略（如 `PUBLIC` / `COOKIE` / `HEADER`）
-- 主请求的 method、endpoint、query/body/payload 模板
-- CLI 参数定义
-- 固定输出列定义
-- 验证材料初稿
-
-生成后必须检查并按需修正：
-
-- `strategy` 是否正确
-- `args` 是否符合实际操作意图
-- `columns` 与字段路径是否对应目标数据
-- `verify` 的最少行数、必填列是否合理
-
-### 9. 基于 spec 生成 CLI 工具
-
-从 `"$CAPTURE_ROOT/web2cli-spec.json"` 生成最终 CLI。
+生成前必须读取并遵循：
 
-```bash
-uv run python .flocks/plugins/skills/web2cli/scripts/generate-cli.py \
-  --spec "$CAPTURE_ROOT/web2cli-spec.json" \
-  --format python \
-  --output "$CAPTURE_ROOT/${CAPTURE_NAME}_cli.py"
-```
-
-如果 `CAPTURE_NAME` 包含 `-` 等不能作为 Python 模块名的字符，生成器会自动规范化输出文件名，例如 `test-domain_cli.py` 会写为 `test_domain_cli.py`，并在命令输出中打印实际路径。
-
-生成验证文件：
+- `$WEB2CLI_SKILL/references/cli-requirements.md`
 
-```bash
-uv run python .flocks/plugins/skills/web2cli/scripts/generate-cli.py \
-  --spec "$CAPTURE_ROOT/web2cli-spec.json" \
-  --format verify \
-  --output "$CAPTURE_ROOT/${CAPTURE_NAME}_verify.json"
-```
+最终产物必须包含：
 
-生成接口文档：
+- `$CAPTURE_ROOT/<normalized_capture_name>_cli.py`
+- `$CAPTURE_ROOT/${CAPTURE_NAME}_verify.json`
+- `$CAPTURE_ROOT/cli-reference.md`
 
-```bash
-uv run python .flocks/plugins/skills/web2cli/scripts/generate-cli.py \
-  --spec "$CAPTURE_ROOT/web2cli-spec.json" \
-  --format markdown \
-  --title "${CAPTURE_NAME} API Documentation" \
-  --output "$CAPTURE_ROOT/${CAPTURE_NAME}_api.md"
-```
+如果 `CAPTURE_NAME` 包含 `-` 等不能作为 Python 模块名的字符，生成 CLI 文件名时必须规范化为 `_`，例如 `test-domain_cli.py` 应写为 `test_domain_cli.py`。
 
-### 10. CLI工具验证与修改
+### 9. CLI工具验证与修改
 
 根据生成的 CLI ，任意选择一个接口调用测试可用性
 - CLI 工具可用性
@@ -325,7 +281,7 @@ uv run python .flocks/plugins/skills/web2cli/scripts/generate-cli.py \
 
 推荐先查看 `"$CAPTURE_ROOT/${CAPTURE_NAME}_verify.json"`，再用生成的 CLI 以默认参数执行一次，确认固定输出列与认证状态都正确。
 
-### 11. 将 WebCLI 能力沉淀为最终产物
+### 10. 将 WebCLI 能力沉淀为最终产物
 
 分为基础层和可选增强层：
 
@@ -345,7 +301,7 @@ uv run python .flocks/plugins/skills/web2cli/scripts/generate-cli.py \
 
 不要只停留在一次性 CLI 或临时抓包结果；最终都要沉淀成可长期维护的资产。
 
-### 12. summary并关闭浏览器 tab
+### 11. summary并关闭浏览器 tab
 
 1. 总结当前生成的 CLI 工具有哪些接口/能力
 2. 确保 CLI 可用后关闭浏览器或 Tab
diff --git a/.flocks/plugins/skills/web2cli/references/cli-in-device.md b/.flocks/plugins/skills/web2cli/references/cli-in-device.md
index 30747c6f0..6df7ac420 100644
--- a/.flocks/plugins/skills/web2cli/references/cli-in-device.md
+++ b/.flocks/plugins/skills/web2cli/references/cli-in-device.md
@@ -44,11 +44,12 @@ $HOME/.flocks/plugins/tools/device/<plugin_id>/
 
 认证默认规则：
 
-- 自定义 CLI / WebCLI 默认认证方式为 `auth-state`
+- 自定义 CLI / WebCLI 默认认证方式为 `cookie/auth-state`：优先复用浏览器保存的 `auth-state.json`，从中按请求域名/path/secure 规则选择 Cookie，并在需要时读取 localStorage
 - 默认认证状态文件：`~/.flocks/browser/<name>/auth-state.json`
 - 优先使用 `auth_state_path` 指向 `~/.flocks/browser/<name>/auth-state.json`
-- 只有在目标站点确实还依赖额外字段时，才补充 `auth_state_json`、`cookie`、`csrf_token`、`access_token`
-- 不要把 `cookie` 或 `token` 设计成和 `auth-state` 并列的多个默认入口
+- 不要生成或使用 `auth_state_json` / `Legacy Auth State JSON` 这类内联 JSON 字段；设备配置只保存 state 文件路径，不粘贴 state 文件内容
+- 只有在目标站点确实还依赖额外字段时，才补充 `cookie`、`csrf_token`、`access_token` 或特定认证头；这些字段是 `auth_state_path` 之外的补充，不替代默认的 cookie/auth-state
+- 不要把 `cookie` 或 `token` 设计成和 `auth-state` 并列的多个默认入口；如果用户提供的是 state 文件路径，必须写入 `auth_state_path`
 
 ## 命名约定
 
@@ -120,7 +121,8 @@ notes: |
 - `description` 用英文，`description_cn` 用中文
 - 只把运行时真正需要用户填写的字段放进 `credential_fields`
 - 不要把真实 cookie、token、密码、auth state JSON 写进插件文件
-- 默认先放 `auth_state_path`，并指向 `~/.flocks/browser/<name>/auth-state.json`；`cookie`、`csrf_token`、`access_token` 只有在实际站点需要时再补
+- 默认先放 `auth_state_path`，并指向 `~/.flocks/browser/<name>/auth-state.json`；不要添加 `auth_state_json` / `Legacy Auth State JSON`
+- `cookie`、`csrf_token`、`access_token` 或特定认证头只有在实际站点需要时再补，并在 handler 中明确说明来源与刷新方式
 
 ## 最小工具 YAML
 
@@ -193,6 +195,8 @@ async def handle(ctx: ToolContext, action: str, **params: Any) -> ToolResult:
 
 - 通过 `ConfigWriter.get_api_service_raw(SERVICE_ID)` 读取当前设备实例配置
 - handler 内部负责认证头构造、分页、超时、重试和响应归一化
+- handler 默认只读取 `auth_state_path` 指向的 `auth-state.json`；如果文件缺失、不是合法 JSON，或没有匹配当前 Base URL 的 Cookie，应返回明确错误并提示重新登录/保存 state
+- handler 不要 fallback 到内联 `auth_state_json`；这会把路径字符串、占位文本或过期内容误当 JSON 解析，导致设备测试报错不清晰
 - CLI 可选保留，但不要让设备运行时通过 subprocess 调 CLI
 
 ## 组合 API / WebCLI / 处理逻辑
@@ -211,6 +215,7 @@ async def handle(ctx: ToolContext, action: str, **params: Any) -> ToolResult:
 3. 需要字段清洗、补全、排序、聚合时，在 handler 内增加 `process`
 4. 需要多个来源补齐同一业务结果时，用 `composed`
 5. 必须验证码、强动态页面或人工交互时，只记录为 browser fallback，不放进默认设备运行时
+6. 如果某个隐藏接口依赖 `Authorization`、`Tdp-Authentication`、CSRF 等临时头，只有在 handler 已实现可靠的恢复/刷新逻辑时才暴露为默认 action；否则保留在 CLI 或文档中，不放进设备默认动作
 
 示例 action 映射：
 
diff --git a/.flocks/plugins/skills/web2cli/references/cli-requirements.md b/.flocks/plugins/skills/web2cli/references/cli-requirements.md
new file mode 100644
index 000000000..16ef30d38
--- /dev/null
+++ b/.flocks/plugins/skills/web2cli/references/cli-requirements.md
@@ -0,0 +1,101 @@
+# Web2CLI CLI 生成要求
+
+> 本文是生成 WebCLI 工具时必须遵循的参考要求。应根据抓包结果、认证状态和用户目标直接生成 CLI、验证材料和接口文档。
+
+## 输入材料
+
+- 抓包 JSON：`$CAPTURE_ROOT/captures/${CAPTURE_NAME}_api.json`
+- 浏览器认证状态：`$CAPTURE_ROOT/auth-state.json`
+- 页面入口 URL：来自用户目标或当前浏览器页面
+- 用户要复现的操作：来自用户目标和最近页面操作
+- 目标 base URL：从抓包 URL 中归纳，必要时结合用户指定值
+
+## 生成目标
+
+生成以下文件：
+
+- CLI 主脚本：`$CAPTURE_ROOT/<normalized_capture_name>_cli.py`
+- 验证材料：`$CAPTURE_ROOT/${CAPTURE_NAME}_verify.json`
+- 接口文档：`$CAPTURE_ROOT/cli-reference.md`
+
+命名要求：
+
+- `<normalized_capture_name>` 必须是合法 Python 文件名片段
+- 将 `-`、空格等不适合作为 Python 模块名的字符替换为 `_`
+- 不要把一次性路径、cookie、token 或用户私密信息硬编码到脚本中
+
+## CLI 行为要求
+
+CLI 必须说明并实现：
+
+- 命令名：`<command_name>`
+- 目标能力：`<capability>`
+- 默认认证策略：`auth-state` / `cookie` / `header` / `public`
+- 默认认证输入：优先使用 `--auth-state "$CAPTURE_ROOT/auth-state.json"` 或对应环境变量
+- 必填参数：`<required_args>`
+- 可选参数与默认值：`<optional_args>`
+- 输出格式：默认 `table` 或 `json`，必要时同时支持 `--json`
+- 退出码：成功为 `0`，认证失败、参数错误、请求失败和验证失败使用非零退出码
+
+## 请求链路要求
+
+从抓包 JSON 中选出与目标操作直接相关的请求，并写清楚：
+
+- 请求顺序和依赖关系
+- method、endpoint、query、body/payload 模板
+- 必要 headers，如 `content-type`、`csrf`、`x-requested-with`
+- 认证信息从哪里读取，如何注入到请求中
+- 分页、排序、过滤、时间范围等参数如何映射到 CLI 参数
+- 响应字段路径，以及嵌套列表、空值、错误结构如何处理
+
+不要把无关埋点、静态资源、日志上报、健康检查或页面渲染请求纳入主链路。
+
+## 输出要求
+
+固定输出列必须写清楚：
+
+| column | source_path | required | description |
+| --- | --- | --- | --- |
+| `<name>` | `<json.path>` | `<true/false>` | `<description>` |
+
+要求：
+
+- 表格输出列顺序稳定
+- JSON 输出保留原始字段或清洗后的结构
+- 必填列为空时应在验证材料中标记为失败
+- 时间、数量、状态等字段需要说明格式化规则
+
+## 验证要求
+
+`verify.json` 至少包含：
+
+- CLI 调用样例
+- 认证输入说明
+- 最少返回行数
+- 必填列列表
+- 预期 HTTP 状态码或业务成功字段
+- 常见失败场景与判定方式
+
+示例结构：
+
+```json
+{
+  "command": "uv run python <normalized_capture_name>_cli.py --auth-state auth-state.json",
+  "min_rows": 1,
+  "required_columns": ["<column>"],
+  "success_status": [200],
+  "failure_hints": ["authentication expired", "missing required argument"]
+}
+```
+
+## 接口文档要求
+
+`cli-reference.md` 至少包含：
+
+- 能力说明和适用场景
+- 认证方式与刷新登录态的方法
+- CLI 参数表
+- 请求链路摘要
+- 输出字段说明
+- 验证方式和常见问题
+
diff --git a/flocks/server/routes/device.py b/flocks/server/routes/device.py
index f5785bffa..2b61c0864 100644
--- a/flocks/server/routes/device.py
+++ b/flocks/server/routes/device.py
@@ -21,6 +21,7 @@
     DeviceGroup,
     DeviceGroupCreate,
     DeviceGroupUpdate,
+    DeviceCredentialResponse,
     DeviceIntegration,
     DeviceIntegrationCreate,
     DeviceIntegrationUpdate,
@@ -128,6 +129,15 @@ async def route_get_device(device_id: str):
     return row_to_device(row)
 
 
+@router.get("/{device_id}/credentials", response_model=DeviceCredentialResponse)
+async def route_get_device_credentials(device_id: str):
+    row = await fetch_device(device_id)
+    if row is None:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="Device not found")
+    db_fields: dict = json.loads(row["fields"] or "{}")
+    return DeviceCredentialResponse(fields=resolve_for_runtime(db_fields))
+
+
 @router.post("", response_model=DeviceIntegration, status_code=http_status.HTTP_201_CREATED)
 async def route_create_device(body: DeviceIntegrationCreate):
     name = body.name.strip()
diff --git a/flocks/tool/device/__init__.py b/flocks/tool/device/__init__.py
index e243dd44e..f4219eb1c 100644
--- a/flocks/tool/device/__init__.py
+++ b/flocks/tool/device/__init__.py
@@ -11,6 +11,7 @@
     DeviceGroup,
     DeviceGroupCreate,
     DeviceGroupUpdate,
+    DeviceCredentialResponse,
     DeviceIntegration,
     DeviceIntegrationCreate,
     DeviceIntegrationUpdate,
@@ -28,6 +29,7 @@
     "DeviceGroup",
     "DeviceGroupCreate",
     "DeviceGroupUpdate",
+    "DeviceCredentialResponse",
     "DeviceIntegration",
     "DeviceIntegrationCreate",
     "DeviceIntegrationUpdate",
diff --git a/flocks/tool/device/models.py b/flocks/tool/device/models.py
index 71def077b..0bf37735f 100644
--- a/flocks/tool/device/models.py
+++ b/flocks/tool/device/models.py
@@ -131,6 +131,10 @@ class DeviceIntegrationUpdate(BaseModel):
     fields: Optional[Dict[str, str]] = None
 
 
+class DeviceCredentialResponse(BaseModel):
+    fields: Dict[str, str] = Field(default_factory=dict)
+
+
 class DeviceTestResult(BaseModel):
     success: bool
     message: str
diff --git a/flocks/tool/device/secrets.py b/flocks/tool/device/secrets.py
index d48a165fe..4ea51fe9f 100644
--- a/flocks/tool/device/secrets.py
+++ b/flocks/tool/device/secrets.py
@@ -135,8 +135,8 @@ def mask_for_display(db_fields: Dict[str, str]) -> Tuple[Dict[str, str], Dict[st
 def resolve_for_runtime(db_fields: Dict[str, str]) -> Dict[str, str]:
     """Resolve ``{secret:…}`` placeholders to plaintext.
 
-    Call ONLY at the moment of making an outbound API request.
-    Never store or return the result through a public interface.
+    Call ONLY at the moment of making an outbound API request or serving an
+    explicit authenticated reveal action. Never store or log the result.
     """
     from flocks.security import get_secret_manager
 
diff --git a/tests/server/routes/test_device_routes.py b/tests/server/routes/test_device_routes.py
index 8a4cd5148..cf94284b0 100644
--- a/tests/server/routes/test_device_routes.py
+++ b/tests/server/routes/test_device_routes.py
@@ -196,3 +196,54 @@ async def fake_fetch_device(device_id: str):
         resp = await client.post("/api/devices/missing-id/test", json={})
 
         assert resp.status_code == 404
+
+
+class TestDeviceCredentialEndpoint:
+    @pytest.mark.asyncio
+    async def test_returns_resolved_fields_for_explicit_reveal(
+        self, client: AsyncClient, monkeypatch: pytest.MonkeyPatch
+    ):
+        captured: dict = {}
+
+        async def fake_fetch_device(device_id: str):
+            captured["device_id"] = device_id
+            return _fake_row(
+                fields={
+                    "api_key": "{secret:device_dev-test_api_key}",
+                    "base_url": "https://console.onesec.net",
+                }
+            )
+
+        monkeypatch.setattr(device_routes, "fetch_device", fake_fetch_device)
+        monkeypatch.setattr(
+            device_routes,
+            "resolve_for_runtime",
+            lambda db_fields: {
+                **db_fields,
+                "api_key": "long-real-onesec-api-key-Cd4Y",
+            },
+        )
+
+        resp = await client.get("/api/devices/dev-test/credentials")
+
+        assert resp.status_code == 200, resp.text
+        assert captured["device_id"] == "dev-test"
+        assert resp.json() == {
+            "fields": {
+                "api_key": "long-real-onesec-api-key-Cd4Y",
+                "base_url": "https://console.onesec.net",
+            }
+        }
+
+    @pytest.mark.asyncio
+    async def test_returns_404_for_unknown_device(
+        self, client: AsyncClient, monkeypatch: pytest.MonkeyPatch
+    ):
+        async def fake_fetch_device(device_id: str):
+            return None
+
+        monkeypatch.setattr(device_routes, "fetch_device", fake_fetch_device)
+
+        resp = await client.get("/api/devices/missing-id/credentials")
+
+        assert resp.status_code == 404
diff --git a/webui/src/api/device.ts b/webui/src/api/device.ts
index 357114a98..8cc810e18 100644
--- a/webui/src/api/device.ts
+++ b/webui/src/api/device.ts
@@ -53,6 +53,10 @@ export interface DeviceIntegration {
   updated_at: number;
 }
 
+export interface DeviceCredentialResponse {
+  fields: Record<string, string>;
+}
+
 export interface DeviceIntegrationCreate {
   name: string;
   storage_key: string;
@@ -110,6 +114,9 @@ export const deviceAPI = {
   get: (id: string) =>
     client.get<DeviceIntegration>(`/api/devices/${id}`),
 
+  getCredentials: (id: string) =>
+    client.get<DeviceCredentialResponse>(`/api/devices/${id}/credentials`),
+
   create: (data: DeviceIntegrationCreate) =>
     client.post<DeviceIntegration>('/api/devices', data),
 
diff --git a/webui/src/pages/DeviceIntegration/index.test.tsx b/webui/src/pages/DeviceIntegration/index.test.tsx
index ae480a1db..079015a5a 100644
--- a/webui/src/pages/DeviceIntegration/index.test.tsx
+++ b/webui/src/pages/DeviceIntegration/index.test.tsx
@@ -20,6 +20,7 @@ const mocks = vi.hoisted(() => ({
   updateDevice: vi.fn(),
   deleteDevice: vi.fn(),
   testDevice: vi.fn(),
+  getDeviceCredentials: vi.fn(),
   listApiServices: vi.fn(),
   getServiceMetadata: vi.fn(),
   listTools: vi.fn(),
@@ -88,6 +89,7 @@ vi.mock('@/api/device', () => ({
   deviceAPI: {
     list: (...args: unknown[]) => mocks.listDevices(...args),
     get: (...args: unknown[]) => mocks.getDevice(...args),
+    getCredentials: (...args: unknown[]) => mocks.getDeviceCredentials(...args),
     listGroups: (...args: unknown[]) => mocks.listGroups(...args),
     updateGroup: (...args: unknown[]) => mocks.updateGroup(...args),
     create: (...args: unknown[]) => mocks.createDevice(...args),
@@ -151,6 +153,7 @@ describe('DeviceIntegrationPage', () => {
     });
     mocks.listApiServices.mockResolvedValue({ data: [buildTemplate()] });
     mocks.getServiceMetadata.mockResolvedValue({ data: { credential_schema: [] } });
+    mocks.getDeviceCredentials.mockResolvedValue({ data: { fields: {} } });
     mocks.listTools.mockResolvedValue({ data: [] });
     mocks.setToolEnabled.mockResolvedValue({ data: {} });
     mocks.refreshTools.mockResolvedValue({ data: { ok: true } });
@@ -378,4 +381,89 @@ describe('DeviceIntegrationPage', () => {
       expect(screen.queryByRole('button', { name: '关闭设备配置面板' })).not.toBeInTheDocument();
     });
   });
+
+  it('reveals the full persisted secret when clicking show', async () => {
+    const user = userEvent.setup();
+    mocks.listDevices.mockResolvedValueOnce({
+      data: [
+        {
+          id: 'device-1',
+          group_id: 'group-1',
+          name: 'onesec-02',
+          storage_key: 'onesec_api_v2_8_2',
+          service_id: 'onesec',
+          enabled: true,
+          verify_ssl: false,
+          fields: {
+            api_key: 'l***Cd4Y',
+            secret: 's***7890',
+            base_url: 'https://console.onesec.net',
+          },
+          fields_set: { api_key: true, secret: true, base_url: true },
+          status: 'connected',
+          created_at: 0,
+          updated_at: 0,
+        },
+      ],
+    });
+    mocks.listApiServices.mockResolvedValueOnce({
+      data: [
+        {
+          id: 'onesec_api_v2_8_2',
+          name: 'OneSEC',
+          enabled: true,
+          status: 'ready',
+          tool_count: 5,
+          verify_ssl: false,
+          integration_type: 'device',
+          vendor: 'threatbook',
+        },
+      ],
+    });
+    mocks.getServiceMetadata.mockResolvedValueOnce({
+      data: {
+        name: 'OneSEC',
+        credential_schema: [
+          {
+            key: 'api_key',
+            label: 'API Key',
+            storage: 'secret',
+            sensitive: true,
+            required: true,
+            input_type: 'password',
+            config_key: 'api_key',
+          },
+          {
+            key: 'secret',
+            label: 'Secret',
+            storage: 'secret',
+            sensitive: true,
+            required: true,
+            input_type: 'password',
+            config_key: 'secret',
+          },
+        ],
+      },
+    });
+    mocks.getDeviceCredentials.mockResolvedValueOnce({
+      data: {
+        fields: {
+          api_key: 'long-real-onesec-api-key-Cd4Y',
+          secret: 'long-real-onesec-secret-7890',
+        },
+      },
+    });
+
+    render(<DeviceIntegrationPage />);
+
+    await user.click(await screen.findByText('onesec-02'));
+    expect(await screen.findByDisplayValue('l***Cd4Y')).toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: '显示API Key' }));
+
+    await waitFor(() => {
+      expect(mocks.getDeviceCredentials).toHaveBeenCalledWith('device-1');
+      expect(screen.getByDisplayValue('long-real-onesec-api-key-Cd4Y')).toBeInTheDocument();
+    });
+  });
 });
diff --git a/webui/src/pages/DeviceIntegration/index.tsx b/webui/src/pages/DeviceIntegration/index.tsx
index 19719d9a6..e2ece252c 100644
--- a/webui/src/pages/DeviceIntegration/index.tsx
+++ b/webui/src/pages/DeviceIntegration/index.tsx
@@ -424,6 +424,7 @@ function DeviceConfigPanel({ device, template, vendorKey, onSave, onDelete, onCl
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [credFields, setCredFields] = useState<APIServiceCredentialField[]>([]);
   const [visibility, setVisibility] = useState<Record<string, boolean>>({});
+  const [revealingFields, setRevealingFields] = useState<Record<string, boolean>>({});
   const [serviceTools, setServiceTools] = useState<Tool[]>([]);
   const [toolModal, setToolModal] = useState<Tool | null>(null);
   const [metadata, setMetadata] = useState<{ name?: string; version?: string; description?: string; description_cn?: string; docs_url?: string } | null>(null);
@@ -568,6 +569,38 @@ function DeviceConfigPanel({ device, template, vendorKey, onSave, onDelete, onCl
     }
   };
 
+  const handleToggleFieldVisibility = async (field: APIServiceCredentialField, hasExisting: boolean) => {
+    const key = field.key;
+    if (visibility[key]) {
+      setVisibility((p) => ({ ...p, [key]: false }));
+      return;
+    }
+
+    const currentValue = fields[key] ?? '';
+    const maskedValue = originalMasked.current[key] ?? '';
+    const shouldRevealPersisted = !!device && hasExisting && (!currentValue || currentValue === maskedValue);
+    if (!shouldRevealPersisted) {
+      setVisibility((p) => ({ ...p, [key]: true }));
+      return;
+    }
+
+    setRevealingFields((p) => ({ ...p, [key]: true }));
+    try {
+      const res = await deviceAPI.getCredentials(device.id);
+      const revealedValue = res.data.fields?.[key];
+      if (typeof revealedValue !== 'string') {
+        toast.error('读取密钥失败');
+        return;
+      }
+      setFields((p) => ({ ...p, [key]: revealedValue }));
+      setVisibility((p) => ({ ...p, [key]: true }));
+    } catch {
+      toast.error('读取密钥失败');
+    } finally {
+      setRevealingFields((p) => ({ ...p, [key]: false }));
+    }
+  };
+
   const handleDelete = async () => {
     if (!confirmDelete) {
       setConfirmDelete(true);
@@ -677,6 +710,7 @@ function DeviceConfigPanel({ device, template, vendorKey, onSave, onDelete, onCl
                     {credFields.map((f) => {
                       const isSecret = f.storage === 'secret' || f.input_type === 'password';
                       const show = !!visibility[f.key];
+                      const revealing = !!revealingFields[f.key];
                       const hasExisting = !!device?.fields_set?.[f.key];
                       return (
                         <div key={f.key}>
@@ -695,10 +729,13 @@ function DeviceConfigPanel({ device, template, vendorKey, onSave, onDelete, onCl
                             {isSecret && (
                               <button
                                 type="button"
-                                onClick={() => setVisibility((p) => ({ ...p, [f.key]: !p[f.key] }))}
-                                className="absolute right-2.5 top-1/2 -translate-y-1/2 text-zinc-400 hover:text-zinc-600"
+                                onClick={() => handleToggleFieldVisibility(f, hasExisting)}
+                                disabled={revealing}
+                                aria-label={show ? `隐藏${f.label}` : `显示${f.label}`}
+                                title={show ? '隐藏' : '显示'}
+                                className="absolute right-2.5 top-1/2 -translate-y-1/2 text-zinc-400 hover:text-zinc-600 disabled:opacity-60"
                               >
-                                {show ? <EyeOff className="w-4 h-4" /> : <Eye className="w-4 h-4" />}
+                                {revealing ? <Loader2 className="w-4 h-4 animate-spin" /> : show ? <EyeOff className="w-4 h-4" /> : <Eye className="w-4 h-4" />}
                               </button>
                             )}
                           </div>

From 3f079d41e37684930864d24e03923544514c2f36 Mon Sep 17 00:00:00 2001
From: xiami762 <>
Date: Mon, 1 Jun 2026 18:49:31 +0800
Subject: [PATCH 4/4] feat(web2cli,webui): document optional auth recovery
 credentials

Allow optional username/password for browser-based cookie recovery
after auth-state expires, and align custom device session prompts
with the updated cli-in-device guidance.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../web2cli/references/cli-in-device.md       | 27 ++++++++++++++++---
 .../DeviceIntegration/customDevice.test.ts    |  5 ++++
 .../pages/DeviceIntegration/customDevice.ts   | 11 +++++---
 3 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/.flocks/plugins/skills/web2cli/references/cli-in-device.md b/.flocks/plugins/skills/web2cli/references/cli-in-device.md
index 6df7ac420..56a12af07 100644
--- a/.flocks/plugins/skills/web2cli/references/cli-in-device.md
+++ b/.flocks/plugins/skills/web2cli/references/cli-in-device.md
@@ -47,6 +47,7 @@ $HOME/.flocks/plugins/tools/device/<plugin_id>/
 - 自定义 CLI / WebCLI 默认认证方式为 `cookie/auth-state`：优先复用浏览器保存的 `auth-state.json`，从中按请求域名/path/secure 规则选择 Cookie，并在需要时读取 localStorage
 - 默认认证状态文件：`~/.flocks/browser/<name>/auth-state.json`
 - 优先使用 `auth_state_path` 指向 `~/.flocks/browser/<name>/auth-state.json`
+- 可以额外暴露可选 `username` / `password`，但它们只用于 cookie 失效后的认证恢复，不替代默认的 `auth_state_path`
 - 不要生成或使用 `auth_state_json` / `Legacy Auth State JSON` 这类内联 JSON 字段；设备配置只保存 state 文件路径，不粘贴 state 文件内容
 - 只有在目标站点确实还依赖额外字段时，才补充 `cookie`、`csrf_token`、`access_token` 或特定认证头；这些字段是 `auth_state_path` 之外的补充，不替代默认的 cookie/auth-state
 - 不要把 `cookie` 或 `token` 设计成和 `auth-state` 并列的多个默认入口；如果用户提供的是 state 文件路径，必须写入 `auth_state_path`
@@ -95,6 +96,21 @@ credential_fields:
     config_key: auth_state_path
     input_type: text
     default: "~/.flocks/browser/acme-portal/auth-state.json"
+  - key: username
+    label: Username
+    storage: config
+    config_key: username
+    input_type: text
+    required: false
+    description: 仅在 cookie 失效后需要 Agent 辅助登录刷新 state 时填写
+  - key: password
+    label: Password
+    storage: secret
+    config_key: password
+    secret_id: acme_portal_password
+    input_type: password
+    required: false
+    description: 仅在 cookie 失效后需要 Agent 辅助登录刷新 state 时填写
   - key: cookie
     label: Cookie
     storage: secret
@@ -122,6 +138,7 @@ notes: |
 - 只把运行时真正需要用户填写的字段放进 `credential_fields`
 - 不要把真实 cookie、token、密码、auth state JSON 写进插件文件
 - 默认先放 `auth_state_path`，并指向 `~/.flocks/browser/<name>/auth-state.json`；不要添加 `auth_state_json` / `Legacy Auth State JSON`
+- 可以补充可选 `username` / `password`，但必须标注它们仅用于认证恢复或浏览器辅助登录，不得作为默认运行时认证入口
 - `cookie`、`csrf_token`、`access_token` 或特定认证头只有在实际站点需要时再补，并在 handler 中明确说明来源与刷新方式
 
 ## 最小工具 YAML
@@ -197,6 +214,7 @@ async def handle(ctx: ToolContext, action: str, **params: Any) -> ToolResult:
 - handler 内部负责认证头构造、分页、超时、重试和响应归一化
 - handler 默认只读取 `auth_state_path` 指向的 `auth-state.json`；如果文件缺失、不是合法 JSON，或没有匹配当前 Base URL 的 Cookie，应返回明确错误并提示重新登录/保存 state
 - handler 不要 fallback 到内联 `auth_state_json`；这会把路径字符串、占位文本或过期内容误当 JSON 解析，导致设备测试报错不清晰
+- 如果模板提供了 `username` / `password`，handler 也不要在普通 tool 调用里静默自动登录；这些字段只用于后续由 Rex 进入浏览器认证恢复流程时辅助填表
 - CLI 可选保留，但不要让设备运行时通过 subprocess 调 CLI
 
 ## 组合 API / WebCLI / 处理逻辑
@@ -240,9 +258,12 @@ normalize_alert: process
 处理原则：
 
 1. 不要无限重试
-2. 提示用户重新登录并更新设备配置中的认证字段
-3. 如果保留了 CLI，可用 CLI 做一次最小验证
-4. 验证通过后，再让用户回到设备页点击“刷新设备模板”
+2. 优先返回明确话术，提示 Rex 使用 `flocks browser` 和对应 skill 的认证失败处理去恢复登录态
+3. 如果设备已配置可选 `username` / `password`，Rex 可以在浏览器恢复流程中读取它们辅助登录；如遇验证码、MFA、短信码或人工确认，立即停下并让用户接管
+4. 登录成功后执行 `flocks browser state save <auth_state_path>` 更新 cookie/state 文件
+5. 如仍失败，再提示用户重新登录或更新设备配置中的认证字段
+6. 如果保留了 CLI，可用 CLI 做一次最小验证
+7. 验证通过后，再让用户回到设备页点击“刷新设备模板”
 
 ## `_test.yaml` 建议
 
diff --git a/webui/src/pages/DeviceIntegration/customDevice.test.ts b/webui/src/pages/DeviceIntegration/customDevice.test.ts
index 4a732adca..5cd45d42f 100644
--- a/webui/src/pages/DeviceIntegration/customDevice.test.ts
+++ b/webui/src/pages/DeviceIntegration/customDevice.test.ts
@@ -55,7 +55,12 @@ describe('customDevice helpers', () => {
     expect(prompt).toContain('~/.flocks/plugins/tools/device/<plugin_id>/');
     expect(prompt).toContain('`service_id` 建议使用：`acme_portal_device`');
     expect(prompt).toContain('`auth_state_path`');
+    expect(prompt).toContain('`cookie/auth-state`');
+    expect(prompt).toContain('`username` / `password`');
+    expect(prompt).toContain('`flocks browser`');
+    expect(prompt).toContain('`flocks browser state save <auth_state_path>`');
     expect(prompt).toContain('`api`、`webcli_api`、`process`、`composed`');
+    expect(prompt).toContain('不要生成 `auth_state_json`');
     expect(prompt).toContain('返回设备页查看是否已经出现对应 WebCLI device 插件');
   });
 
diff --git a/webui/src/pages/DeviceIntegration/customDevice.ts b/webui/src/pages/DeviceIntegration/customDevice.ts
index f1731c492..fb8222ee1 100644
--- a/webui/src/pages/DeviceIntegration/customDevice.ts
+++ b/webui/src/pages/DeviceIntegration/customDevice.ts
@@ -68,8 +68,10 @@ function buildWebCliDeviceRequirements(deviceName: string, vendorName: string):
     '如果目标是安全设备接入，还必须在 skill 集成完成后，再额外生成可在设备页识别、配置和调用的标准 device 插件。',
     '请优先遵循 `web2cli` skill 中的捕获、导出、生成 CLI 的完整流程，再把沉淀出的能力包装为长期资产。',
     ...buildBaseDevicePluginRequirements(deviceName, vendorName),
-    '- 自定义 CLI / WebCLI 默认认证方式为 `auth-state`；默认保存位置为 `~/.flocks/browser/<name>/auth-state.json`，优先使用 `auth_state_path`',
-    '- `auth_state_json`、`cookie`、`csrf_token`、`access_token` 仅作为补充或兜底字段，不要和 `auth-state` 并列设计成多个默认认证入口',
+    '- 自定义 CLI / WebCLI 默认认证方式为 `cookie/auth-state`；默认保存位置为 `~/.flocks/browser/<name>/auth-state.json`，优先使用 `auth_state_path`',
+    '- 模板应允许可选填写 `username` / `password`：前者用 config text，后者用 secret password；它们仅用于 cookie 失效后的浏览器认证恢复，不替代 `auth_state_path`',
+    '- 不要生成 `auth_state_json` 或 `Legacy Auth State JSON` 这类内联 JSON 兜底字段',
+    '- `cookie`、`csrf_token`、`access_token` 或特定认证头仅作为补充字段，不要和 `auth_state_path` 并列设计成多个默认认证入口',
     '- skill 集成始终必选；CLI 主脚本默认放在 skill 的 `scripts/` 中，如设备运行时确有需要，可额外在 device 插件目录下保留适配层',
     '- MVP 阶段优先生成单文件 handler；CLI 可以作为调试入口保留，但不应作为设备运行时主路径',
     '运行时能力设计要求：',
@@ -77,6 +79,7 @@ function buildWebCliDeviceRequirements(deviceName: string, vendorName: string):
     '- handler 内部允许按 `api`、`webcli_api`、`process`、`composed` 四类来源编排，但对外返回统一结构',
     '- 如果正式 API 稳定可用，优先正式 API；正式 API 缺能力时，再使用 WebCLI 抓到的隐藏接口',
     '- 只有必须页面交互、验证码或强动态状态时，才记录为 browser fallback，不要作为默认设备运行时主路径',
+    '- cookie 失效时，返回明确认证失败话术，让 Rex 使用 `flocks browser` 和对应 skill 的认证失败处理刷新登录态；如已配置 `username` / `password`，Rex 可读取后辅助登录，再执行 `flocks browser state save <auth_state_path>`',
     '- 高风险写操作必须设置 `requires_confirmation: true`',
     '完成后请提醒用户返回设备页查看是否已经出现对应 WebCLI device 插件，并继续后续配置。',
   ].join('\n');
@@ -100,7 +103,7 @@ export function buildCustomDeviceSessionContext(mode: CustomDeviceAccessMode): s
       '本次接入方式是 WebCLI 接入。',
       '你必须先读取并使用 web2cli skill，再开始捕获与转换流程。',
       '用户会提供产品 URL 和需要获取的接口/页面行为。你可以使用 web2cli 思路抓取接口，但必须先完成 skill 集成；如果目标是安全设备接入，再额外生成 device 插件。',
-      '自定义 CLI 默认复用 `auth-state`；只有在站点确实需要补充 header、cookie 或 token 时，才额外暴露对应字段。',
+      '自定义 CLI 默认复用 `cookie/auth-state`；可选暴露 `username` / `password` 仅用于 cookie 失效后的浏览器认证恢复。只有在站点确实需要补充 header、cookie 或 token 时，才额外暴露对应字段。',
       'MVP 阶段优先生成单文件 script handler；可复用 CLI 只作为调试/回归入口，不作为设备运行时主路径。',
     ].join('\n');
   }
@@ -114,7 +117,7 @@ export function buildCustomDeviceWelcomeMessage(mode: CustomDeviceAccessMode): s
     return '请补充 API 文档链接或直接上传文档文件，并说明目标能力，我会用 tool-builder skill 帮你生成可在设备页使用的 device 插件。';
   }
   if (mode === 'webcli') {
-    return '请补充产品 URL、目标接口和认证提示，我会用 web2cli skill 先生成并集成 CLI/skill 资产；如果是安全设备接入，再额外生成 device 插件。默认使用 auth-state。';
+    return '请补充产品 URL、目标接口和认证提示，我会用 web2cli skill 先生成并集成 CLI/skill 资产；如果是安全设备接入，再额外生成 device 插件。默认使用 cookie/auth-state，并可选配置 username/password 供认证恢复使用。';
   }
   return 'Syslog 方式不在这里创建插件，请前往工作流集成页面配置。';
 }