@folio-agent/handler 0.6.0 → 0.6.2

package/README.md

@@ -17,15 +17,17 @@ npx folio-agent-ingest folio-agent.config.json knowledge.json
 ```
 
 ```ts
-import { createChatHandler, createGeminiGenerator } from "@folio-agent/handler";
+import { collectAnswerLinks, createChatHandler, createGeminiGenerator, formatKnowledge } from "@folio-agent/handler";
 import knowledgeDoc from "../knowledge.json";
 
-const knowledge = knowledgeDoc.pages.map((p) => `# ${p.url}\n\n${p.text}`).join("\n\n");
+const knowledge = formatKnowledge(knowledgeDoc);
+const answerLinks = collectAnswerLinks(knowledgeDoc);
 
 export default {
   fetch: (request: Request, env: { DB: D1Database; GEMINI_API_KEY: string }) =>
     createChatHandler({
       db: env.DB,
+      answerLinks,
       generateAnswer: createGeminiGenerator({ apiKey: env.GEMINI_API_KEY, knowledge }),
     })(request),
 };

package/dist/chat/answer/links.d.ts

@@ -0,0 +1,13 @@
+import type { KnowledgePagesLike } from "../../ingest/types.js";
+import type { Language } from "../types.js";
+/** A destination an answer may link to, and the text to show when the model wrote the bare URL. */
+export interface AnswerLink {
+    url: string;
+    title: string;
+}
+/**
+ * Lists what an answer may link to: pages outside this site that are in the knowledge (such as
+ * Zenn articles) and the Contact page. This site's own pages are left out on purpose; the visitor
+ * is already on the site, so answers name them instead of linking them.
+ */
+export declare function collectAnswerLinks(doc: KnowledgePagesLike, contactUrl?: string, language?: Language): AnswerLink[];

package/dist/chat/answer/links.js

@@ -0,0 +1,18 @@
+import { DEFAULT_LANGUAGE } from "../types.js";
+const CONTACT_TITLE = {
+    ja: "Contactページ",
+    en: "Contact page",
+};
+/**
+ * Lists what an answer may link to: pages outside this site that are in the knowledge (such as
+ * Zenn articles) and the Contact page. This site's own pages are left out on purpose; the visitor
+ * is already on the site, so answers name them instead of linking them.
+ */
+export function collectAnswerLinks(doc, contactUrl, language = DEFAULT_LANGUAGE) {
+    const links = doc.pages
+        .filter((page) => /^https?:\/\//i.test(page.url))
+        .map((page) => ({ url: page.url, title: page.title }));
+    if (contactUrl)
+        links.push({ url: contactUrl, title: CONTACT_TITLE[language] });
+    return links;
+}

package/dist/chat/answer/normalize.d.ts

@@ -0,0 +1,7 @@
+import type { AnswerLink } from "./links.js";
+/**
+ * Brings a generated answer into the answer format, whatever the model actually produced. The
+ * prompt only asks for the format (prompt/answer-format.ts); this is where it is enforced, so the
+ * widget can rely on it.
+ */
+export declare function normalizeAnswer(answer: string, links?: AnswerLink[]): string;

package/dist/chat/answer/normalize.js

@@ -0,0 +1,48 @@
+// 回答の形式（handler と widget のあいだの決まり）:
+//   プレーンテキスト。段落は空行で区切る。記法はリンクの [表示する文字](http(s)://…) だけ。
+//   リンク先は answerLinks に含まれる URL だけ。
+const MARKDOWN_LINK = /\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)/g;
+const BARE_URL = /https?:\/\/[^\s<>"'（）「」『』【】、。]+/g;
+const TRAILING_PUNCTUATION = /[.,;:!?)\]]+$/;
+const PLACEHOLDER = /\u0000(\d+)\u0000/g;
+function linkKey(url) {
+    return url.replace(/\/+$/, "");
+}
+function stripInlineMarkdown(text) {
+    return text
+        .replace(/\*\*(.+?)\*\*/g, "$1")
+        .replace(/__(.+?)__/g, "$1")
+        .replace(/`([^`\n]+)`/g, "$1");
+}
+/**
+ * Brings a generated answer into the answer format, whatever the model actually produced. The
+ * prompt only asks for the format (prompt/answer-format.ts); this is where it is enforced, so the
+ * widget can rely on it.
+ */
+export function normalizeAnswer(answer, links = []) {
+    const allowed = new Map(links.map((link) => [linkKey(link.url), link]));
+    const kept = [];
+    const keep = (label, url) => {
+        kept.push(`[${stripInlineMarkdown(label)}](${url})`);
+        return `\u0000${kept.length - 1}\u0000`;
+    };
+    let text = answer.replace(MARKDOWN_LINK, (_, label, url) => {
+        const link = allowed.get(linkKey(url));
+        return link ? keep(label, link.url) : label;
+    });
+    // URL をそのまま書かれた場合は、許可されたものだけタイトルのリンクに置き換え、それ以外は消す
+    text = text.replace(BARE_URL, (match) => {
+        const url = match.replace(TRAILING_PUNCTUATION, "");
+        const rest = match.slice(url.length);
+        const link = allowed.get(linkKey(url));
+        return link ? keep(link.title, link.url) + rest : rest;
+    });
+    text = stripInlineMarkdown(text)
+        .replace(/^#{1,6}[ \t]+/gm, "")
+        .replace(/^[ \t]*[-*][ \t]+/gm, "・")
+        .replace(/（\s*）|\(\s*\)/g, "")
+        .replace(PLACEHOLDER, (_, index) => kept[Number(index)])
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n");
+    return text.trim();
+}

package/dist/chat/gemini.d.ts

@@ -1,5 +1,4 @@
 import type { ChatRoute, Language } from "./types.js";
-export declare function buildSystemPrompt(knowledge: string, route: Exclude<ChatRoute, "rate_limited">, contactUrl?: string, language?: Language): string;
 export interface GeminiGeneratorConfig {
     apiKey: string;
     knowledge: string;

package/dist/chat/gemini.js

@@ -1,53 +1,6 @@
 import { GoogleGenAI } from "@google/genai";
+import { buildSystemPrompt } from "./prompt/index.js";
 import { DEFAULT_LANGUAGE } from "./types.js";
-const COMMON_PREAMBLE = {
-    ja: "あなたはポートフォリオサイト作者の代理として応対する受付エージェントです。" +
-        "丁寧だが簡潔で自然な口語で話し、「お問い合わせいただきありがとうございます」のような定型の前置き挨拶はしません。" +
-        "回答は原則3〜4文以内にまとめてください。\n\n" +
-        "以下の知識に書かれていることだけから答えてください。書かれていないことは推測・創作せず、" +
-        "「その点はサイトに記載がない」と伝えたうえでContactページを案内してください。" +
-        "用語の正式名称・展開形も、知識に書かれていなければ創作しないでください。\n\n" +
-        "Markdown記法（`**`・`#`・`-`のリストなど）は使わず、プレーンテキストで答えてください。" +
-        "回答が長くなる場合は、2〜4文ごとに空行を挟んで段落を分けてください。",
-    en: "You are a receptionist agent responding on behalf of the portfolio site's author. " +
-        'Speak politely but concisely and naturally, without formulaic openers such as "Thank you for reaching out." ' +
-        "Keep your answers to about 3-4 sentences.\n\n" +
-        "Only answer based on the knowledge provided below. Do not guess or invent anything that isn't written there — " +
-        "say that the site doesn't cover that point, then guide the visitor to the Contact page. " +
-        "Do not invent official names or expansions of terms that aren't in the knowledge either.\n\n" +
-        "Do not use Markdown formatting (such as `**`, `#`, or `-` lists) — answer in plain text. " +
-        "If the answer runs long, insert a blank line every 2-4 sentences to break it into paragraphs.",
-};
-const ROUTE_INSTRUCTIONS = {
-    ja: {
-        thoughts: "訪問者は作者の考え方について質問しています。知識の内容に沿って考え方を説明してください。",
-        works: "訪問者はWorks（作品）について質問しています。知識に書かれた内容から解説し、" +
-            "対応するZenn記事へのリンクが知識中にあれば案内してください。",
-        inquiry: "訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページへの問い合わせを案内してください。",
-    },
-    en: {
-        thoughts: "The visitor is asking about the author's thinking. Explain it based on the knowledge provided.",
-        works: "The visitor is asking about Works (projects). Explain based on the knowledge, and if a link to the " +
-            "corresponding Zenn article is included in the knowledge, share it.",
-        inquiry: "The visitor wants to discuss hiring or a project request. Respond briefly, then guide them to contact via the Contact page.",
-    },
-};
-const KNOWLEDGE_LABEL = {
-    ja: "---- 知識 ----",
-    en: "---- Knowledge ----",
-};
-function buildInquiryInstruction(language, contactUrl) {
-    if (contactUrl) {
-        return language === "en"
-            ? `The visitor wants to discuss hiring or a project request. Respond briefly, then guide them to contact via the Contact page (${contactUrl}).`
-            : `訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページ（${contactUrl}）への問い合わせを案内してください。`;
-    }
-    return ROUTE_INSTRUCTIONS[language].inquiry;
-}
-export function buildSystemPrompt(knowledge, route, contactUrl, language = DEFAULT_LANGUAGE) {
-    const routeInstruction = route === "inquiry" ? buildInquiryInstruction(language, contactUrl) : ROUTE_INSTRUCTIONS[language][route];
-    return [COMMON_PREAMBLE[language], routeInstruction, KNOWLEDGE_LABEL[language], knowledge].join("\n\n");
-}
 export function createGeminiGenerator(config) {
     const client = new GoogleGenAI({ apiKey: config.apiKey });
     const model = config.model ?? "gemini-3.1-flash-lite";

package/dist/chat/graph.d.ts

@@ -11,7 +11,7 @@ export declare function buildChatGraph(deps: ChatGraphDeps): import("@langchain/
     route?: ChatRoute | undefined;
     overLimit?: boolean | undefined;
     answer?: string | undefined;
-}, "__start__" | "generate" | "input_guard" | "log" | "route_message", {
+}, "__start__" | "generate" | "input_guard" | "log" | "normalize_answer" | "route_message", {
     input: import("@langchain/langgraph").LastValue<string>;
     ip: import("@langchain/langgraph").LastValue<string>;
     route: import("@langchain/langgraph").LastValue<ChatRoute | undefined>;
@@ -35,6 +35,9 @@ export declare function buildChatGraph(deps: ChatGraphDeps): import("@langchain/
         overLimit: false;
     };
     log: {};
+    normalize_answer: {
+        answer: string;
+    };
     route_message: {
         route: "inquiry" | "thoughts" | "works";
     };

package/dist/chat/graph.js

@@ -1,4 +1,5 @@
 import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
+import { normalizeAnswer } from "./answer/normalize.js";
 import { classifyRoute } from "./route.js";
 import { DEFAULT_LANGUAGE } from "./types.js";
 const OVER_LIMIT_MESSAGE = {
@@ -43,6 +44,7 @@ export function buildChatGraph(deps) {
             return { answer: GENERATION_FAILED_MESSAGE[language] };
         }
     })
+        .addNode("normalize_answer", async (state) => ({ answer: normalizeAnswer(state.answer ?? "", deps.answerLinks) }))
         .addNode("log", async (state) => {
         await deps.logChat({
             ip: state.ip,
@@ -59,7 +61,8 @@ export function buildChatGraph(deps) {
         route_message: "route_message",
     })
         .addEdge("route_message", "generate")
-        .addEdge("generate", "log")
+        .addEdge("generate", "normalize_answer")
+        .addEdge("normalize_answer", "log")
         .addEdge("log", END);
     return graph.compile();
 }

package/dist/chat/handler.d.ts

@@ -1,3 +1,4 @@
+import type { AnswerLink } from "./answer/links.js";
 import type { GenerateAnswerFn } from "./gemini.js";
 import type { Language, RateLimitConfig } from "./types.js";
 export interface ChatHandlerConfig {
@@ -5,5 +6,10 @@ export interface ChatHandlerConfig {
     generateAnswer: GenerateAnswerFn;
     rateLimitConfig?: RateLimitConfig;
     language?: Language;
+    /**
+     * What answers may link to, usually `collectAnswerLinks(knowledgeDoc, contactUrl)`. When omitted,
+     * every link in an answer is reduced to its text.
+     */
+    answerLinks?: AnswerLink[];
 }
 export declare function createChatHandler(config: ChatHandlerConfig): (request: Request) => Promise<Response>;

package/dist/chat/handler.js

@@ -11,6 +11,7 @@ export function createChatHandler(config) {
         logChat: (entry) => logChat(config.db, entry),
         rateLimitConfig,
         language: config.language,
+        answerLinks: config.answerLinks,
     });
     return async (request) => {
         let body;

package/dist/chat/prompt/answer-format.d.ts

@@ -0,0 +1,2 @@
+import type { Language } from "../types.js";
+export declare const ANSWER_FORMAT: Record<Language, string>;

package/dist/chat/prompt/answer-format.js

@@ -0,0 +1,15 @@
+// 回答の形式（handler と widget のあいだの決まり）。指示で頼む側で、守らせるのは answer/ の normalize。
+export const ANSWER_FORMAT = {
+    ja: "Markdown記法（`**`・`#`・`-`のリストなど）は使わず、プレーンテキストで答えてください。" +
+        "回答が長くなる場合は、2〜4文ごとに空行を挟んで段落を分けてください。\n\n" +
+        "リンクを示すときだけは [表示する文字](URL) の形で書いてください。URLをそのまま書かず、" +
+        "記事ならそのタイトル、Contactページなら「Contactページ」を表示する文字にします。" +
+        "訪問者はいまこのサイトを見ているので、このサイト内のページはリンクにせず「Aboutページ」のようにページ名で案内してください。" +
+        "リンクにしてよいのは、Contactページと、知識に「URL: https://…」として書かれたこのサイトの外のページだけです。",
+    en: "Do not use Markdown formatting (such as `**`, `#`, or `-` lists) — answer in plain text. " +
+        "If the answer runs long, insert a blank line every 2-4 sentences to break it into paragraphs.\n\n" +
+        "The one exception is links: write them as [text to show](URL). Never show a bare URL; " +
+        'use the article title for an article, and "Contact page" for the Contact page. ' +
+        "The visitor is already on this site, so refer to this site's pages by name (e.g. \"the About page\") instead of linking them. " +
+        'Only link the Contact page and pages outside this site that appear in the knowledge as "URL: https://…".',
+};

package/dist/chat/prompt/grounding.d.ts

@@ -0,0 +1,2 @@
+import type { Language } from "../types.js";
+export declare const GROUNDING: Record<Language, string>;

package/dist/chat/prompt/grounding.js

@@ -0,0 +1,9 @@
+// 知識に書いてあることだけで答え、創作しない。
+export const GROUNDING = {
+    ja: "以下の知識に書かれていることだけから答えてください。書かれていないことは推測・創作せず、" +
+        "「その点はサイトに記載がない」と伝えたうえでContactページを案内してください。" +
+        "用語の正式名称・展開形も、知識に書かれていなければ創作しないでください。",
+    en: "Only answer based on the knowledge provided below. Do not guess or invent anything that isn't written there — " +
+        "say that the site doesn't cover that point, then guide the visitor to the Contact page. " +
+        "Do not invent official names or expansions of terms that aren't in the knowledge either.",
+};

package/dist/chat/prompt/index.d.ts

@@ -0,0 +1,2 @@
+import type { ChatRoute, Language } from "../types.js";
+export declare function buildSystemPrompt(knowledge: string, route: Exclude<ChatRoute, "rate_limited">, contactUrl?: string, language?: Language): string;

package/dist/chat/prompt/index.js

@@ -0,0 +1,13 @@
+import { DEFAULT_LANGUAGE } from "../types.js";
+import { ANSWER_FORMAT } from "./answer-format.js";
+import { GROUNDING } from "./grounding.js";
+import { PERSONA } from "./persona.js";
+import { buildInquiryInstruction, ROUTE_INSTRUCTIONS } from "./routes.js";
+const KNOWLEDGE_LABEL = {
+    ja: "---- 知識 ----",
+    en: "---- Knowledge ----",
+};
+export function buildSystemPrompt(knowledge, route, contactUrl, language = DEFAULT_LANGUAGE) {
+    const routeInstruction = route === "inquiry" ? buildInquiryInstruction(language, contactUrl) : ROUTE_INSTRUCTIONS[language][route];
+    return [PERSONA[language], GROUNDING[language], ANSWER_FORMAT[language], routeInstruction, KNOWLEDGE_LABEL[language], knowledge].join("\n\n");
+}

package/dist/chat/prompt/persona.d.ts

@@ -0,0 +1,2 @@
+import type { Language } from "../types.js";
+export declare const PERSONA: Record<Language, string>;

package/dist/chat/prompt/persona.js

@@ -0,0 +1,9 @@
+// 役割・口調・長さ。
+export const PERSONA = {
+    ja: "あなたはポートフォリオサイト作者の代理として応対する受付エージェントです。" +
+        "丁寧だが簡潔で自然な口語で話し、「お問い合わせいただきありがとうございます」のような定型の前置き挨拶はしません。" +
+        "回答は原則3〜4文以内にまとめてください。",
+    en: "You are a receptionist agent responding on behalf of the portfolio site's author. " +
+        'Speak politely but concisely and naturally, without formulaic openers such as "Thank you for reaching out." ' +
+        "Keep your answers to about 3-4 sentences.",
+};

package/dist/chat/prompt/routes.d.ts

@@ -0,0 +1,3 @@
+import type { ChatRoute, Language } from "../types.js";
+export declare const ROUTE_INSTRUCTIONS: Record<Language, Record<Exclude<ChatRoute, "rate_limited">, string>>;
+export declare function buildInquiryInstruction(language: Language, contactUrl?: string): string;

package/dist/chat/prompt/routes.js

@@ -0,0 +1,22 @@
+export const ROUTE_INSTRUCTIONS = {
+    ja: {
+        thoughts: "訪問者は作者の考え方について質問しています。知識の内容に沿って考え方を説明してください。",
+        works: "訪問者はWorks（作品）について質問しています。知識に書かれた内容から解説し、" +
+            "対応するZenn記事へのリンクが知識中にあれば案内してください。",
+        inquiry: "訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページへの問い合わせを案内してください。",
+    },
+    en: {
+        thoughts: "The visitor is asking about the author's thinking. Explain it based on the knowledge provided.",
+        works: "The visitor is asking about Works (projects). Explain based on the knowledge, and if a link to the " +
+            "corresponding Zenn article is included in the knowledge, share it.",
+        inquiry: "The visitor wants to discuss hiring or a project request. Respond briefly, then guide them to contact via the Contact page.",
+    },
+};
+export function buildInquiryInstruction(language, contactUrl) {
+    if (contactUrl) {
+        return language === "en"
+            ? `The visitor wants to discuss hiring or a project request. Respond briefly, then guide them to contact via the Contact page (${contactUrl}).`
+            : `訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページ（${contactUrl}）への問い合わせを案内してください。`;
+    }
+    return ROUTE_INSTRUCTIONS[language].inquiry;
+}

package/dist/chat/types.d.ts

@@ -1,3 +1,4 @@
+import type { AnswerLink } from "./answer/links.js";
 export type ChatRoute = "thoughts" | "works" | "inquiry" | "rate_limited";
 export type Language = "ja" | "en";
 export declare const DEFAULT_LANGUAGE: Language;
@@ -26,4 +27,6 @@ export interface ChatGraphDeps {
     logChat: (entry: ChatLogEntry) => Promise<void>;
     rateLimitConfig: RateLimitConfig;
     language?: Language;
+    /** What answers may link to. Links to anything else are reduced to their text. */
+    answerLinks?: AnswerLink[];
 }

package/dist/index.d.ts

@@ -1,12 +1,16 @@
 export { generateKnowledge } from "./ingest/generate.js";
 export { createUrlMatcher } from "./ingest/glob.js";
 export { htmlToText } from "./ingest/html-to-text.js";
-export type { IngestConfig, KnowledgeDocument, KnowledgePage, KnowledgeSource, ZennIngestConfig, } from "./ingest/types.js";
+export { formatKnowledge } from "./ingest/format.js";
+export type { IngestConfig, KnowledgeDocument, KnowledgePage, KnowledgePagesLike, KnowledgeSource, ZennIngestConfig, } from "./ingest/types.js";
 export { createChatHandler } from "./chat/handler.js";
 export type { ChatHandlerConfig } from "./chat/handler.js";
 export { buildChatGraph } from "./chat/graph.js";
 export { checkRateLimit } from "./chat/rate-limit.js";
-export { createGeminiGenerator, buildSystemPrompt } from "./chat/gemini.js";
+export { createGeminiGenerator } from "./chat/gemini.js";
+export { buildSystemPrompt } from "./chat/prompt/index.js";
+export { collectAnswerLinks } from "./chat/answer/links.js";
+export type { AnswerLink } from "./chat/answer/links.js";
 export type { GenerateAnswerFn, GeminiGeneratorConfig } from "./chat/gemini.js";
 export { classifyRoute } from "./chat/route.js";
 export { logChat } from "./chat/log.js";

package/dist/index.js

@@ -1,10 +1,13 @@
 export { generateKnowledge } from "./ingest/generate.js";
 export { createUrlMatcher } from "./ingest/glob.js";
 export { htmlToText } from "./ingest/html-to-text.js";
+export { formatKnowledge } from "./ingest/format.js";
 export { createChatHandler } from "./chat/handler.js";
 export { buildChatGraph } from "./chat/graph.js";
 export { checkRateLimit } from "./chat/rate-limit.js";
-export { createGeminiGenerator, buildSystemPrompt } from "./chat/gemini.js";
+export { createGeminiGenerator } from "./chat/gemini.js";
+export { buildSystemPrompt } from "./chat/prompt/index.js";
+export { collectAnswerLinks } from "./chat/answer/links.js";
 export { classifyRoute } from "./chat/route.js";
 export { logChat } from "./chat/log.js";
 export { DEFAULT_RATE_LIMIT_CONFIG } from "./chat/types.js";

package/dist/ingest/format.d.ts

@@ -0,0 +1,6 @@
+import type { KnowledgePagesLike } from "./types.js";
+/**
+ * Turns a knowledge document into the text handed to the system prompt. Each page carries its
+ * title and URL so answers can point to an article by its title instead of a bare URL.
+ */
+export declare function formatKnowledge(doc: KnowledgePagesLike): string;

package/dist/ingest/format.js

@@ -0,0 +1,7 @@
+/**
+ * Turns a knowledge document into the text handed to the system prompt. Each page carries its
+ * title and URL so answers can point to an article by its title instead of a bare URL.
+ */
+export function formatKnowledge(doc) {
+    return doc.pages.map((page) => `# ${page.title}\nURL: ${page.url}\n\n${page.text}`).join("\n\n");
+}

package/dist/ingest/types.d.ts

@@ -45,6 +45,13 @@ export interface KnowledgePage {
     title: string;
     text: string;
 }
+/**
+ * The part of a knowledge document that answering needs. A `knowledge.json` imported as JSON
+ * types `source` as a plain string, so helpers take this rather than `KnowledgeDocument`.
+ */
+export interface KnowledgePagesLike {
+    pages: ReadonlyArray<Pick<KnowledgePage, "url" | "title" | "text">>;
+}
 export interface KnowledgeDocument {
     generatedAt: string;
     pages: KnowledgePage[];

package/dist/init/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_API_ROUTE_PATH, InitArgsError, resolveInitRun, USAGE } from "./options.js";
 import { appendIngestToBuildScript, buildApiRouteTemplate, buildConfigJson, buildThemeCss, deriveEndpointPath, ensureGitignoreEntry, PUBLIC_DIR_NAME, resolveThemeCssPath, THEME_CSS_FILENAME, upsertDevVar, } from "./writers.js";
@@ -9,7 +9,6 @@ const CONFIG_PATH = "folio-agent.config.json";
 const PACKAGE_JSON_PATH = "package.json";
 const DEV_VARS_PATH = ".dev.vars";
 const GITIGNORE_PATH = ".gitignore";
-const KNOWLEDGE_OUTPUT_PATH = "dist/knowledge.json";
 async function readJson(path) {
     if (!existsSync(path))
         return undefined;
@@ -69,7 +68,9 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
         : undefined;
     const pkg = (await readJson(PACKAGE_JSON_PATH)) ?? {};
     const scripts = pkg.scripts ?? {};
-    const nextBuildScript = appendIngestToBuildScript(scripts.build, CONFIG_PATH, KNOWLEDGE_OUTPUT_PATH);
+    // API ルート雛形は <distDir>/knowledge.json を import するので、出力先もそこに揃える
+    const knowledgeOutputPath = posix.join(answers.distDir, "knowledge.json");
+    const nextBuildScript = appendIngestToBuildScript(scripts.build, CONFIG_PATH, knowledgeOutputPath);
     const buildScriptChanged = nextBuildScript !== (scripts.build ?? "");
     const { nextDevVars, gitignoreResult } = planDevVarsAndGitignore(answers.geminiApiKey, await readTextOrEmpty(DEV_VARS_PATH), await readTextOrEmpty(GITIGNORE_PATH));
     const plan = [

package/dist/init/writers.d.ts

@@ -29,7 +29,11 @@ export interface ApiRouteAnswers {
 }
 /** Builds a minimal Cloudflare Pages Function that wires up `createChatHandler`. */
 export declare function buildApiRouteTemplate(answers: ApiRouteAnswers): string;
-/** Appends the ingest command to a `build` script if it isn't already present; otherwise returns it unchanged. */
+/**
+ * Appends the ingest command to a `build` script unless it already runs ingest. Any existing
+ * `folio-agent-ingest` counts, whatever its arguments: sites often write to a different output
+ * path than the default, and appending a second run would ingest twice.
+ */
 export declare function appendIngestToBuildScript(buildScript: string | undefined, configPath: string, knowledgeOutputPath: string): string;
 /** Adds or replaces a single `KEY=value` line in `.dev.vars` content, leaving other lines untouched. */
 export declare function upsertDevVar(content: string, key: string, value: string): string;

package/dist/init/writers.js

@@ -64,13 +64,23 @@ export function deriveEndpointPath(apiRoutePath) {
 /** Builds a minimal Cloudflare Pages Function that wires up `createChatHandler`. */
 export function buildApiRouteTemplate(answers) {
     const knowledgeImportPath = buildKnowledgeImportPath(answers.apiRoutePath, answers.distDir);
-    const languageLine = answers.language === DEFAULT_LANGUAGE ? "" : `\n    language: ${JSON.stringify(answers.language)},`;
-    const contactUrlLine = answers.contactUrl ? `\n      contactUrl: ${JSON.stringify(answers.contactUrl)},` : "";
+    const nonDefaultLanguage = answers.language === DEFAULT_LANGUAGE ? undefined : JSON.stringify(answers.language);
+    const languageLine = nonDefaultLanguage ? `\n    language: ${nonDefaultLanguage},` : "";
+    const generatorLanguageLine = nonDefaultLanguage ? `\n      language: ${nonDefaultLanguage},` : "";
+    const contactUrlConst = answers.contactUrl ? [`const CONTACT_URL = ${JSON.stringify(answers.contactUrl)};`, ""] : [];
+    const contactUrlLine = answers.contactUrl ? "\n      contactUrl: CONTACT_URL," : "";
+    const linkArgs = [
+        "knowledgeDoc",
+        ...(answers.contactUrl || nonDefaultLanguage ? [answers.contactUrl ? "CONTACT_URL" : "undefined"] : []),
+        ...(nonDefaultLanguage ? [nonDefaultLanguage] : []),
+    ].join(", ");
     return [
-        'import { createChatHandler, createGeminiGenerator } from "@folio-agent/handler";',
+        'import { collectAnswerLinks, createChatHandler, createGeminiGenerator, formatKnowledge } from "@folio-agent/handler";',
         `import knowledgeDoc from "${knowledgeImportPath}";`,
         "",
-        'const knowledge = knowledgeDoc.pages.map((page) => `# ${page.url}\\n\\n${page.text}`).join("\\n\\n");',
+        ...contactUrlConst,
+        "const knowledge = formatKnowledge(knowledgeDoc);",
+        `const answerLinks = collectAnswerLinks(${linkArgs});`,
         "",
         "interface Env {",
         "  DB: D1Database;",
@@ -80,9 +90,10 @@ export function buildApiRouteTemplate(answers) {
         "export const onRequestPost: PagesFunction<Env> = async (context) => {",
         "  const handle = createChatHandler({",
         `    db: context.env.DB,${languageLine}`,
+        "    answerLinks,",
         "    generateAnswer: createGeminiGenerator({",
         "      apiKey: context.env.GEMINI_API_KEY,",
-        `      knowledge,${contactUrlLine}`,
+        `      knowledge,${contactUrlLine}${generatorLanguageLine}`,
         "    }),",
         "  });",
         "  return handle(context.request);",
@@ -90,11 +101,15 @@ export function buildApiRouteTemplate(answers) {
         "",
     ].join("\n");
 }
-/** Appends the ingest command to a `build` script if it isn't already present; otherwise returns it unchanged. */
+/**
+ * Appends the ingest command to a `build` script unless it already runs ingest. Any existing
+ * `folio-agent-ingest` counts, whatever its arguments: sites often write to a different output
+ * path than the default, and appending a second run would ingest twice.
+ */
 export function appendIngestToBuildScript(buildScript, configPath, knowledgeOutputPath) {
     const ingestCommand = `${INGEST_COMMAND_PREFIX} ${configPath} ${knowledgeOutputPath}`;
     const base = (buildScript ?? "").trim();
-    if (base.includes(ingestCommand)) {
+    if (base.includes(INGEST_COMMAND_PREFIX)) {
         return base;
     }
     return base.length > 0 ? `${base} && ${ingestCommand}` : ingestCommand;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@folio-agent/handler",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Chat handler (LangGraph.js on Cloudflare Workers) + knowledge ingestion CLI",
   "license": "MIT",
   "type": "module",