foxclaw 0.1.0 → 0.1.2

package/python/frontend/deck/markdown.js

@@ -0,0 +1,48 @@
+import { escapeHtml } from './util.js';
+
+/* ===== 安全 Markdown 渲染(模型输出不可信 → 先整体转义,再只发白名单标签;URL 校验 scheme)=====
+   支持:标题/粗斜体/行内码/代码块/列表/引用/分割线/链接/图片,以及裸图/音/视频 URL 内嵌。
+   代码块占位哨兵用私用区字符 (源码里是 ASCII 转义、运行时是该字符,模型文本不会出现 → 无碰撞)。*/
+function _safeUrl(u){ u=(u||'').trim(); return (/^https?:\/\//i.test(u)||/^mailto:/i.test(u))?u:''; }
+function _safeImgUrl(u){ u=(u||'').trim(); return (/^https?:\/\//i.test(u)||/^data:image\/(png|jpe?g|gif|webp);base64,/i.test(u))?u:''; }
+function _mdInline(s){
+  // s 已在 renderMarkdown 里被 escapeHtml,故 <>&" 均为文本;这里只做 markdown 内联生成白名单标签
+  s=s.replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g,(m,alt,url)=>{ const u=_safeImgUrl(url); return u?`<img class="cc-img" src="${u}" alt="${alt}" loading="lazy">`:m; });
+  s=s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g,(m,txt,url)=>{ const u=_safeUrl(url); return u?`<a href="${u}" target="_blank" rel="noopener noreferrer">${txt}</a>`:m; });
+  s=s.replace(/(^|\s)(https?:\/\/[^\s<]+?\.(?:png|jpe?g|gif|webp))(?=\s|$)/gi,(m,pre,url)=>`${pre}<img class="cc-img" src="${url}" alt="" loading="lazy">`);
+  s=s.replace(/(^|\s)(https?:\/\/[^\s<]+?\.(?:mp3|wav|ogg|m4a))(?=\s|$)/gi,(m,pre,url)=>`${pre}<audio class="cc-media" controls src="${url}"></audio>`);
+  s=s.replace(/(^|\s)(https?:\/\/[^\s<]+?\.(?:mp4|webm|mov))(?=\s|$)/gi,(m,pre,url)=>`${pre}<video class="cc-media" controls src="${url}"></video>`);
+  s=s.replace(/`([^`]+)`/g,(m,c)=>`<code class="cc-ic">${c}</code>`);
+  s=s.replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>').replace(/__([^_]+)__/g,'<strong>$1</strong>');
+  s=s.replace(/(^|[^*])\*([^*\n]+)\*/g,'$1<em>$2</em>').replace(/(^|[^_\w])_([^_\n]+)_/g,'$1<em>$2</em>');
+  return s;
+}
+export function renderMarkdown(src){
+  if(!src) return '';
+  const blocks=[];
+  src=src.replace(/```(\w*)\n?([\s\S]*?)```/g,(m,lang,code)=>{ blocks.push(`<pre class="cc-code"><code>${escapeHtml(code.replace(/\n$/,''))}</code></pre>`); return `B${blocks.length-1}`; });
+  const t=escapeHtml(src);              // 整体转义:此后所有原始 <>&" 都是纯文本
+  const lines=t.split('\n'); const out=[]; let inUl=false, inOl=false;
+  const closeLists=()=>{ if(inUl){out.push('</ul>');inUl=false;} if(inOl){out.push('</ol>');inOl=false;} };
+  for(const raw of lines){
+    const line=raw, tr=line.trim(); let m;
+    if(/^B\d+$/.test(tr)){ closeLists(); out.push(tr); continue; }
+    if((m=line.match(/^(#{1,6})\s+(.*)$/))){ closeLists(); const n=m[1].length; out.push(`<h${n} class="cc-h">${_mdInline(m[2])}</h${n}>`); continue; }
+    if(/^\s*([-*_])\s*\1\s*\1\s*$/.test(line)){ closeLists(); out.push('<hr class="cc-hr">'); continue; }
+    if((m=line.match(/^\s*&gt;\s?(.*)$/))){ closeLists(); out.push(`<blockquote class="cc-bq">${_mdInline(m[1])}</blockquote>`); continue; }
+    if((m=line.match(/^\s*[-*+]\s+(.*)$/))){ if(inOl){out.push('</ol>');inOl=false;} if(!inUl){out.push('<ul class="cc-ul">');inUl=true;} out.push(`<li>${_mdInline(m[1])}</li>`); continue; }
+    if((m=line.match(/^\s*\d+\.\s+(.*)$/))){ if(inUl){out.push('</ul>');inUl=false;} if(!inOl){out.push('<ol class="cc-ol">');inOl=true;} out.push(`<li>${_mdInline(m[1])}</li>`); continue; }
+    if(tr===''){ closeLists(); continue; }
+    closeLists(); out.push(`<p class="cc-p">${_mdInline(line)}</p>`);
+  }
+  closeLists();
+  let html=out.join('');
+  html=html.replace(/B(\d+)/g,(m,i)=>blocks[+i]||'');
+  return html;
+}
+/* 把 markdown 结果渲染进回复区(带 .cc-md 容器,关掉 pre-wrap)*/
+export function renderReply(md){
+  const rp=document.getElementById('ccReply');
+  rp.innerHTML='<div class="cc-md">'+renderMarkdown(md)+'</div>';
+  rp.scrollTop=rp.scrollHeight;
+}

package/python/frontend/deck/settings.js

@@ -0,0 +1,324 @@
+import { API } from './state.js';
+
+/* ===== 设置面板 ===== */
+const SETTINGS_TITLE={
+  model:'模型路由',runtime:'运行参数',ui:'界面偏好',data:'数据管理',auth:'访问密钥',about:'关于',
+  'ag-supervisor':'主管 Agent','ag-finance':'财务 Agent','ag-admin':'行政 Agent',
+  'ag-office':'办公 Agent','ag-assistant':'助手 Agent',
+  'mem-backend':'记忆后端','mem-layer':'双层记忆','mem-recall':'召回参数','mem-manage':'记忆管理',
+};
+// 界面偏好(纯前端,存内存)
+export const uiPref={ autoChat:true, ballAnim:false, mapStyle:'light' };  // ballAnim 默认 false(球体特效默认关,省 GPU;需要时手动勾)
+let _sysInfo=null;
+async function fetchSysInfo(){ try{ _sysInfo=await(await fetch(`${API}/system/info`)).json(); }catch(e){ _sysInfo=null; } return _sysInfo; }
+
+async function renderSettingDetail(key){
+  const body=document.getElementById('sdBody');
+  body.innerHTML='<div class="sd-ph">加载中…</div>';
+  // ── Foxclaw 主系统 ──
+  if(key==='model'){
+    const d=await fetchSysInfo(); const m=d?.model||{};
+    let h=`<div class="sd-card"><div class="sd-k">当前模型</div>
+      <div class="sd-big">${(m.provider||'—')} <span>${m.active?m.model:'(降级 stub)'}</span></div></div>`;
+    h+='<div class="sd-sec">可用 Provider · 点击切换<span class="badge edit">可调</span></div>';
+    (m.available_providers||[]).forEach(p=>{
+      const cur=p.provider===m.provider, dis=!p.configured;
+      h+=`<div class="sd-row ${cur?'cur':''} ${dis?'dis':''}" ${dis||cur?'':`onclick="switchProvider('${p.provider}')"`}>
+        <span>${PROVIDER_LABEL[p.provider]?.n||p.provider}<small>${p.default_model}</small></span>
+        <span class="tag">${cur?'当前':dis?'未配置':'可用'}</span></div>`;
+    });
+    h+='<div class="sd-note">模型 Key 在项目根目录 <code>.env</code> 配置,改后重启生效。</div>';
+    body.innerHTML=h;
+  }else if(key==='runtime'){
+    const d=await fetchSysInfo();
+    body.innerHTML=`
+      <div class="sd-sec">运行参数<span class="badge ro">只读</span></div>
+      <div class="sd-ro">
+      <div class="sd-kv"><span>数据目录</span><b>${d?.data_dir||'—'}</b></div>
+      <div class="sd-kv"><span>Harness 影子轮数</span><b>${d?.shadow_rounds??'—'}</b></div>
+      </div>
+      <div class="sd-note">运行参数在 <code>.env</code> 配置(FOXCLAW_DATA_DIR / FOXCLAW_SHADOW_ROUNDS),改后重启生效。影子轮数越小,Harness 越快进入漂移拦截模式。</div>`;
+  }else if(key==='ui'){
+    body.innerHTML=`
+      <div class="sd-sec">界面偏好<span class="badge edit">可调</span></div>
+      <div class="sd-toggle"><span>发任务自动弹中央对话层</span><label class="sw"><input type="checkbox" id="pf-autoChat" ${uiPref.autoChat?'checked':''}><i></i></label></div>
+      <div class="sd-toggle"><span>背景全息球动画</span><label class="sw"><input type="checkbox" id="pf-ballAnim" ${uiPref.ballAnim?'checked':''}><i></i></label></div>
+      <div class="sd-kv2"><span>地图默认样式</span>
+        <select id="pf-mapStyle"><option value="light" ${uiPref.mapStyle==='light'?'selected':''}>亮色(官网风格)</option><option value="dark" ${uiPref.mapStyle==='dark'?'selected':''}>暗色</option></select></div>
+      <div class="sd-note">界面偏好实时生效,保存在当前会话。</div>`;
+    document.getElementById('pf-autoChat').onchange=e=>uiPref.autoChat=e.target.checked;
+    document.getElementById('pf-ballAnim').onchange=e=>{uiPref.ballAnim=e.target.checked; toggleBallAnim(e.target.checked);};
+    document.getElementById('pf-mapStyle').onchange=e=>uiPref.mapStyle=e.target.value;
+  }else if(key==='data'){
+    const s=await(await fetch(`${API}/memory/stats`)).json().catch(()=>({}));
+    body.innerHTML=`
+      <div class="sd-kv"><span>记忆后端</span><b>${s.backend||'—'}</b></div>
+      <div class="sd-kv"><span>记忆总条数</span><b>${s.total_memories??0}</b></div>
+      <div class="sd-kv"><span>知识关系数</span><b>${s.relations??0}</b></div>
+      <div class="sd-note">运行数据存于本地 <code>foxclaw_data/</code> 目录。清空数据请在本地删除该目录后重启(网页端不直接删除,避免误操作)。</div>`;
+  }else if(key==='auth'){
+    const cur=localStorage.getItem('foxclawApiKey')||'';
+    body.innerHTML=`
+      <div class="sd-sec">后端访问密钥<span class="badge ${cur?'ro':'edit'}">${cur?'已配置':'未配置'}</span></div>
+      <div class="sd-desc">后端 <code>.env</code> 若设置了 <code>FOXCLAW_API_KEY</code>,则所有 <code>/api</code>、<code>/knowledge</code> 请求与 WebSocket 都需携带此密钥,否则返回 401/403、数据无法加载。填入与 <code>.env</code> 相同的值即可恢复。</div>
+      <div class="api-key-row">
+        <input type="password" id="pf-apiKey" class="api-key-inp" placeholder="粘贴 FOXCLAW_API_KEY 的值" value="${cur}" autocomplete="off" spellcheck="false">
+      </div>
+      <div class="api-key-btns">
+        <button id="pf-apiKey-save" class="api-key-btn primary">保存并重连</button>
+        <button id="pf-apiKey-clear" class="api-key-btn">清除</button>
+      </div>
+      <div class="sd-note">密钥仅保存在本机浏览器 <code>localStorage</code>,不会上传到服务器。后端未设 <code>FOXCLAW_API_KEY</code> 时此项留空即可(默认开放)。</div>`;
+    document.getElementById('pf-apiKey-save').onclick=()=>{
+      const v=document.getElementById('pf-apiKey').value.trim();
+      if(v) localStorage.setItem('foxclawApiKey', v);
+      else localStorage.removeItem('foxclawApiKey');
+      location.reload();
+    };
+    document.getElementById('pf-apiKey-clear').onclick=()=>{
+      localStorage.removeItem('foxclawApiKey');
+      location.reload();
+    };
+  }else if(key==='about'){
+    const d=await fetchSysInfo();
+    body.innerHTML=`
+      <div class="sd-card"><div class="sd-big">Foxclaw <span>v${d?.version||'1.0.0'}</span></div>
+        <div class="sd-desc">有记忆的个人智能体 · 记忆/认知层与 LLM 解耦</div></div>
+      <div class="sd-sec">五个 Agent</div>
+      <div class="sd-kv"><span>主管 Supervisor</span><b>分诊调度 · 全局态势</b></div>
+      <div class="sd-kv"><span>财务 Finance</span><b>理财 · 风控 · 守门人</b></div>
+      <div class="sd-kv"><span>行政 Admin</span><b>行程 · 路线 · 高德地图</b></div>
+      <div class="sd-kv"><span>办公 Office</span><b>学习 · 知识图谱</b></div>
+      <div class="sd-kv"><span>助手 Assistant</span><b>通用 · Skill 接入</b></div>
+      <div class="sd-sec">三大模块</div>
+      <div class="sd-desc">Foxclaw(主系统) · Agents(五智能体) · HMR(记忆系统)</div>
+      <div class="sd-note">配置说明见项目 <code>docs/配置指南.md</code></div>`;
+  }else if(key && key.startsWith('mem-')){
+    const s=await(await fetch(`${API}/memory/stats`)).json().catch(()=>({}));
+    if(key==='mem-backend'){
+      body.innerHTML=`
+        <div class="sd-card"><div class="sd-big">${s.backend||'HMR'} <span>v${s.version||'—'}</span></div>
+          <div class="sd-desc">分层记忆系统 · 记忆/认知层与 LLM 解耦</div></div>
+        <div class="sd-sec">后端信息<span class="badge ro">只读</span></div>
+        <div class="sd-kv"><span>记忆后端</span><b>${s.backend||'—'}</b></div>
+        <div class="sd-kv"><span>版本</span><b>v${s.version||'—'}</b></div>
+        <div class="sd-kv"><span>Embedding 模型</span><b>${s.embedding||'—'}</b></div>
+        <div class="sd-kv"><span>知识图谱关系数</span><b>${s.relations??0}</b></div>
+        <div class="sd-note">安装 <code>openai</code> 或 <code>sentence-transformers</code> 可启用更精确的语义向量(当前默认 TF-IDF n-gram 降级)。</div>`;
+    }else if(key==='mem-layer'){
+      const ba=s.by_agent||{}; const entries=Object.entries(ba).sort((a,b)=>b[1]-a[1]);
+      let rows=entries.length?entries.map(([a,n])=>`<div class="sd-kv"><span>${AGENT_META[a]?.cn||a}</span><b>${n} 条</b></div>`).join(''):'<div class="sd-desc">暂无分层记忆数据。</div>';
+      body.innerHTML=`
+        <div class="sd-sec">双层记忆架构<span class="badge ro">只读</span></div>
+        <div class="sd-kv"><span>私有层(各 Agent 独立)</span><b>${s.private??0} 条</b></div>
+        <div class="sd-kv"><span>共享层(跨 Agent 可召回)</span><b>${s.shared??0} 条</b></div>
+        <div class="sd-sec">按 Agent 分布<span class="badge ro">只读</span></div>
+        ${rows}
+        <div class="sd-note">私有层:每个 Agent 只能召回自己的记忆;共享层:标记 shared 的记忆所有 Agent 都可召回(如主管的全局决策)。</div>`;
+    }else if(key==='mem-recall'){
+      body.innerHTML=`
+        <div class="sd-sec">召回参数<span class="badge ro">只读</span></div>
+        <div class="sd-kv"><span>默认召回数量 (top-k)</span><b>5</b></div>
+        <div class="sd-kv"><span>相似度阈值</span><b>自适应</b></div>
+        <div class="sd-kv"><span>召回范围</span><b>本 Agent 私有 + 共享层</b></div>
+        <div class="sd-note">召回采用语义向量相似度排序,默认返回最相关的 top-k 条记忆 + 共享层记忆。参数在记忆适配器中定义,随召回质量自调。</div>`;
+    }else if(key==='mem-manage'){
+      body.innerHTML=`
+        <div class="sd-card"><div class="sd-big">${s.total_memories??0} <span>条记忆</span></div>
+          <div class="sd-desc">私有 ${s.private??0} · 共享 ${s.shared??0} · 关系 ${s.relations??0}</div></div>
+        <div class="sd-sec">记忆管理<span class="badge ro">只读</span></div>
+        <div class="sd-kv"><span>记忆总条数</span><b>${s.total_memories??0}</b></div>
+        <div class="sd-kv"><span>知识关系数</span><b>${s.relations??0}</b></div>
+        <div class="sd-note">运行数据存于本地 <code>foxclaw_data/</code> 目录。清空记忆请在本地删除该目录后重启(网页端不直接删除,避免误操作)。导出功能可通过 HMR 后端 API 实现。</div>`;
+    }
+  }else if(key && key.startsWith('ag-')){
+    await renderAgentDetail(key.slice(3), body);
+  }else{
+    body.innerHTML=`<div class="sd-ph">该模块设置开发中</div>`;
+  }
+}
+
+/* 单个 Agent 设置详情(5 个共用 + 领域特定块)*/
+const AGENT_META={
+  supervisor:{cn:'主管',en:'Supervisor',ac:'#ffc24b',role:'分诊调度 · 全局态势编排'},
+  finance:{cn:'财务',en:'Finance',ac:'#00ffb2',role:'理财 · 预算 · 风控守门'},
+  admin:{cn:'行政',en:'Admin',ac:'#ff9d00',role:'行程 · 日程 · 高德地图'},
+  office:{cn:'办公',en:'Office',ac:'#d99a3c',role:'学习 · 知识 · 间隔重复'},
+  assistant:{cn:'助手',en:'Assistant',ac:'#38bdf8',role:'通用任务 · Skill 接入'},
+};
+async function renderAgentDetail(aid, body){
+  const meta=AGENT_META[aid]||{cn:aid,en:aid,ac:'#00d9ff',role:''};
+  let hs=null, sys=null;
+  try{ hs=await(await fetch(`${API}/harness/${aid}/status`)).json(); }catch(e){}
+  try{ sys=await fetchSysInfo(); }catch(e){}
+  const ag=sys?.agents?.[aid]||{};
+  const shadow=ag.shadow_mode, rounds=ag.shadow_rounds??'—', run=ag.run_count??0;
+  const th=hs?.thresholds||{}, w=hs?.weights||{}, pol=hs?.policy||{};
+
+  let h=`<div class="sd-card" style="border-color:${meta.ac}55">
+    <div class="sd-big" style="color:${meta.ac}">${meta.cn} <span>${meta.en}</span></div>
+    <div class="sd-desc">${meta.role}</div></div>`;
+
+  // Harness 漂移检测
+  h+='<div class="sd-sec">Harness 漂移检测<span class="badge ro">只读</span></div>';
+  h+=`<div class="sd-kv"><span>运行模式</span><b style="color:${shadow?'var(--amber)':'var(--green)'}">${shadow?'影子校准中':'已激活拦截'}</b></div>`;
+  h+=`<div class="sd-kv"><span>校准进度</span><b>${run} / ${rounds} 轮</b></div>`;
+  if(th.warn!=null||th.block!=null){
+    h+=`<div class="sd-kv"><span>预警阈值 (WARN)</span><b>${fmt(th.warn)}</b></div>`;
+    h+=`<div class="sd-kv"><span>拦截阈值 (BLOCK)</span><b>${fmt(th.block)}</b></div>`;
+  }
+  if(w.semantic!=null){
+    h+=`<div class="sd-kv"><span>三维权重</span><b>语义 ${fmt(w.semantic)} · 工具 ${fmt(w.tool)} · 范围 ${fmt(w.scope)}</b></div>`;
+  }
+
+  // 守门人 Policy
+  h+='<div class="sd-sec">守门人 Policy<span class="badge ro">只读</span></div>';
+  if(pol.version!=null||pol.total_rules!=null){
+    h+=`<div class="sd-kv"><span>Policy 版本</span><b>v${pol.version??'—'}</b></div>`;
+    h+=`<div class="sd-kv"><span>规则总数</span><b>${pol.total_rules??0}</b></div>`;
+    h+=`<div class="sd-kv"><span>手工规则 / 自学习</span><b>${pol.manual_rules??0} / ${pol.learned_rules??0}</b></div>`;
+  }else{
+    h+='<div class="sd-desc">策略随运行自学习更新,当前无自定义规则覆盖。</div>';
+  }
+
+  // 领域特定块
+  if(aid==='admin'){
+    h+='<div class="sd-sec">高德地图(行政专属)<span class="badge ro">只读</span></div>';
+    const a=sys?.amap||{};
+    h+=`<div class="sd-kv"><span>Web服务 Key(路线/POI)</span><b style="color:${a.web_key?'var(--green)':'var(--ink-faint)'}">${a.web_key?'已配置':'未配置'}</b></div>`;
+    h+=`<div class="sd-kv"><span>JSAPI Key(前端地图)</span><b style="color:${a.js_key?'var(--green)':'var(--ink-faint)'}">${a.js_key?'已配置':'未配置'}</b></div>`;
+    h+=`<div class="sd-kv"><span>JSAPI 安全密钥</span><b style="color:${a.js_scode?'var(--green)':'var(--ink-faint)'}">${a.js_scode?'已配置':'未配置'}</b></div>`;
+    h+=`<div class="sd-toggle"><span>地图默认样式(暗色)</span><label class="sw"><input type="checkbox" id="pf-mapDark2" ${uiPref.mapStyle==='dark'?'checked':''}><i></i></label></div>`;
+    h+='<div class="sd-note">高德三个 Key 在 <code>.env</code> 配置(AMAP_MAPS_API_KEY / AMAP_JS_KEY / AMAP_JS_SCODE)。</div>';
+  }else if(aid==='finance'){
+    h+='<div class="sd-sec">财务领域参数<span class="badge ro">只读</span></div>';
+    h+='<div class="sd-desc">预算阈值、MAD 异常灵敏度、风控规则在财务内核 policy 中定义,随交易数据自学习。守门人对大额/越权操作执行确认或冻结。</div>';
+  }else if(aid==='office'){
+    h+='<div class="sd-sec">学习领域参数<span class="badge ro">只读</span></div>';
+    h+='<div class="sd-desc">采用 SM-2 间隔重复算法管理知识复习节奏;知识图谱关系自动抽取,守门人防止知识污染。</div>';
+  }else if(aid==='supervisor'){
+    h+='<div class="sd-sec">路由编排<span class="badge ro">只读</span></div>';
+    h+='<div class="sd-desc">元问题(介绍/系统级)由主管自答;业务任务按关键词分诊到财务/行政/办公/助手。可在 agents.py 的 ROUTING_KEYWORDS / META_KEYWORDS 调整。</div>';
+  }else if(aid==='assistant'){
+    h+='<div class="sd-sec">Skill 接入<span class="badge ro">只读</span></div>';
+    h+='<div class="sd-desc">通用任务兜底处理,可接入外部 Skill 工具扩展能力。主管无法明确归类的任务默认派给助手。</div>';
+  }
+
+  h+='<div class="sd-note">Agent 行为参数大多在后端 policy 与代码中定义,此处为只读状态展示。漂移阈值由影子校准期自动学习得出。</div>';
+  body.innerHTML=h;
+
+  // 行政地图暗色开关联动
+  const md=document.getElementById('pf-mapDark2');
+  if(md) md.onchange=e=>{ uiPref.mapStyle=e.target.checked?'dark':'light'; };
+}
+function fmt(v){ return (v==null||isNaN(v))?'—':(typeof v==='number'?v.toFixed(3):v); }
+export async function switchProvider(prov){
+  try{ await fetch(`${API}/model/switch`,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({provider:prov})});
+    _sysInfo=null; renderSettingDetail('model'); loadModel(); }catch(e){}
+}
+function toggleBallAnim(on){
+  const c=document.getElementById('coreCanvas'); if(c)c.style.display=on?'block':'none';
+  // 仅 display:none 不够(loop 还在 60fps 跑,吃 GPU)→ 同步设置 localStorage 标志,
+  // 引导用户硬刷一次(自动 reload)。visuals.js 顶部 _lowpower 检查,刷新后即生效。
+  try{ localStorage.setItem('foxclaw_lowpower', on ? '0' : '1'); }catch{}
+  // 仅当「关」才 reload(开不影响,因为持久态 = 0 时不阻止)
+  if (!on) {
+    // 提示一下,避免用户疑惑
+    console.info('[foxclaw] 关掉球动画后需刷新一次才停止 GPU 占用');
+  }
+}
+
+/* 二级子项定义 */
+const SETTINGS_SUBS={
+  foxclaw:[['model','模型路由'],['runtime','运行参数'],['ui','界面偏好'],['data','数据管理'],['auth','访问密钥'],['about','关于']],
+  agents:[['ag-supervisor','主管 Agent'],['ag-finance','财务 Agent'],['ag-admin','行政 Agent'],['ag-office','办公 Agent'],['ag-assistant','助手 Agent']],
+  hmr:[['mem-backend','记忆后端'],['mem-layer','双层记忆'],['mem-recall','召回参数'],['mem-manage','记忆管理']],
+};
+const _setMenu=document.getElementById('setMenu');
+const _smL2=document.getElementById('smL2');
+const _sdPop=document.getElementById('sdPop');
+let _setHideTimer=null;
+
+export function openSetMenu(){ clearTimeout(_setHideTimer); _setMenu.classList.add('show'); }
+/* 直接打开「访问密钥」设置详情(供 main.js 的鉴权提示条调用) */
+export function openAuthSetting(){ _setMenu.classList.add('show'); openDetailPop('auth'); }
+function closeSetMenu(){
+  clearTimeout(_setHideTimer);
+  _setHideTimer=setTimeout(()=>{ _setMenu.classList.remove('show'); _smL2.innerHTML=''; document.querySelectorAll('.sm-l1 .sm-btn').forEach(b=>b.classList.remove('active')); }, 400);
+}
+// 一级悬停 → 展开二级
+function showL2(group, l1btn){
+  document.querySelectorAll('.sm-l1 .sm-btn').forEach(b=>b.classList.remove('active'));
+  l1btn.classList.add('active');
+  _smL2.innerHTML=(SETTINGS_SUBS[group]||[]).map(([k,name])=>
+    `<div class="sm-btn" data-sub="${k}"><b>${name}</b><span class="chev">›</span></div>`).join('');
+  _smL2.querySelectorAll('.sm-btn').forEach(b=>{
+    b.addEventListener('click',()=>openDetailPop(b.dataset.sub));
+  });
+}
+function openDetailPop(key){
+  document.getElementById('sdTitle').textContent=SETTINGS_TITLE[key]||'详情';
+  _sdPop.classList.add('show');
+  renderSettingDetail(key);
+}
+function closeDetailPop(){ _sdPop.classList.remove('show'); }
+
+const _gear=document.getElementById('settingsBtn');
+_gear.addEventListener('mouseenter', openSetMenu);
+_gear.addEventListener('mouseleave', closeSetMenu);
+_gear.addEventListener('click', openSetMenu);
+_setMenu.addEventListener('mouseenter', ()=>clearTimeout(_setHideTimer));
+_setMenu.addEventListener('mouseleave', closeSetMenu);
+document.querySelectorAll('.sm-l1 .sm-btn').forEach(b=>{
+  b.addEventListener('mouseenter', ()=>showL2(b.dataset.group, b));
+});
+document.getElementById('settingsBtn2')?.addEventListener('click', ()=>{ openSetMenu(); clearTimeout(_setHideTimer); });
+document.getElementById('sdClose').addEventListener('click', closeDetailPop);
+
+document.querySelectorAll('.nav-mini, .feed-item').forEach(it=>{
+  it.addEventListener('click',()=>{ it.classList.add('pressed'); setTimeout(()=>it.classList.remove('pressed'),180); });
+});
+
+
+/* ===== 模型选择器 ===== */
+const PROVIDER_LABEL=
+{anthropic:{n:'Claude',c:'#ff9d00'},openai:{n:'GPT',c:'#00ffb2'},
+  google:{n:'Gemini',c:'#38bdf8'},qwen:{n:'通义千问',c:'#ffc24b'},
+  local:{n:'本地模型',c:'#d99a3c'},stub:{n:'Stub 降级',c:'#7e93b8'}};
+async function loadModel(){
+  try{
+    const d=await(await fetch(`${API}/model`)).json();
+    const lbl=PROVIDER_LABEL[d.provider]||{n:d.provider,c:'#7e93b8'};
+    document.getElementById('modelName').textContent=lbl.n;
+    renderModelMenu(d);
+  }catch(e){}
+}
+function renderModelMenu(d){
+  const menu=document.getElementById('modelMenu'); if(!menu)return;
+  let h='<div class="mtitle">模型路由 · 点击切换</div>';
+  (d.available_providers||[]).forEach(p=>{
+    const lbl=PROVIDER_LABEL[p.provider]||{n:p.provider,c:'#7e93b8'};
+    const cur=p.provider===d.provider;
+    const dis=!p.configured;
+    h+=`<div class="model-opt ${cur?'active':''} ${dis?'disabled':''}" data-prov="${p.provider}">
+      <span class="mdot" style="background:${lbl.c};box-shadow:0 0 6px ${lbl.c}"></span>
+      <span class="mname"><b>${lbl.n}</b><span>${p.default_model}</span></span>
+      ${cur?'<span class="mtag">当前</span>':dis?'<span class="mtag" style="background:rgba(255,157,0,.12);color:var(--amber)">未配置</span>':'<span class="mtag">可用</span>'}</div>`;
+  });
+  menu.innerHTML=h;
+  menu.querySelectorAll('.model-opt:not(.disabled):not(.active)').forEach(opt=>{
+    opt.addEventListener('click',async()=>{
+      const prov=opt.dataset.prov;
+      try{await fetch(`${API}/model/switch`,{method:'POST',headers:{'Content-Type':'application/json'},
+        body:JSON.stringify({provider:prov})});
+        menu.classList.remove('show'); loadModel();
+      }catch(e){}
+    });
+  });
+}
+document.getElementById('modelPill').addEventListener('click',e=>{
+  e.stopPropagation();
+  document.getElementById('modelMenu').classList.toggle('show');
+});
+document.addEventListener('click',()=>document.getElementById('modelMenu')?.classList.remove('show'));
+loadModel();

package/python/frontend/deck/state.js

@@ -0,0 +1,6 @@
+/* 跨模块共享:URL 常量 + 内核数据缓存(零构建,显式 live-binding 导出) */
+const _origin=(location.protocol==='http:'||location.protocol==='https:')?location.origin:'http://localhost:8000';
+const API=_origin+'/api';
+const WS=_origin.replace(/^http/,'ws')+'/ws/harness';
+let _lastKernelData={};   // 缓存各 Agent 最近一次内核数据,供全屏复用
+export { _origin, API, WS, _lastKernelData };

package/python/frontend/deck/util.js

@@ -0,0 +1,6 @@
+/* 安全:HTML 转义 —— 模型输出/用户输入/外部数据写入 innerHTML 前必须转义,防 XSS
+   (模型输出不可信,可能被提示注入产出 <img onerror> 等)。*/
+export function escapeHtml(s){
+  return String(s==null?'':s).replace(/[&<>"']/g,c=>(
+    {'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+}

package/python/frontend/deck/visuals.js

@@ -0,0 +1,212 @@
+/* ═══════ 球体特效开关:默认关,需要时手动开 ═══════
+   ─ 手动开(任一即生效):
+     1) URL 加 ?visual=1                            临时(本次会话)
+     2) localStorage.foxclaw_visual = "1"            永久
+     3) 设置 → 界面偏好 → 背景全息球动画 勾选      永久(写 localStorage.foxclaw_lowpower=0,兼容旧 toggle)
+   ─ 系统级默认关(无需操作):
+     4) matchMedia('(prefers-reduced-motion: reduce)').matches
+     5) navigator.connection.saveData === true
+   ─ 默认:true(不启动 4 个 canvas 动画 + 粒子 emit,省 GPU/CPU,启动秒开) */
+const _lowpower = (() => {
+  try {
+    // 显式开:URL / localStorage / 旧版 toggleBallAnim
+    if (new URLSearchParams(location.search).get('visual') === '1') return false;
+    if (localStorage.getItem('foxclaw_visual') === '1') return false;
+    if (localStorage.getItem('foxclaw_lowpower') === '0') return false;   // 兼容旧版开关
+    // 显式关:URL ?low=1 仍生效(应急)
+    if (new URLSearchParams(location.search).get('low') === '1') return true;
+    // 系统级 → 关
+    if (matchMedia('(prefers-reduced-motion: reduce)').matches) return true;
+    if (navigator.connection && navigator.connection.saveData) return true;
+  } catch {}
+  return true;   // ← 默认:不启动(保护 GPU + 启动秒开)
+})();
+window._foxclawLowpower = _lowpower;   // 暴露给其他模块读
+// 暴露切换 API(控制台手动开:  foxclawVisual.on()  /  永久关:  foxclawVisual.off()  /  状态:  foxclawVisual.isOn())
+window.foxclawVisual = {
+  isOn: () => !_lowpower,
+  on()  { try { localStorage.setItem('foxclaw_visual', '1'); } catch{} location.reload(); },
+  off() { try { localStorage.removeItem('foxclaw_visual'); localStorage.setItem('foxclaw_lowpower', '1'); } catch{} location.reload(); },
+  toggle() { this.isOn() ? this.off() : this.on(); },
+};
+if (_lowpower) console.info('[foxclaw] 球体特效已关闭(默认) — 想看动画:控制台跑 foxclawVisual.on() 或 URL 加 ?visual=1');
+function _lpThrottle(fn, fps) {       // 30fps 节流(不关,但降频)— 关闭模式直接 noop
+  if (_lowpower) return () => {};
+  let last = 0; const gap = 1000 / fps;
+  return function(t) { if (t - last >= gap) { last = t; fn(t); } };
+}
+
+/* ====== 中央全息核心 ====== */
+(function(){
+  if (_lowpower) return;        // 省电:不开中央全息核心(520 球面点 + 经纬弧 + 渐变 60fps)
+  const c=document.getElementById('coreCanvas'), x=c.getContext('2d');
+  function size(){const r=c.parentElement.getBoundingClientRect();c.width=r.width;c.height=r.height;}
+  size(); window.addEventListener('resize',size);
+  const N=520, pts=[];
+  for(let i=0;i<N;i++){const t=Math.acos(2*Math.random()-1),p=Math.random()*Math.PI*2;
+    pts.push({t,p});}
+  let rot=0;
+  function loop(){
+    x.clearRect(0,0,c.width,c.height);
+    const cx=c.width/2, cy=c.height/2, R=Math.min(cx,cy)*0.62;
+    rot+=0.0024;
+    // 光环底座
+    for(let k=0;k<3;k++){
+      x.beginPath();
+      x.ellipse(cx,cy+R*0.92,R*(1.05+k*0.18),R*(0.26+k*0.05),0,0,Math.PI*2);
+      x.strokeStyle=`rgba(0,217,255,${0.18-k*0.04})`; x.lineWidth=2; x.stroke();
+    }
+    // 球面点
+    for(const pt of pts){
+      const t=pt.t, p=pt.p+rot;
+      const xx=Math.sin(t)*Math.cos(p), yy=Math.cos(t), zz=Math.sin(t)*Math.sin(p);
+      const sx=cx+xx*R, sy=cy+yy*R;
+      const depth=(zz+1)/2;
+      x.beginPath(); x.arc(sx,sy,depth*1.6+0.3,0,Math.PI*2);
+      const hue=depth>0.5?'0,217,255':'255,194,75';
+      x.fillStyle=`rgba(${hue},${depth*0.85+0.1})`; x.fill();
+    }
+    // 经纬弧
+    x.strokeStyle='rgba(41,243,255,.12)';x.lineWidth=1;
+    for(let m=0;m<6;m++){
+      x.beginPath();
+      for(let a=0;a<=64;a++){const t=a/64*Math.PI, p=m/6*Math.PI*2+rot;
+        const xx=Math.sin(t)*Math.cos(p),yy=Math.cos(t),zz=Math.sin(t)*Math.sin(p);
+        const sx=cx+xx*R,sy=cy+yy*R; a?x.lineTo(sx,sy):x.moveTo(sx,sy);}
+      x.stroke();
+    }
+    // 中央辉光
+    const g=x.createRadialGradient(cx,cy,0,cx,cy,R*0.5);
+    g.addColorStop(0,'rgba(0,217,255,.28)');g.addColorStop(1,'transparent');
+    x.fillStyle=g;x.beginPath();x.arc(cx,cy,R*0.5,0,Math.PI*2);x.fill();
+    requestAnimationFrame(loop);
+  }
+  loop();
+})();
+
+/* ====== 记忆向量空间 ====== */
+(function(){
+  if (_lowpower) return;        // 省电:不开记忆向量空间动画
+  const c=document.getElementById('memCanvas'); if(!c) return;   // 右栏改版后无此装饰画布 → 静默跳过
+  const x=c.getContext('2d');
+  function size(){const r=c.parentElement.getBoundingClientRect();c.width=r.width;c.height=r.height;}
+  size();window.addEventListener('resize',size);
+  const nodes=[];for(let i=0;i<46;i++)nodes.push({x:Math.random(),y:Math.random(),z:Math.random(),s:Math.random()*2+1});
+  let rot=0;
+  function loop(){
+    x.clearRect(0,0,c.width,c.height);rot+=0.005;
+    const cx=c.width/2,cy=c.height/2;
+    nodes.forEach(n=>{
+      const a=n.x*Math.PI*2+rot, rad=(n.y*0.4+0.15)*Math.min(cx,cy);
+      const px=cx+Math.cos(a)*rad, py=cy+Math.sin(a)*rad*0.6+(n.z-0.5)*40;
+      n._x=px;n._y=py;
+      x.beginPath();x.arc(px,py,n.s,0,Math.PI*2);
+      x.fillStyle=n.z>0.5?'rgba(255,194,75,.9)':'rgba(0,217,255,.85)';x.fill();
+    });
+    x.strokeStyle='rgba(255,194,75,.12)';x.lineWidth=.5;
+    for(let i=0;i<nodes.length;i++)for(let j=i+1;j<nodes.length;j++){
+      const dx=nodes[i]._x-nodes[j]._x,dy=nodes[i]._y-nodes[j]._y,d=Math.hypot(dx,dy);
+      if(d<46){x.beginPath();x.moveTo(nodes[i]._x,nodes[i]._y);x.lineTo(nodes[j]._x,nodes[j]._y);x.stroke();}
+    }
+    requestAnimationFrame(loop);
+  }
+  loop();
+})();
+
+/* ====== 中枢数据流:核心球↔Agent 信息流动 ====== */
+(function(){
+  if (_lowpower) return;        // 省电:不开中枢数据流 + 2.2s 粒子 emit
+  const cv=document.getElementById('streamCanvas'); if(!cv)return;
+  const ctx=cv.getContext('2d');
+  const center=document.querySelector('.center');
+  function resize(){ const r=center.getBoundingClientRect(); cv.width=r.width; cv.height=r.height; }
+  resize(); window.addEventListener('resize',resize);
+  function pts(){
+    const cr=center.getBoundingClientRect();
+    const core=document.querySelector('.corewrap');
+    const coreC=core?core.getBoundingClientRect():cr;
+    const origin={x:coreC.left-cr.left+coreC.width/2, y:coreC.top-cr.top+coreC.height/2};
+    const targets=[...document.querySelectorAll('.acard')].map(a=>{
+      const b=a.getBoundingClientRect();
+      return {x:b.left-cr.left+b.width/2, y:b.top-cr.top+b.height/2,
+        color:getComputedStyle(a).getPropertyValue('--ac').trim()||'#00d9ff'};
+    });
+    return {origin,targets};
+  }
+  let particles=[];
+  function emit(targetAgent){
+    const {origin,targets}=pts();
+    if(!targets.length)return;
+    let t;
+    if(targetAgent){
+      // 定向:射向指定 Agent(发任务时用)
+      const cards=[...document.querySelectorAll('.acard')];
+      const idx=cards.findIndex(c=>c.dataset.agent===targetAgent);
+      t=idx>=0?targets[idx]:targets[Math.floor(Math.random()*targets.length)];
+    }else{
+      t=targets[Math.floor(Math.random()*targets.length)];
+    }
+    const reverse=targetAgent?false:Math.random()<0.4;  // 发任务恒为 核心→Agent
+    particles.push({
+      sx:reverse?t.x:origin.x, sy:reverse?t.y:origin.y,
+      ex:reverse?origin.x:t.x, ey:reverse?origin.y:t.y,
+      x:reverse?t.x:origin.x, y:reverse?t.y:origin.y,
+      p:0, speed:0.012+Math.random()*0.01, color:t.color, trail:[]
+    });
+  }
+  window._emitStream=emit;  // 暴露给发任务联动
+  function ease(t){ return t<.5?2*t*t:1-Math.pow(-2*t+2,2)/2; }
+  function hexA(c,a){
+    c=c||'#00d9ff';
+    if(c.startsWith('rgb'))return c.replace(/rgba?\(([^)]+)\)/,(m,p)=>{const v=p.split(',').slice(0,3).join(','); return `rgba(${v},${a})`;});
+    let h=c.replace('#',''); if(h.length===3)h=h.split('').map(x=>x+x).join('');
+    const n=parseInt(h,16); return `rgba(${(n>>16)&255},${(n>>8)&255},${n&255},${a})`;
+  }
+  function loop(){
+    ctx.clearRect(0,0,cv.width,cv.height);
+    particles.forEach(pt=>{
+      pt.p+=pt.speed;
+      pt.x=pt.sx+(pt.ex-pt.sx)*ease(pt.p);
+      pt.y=pt.sy+(pt.ey-pt.sy)*ease(pt.p);
+      pt.trail.push({x:pt.x,y:pt.y}); if(pt.trail.length>14)pt.trail.shift();
+      pt.trail.forEach((tp,i)=>{
+        const a=(i/pt.trail.length)*(1-pt.p)*0.7;
+        ctx.beginPath(); ctx.arc(tp.x,tp.y,1.6,0,7);
+        ctx.fillStyle=hexA(pt.color,a); ctx.fill();
+      });
+      ctx.beginPath(); ctx.arc(pt.x,pt.y,2.4,0,7);
+      ctx.fillStyle=hexA(pt.color,(1-pt.p)*0.9); ctx.shadowBlur=8; ctx.shadowColor=pt.color; ctx.fill(); ctx.shadowBlur=0;
+    });
+    particles=particles.filter(pt=>pt.p<1);
+    requestAnimationFrame(loop);
+  }
+  loop();
+  setInterval(emit, 2200);
+  setTimeout(emit, 800);
+})();
+
+/* ====== 系统活动波形(已移除,保留空值保护)====== */
+(function(){
+  if (_lowpower) return;        // 省电:不开系统活动波形
+  const c=document.getElementById('actCanvas'); if(!c)return;
+  const x=c.getContext('2d');
+  function size(){const r=c.parentElement.getBoundingClientRect();c.width=r.width;c.height=90;}
+  size();window.addEventListener('resize',size);
+  let t=0;
+  function loop(){
+    x.clearRect(0,0,c.width,c.height);t+=0.03;
+    if(window.actPulse>0)window.actPulse*=0.96;
+    const boost=1+(window.actPulse||0);
+    [[ '0,217,255',0],['255,194,75',1.5]].forEach(([col,ph])=>{
+      x.beginPath();
+      for(let i=0;i<=c.width;i+=4){
+        const y=c.height/2+Math.sin(i*0.025+t+ph)*18*boost*Math.sin(i*0.006+t*0.5)+
+          Math.sin(i*0.05+t*1.3+ph)*8*boost;
+        i?x.lineTo(i,y):x.moveTo(i,y);
+      }
+      x.strokeStyle=`rgba(${col},.7)`;x.lineWidth=2;x.shadowBlur=8;x.shadowColor=`rgba(${col},.6)`;x.stroke();x.shadowBlur=0;
+    });
+    requestAnimationFrame(loop);
+  }
+  loop();
+})();