plugin-build-guide-block 1.0.11 → 1.1.2

package/dist/server/actions/build.js

@@ -44,6 +44,61 @@ var import_messages = require("@langchain/core/messages");
 var import_axios = __toESM(require("axios"));
 var import_fs = __toESM(require("fs"));
 var import_path = __toESM(require("path"));
+var import_crypto = __toESM(require("crypto"));
+var import_marked = require("marked");
+const MAX_SOURCE_CHARS = 9e4;
+const MIN_CHAPTERS = 3;
+const MAX_CHAPTERS = 12;
+const DEFAULT_TARGET_CHAPTERS = 5;
+const SANITIZE_OPTIONS = {
+  allowedTags: [
+    "div",
+    "p",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "ul",
+    "ol",
+    "li",
+    "table",
+    "thead",
+    "tbody",
+    "tr",
+    "td",
+    "th",
+    "a",
+    "img",
+    "span",
+    "strong",
+    "em",
+    "code",
+    "pre",
+    "blockquote",
+    "br",
+    "hr"
+  ],
+  allowedAttributes: {
+    a: ["href", "target"],
+    img: ["src", "alt", "width", "height"],
+    "*": ["style", "class", "id"]
+  },
+  allowedStyles: {
+    "*": {
+      color: [/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, /^rgb/, /^rgba/],
+      "background-color": [/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, /^rgb/, /^rgba/],
+      "text-align": [/^left$/, /^right$/, /^center$/, /^justify$/],
+      "font-size": [/^\d+(?:px|em|%)$/]
+    }
+  }
+};
+function clampChapterCount(value) {
+  const count = Number(value);
+  if (!Number.isFinite(count)) return DEFAULT_TARGET_CHAPTERS;
+  return Math.max(MIN_CHAPTERS, Math.min(MAX_CHAPTERS, Math.round(count)));
+}
 async function fetchFileContent(app, file) {
   const fileManager = app.pm.get("file-manager");
   if (!fileManager) return "";
@@ -52,20 +107,334 @@ async function fetchFileContent(app, file) {
     if (url.startsWith("http")) {
       const response = await import_axios.default.get(url, { responseType: "text", timeout: 15e3 });
       return response.data;
-    } else {
-      let localPath = url;
-      if (process.env.APP_PUBLIC_PATH && localPath.startsWith(process.env.APP_PUBLIC_PATH)) {
-        localPath = localPath.slice(process.env.APP_PUBLIC_PATH.length);
-      }
-      localPath = import_path.default.join(process.cwd(), localPath);
-      const data = await import_fs.default.promises.readFile(localPath, "utf8");
-      return data;
     }
+    let localPath = url;
+    if (process.env.APP_PUBLIC_PATH && localPath.startsWith(process.env.APP_PUBLIC_PATH)) {
+      localPath = localPath.slice(process.env.APP_PUBLIC_PATH.length);
+    }
+    localPath = import_path.default.join(process.cwd(), localPath);
+    return await import_fs.default.promises.readFile(localPath, "utf8");
   } catch (err) {
     app.log.error(`Failed to read file content for document ${file.id}`, err);
     return `[Failed to read document: ${file.filename}]`;
   }
 }
+function toPlainText(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      if (typeof item === "string") return item;
+      if (typeof (item == null ? void 0 : item.text) === "string") return item.text;
+      if (typeof (item == null ? void 0 : item.content) === "string") return item.content;
+      return "";
+    }).filter(Boolean).join("\n");
+  }
+  if (value && typeof value === "object") {
+    const text = value.text || value.content;
+    if (typeof text === "string") return text;
+  }
+  return JSON.stringify(value);
+}
+function stripFence(text) {
+  return text.replace(/^```(?:json|markdown|md|html)?\s*/i, "").replace(/```\s*$/i, "").trim();
+}
+function slugify(text, fallback) {
+  const slug = text.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || fallback;
+}
+function createFallbackPlan(guideTitle, targetChapterCount) {
+  const chapterTemplates = [
+    {
+      title: "Overview and scope",
+      goal: "Explain what the guide covers, who it is for, and the expected outcome."
+    },
+    {
+      title: "Prerequisites and preparation",
+      goal: "List required access, tools, input data, setup steps, and assumptions before starting."
+    },
+    {
+      title: "Initial setup",
+      goal: "Guide the user through the first required configuration or installation flow."
+    },
+    {
+      title: "Core workflow",
+      goal: "Describe the main task flow users need to complete successfully."
+    },
+    {
+      title: "Advanced usage and configuration",
+      goal: "Cover optional settings, variations, and deeper operational procedures."
+    },
+    {
+      title: "Verification and validation",
+      goal: "Show how to confirm that the setup or workflow is working correctly."
+    },
+    {
+      title: "Troubleshooting",
+      goal: "Document common problems, likely causes, and recovery steps."
+    },
+    {
+      title: "Reference and next steps",
+      goal: "Summarize related tasks, reference information, and recommended follow-up actions."
+    }
+  ];
+  return {
+    title: guideTitle,
+    chapters: Array.from({ length: targetChapterCount }, (_, index) => {
+      const template = chapterTemplates[index] || {
+        title: `Additional topic ${index + 1}`,
+        goal: "Expand an important topic from the source documents into a focused guide section."
+      };
+      return {
+        ...template,
+        sourceHints: []
+      };
+    })
+  };
+}
+function normalizePlan(rawText, guideTitle, targetChapterCount) {
+  const cleanText = stripFence(rawText);
+  const jsonStart = cleanText.indexOf("{");
+  const jsonEnd = cleanText.lastIndexOf("}");
+  const jsonText = jsonStart >= 0 && jsonEnd > jsonStart ? cleanText.slice(jsonStart, jsonEnd + 1) : cleanText;
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText);
+  } catch {
+    return createFallbackPlan(guideTitle, targetChapterCount);
+  }
+  const rawChapters = Array.isArray(parsed == null ? void 0 : parsed.chapters) ? parsed.chapters : [];
+  const chapters = rawChapters.slice(0, MAX_CHAPTERS).map((item, index) => ({
+    title: String((item == null ? void 0 : item.title) || `Section ${index + 1}`),
+    goal: (item == null ? void 0 : item.goal) ? String(item.goal) : "",
+    sourceHints: Array.isArray(item == null ? void 0 : item.sourceHints) ? item.sourceHints.map((hint) => String(hint)) : []
+  })).filter((item) => item.title);
+  if (chapters.length < MIN_CHAPTERS) {
+    return createFallbackPlan((parsed == null ? void 0 : parsed.title) ? String(parsed.title) : guideTitle, targetChapterCount);
+  }
+  return {
+    title: (parsed == null ? void 0 : parsed.title) ? String(parsed.title) : guideTitle,
+    chapters
+  };
+}
+async function getLLMProvider(app, llmService, model) {
+  const aiPlugin = app.pm.get("ai");
+  if (!aiPlugin) {
+    throw new Error("Plugin AI is not available");
+  }
+  const serviceData = await aiPlugin.aiManager.getLLMService({ llmService, model });
+  return serviceData.provider;
+}
+async function buildPlan(provider, space, documentsText) {
+  const { title, systemPrompt, targetChapterCount, chapterGuidance } = space.get();
+  const targetCount = clampChapterCount(targetChapterCount);
+  const messages = [];
+  if (systemPrompt) {
+    messages.push(new import_messages.SystemMessage(systemPrompt));
+  }
+  messages.push(
+    new import_messages.HumanMessage(`Create a concise breakdown plan for a multi-page user guide.
+
+Return ONLY valid JSON with this shape:
+{
+  "title": "Guide title",
+  "chapters": [
+    {
+      "title": "Chapter title",
+      "goal": "What this chapter should teach",
+      "sourceHints": ["Relevant topics, file names, or keywords"]
+    }
+  ]
+}
+
+Rules:
+- Create exactly ${targetCount} chapters.
+- Each chapter must cover a distinct user goal. Do not collapse the guide into a single chapter.
+- Keep chapter titles user-facing and action-oriented.
+- Do not include markdown fences or explanations.
+
+Guide title: ${title || "User guide"}
+
+Chapter guidance:
+${chapterGuidance || "Use the source document structure and split the guide into logical user-facing tasks."}
+
+Source documents:
+${documentsText.slice(0, MAX_SOURCE_CHARS)}`)
+  );
+  const response = await provider.chatModel.invoke(messages);
+  return normalizePlan(toPlainText(response.content), title || "User guide", targetCount);
+}
+async function buildPageMarkdown(provider, space, plan, chapter, documentsText) {
+  const { title, systemPrompt } = space.get();
+  const messages = [];
+  if (systemPrompt) {
+    messages.push(new import_messages.SystemMessage(systemPrompt));
+  }
+  messages.push(
+    new import_messages.HumanMessage(`Write one chapter for a user guide in pure Markdown.
+
+Output rules:
+- Output ONLY Markdown content for this chapter.
+- Start with a level-2 heading using the chapter title.
+- Use clear steps, tables, and callouts when useful.
+- Do not wrap the whole response in a code fence.
+- Do not mention that this was generated by AI.
+
+Guide title: ${plan.title || title || "User guide"}
+
+Full chapter plan:
+${JSON.stringify(plan, null, 2)}
+
+Chapter to write:
+${JSON.stringify(chapter, null, 2)}
+
+Source documents:
+${documentsText.slice(0, MAX_SOURCE_CHARS)}`)
+  );
+  const response = await provider.chatModel.invoke(messages);
+  return stripFence(toPlainText(response.content));
+}
+async function markdownToCleanHtml(markdown) {
+  const renderedHtml = await import_marked.marked.parse(markdown, { async: true });
+  return (0, import_sanitize_html.default)(renderedHtml, SANITIZE_OPTIONS);
+}
+async function readDocuments(app, space) {
+  const documents = await space.getDocuments();
+  if (!documents || documents.length === 0) {
+    return "";
+  }
+  const texts = await Promise.all(
+    documents.map(async (doc) => {
+      const content = await fetchFileContent(app, doc);
+      return `--- Document: ${doc.filename || doc.id} ---
+${content}
+`;
+    })
+  );
+  return texts.join("\n");
+}
+async function runBuild(app, db, filterByTk) {
+  const spaceRepo = db.getRepository("aiBuildGuideSpaces");
+  const pageRepo = db.getRepository("aiBuildGuidePages");
+  const space = await spaceRepo.findById(filterByTk);
+  if (!space) {
+    throw new Error("Space not found");
+  }
+  const { llmService, model } = space.get();
+  if (!llmService || !model) {
+    throw new Error("LLM Service or model is missing in space configuration");
+  }
+  await pageRepo.destroy({
+    filter: {
+      spaceId: filterByTk
+    }
+  });
+  await spaceRepo.update({
+    filterByTk,
+    values: {
+      buildPhase: "reading",
+      buildLog: "Reading source documents",
+      generatedHtml: null,
+      generatedMarkdown: null,
+      planJson: null,
+      pageCount: 0
+    }
+  });
+  const documentsText = await readDocuments(app, space);
+  const sourceHash = import_crypto.default.createHash("sha256").update(documentsText).digest("hex");
+  const provider = await getLLMProvider(app, llmService, model);
+  await spaceRepo.update({
+    filterByTk,
+    values: {
+      buildPhase: "planning",
+      buildLog: "Creating guide breakdown plan",
+      sourceHash
+    }
+  });
+  const plan = await buildPlan(provider, space, documentsText);
+  await spaceRepo.update({
+    filterByTk,
+    values: {
+      planJson: plan,
+      pageCount: plan.chapters.length,
+      buildPhase: "building_pages",
+      buildLog: `Plan created with ${plan.chapters.length} chapters`
+    }
+  });
+  const pageRecords = [];
+  for (const [index, chapter] of plan.chapters.entries()) {
+    const page = await pageRepo.create({
+      values: {
+        spaceId: filterByTk,
+        sort: index + 1,
+        title: chapter.title,
+        slug: slugify(chapter.title, `chapter-${index + 1}`),
+        goal: chapter.goal,
+        planItem: chapter,
+        status: "pending"
+      }
+    });
+    pageRecords.push(page);
+  }
+  for (const [index, page] of pageRecords.entries()) {
+    const chapter = plan.chapters[index];
+    const pageId = page.get("id");
+    await pageRepo.update({
+      filterByTk: pageId,
+      values: {
+        status: "building",
+        buildLog: "Building chapter with LLM"
+      }
+    });
+    await spaceRepo.update({
+      filterByTk,
+      values: {
+        buildPhase: "building_pages",
+        buildLog: `Building chapter ${index + 1}/${pageRecords.length}: ${chapter.title}`
+      }
+    });
+    try {
+      const markdown = await buildPageMarkdown(provider, space, plan, chapter, documentsText);
+      const html = await markdownToCleanHtml(markdown);
+      await pageRepo.update({
+        filterByTk: pageId,
+        values: {
+          status: "completed",
+          generatedMarkdown: markdown,
+          generatedHtml: html,
+          buildLog: null
+        }
+      });
+    } catch (error) {
+      await pageRepo.update({
+        filterByTk: pageId,
+        values: {
+          status: "error",
+          buildLog: error.message || String(error)
+        }
+      });
+      throw error;
+    }
+  }
+  const completedPages = await pageRepo.find({
+    filter: {
+      spaceId: filterByTk,
+      status: "completed"
+    },
+    sort: ["sort"]
+  });
+  const combinedMarkdown = completedPages.map((page) => page.get("generatedMarkdown")).filter(Boolean).join("\n\n---\n\n");
+  const combinedHtml = await markdownToCleanHtml(combinedMarkdown);
+  await spaceRepo.update({
+    filterByTk,
+    values: {
+      status: "completed",
+      buildPhase: "completed",
+      buildLog: `Built ${completedPages.length} chapters successfully`,
+      generatedMarkdown: combinedMarkdown,
+      generatedHtml: combinedHtml
+    }
+  });
+}
 async function build(ctx, next) {
   const { filterByTk } = ctx.action.params;
   const repository = ctx.db.getRepository("aiBuildGuideSpaces");
@@ -83,106 +452,18 @@ async function build(ctx, next) {
       filterByTk,
       values: {
         status: "building",
-        buildLog: null
+        buildPhase: "queued",
+        buildLog: "Build queued"
       }
     });
-    const bgPromise = (async () => {
-      const bgRepo = db.getRepository("aiBuildGuideSpaces");
-      const documents = await space.getDocuments();
-      let documentsText = "";
-      if (documents && documents.length > 0) {
-        const texts = await Promise.all(
-          documents.map(async (doc) => {
-            const content = await fetchFileContent(app, doc);
-            return `--- Document: ${doc.filename} ---
-${content}
-`;
-          })
-        );
-        documentsText = texts.join("\n");
-      }
-      const aiPlugin = app.pm.get("ai");
-      if (!aiPlugin) {
-        throw new Error("Plugin AI is not available");
-      }
-      const { llmService, model, systemPrompt } = space.get();
-      if (!llmService || !model) {
-        throw new Error("LLM Service or model is missing in space configuration");
-      }
-      const serviceData = await aiPlugin.aiManager.getLLMService({ llmService, model });
-      const provider = serviceData.provider;
-      const messages = [];
-      if (systemPrompt) {
-        messages.push(new import_messages.SystemMessage(systemPrompt));
-      }
-      const instruction = `Please generate an HTML user guide based on the following documents. Output ONLY valid HTML without Markdown blocks.
-
-Documents:
-${documentsText}`;
-      messages.push(new import_messages.HumanMessage(instruction));
-      const response = await provider.chatModel.invoke(messages);
-      let rawHtml = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      rawHtml = rawHtml.replace(/^```html\s*/, "").replace(/```\s*$/, "");
-      const cleanHtml = (0, import_sanitize_html.default)(rawHtml, {
-        allowedTags: [
-          "div",
-          "p",
-          "h1",
-          "h2",
-          "h3",
-          "h4",
-          "h5",
-          "h6",
-          "ul",
-          "ol",
-          "li",
-          "table",
-          "thead",
-          "tbody",
-          "tr",
-          "td",
-          "th",
-          "a",
-          "img",
-          "span",
-          "strong",
-          "em",
-          "code",
-          "pre",
-          "blockquote",
-          "br",
-          "hr"
-        ],
-        allowedAttributes: {
-          "a": ["href", "target"],
-          "img": ["src", "alt", "width", "height"],
-          "*": ["style", "class"]
-        },
-        allowedStyles: {
-          "*": {
-            "color": [/^\#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, /^rgb/, /^rgba/],
-            "background-color": [/^\#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, /^rgb/, /^rgba/],
-            "text-align": [/^left$/, /^right$/, /^center$/, /^justify$/],
-            "font-size": [/^\d+(?:px|em|%)$/]
-          }
-        }
-      });
-      await bgRepo.update({
-        filterByTk,
-        values: {
-          generatedHtml: cleanHtml,
-          status: "completed"
-        }
-      });
-    })();
-    bgPromise.catch(async (error) => {
+    runBuild(app, db, filterByTk).catch(async (error) => {
       app.log.error("Build Guide Background Error", error);
       try {
-        const bgRepo = db.getRepository("aiBuildGuideSpaces");
-        await bgRepo.update({
+        await repository.update({
           filterByTk,
           values: {
             status: "error",
+            buildPhase: "error",
             buildLog: error.message || String(error)
           }
         });
@@ -197,6 +478,7 @@ ${documentsText}`;
       filterByTk,
       values: {
         status: "error",
+        buildPhase: "error",
         buildLog: error.message || String(error)
       }
     });

package/dist/server/actions/getMarkdown.d.ts

@@ -0,0 +1,2 @@
+import { Context, Next } from '@nocobase/actions';
+export declare function getMarkdown(ctx: Context, next: Next): Promise<void>;

package/dist/server/actions/getMarkdown.js

@@ -0,0 +1,53 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var getMarkdown_exports = {};
+__export(getMarkdown_exports, {
+  getMarkdown: () => getMarkdown
+});
+module.exports = __toCommonJS(getMarkdown_exports);
+async function getMarkdown(ctx, next) {
+  const { filterByTk } = ctx.action.params;
+  const { resourceName } = ctx.action;
+  const repository = ctx.db.getRepository(resourceName);
+  const model = await repository.findById(filterByTk);
+  if (!model) {
+    ctx.throw(404, "User Guide not found");
+  }
+  if (model.get("status") !== "completed") {
+    ctx.throw(400, "User Guide is not ready yet");
+  }
+  ctx.body = model.get("generatedMarkdown") || "";
+  ctx.withoutDataWrapping = true;
+  ctx.set({
+    "Content-Type": "text/markdown; charset=UTF-8"
+  });
+  await next();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getMarkdown
+});

package/dist/server/collections/ai-build-guide-pages.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@nocobase/database").CollectionOptions;
+export default _default;

package/dist/server/collections/ai-build-guide-pages.js

@@ -0,0 +1,90 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ai_build_guide_pages_exports = {};
+__export(ai_build_guide_pages_exports, {
+  default: () => ai_build_guide_pages_default
+});
+module.exports = __toCommonJS(ai_build_guide_pages_exports);
+var import_database = require("@nocobase/database");
+var ai_build_guide_pages_default = (0, import_database.defineCollection)({
+  name: "aiBuildGuidePages",
+  shared: true,
+  dumpRules: "required",
+  migrationRules: ["overwrite", "schema-only"],
+  timestamps: true,
+  fields: [
+    {
+      type: "uid",
+      name: "id",
+      primaryKey: true
+    },
+    {
+      type: "belongsTo",
+      name: "space",
+      target: "aiBuildGuideSpaces",
+      foreignKey: "spaceId"
+    },
+    {
+      type: "integer",
+      name: "sort",
+      defaultValue: 0
+    },
+    {
+      type: "string",
+      name: "title"
+    },
+    {
+      type: "string",
+      name: "slug"
+    },
+    {
+      type: "text",
+      name: "goal"
+    },
+    {
+      type: "json",
+      name: "planItem"
+    },
+    {
+      type: "string",
+      name: "status",
+      defaultValue: "pending"
+    },
+    {
+      type: "text",
+      name: "generatedHtml"
+    },
+    {
+      type: "text",
+      name: "generatedMarkdown"
+    },
+    {
+      type: "text",
+      name: "buildLog"
+    }
+  ]
+});