371 lines
14 KiB
TypeScript
371 lines
14 KiB
TypeScript
|
import { generateObject, generateText } from "ai";
|
|||
|
|
import { z } from "zod";
|
|||
|
|
import {
|
|||
|
|
coerceResearchMapRaw,
|
|||
|
|
extractJsonFromText,
|
|||
|
|
researchMapLooseSchema,
|
|||
|
|
} from "./coerce-research-map";
|
|||
|
|
import type { ProviderApiKeys } from "./keys";
|
|||
|
|
import { getModel } from "./provider";
|
|||
|
|
import {
|
|||
|
|
buildResearchMapSystemPrompt,
|
|||
|
|
buildResearchMapUserPrompt,
|
|||
|
|
} from "./prompts/research-map";
|
|||
|
|
import {
|
|||
|
|
buildPlacementResearchMapSystemPrompt,
|
|||
|
|
buildPlacementResearchMapUserPrompt,
|
|||
|
|
} from "./prompts/research-map-placement";
|
|||
|
|
import type { ResearchMap, SuggestedTag } from "@/lib/types/research";
|
|||
|
|
import type { TopicGoal } from "@/lib/types/topic-goal";
|
|||
|
|
import { isPlacementGoal } from "@/lib/types/topic-goal";
|
|||
|
|
import {
|
|||
|
|
explainProviderApiError,
|
|||
|
|
getOpenCodeGenerationSettings,
|
|||
|
|
prefersOpenCodeTextFirst,
|
|||
|
|
} from "./opencode-go-settings";
|
|||
|
|
import { formatProductContextForPrompt } from "@/lib/types/product-context";
|
|||
|
|
import { filterSuggestedTags } from "./normalize-suggested-tags";
|
|||
|
|
import { generateStructuredObject } from "./generate-structured";
|
|||
|
|
|
|||
|
|
export interface AnalyzeTopicInput {
|
|||
|
|
label: string;
|
|||
|
|
query: string;
|
|||
|
|
brief?: string | null;
|
|||
|
|
productContext?: string | null;
|
|||
|
|
topicGoal?: TopicGoal | string | null;
|
|||
|
|
persona?: string | null;
|
|||
|
|
aiProvider: string;
|
|||
|
|
aiModel: string;
|
|||
|
|
apiKeys?: ProviderApiKeys;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const DEFAULT_QUESTIONS = [
|
|||
|
|
"這個主題下，受眾最常感到焦慮的是什麼？",
|
|||
|
|
"有哪些實用資訊是大家都在找的？",
|
|||
|
|
"同溫層想聽什麼樣的親身經驗？",
|
|||
|
|
"哪些迷思需要被釐清？",
|
|||
|
|
"什麼情境下會特別想搜這個主題？",
|
|||
|
|
];
|
|||
|
|
|
|||
|
|
const DEFAULT_PILLARS = ["實用知識", "同溫經驗", "語錄故事", "迷思破解"];
|
|||
|
|
|
|||
|
|
const DEFAULT_EXCLUSIONS = ["業配硬銷", "未查證偏方", "純情緒宣洩"];
|
|||
|
|
|
|||
|
|
function padStringList(items: string[], minimum: number, maximum: number, defaults: string[]) {
|
|||
|
|
const out = items.map((s) => s.trim()).filter(Boolean);
|
|||
|
|
let i = 0;
|
|||
|
|
while (out.length < minimum) {
|
|||
|
|
out.push(defaults[i] ?? `待補充項目 ${out.length + 1}`);
|
|||
|
|
i += 1;
|
|||
|
|
}
|
|||
|
|
return out.slice(0, maximum);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function padSuggestedTags(
|
|||
|
|
tags: SuggestedTag[],
|
|||
|
|
input: AnalyzeTopicInput
|
|||
|
|
): SuggestedTag[] {
|
|||
|
|
return filterSuggestedTags(tags, {
|
|||
|
|
label: input.label,
|
|||
|
|
query: input.query,
|
|||
|
|
brief: input.brief,
|
|||
|
|
topicGoal: input.topicGoal,
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function normalizeResearchMap(
|
|||
|
|
raw: z.infer<typeof researchMapLooseSchema>,
|
|||
|
|
input: AnalyzeTopicInput
|
|||
|
|
): Omit<ResearchMap, "similarAccounts"> {
|
|||
|
|
const questions = padStringList(raw.questions, 5, 8, DEFAULT_QUESTIONS);
|
|||
|
|
const pillars = padStringList(raw.pillars, 4, 6, DEFAULT_PILLARS);
|
|||
|
|
return {
|
|||
|
|
audienceSummary: raw.audienceSummary.trim(),
|
|||
|
|
contentGoal: raw.contentGoal.trim(),
|
|||
|
|
questions,
|
|||
|
|
pillars,
|
|||
|
|
suggestedTags: padSuggestedTags(raw.suggestedTags, input),
|
|||
|
|
exclusions: padStringList(raw.exclusions, 3, 8, DEFAULT_EXCLUSIONS),
|
|||
|
|
};
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const searchTagBatchSchema = z.object({
|
|||
|
|
tags: z.array(z.object({
|
|||
|
|
tag: z.string().min(2).max(10),
|
|||
|
|
reason: z.string().min(1).max(60),
|
|||
|
|
searchIntent: z.enum(["痛點", "知識", "經驗", "對比", "工具", "語錄", "需求", "求助"]),
|
|||
|
|
searchType: z.enum(["短詞", "情境", "語錄"]),
|
|||
|
|
})).min(6).max(8),
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
const UNNATURAL_SEARCH_TAG =
|
|||
|
|
/[，。！？、：；（）()「」【】]|一步步|過程中的|記錄改|的搞|舒適圈的|怎麼交到新|搜尋詞\d|^(這個|哪些|什麼情境)/;
|
|||
|
|
|
|||
|
|
function naturalSearchTags(tags: SuggestedTag[]): SuggestedTag[] {
|
|||
|
|
const seen = new Set<string>();
|
|||
|
|
return tags.filter((item) => {
|
|||
|
|
const tag = item.tag.replace(/^#/, "").trim();
|
|||
|
|
const key = tag.toLowerCase();
|
|||
|
|
if (tag.length < 2 || tag.length > 10 || UNNATURAL_SEARCH_TAG.test(tag)) return false;
|
|||
|
|
if (/的$|才$|要$|會$|怎麼$|如何$/.test(tag)) return false;
|
|||
|
|
if (seen.has(key)) return false;
|
|||
|
|
seen.add(key);
|
|||
|
|
item.tag = tag;
|
|||
|
|
return true;
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async function generateNaturalSearchTags(
|
|||
|
|
model: ReturnType<typeof getModel>,
|
|||
|
|
input: AnalyzeTopicInput,
|
|||
|
|
map: Omit<ResearchMap, "similarAccounts">
|
|||
|
|
): Promise<SuggestedTag[]> {
|
|||
|
|
const placementMode = isPlacementGoal(input.topicGoal);
|
|||
|
|
const modeRules = placementMode
|
|||
|
|
? `你正在替「找 TA」生成需求型搜尋詞：
|
|||
|
|
- 搜尋目標是正在遇到問題、求助、求推薦或準備選購的人，不是泛知識流量
|
|||
|
|
- 至少 5 個詞要帶具體痛點、症狀、使用情境或選購意圖
|
|||
|
|
- 好例子：狗狗皮膚癢、洗毛精推薦、敏感肌洗毛精、在家洗狗、洗完還是臭
|
|||
|
|
- 壞例子：寵物生活、毛孩日常、產品需求、解決方案、內容分享
|
|||
|
|
- 不產語錄、口號或品牌視角文案；每個詞都要能對應一個當下需求
|
|||
|
|
- searchIntent 優先使用「痛點、需求、求助」，不可把品牌行銷詞當成受眾用語`
|
|||
|
|
: `你正在替「拷貝忍者」生成內容型搜尋詞：
|
|||
|
|
- 組合：2 個核心主題、2 個具體痛點、2 個經驗／行動、1 個受眾用語、最多 1 個語錄詞
|
|||
|
|
- 以「宅男變身」為例，好詞是：宅男改造、男生穿搭、體味改善、內向社交、變帥過程、宅男自救`;
|
|||
|
|
const result = await generateStructuredObject({
|
|||
|
|
model,
|
|||
|
|
provider: input.aiProvider,
|
|||
|
|
modelId: input.aiModel,
|
|||
|
|
schema: searchTagBatchSchema,
|
|||
|
|
system: `你是台灣 Threads 站內搜尋策略師。你只負責把研究地圖改寫成真人會輸入搜尋框的詞。
|
|||
|
|
|
|||
|
|
硬性規則：
|
|||
|
|
- 產出 8 個不重複搜尋詞，每個 2～8 個中文字為佳，最長 10 字
|
|||
|
|
- 它是「搜尋詞」，不是文章標題、內容企劃、完整問句或 hashtag
|
|||
|
|
- 禁止把內容支柱直接截斷；必須先理解語意，再壓縮成自然詞組
|
|||
|
|
- 禁止「一步步記錄改」「穿搭的搞」「過程中的黑色」這類殘句
|
|||
|
|
- 除非種子關鍵字或 Brief 明確指定品牌，否則搜尋詞不可自行加入品牌名
|
|||
|
|
- 不要只換同義字湊數；每個詞應能找到不同但仍相關的貼文
|
|||
|
|
- 想像一位台灣使用者真的會在 Threads 搜尋框輸入它
|
|||
|
|
|
|||
|
|
${modeRules}
|
|||
|
|
|
|||
|
|
壞詞範例：變身實戰記錄一步步記錄改。`,
|
|||
|
|
prompt: `主題：${input.label}
|
|||
|
|
種子關鍵字：${input.query}
|
|||
|
|
Brief：${input.brief ?? ""}
|
|||
|
|
受眾：${map.audienceSummary}
|
|||
|
|
受眾問題：${map.questions.join("｜")}
|
|||
|
|
內容支柱：${map.pillars.join("｜")}
|
|||
|
|
排除：${map.exclusions.join("｜")}
|
|||
|
|
|
|||
|
|
請重新產出自然、可搜尋的 Threads 搜尋詞。`,
|
|||
|
|
jsonPromptSuffix: `\n\n只回傳 JSON，不要 markdown。tags 必須恰好 8 筆且 tag 不可重複：\n{"tags":[{"tag":"2到8字搜尋詞1","reason":"搜尋意圖","searchIntent":"經驗","searchType":"短詞"},{"tag":"2到8字搜尋詞2","reason":"搜尋意圖","searchIntent":"痛點","searchType":"情境"},{"tag":"2到8字搜尋詞3","reason":"搜尋意圖","searchIntent":"知識","searchType":"短詞"},{"tag":"2到8字搜尋詞4","reason":"搜尋意圖","searchIntent":"工具","searchType":"情境"},{"tag":"2到8字搜尋詞5","reason":"搜尋意圖","searchIntent":"經驗","searchType":"情境"},{"tag":"2到8字搜尋詞6","reason":"搜尋意圖","searchIntent":"對比","searchType":"短詞"},{"tag":"2到8字搜尋詞7","reason":"搜尋意圖","searchIntent":"痛點","searchType":"情境"},{"tag":"2到8字搜尋詞8","reason":"搜尋意圖","searchIntent":"語錄","searchType":"語錄"}]}`,
|
|||
|
|
});
|
|||
|
|
const natural = naturalSearchTags(result.tags);
|
|||
|
|
return placementMode
|
|||
|
|
? natural.filter((tag) => tag.searchIntent !== "語錄" && tag.searchType !== "語錄")
|
|||
|
|
: natural;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export async function regenerateSearchTags(
|
|||
|
|
input: AnalyzeTopicInput,
|
|||
|
|
map: Omit<ResearchMap, "similarAccounts">
|
|||
|
|
): Promise<SuggestedTag[]> {
|
|||
|
|
const model = getModel(input.aiProvider, input.aiModel, input.apiKeys ?? {});
|
|||
|
|
const tags = await generateNaturalSearchTags(model, input, map);
|
|||
|
|
if (tags.length < 6) {
|
|||
|
|
throw new Error(`AI 只產出 ${tags.length} 個可用搜尋詞，未達 6 個，請重試或更換研究模型`);
|
|||
|
|
}
|
|||
|
|
return tags.slice(0, 8);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export function formatAnalyzeError(error: unknown): string {
|
|||
|
|
if (typeof error === "string") return error;
|
|||
|
|
if (error instanceof z.ZodError) {
|
|||
|
|
const detail = error.issues
|
|||
|
|
.slice(0, 4)
|
|||
|
|
.map((issue) => {
|
|||
|
|
const field = issue.path.join(".") || "回傳內容";
|
|||
|
|
return `${field}：${issue.message}`;
|
|||
|
|
})
|
|||
|
|
.join("；");
|
|||
|
|
return `AI 回傳的研究地圖格式不完整（${detail}）。請再按一次「AI 分析主題」重試。`;
|
|||
|
|
}
|
|||
|
|
if (error instanceof Error) {
|
|||
|
|
const extra = error as Error & { responseBody?: string };
|
|||
|
|
const explained = explainProviderApiError(
|
|||
|
|
error.message,
|
|||
|
|
typeof extra.responseBody === "string" ? extra.responseBody : undefined
|
|||
|
|
);
|
|||
|
|
if (explained) return explained;
|
|||
|
|
return error.message;
|
|||
|
|
}
|
|||
|
|
return "AI 分析失敗";
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function buildJsonPromptSuffix(): string {
|
|||
|
|
return `
|
|||
|
|
|
|||
|
|
請只回傳 JSON（不要 markdown），格式：
|
|||
|
|
{
|
|||
|
|
"audienceSummary": "string",
|
|||
|
|
"contentGoal": "string",
|
|||
|
|
"questions": ["string", "..."],
|
|||
|
|
"pillars": ["string", "..."],
|
|||
|
|
"suggestedTags": [
|
|||
|
|
{"tag":"2-4字短詞","reason":"為什麼搜","searchIntent":"痛點|知識|經驗|對比|工具|語錄","searchType":"短詞|情境|語錄"}
|
|||
|
|
],
|
|||
|
|
"exclusions": ["string", "..."]
|
|||
|
|
}
|
|||
|
|
questions 至少 5 個、pillars 至少 4 個、suggestedTags 10～14 個、exclusions 至少 3 個。不要輸出 similarAccounts。`;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function resolvePrompts(input: AnalyzeTopicInput) {
|
|||
|
|
if (isPlacementGoal(input.topicGoal)) {
|
|||
|
|
const brief = input.brief?.trim() || `主題是「${input.query}」。`;
|
|||
|
|
const productContext = formatProductContextForPrompt(input.productContext);
|
|||
|
|
const persona =
|
|||
|
|
input.persona?.trim() ||
|
|||
|
|
"專業、願意提供實用建議的品牌代表，語氣自然不硬銷。";
|
|||
|
|
return {
|
|||
|
|
system: buildPlacementResearchMapSystemPrompt(),
|
|||
|
|
prompt: buildPlacementResearchMapUserPrompt({
|
|||
|
|
label: input.label,
|
|||
|
|
query: input.query,
|
|||
|
|
brief,
|
|||
|
|
productContext,
|
|||
|
|
persona,
|
|||
|
|
}),
|
|||
|
|
};
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const brief = input.brief?.trim()
|
|||
|
|
? input.brief.trim()
|
|||
|
|
: `主題是「${input.query}」。請假設受眾是台灣 25～40 歲、會在 Threads 找資訊與同溫感的一般使用者。`;
|
|||
|
|
const persona = input.persona?.trim()
|
|||
|
|
? input.persona.trim()
|
|||
|
|
: "專業、有觀點、願意分享實用資訊的 Threads 創作者，語氣自然不說教。";
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
system: buildResearchMapSystemPrompt(),
|
|||
|
|
prompt: buildResearchMapUserPrompt({
|
|||
|
|
label: input.label,
|
|||
|
|
query: input.query,
|
|||
|
|
brief,
|
|||
|
|
persona,
|
|||
|
|
}),
|
|||
|
|
};
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async function generateWithText(
|
|||
|
|
model: ReturnType<typeof getModel>,
|
|||
|
|
prompt: string,
|
|||
|
|
system: string,
|
|||
|
|
fallback: { label: string; query: string; brief: string },
|
|||
|
|
provider: string,
|
|||
|
|
modelId: string
|
|||
|
|
) {
|
|||
|
|
const settings = getOpenCodeGenerationSettings(provider, modelId);
|
|||
|
|
const { text } = await generateText({
|
|||
|
|
model,
|
|||
|
|
system: `${system}${buildJsonPromptSuffix()}`,
|
|||
|
|
prompt,
|
|||
|
|
...settings,
|
|||
|
|
});
|
|||
|
|
const parsed = extractJsonFromText(text);
|
|||
|
|
return coerceResearchMapRaw(parsed, fallback);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async function generateWithObject(
|
|||
|
|
model: ReturnType<typeof getModel>,
|
|||
|
|
prompt: string,
|
|||
|
|
system: string,
|
|||
|
|
fallback: { label: string; query: string; brief: string },
|
|||
|
|
provider: string,
|
|||
|
|
modelId: string
|
|||
|
|
) {
|
|||
|
|
const settings = getOpenCodeGenerationSettings(provider, modelId);
|
|||
|
|
const result = await generateObject({
|
|||
|
|
model,
|
|||
|
|
schema: researchMapLooseSchema,
|
|||
|
|
system,
|
|||
|
|
prompt: `${prompt}${buildJsonPromptSuffix()}`,
|
|||
|
|
...settings,
|
|||
|
|
});
|
|||
|
|
return coerceResearchMapRaw(result.object, fallback);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export async function analyzeTopicIntent(
|
|||
|
|
input: AnalyzeTopicInput
|
|||
|
|
): Promise<Omit<ResearchMap, "similarAccounts">> {
|
|||
|
|
const model = getModel(input.aiProvider, input.aiModel, input.apiKeys ?? {});
|
|||
|
|
|
|||
|
|
const { system, prompt } = resolvePrompts(input);
|
|||
|
|
const brief = input.brief?.trim() || `主題是「${input.query}」。`;
|
|||
|
|
const fallback = { label: input.label, query: input.query, brief };
|
|||
|
|
const preferText = prefersOpenCodeTextFirst(input.aiProvider, input.aiModel);
|
|||
|
|
|
|||
|
|
let raw: z.infer<typeof researchMapLooseSchema> | null = null;
|
|||
|
|
let lastError: unknown;
|
|||
|
|
|
|||
|
|
const attempts: Array<() => Promise<z.infer<typeof researchMapLooseSchema>>> = preferText
|
|||
|
|
? [
|
|||
|
|
() => generateWithText(model, prompt, system, fallback, input.aiProvider, input.aiModel),
|
|||
|
|
() => generateWithObject(model, prompt, system, fallback, input.aiProvider, input.aiModel),
|
|||
|
|
() =>
|
|||
|
|
generateWithText(
|
|||
|
|
model,
|
|||
|
|
`${prompt}\n\n上次格式不完整，請務必補齊所有欄位。`,
|
|||
|
|
system,
|
|||
|
|
fallback,
|
|||
|
|
input.aiProvider,
|
|||
|
|
input.aiModel
|
|||
|
|
),
|
|||
|
|
]
|
|||
|
|
: [
|
|||
|
|
() => generateWithObject(model, prompt, system, fallback, input.aiProvider, input.aiModel),
|
|||
|
|
() => generateWithText(model, prompt, system, fallback, input.aiProvider, input.aiModel),
|
|||
|
|
() =>
|
|||
|
|
generateWithText(
|
|||
|
|
model,
|
|||
|
|
`${prompt}\n\n上次格式不完整，請務必補齊所有欄位。`,
|
|||
|
|
system,
|
|||
|
|
fallback,
|
|||
|
|
input.aiProvider,
|
|||
|
|
input.aiModel
|
|||
|
|
),
|
|||
|
|
];
|
|||
|
|
|
|||
|
|
for (const attempt of attempts) {
|
|||
|
|
try {
|
|||
|
|
raw = await attempt();
|
|||
|
|
break;
|
|||
|
|
} catch (error) {
|
|||
|
|
lastError = error;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (!raw) {
|
|||
|
|
throw formatAnalyzeError(lastError);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
try {
|
|||
|
|
let normalized = normalizeResearchMap(raw, input);
|
|||
|
|
{
|
|||
|
|
try {
|
|||
|
|
const rewritten = await generateNaturalSearchTags(model, input, normalized);
|
|||
|
|
if (rewritten.length >= 6) {
|
|||
|
|
normalized = { ...normalized, suggestedTags: rewritten.slice(0, 8) };
|
|||
|
|
}
|
|||
|
|
} catch (error) {
|
|||
|
|
console.warn("[analyze-topic] natural search tag rewrite failed:", error);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
return normalized;
|
|||
|
|
} catch (error) {
|
|||
|
|
throw formatAnalyzeError(error);
|
|||
|
|
}
|
|||
|
|
}
|