@tomako/tools-runtime 0.1.0

package/src/features/tools/package/types.ts

@@ -0,0 +1,381 @@
+import type { ZodTypeAny } from "zod";
+
+import type { ToolRiskLevel } from "../types";
+import type { ToolArchetype } from "../../../lib/tools/types";
+import type { AppLocale } from "../../../i18n/locale";
+
+/**
+ * ToolPackage：数据驱动工具页的生产单位。
+ * 一个工具 = 一个 package 文件（纯数据 + 一个 zod 结果 schema 引用），
+ * 由 archetype 引擎渲染，不再为每个工具手写 widget/container/i18n。
+ *
+ * 文案采用叶子级三语（L10nText）：结构由类型系统强制三语同构，
+ * 从根上消除"语言之间段落数量/顺序漂移"这一类校验问题。
+ */
+
+/** 叶子级多语言文本：en/zh 必填，zh-tw 缺省时回退 zh（见 l10n.ts）。 */
+export type L10nText = {
+  en: string;
+  zh: string;
+  "zh-tw"?: string;
+};
+
+export type L10nTextList = {
+  en: string[];
+  zh: string[];
+  "zh-tw"?: string[];
+};
+
+/* ----------------------------- 表单 ----------------------------- */
+
+interface FormFieldBase {
+  /** 字段 id，同时是 brief JSON 的 key（camelCase）。 */
+  id: string;
+  label: L10nText;
+  hint?: L10nText;
+  placeholder?: L10nText;
+  required?: boolean;
+  /** 校验失败时的提示；缺省用引擎通用文案。 */
+  invalidMessage?: L10nText;
+  /** 两列布局时占据整行。 */
+  fullWidth?: boolean;
+  /** 工作台紧凑模式下收进“更多选项”；官网工具页仍默认展开。 */
+  advanced?: boolean;
+}
+
+export interface TextFieldSpec extends FormFieldBase {
+  kind: "text";
+  minLength?: number;
+  maxLength?: number;
+}
+
+export interface TextareaFieldSpec extends FormFieldBase {
+  kind: "textarea";
+  rows?: number;
+  minLength?: number;
+  maxLength?: number;
+}
+
+export interface SelectFieldSpec extends FormFieldBase {
+  kind: "select";
+  options: Array<{ value: string; label: L10nText }>;
+  defaultValue: string;
+}
+
+export interface ToggleFieldSpec extends FormFieldBase {
+  kind: "toggle";
+  onLabel: L10nText;
+  offLabel: L10nText;
+  defaultValue: boolean;
+}
+
+export type FormFieldSpec =
+  | TextFieldSpec
+  | TextareaFieldSpec
+  | SelectFieldSpec
+  | ToggleFieldSpec;
+
+export type FormValues = Record<string, string | boolean>;
+
+/* ----------------------------- 结果视图 ----------------------------- */
+
+/**
+ * ResultView：用少量视图积木解释任意结构化结果。
+ * path 使用点号路径（如 "currentRead.coreDecision"）读取结果字段。
+ */
+
+export interface KeyValuesBlock {
+  block: "keyValues";
+  title?: L10nText;
+  items: Array<{
+    label: L10nText;
+    path: string;
+    /** 为 true 时该值渲染为等宽文本 + 单独复制按钮（instant 工具主产出常用）。 */
+    copyable?: boolean;
+  }>;
+}
+
+export interface BulletListBlock {
+  block: "bulletList";
+  title: L10nText;
+  path: string;
+  /** 视觉基调：默认 neutral。 */
+  tone?: "neutral" | "positive" | "risk";
+}
+
+export interface BulletGroupsBlock {
+  block: "bulletGroups";
+  title?: L10nText;
+  columns: Array<{
+    label: L10nText;
+    path: string;
+    tone?: "neutral" | "positive" | "risk";
+  }>;
+}
+
+export interface CardListBlock {
+  block: "cardList";
+  title: L10nText;
+  path: string;
+  layout?: "stack" | "grid";
+  card: {
+    titleField: string;
+    /** 标题即原子交付物（如单条 slogan）时开启：卡片标题旁提供单条复制。 */
+    titleCopyable?: boolean;
+    /** 标题右侧的小徽标字段（如时长）。 */
+    metaField?: string;
+    metaSuffix?: L10nText;
+    body?: { field: string; label?: L10nText };
+    lists?: Array<{ field: string; label: L10nText }>;
+    footer?: { field: string; label?: L10nText };
+  };
+}
+
+export interface StrategicCurveBlock {
+  block: "strategicCurve";
+  title: L10nText;
+  path: string;
+  playerField: string;
+  valuesField: string;
+  dimensions: L10nTextList;
+  maxScore: number;
+}
+
+export type ResultViewBlock =
+  | KeyValuesBlock
+  | BulletListBlock
+  | BulletGroupsBlock
+  | CardListBlock
+  | StrategicCurveBlock;
+
+/* ----------------------------- 页面内容 ----------------------------- */
+
+export interface SectionImage {
+  src: string;
+  alt: L10nText;
+  side?: "left" | "right";
+  wide?: boolean;
+}
+
+export interface CardsSection {
+  kind: "cards";
+  heading: L10nText;
+  intro?: L10nText;
+  items: Array<{ title: L10nText; body: L10nText }>;
+  image?: SectionImage;
+}
+
+export interface BulletsSection {
+  kind: "bullets";
+  heading: L10nText;
+  intro?: L10nText;
+  groups: Array<{ title?: L10nText; items: L10nTextList }>;
+  image?: SectionImage;
+}
+
+export interface ParagraphsSection {
+  kind: "paragraphs";
+  heading: L10nText;
+  intro?: L10nText;
+  paragraphs: L10nTextList;
+  image?: SectionImage;
+}
+
+export type PageSection = CardsSection | BulletsSection | ParagraphsSection;
+
+export interface ToolStandardBenefitsCopy {
+  title: L10nText;
+  cards: [
+    { title: L10nText; body: L10nText },
+    { title: L10nText; body: L10nText },
+    { title: L10nText; body: L10nText },
+  ];
+}
+
+export interface ToolStandardImageTextCopy {
+  id: "section-primary" | "section-variation" | "section-support";
+  title: L10nText;
+  body: L10nTextList;
+  image: SectionImage;
+  imageFirst?: boolean;
+}
+
+export interface ToolStandardGenerationCopy {
+  title: L10nText;
+  image: SectionImage;
+  steps: Array<{ title: L10nText; body: L10nText }>;
+  ctaLabel: L10nText;
+}
+
+/**
+ * Workspace-first Tool pages use this fixed post-workspace content contract.
+ * Copy and assets vary per tool; section order and layout do not.
+ */
+export interface ToolStandardLandingCopy {
+  benefits: ToolStandardBenefitsCopy;
+  imageTextSections: [
+    ToolStandardImageTextCopy,
+    ToolStandardImageTextCopy,
+    ToolStandardImageTextCopy,
+  ];
+  generation: ToolStandardGenerationCopy;
+  faq: {
+    title: L10nText;
+    intro: L10nText;
+    ctaLabel: L10nText;
+  };
+}
+
+/* ----------------------------- 运行时 ----------------------------- */
+
+/**
+ * agent 车道：走现有 POST /llm/tasks → cc-connect → Skills-OL 链路。
+ * 引擎按已验证的 prompt 骨架自动生成 payload（TASK_ID 提取、结果契约、
+ * 写回命令、单句回复约束），工具只声明差异部分。
+ */
+export interface AgentRuntimeSpec {
+  lane: "agent";
+  scene: string;
+  resultType: string;
+  /** Skills-OL skill 引用名，如 "$user-interview-guide"。 */
+  skillId: string;
+  /** 写回脚本文件名，如 "user-interview-guide.mjs"。 */
+  writebackScript: string;
+  /** 结果 JSON 契约行（camelCase 字段清单），逐行进入 payload。 */
+  outputContract: string[];
+  /** 质量规则行，逐行进入 payload。 */
+  rules: string[];
+  /** 是否在 payload 中禁止 Agent 换用其他 skill（默认 true）。 */
+  restrictToSkill?: boolean;
+  watch?: {
+    pollIntervalMs?: number;
+    graceWindowMs?: number;
+  };
+}
+
+/**
+ * direct 车道：schema 固定的单次 LLM 结构化调用（POST /llm/direct，无 Agent 会话）。
+ * 适合命名、模板、草稿、打分类固定变换，目标 P50 < 15s。
+ * scene 必须加入 portal 的 llm.direct.allowed-scenes 白名单端点才会放行。
+ */
+export interface DirectRuntimeSpec {
+  lane: "direct";
+  scene: string;
+  /** 系统提示（可选，locale 无关；语言指令由引擎按 uiLocale 自动追加）。 */
+  system?: string;
+  /** 用户消息模板；{{briefJson}} 占位符会被替换为表单 brief 的 JSON。 */
+  promptTemplate: string;
+  maxTokens?: number;
+}
+
+/**
+ * instant 车道：纯客户端确定性变换，零 LLM、零网络请求，结果亚秒级返回。
+ * 适合 UTM 构建、格式转换、计算器、编码/解码这类"同输入必同输出"的工具。
+ *
+ * compute 必须是纯函数（无副作用、不发请求）；允许返回 Promise 以兼容
+ * canvas/File 等浏览器异步 API。返回值仍强制通过 resultSchema 解析——
+ * 三条车道共享同一结果契约，解析失败绝不渲染假成功。
+ * 抛出 Error 表示"输入组合无法处理"，引擎落 computeFailed 错误码。
+ */
+export interface InstantRuntimeSpec {
+  lane: "instant";
+  compute: (values: FormValues, locale: AppLocale) => unknown | Promise<unknown>;
+}
+
+export type RuntimeSpec = AgentRuntimeSpec | DirectRuntimeSpec | InstantRuntimeSpec;
+
+/* ----------------------------- 包 ----------------------------- */
+
+export interface ToolPackageMeta {
+  slug: string;
+  toolType: ToolArchetype;
+  riskLevel?: ToolRiskLevel;
+  /**
+   * 关键词证据来源：docs/seo-keyword-briefs/{slug}.md 的相对路径，
+   * 或 "strategic:<原因>" 显式声明不计 SEO KPI。校验器强制非空。
+   */
+  keywordEvidence: string;
+  seo: {
+    publishedAt?: string;
+    updatedAt: string;
+    readingTime: string;
+    featured?: boolean;
+    ogImage?: string;
+  };
+  mcp?: { enabled: boolean; toolName?: string };
+}
+
+export interface ToolPackageCopy {
+  title: L10nText;
+  displayTitle?: L10nText;
+  description: L10nText;
+  intro: L10nText;
+  category: L10nText;
+  keywords: L10nTextList;
+  inputSignal?: L10nText;
+  outputSignal?: L10nText;
+  boundarySignal?: L10nText;
+}
+
+export interface ToolPackageWidgetCopy {
+  formTitle: L10nText;
+  formHint: L10nText;
+  /** 缺省时使用引擎通用文案（toolsPages.engine）。 */
+  submitLabel?: L10nText;
+  resultTitle?: L10nText;
+  pendingTitle?: L10nText;
+  pendingHint?: L10nText;
+  /** 按错误码覆盖引擎通用错误文案。 */
+  errorOverrides?: Partial<
+    Record<
+      | "validation"
+      | "authRequired"
+      | "submitFailed"
+      | "taskFailed"
+      | "resultTimeout"
+      | "wrongResultType"
+      | "invalidResultSchema"
+      | "resultWritebackMissing"
+      | "computeFailed",
+      { title: L10nText; body: L10nText }
+    >
+  >;
+}
+
+export interface ToolPackagePageCopy {
+  workspace: {
+    heading: L10nText;
+    hint: L10nText;
+    badge?: L10nText;
+  };
+  /** Canonical contract for new and rebuilt workspace-first Tool pages. */
+  standard?: ToolStandardLandingCopy;
+  /** @deprecated Legacy package content. Migrate touched tools to `standard`. */
+  sections?: PageSection[];
+  faq: Array<{ question: L10nText; answer: L10nText }>;
+  /** @deprecated The standard stack owns its generation CTA and FAQ action. */
+  cta?: {
+    heading?: L10nText;
+    hint: L10nText;
+    primary: { href: string; label: L10nText };
+    secondary?: { href: string; label: L10nText };
+  };
+}
+
+export interface ToolPackageAssets {
+  /** Legacy-only. Workspace-first pages do not render or generate a standalone Hero. */
+  hero?: { src: string; alt: L10nText };
+}
+
+export interface ToolPackage {
+  meta: ToolPackageMeta;
+  copy: ToolPackageCopy;
+  form: FormFieldSpec[];
+  runtime: RuntimeSpec;
+  /** 结果 schema（zod）；解析失败即 RESULT_INVALID，绝不渲染假成功。 */
+  resultSchema: ZodTypeAny;
+  resultView: ResultViewBlock[];
+  widget: ToolPackageWidgetCopy;
+  page: ToolPackagePageCopy;
+  assets: ToolPackageAssets;
+}

package/src/features/tools/pitch-deck-generator/pitch-deck-generator.container.tsx

@@ -0,0 +1,175 @@
+import { createToolGuideTranslator } from "../shared/tool-message-translator";
+
+import { PitchDeckLibrary } from "./pitch-deck-library";
+import { PitchDeckGenerator } from "./widget";
+
+import {
+    ToolCardGrid,
+    ToolFaqSection,
+    ToolSection,
+    type ToolBoundaryGroup,
+    type ToolFaqItem,
+    type ToolTextCard,
+} from "../shared/tool-content-sections";
+import { ToolCta } from "../shared/tool-cta";
+import { ToolImageVisual, ToolWorkspaceSection } from "../shared/tool-guide-section";
+import { ToolPageShell } from "../shared/tool-page-shell";
+import type { ToolPageProps } from "../types";
+
+type NarrativeStep = {
+  index: string;
+  title: string;
+  body: string;
+};
+
+export async function PitchDeckGeneratorContainer({ locale, spec }: ToolPageProps) {
+  const t = await createToolGuideTranslator(locale, "toolsPages.pitchDeckGenerator.guide");
+  const outputItems = t.raw("outputItems") as readonly ToolTextCard[];
+  const narrativeSteps = t.raw("narrativeSteps") as readonly NarrativeStep[];
+  const standardsItems = t.raw("standardsItems") as readonly ToolTextCard[];
+  const boundaryGroups = t.raw("boundaryGroups") as readonly ToolBoundaryGroup[];
+  const useCases = t.raw("useCaseItems") as readonly ToolTextCard[];
+  const faqItems = t.raw("faqItems") as readonly ToolFaqItem[];
+
+  return (
+    <ToolPageShell
+      locale={locale}
+      spec={spec}
+      heroVariant="immersive"
+      heroBackgroundImage="/tools/pitch-deck-generator-hero-v2.webp"
+      heroBackgroundAlt={t("heroImageAlt")}
+    >
+      <ToolWorkspaceSection
+        heading={t("workspaceHeading")}
+        hint={t("workspaceHint")}
+        badge={t("workspaceBadge")}
+      >
+        <PitchDeckGenerator />
+      </ToolWorkspaceSection>
+
+      <section className="border-t border-[#E1DDD3] py-14 md:py-16">
+        <div className="grid gap-8 md:grid-cols-[0.92fr_1.08fr] md:items-center">
+          <div>
+            <h2 className="text-3xl font-semibold leading-tight text-[#111111] md:text-4xl">
+              {t("outputs")}
+            </h2>
+            <p className="mt-4 text-base leading-7 text-[#555555]">{t("outputsIntro")}</p>
+          </div>
+          <ToolImageVisual src="/tools/pitch-deck-generator-pipeline.webp" alt={t("pipelineVisualAlt")} wide />
+        </div>
+        <div className="mt-8">
+          <ToolCardGrid items={outputItems} />
+        </div>
+      </section>
+
+      <section className="border-t border-[#E1DDD3] py-14 md:py-16">
+        <div className="max-w-3xl">
+          <h2 className="text-3xl font-semibold leading-tight text-[#111111] md:text-4xl">
+            {t("narrative")}
+          </h2>
+          <p className="mt-4 text-base leading-7 text-[#555555]">{t("narrativeIntro")}</p>
+        </div>
+        <div className="mt-7 grid gap-3 sm:grid-cols-2 lg:grid-cols-5">
+          {narrativeSteps.map((step) => (
+            <article
+              key={step.index}
+              className="rounded-[1.25rem] border border-[#D8D4CA] bg-white p-5 shadow-[0_12px_28px_rgba(17,17,17,0.05)]"
+            >
+              <p className="text-xs font-semibold text-[#999999]">{step.index}</p>
+              <h3 className="mt-2 text-base font-semibold leading-tight text-[#111111]">
+                {step.title}
+              </h3>
+              <p className="mt-2 text-sm leading-6 text-[#555555]">{step.body}</p>
+            </article>
+          ))}
+        </div>
+      </section>
+
+      <section className="border-t border-[#E1DDD3] py-14 md:py-16">
+        <div className="max-w-3xl">
+          <h2 className="text-3xl font-semibold leading-tight text-[#111111] md:text-4xl">
+            {t("library")}
+          </h2>
+          <p className="mt-4 text-base leading-7 text-[#555555]">{t("libraryIntro")}</p>
+        </div>
+        <div className="mt-7">
+          <PitchDeckLibrary />
+        </div>
+        <p className="mt-6 max-w-3xl text-sm leading-6 text-[#777777]">{t("libraryOutro")}</p>
+      </section>
+
+      <section className="border-t border-[#E1DDD3] py-14 md:py-16">
+        <div className="grid gap-8 md:grid-cols-[0.98fr_1.02fr] md:items-center">
+          <div>
+            <h2 className="text-3xl font-semibold leading-tight text-[#111111] md:text-4xl">
+              {t("standards")}
+            </h2>
+            <p className="mt-4 text-base leading-7 text-[#555555]">{t("standardsIntro")}</p>
+          </div>
+          <ToolImageVisual
+            src="/tools/pitch-deck-generator-standards.webp"
+            alt={t("standardsVisualAlt")}
+            wide
+          />
+        </div>
+        <div className="mt-8">
+          <ToolCardGrid items={standardsItems} />
+        </div>
+      </section>
+
+      <section className="border-t border-[#E1DDD3] py-14 md:py-16">
+        <div className="grid gap-8 md:grid-cols-[0.9fr_1.1fr] md:items-center">
+          <div>
+            <h2 className="text-3xl font-semibold leading-tight text-[#111111] md:text-4xl">
+              {t("boundary")}
+            </h2>
+            <p className="mt-4 text-base leading-7 text-[#555555]">{t("boundaryIntro")}</p>
+          </div>
+          <ToolImageVisual
+            src="/tools/pitch-deck-generator-boundary.webp"
+            alt={t("boundaryVisualAlt")}
+            wide
+          />
+        </div>
+        <div className="mt-7 grid gap-4 lg:grid-cols-3">
+          {boundaryGroups.map((group) => (
+            <article
+              key={group.title}
+              className="rounded-[1.25rem] border border-[#D8D4CA] bg-white p-5 shadow-[0_12px_28px_rgba(17,17,17,0.05)]"
+            >
+              <h3 className="text-base font-semibold text-[#111111]">{group.title}</h3>
+              <ul className="mt-3 list-disc space-y-2 pl-5 text-sm leading-6 text-[#555555]">
+                {group.items.map((item) => (
+                  <li key={item}>{item}</li>
+                ))}
+              </ul>
+            </article>
+          ))}
+        </div>
+      </section>
+
+      <ToolSection
+        heading={t("useCases")}
+        visual={
+          <ToolImageVisual
+            src="/tools/pitch-deck-generator-use-case.webp"
+            alt={t("useCaseVisualAlt")}
+            wide
+          />
+        }
+        reverse
+      >
+        <ToolCardGrid items={useCases} />
+      </ToolSection>
+
+      <ToolFaqSection heading={t("faq")} items={faqItems} />
+
+      <ToolCta
+        heading={t("ctaTitle")}
+        hint={t("ctaHint")}
+        primary={{ href: "/tools/commercial-bp-generator", label: t("ctaPrimary") }}
+        secondary={{ href: "/tools", label: t("ctaSecondary") }}
+      />
+    </ToolPageShell>
+  );
+}

package/src/features/tools/pitch-deck-generator/pitch-deck-generator.spec.ts

@@ -0,0 +1,14 @@
+import type { ToolSpec } from "../types";
+
+export const pitchDeckGeneratorSpec: ToolSpec = {
+  slug: "pitch-deck-generator",
+  toolType: "generator",
+  seo: {
+    "publishedAt": "2026-07-03",
+    "updatedAt": "2026-07-03",
+    "readingTime": "7 min",
+    "featured": false,
+    "ogImage": "/tools/pitch-deck-generator-hero-v2.webp"
+  },
+  widget: {"id":"pitch-deck-generator","mode":"custom"},
+};