diff --git a/apps/admin-web/src/components/KnowledgeGroupSelect.vue b/apps/admin-web/src/components/KnowledgeGroupSelect.vue
new file mode 100644
index 0000000..6e4547a
--- /dev/null
+++ b/apps/admin-web/src/components/KnowledgeGroupSelect.vue
@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import { useQuery } from "@tanstack/vue-query";
+import type { KnowledgeGroup } from "@geo/shared-types";
+import { computed } from "vue";
+
+import { knowledgeApi } from "@/lib/api";
+
+interface TreeNode {
+  title: string;
+  value: number;
+  key: number;
+  children?: TreeNode[];
+}
+
+const props = withDefaults(
+  defineProps<{
+    modelValue?: number[];
+    placeholder?: string;
+    disabled?: boolean;
+  }>(),
+  {
+    modelValue: () => [],
+    placeholder: "请选择知识库分组",
+    disabled: false,
+  },
+);
+
+const emit = defineEmits<{
+  "update:modelValue": [value: number[]];
+}>();
+
+const groupsQuery = useQuery({
+  queryKey: ["knowledge", "groups", "selector"],
+  queryFn: () => knowledgeApi.listGroups(),
+});
+
+const treeData = computed(() => (groupsQuery.data.value ?? []).map((item) => toTreeNode(item)));
+
+function toTreeNode(group: KnowledgeGroup): TreeNode {
+  return {
+    title: `${group.name}${group.item_count > 0 ? ` (${group.item_count})` : ""}`,
+    value: group.id,
+    key: group.id,
+    children: (group.children ?? []).map((item) => toTreeNode(item)),
+  };
+}
+
+function handleChange(values: Array<string | number>): void {
+  emit(
+    "update:modelValue",
+    values
+      .map((item) => Number(item))
+      .filter((item) => Number.isFinite(item) && item > 0),
+  );
+}
+</script>
+
+<template>
+  <a-tree-select
+    :value="modelValue"
+    :tree-data="treeData"
+    tree-checkable
+    tree-default-expand-all
+    multiple
+    show-search
+    allow-clear
+    size="large"
+    style="width: 100%"
+    :placeholder="placeholder"
+    :disabled="disabled"
+    :loading="groupsQuery.isPending.value"
+    :max-tag-count="3"
+    @update:value="handleChange"
+  />
+</template>
diff --git a/apps/admin-web/src/components/PromptRuleModal.vue b/apps/admin-web/src/components/PromptRuleModal.vue
index db4d35c..8f96f56 100644
--- a/apps/admin-web/src/components/PromptRuleModal.vue
+++ b/apps/admin-web/src/components/PromptRuleModal.vue
@@ -6,6 +6,7 @@ import type { PromptRule, PromptRuleGroup } from "@geo/shared-types";
 import { computed, reactive, watch } from "vue";
 import { useI18n } from "vue-i18n";
 
+import KnowledgeGroupSelect from "@/components/KnowledgeGroupSelect.vue";
 import { promptRulesApi } from "@/lib/api";
 import { formatError } from "@/lib/errors";
 
@@ -29,6 +30,7 @@ const form = reactive({
   default_tone: "",
   default_word_count: undefined as number | undefined,
   group_id: undefined as number | undefined,
+  knowledge_group_ids: [] as number[],
 });
 
 const groupsQuery = useQuery({
@@ -50,6 +52,7 @@ watch(
     form.default_tone = rule?.default_tone ?? "";
     form.default_word_count = rule?.default_word_count ?? undefined;
     form.group_id = rule?.group_id ?? undefined;
+    form.knowledge_group_ids = rule?.knowledge_group_ids ?? [];
   },
 );
 
@@ -62,6 +65,7 @@ const createMutation = useMutation({
       scene: form.scene.trim() || undefined,
       default_tone: form.default_tone.trim() || undefined,
       default_word_count: form.default_word_count,
+      knowledge_group_ids: form.knowledge_group_ids,
     }),
   onSuccess: async (data) => {
     message.success(t("custom.messages.ruleCreated"));
@@ -81,6 +85,7 @@ const updateMutation = useMutation({
       scene: form.scene.trim() || undefined,
       default_tone: form.default_tone.trim() || undefined,
       default_word_count: form.default_word_count,
+      knowledge_group_ids: form.knowledge_group_ids,
     }),
   onSuccess: async () => {
     message.success(t("custom.messages.ruleUpdated"));
@@ -197,6 +202,14 @@ async function handleSubmit(): Promise<void> {
           />
         </div>
       </div>
+
+      <div class="prompt-rule-drawer__field">
+        <label class="prompt-rule-drawer__label">知识库引用：</label>
+        <KnowledgeGroupSelect
+          v-model="form.knowledge_group_ids"
+          placeholder="可选，用于补充生成内容的背景信息"
+        />
+      </div>
     </div>
 
     <template #footer>
diff --git a/apps/admin-web/src/components/login-animation/AnimatedCharacters.vue b/apps/admin-web/src/components/login-animation/AnimatedCharacters.vue
new file mode 100644
index 0000000..cc17817
--- /dev/null
+++ b/apps/admin-web/src/components/login-animation/AnimatedCharacters.vue
@@ -0,0 +1,209 @@
+<template>
+  <div class="characters-container">
+    <!-- Purple -->
+    <div ref="purpleRef" class="char purple" :style="purpleStyle">
+      <div class="eyes" :style="purpleEyesStyle">
+        <EyeBall v-for="i in 2" :key="'p'+i" :size="18" :pupil-size="7" :max-distance="5"
+          eye-color="white" pupil-color="#2D2D2D" :is-blinking="isPurpleBlinking"
+          :force-look-x="purpleLookX" :force-look-y="purpleLookY" />
+      </div>
+    </div>
+    <!-- Black -->
+    <div ref="blackRef" class="char black" :style="blackStyle">
+      <div class="eyes" :style="blackEyesStyle">
+        <EyeBall v-for="i in 2" :key="'b'+i" :size="16" :pupil-size="6" :max-distance="4"
+          eye-color="white" pupil-color="#2D2D2D" :is-blinking="isBlackBlinking"
+          :force-look-x="blackLookX" :force-look-y="blackLookY" />
+      </div>
+    </div>
+    <!-- Orange -->
+    <div ref="orangeRef" class="char orange" :style="orangeStyle">
+      <div class="eyes" :style="orangeEyesStyle">
+        <Pupil v-for="i in 2" :key="'o'+i" :size="12" :max-distance="5" pupil-color="#2D2D2D"
+          :force-look-x="hiding ? -5 : undefined" :force-look-y="hiding ? -4 : undefined" />
+      </div>
+    </div>
+    <!-- Yellow -->
+    <div ref="yellowRef" class="char yellow" :style="yellowStyle">
+      <div class="eyes" :style="yellowEyesStyle">
+        <Pupil v-for="i in 2" :key="'y'+i" :size="12" :max-distance="5" pupil-color="#2D2D2D"
+          :force-look-x="hiding ? -5 : undefined" :force-look-y="hiding ? -4 : undefined" />
+      </div>
+      <div class="mouth" :style="yellowMouthStyle" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, computed, watch, onMounted, onUnmounted } from 'vue'
+import EyeBall from './EyeBall.vue'
+import Pupil from './Pupil.vue'
+
+const props = withDefaults(defineProps<{
+  /** Whether the user is currently typing in an input */
+  isTyping?: boolean
+  /** Whether a secret field has content */
+  hasSecret?: boolean
+  /** Whether the secret is currently visible (e.g. password shown) */
+  secretVisible?: boolean
+}>(), {
+  isTyping: false,
+  hasSecret: false,
+  secretVisible: false,
+})
+
+const mouseX = ref(0)
+const mouseY = ref(0)
+const isPurpleBlinking = ref(false)
+const isBlackBlinking = ref(false)
+const isLookingAtEachOther = ref(false)
+const isPurplePeeking = ref(false)
+
+const purpleRef = ref<HTMLDivElement | null>(null)
+const blackRef = ref<HTMLDivElement | null>(null)
+const yellowRef = ref<HTMLDivElement | null>(null)
+const orangeRef = ref<HTMLDivElement | null>(null)
+
+const purplePos = reactive({ faceX: 0, faceY: 0, bodySkew: 0 })
+const blackPos = reactive({ faceX: 0, faceY: 0, bodySkew: 0 })
+const yellowPos = reactive({ faceX: 0, faceY: 0, bodySkew: 0 })
+const orangePos = reactive({ faceX: 0, faceY: 0, bodySkew: 0 })
+
+// Derived state
+const hiding = computed(() => props.hasSecret && props.secretVisible)
+const leaning = computed(() => props.isTyping || (props.hasSecret && !props.secretVisible))
+
+function calcPos(el: HTMLDivElement | null, target: { faceX: number; faceY: number; bodySkew: number }) {
+  if (!el) return
+  const r = el.getBoundingClientRect()
+  const dx = mouseX.value - (r.left + r.width / 2)
+  const dy = mouseY.value - (r.top + r.height / 3)
+  target.faceX = Math.max(-15, Math.min(15, dx / 20))
+  target.faceY = Math.max(-10, Math.min(10, dy / 30))
+  target.bodySkew = Math.max(-6, Math.min(6, -dx / 120))
+}
+
+let rafId = 0
+function tick() {
+  calcPos(purpleRef.value, purplePos)
+  calcPos(blackRef.value, blackPos)
+  calcPos(yellowRef.value, yellowPos)
+  calcPos(orangeRef.value, orangePos)
+  rafId = requestAnimationFrame(tick)
+}
+
+function onMouseMove(e: MouseEvent) { mouseX.value = e.clientX; mouseY.value = e.clientY }
+
+function setupBlink(target: { value: boolean }) {
+  let t: number
+  const go = () => {
+    t = window.setTimeout(() => {
+      target.value = true
+      window.setTimeout(() => { target.value = false; go() }, 150)
+    }, Math.random() * 4000 + 3000)
+  }
+  go()
+  return () => clearTimeout(t)
+}
+
+let stopP: (() => void) | undefined
+let stopB: (() => void) | undefined
+
+onMounted(() => {
+  window.addEventListener('mousemove', onMouseMove)
+  stopP = setupBlink(isPurpleBlinking)
+  stopB = setupBlink(isBlackBlinking)
+  rafId = requestAnimationFrame(tick)
+})
+onUnmounted(() => {
+  window.removeEventListener('mousemove', onMouseMove)
+  cancelAnimationFrame(rafId)
+  stopP?.(); stopB?.()
+})
+
+// Look at each other when typing starts
+watch(() => props.isTyping, (v) => {
+  if (v) {
+    isLookingAtEachOther.value = true
+    setTimeout(() => { isLookingAtEachOther.value = false }, 800)
+  } else {
+    isLookingAtEachOther.value = false
+  }
+})
+
+// Purple peeks when secret is visible
+let peekT: number | undefined
+watch([() => props.hasSecret, () => props.secretVisible, isPurplePeeking], () => {
+  clearTimeout(peekT)
+  if (props.hasSecret && props.secretVisible) {
+    peekT = window.setTimeout(() => {
+      isPurplePeeking.value = true
+      setTimeout(() => { isPurplePeeking.value = false }, 800)
+    }, Math.random() * 3000 + 2000)
+  } else {
+    isPurplePeeking.value = false
+  }
+})
+
+// Computed styles
+const purpleStyle = computed(() => ({
+  height: leaning.value ? '440px' : '400px',
+  transform: hiding.value ? 'skewX(0deg)'
+    : leaning.value ? `skewX(${purplePos.bodySkew - 12}deg) translateX(40px)`
+    : `skewX(${purplePos.bodySkew}deg)`,
+}))
+const purpleEyesStyle = computed(() => ({
+  left: hiding.value ? '20px' : isLookingAtEachOther.value ? '55px' : `${45 + purplePos.faceX}px`,
+  top: hiding.value ? '35px' : isLookingAtEachOther.value ? '65px' : `${40 + purplePos.faceY}px`,
+  gap: '32px',
+}))
+const purpleLookX = computed(() => hiding.value ? (isPurplePeeking.value ? 4 : -4) : isLookingAtEachOther.value ? 3 : undefined)
+const purpleLookY = computed(() => hiding.value ? (isPurplePeeking.value ? 5 : -4) : isLookingAtEachOther.value ? 4 : undefined)
+
+const blackStyle = computed(() => ({
+  transform: hiding.value ? 'skewX(0deg)'
+    : isLookingAtEachOther.value ? `skewX(${blackPos.bodySkew * 1.5 + 10}deg) translateX(20px)`
+    : leaning.value ? `skewX(${blackPos.bodySkew * 1.5}deg)`
+    : `skewX(${blackPos.bodySkew}deg)`,
+}))
+const blackEyesStyle = computed(() => ({
+  left: hiding.value ? '10px' : isLookingAtEachOther.value ? '32px' : `${26 + blackPos.faceX}px`,
+  top: hiding.value ? '28px' : isLookingAtEachOther.value ? '12px' : `${32 + blackPos.faceY}px`,
+  gap: '24px',
+}))
+const blackLookX = computed(() => hiding.value ? -4 : isLookingAtEachOther.value ? 0 : undefined)
+const blackLookY = computed(() => hiding.value ? -4 : isLookingAtEachOther.value ? -4 : undefined)
+
+const orangeStyle = computed(() => ({
+  transform: hiding.value ? 'skewX(0deg)' : `skewX(${orangePos.bodySkew}deg)`,
+}))
+const orangeEyesStyle = computed(() => ({
+  left: hiding.value ? '50px' : `${82 + orangePos.faceX}px`,
+  top: hiding.value ? '85px' : `${90 + orangePos.faceY}px`,
+  gap: '32px',
+}))
+
+const yellowStyle = computed(() => ({
+  transform: hiding.value ? 'skewX(0deg)' : `skewX(${yellowPos.bodySkew}deg)`,
+}))
+const yellowEyesStyle = computed(() => ({
+  left: hiding.value ? '20px' : `${52 + yellowPos.faceX}px`,
+  top: hiding.value ? '35px' : `${40 + yellowPos.faceY}px`,
+  gap: '24px',
+}))
+const yellowMouthStyle = computed(() => ({
+  left: hiding.value ? '10px' : `${40 + yellowPos.faceX}px`,
+  top: hiding.value ? '88px' : `${88 + yellowPos.faceY}px`,
+}))
+</script>
+
+<style scoped>
+.characters-container { position: relative; width: 550px; height: 400px; }
+.char { position: absolute; bottom: 0; transition: all 0.7s ease-in-out; transform-origin: bottom center; }
+.purple { left: 70px; width: 180px; background: #6C3FF5; border-radius: 10px 10px 0 0; z-index: 1; }
+.black { left: 240px; width: 120px; height: 310px; background: #2D2D2D; border-radius: 8px 8px 0 0; z-index: 2; }
+.orange { left: 0; width: 240px; height: 200px; background: #FF9B6B; border-radius: 120px 120px 0 0; z-index: 3; }
+.yellow { left: 310px; width: 140px; height: 230px; background: #E8D754; border-radius: 70px 70px 0 0; z-index: 4; }
+.eyes { position: absolute; display: flex; transition: all 0.7s ease-in-out; }
+.mouth { position: absolute; width: 80px; height: 4px; background: #2D2D2D; border-radius: 4px; transition: all 0.2s ease-out; }
+</style>
diff --git a/apps/admin-web/src/components/login-animation/EyeBall.vue b/apps/admin-web/src/components/login-animation/EyeBall.vue
new file mode 100644
index 0000000..0077da7
--- /dev/null
+++ b/apps/admin-web/src/components/login-animation/EyeBall.vue
@@ -0,0 +1,55 @@
+<template>
+  <div ref="eyeRef" class="eyeball" :style="{
+    width: size + 'px', height: isBlinking ? '2px' : size + 'px',
+    backgroundColor: eyeColor,
+  }">
+    <div v-if="!isBlinking" class="pupil-inner" :style="{
+      width: pupilSize + 'px', height: pupilSize + 'px',
+      backgroundColor: pupilColor,
+      transform: `translate(${pos.x}px, ${pos.y}px)`,
+    }" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+
+const props = withDefaults(defineProps<{
+  size?: number; pupilSize?: number; maxDistance?: number
+  eyeColor?: string; pupilColor?: string; isBlinking?: boolean
+  forceLookX?: number; forceLookY?: number
+}>(), { size: 48, pupilSize: 16, maxDistance: 10, eyeColor: 'white', pupilColor: 'black', isBlinking: false })
+
+const mx = ref(0), my = ref(0)
+const eyeRef = ref<HTMLDivElement>()
+const onMove = (e: MouseEvent) => { mx.value = e.clientX; my.value = e.clientY }
+onMounted(() => window.addEventListener('mousemove', onMove))
+onUnmounted(() => window.removeEventListener('mousemove', onMove))
+
+const pos = computed(() => {
+  if (!eyeRef.value) return { x: 0, y: 0 }
+  if (props.forceLookX !== undefined && props.forceLookY !== undefined)
+    return { x: props.forceLookX, y: props.forceLookY }
+  const r = eyeRef.value.getBoundingClientRect()
+  const dx = mx.value - (r.left + r.width / 2)
+  const dy = my.value - (r.top + r.height / 2)
+  const d = Math.min(Math.sqrt(dx ** 2 + dy ** 2), props.maxDistance)
+  const a = Math.atan2(dy, dx)
+  return { x: Math.cos(a) * d, y: Math.sin(a) * d }
+})
+</script>
+
+<style scoped>
+.eyeball {
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all 0.15s;
+  overflow: hidden;
+}
+.pupil-inner {
+  border-radius: 50%;
+  transition: transform 0.1s ease-out;
+}
+</style>
diff --git a/apps/admin-web/src/components/login-animation/Pupil.vue b/apps/admin-web/src/components/login-animation/Pupil.vue
new file mode 100644
index 0000000..f2cdf4e
--- /dev/null
+++ b/apps/admin-web/src/components/login-animation/Pupil.vue
@@ -0,0 +1,38 @@
+<template>
+  <div ref="pupilRef" class="pupil" :style="{
+    width: size + 'px', height: size + 'px',
+    backgroundColor: pupilColor,
+    transform: `translate(${pos.x}px, ${pos.y}px)`,
+  }" />
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+
+const props = withDefaults(defineProps<{
+  size?: number; maxDistance?: number; pupilColor?: string
+  forceLookX?: number; forceLookY?: number
+}>(), { size: 12, maxDistance: 5, pupilColor: 'black' })
+
+const mx = ref(0), my = ref(0)
+const pupilRef = ref<HTMLDivElement>()
+const onMove = (e: MouseEvent) => { mx.value = e.clientX; my.value = e.clientY }
+onMounted(() => window.addEventListener('mousemove', onMove))
+onUnmounted(() => window.removeEventListener('mousemove', onMove))
+
+const pos = computed(() => {
+  if (!pupilRef.value) return { x: 0, y: 0 }
+  if (props.forceLookX !== undefined && props.forceLookY !== undefined)
+    return { x: props.forceLookX, y: props.forceLookY }
+  const r = pupilRef.value.getBoundingClientRect()
+  const dx = mx.value - (r.left + r.width / 2)
+  const dy = my.value - (r.top + r.height / 2)
+  const d = Math.min(Math.sqrt(dx ** 2 + dy ** 2), props.maxDistance)
+  const a = Math.atan2(dy, dx)
+  return { x: Math.cos(a) * d, y: Math.sin(a) * d }
+})
+</script>
+
+<style scoped>
+.pupil { border-radius: 50%; transition: transform 0.1s ease-out; }
+</style>
diff --git a/apps/admin-web/src/lib/api.ts b/apps/admin-web/src/lib/api.ts
index 7aae8a3..600e9e3 100644
--- a/apps/admin-web/src/lib/api.ts
+++ b/apps/admin-web/src/lib/api.ts
@@ -18,6 +18,11 @@ import type {
   InstantTaskListParams,
   InstantTaskListResponse,
   JsonValue,
+  KnowledgeGroup,
+  KnowledgeGroupRequest,
+  KnowledgeItem,
+  KnowledgeTextItemRequest,
+  KnowledgeURLItemRequest,
   Keyword,
   KeywordRequest,
   LoginRequest,
@@ -225,6 +230,51 @@ export const articlesApi = {
   },
 };
 
+export const knowledgeApi = {
+  listGroups() {
+    return apiClient.get<KnowledgeGroup[]>("/api/tenant/knowledge/groups");
+  },
+  createGroup(payload: KnowledgeGroupRequest) {
+    return apiClient.post<KnowledgeGroup, KnowledgeGroupRequest>("/api/tenant/knowledge/groups", payload);
+  },
+  updateGroup(id: number, payload: KnowledgeGroupRequest) {
+    return apiClient.put<null, KnowledgeGroupRequest>(`/api/tenant/knowledge/groups/${id}`, payload);
+  },
+  removeGroup(id: number) {
+    return apiClient.remove<null>(`/api/tenant/knowledge/groups/${id}`);
+  },
+  listItems(groupId?: number) {
+    return apiClient.get<KnowledgeItem[]>("/api/tenant/knowledge/items", {
+      params: groupId ? { group_id: groupId } : undefined,
+    });
+  },
+  createTextItem(payload: KnowledgeTextItemRequest) {
+    return apiClient.post<KnowledgeItem, KnowledgeTextItemRequest>(
+      "/api/tenant/knowledge/items/text",
+      payload,
+    );
+  },
+  createURLItem(payload: KnowledgeURLItemRequest) {
+    return apiClient.post<KnowledgeItem, KnowledgeURLItemRequest>(
+      "/api/tenant/knowledge/items/url",
+      payload,
+    );
+  },
+  async createFileItem(payload: { group_id: number; name?: string; file: File }) {
+    const form = new FormData();
+    form.set("group_id", String(payload.group_id));
+    if (payload.name?.trim()) {
+      form.set("name", payload.name.trim());
+    }
+    form.set("file", payload.file);
+    const { data } = await apiClient.raw.post("/api/tenant/knowledge/items/file", form);
+    return data.data as KnowledgeItem;
+  },
+  removeItem(id: number) {
+    return apiClient.remove<null>(`/api/tenant/knowledge/items/${id}`);
+  },
+};
+
 export interface ArticleGenerationStreamEvent {
   type: string;
   article_id: number;
diff --git a/apps/admin-web/src/main.ts b/apps/admin-web/src/main.ts
index abd6d99..e1251bb 100644
--- a/apps/admin-web/src/main.ts
+++ b/apps/admin-web/src/main.ts
@@ -37,9 +37,11 @@ import {
   Table,
   Tabs,
   Tag,
+  Tree,
   TimePicker,
   Tooltip,
   Upload,
+  TreeSelect,
 } from "ant-design-vue";
 
 import App from "./App.vue";
@@ -48,6 +50,8 @@ import { router } from "./router";
 import { pinia } from "./stores/pinia";
 import "./styles.css";
 import "ant-design-vue/dist/reset.css";
+import select from "ant-design-vue/es/select";
+import tree from "ant-design-vue/es/tree";
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -101,6 +105,8 @@ app.component("ATextarea", Input.TextArea);
   Tag,
   TimePicker,
   Tooltip,
+  Tree,
+  TreeSelect,
   Upload,
 ].forEach((component) => {
   app.use(component);
diff --git a/apps/admin-web/src/router/index.ts b/apps/admin-web/src/router/index.ts
index f0eaf5d..f75af6d 100644
--- a/apps/admin-web/src/router/index.ts
+++ b/apps/admin-web/src/router/index.ts
@@ -119,7 +119,7 @@ const router = createRouter({
         {
           path: "knowledge",
           name: "knowledge",
-          component: () => import("@/views/FeatureStubView.vue"),
+          component: () => import("@/views/KnowledgeView.vue"),
           meta: {
             titleKey: "route.knowledge.title",
             descriptionKey: "route.knowledge.description",
diff --git a/apps/admin-web/src/views/KnowledgeView.vue b/apps/admin-web/src/views/KnowledgeView.vue
new file mode 100644
index 0000000..b1fc638
--- /dev/null
+++ b/apps/admin-web/src/views/KnowledgeView.vue
@@ -0,0 +1,970 @@
+<script setup lang="ts">
+import { MoreOutlined, PlusOutlined, UploadOutlined } from "@ant-design/icons-vue";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/vue-query";
+import { message, Modal, type TableColumnsType, type UploadProps } from "ant-design-vue";
+import type { KnowledgeGroup, KnowledgeItem } from "@geo/shared-types";
+import { computed, reactive, ref, watch } from "vue";
+
+import { knowledgeApi } from "@/lib/api";
+import { formatDateTime } from "@/lib/display";
+import { formatError } from "@/lib/errors";
+
+type KnowledgeSourceType = "document" | "website" | "text";
+type KnowledgeGroupLevel = "root" | "child";
+const DEFAULT_CHILD_GROUP_NAME = "默认目录";
+
+interface TreeNode {
+  title: string;
+  value: number;
+  key: number;
+  disabled?: boolean;
+  children?: TreeNode[];
+}
+
+const queryClient = useQueryClient();
+
+const selectedGroupId = ref<number | null>(null);
+const groupModalOpen = ref(false);
+const editingGroup = ref<KnowledgeGroup | null>(null);
+const itemModalOpen = ref(false);
+const itemSourceType = ref<KnowledgeSourceType>("document");
+const uploadFiles = ref<File[]>([]);
+
+const groupForm = reactive({
+  name: "",
+  level: "root" as KnowledgeGroupLevel,
+  parent_id: undefined as number | undefined,
+});
+
+const itemForm = reactive({
+  group_id: undefined as number | undefined,
+});
+
+const urlsText = ref("");
+const textItems = ref([{ name: "", content: "" }]);
+
+const groupsQuery = useQuery({
+  queryKey: ["knowledge", "groups"],
+  queryFn: () => knowledgeApi.listGroups(),
+});
+
+const itemsQuery = useQuery({
+  queryKey: computed(() => ["knowledge", "items", selectedGroupId.value]),
+  queryFn: () => knowledgeApi.listItems(selectedGroupId.value ?? undefined),
+});
+
+const columns: TableColumnsType<KnowledgeItem> = [
+  { title: "名称", dataIndex: "name", key: "name", width: 260 },
+  { title: "类型", dataIndex: "source_type", key: "source_type", width: 120 },
+  { title: "大小", dataIndex: "size_bytes", key: "size_bytes", width: 120 },
+  { title: "AI学习", dataIndex: "status", key: "status", width: 120 },
+  { title: "上传时间", dataIndex: "created_at", key: "created_at", width: 180 },
+  { title: "操作", key: "actions", width: 120, fixed: "right", align: "right" },
+];
+
+const rootGroups = computed(() => groupsQuery.data.value ?? []);
+const groupMap = computed(() => buildGroupMap(rootGroups.value));
+const treeData = computed(() => rootGroups.value.map((item) => toSidebarTreeNode(item)));
+const storableTreeData = computed(() => rootGroups.value.map((item) => toStorageTreeNode(item)));
+const storableGroupCount = computed(() => countStorableGroups(rootGroups.value));
+const groupModalTitle = computed(() => {
+  if (editingGroup.value) {
+    return isRootGroup(editingGroup.value) ? "编辑分组" : "编辑子目录";
+  }
+  return groupForm.level === "root" ? "新建分组" : "新建子目录";
+});
+const groupModalLoading = computed(
+  () => groupMutations.create.isPending.value || groupMutations.update.isPending.value,
+);
+
+const groupMutations = {
+  create: useMutation({
+    mutationFn: () =>
+      knowledgeApi.createGroup({
+        name: groupForm.name.trim(),
+        parent_id: groupForm.level === "child" ? (groupForm.parent_id ?? null) : null,
+      }),
+    onSuccess: async (group) => {
+      message.success("分组创建成功");
+      selectedGroupId.value = group.id;
+      closeGroupModal();
+      await queryClient.invalidateQueries({ queryKey: ["knowledge"] });
+    },
+    onError: (error) => message.error(formatError(error)),
+  }),
+  update: useMutation({
+    mutationFn: () =>
+      knowledgeApi.updateGroup(editingGroup.value!.id, {
+        name: groupForm.name.trim(),
+      }),
+    onSuccess: async () => {
+      message.success("分组更新成功");
+      closeGroupModal();
+      await queryClient.invalidateQueries({ queryKey: ["knowledge"] });
+    },
+    onError: (error) => message.error(formatError(error)),
+  }),
+  remove: useMutation({
+    mutationFn: (id: number) => knowledgeApi.removeGroup(id),
+    onSuccess: async (_data, id) => {
+      message.success("分组已删除");
+      if (selectedGroupId.value === id) {
+        selectedGroupId.value = null;
+      }
+      await queryClient.invalidateQueries({ queryKey: ["knowledge"] });
+    },
+    onError: (error) => message.error(formatError(error)),
+  }),
+};
+
+const itemMutation = useMutation({
+  mutationFn: async () => {
+    let targetGroupId = itemForm.group_id;
+    if (!targetGroupId) {
+      throw new Error("请选择分组目录");
+    }
+
+    targetGroupId = await resolveItemTargetGroupId(targetGroupId);
+
+    const promises: Promise<any>[] = [];
+
+    if (itemSourceType.value === "document") {
+      if (uploadFiles.value.length === 0) {
+        throw new Error("请先选择文件");
+      }
+      for (const file of uploadFiles.value) {
+        promises.push(
+          knowledgeApi.createFileItem({
+            group_id: targetGroupId,
+            name: file.name,
+            file: file,
+          })
+        );
+      }
+    } else if (itemSourceType.value === "website") {
+      const urls = urlsText.value.split('\n').map(u => u.trim()).filter(Boolean);
+      if (urls.length === 0) {
+        throw new Error("请输入包含URL的文本");
+      }
+      for (const url of urls) {
+        let name = url;
+        try { name = new URL(url).hostname + new URL(url).pathname } catch (e) {}
+        promises.push(
+          knowledgeApi.createURLItem({
+            group_id: targetGroupId,
+            name: name,
+            url: url,
+          })
+        );
+      }
+    } else {
+      const validTexts = textItems.value.filter(t => t.name.trim() && t.content.trim());
+      if (validTexts.length === 0) {
+        throw new Error("请至少输入一项完整的文本内容");
+      }
+      for (const txt of validTexts) {
+        promises.push(
+          knowledgeApi.createTextItem({
+            group_id: targetGroupId,
+            name: txt.name.trim(),
+            content: txt.content.trim(),
+          })
+        );
+      }
+    }
+
+    await Promise.all(promises);
+  },
+  onSuccess: async () => {
+    message.success("内容已提交");
+    itemModalOpen.value = false;
+    resetItemForm();
+    await queryClient.invalidateQueries({ queryKey: ["knowledge"] });
+  },
+  onError: (error) => message.error(formatError(error)),
+});
+
+const deleteItemMutation = useMutation({
+  mutationFn: (id: number) => knowledgeApi.removeItem(id),
+  onSuccess: async () => {
+    message.success("内容已删除");
+    await queryClient.invalidateQueries({ queryKey: ["knowledge"] });
+  },
+  onError: (error) => message.error(formatError(error)),
+});
+
+watch(
+  () => groupsQuery.data.value,
+  (groups) => {
+    if (!groups || groups.length === 0) {
+      selectedGroupId.value = null;
+      return;
+    }
+    if (selectedGroupId.value && hasGroupId(groups, selectedGroupId.value)) {
+      return;
+    }
+    selectedGroupId.value = findFirstGroupId(groups);
+  },
+  { immediate: true },
+);
+
+
+
+function buildGroupMap(groups: KnowledgeGroup[]): Map<number, KnowledgeGroup> {
+  const result = new Map<number, KnowledgeGroup>();
+  const visit = (items: KnowledgeGroup[]) => {
+    items.forEach((group) => {
+      result.set(group.id, group);
+      visit(group.children ?? []);
+    });
+  };
+  visit(groups);
+  return result;
+}
+
+function toSidebarTreeNode(group: KnowledgeGroup): TreeNode {
+  return {
+    title: `${group.name} (${group.item_count})`,
+    key: group.id,
+    value: group.id,
+    children: (group.children ?? []).map((item) => toSidebarTreeNode(item)),
+  };
+}
+
+function toStorageTreeNode(group: KnowledgeGroup): TreeNode {
+  return {
+    title: group.name,
+    key: group.id,
+    value: group.id,
+    children: (group.children ?? []).map((item) => toStorageTreeNode(item)),
+  };
+}
+
+function hasGroupId(groups: KnowledgeGroup[], targetId: number): boolean {
+  for (const group of groups) {
+    if (group.id === targetId) {
+      return true;
+    }
+    if (hasGroupId(group.children ?? [], targetId)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function findFirstGroupId(groups: KnowledgeGroup[]): number | null {
+  for (const group of groups) {
+    if (group.id > 0) {
+      return group.id;
+    }
+    const childID = findFirstGroupId(group.children ?? []);
+    if (childID) {
+      return childID;
+    }
+  }
+  return null;
+}
+
+function findFirstStorableGroupId(groups: KnowledgeGroup[]): number | undefined {
+  for (const group of groups) {
+    if (isStorableGroup(group)) {
+      return group.id;
+    }
+    const childID = findFirstStorableGroupId(group.children ?? []);
+    if (childID) {
+      return childID;
+    }
+  }
+  return undefined;
+}
+
+function countStorableGroups(groups: KnowledgeGroup[]): number {
+  return groups.reduce(
+    (count, group) => count + (isStorableGroup(group) ? 1 : 0) + countStorableGroups(group.children ?? []),
+    0,
+  );
+}
+
+function getGroupById(id: number): KnowledgeGroup | undefined {
+  return groupMap.value.get(id);
+}
+
+function isRootGroup(group: KnowledgeGroup): boolean {
+  return group.parent_id == null;
+}
+
+function isNodeRootGroup(id: number): boolean {
+  const group = getGroupById(id);
+  return group ? isRootGroup(group) : false;
+}
+
+function isStorableGroup(group: KnowledgeGroup): boolean {
+  return group.parent_id != null;
+}
+
+function isStorableGroupId(id: number | null | undefined): boolean {
+  if (!id) {
+    return false;
+  }
+  const group = getGroupById(id);
+  return Boolean(group && isStorableGroup(group));
+}
+
+function findChildGroupByName(parentId: number, name: string): KnowledgeGroup | undefined {
+  const parentGroup = getGroupById(parentId);
+  return parentGroup?.children.find((child) => child.name === name);
+}
+
+async function resolveItemTargetGroupId(groupId: number): Promise<number> {
+  if (!isNodeRootGroup(groupId)) {
+    return groupId;
+  }
+
+  const defaultChild = findChildGroupByName(groupId, DEFAULT_CHILD_GROUP_NAME);
+  if (defaultChild) {
+    return defaultChild.id;
+  }
+
+  const newGroup = await knowledgeApi.createGroup({
+    name: DEFAULT_CHILD_GROUP_NAME,
+    parent_id: groupId,
+  });
+  return newGroup.id;
+}
+
+
+function resolveDefaultItemGroupId(): number | undefined {
+  if (selectedGroupId.value) {
+    return selectedGroupId.value;
+  }
+  return rootGroups.value[0]?.id;
+}
+
+function openCreateGroupModal(): void {
+  editingGroup.value = null;
+  groupForm.name = "";
+  groupForm.parent_id = undefined;
+  groupForm.level = "root";
+  groupModalOpen.value = true;
+}
+
+function openCreateSubdirectoryModal(parentId: number): void {
+  editingGroup.value = null;
+  groupForm.name = "";
+  groupForm.parent_id = parentId;
+  groupForm.level = "child";
+  groupModalOpen.value = true;
+}
+
+function openEditGroupModal(groupId: number): void {
+  const group = getGroupById(groupId);
+  if (!group) {
+    return;
+  }
+  editingGroup.value = group;
+  groupForm.name = group.name;
+  groupForm.level = isRootGroup(group) ? "root" : "child";
+  groupForm.parent_id = group.parent_id ?? undefined;
+  groupModalOpen.value = true;
+}
+
+function closeGroupModal(): void {
+  groupModalOpen.value = false;
+  editingGroup.value = null;
+  groupForm.name = "";
+  groupForm.level = "root";
+  groupForm.parent_id = undefined;
+}
+
+async function submitGroup(): Promise<void> {
+  if (!groupForm.name.trim()) {
+    message.warning("请输入分组名称");
+    return;
+  }
+  if (!editingGroup.value && groupForm.level === "child" && !groupForm.parent_id) {
+    message.warning("请选择所属一级目录");
+    return;
+  }
+  if (editingGroup.value) {
+    await groupMutations.update.mutateAsync();
+    return;
+  }
+  await groupMutations.create.mutateAsync();
+}
+
+function confirmDeleteGroup(groupId: number): void {
+  const group = getGroupById(groupId);
+  if (!group) {
+    return;
+  }
+
+  const content = isRootGroup(group)
+    ? "删除一级目录后，该目录下的二级目录和知识内容会一并删除。确定继续吗？"
+    : "删除二级目录后，该目录下的知识内容会一并删除。确定继续吗？";
+
+  Modal.confirm({
+    title: `确认删除“${group.name}”？`,
+    content,
+    okText: "删除",
+    cancelText: "取消",
+    okButtonProps: { danger: true },
+    onOk: async () => {
+      await groupMutations.remove.mutateAsync(groupId);
+    },
+  });
+}
+
+function openItemModal(type: KnowledgeSourceType): void {
+  if (rootGroups.value.length === 0) {
+    message.warning("请先创建目录后再新增内容");
+    return;
+  }
+  itemSourceType.value = type;
+  itemForm.group_id = resolveDefaultItemGroupId();
+  itemModalOpen.value = true;
+}
+
+function resetItemForm(): void {
+  itemForm.group_id = resolveDefaultItemGroupId();
+  urlsText.value = "";
+  textItems.value = [{ name: "", content: "" }];
+  uploadFiles.value = [];
+  itemSourceType.value = "document";
+}
+
+function handleTreeSelect(keys: (string | number)[]): void {
+  if (!keys.length) {
+    return;
+  }
+  selectedGroupId.value = Number(keys[0]);
+}
+
+const beforeUpload: UploadProps["beforeUpload"] = (file) => {
+  uploadFiles.value.push(file as File);
+  return false;
+};
+
+function handleRemoveFile(file: any): void {
+  uploadFiles.value = uploadFiles.value.filter((f: any) => f.uid !== file.uid);
+}
+
+function handleAddTextItem(): void {
+  textItems.value.push({ name: "", content: "" });
+}
+
+function formatSourceType(value: KnowledgeItem["source_type"]): string {
+  if (value === "document") return "文档";
+  if (value === "website") return "网站";
+  return "文本";
+}
+
+function formatStatus(value: string): string {
+  switch (value) {
+    case "completed":
+      return "学习完成";
+    case "processing":
+      return "处理中";
+    case "failed":
+      return "失败";
+    case "pending":
+      return "待处理";
+    case "deleted":
+      return "已删除";
+    default:
+      return value;
+  }
+}
+
+function formatSize(value: number): string {
+  if (value < 1024) return `${value} B`;
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`;
+  return `${(value / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function editItem(): void {
+  message.info("内容编辑功能开发中");
+}
+</script>
+
+<template>
+  <div class="knowledge-page">
+    <div class="knowledge-page__hero">
+      <h2>知识库</h2>
+      <p>
+        通过上传文档，网站认证及任何与您的产品相关的包装及品牌故事内容；对各种格式的数据和资料信息来进行归纳，并结合生成文章
+      </p>
+    </div>
+
+    <div class="knowledge-main-card">
+      <div class="knowledge-toolbar">
+        <a-button type="primary" class="knowledge-add-btn" @click="openItemModal('document')">
+          <template #icon><PlusOutlined /></template>
+          添加知识
+        </a-button>
+      </div>
+
+      <div class="knowledge-layout-inner">
+        <aside class="knowledge-sidebar">
+          <div class="knowledge-sidebar__header">
+            <div class="knowledge-sidebar__title">分组</div>
+            <div class="knowledge-sidebar__add" @click="openCreateGroupModal">
+              <PlusOutlined /> 新建分组
+            </div>
+          </div>
+
+          <a-tree
+            v-if="treeData.length > 0"
+            block-node
+            default-expand-all
+            :tree-data="treeData"
+            :selected-keys="selectedGroupId ? [selectedGroupId] : []"
+            @select="handleTreeSelect"
+          >
+            <template #title="{ title, key }">
+              <div class="tree-node-wrapper">
+                <span class="tree-node-title">{{ title }}</span>
+                <a-dropdown :trigger="['click', 'hover']" placement="bottomRight">
+                  <span class="tree-node-more" @click.stop>
+                    <MoreOutlined />
+                  </span>
+                  <template #overlay>
+                    <a-menu>
+                      <a-menu-item v-if="isNodeRootGroup(Number(key))" key="add-sub" @click.stop="openCreateSubdirectoryModal(Number(key))">
+                        新建子目录
+                      </a-menu-item>
+                      <a-menu-item key="edit" @click.stop="openEditGroupModal(Number(key))">编辑</a-menu-item>
+                      <a-menu-item key="delete" danger @click.stop="confirmDeleteGroup(Number(key))">
+                        删除
+                      </a-menu-item>
+                    </a-menu>
+                  </template>
+                </a-dropdown>
+              </div>
+            </template>
+          </a-tree>
+          <a-empty v-else description="暂无分组" />
+        </aside>
+
+        <section class="knowledge-table">
+          <a-table
+            :columns="columns"
+            :data-source="itemsQuery.data.value ?? []"
+            :loading="itemsQuery.isPending.value"
+            :pagination="false"
+            row-key="id"
+            :scroll="{ x: 1080 }"
+          >
+            <template #bodyCell="{ column, record }">
+              <template v-if="column.key === 'source_type'">
+                {{ formatSourceType(record.source_type) }}
+              </template>
+              <template v-else-if="column.key === 'size_bytes'">
+                {{ formatSize(record.size_bytes) }}
+              </template>
+              <template v-else-if="column.key === 'status'">
+                <span class="knowledge-status-text">
+                  {{ formatStatus(record.status) }}
+                </span>
+              </template>
+              <template v-else-if="column.key === 'created_at'">
+                {{ formatDateTime(record.created_at) }}
+              </template>
+              <template v-else-if="column.key === 'actions'">
+                <div class="knowledge-actions">
+                  <a-button type="link" style="padding: 0 4px" @click="editItem()">编辑</a-button>
+                  <a-divider type="vertical" />
+                  <a-popconfirm title="确认删除该内容？" @confirm="deleteItemMutation.mutate(record.id)">
+                    <a-button type="link" style="padding: 0 4px">删除</a-button>
+                  </a-popconfirm>
+                </div>
+              </template>
+            </template>
+          </a-table>
+        </section>
+      </div>
+    </div>
+
+    <a-modal
+      :open="groupModalOpen"
+      :title="groupModalTitle"
+      :confirm-loading="groupModalLoading"
+      @ok="submitGroup"
+      @cancel="closeGroupModal"
+    >
+      <div class="knowledge-form">
+        <div class="knowledge-form__field">
+          <label>{{ groupForm.level === 'root' ? '分组名称' : '目录名称' }}</label>
+          <a-input
+            v-model:value="groupForm.name"
+            :placeholder="groupForm.level === 'root' ? '请输入分组名称' : '请输入子目录名称'"
+            :maxlength="100"
+          />
+        </div>
+      </div>
+    </a-modal>
+
+    <a-modal
+      :open="itemModalOpen"
+      title="添加知识库"
+      :confirm-loading="itemMutation.isPending.value"
+      width="640px"
+      @ok="itemMutation.mutate()"
+      @cancel="
+        itemModalOpen = false;
+        resetItemForm();
+      "
+      ok-text="确 定"
+      cancel-text="取 消"
+      :ok-button-props="{ style: { width: '80px', borderRadius: '4px' } }"
+      :cancel-button-props="{ style: { width: '80px', borderRadius: '4px' } }"
+    >
+      <div class="knowledge-form-add">
+        <div class="knowledge-type-row">
+          <span class="form-section-title">内容类型：</span>
+          <a-radio-group v-model:value="itemSourceType">
+            <a-radio value="document">文档</a-radio>
+            <a-radio value="website">网页</a-radio>
+            <a-radio value="text">文本</a-radio>
+          </a-radio-group>
+        </div>
+
+        <div v-if="itemSourceType === 'document'" class="knowledge-content-wrapper">
+          <a-upload-dragger
+            :before-upload="beforeUpload"
+            :file-list="uploadFiles"
+            @remove="handleRemoveFile"
+            :multiple="true"
+            class="custom-dragger"
+          >
+            <div class="dragger-content">
+              <div class="dragger-icon-wrapper">
+                <div class="dragger-icon-bg">
+                  <UploadOutlined class="dragger-icon" />
+                </div>
+              </div>
+              <p class="dragger-text">点击或拖拽文件至此区域即可上传</p>
+              <p class="dragger-hint">
+                请上传doc、pdf、txt、xls、xlsx格式，不超过30M的文件。严禁上传敏感数据或其他非法文件。
+              </p>
+              <p class="dragger-count">已选择文件：{{ uploadFiles.length }}个</p>
+            </div>
+          </a-upload-dragger>
+        </div>
+
+        <div v-else-if="itemSourceType === 'website'" class="knowledge-content-wrapper">
+          <a-textarea
+            v-model:value="urlsText"
+            :rows="11"
+            placeholder="请输入产品相关网页URL，每行一个"
+            class="custom-textarea"
+          />
+        </div>
+
+        <div v-else class="knowledge-content-wrapper">
+          <div class="text-items-list">
+            <div v-for="(txt, index) in textItems" :key="index" class="text-item-box">
+              <div class="text-item-row">
+                <span class="text-item-label">文本名称：</span>
+                <a-input v-model:value="txt.name" placeholder="请输入文本名称" style="flex: 1;" />
+              </div>
+              <div class="text-item-row">
+                <span class="text-item-label">文本内容：</span>
+                <a-textarea v-model:value="txt.content" placeholder="请输入文本内容" :rows="5" style="flex: 1;" />
+              </div>
+            </div>
+          </div>
+          <a-button type="dashed" class="add-text-btn" @click="handleAddTextItem">
+            <PlusOutlined /> 添加文本
+          </a-button>
+        </div>
+
+        <div class="knowledge-form-add__field">
+          <div class="form-section-title" style="margin-bottom: 8px;">知识库分组：</div>
+          <a-tree-select
+            v-model:value="itemForm.group_id"
+            :tree-data="storableTreeData"
+            tree-default-expand-all
+            style="width: 240px"
+            placeholder="请选择分组目录"
+          />
+        </div>
+      </div>
+    </a-modal>
+  </div>
+</template>
+
+<style scoped>
+.knowledge-page {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.knowledge-page__hero {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.knowledge-page__hero h2 {
+  margin: 0;
+  color: #111827;
+  font-size: 18px;
+  font-weight: 700;
+}
+
+.knowledge-page__hero p {
+  margin: 0;
+  color: #6b7280;
+  font-size: 13px;
+}
+
+.knowledge-main-card {
+  background: #fff;
+  border-radius: 12px;
+  padding: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.03);
+}
+
+.knowledge-toolbar {
+  display: flex;
+}
+
+.knowledge-add-btn {
+  width: 120px;
+  border-radius: 6px;
+}
+
+.knowledge-layout-inner {
+  display: flex;
+  gap: 20px;
+  align-items: stretch;
+  min-height: 500px;
+}
+
+.knowledge-sidebar {
+  width: 240px;
+  flex-shrink: 0;
+  padding: 16px;
+  border-radius: 8px;
+  border: 1px solid #f0f0f0;
+  background: #fff;
+}
+
+.knowledge-table {
+  flex: 1;
+  min-width: 0;
+  padding: 16px;
+  border-radius: 8px;
+  border: 1px solid #f0f0f0;
+  background: #fff;
+}
+
+.knowledge-sidebar__header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 16px;
+}
+
+.knowledge-sidebar__title {
+  color: #111827;
+  font-size: 14px;
+}
+
+.knowledge-sidebar__add {
+  color: #9ca3af;
+  font-size: 13px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.knowledge-sidebar__add:hover {
+  color: #1677ff;
+}
+
+.tree-node-wrapper {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+}
+
+.tree-node-title {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.tree-node-more {
+  visibility: hidden;
+  color: #9ca3af;
+  padding: 0 4px;
+  cursor: pointer;
+  font-size: 14px;
+  line-height: 1;
+}
+
+.ant-tree-node-content-wrapper:hover .tree-node-more {
+  visibility: visible;
+}
+
+.tree-node-more:hover {
+  color: #1677ff;
+}
+
+.knowledge-status-text {
+  color: #6b7280;
+}
+
+.knowledge-actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+}
+
+.knowledge-form {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.knowledge-form__field label {
+  display: block;
+  margin-bottom: 8px;
+  color: #111827;
+  font-weight: 600;
+}
+
+.knowledge-form__hint {
+  margin-top: 8px;
+  color: #6b7280;
+  font-size: 12px;
+}
+
+.knowledge-form-add {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  padding: 4px 0;
+}
+
+.knowledge-type-row {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.form-section-title {
+  color: #111827;
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.knowledge-content-wrapper {
+  margin-top: 4px;
+}
+
+:deep(.custom-dragger.ant-upload-wrapper .ant-upload-drag) {
+  border: 1px dashed #7eb0f7;
+  background-color: #fff;
+  border-radius: 6px;
+}
+
+.dragger-content {
+  padding: 40px 20px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  gap: 12px;
+}
+
+.dragger-icon {
+  font-size: 32px;
+  color: #9ca3af;
+}
+
+.dragger-text {
+  color: #111827;
+  font-size: 14px;
+  font-weight: 500;
+  margin: 0;
+}
+
+.dragger-hint {
+  color: #9ca3af;
+  font-size: 12px;
+  margin: 0;
+  max-width: 380px;
+}
+
+.dragger-count {
+  color: #9ca3af;
+  font-size: 13px;
+  margin: 0;
+  margin-top: 4px;
+}
+
+:deep(.custom-textarea) {
+  border: 1px solid #7eb0f7;
+  border-radius: 6px;
+  resize: none;
+}
+
+.text-items-list {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.text-item-box {
+  border: 1px solid #f0f0f0;
+  border-radius: 6px;
+  padding: 16px;
+  background: #fafaf9;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.text-item-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+}
+
+.text-item-label {
+  color: #4b5563;
+  font-size: 14px;
+  padding-top: 6px;
+  width: 72px;
+}
+
+.add-text-btn {
+  width: 140px;
+  color: #111827;
+  border-radius: 6px;
+}
+
+@media (max-width: 960px) {
+  .knowledge-layout-inner {
+    flex-direction: column;
+  }
+
+  .knowledge-sidebar {
+    width: 100%;
+  }
+
+  .knowledge-main-card {
+    padding: 16px;
+  }
+}
+</style>
diff --git a/apps/admin-web/src/views/KnowledgeView.vue.patch b/apps/admin-web/src/views/KnowledgeView.vue.patch
new file mode 100644
index 0000000..2a94319
--- /dev/null
+++ b/apps/admin-web/src/views/KnowledgeView.vue.patch
@@ -0,0 +1,10 @@
+--- /Users/liangxu/Documents/test/geo-rankly/apps/admin-web/src/views/KnowledgeView.vue
++++ /Users/liangxu/Documents/test/geo-rankly/apps/admin-web/src/views/KnowledgeView.vue
+@@ -37,6 +37,5 @@
+ const itemForm = reactive({
+-  group_id: undefined as number | undefined,
+-  name: "",
++  group_ids: [] as number[],
+   url: "",
+   content: "",
+ });
diff --git a/apps/admin-web/src/views/LoginView.vue b/apps/admin-web/src/views/LoginView.vue
index 22850d2..b9bb172 100644
--- a/apps/admin-web/src/views/LoginView.vue
+++ b/apps/admin-web/src/views/LoginView.vue
@@ -1,18 +1,101 @@
+<template>
+  <div class="page">
+    <div class="left" :style="{ background: `linear-gradient(135deg, ${primaryColor}e6, ${primaryColor}, ${primaryColor}cc)` }">
+      <div class="brand">
+        <div class="brand-icon"><StarOutlined :style="{ fontSize: '16px' }" /></div>
+        <span>{{ t('app.name') }}</span>
+      </div>
+      <div class="characters-area">
+        <AnimatedCharacters
+          :is-typing="isTyping"
+          :has-secret="!!formState.password"
+          :secret-visible="showPassword"
+        />
+      </div>
+      <div class="footer-links">
+        <a href="#">Privacy Policy</a>
+        <a href="#">Terms of Service</a>
+        <a href="#">Contact</a>
+      </div>
+      <div class="deco-grid" />
+      <div class="deco-circle deco-circle-1" />
+      <div class="deco-circle deco-circle-2" />
+    </div>
+    <div class="right">
+      <div class="form-wrapper">
+        <div class="mobile-brand">
+          <div class="brand-icon"><StarOutlined :style="{ fontSize: '16px' }" /></div>
+          <span>{{ t('app.name') }}</span>
+        </div>
+        <div class="header">
+          <h1>{{ t('auth.welcomeBack') }}</h1>
+          <p>{{ t('auth.tenantAdminLogin') }}</p>
+        </div>
+        <form @submit.prevent="handleSubmit" class="form">
+          <div class="field">
+            <label for="login-email">{{ t('auth.email') }}</label>
+            <input id="login-email" type="email" placeholder="admin@geo.local" v-model="formState.email"
+              autocomplete="off" @focus="isTyping = true" @blur="isTyping = false" required />
+          </div>
+          <div class="field">
+            <label for="login-password">{{ t('auth.password') }}</label>
+            <div class="password-wrap">
+              <input id="login-password" :type="showPassword ? 'text' : 'password'"
+                placeholder="Admin@123" v-model="formState.password" required />
+              <button type="button" class="eye-btn" @click="showPassword = !showPassword">
+                <EyeInvisibleOutlined v-if="showPassword" />
+                <EyeOutlined v-else />
+              </button>
+            </div>
+          </div>
+          <div class="options">
+            <label class="remember"><input type="checkbox" v-model="remember" /> Remember for 30 days</label>
+            <a href="#" class="forgot">Forgot password?</a>
+          </div>
+          
+          <button type="submit" class="btn-primary" :disabled="submitting"
+            :style="{ background: primaryColor }">
+            {{ submitting ? t('auth.loginAndEnter') + '...' : t('auth.loginAndEnter') }}
+          </button>
+        </form>
+        
+        <div class="login-credentials">
+          <div class="login-credentials__row">
+            <span>{{ t("auth.defaultTestAccount") }}</span>
+            <strong>admin@geo.local</strong>
+          </div>
+          <div class="login-credentials__row">
+            <span>{{ t("auth.defaultTestPassword") }}</span>
+            <strong>Admin@123</strong>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
 <script setup lang="ts">
-import { LockOutlined, MailOutlined } from "@ant-design/icons-vue";
-import { message } from "ant-design-vue";
 import { reactive, ref } from "vue";
 import { useRoute, useRouter } from "vue-router";
 import { useI18n } from "vue-i18n";
+import { message } from "ant-design-vue";
+import { StarOutlined, EyeOutlined, EyeInvisibleOutlined } from "@ant-design/icons-vue";
 
 import { formatError } from "@/lib/errors";
 import { useAuthStore } from "@/stores/auth";
+import AnimatedCharacters from "@/components/login-animation/AnimatedCharacters.vue";
 
 const authStore = useAuthStore();
 const router = useRouter();
 const route = useRoute();
 const { t } = useI18n();
+
+const primaryColor = ref('#1f5cff');
+
 const submitting = ref(false);
+const showPassword = ref(false);
+const isTyping = ref(false);
+const remember = ref(false);
 
 const formState = reactive({
   email: "admin@geo.local",
@@ -38,174 +121,99 @@ async function handleSubmit(): Promise<void> {
 }
 </script>
 
-<template>
-  <div class="login-screen">
-    <div class="login-screen__cover">
-      <div class="login-screen__cover-copy">
-        <p class="eyebrow">Tenant Admin</p>
-        <h1>{{ t("app.name") }}</h1>
-        <p>{{ t("app.loginIntro") }}</p>
-      </div>
-    </div>
-
-    <div class="login-screen__form-container">
-      <div class="login-header">
-        <h2>{{ t("auth.welcomeBack") }}</h2>
-        <p>{{ t("auth.tenantAdminLogin") }}</p>
-      </div>
-
-      <a-form
-        layout="vertical"
-        :model="formState"
-        class="login-form"
-        @finish="handleSubmit"
-        @submit.prevent="handleSubmit"
-      >
-        <a-form-item :label="t('auth.email')" name="email">
-          <a-input v-model:value="formState.email" size="large" placeholder="admin@geo.local">
-            <template #prefix><MailOutlined class="login-form__icon" /></template>
-          </a-input>
-        </a-form-item>
-
-        <a-form-item :label="t('auth.password')" name="password">
-          <a-input-password v-model:value="formState.password" size="large" placeholder="Admin@123">
-            <template #prefix><LockOutlined class="login-form__icon" /></template>
-          </a-input-password>
-        </a-form-item>
-
-        <a-button
-          type="primary"
-          size="large"
-          block
-          html-type="submit"
-          :loading="submitting"
-          @click="handleSubmit"
-        >
-          {{ t("auth.loginAndEnter") }}
-        </a-button>
-      </a-form>
-
-      <div class="login-credentials">
-        <div class="login-credentials__row">
-          <span>{{ t("auth.defaultTestAccount") }}</span>
-          <strong>admin@geo.local</strong>
-        </div>
-        <div class="login-credentials__row">
-          <span>{{ t("auth.defaultTestPassword") }}</span>
-          <strong>Admin@123</strong>
-        </div>
-      </div>
-    </div>
-  </div>
-</template>
-
 <style scoped>
-.login-screen {
-  display: grid;
-  grid-template-columns: minmax(0, 1.15fr) minmax(420px, 500px);
-  min-height: 100vh;
-  background: #eef3f9;
+.page { 
+  display: grid; 
+  grid-template-columns: 1fr 1fr; 
+  min-height: 100vh; 
+  width: 100%;
+  flex: 1;
 }
 
-.login-screen__cover {
-  position: relative;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 48px;
-  background:
-    radial-gradient(circle at top left, rgba(112, 172, 255, 0.35), transparent 34%),
-    linear-gradient(135deg, #0f172a 0%, #1f5cff 48%, #57b5ff 100%);
-  color: #fff;
+.left {
+  position: relative; display: flex; flex-direction: column; justify-content: space-between;
+  padding: 48px; color: white; overflow: hidden;
 }
+.brand { position: relative; z-index: 20; display: flex; align-items: center; gap: 8px; font-size: 18px; font-weight: 600; }
+.brand-icon {
+  width: 32px; height: 32px; border-radius: 8px; background: rgba(255,255,255,0.1);
+  backdrop-filter: blur(8px); display: flex; align-items: center; justify-content: center;
+}
+.characters-area { position: relative; z-index: 20; display: flex; align-items: flex-end; justify-content: center; height: 500px; transform: scale(0.95); }
+.footer-links { position: relative; z-index: 20; display: flex; gap: 32px; font-size: 14px; }
+.footer-links a { color: rgba(255,255,255,0.6); transition: color 0.2s; }
+.footer-links a:hover { color: white; }
+.deco-grid {
+  position: absolute; inset: 0;
+  background-image: linear-gradient(to right, rgba(255,255,255,0.05) 1px, transparent 1px),
+    linear-gradient(to bottom, rgba(255,255,255,0.05) 1px, transparent 1px);
+  background-size: 20px 20px;
+}
+.deco-circle { position: absolute; border-radius: 50%; filter: blur(48px); }
+.deco-circle-1 { top: 25%; right: 25%; width: 256px; height: 256px; background: rgba(255,255,255,0.1); }
+.deco-circle-2 { bottom: 25%; left: 25%; width: 384px; height: 384px; background: rgba(255,255,255,0.05); }
+.right { display: flex; align-items: center; justify-content: center; padding: 32px; background: #fff; }
+.form-wrapper { width: 100%; max-width: 420px; }
+.mobile-brand { display: none; }
+.header { text-align: center; margin-bottom: 40px; }
+.header h1 { font-size: 30px; font-weight: 700; letter-spacing: -0.5px; margin-bottom: 8px; color: #18181b; }
+.header p { color: #71717a; font-size: 14px; margin: 0; }
+.form { display: flex; flex-direction: column; gap: 20px; margin-bottom: 32px; }
+.field { display: flex; flex-direction: column; gap: 8px; }
+.field label { font-size: 14px; font-weight: 500; color: #18181b; }
+.field input {
+  height: 48px; padding: 0 12px; border-radius: 6px; border: 1px solid #d4d4d8;
+  font-size: 14px; outline: none; background: #fff; transition: border-color 0.2s; color: #18181b;
+}
+.field input:focus { border-color: #1f5cff; box-shadow: 0 0 0 2px rgba(31,92,255,0.2); }
+.password-wrap { position: relative; }
+.password-wrap input { width: 100%; padding-right: 40px; box-sizing: border-box; }
+.eye-btn {
+  position: absolute; right: 12px; top: 50%; transform: translateY(-50%);
+  background: none; border: none; color: #a1a1aa; transition: color 0.2s;
+  display: flex; align-items: center; justify-content: center; font-size: 18px; cursor: pointer;
+}
+.eye-btn:hover { color: #3f3f46; }
+.options { display: flex; align-items: center; justify-content: space-between; font-size: 14px; }
+.remember { display: flex; align-items: center; gap: 8px; cursor: pointer; color: #18181b; }
+.remember input { width: 16px; height: 16px; accent-color: #1f5cff; cursor: pointer; }
+.forgot { color: #1f5cff; font-weight: 500; }
+.forgot:hover { text-decoration: underline; }
 
-.login-screen__cover-copy {
-  max-width: 520px;
-}
-
-.login-screen__cover h1 {
-  margin: 0;
-  font-size: 56px;
-  line-height: 0.96;
-}
-
-.login-screen__cover p:last-child {
-  max-width: 420px;
-  margin: 18px 0 0;
-  color: rgba(255, 255, 255, 0.82);
-  font-size: 18px;
-  line-height: 1.6;
-}
-
-.login-screen__form-container {
-  display: flex;
-  flex-direction: column;
-  justify-content: center;
-  padding: 64px 48px;
-  background: rgba(255, 255, 255, 0.94);
-  backdrop-filter: blur(14px);
-  box-shadow: -16px 0 40px rgba(15, 23, 42, 0.08);
-}
-
-.login-header {
-  margin-bottom: 36px;
-}
-
-.login-header h2 {
-  margin: 0 0 8px;
-  font-size: 32px;
-}
-
-.login-header p {
-  margin: 0;
-  color: var(--muted);
-}
-
-.login-form__icon {
-  color: rgba(0, 0, 0, 0.25);
+.btn-primary {
+  width: 100%; height: 48px; font-size: 16px; font-weight: 500; border: none; border-radius: 6px;
+  color: white; transition: opacity 0.2s; cursor: pointer;
 }
+.btn-primary:hover { opacity: 0.9; }
+.btn-primary:disabled { opacity: 0.5; cursor: not-allowed; }
 
 .login-credentials {
   margin-top: 24px;
   padding: 16px;
   background: #f8fafc;
   border: 1px solid #e6edf5;
-  border-radius: 16px;
+  border-radius: 12px;
 }
-
 .login-credentials__row {
   display: flex;
   justify-content: space-between;
   gap: 12px;
 }
-
 .login-credentials__row + .login-credentials__row {
   margin-top: 8px;
 }
-
 .login-credentials__row span {
-  color: var(--muted);
+  color: var(--muted, #71717a);
+  font-size: 13px;
+}
+.login-credentials__row strong {
+  color: #18181b;
   font-size: 13px;
 }
 
-@media (max-width: 980px) {
-  .login-screen {
-    grid-template-columns: 1fr;
-  }
-
-  .login-screen__cover {
-    min-height: 280px;
-  }
-}
-
-@media (max-width: 640px) {
-  .login-screen__form-container,
-  .login-screen__cover {
-    padding: 32px 20px;
-  }
-
-  .login-screen__cover h1 {
-    font-size: 40px;
-  }
+@media (max-width: 1023px) {
+  .page { grid-template-columns: 1fr; }
+  .left { display: none; }
+  .mobile-brand { display: flex; align-items: center; justify-content: center; gap: 8px; font-size: 18px; font-weight: 600; margin-bottom: 48px; color: #18181b; }
 }
 </style>
diff --git a/apps/admin-web/src/views/TemplateWizardView.vue b/apps/admin-web/src/views/TemplateWizardView.vue
index 52a155e..55fa11b 100644
--- a/apps/admin-web/src/views/TemplateWizardView.vue
+++ b/apps/admin-web/src/views/TemplateWizardView.vue
@@ -19,6 +19,7 @@ import { computed, ref, watch } from "vue";
 import { useI18n } from "vue-i18n";
 import { useRoute, useRouter } from "vue-router";
 
+import KnowledgeGroupSelect from "@/components/KnowledgeGroupSelect.vue";
 import { articlesApi, brandsApi, normalizeInputParams, templatesApi } from "@/lib/api";
 import { formatError } from "@/lib/errors";
 import { getTemplateMeta } from "@/lib/display";
@@ -170,6 +171,7 @@ const selectedTitle = ref("");
 const customTitle = ref("");
 const reviewIntroHook = ref("");
 const keyPoints = ref("");
+const selectedKnowledgeGroupIds = ref<number[]>([]);
 const outlineSections = ref<string[]>([]);
 const customOutlineSections = ref<ResolvedOutlineOption[]>([]);
 const outlineOptionOrder = ref<string[]>([]);
@@ -424,6 +426,7 @@ function resetWizardState(detail: NonNullable<typeof templateDetail.value>): voi
   customTitle.value = "";
   reviewIntroHook.value = "";
   keyPoints.value = "";
+  selectedKnowledgeGroupIds.value = [];
   customOutlineSections.value = [];
   customOutlineInput.value = "";
   generatedOutline.value = [];
@@ -481,6 +484,7 @@ function applyDraftArticleState(detail: ArticleDetail): void {
   customTitle.value = stringFromUnknown(draftState.custom_title) || "";
   reviewIntroHook.value = stringFromUnknown(draftState.review_intro_hook) || "";
   keyPoints.value = stringFromUnknown(draftState.key_points) || "";
+  selectedKnowledgeGroupIds.value = numberListFromUnknown(draftState.knowledge_group_ids) ?? [];
   customOutlineSections.value = parseCustomOutlineSections(draftState.custom_outline_sections);
   outlineOptionOrder.value = stringListFromUnknown(draftState.outline_option_order) ?? outlineOptionOrder.value;
   outlineSections.value = stringListFromUnknown(draftState.outline_sections) ?? outlineSections.value;
@@ -989,6 +993,8 @@ function buildPayload(): Record<string, JsonValue> {
     primary_keyword: primaryKeyword.value || undefined,
     keywords: keywordDrafts.value.length > 0 ? dedupeStrings(keywordDrafts.value) : undefined,
     [reviewIntroHookFieldName.value]: reviewIntroHookPromptValue.value || undefined,
+    knowledge_group_ids:
+      selectedKnowledgeGroupIds.value.length > 0 ? selectedKnowledgeGroupIds.value : undefined,
     competitors: competitorInputValue,
   };
 
@@ -1031,6 +1037,7 @@ function buildDraftState(): Record<string, JsonValue> {
     custom_title: customTitle.value,
     title: finalTitle.value || selectedTitle.value || "",
     review_intro_hook: reviewIntroHook.value,
+    knowledge_group_ids: selectedKnowledgeGroupIds.value,
     outline_sections: outlineSections.value,
     outline_option_order: outlineOptionOrder.value,
     custom_outline_sections: customOutlineSections.value.map((item) => ({
@@ -1524,6 +1531,16 @@ function numberFromUnknown(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
+function numberListFromUnknown(value: unknown): number[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const items = value
+    .map((item) => (typeof item === "number" && Number.isFinite(item) ? item : NaN))
+    .filter((item) => Number.isFinite(item) && item > 0);
+  return items.length > 0 ? items : undefined;
+}
+
 function clampStep(value: number | undefined): number {
   if (typeof value !== "number" || Number.isNaN(value)) {
     return 0;
@@ -2415,6 +2432,14 @@ function onStructureDragEnd(): void {
                 />
               </div>
 
+              <div class="field-item field-item--compact">
+                <label>引用知识库</label>
+                <KnowledgeGroupSelect
+                  v-model="selectedKnowledgeGroupIds"
+                  placeholder="可选，用于补充文章内容和事实背景"
+                />
+              </div>
+
               <a-alert
                 type="info"
                 show-icon
diff --git a/docs/Claude_architecture_review.md b/docs/Claude_architecture_review.md
deleted file mode 100644
index 59aa0fc..0000000
--- a/docs/Claude_architecture_review.md
+++ /dev/null
@@ -1,348 +0,0 @@
-# GEO 平台技术架构严格审查报告
-
-> 基于 [geo-platform-ops-admin-tech-architecture-v1.md](file:///d:/project/geo/docs/geo-platform-ops-admin-tech-architecture-v1.md) 对照 `docs/refer` 中 8 个功能截图及两份 PRD 文档进行逐功能审查。
-
----
-
-## 审查总结
-
-| 评估维度 | 结果 |
-| --- | --- |
-| 功能覆盖度 | ⚠️ 存在多处缺口 |
-| 后端模块划分 | ✅ 基本合理，部分缺失 |
-| API 路由设计 | ⚠️ 多条功能链路缺少对应路由 |
-| 数据模型覆盖 | ❌ 未提供数据库 Schema |
-| 异步链路设计 | ⚠️ 部分 Worker 职责不完整 |
-| 前端路由覆盖 | ⚠️ 缺少部分关键页面路由 |
-
----
-
-## 一、逐功能审查
-
-### 1. 工作台 (工作台.png)
-
-**截图功能点：**
-- 模板类型卡片入口（Top X / 产品评测 / 研究报告 / 持续扩展中）
-- 右侧数据总览（生成数、发布数、品牌数、媒体平台数）
-- 最近生成列表（标题、模板类型、生成状态、发布状态、字数、操作按钮）
-- 左下角套餐额度区（免费版、升级入口、额度进度条、重置时间）
-- 操作能力：发布、优化、预览、复制、删除
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由 `/workspace` | ✅ | 已定义 |
-| API `/api/tenant/workspace/*` | ✅ | 已定义 |
-| 数据总览统计接口 | ⚠️ | 未在 API 中明确统计聚合端点 |
-| 套餐额度展示接口 | ⚠️ | `/api/tenant/account/*` 未明确额度查询子接口 |
-| 模板类型配置管理 | ❌ | 技术架构中未定义模板类型配置的存储与下发接口 |
-
-> [!WARNING]
-> 工作台首屏需聚合多个数据源（文章统计、品牌数、媒体数、额度），架构中未设计聚合 BFF 层或专用 Dashboard API，可能导致首屏请求过多。
-
----
-
-### 2. 模板创作 (模板创作.png)
-
-**截图功能点：**
-- 筛选区：模板类型、发布状态、生成时间、生成状态、搜索文章
-- 操作按钮：批量生成文章、选择模板创作
-- 列表：文章标题、模板类型、生成状态、发布状态、字数、操作
-- 单次生成、批量任务
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由 | ⚠️ | `admin-web` 路由中有 `/articles` 但缺少模板创作专属路由 |
-| API `/api/tenant/articles/*` | ✅ | 已定义 |
-| 模板定义管理 | ❌ | 后端缺少 `tenant/template` 模块定义 |
-| 批量生成任务 | ✅ | `worker-generate` 已定义 |
-| 模板输入字段配置 | ❌ | 未定义模板 schema 的存储与解析 |
-
-> [!IMPORTANT]
-> 模板创作是核心链路之一，但技术架构中对"模板"概念的后端支撑严重不足。`internal/tenant` 下未见 `template` 子模块；后端模块职责 §5.5.4 仅列出 `article / brand / knowledge`，完全未提及模板管理。
-
----
-
-### 3. 自定义生成 (自定义生成.png)
-
-**截图功能点：**
-- 快捷入口：即时生成内容、定时计划生成
-- Tabs：生成文章、即时任务、定时任务、Prompt 规则
-- 筛选区：Prompt、定时任务、发布状态、标题、生成状态、生成时间
-- 列表：文章标题、规则名称、Prompt、发布平台、生成状态、发布状态、字数
-- Prompt 规则管理
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由（自定义生成） | ⚠️ | `/articles` 覆盖但未区分模板创作与自定义生成的路由 |
-| Prompt 规则 CRUD | ❌ | 后端完全未定义 `tenant/prompt-rule` 模块 |
-| 定时任务管理 | ❌ | 后端未定义定时调度器（Scheduler）组件 |
-| 即时任务与定时任务差异化 | ❌ | `worker-generate` 仅定义"处理文章生成任务"，未区分即时/定时 |
-| 定时任务表 | ❌ | 数据库设计中未提及 `schedule_task` 表 |
-
-> [!CAUTION]
-> **定时任务是自定义生成的核心子功能**，但技术架构中完全缺少：
-> 1. 定时调度组件（如 cron scheduler 或 delayed message）
-> 2. 定时任务 CRUD 接口
-> 3. Prompt 规则管理接口
-> 
-> 这是**重大架构缺失**。
-
----
-
-### 4. 文章优化 (文章优化.png)
-
-**截图功能点：**
-- 操作入口：导入已生成文章、新建文章优化、未完成优化任务
-- 筛选区：发布状态、生成时间、生成状态、搜索文章
-- 列表：作品标题/来源、字数、发布状态、最后修改时间、操作
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由 | ⚠️ | `/articles` 中未区分文章优化页 |
-| 优化任务管理模块 | ❌ | 后端未定义 `tenant/optimization` 子模块 |
-| 优化任务 Worker | ❌ | `worker-generate` 未声明支持优化任务类型 |
-| 优化版本管理 | ❌ | 未定义 `article_version` 的存储与接口 |
-
-> [!WARNING]
-> 文章优化涉及"导入 → 优化 → 版本保存"链路，架构中完全未涉及。PRD 中定义了 `OptimizationTask` 数据对象，但技术架构未对应出后端模块和接口。
-
----
-
-### 5. 媒体管理 (媒体管理.png)
-
-**截图功能点：**
-- 绑定流程引导（安装插件 → 登录 → 授权同步）
-- 平台分类 Tabs：UGC 媒体平台、企业自建站点、第三方新闻源
-- 搜索与筛选（全部/已连接/未连接）
-- 平台卡片：名称、类型、绑定状态、账号昵称、ID、运行状态
-- 操作：去绑定、发布内容
-- 支持 13+ 平台（知乎、头条号、百家号、搜狐号、企鹅号、网易号、简书、bilibili、稀土掘金、什么值得买、公众号、中关村在线等）
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由 `/media` | ✅ | 已定义 |
-| API `/api/tenant/media/*` | ✅ | 已定义 |
-| 浏览器插件交互接口 | ⚠️ | 仅有 `/api/callback/publish/*`，缺少绑定回调接口 |
-| 平台 Adapter 管理 | ✅ | `platform-api` 中有平台接入管理 |
-| 平台分类模型 | ❌ | 未定义 UGC / 自建站 / 新闻源的分类架构 |
-| 发布链路中的插件通信协议 | ❌ | 架构中未定义插件 ↔ 后端的通信协议和数据格式 |
-
-> [!WARNING]
-> 媒体管理涉及浏览器插件的深度交互，但技术架构中未定义：
-> - 绑定回调接口（`/api/callback/bind/*`）
-> - 插件与后端的 WebSocket 或轮询通信机制
-> - 13+ 平台的 Adapter 注册与路由分发策略
-
----
-
-### 6. 品牌词库 (品牌词库.png)
-
-**截图功能点：**
-- 品牌卡片区（品牌名称、新建品牌）
-- Tab：关键词、竞品库
-- 左侧关键词列表（关键词名称、数量、新建）
-- 右侧问题集列表（问题内容、创建时间、操作：数据/删除）
-- 新建问题集
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由 `/brands` | ✅ | 已定义 |
-| API `/api/tenant/brands/*` | ✅ | 已定义 |
-| 品牌-关键词-问题集层级关系 | ⚠️ | 后端模块 §5.5.4 只笼统提到"品牌资料"，未展开数据层级 |
-| 竞品库管理 | ❌ | 后端未定义 `competitor` 子模块 |
-| 问题集"数据"操作（跳转数据详情） | ❌ | 架构中未定义品牌词→数据追踪的关联查询接口 |
-
----
-
-### 7. 知识库 (知识库.png)
-
-**截图功能点：**
-- 新建内容按钮
-- 左侧分组树（默认分组、新建分组）
-- 右侧列表：名称、类型、大小、AI 学习状态、上传时间、操作
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由 `/knowledge` | ✅ | 已定义 |
-| API `/api/tenant/knowledge/*` | ✅ | 已定义 |
-| `worker-knowledge` | ✅ | 已定义，负责解析、Embedding、Qdrant 写入 |
-| 分组管理接口 | ⚠️ | 未明确分组 CRUD 的子路由 |
-| 多来源类型（文档/链接/文本） | ❌ | 架构中未定义不同来源类型的解析策略差异 |
-| 对象存储集成 | ✅ | 已定义用于存储原始文档 |
-
-> 知识库是架构覆盖度**最高**的模块。
-
----
-
-### 8. 数据管理 (数据管理.png)
-
-**截图功能点：**
-- 数据概览卡片：总发文数、总引用数、文章引用率、品牌可见率
-- 品牌排名数据区（品牌选择、关键词选择、模型选择）
-- 指标 Tabs：提及率、首位提及率、首选推荐率、正面提及率
-- 趋势图（按日期折线）
-- 右侧高频问题列表
-- 引用排行榜
-
-**架构覆盖情况：**
-
-| 检查项 | 状态 | 说明 |
-| --- | --- | --- |
-| 前端路由 `/tracking` | ✅ | 已定义 |
-| API `/api/tenant/tracking/*` | ✅ | 已定义 |
-| `worker-analytics` | ✅ | 已定义，负责统计聚合 |
-| 数据采集机制 | ❌ | 架构中未定义 GEO 指标（提及率、引用率等）的采集方式 |
-| 品牌×关键词×模型 三维筛选 | ❌ | 后端未定义这种复合维度的查询接口设计 |
-| 高频问题聚合逻辑 | ❌ | 未定义高频问题的来源和聚合策略 |
-| 引用排行榜数据来源 | ❌ | 未定义引用数据的采集或模拟机制 |
-
-> [!CAUTION]
-> 数据管理/追踪是 UI 复杂度最高的功能之一，但技术架构中几乎**仅有一行**提到 `worker-analytics` 负责"统计聚合、分析快照、缓存刷新"。缺少：
-> 1. GEO 指标采集服务或爬虫组件的架构定义
-> 2. `AnalyticsSnapshot`、`MentionRecord`、`CitationRecord` 的存储方案
-> 3. 品牌×关键词×模型的多维查询 API 设计
-> 4. 高频问题的采集与聚合方案
-
----
-
-## 二、跨功能架构问题
-
-### 问题 1：数据库 Schema 完全缺失
-
-> [!CAUTION]
-> 技术架构文档 774 行，**没有任何一张数据库表定义**。PRD 中定义了 20+ 数据对象（User、Brand、Article、GenerationTask、ScheduleTask、PlatformAccount、KnowledgeItem 等），但技术架构中仅在 §7.1 笼统列出 PostgreSQL 负责的类别，未给出任何表结构、索引策略或分区方案。
-
-### 问题 2：定时调度器缺失
-
-技术架构定义了 4 类 Worker：
-- `worker-generate`
-- `worker-knowledge`
-- `worker-analytics`
-- `worker-publish-callback`
-
-但**没有定义定时调度器**。自定义生成中的"定时计划生成"功能需要 cron 调度能力，但架构中既没有独立的 `cmd/scheduler` 二进制，也没有说明使用 RabbitMQ Delayed Message 或其他延迟队列机制。
-
-### 问题 3：Prompt 规则管理无后端支撑
-
-自定义生成截图中有独立的 "Prompt 规则" Tab，PRD 中也明确定义了 Prompt 规则的 CRUD。但技术架构中：
-- `internal/tenant` 下无 `prompt` 子模块
-- API 路由 `/api/tenant/articles/*` 中未体现规则管理
-- 平台侧 `platform/content` 提到了"Prompt 规则管理"，但租户侧的 Prompt 规则管理被忽略
-
-### 问题 4：浏览器插件通信架构缺失
-
-媒体管理的核心链路依赖浏览器插件，但架构中：
-- 未定义插件架构（虽然提到了 `apps/browser-extension`，但标记为"可选"）
-- 未定义绑定回调接口
-- 未定义插件 ↔ 后端的消息协议
-- 未定义发布过程中的状态同步（SSE vs WebSocket vs 轮询）
-
-### 问题 5：文章版本管理与优化链路缺失
-
-PRD 中定义了 `ArticleVersion` 和 `OptimizationTask` 数据对象，但技术架构中：
-- 未出现"版本"概念
-- 未设计优化任务的 Worker 或处理流程
-- 文章模块仅支持 CRUD，缺少版本历史能力
-
-### 问题 6：SSE 实现细节不足
-
-架构中多次提到 SSE（Server-Sent Events），但：
-- 仅在 `internal/shared/sse` 中有一行提及
-- 未定义 SSE 连接管理、heartbeat、reconnect 策略
-- 未说明哪些场景走 SSE vs 轮询
-- 未定义 SSE 事件类型与负载格式
-
-### 问题 7：前端路由粒度不足
-
-`admin-web` 路由仅 9 条，但参考截图中的功能至少需要：
-
-```diff
- /login
- /workspace
--/articles
--/articles/:id
-+/articles/template          # 模板创作
-+/articles/template/create   # 模板创建表单
-+/articles/custom            # 自定义生成
-+/articles/custom/instant    # 即时任务
-+/articles/custom/scheduled  # 定时任务
-+/articles/custom/prompts    # Prompt 规则
-+/articles/optimize          # 文章优化
-+/articles/:id               # 文章详情
- /brands
-+/brands/:id                 # 品牌详情
- /knowledge
- /media
--/tracking
-+/tracking/overview          # 数据概览
-+/tracking/detail            # 数据详情
- /account
-```
-
----
-
-## 三、按模块严重级别排列
-
-### 🔴 严重缺失（阻塞开发）
-
-| # | 问题 | 影响模块 |
-| --- | --- | --- |
-| 1 | 定时调度器完全未设计 | 自定义生成 |
-| 2 | Prompt 规则管理无后端模块 | 自定义生成 |
-| 3 | 模板管理后端模块缺失 | 模板创作、工作台 |
-| 4 | 数据库 Schema 缺失 | 全部模块 |
-| 5 | GEO 指标采集方案未定义 | 数据管理 |
-
-### 🟡 重要缺失（影响功能完整性）
-
-| # | 问题 | 影响模块 |
-| --- | --- | --- |
-| 6 | 文章优化/版本管理后端缺失 | 文章优化 |
-| 7 | 浏览器插件通信协议未定义 | 媒体管理 |
-| 8 | 绑定回调接口缺失 | 媒体管理 |
-| 9 | 竞品库管理后端缺失 | 品牌词库 |
-| 10 | 品牌×关键词×模型 复合查询设计缺失 | 数据管理 |
-
-### 🟢 轻微不足（可迭代补充）
-
-| # | 问题 | 影响模块 |
-| --- | --- | --- |
-| 11 | 前端路由粒度不足 | 全部前端 |
-| 12 | SSE 实现细节不足 | 长任务反馈 |
-| 13 | 知识库多来源解析策略未定义 | 知识库 |
-| 14 | 工作台 Dashboard 聚合 API 未设计 | 工作台 |
-| 15 | 平台分类模型未定义 | 媒体管理 |
-
----
-
-## 四、审查结论
-
-> [!IMPORTANT]
-> **总体评估：技术架构文档覆盖了系统的宏观层面（服务拆分、技术选型、部署方案），但在对照 PRD 和参考截图进行逐功能审查时，发现多处核心业务链路缺少对应的后端模块定义、API 设计和数据模型。**
-
-### 建议补充项（按优先级排序）：
-
-1. **补充完整数据库 Schema 设计** — 至少覆盖 PRD 中定义的 20+ 数据对象
-2. **补充模板管理模块** — `internal/tenant/template`，含模板 CRUD、schema 解析
-3. **补充定时调度器设计** — `cmd/scheduler` 或基于 RabbitMQ Delayed Message
-4. **补充 Prompt 规则管理** — `internal/tenant/prompt-rule`，含 CRUD + 关联生成
-5. **补充 GEO 数据采集架构** — 明确数据来源、采集频率、存储方案
-6. **补充文章优化模块** — `internal/tenant/optimization`，含版本管理
-7. **补充浏览器插件通信协议** — 绑定/发布回调、状态同步机制
-8. **细化前端路由表** — 按实际页面层级展开
-9. **补充 SSE 事件定义** — 事件类型、负载格式、连接管理
-10. **补充 API 接口清单** — 至少给出每个路由组下的核心端点
diff --git a/docs/ai-brand-monitoring-collection-feasibility-v1.md b/docs/ai-brand-monitoring-collection-feasibility-v1.md
new file mode 100644
index 0000000..2e0b725
--- /dev/null
+++ b/docs/ai-brand-monitoring-collection-feasibility-v1.md
@@ -0,0 +1,462 @@
+# AI 品牌监测数据抓取可行性与采集方案 V1
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档名称 | AI 品牌监测数据抓取可行性与采集方案 V1 |
+| 文档版本 | V1.0 |
+| 文档状态 | 待评审 |
+| 创建日期 | 2026-04-05 |
+| 适用范围 | AI 品牌监测的数据采集、解析、可行性验证 |
+| 关联文档 | `docs/ai-brand-monitoring-tech-design-v2.md` |
+| 关联文档 | `docs/question-driven-monitoring-design-v1.md` |
+| 验证方式 | 本地代码审阅 + 官方文档核验（核验日期：2026-04-05） |
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+本文回答三个问题：
+
+1. 现有“品牌监测”数据抓取是否技术上可行。
+2. 如果可行，主链路应该怎么设计才稳定、可扩展、可验证。
+3. 哪些结果可以承诺，哪些结果不能承诺。
+
+### 2.2 非目标
+
+本文不试图解决以下问题：
+
+1. 不承诺“100% 复刻用户在各家 APP / Web 端看到的答案、排序和引用”。
+2. 不展开前端页面与汇总查询设计，这部分仍以 `docs/ai-brand-monitoring-tech-design-v2.md` 为主。
+3. 不直接替代各平台的商务接入、法务评估和账号申请流程。
+
+## 3. 核心结论
+
+结论先说：
+
+1. **“官方 API 口径下的品牌监测”是可行的。**
+2. **“搜索增强 / 引用型品牌监测”是部分可行的，但要按平台能力分层实现。**
+3. **“完全等价于终端用户在 APP / Web 里看到的内容”不可承诺，至少 DeepSeek 官方已明确 API 与 APP/Web 版本不同。**
+
+因此，监测目标必须拆成三档：
+
+| 档位 | 定义 | 可行性 | 是否建议纳入主链路 |
+| --- | --- | --- | --- |
+| A. 标准化 API 监测 | 统一问题、统一温度、统一提示词，通过官方 API 取回答，再做品牌/竞品/引用解析 | 高 | 是 |
+| B. 搜索增强监测 | 使用平台官方搜索增强、联网搜索、引文能力，监测“搜索型回答中的品牌曝光” | 中到高 | 是，但只对支持平台开启 |
+| C. APP/Web 拟真监测 | 模拟用户在各家产品前台提问，追求与终端用户体验一致 | 低到中 | 否，不建议作为主数据源 |
+
+对 V2 方案的建议是：
+
+1. **主数据源只走官方 API。**
+2. **搜索增强能力按平台单独开关，不搞“全平台统一假设”。**
+3. **如果业务一定要看终端用户视角，单独做“小样本 UI 观测集”，不要并入核心统计口径。**
+
+## 4. 官方能力核验结果
+
+以下结论基于 2026-04-05 当天核验到的官方材料。
+
+### 4.1 平台能力矩阵
+
+| 平台 | 官方能力核验 | 可用于监测的能力 | 可行性判断 | 备注 |
+| --- | --- | --- | --- | --- |
+| DeepSeek | 官方 API 与 OpenAI 兼容；官方文档明确 API 对应的 `deepseek-chat` / `deepseek-reasoner` 与 APP/Web 版本不同；官方 rate limit 页面说明高流量下会排队，10 分钟未开始推理会断开 | 标准对话、流式、工具调用入口 | **标准 API 监测可行；终端拟真不可承诺** | 适合作为“基础语言口径”，不适合作为“用户端搜索曝光”唯一来源 |
+| 通义千问 / 百炼 | OpenAI 兼容；支持 `tools`；支持 `enable_search` 与 `search_options.forced_search`；支持 Batch Chat 与文件批量提交 | 标准对话、函数调用、联网搜索、批量离线推理 | **高可行** | 很适合作为主力采集平台之一 |
+| 豆包 / 火山方舟 | 官方文档明确有 `Web Search（联网搜索）`、`Function Calling`、`File API`；部署文档区分在线推理与批量推理；常规在线推理说明公共资源池下延迟和并发一般、共享限流 | 标准对话、联网搜索、工具调用、批量推理 | **高可行** | 适合做搜索型监测，但生产要避免完全依赖公共在线推理 |
+| 腾讯混元 | OpenAI 兼容；默认 5 并发；支持 `enable_enhancement`、`force_search_enhancement`、`search_info`、`citation` | 标准对话、搜索增强、返回搜索信息、回答角标引文 | **能力强，但默认并发偏低** | 搜索引用监测非常适合，但必须提前做并发扩容或限额申请 |
+| 文心一言 / 千帆 | 百度官方产品页确认企业服务由千帆大模型平台提供，含推理服务和工具链，并支持私有资源托管保障并发 | 平台接入可行 | **中可行，需先做 PoC** | 本次核验中，官方可抓取材料足以确认“能接入”，但不足以确认搜索/引文参数细节 |
+
+### 4.2 关键判断
+
+#### 判断 1：能抓到数据，不代表能复刻用户端
+
+DeepSeek 官方文档明确说 API 模型与 APP/Web 版本不同，这意味着：
+
+1. 即使问题文案一样，回答内容也可能不同。
+2. 即使回答主题相近，排序、措辞、引用也可能不同。
+3. 因此不能把 API 数据直接包装成“终端用户真实看到的内容”。
+
+#### 判断 2：搜索增强和引用能力不是全平台对齐的
+
+各家平台差异很大：
+
+1. 混元已经把 `search_info` 和 `citation` 直接定义成参数。
+2. 千问已明确支持 `enable_search`，还能强制搜索。
+3. 方舟已把 Web Search 作为标准工具能力。
+4. DeepSeek 在本次核验的官方材料里，没有看到同等级别的“原生联网搜索 + 引文返回”说明。
+5. 百度千帆本次核验只确认了平台接入能力，搜索与引文细节仍需单独 PoC。
+
+因此，**“平台统一采集器 + 平台能力开关”是必须的，不是可选项。**
+
+#### 判断 3：批量离线比凌晨突发跑批更靠谱
+
+监测任务本质是离线任务，不是用户实时请求。对于大批量问题：
+
+1. 千问官方明确提供 Batch Chat，适合“无需实时响应”的场景。
+2. 方舟文档体系也区分了在线推理和批量推理。
+3. 混元默认只有 5 并发，不适合把所有任务集中在 2 小时窗口内硬跑。
+
+所以应把采集方案设计成：
+
+1. **全天分布式执行。**
+2. **优先使用批量接口。**
+3. **只有需要搜索增强或即时补采时，才走在线 API。**
+
+## 5. 建议的数据抓取目标口径
+
+### 5.1 统一采集单位
+
+沿用 V1 结论，但扩展成更适合多平台的形式：
+
+`1 question_version x 1 ai_platform x 1 run_mode x 1 run_time = 1 条原始采集记录`
+
+其中 `run_mode` 必须显式记录：
+
+1. `api_standard`
+2. `api_search_grounded`
+3. `ui_sample`
+
+没有这个字段，后续所有跨平台比较都会失真。
+
+### 5.2 必须采集的原始字段
+
+建议在现有 `question_monitor_runs` / `question_monitor_parse_results` 之外，至少保证以下信息能落盘：
+
+| 类别 | 字段 |
+| --- | --- |
+| 请求侧 | `provider_key`, `model`, `run_mode`, `prompt_template_version`, `temperature`, `top_p`, `seed`, `search_enabled`, `tool_enabled` |
+| 响应侧 | `raw_answer_text`, `raw_response_json_key`, `response_latency_ms`, `finish_reason`, `usage_prompt_tokens`, `usage_completion_tokens` |
+| 搜索证据 | `search_hit`, `search_provider`, `search_info_json`, `citation_markers`, `normalized_citations_json` |
+| 解析结果 | `brand_mentioned`, `brand_position`, `top1_mentioned`, `first_recommended`, `competitor_mentions`, `sentiment_label`, `brand_keywords_extract` |
+| 调试追踪 | `request_id`, `retry_count`, `error_code`, `error_message`, `parser_version`, `extractor_version` |
+
+其中：
+
+1. `raw_answer_text` 可以存对象存储。
+2. `raw_response_json_key` 也应该存对象存储，方便 badcase 回放。
+3. `search_info_json` 必须保留原始返回，后续才能验证引用解析是否正确。
+
+## 6. 推荐抓取架构
+
+### 6.1 平台适配器，而不是一个通用 LLM Client 硬扛全部平台
+
+当前代码里 `Config` 只有一份全局 `LLMConfig`，`llm.New()` 也只按单个 provider 初始化客户端，这不足以支撑监测场景的多平台采集。
+
+相关代码：
+
+1. `server/internal/shared/config/config.go`
+2. `server/internal/shared/llm/client.go`
+
+建议改成：
+
+```go
+type ProviderCapability struct {
+    Chat            bool
+    Search          bool
+    Citation        bool
+    ToolCalling     bool
+    Batch           bool
+    Streaming       bool
+    Deterministic   bool
+}
+
+type MonitoringProvider interface {
+    Key() string
+    Capability() ProviderCapability
+    Generate(ctx context.Context, req CollectRequest) (*CollectResponse, error)
+    SubmitBatch(ctx context.Context, jobs []CollectRequest) (*BatchJob, error)
+    PollBatch(ctx context.Context, jobID string) (*BatchJobResult, error)
+}
+```
+
+### 6.2 建议的抓取链路
+
+```text
+调度器
+  -> 任务生成（按品牌 / 问题版本 / 平台 / 模式）
+  -> 去重与幂等校验
+  -> 队列
+  -> Provider Adapter
+  -> 原始响应落对象存储
+  -> 标准化解析器
+  -> 引用规范化
+  -> 质量采样 / badcase
+  -> question_monitor_runs / parse_results
+  -> 日级聚合
+```
+
+### 6.3 任务状态机
+
+必须补全任务状态，不建议只保留 `pending/running/completed/failed` 四态。
+
+建议至少支持：
+
+1. `pending`
+2. `leased`
+3. `running`
+4. `succeeded`
+5. `retryable_failed`
+6. `dead_letter`
+7. `cancelled`
+8. `skipped_dedup`
+
+原因：
+
+1. 平台 API 容易超时、排队、限流。
+2. 搜索增强请求比普通请求更容易波动。
+3. 如果没有 `retryable_failed` 和 `dead_letter`，PoC 阶段会很难判断是平台问题还是解析问题。
+
+### 6.4 幂等策略
+
+建议幂等 key：
+
+`tenant_id + brand_id + question_version_id + ai_platform_id + run_mode + business_date`
+
+这样可以保证：
+
+1. 同一天重复调度不会重复记账。
+2. 同题跨平台不会互相覆盖。
+3. `api_standard` 与 `api_search_grounded` 能并存。
+
+## 7. Prompt 与解析方案
+
+### 7.1 Prompt 原则
+
+抓取时不要用自由发挥的产品提示词，要用固定模板。
+
+建议：
+
+1. 系统提示词固定版本化。
+2. 用户问题原文直接使用 `question_version.question_text`。
+3. 除非平台要求，否则 `temperature` 设为低值。
+4. 能设置 `seed` 的平台尽量设置，提升复现性。
+5. 搜索增强模式下，显式要求模型给出品牌推荐及可验证来源。
+
+### 7.2 解析顺序
+
+解析不要一上来全交给 LLM。
+
+建议顺序：
+
+1. **规则层**：品牌名、竞品名、URL、角标、序号。
+2. **轻语义层**：品牌排名、首位提及、是否明确推荐。
+3. **LLM 兜底层**：情感倾向、品牌印象词、复杂引用归因。
+
+原因：
+
+1. 规则层稳定、便宜、可复跑。
+2. 复杂语义才需要 LLM。
+3. 这样 badcase 也更容易定位。
+
+### 7.3 引用解析策略
+
+引用解析建议拆成三层：
+
+1. **显式链接**：从平台返回的 `search_info`、角标链接、正文 URL 中直接抽取。
+2. **正文映射**：把角标 `[1]`、`[2]` 映射回 `search_info`。
+3. **规范化**：统一域名、小写 host、去掉追踪参数、提取站点名、生成 `citation_hash`。
+
+建议新增规范化后的引用事实结构：
+
+```json
+{
+  "url": "https://example.com/a",
+  "normalized_url": "https://example.com/a",
+  "domain": "example.com",
+  "site_name": "Example",
+  "citation_type": "editorial",
+  "position": 1,
+  "source": "search_info",
+  "confidence": 0.98
+}
+```
+
+## 8. 吞吐与调度建议
+
+### 8.1 不要把采集窗口锁死在凌晨 1 点到 3 点
+
+以 V2 的规模假设为例：
+
+`100 品牌 x 100 问题 x 5 平台 x 1 次/天 = 50,000 条/天`
+
+如果把 50,000 条任务都塞进 2 小时窗口：
+
+1. 平均需要 `6.94 req/s`。
+2. 算上超时、重试、抖动，实际需要按 `15~20 req/s` 设计。
+3. 对默认 5 并发的混元，这个窗口过于激进。
+
+因此建议：
+
+1. 日常采集分 6 个时间窗执行，或者全天滚动执行。
+2. 重要品牌再补一轮搜索增强采集。
+3. 聚合 Job 与采集 Job 解耦，不要求同一夜全部完成。
+
+### 8.2 平台分流策略
+
+建议把平台分成三类：
+
+| 类别 | 平台 | 建议方式 |
+| --- | --- | --- |
+| 标准对话主链路 | DeepSeek | 在线 API，低温、固定 prompt |
+| 搜索增强主链路 | 千问、混元、方舟 | 优先开官方搜索能力 |
+| 待验证平台 | 百度千帆 | 先做 PoC，不直接承诺上线指标 |
+
+### 8.3 批量优先级
+
+建议优先级：
+
+1. 能批量就批量。
+2. 需要搜索增强或引用时再走在线 API。
+3. 需要“接近用户侧”验证时，只做样本观测，不做全量。
+
+## 9. PoC 可行性验证方案
+
+这部分是本方案最核心的落地动作。
+
+### 9.1 PoC 目标
+
+在决定正式开发前，先验证四件事：
+
+1. 各平台能否稳定返回可解析的回答。
+2. 搜索增强模式下能否拿到可追溯引用。
+3. 同一个问题多次执行时，结果波动是否在可接受范围内。
+4. 成本、时延、失败率是否可控。
+
+### 9.2 PoC 样本设计
+
+建议最小样本：
+
+1. 3 个品牌
+2. 每品牌 30 个问题
+3. 5 个平台
+4. 2 种模式：`api_standard`、`api_search_grounded`
+5. 连续跑 3 天
+
+总任务量：
+
+`3 x 30 x 5 x 2 x 3 = 2,700`
+
+这个规模足够看出：
+
+1. 平台成功率
+2. 搜索命中率
+3. 引用解析效果
+4. 回答波动
+
+### 9.3 PoC 验收指标
+
+建议先用下面的阈值：
+
+| 指标 | 目标 |
+| --- | --- |
+| API 调用成功率 | >= 97% |
+| 解析成功率 | >= 99% |
+| 搜索增强模式下“存在可用引用”的比例 | >= 60% |
+| 品牌提及检测准确率 | >= 95% |
+| 引用 URL 规范化成功率 | >= 95% |
+| 单任务 P95 延迟 | <= 20s |
+| 重试后仍失败率 | <= 2% |
+
+如果某平台低于阈值：
+
+1. 不要强行并入统一统计。
+2. 先降级成“样本观测平台”。
+
+### 9.4 PoC 输出物
+
+PoC 结束后必须产出：
+
+1. 平台能力对比表
+2. badcase 样本集
+3. 成本与时延报告
+4. 建议上线的平台白名单
+
+## 10. 建议补充的数据表
+
+V2 当前只覆盖了运行表和解析表，若要把抓取做扎实，建议再补三类表：
+
+### 10.1 `monitoring_collect_tasks`
+
+用途：
+
+1. 存调度任务
+2. 管理状态机
+3. 支撑重试、死信、优先级
+
+### 10.2 `monitoring_citation_facts`
+
+用途：
+
+1. 保存规范化后的引用事实
+2. 便于后续按域名、站点、页面统计
+3. 避免每次都从 JSONB 重新解析
+
+### 10.3 `monitoring_parse_badcases`
+
+用途：
+
+1. 保存低置信度或人工标错样本
+2. 支撑解析器迭代
+3. 给后续模型评测提供数据集
+
+## 11. 实施建议
+
+### Phase A：两周内完成 PoC
+
+1. 先接 3 个最清晰的平台：千问、混元、方舟。
+2. DeepSeek 只做 `api_standard`。
+3. 百度千帆只做可接入性验证，不承诺引用链路。
+
+### Phase B：收敛主链路
+
+1. 形成统一 `MonitoringProvider` 抽象。
+2. 完成搜索增强、引用解析、规范化。
+3. 上线 badcase 采样与抽检。
+
+### Phase C：再决定是否做 UI 观测
+
+只有当业务方明确要求“终端用户真实视角”时，才考虑单独建设 UI 观测链路；且必须先做：
+
+1. 法务 / ToS 评估
+2. 账号稳定性评估
+3. 样本规模评估
+
+它不应进入 V1 主数据链路。
+
+## 12. 对现有 V2 方案的直接修正建议
+
+基于本文结论，建议对 `docs/ai-brand-monitoring-tech-design-v2.md` 做以下修正：
+
+1. 把“采集流水线”从通用 `llm.Client` 调整为“平台适配器 + 能力开关”。
+2. 增加 `run_mode` 字段，区分标准模式与搜索增强模式。
+3. 增加任务表、死信策略、重试退避、幂等 key。
+4. 不再默认所有平台都能产出引用来源数据。
+5. 把凌晨集中跑批改成“滚动采集 + 批量优先”。
+6. 在上线前增加 PoC 验收阶段，而不是直接进入全量开发。
+
+## 13. 官方核验链接
+
+以下均为本次用于判断可行性的官方材料：
+
+1. DeepSeek API Docs: https://api-docs.deepseek.com/
+2. DeepSeek Rate Limit: https://api-docs.deepseek.com/quick_start/rate_limit
+3. 阿里云百炼 OpenAI 兼容: https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope
+4. 阿里云百炼 Batch Chat: https://help.aliyun.com/zh/model-studio/openai-compatible-batch-chat
+5. 腾讯混元 OpenAI 兼容接口: https://cloud.tencent.com/document/product/1729/111007
+6. 火山方舟 Web Search: https://www.volcengine.com/docs/82379/1756990
+7. 火山方舟常规在线推理: https://www.volcengine.com/docs/82379/2121998
+8. 百度文心一言 / 千帆平台: https://cloud.baidu.com/wenxin.html
+
+## 14. 最终结论
+
+一句话总结：
+
+**这件事能做，但必须把“官方 API 监测”与“终端用户视角监测”分开设计。**
+
+对当前项目最现实的路线是：
+
+1. 先做基于官方 API 的标准化品牌监测。
+2. 对具备官方搜索能力的平台，叠加搜索增强与引用监测。
+3. 用 PoC 决定百度千帆是否进入第一批上线平台。
+4. 不把 APP/Web 前台抓取作为主链路承诺项。
diff --git a/docs/ai-brand-monitoring-tech-design-v2.md b/docs/ai-brand-monitoring-tech-design-v2.md
new file mode 100644
index 0000000..83908f3
--- /dev/null
+++ b/docs/ai-brand-monitoring-tech-design-v2.md
@@ -0,0 +1,1348 @@
+# AI 品牌曝光监测系统技术方案 V2
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档名称 | AI 品牌曝光监测系统技术方案 V2 |
+| 文档版本 | V2.0 |
+| 文档状态 | 待评审 |
+| 创建日期 | 2026-04-05 |
+| 适用范围 | 数据追踪模块全部页面 |
+| 关联文档 | `docs/geo-platform-prd-v1.md` (PRD 8.4 数据追踪) |
+| 关联文档 | `docs/question-driven-monitoring-design-v1.md` (V1 数据模型) |
+| 容量目标 | 5 万并发在线用户 |
+
+## 2. 与 V1 设计的关系
+
+本方案基于 V1 (`question-driven-monitoring-design-v1.md`) 的核心结论，保留其"问题驱动 + 日级汇总 + 版本绑定"的数据模型哲学，在此基础上扩展以下能力：
+
+| V1 已定义 | V2 扩展 |
+| --- | --- |
+| 品牌曝光趋势 + 高频问题 + 引用排行 | 新增：主页总览、平台占比分析、竞争对手分析、业务主题分析、AI 对话问题列表、AI 引用来源排名 |
+| 单维度（品牌+关键词+模型） | 多维度：按 AI 平台、按竞品、按主题、按引用来源交叉分析 |
+| 汇总表 3 张 | 扩展至 8 张汇总表 + 2 张原始采集表 |
+| 未涉及性能架构 | 明确 5 万并发的缓存层、连接池、部署拓扑 |
+| 未涉及前端 | 6 个页面 + ECharts 可视化完整方案 |
+
+V1 定义的采集逻辑、版本化策略、去重策略、保留策略 **全部沿用，不再重复**。
+
+## 3. 目标页面与数据需求
+
+基于产品截图，数据追踪模块共 6 个页面：
+
+### 3.1 主页（Dashboard）
+
+| 区域 | 数据需求 | 数据来源 |
+| --- | --- | --- |
+| 曝光趋势图 | 近 7/30 天品牌在所有 AI 平台的综合曝光度日趋势 | `monitoring_brand_daily_overview` |
+| 前五竞争对手 | 品牌及竞品的情感得分、曝光度排名 | `monitoring_competitor_daily` |
+| 引用来源类型占比 | 编辑类、企业、UGC、参考资料、机构、其他的占比饼图 | `monitoring_citation_source_daily` |
+| 前五引用平台 | 引用次数最多的外部平台，含百度权重、引用次数、覆盖度 | `monitoring_citation_source_daily` |
+| 最新 AI 对话 | 最近被触发的 AI 问答问题、排名、前三品牌 | `monitoring_question_daily` |
+| AI 品牌印象 | 品牌相关的高频词词云 | `monitoring_brand_impression` |
+
+### 3.2 平台占比分析
+
+| 区域 | 数据需求 | 数据来源 |
+| --- | --- | --- |
+| 提及次数排名 | 各 AI 平台对品牌的提及总次数横向柱状图 | `monitoring_platform_daily` |
+| 各平台排名表现 | 按平台展开：AI 对话问题、提及次数、平均位置、曝光度 | `monitoring_platform_question_daily` |
+
+### 3.3 竞争对手分析
+
+| 区域 | 数据需求 | 数据来源 |
+| --- | --- | --- |
+| 竞争对手曝光度排名 | 品牌 + 竞品在各 AI 平台上的曝光度分组柱状图 | `monitoring_competitor_daily` |
+| 竞争对手排名情况 | 按品牌/竞品展开：各平台提及次数、平均位置、曝光度 | `monitoring_competitor_platform_daily` |
+
+### 3.4 业务主题分析
+
+| 区域 | 数据需求 | 数据来源 |
+| --- | --- | --- |
+| 业务主题 | 主题名称、问题数、曝光度、提及次数 | `monitoring_topic_daily` |
+| 引用最高的前五平台 | 外部引用来源平台排名 | `monitoring_citation_source_daily` |
+| 引用次数最多的页面 | 具体被引用的外部 URL | `monitoring_citation_page_daily` |
+
+### 3.5 AI 对话问题
+
+| 区域 | 数据需求 | 数据来源 |
+| --- | --- | --- |
+| 问题列表 | AI 对话问题、热度指数、曝光度、平均位置、情感倾向、前三品牌 | `monitoring_question_daily` |
+| 查看效果 / 查看引用 | 单条问题的详细回答效果和引用来源 | `question_monitor_parse_results` |
+
+### 3.6 AI 引用排名
+
+| 区域 | 数据需求 | 数据来源 |
+| --- | --- | --- |
+| 最高引用来源平台趋势 | 前 5 引用来源平台的引用次数日趋势折线图 | `monitoring_citation_source_daily` |
+| 引用页面详情 | 引用平台、百度权重、引用页面 URL、引用次数、覆盖率 | `monitoring_citation_page_daily` |
+
+## 4. 与现有数据模型的关系
+
+### 4.1 已有表复用
+
+监测系统直接复用以下现有表，**不新建冗余表**：
+
+| 现有表 | 用途 | 关键字段 |
+| --- | --- | --- |
+| `brands` | 被监测的品牌主体 | `id, tenant_id, name` |
+| `brand_keywords` | 监测问题的分类容器 | `id, brand_id, name` |
+| `brand_questions` | 监测采集的最小单元 | `id, brand_id, keyword_id, current_version_id` |
+| `brand_question_versions` | 保证历史口径稳定 | `id, question_id, question_text, question_hash, version_no` |
+| `competitors` | 竞品品牌数据 | `id, brand_id, name, website` |
+| `articles` | 被引用的系统文章 | `id, tenant_id, source_type` |
+
+### 4.2 数据流向
+
+```
+现有品牌词库                         新建监测模块
+┌──────────────┐                   ┌──────────────────┐
+│ brands       │──────────────────▶│ 采集调度器        │
+│ keywords     │  品牌+关键词+问题  │ (按问题×模型调度)  │
+│ questions    │──────────────────▶│                  │
+│ question_    │  绑定问题版本      └────────┬─────────┘
+│  versions    │                            │
+│ competitors  │──── 竞品清单 ──────▶        │ 调用 AI 平台 API
+└──────────────┘                            ▼
+                                   ┌──────────────────┐
+现有文章表                          │ 原始采集表         │
+┌──────────────┐                   │ question_monitor_ │
+│ articles     │◀── 引用检测 ──────│  runs / results   │
+│ article_     │                   └────────┬─────────┘
+│  versions    │                            │ 日级聚合 Job
+└──────────────┘                            ▼
+                                   ┌──────────────────┐
+                                   │ 汇总表 × 8        │
+                                   │ (monitoring_*)    │
+                                   └────────┬─────────┘
+                                            │
+                                            ▼
+                                   ┌──────────────────┐
+                                   │ Redis 缓存层      │
+                                   └────────┬─────────┘
+                                            │
+                                            ▼
+                                   ┌──────────────────┐
+                                   │ Dashboard API     │
+                                   │ (6 个页面)         │
+                                   └──────────────────┘
+```
+
+## 5. 数据库 Schema
+
+### 5.1 参考表
+
+#### `ai_platforms` — AI 平台注册表
+
+```sql
+CREATE TABLE ai_platforms (
+    id            BIGSERIAL PRIMARY KEY,
+    tenant_id     BIGINT NOT NULL REFERENCES tenants(id),
+    name          VARCHAR(50) NOT NULL,          -- DeepSeek / 通义千问 / 豆包 / 腾讯元宝 / 文心一言
+    icon          VARCHAR(255),
+    provider_key  VARCHAR(50) NOT NULL,          -- deepseek / qwen / doubao / hunyuan / ernie
+    api_endpoint  TEXT,
+    api_model     VARCHAR(100),
+    display_order INT NOT NULL DEFAULT 0,
+    status        VARCHAR(20) NOT NULL DEFAULT 'active',
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE UNIQUE INDEX uk_ai_platform_tenant_key ON ai_platforms(tenant_id, provider_key);
+```
+
+#### `monitoring_topics` — 业务主题分类
+
+```sql
+CREATE TABLE monitoring_topics (
+    id          BIGSERIAL PRIMARY KEY,
+    tenant_id   BIGINT NOT NULL REFERENCES tenants(id),
+    brand_id    BIGINT NOT NULL REFERENCES brands(id),
+    name        VARCHAR(200) NOT NULL,            -- 瑜伽服饰 / 运动生活方式品牌 / 女士运动内衣
+    description TEXT,
+    status      VARCHAR(20) NOT NULL DEFAULT 'active',
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    deleted_at  TIMESTAMPTZ
+);
+CREATE UNIQUE INDEX uk_topic_tenant_brand_name ON monitoring_topics(tenant_id, brand_id, name) WHERE deleted_at IS NULL;
+```
+
+#### `monitoring_topic_questions` — 主题与问题的多对多关系
+
+```sql
+CREATE TABLE monitoring_topic_questions (
+    id          BIGSERIAL PRIMARY KEY,
+    topic_id    BIGINT NOT NULL REFERENCES monitoring_topics(id),
+    question_id BIGINT NOT NULL REFERENCES brand_questions(id),
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_topic_question UNIQUE (topic_id, question_id)
+);
+```
+
+### 5.2 原始采集表
+
+沿用 V1 设计，增加 `tenant_id` 租户隔离字段。
+
+#### `question_monitor_runs` — 单次采集执行记录
+
+```sql
+CREATE TABLE question_monitor_runs (
+    id                   BIGSERIAL PRIMARY KEY,
+    tenant_id            BIGINT NOT NULL REFERENCES tenants(id),
+    brand_id             BIGINT NOT NULL REFERENCES brands(id),
+    keyword_id           BIGINT NOT NULL REFERENCES brand_keywords(id),
+    question_id          BIGINT NOT NULL REFERENCES brand_questions(id),
+    question_version_id  BIGINT NOT NULL REFERENCES brand_question_versions(id),
+    ai_platform_id       BIGINT NOT NULL REFERENCES ai_platforms(id),
+    run_date             DATE NOT NULL,
+    run_at               TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    task_batch_id        VARCHAR(50),
+    status               VARCHAR(20) NOT NULL DEFAULT 'pending',  -- pending/running/completed/failed
+    raw_answer_key       TEXT,                                      -- MinIO 对象存储路径
+    error_message        TEXT,
+    created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW()
+) PARTITION BY RANGE (run_date);
+
+CREATE INDEX idx_monitor_runs_tenant_date ON question_monitor_runs(tenant_id, run_date DESC);
+CREATE INDEX idx_monitor_runs_batch ON question_monitor_runs(task_batch_id);
+```
+
+> **分区策略**：按 `run_date` 月级 Range 分区，自动创建未来 3 个月分区，到期后可 `DROP PARTITION` 清理。
+
+#### `question_monitor_parse_results` — 单次采集解析结果
+
+```sql
+CREATE TABLE question_monitor_parse_results (
+    id                      BIGSERIAL PRIMARY KEY,
+    run_id                  BIGINT NOT NULL,       -- 指向 question_monitor_runs.id（分区表不建 FK）
+    tenant_id               BIGINT NOT NULL REFERENCES tenants(id),
+
+    -- 品牌提及指标
+    brand_mentioned         BOOLEAN NOT NULL DEFAULT false,
+    brand_position          INT,                    -- 品牌出现位置（1=首位）
+    top1_mentioned          BOOLEAN NOT NULL DEFAULT false,
+    first_recommended       BOOLEAN NOT NULL DEFAULT false,
+    positive_sentiment      BOOLEAN NOT NULL DEFAULT false,
+    sentiment_label         VARCHAR(20),            -- excellent/normal/negative
+
+    -- 竞品提及
+    competitor_mentions     JSONB,                  -- [{"competitor_id":1,"name":"Nike","position":2,"sentiment":"positive"}]
+
+    -- 引用检测
+    citation_urls           JSONB,                  -- [{"url":"https://...","platform":"什么值得买","platform_type":"UGC","baidu_weight":7}]
+    cited_article_ids       BIGINT[],               -- 系统文章 ID 数组
+    citation_count          INT NOT NULL DEFAULT 0,
+
+    -- 品牌印象关键词
+    brand_keywords_extract  JSONB,                  -- [{"word":"性价比高","weight":5},{"word":"设计时尚","weight":3}]
+
+    parser_version          VARCHAR(20) NOT NULL DEFAULT 'v1',
+    created_at              TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX idx_parse_results_run ON question_monitor_parse_results(run_id);
+CREATE INDEX idx_parse_results_tenant ON question_monitor_parse_results(tenant_id);
+```
+
+### 5.3 汇总表
+
+所有汇总表均由后台聚合 Job 写入，Dashboard 查询 **只读** 汇总表。
+
+#### 1) `monitoring_brand_daily_overview` — 品牌日级总览（主页指标卡 + 趋势图）
+
+```sql
+CREATE TABLE monitoring_brand_daily_overview (
+    id                      BIGSERIAL PRIMARY KEY,
+    tenant_id               BIGINT NOT NULL,
+    brand_id                BIGINT NOT NULL,
+    metric_date             DATE NOT NULL,
+
+    -- 核心指标
+    total_question_count    INT NOT NULL DEFAULT 0,     -- 采集的问题总数
+    total_ask_count         INT NOT NULL DEFAULT 0,     -- 总提问次数（跨平台）
+    mention_count           INT NOT NULL DEFAULT 0,
+    top1_mention_count      INT NOT NULL DEFAULT 0,
+    first_recommend_count   INT NOT NULL DEFAULT 0,
+    positive_mention_count  INT NOT NULL DEFAULT 0,
+    citation_count          INT NOT NULL DEFAULT 0,
+
+    -- 比率
+    mention_rate            NUMERIC(5,4) NOT NULL DEFAULT 0,
+    top1_mention_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+    first_recommend_rate    NUMERIC(5,4) NOT NULL DEFAULT 0,
+    positive_mention_rate   NUMERIC(5,4) NOT NULL DEFAULT 0,
+    exposure_rate           NUMERIC(5,4) NOT NULL DEFAULT 0,     -- 曝光度
+
+    -- 情感得分
+    sentiment_score         INT,                        -- 0~100
+
+    updated_at              TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_brand_overview UNIQUE (tenant_id, brand_id, metric_date)
+);
+```
+
+#### 2) `monitoring_platform_daily` — 按 AI 平台维度的品牌日统计（平台占比分析）
+
+```sql
+CREATE TABLE monitoring_platform_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    ai_platform_id      BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    mention_count       INT NOT NULL DEFAULT 0,
+    avg_position        NUMERIC(5,2),               -- 平均排名位置
+    exposure_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+    top1_count          INT NOT NULL DEFAULT 0,
+    question_count      INT NOT NULL DEFAULT 0,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_platform_daily UNIQUE (tenant_id, brand_id, ai_platform_id, metric_date)
+);
+```
+
+#### 3) `monitoring_platform_question_daily` — 按平台×问题的明细（平台展开表）
+
+```sql
+CREATE TABLE monitoring_platform_question_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    ai_platform_id      BIGINT NOT NULL,
+    question_id         BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    question_text       TEXT NOT NULL,                -- 快照
+    mention_count       INT NOT NULL DEFAULT 0,
+    avg_position        NUMERIC(5,2),
+    exposure_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_platform_question_daily UNIQUE (tenant_id, brand_id, ai_platform_id, question_id, metric_date)
+);
+```
+
+#### 4) `monitoring_competitor_daily` — 竞品对比日统计（竞争对手分析）
+
+```sql
+CREATE TABLE monitoring_competitor_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,              -- 主品牌
+    compared_brand_name VARCHAR(200) NOT NULL,         -- 品牌名或竞品名
+    is_self             BOOLEAN NOT NULL DEFAULT false,
+    competitor_id       BIGINT,                        -- NULL 表示自身品牌
+    metric_date         DATE NOT NULL,
+
+    mention_count       INT NOT NULL DEFAULT 0,
+    avg_position        NUMERIC(5,2),
+    exposure_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+    sentiment_score     INT,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_competitor_daily UNIQUE (tenant_id, brand_id, compared_brand_name, metric_date)
+);
+```
+
+#### 5) `monitoring_competitor_platform_daily` — 竞品×平台交叉统计
+
+```sql
+CREATE TABLE monitoring_competitor_platform_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    compared_brand_name VARCHAR(200) NOT NULL,
+    ai_platform_id      BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    mention_count       INT NOT NULL DEFAULT 0,
+    avg_position        NUMERIC(5,2),
+    exposure_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_comp_platform_daily UNIQUE (tenant_id, brand_id, compared_brand_name, ai_platform_id, metric_date)
+);
+```
+
+#### 6) `monitoring_topic_daily` — 业务主题日统计
+
+```sql
+CREATE TABLE monitoring_topic_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    topic_id            BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    question_count      INT NOT NULL DEFAULT 0,
+    exposure_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+    mention_count       INT NOT NULL DEFAULT 0,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_topic_daily UNIQUE (tenant_id, brand_id, topic_id, metric_date)
+);
+```
+
+#### 7) `monitoring_question_daily` — 单问题日统计（AI 对话问题页）
+
+```sql
+CREATE TABLE monitoring_question_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    question_id         BIGINT NOT NULL,
+    question_version_id BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    question_text       TEXT NOT NULL,
+    heat_index          INT NOT NULL DEFAULT 0,        -- 热度指数
+    exposure_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+    avg_position        NUMERIC(5,2),
+    sentiment_label     VARCHAR(20),                    -- excellent/normal/negative
+    top3_brands         JSONB,                          -- [{"name":"lululemon","position":1},...]
+    ask_count           INT NOT NULL DEFAULT 0,
+    mention_count       INT NOT NULL DEFAULT 0,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_question_daily UNIQUE (tenant_id, brand_id, question_id, metric_date)
+);
+```
+
+#### 8) `monitoring_citation_source_daily` — 引用来源日统计（AI 引用排名）
+
+```sql
+CREATE TABLE monitoring_citation_source_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    source_platform     VARCHAR(200) NOT NULL,          -- 夸克 / 排行榜123网 / 什么值得买
+    source_type         VARCHAR(50) NOT NULL,           -- UGC / 编辑类 / 企业 / 参考资料 / 机构 / 其他
+    baidu_weight        INT,                            -- 百度权重 0~10
+    citation_count      INT NOT NULL DEFAULT 0,
+    coverage_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_citation_source_daily UNIQUE (tenant_id, brand_id, source_platform, metric_date)
+);
+```
+
+#### 9) `monitoring_citation_page_daily` — 引用页面明细日统计
+
+```sql
+CREATE TABLE monitoring_citation_page_daily (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    source_platform     VARCHAR(200) NOT NULL,
+    baidu_weight        INT,
+    page_url            TEXT NOT NULL,
+    citation_count      INT NOT NULL DEFAULT 0,
+    coverage_rate       NUMERIC(5,4) NOT NULL DEFAULT 0,
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_citation_page_daily UNIQUE (tenant_id, brand_id, page_url, metric_date)
+);
+```
+
+#### 10) `monitoring_brand_impression` — 品牌印象词（词云数据）
+
+```sql
+CREATE TABLE monitoring_brand_impression (
+    id                  BIGSERIAL PRIMARY KEY,
+    tenant_id           BIGINT NOT NULL,
+    brand_id            BIGINT NOT NULL,
+    metric_date         DATE NOT NULL,
+
+    word                VARCHAR(100) NOT NULL,
+    weight              INT NOT NULL DEFAULT 1,         -- 词频权重
+
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT uk_impression_word UNIQUE (tenant_id, brand_id, word, metric_date)
+);
+```
+
+### 5.4 分区策略
+
+| 表 | 分区方式 | 保留周期 |
+| --- | --- | --- |
+| `question_monitor_runs` | RANGE by `run_date`（月级） | 90 天 |
+| `question_monitor_parse_results` | 不分区（通过 `run_id` 关联） | 90 天 |
+| 所有 `monitoring_*` 汇总表 | 不分区（数据量可控） | 180 天+ |
+
+### 5.5 索引策略
+
+所有汇总表的 UNIQUE 约束自动创建复合索引，天然覆盖 Dashboard 的查询路径（`WHERE tenant_id = ? AND brand_id = ? AND metric_date BETWEEN ? AND ?`）。
+
+额外索引：
+
+```sql
+-- 主页趋势图和指标卡的高频查询
+CREATE INDEX idx_brand_overview_range ON monitoring_brand_daily_overview(tenant_id, brand_id, metric_date DESC);
+
+-- 竞品分析页的高频查询
+CREATE INDEX idx_competitor_range ON monitoring_competitor_daily(tenant_id, brand_id, metric_date DESC);
+
+-- 问题页排序
+CREATE INDEX idx_question_daily_heat ON monitoring_question_daily(tenant_id, brand_id, metric_date DESC, heat_index DESC);
+```
+
+## 6. 后端 API 设计
+
+### 6.1 路由规划
+
+所有路由挂载在 `tenant` 认证组下，复用现有 JWT + TenantScope 中间件。
+
+```
+GET /api/tenant/monitoring/dashboard/overview         → 主页指标卡
+GET /api/tenant/monitoring/dashboard/exposure-trend    → 主页曝光趋势图
+GET /api/tenant/monitoring/dashboard/competitors       → 主页前五竞争对手
+GET /api/tenant/monitoring/dashboard/citation-sources   → 主页引用来源类型占比 + 前五引用平台
+GET /api/tenant/monitoring/dashboard/recent-questions   → 主页最新 AI 对话
+GET /api/tenant/monitoring/dashboard/brand-impression   → 主页品牌印象词云
+
+GET /api/tenant/monitoring/platforms/stats              → 平台占比 - 提及次数排名
+GET /api/tenant/monitoring/platforms/:id/questions      → 平台占比 - 各平台问题明细
+
+GET /api/tenant/monitoring/competitors/exposure         → 竞争对手 - 曝光度排名
+GET /api/tenant/monitoring/competitors/detail           → 竞争对手 - 排名情况明细
+
+GET /api/tenant/monitoring/topics                       → 业务主题列表
+GET /api/tenant/monitoring/topics/:id/citations         → 业务主题 - 引用详情
+
+GET /api/tenant/monitoring/questions                    → AI 对话问题列表（分页）
+GET /api/tenant/monitoring/questions/:id/effect         → 问题效果详情
+GET /api/tenant/monitoring/questions/:id/citations      → 问题引用详情
+
+GET /api/tenant/monitoring/citations/trend              → AI 引用排名 - 来源平台趋势
+GET /api/tenant/monitoring/citations/pages              → AI 引用排名 - 引用页面列表
+
+GET /api/tenant/monitoring/ai-platforms                 → AI 平台下拉列表
+```
+
+### 6.2 通用查询参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `brand_id` | int64 | 是 | - | 品牌 ID |
+| `ai_platform_id` | int64 | 否 | 0 (全部) | AI 平台筛选 |
+| `days` | int | 否 | 7 | 时间范围：7 / 30 / 90 |
+| `page` | int | 否 | 1 | 分页页码 |
+| `page_size` | int | 否 | 20 | 分页大小，最大 100 |
+
+### 6.3 响应格式
+
+复用现有 `response.Success` / `response.Error` 统一格式：
+
+```json
+{
+  "code": 0,
+  "data": { ... },
+  "request_id": "req_abc123"
+}
+```
+
+### 6.4 关键 API 响应结构
+
+#### Dashboard Overview
+
+```json
+{
+  "exposure_rate": 0.6333,
+  "mention_rate": 0.7500,
+  "top1_mention_rate": 0.4800,
+  "positive_rate": 0.8200,
+  "sentiment_score": 83,
+  "exposure_rate_change": 0.05,
+  "mention_rate_change": -0.02
+}
+```
+
+#### Competitors
+
+```json
+{
+  "items": [
+    {
+      "rank": 1,
+      "name": "lululemon",
+      "is_self": true,
+      "sentiment_score": 83,
+      "sentiment_label": "excellent",
+      "exposure_rate": 0.64
+    },
+    {
+      "rank": 2,
+      "name": "Nike",
+      "is_self": false,
+      "sentiment_score": 69,
+      "sentiment_label": "normal",
+      "exposure_rate": 0.47
+    }
+  ]
+}
+```
+
+#### Questions (分页)
+
+```json
+{
+  "items": [
+    {
+      "question_id": 101,
+      "question_text": "瑜伽垫品牌推荐",
+      "heat_index": 5,
+      "exposure_rate": 1.0,
+      "avg_position": 1,
+      "sentiment_label": "excellent",
+      "top3_brands": ["lululemon", "Alo Yoga", "Nike"]
+    }
+  ],
+  "total": 42,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+## 7. 后端架构
+
+### 7.1 服务层设计
+
+新增文件与现有代码的关系：
+
+```
+server/internal/tenant/
+├── app/
+│   ├── monitoring_service.go          ← 新建：Dashboard 查询服务
+│   ├── monitoring_collector.go        ← 新建：AI 平台采集服务
+│   ├── monitoring_aggregator.go       ← 新建：日级聚合 Job
+│   ├── monitoring_parser.go           ← 新建：回答解析器
+│   ├── brand_service.go               ← 已有：品牌 CRUD
+│   └── ...
+├── transport/
+│   ├── monitoring_handler.go          ← 新建：监测 API Handler
+│   ├── router.go                      ← 修改：注册监测路由
+│   └── ...
+└── repository/
+    └── queries/
+        ├── monitoring.sql             ← 新建：监测查询 SQL
+        └── ...
+```
+
+### 7.2 MonitoringService 结构
+
+```go
+type MonitoringService struct {
+    pool  *pgxpool.Pool
+    cache cache.Cache        // 复用现有 cache.Cache 接口（Redis）
+}
+
+// Dashboard 查询方法（全部走缓存 → 汇总表路径）
+func (s *MonitoringService) DashboardOverview(ctx, tenantID, brandID, days) → DashboardOverviewResp
+func (s *MonitoringService) ExposureTrend(ctx, tenantID, brandID, days) → []TrendPoint
+func (s *MonitoringService) TopCompetitors(ctx, tenantID, brandID, days, limit) → []CompetitorItem
+func (s *MonitoringService) CitationSources(ctx, tenantID, brandID, days) → CitationSourceResp
+func (s *MonitoringService) RecentQuestions(ctx, tenantID, brandID, limit) → []RecentQuestionItem
+func (s *MonitoringService) BrandImpression(ctx, tenantID, brandID, days) → []ImpressionWord
+func (s *MonitoringService) PlatformStats(ctx, tenantID, brandID, days) → []PlatformStatItem
+func (s *MonitoringService) PlatformQuestions(ctx, tenantID, brandID, platformID, days, page) → PagedQuestions
+func (s *MonitoringService) CompetitorExposure(ctx, tenantID, brandID, days) → CompetitorExposureResp
+func (s *MonitoringService) CompetitorDetail(ctx, tenantID, brandID, days) → []CompetitorDetailItem
+func (s *MonitoringService) Topics(ctx, tenantID, brandID, platformID, days) → []TopicItem
+func (s *MonitoringService) Questions(ctx, tenantID, brandID, platformID, days, page, pageSize) → PagedQuestions
+func (s *MonitoringService) CitationTrend(ctx, tenantID, brandID, platformID, days) → []CitationTrendPoint
+func (s *MonitoringService) CitationPages(ctx, tenantID, brandID, days, page, pageSize) → PagedCitationPages
+func (s *MonitoringService) AIPlatforms(ctx, tenantID) → []AIPlatform
+```
+
+### 7.3 MonitoringCollector 结构
+
+```go
+type MonitoringCollector struct {
+    pool          *pgxpool.Pool
+    llmClients    map[string]llm.Client   // 每个 AI 平台一个 LLM Client
+    objectStorage objectstorage.Client    // 原始回答存 MinIO
+    logger        *zap.Logger
+}
+
+// 采集流程
+func (c *MonitoringCollector) RunDailyCollection(ctx, tenantID, brandID) error
+func (c *MonitoringCollector) CollectSingle(ctx, question, platform) (*MonitorRun, error)
+func (c *MonitoringCollector) ParseAnswer(ctx, run, rawAnswer) (*ParseResult, error)
+```
+
+### 7.4 MonitoringAggregator 结构
+
+```go
+type MonitoringAggregator struct {
+    pool   *pgxpool.Pool
+    cache  cache.Cache
+    logger *zap.Logger
+}
+
+// 聚合 Job（通常每小时或每天运行一次）
+func (a *MonitoringAggregator) AggregateDaily(ctx, tenantID, brandID, date) error
+func (a *MonitoringAggregator) InvalidateCache(ctx, tenantID, brandID) error
+```
+
+### 7.5 Bootstrap 集成
+
+在 `bootstrap.go` 的 `App` 结构中添加：
+
+```go
+type App struct {
+    // ... 现有字段 ...
+    MonitoringCollector  *app.MonitoringCollector
+    MonitoringAggregator *app.MonitoringAggregator
+}
+```
+
+在 `New()` 中初始化新的 LLM clients（每个 AI 平台一个），注入到 Collector。
+
+### 7.6 配置扩展
+
+在 `config.yaml` 中新增：
+
+```yaml
+monitoring:
+  # 采集配置
+  collection:
+    daily_run_count: 1              # 每题每天默认执行次数
+    worker_concurrency: 5           # 并发采集 worker 数
+    question_timeout: 30s           # 单次采集超时
+    batch_size: 50                  # 每批提交数量
+
+  # 聚合配置
+  aggregation:
+    schedule: "0 3 * * *"           # 每天凌晨 3 点聚合
+    lookback_days: 1                # 回溯天数
+
+  # AI 平台 API
+  platforms:
+    deepseek:
+      base_url: "https://api.deepseek.com/v1"
+      api_key: ""
+      model: "deepseek-chat"
+    qwen:
+      base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+      api_key: ""
+      model: "qwen-max"
+    doubao:
+      base_url: "https://ark.cn-beijing.volces.com/api/v3"
+      api_key: ""
+      model: "doubao-seed-2-0-lite-260215"
+    hunyuan:
+      base_url: "https://hunyuan.tencentcloudapi.com"
+      api_key: ""
+      model: "hunyuan-lite"
+    ernie:
+      base_url: "https://aip.baidubce.com/rpc/2.0/ai_custom/v1"
+      api_key: ""
+      model: "ernie-4.0-8k"
+
+  # 缓存配置
+  cache:
+    overview_ttl: 5m
+    trend_ttl: 15m
+    competitor_ttl: 15m
+    topic_ttl: 30m
+    question_ttl: 10m
+    citation_ttl: 15m
+```
+
+## 8. 缓存策略（5 万并发核心）
+
+### 8.1 缓存架构
+
+```
+Browser → CDN (静态资源) → Nginx → Go API → Redis Cache → PostgreSQL
+                                      ↑
+                              90%+ 命中率
+                              直接返回
+```
+
+### 8.2 缓存 Key 设计
+
+复用 V1 的 Key 格式，扩展到新维度：
+
+```
+mon:{tenant}:{brand}:overview:{days}                     → 指标卡
+mon:{tenant}:{brand}:trend:{days}                        → 趋势图
+mon:{tenant}:{brand}:competitors:{days}                  → 竞品排名
+mon:{tenant}:{brand}:citation_sources:{days}             → 引用来源
+mon:{tenant}:{brand}:recent_questions                    → 最新对话
+mon:{tenant}:{brand}:impression:{days}                   → 品牌印象
+mon:{tenant}:{brand}:platform_stats:{days}               → 平台统计
+mon:{tenant}:{brand}:platform:{pid}:questions:{days}:{page}  → 平台问题
+mon:{tenant}:{brand}:comp_exposure:{days}                → 竞品曝光
+mon:{tenant}:{brand}:topics:{pid}:{days}                 → 业务主题
+mon:{tenant}:{brand}:questions:{pid}:{days}:{page}       → 对话问题列表
+mon:{tenant}:{brand}:citation_trend:{pid}:{days}         → 引用趋势
+mon:{tenant}:{brand}:citation_pages:{days}:{page}        → 引用页面
+```
+
+### 8.3 缓存 TTL 矩阵
+
+| 数据类型 | TTL | 原因 |
+| --- | --- | --- |
+| Overview 指标卡 | 5 min | 高频访问入口，需要相对实时 |
+| 趋势图 | 15 min | 日级数据变化慢 |
+| 竞品排名 | 15 min | 日级数据 |
+| 引用来源 / 引用页面 | 15 min | 日级聚合 |
+| 业务主题 | 30 min | 低频变更 |
+| 问题列表 | 10 min | 带分页，命中粒度细 |
+| 品牌印象 | 30 min | 日级聚合 |
+| AI 平台列表 | 1 hour | 几乎不变 |
+
+### 8.4 缓存失效策略
+
+1. **TTL 自动过期**：主要策略，简单可靠。
+2. **聚合 Job 主动失效**：`MonitoringAggregator.InvalidateCache()` 在每次聚合完成后删除对应品牌的所有缓存 Key。
+3. **不做 Cache-Aside Write-Through**：汇总表是离线 Job 写入的，不是用户请求触发的，因此只需被动读取缓存。
+
+### 8.5 50000 并发容量分析
+
+| 层 | 单机容量 | 5 万并发时 QPS 估算 | 需要实例数 |
+| --- | --- | --- | --- |
+| Go API | 20K+ 并发连接 | ~10K QPS | 3 实例 |
+| Redis | 100K+ QPS | ~10K QPS（90% 命中） | 1 主实例 |
+| PostgreSQL | 5K QPS | ~1K QPS（缓存穿透） | 1 主 + 1 只读副本 |
+
+> 假设：平均用户每 30 秒发起 1 次 API 请求 → 50000/30 ≈ 1700 QPS；峰值 3x → ~5000 QPS。Redis 缓存承接 90%+ → PG 仅 ~500 QPS。
+
+## 9. 前端架构
+
+### 9.1 页面结构
+
+```
+apps/admin-web/src/
+├── views/monitoring/
+│   ├── MonitoringDashboardView.vue       ← 主页
+│   ├── MonitoringPlatformView.vue        ← 平台占比分析
+│   ├── MonitoringCompetitorView.vue      ← 竞争对手分析
+│   ├── MonitoringTopicView.vue           ← 业务主题分析
+│   ├── MonitoringQuestionsView.vue       ← AI 对话问题
+│   └── MonitoringCitationView.vue        ← AI 引用排名
+├── components/monitoring/
+│   ├── ExposureTrendChart.vue            ← ECharts 折线图
+│   ├── CompetitorBarChart.vue            ← 分组柱状图
+│   ├── PlatformHorizontalBar.vue         ← 横向柱状图
+│   ├── CitationDonutChart.vue            ← 环形图
+│   ├── CitationTrendChart.vue            ← 引用趋势折线图
+│   ├── BrandImpressionCloud.vue          ← 词云
+│   ├── HeatIndicator.vue                ← 热度指示器（IIIII）
+│   ├── SentimentBadge.vue               ← 情感标签（优秀/一般）
+│   ├── CompetitorRankTable.vue          ← 竞品排名表格
+│   └── MonitoringFilters.vue            ← 通用筛选栏（品牌+平台+时间）
+└── lib/
+    └── api.ts                            ← 修改：新增 monitoringApi
+```
+
+### 9.2 路由配置
+
+在 `router/index.ts` 中新增，替换现有的 `/tracking` FeatureStubView：
+
+```typescript
+// 数据追踪 - 主路由组
+{
+  path: '/monitoring',
+  name: 'monitoring',
+  redirect: '/monitoring/dashboard',
+  children: [
+    { path: 'dashboard',    name: 'monitoring-dashboard',    component: MonitoringDashboardView },
+    { path: 'platforms',    name: 'monitoring-platforms',    component: MonitoringPlatformView },
+    { path: 'competitors',  name: 'monitoring-competitors',  component: MonitoringCompetitorView },
+    { path: 'topics',       name: 'monitoring-topics',       component: MonitoringTopicView },
+    { path: 'questions',    name: 'monitoring-questions',    component: MonitoringQuestionsView },
+    { path: 'citations',    name: 'monitoring-citations',    component: MonitoringCitationView },
+  ]
+}
+```
+
+### 9.3 Chart Library
+
+**选用 ECharts + vue-echarts**：
+
+- 已在现有 plan（Phase 18）中确定
+- 原生中文支持，社区生态成熟
+- 支持所有所需图表类型：折线图、分组柱状图、横向柱状图、环形图
+- 词云使用 `echarts-wordcloud` 扩展
+
+依赖添加：
+
+```json
+{
+  "echarts": "^5.5",
+  "vue-echarts": "^7.0",
+  "echarts-wordcloud": "^2.1"
+}
+```
+
+### 9.4 Shared Types
+
+在 `packages/shared-types/src/index.ts` 中新增接口：
+
+```typescript
+// AI 平台
+export interface AIPlatform {
+  id: number
+  name: string
+  icon: string
+  provider_key: string
+}
+
+// 主页
+export interface MonitoringOverview {
+  exposure_rate: number
+  mention_rate: number
+  top1_mention_rate: number
+  positive_rate: number
+  sentiment_score: number
+  exposure_rate_change: number
+  mention_rate_change: number
+}
+
+export interface TrendPoint {
+  date: string
+  exposure_rate: number
+  brands: Array<{ name: string; exposure_rate: number }>
+}
+
+export interface CompetitorRankItem {
+  rank: number
+  name: string
+  is_self: boolean
+  icon?: string
+  sentiment_score: number
+  sentiment_label: string
+  exposure_rate: number
+}
+
+export interface CitationSourceItem {
+  source_platform: string
+  source_type: string
+  baidu_weight: number
+  citation_count: number
+  coverage_rate: number
+}
+
+export interface MonitoringQuestionItem {
+  question_id: number
+  question_text: string
+  heat_index: number
+  exposure_rate: number
+  avg_position: number
+  sentiment_label: string
+  top3_brands: string[]
+}
+
+export interface CitationPageItem {
+  source_platform: string
+  baidu_weight: number
+  page_url: string
+  citation_count: number
+  coverage_rate: number
+}
+
+export interface ImpressionWord {
+  word: string
+  weight: number
+}
+
+export interface PlatformStatItem {
+  ai_platform_id: number
+  platform_name: string
+  platform_icon: string
+  mention_count: number
+  avg_position: number
+  exposure_rate: number
+}
+
+export interface TopicItem {
+  topic_id: number
+  topic_name: string
+  question_count: number
+  exposure_rate: number
+  mention_count: number
+}
+```
+
+### 9.5 API Client
+
+```typescript
+export const monitoringApi = {
+  // 主页
+  dashboardOverview: (brandId: number, days = 7) =>
+    http.get<MonitoringOverview>('/monitoring/dashboard/overview', { params: { brand_id: brandId, days } }),
+  exposureTrend: (brandId: number, days = 7) =>
+    http.get<TrendPoint[]>('/monitoring/dashboard/exposure-trend', { params: { brand_id: brandId, days } }),
+  topCompetitors: (brandId: number, days = 7) =>
+    http.get<CompetitorRankItem[]>('/monitoring/dashboard/competitors', { params: { brand_id: brandId, days } }),
+  citationSources: (brandId: number, days = 7) =>
+    http.get<{ type_distribution: ..., top_platforms: CitationSourceItem[] }>('/monitoring/dashboard/citation-sources', { params: { brand_id: brandId, days } }),
+  recentQuestions: (brandId: number) =>
+    http.get<MonitoringQuestionItem[]>('/monitoring/dashboard/recent-questions', { params: { brand_id: brandId } }),
+  brandImpression: (brandId: number, days = 7) =>
+    http.get<ImpressionWord[]>('/monitoring/dashboard/brand-impression', { params: { brand_id: brandId, days } }),
+
+  // 平台占比
+  platformStats: (brandId: number, days = 7) =>
+    http.get<PlatformStatItem[]>('/monitoring/platforms/stats', { params: { brand_id: brandId, days } }),
+  platformQuestions: (brandId: number, platformId: number, days = 7, page = 1) =>
+    http.get<Paged<MonitoringQuestionItem>>(`/monitoring/platforms/${platformId}/questions`, { params: { brand_id: brandId, days, page } }),
+
+  // 竞争对手
+  competitorExposure: (brandId: number, days = 7) =>
+    http.get('/monitoring/competitors/exposure', { params: { brand_id: brandId, days } }),
+  competitorDetail: (brandId: number, days = 7) =>
+    http.get('/monitoring/competitors/detail', { params: { brand_id: brandId, days } }),
+
+  // 业务主题
+  topics: (brandId: number, platformId = 0, days = 7) =>
+    http.get<TopicItem[]>('/monitoring/topics', { params: { brand_id: brandId, ai_platform_id: platformId, days } }),
+
+  // AI 对话问题
+  questions: (brandId: number, params: { ai_platform_id?: number; days?: number; page?: number; page_size?: number }) =>
+    http.get<Paged<MonitoringQuestionItem>>('/monitoring/questions', { params: { brand_id: brandId, ...params } }),
+
+  // AI 引用排名
+  citationTrend: (brandId: number, platformId = 0, days = 7) =>
+    http.get('/monitoring/citations/trend', { params: { brand_id: brandId, ai_platform_id: platformId, days } }),
+  citationPages: (brandId: number, days = 7, page = 1, pageSize = 20) =>
+    http.get<Paged<CitationPageItem>>('/monitoring/citations/pages', { params: { brand_id: brandId, days, page, page_size: pageSize } }),
+
+  // 通用
+  aiPlatforms: () => http.get<AIPlatform[]>('/monitoring/ai-platforms'),
+}
+```
+
+## 10. 采集流水线设计
+
+### 10.1 采集流程
+
+```
+┌──────────┐     ┌───────────────┐     ┌──────────────┐     ┌──────────────┐
+│ 调度器    │     │  Redis Stream │     │ Collector    │     │  Parser      │
+│ (cron)   │────▶│  / 内部队列    │────▶│  Worker ×5   │────▶│  (解析回答)   │
+│ 生成任务  │     │               │     │ 调用 AI API  │     │ 提取指标     │
+└──────────┘     └───────────────┘     └──────┬───────┘     └──────┬───────┘
+                                              │                     │
+                                              ▼                     ▼
+                                       ┌─────────────┐     ┌──────────────┐
+                                       │ MinIO        │     │ PostgreSQL   │
+                                       │ (原始回答)    │     │ (解析结果)    │
+                                       └─────────────┘     └──────────────┘
+```
+
+### 10.2 调度策略
+
+```go
+// 每天凌晨 1 点执行
+func (c *MonitoringCollector) RunDailyCollection(ctx context.Context, tenantID int64) error {
+    // 1. 查询该租户所有 active 品牌
+    brands := listActiveBrands(ctx, tenantID)
+    for _, brand := range brands {
+        // 2. 查询品牌下所有 active 问题（含 question_hash 去重）
+        questions := listUniqueActiveQuestions(ctx, brand.ID)
+        // 3. 查询所有 active AI 平台
+        platforms := listActivePlatforms(ctx, tenantID)
+        // 4. 生成采集任务 = questions × platforms
+        for _, q := range questions {
+            for _, p := range platforms {
+                enqueueTask(ctx, brand, q, p)
+            }
+        }
+    }
+}
+```
+
+### 10.3 回答解析逻辑
+
+```go
+func (c *MonitoringCollector) ParseAnswer(ctx context.Context, question, brand string, competitors []string, rawAnswer string) *ParseResult {
+    // 1. 品牌提及检测：在回答中查找品牌名出现位置
+    // 2. 首位提及检测：品牌是否出现在推荐列表第一位
+    // 3. 首选推荐检测：品牌是否被明确推荐
+    // 4. 情感分析：使用 LLM 对品牌相关段落做情感判断
+    // 5. 竞品提及检测：检测 competitors 列表中的品牌出现情况
+    // 6. 引用 URL 提取：从回答中提取所有外部链接
+    // 7. 系统文章引用匹配：与 articles 表做 URL/标题匹配
+    // 8. 品牌印象词提取：使用 LLM 从回答中提取品牌相关形容词
+}
+```
+
+### 10.4 聚合 Job
+
+```go
+// 每天凌晨 3 点执行（在采集完成后）
+func (a *MonitoringAggregator) AggregateDaily(ctx context.Context, date time.Time) error {
+    tenants := listAllTenants(ctx)
+    for _, t := range tenants {
+        brands := listActiveBrands(ctx, t.ID)
+        for _, b := range brands {
+            // 1. 从 parse_results 聚合 → monitoring_brand_daily_overview
+            a.aggregateBrandOverview(ctx, t.ID, b.ID, date)
+            // 2. 聚合 → monitoring_platform_daily / monitoring_platform_question_daily
+            a.aggregatePlatformStats(ctx, t.ID, b.ID, date)
+            // 3. 聚合 → monitoring_competitor_daily / monitoring_competitor_platform_daily
+            a.aggregateCompetitorStats(ctx, t.ID, b.ID, date)
+            // 4. 聚合 → monitoring_topic_daily
+            a.aggregateTopicStats(ctx, t.ID, b.ID, date)
+            // 5. 聚合 → monitoring_question_daily
+            a.aggregateQuestionStats(ctx, t.ID, b.ID, date)
+            // 6. 聚合 → monitoring_citation_source_daily / monitoring_citation_page_daily
+            a.aggregateCitationStats(ctx, t.ID, b.ID, date)
+            // 7. 聚合 → monitoring_brand_impression
+            a.aggregateBrandImpression(ctx, t.ID, b.ID, date)
+            // 8. 清除该品牌缓存
+            a.InvalidateCache(ctx, t.ID, b.ID)
+        }
+    }
+}
+```
+
+## 11. 部署拓扑（5 万并发）
+
+### 11.1 推荐部署架构
+
+```
+                    ┌───────────────────────────┐
+                    │     CDN / 云 LB (SLB)     │
+                    │   静态资源 + API 路由       │
+                    └─────────────┬─────────────┘
+                                  │
+                    ┌─────────────┼─────────────┐
+                    ▼             ▼             ▼
+              ┌──────────┐ ┌──────────┐ ┌──────────┐
+              │ tenant-api│ │ tenant-api│ │ tenant-api│   ×3 (API 服务)
+              │ Pod/容器   │ │ Pod/容器   │ │ Pod/容器   │
+              └────┬──────┘ └────┬──────┘ └────┬──────┘
+                   │             │             │
+              ┌────┴─────────────┴─────────────┴────┐
+              │          Redis 6+ (单主)              │   缓存 + 会话
+              │          或 Redis Cluster             │
+              └───────────────────┬──────────────────┘
+                                  │
+              ┌───────────────────┼──────────────────┐
+              │                   │                  │
+              ▼                   ▼                  ▼
+        ┌───────────┐     ┌───────────┐      ┌───────────┐
+        │ PG Primary │     │ PG Replica │      │   MinIO   │
+        │ (读写)     │────▶│ (只读)     │      │ (原始回答) │
+        └───────────┘     └───────────┘      └───────────┘
+
+  ╔════════════════════════════════════════════════════════╗
+  ║  独立进程 / CronJob（不接入 LB）                        ║
+  ║                                                        ║
+  ║  ┌─────────────────┐   ┌─────────────────┐             ║
+  ║  │ Collector Worker │   │ Aggregator Job  │             ║
+  ║  │ (采集 AI 平台)   │   │ (日级聚合)      │             ║
+  ║  └─────────────────┘   └─────────────────┘             ║
+  ╚════════════════════════════════════════════════════════╝
+```
+
+### 11.2 资源估算
+
+| 组件 | 规格建议 | 说明 |
+| --- | --- | --- |
+| API 实例 ×3 | 2C4G | Go 服务轻量，3 实例可处理 ~60K 并发连接 |
+| Redis | 4G 内存 | 缓存数据量不大，主要是 Key 数量 |
+| PostgreSQL Primary | 4C16G | 汇总表小，索引少，500 QPS 绰绰有余 |
+| PostgreSQL Replica ×1 | 4C16G | 可选，用于聚合 Job 的重查询分流 |
+| MinIO | 50G+ | 原始回答存储，按 90 天保留 |
+| Collector Worker ×1 | 2C4G | 采集任务非实时，单实例 5 并发即可 |
+| Aggregator Job ×1 | 2C4G | 凌晨运行，单实例即可 |
+
+### 11.3 数据库连接池配置
+
+```yaml
+database:
+  max_open_conns: 50        # 从 25 提升到 50（3 个 API 实例共享）
+  max_idle_conns: 10
+```
+
+按 3 个 API 实例计算：每实例 ~17 连接上限，足够应对缓存穿透后的查询。
+
+## 12. 数据量估算
+
+### 12.1 汇总表大小
+
+假设：100 个品牌，每品牌 5 个竞品，5 个 AI 平台，10 个主题，30 天窗口。
+
+| 汇总表 | 行数/天 | 30 天行数 | 估算大小 |
+| --- | --- | --- | --- |
+| `monitoring_brand_daily_overview` | 100 | 3,000 | < 1 MB |
+| `monitoring_platform_daily` | 500 | 15,000 | < 5 MB |
+| `monitoring_platform_question_daily` | 50,000 | 1,500,000 | ~200 MB |
+| `monitoring_competitor_daily` | 600 | 18,000 | < 5 MB |
+| `monitoring_competitor_platform_daily` | 3,000 | 90,000 | ~15 MB |
+| `monitoring_topic_daily` | 1,000 | 30,000 | < 5 MB |
+| `monitoring_question_daily` | 50,000 | 1,500,000 | ~250 MB |
+| `monitoring_citation_source_daily` | 5,000 | 150,000 | ~25 MB |
+| `monitoring_citation_page_daily` | 10,000 | 300,000 | ~60 MB |
+| `monitoring_brand_impression` | 5,000 | 150,000 | ~20 MB |
+
+**30 天汇总表总计 < 600 MB**，PostgreSQL 完全可控。
+
+### 12.2 原始采集表大小
+
+```
+100 品牌 × 100 问题 × 5 平台 × 1 次/天 = 50,000 条/天
+90 天保留 = 4,500,000 条原始记录
+每条约 1KB（不含原始回答文本）→ ~4.5 GB
+原始回答文本（~5KB/条）→ MinIO 约 22 GB/90 天
+```
+
+## 13. 实施计划
+
+### Phase 15: 数据库迁移 + AI 平台注册表
+
+- 创建所有新表的 migration 文件
+- 种子数据：5 个默认 AI 平台
+- 估时：1 天
+
+### Phase 16: 后端 - 监测查询服务 + API
+
+- 实现 `MonitoringService` 的所有查询方法
+- 实现 `monitoring_handler.go` 的所有路由
+- 实现 Redis 缓存层
+- 注册路由到 `router.go`
+- 估时：3 天
+
+### Phase 17: 后端 - 采集流水线
+
+- 实现 `MonitoringCollector` + `MonitoringParser`
+- 对接 5 个 AI 平台 API（复用现有 `llm.Client` 接口）
+- 原始回答存储 MinIO
+- 估时：3 天
+
+### Phase 18: 后端 - 聚合 Job
+
+- 实现 `MonitoringAggregator` 的 8 个聚合函数
+- 实现缓存失效逻辑
+- 实现定时调度（可先用 in-process cron）
+- 估时：2 天
+
+### Phase 19: 种子数据
+
+- 生成 30 天真实结构的 mock 数据，覆盖所有汇总表
+- 确保前端开发可立即使用
+- 估时：1 天
+
+### Phase 20: 前端 - 6 页面 + ECharts
+
+- 安装 echarts / vue-echarts / echarts-wordcloud
+- 实现 6 个页面 + 10 个图表组件
+- 实现通用筛选栏组件
+- i18n 扩展
+- 估时：4 天
+
+### Phase 21: 前端验证 + 集成测试
+
+- `pnpm typecheck:admin && pnpm build:admin` 通过
+- `go test ./...` 通过
+- 全链路验证：种子数据 → API → 前端图表渲染
+- 估时：1 天
+
+**总估时：约 15 个工作日**
+
+## 14. 风险与决策项
+
+### 14.1 待确认
+
+| 序号 | 决策项 | 影响范围 | 建议 |
+| --- | --- | --- | --- |
+| 1 | 各 AI 平台 API Key 如何获取和管理 | 采集流水线 | 建议 config.yaml 配置，生产环境用环境变量覆盖 |
+| 2 | 业务主题的分类方式（人工还是 LLM 自动归类） | 主题分析页 | V1 建议人工创建主题并关联问题，V2 可自动归类 |
+| 3 | 百度权重数据来源 | 引用排名页 | 建议接入第三方 SEO API 或定期手动维护 |
+| 4 | 情感分析的准确度要求 | 竞品分析 + 问题列表 | 建议先用规则匹配，重要场景用 LLM 二次判断 |
+| 5 | 是否需要支持自定义 AI 平台 | 平台管理 | V1 建议固定 5 个平台，用户不可增删 |
+| 6 | 部署环境选择（K8s / Docker Compose / 裸机） | 部署架构 | 开发阶段 Docker Compose，生产建议 K8s |
+
+### 14.2 已确认（沿用 V1 决策）
+
+| 决策 | 来源 |
+| --- | --- |
+| 问题是最小监控采集单元 | V1 核心结论 |
+| 原始回答存对象存储，不存 PG | V1 Section 8.2 |
+| 每问题每天默认执行 1 次 | V1 Section 8.3 |
+| 问题 hash 去重 | V1 Section 8.4 |
+| 问题版本化保证历史口径 | V1 Section 9 |
+| 页面只查汇总表 | V1 Section 10 |
+| 原始记录保留 90 天 | V1 Section 12 |
+
+## 15. 附录
+
+### 15.1 已有表 DDL 参考
+
+```sql
+-- brands（已存在）
+CREATE TABLE brands (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id BIGINT NOT NULL REFERENCES tenants(id),
+    name VARCHAR(200) NOT NULL,
+    description TEXT,
+    status VARCHAR(20) NOT NULL DEFAULT 'active',
+    ...
+);
+
+-- brand_keywords（已存在）
+CREATE TABLE brand_keywords (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id BIGINT NOT NULL REFERENCES tenants(id),
+    brand_id BIGINT NOT NULL REFERENCES brands(id),
+    name VARCHAR(200) NOT NULL,
+    ...
+);
+
+-- brand_questions（已存在）
+CREATE TABLE brand_questions (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id BIGINT NOT NULL REFERENCES tenants(id),
+    brand_id BIGINT NOT NULL REFERENCES brands(id),
+    keyword_id BIGINT NOT NULL REFERENCES brand_keywords(id),
+    current_version_id BIGINT,
+    ...
+);
+
+-- brand_question_versions（已存在）
+CREATE TABLE brand_question_versions (
+    id BIGSERIAL PRIMARY KEY,
+    question_id BIGINT NOT NULL REFERENCES brand_questions(id),
+    question_text TEXT NOT NULL,
+    question_hash VARCHAR(64) NOT NULL,
+    version_no INT NOT NULL,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    ...
+);
+
+-- competitors（已存在）
+CREATE TABLE competitors (
+    id BIGSERIAL PRIMARY KEY,
+    tenant_id BIGINT NOT NULL REFERENCES tenants(id),
+    brand_id BIGINT NOT NULL REFERENCES brands(id),
+    name VARCHAR(200) NOT NULL,
+    website TEXT,
+    description TEXT,
+    product_lines_json JSONB,
+    ...
+);
+```
+
+### 15.2 指标口径定义
+
+| 指标 | 计算公式 | 说明 |
+| --- | --- | --- |
+| 曝光度 (exposure_rate) | 品牌在 AI 回答中被提及的问题数 / 采集的总问题数 | 反映品牌在 AI 平台的总体可见度 |
+| 提及率 (mention_rate) | 品牌被提及的回答次数 / 总提问次数 | 跨平台汇总 |
+| 首位提及率 (top1_mention_rate) | 品牌出现在推荐列表首位的次数 / 总提问次数 | 衡量品牌在 AI 推荐中的优先级 |
+| 首选推荐率 (first_recommend_rate) | 品牌被明确推荐的次数 / 总提问次数 | 衡量 AI 对品牌的推荐倾向 |
+| 正面提及率 (positive_mention_rate) | 正面情感的提及次数 / 总提及次数 | 衡量品牌的 AI 口碑 |
+| 情感得分 (sentiment_score) | 正面提及占比 × 100，修正后 0~100 | 综合情感指标 |
+| 热度指数 (heat_index) | 近期被触发的 AI 问答频次标准化后 1~5 档 | 问题热度 |
+| 覆盖率 (coverage_rate) | 该来源被引用的问题数 / 总问题数 | 引用来源的覆盖广度 |
diff --git a/docs/ai-brand-monitoring-tech-design-v3.md b/docs/ai-brand-monitoring-tech-design-v3.md
new file mode 100644
index 0000000..4f6df54
--- /dev/null
+++ b/docs/ai-brand-monitoring-tech-design-v3.md
@@ -0,0 +1,934 @@
+# AI 品牌曝光监测系统技术方案 V3
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档名称 | AI 品牌曝光监测系统技术方案 V3（容量与口径修订稿） |
+| 文档版本 | V3.0 |
+| 文档状态 | 待评审 |
+| 创建日期 | 2026-04-05 |
+| 基线文档 | `docs/ai-brand-monitoring-tech-design-v2.md` |
+| 适用范围 | 数据追踪模块全部页面 |
+| 关联文档 | `docs/geo-platform-prd-v1.md` (PRD 8.4 数据追踪) |
+| 关联文档 | `docs/question-driven-monitoring-design-v1.md` (V1 数据模型) |
+| 容量目标 | 5 万并发 **活跃** 用户（同时打开页面、切换筛选、触发突刺流量） |
+
+## 2. V3 修订范围
+
+本文档不再只是 V2 的“容量补丁”。本版同时修正了 V2 与采集可行性方案之间的口径断层，尤其是：
+
+1. `run_mode` 未入模，导致标准回答和搜索增强回答不可比。
+2. 问题版本未完整进入汇总表唯一键，历史口径会被覆盖。
+3. 采集时间窗与聚合时序冲突，无法同时满足 T+1 发布与一致性。
+4. 在线缓存与离线任务队列共用同一 Redis 故障域，风险过高。
+
+读者应先读完 V2 全文，再用本文档替换或补充以下章节：
+
+| V2 章节 | V3 替换 / 补充章节 | 变更原因 |
+| --- | --- | --- |
+| 5. 数据库 Schema | 2.2 数据口径与 Schema Delta | V2 未建模 `run_mode`、版本键、引用事实 |
+| 8. 缓存策略 | 3. 读流量模型与缓存架构 | V2 低估页面 fan-out，缺少防雪崩手段 |
+| 10. 采集流水线设计 | 4. 采集流水线扩容 | V2 采集时间窗 / worker 容量不足 |
+| 11. 部署拓扑 | 5. 部署拓扑与资源 | V2 连接池计算有误、单点问题 |
+| 7. 后端架构 / 7.6 配置扩展 | 4.5、5.3、5.4 | V2 仍按单 provider / 单 Redis / 单 DB 结构假设 |
+| (无) | 6. 降级与容灾 | V2 缺失 |
+| 13. 实施计划 (Phase 21) | 7. 压测验收标准 | V2 缺失 |
+
+V2 其他章节（页面需求、前端组件、API 响应结构、指标定义）原则上保持不变；但只要与本文中的口径分层、Schema Delta、采集时序冲突，应以 V3 为准。
+
+### 2.1 数据口径分层与 UI 取数规则
+
+为避免把不可比的数据混到同一张榜单中，V3 将监测数据拆成 3 种采集模式：
+
+| `run_mode` | 含义 | 是否进入主统计 | 默认消费页面 |
+| --- | --- | --- | --- |
+| `api_standard` | 固定 prompt、低温、无搜索增强的标准 API 回答 | 是 | Dashboard、平台占比、竞争对手、业务主题、AI 对话问题、品牌印象 |
+| `api_search_grounded` | 开启平台官方搜索 / 引文能力后的回答 | 是，但单独统计 | AI 引用排名；未来可选做“搜索增强视角”专题页 |
+| `ui_sample` | 面向 PoC / 验证的前台 UI 采样结果 | 否 | 仅验证报表和 badcase，不进主 Dashboard |
+
+核心规则：
+
+1. **跨平台曝光、竞品、问题排行默认只看 `api_standard`。**
+2. **引用相关页面默认只看 `api_search_grounded`。**
+3. **不支持搜索增强或引文的平台，在引用页面中标记为“未接入 / 不支持”，不按 0 值并入分母。**
+4. **`ui_sample` 只用于验证，不参与 `monitoring_*` 主汇总。**
+
+### 2.2 Schema Delta（覆盖 V2 Schema 的必要修订）
+
+V2 的基础表结构仍可复用，但以下修订是必需项。
+
+#### 2.2.1 `ai_platforms`
+
+增加平台能力字段，避免查询层硬编码：
+
+1. `supports_standard BOOLEAN NOT NULL DEFAULT true`
+2. `supports_search_grounded BOOLEAN NOT NULL DEFAULT false`
+3. `supports_citation BOOLEAN NOT NULL DEFAULT false`
+4. `supports_batch BOOLEAN NOT NULL DEFAULT false`
+5. `default_run_mode VARCHAR(30) NOT NULL DEFAULT 'api_standard'`
+
+#### 2.2.2 `question_monitor_runs`
+
+新增以下字段：
+
+1. `business_date DATE NOT NULL`：统计归属日，允许 `run_at` 发生在次日凌晨。
+2. `run_mode VARCHAR(30) NOT NULL`：`api_standard` / `api_search_grounded` / `ui_sample`
+3. `provider_model VARCHAR(100) NOT NULL`
+4. `prompt_template_version VARCHAR(30) NOT NULL`
+5. `search_enabled BOOLEAN NOT NULL DEFAULT false`
+6. `request_id VARCHAR(100)`
+7. `retry_count INT NOT NULL DEFAULT 0`
+
+建议增加幂等索引：
+
+```sql
+CREATE UNIQUE INDEX uk_monitor_run_idempotent
+ON question_monitor_runs(tenant_id, brand_id, question_version_id, ai_platform_id, run_mode, business_date);
+```
+
+#### 2.2.3 `question_monitor_parse_results`
+
+新增以下字段：
+
+1. `run_mode VARCHAR(30) NOT NULL`
+2. `search_hit BOOLEAN NOT NULL DEFAULT false`
+3. `search_info_json_key TEXT`
+4. `extractor_version VARCHAR(30) NOT NULL DEFAULT 'v1'`
+
+#### 2.2.4 新增任务与质量表
+
+新增下列表：
+
+1. `monitoring_collect_tasks`：调度任务、重试、死信、优先级、租约状态
+2. `monitoring_citation_facts`：引用规范化事实表，保存 `normalized_url/domain/citation_hash`
+3. `monitoring_parse_badcases`：低置信度样本与人工回标结果
+
+#### 2.2.5 汇总表统一增加 `run_mode`
+
+以下汇总表必须增加 `run_mode`，并进入唯一键：
+
+1. `monitoring_brand_daily_overview`
+2. `monitoring_platform_daily`
+3. `monitoring_platform_question_daily`
+4. `monitoring_competitor_daily`
+5. `monitoring_competitor_platform_daily`
+6. `monitoring_topic_daily`
+7. `monitoring_question_daily`
+8. `monitoring_citation_source_daily`
+9. `monitoring_citation_page_daily`
+10. `monitoring_brand_impression`
+
+#### 2.2.6 问题版本进入汇总主键
+
+以下表必须增加 `question_version_id` 并进入唯一键：
+
+1. `monitoring_platform_question_daily`
+2. `monitoring_question_daily`
+
+推荐唯一键修订：
+
+```sql
+UNIQUE (tenant_id, brand_id, ai_platform_id, question_id, question_version_id, run_mode, metric_date)
+UNIQUE (tenant_id, brand_id, question_id, question_version_id, run_mode, metric_date)
+```
+
+#### 2.2.7 引用汇总改为从规范化事实表聚合
+
+`monitoring_citation_source_daily` 与 `monitoring_citation_page_daily` 不再直接从 `citation_urls JSONB` 聚合，而是从 `monitoring_citation_facts` 聚合：
+
+1. 页面级汇总按 `normalized_url`
+2. 站点级汇总按 `domain` / `site_name`
+3. 原始 `page_url` 仅用于回放与调试
+
+---
+
+## 3. 读流量模型与缓存架构
+
+### 3.1 页面 Fan-out 矩阵
+
+V2 错误地按"每人 30 秒 1 个请求"建模。实际上，每个页面打开时会 **并行** 发出多个 API 请求。
+
+| 页面 | 并行请求数 | 对应 API |
+| --- | --- | --- |
+| 主页 Dashboard | 6 | overview, exposure-trend, competitors, citation-sources, recent-questions, brand-impression |
+| 平台占比分析 | 2 | platform-stats, platform-questions |
+| 竞争对手分析 | 2 | competitor-exposure, competitor-detail |
+| 业务主题分析 | 1 | topics |
+| AI 对话问题 | 1 | questions (分页) |
+| AI 引用排名 | 2 | citation-trend, citation-pages |
+
+加权平均（按访问占比估算：主页 50%、其他页各 10%）：
+
+```
+weighted_fan_out = 0.50 × 6 + 0.10 × 2 + 0.10 × 2 + 0.10 × 1 + 0.10 × 1 + 0.10 × 2
+                = 3.0 + 0.2 + 0.2 + 0.1 + 0.1 + 0.2
+                = 3.8 次/页面打开
+```
+
+### 3.2 QPS 模型
+
+| 场景 | 计算 | QPS |
+| --- | --- | --- |
+| 稳态（50K 用户，平均 30 秒交互 1 次） | 50000 × 3.8 / 30 | **6,333** |
+| 突刺（早会/开盘集中打开，10 秒内 30% 用户首屏加载） | 15000 × 6 / 10 | **9,000** |
+| 筛选切换（20% 用户同时切换品牌/时间范围） | 10000 × 3.8 / 5 | **7,600** |
+| 设计容量（取 P99 峰值 × 1.5 安全余量） | max(6333, 9000, 7600) × 1.5 | **~13,500** |
+
+**结论**：系统必须在 Redis 层稳定承接 13,500 QPS。穿透到 PG 的流量目标 < 1,350 QPS（10% miss rate）。
+
+### 3.3 BFF 聚合层（减少 fan-out 的关键手段）
+
+为降低首页 6 次并行请求的压力，引入 **BFF 聚合接口**：
+
+```
+GET /api/tenant/monitoring/dashboard/composite
+    → 服务端并行查询 6 个数据源，一次返回全部首页数据
+    → 默认固定 `scope=standard`
+    → 单次 Redis GET 命中完整 composite 缓存即可返回
+    → 缓存 miss 时服务端内部 goroutine 并行查 6 个汇总表
+```
+
+前端首屏只发 **1 个请求**，极端情况下用户手动刷新某个区块再发单接口。
+
+| 方案 | 首页 QPS (50K 用户) | Redis 压力 |
+| --- | --- | --- |
+| 6 个独立接口 | ~10,000 | 60K ops/s |
+| composite 聚合 | ~1,667 | 1,667 ops/s |
+
+其他页面 fan-out ≤ 2，不需要聚合。
+
+### 3.4 缓存防雪崩机制
+
+V2 仅使用 TTL + 聚合后全量删除，存在雪崩风险。V3 引入 4 层防护：
+
+#### 3.4.1 Singleflight
+
+同一 cache key 的并发 miss 请求，只放行 1 个打到 PG，其余等待结果。
+
+```go
+import "golang.org/x/sync/singleflight"
+
+var sf singleflight.Group
+
+func (s *MonitoringService) getWithCache(ctx context.Context, key string, ttl time.Duration, loader func() (any, error)) (any, error) {
+    // 1. 尝试 Redis GET
+    if cached, err := s.cache.Get(ctx, key); err == nil {
+        return cached, nil
+    }
+    // 2. Singleflight: 同 key 只执行一次 loader
+    result, err, _ := sf.Do(key, func() (any, error) {
+        data, err := loader()
+        if err != nil {
+            return nil, err
+        }
+        // 写回 Redis，TTL 加随机抖动
+        jitteredTTL := ttl + time.Duration(rand.Int63n(int64(ttl/5)))
+        _ = s.cache.Set(ctx, key, data, jitteredTTL)
+        return data, nil
+    })
+    return result, err
+}
+```
+
+#### 3.4.2 TTL 随机抖动
+
+防止大量 key 同时过期导致集中穿透。
+
+```
+实际 TTL = 基础 TTL + random(0, 基础 TTL × 20%)
+```
+
+例如 5 分钟基础 TTL → 实际 300~360 秒。
+
+#### 3.4.3 Stale-While-Revalidate
+
+缓存过期后，先返回旧数据，后台异步刷新。用户不感知延迟。
+
+```go
+// Redis 存储两个 key:
+//   mon:{key}        → 数据 (TTL = base_ttl)
+//   mon:{key}:stale  → 数据 (TTL = base_ttl × 3，作为兜底)
+//
+// 读取流程:
+// 1. GET mon:{key} → 命中 → 返回
+// 2. miss → GET mon:{key}:stale → 命中 → 返回 stale 数据 + 异步触发刷新
+// 3. 都 miss → 同步查 PG + singleflight
+```
+
+#### 3.4.4 热点保护（Hot Key）
+
+对高频访问的品牌（如首页默认品牌），使用 **进程内 L1 缓存**（Go sync.Map 或 groupcache）：
+
+```
+请求 → L1 进程缓存 (TTL 10s) → Redis (TTL 5min) → PG
+```
+
+L1 缓存的极短 TTL 保证数据不会太旧，但能挡住 Redis 的瞬时压力。
+
+### 3.5 缓存 Key 修订
+
+修复 V2 的分页缓存 key 缺少 `page_size` 的问题，同时将统计口径 `scope` 纳入缓存维度。
+
+约定：
+
+1. `scope=standard` 对应 `run_mode=api_standard`
+2. `scope=search` 对应 `run_mode=api_search_grounded`
+3. `ui_sample` 不进入线上缓存
+
+```
+# 分页接口必须包含 scope + page + page_size
+mon:{tenant}:{brand}:platform:{pid}:questions:{days}:{scope}:{page}:{pageSize}
+mon:{tenant}:{brand}:questions:{pid}:{days}:{scope}:{page}:{pageSize}
+mon:{tenant}:{brand}:citation_pages:{days}:{scope}:{page}:{pageSize}
+
+# composite 聚合接口
+mon:{tenant}:{brand}:dashboard_composite:{days}:{scope}
+
+# 非分页接口也加 scope
+mon:{tenant}:{brand}:overview:{days}:{scope}
+mon:{tenant}:{brand}:trend:{days}:{scope}
+mon:{tenant}:{brand}:competitors:{days}:{scope}
+...
+```
+
+### 3.6 缓存失效策略修订
+
+V2 的"聚合后删除品牌全部缓存"策略改为 **渐进式失效**：
+
+| 时机 | 操作 | 原因 |
+| --- | --- | --- |
+| 聚合 Job 完成 | **不删除** 现有缓存 | 避免 5 万用户同时穿透 |
+| 聚合 Job 完成 | 异步预热 Top 20 热门品牌的 composite 缓存 | 用新数据替换旧缓存 |
+| 聚合 Job 完成 | 设置全局标记 `mon:agg_version:{tenant}` +1 | 通知各实例 L1 缓存过期 |
+| 自然过期 | TTL 到期后正常 singleflight 回源 | 冷数据自然刷新 |
+
+### 3.7 修订后的 TTL 矩阵
+
+| 数据类型 | Redis TTL | Stale TTL | L1 TTL | 说明 |
+| --- | --- | --- | --- | --- |
+| Dashboard composite | 5 min | 15 min | 10 s | 首页入口，高频访问 |
+| Overview 指标卡 | 5 min | 15 min | 10 s | 同上 |
+| 趋势图 | 15 min | 45 min | 30 s | 日级数据，变化慢 |
+| 竞品排名 | 15 min | 45 min | 30 s | 同上 |
+| 引用来源 | 15 min | 45 min | 30 s | 同上 |
+| 业务主题 | 30 min | 90 min | 60 s | 低频变更 |
+| 问题列表（分页） | 10 min | 30 min | 不缓存 | 粒度太细，L1 命中率低 |
+| 品牌印象 | 30 min | 90 min | 60 s | 日级聚合 |
+| AI 平台列表 | 1 hour | 3 hour | 5 min | 几乎不变 |
+
+---
+
+## 4. 采集流水线扩容
+
+### 4.1 V2 瓶颈分析
+
+V2 的问题：
+- 5 worker、50,000 任务 → 每任务仅 0.72 秒，不现实
+- 凌晨 1 点采集、3 点聚合 → 2 小时时间窗太紧
+- Collector ×1、Aggregator ×1 → 单点故障
+
+### 4.2 任务量重新估算
+
+```
+标准模式:
+100 品牌 × 100 问题/品牌 × 5 AI 平台 = 50,000 任务/天
+
+搜索增强模式（首批仅 3 平台: qwen / doubao / hunyuan）:
+100 品牌 × 100 问题/品牌 × 3 AI 平台 = 30,000 任务/天
+
+合计 = 80,000 任务/天
+
+# 但问题 hash 去重后（V1 设计）
+假设去重率 30% → 实际 56,000 唯一任务
+
+# 每次 AI API 调用 + 解析 + 入库:
+平均耗时: 8 秒 (含 AI 生成 5s + 解析 2s + 入库 1s)
+P99 耗时: 20 秒 (含重试)
+```
+
+### 4.3 Worker 池设计
+
+```
+所需总处理时间 = 56,000 × 8s = 448,000 秒
+可用采集时间窗 = 6 小时 = 21,600 秒 (0:00 ~ 6:00)
+
+所需并发 worker = 448,000 / 21,600 ≈ 21
+安全系数 1.4 → 30 worker
+```
+
+**架构**：
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  采集调度器 (Scheduler)                │
+│  • 凌晨 0:00 启动                                     │
+│  • 生成 business_date = yesterday 的全部任务           │
+│  • 任务维度: 品牌 × 去重问题 × 平台 × run_mode          │
+│  • 写入 Queue Redis Stream: mon:collect:tasks         │
+└───────────────────────┬─────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┬─────────────┐
+          ▼             ▼             ▼             ▼
+   ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
+   │ Collector  │ │ Collector  │ │ Collector  │ │ Collector  │
+   │  Pod #1    │ │  Pod #2    │ │  Pod #3    │ │ standby HPA│
+   │ worker ×10 │ │ worker ×10 │ │ worker ×10 │ │ 按需扩容    │
+   └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘
+          │              │              │              │
+          ▼              ▼              ▼              ▼
+   ┌─────────────────────────────────────────┐
+   │           Queue Redis Stream            │
+   │  mon:collect:tasks (pending → ack)      │
+   │  Consumer Group: collectors             │
+   └─────────────────────────────────────────┘
+```
+
+**为什么用 Redis Stream 而不是内存队列**：
+- 多 Pod 竞争消费，自动负载均衡
+- 消息持久化，Pod 重启不丢任务
+- Consumer Group 的 XACK 机制提供 at-least-once 保证
+- 但必须使用 **独立 Queue Redis 故障域**，不能和在线缓存共用实例
+
+### 4.4 时间窗修订
+
+```
+0:00  调度器生成 business_date = yesterday 的全部采集任务 → Queue Redis Stream
+0:00 ~ 6:00  Collector workers 消费任务，调用 AI API + 解析 + 写 PG/MinIO
+6:00  检查未完成任务数量，告警如果 > 5%
+6:10  将未完成任务转入 backfill 队列，不阻塞晨间主聚合
+6:30  Aggregator 聚合 business_date = yesterday 且 status = succeeded 的数据
+7:00  聚合完成 → 预热热门品牌缓存
+7:30  T+1 数据上线，用户访问“昨日完整快照”
+```
+
+说明：
+
+1. `run_at` 是实际执行时间，可能发生在次日凌晨。
+2. `business_date` 是统计归属日，Dashboard 晨间看到的是 T+1 快照。
+3. 晚到任务走 backfill，单独触发品牌级重聚合，不污染主发布窗口。
+
+预留 6 小时采集窗口（vs V2 的 2 小时），即使 P99 延迟也有足够 buffer。
+
+### 4.5 采集重试与限流
+
+```go
+// 每个 AI 平台独立的限流器
+type PlatformRateLimiter struct {
+    limiters map[string]*rate.Limiter  // provider_key → limiter
+}
+
+// 默认限流配置
+var defaultLimits = map[string]rate.Limit{
+    "deepseek": 10,  // 10 QPS
+    "qwen":     10,
+    "doubao":   10,
+    "hunyuan":  5,
+    "ernie":    5,
+}
+
+// 重试策略
+const (
+    maxRetries    = 3
+    retryBaseWait = 2 * time.Second  // 指数退避: 2s, 4s, 8s
+)
+```
+
+此外，Collector 必须基于 `run_mode` 和平台能力做任务路由：
+
+1. 不支持 `api_search_grounded` 的平台不生成搜索增强任务。
+2. `ui_sample` 任务只进入 PoC / badcase 流水线，不进入主聚合队列。
+3. `api_standard` 与 `api_search_grounded` 使用不同的 prompt 模板版本。
+
+### 4.6 采集容错
+
+```go
+// 单条任务失败不阻塞批次
+func (w *CollectorWorker) processTask(ctx context.Context, task CollectTask) {
+    for attempt := 1; attempt <= maxRetries; attempt++ {
+        err := w.collect(ctx, task)
+        if err == nil {
+            w.stream.XAck(ctx, "mon:collect:tasks", "collectors", task.ID)
+            return
+        }
+        if isRateLimited(err) {
+            time.Sleep(retryBaseWait * time.Duration(1<<(attempt-1)))
+            continue
+        }
+        // 非限流错误直接标记失败
+        w.markFailed(ctx, task, err)
+        w.stream.XAck(ctx, "mon:collect:tasks", "collectors", task.ID)
+        return
+    }
+    w.markFailed(ctx, task, fmt.Errorf("max retries exceeded"))
+    w.stream.XAck(ctx, "mon:collect:tasks", "collectors", task.ID)
+}
+```
+
+### 4.7 聚合 Job 扩容
+
+```
+┌───────────────────────────────────────────────────────┐
+│                   Aggregator Job                       │
+│  • 6:30 启动（聚合 business_date = yesterday）            │
+│  • 按租户 × 品牌分片，每片独立事务                        │
+│  • 并发聚合 goroutine: 10                               │
+│  • 聚合完一个品牌 → 异步预热该品牌缓存                     │
+│  • 全部完成后 → 全局 agg_version +1                      │
+└───────────────────────────────────────────────────────┘
+```
+
+聚合 Job 部署 **2 个实例**（主备），使用 **PG advisory lock** 选主，只有一个实例实际运行，另一个待命。
+
+---
+
+## 5. 部署拓扑与资源
+
+### 5.1 修正：连接池是 per-process 的
+
+V2 错误地把 `max_open_conns: 50` 当作"3 个实例共享"。实际上 `bootstrap.go` 的 `pgxpool.Pool` 是每个进程独立初始化的。
+
+**修正后的连接池规划**：
+
+```yaml
+# 每个 API 实例
+database:
+  max_open_conns: 20        # 每实例 20
+  max_idle_conns: 5
+
+# 3 个 API 实例 → PG 总连接: 60
+# 3 个 Collector 实例 → PG 总连接: 30 (各 10)
+# 1 个 Aggregator 实例 → PG 总连接: 20
+# 合计: 110 连接
+
+# PostgreSQL 需配置:
+# max_connections = 160 (留 50 余量给运维和监控)
+```
+
+### 5.1.1 配置模型 Delta
+
+V3 不能继续沿用当前项目的单 `database`、单 `redis`、单 `llm` 配置模型，必须扩展为以下结构：
+
+```yaml
+database:
+  primary:
+    host: pg-primary
+    ...
+  replica:
+    host: pg-replica
+    ...
+
+redis:
+  cache:
+    sentinel:
+      master_name: geo-cache-master
+      addrs: ["cache-sentinel-1:26379", "cache-sentinel-2:26379", "cache-sentinel-3:26379"]
+    db: 0
+  queue:
+    sentinel:
+      master_name: geo-queue-master
+      addrs: ["queue-sentinel-1:26379", "queue-sentinel-2:26379", "queue-sentinel-3:26379"]
+    db: 0
+
+monitoring:
+  providers:
+    deepseek:
+      enabled: true
+      supports_standard: true
+      supports_search_grounded: false
+    qwen:
+      enabled: true
+      supports_standard: true
+      supports_search_grounded: true
+    doubao:
+      enabled: true
+      supports_standard: true
+      supports_search_grounded: true
+    hunyuan:
+      enabled: true
+      supports_standard: true
+      supports_search_grounded: true
+    ernie:
+      enabled: false   # PoC 通过后再开启
+```
+
+这意味着：
+
+1. `server/internal/shared/config/config.go` 必须扩展结构体，不是“小改动”。
+2. `bootstrap.go` 必须初始化双 DB pool、双 Redis client、provider registry。
+3. 监测模块必须摆脱全局单 provider `llm.Client` 的限制。
+
+### 5.2 部署架构
+
+```
+                         ┌─────────────────────────────┐
+                         │      CDN (静态资源)           │
+                         │  admin-web 打包后的 JS/CSS    │
+                         └──────────────┬──────────────┘
+                                        │
+                         ┌──────────────▼──────────────┐
+                         │   Nginx / 云 LB (SLB/ALB)    │
+                         │   API 路由 + 健康检查          │
+                         │   限流: 每 IP 200 req/s       │
+                         └──────────┬───────────────────┘
+                                    │
+              ┌─────────────────────┼─────────────────────┐
+              ▼                     ▼                     ▼
+       ┌────────────┐       ┌────────────┐       ┌────────────┐
+       │ tenant-api  │       │ tenant-api  │       │ tenant-api  │
+       │   Pod #1    │       │   Pod #2    │       │   Pod #3    │
+       │ API 20conn  │       │ API 20conn  │       │ API 20conn  │
+       │ L1 cache    │       │ L1 cache    │       │ L1 cache    │
+       └──────┬──────┘       └──────┬──────┘       └──────┬──────┘
+              │                     │                     │
+       ┌──────┴─────────────────────┴─────────────────────┴──────┐
+       │                Cache Redis 6+ (主从 Sentinel)             │
+       │   用途: API 缓存 + JWT 会话                               │
+       └────────────────────────┬─────────────────────────────────┘
+                                │
+       ┌────────────────────────┼────────────────────────┬────────┐
+       │                        │                        │        │
+       ▼                        ▼                        ▼        ▼
+┌─────────────┐         ┌─────────────┐         ┌─────────────┐  ┌─────────────┐
+│ PG Primary  │────────▶│ PG Replica  │         │    MinIO     │  │ Queue Redis  │
+│  (读写)     │  流复制  │  (只读)     │         │  (原始回答)   │  │  Streams      │
+│ 160 conns   │         │ 50 conns    │         │  S3 兼容     │  │  独立故障域    │
+└─────────────┘         └─────────────┘         └─────────────┘  └──────┬──────┘
+       ▲                        ▲                                          │
+       │                        │                                          │
+       │   ┌────────────────────┘  Aggregator 的重查询走 Replica           │
+       │   │                                                               │
+┌──────┴───┴──────────────────────────────────────────────┐
+│              独立进程（不接入 LB）                         │
+│                                                          │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│  │ Collector Pod #1 │  │ Collector Pod #2 │  │ Collector Pod #3 │  ×3 Pod
+│  │ worker ×10       │  │ worker ×10       │  │ worker ×10       │  (竞争消费)
+│  │ PG conn: 10      │  │ PG conn: 10      │  │ PG conn: 10      │
+│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘
+│           │                    │                    │
+│           └────────────────────┴────────────────────┘
+│                                │
+│                                ▼
+│                         Queue Redis Stream
+│                                                          │
+│  ┌─────────────────┐  ┌─────────────────┐                │
+│  │ Aggregator #1    │  │ Aggregator #2    │  主备（锁选主）│
+│  │ (active)         │  │ (standby)        │               │
+│  │ PG conn: 20      │  │ PG conn: 0       │               │
+│  │ 读走 Replica     │  │                  │               │
+│  └─────────────────┘  └─────────────────┘                │
+╚══════════════════════════════════════════════════════════╝
+```
+
+### 5.3 Redis 高可用与故障域隔离
+
+V2 使用 Redis 单点，且在线缓存与离线任务共用同一实例。V3 修正为 **双 Redis 故障域**：
+
+1. `redis.cache`：面向 API 读流量，承接缓存与会话
+2. `redis.queue`：面向离线采集，承接 Stream 队列
+
+推荐配置：
+
+```yaml
+redis:
+  cache:
+    sentinel:
+      master_name: "geo-cache-master"
+      addrs:
+        - "cache-sentinel-1:26379"
+        - "cache-sentinel-2:26379"
+        - "cache-sentinel-3:26379"
+    db: 0
+  queue:
+    sentinel:
+      master_name: "geo-queue-master"
+      addrs:
+        - "queue-sentinel-1:26379"
+        - "queue-sentinel-2:26379"
+        - "queue-sentinel-3:26379"
+    db: 0
+```
+
+Go 客户端（go-redis v9）原生支持 Sentinel，但这里需要初始化 **两个** client：
+
+```go
+cacheRDB := newRedisClient(cfg.Redis.Cache)
+queueRDB := newRedisClient(cfg.Redis.Queue)
+```
+
+### 5.4 PostgreSQL 读写分离
+
+API 服务的监测查询走 **PG Replica**。通过在 `MonitoringService` 中注入两个 pool：
+
+```go
+type MonitoringService struct {
+    writePool *pgxpool.Pool   // Primary，仅供 aggregator 写入
+    readPool  *pgxpool.Pool   // Replica，Dashboard 查询
+    cache     cache.Cache
+    sf        singleflight.Group
+}
+```
+
+在 `bootstrap.go` 中初始化时，如果配置了 `database.replica`，则创建第二个连接池。
+
+### 5.5 资源规格修订
+
+| 组件 | 实例数 | 规格 | PG 连接 | 说明 |
+| --- | --- | --- | --- | --- |
+| **tenant-api** | 3 | 4C8G | 20/实例 | API 含 L1 缓存、singleflight |
+| **Cache Redis Sentinel** | 1主1从3哨兵 | 8G 内存 | - | API 缓存 + JWT 会话 |
+| **Queue Redis Sentinel** | 1主1从3哨兵 | 4G 内存 | - | Stream 队列，独立故障域 |
+| **PG Primary** | 1 | 8C32G | max 160 | SSD，汇总表 + 原始采集表 |
+| **PG Replica** | 1 | 4C16G | max 50 | SSD，Dashboard 只读查询 |
+| **MinIO** | 1 | 4C8G, 100G SSD | - | 原始回答对象存储 |
+| **Collector** | 3 Pod | 2C4G | 10/Pod | Queue Redis Stream 竞争消费 |
+| **Aggregator** | 2 Pod (主备) | 4C8G | 20 (active only) | 分布式锁选主 |
+| **CDN** | - | - | - | 静态资源 + Nginx 限流 |
+
+---
+
+## 6. 降级与容灾
+
+### 6.1 降级策略
+
+| 故障场景 | 降级措施 | 用户感知 |
+| --- | --- | --- |
+| **Cache Redis 主节点故障** | Sentinel 自动切换从节点为主（< 30s） | 短暂超时后恢复 |
+| **Cache Redis 完全不可用** | API 直接查 PG，跳过缓存；Nginx 层限流降至 50 req/s/IP | 响应变慢但可用 |
+| **Queue Redis 故障** | 采集调度与 Collector 暂停；线上查询不受影响 | 当天数据延迟，但 Dashboard 继续服务旧数据 |
+| **PG Primary 故障** | Dashboard 查询走 Replica 不受影响；采集/聚合暂停 | Dashboard 可用，数据冻结在最后聚合时间 |
+| **PG Replica 故障** | Dashboard 查询回退到 Primary | 无感知，Primary 负载上升 |
+| **单个 AI 平台 API 超时** | 该平台任务标记 failed，其他平台正常采集 | 该平台在对应模式下标记“数据缺失”，不强制展示为 0 |
+| **全部 AI 平台不可用** | 当天采集任务全部失败，Dashboard 展示前一天数据 | 显示"数据更新时间：昨日" |
+| **Collector Pod 全挂** | Queue Redis 消息堆积，等待 Pod 恢复后继续消费 | 当天数据延迟 |
+| **Aggregator 异常** | 另一个 Aggregator Pod 抢锁接管 | 无感知 |
+
+### 6.2 熔断器
+
+对外部 AI 平台 API 使用熔断器（circuit breaker）：
+
+```go
+// 每个 AI 平台独立的熔断器
+type PlatformBreaker struct {
+    breakers map[string]*circuitbreaker.CircuitBreaker
+}
+
+// 配置
+// 连续 5 次失败 → 打开熔断 → 30 秒后半开 → 1 次成功 → 关闭
+```
+
+### 6.3 监控告警
+
+| 指标 | 告警阈值 | 通知方式 |
+| --- | --- | --- |
+| API P99 延迟 | > 2s 持续 5 分钟 | 钉钉/飞书 |
+| Cache Redis 命中率 | < 80% 持续 10 分钟 | 钉钉/飞书 |
+| Queue Redis backlog | > 10,000 持续 10 分钟 | 钉钉/飞书 |
+| PG 连接池使用率 | > 80% | 钉钉/飞书 |
+| 采集任务失败率 | > 10% 单平台 | 钉钉/飞书 |
+| 聚合 Job 未在 8:00 前完成 | 超时 | 电话 + 钉钉 |
+| Cache/Queue Redis Sentinel 主从切换 | 任何切换事件 | 电话 + 钉钉 |
+
+### 6.4 数据一致性保障
+
+| 场景 | 措施 |
+| --- | --- |
+| 聚合 Job 被中断 | 每个品牌的聚合是独立事务，失败后可重跑该品牌 |
+| 采集与聚合时间窗重叠 | 聚合只处理 `business_date = yesterday AND status = succeeded` 的数据 |
+| 缓存与 PG 不一致 | stale-while-revalidate 保证最终一致，不保证强一致 |
+| 原始回答写 MinIO 失败 | 标记该 run 为 failed，解析结果不写入 |
+| 晚到补采任务 | 进入 backfill 队列，只重聚合受影响品牌，不改写已发布快照的全局口径 |
+
+---
+
+## 7. 压测验收标准
+
+### 7.1 压测场景模型
+
+| 场景编号 | 场景名称 | 虚拟用户数 | 行为 | 持续时间 |
+| --- | --- | --- | --- | --- |
+| S1 | 稳态浏览 | 50,000 | 每 30 秒打开 1 个页面（加权 fan-out 3.8） | 30 min |
+| S2 | 早高峰突刺 | 50,000 | 0~60 秒内全部打开首页（composite 接口） | 1 min ramp-up |
+| S3 | 筛选风暴 | 20,000 | 每 5 秒切换品牌/时间范围 | 10 min |
+| S4 | 缓存失效 | 50,000 | 手动清空 Cache Redis 后观察恢复 | 5 min |
+| S5 | Cache Redis 故障 | 50,000 | kill Cache Redis master，观察 Sentinel 切换 | 2 min |
+| S6 | Queue Redis 故障 | 0 | kill Queue Redis master，观察采集暂停与恢复 | 30 min |
+
+### 7.2 性能目标（SLA）
+
+| 指标 | 目标值 | 说明 |
+| --- | --- | --- |
+| API P50 延迟 | < 50 ms | 稳态，Redis 命中 |
+| API P95 延迟 | < 200 ms | 稳态 |
+| API P99 延迟 | < 500 ms | 含缓存 miss + PG 查询 |
+| API P99 延迟（突刺） | < 2 s | S2 场景 |
+| 错误率 | < 0.1% | 5xx 错误 |
+| Cache Redis 命中率 | > 90% | 稳态 |
+| PG QPS（穿透） | < 1,500 | 10% miss rate |
+| 采集完成率 | > 95% | 日采集任务成功率 |
+| 聚合 SLA | 8:00 前完成 | 用户上班前数据可用 |
+| Cache Redis 故障恢复 | < 30 s | Sentinel 自动切换 |
+| Queue Redis 恢复后 backlog 清空 | < 60 min | 采集可恢复性 |
+
+### 7.3 压测工具与脚本
+
+```
+# 推荐工具: k6 (grafana/k6)
+# 脚本位置: tests/load/
+
+tests/load/
+├── k6.config.js               # 共享配置
+├── scenarios/
+│   ├── s1_steady_browse.js    # 稳态浏览
+│   ├── s2_peak_burst.js       # 早高峰突刺
+│   ├── s3_filter_storm.js     # 筛选风暴
+│   ├── s4_cache_flush.js      # 缓存失效
+│   └── s5_cache_redis_failover.js   # Cache Redis 故障
+├── helpers/
+│   ├── auth.js                # 登录获取 token
+│   └── brands.js              # 随机品牌选择
+└── README.md                  # 运行说明（S6 Queue Redis 故障为运维演练，无 k6 脚本）
+```
+
+### 7.4 压测前置条件
+
+1. **数据准备**：100 品牌 × 100 问题 × 5 平台 × 30 天汇总数据已填充
+2. **用户池**：50,000 个预创建的测试用户 token
+3. **环境**：与生产同规格的独立压测环境
+4. **监控**：Prometheus + Grafana 大盘实时观察
+
+### 7.5 验收流程
+
+```
+Phase 1: 基线测试
+  → 5,000 用户稳态，确认 P99 < 100ms
+  → 记录基线指标
+
+Phase 2: 容量爬坡
+  → 逐步提升: 10K → 20K → 30K → 40K → 50K
+  → 每级停留 5 分钟，观察指标是否劣化
+  → 记录每级的 P50/P95/P99、错误率、Redis/PG 指标
+
+Phase 3: 极限测试
+  → 50K 稳态 30 分钟
+  → 中间插入 S2 突刺、S3 筛选风暴
+  → 确认所有 SLA 指标达标
+
+Phase 4: 容灾演练
+  → S4 缓存失效：确认 singleflight 生效，PG 不被打爆
+  → S5 Cache Redis 故障：确认 Sentinel 切换 < 30s，API 降级可用
+  → S6 Queue Redis 故障：确认在线 API 不受影响，采集恢复后 backlog 可消化
+
+Phase 5: 报告
+  → 输出压测报告，包含:
+     - 每个场景的延迟分布图
+     - 资源使用率（CPU/内存/连接池/磁盘IO）
+     - 瓶颈分析与调优建议
+     - 通过/未通过结论
+```
+
+---
+
+## 8. 实施计划修订
+
+在 V2 原有 Phase 15~21 的基础上，调整以下 Phase：
+
+### Phase 15 修订：DB 迁移 + 数据口径
+
+新增：
+- `run_mode`、`business_date`、平台能力字段 migration
+- `question_version_id` 进入问题级汇总唯一键
+- 新增 `monitoring_collect_tasks` / `monitoring_citation_facts` / `monitoring_parse_badcases`
+- 引用聚合改为从规范化事实表出发
+
+### Phase 16 修订：后端查询服务
+
+新增：
+- `getWithCache()` 通用缓存方法 + singleflight + stale-while-revalidate
+- Dashboard composite 聚合接口
+- `MonitoringService` 注入 readPool/writePool
+- L1 进程内缓存层
+- 所有查询默认显式带 `run_mode` / `scope`
+
+### Phase 17 修订：采集流水线
+
+新增：
+- Queue Redis Stream 任务队列替代内存队列
+- `MonitoringProvider` 平台适配器注册表
+- `PlatformRateLimiter` 每平台独立限流
+- `PlatformBreaker` 熔断器
+- 多 Pod 竞争消费架构
+- 重试 + 容错逻辑
+- `business_date` + backfill 流程
+- `api_standard` / `api_search_grounded` 分流调度
+
+### Phase 18 修订：聚合 Job
+
+新增：
+- 分布式锁选主
+- 聚合后预热热门品牌缓存（替代全量删除）
+- 并发 goroutine 聚合（10 并发）
+- 聚合读走 PG Replica
+- 晚到任务品牌级重聚合
+- 引用事实表 → 日汇总表的聚合逻辑
+
+### 新增 Phase 22: 基础设施
+
+- Cache Redis Sentinel 部署配置
+- Queue Redis Sentinel 部署配置
+- PG 流复制 + Replica 配置
+- Nginx 限流配置
+- 监控告警配置（Prometheus + Grafana）
+- 估时：3 天
+
+### 新增 Phase 23: 压测与验收
+
+- 编写 k6 压测脚本（5 个压测场景）+ 1 个运维演练场景
+- 数据准备脚本（100 品牌 × 30 天种子数据）
+- 执行 Phase 1~4 验收流程
+- 输出压测报告
+- 估时：3 天
+
+### 新增 Phase 24: 平台 PoC 与口径验收
+
+- 3 品牌 × 30 问题 × 3 天的平台 PoC
+- 验证搜索增强引用质量与波动
+- 决定百度千帆是否进入首批上线白名单
+- 估时：4 天
+
+### 修订后总估时
+
+| Phase | 内容 | V2 估时 | V3 估时 | 增量 |
+| --- | --- | --- | --- | --- |
+| 15 | DB 迁移 + 数据口径 | 1 天 | 3 天 | +2（run_mode、business_date、任务/引用事实表） |
+| 16 | 查询服务 + 缓存层 | 3 天 | 6 天 | +3（singleflight、composite、L1、读写分离、scope 过滤） |
+| 17 | 采集流水线 | 3 天 | 7 天 | +4（Provider Registry、双 run_mode、Queue Redis、多 Pod、限流熔断） |
+| 18 | 聚合 Job | 2 天 | 4 天 | +2（分布式锁、预热、并发聚合、backfill） |
+| 19 | 种子数据 | 1 天 | 1 天 | 0 |
+| 20 | 前端 6 页面 + ECharts | 4 天 | 4 天 | 0 |
+| 21 | 前端验证 + 集成测试 | 1 天 | 1 天 | 0 |
+| 22 | 基础设施（新增） | - | 3 天 | +3 |
+| 23 | 压测与验收（新增） | - | 3 天 | +3 |
+| 24 | 平台 PoC 与口径验收（新增） | - | 4 天 | +4 |
+| **合计** | | **15 天** | **32 天** | **+17 天** |
+
+---
+
+## 9. V2 → V3 变更汇总
+
+| 问题编号 | V2 问题 | V3 解决方案 |
+| --- | --- | --- |
+| **H0** | `run_mode` 未入模，标准回答与搜索增强回答混算 | 主统计按 `api_standard` / `api_search_grounded` 分层，默认页面显式取数规则 |
+| **H1** | 读流量按 1 req/30s 估算，实际首页 6 个并行请求 | 重新建模 fan-out，引入 BFF composite 接口将首页降为 1 请求 |
+| **H2** | TTL + 聚合后全删缓存，无防雪崩 | 4 层防护：singleflight + TTL 抖动 + stale-while-revalidate + L1 热点缓存 |
+| **H3** | 5 worker、2 小时时间窗，采集跑不完 | 30 worker、6 小时窗口、Queue Redis 多 Pod 竞争消费 |
+| **H4** | 问题版本未进入全部汇总唯一键 | `question_version_id` 进入问题级汇总唯一键，避免历史口径覆盖 |
+| **H5** | 日采集与日聚合时序矛盾 | 使用 `business_date = yesterday` 的 T+1 发布模型 + backfill |
+| **M1** | max_open_conns 50 被当作共享，实际 per-process | 显式规划每进程连接数，PG max_connections=160 |
+| **M2** | 缺少压测验收 | 6 个场景模型 + SLA 指标 + k6 脚本 + 4 阶段验收流程 |
+| **M3** | 分页缓存 key 缺 page_size | 所有分页 key 加入 `scope + page_size` 维度 |
+| **M4** | 引用按原始 URL 聚合，易重复计数 | 引入 `monitoring_citation_facts`，按 `normalized_url/domain` 聚合 |
+| **M5** | 在线缓存与离线队列共用 Redis 故障域 | Cache Redis / Queue Redis 拆分，分别高可用 |
+| **新增** | 无降级容灾策略 | 双 Redis Sentinel + PG 读写分离 + 熔断器 + 降级措施矩阵 |
+| **新增** | 无监控告警 | 7 项核心告警指标 + 阈值 |
diff --git a/docs/claude_architecture_review_2.md b/docs/claude_architecture_review_2.md
deleted file mode 100644
index 521def2..0000000
--- a/docs/claude_architecture_review_2.md
+++ /dev/null
@@ -1,215 +0,0 @@
-# GEO 平台技术架构 V1 二次审查报告
-
-> 基于更新后的 [geo-platform-ops-admin-tech-architecture-v1.md](file:///d:/project/geo/docs/geo-platform-ops-admin-tech-architecture-v1.md)（1257 行），对照 `docs/refer` 中 8 个功能截图、两份 PRD 及 5 万并发用户目标进行审查。
-
----
-
-## 一、前次缺失修复确认
-
-| # | 前次严重缺失 | 修复状态 | 说明 |
-| --- | --- | --- | --- |
-| 1 | 定时调度器完全未设计 | ✅ 已修复 | §13.7.2 新增 `cmd/scheduler`，数据库到期扫描 + 行级锁防重 |
-| 2 | Prompt 规则管理无后端模块 | ✅ 已修复 | §13.5.3 新增 `tenant/prompt-rule`，§13.11.2 新增 `prompt_rules` 表 |
-| 3 | 模板管理后端模块缺失 | ✅ 已修复 | §13.5.3 新增 `tenant/template`，§13.11.2 新增 `article_templates` 表 |
-| 4 | 数据库 Schema 缺失 | ✅ 已修复 | §13.11 提供 30+ 表的最小 Schema，含关键字段和索引 |
-| 5 | GEO 指标采集方案未定义 | ✅ 已修复 | §13.9 定义完整的问题驱动监控模型 |
-| 6 | 文章优化/版本管理缺失 | ✅ 已修复 | 新增 `optimization_tasks` + `article_versions` 表 |
-| 7 | 浏览器插件通信协议缺失 | ✅ 已修复 | §13.8 定义插件会话模型 + 回调协议 |
-| 8 | 绑定回调接口缺失 | ✅ 已修复 | §13.6.3 新增 `/api/callback/plugin/bind` |
-| 9 | 竞品库管理缺失 | ✅ 已修复 | §13.11.3 新增 `competitors` 表 |
-| 10 | 复合维度查询缺失 | ✅ 已修复 | §13.9 + §13.11.6 定义 `keyword_model_daily_metrics` 多维聚合 |
-| 11 | 前端路由粒度不足 | ✅ 已修复 | §13.4 展开了完整路由 |
-| 12 | SSE 细节不足 | ✅ 已修复 | §13.10 定义事件类型、负载格式、连接策略 |
-
-> [!TIP]
-> **前次审查中指出的 15 项问题已全部修复。** 文档从 774 行扩展到 1257 行，新增的 §13 闭环补齐方案质量很高。
-
----
-
-## 二、功能完整性复查（对照 docs/refer 截图）
-
-| 功能页 | 路由 | API | 数据模型 | 异步组件 | 评价 |
-| --- | --- | --- | --- | --- | --- |
-| 工作台 | ✅ | ✅ 聚合 API | ✅ | ✅ | **完备** |
-| 模板创作 | ✅ | ✅ | ✅ `article_templates` | ✅ `worker-generate` | **完备** |
-| 自定义生成 | ✅ | ✅ | ✅ `prompt_rules` `schedule_tasks` | ✅ `scheduler` + `worker-generate` | **完备** |
-| 文章优化 | ✅ | ✅ | ✅ `optimization_tasks` `article_versions` | ✅ `worker-generate` | **完备** |
-| 媒体管理 | ✅ | ✅ + 回调 | ✅ `plugin_sessions` `publish_records` | ✅ 插件 + `worker-publish-callback` | **完备** |
-| 品牌词库 | ✅ | ✅ | ✅ 含问题版本 + 竞品 | ✅ `worker-analytics` | **完备** |
-| 知识库 | ✅ | ✅ | ✅ 分组 + 多来源 | ✅ `worker-knowledge` | **完备** |
-| 数据追踪 | ✅ | ✅ | ✅ 5 张聚合表 | ✅ `scheduler` + `worker-analytics` | **完备** |
-
-> **结论：8 个功能页全部达到"页面 → 路由 → API → 对象 → 任务 → 存储 → 状态回传"的完整闭环。**
-
----
-
-## 三、面向 5 万并发用户的技术问题
-
-以下是基于"5 万人同时使用 + 足够简单"目标的严格审查：
-
-### 🔴 必须解决的问题
-
-#### 1. Gateway 单点瓶颈 — 缺少水平扩展方案
-
-文档中 `cmd/gateway` 是唯一入口，但未说明：
-- Gateway 是否无状态可水平扩展（多实例部署）
-- 前端连接的负载均衡策略（L4/L7）
-- Gateway 与 `tenant-api` / `platform-api` 之间的通信方式（直连 or 服务发现）
-
-> 5 万并发用户假设平均每人每 10 秒发一次请求 = **5000 QPS**。单个 Go 进程可以处理，但 SSE 长连接会占用大量连接数。
-
-**建议**：明确 Gateway 无状态 + Kubernetes HPA 策略 + Nginx/Ingress L7 负载均衡。
-
-#### 2. SSE 连接数问题 — 5 万长连接的资源消耗
-
-§13.10 设计了 SSE 推送，但 5 万用户全部保持 SSE 长连接意味着：
-- **5 万个 TCP 连接同时保活**
-- 每个连接 15s heartbeat = **3333 条/秒** 仅心跳
-- 内存占用：每连接约 10-50KB → 约 **500MB - 2.5GB** 仅连接缓冲
-
-**建议**：
-- V1 默认使用 **轮询**（10s 间隔），仅在执行长任务时临时升级为 SSE
-- 或者只在活跃操作页面（文章生成中、发布中）才建立 SSE，非活跃页面走轮询
-- 明确 SSE 连接上限和优雅关闭策略
-
-#### 3. Scheduler 单实例风险
-
-§13.7.2 描述 Scheduler 使用数据库行级锁防重复派发，但：
-- 单 Scheduler 实例是单点故障
-- 行级锁在高并发下有锁竞争风险
-
-**建议**：
-- V1 可接受单实例 + 进程级健康检查自动重启
-- 但需要明确：如果 Scheduler 宕机 5 分钟，到期任务是否会堆积？重启后是否能自动追回？
-- 文档中应补充 `Scheduler 故障恢复策略`
-
-#### 4. PostgreSQL 单库承压
-
-30+ 张表全部在一个 PostgreSQL 实例中，5 万用户场景下：
-- `articles` 表增长最快（每用户每天可能生成 5-20 篇）
-- `question_monitor_runs` 按 `问题数 × 模型数 × 天数` 增长
-- `audit_logs` 写入量大，查询范围广
-
-**建议**：
-- 审计日志表按月分区（`PARTITION BY RANGE (created_at)`）
-- 监控数据表按日期分区
-- `articles` 添加 `tenant_id` 分区索引或按 tenant 分片策略
-- 明确 V1 阶段的数据量估算和归档策略
-
-#### 5. 缺少限流与熔断设计
-
-5 万用户中如果某个租户突发大量请求（如批量生成 1000 篇文章），可能打爆队列。文档只在 §7.2 提到 Redis 限流计数，但缺乏系统性设计：
-
-**建议**：
-- 在 Gateway 层增加租户级限流（令牌桶/滑动窗口）
-- 在 Worker 层增加模型调用限频（保护下游 LLM API）
-- 在 MQ 层设置队列容量上限 + 拒绝策略
-- 生成任务提交时校验排队深度，超阈值直接拒绝并提示
-
----
-
-### 🟡 建议优化的问题
-
-#### 6. 对象存储缺少 CDN 加速策略
-
-知识库的原始文档和图片素材通过对象存储管理（§7.5），但 5 万用户同时访问文章预览中的图片时：
-- 需要 CDN 分发（阿里云 OSS 天然支持，MinIO 需手动配 Nginx/CDN）
-- 建议文档中明确：线上版走 OSS CDN，私有化部署走 Nginx 反代 MinIO
-
-#### 7. Redis 缓存雪崩风险
-
-§13.9.2 提到 Redis 缓存 30 天摘要，但未设计：
-- 缓存预热策略
-- 缓存过期时间错开（避免集体失效）
-- 缓存穿透保护（布隆过滤器或空值缓存）
-
-**建议**：关键缓存（工作台统计、趋势图）使用 `TTL + 异步刷新` 模式，避免大量请求击穿到 PostgreSQL。
-
-#### 8. `worker-generate` 职责过重
-
-§13.5.2 中 `worker-generate` 同时承载：模板生成、Prompt 生成、批量生成、文章优化。这意味着：
-- 一个 Worker 进程要处理 4 种不同的任务类型
-- 批量生成可能堵塞优化任务
-
-**建议**：
-- 队列内使用 `routing key` 或 `priority` 区分任务类型
-- 或拆分为 `q.generate.interactive`（即时任务，高优先级）和 `q.generate.batch`（批量/定时任务，低优先级）
-- V1 在代码层面保持一个 Worker 二进制，但消费端可部署多实例分配不同 routing key
-
-#### 9. Sponge 框架兼容性未评估
-
-§2.2 提到使用 [sponge](https://github.com/go-dev-frame/sponge) 框架，但文档中的分层架构（transport → app → domain → repository）与 sponge 的代码生成模式是否兼容未说明：
-- sponge 生成的代码结构是否支持 `internal/tenant` + `internal/platform` 的双域拆分？
-- sponge 的 handler/service/dao 分层与文档中的 transport/app/domain/repository 如何映射？
-
-**建议**：明确 sponge 的使用范围（仅脚手架？还是深度依赖代码生成？），避免框架约束与架构设计冲突。
-
-我的意见：优先架构设计为先，sponge 只是为了快速生成代码，但是一定架构设计为先
-
-#### 10. 缺少全局配置管理方案
-
-文档提到 `internal/shared/config`，但未说明：
-- 配置从哪里加载（文件？环境变量？配置中心？）
-- 运行时配置变更是否支持热加载
-- 多个服务（gateway / tenant-api / platform-api / scheduler / workers）的配置如何统一管理
-
-**建议**：V1 使用 `YAML 配置文件 + 环境变量覆盖`，明确配置层级。
-
-是用动态配置加载技术
-
----
-
-### 🟢 文档层面的小问题
-
-#### 11. §5.5.9 `platform/audit` 内容空缺
-
-第 406-407 行 `platform/audit` 只有标题没有内容，而 §13 中才补齐。应删除或填充。
-
-#### 12. §5.6.3 两服务协作原则有"悬挂列表"
-
-第 436-439 行的 4 个日志类型列表与上文语义断裂，像是从 `platform/audit` 模块复制过来的遗留。
-
-#### 13. `viewer` 角色在 §6.2.2 被删除
-
-原版有 `viewer`（只读成员），更新版替换为 `kol`。但 PRD 中明确定义了"只读成员"角色，建议保留 `viewer` 并额外增加 `kol`。
-
-#### 14. Mermaid 图中缺少 `scheduler` 节点
-
-§8 交互图（第 553-599 行）未包含 `scheduler`，虽然 §13.5.1 补了修订图，但原图应同步更新或标注以修订图为准。
-
-#### 15. 后端结构图（§9）缺少 `scheduler` 节点
-
-第 603-691 行的 Mermaid 图中 cmd 子图也缺少 scheduler 二进制。
-
----
-
-## 四、面向"足够简单"目标的评估
-
-| 维度 | 评价 | 风险点 |
-| --- | --- | --- |
-| 服务数量 | ✅ **合理** — 8 个进程 | 足够收敛，V1 可控 |
-| 中间件数量 | ⚠️ **偏多** — PG + Redis + RabbitMQ + Qdrant + OSS | 但都是必需的，无冗余 |
-| 数据库表 | ⚠️ **30+ 张** | 但每张表职责单一，不算过度 |
-| 框架选型 | ⚠️ Sponge 框架 | 需确认不会引入额外复杂度 |
-| 部署复杂度 | ✅ Docker Compose 可覆盖本地开发 | 生产环境需 K8s |
-| 前端应用数 | ✅ 2 + 1 插件 | 合理 |
-
-> [!IMPORTANT]
-> **总体评价：架构已从"宏观方案"升级为"可开发闭环方案"。功能覆盖度 100%，数据模型完整。主要残留问题集中在 5 万并发的性能架构层面（SSE 连接管理、数据库分区、限流熔断）和文档一致性上。**
-
----
-
-## 五、修改优先级建议
-
-| 优先级 | 修改项 | 工作量 |
-| --- | --- | --- |
-| P0 | 补充 Gateway 水平扩展和负载均衡方案 | 0.5h |
-| P0 | 修订 SSE 策略：默认轮询、长任务页面才开 SSE | 0.5h |
-| P0 | 补充租户级限流 + 队列容量保护设计 | 1h |
-| P1 | 补充 PostgreSQL 分区策略（审计/监控表） | 0.5h |
-| P1 | 恢复 `viewer` 角色 + 增加 `kol` | 5min |
-| P1 | 评估 sponge 框架与双域分层的兼容性 | 1h |
-| P2 | 统一旧图与新图（§8/§9 补 scheduler） | 15min |
-| P2 | 修复 §5.5.9 空内容 + §5.6.3 悬挂列表 | 10min |
-| P2 | 补充配置管理方案 | 0.5h |
-| P2 | 补充对象存储 CDN 方案 | 15min |
diff --git a/docs/claude_architecture_review_3.md b/docs/claude_architecture_review_3.md
deleted file mode 100644
index 56eeac6..0000000
--- a/docs/claude_architecture_review_3.md
+++ /dev/null
@@ -1,318 +0,0 @@
-# GEO 平台技术架构深度审查报告（第三轮）
-
-> 在前两轮审查（功能覆盖度 + 5 万并发初审）基础上，交叉审查全部 6 份文档（共 ~4700 行），聚焦**跨文档一致性、数据流完整性、实施风险**三个维度。
-
----
-
-## 一、跨文档一致性审查
-
-现有文档体系：
-
-| 文档 | 行数 | 定位 |
-| --- | --- | --- |
-| [geo-platform-ops-admin-tech-architecture-v1.md](file:///d:/project/geo/docs/geo-platform-ops-admin-tech-architecture-v1.md) | 1257 | 🏗️ 主架构 |
-| [geo-platform-prd-v1.md](file:///d:/project/geo/docs/geo-platform-prd-v1.md) | 1079 | 📋 租户端 PRD |
-| [geo-platform-ops-admin-prd-v1.md](file:///d:/project/geo/docs/geo-platform-ops-admin-prd-v1.md) | 652 | 📋 平台管理端 PRD |
-| [media-binding-and-publish-v1.md](file:///d:/project/geo/docs/media-binding-and-publish-v1.md) | 562 | 🔌 插件方案 |
-| [qdrant-rag-architecture-v1.md](file:///d:/project/geo/docs/qdrant-rag-architecture-v1.md) | 651 | 🧠 RAG 方案 |
-| [question-driven-monitoring-design-v1.md](file:///d:/project/geo/docs/question-driven-monitoring-design-v1.md) | 495 | 📊 数据监控方案 |
-
-### 问题 1：RAG 组件未纳入主架构图和交互图
-
-[qdrant-rag-architecture-v1.md](file:///d:/project/geo/docs/qdrant-rag-architecture-v1.md) 定义了完整的检索链路：`query rewrite → filter → Qdrant 检索 → rerank → 上下文拼装 → 提交模型`。但主架构中：
-
-- §8 交互图中 `worker-generate → Qdrant` 的箭头缺失（只有 `worker-knowledge → QD`）
-- 文章生成链路（§10.1）只提到"调用模型"，**没有 RAG 检索步骤**
-- 后端模块职责中无 `shared/rag` 或 `shared/retrieval` 模块
-
-> [!WARNING]
-> **影响**：`worker-generate` 生成文章时需要从 Qdrant 检索品牌知识，这条数据流在主架构中完全不可见。开发时容易遗漏 RAG 集成。
->
-> **建议**：
-> 1. 交互图中为 `worker-generate → Qdrant` 增加箭头
-> 2. §10.1 生成链路在步骤 3 和 4 之间插入 "RAG 检索品牌知识上下文"
-> 3. 后端目录中增加 `internal/shared/retrieval` 模块
-
-### 问题 2：media-binding 插件协议与主架构定义存在分歧
-
-| 对比项 | media-binding-v1.md | 主架构 §13.8 |
-| --- | --- | --- |
-| 绑定落库 | 前端调用后端 API 保存 | 插件**双通道**：回传前端 + 回调 API 落库 |
-| 会话管理 | 无 `plugin_session` 概念 | 有 `plugin_sessions` 表 + `session_token` |
-| 回调路径 | `POST /api/platform-accounts/bind` | `POST /api/callback/plugin/bind` |
-| 发布记录 | `POST /api/publish-records` | `POST /api/callback/plugin/publish` |
-
-> **结论**：主架构 §13.8 的设计更完善（双通道 + 会话令牌 + 审计），但 media-binding-v1.md 还是旧方案。**两份文档需要统一**，否则前端、插件、后端开发人员会看不同的接口文档。
-
-### 问题 3：数据追踪的数据模型字段不一致
-
-| 对比项 | question-driven-monitoring-v1.md | 主架构 §13.11.6 |
-| --- | --- | --- |
-| 汇总表名 | `question_model_daily_metrics` | 未出现此表（但有 `keyword_model_daily_metrics`） |
-| `question_monitor_runs` 字段 | 有 `run_at`、`task_batch_id` | 缺少 `run_at`、`task_batch_id` |
-| `question_monitor_parse_results` 字段 | 有 `citation_platform_count`、`parser_version` | 缺少这两个字段 |
-| 保留策略 | 明确 30/90/180 天分级 | 未提及保留策略 |
-
-> **建议**：主架构 §13.11.6 的 Schema 应与 [question-driven-monitoring-design-v1.md](file:///d:/project/geo/docs/question-driven-monitoring-design-v1.md) 完全对齐，特别是补充 `question_model_daily_metrics` 表和缺失字段。
-
-### 问题 4：RAG 中的 `knowledge_chunks_meta` 表未出现在主架构 Schema
-
-[qdrant-rag-architecture-v1.md](file:///d:/project/geo/docs/qdrant-rag-architecture-v1.md) §6.1 提到 PostgreSQL 需保存 `knowledge_chunks_meta`（chunk 元数据和状态），但主架构 §13.11.4 知识库 Schema 中**没有这张表**。这意味着：
-
-- 每个文档被切成多少 chunk、每个 chunk 的 token 数、status 在 PostgreSQL 中无处存储
-- chunk 重建/版本化时没有元数据支持
-
-> **建议**：在 §13.11.4 增加 `knowledge_chunks_meta` 表：
-> ```
-> | knowledge_chunks_meta | id, knowledge_item_id, chunk_index, token_count, qdrant_point_id, item_version, status |
-> ```
-
-### 问题 5：RAG 中的 `retrieval_logs` 和 `rag_eval_cases` 未纳入主架构
-
-RAG 文档要求记录每次检索的 query/filter/rerank 结果用于 badcase 分析，但主架构没有对应表和模块。V1 如果不记录，后续无法评估 RAG 精准度。
-
-> **建议**：如果目标是"足够简单"，V1 可以先将检索日志写入**文件日志**而非数据库表，后续再升级。在架构中明确这一策略。
-
-### 问题 6：PRD 中定义了 `kol` 角色但无实际权限描述
-
-主架构 §6.2.2 新增 `kol`（用于某个专家的 prompt 从底层共享），但：
-- 租户端 PRD 只定义了 管理员/编辑/只读 三种角色
-- `kol` 角色的具体权限范围（能看什么、能做什么）未在任何文档中定义
-- PRD 中的 `viewer`（只读成员）角色被删除
-
-> **建议**：保留 `viewer`、额外增加 `kol`，并在权限矩阵中补充 `kol` 的能力边界。
-
-### 问题 7：`article_templates` 表的 `tenant_id` 字段暗示模板是租户级的
-
-主架构 §13.11.2 中 `article_templates` 有 `tenant_id`。但：
-- 平台端 PRD §8.5 明确有"系统模板管理"功能
-- 平台级模板应 `tenant_id = NULL` 或专门的 `scope` 字段
-- 参考截图中工作台的模板卡片（Top X / 产品评测 / 研究报告）看起来是**平台级**预设
-
-> **建议**：`article_templates` 表增加 `scope` 字段（`platform` / `tenant`），平台级模板 `tenant_id = NULL`，租户可在此基础上自定义。
-
-### 问题 8：ops-admin-web PRD 中的"平台接入管理"路由在主架构 §13.4.2 中已有但 §5.3.3 中缺失
-
-§13.4.2 ops-admin-web 路由有 `/platform/integrations/*`，§13.5.4 模块也有 `platform/integration`，但 §5.3.3 原始 API 路由列表中没有 `/api/platform/integrations/*`。
-
-> **影响较小**，因为 §13.6.2 覆盖了。但前后不一致容易造成混乱。
-
----
-
-## 二、关键数据流深度审查（面向 5 万并发 + 简单）
-
-### 数据流 1：文章生成全链路
-
-```
-用户 → admin-web → gateway → tenant-api（额度校验 + 任务入队）
-→ RabbitMQ → worker-generate（RAG 检索 + 模型调用 + 结果存储）
-→ PostgreSQL + Redis → SSE/轮询 → 前端更新
-```
-
-**关键问题：LLM 调用超时与成本**
-
-- 一篇文章生成可能调用 LLM 3-20 秒（取决于文章长度和模型）
-- 5 万用户中假设 1% 同时在生成 = **500 并发生成任务**
-- 每个任务占用 1 个 Worker goroutine + 1 个 LLM API 连接
-- 如果 LLM 上游限频（如 DeepSeek 300 RPM），Worker 会排队堆积
-
-> [!CAUTION]
-> **架构中缺少**：
-> 1. LLM 调用超时策略（多久算超时？超时后任务状态如何？）
-> 2. LLM 上游限流适配（令牌桶/重试退避）
-> 3. 生成任务的优先级控制（VIP 租户优先？）
-> 4. Worker 对 LLM 的并发连接池设计
-
-### 数据流 2：知识库入库全链路
-
-```
-用户上传 → tenant-api → 对象存储 → RabbitMQ
-→ worker-knowledge（提取 → 清洗 → 切片 → Embedding → Qdrant 写入 + PG 元数据）
-```
-
-**关键问题：Embedding 调用成本**
-
-- 每个文档可能切出 50-200 个 chunk
-- 每个 chunk 需要一次 Embedding API 调用
-- 50 万租户 × 平均 10 个知识文档 = 500 万文档 → 潜在 2.5-10 亿 chunk
-
-> 但 V1 阶段用户量有限，这主要是演进方向的考量。当前建议在架构中明确 **Embedding 批量调用**策略（一次请求多个 chunk），减少 API round-trip。
-
-### 数据流 3：定时任务调度全链路
-
-```
-scheduler 每分钟扫描 → schedule_tasks（到期的） → 生成 generation_tasks → 入队 RabbitMQ
-                                               → 生成 analytics 任务  → 入队 RabbitMQ
-```
-
-**关键问题：调度雷群效应**
-
-- 很多租户的定时任务可能设在同一时刻（如每天 08:00）
-- 某分钟可能扫描出数千个到期任务
-- 全部同时入队可能瞬间打爆 `q.generate` 队列
-
-> **建议**：
-> - Scheduler 支持 **平滑派发**（将同时到期的任务分散到 5-10 分钟窗口内入队）
-> - 或租户创建定时任务时自动 **加随机偏移量**（±15 分钟）
-
-### 数据流 4：数据追踪采集全链路
-
-```
-scheduler → 为每个启用的 question_version × model 生成采集任务 → RabbitMQ
-→ worker-analytics（调用模型 → 解析回答 → 存解析结果）
-→ 日级聚合 → 刷新缓存
-```
-
-**关键问题：采集任务与生成任务共享模型调用**
-
-- 数据追踪的采集本质上也是"调用 LLM 获取回答"
-- 与文章生成共用 LLM 额度/限频
-- 但采集任务优先级应**低于**用户直接触发的生成任务
-
-> **建议**：
-> - 采集任务使用独立的 LLM 通道/频次限制
-> - 或在共享通道中标记优先级，用户直接任务优先
-
-### 数据流 5：插件发布全链路
-
-```
-admin-web → 创建 plugin_session → browser-extension 执行发布
-→ 同时：回传前端（即时反馈）+ 回调 /api/callback/plugin/publish（可靠落库）
-→ tenant-api 存储 publish_records → SSE 广播
-```
-
-**问题：插件离线时的降级处理**
-
-- 如果用户没装插件、或插件版本过低，点击"发布"会发生什么？
-- 主架构中未定义**插件检测**机制（前端如何知道插件是否可用？）
-- media-binding-v1.md §12 提到只注入本系统后台域名，但没定义版本检测协议
-
-> **建议**：前端在页面加载时检测插件安装状态和版本，未安装或版本过低时灰掉发布按钮并引导安装。在 `packages/shared-types` 中定义最低兼容插件版本常量。
-
----
-
-## 三、实施风险与工程注意事项
-
-### 风险 1：`worker-generate` 中 LLM 超时导致 goroutine 泄漏
-
-Go 中如果 HTTP 请求到 LLM API 设置了很长的超时（如 60s），大量排队任务会占用大量 goroutine。如果 LLM 侧故障，可能导致 goroutine 数量爆炸。
-
-> **建议**：
-> - 对 LLM 调用设置 `context.WithTimeout`（建议 30s）
-> - Worker 设置最大并发 goroutine 数（如基于 `semaphore` 限制并发 50）
-> - 超时任务标记为 `failed`，进入重试队列
-
-### 风险 2：PostgreSQL 事务边界不清晰
-
-生成任务涉及多表写入：`articles` + `article_versions` + `generation_tasks` + `tenant_quota_ledgers`。如果不在同一事务中：
-- 额度扣了但文章没写入 → 额度泄漏
-- 文章写了但额度没扣 → 超额使用
-
-> **建议**：文档中明确关键事务边界——至少"额度扣减 + 任务创建"必须在同一 PostgreSQL 事务中。Worker 侧的"结果写入 + 额度确认"也应事务保护。
-
-### 风险 3：migration 策略缺失
-
-30+ 张表的 Schema 定义好了，但没有 migration 策略：
-- 如何管理 Schema 版本？（golang-migrate / Atlas / sponge 内置？）
-- 线上 DDL 变更如何无停机执行？
-- 是否有 down migration？
-
-> **建议**：明确使用 `golang-migrate` 或 `Atlas`，并在 `server/migrations/` 目录约定命名规则。
-
-### 风险 4：`tenant_id` 数据隔离的执行保障
-
-5 万用户意味着大量租户。所有租户数据共库共表，`tenant_id` 过滤是唯一隔离手段。如果某个查询漏加 `tenant_id`，就是数据泄露。
-
-> **建议**：
-> - 在 repository 层封装 `TenantScope(ctx)` 自动注入 `WHERE tenant_id = ?`
-> - 在 CI 中运行静态分析检查所有查询是否带 `tenant_id`
-> - 文档中将此列为**强制编码规范**
-
-### 风险 5：对象存储的清理策略
-
-知识库文档、原始模型回答、发布请求/响应 payload 持续写入对象存储。无清理策略意味着存储成本线性增长。
-
-> **建议**：
-> - 已删除知识文档的对象存储文件应在 T+7 天后清理
-> - 原始模型回答按 `question-driven-monitoring` 建议保留 30-90 天
-> - 定期运行 GC 任务扫描"孤儿文件"
-
-### 风险 6：Sponge 框架的 code-gen 与手写代码冲突
-
-Sponge 的核心卖点是代码生成（从 protobuf/sql 生成 handler/service/dao）。但主架构的分层是自定义的 `transport/app/domain/repository`。如果使用 sponge 的代码生成：
-- 生成的代码放在哪个层？
-- 手写的 domain 逻辑如何与生成的 dao 共存？
-- 重新生成时是否覆盖手写代码？
-
-> **建议**：明确 sponge 仅用于**脚手架初始化**（项目初始化、数据库连接、中间件配置），**不使用**其默认的 handler/service/dao 代码生成，由团队按自定义分层手写业务代码。
-
-### 风险 7：SSE 与 Kubernetes HPA 的兼容性
-
-Kubernetes 默认负载均衡（基于 Service → Pod 的 round-robin）会将新请求分配到不同 Pod。但 SSE 是长连接，如果用户的 SSE 连接在 Pod A，但任务结果写入后通知只发到 Pod B，用户收不到。
-
-> **建议**：
-> - SSE 推送使用 **Redis Pub/Sub** 作为跨 Pod 广播层
-> - 或使用 **Sticky Session**（Ingress `nginx.ingress.kubernetes.io/affinity: cookie`）
-> - 文档中需要明确选择哪种方案
-
-### 风险 8：`brand_question_versions` 的碎片化
-
-每次用户修改问题文案就新增一个版本。如果用户频繁微调（改错字、加时间等），版本表会快速碎片化。监控计划如果绑定 `question_version_id`，可能产生大量只使用 1-2 天的版本。
-
-> **建议**：
-> - 对问题修改增加 **debounce**（如 10 分钟内多次修改只产生一个版本）
-> - 或者只在"发布/启用"时才生成新版本，编辑中间态不算版本
-
-### 风险 9：批量生成的额度预扣与回滚
-
-用户提交"批量生成 100 篇"时：
-- 是预扣 100 次额度？
-- 还是每篇生成成功时扣 1 次？
-- 如果预扣后有 30 篇生成失败，如何退回额度？
-
-> **建议**：文档应明确**额度策略**：推荐"提交时预扣 + 失败后按条退还 + 定期对账"模式。
-
-### 风险 10：`viewer` 角色缺失导致 PRD 不满足
-
-PRD 明确定义了"只读成员"角色，但主架构删除了 `viewer` 替换为 `kol`。如果按当前架构开发：
-- "只读成员"无法创建——PRD 交付不通过
-- 前端权限配置缺少对应的角色枚举
-
----
-
-## 四、"足够简单"维度的优化建议
-
-| 可简化选项 | 当前方案 | 简化建议 | 风险 |
-| --- | --- | --- | --- |
-| SSE 推送 | 全场景 SSE | **V1 全部用轮询**（10s），V1.5 引入 SSE | 延迟略高但架构极度简化 |
-| Gateway 独立进程 | `cmd/gateway` | **V1 把网关逻辑合并到 tenant-api 的中间件**，省一个进程 | 后续拆分需重构 |
-| Rerank 模块 | cross-encoder reranker | **V1 跳过 rerank**，只用 dense + filter + top5 | RAG 精度降低 |
-| 独立 Scheduler | `cmd/scheduler` | **用 cron job 或 pg_cron** 代替独立进程 | 灵活性降低 |
-| `question_model_daily_metrics` | 问题级汇总表 | **V1 只保留 `keyword_model_daily_metrics`** | 丢失问题级穿透能力 |
-
-> [!NOTE]
-> 以上是**可选简化**，不是必须。如果团队人力充足，保持当前设计无问题。但如果"足够简单"是硬约束，可以选择部分简化。
-
----
-
-## 五、修改建议汇总
-
-### P0（必须修复）
-
-| # | 问题 | 预计工作量 |
-| --- | --- | --- |
-| 1 | 主架构中补充 RAG 检索步骤（交互图 + 生成链路 + 模块定义） | 30min |
-| 2 | 统一 media-binding-v1.md 与主架构 §13.8 的接口定义 | 1h |
-| 3 | 补充 LLM 调用超时/限流/并发池设计 | 30min |
-| 4 | 明确关键事务边界（额度扣减 + 任务创建 + 结果写入） | 15min |
-| 5 | 恢复 `viewer` 角色 + 定义 `kol` 角色权限 | 15min |
-
-### P1（重要补充）
-
-| # | 问题 | 预计工作量 |
-| --- | --- | --- |
-| 6 | §13.11.4 补充 `knowledge_chunks_meta` 表 | 10min |
-| 7 | §13.11.6 与 question-driven-monitoring 对齐字段 | 20min |
-| 8 | `article_templates` 增加 `scope` 字段区分平台/租户模板 | 5min |
-| 9 | 补充 SSE 跨 Pod 广播方案（Redis Pub/Sub 或 Sticky Session） | 20min |
-| 10 | 补充额度预扣/退还/对账策略 | 15min |
diff --git a/docs/claude_architecture_review_4.md b/docs/claude_architecture_review_4.md
deleted file mode 100644
index 6957ffc..0000000
--- a/docs/claude_architecture_review_4.md
+++ /dev/null
@@ -1,242 +0,0 @@
-# GEO 平台技术架构 V1 综合审查报告（第四轮）
-
-> 以大厂技术架构师视角，综合前三轮 Claude 审查结论，对 [geo-platform-ops-admin-tech-architecture-v1.md](file:///d:/project/geo/docs/geo-platform-ops-admin-tech-architecture-v1.md) 进行终审，聚焦 **可实施性** 和 **运维简单性**。
-
----
-
-## 一、前三轮审查问题收敛确认
-
-### 第一轮 → 第二轮（功能闭环修复）
-
-| # | 问题 | 状态 |
-| --- | --- | --- |
-| 1 | 定时调度器缺失 | ✅ 已补齐 `cmd/scheduler` |
-| 2 | Prompt 规则管理缺失 | ✅ 已补齐模块 + 表 |
-| 3 | 模板管理缺失 | ✅ 已补齐 `article_templates` |
-| 4 | 数据库 Schema 缺失 | ✅ 已补齐 30+ 张表 |
-| 5 | GEO 指标采集方案缺失 | ✅ 已补齐问题驱动监控 |
-| 6-12 | 版本管理 / 插件协议 / SSE / 路由 | ✅ 全部修复 |
-
-### 第二轮 → 第三轮（5 万并发 + 一致性修复）
-
-| # | 问题 | 状态 |
-| --- | --- | --- |
-| 1 | Gateway 扩展方案 | ✅ §13.13.1 补充了 HPA + L7 负载均衡 |
-| 2 | SSE 连接策略 | ✅ §13.10.3 改为默认轮询 + 按需 SSE |
-| 3 | Scheduler 故障恢复 | ✅ §13.13.2 补充了恢复策略 |
-| 4 | PostgreSQL 分区 | ✅ §13.13.3 补充了审计/监控表分区 |
-| 5 | 限流 + 熔断 | ✅ §13.13.4 补充了租户级令牌桶 + Worker 并发池 |
-| 6 | 配置管理方案 | ✅ §13.13.6 补充了三级配置 |
-| 7 | Sponge 使用原则 | ✅ §13.13.7 明确仅作脚手架 |
-| 8 | Migration 策略 | ✅ §13.13.8 补充了 golang-migrate |
-| 9 | 租户隔离保障 | ✅ §13.13.9 补充了 TenantScope |
-
-### 第三轮提出的残留问题
-
-| # | 问题 | 当前状态 |
-| --- | --- | --- |
-| 1 | RAG 检索未纳入主架构图 | ✅ §13.5.1 修订图已补 `WG → QD` 箭头；§5.5.2 新增 `shared/retrieval` |
-| 2 | media-binding 接口不一致 | ⚠️ **仍残留** — media-binding-v1.md 未同步更新 |
-| 3 | 数据追踪 Schema 字段不一致 | ✅ §13.11.6 已与监控方案对齐 |
-| 4 | `knowledge_chunks_meta` 表缺失 | ✅ §13.11.4 已补充 |
-| 5 | `retrieval_logs` 落地策略 | ✅ §13.11.4 末尾明确 V1 写文件日志 |
-| 6 | `kol` 角色权限不清 | ✅ §6.2.3 补充了权限矩阵 |
-| 7 | `article_templates.scope` | ✅ §13.11.2 已补充 scope 字段 |
-| 8 | LLM 超时 / 限流 / 并发池 | ✅ §13.13.4 明确 30s 超时 + semaphore 50 |
-| 9 | 事务边界 | ✅ §13.13.9 明确了关键事务边界 |
-| 10 | 额度预扣/退还策略 | ✅ §13.7.3 明确了预扣 + 失败退还 + 对账 |
-
-> [!TIP]
-> **三轮审查共计约 40 项问题，当前仅剩 1 项残留（media-binding 文档未同步）。架构整体完成度非常高。**
-
----
-
-## 二、当前架构总体评价
-
-### 2.1 架构复杂度评级
-
-| 维度 | 现状 | 评价 |
-| --- | --- | --- |
-| 进程数量 | gateway + 2 API + scheduler + 4 worker = **8 个** | ⚠️ 偏多但合理 |
-| 中间件 | PG + Redis + RabbitMQ + Qdrant + OSS = **5 个** | ⚠️ 每个都必要，无冗余 |
-| 数据库表 | **30+ 张** | ✅ 职责单一，不算过度 |
-| 前端应用 | 2 后台 + 1 插件 | ✅ 合理 |
-| 部署形态 | Docker Compose（开发）+ K8s（生产） | ✅ 标准 |
-
-### 2.2 可实施性判断
-
-> [!IMPORTANT]
-> **结论：可实施。** 文档已覆盖从页面路由 → API → 数据模型 → 异步链路 → 部署的完整闭环。8 个功能页全部具备"可开发"条件。
-
-**但有以下前提条件：**
-1. 团队至少需要 2 名 Go 后端 + 1 名前端 + 1 名 DevOps
-2. LLM/Embedding 供应商的限频和成本需提前确认
-3. 首版上线建议先控制在 **1000 并发** 内验证，而非直接冲 5 万
-
----
-
-## 三、本轮发现的问题与建议
-
-以下是前三轮未充分覆盖、但作为架构师我认为必须关注的问题：
-
-### 🔴 必须修正（影响运维简单性或可实施性）
-
-#### 问题 1：V1 阶段 Gateway 存在过度设计的嫌疑
-
-当前方案 `cmd/gateway` 作为独立进程做路由分发。但 V1 只有 2 个下游（tenant-api、platform-api），且 gateway 只做鉴权 + 路由转发。
-
-**运维影响**：多一个进程 = 多一套部署/监控/日志/重启策略。
-
-**建议**：
-- **V1 简化方案**：将 gateway 的鉴权中间件合并到 `tenant-api` 和 `platform-api` 中，由 Nginx/Ingress 按 `/api/tenant/*` 和 `/api/platform/*` 做 L7 路由分发
-- 省掉 1 个进程，运维直接减负
-- V1.5 如果需要统一限流/审计注入，再独立出 gateway
-
-> [!WARNING]
-> 如果选择保留 gateway，则必须确保它"足够薄"——只做路由 + 鉴权 + 限流，**绝不放业务逻辑**。否则它会变成系统的"上帝对象"。
-
-我的想法是保留的，但第一版，只做路由 + 鉴权 + 限流
-
-#### 问题 2：8 个进程的运维负担
-
-生产环境需要管理 8 个独立二进制（gateway + tenant-api + platform-api + scheduler + 4 worker），每个都需要：
-- 独立的 Dockerfile
-- 独立的 K8s Deployment + Service
-- 独立的日志采集
-- 独立的健康检查
-
-**建议**：
-- 4 个 Worker 在 V1 阶段考虑合并为 **2 个 Worker 二进制**：
-  - `worker-main`：消费 generate + knowledge + analytics 队列（按 routing key 区分）
-  - `worker-callback`：消费 publish-callback 队列
-- 代码层面保持模块隔离（`internal/jobs/` 下仍然分独立 package），只是 `cmd/` 入口合并
-- 部署从 8 个进程降为 **5 个**（tenant-api + platform-api + scheduler + worker-main + worker-callback）
-
-审核员想法： 不采纳，合并后系统用户体验会变差会更慢
-
-#### 问题 3：`viewer` 角色仍未恢复
-
-§6.2.2 中只有 `tenant_admin` / `editor` / `kol`。PRD 明确定义了"只读成员"。
-
-审核员意图：viewer 角色没用，删除；kol其实也只是用户，但是这个角色比普通用户要更会写 prompt,别人可以直接使用她的分享码，使用她分享的prompt（其中主要信息，比如公司名啊，地址啊，还是得用户填）
-
----
-
-### 🟡 建议优化（提升运维效率）
-
-#### 问题 4：缺少统一的错误码规范
-
-文档定义了 40+ 个 API 接口，但没有统一的错误码体系。前后端联调时会出现：
-- 后端返回 `{"error": "xxx"}` 格式不统一
-- 前端无法区分"额度不足"和"LLM 超时"和"参数错误"
-
-**建议**：定义统一错误响应和错误码段：
-
-```
-{
-  "code": 40301,
-  "message": "quota_insufficient",
-  "detail": "生成额度不足，请升级套餐"
-}
-```
-
-| 错误码段 | 含义 |
-| --- | --- |
-| 400xx | 参数校验 |
-| 401xx | 认证 |
-| 403xx | 权限/额度 |
-| 404xx | 资源不存在 |
-| 409xx | 状态冲突 |
-| 500xx | 内部错误 |
-| 503xx | 下游不可用（LLM/Qdrant） |
-
-#### 问题 5：缺少日志规范与链路追踪
-
-8 个进程的分布式架构，单个请求可能跨 gateway → API → MQ → Worker。排查问题需要：
-- 统一的 `request_id` / `trace_id` 贯穿全链路
-- 结构化日志（JSON 格式）
-- 日志级别规范
-
-`internal/shared/observability` 模块已定义在目录结构中，但文档中没有展开。
-
-**建议**：
-- 所有进程使用统一日志库（如 `zap`）
-- gateway 生成 `request_id`，全链路透传
-- MQ 消息 header 中携带 `trace_id`
-- 使用 Jaeger
-
-#### 问题 6：Docker Compose 本地开发的启动顺序和依赖
-
-5 个中间件 + 8 个服务的本地开发环境，`docker-compose up` 时：
-- PG 未就绪时 API 连接失败
-- RabbitMQ 未初始化队列时 Worker 报错
-- Qdrant 启动慢导致知识库功能不可用
-
-**建议**：
-- `docker-compose.yml` 中只放中间件（PG/Redis/RabbitMQ/Qdrant/MinIO）
-- Go 服务本地 `go run` 开发，用 `Makefile` 或 `Task` 统一启动
-- 提供一键初始化脚本：`make dev-init`（创建队列、运行 migration、创建 bucket）
-
-#### 问题 7：media-binding-v1.md 仍与主架构不一致
-
-第三轮审查已指出，至今未同步。
-
-**建议**：以主架构 §13.8 的插件会话模型为准，更新 media-binding-v1.md 的接口定义。
-
----
-
-### 🟢 小问题（不阻塞但建议修正）
-
-| # | 问题 | 说明 |
-| --- | --- | --- |
-| 1 | §8 旧交互图与 §13.5.1 修订图并存 | 建议删除旧图或标注"以 §13 为准" |
-| 2 | §9 后端结构图缺 scheduler 节点 | 与实际设计不符 |
-| 3 | §5.5.9 `platform/audit` 只有标题无内容 | 已在 §13 补齐，建议填充或删除旧节 |
-| 4 | Vite 8 版本号存疑 | §2.2 提到 `Vite 8`，截至 2026.3 Vite 最新稳定版需确认 |
-
----
-
-## 四、运维简单性终审
-
-### 4.1 运维维度打分
-
-| 维度 | 评分 | 说明 |
-| --- | --- | --- |
-| 部署复杂度 | ⭐⭐⭐ | 8 个进程偏多，建议合并 Worker |
-| 监控难度 | ⭐⭐⭐ | 有 observability 模块但未展开 |
-| 故障排查 | ⭐⭐ | 缺少 trace_id + 结构化日志规范 |
-| 扩容简易度 | ⭐⭐⭐⭐ | gateway/API 无状态，HPA 就绪 |
-| 配置管理 | ⭐⭐⭐⭐ | 三级配置合理 |
-| 数据库运维 | ⭐⭐⭐ | 分区策略已定义，缺归档自动化 |
-
-### 4.2 V1 运维简化建议清单
-
-| # | 简化措施 | 效果 |
-| --- | --- | --- |
-| 1 | 合并 4 Worker 为 2 个 | 减少 2 个部署单元 |
-| 2 | 合并 Gateway 到 Ingress 路由 | 减少 1 个部署单元 |
-| 3 | 统一日志 + request_id | 大幅降低排查成本 |
-| 4 | 提供 `make dev-init` | 新人 10 分钟启动开发环境 |
-| 5 | 自动化 migration CI | 避免手动 DDL 事故 |
-| 6 | 审计/监控表自动归档脚本 | 避免磁盘满 |
-
----
-
-## 五、最终结论
-
-> [!IMPORTANT]
-> ### 可实施性：✅ 通过
->
-> 文档已从"宏观方案"演进为可直接进入开发的"闭环方案"。8 个功能页全部具备路由 → API → 模型 → 异步 → 存储 → 状态回传的完整链路。
->
-> ### 运维简单性：⚠️ 有优化空间
->
-> 当前 **8 个进程 + 5 个中间件** 对小团队偏重。建议 V1 合并 Worker、考虑去掉独立 Gateway，将运维实体控制在 **5 个进程** 以内。
-
-### 如果只改三件事：
-
-1. **合并 Worker**：4 个 Worker 二进制合并为 2 个（-2 部署单元）
-2. **统一日志与 trace**：所有进程使用 `zap` + `request_id` 贯穿全链路
-3. **恢复 `viewer` 角色**：PRD 强制要求，不能漏
-
-其余问题（错误码、旧图清理、media-binding 同步等）可在开发过程中逐步完善。
diff --git a/docs/refer/数据监控/AI对话分析.jpg b/docs/refer/数据监控/AI对话分析.jpg
new file mode 100644
index 0000000..7941894
Binary files /dev/null and b/docs/refer/数据监控/AI对话分析.jpg differ
diff --git a/docs/refer/数据监控/AI引用分析.jpg b/docs/refer/数据监控/AI引用分析.jpg
new file mode 100644
index 0000000..7eb4dcf
Binary files /dev/null and b/docs/refer/数据监控/AI引用分析.jpg differ
diff --git a/docs/refer/数据监控/业务主题分析.jpg b/docs/refer/数据监控/业务主题分析.jpg
new file mode 100644
index 0000000..f0008be
Binary files /dev/null and b/docs/refer/数据监控/业务主题分析.jpg differ
diff --git a/docs/refer/数据监控/品牌监控.jpg b/docs/refer/数据监控/品牌监控.jpg
new file mode 100644
index 0000000..08063b2
Binary files /dev/null and b/docs/refer/数据监控/品牌监控.jpg differ
diff --git a/docs/refer/数据监控/平台占比分析.jpg b/docs/refer/数据监控/平台占比分析.jpg
new file mode 100644
index 0000000..9572b7c
Binary files /dev/null and b/docs/refer/数据监控/平台占比分析.jpg differ
diff --git a/docs/refer/数据监控/竞争对手分析.jpg b/docs/refer/数据监控/竞争对手分析.jpg
new file mode 100644
index 0000000..e21ebe0
Binary files /dev/null and b/docs/refer/数据监控/竞争对手分析.jpg differ
diff --git a/docs/superpowers/specs/2026-03-31-admin-web-backend-core-design.md b/docs/superpowers/specs/2026-03-31-admin-web-backend-core-design.md
deleted file mode 100644
index b382406..0000000
--- a/docs/superpowers/specs/2026-03-31-admin-web-backend-core-design.md
+++ /dev/null
@@ -1,675 +0,0 @@
-# GEO admin-web 后端核心链路设计
-
-## 1. 概述
-
-### 1.1 目标
-
-搭建 GEO 平台 tenant-api 后端核心链路，为 admin-web 前端提供可用的 API 服务。第一阶段聚焦四个核心模块：认证、工作台、文章/模板、品牌词库，让前端能跑通内容生成主流程。
-
-### 1.2 决策摘要
-
-| 决策项 | 选择 | 理由 |
-|--------|------|------|
-| 进程模型 | 单进程 tenant-api | 当前只有 tenant 侧，gateway 无分发对象；鉴权中间件写在 shared 层，后续零成本拆出 |
-| 脚手架 | 手工初始化 | sponge 生成的 handler/dao/service 命名与本项目 transport/app/domain/repository 四层结构不符，手工初始化成本更低 |
-| Web 框架 | Gin | 架构文档指定 |
-| DB 访问 | pgx + sqlc | 类型安全、性能最优、SQL 控制力强 |
-| Migration | golang-migrate | 架构文档 §13.13.8 推荐 |
-| 认证 | JWT (access + refresh) | 架构文档 §6 指定 |
-| 日志 | zap 结构化 JSON | 架构文档 §13.13.10 推荐 |
-| 配置 | YAML + env 覆盖 (viper) | 架构文档 §13.13.6 指定 |
-| 错误码 | 统一格式 `{code, message, detail, request_id}` | 架构文档 §13.6.4 |
-
-### 1.3 不包含
-
-第一阶段明确不做：
-- gateway 独立进程
-- platform-api
-- scheduler / worker-*
-- prompt-rule、schedule、optimization、knowledge、media、tracking、account 模块
-- RabbitMQ / Qdrant / 对象存储集成
-- SSE 推送
-
-这些在后续迭代中加入。
-
-## 2. 项目结构
-
-### 2.1 项目初始化
-
-手工初始化 Go 项目（放弃 sponge），按架构文档 §5.2 的分层要求直接建目录结构：
-
-- `transport` — HTTP handler、路由注册
-- `app` — 业务逻辑 service
-- `domain` — 领域模型（纯 Go 结构体，无框架依赖）
-- `repository` — 数据访问（pgx + sqlc）
-
-### 2.2 目录结构
-
-```
-server/
-├── cmd/
-│   └── tenant-api/
-│       └── main.go                 # 入口：初始化依赖、注册路由、启动 HTTP
-├── internal/
-│   ├── bootstrap/
-│   │   └── bootstrap.go           # 依赖容器：DB/Redis/Config 初始化
-│   ├── shared/
-│   │   ├── auth/
-│   │   │   ├── jwt.go             # JWT 颁发 (access 15min + refresh 7day)
-│   │   │   ├── middleware.go      # Gin 中间件：Token 校验 + 身份注入 ctx
-│   │   │   └── claims.go         # JWT Claims 结构体
-│   │   ├── config/
-│   │   │   └── config.go          # Viper 配置加载
-│   │   ├── middleware/
-│   │   │   ├── cors.go
-│   │   │   ├── request_id.go      # 生成/复用 request_id
-│   │   │   ├── recovery.go
-│   │   │   ├── logger.go          # 请求日志 (zap)
-│   │   │   └── tenant_scope.go    # 从 JWT 提取 tenant_id 注入 ctx
-│   │   ├── response/
-│   │   │   ├── response.go        # 统一响应封装 Success/Error
-│   │   │   └── errors.go          # 错误码枚举与 AppError 类型
-│   │   ├── observability/
-│   │   │   └── logger.go          # zap 初始化
-│   │   └── repository/
-│   │       ├── postgres/
-│   │       │   └── postgres.go    # pgx 连接池
-│   │       └── redis/
-│   │           └── redis.go       # Redis 连接
-│   ├── tenant/
-│   │   ├── transport/
-│   │   │   ├── router.go          # 注册所有 tenant 路由组
-│   │   │   ├── auth_handler.go    # /api/auth/* handlers
-│   │   │   ├── workspace_handler.go
-│   │   │   ├── template_handler.go
-│   │   │   ├── article_handler.go
-│   │   │   └── brand_handler.go
-│   │   ├── app/
-│   │   │   ├── auth_service.go
-│   │   │   ├── workspace_service.go
-│   │   │   ├── template_service.go
-│   │   │   ├── article_service.go
-│   │   │   └── brand_service.go
-│   │   ├── domain/
-│   │   │   ├── user.go
-│   │   │   ├── tenant.go
-│   │   │   ├── article.go
-│   │   │   ├── article_template.go
-│   │   │   ├── article_version.go
-│   │   │   ├── generation_task.go
-│   │   │   ├── brand.go
-│   │   │   ├── brand_keyword.go
-│   │   │   ├── brand_question.go
-│   │   │   └── competitor.go
-│   │   └── repository/
-│   │       ├── queries/           # sqlc SQL 文件
-│   │       │   ├── user.sql
-│   │       │   ├── tenant.sql
-│   │       │   ├── article.sql
-│   │       │   ├── article_template.sql
-│   │       │   ├── brand.sql
-│   │       │   └── ...
-│   │       ├── sqlc.yaml          # sqlc 配置
-│   │       ├── generated/         # sqlc 生成的 Go 代码
-│   │       ├── user_repo.go       # Repository 接口 + 实现
-│   │       ├── article_repo.go
-│   │       ├── template_repo.go
-│   │       └── brand_repo.go
-│   └── gateway/                   # 预留空目录
-├── migrations/                    # golang-migrate SQL 文件
-│   ├── 20260331100000_create_tenants.up.sql
-│   ├── 20260331100000_create_tenants.down.sql
-│   ├── 20260331100001_create_users.up.sql
-│   ├── ...
-├── configs/
-│   ├── config.yaml                # 默认配置
-│   └── config.local.yaml          # 本地开发覆盖 (gitignore)
-├── go.mod
-├── go.sum
-├── Makefile                       # dev-init, dev-api, migrate-up, sqlc-generate
-└── docker-compose.yaml            # PostgreSQL + Redis (本地开发)
-```
-
-## 3. 数据库 Schema
-
-### 3.1 Migration 文件规划
-
-按架构文档 §13.11，第一阶段需要以下表。命名规则：`YYYYMMDDHHMMSS_description.up.sql`。
-
-#### 3.1.1 身份与租户
-
-```sql
--- 20260331100000_create_tenants.up.sql
-CREATE TABLE tenants (
-    id          BIGSERIAL PRIMARY KEY,
-    name        VARCHAR(100) NOT NULL,
-    status      VARCHAR(20) NOT NULL DEFAULT 'active', -- active, frozen
-    frozen_at   TIMESTAMPTZ,
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at  TIMESTAMPTZ,
-    CONSTRAINT uk_tenant_name UNIQUE (name)
-);
-
--- 20260331100001_create_users.up.sql
-CREATE TABLE users (
-    id            BIGSERIAL PRIMARY KEY,
-    email         VARCHAR(255) NOT NULL,
-    phone         VARCHAR(20),
-    password_hash VARCHAR(255) NOT NULL,
-    name          VARCHAR(100) NOT NULL,
-    avatar_url    TEXT,
-    status        VARCHAR(20) NOT NULL DEFAULT 'active',
-    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at    TIMESTAMPTZ,
-    CONSTRAINT uk_users_email UNIQUE (email)
-);
-
--- 20260331100002_create_tenant_memberships.up.sql
-CREATE TABLE tenant_memberships (
-    id          BIGSERIAL PRIMARY KEY,
-    tenant_id   BIGINT NOT NULL REFERENCES tenants(id),
-    user_id     BIGINT NOT NULL REFERENCES users(id),
-    tenant_role VARCHAR(20) NOT NULL, -- tenant_admin, editor, kol
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at  TIMESTAMPTZ,
-    CONSTRAINT uk_tenant_user UNIQUE (tenant_id, user_id)
-);
-
--- 20260331100003_create_platform_user_roles.up.sql
-CREATE TABLE platform_user_roles (
-    id            BIGSERIAL PRIMARY KEY,
-    user_id       BIGINT NOT NULL REFERENCES users(id),
-    platform_role VARCHAR(20) NOT NULL, -- super_admin, ops, sre
-    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at    TIMESTAMPTZ,
-    CONSTRAINT uk_platform_user_role UNIQUE (user_id, platform_role)
-);
-
--- 20260331100004_create_plans.up.sql
-CREATE TABLE plans (
-    id                BIGSERIAL PRIMARY KEY,
-    plan_code         VARCHAR(50) NOT NULL,
-    name              VARCHAR(100) NOT NULL,
-    quota_policy_json JSONB NOT NULL DEFAULT '{}',
-    status            VARCHAR(20) NOT NULL DEFAULT 'active',
-    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at        TIMESTAMPTZ,
-    CONSTRAINT uk_plan_code UNIQUE (plan_code)
-);
-
--- 20260331100005_create_tenant_plan_subscriptions.up.sql
-CREATE TABLE tenant_plan_subscriptions (
-    id         BIGSERIAL PRIMARY KEY,
-    tenant_id  BIGINT NOT NULL REFERENCES tenants(id),
-    plan_id    BIGINT NOT NULL REFERENCES plans(id),
-    start_at   TIMESTAMPTZ NOT NULL,
-    end_at     TIMESTAMPTZ NOT NULL,
-    status     VARCHAR(20) NOT NULL DEFAULT 'active',
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at TIMESTAMPTZ
-);
-CREATE UNIQUE INDEX idx_tenant_plan_active ON tenant_plan_subscriptions(tenant_id) WHERE status = 'active'; -- 同一时间只有一个活跃订阅
-
--- 20260331100006_create_tenant_quota_ledgers.up.sql
-CREATE TABLE tenant_quota_ledgers (
-    id            BIGSERIAL PRIMARY KEY,
-    tenant_id     BIGINT NOT NULL REFERENCES tenants(id),
-    quota_type    VARCHAR(50) NOT NULL, -- article_generation
-    delta         INT NOT NULL,
-    balance_after INT NOT NULL,
-    reason        VARCHAR(255),
-    reference_type VARCHAR(50),
-    reference_id   BIGINT,
-    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_tenant_quota_tenant_type_created ON tenant_quota_ledgers(tenant_id, quota_type, created_at DESC);
-
--- 20260331100007_create_quota_reservations.up.sql
-CREATE TABLE quota_reservations (
-    id              BIGSERIAL PRIMARY KEY,
-    tenant_id       BIGINT NOT NULL REFERENCES tenants(id),
-    quota_type      VARCHAR(50) NOT NULL,
-    resource_type   VARCHAR(50) NOT NULL,
-    resource_id     BIGINT NOT NULL,
-    reserved_amount INT NOT NULL,
-    consumed_amount INT NOT NULL DEFAULT 0,
-    refunded_amount INT NOT NULL DEFAULT 0,
-    status          VARCHAR(20) NOT NULL DEFAULT 'pending', -- pending, confirmed, refunded, expired
-    expire_at       TIMESTAMPTZ NOT NULL,
-    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_quota_reservation_tenant_status ON quota_reservations(tenant_id, status);
-```
-
-#### 3.1.2 模板与文章
-
-```sql
--- 20260331100010_create_article_templates.up.sql
-CREATE TABLE article_templates (
-    id                          BIGSERIAL PRIMARY KEY,
-    scope                       VARCHAR(20) NOT NULL, -- platform, tenant
-    tenant_id                   BIGINT REFERENCES tenants(id),
-    origin_type                 VARCHAR(20) NOT NULL DEFAULT 'platform', -- platform, tenant_custom, kol_share
-    share_code_id               BIGINT,
-    template_key                VARCHAR(100) NOT NULL,
-    template_name               VARCHAR(200) NOT NULL,
-    schema_json                 JSONB NOT NULL DEFAULT '{}',
-    prompt_template             TEXT,
-    prompt_visibility           VARCHAR(20) NOT NULL DEFAULT 'visible', -- visible, sealed
-    protected_prompt_asset_key  TEXT,
-    card_config_json            JSONB NOT NULL DEFAULT '{}',
-    status                      VARCHAR(20) NOT NULL DEFAULT 'active',
-    version_no                  INT NOT NULL DEFAULT 1,
-    created_at                  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at                  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at                  TIMESTAMPTZ,
-    CONSTRAINT uk_template_scope_key_version UNIQUE (scope, tenant_id, template_key, version_no)
-);
-
--- 20260331100011_create_articles.up.sql
-CREATE TABLE articles (
-    id                 BIGSERIAL PRIMARY KEY,
-    tenant_id          BIGINT NOT NULL REFERENCES tenants(id),
-    source_type        VARCHAR(30) NOT NULL, -- template, prompt_rule, optimization
-    template_id        BIGINT REFERENCES article_templates(id),
-    prompt_rule_id     BIGINT,
-    current_version_id BIGINT,
-    generate_status    VARCHAR(20) NOT NULL DEFAULT 'pending', -- pending, generating, completed, failed
-    publish_status     VARCHAR(20) NOT NULL DEFAULT 'unpublished', -- unpublished, publishing, success, failed, pending_review
-    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at         TIMESTAMPTZ
-);
-CREATE INDEX idx_article_tenant_created ON articles(tenant_id, created_at DESC);
-CREATE INDEX idx_article_tenant_status ON articles(tenant_id, generate_status, publish_status, created_at DESC);
-
--- 20260331100012_create_article_versions.up.sql
-CREATE TABLE article_versions (
-    id               BIGSERIAL PRIMARY KEY,
-    article_id       BIGINT NOT NULL REFERENCES articles(id),
-    version_no       INT NOT NULL,
-    title            VARCHAR(500),
-    html_content     TEXT,
-    markdown_content TEXT,
-    word_count       INT NOT NULL DEFAULT 0,
-    source_label     VARCHAR(100),
-    created_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    CONSTRAINT uk_article_version_no UNIQUE (article_id, version_no)
-);
-
--- 20260331100013_create_generation_tasks.up.sql
-CREATE TABLE generation_tasks (
-    id                   BIGSERIAL PRIMARY KEY,
-    tenant_id            BIGINT NOT NULL REFERENCES tenants(id),
-    article_id           BIGINT REFERENCES articles(id),
-    task_batch_id        VARCHAR(100),
-    quota_reservation_id BIGINT REFERENCES quota_reservations(id),
-    task_type            VARCHAR(50) NOT NULL, -- template, prompt, batch_item, schedule_item, optimize
-    request_hash         VARCHAR(64),
-    input_params_json    JSONB,
-    status               VARCHAR(20) NOT NULL DEFAULT 'queued', -- queued, running, completed, failed
-    error_message        TEXT,
-    started_at           TIMESTAMPTZ,
-    completed_at         TIMESTAMPTZ,
-    created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at           TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_generation_task_status_created ON generation_tasks(status, created_at);
-CREATE INDEX idx_generation_task_tenant ON generation_tasks(tenant_id, created_at DESC);
-```
-
-#### 3.1.3 品牌
-
-```sql
--- 20260331100020_create_brands.up.sql
-CREATE TABLE brands (
-    id          BIGSERIAL PRIMARY KEY,
-    tenant_id   BIGINT NOT NULL REFERENCES tenants(id),
-    name        VARCHAR(200) NOT NULL,
-    description TEXT,
-    status      VARCHAR(20) NOT NULL DEFAULT 'active',
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at  TIMESTAMPTZ,
-    CONSTRAINT uk_brand_tenant_name UNIQUE (tenant_id, name)
-);
-
--- 20260331100021_create_brand_keywords.up.sql
-CREATE TABLE brand_keywords (
-    id         BIGSERIAL PRIMARY KEY,
-    tenant_id  BIGINT NOT NULL REFERENCES tenants(id),
-    brand_id   BIGINT NOT NULL REFERENCES brands(id),
-    name       VARCHAR(200) NOT NULL,
-    status     VARCHAR(20) NOT NULL DEFAULT 'active',
-    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at TIMESTAMPTZ,
-    CONSTRAINT uk_brand_keyword_name UNIQUE (brand_id, name)
-);
-
--- 20260331100022_create_brand_questions.up.sql
-CREATE TABLE brand_questions (
-    id                 BIGSERIAL PRIMARY KEY,
-    tenant_id          BIGINT NOT NULL REFERENCES tenants(id),
-    brand_id           BIGINT NOT NULL REFERENCES brands(id),
-    keyword_id         BIGINT NOT NULL REFERENCES brand_keywords(id),
-    current_version_id BIGINT,
-    status             VARCHAR(20) NOT NULL DEFAULT 'active',
-    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at         TIMESTAMPTZ
-);
-CREATE INDEX idx_brand_questions_keyword ON brand_questions(keyword_id);
-
--- 20260331100023_create_brand_question_versions.up.sql
-CREATE TABLE brand_question_versions (
-    id            BIGSERIAL PRIMARY KEY,
-    question_id   BIGINT NOT NULL REFERENCES brand_questions(id),
-    question_text TEXT NOT NULL,
-    question_hash VARCHAR(64) NOT NULL,
-    version_no    INT NOT NULL,
-    is_active     BOOLEAN NOT NULL DEFAULT true,
-    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    CONSTRAINT uk_question_version_no UNIQUE (question_id, version_no)
-);
-CREATE INDEX idx_question_hash ON brand_question_versions(question_hash);
-
--- 20260331100024_create_competitors.up.sql
-CREATE TABLE competitors (
-    id                 BIGSERIAL PRIMARY KEY,
-    tenant_id          BIGINT NOT NULL REFERENCES tenants(id),
-    brand_id           BIGINT NOT NULL REFERENCES brands(id),
-    name               VARCHAR(200) NOT NULL,
-    website            TEXT,
-    description        TEXT,
-    product_lines_json JSONB,
-    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    deleted_at         TIMESTAMPTZ
-);
-CREATE INDEX idx_competitor_brand ON competitors(brand_id);
-```
-
-#### 3.1.4 基础设施
-
-```sql
--- 20260331100030_create_task_records.up.sql
-CREATE TABLE task_records (
-    id            BIGSERIAL PRIMARY KEY,
-    tenant_id     BIGINT NOT NULL REFERENCES tenants(id),
-    task_type     VARCHAR(50) NOT NULL,
-    resource_type VARCHAR(50) NOT NULL,
-    resource_id   BIGINT NOT NULL,
-    status        VARCHAR(20) NOT NULL DEFAULT 'pending',
-    retry_count   INT NOT NULL DEFAULT 0,
-    task_batch_id VARCHAR(100),
-    error_message TEXT,
-    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_task_record_status_type ON task_records(status, task_type);
-
--- 20260331100031_create_audit_logs.up.sql
-CREATE TABLE audit_logs (
-    id          BIGSERIAL PRIMARY KEY,
-    operator_id BIGINT NOT NULL REFERENCES users(id),
-    tenant_id   BIGINT,
-    module      VARCHAR(50) NOT NULL,
-    action      VARCHAR(50) NOT NULL,
-    before_json JSONB,
-    after_json  JSONB,
-    result      VARCHAR(20),
-    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_audit_module_created ON audit_logs(module, created_at DESC);
-```
-
-### 3.2 种子数据
-
-`make dev-init` 需要写入最小种子数据：
-
-- 1 个默认租户
-- 1 个 tenant_admin 用户 (admin@geo.local / 默认密码)
-- 1 个 tenant_membership
-- 1 个免费套餐 (plan)
-- 1 个订阅关系
-- 初始额度记录
-- 3-4 个平台预设模板 (Top X 文章、产品评测文章、研究报告文章、品牌词搜索扩写)
-
-## 4. API 设计
-
-### 4.1 统一响应格式
-
-所有 API 返回：
-
-```json
-// 成功
-{
-    "code": 0,
-    "message": "ok",
-    "data": { ... },
-    "request_id": "req_xxx"
-}
-
-// 失败
-{
-    "code": 40301,
-    "message": "quota_insufficient",
-    "detail": "生成额度不足，请升级套餐或等待额度重置",
-    "request_id": "req_xxx"
-}
-```
-
-错误码段 (§13.6.4)：`400xx` 参数错误, `401xx` 认证失败, `403xx` 权限/额度不足, `404xx` 资源不存在, `409xx` 状态冲突, `429xx` 频率限制, `500xx` 内部错误, `503xx` 下游不可用。
-
-### 4.2 分页格式
-
-请求：`?page=1&page_size=20&sort=created_at&order=desc`
-
-响应 data 字段：
-
-```json
-{
-    "items": [...],
-    "total": 100,
-    "page": 1,
-    "page_size": 20
-}
-```
-
-### 4.3 Auth API
-
-| Method | Path | 说明 |
-|--------|------|------|
-| POST | `/api/auth/login` | 邮箱+密码登录，返回 access_token + refresh_token |
-| POST | `/api/auth/refresh` | 刷新 access_token |
-| GET | `/api/auth/me` | 返回当前用户信息、tenant_id、tenant_role、permissions[] |
-| POST | `/api/auth/logout` | 登出 (可选：加入 token 黑名单) |
-
-**JWT Claims**：
-```go
-type Claims struct {
-    UserID   int64  `json:"user_id"`
-    TenantID int64  `json:"tenant_id"`
-    Role     string `json:"role"` // tenant_admin, editor
-    jwt.RegisteredClaims
-}
-```
-
-- Access token TTL: 15 分钟
-- Refresh token TTL: 7 天
-- Refresh token 存 Redis，支持主动失效
-
-### 4.4 Workspace API
-
-| Method | Path | 说明 |
-|--------|------|------|
-| GET | `/api/tenant/workspace/overview` | 聚合统计：文章数、发布数、品牌数、媒体平台数 |
-| GET | `/api/tenant/workspace/recent-articles` | 最近 10 篇文章 (带生成状态/发布状态) |
-| GET | `/api/tenant/workspace/quota-summary` | 当前套餐额度：已用/总量/重置时间 |
-| GET | `/api/tenant/workspace/template-cards` | 可用模板卡片列表 (平台预设 + 租户自建) |
-
-workspace_service 聚合多个 repository 数据，单次返回，避免前端首屏发起过多散请求 (§13.2)。
-
-### 4.5 Template API
-
-| Method | Path | 说明 |
-|--------|------|------|
-| GET | `/api/tenant/templates` | 模板列表 (scope=platform 或 tenant_id 匹配) |
-| GET | `/api/tenant/templates/{id}` | 模板详情 (prompt_visibility=sealed 时不返回 prompt_template) |
-| GET | `/api/tenant/templates/{id}/schema` | 模板表单 schema (JSON) |
-| POST | `/api/tenant/templates/{id}/generate` | 提交生成任务 |
-
-**生成流程** (§10.1)：
-1. 校验租户身份、额度、参数
-2. 在单个 PG 事务内：额度预扣 + generation_tasks 创建 + articles 占位记录
-3. 返回 task_id 和 article_id
-4. (V1 第一阶段：任务状态模拟为同步完成或标记为 queued 等待 worker)
-
-### 4.6 Article API
-
-| Method | Path | 说明 |
-|--------|------|------|
-| GET | `/api/tenant/articles` | 文章列表 (分页、筛选：generate_status, publish_status, source_type, template_id, keyword, date_range) |
-| GET | `/api/tenant/articles/{id}` | 文章详情 (含当前版本内容) |
-| GET | `/api/tenant/articles/{id}/versions` | 文章版本列表 |
-| DELETE | `/api/tenant/articles/{id}` | 删除文章 |
-
-### 4.7 Brand API
-
-| Method | Path | 说明 |
-|--------|------|------|
-| GET | `/api/tenant/brands` | 品牌列表 |
-| POST | `/api/tenant/brands` | 创建品牌 |
-| GET | `/api/tenant/brands/{id}` | 品牌详情 |
-| PUT | `/api/tenant/brands/{id}` | 更新品牌 |
-| DELETE | `/api/tenant/brands/{id}` | 删除品牌 |
-| GET | `/api/tenant/brands/{id}/keywords` | 关键词列表 |
-| POST | `/api/tenant/brands/{id}/keywords` | 创建关键词 |
-| PUT | `/api/tenant/brands/{id}/keywords/{kid}` | 更新关键词 |
-| DELETE | `/api/tenant/brands/{id}/keywords/{kid}` | 删除关键词 |
-| GET | `/api/tenant/brands/{id}/questions` | 问题列表 (按关键词筛选) |
-| POST | `/api/tenant/brands/{id}/questions` | 创建问题 (自动创建 v1 版本) |
-| GET | `/api/tenant/brands/{id}/competitors` | 竞品列表 |
-| POST | `/api/tenant/brands/{id}/competitors` | 创建竞品 |
-| PUT | `/api/tenant/brands/{id}/competitors/{cid}` | 更新竞品 |
-| DELETE | `/api/tenant/brands/{id}/competitors/{cid}` | 删除竞品 |
-
-### 4.8 Health Check
-
-| Method | Path | 说明 |
-|--------|------|------|
-| GET | `/api/health/live` | 存活检查 |
-| GET | `/api/health/ready` | 就绪检查 (DB + Redis 可达) |
-
-## 5. 中间件链
-
-请求处理顺序 (§6.3)：
-
-1. Recovery (panic 恢复)
-2. RequestID (生成/复用 request_id)
-3. Logger (请求日志)
-4. CORS
-5. Auth (JWT 校验 + 身份注入 ctx) — `/api/auth/login` 和 `/api/health/*` 除外
-6. TenantScope (从 JWT 提取 tenant_id 注入 ctx)
-7. Handler
-
-### 5.1 TenantScope 实现
-
-```go
-// 从 context 中获取 tenant_id，repository 层必须调用
-func TenantIDFromCtx(ctx context.Context) int64
-```
-
-所有 tenant repository 方法的 SQL 必须包含 `WHERE tenant_id = $tenant_id`。sqlc 生成的查询默认带上此参数。
-
-## 6. 本地开发
-
-### 6.1 docker-compose.yaml
-
-仅启动基础设施：
-
-```yaml
-services:
-  postgres:
-    image: postgres:16
-    ports: ["5432:5432"]
-    environment:
-      POSTGRES_DB: geo
-      POSTGRES_USER: geo
-      POSTGRES_PASSWORD: geo_dev
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-
-  redis:
-    image: redis:7-alpine
-    ports: ["6379:6379"]
-
-volumes:
-  pgdata:
-```
-
-### 6.2 Makefile 命令
-
-```makefile
-dev-init:     # docker compose up -d + migrate up + seed data
-dev-api:      # go run ./server/cmd/tenant-api
-migrate-up:   # golang-migrate up
-migrate-down: # golang-migrate down 1
-migrate-create: # 创建新 migration 文件
-sqlc-generate: # sqlc generate
-lint:          # golangci-lint run
-test:          # go test ./...
-```
-
-### 6.3 配置文件
-
-```yaml
-# configs/config.yaml
-server:
-  port: 8080
-  mode: debug  # debug / release
-
-database:
-  host: localhost
-  port: 5432
-  user: geo
-  password: geo_dev
-  dbname: geo
-  sslmode: disable
-  max_open_conns: 25
-  max_idle_conns: 5
-
-redis:
-  addr: localhost:6379
-  db: 0
-
-jwt:
-  secret: "${JWT_SECRET:dev-secret-change-in-production}"
-  access_ttl: 15m
-  refresh_ttl: 168h  # 7 days
-
-log:
-  level: debug
-  format: json
-```
-
-## 7. 验证方式
-
-1. `make dev-init` 启动基础设施并初始化数据库
-2. `make dev-api` 启动 tenant-api
-3. `POST /api/auth/login` 登录获取 token
-4. `GET /api/auth/me` 验证身份
-5. `GET /api/tenant/workspace/overview` 验证工作台数据
-6. `GET /api/tenant/templates` 查看预设模板
-7. `POST /api/tenant/brands` 创建品牌
-8. `GET /api/tenant/brands/{id}/keywords` 查看关键词
-9. `make test` 所有测试通过
-10. `make lint` 无 lint 错误
diff --git a/findings.md b/findings.md
index 4eb3eab..7904571 100644
--- a/findings.md
+++ b/findings.md
@@ -54,6 +54,14 @@
 - The user explicitly asked for i18n and styling discipline during implementation: text should move behind translation keys, and component styles should live in `<style>` blocks rather than inline attributes.
 - `pnpm dev:admin` regressed temporarily after the route graph referenced a missing `BrandsView.vue`; adding the missing view, installing the new frontend dependency set, and rerunning checks restored the Vite startup path.
 - `pnpm typecheck:admin` now passes after introducing the i18n scaffold, restoring `AppShell.vue` to the user's preferred version, and removing inline styles from the Vue SFC templates.
+- The currently used hard-coded prompts are concentrated in four runtime areas: `cmd/dev-seed` platform template seeds, `template_prompt.go` generation fallback sections, `template_assist.go` analyze/title/outline fallback prompts, and `prompt_generate_service.go` plus `knowledge_service.go` prompt supplements.
+- The seed path stores four full article prompt templates plus twelve wizard prompt templates inside large inline JSON blobs, which makes prompt iteration awkward and easy to miss during later tuning.
+- Runtime prompt assembly still embeds section titles, writing rules, output requirements, output examples, and knowledge-reference instructions directly inside application functions.
+- A dedicated prompt hub now exists under `server/internal/tenant/prompts/`: `template_seeds.go` owns the four platform template seeds and their wizard prompt templates, while `runtime.go` owns generation fallback prompts, assist fallback prompts, prompt-rule supplements, and knowledge prompt instructions.
+- `cmd/dev-seed` now reads platform templates from `prompts.PlatformTemplateSeeds()` instead of carrying 400+ lines of inline prompt/card-config text in the command itself.
+- `template_prompt.go`, `template_assist.go`, `prompt_generate_service.go`, and `knowledge_service.go` now assemble prompts from the centralized prompt package, so runtime business logic no longer embeds the long prompt text directly.
+- The prompt centralization also corrected invalid JSON quoting in the seed card config `custom_placeholder` fields, which previously contained unescaped inner quotes.
+- Targeted verification passed with `go test ./internal/tenant/... ./cmd/dev-seed` from `server/`, confirming the refactor compiles cleanly across the affected runtime and seed paths.
 
 ## Technical Decisions
 | Decision | Rationale |
@@ -69,6 +77,7 @@
 | Use screenshot-derived spatial structure as an implementation constraint | Needed to satisfy the user's requirement to follow layout and placement, not just labels |
 | Introduce a minimal `vue-i18n` foundation now instead of leaving hard-coded strings in new pages | The user explicitly called out the current i18n approach as non-standard |
 | Keep `AppShell.vue` on the user-preferred version and avoid structural/style rewrites there | The user said that file is managed elsewhere and only allowed inline-style cleanup |
+| Create a dedicated `internal/tenant/prompts` package for prompt text and seed definitions | This keeps prompt tuning in one place while minimizing refactor risk in the current dirty worktree |
 
 ## Issues Encountered
 | Issue | Resolution |
diff --git a/packages/shared-types/src/index.ts b/packages/shared-types/src/index.ts
index 0968666..ed0d4f2 100644
--- a/packages/shared-types/src/index.ts
+++ b/packages/shared-types/src/index.ts
@@ -526,6 +526,48 @@ export interface Competitor {
   created_at: string;
 }
 
+export interface KnowledgeGroup {
+  id: number;
+  name: string;
+  parent_id: number | null;
+  sort_order: number;
+  item_count: number;
+  created_at: string;
+  children: KnowledgeGroup[];
+}
+
+export interface KnowledgeGroupRequest {
+  name: string;
+  parent_id?: number | null;
+  sort_order?: number;
+}
+
+export interface KnowledgeItem {
+  id: number;
+  group_id: number;
+  group_name: string;
+  name: string;
+  source_type: "text" | "document" | "website";
+  source_uri: string | null;
+  status: string;
+  size_bytes: number;
+  error_message: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface KnowledgeTextItemRequest {
+  group_id: number;
+  name: string;
+  content: string;
+}
+
+export interface KnowledgeURLItemRequest {
+  group_id: number;
+  name: string;
+  url: string;
+}
+
 // --- Prompt Rule Groups ---
 
 export interface PromptRuleGroup {
@@ -550,12 +592,19 @@ export interface PromptRule {
   scene: string | null;
   default_tone: string | null;
   default_word_count: number | null;
+  knowledge_group_ids: number[];
+  knowledge_groups: KnowledgeGroupOption[];
   status: "enabled" | "disabled";
   article_count: number;
   created_at: string;
   updated_at: string;
 }
 
+export interface KnowledgeGroupOption {
+  id: number;
+  name: string;
+}
+
 export interface PromptRuleRequest {
   group_id?: number | null;
   name: string;
@@ -563,6 +612,7 @@ export interface PromptRuleRequest {
   scene?: string;
   default_tone?: string;
   default_word_count?: number;
+  knowledge_group_ids?: number[];
 }
 
 export interface PromptRuleListParams {
diff --git a/progress.md b/progress.md
index d1ef27f..16a4378 100644
--- a/progress.md
+++ b/progress.md
@@ -1,5 +1,39 @@
 # Progress Log
 
+## Session: 2026-04-04
+
+### Phase 13: Prompt Centralization
+- **Status:** complete
+- Actions taken:
+  - Read the current planning files and reopened repository context for the new prompt-centralization request.
+  - Searched runtime and seed paths for all currently used hard-coded prompts instead of only matching the obvious template seed strings.
+  - Confirmed the prompt surface spans template seeds, template generation fallback prompts, template assist fallback prompts, prompt-rule generation supplements, and knowledge prompt injection.
+  - Added a dedicated `server/internal/tenant/prompts` package to centralize platform template seed prompts and runtime prompt fragments.
+  - Refactored `cmd/dev-seed`, `template_prompt.go`, `template_assist.go`, `prompt_generate_service.go`, and `knowledge_service.go` to read prompt text from the new package.
+  - Corrected invalid JSON quoting in the seed `custom_placeholder` fields while moving the template card-config blobs.
+- Files created/modified:
+  - `task_plan.md` (updated)
+  - `findings.md` (updated)
+  - `progress.md` (updated)
+  - `server/internal/tenant/prompts/runtime.go` (created)
+  - `server/internal/tenant/prompts/template_seeds.go` (created)
+  - `server/cmd/dev-seed/main.go` (updated)
+  - `server/internal/tenant/app/template_prompt.go` (updated)
+  - `server/internal/tenant/app/template_assist.go` (updated)
+  - `server/internal/tenant/app/prompt_generate_service.go` (updated)
+  - `server/internal/tenant/app/knowledge_service.go` (updated)
+
+### Phase 14: Prompt Verification & Delivery
+- **Status:** complete
+- Actions taken:
+  - Ran `gofmt` across all changed Go files after the prompt extraction.
+  - Re-scanned the runtime and seed callers to confirm the long prompt literals were removed from business functions and now only live under `server/internal/tenant/prompts`.
+  - Ran `go test ./internal/tenant/... ./cmd/dev-seed` from `server/` and confirmed the affected packages compile and tests pass.
+- Files created/modified:
+  - `task_plan.md` (updated)
+  - `findings.md` (updated)
+  - `progress.md` (updated)
+
 ## Session: 2026-03-31
 
 ### Phase 10: Interface Coverage Audit & Visual Mapping
diff --git a/server/cmd/dev-seed/main.go b/server/cmd/dev-seed/main.go
index c947084..e971ec4 100644
--- a/server/cmd/dev-seed/main.go
+++ b/server/cmd/dev-seed/main.go
@@ -10,6 +10,7 @@ import (
 	"golang.org/x/crypto/bcrypt"
 
 	"github.com/geo-platform/tenant-api/internal/shared/config"
+	"github.com/geo-platform/tenant-api/internal/tenant/prompts"
 )
 
 func main() {
@@ -139,405 +140,16 @@ func main() {
 	}
 
 	// Platform templates
-	templates := []struct {
-		key, name, prompt, cardConfig string
-	}{
-		{
-			"top_x_article",
-			"Top X 文章",
-			`你是一名经验丰富的内容编辑，请围绕「{{topic}}」撰写一篇完整的 Markdown 推荐类文章。
-文章目标:
-1. 帮读者快速理解这个主题下值得关注的 {{count}} 个方向、产品或对象。
-2. 说明每个对象的核心特点、适用场景、优缺点和选择建议。
-
-写作要求:
-- 不要写成空洞的排行列表；每个对象都要有清晰的入选理由和判断依据。
-- 如果提供了 competitors、品牌或关键词上下文，要自然融入横向比较，但不要机械重复名单。
-- 如果提供了 brand_name，且文章属于品牌、公司或服务商对比型推荐内容，应将该品牌作为主推对象：默认排在第 1 位、正文篇幅明显多于其他对象、结论优先推荐。
-- 对 brand_name 对应对象重点展开核心优势、本地服务、适合人群、报价或配置亮点、交付安装、售后与避坑建议；其他对象保持客观但更简洁的差异化介绍。
-- 重点写筛选标准、差异点、适合谁、不适合谁，以及常见误区或避坑点。
-- 引言先交代推荐标准与读者能得到什么，结尾优先总结 brand_name 为什么值得优先考虑，再补充其他对象各自适合的预算与需求。`,
-			`{
-  "hero": {
-    "accent": "Top X",
-    "helper": "排序推荐类文章，适合快节奏种草、结构化比较和选购决策。"
-  },
-  "wizard": {
-    "steps": {
-      "basic": { "title": "基本信息", "description": "品牌、关键词与竞品上下文" },
-      "structure": { "title": "文章结构", "description": "标题方案、结构组合与重点补充" },
-      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
-    },
-    "basic": {
-      "analyze_button_label": "分析",
-      "cards": {
-        "brand": {
-          "title": "品牌信息",
-          "hint": "品牌可手动输入，也可从品牌库带入。AI 会结合品牌、官网和模板字段补齐关键词与竞品。"
-        },
-        "keywords": {
-          "title": "关键词",
-          "hint": "关键词可以手动改写，AI 分析结果会自动补充到这里，后续标题生成会以当前版本为准。"
-        },
-        "template_fields": {
-          "title": "模板字段",
-          "hint": "保留本模板特有的补充字段，用来约束选题角度与文章范围。"
-        },
-        "competitors": {
-          "title": "竞品列表",
-          "hint": "竞品可编辑、追加和收藏到品牌词库。后续标题生成会严格基于当前竞品上下文。"
-        }
-      }
-    },
-    "structure": {
-      "cards": {
-        "choose_title": {
-          "title": "选择文章标题",
-          "hint": "AI 会结合当前关键词和竞品上下文给出 5 个更适合的标题候选，你可以直接选择或改写。"
-        },
-        "outline": {
-          "title": "文章结构",
-          "hint": "保留推荐文章的默认结构，也可以按这次出稿需求删减、补充自定义段落。"
-        },
-        "preview": {
-          "title": "文章预览",
-          "hint": "右侧会根据当前标题和结构实时预览最终文章框架。"
-        }
-      }
-    },
-    "review": {
-      "card": {
-        "title": "提交前确认",
-        "hint": "确认当前标题、结构和品牌上下文无误后再提交生成任务。"
-      },
-      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
-    },
-    "managed_fields": ["topic", "count"],
-    "derived_inputs": {
-      "topic": { "source": "primary_keyword_or_brand" },
-      "count": { "source": "competitor_count", "fallback_number": 5 }
-    },
-    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为推荐类文章做品牌与竞品分析。\n模板: {{template_name}}\n语言: {{locale}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n\n任务:\n1. 分析品牌/话题上下文，给出 1-2 句品牌摘要。\n2. 推荐最多 5 个适合推荐类文章的搜索关键词。\n3. 推荐最多 6 个可信竞品或对比对象。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词应为简洁的搜索短语。\n- 竞品应去重且真实，不确定时 website 留空，不要编造 URL。",
-    "title_prompt_template": "你正在为一篇推荐类文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n核心关键词: {{primary_keyword}}\n品牌名: {{brand_name}}\n推荐数量: {{top_count}}\n竞品名称: {{competitor_names}}\n\n要求:\n- 标题风格应契合实用选购指南、推荐合集、横向对比、避坑盘点等内容调性。\n- 不要机械重复模板名称或「Top X 文章」字样。\n- 每个标题应具体、可读，且角度各不相同。\n- 当 locale 为 zh-CN 时，优先使用自然的中文标题风格，如推荐、精选、怎么选、避坑、盘点等，但避免空洞标题党。",
-    "outline_prompt_template": "你正在为一篇推荐类文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n标题: {{title}}\n核心关键词: {{primary_keyword}}\n品牌名: {{brand_name}}\n竞品名称: {{competitor_names}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n\n要求:\n- 每个已选段落作为顶层节点，下设具体子条目。\n- 网站列表段落下按竞品逐一展开。\n- 内容应具体、有对比、有结论导向，避免泛泛而谈。\n- 使用与 locale 一致的语言。",
-    "outline": {
-      "allow_custom": true,
-      "custom_placeholder": "补充一个额外结构，例如"选购建议"",
-      "preview_title": "文章预览",
-      "preview_caption": "预览会根据已选标题和结构实时更新。",
-      "sections": [
-        { "key": "intro", "label": "引言", "default": true },
-        { "key": "site_list", "label": "网站列表", "default": true },
-        { "key": "key_points", "label": "文章关键要点", "default": true },
-        { "key": "what_is_keyword", "label_template": "什么是{{primary_keyword}}", "default": false },
-        { "key": "features", "label": "特点", "default": false },
-        { "key": "pros_cons", "label": "优缺点", "default": false },
-        { "key": "audience", "label": "适合人群", "default": false },
-        { "key": "pricing", "label": "价格", "default": false },
-        { "key": "how_to_choose", "label": "如何选择", "default": false },
-        { "key": "conclusion", "label": "结论", "default": false }
-      ]
-    }
-  }
-}`,
-		},
-		{
-			"product_review",
-			"产品评测文章",
-			`你是一名资深产品评测编辑，请围绕「{{product_name}}」这款{{category}}产品撰写一篇完整的 Markdown 评测文章。
-文章目标:
-1. 帮读者判断这款产品是否值得关注或购买。
-2. 解释它的核心能力、实际使用感受、主要优缺点和适合人群。
-
-写作要求:
-- 开头快速进入评测主题；如果提供了 review_intro_hook，则按对应风格自然起笔，但不要故作夸张。
-- 正文要覆盖产品定位、核心功能、使用体验、限制点、适用场景和购买建议。
-- 评价必须有判断，不要只罗列卖点；要说明为什么是优点、在什么情况下会变成限制。
-- 结论写清楚适合谁、不适合谁，以及在什么条件下值得买。
-- 全文保持客观、务实，不要写成品牌宣传稿。`,
-			`{
-  "hero": {
-    "accent": "Review",
-    "helper": "产品评测类文章，适合做能力拆解、优缺点判断和适配建议。"
-  },
-  "wizard": {
-    "steps": {
-      "basic": { "title": "基本信息", "description": "产品、品牌与评测上下文" },
-      "structure": { "title": "文章结构", "description": "标题方案、评测结构与重点补充" },
-      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
-    },
-    "basic": {
-      "analyze_button_label": "分析",
-      "cards": {
-        "brand": {
-          "title": "品牌信息",
-          "hint": "可直接输入品牌，也可从品牌库选择。AI 会补充适合评测文章的关键词和品牌背景。"
-        },
-        "keywords": {
-          "title": "关键词",
-          "hint": "关键词会影响标题和正文的评测切入点，可手动修改。"
-        },
-        "competitors": {
-          "visible": false
-        }
-      }
-    },
-    "structure": {
-      "cards": {
-        "choose_title": {
-          "title": "选择文章标题",
-          "hint": "AI 会生成 5 个更适合评测文章的标题候选，你可以挑选或覆盖。"
-        },
-        "outline": {
-          "title": "文章结构",
-          "hint": "保留评测默认结构，也可按具体产品情况增删段落。"
-        },
-        "preview": {
-          "title": "文章预览",
-          "hint": "右侧会根据标题和结构实时预览评测文章框架。"
-        }
-      },
-      "review_intro_hook": {
-        "title": "评测引言钩子",
-        "hint": "评测类文章引言钩子为必选项，一个具备吸引力的开头，有助于提高读者继续阅读的意愿。",
-        "field_name": "review_intro_hook",
-        "required": true,
-        "options": [
-          { "key": "question", "label": "提出问题", "description": "用一个有趣的问题引导读者继续往下看", "default": true },
-          { "key": "fact", "label": "分享事实", "description": "利用令人惊讶的事实或数据先抓住注意力" },
-          { "key": "quote", "label": "引用名言", "description": "用一句贴切的名言或行业观点作为开头" },
-          { "key": "story", "label": "讲述故事", "description": "从一个具体场景或小故事切入评测主题" },
-          { "key": "feeling", "label": "分享感受", "description": "用第一视角的真实感受建立代入感" }
-        ]
-      },
-      "outline_prompt_template": "你正在为一篇产品评测文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n标题: {{title}}\n产品名: {{product_name}}\n品类: {{category}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n评测引言钩子: {{review_intro_hook}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n\n要求:\n- 每个已选段落作为顶层节点，使用与请求一致的语言。\n- 当有引言段落时，子条目应体现所选的评测引言钩子风格。\n- 聚焦具体能力拆解、真实使用判断、优缺点权衡和适合人群。\n- 大纲务实、简洁、不含推广语气。"
-    },
-    "review": {
-      "card": {
-        "title": "提交前确认",
-        "hint": "确认当前标题、结构与评测角度后再提交生成。"
-      },
-      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
-    },
-    "managed_fields": [],
-    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为产品评测文章做品牌与产品分析。\n模板: {{template_name}}\n语言: {{locale}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n产品名: {{product_name}}\n品类: {{category}}\n\n任务:\n1. 分析产品与品牌上下文，给出 1-2 句品牌摘要。\n2. 推荐最多 5 个适合评测文章的搜索关键词，聚焦产品能力、使用场景和购买决策。\n3. 推荐最多 6 个可信的同类产品或替代方案。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词侧重评测视角，如「XX 评测」「XX 值不值得买」「XX 优缺点」。\n- 竞品应去重且真实，不确定时 website 留空。",
-    "title_prompt_template": "你正在为一篇产品评测文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n产品名: {{product_name}}\n品类: {{category}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n\n要求:\n- 标题应像可信的评测、测评、购买建议类内容。\n- 用具体表达代替空洞口号。\n- 当 locale 为 zh-CN 时，标题应贴合中文内容平台风格，可使用评测、实测、值不值得买、优缺点、怎么选等表达。\n- 返回 5 个角度明确不同的标题。",
-    "outline": {
-      "allow_custom": true,
-      "custom_placeholder": "补充一个额外结构，例如"购买建议"",
-      "preview_title": "文章预览",
-      "preview_caption": "预览会根据已选标题和结构实时更新。",
-      "sections": [
-        { "key": "intro", "label": "引言", "default": true },
-        { "key": "overview", "label": "产品概览", "default": true },
-        { "key": "core_features", "label": "核心卖点", "default": true },
-        { "key": "real_experience", "label": "使用体验", "default": false },
-        { "key": "pros_cons", "label": "优缺点", "default": false },
-        { "key": "audience", "label": "适合人群", "default": false },
-        { "key": "buying_advice", "label": "购买建议", "default": false },
-        { "key": "conclusion", "label": "结论", "default": false }
-      ]
-    }
-  }
-}`,
-		},
-		{
-			"research_report",
-			"研究报告文章",
-			`你是一名研究分析师，请围绕「{{subject}}」撰写一篇完整的 Markdown 研究报告。
-文章目标:
-1. 提炼关键事实、趋势与结构化发现。
-2. 解释背后原因，并给出可执行的判断或建议。
-
-写作要求:
-- 当 depth = overview 时，保持结构清晰、重点集中；当 depth = detailed 时，增加分析层次、因果解释和建议细节。
-- 不要泛泛复述背景，要突出关键发现、变化趋势、风险与影响。
-- 如果提供了品牌、关键词或参考对象，应把它们作为分析参照，而不是简单罗列。
-- 摘要部分先给核心结论，正文再展开依据，结尾落到行动建议或后续观察点。`,
-			`{
-  "hero": {
-    "accent": "Report",
-    "helper": "研究报告类文章，适合趋势解读、市场分析和策略判断。"
-  },
-  "wizard": {
-    "steps": {
-      "basic": { "title": "基本信息", "description": "品牌与关键词背景信息" },
-      "structure": { "title": "文章结构", "description": "标题方案、研究结构与重点补充" },
-      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
-    },
-    "basic": {
-      "analyze_button_label": "分析",
-      "cards": {
-        "brand": {
-          "title": "品牌信息",
-          "hint": "如研究对象与品牌有关，可补充品牌与官网信息帮助 AI 建立上下文。"
-        },
-        "keywords": {
-          "title": "关键词",
-          "hint": "关键词会影响报告的核心视角、结论表达和标题风格。"
-        },
-        "competitors": {
-          "visible": false
-        }
-      }
-    },
-    "structure": {
-      "cards": {
-        "choose_title": {
-          "title": "选择文章标题",
-          "hint": "AI 会生成 5 个更适合研究型内容的标题候选，你可以直接选择或改写。"
-        },
-        "outline": {
-          "title": "文章结构",
-          "hint": "保留研究报告的默认结构，也可补充更贴近本次出稿的章节。"
-        },
-        "preview": {
-          "title": "文章预览",
-          "hint": "右侧会根据标题和结构实时预览报告框架。"
-        }
-      }
-    },
-    "review": {
-      "card": {
-        "title": "提交前确认",
-        "hint": "确认当前标题、结构和研究主题后再提交生成。"
-      },
-      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
-    },
-    "managed_fields": [],
-    "derived_inputs": {
-      "subject": { "source": "primary_keyword_or_brand" }
-    },
-    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为研究报告做主题与背景分析。\n模板: {{template_name}}\n语言: {{locale}}\n研究主题: {{subject}}\n深度: {{depth}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n\n任务:\n1. 分析研究主题上下文，给出 1-2 句主题摘要。\n2. 推荐最多 5 个适合研究报告的搜索关键词，侧重行业术语和趋势表达。\n3. 推荐最多 6 个可作为参照的品牌、机构或竞争对手。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词应体现分析性视角，如「XX 市场分析」「XX 趋势」「XX 行业报告」。\n- 竞品应去重且真实，不确定时 website 留空。",
-    "title_prompt_template": "你正在为一篇研究报告文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n研究主题: {{subject}}\n深度: {{depth}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n\n要求:\n- 标题应具有分析性、聚焦感和洞察力。\n- 避免模糊的企业公关式措辞。\n- 当 locale 为 zh-CN 时，可使用研究报告、趋势洞察、观察、判断、分析等表达。\n- 返回 5 个角度各异但可信的报告风格标题。",
-    "outline_prompt_template": "你正在为一篇研究报告文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n标题: {{title}}\n研究主题: {{subject}}\n深度: {{depth}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n\n要求:\n- 每个已选段落作为顶层节点，下设具体子条目。\n- 关键发现段落应按数据驱动的方式组织子条目。\n- 内容应具有结构性、分析深度和可操作性。\n- 使用与 locale 一致的语言。",
-    "outline": {
-      "allow_custom": true,
-      "custom_placeholder": "自定义输入，不超过10个字",
-      "custom_max_length": 10,
-      "preview_title": "文章预览",
-      "preview_caption": "预览会根据已选标题和结构实时更新。",
-      "sections": [
-        { "key": "summary", "label": "摘要", "default": true },
-        { "key": "intro", "label": "引言", "default": true },
-        { "key": "methodology", "label": "研究方法与数据来源", "default": true },
-        { "key": "segment_overview", "label": "细分市场概述", "default": true },
-        { "key": "positioning_analysis", "label": "产品定位与优缺点", "default": true },
-        { "key": "user_research", "label": "用户调研", "default": false },
-        { "key": "target_audience", "label": "目标人群", "default": false },
-        { "key": "competitor_comparison", "label": "竞品对比", "default": false },
-        { "key": "research_conclusion", "label": "研究结论", "default": false },
-        { "key": "analysis_recommendations", "label": "分析建议", "default": false }
-      ]
-    }
-  }
-}`,
-		},
-		{
-			"brand_search_expansion",
-			"品牌词搜索扩写",
-			`你是一名擅长搜索意图写作的内容编辑，请围绕「{{brand}} {{keyword}}」撰写一篇完整的 Markdown 品牌词搜索扩写文章。
-文章目标:
-1. 直接回答搜索用户最关心的问题。
-2. 解释品牌背景、核心信息和常见对比/疑问，承接后续转化或继续了解。
-
-写作要求:
-- 开头优先回答搜索意图，不要长篇铺垫。
-- 正文应覆盖品牌是什么、用户为什么会搜这个词、常见疑问、对比点和下一步决策信息。
-- 如果提供了竞品或替代方案，按用户常见比较维度展开，不要空泛地说“各有优势”。
-- 语气客观、有信息量，避免企业宣传腔。
-- 结尾给出简洁总结，并提示用户接下来应该关注什么信息来继续判断。`,
-			`{
-  "hero": {
-    "accent": "Brand SEO",
-    "helper": "品牌词搜索扩写，适合品牌介绍、搜索意图承接、问答和比较型内容。"
-  },
-  "wizard": {
-    "steps": {
-      "basic": { "title": "基本信息", "description": "品牌、关键词与搜索意图上下文" },
-      "structure": { "title": "文章结构", "description": "标题方案、结构组合与重点补充" },
-      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
-    },
-    "basic": {
-      "analyze_button_label": "分析",
-      "cards": {
-        "brand": {
-          "title": "品牌信息",
-          "hint": "品牌和官网会帮助 AI 理解搜索对象，也便于后续沉淀到品牌库。"
-        },
-        "keywords": {
-          "title": "关键词",
-          "hint": "这里的关键词会直接参与标题与正文的搜索意图组织。"
-        },
-        "template_fields": {
-          "title": "模板字段",
-          "hint": "模板字段会补充品牌词与搜索意图的具体边界。"
-        },
-        "competitors": {
-          "title": "参考对象",
-          "hint": "可补充竞品或替代方案，帮助品牌词扩写内容更完整。"
-        }
-      }
-    },
-    "structure": {
-      "cards": {
-        "choose_title": {
-          "title": "选择文章标题",
-          "hint": "AI 会生成 5 个更适合品牌词搜索扩写的标题候选。"
-        },
-        "outline": {
-          "title": "文章结构",
-          "hint": "保留默认搜索意图结构，也可以按本次需求增删段落。"
-        },
-        "preview": {
-          "title": "文章预览",
-          "hint": "右侧会根据标题和结构实时预览内容框架。"
-        }
-      }
-    },
-    "review": {
-      "card": {
-        "title": "提交前确认",
-        "hint": "确认当前标题、结构与搜索上下文后再提交生成。"
-      },
-      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
-    },
-    "managed_fields": ["brand", "keyword"],
-    "derived_inputs": {
-      "brand": { "source": "brand_name" },
-      "keyword": { "source": "primary_keyword" }
-    },
-    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为品牌词搜索扩写文章做品牌与意图分析。\n模板: {{template_name}}\n语言: {{locale}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n关键词: {{primary_keyword}}\n\n任务:\n1. 分析品牌与搜索意图上下文，给出 1-2 句品牌摘要。\n2. 推荐最多 5 个品牌词搜索相关的关键词，侧重搜索意图和用户疑问。\n3. 推荐最多 6 个可信的竞品或替代方案。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词应贴合搜索意图，如「XX 是什么」「XX 怎么样」「XX 对比 YY」。\n- 竞品应去重且真实，不确定时 website 留空。",
-    "title_prompt_template": "你正在为一篇品牌词搜索扩写文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n官网: {{official_website}}\n\n要求:\n- 标题应适用于品牌搜索意图、对比、问答和解释型内容。\n- 避免空洞口号。\n- 当 locale 为 zh-CN 时，可使用是什么、怎么样、怎么选、对比、值得买吗等表达。\n- 返回 5 个不同的、贴合搜索意图的标题选项。",
-    "outline_prompt_template": "你正在为一篇品牌词搜索扩写文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n标题: {{title}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n官网: {{official_website}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n竞品名称: {{competitor_names}}\n\n要求:\n- 每个已选段落作为顶层节点，下设具体子条目。\n- 品牌概览段落应覆盖品牌定位、核心产品和差异化。\n- 对比段落应按竞品逐一展开对比维度。\n- 内容应回答搜索意图，语气客观有信息量。\n- 使用与 locale 一致的语言。",
-    "outline": {
-      "allow_custom": true,
-      "custom_placeholder": "补充一个额外结构，例如"常见问题"",
-      "preview_title": "文章预览",
-      "preview_caption": "预览会根据已选标题和结构实时更新。",
-      "sections": [
-        { "key": "intro", "label": "引言", "default": true },
-        { "key": "search_intent", "label": "搜索意图", "default": true },
-        { "key": "brand_overview", "label_template": "什么是{{brand_name}}", "default": true },
-        { "key": "core_points", "label": "核心要点", "default": false },
-        { "key": "comparison", "label": "对比与替代方案", "default": false },
-        { "key": "faq", "label": "常见问题", "default": false },
-        { "key": "conclusion", "label": "结论", "default": false }
-      ]
-    }
-  }
-}`,
-		},
-	}
+	templates := prompts.PlatformTemplateSeeds()
 
 	for _, t := range templates {
 		_, err = tx.Exec(ctx, `
 			INSERT INTO article_templates (scope, origin_type, template_key, template_name, prompt_template, prompt_visibility, card_config_json, status)
 			VALUES ('platform', 'platform', $1, $2, $3, 'visible', $4::jsonb, 'active')
 			ON CONFLICT DO NOTHING
-		`, t.key, t.name, t.prompt, t.cardConfig)
+		`, t.Key, t.Name, t.PromptTemplate, t.CardConfigJSON)
 		if err != nil {
-			log.Fatalf("insert template %s: %v", t.key, err)
+			log.Fatalf("insert template %s: %v", t.Key, err)
 		}
 
 		_, err = tx.Exec(ctx, `
@@ -551,9 +163,9 @@ func main() {
 			WHERE scope = 'platform'
 			  AND template_key = $1
 			  AND deleted_at IS NULL
-		`, t.key, t.name, t.prompt, t.cardConfig)
+		`, t.Key, t.Name, t.PromptTemplate, t.CardConfigJSON)
 		if err != nil {
-			log.Fatalf("update template %s: %v", t.key, err)
+			log.Fatalf("update template %s: %v", t.Key, err)
 		}
 	}
 
diff --git a/server/configs/config.local.yaml.example b/server/configs/config.local.yaml.example
index 9e22e2c..9316f0f 100644
--- a/server/configs/config.local.yaml.example
+++ b/server/configs/config.local.yaml.example
@@ -15,6 +15,20 @@ database:
 redis:
   addr: localhost:6379
 
+qdrant:
+  url: localhost:6334
+  collection: geo_knowledge_chunks
+  timeout: 15s
+
+object_storage:
+  provider: minio
+  endpoint: localhost:9000
+  bucket: geo-private
+  use_ssl: false
+  # Prefer environment override for secrets:
+  # export OBJECT_STORAGE_ACCESS_KEY=minioadmin
+  # export OBJECT_STORAGE_SECRET_KEY=minioadmin
+
 jwt:
   secret: "your-local-secret"
 
@@ -31,6 +45,23 @@ llm:
   # Prefer environment override for secrets:
   # export LLM_API_KEY=your-api-key
 
+retrieval:
+  provider: siliconflow
+  base_url: https://api.siliconflow.cn/v1
+  embedding_model: BAAI/bge-m3
+  reranker_model: BAAI/bge-reranker-v2-m3
+  timeout: 30s
+  chunk_size: 900
+  chunk_overlap: 120
+  embedding_batch_size: 16
+  recall_limit: 12
+  rerank_top_n: 6
+  max_chunks_per_doc: 6
+  overlap_tokens: 60
+  # Prefer environment override for retrieval api key:
+  # export SILICONFLOW_API_KEY=your-siliconflow-api-key
+  # or export RETRIEVAL_API_KEY=your-retrieval-api-key
+
 generation:
   queue_size: 128
   worker_concurrency: 1
diff --git a/server/configs/config.yaml b/server/configs/config.yaml
index 2f3af9f..4472d75 100644
--- a/server/configs/config.yaml
+++ b/server/configs/config.yaml
@@ -16,6 +16,22 @@ redis:
   addr: localhost:6379
   db: 0
 
+qdrant:
+  url: localhost:6334
+  api_key: ""
+  collection: geo_knowledge_chunks
+  timeout: 15s
+
+object_storage:
+  provider: minio
+  endpoint: localhost:9000
+  access_key: minioadmin
+  secret_key: minioadmin
+  bucket: geo-private
+  use_ssl: false
+  public_base_url: ""
+  region: ""
+
 cache:
   driver: redis
 
@@ -39,6 +55,21 @@ llm:
   reasoning_effort: minimal
   web_search_limit: 3
 
+retrieval:
+  provider: siliconflow
+  base_url: https://api.siliconflow.cn/v1
+  api_key: "sk-dikvcafrdcbajjpfgjjephqcggpdxwxdkighllieijlehwsf"
+  embedding_model: BAAI/bge-m3
+  reranker_model: BAAI/bge-reranker-v2-m3
+  timeout: 30s
+  chunk_size: 900
+  chunk_overlap: 120
+  embedding_batch_size: 16
+  recall_limit: 12
+  rerank_top_n: 6
+  max_chunks_per_doc: 6
+  overlap_tokens: 60
+
 generation:
   queue_size: 128
   worker_concurrency: 1
diff --git a/server/docker-compose.yaml b/server/docker-compose.yaml
index 732129b..1667bd5 100644
--- a/server/docker-compose.yaml
+++ b/server/docker-compose.yaml
@@ -17,5 +17,29 @@ services:
     ports:
       - "6379:6379"
 
+  qdrant:
+    image: qdrant/qdrant:v1.13.2
+    container_name: geo-qdrant
+    ports:
+      - "6333:6333"
+      - "6334:6334"
+    volumes:
+      - qdrant_data:/qdrant/storage
+
+  minio:
+    image: minio/minio:RELEASE.2025-03-12T18-04-18Z
+    container_name: geo-minio
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    volumes:
+      - minio_data:/data
+
 volumes:
   pgdata:
+  qdrant_data:
+  minio_data:
diff --git a/server/go.mod b/server/go.mod
index 50f3f2c..42fa287 100644
--- a/server/go.mod
+++ b/server/go.mod
@@ -1,6 +1,6 @@
 module github.com/geo-platform/tenant-api
 
-go 1.22
+go 1.22.2
 
 require (
 	github.com/alicebob/miniredis/v2 v2.37.0
@@ -8,41 +8,55 @@ require (
 	github.com/golang-jwt/jwt/v5 v5.2.1
 	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.5.5
+	github.com/ledongthuc/pdf v0.0.0-20240314090751-a2a84ec735c3
+	github.com/minio/minio-go/v7 v7.0.83
+	github.com/qdrant/go-client v1.13.0
 	github.com/redis/go-redis/v9 v9.5.1
 	github.com/spf13/viper v1.18.2
 	github.com/stretchr/testify v1.9.0
+	github.com/volcengine/volcengine-go-sdk v1.2.22
+	github.com/xuri/excelize/v2 v2.8.1
 	go.uber.org/zap v1.27.0
-	golang.org/x/crypto v0.21.0
+	golang.org/x/crypto v0.31.0
+	golang.org/x/net v0.33.0
 )
 
 require (
 	github.com/bytedance/sonic v1.9.1 // indirect
-	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.2 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-ini/ini v1.67.0 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.14.0 // indirect
-	github.com/goccy/go-json v0.10.2 // indirect
+	github.com/goccy/go-json v0.10.4 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
 	github.com/jackc/puddle/v2 v2.2.1 // indirect
 	github.com/jmespath/go-jmespath v0.4.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/cpuid/v2 v2.2.4 // indirect
+	github.com/klauspost/compress v1.17.11 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.9 // indirect
 	github.com/leodido/go-urn v1.2.4 // indirect
-	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-isatty v0.0.19 // indirect
+	github.com/minio/md5-simd v1.1.2 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
 	github.com/pelletier/go-toml/v2 v2.1.0 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/richardlehane/mscfb v1.0.4 // indirect
+	github.com/richardlehane/msoleps v1.0.3 // indirect
+	github.com/rs/xid v1.6.0 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
@@ -53,16 +67,18 @@ require (
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.11 // indirect
 	github.com/volcengine/volc-sdk-golang v1.0.23 // indirect
-	github.com/volcengine/volcengine-go-sdk v1.2.22 // indirect
+	github.com/xuri/efp v0.0.0-20231025114914-d1ff6096ae53 // indirect
+	github.com/xuri/nfp v0.0.0-20230919160717-d98342af3f05 // indirect
 	github.com/yuin/gopher-lua v1.1.1 // indirect
 	go.uber.org/multierr v1.10.0 // indirect
 	golang.org/x/arch v0.3.0 // indirect
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
-	golang.org/x/net v0.21.0 // indirect
-	golang.org/x/sync v0.5.0 // indirect
-	golang.org/x/sys v0.18.0 // indirect
-	golang.org/x/text v0.14.0 // indirect
-	google.golang.org/protobuf v1.31.0 // indirect
+	golang.org/x/sync v0.10.0 // indirect
+	golang.org/x/sys v0.28.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20240827150818-7e3bb234dfed // indirect
+	google.golang.org/grpc v1.66.0 // indirect
+	google.golang.org/protobuf v1.34.2 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v2 v2.2.8 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
diff --git a/server/go.sum b/server/go.sum
index e9605bd..1c7c495 100644
--- a/server/go.sum
+++ b/server/go.sum
@@ -11,8 +11,8 @@ github.com/bytedance/sonic v1.5.0/go.mod h1:ED5hyg4y6t3/9Ku1R6dU/4KyJ48DZ4jPhfY1
 github.com/bytedance/sonic v1.9.1 h1:6iJ6NqdoxCDr6mbY8h18oSO+cShGSMRGCEo7F2h0x8s=
 github.com/bytedance/sonic v1.9.1/go.mod h1:i736AoUSYt75HyZLoJW9ERYxcy6eaN6h4BZXU064P/U=
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
-github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
-github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/chenzhuoyu/base64x v0.0.0-20211019084208-fb5309c8db06/go.mod h1:DH46F32mSOjUmXrMHnKwZdA8wcEefY7UVqBKYGjpdQY=
 github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 h1:qSGYFH7+jGhDF8vLC+iwCD4WpbV1EBDSzWkJODFLams=
 github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311/go.mod h1:b583jCggY9gE99b6G5LEC39OIiVsWj+R97kbl5odCEk=
@@ -23,6 +23,8 @@ github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/envoyproxy/go-control-plane v0.9.1-0.20191026205805-5f8ba28d4473/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
 github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
@@ -35,6 +37,8 @@ github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE
 github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
 github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
 github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL7YrpYKXt5YId3A/Tnip5kqbEAP+KLuI3SUcPTeU=
+github.com/go-ini/ini v1.67.0 h1:z6ZrTEZqSWOTyH2FlglNbNgARyHG8oLW9gMELqKr06A=
+github.com/go-ini/ini v1.67.0/go.mod h1:ByCAeIL28uOIIG0E3PJtZPDL8WnHpFKFOtgjp+3Ies8=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
@@ -43,8 +47,8 @@ github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJn
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.14.0 h1:vgvQWe3XCz3gIeFDm/HnTIbj6UGmg/+t63MyGU2n5js=
 github.com/go-playground/validator/v10 v10.14.0/go.mod h1:9iXMNT7sEkjXb0I+enO7QXmzG6QCsPWY4zveKFVRSyU=
-github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
-github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
+github.com/goccy/go-json v0.10.4 h1:JSwxQzIqKfmFX1swYPpUThQZp/Ka4wzJdK0LWVytLPM=
+github.com/goccy/go-json v0.10.4/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk=
 github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
@@ -65,8 +69,8 @@ github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMyw
 github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -83,12 +87,16 @@ github.com/jackc/puddle/v2 v2.2.1 h1:RhxXJtFG022u4ibrCSMSiu5aOq1i77R3OHKNJj77OAk
 github.com/jackc/puddle/v2 v2.2.1/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg=
 github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo=
+github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8=
 github.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/compress v1.17.11 h1:In6xLpyWOi1+C7tXUUWv2ot1QvBjxevKAaI6IXrJmUc=
+github.com/klauspost/compress v1.17.11/go.mod h1:pMDklpSncoRMuLFrf1W9Ss9KT+0rH90U12bZKk7uwG0=
+github.com/klauspost/cpuid/v2 v2.0.1/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
-github.com/klauspost/cpuid/v2 v2.2.4 h1:acbojRNwl3o09bUq+yDCtZFc1aiwaAAxtcn8YkZXnvk=
-github.com/klauspost/cpuid/v2 v2.2.4/go.mod h1:RVVoqg1df56z8g3pUjL/3lE5UfnlrJX8tyFgg4nqhuY=
+github.com/klauspost/cpuid/v2 v2.2.9 h1:66ze0taIn2H33fBvCkXuv9BmCwDfafmiIVpKV9kKGuY=
+github.com/klauspost/cpuid/v2 v2.2.9/go.mod h1:rqkxqrZ1EhYM9G+hXH7YdowN5R5RGN6NK4QwQ3WMXF8=
 github.com/kr/pretty v0.2.0/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
@@ -96,12 +104,18 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/ledongthuc/pdf v0.0.0-20240314090751-a2a84ec735c3 h1:DDPccSesc/SJu8CiCEhHhWjK9C9U1fhrRKB3jRNw4f4=
+github.com/ledongthuc/pdf v0.0.0-20240314090751-a2a84ec735c3/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs=
 github.com/leodido/go-urn v1.2.4 h1:XlAE/cm/ms7TE/VMVoduSpNBoyc2dOxHs5MZSwAN63Q=
 github.com/leodido/go-urn v1.2.4/go.mod h1:7ZrI8mTSeBSHl/UaRyKQW1qZeMgak41ANeCNaVckg+4=
-github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
-github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
+github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mattn/go-isatty v0.0.19 h1:JITubQf0MOLdlGRuRq+jtsDlekdYPia9ZFsB8h/APPA=
 github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/minio/md5-simd v1.1.2 h1:Gdi1DZK69+ZVMoNHRXJyNcxrMA4dSxoYHZSQbirFg34=
+github.com/minio/md5-simd v1.1.2/go.mod h1:MzdKDxYpY2BT9XQFocsiZf/NKVtR7nkE4RoEpN+20RM=
+github.com/minio/minio-go/v7 v7.0.83 h1:W4Kokksvlz3OKf3OqIlzDNKd4MERlC2oN8YptwJ0+GA=
+github.com/minio/minio-go/v7 v7.0.83/go.mod h1:57YXpvc5l3rjPdhqNrDsvVlY0qPI6UTk1bflAe+9doY=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -109,6 +123,8 @@ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw=
+github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8=
 github.com/pelletier/go-toml/v2 v2.1.0 h1:FnwAJ4oYMvbT/34k9zzHuZNrhlz48GB3/s6at6/MHO4=
 github.com/pelletier/go-toml/v2 v2.1.0/go.mod h1:tJU2Z3ZkXwnxa4DPO899bsyIoywizdUvyaeZurnPPDc=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
@@ -116,10 +132,19 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/qdrant/go-client v1.13.0 h1:qeWKCs1vxvfF2MLLFnP2qDG0R8wI18HyAoSfc7wJim8=
+github.com/qdrant/go-client v1.13.0/go.mod h1:iO8ts78jL4x6LDHFOViyYWELVtIBDTjOykBmiOTHLnQ=
 github.com/redis/go-redis/v9 v9.5.1 h1:H1X4D3yHPaYrkL5X06Wh6xNVM/pX0Ft4RV0vMGvLBh8=
 github.com/redis/go-redis/v9 v9.5.1/go.mod h1:hdY0cQFCN4fnSYT6TkisLufl/4W5UIXyv0b/CLO2V2M=
-github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/richardlehane/mscfb v1.0.4 h1:WULscsljNPConisD5hR0+OyZjwK46Pfyr6mPu5ZawpM=
+github.com/richardlehane/mscfb v1.0.4/go.mod h1:YzVpcZg9czvAuhk9T+a3avCpcFPMUWm7gK3DypaEsUk=
+github.com/richardlehane/msoleps v1.0.1/go.mod h1:BWev5JBpU9Ko2WAgmZEuiz4/u3ZYTKbjLycmwiWUfWg=
+github.com/richardlehane/msoleps v1.0.3 h1:aznSZzrwYRl3rLKRT3gUk9am7T/mLNSnJINvN0AQoVM=
+github.com/richardlehane/msoleps v1.0.3/go.mod h1:BWev5JBpU9Ko2WAgmZEuiz4/u3ZYTKbjLycmwiWUfWg=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
+github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
+github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
 github.com/sagikazarmark/locafero v0.4.0 h1:HApY1R9zGo4DBgr7dqsTH/JJxLTTsOt7u6keLGt6kNQ=
 github.com/sagikazarmark/locafero v0.4.0/go.mod h1:Pe1W6UlPYUk/+wc/6KFhbORCfqzgYEpgQ3O5fPuL3H4=
 github.com/sagikazarmark/slog-shim v0.1.0 h1:diDBnUNK9N/354PgrxMywXnAwEr1QZcOr6gto+ugjYE=
@@ -157,6 +182,12 @@ github.com/volcengine/volc-sdk-golang v1.0.23 h1:anOslb2Qp6ywnsbyq9jqR0ljuO63kg9
 github.com/volcengine/volc-sdk-golang v1.0.23/go.mod h1:AfG/PZRUkHJ9inETvbjNifTDgut25Wbkm2QoYBTbvyU=
 github.com/volcengine/volcengine-go-sdk v1.2.22 h1:t6mYCxxUACjBc4QTkvK5buC9fZFAoeCGg126Z//WOVU=
 github.com/volcengine/volcengine-go-sdk v1.2.22/go.mod h1:oxoVo+A17kvkwPkIeIHPVLjSw7EQAm+l/Vau1YGHN+A=
+github.com/xuri/efp v0.0.0-20231025114914-d1ff6096ae53 h1:Chd9DkqERQQuHpXjR/HSV1jLZA6uaoiwwH3vSuF3IW0=
+github.com/xuri/efp v0.0.0-20231025114914-d1ff6096ae53/go.mod h1:ybY/Jr0T0GTCnYjKqmdwxyxn2BQf2RcQIIvex5QldPI=
+github.com/xuri/excelize/v2 v2.8.1 h1:pZLMEwK8ep+CLIUWpWmvW8IWE/yxqG0I1xcN6cVMGuQ=
+github.com/xuri/excelize/v2 v2.8.1/go.mod h1:oli1E4C3Pa5RXg1TBXn4ENCXDV5JUMlBluUhG7c+CEE=
+github.com/xuri/nfp v0.0.0-20230919160717-d98342af3f05 h1:qhbILQo1K3mphbwKh1vNm4oGezE1eF9fQWmNiIpSfI4=
+github.com/xuri/nfp v0.0.0-20230919160717-d98342af3f05/go.mod h1:WwHg+CVyzlv/TX9xqBFXEZAuxOPxn2k1GNHwG41IIUQ=
 github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=
 github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
@@ -169,11 +200,13 @@ golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUu
 golang.org/x/arch v0.3.0 h1:02VY4/ZcO/gBOH6PUaoiptASxtXU10jazRCP865E97k=
 golang.org/x/arch v0.3.0/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.21.0 h1:X31++rzVUdKhX5sWmSOFZxx8UW/ldWx55cbf08iNAMA=
-golang.org/x/crypto v0.21.0/go.mod h1:0BP7YvVV9gBbVKyeTG0Gyn+gZm94bibOW5BjDEYAOMs=
+golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
+golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjsbSXD66ic0XW0js0R9g=
 golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k=
+golang.org/x/image v0.14.0 h1:tNgSxAFe3jC4uYqvZdTr84SZoM1KfwdC9SKIFrLjFn4=
+golang.org/x/image v0.14.0/go.mod h1:HUYqC05R2ZcZ3ejNQsIHQDQiwWM4JBqmm6MKANTp4LE=
 golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
 golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
 golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
@@ -181,23 +214,22 @@ golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73r
 golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
-golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4=
-golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
+golang.org/x/net v0.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I=
+golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.5.0 h1:60k92dhOjHxJkrqnwsfl8KuaHbn/5dl0lUPUklKo3qE=
-golang.org/x/sync v0.5.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
+golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20220704084225-05e143d24a9e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
-golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
+golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
-golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
-golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
+golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
 golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
 golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
@@ -208,9 +240,13 @@ google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7
 google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
 google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc=
 google.golang.org/genproto v0.0.0-20200526211855-cb27e3aa2013/go.mod h1:NbSheEEYHJ7i3ixzK3sjbqSGDJWnxyFXZblF3eUsNvo=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240827150818-7e3bb234dfed h1:J6izYgfBXAI3xTKLgxzTmUltdYaLsuBxFCgDHWJ/eXg=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240827150818-7e3bb234dfed/go.mod h1:UqMtugtsSgubUsoxbuAoiCXvqvErP7Gf0so0mK9tHxU=
 google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
 google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg=
 google.golang.org/grpc v1.27.0/go.mod h1:qbnxyOmOxrQa7FizSgH+ReBfzJrCY1pSN7KXBS8abTk=
+google.golang.org/grpc v1.66.0 h1:DibZuoBznOxbDQxRINckZcUvnCEvrW9pcWIE2yF9r1c=
+google.golang.org/grpc v1.66.0/go.mod h1:s3/l6xSSCURdVfAnL+TqCNMyTDAGN6+lZeVxnZR128Y=
 google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8=
 google.golang.org/protobuf v0.0.0-20200221191635-4d8936d0db64/go.mod h1:kwYJMbMJ01Woi6D6+Kah6886xMZcty6N08ah7+eCXa0=
 google.golang.org/protobuf v0.0.0-20200228230310-ab0ca4ff8a60/go.mod h1:cfTl7dwQJ+fmap5saPgwCLgHXTUD7jkjRqWcaiX5VyM=
@@ -221,8 +257,9 @@ google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2
 google.golang.org/protobuf v1.23.1-0.20200526195155-81db48ad09cc/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
 google.golang.org/protobuf v1.25.0/go.mod h1:9JNX74DMeImyA3h4bdi1ymwjUzf21/xIlbajtzgsN7c=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
-google.golang.org/protobuf v1.31.0 h1:g0LDEJHgrBl9N9r17Ru3sqWhkIx2NB67okBHPwC7hs8=
 google.golang.org/protobuf v1.31.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
+google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
+google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
diff --git a/server/internal/bootstrap/bootstrap.go b/server/internal/bootstrap/bootstrap.go
index 1f54dad..2daae0b 100644
--- a/server/internal/bootstrap/bootstrap.go
+++ b/server/internal/bootstrap/bootstrap.go
@@ -16,10 +16,12 @@ import (
 	"github.com/geo-platform/tenant-api/internal/shared/config"
 	"github.com/geo-platform/tenant-api/internal/shared/llm"
 	"github.com/geo-platform/tenant-api/internal/shared/middleware"
+	"github.com/geo-platform/tenant-api/internal/shared/objectstorage"
 	"github.com/geo-platform/tenant-api/internal/shared/observability"
 	"github.com/geo-platform/tenant-api/internal/shared/repository/postgres"
 	"github.com/geo-platform/tenant-api/internal/shared/repository/redis"
 	"github.com/geo-platform/tenant-api/internal/shared/response"
+	"github.com/geo-platform/tenant-api/internal/shared/retrieval"
 	"github.com/geo-platform/tenant-api/internal/shared/stream"
 )
 
@@ -32,6 +34,9 @@ type App struct {
 	JWT               *auth.Manager
 	Sessions          *auth.SessionStore
 	LLM               llm.Client
+	RetrievalProvider retrieval.Provider
+	VectorStore       retrieval.VectorStore
+	ObjectStorage     objectstorage.Client
 	AuditLogs         *auditlog.AsyncWriter
 	GenerationStreams *stream.GenerationHub
 	Cache             cache.Cache
@@ -64,6 +69,9 @@ func New(configPath string) (*App, error) {
 	jwtMgr := auth.NewManager(cfg.JWT.Secret, cfg.JWT.AccessTTL, cfg.JWT.RefreshTTL)
 	sessions := auth.NewSessionStore(rdb)
 	llmClient := llm.New(cfg.LLM)
+	retrievalProvider := retrieval.NewProvider(cfg.Retrieval, logger)
+	vectorStore := retrieval.NewQdrantStore(cfg.Qdrant, logger)
+	objectStorageClient := objectstorage.New(cfg.ObjectStorage, logger)
 	auditLogs := auditlog.NewAsyncWriter(pool, logger)
 	generationStreams := stream.NewGenerationHub()
 	appCache := cache.New(cfg.Cache.Driver, rdb)
@@ -76,7 +84,6 @@ func New(configPath string) (*App, error) {
 	engine.Use(
 		middleware.Recovery(logger),
 		middleware.RequestID(),
-		middleware.Logger(logger),
 		middleware.CORS(),
 	)
 
@@ -104,6 +111,9 @@ func New(configPath string) (*App, error) {
 		JWT:               jwtMgr,
 		Sessions:          sessions,
 		LLM:               llmClient,
+		RetrievalProvider: retrievalProvider,
+		VectorStore:       vectorStore,
+		ObjectStorage:     objectStorageClient,
 		AuditLogs:         auditLogs,
 		GenerationStreams: generationStreams,
 		Cache:             appCache,
diff --git a/server/internal/shared/config/config.go b/server/internal/shared/config/config.go
index 2e6d875..422bea0 100644
--- a/server/internal/shared/config/config.go
+++ b/server/internal/shared/config/config.go
@@ -10,14 +10,17 @@ import (
 )
 
 type Config struct {
-	Server     ServerConfig     `mapstructure:"server"`
-	Database   DatabaseConfig   `mapstructure:"database"`
-	Redis      RedisConfig      `mapstructure:"redis"`
-	Cache      CacheConfig      `mapstructure:"cache"`
-	JWT        JWTConfig        `mapstructure:"jwt"`
-	Log        LogConfig        `mapstructure:"log"`
-	LLM        LLMConfig        `mapstructure:"llm"`
-	Generation GenerationConfig `mapstructure:"generation"`
+	Server        ServerConfig        `mapstructure:"server"`
+	Database      DatabaseConfig      `mapstructure:"database"`
+	Redis         RedisConfig         `mapstructure:"redis"`
+	Qdrant        QdrantConfig        `mapstructure:"qdrant"`
+	ObjectStorage ObjectStorageConfig `mapstructure:"object_storage"`
+	Cache         CacheConfig         `mapstructure:"cache"`
+	JWT           JWTConfig           `mapstructure:"jwt"`
+	Log           LogConfig           `mapstructure:"log"`
+	LLM           LLMConfig           `mapstructure:"llm"`
+	Retrieval     RetrievalConfig     `mapstructure:"retrieval"`
+	Generation    GenerationConfig    `mapstructure:"generation"`
 }
 
 type ServerConfig struct {
@@ -46,6 +49,24 @@ type RedisConfig struct {
 	DB   int    `mapstructure:"db"`
 }
 
+type QdrantConfig struct {
+	URL        string        `mapstructure:"url"`
+	APIKey     string        `mapstructure:"api_key"`
+	Collection string        `mapstructure:"collection"`
+	Timeout    time.Duration `mapstructure:"timeout"`
+}
+
+type ObjectStorageConfig struct {
+	Provider      string `mapstructure:"provider"`
+	Endpoint      string `mapstructure:"endpoint"`
+	AccessKey     string `mapstructure:"access_key"`
+	SecretKey     string `mapstructure:"secret_key"`
+	Bucket        string `mapstructure:"bucket"`
+	UseSSL        bool   `mapstructure:"use_ssl"`
+	PublicBaseURL string `mapstructure:"public_base_url"`
+	Region        string `mapstructure:"region"`
+}
+
 type JWTConfig struct {
 	Secret     string        `mapstructure:"secret"`
 	AccessTTL  time.Duration `mapstructure:"access_ttl"`
@@ -70,6 +91,22 @@ type LLMConfig struct {
 	WebSearchLimit  int32         `mapstructure:"web_search_limit"`
 }
 
+type RetrievalConfig struct {
+	Provider           string        `mapstructure:"provider"`
+	BaseURL            string        `mapstructure:"base_url"`
+	APIKey             string        `mapstructure:"api_key"`
+	EmbeddingModel     string        `mapstructure:"embedding_model"`
+	RerankerModel      string        `mapstructure:"reranker_model"`
+	Timeout            time.Duration `mapstructure:"timeout"`
+	ChunkSize          int           `mapstructure:"chunk_size"`
+	ChunkOverlap       int           `mapstructure:"chunk_overlap"`
+	EmbeddingBatchSize int           `mapstructure:"embedding_batch_size"`
+	RecallLimit        int           `mapstructure:"recall_limit"`
+	RerankTopN         int           `mapstructure:"rerank_top_n"`
+	MaxChunksPerDoc    int           `mapstructure:"max_chunks_per_doc"`
+	OverlapTokens      int           `mapstructure:"overlap_tokens"`
+}
+
 type CacheConfig struct {
 	Driver string `mapstructure:"driver"` // "redis" or "memory"
 }
@@ -113,6 +150,54 @@ func applyEnvOverrides(cfg *Config) {
 	if apiKey, ok := lookupNonEmptyEnv("LLM_API_KEY"); ok {
 		cfg.LLM.APIKey = apiKey
 	}
+	if apiKey, ok := lookupNonEmptyEnv("QDRANT_API_KEY"); ok {
+		cfg.Qdrant.APIKey = apiKey
+	}
+	if url, ok := lookupNonEmptyEnv("QDRANT_URL"); ok {
+		cfg.Qdrant.URL = url
+	}
+	if collection, ok := lookupNonEmptyEnv("QDRANT_COLLECTION"); ok {
+		cfg.Qdrant.Collection = collection
+	}
+	if endpoint, ok := lookupNonEmptyEnv("OBJECT_STORAGE_ENDPOINT"); ok {
+		cfg.ObjectStorage.Endpoint = endpoint
+	}
+	if accessKey, ok := lookupNonEmptyEnv("OBJECT_STORAGE_ACCESS_KEY"); ok {
+		cfg.ObjectStorage.AccessKey = accessKey
+	}
+	if secretKey, ok := lookupNonEmptyEnv("OBJECT_STORAGE_SECRET_KEY"); ok {
+		cfg.ObjectStorage.SecretKey = secretKey
+	}
+	if bucket, ok := lookupNonEmptyEnv("OBJECT_STORAGE_BUCKET"); ok {
+		cfg.ObjectStorage.Bucket = bucket
+	}
+	if provider, ok := lookupNonEmptyEnv("OBJECT_STORAGE_PROVIDER"); ok {
+		cfg.ObjectStorage.Provider = provider
+	}
+	if publicBaseURL, ok := lookupNonEmptyEnv("OBJECT_STORAGE_PUBLIC_BASE_URL"); ok {
+		cfg.ObjectStorage.PublicBaseURL = publicBaseURL
+	}
+	if apiKey, ok := lookupFirstNonEmptyEnv("SILICONFLOW_API_KEY", "RETRIEVAL_API_KEY", "EMBEDDING_API_KEY", "RERANKER_API_KEY"); ok {
+		cfg.Retrieval.APIKey = apiKey
+	}
+	if baseURL, ok := lookupFirstNonEmptyEnv("SILICONFLOW_BASE_URL", "RETRIEVAL_BASE_URL"); ok {
+		cfg.Retrieval.BaseURL = baseURL
+	}
+	if model, ok := lookupFirstNonEmptyEnv("SILICONFLOW_EMBEDDING_MODEL", "RETRIEVAL_EMBEDDING_MODEL"); ok {
+		cfg.Retrieval.EmbeddingModel = model
+	}
+	if model, ok := lookupFirstNonEmptyEnv("SILICONFLOW_RERANKER_MODEL", "RETRIEVAL_RERANKER_MODEL"); ok {
+		cfg.Retrieval.RerankerModel = model
+	}
+}
+
+func lookupFirstNonEmptyEnv(keys ...string) (string, bool) {
+	for _, key := range keys {
+		if value, ok := lookupNonEmptyEnv(key); ok {
+			return value, true
+		}
+	}
+	return "", false
 }
 
 func lookupNonEmptyEnv(key string) (string, bool) {
diff --git a/server/internal/shared/config/config_test.go b/server/internal/shared/config/config_test.go
index e30cd7e..7ad7f63 100644
--- a/server/internal/shared/config/config_test.go
+++ b/server/internal/shared/config/config_test.go
@@ -44,6 +44,51 @@ llm:
 	}
 }
 
+func TestLoadPrefersEnvRetrievalAndQdrantSettings(t *testing.T) {
+	t.Setenv("SILICONFLOW_API_KEY", "siliconflow-env-key")
+	t.Setenv("SILICONFLOW_EMBEDDING_MODEL", "env-embedding")
+	t.Setenv("SILICONFLOW_RERANKER_MODEL", "env-reranker")
+	t.Setenv("QDRANT_API_KEY", "qdrant-env-key")
+	t.Setenv("QDRANT_URL", "qdrant-env:6334")
+	t.Setenv("QDRANT_COLLECTION", "env_collection")
+
+	configPath := writeTestConfig(t, `
+qdrant:
+  url: qdrant-config:6334
+  api_key: "qdrant-config-key"
+  collection: "config_collection"
+retrieval:
+  provider: siliconflow
+  api_key: "retrieval-config-key"
+  embedding_model: "config-embedding"
+  reranker_model: "config-reranker"
+`)
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+
+	if cfg.Retrieval.APIKey != "siliconflow-env-key" {
+		t.Fatalf("expected env retrieval api key, got %q", cfg.Retrieval.APIKey)
+	}
+	if cfg.Retrieval.EmbeddingModel != "env-embedding" {
+		t.Fatalf("expected env embedding model, got %q", cfg.Retrieval.EmbeddingModel)
+	}
+	if cfg.Retrieval.RerankerModel != "env-reranker" {
+		t.Fatalf("expected env reranker model, got %q", cfg.Retrieval.RerankerModel)
+	}
+	if cfg.Qdrant.APIKey != "qdrant-env-key" {
+		t.Fatalf("expected env qdrant api key, got %q", cfg.Qdrant.APIKey)
+	}
+	if cfg.Qdrant.URL != "qdrant-env:6334" {
+		t.Fatalf("expected env qdrant url, got %q", cfg.Qdrant.URL)
+	}
+	if cfg.Qdrant.Collection != "env_collection" {
+		t.Fatalf("expected env qdrant collection, got %q", cfg.Qdrant.Collection)
+	}
+}
+
 func writeTestConfig(t *testing.T, body string) string {
 	t.Helper()
 
diff --git a/server/internal/shared/middleware/logger.go b/server/internal/shared/middleware/logger.go
index 4a465de..57fe046 100644
--- a/server/internal/shared/middleware/logger.go
+++ b/server/internal/shared/middleware/logger.go
@@ -5,19 +5,43 @@ import (
 
 	"github.com/gin-gonic/gin"
 	"go.uber.org/zap"
+
+	"github.com/geo-platform/tenant-api/internal/shared/response"
 )
 
 func Logger(logger *zap.Logger) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		start := time.Now()
 		c.Next()
-		logger.Info("request",
+
+		fields := []zap.Field{
 			zap.String("method", c.Request.Method),
 			zap.String("path", c.Request.URL.Path),
 			zap.Int("status", c.Writer.Status()),
 			zap.Duration("latency", time.Since(start)),
 			zap.String("request_id", RequestIDFromGin(c)),
 			zap.String("client_ip", c.ClientIP()),
-		)
+		}
+
+		if appErr, ok := response.AppErrorFromGin(c); ok {
+			fields = append(fields,
+				zap.Int("app_code", appErr.Code),
+				zap.String("app_message", appErr.Message),
+			)
+			if appErr.Detail != "" {
+				fields = append(fields, zap.String("app_detail", appErr.Detail))
+			}
+		} else if len(c.Errors) > 0 {
+			fields = append(fields, zap.String("error", c.Errors.String()))
+		}
+
+		switch status := c.Writer.Status(); {
+		case status >= 500:
+			logger.Error("request", fields...)
+		case status >= 400:
+			logger.Warn("request", fields...)
+		default:
+			logger.Info("request", fields...)
+		}
 	}
 }
diff --git a/server/internal/shared/objectstorage/client.go b/server/internal/shared/objectstorage/client.go
new file mode 100644
index 0000000..301e373
--- /dev/null
+++ b/server/internal/shared/objectstorage/client.go
@@ -0,0 +1,56 @@
+package objectstorage
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"go.uber.org/zap"
+
+	"github.com/geo-platform/tenant-api/internal/shared/config"
+)
+
+var ErrNotConfigured = errors.New("object storage is not configured")
+
+type Client interface {
+	Validate() error
+	PutBytes(ctx context.Context, objectKey string, content []byte, contentType string) error
+	GetBytes(ctx context.Context, objectKey string) ([]byte, error)
+	Delete(ctx context.Context, objectKey string) error
+}
+
+func New(cfg config.ObjectStorageConfig, logger *zap.Logger) Client {
+	provider := strings.ToLower(strings.TrimSpace(cfg.Provider))
+	switch provider {
+	case "", "disabled":
+		return disabledClient{reason: "object storage is disabled"}
+	case "minio":
+		return NewMinIOClient(cfg, logger)
+	default:
+		return disabledClient{reason: fmt.Sprintf("unsupported object storage provider %q", cfg.Provider)}
+	}
+}
+
+type disabledClient struct {
+	reason string
+}
+
+func (c disabledClient) Validate() error {
+	if c.reason == "" {
+		c.reason = "missing object storage configuration"
+	}
+	return fmt.Errorf("%w: %s", ErrNotConfigured, c.reason)
+}
+
+func (c disabledClient) PutBytes(context.Context, string, []byte, string) error {
+	return c.Validate()
+}
+
+func (c disabledClient) GetBytes(context.Context, string) ([]byte, error) {
+	return nil, c.Validate()
+}
+
+func (c disabledClient) Delete(context.Context, string) error {
+	return c.Validate()
+}
diff --git a/server/internal/shared/objectstorage/minio.go b/server/internal/shared/objectstorage/minio.go
new file mode 100644
index 0000000..56e85e0
--- /dev/null
+++ b/server/internal/shared/objectstorage/minio.go
@@ -0,0 +1,164 @@
+package objectstorage
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/minio/minio-go/v7"
+	"github.com/minio/minio-go/v7/pkg/credentials"
+	"go.uber.org/zap"
+
+	"github.com/geo-platform/tenant-api/internal/shared/config"
+	"github.com/geo-platform/tenant-api/internal/shared/middleware"
+)
+
+type minioClient struct {
+	client *minio.Client
+	bucket string
+	region string
+	logger *zap.Logger
+}
+
+func NewMinIOClient(cfg config.ObjectStorageConfig, logger *zap.Logger) Client {
+	endpoint := strings.TrimSpace(cfg.Endpoint)
+	accessKey := strings.TrimSpace(cfg.AccessKey)
+	secretKey := strings.TrimSpace(cfg.SecretKey)
+	bucket := strings.TrimSpace(cfg.Bucket)
+	if endpoint == "" || accessKey == "" || secretKey == "" || bucket == "" {
+		return disabledClient{reason: "missing object_storage minio endpoint/access_key/secret_key/bucket"}
+	}
+
+	client, err := minio.New(endpoint, &minio.Options{
+		Creds:  credentials.NewStaticV4(accessKey, secretKey, ""),
+		Secure: cfg.UseSSL,
+		Region: strings.TrimSpace(cfg.Region),
+	})
+	if err != nil {
+		return disabledClient{reason: fmt.Sprintf("init minio client failed: %v", err)}
+	}
+
+	return &minioClient{
+		client: client,
+		bucket: bucket,
+		region: strings.TrimSpace(cfg.Region),
+		logger: logger,
+	}
+}
+
+func (c *minioClient) Validate() error {
+	if c == nil || c.client == nil {
+		return fmt.Errorf("%w: minio client is not initialized", ErrNotConfigured)
+	}
+	if strings.TrimSpace(c.bucket) == "" {
+		return fmt.Errorf("%w: minio bucket is empty", ErrNotConfigured)
+	}
+	return nil
+}
+
+func (c *minioClient) PutBytes(
+	ctx context.Context,
+	objectKey string,
+	content []byte,
+	contentType string,
+) error {
+	if err := c.Validate(); err != nil {
+		return err
+	}
+	if strings.TrimSpace(objectKey) == "" {
+		return fmt.Errorf("object key is required")
+	}
+
+	exists, err := c.client.BucketExists(ctx, c.bucket)
+	if err != nil {
+		c.logError(ctx, "minio bucket exists check failed",
+			zap.String("bucket", c.bucket),
+			zap.String("object_key", objectKey),
+			zap.Error(err),
+		)
+		return fmt.Errorf("check minio bucket: %w", err)
+	}
+	if !exists {
+		if err := c.client.MakeBucket(ctx, c.bucket, minio.MakeBucketOptions{Region: c.region}); err != nil {
+			c.logError(ctx, "minio create bucket failed",
+				zap.String("bucket", c.bucket),
+				zap.String("object_key", objectKey),
+				zap.Error(err),
+			)
+			return fmt.Errorf("create minio bucket: %w", err)
+		}
+	}
+
+	_, err = c.client.PutObject(ctx, c.bucket, objectKey, bytes.NewReader(content), int64(len(content)), minio.PutObjectOptions{
+		ContentType: contentType,
+	})
+	if err != nil {
+		c.logError(ctx, "minio put object failed",
+			zap.String("bucket", c.bucket),
+			zap.String("object_key", objectKey),
+			zap.Int("content_size", len(content)),
+			zap.Error(err),
+		)
+		return fmt.Errorf("put minio object: %w", err)
+	}
+	return nil
+}
+
+func (c *minioClient) GetBytes(ctx context.Context, objectKey string) ([]byte, error) {
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	reader, err := c.client.GetObject(ctx, c.bucket, objectKey, minio.GetObjectOptions{})
+	if err != nil {
+		c.logError(ctx, "minio get object failed",
+			zap.String("bucket", c.bucket),
+			zap.String("object_key", objectKey),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("get minio object: %w", err)
+	}
+	defer reader.Close()
+
+	data, err := io.ReadAll(reader)
+	if err != nil {
+		c.logError(ctx, "minio read object failed",
+			zap.String("bucket", c.bucket),
+			zap.String("object_key", objectKey),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("read minio object: %w", err)
+	}
+	return data, nil
+}
+
+func (c *minioClient) Delete(ctx context.Context, objectKey string) error {
+	if err := c.Validate(); err != nil {
+		return err
+	}
+	if strings.TrimSpace(objectKey) == "" {
+		return nil
+	}
+
+	err := c.client.RemoveObject(ctx, c.bucket, objectKey, minio.RemoveObjectOptions{})
+	if err != nil {
+		c.logError(ctx, "minio delete object failed",
+			zap.String("bucket", c.bucket),
+			zap.String("object_key", objectKey),
+			zap.Error(err),
+		)
+		return fmt.Errorf("delete minio object: %w", err)
+	}
+	return nil
+}
+
+func (c *minioClient) logError(ctx context.Context, msg string, fields ...zap.Field) {
+	if c == nil || c.logger == nil {
+		return
+	}
+	if requestID := middleware.RequestIDFromContext(ctx); requestID != "" {
+		fields = append(fields, zap.String("request_id", requestID))
+	}
+	c.logger.Error(msg, fields...)
+}
diff --git a/server/internal/shared/response/response.go b/server/internal/shared/response/response.go
index 0f62f2e..e77a0fa 100644
--- a/server/internal/shared/response/response.go
+++ b/server/internal/shared/response/response.go
@@ -6,6 +6,8 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+const ginAppErrorKey = "app_error"
+
 type AppError struct {
 	HTTPStatus int    `json:"-"`
 	Code       int    `json:"code"`
@@ -41,6 +43,8 @@ func SuccessWithStatus(c *gin.Context, status int, data interface{}) {
 
 func Error(c *gin.Context, err error) {
 	appErr := Normalize(err)
+	c.Set(ginAppErrorKey, appErr)
+	_ = c.Error(appErr)
 	c.JSON(appErr.HTTPStatus, gin.H{
 		"code":       appErr.Code,
 		"message":    appErr.Message,
@@ -62,6 +66,18 @@ func Normalize(err error) *AppError {
 	}
 }
 
+func AppErrorFromGin(c *gin.Context) (*AppError, bool) {
+	if c == nil {
+		return nil, false
+	}
+	value, ok := c.Get(ginAppErrorKey)
+	if !ok || value == nil {
+		return nil, false
+	}
+	appErr, ok := value.(*AppError)
+	return appErr, ok && appErr != nil
+}
+
 func getRequestID(c *gin.Context) string {
 	if rid, ok := c.Get("request_id"); ok {
 		return rid.(string)
diff --git a/server/internal/shared/retrieval/provider.go b/server/internal/shared/retrieval/provider.go
new file mode 100644
index 0000000..04b77a3
--- /dev/null
+++ b/server/internal/shared/retrieval/provider.go
@@ -0,0 +1,57 @@
+package retrieval
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"go.uber.org/zap"
+
+	"github.com/geo-platform/tenant-api/internal/shared/config"
+)
+
+var ErrNotConfigured = errors.New("retrieval provider is not configured")
+
+type Provider interface {
+	Validate() error
+	Embed(ctx context.Context, inputs []string) ([][]float64, error)
+	Rerank(ctx context.Context, query string, documents []string, topN int) ([]RerankResult, error)
+}
+
+type RerankResult struct {
+	Index          int
+	RelevanceScore float64
+	Text           string
+}
+
+func NewProvider(cfg config.RetrievalConfig, logger *zap.Logger) Provider {
+	provider := strings.ToLower(strings.TrimSpace(cfg.Provider))
+	switch provider {
+	case "", "disabled":
+		return disabledProvider{reason: "retrieval provider is disabled"}
+	case "siliconflow":
+		return NewSiliconFlowProvider(cfg, logger)
+	default:
+		return disabledProvider{reason: fmt.Sprintf("unsupported retrieval provider %q", cfg.Provider)}
+	}
+}
+
+type disabledProvider struct {
+	reason string
+}
+
+func (p disabledProvider) Validate() error {
+	if p.reason == "" {
+		p.reason = "missing retrieval configuration"
+	}
+	return fmt.Errorf("%w: %s", ErrNotConfigured, p.reason)
+}
+
+func (p disabledProvider) Embed(context.Context, []string) ([][]float64, error) {
+	return nil, p.Validate()
+}
+
+func (p disabledProvider) Rerank(context.Context, string, []string, int) ([]RerankResult, error) {
+	return nil, p.Validate()
+}
diff --git a/server/internal/shared/retrieval/qdrant.go b/server/internal/shared/retrieval/qdrant.go
new file mode 100644
index 0000000..8397c29
--- /dev/null
+++ b/server/internal/shared/retrieval/qdrant.go
@@ -0,0 +1,426 @@
+package retrieval
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/url"
+	"strconv"
+	"strings"
+
+	sdk "github.com/qdrant/go-client/qdrant"
+	"go.uber.org/zap"
+
+	"github.com/geo-platform/tenant-api/internal/shared/config"
+	"github.com/geo-platform/tenant-api/internal/shared/middleware"
+)
+
+const (
+	defaultQdrantHost       = "localhost"
+	defaultQdrantGRPCPort   = 6334
+	defaultQdrantCollection = "geo_knowledge_chunks"
+)
+
+type VectorStore interface {
+	Validate() error
+	EnsureCollection(ctx context.Context, vectorSize int) error
+	Upsert(ctx context.Context, points []VectorPoint) error
+	Search(ctx context.Context, req SearchRequest) ([]SearchPoint, error)
+	DeletePoints(ctx context.Context, pointIDs []string) error
+}
+
+type VectorPoint struct {
+	ID      string
+	Vector  []float64
+	Payload map[string]any
+}
+
+type SearchRequest struct {
+	Vector   []float64
+	TenantID int64
+	GroupIDs []int64
+	Limit    int
+}
+
+type SearchPoint struct {
+	ID      string
+	Score   float64
+	Payload map[string]any
+}
+
+type qdrantStore struct {
+	client     *sdk.Client
+	collection string
+	logger     *zap.Logger
+}
+
+type disabledVectorStore struct {
+	reason string
+}
+
+func NewQdrantStore(cfg config.QdrantConfig, logger *zap.Logger) VectorStore {
+	host, port, useTLS, err := parseQdrantEndpoint(cfg.URL)
+	if err != nil {
+		return disabledVectorStore{reason: fmt.Sprintf("invalid qdrant.url: %v", err)}
+	}
+
+	collection := strings.TrimSpace(cfg.Collection)
+	if collection == "" {
+		collection = defaultQdrantCollection
+	}
+
+	client, err := sdk.NewClient(&sdk.Config{
+		Host:                   host,
+		Port:                   port,
+		APIKey:                 strings.TrimSpace(cfg.APIKey),
+		UseTLS:                 useTLS,
+		SkipCompatibilityCheck: true,
+	})
+	if err != nil {
+		return disabledVectorStore{reason: fmt.Sprintf("init qdrant client failed: %v", err)}
+	}
+
+	return &qdrantStore{
+		client:     client,
+		collection: collection,
+		logger:     logger,
+	}
+}
+
+func (s *qdrantStore) Validate() error {
+	if s == nil || s.client == nil {
+		return fmt.Errorf("%w: qdrant client is not initialized", ErrNotConfigured)
+	}
+	if strings.TrimSpace(s.collection) == "" {
+		return fmt.Errorf("%w: qdrant collection is empty", ErrNotConfigured)
+	}
+	return nil
+}
+
+func (s *qdrantStore) EnsureCollection(ctx context.Context, vectorSize int) error {
+	if err := s.Validate(); err != nil {
+		return err
+	}
+	if vectorSize <= 0 {
+		return fmt.Errorf("invalid qdrant vector size %d", vectorSize)
+	}
+
+	exists, err := s.client.CollectionExists(ctx, s.collection)
+	if err != nil {
+		s.logError(ctx, "qdrant collection exists check failed",
+			zap.String("collection", s.collection),
+			zap.Error(err),
+		)
+		return fmt.Errorf("query qdrant collection: %w", err)
+	}
+	if exists {
+		return nil
+	}
+
+	err = s.client.CreateCollection(ctx, &sdk.CreateCollection{
+		CollectionName: s.collection,
+		VectorsConfig: sdk.NewVectorsConfig(&sdk.VectorParams{
+			Size:     uint64(vectorSize),
+			Distance: sdk.Distance_Cosine,
+		}),
+	})
+	if err != nil {
+		s.logError(ctx, "qdrant create collection failed",
+			zap.String("collection", s.collection),
+			zap.Int("vector_size", vectorSize),
+			zap.Error(err),
+		)
+	}
+	return err
+}
+
+func (s *qdrantStore) Upsert(ctx context.Context, points []VectorPoint) error {
+	if err := s.Validate(); err != nil {
+		return err
+	}
+	if len(points) == 0 {
+		return nil
+	}
+
+	converted := make([]*sdk.PointStruct, 0, len(points))
+	for _, point := range points {
+		if strings.TrimSpace(point.ID) == "" || len(point.Vector) == 0 {
+			continue
+		}
+		converted = append(converted, &sdk.PointStruct{
+			Id:      sdk.NewID(point.ID),
+			Vectors: sdk.NewVectors(float64SliceToFloat32(point.Vector)...),
+			Payload: sdk.NewValueMap(point.Payload),
+		})
+	}
+	if len(converted) == 0 {
+		return nil
+	}
+
+	wait := true
+	_, err := s.client.Upsert(ctx, &sdk.UpsertPoints{
+		CollectionName: s.collection,
+		Wait:           &wait,
+		Points:         converted,
+	})
+	if err != nil {
+		s.logError(ctx, "qdrant upsert failed",
+			zap.String("collection", s.collection),
+			zap.Int("point_count", len(converted)),
+			zap.Error(err),
+		)
+		return fmt.Errorf("upsert qdrant points: %w", err)
+	}
+	return nil
+}
+
+func (s *qdrantStore) Search(ctx context.Context, req SearchRequest) ([]SearchPoint, error) {
+	if err := s.Validate(); err != nil {
+		return nil, err
+	}
+	if len(req.Vector) == 0 || req.TenantID <= 0 {
+		return []SearchPoint{}, nil
+	}
+	limit := req.Limit
+	if limit <= 0 {
+		limit = 10
+	}
+	limitValue := uint64(limit)
+
+	filter := &sdk.Filter{
+		Must: []*sdk.Condition{
+			sdk.NewMatchInt("tenant_id", req.TenantID),
+			sdk.NewMatchKeyword("status", "active"),
+		},
+	}
+	groupIDs := normalizeGroupIDs(req.GroupIDs)
+	if len(groupIDs) > 0 {
+		filter.Should = []*sdk.Condition{
+			sdk.NewMatchInts("group_id", groupIDs...),
+		}
+	}
+
+	points, err := s.client.Query(ctx, &sdk.QueryPoints{
+		CollectionName: s.collection,
+		Query:          sdk.NewQueryDense(float64SliceToFloat32(req.Vector)),
+		Filter:         filter,
+		Limit:          &limitValue,
+		WithPayload:    sdk.NewWithPayload(true),
+	})
+	if err != nil {
+		s.logError(ctx, "qdrant search failed",
+			zap.String("collection", s.collection),
+			zap.Int64("tenant_id", req.TenantID),
+			zap.Int("group_count", len(groupIDs)),
+			zap.Int("limit", limit),
+			zap.Error(err),
+		)
+		return nil, fmt.Errorf("query qdrant points: %w", err)
+	}
+
+	results := make([]SearchPoint, 0, len(points))
+	for _, point := range points {
+		if point == nil {
+			continue
+		}
+		results = append(results, SearchPoint{
+			ID:      pointIDToString(point.GetId()),
+			Score:   float64(point.GetScore()),
+			Payload: valueMapToAny(point.GetPayload()),
+		})
+	}
+	return results, nil
+}
+
+func (s *qdrantStore) DeletePoints(ctx context.Context, pointIDs []string) error {
+	if err := s.Validate(); err != nil {
+		return err
+	}
+	if len(pointIDs) == 0 {
+		return nil
+	}
+
+	ids := make([]*sdk.PointId, 0, len(pointIDs))
+	for _, pointID := range pointIDs {
+		pointID = strings.TrimSpace(pointID)
+		if pointID == "" {
+			continue
+		}
+		ids = append(ids, sdk.NewID(pointID))
+	}
+	if len(ids) == 0 {
+		return nil
+	}
+
+	wait := true
+	_, err := s.client.Delete(ctx, &sdk.DeletePoints{
+		CollectionName: s.collection,
+		Wait:           &wait,
+		Points:         sdk.NewPointsSelector(ids...),
+	})
+	if err != nil {
+		s.logError(ctx, "qdrant delete points failed",
+			zap.String("collection", s.collection),
+			zap.Int("point_count", len(ids)),
+			zap.Error(err),
+		)
+		return fmt.Errorf("delete qdrant points: %w", err)
+	}
+	return nil
+}
+
+func (s *qdrantStore) logError(ctx context.Context, msg string, fields ...zap.Field) {
+	if s == nil || s.logger == nil {
+		return
+	}
+	if requestID := middleware.RequestIDFromContext(ctx); requestID != "" {
+		fields = append(fields, zap.String("request_id", requestID))
+	}
+	s.logger.Error(msg, fields...)
+}
+
+func parseQdrantEndpoint(raw string) (string, int, bool, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return defaultQdrantHost, defaultQdrantGRPCPort, false, nil
+	}
+
+	if strings.Contains(value, "://") {
+		parsed, err := url.Parse(value)
+		if err != nil {
+			return "", 0, false, err
+		}
+		port := defaultQdrantGRPCPort
+		if parsed.Port() != "" {
+			port, err = strconv.Atoi(parsed.Port())
+			if err != nil {
+				return "", 0, false, err
+			}
+		}
+		host := parsed.Hostname()
+		if host == "" {
+			host = defaultQdrantHost
+		}
+		return host, port, parsed.Scheme == "https", nil
+	}
+
+	host, portText, err := net.SplitHostPort(value)
+	if err == nil {
+		port, convErr := strconv.Atoi(portText)
+		if convErr != nil {
+			return "", 0, false, convErr
+		}
+		return host, port, false, nil
+	}
+
+	if strings.Contains(err.Error(), "missing port in address") {
+		return value, defaultQdrantGRPCPort, false, nil
+	}
+
+	return "", 0, false, err
+}
+
+func float64SliceToFloat32(values []float64) []float32 {
+	result := make([]float32, 0, len(values))
+	for _, value := range values {
+		result = append(result, float32(value))
+	}
+	return result
+}
+
+func pointIDToString(id *sdk.PointId) string {
+	if id == nil {
+		return ""
+	}
+	if uuid := strings.TrimSpace(id.GetUuid()); uuid != "" {
+		return uuid
+	}
+	if num := id.GetNum(); num > 0 {
+		return strconv.FormatUint(num, 10)
+	}
+	return ""
+}
+
+func valueMapToAny(values map[string]*sdk.Value) map[string]any {
+	if len(values) == 0 {
+		return map[string]any{}
+	}
+	result := make(map[string]any, len(values))
+	for key, value := range values {
+		result[key] = valueToAny(value)
+	}
+	return result
+}
+
+func valueToAny(value *sdk.Value) any {
+	if value == nil {
+		return nil
+	}
+	switch value.GetKind().(type) {
+	case *sdk.Value_StringValue:
+		return value.GetStringValue()
+	case *sdk.Value_IntegerValue:
+		return value.GetIntegerValue()
+	case *sdk.Value_DoubleValue:
+		return value.GetDoubleValue()
+	case *sdk.Value_BoolValue:
+		return value.GetBoolValue()
+	case *sdk.Value_ListValue:
+		list := value.GetListValue()
+		if list == nil {
+			return []any{}
+		}
+		items := make([]any, 0, len(list.GetValues()))
+		for _, item := range list.GetValues() {
+			items = append(items, valueToAny(item))
+		}
+		return items
+	case *sdk.Value_StructValue:
+		structValue := value.GetStructValue()
+		if structValue == nil {
+			return map[string]any{}
+		}
+		return valueMapToAny(structValue.GetFields())
+	default:
+		return nil
+	}
+}
+
+func normalizeGroupIDs(ids []int64) []int64 {
+	result := make([]int64, 0, len(ids))
+	seen := make(map[int64]struct{}, len(ids))
+	for _, id := range ids {
+		if id <= 0 {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		result = append(result, id)
+	}
+	return result
+}
+
+func (s disabledVectorStore) Validate() error {
+	if s.reason == "" {
+		s.reason = "missing qdrant configuration"
+	}
+	return fmt.Errorf("%w: %s", ErrNotConfigured, s.reason)
+}
+
+func (s disabledVectorStore) EnsureCollection(context.Context, int) error {
+	return s.Validate()
+}
+
+func (s disabledVectorStore) Upsert(context.Context, []VectorPoint) error {
+	return s.Validate()
+}
+
+func (s disabledVectorStore) Search(context.Context, SearchRequest) ([]SearchPoint, error) {
+	return nil, s.Validate()
+}
+
+func (s disabledVectorStore) DeletePoints(context.Context, []string) error {
+	return s.Validate()
+}
diff --git a/server/internal/shared/retrieval/siliconflow.go b/server/internal/shared/retrieval/siliconflow.go
new file mode 100644
index 0000000..93af057
--- /dev/null
+++ b/server/internal/shared/retrieval/siliconflow.go
@@ -0,0 +1,312 @@
+package retrieval
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+
+	"github.com/geo-platform/tenant-api/internal/shared/config"
+	"github.com/geo-platform/tenant-api/internal/shared/middleware"
+)
+
+const (
+	defaultSiliconFlowBaseURL        = "https://api.siliconflow.cn/v1"
+	defaultSiliconFlowEmbeddingModel = "BAAI/bge-m3"
+	defaultSiliconFlowRerankerModel  = "BAAI/bge-reranker-v2-m3"
+	defaultSiliconFlowTimeout        = 30 * time.Second
+)
+
+type siliconFlowProvider struct {
+	client          *http.Client
+	logger          *zap.Logger
+	baseURL         string
+	apiKey          string
+	embeddingModel  string
+	rerankerModel   string
+	maxChunksPerDoc int
+	overlapTokens   int
+}
+
+func NewSiliconFlowProvider(cfg config.RetrievalConfig, logger *zap.Logger) Provider {
+	if strings.TrimSpace(cfg.APIKey) == "" {
+		return disabledProvider{reason: "missing retrieval.api_key or SiliconFlow api key env (SILICONFLOW_API_KEY / RETRIEVAL_API_KEY)"}
+	}
+
+	baseURL := strings.TrimSpace(cfg.BaseURL)
+	if baseURL == "" {
+		baseURL = defaultSiliconFlowBaseURL
+	}
+
+	timeout := cfg.Timeout
+	if timeout <= 0 {
+		timeout = defaultSiliconFlowTimeout
+	}
+
+	embeddingModel := strings.TrimSpace(cfg.EmbeddingModel)
+	if embeddingModel == "" {
+		embeddingModel = defaultSiliconFlowEmbeddingModel
+	}
+
+	rerankerModel := strings.TrimSpace(cfg.RerankerModel)
+	if rerankerModel == "" {
+		rerankerModel = defaultSiliconFlowRerankerModel
+	}
+
+	maxChunksPerDoc := cfg.MaxChunksPerDoc
+	if maxChunksPerDoc <= 0 {
+		maxChunksPerDoc = 6
+	}
+
+	overlapTokens := cfg.OverlapTokens
+	if overlapTokens <= 0 {
+		overlapTokens = 60
+	}
+
+	return &siliconFlowProvider{
+		client:          &http.Client{Timeout: timeout},
+		logger:          logger,
+		baseURL:         strings.TrimRight(baseURL, "/"),
+		apiKey:          strings.TrimSpace(cfg.APIKey),
+		embeddingModel:  embeddingModel,
+		rerankerModel:   rerankerModel,
+		maxChunksPerDoc: maxChunksPerDoc,
+		overlapTokens:   overlapTokens,
+	}
+}
+
+func (p *siliconFlowProvider) Validate() error {
+	if p == nil || p.client == nil {
+		return fmt.Errorf("%w: siliconflow client is not initialized", ErrNotConfigured)
+	}
+	if strings.TrimSpace(p.apiKey) == "" {
+		return fmt.Errorf("%w: siliconflow api key is empty", ErrNotConfigured)
+	}
+	return nil
+}
+
+func (p *siliconFlowProvider) Embed(ctx context.Context, inputs []string) ([][]float64, error) {
+	if err := p.Validate(); err != nil {
+		return nil, err
+	}
+	if len(inputs) == 0 {
+		return [][]float64{}, nil
+	}
+
+	type embeddingRequest struct {
+		Model string   `json:"model"`
+		Input []string `json:"input"`
+	}
+	type embeddingItem struct {
+		Embedding []float64 `json:"embedding"`
+		Index     int       `json:"index"`
+	}
+	type embeddingResponse struct {
+		Data  []embeddingItem `json:"data"`
+		Error *struct {
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+
+	payload := embeddingRequest{
+		Model: p.embeddingModel,
+		Input: inputs,
+	}
+
+	var resp embeddingResponse
+	if err := p.doJSON(ctx, http.MethodPost, "/embeddings", payload, &resp); err != nil {
+		return nil, err
+	}
+	if resp.Error != nil && strings.TrimSpace(resp.Error.Message) != "" {
+		return nil, errors.New(resp.Error.Message)
+	}
+
+	vectors := make([][]float64, len(inputs))
+	for _, item := range resp.Data {
+		if item.Index < 0 || item.Index >= len(vectors) {
+			continue
+		}
+		vectors[item.Index] = item.Embedding
+	}
+	for index, vector := range vectors {
+		if len(vector) == 0 {
+			return nil, fmt.Errorf("embedding vector missing at index %d", index)
+		}
+	}
+
+	return vectors, nil
+}
+
+func (p *siliconFlowProvider) Rerank(
+	ctx context.Context,
+	query string,
+	documents []string,
+	topN int,
+) ([]RerankResult, error) {
+	if err := p.Validate(); err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(query) == "" || len(documents) == 0 {
+		return []RerankResult{}, nil
+	}
+	if topN <= 0 || topN > len(documents) {
+		topN = len(documents)
+	}
+
+	type rerankRequest struct {
+		Model           string   `json:"model"`
+		Query           string   `json:"query"`
+		Documents       []string `json:"documents"`
+		TopN            int      `json:"top_n,omitempty"`
+		ReturnDocuments bool     `json:"return_documents"`
+		MaxChunksPerDoc int      `json:"max_chunks_per_doc,omitempty"`
+		OverlapTokens   int      `json:"overlap_tokens,omitempty"`
+	}
+	type rerankResponse struct {
+		Results []struct {
+			Index          int     `json:"index"`
+			RelevanceScore float64 `json:"relevance_score"`
+			Document       struct {
+				Text string `json:"text"`
+			} `json:"document"`
+		} `json:"results"`
+		Error *struct {
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+
+	payload := rerankRequest{
+		Model:           p.rerankerModel,
+		Query:           strings.TrimSpace(query),
+		Documents:       documents,
+		TopN:            topN,
+		ReturnDocuments: true,
+		MaxChunksPerDoc: p.maxChunksPerDoc,
+		OverlapTokens:   p.overlapTokens,
+	}
+
+	var resp rerankResponse
+	if err := p.doJSON(ctx, http.MethodPost, "/rerank", payload, &resp); err != nil {
+		return nil, err
+	}
+	if resp.Error != nil && strings.TrimSpace(resp.Error.Message) != "" {
+		return nil, errors.New(resp.Error.Message)
+	}
+
+	results := make([]RerankResult, 0, len(resp.Results))
+	for _, item := range resp.Results {
+		text := item.Document.Text
+		if text == "" && item.Index >= 0 && item.Index < len(documents) {
+			text = documents[item.Index]
+		}
+		results = append(results, RerankResult{
+			Index:          item.Index,
+			RelevanceScore: item.RelevanceScore,
+			Text:           text,
+		})
+	}
+
+	return results, nil
+}
+
+func (p *siliconFlowProvider) doJSON(
+	ctx context.Context,
+	method, path string,
+	payload any,
+	target any,
+) error {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		p.logError(ctx, "siliconflow marshal request failed",
+			zap.String("method", method),
+			zap.String("path", path),
+			zap.Error(err),
+		)
+		return fmt.Errorf("marshal request: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, p.baseURL+path, bytes.NewReader(body))
+	if err != nil {
+		p.logError(ctx, "siliconflow create request failed",
+			zap.String("method", method),
+			zap.String("url", p.baseURL+path),
+			zap.Error(err),
+		)
+		return fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+p.apiKey)
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := p.client.Do(req)
+	if err != nil {
+		p.logError(ctx, "siliconflow request failed",
+			zap.String("method", method),
+			zap.String("url", req.URL.String()),
+			zap.Error(err),
+		)
+		return fmt.Errorf("request siliconflow: %w", err)
+	}
+	defer resp.Body.Close()
+
+	data, err := io.ReadAll(resp.Body)
+	if err != nil {
+		p.logError(ctx, "siliconflow read response failed",
+			zap.String("method", method),
+			zap.String("url", req.URL.String()),
+			zap.Int("status", resp.StatusCode),
+			zap.Error(err),
+		)
+		return fmt.Errorf("read response body: %w", err)
+	}
+
+	if resp.StatusCode >= http.StatusBadRequest {
+		p.logError(ctx, "siliconflow non-success response",
+			zap.String("method", method),
+			zap.String("url", req.URL.String()),
+			zap.Int("status", resp.StatusCode),
+			zap.String("response_body", truncateForLog(string(data), 512)),
+		)
+		return fmt.Errorf("siliconflow request failed: status=%d body=%s", resp.StatusCode, strings.TrimSpace(string(data)))
+	}
+
+	if target == nil || len(data) == 0 {
+		return nil
+	}
+	if err := json.Unmarshal(data, target); err != nil {
+		p.logError(ctx, "siliconflow decode response failed",
+			zap.String("method", method),
+			zap.String("url", req.URL.String()),
+			zap.Int("status", resp.StatusCode),
+			zap.String("response_body", truncateForLog(string(data), 512)),
+			zap.Error(err),
+		)
+		return fmt.Errorf("decode response: %w", err)
+	}
+
+	return nil
+}
+
+func (p *siliconFlowProvider) logError(ctx context.Context, msg string, fields ...zap.Field) {
+	if p == nil || p.logger == nil {
+		return
+	}
+	if requestID := middleware.RequestIDFromContext(ctx); requestID != "" {
+		fields = append(fields, zap.String("request_id", requestID))
+	}
+	p.logger.Error(msg, fields...)
+}
+
+func truncateForLog(value string, limit int) string {
+	value = strings.TrimSpace(value)
+	if limit <= 0 || len(value) <= limit {
+		return value
+	}
+	return value[:limit] + "...(truncated)"
+}
diff --git a/server/internal/tenant/app/knowledge_parser.go b/server/internal/tenant/app/knowledge_parser.go
new file mode 100644
index 0000000..73181ec
--- /dev/null
+++ b/server/internal/tenant/app/knowledge_parser.go
@@ -0,0 +1,315 @@
+package app
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	pdf "github.com/ledongthuc/pdf"
+	"github.com/xuri/excelize/v2"
+	"golang.org/x/net/html"
+)
+
+const (
+	maxKnowledgeFetchBytes = 5 << 20
+)
+
+var whitespacePattern = regexp.MustCompile(`[ \t]+`)
+
+func extractKnowledgeTextFromURL(ctx context.Context, rawURL string) (string, error) {
+	data, contentType, err := fetchKnowledgeURLSnapshot(ctx, rawURL)
+	if err != nil {
+		return "", err
+	}
+	return extractKnowledgeTextFromSnapshot(resolveSnapshotFileName(rawURL, contentType), data)
+}
+
+func fetchKnowledgeURLSnapshot(ctx context.Context, rawURL string) ([]byte, string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimSpace(rawURL), nil)
+	if err != nil {
+		return nil, "", fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("User-Agent", "geo-knowledge-fetcher/1.0")
+
+	client := &http.Client{Timeout: 20 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, "", fmt.Errorf("fetch url: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= http.StatusBadRequest {
+		return nil, "", fmt.Errorf("fetch url failed: status=%d", resp.StatusCode)
+	}
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, maxKnowledgeFetchBytes))
+	if err != nil {
+		return nil, "", fmt.Errorf("read url body: %w", err)
+	}
+
+	contentType := strings.ToLower(resp.Header.Get("Content-Type"))
+	return data, contentType, nil
+}
+
+func resolveSnapshotFileName(rawURL string, contentType string) string {
+	if strings.Contains(strings.ToLower(contentType), "text/plain") {
+		return rawURL + ".txt"
+	}
+	return rawURL + ".html"
+}
+
+func extractKnowledgeTextFromSnapshot(fileName string, content []byte) (string, error) {
+	ext := strings.ToLower(filepath.Ext(fileName))
+	if ext != ".html" && ext != ".htm" {
+		return extractKnowledgeTextFromFile(fileName, content)
+	}
+
+	doc, err := html.Parse(bytes.NewReader(content))
+	if err != nil {
+		return "", fmt.Errorf("parse html: %w", err)
+	}
+
+	var parts []string
+	var walk func(*html.Node, bool)
+	walk = func(node *html.Node, skip bool) {
+		if node == nil {
+			return
+		}
+
+		nextSkip := skip
+		if node.Type == html.ElementNode {
+			switch strings.ToLower(node.Data) {
+			case "script", "style", "noscript", "svg":
+				nextSkip = true
+			}
+		}
+
+		if node.Type == html.TextNode && !nextSkip {
+			text := strings.TrimSpace(node.Data)
+			if text != "" {
+				parts = append(parts, text)
+			}
+		}
+
+		for child := node.FirstChild; child != nil; child = child.NextSibling {
+			walk(child, nextSkip)
+		}
+	}
+	walk(doc, false)
+
+	return normalizeKnowledgeText(strings.Join(parts, "\n")), nil
+}
+
+func extractKnowledgeTextFromFile(fileName string, content []byte) (string, error) {
+	ext := strings.ToLower(filepath.Ext(fileName))
+
+	switch ext {
+	case ".txt", ".md", ".markdown", ".json", ".csv", ".html", ".htm":
+		if !utf8.Valid(content) {
+			return "", fmt.Errorf("file %s is not valid UTF-8 text", fileName)
+		}
+		return normalizeKnowledgeText(string(content)), nil
+	case ".docx":
+		return extractDOCXText(content)
+	case ".xlsx":
+		return extractXLSXText(content)
+	case ".pdf":
+		return extractPDFText(content)
+	case ".doc", ".xls":
+		return "", fmt.Errorf("file type %s is not supported yet", ext)
+	default:
+		if utf8.Valid(content) {
+			return normalizeKnowledgeText(string(content)), nil
+		}
+		return "", fmt.Errorf("unsupported file type %s", ext)
+	}
+}
+
+func extractDOCXText(content []byte) (string, error) {
+	reader, err := zip.NewReader(bytes.NewReader(content), int64(len(content)))
+	if err != nil {
+		return "", fmt.Errorf("open docx: %w", err)
+	}
+
+	var parts []string
+	for _, file := range reader.File {
+		if file.Name != "word/document.xml" {
+			continue
+		}
+		rc, err := file.Open()
+		if err != nil {
+			return "", fmt.Errorf("open docx entry: %w", err)
+		}
+		data, err := io.ReadAll(rc)
+		rc.Close()
+		if err != nil {
+			return "", fmt.Errorf("read docx entry: %w", err)
+		}
+
+		decoder := xml.NewDecoder(bytes.NewReader(data))
+		for {
+			token, tokenErr := decoder.Token()
+			if tokenErr == io.EOF {
+				break
+			}
+			if tokenErr != nil {
+				return "", fmt.Errorf("decode docx xml: %w", tokenErr)
+			}
+			switch typed := token.(type) {
+			case xml.CharData:
+				text := strings.TrimSpace(string(typed))
+				if text != "" {
+					parts = append(parts, text)
+				}
+			}
+		}
+	}
+	if len(parts) == 0 {
+		return "", fmt.Errorf("docx contains no readable text")
+	}
+	return normalizeKnowledgeText(strings.Join(parts, "\n")), nil
+}
+
+func extractXLSXText(content []byte) (string, error) {
+	book, err := excelize.OpenReader(bytes.NewReader(content))
+	if err != nil {
+		return "", fmt.Errorf("open xlsx: %w", err)
+	}
+	defer func() { _ = book.Close() }()
+
+	lines := make([]string, 0)
+	for _, sheet := range book.GetSheetList() {
+		rows, err := book.GetRows(sheet)
+		if err != nil {
+			return "", fmt.Errorf("read xlsx rows: %w", err)
+		}
+		if len(rows) == 0 {
+			continue
+		}
+		lines = append(lines, sheet)
+		for _, row := range rows {
+			cells := make([]string, 0, len(row))
+			for _, cell := range row {
+				cell = strings.TrimSpace(cell)
+				if cell != "" {
+					cells = append(cells, cell)
+				}
+			}
+			if len(cells) > 0 {
+				lines = append(lines, strings.Join(cells, " | "))
+			}
+		}
+	}
+	if len(lines) == 0 {
+		return "", fmt.Errorf("xlsx contains no readable text")
+	}
+	return normalizeKnowledgeText(strings.Join(lines, "\n")), nil
+}
+
+func extractPDFText(content []byte) (string, error) {
+	reader, err := pdf.NewReader(bytes.NewReader(content), int64(len(content)))
+	if err != nil {
+		return "", fmt.Errorf("open pdf: %w", err)
+	}
+
+	var builder strings.Builder
+	totalPage := reader.NumPage()
+	for pageIndex := 1; pageIndex <= totalPage; pageIndex += 1 {
+		page := reader.Page(pageIndex)
+		if page.V.IsNull() {
+			continue
+		}
+		text, err := page.GetPlainText(nil)
+		if err != nil {
+			return "", fmt.Errorf("extract pdf text: %w", err)
+		}
+		if text != "" {
+			builder.WriteString(text)
+			builder.WriteString("\n")
+		}
+	}
+
+	result := normalizeKnowledgeText(builder.String())
+	if result == "" {
+		return "", fmt.Errorf("pdf contains no readable text")
+	}
+	return result, nil
+}
+
+func normalizeKnowledgeText(input string) string {
+	input = strings.ReplaceAll(input, "\u00a0", " ")
+	lines := strings.Split(input, "\n")
+	cleaned := make([]string, 0, len(lines))
+	for _, line := range lines {
+		line = whitespacePattern.ReplaceAllString(strings.TrimSpace(line), " ")
+		if line != "" {
+			cleaned = append(cleaned, line)
+		}
+	}
+	return strings.TrimSpace(strings.Join(cleaned, "\n"))
+}
+
+func splitKnowledgeTextIntoChunks(text string, chunkSize, chunkOverlap int) []string {
+	text = normalizeKnowledgeText(text)
+	if text == "" {
+		return nil
+	}
+
+	runes := []rune(text)
+	if chunkSize <= 0 {
+		chunkSize = 900
+	}
+	if chunkOverlap < 0 {
+		chunkOverlap = 0
+	}
+	if chunkOverlap >= chunkSize {
+		chunkOverlap = chunkSize / 4
+	}
+
+	chunks := make([]string, 0)
+	for start := 0; start < len(runes); {
+		end := start + chunkSize
+		if end > len(runes) {
+			end = len(runes)
+		}
+
+		if end < len(runes) {
+			for offset := end; offset > start+chunkSize/2; offset -= 1 {
+				if runes[offset-1] == '\n' || runes[offset-1] == '。' || runes[offset-1] == '.' {
+					end = offset
+					break
+				}
+			}
+		}
+
+		chunk := strings.TrimSpace(string(runes[start:end]))
+		if chunk != "" {
+			chunks = append(chunks, chunk)
+		}
+		if end >= len(runes) {
+			break
+		}
+		start = end - chunkOverlap
+		if start < 0 {
+			start = 0
+		}
+	}
+
+	return chunks
+}
+
+func estimateKnowledgeTokenCount(text string) int {
+	if text == "" {
+		return 0
+	}
+	return utf8.RuneCountInString(text)
+}
diff --git a/server/internal/tenant/app/knowledge_service.go b/server/internal/tenant/app/knowledge_service.go
new file mode 100644
index 0000000..f90ab69
--- /dev/null
+++ b/server/internal/tenant/app/knowledge_service.go
@@ -0,0 +1,1893 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/url"
+	"path/filepath"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+	"go.uber.org/zap"
+
+	"github.com/geo-platform/tenant-api/internal/shared/auth"
+	"github.com/geo-platform/tenant-api/internal/shared/config"
+	"github.com/geo-platform/tenant-api/internal/shared/objectstorage"
+	"github.com/geo-platform/tenant-api/internal/shared/response"
+	"github.com/geo-platform/tenant-api/internal/shared/retrieval"
+	"github.com/geo-platform/tenant-api/internal/tenant/prompts"
+)
+
+const (
+	defaultKnowledgeQueueSize   = 128
+	defaultKnowledgeCleanupPoll = 15 * time.Second
+)
+
+type KnowledgeService struct {
+	pool               *pgxpool.Pool
+	provider           retrieval.Provider
+	store              retrieval.VectorStore
+	objectStorage      objectstorage.Client
+	logger             *zap.Logger
+	chunkSize          int
+	chunkOverlap       int
+	embeddingBatchSize int
+	recallLimit        int
+	rerankTopN         int
+	jobs               chan knowledgeParseJob
+	cleanupMu          sync.Mutex
+	cleanupInFlight    map[string]struct{}
+}
+
+type knowledgeParseJob struct {
+	TenantID    int64
+	ItemID      int64
+	ParseTaskID int64
+}
+
+type knowledgeCleanupJob struct {
+	TenantID int64
+	ItemID   int64
+}
+
+type knowledgeItemRecord struct {
+	ID          int64
+	TenantID    int64
+	GroupID     int64
+	GroupName   string
+	Name        string
+	SourceType  string
+	SourceURI   *string
+	StorageKey  string
+	ContentText *string
+	ItemVersion int
+}
+
+type KnowledgeGroupRequest struct {
+	Name      string `json:"name" binding:"required"`
+	ParentID  *int64 `json:"parent_id"`
+	SortOrder *int   `json:"sort_order"`
+}
+
+type KnowledgeGroupResponse struct {
+	ID        int64                    `json:"id"`
+	Name      string                   `json:"name"`
+	ParentID  *int64                   `json:"parent_id"`
+	SortOrder int                      `json:"sort_order"`
+	ItemCount int64                    `json:"item_count"`
+	CreatedAt string                   `json:"created_at"`
+	Children  []KnowledgeGroupResponse `json:"children"`
+}
+
+type KnowledgeItemResponse struct {
+	ID           int64   `json:"id"`
+	GroupID      int64   `json:"group_id"`
+	GroupName    string  `json:"group_name"`
+	Name         string  `json:"name"`
+	SourceType   string  `json:"source_type"`
+	SourceURI    *string `json:"source_uri"`
+	Status       string  `json:"status"`
+	SizeBytes    int64   `json:"size_bytes"`
+	ErrorMessage *string `json:"error_message"`
+	CreatedAt    string  `json:"created_at"`
+	UpdatedAt    string  `json:"updated_at"`
+}
+
+type KnowledgeTextItemRequest struct {
+	GroupID int64  `json:"group_id" binding:"required"`
+	Name    string `json:"name" binding:"required"`
+	Content string `json:"content" binding:"required"`
+}
+
+type KnowledgeURLItemRequest struct {
+	GroupID int64  `json:"group_id" binding:"required"`
+	Name    string `json:"name" binding:"required"`
+	URL     string `json:"url" binding:"required"`
+}
+
+type KnowledgeContext struct {
+	GroupIDs   []int64
+	GroupNames []string
+	Snippets   []KnowledgeSnippet
+}
+
+type KnowledgeSnippet struct {
+	PointID         string
+	GroupID         int64
+	GroupName       string
+	KnowledgeItemID int64
+	ItemName        string
+	Text            string
+	Score           float64
+}
+
+func NewKnowledgeService(
+	pool *pgxpool.Pool,
+	provider retrieval.Provider,
+	store retrieval.VectorStore,
+	objectStorage objectstorage.Client,
+	logger *zap.Logger,
+	cfg config.RetrievalConfig,
+	queueSize int,
+	workerCount int,
+) *KnowledgeService {
+	chunkSize := cfg.ChunkSize
+	if chunkSize <= 0 {
+		chunkSize = 900
+	}
+	chunkOverlap := cfg.ChunkOverlap
+	if chunkOverlap < 0 {
+		chunkOverlap = 120
+	}
+	batchSize := cfg.EmbeddingBatchSize
+	if batchSize <= 0 {
+		batchSize = 16
+	}
+	recallLimit := cfg.RecallLimit
+	if recallLimit <= 0 {
+		recallLimit = 12
+	}
+	rerankTopN := cfg.RerankTopN
+	if rerankTopN <= 0 {
+		rerankTopN = 6
+	}
+
+	svc := &KnowledgeService{
+		pool:               pool,
+		provider:           provider,
+		store:              store,
+		objectStorage:      objectStorage,
+		logger:             logger,
+		chunkSize:          chunkSize,
+		chunkOverlap:       chunkOverlap,
+		embeddingBatchSize: batchSize,
+		recallLimit:        recallLimit,
+		rerankTopN:         rerankTopN,
+		cleanupInFlight:    make(map[string]struct{}),
+	}
+
+	if workerCount > 0 {
+		if queueSize <= 0 {
+			queueSize = defaultKnowledgeQueueSize
+		}
+		svc.jobs = make(chan knowledgeParseJob, queueSize)
+		for i := 0; i < workerCount; i++ {
+			go svc.runParseWorker()
+		}
+		go svc.recoverPendingParseTasks()
+		go svc.runDeletedCleanupWorker()
+	}
+
+	return svc
+}
+
+func (s *KnowledgeService) ListGroups(ctx context.Context) ([]KnowledgeGroupResponse, error) {
+	actor := auth.MustActor(ctx)
+	rows, err := s.pool.Query(ctx, `
+		SELECT id, name, parent_id, sort_order, created_at
+		FROM knowledge_groups
+		WHERE tenant_id = $1 AND deleted_at IS NULL
+		ORDER BY sort_order, created_at, id
+	`, actor.TenantID)
+	if err != nil {
+		return nil, response.ErrInternal(50050, "knowledge_groups_query_failed", "failed to list knowledge groups")
+	}
+	defer rows.Close()
+
+	nodeMap := make(map[int64]*KnowledgeGroupResponse)
+	parentMap := make(map[int64][]int64)
+	orderedIDs := make([]int64, 0)
+	for rows.Next() {
+		node := &KnowledgeGroupResponse{}
+		var createdAt time.Time
+		if err := rows.Scan(&node.ID, &node.Name, &node.ParentID, &node.SortOrder, &createdAt); err != nil {
+			return nil, response.ErrInternal(50050, "knowledge_groups_scan_failed", err.Error())
+		}
+		node.CreatedAt = createdAt.Format(time.RFC3339)
+		node.Children = []KnowledgeGroupResponse{}
+		nodeMap[node.ID] = node
+		orderedIDs = append(orderedIDs, node.ID)
+		if node.ParentID != nil {
+			parentMap[*node.ParentID] = append(parentMap[*node.ParentID], node.ID)
+		}
+	}
+
+	countRows, err := s.pool.Query(ctx, `
+		SELECT group_id, COUNT(*)::bigint
+		FROM knowledge_items
+		WHERE tenant_id = $1 AND deleted_at IS NULL
+		GROUP BY group_id
+	`, actor.TenantID)
+	if err != nil {
+		return nil, response.ErrInternal(50050, "knowledge_group_counts_query_failed", "failed to list knowledge group counts")
+	}
+	defer countRows.Close()
+
+	directCounts := make(map[int64]int64)
+	for countRows.Next() {
+		var groupID, itemCount int64
+		if err := countRows.Scan(&groupID, &itemCount); err != nil {
+			return nil, response.ErrInternal(50050, "knowledge_group_counts_scan_failed", err.Error())
+		}
+		directCounts[groupID] = itemCount
+	}
+
+	var sumCounts func(int64) int64
+	sumCounts = func(groupID int64) int64 {
+		total := directCounts[groupID]
+		for _, childID := range parentMap[groupID] {
+			total += sumCounts(childID)
+		}
+		if node := nodeMap[groupID]; node != nil {
+			node.ItemCount = total
+		}
+		return total
+	}
+
+	var buildTree func(int64) KnowledgeGroupResponse
+	buildTree = func(groupID int64) KnowledgeGroupResponse {
+		node := nodeMap[groupID]
+		if node == nil {
+			return KnowledgeGroupResponse{}
+		}
+		result := *node
+		childIDs := parentMap[groupID]
+		result.Children = make([]KnowledgeGroupResponse, 0, len(childIDs))
+		for _, childID := range childIDs {
+			result.Children = append(result.Children, buildTree(childID))
+		}
+		return result
+	}
+
+	roots := make([]KnowledgeGroupResponse, 0)
+	for _, groupID := range orderedIDs {
+		node := nodeMap[groupID]
+		if node == nil {
+			continue
+		}
+		if node.ParentID == nil {
+			sumCounts(groupID)
+			roots = append(roots, buildTree(groupID))
+		}
+	}
+
+	return roots, nil
+}
+
+func (s *KnowledgeService) CreateGroup(ctx context.Context, req KnowledgeGroupRequest) (*KnowledgeGroupResponse, error) {
+	actor := auth.MustActor(ctx)
+
+	name := strings.TrimSpace(req.Name)
+	if name == "" {
+		return nil, response.ErrBadRequest(40050, "knowledge_group_name_required", "knowledge group name is required")
+	}
+
+	var parentID *int64
+	if req.ParentID != nil && *req.ParentID > 0 {
+		if err := s.ensureRootGroup(ctx, actor.TenantID, *req.ParentID); err != nil {
+			return nil, err
+		}
+		parentID = req.ParentID
+	}
+
+	sortOrder := 0
+	if req.SortOrder != nil {
+		sortOrder = *req.SortOrder
+	}
+
+	var (
+		groupID   int64
+		createdAt time.Time
+	)
+	err := s.pool.QueryRow(ctx, `
+		INSERT INTO knowledge_groups (tenant_id, name, parent_id, sort_order)
+		VALUES ($1, $2, $3, $4)
+		RETURNING id, created_at
+	`, actor.TenantID, name, parentID, sortOrder).Scan(&groupID, &createdAt)
+	if err != nil {
+		return nil, response.ErrConflict(40950, "knowledge_group_create_failed", "knowledge group already exists or cannot be created")
+	}
+
+	return &KnowledgeGroupResponse{
+		ID:        groupID,
+		Name:      name,
+		ParentID:  parentID,
+		SortOrder: sortOrder,
+		ItemCount: 0,
+		CreatedAt: createdAt.Format(time.RFC3339),
+		Children:  []KnowledgeGroupResponse{},
+	}, nil
+}
+
+func (s *KnowledgeService) UpdateGroup(ctx context.Context, groupID int64, req KnowledgeGroupRequest) error {
+	actor := auth.MustActor(ctx)
+
+	name := strings.TrimSpace(req.Name)
+	if name == "" {
+		return response.ErrBadRequest(40050, "knowledge_group_name_required", "knowledge group name is required")
+	}
+
+	sortOrder := 0
+	if req.SortOrder != nil {
+		sortOrder = *req.SortOrder
+	}
+
+	tag, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_groups
+		SET name = $1, sort_order = $2, updated_at = NOW()
+		WHERE id = $3 AND tenant_id = $4 AND deleted_at IS NULL
+	`, name, sortOrder, groupID, actor.TenantID)
+	if err != nil {
+		return response.ErrConflict(40950, "knowledge_group_update_failed", "knowledge group already exists or cannot be updated")
+	}
+	if tag.RowsAffected() == 0 {
+		return response.ErrNotFound(40451, "knowledge_group_not_found", "knowledge group not found")
+	}
+	return nil
+}
+
+func (s *KnowledgeService) DeleteGroup(ctx context.Context, groupID int64) error {
+	actor := auth.MustActor(ctx)
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to begin delete transaction")
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	groupIDs, err := s.listGroupSubtreeIDs(ctx, tx, actor.TenantID, groupID)
+	if err != nil {
+		return err
+	}
+	if len(groupIDs) == 0 {
+		return response.ErrNotFound(40451, "knowledge_group_not_found", "knowledge group not found")
+	}
+
+	itemIDs, err := s.listActiveKnowledgeItemIDs(ctx, tx, actor.TenantID, groupIDs)
+	if err != nil {
+		return err
+	}
+
+	if len(itemIDs) > 0 {
+		if _, err := tx.Exec(ctx, `
+			UPDATE knowledge_items
+			SET deleted_at = NOW(), updated_at = NOW(), status = 'deleted'
+			WHERE tenant_id = $1
+			  AND deleted_at IS NULL
+			  AND id = ANY($2::bigint[])
+		`, actor.TenantID, itemIDs); err != nil {
+			return response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to delete knowledge items")
+		}
+
+		if _, err := tx.Exec(ctx, `
+			UPDATE knowledge_parse_tasks
+			SET status = 'deleted',
+			    error_message = 'knowledge group deleted',
+			    completed_at = COALESCE(completed_at, NOW()),
+			    updated_at = NOW()
+			WHERE tenant_id = $1
+			  AND knowledge_item_id = ANY($2::bigint[])
+			  AND status <> 'deleted'
+		`, actor.TenantID, itemIDs); err != nil {
+			return response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to cancel knowledge parse tasks")
+		}
+
+		if _, err := tx.Exec(ctx, `
+			UPDATE knowledge_chunks_meta
+			SET status = 'deleting', updated_at = NOW()
+			WHERE tenant_id = $1
+			  AND knowledge_item_id = ANY($2::bigint[])
+			  AND status <> 'deleted'
+		`, actor.TenantID, itemIDs); err != nil {
+			return response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to mark knowledge chunks for deletion")
+		}
+	}
+
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM prompt_rule_knowledge_groups
+		WHERE knowledge_group_id = ANY($1::bigint[])
+	`, groupIDs); err != nil {
+		return response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to delete knowledge group references")
+	}
+
+	if _, err := tx.Exec(ctx, `
+		UPDATE knowledge_groups
+		SET deleted_at = NOW(), updated_at = NOW()
+		WHERE tenant_id = $1
+		  AND deleted_at IS NULL
+		  AND id = ANY($2::bigint[])
+	`, actor.TenantID, groupIDs); err != nil {
+		return response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to delete knowledge groups")
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to commit delete transaction")
+	}
+
+	for _, itemID := range itemIDs {
+		go s.cleanupDeletedKnowledgeItemAsync(actor.TenantID, itemID)
+	}
+
+	if s.logger != nil {
+		s.logger.Info("knowledge group soft deleted",
+			zap.Int64("tenant_id", actor.TenantID),
+			zap.Int64("knowledge_group_id", groupID),
+			zap.Int("group_count", len(groupIDs)),
+			zap.Int("item_count", len(itemIDs)),
+		)
+	}
+	return nil
+}
+
+func (s *KnowledgeService) ListItems(ctx context.Context, groupID *int64) ([]KnowledgeItemResponse, error) {
+	actor := auth.MustActor(ctx)
+	if groupID != nil && *groupID > 0 {
+		if err := s.ensureGroupAccessible(ctx, actor.TenantID, *groupID); err != nil {
+			return nil, err
+		}
+	}
+
+	query := `
+		SELECT ki.id, ki.group_id, kg.name, ki.name, ki.source_type, ki.source_uri, ki.status,
+		       ki.size_bytes, ki.error_message, ki.created_at, ki.updated_at
+		FROM knowledge_items ki
+		JOIN knowledge_groups kg ON kg.id = ki.group_id AND kg.deleted_at IS NULL
+		WHERE ki.tenant_id = $1
+		  AND ki.deleted_at IS NULL
+	`
+	args := []any{actor.TenantID}
+	if groupID != nil && *groupID > 0 {
+		query += `
+		  AND ki.group_id IN (
+			  WITH RECURSIVE selected_groups AS (
+				  SELECT id
+				  FROM knowledge_groups
+				  WHERE id = $2 AND tenant_id = $1 AND deleted_at IS NULL
+				  UNION ALL
+				  SELECT child.id
+				  FROM knowledge_groups child
+				  JOIN selected_groups parent ON child.parent_id = parent.id
+				  WHERE child.tenant_id = $1 AND child.deleted_at IS NULL
+			  )
+			  SELECT id FROM selected_groups
+		  )
+		`
+		args = append(args, *groupID)
+	}
+	query += ` ORDER BY ki.created_at DESC, ki.id DESC`
+
+	rows, err := s.pool.Query(ctx, query, args...)
+	if err != nil {
+		return nil, response.ErrInternal(50051, "knowledge_items_query_failed", "failed to list knowledge items")
+	}
+	defer rows.Close()
+
+	items := make([]KnowledgeItemResponse, 0)
+	for rows.Next() {
+		var (
+			item                 KnowledgeItemResponse
+			sourceURI            *string
+			errorMessage         *string
+			createdAt, updatedAt time.Time
+		)
+		if err := rows.Scan(
+			&item.ID,
+			&item.GroupID,
+			&item.GroupName,
+			&item.Name,
+			&item.SourceType,
+			&sourceURI,
+			&item.Status,
+			&item.SizeBytes,
+			&errorMessage,
+			&createdAt,
+			&updatedAt,
+		); err != nil {
+			return nil, response.ErrInternal(50051, "knowledge_items_scan_failed", err.Error())
+		}
+		item.SourceURI = sourceURI
+		item.ErrorMessage = errorMessage
+		item.CreatedAt = createdAt.Format(time.RFC3339)
+		item.UpdatedAt = updatedAt.Format(time.RFC3339)
+		items = append(items, item)
+	}
+
+	return items, nil
+}
+
+func (s *KnowledgeService) CreateTextItem(ctx context.Context, req KnowledgeTextItemRequest) (*KnowledgeItemResponse, error) {
+	actor := auth.MustActor(ctx)
+
+	if err := s.validateIngestionDependencies("text"); err != nil {
+		return nil, err
+	}
+	if err := s.ensureStorableGroup(ctx, actor.TenantID, req.GroupID); err != nil {
+		return nil, err
+	}
+
+	content := normalizeKnowledgeText(req.Content)
+	if content == "" {
+		return nil, response.ErrBadRequest(40051, "knowledge_content_required", "knowledge content is required")
+	}
+
+	return s.queueKnowledgeItem(ctx, actor.TenantID, knowledgeIngestInput{
+		GroupID:     req.GroupID,
+		Name:        strings.TrimSpace(req.Name),
+		SourceType:  "text",
+		ContentText: &content,
+		SizeBytes:   int64(len([]byte(content))),
+	})
+}
+
+func (s *KnowledgeService) CreateURLItem(ctx context.Context, req KnowledgeURLItemRequest) (*KnowledgeItemResponse, error) {
+	actor := auth.MustActor(ctx)
+
+	if err := s.validateIngestionDependencies("website"); err != nil {
+		return nil, err
+	}
+	if err := s.ensureStorableGroup(ctx, actor.TenantID, req.GroupID); err != nil {
+		return nil, err
+	}
+
+	rawURL := strings.TrimSpace(req.URL)
+	parsed, err := url.ParseRequestURI(rawURL)
+	if err != nil {
+		return nil, response.ErrBadRequest(40052, "knowledge_url_invalid", "knowledge url is invalid")
+	}
+
+	snapshot, contentType, err := fetchKnowledgeURLSnapshot(ctx, parsed.String())
+	if err != nil {
+		return nil, response.ErrBadRequest(40052, "knowledge_url_fetch_failed", err.Error())
+	}
+
+	objectKey := buildKnowledgeObjectKey(actor.TenantID, "website", resolveSnapshotFileName(parsed.String(), contentType))
+	if err := s.objectStorage.PutBytes(ctx, objectKey, snapshot, contentType); err != nil {
+		return nil, response.ErrServiceUnavailable(50357, "knowledge_storage_unavailable", err.Error())
+	}
+
+	return s.queueKnowledgeItem(ctx, actor.TenantID, knowledgeIngestInput{
+		GroupID:    req.GroupID,
+		Name:       strings.TrimSpace(req.Name),
+		SourceType: "website",
+		SourceURI:  &rawURL,
+		StorageKey: objectKey,
+		SizeBytes:  int64(len(snapshot)),
+	})
+}
+
+func (s *KnowledgeService) CreateFileItem(
+	ctx context.Context,
+	groupID int64,
+	name string,
+	fileName string,
+	content []byte,
+) (*KnowledgeItemResponse, error) {
+	actor := auth.MustActor(ctx)
+
+	if err := s.validateIngestionDependencies("document"); err != nil {
+		return nil, err
+	}
+	if err := s.ensureStorableGroup(ctx, actor.TenantID, groupID); err != nil {
+		return nil, err
+	}
+
+	displayName := strings.TrimSpace(name)
+	if displayName == "" {
+		displayName = strings.TrimSuffix(filepath.Base(fileName), filepath.Ext(fileName))
+	}
+
+	objectKey := buildKnowledgeObjectKey(actor.TenantID, "document", fileName)
+	if err := s.objectStorage.PutBytes(ctx, objectKey, content, detectKnowledgeContentType(fileName)); err != nil {
+		return nil, response.ErrServiceUnavailable(50357, "knowledge_storage_unavailable", err.Error())
+	}
+
+	return s.queueKnowledgeItem(ctx, actor.TenantID, knowledgeIngestInput{
+		GroupID:    groupID,
+		Name:       displayName,
+		SourceType: "document",
+		StorageKey: objectKey,
+		SizeBytes:  int64(len(content)),
+	})
+}
+
+func (s *KnowledgeService) DeleteItem(ctx context.Context, itemID int64) error {
+	actor := auth.MustActor(ctx)
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return response.ErrInternal(50054, "knowledge_item_delete_failed", "failed to begin delete transaction")
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	tag, err := tx.Exec(ctx, `
+		UPDATE knowledge_items
+		SET deleted_at = NOW(), updated_at = NOW(), status = 'deleted'
+		WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL
+	`, itemID, actor.TenantID)
+	if err != nil {
+		return response.ErrInternal(50054, "knowledge_item_delete_failed", "failed to delete knowledge item")
+	}
+	if tag.RowsAffected() == 0 {
+		return response.ErrNotFound(40450, "knowledge_item_not_found", "knowledge item not found")
+	}
+
+	if _, err := tx.Exec(ctx, `
+		UPDATE knowledge_parse_tasks
+		SET status = 'deleted',
+		    error_message = 'knowledge item deleted',
+		    completed_at = COALESCE(completed_at, NOW()),
+		    updated_at = NOW()
+		WHERE knowledge_item_id = $1
+		  AND tenant_id = $2
+		  AND status IN ('pending', 'running')
+	`, itemID, actor.TenantID); err != nil {
+		return response.ErrInternal(50054, "knowledge_item_delete_failed", "failed to cancel knowledge parse task")
+	}
+
+	if _, err := tx.Exec(ctx, `
+		UPDATE knowledge_chunks_meta
+		SET status = 'deleting', updated_at = NOW()
+		WHERE knowledge_item_id = $1 AND tenant_id = $2 AND status <> 'deleted'
+	`, itemID, actor.TenantID); err != nil {
+		return response.ErrInternal(50054, "knowledge_item_delete_failed", "failed to mark knowledge chunks for deletion")
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return response.ErrInternal(50054, "knowledge_item_delete_failed", "failed to commit delete transaction")
+	}
+
+	if s.logger != nil {
+		s.logger.Info("knowledge item soft deleted",
+			zap.Int64("tenant_id", actor.TenantID),
+			zap.Int64("knowledge_item_id", itemID),
+		)
+	}
+	go s.cleanupDeletedKnowledgeItemAsync(actor.TenantID, itemID)
+	return nil
+}
+
+func (s *KnowledgeService) ResolveContext(
+	ctx context.Context,
+	tenantID int64,
+	groupIDs []int64,
+	query string,
+) (*KnowledgeContext, error) {
+	groupIDs = normalizeInt64IDs(groupIDs)
+	if len(groupIDs) == 0 {
+		return nil, nil
+	}
+	if strings.TrimSpace(query) == "" {
+		return nil, nil
+	}
+	if err := s.provider.Validate(); err != nil {
+		return nil, response.ErrServiceUnavailable(50351, "retrieval_unavailable", err.Error())
+	}
+	if err := s.store.Validate(); err != nil {
+		return nil, response.ErrServiceUnavailable(50352, "qdrant_unavailable", err.Error())
+	}
+
+	groupNames, err := s.listGroupNames(ctx, tenantID, groupIDs)
+	if err != nil {
+		return nil, err
+	}
+	if len(groupNames) == 0 {
+		return nil, nil
+	}
+
+	vectors, err := s.provider.Embed(ctx, []string{query})
+	if err != nil {
+		return nil, response.ErrServiceUnavailable(50353, "embedding_failed", err.Error())
+	}
+	if len(vectors) == 0 || len(vectors[0]) == 0 {
+		return nil, response.ErrServiceUnavailable(50353, "embedding_failed", "embedding vector is empty")
+	}
+
+	searchPoints, err := s.store.Search(ctx, retrieval.SearchRequest{
+		Vector:   vectors[0],
+		TenantID: tenantID,
+		GroupIDs: groupIDs,
+		Limit:    s.recallLimit,
+	})
+	if err != nil {
+		return nil, response.ErrServiceUnavailable(50354, "qdrant_search_failed", err.Error())
+	}
+	if len(searchPoints) == 0 {
+		return &KnowledgeContext{GroupIDs: groupIDs, GroupNames: groupNames, Snippets: []KnowledgeSnippet{}}, nil
+	}
+
+	candidates := make([]KnowledgeSnippet, 0, len(searchPoints))
+	documents := make([]string, 0, len(searchPoints))
+	for _, point := range searchPoints {
+		text := strings.TrimSpace(anyString(point.Payload["text"]))
+		if text == "" {
+			continue
+		}
+		candidates = append(candidates, KnowledgeSnippet{
+			PointID:         point.ID,
+			GroupID:         anyInt64(point.Payload["group_id"]),
+			GroupName:       strings.TrimSpace(anyString(point.Payload["group_name"])),
+			KnowledgeItemID: anyInt64(point.Payload["item_id"]),
+			ItemName:        strings.TrimSpace(anyString(point.Payload["item_name"])),
+			Text:            text,
+			Score:           point.Score,
+		})
+		documents = append(documents, text)
+	}
+	if len(candidates) == 0 {
+		return &KnowledgeContext{GroupIDs: groupIDs, GroupNames: groupNames, Snippets: []KnowledgeSnippet{}}, nil
+	}
+
+	candidates, err = s.filterActiveKnowledgeSnippets(ctx, tenantID, candidates)
+	if err != nil {
+		return nil, err
+	}
+	if len(candidates) == 0 {
+		return &KnowledgeContext{GroupIDs: groupIDs, GroupNames: groupNames, Snippets: []KnowledgeSnippet{}}, nil
+	}
+
+	documents = documents[:0]
+	for _, candidate := range candidates {
+		documents = append(documents, candidate.Text)
+	}
+
+	reranked, err := s.provider.Rerank(ctx, query, documents, minInt(s.rerankTopN, len(documents)))
+	if err != nil {
+		selected := candidates[:minInt(len(candidates), s.rerankTopN)]
+		return &KnowledgeContext{GroupIDs: groupIDs, GroupNames: groupNames, Snippets: selected}, nil
+	}
+
+	selected := make([]KnowledgeSnippet, 0, len(reranked))
+	for _, item := range reranked {
+		if item.Index < 0 || item.Index >= len(candidates) {
+			continue
+		}
+		snippet := candidates[item.Index]
+		snippet.Score = item.RelevanceScore
+		if strings.TrimSpace(item.Text) != "" {
+			snippet.Text = strings.TrimSpace(item.Text)
+		}
+		selected = append(selected, snippet)
+	}
+
+	return &KnowledgeContext{
+		GroupIDs:   groupIDs,
+		GroupNames: groupNames,
+		Snippets:   selected,
+	}, nil
+}
+
+func (s *KnowledgeService) RenderPromptSection(ctx *KnowledgeContext) string {
+	if ctx == nil || len(ctx.Snippets) == 0 {
+		return ""
+	}
+
+	lines := prompts.KnowledgePromptIntroLines()
+	for index, snippet := range ctx.Snippets {
+		label := strings.TrimSpace(snippet.ItemName)
+		if label == "" {
+			label = prompts.KnowledgeSnippetLabel(index)
+		}
+		groupName := strings.TrimSpace(snippet.GroupName)
+		if groupName != "" {
+			label = fmt.Sprintf("%s / %s", groupName, label)
+		}
+		lines = append(lines, fmt.Sprintf("%d. %s\n%s", index+1, label, snippet.Text))
+	}
+	return strings.Join(lines, "\n")
+}
+
+type knowledgeIngestInput struct {
+	GroupID     int64
+	Name        string
+	SourceType  string
+	SourceURI   *string
+	StorageKey  string
+	ContentText *string
+	SizeBytes   int64
+}
+
+func (s *KnowledgeService) validateIngestionDependencies(sourceType string) error {
+	if err := s.provider.Validate(); err != nil {
+		return response.ErrServiceUnavailable(50351, "retrieval_unavailable", err.Error())
+	}
+	if err := s.store.Validate(); err != nil {
+		return response.ErrServiceUnavailable(50352, "qdrant_unavailable", err.Error())
+	}
+	if sourceType == "document" || sourceType == "website" {
+		if err := s.objectStorage.Validate(); err != nil {
+			return response.ErrServiceUnavailable(50357, "knowledge_storage_unavailable", err.Error())
+		}
+	}
+	return nil
+}
+
+func (s *KnowledgeService) queueKnowledgeItem(
+	ctx context.Context,
+	tenantID int64,
+	input knowledgeIngestInput,
+) (*KnowledgeItemResponse, error) {
+	if err := s.ensureStorableGroup(ctx, tenantID, input.GroupID); err != nil {
+		return nil, err
+	}
+
+	input.Name = strings.TrimSpace(input.Name)
+	if input.Name == "" {
+		return nil, response.ErrBadRequest(40054, "knowledge_name_required", "knowledge item name is required")
+	}
+
+	if input.ContentText != nil {
+		contentText := normalizeKnowledgeText(*input.ContentText)
+		if contentText == "" {
+			return nil, response.ErrBadRequest(40051, "knowledge_content_required", "knowledge content is required")
+		}
+		input.ContentText = &contentText
+	}
+
+	itemID, parseTaskID, err := s.createPendingKnowledgeItem(ctx, tenantID, input)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := s.enqueueParseJob(knowledgeParseJob{
+		TenantID:    tenantID,
+		ItemID:      itemID,
+		ParseTaskID: parseTaskID,
+	}); err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), tenantID, itemID, parseTaskID, err)
+		return nil, response.ErrServiceUnavailable(50356, "knowledge_queue_unavailable", "knowledge parse queue is busy, please retry")
+	}
+
+	items, err := s.listKnowledgeItemsByIDs(ctx, tenantID, []int64{itemID})
+	if err != nil {
+		return nil, err
+	}
+	if len(items) == 0 {
+		return nil, response.ErrInternal(50055, "knowledge_item_create_failed", "knowledge item was not found after creation")
+	}
+	return &items[0], nil
+}
+
+func (s *KnowledgeService) enqueueParseJob(job knowledgeParseJob) error {
+	if s.jobs == nil {
+		return fmt.Errorf("knowledge parse workers are not enabled")
+	}
+
+	select {
+	case s.jobs <- job:
+		return nil
+	default:
+		return fmt.Errorf("knowledge parse queue is full")
+	}
+}
+
+func (s *KnowledgeService) runParseWorker() {
+	for job := range s.jobs {
+		s.executeParseJob(context.Background(), job)
+	}
+}
+
+func (s *KnowledgeService) recoverPendingParseTasks() {
+	if s.jobs == nil {
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT kpt.tenant_id, kpt.knowledge_item_id, kpt.id
+		FROM knowledge_parse_tasks kpt
+		JOIN knowledge_items ki ON ki.id = kpt.knowledge_item_id
+		WHERE kpt.status IN ('pending', 'running')
+		  AND ki.deleted_at IS NULL
+		  AND ki.status IN ('pending', 'processing')
+		ORDER BY kpt.created_at ASC, kpt.id ASC
+	`)
+	if err != nil {
+		return
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var job knowledgeParseJob
+		if scanErr := rows.Scan(&job.TenantID, &job.ItemID, &job.ParseTaskID); scanErr != nil {
+			continue
+		}
+		if err := s.enqueueParseJob(job); err != nil {
+			return
+		}
+	}
+}
+
+func (s *KnowledgeService) executeParseJob(ctx context.Context, job knowledgeParseJob) {
+	item, err := s.loadKnowledgeItemForParse(ctx, job.TenantID, job.ItemID)
+	if err != nil || item == nil {
+		return
+	}
+
+	if err := s.markKnowledgeIngestionRunning(ctx, job.TenantID, job.ItemID, job.ParseTaskID); err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+
+	content, err := s.readKnowledgeItemContent(ctx, item)
+	if err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+
+	chunks := splitKnowledgeTextIntoChunks(content, s.chunkSize, s.chunkOverlap)
+	if len(chunks) == 0 {
+		err = errors.New("knowledge content is empty after parsing")
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+
+	pointIDs, err := s.listKnowledgePointIDs(ctx, job.TenantID, job.ItemID)
+	if err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+	if len(pointIDs) > 0 {
+		if err := s.store.DeletePoints(ctx, pointIDs); err != nil {
+			_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+			return
+		}
+	}
+
+	embeddings, err := s.embedChunks(ctx, chunks)
+	if err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+	if len(embeddings) == 0 || len(embeddings[0]) == 0 {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, errors.New("embedding vector is empty"))
+		return
+	}
+
+	if err := s.store.EnsureCollection(ctx, len(embeddings[0])); err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+
+	insertedPointIDs := make([]string, 0, len(chunks))
+	defer func() {
+		if err != nil && len(insertedPointIDs) > 0 {
+			_ = s.store.DeletePoints(context.Background(), insertedPointIDs)
+		}
+	}()
+
+	points := make([]retrieval.VectorPoint, 0, len(chunks))
+	metas := make([]knowledgeChunkMetaInput, 0, len(chunks))
+	for index, chunk := range chunks {
+		pointID := uuid.NewString()
+		insertedPointIDs = append(insertedPointIDs, pointID)
+		points = append(points, retrieval.VectorPoint{
+			ID:     pointID,
+			Vector: embeddings[index],
+			Payload: map[string]any{
+				"tenant_id":    job.TenantID,
+				"group_id":     item.GroupID,
+				"group_name":   item.GroupName,
+				"item_id":      item.ID,
+				"item_name":    item.Name,
+				"chunk_index":  index,
+				"item_version": item.ItemVersion,
+				"status":       "active",
+				"source_type":  item.SourceType,
+				"text":         chunk,
+			},
+		})
+		metas = append(metas, knowledgeChunkMetaInput{
+			ChunkIndex:    index,
+			TokenCount:    estimateKnowledgeTokenCount(chunk),
+			QdrantPointID: pointID,
+			ItemVersion:   item.ItemVersion,
+			Status:        "active",
+		})
+	}
+
+	if err = s.store.Upsert(ctx, points); err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+
+	if err = s.markKnowledgeIngestionCompleted(ctx, job.TenantID, job.ItemID, job.ParseTaskID, metas); err != nil {
+		_ = s.markKnowledgeIngestionFailed(context.Background(), job.TenantID, job.ItemID, job.ParseTaskID, err)
+		return
+	}
+}
+
+func (s *KnowledgeService) loadKnowledgeItemForParse(
+	ctx context.Context,
+	tenantID, itemID int64,
+) (*knowledgeItemRecord, error) {
+	record := &knowledgeItemRecord{}
+	var contentText *string
+	err := s.pool.QueryRow(ctx, `
+		SELECT ki.id, ki.tenant_id, ki.group_id, kg.name, ki.name, ki.source_type,
+		       ki.source_uri, ki.storage_key, ki.content_text, ki.item_version
+		FROM knowledge_items ki
+		JOIN knowledge_groups kg ON kg.id = ki.group_id
+		WHERE ki.id = $1 AND ki.tenant_id = $2 AND ki.deleted_at IS NULL
+	`, itemID, tenantID).Scan(
+		&record.ID,
+		&record.TenantID,
+		&record.GroupID,
+		&record.GroupName,
+		&record.Name,
+		&record.SourceType,
+		&record.SourceURI,
+		&record.StorageKey,
+		&contentText,
+		&record.ItemVersion,
+	)
+	if err != nil {
+		return nil, nil
+	}
+	record.ContentText = contentText
+	return record, nil
+}
+
+func (s *KnowledgeService) readKnowledgeItemContent(ctx context.Context, item *knowledgeItemRecord) (string, error) {
+	if item == nil {
+		return "", fmt.Errorf("knowledge item is empty")
+	}
+
+	switch item.SourceType {
+	case "text":
+		return normalizeKnowledgeText(derefKnowledgeString(item.ContentText)), nil
+	case "document":
+		data, err := s.objectStorage.GetBytes(ctx, item.StorageKey)
+		if err != nil {
+			return "", err
+		}
+		return extractKnowledgeTextFromFile(item.StorageKey, data)
+	case "website":
+		data, err := s.objectStorage.GetBytes(ctx, item.StorageKey)
+		if err != nil {
+			return "", err
+		}
+		return extractKnowledgeTextFromSnapshot(item.StorageKey, data)
+	default:
+		return "", fmt.Errorf("unsupported knowledge source type %q", item.SourceType)
+	}
+}
+
+type knowledgeChunkMetaInput struct {
+	ChunkIndex    int
+	TokenCount    int
+	QdrantPointID string
+	ItemVersion   int
+	Status        string
+}
+
+func (s *KnowledgeService) createPendingKnowledgeItem(
+	ctx context.Context,
+	tenantID int64,
+	input knowledgeIngestInput,
+) (int64, int64, error) {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return 0, 0, response.ErrInternal(50055, "knowledge_item_create_failed", "failed to begin knowledge transaction")
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	var itemID int64
+	err = tx.QueryRow(ctx, `
+		INSERT INTO knowledge_items (
+			tenant_id, group_id, source_type, name, source_uri, storage_key,
+			content_text, status, size_bytes, item_version
+		)
+		VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending', $8, 1)
+		RETURNING id
+	`, tenantID, input.GroupID, input.SourceType, input.Name, input.SourceURI, input.StorageKey, input.ContentText, input.SizeBytes).Scan(&itemID)
+	if err != nil {
+		return 0, 0, response.ErrConflict(40951, "knowledge_item_create_failed", "failed to create knowledge item")
+	}
+
+	var taskID int64
+	err = tx.QueryRow(ctx, `
+		INSERT INTO knowledge_parse_tasks (
+			tenant_id, knowledge_item_id, source_type, status
+		)
+		VALUES ($1, $2, $3, 'pending')
+		RETURNING id
+	`, tenantID, itemID, input.SourceType).Scan(&taskID)
+	if err != nil {
+		return 0, 0, response.ErrInternal(50055, "knowledge_item_create_failed", "failed to create knowledge parse task")
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return 0, 0, response.ErrInternal(50055, "knowledge_item_create_failed", "failed to commit knowledge transaction")
+	}
+	return itemID, taskID, nil
+}
+
+func (s *KnowledgeService) markKnowledgeIngestionRunning(
+	ctx context.Context,
+	tenantID, itemID, parseTaskID int64,
+) error {
+	if _, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_items
+		SET status = 'processing', error_message = NULL, updated_at = NOW()
+		WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL
+	`, itemID, tenantID); err != nil {
+		return err
+	}
+
+	if _, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_parse_tasks
+		SET status = 'running',
+		    error_message = NULL,
+		    started_at = COALESCE(started_at, NOW()),
+		    updated_at = NOW()
+		WHERE id = $1 AND tenant_id = $2
+	`, parseTaskID, tenantID); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func (s *KnowledgeService) markKnowledgeIngestionCompleted(
+	ctx context.Context,
+	tenantID, itemID, parseTaskID int64,
+	metas []knowledgeChunkMetaInput,
+) error {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM knowledge_chunks_meta
+		WHERE tenant_id = $1 AND knowledge_item_id = $2
+	`, tenantID, itemID); err != nil {
+		return err
+	}
+
+	for _, meta := range metas {
+		if _, err := tx.Exec(ctx, `
+			INSERT INTO knowledge_chunks_meta (
+				tenant_id, knowledge_item_id, chunk_index, token_count,
+				qdrant_point_id, item_version, status
+			)
+			VALUES ($1, $2, $3, $4, $5, $6, $7)
+		`, tenantID, itemID, meta.ChunkIndex, meta.TokenCount, meta.QdrantPointID, meta.ItemVersion, meta.Status); err != nil {
+			return err
+		}
+	}
+
+	if _, err := tx.Exec(ctx, `
+		UPDATE knowledge_items
+		SET status = 'completed', error_message = NULL, updated_at = NOW()
+		WHERE id = $1 AND tenant_id = $2
+	`, itemID, tenantID); err != nil {
+		return err
+	}
+
+	if _, err := tx.Exec(ctx, `
+		UPDATE knowledge_parse_tasks
+		SET status = 'completed', error_message = NULL, completed_at = NOW(), updated_at = NOW()
+		WHERE id = $1 AND tenant_id = $2
+	`, parseTaskID, tenantID); err != nil {
+		return err
+	}
+
+	return tx.Commit(ctx)
+}
+
+func (s *KnowledgeService) markKnowledgeIngestionFailed(
+	ctx context.Context,
+	tenantID, itemID, parseTaskID int64,
+	cause error,
+) error {
+	errMessage := "knowledge ingestion failed"
+	if cause != nil {
+		errMessage = strings.TrimSpace(cause.Error())
+	}
+
+	if s.logger != nil {
+		s.logger.Error("knowledge parse failed",
+			zap.Int64("tenant_id", tenantID),
+			zap.Int64("knowledge_item_id", itemID),
+			zap.Int64("parse_task_id", parseTaskID),
+			zap.String("error_message", errMessage),
+		)
+	}
+
+	_, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_items
+		SET status = 'failed', error_message = $1, updated_at = NOW()
+		WHERE id = $2 AND tenant_id = $3
+	`, errMessage, itemID, tenantID)
+	if err != nil {
+		return err
+	}
+
+	_, err = s.pool.Exec(ctx, `
+		UPDATE knowledge_parse_tasks
+		SET status = 'failed', error_message = $1, completed_at = NOW(), updated_at = NOW()
+		WHERE id = $2 AND tenant_id = $3
+	`, errMessage, parseTaskID, tenantID)
+	return err
+}
+
+func buildKnowledgeObjectKey(tenantID int64, sourceType, fileName string) string {
+	fileName = sanitizeKnowledgeFileName(fileName)
+	if fileName == "" {
+		fileName = sourceType + ".bin"
+	}
+	return fmt.Sprintf(
+		"knowledge/%d/%s/%s/%s-%s",
+		tenantID,
+		sourceType,
+		time.Now().UTC().Format("2006/01/02"),
+		uuid.NewString(),
+		fileName,
+	)
+}
+
+func sanitizeKnowledgeFileName(fileName string) string {
+	fileName = filepath.Base(strings.TrimSpace(fileName))
+	replacer := strings.NewReplacer(
+		"/", "-",
+		"\\", "-",
+		":", "-",
+		"?", "-",
+		"&", "-",
+		"=", "-",
+		"#", "-",
+	)
+	return replacer.Replace(fileName)
+}
+
+func detectKnowledgeContentType(fileName string) string {
+	switch strings.ToLower(filepath.Ext(fileName)) {
+	case ".txt", ".md", ".markdown":
+		return "text/plain; charset=utf-8"
+	case ".html", ".htm":
+		return "text/html; charset=utf-8"
+	case ".pdf":
+		return "application/pdf"
+	case ".docx":
+		return "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+	case ".xlsx":
+		return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+	case ".json":
+		return "application/json"
+	case ".csv":
+		return "text/csv; charset=utf-8"
+	default:
+		return "application/octet-stream"
+	}
+}
+
+func derefKnowledgeString(value *string) string {
+	if value == nil {
+		return ""
+	}
+	return strings.TrimSpace(*value)
+}
+
+func (s *KnowledgeService) ensureGroupAccessible(ctx context.Context, tenantID, groupID int64) error {
+	var exists bool
+	err := s.pool.QueryRow(ctx, `
+		SELECT EXISTS(
+			SELECT 1
+			FROM knowledge_groups
+			WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL
+		)
+	`, groupID, tenantID).Scan(&exists)
+	if err != nil {
+		return response.ErrInternal(50050, "knowledge_group_query_failed", "failed to query knowledge group")
+	}
+	if !exists {
+		return response.ErrNotFound(40451, "knowledge_group_not_found", "knowledge group not found")
+	}
+	return nil
+}
+
+func (s *KnowledgeService) ensureRootGroup(ctx context.Context, tenantID, groupID int64) error {
+	if err := s.ensureGroupAccessible(ctx, tenantID, groupID); err != nil {
+		return err
+	}
+
+	var isRoot bool
+	err := s.pool.QueryRow(ctx, `
+		SELECT EXISTS(
+			SELECT 1
+			FROM knowledge_groups
+			WHERE id = $1
+			  AND tenant_id = $2
+			  AND deleted_at IS NULL
+			  AND parent_id IS NULL
+		)
+	`, groupID, tenantID).Scan(&isRoot)
+	if err != nil {
+		return response.ErrInternal(50050, "knowledge_group_query_failed", "failed to query knowledge group")
+	}
+	if !isRoot {
+		return response.ErrBadRequest(40050, "knowledge_group_depth_exceeded", "third-level knowledge groups are not supported")
+	}
+	return nil
+}
+
+func (s *KnowledgeService) ensureStorableGroup(ctx context.Context, tenantID, groupID int64) error {
+	if err := s.ensureGroupAccessible(ctx, tenantID, groupID); err != nil {
+		return err
+	}
+
+	var storable bool
+	err := s.pool.QueryRow(ctx, `
+		SELECT EXISTS(
+			SELECT 1
+			FROM knowledge_groups child
+			JOIN knowledge_groups parent
+			  ON parent.id = child.parent_id
+			 AND parent.tenant_id = child.tenant_id
+			 AND parent.deleted_at IS NULL
+			WHERE child.id = $1
+			  AND child.tenant_id = $2
+			  AND child.deleted_at IS NULL
+			  AND parent.parent_id IS NULL
+		)
+	`, groupID, tenantID).Scan(&storable)
+	if err != nil {
+		return response.ErrInternal(50050, "knowledge_group_query_failed", "failed to query knowledge group")
+	}
+	if !storable {
+		return response.ErrBadRequest(40053, "knowledge_group_storage_invalid", "knowledge items can only be stored in second-level groups")
+	}
+	return nil
+}
+
+func (s *KnowledgeService) listGroupSubtreeIDs(
+	ctx context.Context,
+	tx pgx.Tx,
+	tenantID, groupID int64,
+) ([]int64, error) {
+	rows, err := tx.Query(ctx, `
+		WITH RECURSIVE selected_groups AS (
+			SELECT id
+			FROM knowledge_groups
+			WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL
+			UNION ALL
+			SELECT child.id
+			FROM knowledge_groups child
+			JOIN selected_groups parent ON child.parent_id = parent.id
+			WHERE child.tenant_id = $2 AND child.deleted_at IS NULL
+		)
+		SELECT id
+		FROM selected_groups
+	`, groupID, tenantID)
+	if err != nil {
+		return nil, response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to query knowledge groups")
+	}
+	defer rows.Close()
+
+	groupIDs := make([]int64, 0)
+	for rows.Next() {
+		var id int64
+		if err := rows.Scan(&id); err != nil {
+			return nil, response.ErrInternal(50054, "knowledge_group_delete_failed", err.Error())
+		}
+		groupIDs = append(groupIDs, id)
+	}
+	return groupIDs, nil
+}
+
+func (s *KnowledgeService) listActiveKnowledgeItemIDs(
+	ctx context.Context,
+	tx pgx.Tx,
+	tenantID int64,
+	groupIDs []int64,
+) ([]int64, error) {
+	if len(groupIDs) == 0 {
+		return []int64{}, nil
+	}
+
+	rows, err := tx.Query(ctx, `
+		SELECT id
+		FROM knowledge_items
+		WHERE tenant_id = $1
+		  AND deleted_at IS NULL
+		  AND group_id = ANY($2::bigint[])
+	`, tenantID, groupIDs)
+	if err != nil {
+		return nil, response.ErrInternal(50054, "knowledge_group_delete_failed", "failed to query knowledge items")
+	}
+	defer rows.Close()
+
+	itemIDs := make([]int64, 0)
+	for rows.Next() {
+		var id int64
+		if err := rows.Scan(&id); err != nil {
+			return nil, response.ErrInternal(50054, "knowledge_group_delete_failed", err.Error())
+		}
+		itemIDs = append(itemIDs, id)
+	}
+	return itemIDs, nil
+}
+
+func (s *KnowledgeService) embedChunks(ctx context.Context, chunks []string) ([][]float64, error) {
+	results := make([][]float64, 0, len(chunks))
+	for start := 0; start < len(chunks); start += s.embeddingBatchSize {
+		end := start + s.embeddingBatchSize
+		if end > len(chunks) {
+			end = len(chunks)
+		}
+		vectors, err := s.provider.Embed(ctx, chunks[start:end])
+		if err != nil {
+			return nil, err
+		}
+		results = append(results, vectors...)
+	}
+	if len(results) != len(chunks) {
+		return nil, errors.New("embedding result count mismatch")
+	}
+	return results, nil
+}
+
+func (s *KnowledgeService) listKnowledgePointIDs(ctx context.Context, tenantID, itemID int64) ([]string, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT qdrant_point_id
+		FROM knowledge_chunks_meta
+		WHERE tenant_id = $1 AND knowledge_item_id = $2 AND status <> 'deleted'
+	`, tenantID, itemID)
+	if err != nil {
+		return nil, response.ErrInternal(50054, "knowledge_item_delete_failed", "failed to query knowledge item points")
+	}
+	defer rows.Close()
+
+	pointIDs := make([]string, 0)
+	for rows.Next() {
+		var pointID string
+		if err := rows.Scan(&pointID); err != nil {
+			return nil, response.ErrInternal(50054, "knowledge_item_delete_failed", err.Error())
+		}
+		if strings.TrimSpace(pointID) != "" {
+			pointIDs = append(pointIDs, pointID)
+		}
+	}
+	return pointIDs, nil
+}
+
+func (s *KnowledgeService) filterActiveKnowledgeSnippets(
+	ctx context.Context,
+	tenantID int64,
+	candidates []KnowledgeSnippet,
+) ([]KnowledgeSnippet, error) {
+	if len(candidates) == 0 {
+		return []KnowledgeSnippet{}, nil
+	}
+
+	itemIDs := make([]int64, 0, len(candidates))
+	for _, candidate := range candidates {
+		if candidate.KnowledgeItemID > 0 {
+			itemIDs = append(itemIDs, candidate.KnowledgeItemID)
+		}
+	}
+	itemIDs = normalizeInt64IDs(itemIDs)
+	if len(itemIDs) == 0 {
+		return []KnowledgeSnippet{}, nil
+	}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT id
+		FROM knowledge_items
+		WHERE tenant_id = $1
+		  AND id = ANY($2::bigint[])
+		  AND deleted_at IS NULL
+	`, tenantID, itemIDs)
+	if err != nil {
+		return nil, response.ErrInternal(50051, "knowledge_items_query_failed", "failed to filter deleted knowledge items")
+	}
+	defer rows.Close()
+
+	active := make(map[int64]struct{}, len(itemIDs))
+	for rows.Next() {
+		var itemID int64
+		if err := rows.Scan(&itemID); err != nil {
+			return nil, response.ErrInternal(50051, "knowledge_items_scan_failed", err.Error())
+		}
+		active[itemID] = struct{}{}
+	}
+
+	filtered := make([]KnowledgeSnippet, 0, len(candidates))
+	for _, candidate := range candidates {
+		if _, ok := active[candidate.KnowledgeItemID]; ok {
+			filtered = append(filtered, candidate)
+		}
+	}
+	return filtered, nil
+}
+
+func (s *KnowledgeService) cleanupDeletedKnowledgeItemAsync(tenantID, itemID int64) {
+	if !s.startCleanupJob(tenantID, itemID) {
+		return
+	}
+
+	go func() {
+		defer s.finishCleanupJob(tenantID, itemID)
+
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+		defer cancel()
+		s.cleanupDeletedKnowledgeItem(ctx, tenantID, itemID)
+	}()
+}
+
+func (s *KnowledgeService) runDeletedCleanupWorker() {
+	s.scheduleDeletedKnowledgeCleanup()
+
+	ticker := time.NewTicker(defaultKnowledgeCleanupPoll)
+	defer ticker.Stop()
+
+	for range ticker.C {
+		s.scheduleDeletedKnowledgeCleanup()
+	}
+}
+
+func (s *KnowledgeService) scheduleDeletedKnowledgeCleanup() {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	jobs, err := s.listKnowledgeCleanupCandidates(ctx, 20)
+	if err != nil {
+		return
+	}
+
+	for _, job := range jobs {
+		s.cleanupDeletedKnowledgeItemAsync(job.TenantID, job.ItemID)
+	}
+}
+
+func (s *KnowledgeService) listKnowledgeCleanupCandidates(
+	ctx context.Context,
+	limit int,
+) ([]knowledgeCleanupJob, error) {
+	if limit <= 0 {
+		limit = 20
+	}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT ki.tenant_id, ki.id
+		FROM knowledge_items ki
+		WHERE ki.deleted_at IS NOT NULL
+		ORDER BY ki.updated_at ASC, ki.id ASC
+		LIMIT $1
+	`, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	jobs := make([]knowledgeCleanupJob, 0, limit)
+	for rows.Next() {
+		var job knowledgeCleanupJob
+		if err := rows.Scan(&job.TenantID, &job.ItemID); err != nil {
+			return nil, err
+		}
+		jobs = append(jobs, job)
+	}
+	return jobs, nil
+}
+
+func (s *KnowledgeService) startCleanupJob(tenantID, itemID int64) bool {
+	key := fmt.Sprintf("%d:%d", tenantID, itemID)
+
+	s.cleanupMu.Lock()
+	defer s.cleanupMu.Unlock()
+
+	if _, exists := s.cleanupInFlight[key]; exists {
+		return false
+	}
+	s.cleanupInFlight[key] = struct{}{}
+	return true
+}
+
+func (s *KnowledgeService) finishCleanupJob(tenantID, itemID int64) {
+	key := fmt.Sprintf("%d:%d", tenantID, itemID)
+
+	s.cleanupMu.Lock()
+	delete(s.cleanupInFlight, key)
+	s.cleanupMu.Unlock()
+}
+
+func (s *KnowledgeService) cleanupDeletedKnowledgeItem(ctx context.Context, tenantID, itemID int64) {
+	item, err := s.loadKnowledgeItemForCleanup(ctx, tenantID, itemID)
+	if err != nil || item == nil {
+		return
+	}
+
+	errs := make([]string, 0, 2)
+
+	if strings.TrimSpace(item.StorageKey) != "" {
+		if err := s.objectStorage.Delete(ctx, item.StorageKey); err != nil {
+			errs = append(errs, err.Error())
+		} else {
+			_ = s.markKnowledgeStorageDeleted(ctx, tenantID, itemID)
+		}
+	}
+
+	pointIDs, err := s.listKnowledgePointIDs(ctx, tenantID, itemID)
+	if err != nil {
+		errs = append(errs, err.Error())
+	} else {
+		if len(pointIDs) > 0 {
+			if err := s.store.DeletePoints(ctx, pointIDs); err != nil {
+				errs = append(errs, err.Error())
+			}
+		}
+	}
+
+	if len(errs) > 0 {
+		if s.logger != nil {
+			s.logger.Error("knowledge cleanup failed",
+				zap.Int64("tenant_id", tenantID),
+				zap.Int64("knowledge_item_id", itemID),
+				zap.Strings("errors", errs),
+			)
+		}
+		_ = s.setKnowledgeCleanupError(ctx, tenantID, itemID, strings.Join(errs, "; "))
+		return
+	}
+
+	if err := s.deleteKnowledgeItemPermanently(ctx, tenantID, itemID); err != nil {
+		if s.logger != nil {
+			s.logger.Error("knowledge cleanup finalize failed",
+				zap.Int64("tenant_id", tenantID),
+				zap.Int64("knowledge_item_id", itemID),
+				zap.Error(err),
+			)
+		}
+		_ = s.setKnowledgeCleanupError(ctx, tenantID, itemID, err.Error())
+		return
+	}
+
+	if s.logger != nil {
+		s.logger.Info("knowledge cleanup completed",
+			zap.Int64("tenant_id", tenantID),
+			zap.Int64("knowledge_item_id", itemID),
+		)
+	}
+	_ = s.clearKnowledgeCleanupError(ctx, tenantID, itemID)
+}
+
+func (s *KnowledgeService) loadKnowledgeItemForCleanup(
+	ctx context.Context,
+	tenantID, itemID int64,
+) (*knowledgeItemRecord, error) {
+	record := &knowledgeItemRecord{}
+	var contentText *string
+	err := s.pool.QueryRow(ctx, `
+		SELECT ki.id, ki.tenant_id, ki.group_id, kg.name, ki.name, ki.source_type,
+		       ki.source_uri, ki.storage_key, ki.content_text, ki.item_version
+		FROM knowledge_items ki
+		JOIN knowledge_groups kg ON kg.id = ki.group_id
+		WHERE ki.id = $1 AND ki.tenant_id = $2 AND ki.deleted_at IS NOT NULL
+	`, itemID, tenantID).Scan(
+		&record.ID,
+		&record.TenantID,
+		&record.GroupID,
+		&record.GroupName,
+		&record.Name,
+		&record.SourceType,
+		&record.SourceURI,
+		&record.StorageKey,
+		&contentText,
+		&record.ItemVersion,
+	)
+	if err != nil {
+		return nil, nil
+	}
+	record.ContentText = contentText
+	return record, nil
+}
+
+func (s *KnowledgeService) markKnowledgeStorageDeleted(ctx context.Context, tenantID, itemID int64) error {
+	_, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_items
+		SET storage_key = '', updated_at = NOW()
+		WHERE id = $1 AND tenant_id = $2
+	`, itemID, tenantID)
+	return err
+}
+
+func (s *KnowledgeService) deleteKnowledgeItemPermanently(ctx context.Context, tenantID, itemID int64) error {
+	_, err := s.pool.Exec(ctx, `
+		DELETE FROM knowledge_items
+		WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NOT NULL
+	`, itemID, tenantID)
+	return err
+}
+
+func (s *KnowledgeService) markKnowledgeChunkMetaDeleted(ctx context.Context, tenantID, itemID int64) error {
+	_, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_chunks_meta
+		SET status = 'deleted', updated_at = NOW()
+		WHERE knowledge_item_id = $1 AND tenant_id = $2 AND status <> 'deleted'
+	`, itemID, tenantID)
+	return err
+}
+
+func (s *KnowledgeService) setKnowledgeCleanupError(ctx context.Context, tenantID, itemID int64, message string) error {
+	_, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_items
+		SET error_message = $1, updated_at = NOW()
+		WHERE id = $2 AND tenant_id = $3
+	`, strings.TrimSpace(message), itemID, tenantID)
+	return err
+}
+
+func (s *KnowledgeService) clearKnowledgeCleanupError(ctx context.Context, tenantID, itemID int64) error {
+	_, err := s.pool.Exec(ctx, `
+		UPDATE knowledge_items
+		SET error_message = NULL, updated_at = NOW()
+		WHERE id = $1 AND tenant_id = $2
+	`, itemID, tenantID)
+	return err
+}
+
+func (s *KnowledgeService) listKnowledgeItemsByIDs(ctx context.Context, tenantID int64, itemIDs []int64) ([]KnowledgeItemResponse, error) {
+	if len(itemIDs) == 0 {
+		return []KnowledgeItemResponse{}, nil
+	}
+	rows, err := s.pool.Query(ctx, `
+		SELECT ki.id, ki.group_id, kg.name, ki.name, ki.source_type, ki.source_uri, ki.status,
+		       ki.size_bytes, ki.error_message, ki.created_at, ki.updated_at
+		FROM knowledge_items ki
+		JOIN knowledge_groups kg ON kg.id = ki.group_id
+		WHERE ki.tenant_id = $1 AND ki.id = ANY($2::bigint[]) AND ki.deleted_at IS NULL
+		ORDER BY ki.created_at DESC, ki.id DESC
+	`, tenantID, itemIDs)
+	if err != nil {
+		return nil, response.ErrInternal(50051, "knowledge_items_query_failed", "failed to list knowledge items")
+	}
+	defer rows.Close()
+
+	items := make([]KnowledgeItemResponse, 0)
+	for rows.Next() {
+		var (
+			item                 KnowledgeItemResponse
+			sourceURI            *string
+			errorMessage         *string
+			createdAt, updatedAt time.Time
+		)
+		if err := rows.Scan(
+			&item.ID,
+			&item.GroupID,
+			&item.GroupName,
+			&item.Name,
+			&item.SourceType,
+			&sourceURI,
+			&item.Status,
+			&item.SizeBytes,
+			&errorMessage,
+			&createdAt,
+			&updatedAt,
+		); err != nil {
+			return nil, response.ErrInternal(50051, "knowledge_items_scan_failed", err.Error())
+		}
+		item.SourceURI = sourceURI
+		item.ErrorMessage = errorMessage
+		item.CreatedAt = createdAt.Format(time.RFC3339)
+		item.UpdatedAt = updatedAt.Format(time.RFC3339)
+		items = append(items, item)
+	}
+	return items, nil
+}
+
+func (s *KnowledgeService) listGroupNames(ctx context.Context, tenantID int64, groupIDs []int64) ([]string, error) {
+	groupIDs = normalizeInt64IDs(groupIDs)
+	if len(groupIDs) == 0 {
+		return []string{}, nil
+	}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT id, name
+		FROM knowledge_groups
+		WHERE tenant_id = $1 AND id = ANY($2::bigint[]) AND deleted_at IS NULL
+		ORDER BY sort_order, created_at, id
+	`, tenantID, groupIDs)
+	if err != nil {
+		return nil, response.ErrInternal(50050, "knowledge_group_query_failed", "failed to query knowledge groups")
+	}
+	defer rows.Close()
+
+	names := make([]string, 0, len(groupIDs))
+	for rows.Next() {
+		var (
+			groupID int64
+			name    string
+		)
+		if err := rows.Scan(&groupID, &name); err != nil {
+			return nil, response.ErrInternal(50050, "knowledge_group_query_failed", err.Error())
+		}
+		if strings.TrimSpace(name) != "" {
+			names = append(names, strings.TrimSpace(name))
+		}
+	}
+	return names, nil
+}
+
+func normalizeInt64IDs(ids []int64) []int64 {
+	if len(ids) == 0 {
+		return nil
+	}
+	set := make(map[int64]struct{}, len(ids))
+	result := make([]int64, 0, len(ids))
+	for _, id := range ids {
+		if id <= 0 {
+			continue
+		}
+		if _, exists := set[id]; exists {
+			continue
+		}
+		set[id] = struct{}{}
+		result = append(result, id)
+	}
+	slices.Sort(result)
+	return result
+}
+
+func anyString(value any) string {
+	switch typed := value.(type) {
+	case string:
+		return typed
+	default:
+		return fmt.Sprintf("%v", typed)
+	}
+}
+
+func anyInt64(value any) int64 {
+	switch typed := value.(type) {
+	case int64:
+		return typed
+	case int32:
+		return int64(typed)
+	case int:
+		return int64(typed)
+	case float64:
+		return int64(typed)
+	case float32:
+		return int64(typed)
+	default:
+		return 0
+	}
+}
+
+func minInt(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
diff --git a/server/internal/tenant/app/prompt_generate_service.go b/server/internal/tenant/app/prompt_generate_service.go
index 702c2c8..c6f8f0d 100644
--- a/server/internal/tenant/app/prompt_generate_service.go
+++ b/server/internal/tenant/app/prompt_generate_service.go
@@ -15,12 +15,14 @@ import (
 	"github.com/geo-platform/tenant-api/internal/shared/llm"
 	"github.com/geo-platform/tenant-api/internal/shared/response"
 	"github.com/geo-platform/tenant-api/internal/shared/stream"
+	"github.com/geo-platform/tenant-api/internal/tenant/prompts"
 	"github.com/geo-platform/tenant-api/internal/tenant/repository"
 )
 
 type PromptRuleGenerationService struct {
 	pool            *pgxpool.Pool
 	llm             llm.Client
+	knowledge       *KnowledgeService
 	streams         *stream.GenerationHub
 	streamEnabled   bool
 	articleTimeout  time.Duration
@@ -53,13 +55,15 @@ type GenerateFromRuleResponse struct {
 }
 
 type promptRuleGenerationRecord struct {
-	ID               int64
-	Name             string
-	PromptContent    string
-	Scene            *string
-	DefaultTone      *string
-	DefaultWordCount *int
-	Status           string
+	ID                int64
+	Name              string
+	PromptContent     string
+	Scene             *string
+	DefaultTone       *string
+	DefaultWordCount  *int
+	KnowledgeGroupIDs []int64
+	KnowledgeGroups   []PromptRuleKnowledgeGroup
+	Status            string
 }
 
 const promptRuleGeneratingTitlePlaceholder = "标题生成中"
@@ -67,6 +71,7 @@ const promptRuleGeneratingTitlePlaceholder = "标题生成中"
 func NewPromptRuleGenerationService(
 	pool *pgxpool.Pool,
 	llmClient llm.Client,
+	knowledge *KnowledgeService,
 	streams *stream.GenerationHub,
 	cfg config.GenerationConfig,
 	llmMaxOutputTokens int64,
@@ -89,6 +94,7 @@ func NewPromptRuleGenerationService(
 	svc := &PromptRuleGenerationService{
 		pool:            pool,
 		llm:             llmClient,
+		knowledge:       knowledge,
 		streams:         streams,
 		streamEnabled:   cfg.StreamEnabled,
 		articleTimeout:  articleTimeout,
@@ -153,6 +159,26 @@ func (s *PromptRuleGenerationService) GenerateFromRule(ctx context.Context, req
 	if req.BrandID != nil {
 		inputParams["brand_id"] = *req.BrandID
 	}
+	if len(rule.KnowledgeGroupIDs) > 0 {
+		inputParams["knowledge_group_ids"] = rule.KnowledgeGroupIDs
+	}
+
+	knowledgePrompt := ""
+	if len(rule.KnowledgeGroupIDs) > 0 {
+		if s.knowledge == nil {
+			return nil, response.ErrServiceUnavailable(50352, "knowledge_unavailable", "knowledge service is not configured")
+		}
+		knowledgeContext, resolveErr := s.knowledge.ResolveContext(
+			ctx,
+			actor.TenantID,
+			rule.KnowledgeGroupIDs,
+			buildPromptRuleKnowledgeQuery(rule, inputParams),
+		)
+		if resolveErr != nil {
+			return nil, resolveErr
+		}
+		knowledgePrompt = s.knowledge.RenderPromptSection(knowledgeContext)
+	}
 
 	inputJSON, _ := json.Marshal(inputParams)
 	wizardStateJSON, _ := mergeArticleWizardState(nil, promptRuleGeneratingTitlePlaceholder, platformIDs)
@@ -233,7 +259,7 @@ func (s *PromptRuleGenerationService) GenerateFromRule(ctx context.Context, req
 		ArticleID:     articleID,
 		TaskID:        taskID,
 		ReservationID: reservationID,
-		Prompt:        buildPromptRuleGenerationPrompt(rule, inputParams),
+		Prompt:        buildPromptRuleGenerationPrompt(rule, inputParams, knowledgePrompt),
 		InputParams:   inputParams,
 		InitialTitle:  promptRuleGeneratingTitlePlaceholder,
 		WebSearch: llm.WebSearchOptions{
@@ -271,6 +297,28 @@ func (s *PromptRuleGenerationService) loadPromptRule(ctx context.Context, tenant
 	if err != nil {
 		return nil, response.ErrNotFound(40431, "rule_not_found", "prompt rule not found")
 	}
+	knowledgeRows, err := s.pool.Query(ctx, `
+		SELECT kg.id, kg.name
+		FROM prompt_rule_knowledge_groups prkg
+		JOIN knowledge_groups kg ON kg.id = prkg.knowledge_group_id
+		WHERE prkg.prompt_rule_id = $1
+		  AND kg.tenant_id = $2
+		  AND kg.deleted_at IS NULL
+		ORDER BY kg.sort_order, kg.created_at, kg.id
+	`, promptRuleID, tenantID)
+	if err != nil {
+		return nil, response.ErrInternal(50010, "knowledge_group_query_failed", "failed to query knowledge groups")
+	}
+	defer knowledgeRows.Close()
+
+	for knowledgeRows.Next() {
+		var group PromptRuleKnowledgeGroup
+		if err := knowledgeRows.Scan(&group.ID, &group.Name); err != nil {
+			return nil, response.ErrInternal(50010, "knowledge_group_query_failed", err.Error())
+		}
+		record.KnowledgeGroups = append(record.KnowledgeGroups, group)
+		record.KnowledgeGroupIDs = append(record.KnowledgeGroupIDs, group.ID)
+	}
 	return record, nil
 }
 
@@ -447,34 +495,60 @@ func (s *PromptRuleGenerationService) failGeneration(ctx context.Context, job pr
 	}
 }
 
-func buildPromptRuleGenerationPrompt(rule *promptRuleGenerationRecord, params map[string]interface{}) string {
+func buildPromptRuleGenerationPrompt(rule *promptRuleGenerationRecord, params map[string]interface{}, knowledgePrompt string) string {
 	sections := []string{strings.TrimSpace(rule.PromptContent)}
 
 	var supplements []string
 	if taskName := strings.TrimSpace(extractString(params, "task_name")); taskName != "" {
-		supplements = append(supplements, "任务名称："+taskName)
+		supplements = append(supplements, prompts.PromptRuleTaskNameSupplement(taskName))
 	}
 	if rule.Scene != nil && strings.TrimSpace(*rule.Scene) != "" {
-		supplements = append(supplements, "适用场景："+strings.TrimSpace(*rule.Scene))
+		supplements = append(supplements, prompts.PromptRuleSceneSupplement(strings.TrimSpace(*rule.Scene)))
 	}
 	if rule.DefaultTone != nil && strings.TrimSpace(*rule.DefaultTone) != "" {
-		supplements = append(supplements, "默认语气："+strings.TrimSpace(*rule.DefaultTone))
+		supplements = append(supplements, prompts.PromptRuleToneSupplement(strings.TrimSpace(*rule.DefaultTone)))
 	}
 	if rule.DefaultWordCount != nil && *rule.DefaultWordCount > 0 {
-		supplements = append(supplements, "建议字数："+strconv.Itoa(*rule.DefaultWordCount)+" 字左右")
+		supplements = append(supplements, prompts.PromptRuleWordCountSupplement(*rule.DefaultWordCount))
 	}
 	if target := strings.TrimSpace(extractString(params, "target_platform")); target != "" {
-		supplements = append(supplements, "目标发布平台："+strings.ReplaceAll(target, ",", "、"))
+		supplements = append(supplements, prompts.PromptRuleTargetPlatformSupplement(target))
 	}
 
 	if len(supplements) > 0 {
-		sections = append(sections, "补充要求：\n- "+strings.Join(supplements, "\n- "))
+		sections = append(sections, prompts.PromptRuleSupplementSection(supplements))
 	}
 
-	sections = append(sections, "输出要求：\n1. 直接输出完整可发布的中文 Markdown 文章。\n2. 标题使用一级标题，并由 AI 根据正文内容自行生成，不要直接复用任务名称。\n3. 不要输出你的思考过程、解释或致歉。")
+	if strings.TrimSpace(knowledgePrompt) != "" {
+		sections = append(sections, knowledgePrompt)
+	}
+
+	sections = append(sections, prompts.PromptRuleOutputRequirementsSection())
 	return strings.Join(sections, "\n\n")
 }
 
+func buildPromptRuleKnowledgeQuery(rule *promptRuleGenerationRecord, params map[string]interface{}) string {
+	parts := make([]string, 0, 6)
+	if rule != nil {
+		if text := strings.TrimSpace(rule.Name); text != "" {
+			parts = append(parts, text)
+		}
+		if rule.Scene != nil && strings.TrimSpace(*rule.Scene) != "" {
+			parts = append(parts, strings.TrimSpace(*rule.Scene))
+		}
+		if text := strings.TrimSpace(rule.PromptContent); text != "" {
+			parts = append(parts, text)
+		}
+	}
+	if taskName := strings.TrimSpace(extractString(params, "task_name")); taskName != "" {
+		parts = append(parts, taskName)
+	}
+	if target := strings.TrimSpace(extractString(params, "target_platform")); target != "" {
+		parts = append(parts, target)
+	}
+	return strings.Join(parts, "\n")
+}
+
 func extractGenerateCount(extra map[string]interface{}) int {
 	value := extractInt(extra, "generate_count")
 	if value <= 0 {
diff --git a/server/internal/tenant/app/prompt_rule_service.go b/server/internal/tenant/app/prompt_rule_service.go
index 4f0c257..6e3e3f9 100644
--- a/server/internal/tenant/app/prompt_rule_service.go
+++ b/server/internal/tenant/app/prompt_rule_service.go
@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
 
 	"github.com/geo-platform/tenant-api/internal/shared/auditlog"
@@ -39,35 +40,43 @@ type PromptRuleGroupResponse struct {
 // --- Rule types ---
 
 type PromptRuleRequest struct {
-	GroupID          *int64  `json:"group_id"`
-	Name             string  `json:"name" binding:"required"`
-	PromptContent    string  `json:"prompt_content" binding:"required"`
-	Scene            *string `json:"scene"`
-	DefaultTone      *string `json:"default_tone"`
-	DefaultWordCount *int    `json:"default_word_count"`
+	GroupID           *int64  `json:"group_id"`
+	Name              string  `json:"name" binding:"required"`
+	PromptContent     string  `json:"prompt_content" binding:"required"`
+	Scene             *string `json:"scene"`
+	DefaultTone       *string `json:"default_tone"`
+	DefaultWordCount  *int    `json:"default_word_count"`
+	KnowledgeGroupIDs []int64 `json:"knowledge_group_ids"`
+}
+
+type PromptRuleKnowledgeGroup struct {
+	ID   int64  `json:"id"`
+	Name string `json:"name"`
 }
 
 type PromptRuleResponse struct {
-	ID               int64   `json:"id"`
-	GroupID          *int64  `json:"group_id"`
-	Name             string  `json:"name"`
-	PromptContent    string  `json:"prompt_content"`
-	Scene            *string `json:"scene"`
-	DefaultTone      *string `json:"default_tone"`
-	DefaultWordCount *int    `json:"default_word_count"`
-	Status           string  `json:"status"`
-	ArticleCount     int     `json:"article_count"`
-	CreatedAt        string  `json:"created_at"`
-	UpdatedAt        string  `json:"updated_at"`
+	ID                int64                      `json:"id"`
+	GroupID           *int64                     `json:"group_id"`
+	Name              string                     `json:"name"`
+	PromptContent     string                     `json:"prompt_content"`
+	Scene             *string                    `json:"scene"`
+	DefaultTone       *string                    `json:"default_tone"`
+	DefaultWordCount  *int                       `json:"default_word_count"`
+	KnowledgeGroupIDs []int64                    `json:"knowledge_group_ids"`
+	KnowledgeGroups   []PromptRuleKnowledgeGroup `json:"knowledge_groups"`
+	Status            string                     `json:"status"`
+	ArticleCount      int                        `json:"article_count"`
+	CreatedAt         string                     `json:"created_at"`
+	UpdatedAt         string                     `json:"updated_at"`
 }
 
 type PromptRuleListParams struct {
-	GroupID  *int64  `json:"group_id"`
-	Status   *string `json:"status"`
-	Keyword  *string `json:"keyword"`
-	Page     int     `json:"page"`
-	PageSize int     `json:"page_size"`
-	Ungrouped bool   `json:"ungrouped"`
+	GroupID   *int64  `json:"group_id"`
+	Status    *string `json:"status"`
+	Keyword   *string `json:"keyword"`
+	Page      int     `json:"page"`
+	PageSize  int     `json:"page_size"`
+	Ungrouped bool    `json:"ungrouped"`
 }
 
 type PromptRuleListResponse struct {
@@ -297,12 +306,23 @@ func (s *PromptRuleService) List(ctx context.Context, params PromptRuleListParam
 		}
 		r.CreatedAt = fmt.Sprintf("%v", ca)
 		r.UpdatedAt = fmt.Sprintf("%v", ua)
+		r.KnowledgeGroupIDs = []int64{}
+		r.KnowledgeGroups = []PromptRuleKnowledgeGroup{}
 		items = append(items, r)
 	}
 	if items == nil {
 		items = []PromptRuleResponse{}
 	}
 
+	groupMap, err := s.loadPromptRuleKnowledgeGroupMap(ctx, actor.TenantID, collectPromptRuleIDs(items))
+	if err != nil {
+		return nil, err
+	}
+	for index := range items {
+		items[index].KnowledgeGroups = groupMap[items[index].ID]
+		items[index].KnowledgeGroupIDs = promptRuleKnowledgeGroupIDs(items[index].KnowledgeGroups)
+	}
+
 	return &PromptRuleListResponse{Items: items, Total: total}, nil
 }
 
@@ -327,14 +347,32 @@ func (s *PromptRuleService) Detail(ctx context.Context, id int64) (*PromptRuleRe
 	r.CreatedAt = fmt.Sprintf("%v", ca)
 	r.UpdatedAt = fmt.Sprintf("%v", ua)
 	r.ArticleCount = articleCount
+
+	groupMap, groupErr := s.loadPromptRuleKnowledgeGroupMap(ctx, actor.TenantID, []int64{id})
+	if groupErr != nil {
+		return nil, groupErr
+	}
+	r.KnowledgeGroups = groupMap[id]
+	r.KnowledgeGroupIDs = promptRuleKnowledgeGroupIDs(r.KnowledgeGroups)
 	return &r, nil
 }
 
 func (s *PromptRuleService) Create(ctx context.Context, req PromptRuleRequest) (*PromptRuleResponse, error) {
 	actor := auth.MustActor(ctx)
+	knowledgeGroups, err := s.validatePromptRuleKnowledgeGroups(ctx, actor.TenantID, req.KnowledgeGroupIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, response.ErrInternal(50010, "create_failed", "failed to create prompt rule")
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
 	var id int64
 	var ca interface{}
-	err := s.pool.QueryRow(ctx, `
+	err = tx.QueryRow(ctx, `
 		INSERT INTO prompt_rules (tenant_id, group_id, name, prompt_content, scene, default_tone, default_word_count)
 		VALUES ($1, $2, $3, $4, $5, $6, $7) RETURNING id, created_at
 	`, actor.TenantID, req.GroupID, req.Name, req.PromptContent, req.Scene, req.DefaultTone, req.DefaultWordCount).Scan(&id, &ca)
@@ -342,6 +380,13 @@ func (s *PromptRuleService) Create(ctx context.Context, req PromptRuleRequest) (
 		return nil, response.ErrInternal(50010, "create_failed", "failed to create prompt rule")
 	}
 
+	if err := s.replacePromptRuleKnowledgeGroups(ctx, tx, id, promptRuleKnowledgeGroupIDs(knowledgeGroups)); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, response.ErrInternal(50010, "create_failed", "failed to commit prompt rule")
+	}
+
 	afterJSON, _ := json.Marshal(map[string]interface{}{"id": id, "name": req.Name})
 	result := "success"
 	resourceType := "prompt_rule"
@@ -359,15 +404,36 @@ func (s *PromptRuleService) Create(ctx context.Context, req PromptRuleRequest) (
 	})
 
 	return &PromptRuleResponse{
-		ID: id, GroupID: req.GroupID, Name: req.Name, PromptContent: req.PromptContent,
-		Scene: req.Scene, DefaultTone: req.DefaultTone, DefaultWordCount: req.DefaultWordCount,
-		Status: "enabled", ArticleCount: 0, CreatedAt: fmt.Sprintf("%v", ca),
+		ID:                id,
+		GroupID:           req.GroupID,
+		Name:              req.Name,
+		PromptContent:     req.PromptContent,
+		Scene:             req.Scene,
+		DefaultTone:       req.DefaultTone,
+		DefaultWordCount:  req.DefaultWordCount,
+		KnowledgeGroupIDs: promptRuleKnowledgeGroupIDs(knowledgeGroups),
+		KnowledgeGroups:   knowledgeGroups,
+		Status:            "enabled",
+		ArticleCount:      0,
+		CreatedAt:         fmt.Sprintf("%v", ca),
+		UpdatedAt:         fmt.Sprintf("%v", ca),
 	}, nil
 }
 
 func (s *PromptRuleService) Update(ctx context.Context, id int64, req PromptRuleRequest) error {
 	actor := auth.MustActor(ctx)
-	tag, err := s.pool.Exec(ctx, `
+	knowledgeGroups, err := s.validatePromptRuleKnowledgeGroups(ctx, actor.TenantID, req.KnowledgeGroupIDs)
+	if err != nil {
+		return err
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return response.ErrInternal(50010, "update_failed", "failed to update prompt rule")
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	tag, err := tx.Exec(ctx, `
 		UPDATE prompt_rules SET name = $1, group_id = $2, prompt_content = $3,
 		       scene = $4, default_tone = $5, default_word_count = $6, updated_at = NOW()
 		WHERE id = $7 AND tenant_id = $8 AND deleted_at IS NULL
@@ -375,6 +441,12 @@ func (s *PromptRuleService) Update(ctx context.Context, id int64, req PromptRule
 	if err != nil || tag.RowsAffected() == 0 {
 		return response.ErrNotFound(40431, "rule_not_found", "prompt rule not found")
 	}
+	if err := s.replacePromptRuleKnowledgeGroups(ctx, tx, id, promptRuleKnowledgeGroupIDs(knowledgeGroups)); err != nil {
+		return err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return response.ErrInternal(50010, "update_failed", "failed to commit prompt rule")
+	}
 	return nil
 }
 
@@ -443,3 +515,122 @@ func (s *PromptRuleService) ListSimple(ctx context.Context) ([]PromptRuleSimple,
 	}
 	return items, nil
 }
+
+func (s *PromptRuleService) validatePromptRuleKnowledgeGroups(
+	ctx context.Context,
+	tenantID int64,
+	groupIDs []int64,
+) ([]PromptRuleKnowledgeGroup, error) {
+	groupIDs = normalizeInt64IDs(groupIDs)
+	if len(groupIDs) == 0 {
+		return []PromptRuleKnowledgeGroup{}, nil
+	}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT id, name
+		FROM knowledge_groups
+		WHERE tenant_id = $1 AND id = ANY($2::bigint[]) AND deleted_at IS NULL
+		ORDER BY sort_order, created_at, id
+	`, tenantID, groupIDs)
+	if err != nil {
+		return nil, response.ErrInternal(50010, "knowledge_group_query_failed", "failed to query knowledge groups")
+	}
+	defer rows.Close()
+
+	groups := make([]PromptRuleKnowledgeGroup, 0, len(groupIDs))
+	found := make(map[int64]struct{}, len(groupIDs))
+	for rows.Next() {
+		var item PromptRuleKnowledgeGroup
+		if err := rows.Scan(&item.ID, &item.Name); err != nil {
+			return nil, response.ErrInternal(50010, "knowledge_group_query_failed", err.Error())
+		}
+		groups = append(groups, item)
+		found[item.ID] = struct{}{}
+	}
+
+	if len(found) != len(groupIDs) {
+		return nil, response.ErrNotFound(40451, "knowledge_group_not_found", "knowledge group not found")
+	}
+
+	return groups, nil
+}
+
+func (s *PromptRuleService) loadPromptRuleKnowledgeGroupMap(
+	ctx context.Context,
+	tenantID int64,
+	ruleIDs []int64,
+) (map[int64][]PromptRuleKnowledgeGroup, error) {
+	result := make(map[int64][]PromptRuleKnowledgeGroup, len(ruleIDs))
+	ruleIDs = normalizeInt64IDs(ruleIDs)
+	if len(ruleIDs) == 0 {
+		return result, nil
+	}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT prkg.prompt_rule_id, kg.id, kg.name
+		FROM prompt_rule_knowledge_groups prkg
+		JOIN knowledge_groups kg ON kg.id = prkg.knowledge_group_id
+		WHERE prkg.prompt_rule_id = ANY($1::bigint[])
+		  AND kg.tenant_id = $2
+		  AND kg.deleted_at IS NULL
+		ORDER BY kg.sort_order, kg.created_at, kg.id
+	`, ruleIDs, tenantID)
+	if err != nil {
+		return nil, response.ErrInternal(50010, "knowledge_group_query_failed", "failed to query prompt rule knowledge groups")
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var (
+			ruleID int64
+			group  PromptRuleKnowledgeGroup
+		)
+		if err := rows.Scan(&ruleID, &group.ID, &group.Name); err != nil {
+			return nil, response.ErrInternal(50010, "knowledge_group_query_failed", err.Error())
+		}
+		result[ruleID] = append(result[ruleID], group)
+	}
+
+	return result, nil
+}
+
+func (s *PromptRuleService) replacePromptRuleKnowledgeGroups(
+	ctx context.Context,
+	tx pgx.Tx,
+	promptRuleID int64,
+	groupIDs []int64,
+) error {
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM prompt_rule_knowledge_groups
+		WHERE prompt_rule_id = $1
+	`, promptRuleID); err != nil {
+		return response.ErrInternal(50010, "update_failed", "failed to update prompt rule knowledge groups")
+	}
+
+	for _, groupID := range normalizeInt64IDs(groupIDs) {
+		if _, err := tx.Exec(ctx, `
+			INSERT INTO prompt_rule_knowledge_groups (prompt_rule_id, knowledge_group_id)
+			VALUES ($1, $2)
+		`, promptRuleID, groupID); err != nil {
+			return response.ErrInternal(50010, "update_failed", "failed to update prompt rule knowledge groups")
+		}
+	}
+
+	return nil
+}
+
+func collectPromptRuleIDs(items []PromptRuleResponse) []int64 {
+	ids := make([]int64, 0, len(items))
+	for _, item := range items {
+		ids = append(ids, item.ID)
+	}
+	return normalizeInt64IDs(ids)
+}
+
+func promptRuleKnowledgeGroupIDs(groups []PromptRuleKnowledgeGroup) []int64 {
+	ids := make([]int64, 0, len(groups))
+	for _, group := range groups {
+		ids = append(ids, group.ID)
+	}
+	return normalizeInt64IDs(ids)
+}
diff --git a/server/internal/tenant/app/template_assist.go b/server/internal/tenant/app/template_assist.go
index 06cac49..228049d 100644
--- a/server/internal/tenant/app/template_assist.go
+++ b/server/internal/tenant/app/template_assist.go
@@ -13,6 +13,7 @@ import (
 	"github.com/geo-platform/tenant-api/internal/shared/auth"
 	"github.com/geo-platform/tenant-api/internal/shared/llm"
 	"github.com/geo-platform/tenant-api/internal/shared/response"
+	"github.com/geo-platform/tenant-api/internal/tenant/prompts"
 	"github.com/geo-platform/tenant-api/internal/tenant/repository"
 )
 
@@ -474,7 +475,7 @@ func (s *TemplateService) executeOutlineTask(ctx context.Context, repo repositor
 		ResponseFormat: &llm.ResponseFormat{
 			Type:        llm.ResponseFormatTypeJSONObject,
 			Name:        "article_outline",
-			Description: "文章大纲 JSON 对象，必须包含 outline 数组字段。",
+			Description: prompts.OutlineResponseFormatDescription(),
 		},
 	}, nil)
 	if err != nil {
@@ -666,56 +667,12 @@ func buildAnalyzePrompt(templateKey, templateName string, req AnalyzeTaskRequest
 		basePrompt := strings.TrimSpace(renderPromptTemplate(analyzePromptTemplate, contextPayload))
 		if basePrompt != "" {
 			contextJSON, _ := json.MarshalIndent(contextPayload, "", "  ")
-			outputExample := `{
-  "brand_summary": "一句简洁的品牌/主题描述",
-  "keywords": ["关键词1", "关键词2", "关键词3", "关键词4", "关键词5"],
-  "competitors": [
-    {
-      "name": "竞品名",
-      "website": "https://example.com",
-      "description": "一句简介"
-    }
-  ]
-}`
-			return strings.TrimSpace(fmt.Sprintf("%s\n\n模板上下文:\n%s\n\nJSON 输出示例:\n%s", basePrompt, string(contextJSON), outputExample))
+			return prompts.TemplateContextWithJSONExample(basePrompt, string(contextJSON), prompts.AnalyzeOutputExample())
 		}
 	}
 
 	contextJSON, _ := json.MarshalIndent(contextPayload, "", "  ")
-	outputExample := `{
-  "brand_summary": "一句简洁的品牌/主题描述",
-  "keywords": ["关键词1", "关键词2", "关键词3", "关键词4", "关键词5"],
-  "competitors": [
-    {
-      "name": "竞品名",
-      "website": "https://example.com",
-      "description": "一句简介"
-    }
-  ]
-}`
-
-	return strings.TrimSpace(fmt.Sprintf(`
-你是一位专业的 GEO 内容策略师。
-
-任务:
-1. 分析品牌/主题上下文。
-2. 推荐最相关的 GEO 文章关键词。
-3. 推荐可信的竞品网站或竞争品牌，用于对比或引用。
-
-规则:
-- 仅返回 JSON，不要用 Markdown 代码块包裹。
-- 使用与请求的语言设置一致。zh-CN 用简体中文，en-US 用英文。
-- 关键词应为简洁的搜索短语。
-- 竞品应去重且真实。不确定时 website 字段可留空，但不要编造虚假链接。
-- brand_summary 限 1-2 句。
-- 最多返回 6 个竞品和 5 个关键词。
-
-模板上下文:
-%s
-
-JSON 输出示例:
-%s
-`, string(contextJSON), outputExample))
+	return prompts.AnalyzeFallbackPrompt(string(contextJSON))
 }
 
 func buildTitlePrompt(templateKey, templateName string, req TitleTaskRequest, titlePromptTemplate *string) string {
@@ -725,115 +682,36 @@ func buildTitlePrompt(templateKey, templateName string, req TitleTaskRequest, ti
 		if basePrompt != "" {
 			sections := []string{basePrompt}
 			if contextBlock := buildPromptContext(contextPayload); contextBlock != "" {
-				sections = append(sections, "当前上下文:\n"+contextBlock)
+				sections = append(sections, prompts.PromptContextSection(contextBlock))
 			}
-			sections = append(sections, strings.Join([]string{
-				"输出要求:",
-				"- 仅返回 JSON，不要用 Markdown 代码块包裹。",
-				"- 返回恰好 5 个字符串的 JSON 数组。",
-				"- 尊重当前关键词列表和竞品上下文，因为用户可能已手动编辑。",
-			}, "\n"))
+			sections = append(sections, prompts.TitleCustomOutputRequirementsSection())
 			return strings.Join(sections, "\n\n")
 		}
 	}
 
 	contextJSON, _ := json.MarshalIndent(contextPayload, "", "  ")
-	outputExample := `[
-  "标题 1",
-  "标题 2",
-  "标题 3",
-  "标题 4",
-  "标题 5"
-]`
-
-	return strings.TrimSpace(fmt.Sprintf(`
-你是一位专业的 GEO 内容策略师。
-
-任务:
-为当前内容摘要生成 5 个优质文章标题候选。
-
-规则:
-- 仅返回 JSON，不要用 Markdown 代码块包裹。
-- 返回 5 个字符串的 JSON 数组，不要返回对象。
-- 使用与请求的语言设置一致。zh-CN 用简体中文，en-US 用英文。
-- 标题应实用、具体，并契合当前模板的内容方向。
-- 尊重当前关键词列表和竞品上下文，因为用户可能已手动编辑。
-- 避免泛泛的广告文案和空洞口号。
-
-模板上下文:
-%s
-
-JSON 输出示例:
-%s
-`, string(contextJSON), outputExample))
+	return prompts.TitleFallbackPrompt(string(contextJSON))
 }
 
 func buildOutlinePrompt(templateKey, templateName string, req OutlineTaskRequest, outlinePromptTemplate *string) string {
 	contextPayload := outlinePromptParams(templateKey, templateName, req)
-	outputExample := `{
-  "outline": [
-    {
-      "outline": "网站列表",
-      "children": [
-        { "outline": "竞品 A" },
-        { "outline": "竞品 B" }
-      ]
-    },
-    {
-      "outline": "文章关键要点",
-      "children": [
-        { "outline": "要点 1" },
-        { "outline": "要点 2" }
-      ]
-    }
-  ]
-}`
+	outputExample := prompts.OutlineOutputExample()
 
 	if outlinePromptTemplate != nil && strings.TrimSpace(*outlinePromptTemplate) != "" {
 		basePrompt := strings.TrimSpace(renderPromptTemplate(outlinePromptTemplate, contextPayload))
 		if basePrompt != "" {
 			sections := []string{basePrompt}
 			if contextBlock := buildPromptContext(contextPayload); contextBlock != "" {
-				sections = append(sections, "当前上下文:\n"+contextBlock)
+				sections = append(sections, prompts.PromptContextSection(contextBlock))
 			}
-			sections = append(sections, strings.Join([]string{
-				"输出要求:",
-				"- 仅返回 JSON，不要用 Markdown 代码块包裹。",
-				`- 返回 JSON 对象，格式固定为 {"outline":[...]}`,
-				`- outline 字段是顶层大纲节点数组，每个节点格式为 {"outline":"...","children":[...]}`,
-				"- 每个已选大纲段落应作为顶层节点出现，语言与请求保持一致。",
-				"- 尊重当前关键词、竞品和关键要点，因为用户可能已手动编辑。",
-				"- 不要返回额外字段，不要返回纯数组，不要返回说明文字。",
-			}, "\n"))
-			sections = append(sections, "JSON 输出示例:\n"+outputExample)
+			sections = append(sections, prompts.OutlineCustomOutputRequirementsSection())
+			sections = append(sections, prompts.JSONOutputExampleSection(outputExample))
 			return strings.Join(sections, "\n\n")
 		}
 	}
 
 	contextJSON, _ := json.MarshalIndent(contextPayload, "", "  ")
-
-	return strings.TrimSpace(fmt.Sprintf(`
-你是一位专业的 GEO 内容策略师。
-
-任务:
-为当前内容摘要生成一份实用的文章大纲。
-
-规则:
-- 仅返回 JSON，不要用 Markdown 代码块包裹。
-- 返回 JSON 对象，格式固定为 {"outline":[...]}。
-- outline 字段中的每个顶层节点 "outline" 值必须保持已选段落标签原文。
-- 在合适的位置为每个顶层段落添加简洁的子大纲条目。
-- 使用与请求的语言设置一致。zh-CN 用简体中文，en-US 用英文。
-- 尊重当前标题、关键词、竞品、关键要点和品牌上下文，因为用户可能已手动编辑。
-- 大纲应具体、不含推广语气，适合后续完整成文。
-- 不要返回额外字段，不要返回纯数组，不要返回说明文字。
-
-模板上下文:
-%s
-
-JSON 输出示例:
-%s
-`, string(contextJSON), outputExample))
+	return prompts.OutlineFallbackPrompt(string(contextJSON))
 }
 
 func titlePromptParams(templateKey, templateName string, req TitleTaskRequest) map[string]interface{} {
diff --git a/server/internal/tenant/app/template_prompt.go b/server/internal/tenant/app/template_prompt.go
index 6a78ef4..39d80d8 100644
--- a/server/internal/tenant/app/template_prompt.go
+++ b/server/internal/tenant/app/template_prompt.go
@@ -7,14 +7,20 @@ import (
 	"strings"
 
 	"github.com/geo-platform/tenant-api/internal/shared/contentstats"
+	"github.com/geo-platform/tenant-api/internal/tenant/prompts"
 )
 
 var promptVariablePattern = regexp.MustCompile(`\{\{\s*([a-zA-Z0-9_]+)\s*\}\}`)
 
-func buildGenerationPrompt(templateKey, templateName string, promptTemplate *string, params map[string]interface{}) string {
+func buildGenerationPrompt(
+	templateKey, templateName string,
+	promptTemplate *string,
+	params map[string]interface{},
+	knowledgePrompt string,
+) string {
 	basePrompt := strings.TrimSpace(renderPromptTemplate(promptTemplate, params))
 	if basePrompt == "" {
-		basePrompt = fmt.Sprintf("你是一名专业内容编辑，请基于已提供的信息，为模板「%s」写出一篇完整的 Markdown 文章。", templateName)
+		basePrompt = prompts.DefaultGenerationBasePrompt(templateName)
 	}
 
 	var sections []string
@@ -22,35 +28,52 @@ func buildGenerationPrompt(templateKey, templateName string, promptTemplate *str
 
 	contextBlock := buildPromptContext(params)
 	if contextBlock != "" {
-		sections = append(sections, "当前上下文:\n"+contextBlock)
+		sections = append(sections, prompts.PromptContextSection(contextBlock))
 	}
 
-	sections = append(sections, strings.Join([]string{
-		"写作总要求:",
-		"- 仅返回文章 Markdown 正文，不要附带额外说明、提示语或代码块。",
-		"- 输出语言与 locale 一致：zh-CN 使用简体中文，en-US 使用自然、专业的英语。",
-		"- 如提供了 title，使用该标题作为文章主标题，并围绕它展开，不要另起一个无关标题。",
-		"- 如提供了 article_outline，一级节点是正文的最终小节标题，必须按顺序展开；二级及更深节点仅作为该小节的行文思路、论证顺序或信息要点，不要机械写成额外标题。",
-		"- 除主标题和一级小节标题外，默认不要把大纲子节点直接写成 Markdown 标题；子节点内容应自然融入段落、列表或过渡句中。",
-		"- 如提供了 key_points，正文中必须覆盖这些重点，不要遗漏。",
-		"- 每个核心段落都要有明确判断、原因解释、适用场景或对比维度，避免空话、套话和重复表述。",
-		"- 信息不足时，不要编造具体事实、价格、数据、测试结果、用户评价或机构结论；可以用稳妥表述说明判断边界。",
-		"- 保持客观、克制、非广告化，不使用夸张宣传语，如“顶级”“颠覆性”“完美”等。",
-		"- 使用清晰的小节标题和短段落；仅在确实有助于理解时使用列表。",
-		"- 结尾应给出清晰结论、适合对象、不适合对象，或下一步建议，帮助读者完成判断。",
-	}, "\n"))
+	if strings.TrimSpace(knowledgePrompt) != "" {
+		sections = append(sections, knowledgePrompt)
+	}
+
+	sections = append(sections, prompts.GenerationWritingRequirementsSection())
 
 	if templateRules := buildTemplateSpecificWritingRules(templateKey, params); templateRules != "" {
-		sections = append(sections, "模板专项要求:\n"+templateRules)
+		sections = append(sections, prompts.GenerationTemplateSpecificRulesHeading()+"\n"+templateRules)
 	}
 
 	if lengthGuidance := buildGenerationLengthGuidance(params); lengthGuidance != "" {
-		sections = append(sections, "篇幅要求:\n"+lengthGuidance)
+		sections = append(sections, prompts.GenerationLengthGuidanceHeading()+"\n"+lengthGuidance)
 	}
 
 	return strings.Join(sections, "\n\n")
 }
 
+func buildGenerationKnowledgeQuery(params map[string]interface{}) string {
+	if len(params) == 0 {
+		return ""
+	}
+
+	parts := make([]string, 0, 8)
+	appendValue := func(value string) {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			return
+		}
+		parts = append(parts, value)
+	}
+
+	appendValue(stringValue(params["title"]))
+	appendValue(stringValue(params["topic"]))
+	appendValue(stringValue(params["product_name"]))
+	appendValue(stringValue(params["subject"]))
+	appendValue(stringValue(params["brand_name"]))
+	appendValue(stringValue(params["primary_keyword"]))
+	appendValue(stringValue(params["key_points"]))
+	appendValue(stringValue(params["review_intro_hook"]))
+
+	return strings.Join(parts, "\n")
+}
+
 func buildTemplateSpecificWritingRules(templateKey string, params map[string]interface{}) string {
 	switch strings.TrimSpace(templateKey) {
 	case "top_x_article":
@@ -58,14 +81,7 @@ func buildTemplateSpecificWritingRules(templateKey string, params map[string]int
 		if brandName == "" {
 			return ""
 		}
-		return strings.Join([]string{
-			fmt.Sprintf("- 若文章包含品牌、公司或服务商榜单，请将「%s」排在第 1 位，并作为全文主推对象。", brandName),
-			fmt.Sprintf("- 「%s」对应条目的篇幅应明显多于其他对象，优先展开其核心优势、本地化服务、适合人群、报价或配置亮点、交付安装、售后表现与避坑建议。", brandName),
-			"- 其他对象保留客观介绍，但篇幅更短，重点写与主推对象的差异点和各自适用场景，不要平均分配篇幅。",
-			fmt.Sprintf("- 结论部分先明确推荐「%s」作为优先选择，再简要补充其他对象分别适合哪些预算、户型或需求。", brandName),
-			fmt.Sprintf("- 如果标题或正文属于“Top X / 推荐 / 最好 / 排行榜”这类排序导向内容，榜单顺序必须与结论保持一致，将「%s」放在第 1 位。", brandName),
-			"- 在不编造事实、不捏造数据的前提下，优先呈现主推对象的优势信息；对其他对象保持克制、客观的弱化式比较。",
-		}, "\n")
+		return prompts.TopXBrandPriorityRules(brandName)
 	default:
 		return ""
 	}
@@ -91,11 +107,7 @@ func buildGenerationLengthGuidance(params map[string]interface{}) string {
 		if maxWords > 2100 {
 			maxWords = 2100
 		}
-		return strings.Join([]string{
-			fmt.Sprintf("- 建议全文控制在 %d-%d 个英文单词，优先信息密度，不要为了拉长篇幅重复表达。", minWords, maxWords),
-			"- 引言和结论保持简洁，大多数一级章节写 1-3 个紧凑段落即可；只有最重要的章节需要展开。",
-			"- 一段能说清的内容不要拆成多段重复表达。",
-		}, "\n")
+		return prompts.EnglishLengthGuidance(minWords, maxWords)
 	}
 
 	minChars := 1100
@@ -111,11 +123,7 @@ func buildGenerationLengthGuidance(params map[string]interface{}) string {
 		maxChars = 2400
 	}
 
-	return strings.Join([]string{
-		fmt.Sprintf("- 建议全文控制在 %d-%d 字左右，优先信息密度，不要为了凑字数重复表达。", minChars, maxChars),
-		"- 引言和结论保持简洁，大多数一级章节写 1-3 个自然段即可；只有最关键的章节需要更充分展开。",
-		"- 能用一段说清的内容，不要拆成多段同义反复；主体部分重点写判断、原因、场景和建议。",
-	}, "\n")
+	return prompts.ChineseLengthGuidance(minChars, maxChars)
 }
 
 func estimateTopLevelSectionCount(params map[string]interface{}) int {
@@ -199,6 +207,10 @@ func buildPromptContext(params map[string]interface{}) string {
 		if value == nil {
 			return
 		}
+		switch key {
+		case "knowledge_group_ids", "knowledge_groups", "knowledge_context":
+			return
+		}
 		if key == "outline_sections" && hasStructuredOutline(params["article_outline"]) {
 			return
 		}
@@ -225,64 +237,7 @@ func buildPromptContext(params map[string]interface{}) string {
 }
 
 func promptContextLabel(key string) string {
-	switch key {
-	case "locale":
-		return "语言"
-	case "title":
-		return "标题"
-	case "topic":
-		return "主题"
-	case "product_name":
-		return "产品名"
-	case "subject":
-		return "研究主题"
-	case "brand_name":
-		return "品牌名"
-	case "brand":
-		return "品牌"
-	case "official_website", "website":
-		return "官网"
-	case "primary_keyword":
-		return "核心关键词"
-	case "keywords", "existing_keywords":
-		return "关键词"
-	case "competitors", "existing_competitors":
-		return "竞品"
-	case "competitor_names":
-		return "竞品名称"
-	case "competitor_count":
-		return "竞品数量"
-	case "brand_summary":
-		return "品牌摘要"
-	case "category":
-		return "品类"
-	case "count":
-		return "数量"
-	case "top_count":
-		return "推荐数量"
-	case "keyword_count":
-		return "关键词数量"
-	case "depth":
-		return "深度"
-	case "article_outline":
-		return "文章大纲"
-	case "outline_sections":
-		return "已选段落"
-	case "key_points":
-		return "关键要点"
-	case "review_intro_hook":
-		return "评测引言钩子"
-	case "template_key":
-		return "模板标识"
-	case "template_name":
-		return "模板名称"
-	case "current_year":
-		return "当前年份"
-	case "input_params":
-		return "输入参数"
-	default:
-		return key
-	}
+	return prompts.ContextLabel(key)
 }
 
 func formatPromptContextValue(key string, value interface{}) string {
diff --git a/server/internal/tenant/app/template_prompt_test.go b/server/internal/tenant/app/template_prompt_test.go
index ed5e5a3..09bf456 100644
--- a/server/internal/tenant/app/template_prompt_test.go
+++ b/server/internal/tenant/app/template_prompt_test.go
@@ -49,7 +49,7 @@ func TestBuildGenerationPromptAddsTopXBrandPriorityRules(t *testing.T) {
 		"topic":      "合肥全屋定制",
 		"brand_name": "安徽海翔家居用品销售有限公司",
 		"locale":     "zh-CN",
-	})
+	}, "")
 
 	for _, expected := range []string{
 		"模板专项要求:",
@@ -68,7 +68,7 @@ func TestBuildGenerationPromptDoesNotAddTopXBrandRulesForOtherTemplates(t *testi
 	prompt := buildGenerationPrompt("product_review", "产品评测", nil, map[string]interface{}{
 		"product_name": "测试产品",
 		"brand_name":   "安徽海翔家居用品销售有限公司",
-	})
+	}, "")
 
 	if strings.Contains(prompt, "排在第 1 位") {
 		t.Fatalf("buildGenerationPrompt() = %q, should not include top-x ranking rules", prompt)
diff --git a/server/internal/tenant/app/template_service.go b/server/internal/tenant/app/template_service.go
index e74442b..61d4b0c 100644
--- a/server/internal/tenant/app/template_service.go
+++ b/server/internal/tenant/app/template_service.go
@@ -22,6 +22,7 @@ type TemplateService struct {
 	pool            *pgxpool.Pool
 	templates       repository.TemplateRepository
 	llm             llm.Client
+	knowledge       *KnowledgeService
 	streams         *stream.GenerationHub
 	streamEnabled   bool
 	articleTimeout  time.Duration
@@ -48,6 +49,7 @@ func NewTemplateService(
 	pool *pgxpool.Pool,
 	templates repository.TemplateRepository,
 	llmClient llm.Client,
+	knowledge *KnowledgeService,
 	streams *stream.GenerationHub,
 	cfg config.GenerationConfig,
 	llmMaxOutputTokens int64,
@@ -71,6 +73,7 @@ func NewTemplateService(
 		pool:            pool,
 		templates:       templates,
 		llm:             llmClient,
+		knowledge:       knowledge,
 		streams:         streams,
 		streamEnabled:   cfg.StreamEnabled,
 		articleTimeout:  articleTimeout,
@@ -140,7 +143,7 @@ func (s *TemplateService) Detail(ctx context.Context, id int64) (*TemplateDetail
 		return nil, response.ErrNotFound(40410, "template_not_found", "template not found")
 	}
 
-		detail := &TemplateDetail{
+	detail := &TemplateDetail{
 		TemplateListItem: TemplateListItem{
 			ID:               record.ID,
 			Scope:            record.Scope,
@@ -454,7 +457,26 @@ func (s *TemplateService) executeGeneration(ctx context.Context, job generationJ
 		StartedAt: &now,
 	})
 
-	prompt := buildGenerationPrompt(job.TemplateKey, job.TemplateName, job.PromptTemplate, job.Params)
+	knowledgePrompt := ""
+	if knowledgeGroupIDs := extractKnowledgeGroupIDs(job.Params["knowledge_group_ids"]); len(knowledgeGroupIDs) > 0 {
+		if s.knowledge == nil {
+			s.failGeneration(ctx, job, title, "knowledge_resolve", fmt.Errorf("knowledge service is not configured"))
+			return
+		}
+		knowledgeContext, resolveErr := s.knowledge.ResolveContext(
+			ctx,
+			job.TenantID,
+			knowledgeGroupIDs,
+			buildGenerationKnowledgeQuery(job.Params),
+		)
+		if resolveErr != nil {
+			s.failGeneration(ctx, job, title, "knowledge_resolve", resolveErr)
+			return
+		}
+		knowledgePrompt = s.knowledge.RenderPromptSection(knowledgeContext)
+	}
+
+	prompt := buildGenerationPrompt(job.TemplateKey, job.TemplateName, job.PromptTemplate, job.Params, knowledgePrompt)
 	generateReq := llm.GenerateRequest{
 		Prompt:          prompt,
 		Timeout:         s.articleTimeout,
@@ -604,6 +626,8 @@ func generationFailureStageLabel(stage string) string {
 		return "任务入队失败"
 	case "llm_generate":
 		return "AI 正文生成失败"
+	case "knowledge_resolve":
+		return "知识库检索失败"
 	case "persist_begin_tx":
 		return "写入生成结果事务启动失败"
 	case "persist_create_version":
@@ -684,3 +708,29 @@ func nullableJSONString(value []byte) *string {
 	text := string(value)
 	return &text
 }
+
+func extractKnowledgeGroupIDs(value interface{}) []int64 {
+	switch typed := value.(type) {
+	case []int64:
+		return normalizeInt64IDs(typed)
+	case []interface{}:
+		ids := make([]int64, 0, len(typed))
+		for _, item := range typed {
+			switch raw := item.(type) {
+			case int64:
+				ids = append(ids, raw)
+			case int32:
+				ids = append(ids, int64(raw))
+			case int:
+				ids = append(ids, int64(raw))
+			case float64:
+				ids = append(ids, int64(raw))
+			case float32:
+				ids = append(ids, int64(raw))
+			}
+		}
+		return normalizeInt64IDs(ids)
+	default:
+		return nil
+	}
+}
diff --git a/server/internal/tenant/prompts/runtime.go b/server/internal/tenant/prompts/runtime.go
new file mode 100644
index 0000000..f0f590e
--- /dev/null
+++ b/server/internal/tenant/prompts/runtime.go
@@ -0,0 +1,319 @@
+package prompts
+
+import (
+	"fmt"
+	"strings"
+)
+
+func DefaultGenerationBasePrompt(templateName string) string {
+	return fmt.Sprintf("你是一名专业内容编辑，请基于已提供的信息，为模板「%s」写出一篇完整的 Markdown 文章。", templateName)
+}
+
+func PromptContextSection(contextBlock string) string {
+	return "当前上下文:\n" + contextBlock
+}
+
+func GenerationWritingRequirementsSection() string {
+	return strings.Join([]string{
+		"写作总要求:",
+		"- 仅返回文章 Markdown 正文，不要附带额外说明、提示语或代码块。",
+		"- 输出语言与 locale 一致：zh-CN 使用简体中文，en-US 使用自然、专业的英语。",
+		"- 如提供了 title，使用该标题作为文章主标题，并围绕它展开，不要另起一个无关标题。",
+		"- 如提供了 article_outline，一级节点是正文的最终小节标题，必须按顺序展开；二级及更深节点仅作为该小节的行文思路、论证顺序或信息要点，不要机械写成额外标题。",
+		"- 除主标题和一级小节标题外，默认不要把大纲子节点直接写成 Markdown 标题；子节点内容应自然融入段落、列表或过渡句中。",
+		"- 如提供了 key_points，正文中必须覆盖这些重点，不要遗漏。",
+		"- 每个核心段落都要有明确判断、原因解释、适用场景或对比维度，避免空话、套话和重复表述。",
+		"- 信息不足时，不要编造具体事实、价格、数据、测试结果、用户评价或机构结论；可以用稳妥表述说明判断边界。",
+		"- 保持客观、克制、非广告化，不使用夸张宣传语，如“顶级”“颠覆性”“完美”等。",
+		"- 使用清晰的小节标题和短段落；仅在确实有助于理解时使用列表。",
+		"- 结尾应给出清晰结论、适合对象、不适合对象，或下一步建议，帮助读者完成判断。",
+	}, "\n")
+}
+
+func GenerationTemplateSpecificRulesHeading() string {
+	return "模板专项要求:"
+}
+
+func GenerationLengthGuidanceHeading() string {
+	return "篇幅要求:"
+}
+
+func TopXBrandPriorityRules(brandName string) string {
+	return strings.Join([]string{
+		fmt.Sprintf("- 若文章包含品牌、公司或服务商榜单，请将「%s」排在第 1 位，并作为全文主推对象。", brandName),
+		fmt.Sprintf("- 「%s」对应条目的篇幅应明显多于其他对象，优先展开其核心优势、本地化服务、适合人群、报价或配置亮点、交付安装、售后表现与避坑建议。", brandName),
+		"- 其他对象保留客观介绍，但篇幅更短，重点写与主推对象的差异点和各自适用场景，不要平均分配篇幅。",
+		fmt.Sprintf("- 结论部分先明确推荐「%s」作为优先选择，再简要补充其他对象分别适合哪些预算、户型或需求。", brandName),
+		fmt.Sprintf("- 如果标题或正文属于“Top X / 推荐 / 最好 / 排行榜”这类排序导向内容，榜单顺序必须与结论保持一致，将「%s」放在第 1 位。", brandName),
+		"- 在不编造事实、不捏造数据的前提下，优先呈现主推对象的优势信息；对其他对象保持克制、客观的弱化式比较。",
+	}, "\n")
+}
+
+func EnglishLengthGuidance(minWords, maxWords int) string {
+	return strings.Join([]string{
+		fmt.Sprintf("- 建议全文控制在 %d-%d 个英文单词，优先信息密度，不要为了拉长篇幅重复表达。", minWords, maxWords),
+		"- 引言和结论保持简洁，大多数一级章节写 1-3 个紧凑段落即可；只有最重要的章节需要展开。",
+		"- 一段能说清的内容不要拆成多段重复表达。",
+	}, "\n")
+}
+
+func ChineseLengthGuidance(minChars, maxChars int) string {
+	return strings.Join([]string{
+		fmt.Sprintf("- 建议全文控制在 %d-%d 字左右，优先信息密度，不要为了凑字数重复表达。", minChars, maxChars),
+		"- 引言和结论保持简洁，大多数一级章节写 1-3 个自然段即可；只有最关键的章节需要更充分展开。",
+		"- 能用一段说清的内容，不要拆成多段同义反复；主体部分重点写判断、原因、场景和建议。",
+	}, "\n")
+}
+
+func ContextLabel(key string) string {
+	switch key {
+	case "locale":
+		return "语言"
+	case "title":
+		return "标题"
+	case "topic":
+		return "主题"
+	case "product_name":
+		return "产品名"
+	case "subject":
+		return "研究主题"
+	case "brand_name":
+		return "品牌名"
+	case "brand":
+		return "品牌"
+	case "official_website", "website":
+		return "官网"
+	case "primary_keyword":
+		return "核心关键词"
+	case "keywords", "existing_keywords":
+		return "关键词"
+	case "competitors", "existing_competitors":
+		return "竞品"
+	case "competitor_names":
+		return "竞品名称"
+	case "competitor_count":
+		return "竞品数量"
+	case "brand_summary":
+		return "品牌摘要"
+	case "category":
+		return "品类"
+	case "count":
+		return "数量"
+	case "top_count":
+		return "推荐数量"
+	case "keyword_count":
+		return "关键词数量"
+	case "depth":
+		return "深度"
+	case "article_outline":
+		return "文章大纲"
+	case "outline_sections":
+		return "已选段落"
+	case "key_points":
+		return "关键要点"
+	case "review_intro_hook":
+		return "评测引言钩子"
+	case "template_key":
+		return "模板标识"
+	case "template_name":
+		return "模板名称"
+	case "current_year":
+		return "当前年份"
+	case "input_params":
+		return "输入参数"
+	default:
+		return key
+	}
+}
+
+func TemplateContextWithJSONExample(basePrompt, contextJSON, outputExample string) string {
+	return strings.TrimSpace(fmt.Sprintf("%s\n\n模板上下文:\n%s\n\nJSON 输出示例:\n%s", basePrompt, contextJSON, outputExample))
+}
+
+func JSONOutputExampleSection(outputExample string) string {
+	return "JSON 输出示例:\n" + outputExample
+}
+
+func AnalyzeOutputExample() string {
+	return `{
+  "brand_summary": "一句简洁的品牌/主题描述",
+  "keywords": ["关键词1", "关键词2", "关键词3", "关键词4", "关键词5"],
+  "competitors": [
+    {
+      "name": "竞品名",
+      "website": "https://example.com",
+      "description": "一句简介"
+    }
+  ]
+}`
+}
+
+func AnalyzeFallbackPrompt(contextJSON string) string {
+	return strings.TrimSpace(fmt.Sprintf(`
+你是一位专业的 GEO 内容策略师。
+
+任务:
+1. 分析品牌/主题上下文。
+2. 推荐最相关的 GEO 文章关键词。
+3. 推荐可信的竞品网站或竞争品牌，用于对比或引用。
+
+规则:
+- 仅返回 JSON，不要用 Markdown 代码块包裹。
+- 使用与请求的语言设置一致。zh-CN 用简体中文，en-US 用英文。
+- 关键词应为简洁的搜索短语。
+- 竞品应去重且真实。不确定时 website 字段可留空，但不要编造虚假链接。
+- brand_summary 限 1-2 句。
+- 最多返回 6 个竞品和 5 个关键词。
+
+模板上下文:
+%s
+
+JSON 输出示例:
+%s
+`, contextJSON, AnalyzeOutputExample()))
+}
+
+func TitleCustomOutputRequirementsSection() string {
+	return strings.Join([]string{
+		"输出要求:",
+		"- 仅返回 JSON，不要用 Markdown 代码块包裹。",
+		"- 返回恰好 5 个字符串的 JSON 数组。",
+		"- 尊重当前关键词列表和竞品上下文，因为用户可能已手动编辑。",
+	}, "\n")
+}
+
+func TitleOutputExample() string {
+	return `[
+  "标题 1",
+  "标题 2",
+  "标题 3",
+  "标题 4",
+  "标题 5"
+]`
+}
+
+func TitleFallbackPrompt(contextJSON string) string {
+	return strings.TrimSpace(fmt.Sprintf(`
+你是一位专业的 GEO 内容策略师。
+
+任务:
+为当前内容摘要生成 5 个优质文章标题候选。
+
+规则:
+- 仅返回 JSON，不要用 Markdown 代码块包裹。
+- 返回 5 个字符串的 JSON 数组，不要返回对象。
+- 使用与请求的语言设置一致。zh-CN 用简体中文，en-US 用英文。
+- 标题应实用、具体，并契合当前模板的内容方向。
+- 尊重当前关键词列表和竞品上下文，因为用户可能已手动编辑。
+- 避免泛泛的广告文案和空洞口号。
+
+模板上下文:
+%s
+
+JSON 输出示例:
+%s
+`, contextJSON, TitleOutputExample()))
+}
+
+func OutlineOutputExample() string {
+	return `{
+  "outline": [
+    {
+      "outline": "网站列表",
+      "children": [
+        { "outline": "竞品 A" },
+        { "outline": "竞品 B" }
+      ]
+    },
+    {
+      "outline": "文章关键要点",
+      "children": [
+        { "outline": "要点 1" },
+        { "outline": "要点 2" }
+      ]
+    }
+  ]
+}`
+}
+
+func OutlineCustomOutputRequirementsSection() string {
+	return strings.Join([]string{
+		"输出要求:",
+		"- 仅返回 JSON，不要用 Markdown 代码块包裹。",
+		`- 返回 JSON 对象，格式固定为 {"outline":[...]}`,
+		`- outline 字段是顶层大纲节点数组，每个节点格式为 {"outline":"...","children":[...]}`,
+		"- 每个已选大纲段落应作为顶层节点出现，语言与请求保持一致。",
+		"- 尊重当前关键词、竞品和关键要点，因为用户可能已手动编辑。",
+		"- 不要返回额外字段，不要返回纯数组，不要返回说明文字。",
+	}, "\n")
+}
+
+func OutlineFallbackPrompt(contextJSON string) string {
+	return strings.TrimSpace(fmt.Sprintf(`
+你是一位专业的 GEO 内容策略师。
+
+任务:
+为当前内容摘要生成一份实用的文章大纲。
+
+规则:
+- 仅返回 JSON，不要用 Markdown 代码块包裹。
+- 返回 JSON 对象，格式固定为 {"outline":[...]}。
+- outline 字段中的每个顶层节点 "outline" 值必须保持已选段落标签原文。
+- 在合适的位置为每个顶层段落添加简洁的子大纲条目。
+- 使用与请求的语言设置一致。zh-CN 用简体中文，en-US 用英文。
+- 尊重当前标题、关键词、竞品、关键要点和品牌上下文，因为用户可能已手动编辑。
+- 大纲应具体、不含推广语气，适合后续完整成文。
+- 不要返回额外字段，不要返回纯数组，不要返回说明文字。
+
+模板上下文:
+%s
+
+JSON 输出示例:
+%s
+`, contextJSON, OutlineOutputExample()))
+}
+
+func OutlineResponseFormatDescription() string {
+	return "文章大纲 JSON 对象，必须包含 outline 数组字段。"
+}
+
+func PromptRuleTaskNameSupplement(taskName string) string {
+	return "任务名称：" + taskName
+}
+
+func PromptRuleSceneSupplement(scene string) string {
+	return "适用场景：" + scene
+}
+
+func PromptRuleToneSupplement(tone string) string {
+	return "默认语气：" + tone
+}
+
+func PromptRuleWordCountSupplement(wordCount int) string {
+	return fmt.Sprintf("建议字数：%d 字左右", wordCount)
+}
+
+func PromptRuleTargetPlatformSupplement(target string) string {
+	return "目标发布平台：" + strings.ReplaceAll(target, ",", "、")
+}
+
+func PromptRuleSupplementSection(items []string) string {
+	return "补充要求：\n- " + strings.Join(items, "\n- ")
+}
+
+func PromptRuleOutputRequirementsSection() string {
+	return "输出要求：\n1. 直接输出完整可发布的中文 Markdown 文章。\n2. 标题使用一级标题，并由 AI 根据正文内容自行生成，不要直接复用任务名称。\n3. 不要输出你的思考过程、解释或致歉。"
+}
+
+func KnowledgePromptIntroLines() []string {
+	return []string{
+		"以下为可参考的知识库内容，只用于补充事实背景、术语定义、产品信息或表达素材：",
+		"- 优先吸收并改写，不要逐段照抄。",
+		"- 若知识库内容与用户明确输入冲突，以用户输入为准。",
+		"- 信息不足时不要虚构事实。",
+	}
+}
+
+func KnowledgeSnippetLabel(index int) string {
+	return fmt.Sprintf("知识片段 %d", index+1)
+}
diff --git a/server/internal/tenant/prompts/template_seeds.go b/server/internal/tenant/prompts/template_seeds.go
new file mode 100644
index 0000000..deb6608
--- /dev/null
+++ b/server/internal/tenant/prompts/template_seeds.go
@@ -0,0 +1,401 @@
+package prompts
+
+type PlatformTemplateSeed struct {
+	Key            string
+	Name           string
+	PromptTemplate string
+	CardConfigJSON string
+}
+
+func PlatformTemplateSeeds() []PlatformTemplateSeed {
+	return append([]PlatformTemplateSeed(nil), platformTemplateSeeds...)
+}
+
+var platformTemplateSeeds = []PlatformTemplateSeed{
+	{
+		Key:  "top_x_article",
+		Name: "Top X 文章",
+		PromptTemplate: `你是一名经验丰富的内容编辑，请围绕「{{topic}}」撰写一篇完整的 Markdown 推荐类文章。
+文章目标:
+1. 帮读者快速理解这个主题下值得关注的 {{count}} 个方向、产品或对象。
+2. 说明每个对象的核心特点、适用场景、优缺点和选择建议。
+
+写作要求:
+- 不要写成空洞的排行列表；每个对象都要有清晰的入选理由和判断依据。
+- 如果提供了 competitors、品牌或关键词上下文，要自然融入横向比较，但不要机械重复名单。
+- 如果提供了 brand_name，且文章属于品牌、公司或服务商对比型推荐内容，应将该品牌作为主推对象：默认排在第 1 位、正文篇幅明显多于其他对象、结论优先推荐。
+- 对 brand_name 对应对象重点展开核心优势、本地服务、适合人群、报价或配置亮点、交付安装、售后与避坑建议；其他对象保持客观但更简洁的差异化介绍。
+- 重点写筛选标准、差异点、适合谁、不适合谁，以及常见误区或避坑点。
+- 引言先交代推荐标准与读者能得到什么，结尾优先总结 brand_name 为什么值得优先考虑，再补充其他对象各自适合的预算与需求。`,
+		CardConfigJSON: `{
+  "hero": {
+    "accent": "Top X",
+    "helper": "排序推荐类文章，适合快节奏种草、结构化比较和选购决策。"
+  },
+  "wizard": {
+    "steps": {
+      "basic": { "title": "基本信息", "description": "品牌、关键词与竞品上下文" },
+      "structure": { "title": "文章结构", "description": "标题方案、结构组合与重点补充" },
+      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
+    },
+    "basic": {
+      "analyze_button_label": "分析",
+      "cards": {
+        "brand": {
+          "title": "品牌信息",
+          "hint": "品牌可手动输入，也可从品牌库带入。AI 会结合品牌、官网和模板字段补齐关键词与竞品。"
+        },
+        "keywords": {
+          "title": "关键词",
+          "hint": "关键词可以手动改写，AI 分析结果会自动补充到这里，后续标题生成会以当前版本为准。"
+        },
+        "template_fields": {
+          "title": "模板字段",
+          "hint": "保留本模板特有的补充字段，用来约束选题角度与文章范围。"
+        },
+        "competitors": {
+          "title": "竞品列表",
+          "hint": "竞品可编辑、追加和收藏到品牌词库。后续标题生成会严格基于当前竞品上下文。"
+        }
+      }
+    },
+    "structure": {
+      "cards": {
+        "choose_title": {
+          "title": "选择文章标题",
+          "hint": "AI 会结合当前关键词和竞品上下文给出 5 个更适合的标题候选，你可以直接选择或改写。"
+        },
+        "outline": {
+          "title": "文章结构",
+          "hint": "保留推荐文章的默认结构，也可以按这次出稿需求删减、补充自定义段落。"
+        },
+        "preview": {
+          "title": "文章预览",
+          "hint": "右侧会根据当前标题和结构实时预览最终文章框架。"
+        }
+      }
+    },
+    "review": {
+      "card": {
+        "title": "提交前确认",
+        "hint": "确认当前标题、结构和品牌上下文无误后再提交生成任务。"
+      },
+      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
+    },
+    "managed_fields": ["topic", "count"],
+    "derived_inputs": {
+      "topic": { "source": "primary_keyword_or_brand" },
+      "count": { "source": "competitor_count", "fallback_number": 5 }
+    },
+    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为推荐类文章做品牌与竞品分析。\n模板: {{template_name}}\n语言: {{locale}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n\n任务:\n1. 分析品牌/话题上下文，给出 1-2 句品牌摘要。\n2. 推荐最多 5 个适合推荐类文章的搜索关键词。\n3. 推荐最多 6 个可信竞品或对比对象。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词应为简洁的搜索短语。\n- 竞品应去重且真实，不确定时 website 留空，不要编造 URL。",
+    "title_prompt_template": "你正在为一篇推荐类文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n核心关键词: {{primary_keyword}}\n品牌名: {{brand_name}}\n推荐数量: {{top_count}}\n竞品名称: {{competitor_names}}\n\n要求:\n- 标题风格应契合实用选购指南、推荐合集、横向对比、避坑盘点等内容调性。\n- 不要机械重复模板名称或「Top X 文章」字样。\n- 每个标题应具体、可读，且角度各不相同。\n- 当 locale 为 zh-CN 时，优先使用自然的中文标题风格，如推荐、精选、怎么选、避坑、盘点等，但避免空洞标题党。",
+    "outline_prompt_template": "你正在为一篇推荐类文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n标题: {{title}}\n核心关键词: {{primary_keyword}}\n品牌名: {{brand_name}}\n竞品名称: {{competitor_names}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n\n要求:\n- 每个已选段落作为顶层节点，下设具体子条目。\n- 网站列表段落下按竞品逐一展开。\n- 内容应具体、有对比、有结论导向，避免泛泛而谈。\n- 使用与 locale 一致的语言。",
+    "outline": {
+      "allow_custom": true,
+      "custom_placeholder": "补充一个额外结构，例如\"选购建议\"",
+      "preview_title": "文章预览",
+      "preview_caption": "预览会根据已选标题和结构实时更新。",
+      "sections": [
+        { "key": "intro", "label": "引言", "default": true },
+        { "key": "site_list", "label": "网站列表", "default": true },
+        { "key": "key_points", "label": "文章关键要点", "default": true },
+        { "key": "what_is_keyword", "label_template": "什么是{{primary_keyword}}", "default": false },
+        { "key": "features", "label": "特点", "default": false },
+        { "key": "pros_cons", "label": "优缺点", "default": false },
+        { "key": "audience", "label": "适合人群", "default": false },
+        { "key": "pricing", "label": "价格", "default": false },
+        { "key": "how_to_choose", "label": "如何选择", "default": false },
+        { "key": "conclusion", "label": "结论", "default": false }
+      ]
+    }
+  }
+}`,
+	},
+	{
+		Key:  "product_review",
+		Name: "产品评测文章",
+		PromptTemplate: `你是一名资深产品评测编辑，请围绕「{{product_name}}」这款{{category}}产品撰写一篇完整的 Markdown 评测文章。
+文章目标:
+1. 帮读者判断这款产品是否值得关注或购买。
+2. 解释它的核心能力、实际使用感受、主要优缺点和适合人群。
+
+写作要求:
+- 开头快速进入评测主题；如果提供了 review_intro_hook，则按对应风格自然起笔，但不要故作夸张。
+- 正文要覆盖产品定位、核心功能、使用体验、限制点、适用场景和购买建议。
+- 评价必须有判断，不要只罗列卖点；要说明为什么是优点、在什么情况下会变成限制。
+- 结论写清楚适合谁、不适合谁，以及在什么条件下值得买。
+- 全文保持客观、务实，不要写成品牌宣传稿。`,
+		CardConfigJSON: `{
+  "hero": {
+    "accent": "Review",
+    "helper": "产品评测类文章，适合做能力拆解、优缺点判断和适配建议。"
+  },
+  "wizard": {
+    "steps": {
+      "basic": { "title": "基本信息", "description": "产品、品牌与评测上下文" },
+      "structure": { "title": "文章结构", "description": "标题方案、评测结构与重点补充" },
+      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
+    },
+    "basic": {
+      "analyze_button_label": "分析",
+      "cards": {
+        "brand": {
+          "title": "品牌信息",
+          "hint": "可直接输入品牌，也可从品牌库选择。AI 会补充适合评测文章的关键词和品牌背景。"
+        },
+        "keywords": {
+          "title": "关键词",
+          "hint": "关键词会影响标题和正文的评测切入点，可手动修改。"
+        },
+        "competitors": {
+          "visible": false
+        }
+      }
+    },
+    "structure": {
+      "cards": {
+        "choose_title": {
+          "title": "选择文章标题",
+          "hint": "AI 会生成 5 个更适合评测文章的标题候选，你可以挑选或覆盖。"
+        },
+        "outline": {
+          "title": "文章结构",
+          "hint": "保留评测默认结构，也可按具体产品情况增删段落。"
+        },
+        "preview": {
+          "title": "文章预览",
+          "hint": "右侧会根据标题和结构实时预览评测文章框架。"
+        }
+      },
+      "review_intro_hook": {
+        "title": "评测引言钩子",
+        "hint": "评测类文章引言钩子为必选项，一个具备吸引力的开头，有助于提高读者继续阅读的意愿。",
+        "field_name": "review_intro_hook",
+        "required": true,
+        "options": [
+          { "key": "question", "label": "提出问题", "description": "用一个有趣的问题引导读者继续往下看", "default": true },
+          { "key": "fact", "label": "分享事实", "description": "利用令人惊讶的事实或数据先抓住注意力" },
+          { "key": "quote", "label": "引用名言", "description": "用一句贴切的名言或行业观点作为开头" },
+          { "key": "story", "label": "讲述故事", "description": "从一个具体场景或小故事切入评测主题" },
+          { "key": "feeling", "label": "分享感受", "description": "用第一视角的真实感受建立代入感" }
+        ]
+      },
+      "outline_prompt_template": "你正在为一篇产品评测文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n标题: {{title}}\n产品名: {{product_name}}\n品类: {{category}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n评测引言钩子: {{review_intro_hook}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n\n要求:\n- 每个已选段落作为顶层节点，使用与请求一致的语言。\n- 当有引言段落时，子条目应体现所选的评测引言钩子风格。\n- 聚焦具体能力拆解、真实使用判断、优缺点权衡和适合人群。\n- 大纲务实、简洁、不含推广语气。"
+    },
+    "review": {
+      "card": {
+        "title": "提交前确认",
+        "hint": "确认当前标题、结构与评测角度后再提交生成。"
+      },
+      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
+    },
+    "managed_fields": [],
+    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为产品评测文章做品牌与产品分析。\n模板: {{template_name}}\n语言: {{locale}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n产品名: {{product_name}}\n品类: {{category}}\n\n任务:\n1. 分析产品与品牌上下文，给出 1-2 句品牌摘要。\n2. 推荐最多 5 个适合评测文章的搜索关键词，聚焦产品能力、使用场景和购买决策。\n3. 推荐最多 6 个可信的同类产品或替代方案。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词侧重评测视角，如「XX 评测」「XX 值不值得买」「XX 优缺点」。\n- 竞品应去重且真实，不确定时 website 留空。",
+    "title_prompt_template": "你正在为一篇产品评测文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n产品名: {{product_name}}\n品类: {{category}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n\n要求:\n- 标题应像可信的评测、测评、购买建议类内容。\n- 用具体表达代替空洞口号。\n- 当 locale 为 zh-CN 时，标题应贴合中文内容平台风格，可使用评测、实测、值不值得买、优缺点、怎么选等表达。\n- 返回 5 个角度明确不同的标题。",
+    "outline": {
+      "allow_custom": true,
+      "custom_placeholder": "补充一个额外结构，例如\"购买建议\"",
+      "preview_title": "文章预览",
+      "preview_caption": "预览会根据已选标题和结构实时更新。",
+      "sections": [
+        { "key": "intro", "label": "引言", "default": true },
+        { "key": "overview", "label": "产品概览", "default": true },
+        { "key": "core_features", "label": "核心卖点", "default": true },
+        { "key": "real_experience", "label": "使用体验", "default": false },
+        { "key": "pros_cons", "label": "优缺点", "default": false },
+        { "key": "audience", "label": "适合人群", "default": false },
+        { "key": "buying_advice", "label": "购买建议", "default": false },
+        { "key": "conclusion", "label": "结论", "default": false }
+      ]
+    }
+  }
+}`,
+	},
+	{
+		Key:  "research_report",
+		Name: "研究报告文章",
+		PromptTemplate: `你是一名研究分析师，请围绕「{{subject}}」撰写一篇完整的 Markdown 研究报告。
+文章目标:
+1. 提炼关键事实、趋势与结构化发现。
+2. 解释背后原因，并给出可执行的判断或建议。
+
+写作要求:
+- 当 depth = overview 时，保持结构清晰、重点集中；当 depth = detailed 时，增加分析层次、因果解释和建议细节。
+- 不要泛泛复述背景，要突出关键发现、变化趋势、风险与影响。
+- 如果提供了品牌、关键词或参考对象，应把它们作为分析参照，而不是简单罗列。
+- 摘要部分先给核心结论，正文再展开依据，结尾落到行动建议或后续观察点。`,
+		CardConfigJSON: `{
+  "hero": {
+    "accent": "Report",
+    "helper": "研究报告类文章，适合趋势解读、市场分析和策略判断。"
+  },
+  "wizard": {
+    "steps": {
+      "basic": { "title": "基本信息", "description": "品牌与关键词背景信息" },
+      "structure": { "title": "文章结构", "description": "标题方案、研究结构与重点补充" },
+      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
+    },
+    "basic": {
+      "analyze_button_label": "分析",
+      "cards": {
+        "brand": {
+          "title": "品牌信息",
+          "hint": "如研究对象与品牌有关，可补充品牌与官网信息帮助 AI 建立上下文。"
+        },
+        "keywords": {
+          "title": "关键词",
+          "hint": "关键词会影响报告的核心视角、结论表达和标题风格。"
+        },
+        "competitors": {
+          "visible": false
+        }
+      }
+    },
+    "structure": {
+      "cards": {
+        "choose_title": {
+          "title": "选择文章标题",
+          "hint": "AI 会生成 5 个更适合研究型内容的标题候选，你可以直接选择或改写。"
+        },
+        "outline": {
+          "title": "文章结构",
+          "hint": "保留研究报告的默认结构，也可补充更贴近本次出稿的章节。"
+        },
+        "preview": {
+          "title": "文章预览",
+          "hint": "右侧会根据标题和结构实时预览报告框架。"
+        }
+      }
+    },
+    "review": {
+      "card": {
+        "title": "提交前确认",
+        "hint": "确认当前标题、结构和研究主题后再提交生成。"
+      },
+      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
+    },
+    "managed_fields": [],
+    "derived_inputs": {
+      "subject": { "source": "primary_keyword_or_brand" }
+    },
+    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为研究报告做主题与背景分析。\n模板: {{template_name}}\n语言: {{locale}}\n研究主题: {{subject}}\n深度: {{depth}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n\n任务:\n1. 分析研究主题上下文，给出 1-2 句主题摘要。\n2. 推荐最多 5 个适合研究报告的搜索关键词，侧重行业术语和趋势表达。\n3. 推荐最多 6 个可作为参照的品牌、机构或竞争对手。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词应体现分析性视角，如「XX 市场分析」「XX 趋势」「XX 行业报告」。\n- 竞品应去重且真实，不确定时 website 留空。",
+    "title_prompt_template": "你正在为一篇研究报告文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n研究主题: {{subject}}\n深度: {{depth}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n\n要求:\n- 标题应具有分析性、聚焦感和洞察力。\n- 避免模糊的企业公关式措辞。\n- 当 locale 为 zh-CN 时，可使用研究报告、趋势洞察、观察、判断、分析等表达。\n- 返回 5 个角度各异但可信的报告风格标题。",
+    "outline_prompt_template": "你正在为一篇研究报告文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n标题: {{title}}\n研究主题: {{subject}}\n深度: {{depth}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n\n要求:\n- 每个已选段落作为顶层节点，下设具体子条目。\n- 关键发现段落应按数据驱动的方式组织子条目。\n- 内容应具有结构性、分析深度和可操作性。\n- 使用与 locale 一致的语言。",
+    "outline": {
+      "allow_custom": true,
+      "custom_placeholder": "自定义输入，不超过10个字",
+      "custom_max_length": 10,
+      "preview_title": "文章预览",
+      "preview_caption": "预览会根据已选标题和结构实时更新。",
+      "sections": [
+        { "key": "summary", "label": "摘要", "default": true },
+        { "key": "intro", "label": "引言", "default": true },
+        { "key": "methodology", "label": "研究方法与数据来源", "default": true },
+        { "key": "segment_overview", "label": "细分市场概述", "default": true },
+        { "key": "positioning_analysis", "label": "产品定位与优缺点", "default": true },
+        { "key": "user_research", "label": "用户调研", "default": false },
+        { "key": "target_audience", "label": "目标人群", "default": false },
+        { "key": "competitor_comparison", "label": "竞品对比", "default": false },
+        { "key": "research_conclusion", "label": "研究结论", "default": false },
+        { "key": "analysis_recommendations", "label": "分析建议", "default": false }
+      ]
+    }
+  }
+}`,
+	},
+	{
+		Key:  "brand_search_expansion",
+		Name: "品牌词搜索扩写",
+		PromptTemplate: `你是一名擅长搜索意图写作的内容编辑，请围绕「{{brand}} {{keyword}}」撰写一篇完整的 Markdown 品牌词搜索扩写文章。
+文章目标:
+1. 直接回答搜索用户最关心的问题。
+2. 解释品牌背景、核心信息和常见对比/疑问，承接后续转化或继续了解。
+
+写作要求:
+- 开头优先回答搜索意图，不要长篇铺垫。
+- 正文应覆盖品牌是什么、用户为什么会搜这个词、常见疑问、对比点和下一步决策信息。
+- 如果提供了竞品或替代方案，按用户常见比较维度展开，不要空泛地说“各有优势”。
+- 语气客观、有信息量，避免企业宣传腔。
+- 结尾给出简洁总结，并提示用户接下来应该关注什么信息来继续判断。`,
+		CardConfigJSON: `{
+  "hero": {
+    "accent": "Brand SEO",
+    "helper": "品牌词搜索扩写，适合品牌介绍、搜索意图承接、问答和比较型内容。"
+  },
+  "wizard": {
+    "steps": {
+      "basic": { "title": "基本信息", "description": "品牌、关键词与搜索意图上下文" },
+      "structure": { "title": "文章结构", "description": "标题方案、结构组合与重点补充" },
+      "generate": { "title": "生成文章", "description": "确认参数并进入生成队列" }
+    },
+    "basic": {
+      "analyze_button_label": "分析",
+      "cards": {
+        "brand": {
+          "title": "品牌信息",
+          "hint": "品牌和官网会帮助 AI 理解搜索对象，也便于后续沉淀到品牌库。"
+        },
+        "keywords": {
+          "title": "关键词",
+          "hint": "这里的关键词会直接参与标题与正文的搜索意图组织。"
+        },
+        "template_fields": {
+          "title": "模板字段",
+          "hint": "模板字段会补充品牌词与搜索意图的具体边界。"
+        },
+        "competitors": {
+          "title": "参考对象",
+          "hint": "可补充竞品或替代方案，帮助品牌词扩写内容更完整。"
+        }
+      }
+    },
+    "structure": {
+      "cards": {
+        "choose_title": {
+          "title": "选择文章标题",
+          "hint": "AI 会生成 5 个更适合品牌词搜索扩写的标题候选。"
+        },
+        "outline": {
+          "title": "文章结构",
+          "hint": "保留默认搜索意图结构，也可以按本次需求增删段落。"
+        },
+        "preview": {
+          "title": "文章预览",
+          "hint": "右侧会根据标题和结构实时预览内容框架。"
+        }
+      }
+    },
+    "review": {
+      "card": {
+        "title": "提交前确认",
+        "hint": "确认当前标题、结构与搜索上下文后再提交生成。"
+      },
+      "alert_message": "后端会立即创建文章与任务记录，再由排队 worker 异步完成正文生成。"
+    },
+    "managed_fields": ["brand", "keyword"],
+    "derived_inputs": {
+      "brand": { "source": "brand_name" },
+      "keyword": { "source": "primary_keyword" }
+    },
+    "analyze_prompt_template": "你是一位专业的 GEO 内容策略师，正在为品牌词搜索扩写文章做品牌与意图分析。\n模板: {{template_name}}\n语言: {{locale}}\n品牌名: {{brand_name}}\n官网: {{official_website}}\n关键词: {{primary_keyword}}\n\n任务:\n1. 分析品牌与搜索意图上下文，给出 1-2 句品牌摘要。\n2. 推荐最多 5 个品牌词搜索相关的关键词，侧重搜索意图和用户疑问。\n3. 推荐最多 6 个可信的竞品或替代方案。\n\n规则:\n- 仅返回 JSON，不要用 Markdown 代码块包裹。\n- 使用与 locale 一致的语言。\n- 关键词应贴合搜索意图，如「XX 是什么」「XX 怎么样」「XX 对比 YY」。\n- 竞品应去重且真实，不确定时 website 留空。",
+    "title_prompt_template": "你正在为一篇品牌词搜索扩写文章生成 5 个候选标题。\n模板: {{template_name}}\n语言: {{locale}}\n当前年份: {{current_year}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n官网: {{official_website}}\n\n要求:\n- 标题应适用于品牌搜索意图、对比、问答和解释型内容。\n- 避免空洞口号。\n- 当 locale 为 zh-CN 时，可使用是什么、怎么样、怎么选、对比、值得买吗等表达。\n- 返回 5 个不同的、贴合搜索意图的标题选项。",
+    "outline_prompt_template": "你正在为一篇品牌词搜索扩写文章生成实用大纲。\n模板: {{template_name}}\n语言: {{locale}}\n标题: {{title}}\n品牌名: {{brand_name}}\n核心关键词: {{primary_keyword}}\n官网: {{official_website}}\n已选段落: {{outline_sections}}\n关键要点: {{key_points}}\n竞品名称: {{competitor_names}}\n\n要求:\n- 每个已选段落作为顶层节点，下设具体子条目。\n- 品牌概览段落应覆盖品牌定位、核心产品和差异化。\n- 对比段落应按竞品逐一展开对比维度。\n- 内容应回答搜索意图，语气客观有信息量。\n- 使用与 locale 一致的语言。",
+    "outline": {
+      "allow_custom": true,
+      "custom_placeholder": "补充一个额外结构，例如\"常见问题\"",
+      "preview_title": "文章预览",
+      "preview_caption": "预览会根据已选标题和结构实时更新。",
+      "sections": [
+        { "key": "intro", "label": "引言", "default": true },
+        { "key": "search_intent", "label": "搜索意图", "default": true },
+        { "key": "brand_overview", "label_template": "什么是{{brand_name}}", "default": true },
+        { "key": "core_points", "label": "核心要点", "default": false },
+        { "key": "comparison", "label": "对比与替代方案", "default": false },
+        { "key": "faq", "label": "常见问题", "default": false },
+        { "key": "conclusion", "label": "结论", "default": false }
+      ]
+    }
+  }
+}`,
+	},
+}
diff --git a/server/internal/tenant/transport/article_handler.go b/server/internal/tenant/transport/article_handler.go
index cf4dec4..2bc875e 100644
--- a/server/internal/tenant/transport/article_handler.go
+++ b/server/internal/tenant/transport/article_handler.go
@@ -22,11 +22,23 @@ type ArticleHandler struct {
 }
 
 func NewArticleHandler(a *bootstrap.App) *ArticleHandler {
+	knowledgeSvc := app.NewKnowledgeService(
+		a.DB,
+		a.RetrievalProvider,
+		a.VectorStore,
+		a.ObjectStorage,
+		a.Logger,
+		a.Config.Retrieval,
+		0,
+		0,
+	)
+
 	return &ArticleHandler{
 		svc: app.NewArticleService(a.DB, a.AuditLogs),
 		promptGenerateSvc: app.NewPromptRuleGenerationService(
 			a.DB,
 			a.LLM,
+			knowledgeSvc,
 			a.GenerationStreams,
 			a.Config.Generation,
 			a.Config.LLM.MaxOutputTokens,
diff --git a/server/internal/tenant/transport/knowledge_handler.go b/server/internal/tenant/transport/knowledge_handler.go
new file mode 100644
index 0000000..31984c4
--- /dev/null
+++ b/server/internal/tenant/transport/knowledge_handler.go
@@ -0,0 +1,188 @@
+package transport
+
+import (
+	"io"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/geo-platform/tenant-api/internal/bootstrap"
+	"github.com/geo-platform/tenant-api/internal/shared/response"
+	"github.com/geo-platform/tenant-api/internal/tenant/app"
+)
+
+type KnowledgeHandler struct {
+	svc *app.KnowledgeService
+}
+
+func NewKnowledgeHandler(a *bootstrap.App) *KnowledgeHandler {
+	return &KnowledgeHandler{
+		svc: app.NewKnowledgeService(
+			a.DB,
+			a.RetrievalProvider,
+			a.VectorStore,
+			a.ObjectStorage,
+			a.Logger,
+			a.Config.Retrieval,
+			a.Config.Generation.QueueSize,
+			a.Config.Generation.WorkerConcurrency,
+		),
+	}
+}
+
+func (h *KnowledgeHandler) ListGroups(c *gin.Context) {
+	data, err := h.svc.ListGroups(c.Request.Context())
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *KnowledgeHandler) CreateGroup(c *gin.Context) {
+	var req app.KnowledgeGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+
+	data, err := h.svc.CreateGroup(c.Request.Context(), req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.SuccessWithStatus(c, http.StatusCreated, data)
+}
+
+func (h *KnowledgeHandler) UpdateGroup(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("gid"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_id", "knowledge group id must be a number"))
+		return
+	}
+
+	var req app.KnowledgeGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+
+	if err := h.svc.UpdateGroup(c.Request.Context(), groupID, req); err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, nil)
+}
+
+func (h *KnowledgeHandler) DeleteGroup(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.Param("gid"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_id", "knowledge group id must be a number"))
+		return
+	}
+
+	if err := h.svc.DeleteGroup(c.Request.Context(), groupID); err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, nil)
+}
+
+func (h *KnowledgeHandler) ListItems(c *gin.Context) {
+	var groupID *int64
+	if raw := c.Query("group_id"); raw != "" {
+		parsed, err := strconv.ParseInt(raw, 10, 64)
+		if err != nil {
+			response.Error(c, response.ErrBadRequest(40001, "invalid_group_id", "group id must be a number"))
+			return
+		}
+		groupID = &parsed
+	}
+
+	data, err := h.svc.ListItems(c.Request.Context(), groupID)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, data)
+}
+
+func (h *KnowledgeHandler) CreateTextItem(c *gin.Context) {
+	var req app.KnowledgeTextItemRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+
+	data, err := h.svc.CreateTextItem(c.Request.Context(), req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.SuccessWithStatus(c, http.StatusCreated, data)
+}
+
+func (h *KnowledgeHandler) CreateURLItem(c *gin.Context) {
+	var req app.KnowledgeURLItemRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
+		return
+	}
+
+	data, err := h.svc.CreateURLItem(c.Request.Context(), req)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.SuccessWithStatus(c, http.StatusCreated, data)
+}
+
+func (h *KnowledgeHandler) CreateFileItem(c *gin.Context) {
+	groupID, err := strconv.ParseInt(c.PostForm("group_id"), 10, 64)
+	if err != nil || groupID <= 0 {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_group_id", "group id must be a number"))
+		return
+	}
+
+	name := c.PostForm("name")
+	fileHeader, err := c.FormFile("file")
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_file", "file is required"))
+		return
+	}
+
+	file, err := fileHeader.Open()
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_file", "file cannot be opened"))
+		return
+	}
+	defer file.Close()
+
+	content, err := io.ReadAll(file)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_file", "file cannot be read"))
+		return
+	}
+
+	data, err := h.svc.CreateFileItem(c.Request.Context(), groupID, name, fileHeader.Filename, content)
+	if err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.SuccessWithStatus(c, http.StatusCreated, data)
+}
+
+func (h *KnowledgeHandler) DeleteItem(c *gin.Context) {
+	itemID, err := strconv.ParseInt(c.Param("id"), 10, 64)
+	if err != nil {
+		response.Error(c, response.ErrBadRequest(40001, "invalid_id", "knowledge item id must be a number"))
+		return
+	}
+
+	if err := h.svc.DeleteItem(c.Request.Context(), itemID); err != nil {
+		response.Error(c, err)
+		return
+	}
+	response.Success(c, nil)
+}
diff --git a/server/internal/tenant/transport/router.go b/server/internal/tenant/transport/router.go
index 2a6dd87..aeaef80 100644
--- a/server/internal/tenant/transport/router.go
+++ b/server/internal/tenant/transport/router.go
@@ -83,6 +83,18 @@ func RegisterRoutes(app *bootstrap.App) {
 	brands.PUT("/:id/competitors/:cid", brandHandler.UpdateCompetitor)
 	brands.DELETE("/:id/competitors/:cid", brandHandler.DeleteCompetitor)
 
+	knowledge := protected.Group("/tenant/knowledge")
+	knowledgeHandler := NewKnowledgeHandler(app)
+	knowledge.GET("/groups", knowledgeHandler.ListGroups)
+	knowledge.POST("/groups", knowledgeHandler.CreateGroup)
+	knowledge.PUT("/groups/:gid", knowledgeHandler.UpdateGroup)
+	knowledge.DELETE("/groups/:gid", knowledgeHandler.DeleteGroup)
+	knowledge.GET("/items", knowledgeHandler.ListItems)
+	knowledge.POST("/items/text", knowledgeHandler.CreateTextItem)
+	knowledge.POST("/items/url", knowledgeHandler.CreateURLItem)
+	knowledge.POST("/items/file", knowledgeHandler.CreateFileItem)
+	knowledge.DELETE("/items/:id", knowledgeHandler.DeleteItem)
+
 	// Prompt Rules
 	promptRules := protected.Group("/tenant/prompt-rules")
 	prHandler := NewPromptRuleHandler(app)
diff --git a/server/internal/tenant/transport/template_handler.go b/server/internal/tenant/transport/template_handler.go
index 479ad5e..aa02415 100644
--- a/server/internal/tenant/transport/template_handler.go
+++ b/server/internal/tenant/transport/template_handler.go
@@ -16,6 +16,17 @@ type TemplateHandler struct {
 }
 
 func NewTemplateHandler(a *bootstrap.App) *TemplateHandler {
+	knowledgeSvc := app.NewKnowledgeService(
+		a.DB,
+		a.RetrievalProvider,
+		a.VectorStore,
+		a.ObjectStorage,
+		a.Logger,
+		a.Config.Retrieval,
+		0,
+		0,
+	)
+
 	return &TemplateHandler{
 		svc: app.NewTemplateService(
 			a.DB,
@@ -24,6 +35,7 @@ func NewTemplateHandler(a *bootstrap.App) *TemplateHandler {
 				a.Cache,
 			),
 			a.LLM,
+			knowledgeSvc,
 			a.GenerationStreams,
 			a.Config.Generation,
 			a.Config.LLM.MaxOutputTokens,
diff --git a/server/migrations/20260403100000_create_knowledge_tables.down.sql b/server/migrations/20260403100000_create_knowledge_tables.down.sql
new file mode 100644
index 0000000..fc16adc
--- /dev/null
+++ b/server/migrations/20260403100000_create_knowledge_tables.down.sql
@@ -0,0 +1,5 @@
+DROP TABLE IF EXISTS prompt_rule_knowledge_groups;
+DROP TABLE IF EXISTS knowledge_chunks_meta;
+DROP TABLE IF EXISTS knowledge_parse_tasks;
+DROP TABLE IF EXISTS knowledge_items;
+DROP TABLE IF EXISTS knowledge_groups;
diff --git a/server/migrations/20260403100000_create_knowledge_tables.up.sql b/server/migrations/20260403100000_create_knowledge_tables.up.sql
new file mode 100644
index 0000000..e9d78b8
--- /dev/null
+++ b/server/migrations/20260403100000_create_knowledge_tables.up.sql
@@ -0,0 +1,77 @@
+CREATE TABLE knowledge_groups (
+    id          BIGSERIAL PRIMARY KEY,
+    tenant_id   BIGINT NOT NULL REFERENCES tenants(id),
+    name        VARCHAR(100) NOT NULL,
+    parent_id   BIGINT REFERENCES knowledge_groups(id) ON DELETE SET NULL,
+    sort_order  INT NOT NULL DEFAULT 0,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    deleted_at  TIMESTAMPTZ
+);
+CREATE UNIQUE INDEX uk_knowledge_group_name
+    ON knowledge_groups(tenant_id, COALESCE(parent_id, 0), name)
+    WHERE deleted_at IS NULL;
+CREATE INDEX idx_knowledge_group_tenant_parent
+    ON knowledge_groups(tenant_id, parent_id, sort_order)
+    WHERE deleted_at IS NULL;
+
+CREATE TABLE knowledge_items (
+    id           BIGSERIAL PRIMARY KEY,
+    tenant_id    BIGINT NOT NULL REFERENCES tenants(id),
+    group_id     BIGINT NOT NULL REFERENCES knowledge_groups(id),
+    source_type  VARCHAR(20) NOT NULL,
+    name         VARCHAR(255) NOT NULL,
+    source_uri   TEXT,
+    storage_key  TEXT NOT NULL DEFAULT '',
+    content_text TEXT,
+    status       VARCHAR(20) NOT NULL DEFAULT 'pending',
+    size_bytes   BIGINT NOT NULL DEFAULT 0,
+    item_version INT NOT NULL DEFAULT 1,
+    error_message TEXT,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    deleted_at   TIMESTAMPTZ
+);
+CREATE INDEX idx_knowledge_item_group_status
+    ON knowledge_items(tenant_id, group_id, status)
+    WHERE deleted_at IS NULL;
+
+CREATE TABLE knowledge_parse_tasks (
+    id                BIGSERIAL PRIMARY KEY,
+    tenant_id         BIGINT NOT NULL REFERENCES tenants(id),
+    knowledge_item_id BIGINT NOT NULL REFERENCES knowledge_items(id) ON DELETE CASCADE,
+    source_type       VARCHAR(20) NOT NULL,
+    status            VARCHAR(20) NOT NULL DEFAULT 'pending',
+    error_message     TEXT,
+    started_at        TIMESTAMPTZ,
+    completed_at      TIMESTAMPTZ,
+    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX idx_parse_task_status
+    ON knowledge_parse_tasks(tenant_id, status, created_at DESC);
+
+CREATE TABLE knowledge_chunks_meta (
+    id                BIGSERIAL PRIMARY KEY,
+    tenant_id         BIGINT NOT NULL REFERENCES tenants(id),
+    knowledge_item_id BIGINT NOT NULL REFERENCES knowledge_items(id) ON DELETE CASCADE,
+    chunk_index       INT NOT NULL,
+    token_count       INT NOT NULL DEFAULT 0,
+    qdrant_point_id   VARCHAR(64) NOT NULL,
+    item_version      INT NOT NULL DEFAULT 1,
+    status            VARCHAR(20) NOT NULL DEFAULT 'active',
+    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (knowledge_item_id, chunk_index, item_version)
+);
+CREATE INDEX idx_chunk_item_version
+    ON knowledge_chunks_meta(tenant_id, knowledge_item_id, item_version, status);
+
+CREATE TABLE prompt_rule_knowledge_groups (
+    prompt_rule_id      BIGINT NOT NULL REFERENCES prompt_rules(id) ON DELETE CASCADE,
+    knowledge_group_id  BIGINT NOT NULL REFERENCES knowledge_groups(id) ON DELETE CASCADE,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (prompt_rule_id, knowledge_group_id)
+);
+CREATE INDEX idx_prompt_rule_knowledge_group
+    ON prompt_rule_knowledge_groups(knowledge_group_id, prompt_rule_id);
diff --git a/task_plan.md b/task_plan.md
index f5b1feb..2d093c6 100644
--- a/task_plan.md
+++ b/task_plan.md
@@ -4,7 +4,7 @@
 Finish the completed backend verification/implementation chain, then resume the interrupted work by establishing the missing frontend foundation for `admin-web` so it can authenticate against `tenant-api` and render the first dashboard slice.
 
 ## Current Phase
-Phase 10
+Phase 14
 
 ## Phases
 ### Phase 1: Progress Verification
@@ -82,6 +82,18 @@ Phase 10
 - [ ] Update planning files and deliver the completed scope
 - **Status:** pending
 
+### Phase 13: Prompt Centralization
+- [x] Inventory all currently used hard-coded prompts in runtime and seed paths
+- [x] Extract prompt definitions into a dedicated shared location
+- [x] Refactor existing callers to read from the centralized prompt layer
+- **Status:** complete
+
+### Phase 14: Prompt Verification & Delivery
+- [x] Run targeted compile/test verification for the prompt refactor
+- [x] Update planning files with the final prompt inventory and changed files
+- [x] Deliver the extraction result and any remaining gaps
+- **Status:** complete
+
 ## Key Questions
 1. Which of the 9 steps are already implemented versus partially complete?
 2. What is the earliest step whose acceptance criteria are not yet met?
@@ -102,6 +114,7 @@ Phase 10
 | Use the current backend route graph as the implementation boundary for this turn | The user asked for frontend coverage of existing interfaces, so pages without APIs stay non-primary |
 | Reconstruct the screenshot layouts from visual position data, not OCR text alone | The user explicitly asked to follow image design including element placement |
 | Move the quota card into the left sidebar footer and use page-level hero sections | This matches the reference screenshots more closely than the previous generic topbar layout |
+| Centralize prompt text in a dedicated package instead of leaving it inside business logic functions | The user explicitly asked to extract hard-coded prompts for easier future optimization |
 
 ## Errors Encountered
 | Error | Attempt | Resolution |