智能助手

可发布到 npm 的嵌入式 AI 对话窗口，以及前端可配置的 AI 能力中台。

运行时包以 TypeScript 维护源码，构建输出到 dist。Vue3 只用于 demo，不进入运行时依赖，也不会随 npm 包一起发布。

目录

• src/: npm 工具包源码，TypeScript。
• src/core/capability-center.ts: 模型、知识库、内置系统 Skill、SKILL.md、项目方法技能的编排层。
• src/skills/built-in-skills.ts: npm 运行时内置系统 Skill，只随包发布，不放入 demo。
• src/components/web-dialog-ai.ts: 可嵌入 Web Component 对话窗口。
• src/providers/openai-compatible.ts: OpenAI-compatible /chat/completions 适配器，支持 SSE streaming。
• demo/App.vue: Vue3 <script setup lang="ts"> demo。
• demo/config/aiConfig.ts: demo 总配置。
• demo/config/knowledgeBases.ts: 知识库配置。
• demo/config/skillLibraries.ts: SKILL.md 技能库配置。
• demo/config/projectSkills.ts: 项目方法技能配置。
• demo/config/projectMethods.ts: demo 模拟的宿主项目方法。

本地开发

npm install
npm run dev

打开：

http://localhost:4173/

demo 左侧包含 Chat、Skills、知识库 三个菜单。Chat 挂载真实对话窗口；Skills 展示 npm 内置系统 Skill、demo SKILL.md 和项目方法 Skill；知识库 展示港口基础知识 seed 数据，不改变 npm 工具包的运行时结构。

当前知识库配置保留 source 和 metadata 字段，后续从数据库读取时可以让后端返回同样的 KnowledgeBaseConfig.documents 数据形状。

在对话里输入类似 打开知识库、打开skills界面、open skills、回到对话，demo 会通过 Project method skill 返回 uiAction，再由 Vue demo 切换左侧菜单。

在 demo 对话里输入类似 London weather、北京天气 会触发 demo 配置的 Weather SKILL.md，不属于项目方法技能，也不是 npm 运行时系统内置技能。它会把 wttr.in 和 Open-Meteo 的无 key 用法提供给模型作为上下文。

在对话里输入类似 切换英文、切换中文、切换深色系统、你可以叫我郭源潮，运行时会默认允许模型通过隐藏动作更新除 model 外的 AiConfig 配置。包内置中文和英文，默认语言也可以在 aiConfig.ui.locale 中配置。

构建与检查

npm run build
npm run demo:build
npm run check
npm pack --dry-run

npm run build 只构建发布包到 dist。npm run demo:build 只验证 Vue3 demo。

在业务项目中使用

安装发布后的包后，业务项目只需要准备一个挂载节点和一个 aiConfig.ts，不需要引入 demo、Vue 页面或额外样式。组件样式内置在 Web Component 的 Shadow DOM 中。

import { mountWebDialogAi } from "tt-agent-dialog";
import { aiConfig } from "./ai.config";

mountWebDialogAi("#ai-root", aiConfig);

也可以使用自定义元素：

import { defineWebDialogAi } from "tt-agent-dialog";
import { aiConfig } from "./ai.config";

defineWebDialogAi();

const element = document.createElement("web-dialog-ai");
element.config = aiConfig;
document.querySelector("#ai-root")?.appendChild(element);

配置拆分示例

// ai.config.ts
import { knowledgeBases } from "./knowledgeBases";
import { projectSkills } from "./projectSkills";
import { skillLibraries } from "./skillLibraries";
import type { AiConfig } from "tt-agent-dialog";

export const aiConfig: AiConfig = {
  model: {
    provider: "openai-compatible",
    baseUrl: "https://api.example.com/v1",
    endpoint: "/chat/completions",
    apiKey: "replace-in-frontend-for-now",
    model: "gpt-4.1-mini",
    stream: true,
  },
  conversation: {
    title: {
      "zh-CN": "智能助手",
      en: "Intelligent Assistant",
    },
    systemPrompt: "Answer using the configured context first.",
    welcomeMessage: {
      "zh-CN": "有什么可以帮忙的？",
      en: "How can I help?",
    },
    historyLimit: 10,
  },
  ui: {
    locale: "zh-CN",
    placeholder: {
      "zh-CN": "请输入消息",
      en: "Message Intelligent Assistant",
    },
    width: "100%",
    height: "640px",
  },
  preset: {
    identity: {
      "zh-CN": "智能助手，专注港口基础知识和业务系统问答。",
      en: "Intelligent Assistant focused on port knowledge and business system Q&A.",
    },
    tone: {
      "zh-CN": "专业、直接、简洁。",
      en: "Professional, direct, and concise.",
    },
    instructions: [
      {
        "zh-CN": "优先基于配置的知识库、公共 SKILL.md 和项目方法输出回答。",
        en: "Prefer configured knowledge bases, public SKILL.md instructions, and project method outputs.",
      },
    ],
  },
  aboutUser: {
    nickname: "访客",
    occupation: "未设置",
    details: {
      "zh-CN": "可由宿主项目通过对话解析后更新。",
      en: "The host project can update this through chat parsing.",
    },
  },
  appearance: {
    theme: "light",
  },
  knowledgeBases,
  skillLibraries,
  projectSkills,
};

conversation.title、conversation.welcomeMessage 和 ui.placeholder 可以直接写字符串，也可以写 { "zh-CN": "...", "en": "..." }。ui.locale 决定默认语言；模型触发配置动作更新 ui.locale 后，组件会自动取对应语言文本。

ui.width 和 ui.height 可以传 CSS 长度字符串或数字。设置后聊天窗口按固定宽高渲染，消息区内部滚动。

preset 会进入模型 system prompt，用来配置 AI 身份、语气和自定义指令。aboutUser 会进入模型上下文，用来配置用户昵称、职业和详情。appearance.theme 默认为 light，也可以设置为 dark。运行时 system prompt 默认会告诉模型：用户要求修改国际化、主题、AI 预设、关于你等非 model 配置时，输出隐藏的 <web-dialog-ai-action> 配置动作；组件会解析并应用这个动作，且会丢弃动作里的 model 字段。

requirements-review 和 kb-grounded-answer 是 npm 运行时内置系统 Skill，不需要业务项目或 demo 再配置。业务项目自己的 SKILL.md 技能可以继续写在 aiConfig.skillLibraries，也可以从后端接口返回后再组装进 aiConfig。项目方法 skill 的 handler 是函数，不能作为纯 JSON 从数据库传输，需要由宿主前端在 aiConfig.ts 中注入。

Project method skill 用于调用宿主项目自己的方法，例如打开左侧菜单。系统配置修改不需要 demo 项目方法技能，默认由模型隐藏动作处理。宿主项目仍然可以监听 web-dialog-ai:ui-action 处理自定义动作：

export const projectSkills = [
  {
    id: "open-left-menu",
    name: "Open Left Menu",
    triggers: ["打开知识库", "open skills"],
    handler: async ({ message }) => ({
      source: "host-project-method",
      uiAction: {
        type: "navigate-menu",
        target: message.includes("skills") ? "skills" : "knowledge",
      },
    }),
  },
];

SKILL.md 库格式

demo 里只有一个 Weather skill，不再单独维护 manifest.json，直接在 skillLibraries.ts 里用 ?raw 引入 SKILL.md：

import weatherSkill from "../skills/weather/SKILL.md?raw";

export const skillLibraries = [
  {
    id: "demo-skills",
    name: "Demo SKILL.md",
    enabled: true,
    skills: [
      {
        id: "weather",
        name: "Weather",
        content: weatherSkill,
        triggers: ["weather", "forecast", "temperature", "天气", "预报", "温度"],
      },
    ],
  },
];

demo/skills/weather/SKILL.md:

---
id: weather
name: Weather
description: Look up current weather with free no-key services.
---
Use this demo SKILL.md capability when the user asks about weather.

发布

发布前按你的 npm scope 修改 package.json 里的 name，然后执行：

npm run build
npm publish --access public