@folio-agent/handler 0.6.1 → 0.7.0

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/contract.d.ts

@@ -0,0 +1,17 @@
+import type { AnswerLink } from "./links.js";
+export declare const LINK_SYNTAX: RegExp;
+export declare const BARE_URL: RegExp;
+export type AnswerViolationKind = "disallowed_link" | "bare_url" | "markdown";
+export interface AnswerViolation {
+    kind: AnswerViolationKind;
+    /** The offending part of the answer, quoted back to the model when asking it to correct. */
+    excerpt: string;
+}
+export declare function findAllowedLink(url: string, links: AnswerLink[]): AnswerLink | undefined;
+/**
+ * Deterministic cleanups too trivial to send back to the model: surrounding whitespace, trailing
+ * spaces on lines, and runs of blank lines.
+ */
+export declare function tidyAnswer(answer: string): string;
+/** Returns what in `answer` breaks the answer format; an empty list means it complies. */
+export declare function findAnswerFormatViolations(answer: string, links: AnswerLink[]): AnswerViolation[];

package/dist/chat/answer/contract.js

@@ -0,0 +1,37 @@
+// 回答の形式（handler と widget のあいだの決まり）を、検査できる形で書いたもの。
+//   - プレーンテキスト。段落は空行1つで区切る
+//   - 記法はリンクの [表示する文字](URL) だけ。URL は answerLinks にあるものだけ
+//   - URL をそのまま見せない
+// check_answer がこれで違反を探し、違反があれば LLM に指摘して作り直させる。
+export const LINK_SYNTAX = /\[([^\]\n]+)\]\(([^)\n]*)\)/g;
+export const BARE_URL = /https?:\/\/[^\s<>"'（）「」『』【】、。]+/g;
+function linkKey(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+export function findAllowedLink(url, links) {
+    return links.find((link) => linkKey(link.url) === linkKey(url));
+}
+/**
+ * Deterministic cleanups too trivial to send back to the model: surrounding whitespace, trailing
+ * spaces on lines, and runs of blank lines.
+ */
+export function tidyAnswer(answer) {
+    return answer.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** Returns what in `answer` breaks the answer format; an empty list means it complies. */
+export function findAnswerFormatViolations(answer, links) {
+    const violations = [];
+    // リンクは表示する文字に置き換えてから残りを調べる（空にすると、後ろの文字が行頭にあるように見える）
+    const rest = answer.replace(LINK_SYNTAX, (whole, label, url) => {
+        if (!findAllowedLink(url, links))
+            violations.push({ kind: "disallowed_link", excerpt: whole });
+        return label;
+    });
+    for (const match of rest.matchAll(BARE_URL))
+        violations.push({ kind: "bare_url", excerpt: match[0] });
+    for (const line of rest.split("\n")) {
+        if (/\*\*|__|`|^[ \t]*#{1,6}[ \t]|^[ \t]*[-*][ \t]/.test(line))
+            violations.push({ kind: "markdown", excerpt: line.trim() });
+    }
+    return violations;
+}

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

@@ -0,0 +1,7 @@
+import type { AnswerLink } from "./links.js";
+/**
+ * The last resort when the model still breaks the answer format after being asked to correct it.
+ * Keeps only allowed links, reduces every other link to its text, drops bare URLs and Markdown
+ * markers. It never asks the model again, so its output always complies.
+ */
+export declare function toPlainAnswer(answer: string, links?: AnswerLink[]): string;

package/dist/chat/answer/fallback.js

@@ -0,0 +1,43 @@
+import { BARE_URL, findAllowedLink, LINK_SYNTAX, tidyAnswer } from "./contract.js";
+const TRAILING_PUNCTUATION = /[.,;:!?)\]]+$/;
+const PLACEHOLDER = /\u0000(\d+)\u0000/g;
+function stripInlineMarkdown(text) {
+    return text
+        .replace(/\*\*(.+?)\*\*/g, "$1")
+        .replace(/__(.+?)__/g, "$1")
+        .replace(/`([^`\n]+)`/g, "$1")
+        .replace(/\*\*|__|`/g, "");
+}
+/**
+ * The last resort when the model still breaks the answer format after being asked to correct it.
+ * Keeps only allowed links, reduces every other link to its text, drops bare URLs and Markdown
+ * markers. It never asks the model again, so its output always complies.
+ */
+export function toPlainAnswer(answer, links = []) {
+    const kept = [];
+    const keep = (label, url) => {
+        kept.push(`[${stripInlineMarkdown(label)}](${url})`);
+        return `\u0000${kept.length - 1}\u0000`;
+    };
+    // リンク先の形は問わず、すべてのリンク記法を拾う。許可されたもの以外（相対パス・mailto: なども）は文字だけにする
+    let text = answer.replace(LINK_SYNTAX, (_, label, url) => {
+        const link = findAllowedLink(url.trim(), links);
+        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 = findAllowedLink(url, links);
+        return link ? keep(link.title, link.url) + rest : rest;
+    });
+    // 消した URL の跡の空括弧を先に取る。後に回すと、括弧の後ろにあった見出しやリストの記号が行頭に出てくる
+    text = stripInlineMarkdown(text.replace(/（\s*）|\(\s*\)/g, ""))
+        .replace(/^[ \t]*(?:#{1,6}[ \t]+)+/gm, "")
+        .replace(/^[ \t]*(?:[-*][ \t]+)+/gm, "・")
+        // この時点で残る "](" は、閉じていないリンク記法などの切れ端。残すと、戻したリンクとつながって
+        // 許可していないリンク記法ができてしまう
+        .replace(/\]\(/g, "] (")
+        .replace(PLACEHOLDER, (_, index) => kept[Number(index)]);
+    return tidyAnswer(text);
+}

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/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;
@@ -7,5 +6,11 @@ export interface GeminiGeneratorConfig {
     contactUrl?: string;
     language?: Language;
 }
-export type GenerateAnswerFn = (input: string, route: ChatRoute) => Promise<string>;
+/** Passed when check_answer found the previous answer breaking the answer format. */
+export interface AnswerCorrection {
+    previousAnswer: string;
+    /** What to fix, written for the model (see prompt/correction.ts). */
+    request: string;
+}
+export type GenerateAnswerFn = (input: string, route: ChatRoute, correction?: AnswerCorrection) => Promise<string>;
 export declare function createGeminiGenerator(config: GeminiGeneratorConfig): GenerateAnswerFn;

package/dist/chat/gemini.js

@@ -1,64 +1,24 @@
 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";
+    const model = config.model ?? "gemini-3.5-flash-lite";
     const language = config.language ?? DEFAULT_LANGUAGE;
-    return async (input, route) => {
+    return async (input, route, correction) => {
         if (route === "rate_limited") {
             throw new Error("generateAnswer should not be called for a rate-limited route");
         }
         const response = await client.models.generateContent({
             model,
-            contents: input,
+            // 作り直しでは、元の質問・直前の回答・指摘を会話として渡し、同じ質問への答え直しであることを伝える
+            contents: correction
+                ? [
+                    { role: "user", parts: [{ text: input }] },
+                    { role: "model", parts: [{ text: correction.previousAnswer }] },
+                    { role: "user", parts: [{ text: correction.request }] },
+                ]
+                : input,
             config: { systemInstruction: buildSystemPrompt(config.knowledge, route, config.contactUrl, language) },
         });
         return response.text ?? "";

package/dist/chat/graph.d.ts

@@ -1,3 +1,4 @@
+import type { AnswerViolation } from "./answer/contract.js";
 import type { ChatGraphDeps, ChatRoute } from "./types.js";
 export declare function buildChatGraph(deps: ChatGraphDeps): import("@langchain/langgraph").CompiledStateGraph<{
     input: string;
@@ -5,26 +6,43 @@ export declare function buildChatGraph(deps: ChatGraphDeps): import("@langchain/
     route: ChatRoute | undefined;
     overLimit: boolean;
     answer: string | undefined;
+    attempt: number;
+    violations: AnswerViolation[];
 }, {
     input?: string | undefined;
     ip?: string | undefined;
     route?: ChatRoute | undefined;
     overLimit?: boolean | undefined;
     answer?: string | undefined;
-}, "__start__" | "generate" | "input_guard" | "log" | "route_message", {
+    attempt?: number | undefined;
+    violations?: AnswerViolation[] | undefined;
+}, "__start__" | "check_answer" | "fallback" | "generate" | "input_guard" | "log" | "route_message", {
     input: import("@langchain/langgraph").LastValue<string>;
     ip: import("@langchain/langgraph").LastValue<string>;
     route: import("@langchain/langgraph").LastValue<ChatRoute | undefined>;
     overLimit: import("@langchain/langgraph").LastValue<boolean>;
     answer: import("@langchain/langgraph").LastValue<string | undefined>;
+    attempt: import("@langchain/langgraph").LastValue<number>;
+    violations: import("@langchain/langgraph").LastValue<AnswerViolation[]>;
 }, {
     input: import("@langchain/langgraph").LastValue<string>;
     ip: import("@langchain/langgraph").LastValue<string>;
     route: import("@langchain/langgraph").LastValue<ChatRoute | undefined>;
     overLimit: import("@langchain/langgraph").LastValue<boolean>;
     answer: import("@langchain/langgraph").LastValue<string | undefined>;
+    attempt: import("@langchain/langgraph").LastValue<number>;
+    violations: import("@langchain/langgraph").LastValue<AnswerViolation[]>;
 }, import("@langchain/langgraph").StateDefinition, {
+    check_answer: {
+        answer: string;
+        violations: AnswerViolation[];
+    };
+    fallback: {
+        answer: string;
+        violations: never[];
+    };
     generate: {
+        attempt: number;
         answer: string;
     };
     input_guard: {

package/dist/chat/graph.js

@@ -1,4 +1,7 @@
 import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
+import { findAnswerFormatViolations, tidyAnswer } from "./answer/contract.js";
+import { toPlainAnswer } from "./answer/fallback.js";
+import { buildCorrectionRequest } from "./prompt/correction.js";
 import { classifyRoute } from "./route.js";
 import { DEFAULT_LANGUAGE } from "./types.js";
 const OVER_LIMIT_MESSAGE = {
@@ -13,12 +16,16 @@ const GENERATION_FAILED_MESSAGE = {
     ja: "本日の受付上限に達したか、一時的な不具合が発生しています。恐れ入りますがContactからお問い合わせください。",
     en: "You may have reached today's limit, or a temporary issue has occurred. Please contact us via the Contact page.",
 };
+// 1回目の回答と、指摘して作り直させた回答の2回まで。無料枠の回数の上限があるので、それ以上は呼ばない
+const MAX_ATTEMPTS = 2;
 const ChatState = Annotation.Root({
     input: Annotation(),
     ip: Annotation(),
     route: Annotation(),
     overLimit: Annotation(),
     answer: Annotation(),
+    attempt: Annotation(),
+    violations: Annotation(),
 });
 export function buildChatGraph(deps) {
     const language = deps.language ?? DEFAULT_LANGUAGE;
@@ -35,14 +42,38 @@ export function buildChatGraph(deps) {
     })
         .addNode("route_message", async (state) => ({ route: classifyRoute(state.input, language) }))
         .addNode("generate", async (state) => {
+        const attempt = (state.attempt ?? 0) + 1;
+        const correction = state.violations?.length && state.answer !== undefined
+            ? { previousAnswer: state.answer, request: buildCorrectionRequest(state.violations, language) }
+            : undefined;
         try {
-            return { answer: await deps.generateAnswer(state.input, state.route) };
+            return { attempt, answer: await deps.generateAnswer(state.input, state.route, correction) };
         }
         catch (error) {
             console.error("generateAnswer failed", error);
-            return { answer: GENERATION_FAILED_MESSAGE[language] };
+            return { attempt, answer: GENERATION_FAILED_MESSAGE[language] };
         }
     })
+        .addNode("check_answer", async (state) => {
+        const answer = tidyAnswer(state.answer ?? "");
+        const violations = findAnswerFormatViolations(answer, deps.answerLinks ?? []);
+        if (violations.length > 0 && deps.logAnswerViolation) {
+            try {
+                await deps.logAnswerViolation({
+                    route: state.route,
+                    attempt: state.attempt,
+                    kinds: [...new Set(violations.map((violation) => violation.kind))],
+                    answer,
+                });
+            }
+            catch (error) {
+                // 記録に失敗しても（migration 未適用など）訪問者への回答は止めない
+                console.error("logAnswerViolation failed", error);
+            }
+        }
+        return { answer, violations };
+    })
+        .addNode("fallback", async (state) => ({ answer: toPlainAnswer(state.answer ?? "", deps.answerLinks), violations: [] }))
         .addNode("log", async (state) => {
         await deps.logChat({
             ip: state.ip,
@@ -59,7 +90,9 @@ export function buildChatGraph(deps) {
         route_message: "route_message",
     })
         .addEdge("route_message", "generate")
-        .addEdge("generate", "log")
+        .addEdge("generate", "check_answer")
+        .addConditionalEdges("check_answer", (state) => (state.violations.length === 0 ? "log" : state.attempt < MAX_ATTEMPTS ? "generate" : "fallback"), { log: "log", generate: "generate", fallback: "fallback" })
+        .addEdge("fallback", "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

@@ -1,5 +1,5 @@
 import { buildChatGraph } from "./graph.js";
-import { logChat } from "./log.js";
+import { logAnswerViolation, logChat } from "./log.js";
 import { checkRateLimit } from "./rate-limit.js";
 import { DEFAULT_RATE_LIMIT_CONFIG } from "./types.js";
 const MAX_INPUT_LENGTH = 1000;
@@ -11,6 +11,8 @@ export function createChatHandler(config) {
         logChat: (entry) => logChat(config.db, entry),
         rateLimitConfig,
         language: config.language,
+        answerLinks: config.answerLinks,
+        logAnswerViolation: (entry) => logAnswerViolation(config.db, entry),
     });
     return async (request) => {
         let body;

package/dist/chat/log.d.ts

@@ -1,2 +1,3 @@
-import type { ChatLogEntry } from "./types.js";
+import type { AnswerViolationLogEntry, ChatLogEntry } from "./types.js";
 export declare function logChat(db: D1Database, entry: ChatLogEntry, now?: Date): Promise<void>;
+export declare function logAnswerViolation(db: D1Database, entry: AnswerViolationLogEntry, now?: Date): Promise<void>;

package/dist/chat/log.js

@@ -4,3 +4,10 @@ export async function logChat(db, entry, now = new Date()) {
         .bind(now.toISOString(), entry.ip, entry.route, entry.message, entry.response, entry.overLimit ? 1 : 0)
         .run();
 }
+// 訪問者の入力は残さない。集計したいのは LLM がどう間違えたかで、誰が何を聞いたかではない
+export async function logAnswerViolation(db, entry, now = new Date()) {
+    await db
+        .prepare("INSERT INTO answer_violations (created_at, route, attempt, kinds, answer) VALUES (?, ?, ?, ?, ?)")
+        .bind(now.toISOString(), entry.route, entry.attempt, JSON.stringify(entry.kinds), entry.answer)
+        .run();
+}

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

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

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

@@ -0,0 +1,22 @@
+// 回答の形式（handler と widget のあいだの決まり）。指示で頼む側で、守らせるのは answer/contract.ts と check_answer。
+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 pages marked \"(a page on this site)\" in the knowledge 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://…".',
+};
+// Contact は経路に関係なく案内されうる。URL を渡さないと LLM は /contact のような URL を作ってしまうので、
+// 書き方の見本をそのまま渡す
+export function buildContactLinkExample(language, contactUrl) {
+    return language === "en"
+        ? `When pointing to the Contact page, write it exactly like this: [Contact page](${contactUrl})`
+        : `Contactページを案内するときは、次の書き方をそのまま使ってください: [Contactページ](${contactUrl})`;
+}

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

@@ -0,0 +1,3 @@
+import type { AnswerViolation } from "../answer/contract.js";
+import type { Language } from "../types.js";
+export declare function buildCorrectionRequest(violations: AnswerViolation[], language: Language): string;

package/dist/chat/prompt/correction.js

@@ -0,0 +1,25 @@
+// check_answer が違反を見つけたとき、LLM に作り直させるための指摘文。
+const KIND_TEXT = {
+    ja: {
+        disallowed_link: "リンクにしてはいけない先へのリンクがあります。このサイト内のページはリンクにせずページ名で案内し、" +
+            "リンクはContactページと知識に「URL: https://…」として書かれたページだけにしてください",
+        bare_url: "URLがそのまま書かれています。[表示する文字](URL) の形にし、記事ならタイトルを表示する文字にしてください",
+        markdown: "リンク以外のMarkdown記法（**・#・- のリスト・`）が使われています。プレーンテキストにしてください",
+    },
+    en: {
+        disallowed_link: "It links to a destination that must not be linked. Refer to this site's pages by name, and only link the " +
+            'Contact page and pages that appear in the knowledge as "URL: https://…"',
+        bare_url: "It shows a bare URL. Write it as [text to show](URL), using the title for an article",
+        markdown: "It uses Markdown other than links (**, #, - lists, `). Use plain text",
+    },
+};
+const INTRO = {
+    ja: "直前の回答は、回答の形式の決まりに次の点で合っていません。内容は変えずに、決まりに合わせて回答だけを書き直してください。" +
+        "書き直したことは訪問者には見えないので、謝ったり直したことに触れたりせず、訪問者への回答だけを書いてください。",
+    en: "Your previous answer breaks the answer format in the following ways. Keep the content and rewrite only the answer so it complies. " +
+        "The visitor never sees this correction, so do not apologize or mention it; write only the answer to the visitor.",
+};
+export function buildCorrectionRequest(violations, language) {
+    const lines = violations.map((violation) => `- ${KIND_TEXT[language][violation.kind]}: ${violation.excerpt}`);
+    return [INTRO[language], ...lines].join("\n");
+}

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,16 @@
+import { DEFAULT_LANGUAGE } from "../types.js";
+import { ANSWER_FORMAT, buildContactLinkExample } 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];
+    const answerFormat = contactUrl
+        ? `${ANSWER_FORMAT[language]}\n${buildContactLinkExample(language, contactUrl)}`
+        : ANSWER_FORMAT[language];
+    return [PERSONA[language], GROUNDING[language], answerFormat, 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,6 @@
+import type { AnswerViolationKind } from "./answer/contract.js";
+import type { AnswerLink } from "./answer/links.js";
+import type { AnswerCorrection } from "./gemini.js";
 export type ChatRoute = "thoughts" | "works" | "inquiry" | "rate_limited";
 export type Language = "ja" | "en";
 export declare const DEFAULT_LANGUAGE: Language;
@@ -22,8 +25,19 @@ export interface ChatLogEntry {
 }
 export interface ChatGraphDeps {
     checkRateLimit: (ip: string) => Promise<RateLimitResult>;
-    generateAnswer: (input: string, route: ChatRoute) => Promise<string>;
+    generateAnswer: (input: string, route: ChatRoute, correction?: AnswerCorrection) => Promise<string>;
     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[];
+    /** Records answers that broke the answer format, to see which mistakes are common. */
+    logAnswerViolation?: (entry: AnswerViolationLogEntry) => Promise<void>;
+}
+export interface AnswerViolationLogEntry {
+    route: ChatRoute;
+    /** 1 for the first answer, 2 for the answer after one correction. */
+    attempt: number;
+    kinds: AnswerViolationKind[];
+    answer: string;
 }

package/dist/index.d.ts

@@ -1,14 +1,18 @@
 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 type { GenerateAnswerFn, GeminiGeneratorConfig } 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 { AnswerCorrection, GenerateAnswerFn, GeminiGeneratorConfig } from "./chat/gemini.js";
 export { classifyRoute } from "./chat/route.js";
-export { logChat } from "./chat/log.js";
-export type { ChatRoute, ChatGraphDeps, ChatLogEntry, RateLimitConfig, RateLimitResult, RateLimitReason, } from "./chat/types.js";
+export { logAnswerViolation, logChat } from "./chat/log.js";
+export type { ChatRoute, ChatGraphDeps, AnswerViolationLogEntry, ChatLogEntry, RateLimitConfig, RateLimitResult, RateLimitReason, } from "./chat/types.js";
 export { DEFAULT_RATE_LIMIT_CONFIG } from "./chat/types.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 { logAnswerViolation, logChat } from "./chat/log.js";
 export { DEFAULT_RATE_LIMIT_CONFIG } from "./chat/types.js";

package/dist/ingest/format.d.ts

@@ -0,0 +1,9 @@
+import type { Language } from "../chat/types.js";
+import type { KnowledgePagesLike } from "./types.js";
+/**
+ * Turns a knowledge document into the text handed to the system prompt. Pages outside this site
+ * (such as Zenn articles) carry their title and URL, so answers can link them by title. This
+ * site's pages carry only their name, without the site-name suffix and without a URL: the visitor
+ * is already on the site, and handing the model a URL invites it to link the page anyway.
+ */
+export declare function formatKnowledge(doc: KnowledgePagesLike, language?: Language): string;

package/dist/ingest/format.js

@@ -0,0 +1,46 @@
+import { DEFAULT_LANGUAGE } from "../chat/types.js";
+const SITE_PAGE_LABEL = {
+    ja: "（このサイトのページ）",
+    en: " (a page on this site)",
+};
+const TITLE_WITH_SUFFIX = /^(.+?)\s+[•|｜\-–—:]\s+(.+)$/;
+function isExternal(url) {
+    return /^https?:\/\//i.test(url);
+}
+/**
+ * Finds the site-name suffix that this site's page titles share ("Works • ykts.net" and
+ * "About • ykts.net" share " • ykts.net"). A suffix seen on only one page isn't treated as the
+ * site name, since it may be part of that page's own title.
+ */
+function sharedTitleSuffix(titles) {
+    const counts = new Map();
+    for (const title of titles) {
+        const suffix = TITLE_WITH_SUFFIX.exec(title)?.[2];
+        if (suffix)
+            counts.set(suffix, (counts.get(suffix) ?? 0) + 1);
+    }
+    let best;
+    for (const [suffix, count] of counts) {
+        if (count >= 2 && count > (best ? (counts.get(best) ?? 0) : 0))
+            best = suffix;
+    }
+    return best;
+}
+/**
+ * Turns a knowledge document into the text handed to the system prompt. Pages outside this site
+ * (such as Zenn articles) carry their title and URL, so answers can link them by title. This
+ * site's pages carry only their name, without the site-name suffix and without a URL: the visitor
+ * is already on the site, and handing the model a URL invites it to link the page anyway.
+ */
+export function formatKnowledge(doc, language = DEFAULT_LANGUAGE) {
+    const suffix = sharedTitleSuffix(doc.pages.filter((page) => !isExternal(page.url)).map((page) => page.title));
+    return doc.pages
+        .map((page) => {
+        if (isExternal(page.url))
+            return `# ${page.title}\nURL: ${page.url}\n\n${page.text}`;
+        const match = TITLE_WITH_SUFFIX.exec(page.title);
+        const name = suffix && match?.[2] === suffix ? match[1] : page.title;
+        return `# ${name}${SITE_PAGE_LABEL[language]}\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/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);",

package/migrations/0002_answer_violations.sql

@@ -0,0 +1,10 @@
+-- LLM の回答が回答の形式の決まりを破った記録。どの間違いが多いかを集計し、
+-- 多いものだけをプロンプトやコードで手当てするために使う。訪問者の入力は持たない。
+CREATE TABLE IF NOT EXISTS answer_violations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  created_at TEXT NOT NULL,
+  route TEXT NOT NULL,
+  attempt INTEGER NOT NULL,
+  kinds TEXT NOT NULL,
+  answer TEXT NOT NULL
+);

package/package.json

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