feat: 扩展主题界面适配与 Agent 服务工具

frontend/src/assets/themes/paper-moments.theme

@@ -286,7 +286,7 @@ license: MIT
 
 
 /* Shared paper surfaces across settings, search, agents, media and extensions. */
-[data-theme="paper-moments"] :is(.panel, .item-card, .event-card, .citation-card, .routing-card, .vault-card, .modal-card, .modal, .usage-chart) {
+[data-theme="paper-moments"] :is(.panel, .item-card, .event-card, .citation-card, .routing-card, .vault-card, .modal-card, .modal, .usage-chart, .community-card, .tool-choice, .user-skill-card, .metric-card, .workspace-chat) {
   position: relative;
   border: 1px solid #b5a693;
   border-radius: 8px 14px 8px 8px;
@@ -296,7 +296,7 @@ license: MIT
   background-image: repeating-linear-gradient(transparent 0 31px, #b6c7bd18 31px 32px);
   box-shadow: 3px 4px 0 #d8e6e2, 6px 7px 0 #f0d8cf;
 }
-[data-theme="paper-moments"] :is(.panel, .item-card, .event-card, .citation-card, .routing-card, .vault-card, .modal-card, .modal)::before {
+[data-theme="paper-moments"] :is(.panel, .item-card, .event-card, .citation-card, .routing-card, .vault-card, .modal-card, .modal, .community-card, .tool-choice, .user-skill-card, .metric-card, .workspace-chat)::before {
   content: '';
   position: absolute;
   inset: 0 24px auto auto;
@@ -307,7 +307,7 @@ license: MIT
   background: repeating-linear-gradient(45deg, #c5dfe0b0 0 6px, #daeceba0 6px 12px);
   pointer-events: none;
 }
-[data-theme="paper-moments"] :is(.item-card, .event-card, .citation-card, .routing-card):nth-child(2n)::before {
+[data-theme="paper-moments"] :is(.item-card, .event-card, .citation-card, .routing-card, .community-card, .tool-choice, .user-skill-card, .metric-card):nth-child(2n)::before {
   background: repeating-linear-gradient(45deg, #e7bcb3b0 0 6px, #f2d4cba0 6px 12px);
 }
 [data-theme="paper-moments"] :is(.panel, .item-card, .routing-card, .vault-card) :is(h2, h3, h4) {

frontend/src/components/common/TitleBar.vue

@@ -210,7 +210,7 @@ function toggleFromTitlebar(event: MouseEvent) {
 
   &.close:hover {
     background: var(--color-error);
-    color: white;
+    color: var(--color-on-error);
   }
 }
 

frontend/src/components/common/TitleBarMenu.spec.ts

@@ -55,7 +55,9 @@ describe('桌面顶部段落菜单', () => {
     expect(wrapper.text()).toContain('工作区搜索AI 对话智能体任务音视频')
     expect(wrapper.text()).toContain('Skill 管理Plugin 管理MCP 服务器')
     await wrapper.get('[data-menu="help"] .menu-trigger').trigger('click')
-    expect(wrapper.text()).toContain('运行日志Benchmark 评测社区目录设置与诊断…')
+    expect(wrapper.text()).toContain('运行日志Benchmark 评测社区目录Function Plot 教程设置与诊断…')
+    await wrapper.get('[data-help-function-plot]').trigger('click')
+    expect(routerPush).toHaveBeenCalledWith('/help/function-plot')
     wrapper.unmount()
   })
 

frontend/src/components/common/TitleBarMenu.vue

@@ -332,6 +332,7 @@ onBeforeUnmount(() => {
         <button data-menu-item role="menuitem" @click="navigate('/logs')"><span>{{ t('运行日志', 'Operation logs') }}</span></button>
         <button data-menu-item role="menuitem" @click="navigate('/benchmarks')"><span>{{ t('Benchmark 评测', 'Benchmarks') }}</span></button>
         <button data-menu-item role="menuitem" @click="navigate('/community')"><span>{{ t('社区目录', 'Community catalog') }}</span></button>
+        <button data-help-function-plot data-menu-item role="menuitem" @click="navigate('/help/function-plot')"><span>{{ t('Function Plot 教程', 'Function Plot tutorial') }}</span></button>
         <span class="menu-separator" role="separator" />
         <button data-menu-item role="menuitem" :disabled="!workspace.hasVault" @click="navigate('/settings')"><span>{{ t('设置与诊断…', 'Settings and diagnostics…') }}</span></button>
       </div>

frontend/src/features/agent/labels.ts

@@ -55,11 +55,22 @@ const toolLabels: Record<string, string> = {
   'notes.update': '更新笔记',
   'notes.list': '列出笔记',
   'notes.move': '移动笔记',
+  'notes.rename': '重命名笔记',
+  'notes.delete': '删除笔记',
   'tasks.create': '创建任务',
   'tasks.update': '更新任务',
   'tasks.list': '列出任务',
+  'tasks.read': '读取任务',
+  'tasks.delete': '删除任务',
   'attachments.read': '读取附件',
   'audio.transcribe': '音频转写',
+  'audio.transcription_status': '读取转写结果',
+  'function_plot.compose': '生成函数图',
+  'skills.list': '列出自定义 Skill',
+  'skills.create': '创建自定义 Skill',
+  'skills.update': '更新自定义 Skill',
+  'plugins.list': '列出 Plugin',
+  'plugins.create': '创建声明式 Plugin',
   'text.uppercase': '文本转大写',
 }
 
@@ -76,11 +87,22 @@ const toolDescriptions: Record<string, string> = {
   'notes.update': '更新已有 Markdown 笔记。',
   'notes.list': '按文件夹和标签筛选并列出笔记摘要。',
   'notes.move': '移动笔记到其他文件夹并保留笔记 ID。',
+  'notes.rename': '重命名 Markdown 文件并保留笔记 ID 和索引身份。',
+  'notes.delete': '删除当前知识库中的指定笔记。',
   'tasks.create': '创建并持久化任务。',
   'tasks.update': '更新已有任务。',
   'tasks.list': '列出已持久化的任务。',
+  'tasks.read': '根据任务 ID 读取完整任务。',
+  'tasks.delete': '删除指定的持久化任务。',
   'attachments.read': '读取由宿主管理的 UTF-8 附件。',
   'audio.transcribe': '将音频转写为文本，按模型路由使用 API 或本地后端。',
+  'audio.transcription_status': '读取转写任务状态、文本、分段和错误信息。',
+  'function_plot.compose': '根据表达式生成并校验安全的 function-plot Markdown 代码块。',
+  'skills.list': '列出当前知识库中的自定义 Skill 及依赖状态。',
+  'skills.create': '把提示词、工具和权限声明保存为当前知识库的自定义 Skill。',
+  'skills.update': '使用当前版本号更新自定义 Skill，防止覆盖并发修改。',
+  'plugins.list': '列出已安装 Plugin 及生命周期状态。',
+  'plugins.create': '生成并安装仅使用宿主白名单处理器的声明式 Plugin；创建后需在 Plugin 页面检查并启用。',
   'text.uppercase': '将输入文本中的字母转换为大写。',
 }
 
@@ -105,9 +127,12 @@ const permissionLabels: Record<string, string> = {
   'notes.search': '搜索笔记',
   'notes.read': '读取笔记',
   'notes.write': '修改笔记',
+  'notes.delete': '删除笔记',
   'tasks.read': '读取任务',
   'tasks.write': '修改任务',
   'attachments.read': '读取附件',
+  'skills.write': '创建或更新自定义 Skill',
+  'plugins.write': '创建声明式 Plugin',
   'network.request': '访问网络',
   'secrets.use': '使用密钥',
 }

frontend/src/features/help/FunctionPlotHelpView.spec.ts

@@ -0,0 +1,30 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import FunctionPlotHelpView from './FunctionPlotHelpView.vue'
+
+const render = vi.hoisted(() => vi.fn())
+vi.mock('@/services/functionPlotService', () => ({ renderFunctionPlot: render }))
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  setActivePinia(createPinia())
+  render.mockReset().mockResolvedValue({ svg: '<svg class="function-plot-svg"></svg>', warnings: [], nodeCount: 8 })
+})
+
+describe('Function Plot tutorial', () => {
+  it('documents the fenced syntax and renders the editable example', async () => {
+    const wrapper = mount(FunctionPlotHelpView)
+    expect(wrapper.text()).toContain('Function Plot 教程')
+    expect(wrapper.text()).toContain('domain: -10, 10')
+    expect(wrapper.text()).toContain('sin(x)')
+    expect(wrapper.text()).toContain('最多 16 条表达式')
+    await vi.advanceTimersByTimeAsync(200)
+    await flushPromises()
+    expect(render).toHaveBeenCalledWith(expect.stringContaining('y = sin(x)'), 'light')
+    expect(wrapper.get('.svg-host').html()).toContain('function-plot-svg')
+    wrapper.unmount()
+    vi.useRealTimers()
+  })
+})

frontend/src/features/help/FunctionPlotHelpView.vue

@@ -0,0 +1,139 @@
+<script setup lang="ts">
+import { onBeforeUnmount, ref, watch } from 'vue'
+import { t } from '@/i18n'
+import { useThemeStore } from '@/stores/theme'
+import { renderFunctionPlot } from '@/services/functionPlotService'
+
+const theme = useThemeStore()
+const source = ref(`domain: -6, 6
+range: -2, 8
+xlabel: x
+ylabel: y
+grid: true
+y = sin(x)
+y = x^2 / 5`)
+const svg = ref('')
+const warnings = ref<string[]>([])
+const error = ref('')
+const loading = ref(false)
+let timer: ReturnType<typeof setTimeout> | undefined
+let generation = 0
+
+async function renderPreview() {
+  const current = ++generation
+  loading.value = true
+  error.value = ''
+  try {
+    const result = await renderFunctionPlot(source.value, theme.currentThemeId)
+    if (current !== generation) return
+    svg.value = result.svg
+    warnings.value = result.warnings
+  } catch (cause) {
+    if (current !== generation) return
+    svg.value = ''
+    warnings.value = []
+    error.value = cause instanceof Error ? cause.message : t('函数图渲染失败', 'Function Plot rendering failed')
+  } finally {
+    if (current === generation) loading.value = false
+  }
+}
+
+watch([source, () => theme.currentThemeId], () => {
+  clearTimeout(timer)
+  timer = setTimeout(() => void renderPreview(), 180)
+}, { immediate: true })
+onBeforeUnmount(() => { clearTimeout(timer); generation += 1 })
+</script>
+
+<template>
+  <div class="feature-page function-plot-help">
+    <header class="feature-header">
+      <div>
+        <span class="badge info">Markdown · Function Plot</span>
+        <h1>{{ t('Function Plot 教程', 'Function Plot Tutorial') }}</h1>
+        <p>{{ t('用安全的数学表达式在笔记中绘制静态函数图。预览、HTML 和 PDF 导出使用同一套解析规则。', 'Draw static function graphs in notes with safe mathematical expressions. Preview, HTML, and PDF export share the same parser.') }}</p>
+      </div>
+    </header>
+
+    <div class="tutorial-layout">
+      <main class="tutorial-content">
+        <section class="panel lesson">
+          <span class="step">01</span>
+          <h2>{{ t('插入代码围栏', 'Insert a fenced block') }}</h2>
+          <p>{{ t('语言标记使用 function-plot。每个非空表达式行都绘制一条曲线。', 'Use function-plot as the language tag. Every non-empty expression line draws one curve.') }}</p>
+          <pre><code>```function-plot
+domain: -10, 10
+y = sin(x)
+y = x^2 / 8
+```</code></pre>
+        </section>
+
+        <section class="panel lesson">
+          <span class="step">02</span>
+          <h2>{{ t('设置坐标范围', 'Configure the axes') }}</h2>
+          <div class="directive-grid">
+            <div class="surface-nested"><code>domain: -10, 10</code><span>{{ t('横轴范围', 'X-axis range') }}</span></div>
+            <div class="surface-nested"><code>range: -5, 20</code><span>{{ t('可选纵轴范围', 'Optional Y-axis range') }}</span></div>
+            <div class="surface-nested"><code>xlabel: 时间</code><span>{{ t('横轴名称', 'X-axis label') }}</span></div>
+            <div class="surface-nested"><code>ylabel: 距离</code><span>{{ t('纵轴名称', 'Y-axis label') }}</span></div>
+            <div class="surface-nested"><code>grid: false</code><span>{{ t('显示或隐藏网格', 'Show or hide the grid') }}</span></div>
+          </div>
+        </section>
+
+        <section class="panel lesson">
+          <span class="step">03</span>
+          <h2>{{ t('可用数学语法', 'Supported math syntax') }}</h2>
+          <p>{{ t('支持 +、-、*、/、^，变量 x，常量 pi、e，以及以下单参数函数。2x、2(x+1) 等隐式乘法也可使用。', 'Use +, -, *, /, ^, variable x, constants pi and e, and the single-argument functions below. Implicit multiplication such as 2x and 2(x+1) is also supported.') }}</p>
+          <div class="tag-list function-list">
+            <code v-for="name in ['sin', 'cos', 'tan', 'asin', 'acos', 'atan', 'sinh', 'cosh', 'tanh', 'exp', 'log', 'ln', 'log10', 'log2', 'sqrt', 'abs']" :key="name">{{ name }}(x)</code>
+          </div>
+          <p class="notice-banner safety-note">{{ t('表达式由白名单解析器计算，不执行 JavaScript、Python、属性访问或任意函数调用。单个图块最多 16 条表达式。', 'Expressions are evaluated by an allowlist parser. JavaScript, Python, property access, and arbitrary calls are never executed. Each plot supports up to 16 expressions.') }}</p>
+        </section>
+      </main>
+
+      <aside class="panel playground">
+        <div class="playground-heading"><div><span class="step">04</span><h2>{{ t('即时练习', 'Try it live') }}</h2></div><span v-if="loading" class="badge">{{ t('渲染中', 'Rendering') }}</span></div>
+        <label class="field">
+          <span>{{ t('函数图源码', 'Function Plot source') }}</span>
+          <textarea v-model="source" class="textarea plot-source" spellcheck="false" />
+        </label>
+        <div class="plot-preview" :aria-busy="loading">
+          <div v-if="svg" class="svg-host" v-html="svg" />
+          <div v-else class="empty-state"><strong>{{ t('暂无预览', 'No preview') }}</strong><span>{{ error || t('输入有效表达式后会在这里显示。', 'Enter a valid expression to render it here.') }}</span></div>
+        </div>
+        <div v-if="error" class="error-banner" role="alert">{{ error }}</div>
+        <ul v-if="warnings.length" class="warning-list">
+          <li v-for="warning in warnings" :key="warning">{{ warning }}</li>
+        </ul>
+        <p class="subtle">{{ t('也可以在智能体中启用 function_plot.compose，让 Agent 生成并校验同样的代码块。', 'Enable function_plot.compose in an Agent to generate and validate the same fenced block.') }}</p>
+      </aside>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.function-plot-help { container-type: inline-size; }
+.feature-header h1 { margin-top: var(--space-sm); }
+.tutorial-layout { display: grid; grid-template-columns: minmax(0, 1.15fr) minmax(340px, .85fr); gap: var(--space-lg); max-width: 1180px; margin-inline: auto; align-items: start; }
+.tutorial-content { display: grid; gap: var(--space-lg); }
+.lesson { position: relative; display: grid; gap: var(--space-md); }
+.step { color: var(--color-accent-primary); font: 700 var(--font-size-xs)/1 var(--font-ui-mono); letter-spacing: .12em; }
+.lesson p { color: var(--color-text-secondary); line-height: var(--line-height-relaxed); }
+pre { overflow: auto; padding: var(--space-lg); border: 1px solid var(--color-code-border); border-radius: var(--radius-md); background: var(--color-code-background); color: var(--color-code-text); }
+code { font-family: var(--font-ui-mono); }
+.directive-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(190px, 1fr)); gap: var(--space-sm); }
+.directive-grid > div { display: grid; gap: var(--space-xs); padding: var(--space-md); }
+.directive-grid span { color: var(--color-text-secondary); font-size: var(--font-size-sm); }
+.function-list code { padding: 5px 8px; border: 1px solid var(--color-border-subtle); border-radius: var(--radius-sm); background: var(--color-background-secondary); color: var(--color-accent-primary); }
+.safety-note { margin: 0; }
+.playground { position: sticky; top: var(--space-lg); display: grid; gap: var(--space-md); }
+.playground-heading, .playground-heading > div { display: flex; align-items: center; justify-content: space-between; gap: var(--space-sm); }
+.playground-heading > div { justify-content: flex-start; }
+.plot-source { min-height: 190px; font-family: var(--font-ui-mono); }
+.plot-preview { min-height: 280px; overflow: auto; border: 1px solid var(--color-border-default); border-radius: var(--radius-md); background: var(--color-plot-background); }
+.svg-host { min-width: 620px; line-height: 0; }
+.svg-host :deep(svg) { display: block; width: 100%; height: auto; }
+.plot-preview .empty-state { min-height: 278px; border: 0; border-radius: 0; }
+.warning-list { display: grid; gap: var(--space-xs); color: var(--color-warning); font-size: var(--font-size-sm); }
+@container (max-width: 860px) { .tutorial-layout { grid-template-columns: 1fr; } .playground { position: static; } }
+</style>

frontend/src/features/plugins/PluginSettingsPanel.vue

@@ -355,7 +355,7 @@ watch(() => props.pluginId, load)
   height: 18px;
   border-radius: 50%;
   background: var(--color-text-inverse);
-  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+  box-shadow: 0 1px 3px color-mix(in srgb, var(--color-text-primary) 20%, transparent);
   transition: transform var(--motion-fast);
 }
 

frontend/src/features/settings/ProviderLogo.vue

@@ -17,8 +17,8 @@ const source = computed(() => {
 </template>
 
 <style scoped>
-.provider-logo { display: inline-flex; flex: 0 0 28px; align-items: center; justify-content: center; width: 28px; height: 28px; border-radius: 7px; background: #fff; color: #252b36; }
+.provider-logo { display: inline-flex; flex: 0 0 28px; align-items: center; justify-content: center; width: 28px; height: 28px; border: 1px solid var(--color-border-subtle); border-radius: 7px; background: var(--color-brand-surface); color: var(--color-brand-ink); }
 img { display: block; object-fit: contain; }
-.dark-logo { background: #111; }
+.dark-logo { background: var(--color-brand-surface-dark); }
 .custom-logo { font-size: 23px; line-height: 1; }
 </style>

frontend/src/features/settings/UsageChart.vue

@@ -90,7 +90,7 @@ const maximum = computed(() => Math.max(1, ...props.buckets.flatMap(bucket => so
 <style scoped>
 .usage-bar.stacked { display: flex; flex-direction: column-reverse; background: transparent; overflow: hidden; }
 .model-segment { width: 100%; flex-shrink: 0; border-top: 1px solid var(--color-surface-primary); box-sizing: border-box; }
-.api .model-segment { background-image: repeating-linear-gradient(45deg, transparent 0 4px, #ffffff30 4px 7px); }
+.api .model-segment { background-image: repeating-linear-gradient(45deg, transparent 0 4px, var(--color-highlight-overlay) 4px 7px); }
 .model-legend { display: flex; gap: 12px; flex-wrap: wrap; font-size: 11px; margin-top: 14px; }.model-legend span { display: inline-flex; align-items: center; gap: 5px; overflow-wrap: anywhere; }.model-legend i { width: 12px; height: 12px; border-radius: 2px; flex-shrink: 0; }.model-readout { display: block; }
 
 .chart-layout { display: grid; grid-template-columns: minmax(0, 2fr) minmax(220px, 1fr); gap: 24px; margin-top: 16px; }

frontend/src/features/skills/UserSkillEditor.vue

@@ -9,7 +9,7 @@ import { computed, reactive, ref, watch } from 'vue'
 
 const permissions = [
   'notes.read', 'notes.search', 'notes.write', 'notes.delete', 'tasks.read', 'tasks.write',
-  'attachments.read', 'network.request', 'secrets.use', 'ui.command', 'ui.settings', 'ui.sidebar',
+  'attachments.read', 'skills.write', 'plugins.write', 'network.request', 'secrets.use', 'ui.command', 'ui.settings', 'ui.sidebar',
 ]
 const capabilities = [
   'chat', 'vision', 'tool_calling', 'reasoning', 'streaming', 'structured_output',

frontend/src/features/tasks/TasksView.vue

@@ -68,7 +68,7 @@ async function remove(task: TaskItem) {
 .task-card { display: grid; grid-template-columns: auto 1fr auto; align-items: center; gap: var(--space-md); }
 .status-check { width: 28px; height: 28px; border: 2px solid var(--color-border-default); border-radius: var(--radius-full); transition: border-color var(--motion-fast), background-color var(--motion-fast), color var(--motion-fast), transform var(--motion-fast); }
 .status-check:hover { border-color: var(--color-success); transform: scale(1.06); }
-.status-check.done { border-color: var(--color-success); background: var(--color-success); color: white; box-shadow: 0 3px 10px color-mix(in srgb, var(--color-success) 24%, transparent); }
+.status-check.done { border-color: var(--color-success); background: var(--color-success); color: var(--color-on-success); box-shadow: 0 3px 10px color-mix(in srgb, var(--color-success) 24%, transparent); }
 .task-title { display: flex; align-items: center; flex-wrap: wrap; gap: var(--space-sm); }
 .task-content p { margin: var(--space-xs) 0; }
 .task-content .subtle { display: flex; flex-wrap: wrap; gap: var(--space-md); }

frontend/src/router/index.ts

@@ -6,6 +6,7 @@ const routes = [
   { path: '/community', name: 'community', component: () => import('@/features/community/CommunityView.vue'), meta: { title: '社区目录' } },
   { path: '/benchmarks', name: 'benchmarks', component: () => import('@/features/benchmarks/BenchmarkView.vue'), meta: { title: 'Benchmark' } },
   { path: '/logs', name: 'logs', component: () => import('@/features/logs/LogsView.vue'), meta: { title: '运行日志' } },
+  { path: '/help/function-plot', name: 'function-plot-help', component: () => import('@/features/help/FunctionPlotHelpView.vue'), meta: { title: 'Function Plot 教程' } },
   { path: '/media', name: 'media', component: () => import('@/features/media/MediaView.vue'), meta: { title: '音视频转写', requiresVault: true } },
   {
     path: '/',
@@ -97,6 +98,7 @@ export function updateDocumentTitle(to = router.currentRoute.value) {
   const baseTitle = 'OpenNexus'
   const titles: Record<string, string> = {
     logs: t('运行日志', 'Operation logs'),
+    'function-plot-help': t('Function Plot 教程', 'Function Plot Tutorial'),
     media: t('音视频转写', 'Media Transcription'),
     'vault-entry': t('选择知识库', 'Select Knowledge Base'),
     workspace: t('工作区', 'Workspace'),

frontend/src/services/themePackageService.ts

@@ -6,6 +6,25 @@ import { isMap, parseDocument } from 'yaml'
 
 export const THEME_APP_VERSION = appPackage.version
 
+/**
+ * Semantic colors every page and component may consume. Theme packages can
+ * override any subset; the compatibility layer supplies the rest.
+ */
+export const REQUIRED_THEME_COLOR_TOKENS = [
+  'background-primary', 'background-secondary', 'background-tertiary', 'background-hover', 'background-active', 'background-overlay',
+  'surface-primary', 'surface-secondary', 'surface-elevated',
+  'text-primary', 'text-secondary', 'text-tertiary', 'text-inverse', 'text-link', 'text-disabled',
+  'accent-primary', 'accent-primary-hover', 'accent-primary-active', 'accent-secondary', 'accent-soft', 'accent-soft-hover',
+  'success', 'success-soft', 'warning', 'warning-soft', 'error', 'error-soft', 'info', 'info-soft',
+  'border-default', 'border-subtle', 'border-focus', 'border-disabled',
+  'markdown-selection', 'markdown-grid', 'markdown-marker', 'markdown-table-header',
+  'editor-scroll-background', 'editor-scroll-text',
+  'callout-info', 'callout-success', 'callout-warning', 'callout-danger', 'callout-important', 'callout-quote',
+  'plot-background', 'plot-text', 'plot-axis', 'plot-grid',
+  'plot-curve-0', 'plot-curve-1', 'plot-curve-2', 'plot-curve-3', 'plot-curve-4', 'plot-curve-5',
+  'on-error', 'on-success', 'brand-surface', 'brand-ink', 'brand-surface-dark', 'highlight-overlay',
+] as const
+
 const STORAGE_KEY = 'installed-themes'
 const ACTIVE_CUSTOM_KEY = 'active-custom-theme'
 export const MAX_THEME_BYTES = 5 * 1024 * 1024
@@ -159,6 +178,47 @@ function applyThemeCss(themeId: string, css: string) {
   styleEl.textContent = css
 }
 
+const THEME_CONTRACT_MARKER = '/* opennexus-theme-contract */'
+
+/** Fill incomplete third-party themes with an accessible semantic palette. */
+export function withThemeContract(themeId: string, isDark: boolean, css: string): string {
+  if (css.includes(THEME_CONTRACT_MARKER)) return css
+  const selector = `[data-theme="${themeId}"]`
+  const base = isDark ? {
+    bg: '#0d1117', bg2: '#161b22', bg3: '#21262d', hover: '#1f2630', active: '#2d333b', overlay: '#000000a6',
+    surface: '#161b22', surface2: '#0d1117', elevated: '#1c2128', text: '#e6edf3', text2: '#9ba6b2', text3: '#768390', inverse: '#0d1117', disabled: '#58616b',
+    accent: '#7d8bff', accentHover: '#909cff', soft: '#1e2352', border: '#30363d', subtle: '#21262d',
+    success: '#3fb950', successSoft: '#033a16', warning: '#d29922', warningSoft: '#4d3a00', error: '#f85149', errorSoft: '#5c1318', info: '#58a6ff', infoSoft: '#051d4d',
+    calloutInfo: '#8bbdff', calloutSuccess: '#80ce93', calloutWarning: '#efc66f', calloutDanger: '#ff9b9b', calloutImportant: '#c8a5ff', calloutQuote: '#abb6c2',
+    curves: ['#79c0ff', '#ff9b9b', '#7ee787', '#d2a8ff', '#f2cc60', '#ffa657'],
+  } : {
+    bg: '#ffffff', bg2: '#f7f8fa', bg3: '#eef0f3', hover: '#f0f2f5', active: '#e4e7eb', overlay: '#00000073',
+    surface: '#ffffff', surface2: '#fafbfc', elevated: '#ffffff', text: '#1f2328', text2: '#656d76', text3: '#7b838c', inverse: '#ffffff', disabled: '#9aa0a8',
+    accent: '#5b67f1', accentHover: '#4a55e0', soft: '#eef0ff', border: '#d8dce2', subtle: '#e9ebef',
+    success: '#2da44e', successSoft: '#dafbe3', warning: '#9a6700', warningSoft: '#fff5c2', error: '#cf222e', errorSoft: '#ffebe9', info: '#0969da', infoSoft: '#ddf4ff',
+    calloutInfo: '#175da6', calloutSuccess: '#236b3b', calloutWarning: '#855700', calloutDanger: '#ad2935', calloutImportant: '#7443ad', calloutQuote: '#59636e',
+    curves: ['#0969da', '#d1242f', '#1a7f37', '#8250df', '#9a6700', '#bc4c00'],
+  }
+  return `${THEME_CONTRACT_MARKER}
+${selector} {
+  color-scheme: ${isDark ? 'dark' : 'light'};
+  --color-background-primary: ${base.bg}; --color-background-secondary: ${base.bg2}; --color-background-tertiary: ${base.bg3};
+  --color-background-hover: ${base.hover}; --color-background-active: ${base.active}; --color-background-overlay: ${base.overlay};
+  --color-surface-primary: ${base.surface}; --color-surface-secondary: ${base.surface2}; --color-surface-elevated: ${base.elevated};
+  --color-text-primary: ${base.text}; --color-text-secondary: ${base.text2}; --color-text-tertiary: ${base.text3}; --color-text-inverse: ${base.inverse}; --color-text-link: var(--color-accent-primary); --color-text-disabled: ${base.disabled};
+  --color-accent-primary: ${base.accent}; --color-accent-primary-hover: ${base.accentHover}; --color-accent-primary-active: color-mix(in srgb, var(--color-accent-primary) 80%, var(--color-text-primary)); --color-accent-secondary: var(--color-accent-primary); --color-accent-soft: ${base.soft}; --color-accent-soft-hover: color-mix(in srgb, var(--color-accent-soft) 80%, var(--color-accent-primary));
+  --color-success: ${base.success}; --color-success-soft: ${base.successSoft}; --color-warning: ${base.warning}; --color-warning-soft: ${base.warningSoft}; --color-error: ${base.error}; --color-error-soft: ${base.errorSoft}; --color-info: ${base.info}; --color-info-soft: ${base.infoSoft};
+  --color-border-default: ${base.border}; --color-border-subtle: ${base.subtle}; --color-border-focus: var(--color-accent-primary); --color-border-disabled: var(--color-border-subtle);
+  --color-markdown-selection: color-mix(in srgb, var(--color-accent-primary) 24%, var(--color-background-primary)); --color-markdown-grid: var(--color-border-default); --color-markdown-marker: var(--color-text-secondary); --color-markdown-table-header: var(--color-background-tertiary);
+  --color-editor-scroll-background: var(--color-surface-elevated); --color-editor-scroll-text: var(--color-accent-primary);
+  --color-callout-info: ${base.calloutInfo}; --color-callout-success: ${base.calloutSuccess}; --color-callout-warning: ${base.calloutWarning}; --color-callout-danger: ${base.calloutDanger}; --color-callout-important: ${base.calloutImportant}; --color-callout-quote: ${base.calloutQuote};
+  --color-plot-background: var(--color-surface-primary); --color-plot-text: var(--color-text-primary); --color-plot-axis: var(--color-text-secondary); --color-plot-grid: var(--color-border-default);
+  --color-plot-curve-0: ${base.curves[0]}; --color-plot-curve-1: ${base.curves[1]}; --color-plot-curve-2: ${base.curves[2]}; --color-plot-curve-3: ${base.curves[3]}; --color-plot-curve-4: ${base.curves[4]}; --color-plot-curve-5: ${base.curves[5]};
+  --color-on-error: #ffffff; --color-on-success: #ffffff; --color-brand-surface: #ffffff; --color-brand-ink: #252b36; --color-brand-surface-dark: #111111; --color-highlight-overlay: #ffffff30;
+}
+${css}`
+}
+
 function removeThemeCss(themeId: string) {
   const styleEl = document.getElementById(`theme-style-${themeId}`)
   if (styleEl) styleEl.remove()
@@ -294,7 +354,7 @@ export async function installTheme(
   const idx = existing.findIndex((t) => t.theme_id === manifest.theme_id)
   if (idx >= 0) existing[idx] = installed
   else existing.push(installed)
-  localStorage.setItem(`${STORAGE_KEY}-css-${manifest.theme_id}`, cssContent)
+  localStorage.setItem(`${STORAGE_KEY}-css-${manifest.theme_id}`, withThemeContract(manifest.theme_id, manifest.is_dark, cssContent))
   saveThemes(existing)
   return installed
 }
@@ -345,7 +405,9 @@ export function setActiveCustomTheme(themeId: string | null) {
     if (!theme) throw new Error('THEME_PACKAGE_NOT_FOUND')
     validateManifest(theme.manifest as unknown as Record<string, unknown>)
   }
-  const css = themeId ? localStorage.getItem(`${STORAGE_KEY}-css-${themeId}`) : null
+  const theme = themeId ? loadStoredThemes().find(item => item.theme_id === themeId) : undefined
+  const storedCss = themeId ? localStorage.getItem(`${STORAGE_KEY}-css-${themeId}`) : null
+  const css = themeId && theme && storedCss ? withThemeContract(themeId, theme.is_dark, storedCss) : storedCss
   // Validate before changing the current page. Only the selected theme owns a style node.
   if (css) validateCssSafety(css)
   document.head.querySelectorAll('style[id^="theme-style-"]').forEach(style => style.remove())
@@ -458,10 +520,10 @@ export async function installCommunityTheme(themeId: string): Promise<InstalledT
 }
 
 export function getCommunityThemePreviewCss(themeId: string): string {
-  if (themeId === 'paper-moments') return paperMoments.css
+  if (themeId === 'paper-moments') return withThemeContract(themeId, false, paperMoments.css)
   const t = mockCommunityThemes.find((m) => m.theme_id === themeId)
   if (!t) return ''
-  return buildCommunityThemeCss(themeId, t.is_dark) + `
+  return withThemeContract(themeId, t.is_dark, buildCommunityThemeCss(themeId, t.is_dark) + `
 [data-theme="${themeId}"] {
   color-scheme: ${t.is_dark ? 'dark' : 'light'};
   --color-markdown-selection: ${t.is_dark ? '#443252' : '#d4eaf5'};
@@ -483,5 +545,5 @@ export function getCommunityThemePreviewCss(themeId: string): string {
   --color-markdown-grid: var(--color-border-default);
   --color-markdown-marker: var(--color-text-secondary);
   --color-markdown-table-header: var(--color-background-tertiary);
-}`
+}`)
 }

frontend/src/style.css

@@ -1,70 +0,0 @@
-:root {
-  font-family: Inter, "PingFang SC", "Microsoft YaHei", system-ui, sans-serif;
-  color: #20211f;
-  background: #f4f1e9;
-  font-synthesis: none;
-  text-rendering: optimizeLegibility;
-  --ink: #20211f;
-  --muted: #77776f;
-  --paper: #fffdf7;
-  --line: #dedbd0;
-  --accent: #e76f3d;
-  --success: #307b59;
-}
-
-* { box-sizing: border-box; }
-body { margin: 0; min-width: 320px; min-height: 100vh; }
-button { font: inherit; }
-
-.app-shell { display: grid; grid-template-columns: 240px 1fr; min-height: 100vh; }
-.sidebar {
-  display: flex; flex-direction: column; padding: 28px 20px;
-  color: #f8f5ed; background: #20211f;
-}
-.brand { display: flex; align-items: center; gap: 12px; margin-bottom: 48px; font-weight: 700; }
-.brand-mark {
-  display: grid; place-items: center; width: 32px; height: 32px;
-  border-radius: 10px; color: #20211f; background: #f2c14e;
-}
-nav { display: grid; gap: 6px; }
-.nav-item {
-  padding: 11px 14px; border: 0; border-radius: 8px; text-align: left;
-  color: #bcbdb7; background: transparent;
-}
-.nav-item.active { color: white; background: #343632; }
-.nav-item:disabled { cursor: not-allowed; opacity: .55; }
-.sidebar-hint { margin-top: auto; color: #8f918a; font-size: 13px; }
-
-.workspace { padding: 64px clamp(28px, 6vw, 88px); }
-.workspace header { max-width: 720px; margin-bottom: 42px; }
-.eyebrow, .card-label { margin: 0 0 10px; color: var(--accent); font-size: 12px; font-weight: 800; letter-spacing: .14em; }
-h1 { margin: 0; font-family: Georgia, "Noto Serif SC", serif; font-size: clamp(42px, 7vw, 76px); line-height: 1; letter-spacing: -.045em; }
-.subtitle { max-width: 580px; margin: 20px 0 0; color: var(--muted); font-size: 17px; line-height: 1.7; }
-.cards { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px; max-width: 960px; }
-.card { min-height: 180px; padding: 28px; border: 1px solid var(--line); border-radius: 18px; background: var(--paper); box-shadow: 0 12px 40px rgb(46 43 36 / 6%); }
-.hero-card { grid-column: 1 / -1; display: grid; grid-template-columns: 1fr auto; gap: 22px; align-items: center; }
-.card h2 { margin: 0 0 12px; font-size: 21px; }
-.card p { color: var(--muted); line-height: 1.6; }
-.status-line { display: flex; align-items: center; gap: 12px; min-width: 250px; }
-.status-line p { margin: 3px 0 0; font-size: 13px; }
-.status-dot { width: 10px; height: 10px; border-radius: 50%; background: #aaa; box-shadow: 0 0 0 5px rgb(120 120 120 / 10%); }
-.status-line.success .status-dot { background: var(--success); box-shadow: 0 0 0 5px rgb(48 123 89 / 12%); }
-.status-line.error .status-dot { background: #b84737; box-shadow: 0 0 0 5px rgb(184 71 55 / 12%); }
-.primary-button {
-  justify-self: end; padding: 10px 16px; border: 0; border-radius: 9px;
-  color: white; background: var(--ink); cursor: pointer;
-}
-.primary-button:disabled { cursor: wait; opacity: .6; }
-
-@media (max-width: 720px) {
-  .app-shell { grid-template-columns: 1fr; }
-  .sidebar { min-height: auto; padding: 18px 20px; }
-  .brand { margin-bottom: 18px; }
-  nav { grid-template-columns: repeat(4, 1fr); }
-  .nav-item { padding: 9px 6px; text-align: center; font-size: 13px; }
-  .sidebar-hint { display: none; }
-  .workspace { padding-top: 42px; }
-  .cards { grid-template-columns: 1fr; }
-  .hero-card { display: grid; grid-column: auto; }
-  .primary-button { justify-self: start; }
-}

frontend/src/styles/callouts.css

@@ -4,7 +4,7 @@
   border: 1px solid color-mix(in srgb, var(--callout-color) 35%, transparent);
   border-inline-start: 4px solid var(--callout-color);
   border-radius: var(--radius-md, 8px);
-  background: color-mix(in srgb, var(--callout-color) 8%, var(--color-surface-primary, var(--paper, #fffdf7)));
+  background: color-mix(in srgb, var(--callout-color) 8%, var(--color-surface-primary));
   color: var(--color-text-primary, var(--ink, inherit));
   margin: 12px 0; padding: 12px 16px; min-width: 0;
 }

frontend/src/styles/themeCoverage.spec.ts

@@ -2,7 +2,7 @@
 import { readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { expect, it } from 'vitest'
-import { getCommunityThemePreviewCss, mockCommunityThemes } from '@/services/themePackageService'
+import { getCommunityThemePreviewCss, mockCommunityThemes, REQUIRED_THEME_COLOR_TOKENS, withThemeContract } from '@/services/themePackageService'
 const root = join(process.cwd(), 'src')
 const files = Object.fromEntries(readdirSync(root, { recursive: true }).map(String).filter(path => /\.(vue|css|ts|theme)$/.test(path)).map(path => [path, readFileSync(join(root, path), 'utf8')]))
 it('resolves semantic style token references throughout the component source tree', () => {
@@ -17,12 +17,28 @@ it('resolves semantic style token references throughout the component source tre
 })
 it.each(mockCommunityThemes)('provides interaction and Markdown colors in $theme_id', theme => {
   const css = getCommunityThemePreviewCss(theme.theme_id)
-  for (const token of ['accent-primary-active', 'accent-soft-hover', 'border-focus', 'text-inverse', 'markdown-grid', 'markdown-marker', 'markdown-table-header']) {
+  for (const token of REQUIRED_THEME_COLOR_TOKENS) {
     expect(css).toContain(`--color-${token}:`)
   }
   expect(css).toContain(`color-scheme: ${theme.is_dark ? 'dark' : 'light'}`)
 })
 
+it.each([false, true])('fills an incomplete custom theme with the complete semantic contract (dark=%s)', isDark => {
+  const css = withThemeContract('minimal', isDark, '[data-theme="minimal"] { --color-accent-primary: hotpink; }')
+  for (const token of REQUIRED_THEME_COLOR_TOKENS) expect(css).toContain(`--color-${token}:`)
+  expect(css).toContain(`color-scheme: ${isDark ? 'dark' : 'light'}`)
+  expect(css.endsWith('--color-accent-primary: hotpink; }')).toBe(true)
+})
+
+it('keeps page and component styles on semantic colors', () => {
+  const rawColors: string[] = []
+  for (const [path, source] of Object.entries(files)) {
+    if (!path.endsWith('.vue') || path.endsWith('.spec.ts') || path.includes('features/themes/ThemesView.vue') || path.includes('features\\themes\\ThemesView.vue')) continue
+    for (const match of source.matchAll(/(?:#[\da-f]{3,8}|rgba?\([^)]*\))/gi)) rawColors.push(`${path}: ${match[0]}`)
+  }
+  expect(rawColors).toEqual([])
+})
+
 const calloutThemes = ['light', 'dark', 'sepia', ...mockCommunityThemes.map(theme => theme.theme_id)]
 const calloutTones = ['info', 'success', 'warning', 'danger', 'important', 'quote']
 it.each(calloutThemes)('keeps callout headings readable against tinted surfaces in %s', themeId => {

frontend/src/styles/tokens.css

@@ -47,6 +47,12 @@
   --color-error-soft: #ffebe9;
   --color-info: #0969da;
   --color-info-soft: #ddf4ff;
+  --color-on-error: #ffffff;
+  --color-on-success: #ffffff;
+  --color-brand-surface: #ffffff;
+  --color-brand-ink: #252b36;
+  --color-brand-surface-dark: #111111;
+  --color-highlight-overlay: #ffffff30;
 
   /* Border */
   --color-border-default: #e4e7eb;
@@ -128,6 +134,7 @@
 }
 
 [data-theme='light'] {
+  color-scheme: light;
   --color-callout-info: #175da6;
   --color-callout-success: #236b3b;
   --color-callout-warning: #855700;
@@ -193,6 +200,7 @@
 }
 
 [data-theme='sepia'] {
+  color-scheme: light;
   --color-callout-info: #396578;
   --color-callout-success: #496b3b;
   --color-callout-warning: #805918;