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

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,32 @@ 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,
+  props?: 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?, suggestedProps? }` 结束（生成阶段可通过工具声明组件域 / 组件参数）
+
+前端从 `@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,216 @@
+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,
+    meta,
+    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)) {
+    const cached = await readCachedCatalog(dir, name, version);
+    if ((cached.index || []).length || Object.keys(cached.components || {}).length) {
+      return cached;
+    }
+  }
+
+  const packageName = resolvePackageName(remote, options);
+  const writeEmpty = async error => {
+    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, 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, error, ...empty };
+  };
+
+  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}`);
+    return writeEmpty(e.message);
+  }
+
+  try {
+    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
+    };
+  } catch (e) {
+    console.warn(`[ai-catalog] build failed for ${packageName}@${version}: ${e.message}`);
+    return writeEmpty(e.message);
+  }
+};
+
+const withTimeout = (promise, ms, label) => {
+  let timer;
+  return Promise.race([
+    Promise.resolve(promise).finally(() => clearTimeout(timer)),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timeout after ${ms}ms`)), ms);
+    })
+  ]);
+};
+
+const ensureRemotesCatalogs = async (remotes, options) => {
+  const list = Array.isArray(remotes) ? remotes : [];
+  const timeoutMs = Number(options.ai?.catalogTimeoutMs) > 0 ? Number(options.ai.catalogTimeoutMs) : 20000;
+  const results = await Promise.all(
+    list.map(remote =>
+      withTimeout(ensureRemoteCatalog(remote, options), timeoutMs, remote?.name || 'remote').catch(e => {
+        console.warn(`[ai-catalog] ${remote?.name || '?'}: ${e.message}`);
+        return null;
+      })
+    )
+  );
+  return results.filter(Boolean);
+};
+
+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/extract-props.js

@@ -0,0 +1,61 @@
+const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const inferPropDef = (code, name) => {
+  if (/^on[A-Z]/.test(name)) {
+    return { type: 'function', defaultValue: '()=>null' };
+  }
+  const access = `props(?:\\?\\.)?\\.${escapeRegExp(name)}`;
+  const orString = code.match(new RegExp(`${access}\\s*(?:\\|\\||\\?\\?)\\s*['"\`]([^'"\`]*)['"\`]`));
+  if (orString) {
+    return { type: 'string', defaultValue: orString[1] };
+  }
+  const orNum = code.match(new RegExp(`${access}\\s*(?:\\|\\||\\?\\?)\\s*(-?\\d+(?:\\.\\d+)?)`));
+  if (orNum) {
+    return { type: 'number', defaultValue: orNum[1] };
+  }
+  const orBool = code.match(new RegExp(`${access}\\s*(?:\\|\\||\\?\\?)\\s*(true|false)\\b`));
+  if (orBool) {
+    return { type: 'boolean', defaultValue: orBool[1] };
+  }
+  if (new RegExp(`${access}\\s*(?:\\|\\||\\?\\?)\\s*\\[`).test(code)) {
+    return { type: 'array', defaultValue: '[]' };
+  }
+  if (new RegExp(`${access}\\s*(?:\\|\\||\\?\\?)\\s*\\{`).test(code)) {
+    return { type: 'object', defaultValue: '{}' };
+  }
+  return { type: 'string', defaultValue: '' };
+};
+
+/** 从生成代码中扫描 props.xxx，补齐 suggestProps 可能漏掉的声明 */
+const extractPropsFromCode = (code, existingProps = {}) => {
+  const text = String(code || '');
+  if (!text.trim()) {
+    return {};
+  }
+  // 去掉 markdown 围栏外壳再扫，避免漏检
+  const stripped = text.replace(/^```(?:jsx|javascript|js|tsx|ts)?\s*/i, '').replace(/```\s*$/i, '');
+  const names = new Set();
+  const re = /props(?:\?\.)?\.([A-Za-z_$][\w$]*)|props\[\s*['"`]([^'"`]+)['"`]\s*\]/g;
+  let match;
+  while ((match = re.exec(stripped))) {
+    const name = match[1] || match[2];
+    if (name) {
+      names.add(name);
+    }
+  }
+  const result = {};
+  names.forEach(name => {
+    if (existingProps && existingProps[name]) {
+      return;
+    }
+    result[name] = inferPropDef(stripped, name);
+  });
+  return result;
+};
+
+const mergeSuggestedProps = (code, suggestedProps, existingProps = {}) => Object.assign({}, extractPropsFromCode(code, existingProps), suggestedProps && typeof suggestedProps === 'object' ? suggestedProps : {});
+
+module.exports = {
+  extractPropsFromCode,
+  mergeSuggestedProps
+};

package/libs/ai/prompts.js

@@ -0,0 +1,218 @@
+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 **只能是可放入 JSX 子节点位置的表达式**（通常是一个根 JSX 元素，或用 \`<>...</>\` / \`(...)\` 包裹的表达式）。
+   - **禁止**写 \`import\` / \`export\` / 外层 \`render(\`。
+   - **禁止**在 content 里写 JS 语句：\`const\` / \`let\` / \`var\` / \`function\` / \`class\` / \`return\` / \`if\` 语句块等。
+   - **禁止**伪代码块：\`<>{ const x = 1; return (<div/>); }</>\` 或 IIFE \`(()=>{...})()\`（除非整段仍是纯表达式且无语句；默认不要用）。
+   - 需要临时数据时，把数组/对象 **内联**在 JSX 属性里，例如 \`options={[{ label: '男', value: '男' }]}\`。
+3. 运行时可用标识：
+   - React、Antd（antd 全量，但表单场景有额外禁令，见第 8 条）、props（合并后的组件参数）
+   - scope 声明的变量名（如 FormInfo ← components-core:FormInfo），另有 PureGlobal
+   - libs：仅限当前请求告知的 libKeys，禁止使用未列出的 lib 标识符
+4. 组件选用优先级（强制）：
+   1) 远程组件优先（本次 remotes 索引 / 当前 scope 中已有）
+   2) 其次 Antd.*（**表单除外，见第 8 条**）
+   3) 最后原生 HTML；禁止用 HTML 重复实现已有远程或 Antd 能力
+5. props 与 scope（生成时必须显式声明，不能只写在 content 里假设已存在）：
+   - props 形态：\`{ name: { type: 'string'|'number'|'boolean'|'array'|'object'|'function', defaultValue } }\`，代码里用 \`props.xxx\`。
+   - scope 形态：\`{ 变量名: 'moduleToken' }\`（如 \`FormInfo: 'components-core:FormInfo'\`）。
+   - 使用了当前 scope 没有的远程组件 → **必须**调用 \`suggestScope\`。
+   - content 使用了 \`props.xxx\` 且当前 props 没有该字段 → **必须**调用 \`suggestProps\` 补齐声明（含 type 与合理 defaultValue；function 类型 defaultValue 用 \`'()=>null'\`）。
+6. 使用 FormInfo 时字段须落在 <FormInfo.Form> 上下文中（已有则保持；缺失可包一层）。
+7. 保持现有代码风格；不引入 npm 包名式 import。文档示例中的 _FormInfo / @components/FormInfo 在 Live 中应写成 scope 变量 FormInfo + token components-core:FormInfo。
+8. **表单强制规范（最高优先级，覆盖第 4 条的 Antd 选型）**：
+   - 凡涉及表单（录入、校验、提交、表单项布局），**必须**用 \`components-core:FormInfo\` 实现，并确保 scope 含 \`FormInfo: 'components-core:FormInfo'\`（可用 suggestScope）。
+   - **禁止**使用 \`Antd.Form\` / \`Antd.Form.Item\` / \`Antd.Form.List\` 以及把 \`Antd.Input\` / \`Antd.Select\` / \`Antd.DatePicker\` 等当作表单字段直接拼表单。
+   - **禁止** \`const { Input } = FormInfo.fields\` 这类解构（属于 JS 语句，Live 无法运行）。字段必须写成 \`FormInfo.fields.Input\` / \`FormInfo.fields.Select\` 等。
+   - 标准写法示例（注意整段都是 JSX，无 const/return）：
+\`\`\`jsx
+<FormInfo.Form data={{}}>
+  <FormInfo
+    title="基础信息"
+    list={[
+      <FormInfo.fields.Input name="name" label="姓名" rule="REQ" placeholder="请输入姓名" />,
+      <FormInfo.fields.Select
+        name="gender"
+        label="性别"
+        rule="REQ"
+        options={[
+          { label: '男', value: '男' },
+          { label: '女', value: '女' }
+        ]}
+        placeholder="请选择性别"
+      />
+    ]}
+  />
+  <FormInfo.SubmitButton>提交</FormInfo.SubmitButton>
+</FormInfo.Form>
+\`\`\`
+   - 字段必须带 FormInfo 字段契约：\`name\`、\`label\`，校验用 \`rule\` 字符串（如 \`REQ\`、\`REQ EMAIL\`、\`LEN-3-50\`），需要自定义规则时走 FormInfo.Form 的 \`rules\` / \`interceptors\`，不要用 Antd rules。
+   - **自定义字段类型**：不得手写 Antd Form.Item 包装。必须符合 FormInfo 字段规范——优先复用 \`FormInfo.fields.*\`；若确需自定义，只能用表达式方式挂到已有字段能力上，且仍出现在 \`FormInfo\` 的 \`list\` 与 \`FormInfo.Form\` 上下文中（不要在 content 里声明新组件函数）。
+`.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);
+      }
+    });
+  });
+  // 表单相关需求强制带上 FormInfo 文档命中，便于注入 L2
+  if (/表单|校验|FormInfo|Form\.Item|录入|提交|字段/.test(text)) {
+    hits.add('FormInfo');
+  }
+  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；但**凡表单必须推荐 FormInfo**，禁止建议 Antd.Form / Form.Item。
+2. 涉及表单时提醒：字段写 FormInfo.fields.*（禁止解构 const），options 等数据内联在 JSX 属性；必须是纯 JSX 表达式；scope 需 FormInfo。
+3. 涉及 UI 结构时，必须用 **HTML 线框示意**给出 2～4 个方案（A/B/C…），简述差异，请用户选择；**禁止 ASCII 字符画**。HTML 必须放在 Markdown 的 \`\`\`html 围栏中（前端会渲染为真实 DOM，不要指望当代码展示）。示例外层可用 class="ui-mock" 或 "layout-mock"。回复整体使用 Markdown。选定前不要宣称需求已确认。
+4. 信息与布局都够了后，用短结构化小结（目标 / 改动点 / 选用布局 / 建议组件 / 是否动 props·scope），并明确提示用户点击界面上的「开始生成」按钮。
+5. 不要暗示会自动写代码或自行进入生成阶段。
+6. 不要输出完整组件实现（可运行 JSX）。`
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+};
+
+const buildCurrentPropsSection = props => {
+  const keys = props && typeof props === 'object' ? Object.keys(props) : [];
+  if (!keys.length) {
+    return '当前组件参数 props：（空）若 content 使用 props.xxx，必须 suggestProps 声明。';
+  }
+  return `当前组件参数 props：\n${JSON.stringify(props, null, 2)}\n若新增 props.xxx，必须 suggestProps 补齐未声明字段。`;
+};
+
+const buildCurrentScopeSection = scope => {
+  const keys = scope && typeof scope === 'object' ? Object.keys(scope) : [];
+  if (!keys.length) {
+    return '当前组件域 scope：（空）若使用远程组件，必须 suggestScope 声明。';
+  }
+  return `当前组件域 scope：\n${JSON.stringify(scope, null, 2)}\n若使用未列出的远程组件，必须 suggestScope 补齐。`;
+};
+
+const buildGenerateSystemPrompt = ctx => {
+  const { libKeys = [], catalogs = [], messages = [], scope = {}, props = {}, 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 代码生成器。根据已完善的需求对话，一次产出可直接写入编辑器的源码，并同步声明所需的 scope / props。',
+    LIVE_COMPONENT_SPEC,
+    buildLibsSection(libKeys),
+    buildCurrentScopeSection(scope),
+    buildCurrentPropsSection(props),
+    buildCatalogIndexSection(catalogs),
+    detail,
+    hasSelection ? `只输出替换后的选中片段源码（选中：${selectionLabel || ''}）。不要输出整文件。` : '输出替换后的整份 content 源码。',
+    `工具：
+- getComponentExample：按示例 id 读取完整示例 code（先看示例目录的 description 再决定是否拉取）。
+- suggestScope：声明需要合并进编辑器「组件域」的 scope，形如 { FormInfo: 'components-core:FormInfo' }。
+- suggestProps：声明需要合并进编辑器「组件参数」的 props，形如 { title: { type: 'string', defaultValue: '标题' } }。
+
+输出契约：
+1. 优先纯代码；不要追问、不要复述需求、不要解释。
+2. **输出必须是纯 JSX 表达式**（可被 \`render(<content>);\` 包裹）；禁止 const/let/return/函数声明，禁止 \`<>{ const ...; return (...); }</>\`。
+3. 选型：远程 → Antd → HTML；**表单必须 FormInfo，禁止 Antd.Form / Form.Item**；字段用 \`FormInfo.fields.Xxx\`，options 内联在 JSX 属性中。
+4. 只能使用本次 libs 键与 scope∪suggestedScope；用到 FormInfo 时必须 suggestScope（若 scope 尚无）。
+5. content 中凡出现 props.xxx，必须已在当前 props 或本次 suggestProps 中声明；不要虚构未声明参数。
+6. 自定义表单字段优先复用 FormInfo.fields；禁止在 content 里新声明组件函数。
+7. 需要官方示例时根据 description 挑选后调用 getComponentExample（优先 FormInfo）；仿写时把示例里的 \`const { Input } = fields\` 改成 \`FormInfo.fields.Input\`。
+8. **工具调用结束后必须再输出完整 JSX 正文**；禁止只调 suggestScope/suggestProps/getComponentExample 而不写代码。不要包 Markdown 说明；若使用代码围栏，仅允许一个 \`\`\`jsx 围栏且围栏内是完整可运行 JSX。`
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+};
+
+module.exports = {
+  LIVE_COMPONENT_SPEC,
+  stripHtml,
+  buildRefineSystemPrompt,
+  buildGenerateSystemPrompt,
+  collectHitComponentNames,
+  buildCatalogIndexSection,
+  buildComponentDetailSection
+};

package/libs/ai/run.js

@@ -0,0 +1,172 @@
+const { streamText, tool, stepCountIs } = require('ai');
+const { z } = require('zod');
+const { buildRefineSystemPrompt, buildGenerateSystemPrompt } = require('./prompts');
+const { getExampleCode } = require('./catalog');
+const { mergeSuggestedProps } = require('./extract-props');
+
+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 (job.props && Object.keys(job.props).length) {
+      parts.push(`[当前 props]\n${JSON.stringify(job.props, 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 propDefSchema = z.object({
+  type: z.enum(['string', 'number', 'boolean', 'array', 'object', 'function']),
+  defaultValue: z.any().optional()
+});
+
+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 || {},
+    props: job.props || {}
+  };
+
+  const system = job.mode === 'generate' ? buildGenerateSystemPrompt(ctx) : buildRefineSystemPrompt(ctx);
+  let suggestedScope = {};
+  let suggestedProps = {};
+  let streamedText = '';
+
+  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 };
+            }
+          }),
+          suggestProps: tool({
+            description: '声明需要合并进编辑器「组件参数」的 props；content 使用 props.xxx 时必须调用。形如 { title: { type: "string", defaultValue: "标题" } }',
+            inputSchema: z.object({
+              props: z.record(propDefSchema)
+            }),
+            execute: async ({ props }) => {
+              suggestedProps = Object.assign({}, suggestedProps, props || {});
+              return { ok: true, suggestedProps };
+            }
+          })
+        }
+      : {
+          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 || part.delta || part.textDelta || '';
+      if (text) {
+        streamedText += text;
+        writeSse(reply, { text, done: false });
+      }
+    }
+  }
+
+  let finalText = streamedText;
+  try {
+    const fromResult = await result.text;
+    if (typeof fromResult === 'string' && fromResult) {
+      if (!streamedText) {
+        finalText = fromResult;
+        writeSse(reply, { text: fromResult, done: false });
+      } else if (fromResult.length > streamedText.length && fromResult.startsWith(streamedText)) {
+        const rest = fromResult.slice(streamedText.length);
+        finalText = fromResult;
+        if (rest) {
+          writeSse(reply, { text: rest, done: false });
+        }
+      } else if (!streamedText.trim() && fromResult.trim()) {
+        finalText = fromResult;
+        writeSse(reply, { text: fromResult, done: false });
+      }
+    }
+  } catch (e) {
+    // ignore text aggregation errors; streamedText may still be enough
+  }
+
+  const donePayload = { done: true };
+  if (!streamedText.trim() && finalText.trim()) {
+    donePayload.text = finalText;
+  }
+  if (Object.keys(suggestedScope).length) {
+    donePayload.suggestedScope = suggestedScope;
+  }
+  // 即使模型未调 suggestProps，也从生成代码扫描 props.xxx 补齐声明
+  if (job.mode === 'generate' && finalText.trim()) {
+    suggestedProps = mergeSuggestedProps(finalText, suggestedProps, job.props || {});
+  }
+  if (Object.keys(suggestedProps).length) {
+    donePayload.suggestedProps = suggestedProps;
+  }
+  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`,
     {
@@ -289,6 +368,34 @@ module.exports = fp(async (fastify, options) => {
     }
   );
 
+  fastify.post(
+    `${options.prefix}/:shorten/move`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        summary: '移动文件或文件夹到目标目录',
+        params: {
+          type: 'object',
+          required: ['shorten'],
+          properties: {
+            shorten: { type: 'string' }
+          }
+        },
+        body: {
+          type: 'object',
+          required: ['id'],
+          properties: {
+            id: { type: 'string' },
+            parentId: { type: ['string', 'null'] }
+          }
+        }
+      }
+    },
+    async request => {
+      return services.node.move(request.authenticatePayload, request.body);
+    }
+  );
+
   fastify.post(
     `${options.prefix}/:shorten/remove`,
     {

package/libs/services/ai.js

@@ -0,0 +1,104 @@
+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 props = body.props && typeof body.props === 'object' ? body.props : {};
+    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 不能为空');
+    }
+
+    // 不在 start 阻塞拉文档索引（易触发网关/代理 504）；在 stream 阶段再确保
+    const streamToken = createStreamJob({
+      mode,
+      messages,
+      remotes,
+      libs,
+      scope,
+      props,
+      content,
+      selection,
+      catalogs: null,
+      catalogOptions: options,
+      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 {
+      if (!job.catalogs) {
+        job.catalogs = await ensureRemotesCatalogs(job.remotes, job.catalogOptions || options);
+      }
+      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/libs/services/node.js

@@ -227,6 +227,60 @@ module.exports = fp(async (fastify, options) => {
     };
   };
 
+  const isDescendantOf = async (siteId, ancestorId, maybeDescendantId) => {
+    let currentId = toId(maybeDescendantId);
+    const visited = new Set();
+    while (currentId) {
+      if (currentId === toId(ancestorId)) {
+        return true;
+      }
+      if (visited.has(currentId)) {
+        return false;
+      }
+      visited.add(currentId);
+      const current = await models.node.findOne({
+        where: { id: currentId, siteId },
+        attributes: ['parentId']
+      });
+      currentId = toId(current?.parentId);
+    }
+    return false;
+  };
+
+  const move = async (authenticatePayload, { id, parentId }) => {
+    const siteId = getSiteId(authenticatePayload);
+    const node = await findNode(siteId, id);
+    assertWritable(node);
+
+    const targetParentId = toId(parentId);
+    const currentParentId = toId(node.parentId);
+    if (targetParentId === currentParentId) {
+      throw new BadRequest('INVALID_MOVE_TARGET');
+    }
+    if (targetParentId && targetParentId === toId(node.id)) {
+      throw new BadRequest('INVALID_MOVE_TARGET');
+    }
+    if (node.type === 'directory' && targetParentId) {
+      const looping = await isDescendantOf(siteId, node.id, targetParentId);
+      if (looping) {
+        throw new BadRequest('INVALID_MOVE_TARGET');
+      }
+    }
+
+    await resolveParent(siteId, targetParentId);
+    await assertUniqueSiblingName(siteId, targetParentId, node.name, node.id);
+
+    node.parentId = targetParentId;
+    await node.save();
+    return {
+      id: String(node.id),
+      name: node.name,
+      type: node.type,
+      permission: node.permission,
+      parentId: targetParentId
+    };
+  };
+
   const remove = async (authenticatePayload, { ids }) => {
     const siteId = getSiteId(authenticatePayload);
     const idList = Array.isArray(ids) ? ids : [ids];
@@ -272,6 +326,7 @@ module.exports = fp(async (fastify, options) => {
       create,
       save,
       rename,
+      move,
       remove
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-live-components-site",
-  "version": "0.1.0",
+  "version": "0.1.9",
   "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": "^7.0.37",
     "http-errors": "^2.0.0",
-    "lodash": "^4.17.21"
+    "lodash": "^4.17.21",
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "@kne/fastify-account": "*",