@kne/fastify-live-components-site 0.1.0 → 0.1.1

package/README.md

@@ -42,6 +42,20 @@ npm i --save @kne/fastify-live-components-site
 | getContentHost | 内容短链基址（不含站点 shorten） | `() => string` | `` `${prefix}` `` → 访问路径 `` `${prefix}/content/{code}` `` |
 | getShortenServices | 注入 shorten 服务 | `() => services` | `() => fastify.shorten.services` |
 | getAuthenticate | 按功能返回鉴权中间件 | `(type) => middleware[]` | 见下表 |
+| ai | AI 生成配置 | object | 见下表 |
+
+### ai
+
+| 属性名 | 说明 | 类型 | 默认值 |
+|-----|----|----|-----|
+| getAIModel | 返回 ai-sdk LanguageModel；未配置则全站 `aiEnabled: false` | `() => LanguageModel \| Promise<LanguageModel>` | `null` |
+| catalogCacheDir | 远程组件文档索引缓存目录（按库名/版本落盘） | string | 插件内 `data/ai-catalog` |
+| npmRegistry | 传给 `@kne/load-npm-info` 的 registry；不传则用其默认 | string | - |
+| remotePackageNames | remote 名 → npm 包名；默认 `` `@kne-components/${name}` `` | object | `{}` |
+
+站点 `options.aiEnabled === false` 时可关闭单站 AI（在 create/save 的 `options` 中配置）。
+
+提示词（refine/generate）仅插件内置，不允许外部传入。
 
 ### getAuthenticate(type)
 
@@ -72,6 +86,7 @@ npm i --save @kne/fastify-live-components-site
 
 | 方法 | 路径 | 说明 |
 |------|------|------|
+| GET | `{host}/info` | `{ name, status, aiEnabled, defaultPermission }` |
 | GET | `{host}/getFolderTree` | 文件树 |
 | GET | `{host}/get?id=` | 读文件（JSON：`{ id, name, permission, content }`） |
 | GET | `{prefix}/content/{contentShorten}` | 直出已保存 content（`text/plain`，无 `{code,data}`；不带站点 shorten） |
@@ -83,6 +98,31 @@ npm i --save @kne/fastify-live-components-site
 | POST | `{host}/save` | `{ id, content }` |
 | POST | `{host}/rename` | `{ id, name }` |
 | POST | `{host}/remove` | `{ ids: string[] }` |
+| POST | `{host}/ai/start` | 创建 AI 流任务；见下 |
+| GET | `{host}/ai/stream?token=` | SSE 流式输出 |
+
+### AI（需 `options.ai.getAIModel`）
+
+`POST {host}/ai/start` body：
+
+```js
+{
+  mode: 'refine' | 'generate',
+  messages: [{ role: 'user'|'assistant', content: string }],
+  content?: string,
+  scope?: object,
+  libs?: string[],
+  remotes?: [{ name, version, packageName? }],
+  selection?: { startLine, endLine, code, label }
+}
+```
+
+返回 `{ streamToken }`。随后 `GET {host}/ai/stream?token=` 以 SSE 推送：
+
+- `{ text, done: false }` 增量文本
+- `{ done: true, suggestedScope? }` 结束
+
+前端从 `@kne/remote-loader` preset 收集 `remotes`，并从当前环境合并 `libs` 键名一并上传。服务端按「库名/版本」缓存组件文档索引（`load-npm-info` + `md-doc`）。
 
 树节点：`{ id, name, type: 'file'|'directory', permission: 'r'|'rw', children? }`。
 

package/index.js

@@ -17,6 +17,12 @@ module.exports = fp(
         getSiteHost: null,
         // 内容短链基址（不含站点 shorten），默认 `${prefix}` → `${prefix}/content/{code}`
         getContentHost: null,
+        ai: {
+          getAIModel: null,
+          catalogCacheDir: null,
+          npmRegistry: null,
+          remotePackageNames: {}
+        },
         getShortenServices: () => {
           if (!fastify.shorten) {
             throw new Error('fastify-shorten plugin must be registered before @kne/fastify-live-components-site, or set options.getShortenServices');
@@ -57,6 +63,15 @@ module.exports = fp(
     if (typeof options.getContentHost !== 'function') {
       options.getContentHost = () => options.prefix;
     }
+    options.ai = Object.assign(
+      {
+        getAIModel: null,
+        catalogCacheDir: null,
+        npmRegistry: null,
+        remotePackageNames: {}
+      },
+      options.ai || {}
+    );
 
     fastify.register(require('@kne/fastify-namespace'), {
       options,

package/libs/ai/catalog.js

@@ -0,0 +1,191 @@
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const loadNpmInfo = require('@kne/load-npm-info');
+const { parse: parseMdDoc } = require('@kne/md-doc');
+const { stripHtml } = require('./prompts');
+
+const DOC_MD_RE = /<!--START_SECTION:DOC_MD-->([\s\S]*?)<!--END_SECTION:DOC_MD-->/;
+
+const extractDocMd = readme => {
+  if (!readme || typeof readme !== 'string') {
+    return '';
+  }
+  const m = readme.match(DOC_MD_RE);
+  return (m ? m[1] : readme).trim();
+};
+
+const splitComponentSections = docMd => {
+  if (!docMd) {
+    return [];
+  }
+  return docMd.split(/\n(?=# )/g).filter(s => s.startsWith('# '));
+};
+
+const resolvePackageName = (remote, options) => {
+  if (remote.packageName) {
+    return remote.packageName;
+  }
+  const map = options.ai?.remotePackageNames || {};
+  if (map[remote.name]) {
+    return map[remote.name];
+  }
+  return `@kne-components/${remote.name}`;
+};
+
+const getCacheDir = (options, remoteName, version) => {
+  const base = options.ai?.catalogCacheDir || path.resolve(__dirname, '../../data/ai-catalog');
+  return path.join(base, remoteName, version || 'latest');
+};
+
+const isCacheComplete = dir => {
+  try {
+    return fs.existsSync(path.join(dir, 'index.json')) && fs.existsSync(path.join(dir, 'components.json'));
+  } catch {
+    return false;
+  }
+};
+
+const readCachedCatalog = async (dir, remoteName, version) => {
+  const [index, components, meta] = await Promise.all([
+    fsp.readFile(path.join(dir, 'index.json'), 'utf8').then(JSON.parse),
+    fsp.readFile(path.join(dir, 'components.json'), 'utf8').then(JSON.parse),
+    fsp
+      .readFile(path.join(dir, 'meta.json'), 'utf8')
+      .then(JSON.parse)
+      .catch(() => ({}))
+  ]);
+  return {
+    remote: remoteName,
+    version,
+    packageName: meta.packageName,
+    index,
+    components
+  };
+};
+
+const buildCatalogFromReadme = (readme, remoteName) => {
+  const docMd = extractDocMd(readme);
+  const sections = splitComponentSections(docMd);
+  const index = [];
+  const components = {};
+
+  sections.forEach(section => {
+    let parsed;
+    try {
+      parsed = parseMdDoc(section);
+    } catch {
+      return;
+    }
+    const name = parsed.name || '';
+    if (!name) {
+      return;
+    }
+    const token = `${remoteName}:${name}`;
+    const summary = stripHtml(parsed.summary).slice(0, 400);
+    index.push({ name, token, summary });
+    components[name] = {
+      name,
+      token,
+      summary: parsed.summary || '',
+      api: parsed.api || '',
+      examples: (parsed.example?.list || []).map((ex, i) => ({
+        id: String(i),
+        title: ex.title || `示例${i + 1}`,
+        description: ex.description || '',
+        code: ex.code || ''
+      }))
+    };
+  });
+
+  return { index, components };
+};
+
+const ensureRemoteCatalog = async (remote, options) => {
+  const name = remote?.name;
+  const version = remote?.version || 'latest';
+  if (!name) {
+    return null;
+  }
+
+  const dir = getCacheDir(options, name, version);
+  if (isCacheComplete(dir)) {
+    return readCachedCatalog(dir, name, version);
+  }
+
+  const packageName = resolvePackageName(remote, options);
+  const loadOpts = {};
+  if (options.ai?.npmRegistry) {
+    loadOpts.registry = options.ai.npmRegistry;
+  }
+
+  let info;
+  try {
+    const pkgSpec = version && version !== 'latest' ? `${packageName}@${version}` : packageName;
+    info = await loadNpmInfo(pkgSpec, loadOpts);
+  } catch (e) {
+    console.warn(`[ai-catalog] load-npm-info failed for ${packageName}@${version}: ${e.message}`);
+    await fsp.mkdir(dir, { recursive: true });
+    const empty = { index: [], components: {} };
+    await Promise.all([
+      fsp.writeFile(path.join(dir, 'meta.json'), JSON.stringify({ packageName, version, error: e.message, builtAt: Date.now() }, null, 2)),
+      fsp.writeFile(path.join(dir, 'index.json'), JSON.stringify(empty.index, null, 2)),
+      fsp.writeFile(path.join(dir, 'components.json'), JSON.stringify(empty.components, null, 2))
+    ]);
+    return { remote: name, version, packageName, ...empty };
+  }
+
+  const { index, components } = buildCatalogFromReadme(info.readme, name);
+  await fsp.mkdir(dir, { recursive: true });
+  await Promise.all([
+    fsp.writeFile(path.join(dir, 'meta.json'), JSON.stringify({ packageName, version: info.version || version, builtAt: Date.now() }, null, 2)),
+    fsp.writeFile(path.join(dir, 'index.json'), JSON.stringify(index, null, 2)),
+    fsp.writeFile(path.join(dir, 'components.json'), JSON.stringify(components, null, 2))
+  ]);
+
+  return {
+    remote: name,
+    version: info.version || version,
+    packageName,
+    index,
+    components
+  };
+};
+
+const ensureRemotesCatalogs = async (remotes, options) => {
+  const list = Array.isArray(remotes) ? remotes : [];
+  const catalogs = [];
+  for (const remote of list) {
+    const cat = await ensureRemoteCatalog(remote, options);
+    if (cat) {
+      catalogs.push(cat);
+    }
+  }
+  return catalogs;
+};
+
+const getExampleCode = (catalogs, { remote, version, component, exampleId }) => {
+  const cat = (catalogs || []).find(c => c.remote === remote && (!version || c.version === version || String(c.version) === String(version))) || (catalogs || []).find(c => c.remote === remote);
+  if (!cat) {
+    return { error: `catalog not found: ${remote}` };
+  }
+  const comp = cat.components?.[component];
+  if (!comp) {
+    return { error: `component not found: ${component}` };
+  }
+  const ex = (comp.examples || []).find(e => String(e.id) === String(exampleId));
+  if (!ex) {
+    return { error: `example not found: ${exampleId}` };
+  }
+  return { title: ex.title, description: ex.description, code: ex.code || '' };
+};
+
+module.exports = {
+  ensureRemotesCatalogs,
+  ensureRemoteCatalog,
+  getExampleCode,
+  getCacheDir,
+  buildCatalogFromReadme,
+  extractDocMd,
+  resolvePackageName
+};

package/libs/ai/prompts.js

@@ -0,0 +1,154 @@
+const stripHtml = html =>
+  String(html || '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const LIVE_COMPONENT_SPEC = `
+## Live 组件规范（必须遵守）
+
+1. 编辑对象是配置里的 content 字段：一段 JSX 表达式源码，不是完整 .js 模块，也不是 PlantUML 编码串。
+2. 运行时会编译为 render(<content>);，因此 content 应是可放入 render(...) 的表达式；不要写 import / export / 外层 render(。
+3. 运行时可用标识：
+   - React、Antd（antd 全量）、props（合并后的组件参数）
+   - scope 声明的变量名（如 FormInfo ← components-core:FormInfo），另有 PureGlobal
+   - libs：仅限当前请求告知的 libKeys，禁止使用未列出的 lib 标识符
+4. 组件选用优先级（强制）：
+   1) 远程组件优先（本次 remotes 索引 / 当前 scope 中已有）
+   2) 其次 Antd.*
+   3) 最后原生 HTML；禁止用 HTML 重复实现已有远程或 Antd 能力
+5. props：{ name: { type, defaultValue } }，代码里用 props.xxx；scope：{ 变量名: 'moduleToken' }。若使用了当前 scope 没有的远程组件，须通过 suggestScope 工具声明 suggestedScope。
+6. 使用 FormInfo 时字段须落在 <FormInfo.Form> 上下文中（已有则保持；缺失可包一层）。
+7. 保持现有代码风格；不引入 npm 包名式 import。文档示例中的 _FormInfo / @components/FormInfo 在 Live 中应写成 scope 变量 FormInfo + token components-core:FormInfo。
+`.trim();
+
+const buildLibsSection = libKeys => {
+  const keys = Array.isArray(libKeys) ? libKeys.filter(Boolean) : [];
+  if (!keys.length) {
+    return '当前环境可用 libs：（无）请勿使用任何第三方 lib 标识符。';
+  }
+  return `当前环境可用 libs：${keys.join(', ')}。只能使用这些标识符。`;
+};
+
+const buildCatalogIndexSection = catalogs => {
+  if (!catalogs?.length) {
+    return '远程组件索引：（无可用索引）';
+  }
+  const lines = ['远程组件索引（L1）：'];
+  catalogs.forEach(cat => {
+    lines.push(`### ${cat.remote}@${cat.version}`);
+    (cat.index || []).forEach(item => {
+      lines.push(`- ${item.name} | ${item.token} | ${item.summary || ''}`);
+    });
+  });
+  return lines.join('\n');
+};
+
+const buildComponentDetailSection = (catalogs, hitNames) => {
+  if (!hitNames?.length || !catalogs?.length) {
+    return '';
+  }
+  const nameSet = new Set(hitNames.map(n => String(n).toLowerCase()));
+  const blocks = [];
+  catalogs.forEach(cat => {
+    const components = cat.components || {};
+    Object.keys(components).forEach(name => {
+      if (!nameSet.has(name.toLowerCase())) {
+        return;
+      }
+      const c = components[name];
+      const examples = (c.examples || []).map(ex => `- id=${ex.id} | ${ex.title || ''} | ${ex.description || ''}`).join('\n');
+      blocks.push(
+        [
+          `### 组件详情 ${c.token || `${cat.remote}:${name}`}`,
+          stripHtml(c.summary).slice(0, 800),
+          c.api ? `API 摘要：${stripHtml(c.api).slice(0, 1200)}` : '',
+          '示例目录（仅 title/description，完整 code 请调用 getComponentExample）：',
+          examples || '（无示例）'
+        ]
+          .filter(Boolean)
+          .join('\n')
+      );
+    });
+  });
+  return blocks.join('\n\n');
+};
+
+const collectHitComponentNames = ({ messages = [], scope = {}, catalogs = [] }) => {
+  const hits = new Set();
+  Object.keys(scope || {}).forEach(k => hits.add(k));
+  Object.values(scope || {}).forEach(token => {
+    const m = String(token).match(/:([^@]+)/);
+    if (m) {
+      hits.add(m[1]);
+    }
+  });
+  const text = (messages || []).map(m => m.content || '').join('\n');
+  catalogs.forEach(cat => {
+    (cat.index || []).forEach(item => {
+      if (item.name && text.includes(item.name)) {
+        hits.add(item.name);
+      }
+    });
+  });
+  return Array.from(hits);
+};
+
+const buildRefineSystemPrompt = ctx => {
+  const { libKeys = [], catalogs = [], messages = [], scope = {}, hasSelection, selectionLabel } = ctx;
+  const hits = collectHitComponentNames({ messages, scope, catalogs });
+  const detail = buildComponentDetailSection(catalogs, hits);
+  return [
+    '你是 Live 组件需求顾问（不是通用前端架构师）。只聊需求、完善描述，禁止输出可运行业务源码或大段 JSX。',
+    LIVE_COMPONENT_SPEC,
+    buildLibsSection(libKeys),
+    buildCatalogIndexSection(catalogs),
+    detail,
+    hasSelection ? `当前讨论范围限定在选中组件：${selectionLabel || '已选中片段'}。` : '当前讨论整份 content。',
+    `行为规则：
+1. 推荐组件时遵守：远程 → Antd → HTML。
+2. 涉及 UI 结构时，必须用 ASCII 线框给出 2～4 个方案（A/B/C…），简述差异，请用户选择；选定前不要宣称需求已确认。
+3. 信息与布局都够了后，用短结构化小结（目标 / 改动点 / 选用布局 / 建议组件 / 是否动 props·scope），并明确提示用户点击界面上的「开始生成」按钮。
+4. 不要暗示会自动写代码或自行进入生成阶段。
+5. 不要输出完整组件实现。`
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+};
+
+const buildGenerateSystemPrompt = ctx => {
+  const { libKeys = [], catalogs = [], messages = [], scope = {}, hasSelection, selectionLabel } = ctx;
+  const hits = collectHitComponentNames({ messages, scope, catalogs });
+  // generate：对命中组件 + 索引前列组件提供详情；若无命中则不塞过多
+  const detailNames = hits.length ? hits : (catalogs[0]?.index || []).slice(0, 5).map(i => i.name);
+  const detail = buildComponentDetailSection(catalogs, detailNames);
+  return [
+    '你是 Live content 代码生成器。根据已完善的需求对话，一次产出可直接写入编辑器的源码。',
+    LIVE_COMPONENT_SPEC,
+    buildLibsSection(libKeys),
+    buildCatalogIndexSection(catalogs),
+    detail,
+    hasSelection ? `只输出替换后的选中片段源码（选中：${selectionLabel || ''}）。不要输出整文件。` : '输出替换后的整份 content 源码。',
+    `工具：
+- getComponentExample：按示例 id 读取完整示例 code（先看示例目录的 description 再决定是否拉取）。
+- suggestScope：若使用了当前 scope 没有的远程组件，调用此工具声明 { 变量名: 'remote:Component' }。
+
+输出契约：
+1. 优先纯代码；不要追问、不要复述需求、不要解释。
+2. 选型：远程 → Antd → HTML。
+3. 只能使用本次 libs 键与 scope∪suggestedScope。
+4. 需要官方示例时根据 description 挑选后调用 getComponentExample。`
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+};
+
+module.exports = {
+  LIVE_COMPONENT_SPEC,
+  stripHtml,
+  buildRefineSystemPrompt,
+  buildGenerateSystemPrompt,
+  collectHitComponentNames,
+  buildCatalogIndexSection,
+  buildComponentDetailSection
+};

package/libs/ai/run.js

@@ -0,0 +1,117 @@
+const { streamText, tool, stepCountIs } = require('ai');
+const { z } = require('zod');
+const { buildRefineSystemPrompt, buildGenerateSystemPrompt } = require('./prompts');
+const { getExampleCode } = require('./catalog');
+
+const writeSse = (reply, data) => {
+  reply.raw.write(`data: ${JSON.stringify(data)}\n\n`);
+};
+
+const buildUserMessages = job => {
+  const messages = Array.isArray(job.messages) ? job.messages.filter(m => m && (m.role === 'user' || m.role === 'assistant') && m.content).map(m => ({ role: m.role, content: String(m.content) })) : [];
+
+  if (job.mode === 'generate') {
+    const parts = [];
+    if (job.selection?.code) {
+      parts.push(`[选中片段]\n${job.selection.code}`);
+    } else if (job.content) {
+      parts.push(`[当前 content]\n${job.content}`);
+    }
+    if (job.scope && Object.keys(job.scope).length) {
+      parts.push(`[当前 scope]\n${JSON.stringify(job.scope, null, 2)}`);
+    }
+    if (parts.length) {
+      messages.push({ role: 'user', content: parts.join('\n\n') });
+    }
+  } else if (job.selection?.code) {
+    messages.push({ role: 'user', content: `[当前选中片段参考]\n${job.selection.code}` });
+  }
+
+  if (!messages.length) {
+    messages.push({ role: 'user', content: job.mode === 'generate' ? '请根据对话生成代码。' : '请帮助完善需求。' });
+  }
+
+  return messages;
+};
+
+const runAiStream = async (job, reply) => {
+  const model = await job.getAIModel();
+  if (!model) {
+    writeSse(reply, { text: 'AI model 未配置', done: true });
+    return;
+  }
+
+  const ctx = {
+    mode: job.mode,
+    hasSelection: !!(job.selection?.code || job.selection?.startLine),
+    selectionLabel: job.selection?.label,
+    scopeKeys: Object.keys(job.scope || {}),
+    libKeys: job.libs || [],
+    catalogs: job.catalogs || [],
+    messages: job.messages || [],
+    scope: job.scope || {}
+  };
+
+  const system = job.mode === 'generate' ? buildGenerateSystemPrompt(ctx) : buildRefineSystemPrompt(ctx);
+  let suggestedScope = {};
+
+  const exampleTool = tool({
+    description: job.mode === 'generate' ? '按示例 id 读取远程组件文档中的完整示例代码' : '可选：查看某示例代码以便更准确描述需求（refine 阶段仍不要输出业务实现代码）',
+    inputSchema: z.object({
+      remote: z.string(),
+      version: z.string().optional(),
+      component: z.string(),
+      exampleId: z.string()
+    }),
+    execute: async ({ remote, version, component, exampleId }) => {
+      return getExampleCode(job.catalogs, { remote, version, component, exampleId });
+    }
+  });
+
+  const tools =
+    job.mode === 'generate'
+      ? {
+          getComponentExample: exampleTool,
+          suggestScope: tool({
+            description: '声明需要合并进编辑器的 scope（远程组件 token）',
+            inputSchema: z.object({
+              scope: z.record(z.string())
+            }),
+            execute: async ({ scope }) => {
+              suggestedScope = Object.assign({}, suggestedScope, scope || {});
+              return { ok: true, suggestedScope };
+            }
+          })
+        }
+      : {
+          getComponentExample: exampleTool
+        };
+
+  const result = streamText({
+    model,
+    system,
+    messages: buildUserMessages(job),
+    tools,
+    stopWhen: stepCountIs(job.mode === 'generate' ? 8 : 4)
+  });
+
+  for await (const part of result.fullStream) {
+    if (part.type === 'text-delta') {
+      const text = part.text || '';
+      if (text) {
+        writeSse(reply, { text, done: false });
+      }
+    }
+  }
+
+  const donePayload = { done: true };
+  if (Object.keys(suggestedScope).length) {
+    donePayload.suggestedScope = suggestedScope;
+  }
+  writeSse(reply, donePayload);
+};
+
+module.exports = {
+  runAiStream,
+  buildUserMessages
+};

package/libs/ai/stream-store.js

@@ -0,0 +1,42 @@
+const crypto = require('node:crypto');
+
+const TTL_MS = 2 * 60 * 1000;
+const store = new Map();
+
+const cleanup = () => {
+  const now = Date.now();
+  for (const [key, value] of store.entries()) {
+    if (now - value.createdAt > TTL_MS) {
+      store.delete(key);
+    }
+  }
+};
+
+const createStreamJob = payload => {
+  cleanup();
+  const token = crypto.randomBytes(16).toString('hex');
+  store.set(token, { ...payload, createdAt: Date.now() });
+  return token;
+};
+
+const takeStreamJob = token => {
+  cleanup();
+  const job = store.get(token);
+  if (!job) {
+    return null;
+  }
+  store.delete(token);
+  return job;
+};
+
+const peekStreamJob = token => {
+  cleanup();
+  return store.get(token) || null;
+};
+
+module.exports = {
+  createStreamJob,
+  takeStreamJob,
+  peekStreamJob,
+  TTL_MS
+};

package/libs/controllers/entry.js

@@ -47,6 +47,85 @@ module.exports = fp(async (fastify, options) => {
     }
   );
 
+  fastify.get(
+    `${options.prefix}/:shorten/info`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '站点信息（含是否支持 AI）',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.ai.getInfo(request.authenticatePayload);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/ai/start`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '创建 AI 流式任务，返回 streamToken',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          properties: {
+            mode: { type: 'string' },
+            messages: { type: 'array' },
+            content: { type: 'string' },
+            scope: { type: 'object' },
+            libs: { type: 'array' },
+            remotes: { type: 'array' },
+            selection: { type: 'object' }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.ai.start(request.authenticatePayload, request.body || {});
+    }
+  );
+
+  fastify.get(
+    `${options.prefix}/:shorten/ai/stream`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: 'SSE 推送 AI 流式输出',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        query: {
+          type: 'object',
+          required: ['token'],
+          properties: {
+            token: { type: 'string' }
+          }
+        }
+      }
+    },
+    async (request, reply) => {
+      return services.ai.stream(request.authenticatePayload, request.query, reply);
+    }
+  );
+
   fastify.get(
     `${options.prefix}/:shorten/getFolderTree`,
     {

package/libs/services/ai.js

@@ -0,0 +1,98 @@
+const fp = require('fastify-plugin');
+const { Forbidden, BadRequest, NotFound } = require('http-errors');
+const { ensureRemotesCatalogs } = require('../ai/catalog');
+const { createStreamJob, takeStreamJob } = require('../ai/stream-store');
+const { runAiStream } = require('../ai/run');
+
+module.exports = fp(async (fastify, options) => {
+  const isAiEnabledForSite = site => {
+    if (typeof options.ai?.getAIModel !== 'function') {
+      return false;
+    }
+    const siteOptions = site?.options && typeof site.options === 'object' ? site.options : {};
+    return siteOptions.aiEnabled !== false;
+  };
+
+  const getInfo = async authenticatePayload => {
+    const site = authenticatePayload.site;
+    return {
+      name: site.name,
+      status: site.status,
+      defaultPermission: site.defaultPermission,
+      aiEnabled: isAiEnabledForSite(site)
+    };
+  };
+
+  const start = async (authenticatePayload, body = {}) => {
+    if (!isAiEnabledForSite(authenticatePayload.site)) {
+      throw new Forbidden('站点未开启 AI 生成');
+    }
+    if (typeof options.ai?.getAIModel !== 'function') {
+      throw new Forbidden('AI 未配置');
+    }
+
+    const mode = body.mode === 'generate' ? 'generate' : 'refine';
+    const messages = Array.isArray(body.messages) ? body.messages : [];
+    const remotes = Array.isArray(body.remotes) ? body.remotes : [];
+    const libs = Array.isArray(body.libs) ? body.libs.map(String) : [];
+    const scope = body.scope && typeof body.scope === 'object' ? body.scope : {};
+    const content = typeof body.content === 'string' ? body.content : '';
+    const selection = body.selection && typeof body.selection === 'object' ? body.selection : null;
+
+    if (mode === 'refine' && !messages.length) {
+      throw new BadRequest('messages 不能为空');
+    }
+
+    const catalogs = await ensureRemotesCatalogs(remotes, options);
+    const streamToken = createStreamJob({
+      mode,
+      messages,
+      remotes,
+      libs,
+      scope,
+      content,
+      selection,
+      catalogs,
+      getAIModel: options.ai.getAIModel
+    });
+
+    return { streamToken };
+  };
+
+  const stream = async (authenticatePayload, { token }, reply) => {
+    if (!isAiEnabledForSite(authenticatePayload.site)) {
+      throw new Forbidden('站点未开启 AI 生成');
+    }
+    if (!token) {
+      throw new BadRequest('token 不能为空');
+    }
+    const job = takeStreamJob(token);
+    if (!job) {
+      throw new NotFound('stream token 无效或已过期');
+    }
+
+    reply.hijack();
+    reply.raw.writeHead(200, {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'Access-Control-Allow-Origin': '*'
+    });
+
+    try {
+      await runAiStream(job, reply);
+    } catch (e) {
+      reply.raw.write(`data: ${JSON.stringify({ text: e.message || 'AI 流式失败', done: true })}\n\n`);
+    }
+    reply.raw.end();
+  };
+
+  Object.assign(fastify[options.name].services, {
+    ai: {
+      getInfo,
+      start,
+      stream,
+      isAiEnabledForSite
+    }
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-live-components-site",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Fastify 插件：为 LiveComponentEditor 提供远程站点文件树与短链访问管理",
   "main": "index.js",
   "scripts": {
@@ -40,8 +40,12 @@
   },
   "homepage": "https://github.com/kne-union/fastify-live-components-site#readme",
   "dependencies": {
+    "@kne/load-npm-info": "^0.1.8",
+    "@kne/md-doc": "^0.1.24",
+    "ai": "^5.0.220",
     "http-errors": "^2.0.0",
-    "lodash": "^4.17.21"
+    "lodash": "^4.17.21",
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "@kne/fastify-account": "*",