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

package/README.md

@@ -111,6 +111,7 @@ npm i --save @kne/fastify-live-components-site
   messages: [{ role: 'user'|'assistant', content: string }],
   content?: string,
   scope?: object,
+  props?: object,
   libs?: string[],
   remotes?: [{ name, version, packageName? }],
   selection?: { startLine, endLine, code, label }
@@ -120,7 +121,7 @@ npm i --save @kne/fastify-live-components-site
 返回 `{ streamToken }`。随后 `GET {host}/ai/stream?token=` 以 SSE 推送：
 
 - `{ text, done: false }` 增量文本
-- `{ done: true, suggestedScope? }` 结束
+- `{ done: true, suggestedScope?, suggestedProps? }` 结束（生成阶段可通过工具声明组件域 / 组件参数）
 
 前端从 `@kne/remote-loader` preset 收集 `remotes`，并从当前环境合并 `libs` 键名一并上传。服务端按「库名/版本」缓存组件文档索引（`load-npm-info` + `md-doc`）。
 

package/libs/ai/catalog.js

@@ -59,6 +59,7 @@ const readCachedCatalog = async (dir, remoteName, version) => {
     remote: remoteName,
     version,
     packageName: meta.packageName,
+    meta,
     index,
     components
   };
@@ -110,10 +111,24 @@ const ensureRemoteCatalog = async (remote, options) => {
 
   const dir = getCacheDir(options, name, version);
   if (isCacheComplete(dir)) {
-    return readCachedCatalog(dir, name, version);
+    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;
@@ -125,43 +140,53 @@ const ensureRemoteCatalog = async (remote, options) => {
     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 });
-    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))
+      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, packageName, ...empty };
+
+    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 { 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))
+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);
+    })
   ]);
-
-  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 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 }) => {

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

@@ -7,19 +7,55 @@ const stripHtml = html =>
 const LIVE_COMPONENT_SPEC = `
 ## Live 组件规范（必须遵守）
 
-1. 编辑对象是配置里的 content 字段：一段 JSX 表达式源码，不是完整 .js 模块，也不是 PlantUML 编码串。
-2. 运行时会编译为 render(<content>);，因此 content 应是可放入 render(...) 的表达式；不要写 import / export / 外层 render(。
+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 全量）、props（合并后的组件参数）
+   - React、Antd（antd 全量，但表单场景有额外禁令，见第 8 条）、props（合并后的组件参数）
    - scope 声明的变量名（如 FormInfo ← components-core:FormInfo），另有 PureGlobal
    - libs：仅限当前请求告知的 libKeys，禁止使用未列出的 lib 标识符
 4. 组件选用优先级（强制）：
    1) 远程组件优先（本次 remotes 索引 / 当前 scope 中已有）
-   2) 其次 Antd.*
+   2) 其次 Antd.*（**表单除外，见第 8 条**）
    3) 最后原生 HTML；禁止用 HTML 重复实现已有远程或 Antd 能力
-5. props：{ name: { type, defaultValue } }，代码里用 props.xxx；scope：{ 变量名: 'moduleToken' }。若使用了当前 scope 没有的远程组件，须通过 suggestScope 工具声明 suggestedScope。
+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 => {
@@ -91,6 +127,10 @@ const collectHitComponentNames = ({ messages = [], scope = {}, catalogs = [] })
       }
     });
   });
+  // 表单相关需求强制带上 FormInfo 文档命中，便于注入 L2
+  if (/表单|校验|FormInfo|Form\.Item|录入|提交|字段/.test(text)) {
+    hits.add('FormInfo');
+  }
   return Array.from(hits);
 };
 
@@ -106,38 +146,62 @@ const buildRefineSystemPrompt = ctx => {
     detail,
     hasSelection ? `当前讨论范围限定在选中组件：${selectionLabel || '已选中片段'}。` : '当前讨论整份 content。',
     `行为规则：
-1. 推荐组件时遵守：远程 → Antd → HTML。
-2. 涉及 UI 结构时，必须用 ASCII 线框给出 2～4 个方案（A/B/C…），简述差异，请用户选择；选定前不要宣称需求已确认。
-3. 信息与布局都够了后，用短结构化小结（目标 / 改动点 / 选用布局 / 建议组件 / 是否动 props·scope），并明确提示用户点击界面上的「开始生成」按钮。
-4. 不要暗示会自动写代码或自行进入生成阶段。
-5. 不要输出完整组件实现。`
+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 = {}, hasSelection, selectionLabel } = 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 代码生成器。根据已完善的需求对话，一次产出可直接写入编辑器的源码。',
+    '你是 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 没有的远程组件，调用此工具声明 { 变量名: 'remote:Component' }。
+- suggestScope：声明需要合并进编辑器「组件域」的 scope，形如 { FormInfo: 'components-core:FormInfo' }。
+- suggestProps：声明需要合并进编辑器「组件参数」的 props，形如 { title: { type: 'string', defaultValue: '标题' } }。
 
 输出契约：
 1. 优先纯代码；不要追问、不要复述需求、不要解释。
-2. 选型：远程 → Antd → HTML。
-3. 只能使用本次 libs 键与 scope∪suggestedScope。
-4. 需要官方示例时根据 description 挑选后调用 getComponentExample。`
+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');

package/libs/ai/run.js

@@ -2,6 +2,7 @@ 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`);
@@ -20,6 +21,9 @@ const buildUserMessages = job => {
     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') });
     }
@@ -34,6 +38,11 @@ const buildUserMessages = job => {
   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) {
@@ -49,11 +58,14 @@ const runAiStream = async (job, reply) => {
     libKeys: job.libs || [],
     catalogs: job.catalogs || [],
     messages: job.messages || [],
-    scope: job.scope || {}
+    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 阶段仍不要输出业务实现代码）',
@@ -73,7 +85,7 @@ const runAiStream = async (job, reply) => {
       ? {
           getComponentExample: exampleTool,
           suggestScope: tool({
-            description: '声明需要合并进编辑器的 scope（远程组件 token）',
+            description: '声明需要合并进编辑器「组件域」的 scope（远程组件 token）',
             inputSchema: z.object({
               scope: z.record(z.string())
             }),
@@ -81,6 +93,16 @@ const runAiStream = async (job, reply) => {
               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 };
+            }
           })
         }
       : {
@@ -97,17 +119,50 @@ const runAiStream = async (job, reply) => {
 
   for await (const part of result.fullStream) {
     if (part.type === 'text-delta') {
-      const text = part.text || '';
+      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);
 };
 

package/libs/controllers/entry.js

@@ -1,5 +1,25 @@
 const fp = require('fastify-plugin');
 const { allowCors, handleOptions, normalizeHooks } = require('../utils/cors');
+const { str, bool, any, list, obj, success, PERMISSION, SITE_STATUS, nodeBase, treeNode, contentShare } = require('../schema/response');
+
+const TAG_SITE = 'Live组件站点-站点信息';
+const TAG_AI = 'Live组件站点-AI';
+const TAG_FILE = 'Live组件站点-文件';
+const TAG_SHARE = 'Live组件站点-内容分享';
+
+const ENTRY_HINT = '通过站点短码 shorten 鉴权（站点须存在且为开启状态，关闭返回 403，短码无效返回 401），允许任意 Origin 跨域';
+
+const shortenParams = {
+  type: 'object',
+  required: ['shorten'],
+  properties: {
+    shorten: { type: 'string', description: '站点公开访问短码（不区分大小写）' }
+  }
+};
+
+const PARENT_ID = '父文件夹节点 ID，为空表示根目录；父节点须为可写文件夹';
+
+const fileNode = obj('文件节点', nodeBase);
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -28,14 +48,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: allowCors,
       schema: {
+        tags: [TAG_SHARE],
         summary: '通过内容短码直出已保存 content（text/plain，无 code/data；不带站点 shorten）',
+        description: '公开访问，无需站点短码；短码无效或已过期返回 401，所属站点关闭返回 403。允许任意 Origin 跨域',
         params: {
           type: 'object',
           required: ['contentShorten'],
           properties: {
-            contentShorten: { type: 'string' }
+            contentShorten: { type: 'string', description: '内容分享短码（不区分大小写）' }
           }
-        }
+        },
+        response: success('文件已保存的内容原文，Content-Type 为 text/plain; charset=utf-8', { type: 'string' })
       }
     },
     async (request, reply) => {
@@ -52,14 +75,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SITE],
         summary: '站点信息（含是否支持 AI）',
-        params: {
+        description: ENTRY_HINT,
+        params: shortenParams,
+        response: success('站点公开信息', {
           type: 'object',
-          required: ['shorten'],
+          additionalProperties: true,
           properties: {
-            shorten: { type: 'string' }
+            name: str('站点名称'),
+            status: str(SITE_STATUS),
+            defaultPermission: str(`新建节点默认${PERMISSION}`),
+            aiEnabled: bool('是否可用 AI 生成：插件配置了 ai.getAIModel 且站点 options.aiEnabled 不为 false')
           }
-        }
+        })
       }
     },
     async request => {
@@ -72,26 +101,38 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_AI],
         summary: '创建 AI 流式任务，返回 streamToken',
-        params: {
+        description: `${ENTRY_HINT}。站点未开启 AI 返回 403；refine 模式 messages 不能为空。任务暂存于内存，2 分钟内需用 streamToken 调用 ai/stream 消费`,
+        params: shortenParams,
+        body: {
           type: 'object',
-          required: ['shorten'],
           properties: {
-            shorten: { type: 'string' }
+            mode: { type: 'string', description: '任务模式：generate 生成代码，其它值按 refine（完善需求对话）处理' },
+            messages: { type: 'array', description: '对话历史，元素形如 { role: user|assistant, content }，其它 role 或空 content 会被忽略' },
+            content: { type: 'string', description: '编辑器当前整份源码' },
+            scope: { type: 'object', description: '编辑器当前 scope（可用变量/组件声明）' },
+            props: { description: '编辑器当前组件参数，形如 { name: { type, defaultValue } }；非对象时忽略' },
+            libs: { type: 'array', description: '可用依赖库标识列表，元素会转为字符串' },
+            remotes: { type: 'array', description: '可用远程组件包列表，用于在 stream 阶段拉取组件文档索引' },
+            selection: {
+              type: 'object',
+              description: '编辑器选中片段；传入时 AI 只针对选中部分',
+              properties: {
+                code: { description: '选中片段源码' },
+                startLine: { description: '选中片段起始行' },
+                label: { description: '选中片段名称，用于提示' }
+              }
+            }
           }
         },
-        body: {
+        response: success('任务已创建', {
           type: 'object',
+          additionalProperties: true,
           properties: {
-            mode: { type: 'string' },
-            messages: { type: 'array' },
-            content: { type: 'string' },
-            scope: { type: 'object' },
-            libs: { type: 'array' },
-            remotes: { type: 'array' },
-            selection: { type: 'object' }
+            streamToken: str('一次性流式任务令牌，传给 ai/stream 的 token')
           }
-        }
+        })
       }
     },
     async request => {
@@ -104,20 +145,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_AI],
         summary: 'SSE 推送 AI 流式输出',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。token 只能消费一次，无效或过期返回 404；成功后以 text/event-stream 推送 data: {...} 事件直到结束`,
+        params: shortenParams,
         query: {
           type: 'object',
           required: ['token'],
           properties: {
-            token: { type: 'string' }
+            token: { type: 'string', description: 'ai/start 返回的 streamToken' }
           }
+        },
+        response: {
+          200: { description: 'text/event-stream 事件流，每条为 data: JSON；出错时推送 { text: 错误信息, done: true } 后结束' }
         }
       }
     },
@@ -131,14 +171,11 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '获取站点文件树',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        }
+        description: `${ENTRY_HINT}。同级按类型（文件夹在前）、名称排序`,
+        params: shortenParams,
+        response: success('根节点列表，文件夹带 children', { type: 'array', items: treeNode })
       }
     },
     async request => {
@@ -151,21 +188,27 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '读取文件内容',
-        params: {
+        description: `${ENTRY_HINT}。节点不存在返回 404，非文件返回 400`,
+        params: shortenParams,
+        query: {
           type: 'object',
-          required: ['shorten'],
+          required: ['id'],
           properties: {
-            shorten: { type: 'string' }
+            id: { type: 'string', description: '文件节点 ID' }
           }
         },
-        query: {
+        response: success('文件内容', {
           type: 'object',
-          required: ['id'],
+          additionalProperties: true,
           properties: {
-            id: { type: 'string' }
+            id: any('节点 ID（字符串）'),
+            name: str('文件名'),
+            permission: str(PERMISSION),
+            content: str('文件内容，未保存过为空字符串')
           }
-        }
+        })
       }
     },
     async request => {
@@ -178,22 +221,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SHARE],
         summary: '创建文件内容分享短链（可设有效期）',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。只能分享文件；生成的短链通过 content/:contentShorten 公开访问`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' },
-            expiresIn: { type: ['number', 'null'] }
+            id: { type: 'string', description: '文件节点 ID' },
+            expiresIn: { type: ['number', 'null'], description: '有效期（秒），不传、null 或不大于 0 表示永久有效' }
           }
-        }
+        },
+        response: success('创建的分享短链', contentShare)
       }
     },
     async request => {
@@ -206,21 +246,18 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SHARE],
         summary: '列出文件已有内容分享短链',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。按创建时间倒序；已过期的分享会在查询时被删除并移除短码，不出现在结果中`,
+        params: shortenParams,
         query: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' }
+            id: { type: 'string', description: '文件节点 ID' }
           }
-        }
+        },
+        response: success('未过期的分享短链列表', { type: 'array', items: contentShare })
       }
     },
     async request => {
@@ -233,21 +270,24 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_SHARE],
         summary: '删除文件内容分享短链',
-        params: {
+        description: `${ENTRY_HINT}。删除分享记录并移除内容短码；分享不存在返回 404`,
+        params: shortenParams,
+        body: {
           type: 'object',
           required: ['shorten'],
           properties: {
-            shorten: { type: 'string' }
+            shorten: { type: 'string', description: '要删除的内容分享短码（不区分大小写）' }
           }
         },
-        body: {
+        response: success('删除成功', {
           type: 'object',
-          required: ['shorten'],
+          additionalProperties: true,
           properties: {
-            shorten: { type: 'string' }
+            shorten: str('已删除的内容短码（大写）')
           }
-        }
+        })
       }
     },
     async request => {
@@ -260,22 +300,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '创建文件夹',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。同级重名返回 400 DUPLICATE_NAME；新节点权限取站点 defaultPermission`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['name'],
           properties: {
-            parentId: { type: ['string', 'null'] },
-            name: { type: 'string' }
+            parentId: { type: ['string', 'null'], description: PARENT_ID },
+            name: { type: 'string', description: '文件夹名称，去除首尾空格后不能为空' }
           }
-        }
+        },
+        response: success('创建的文件夹', obj('文件夹节点', Object.assign({}, nodeBase, { children: list('子节点，新建时为空数组', obj('子节点')) })))
       }
     },
     async request => {
@@ -288,23 +325,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '创建文件',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。同级重名返回 400 DUPLICATE_NAME；新节点权限取站点 defaultPermission`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['name'],
           properties: {
-            parentId: { type: ['string', 'null'] },
-            name: { type: 'string' },
-            content: { type: 'string' }
+            parentId: { type: ['string', 'null'], description: PARENT_ID },
+            name: { type: 'string', description: '文件名称，去除首尾空格后不能为空' },
+            content: { type: 'string', description: '初始文件内容，默认空字符串' }
           }
-        }
+        },
+        response: success('创建的文件', fileNode)
       }
     },
     async request => {
@@ -317,22 +351,26 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '保存文件内容',
-        params: {
+        description: `${ENTRY_HINT}。只读节点返回 403，非文件返回 400`,
+        params: shortenParams,
+        body: {
           type: 'object',
-          required: ['shorten'],
+          required: ['id'],
           properties: {
-            shorten: { type: 'string' }
+            id: { type: 'string', description: '文件节点 ID' },
+            content: { type: 'string', description: '新的文件内容，不传保存为空字符串' }
           }
         },
-        body: {
+        response: success('保存后的文件内容', {
           type: 'object',
-          required: ['id'],
+          additionalProperties: true,
           properties: {
-            id: { type: 'string' },
-            content: { type: 'string' }
+            id: any('节点 ID（字符串）'),
+            content: str('保存后的文件内容')
           }
-        }
+        })
       }
     },
     async request => {
@@ -345,22 +383,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: withEntryAuth,
       schema: {
+        tags: [TAG_FILE],
         summary: '重命名节点',
-        params: {
-          type: 'object',
-          required: ['shorten'],
-          properties: {
-            shorten: { type: 'string' }
-          }
-        },
+        description: `${ENTRY_HINT}。只读节点返回 403，同级重名返回 400 DUPLICATE_NAME`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['id', 'name'],
           properties: {
-            id: { type: 'string' },
-            name: { type: 'string' }
+            id: { type: 'string', description: '文件或文件夹节点 ID' },
+            name: { type: 'string', description: '新名称，去除首尾空格后不能为空' }
           }
-        }
+        },
+        response: success('重命名后的节点', fileNode)
       }
     },
     async request => {
@@ -369,28 +404,65 @@ module.exports = fp(async (fastify, options) => {
   );
 
   fastify.post(
-    `${options.prefix}/:shorten/remove`,
+    `${options.prefix}/:shorten/move`,
     {
       onRequest: withEntryAuth,
       schema: {
-        summary: '删除节点',
-        params: {
+        tags: [TAG_FILE],
+        summary: '移动文件或文件夹到目标目录',
+        description: `${ENTRY_HINT}。目标与当前目录相同、移动到自身或自身子目录返回 400 INVALID_MOVE_TARGET；目标目录下重名返回 400 DUPLICATE_NAME`,
+        params: shortenParams,
+        body: {
           type: 'object',
-          required: ['shorten'],
+          required: ['id'],
           properties: {
-            shorten: { type: 'string' }
+            id: { type: 'string', description: '要移动的节点 ID' },
+            parentId: { type: ['string', 'null'], description: '目标文件夹节点 ID，为空表示移动到根目录' }
           }
         },
+        response: success(
+          '移动后的节点',
+          obj(
+            '节点',
+            Object.assign({}, nodeBase, {
+              parentId: any('新的父节点 ID，根目录为 null')
+            })
+          )
+        )
+      }
+    },
+    async request => {
+      return services.node.move(request.authenticatePayload, request.body);
+    }
+  );
+
+  fastify.post(
+    `${options.prefix}/:shorten/remove`,
+    {
+      onRequest: withEntryAuth,
+      schema: {
+        tags: [TAG_FILE],
+        summary: '删除节点',
+        description: `${ENTRY_HINT}。按顺序逐个删除，遇到只读节点（403）或非空文件夹（400）即中止，已删除的不回滚；删除文件时一并删除其内容分享短链`,
+        params: shortenParams,
         body: {
           type: 'object',
           required: ['ids'],
           properties: {
             ids: {
               type: 'array',
-              items: { type: 'string' }
+              items: { type: 'string' },
+              description: '要删除的节点 ID 列表'
             }
           }
-        }
+        },
+        response: success('删除成功', {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            ids: list('已删除的节点 ID 列表', any('节点 ID（字符串）'))
+          }
+        })
       }
     },
     async request => {

package/libs/controllers/site.js

@@ -1,4 +1,15 @@
 const fp = require('fastify-plugin');
+const { num, list, success, empty, PERMISSION, SITE_STATUS, site } = require('../schema/response');
+
+const TAG = 'Live组件站点管理后台-站点';
+
+const siteOptions = {
+  type: 'object',
+  description: '站点扩展配置（JSON），原样保存',
+  properties: {
+    aiEnabled: { description: '是否开启 AI 生成，传 false 关闭；未传视为开启（需同时配置插件 ai.getAIModel）' }
+  }
+};
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -8,15 +19,33 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site'),
       schema: {
+        tags: [TAG],
         summary: '站点列表',
+        description: '分页查询站点，按创建时间倒序；可按状态与名称关键字筛选',
         query: {
           type: 'object',
           properties: {
-            filter: { type: 'object', default: {} },
-            perPage: { type: 'number', default: 20 },
-            currentPage: { type: 'number', default: 1 }
+            filter: {
+              type: 'object',
+              default: {},
+              description: '筛选条件，如 filter[status]=open',
+              properties: {
+                status: { description: `按状态筛选，${SITE_STATUS}；其它值忽略` },
+                keyword: { description: '按站点名称模糊匹配' }
+              }
+            },
+            perPage: { type: 'number', default: 20, description: '每页条数' },
+            currentPage: { type: 'number', default: 1, description: '当前页码，从 1 开始' }
+          }
+        },
+        response: success('站点分页列表', {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            pageData: list('当前页站点列表', site),
+            totalCount: num('符合条件的站点总数')
           }
-        }
+        })
       }
     },
     async request => {
@@ -29,14 +58,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site'),
       schema: {
+        tags: [TAG],
         summary: '站点详情',
+        description: '按 ID 获取站点信息，含公开入口地址 host；站点不存在返回 404',
         query: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' }
+            id: { type: 'string', description: '站点 ID' }
           }
-        }
+        },
+        response: success('站点详情', site)
       }
     },
     async request => {
@@ -49,17 +81,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site:create'),
       schema: {
+        tags: [TAG],
         summary: '创建站点并签发 shorten 链接',
+        description: '创建站点后通过 shorten 服务签发站点公开访问短码，返回带 host 的站点信息',
         body: {
           type: 'object',
           required: ['name'],
           properties: {
-            name: { type: 'string' },
-            defaultPermission: { type: 'string', enum: ['r', 'rw'] },
-            status: { type: 'string', enum: ['open', 'closed'] },
-            options: { type: 'object' }
+            name: { type: 'string', description: '站点名称，去除首尾空格后不能为空' },
+            defaultPermission: { type: 'string', enum: ['r', 'rw'], description: `新建节点默认${PERMISSION}；默认 rw` },
+            status: { type: 'string', enum: ['open', 'closed'], description: `${SITE_STATUS}；默认 open` },
+            options: siteOptions
           }
-        }
+        },
+        response: success('创建后的站点', site)
       }
     },
     async request => {
@@ -72,18 +107,21 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site:manage'),
       schema: {
+        tags: [TAG],
         summary: '修改站点（含开启/关闭）',
+        description: '只更新传入的字段；shorten、时间字段不可修改。关闭后站点公开入口与内容短链返回 403，重新开启后沿用原 host',
         body: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' },
-            name: { type: 'string' },
-            status: { type: 'string', enum: ['open', 'closed'] },
-            defaultPermission: { type: 'string', enum: ['r', 'rw'] },
-            options: { type: 'object' }
+            id: { type: 'string', description: '站点 ID' },
+            name: { type: 'string', description: '站点名称，传入时去除首尾空格后不能为空' },
+            status: { type: 'string', enum: ['open', 'closed'], description: SITE_STATUS },
+            defaultPermission: { type: 'string', enum: ['r', 'rw'], description: `新建节点默认${PERMISSION}` },
+            options: Object.assign({}, siteOptions, { description: '站点扩展配置（JSON），整体覆盖原值' })
           }
-        }
+        },
+        response: empty('保存成功')
       }
     },
     async request => {
@@ -97,14 +135,17 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.getAuthenticate('site:manage'),
       schema: {
+        tags: [TAG],
         summary: '删除站点',
+        description: '删除站点及其全部文件节点、内容分享记录，并移除站点短码与内容短码',
         body: {
           type: 'object',
           required: ['id'],
           properties: {
-            id: { type: 'string' }
+            id: { type: 'string', description: '站点 ID' }
           }
-        }
+        },
+        response: empty('删除成功')
       }
     },
     async request => {

package/libs/schema/response.js

@@ -0,0 +1,50 @@
+// 响应 schema 会参与 fast-json-stringify 序列化：对象一律 additionalProperties: true 以免裁掉未声明字段；
+// 用 nullable 而非类型数组（类型数组遇到不匹配的值会直接 500），类型不确定的字段（如 id、日期、JSON 列）只写说明不声明类型
+const str = description => ({ type: 'string', nullable: true, description });
+const num = description => ({ type: 'number', nullable: true, description });
+const bool = description => ({ type: 'boolean', nullable: true, description });
+const any = description => ({ description });
+const list = (description, items) => ({ type: 'array', nullable: true, description, items });
+const obj = (description, properties = {}) => ({ type: 'object', nullable: true, description, additionalProperties: true, properties });
+
+const success = (description, schema) => ({
+  200: Object.assign({}, schema || { type: 'object' }, { description })
+});
+
+const empty = (description = '操作成功，返回空对象') => success(description);
+
+const PERMISSION = '权限：r 只读，rw 可读写';
+const SITE_STATUS = '站点状态：open 开启，closed 关闭';
+
+const site = obj('站点', {
+  id: any('站点 ID（字符串）'),
+  name: str('站点名称'),
+  shorten: str('站点公开访问短码'),
+  host: str('站点公开入口地址，由 getSiteHost(shorten) 生成，默认 {prefix}/{shorten}'),
+  status: str(SITE_STATUS),
+  defaultPermission: str(`新建节点默认${PERMISSION}`),
+  options: any('站点扩展配置（JSON），如 aiEnabled: false 关闭 AI'),
+  createdAt: any('创建时间'),
+  updatedAt: any('更新时间'),
+  deletedAt: any('删除时间，未删除为 null')
+});
+
+const nodeBase = {
+  id: any('节点 ID（字符串）'),
+  name: str('节点名称'),
+  type: str('节点类型：file 文件，directory 文件夹'),
+  permission: str(PERMISSION)
+};
+
+const treeNode = obj('文件树节点', Object.assign({}, nodeBase, { children: list('子节点列表（仅文件夹有），结构同本节点', obj('子节点')) }));
+
+const contentShare = obj('内容分享短链', {
+  id: any('分享记录 ID（字符串）'),
+  nodeId: any('文件节点 ID（字符串）'),
+  shorten: str('内容短码（大写）'),
+  expires: any('过期时间，null 表示永久有效'),
+  url: str('内容访问地址：{getContentHost()}/content/{shorten}，不带站点短码'),
+  createdAt: any('创建时间')
+});
+
+module.exports = { str, num, bool, any, list, obj, success, empty, PERMISSION, SITE_STATUS, site, nodeBase, treeNode, contentShare };

package/libs/services/ai.js

@@ -36,6 +36,7 @@ module.exports = fp(async (fastify, options) => {
     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;
 
@@ -43,16 +44,18 @@ module.exports = fp(async (fastify, options) => {
       throw new BadRequest('messages 不能为空');
     }
 
-    const catalogs = await ensureRemotesCatalogs(remotes, options);
+    // 不在 start 阻塞拉文档索引（易触发网关/代理 504）；在 stream 阶段再确保
     const streamToken = createStreamJob({
       mode,
       messages,
       remotes,
       libs,
       scope,
+      props,
       content,
       selection,
-      catalogs,
+      catalogs: null,
+      catalogOptions: options,
       getAIModel: options.ai.getAIModel
     });
 
@@ -80,6 +83,9 @@ module.exports = fp(async (fastify, options) => {
     });
 
     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`);

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.1",
+  "version": "0.1.10",
   "description": "Fastify 插件：为 LiveComponentEditor 提供远程站点文件树与短链访问管理",
   "main": "index.js",
   "scripts": {
@@ -42,7 +42,7 @@
   "dependencies": {
     "@kne/load-npm-info": "^0.1.8",
     "@kne/md-doc": "^0.1.24",
-    "ai": "^5.0.220",
+    "ai": "^7.0.37",
     "http-errors": "^2.0.0",
     "lodash": "^4.17.21",
     "zod": "^3.25.76"