plugin-build-guide-block 1.0.12 → 1.1.3

package/dist/server/actions/build.js

@@ -1,12 +1,3 @@
-/**
- * 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 __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -44,7 +35,12 @@ 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 = 1;
+const MAX_CHAPTERS = 12;
+const DEFAULT_TARGET_CHAPTERS = 5;
 const SANITIZE_OPTIONS = {
   allowedTags: [
     "div",
@@ -78,7 +74,7 @@ const SANITIZE_OPTIONS = {
   allowedAttributes: {
     a: ["href", "target"],
     img: ["src", "alt", "width", "height"],
-    "*": ["style", "class"]
+    "*": ["style", "class", "id"]
   },
   allowedStyles: {
     "*": {
@@ -89,6 +85,11 @@ const SANITIZE_OPTIONS = {
     }
   }
 };
+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 "";
@@ -97,20 +98,341 @@ 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 targetCount = clampChapterCount(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, targetCount);
+  }
+  const rawChapters = Array.isArray(parsed == null ? void 0 : parsed.chapters) ? parsed.chapters : [];
+  const planTitle = (parsed == null ? void 0 : parsed.title) ? String(parsed.title) : guideTitle;
+  const fallbackPlan = createFallbackPlan(planTitle, targetCount);
+  const chapters = fallbackPlan.chapters.map((fallback, index) => {
+    const item = rawChapters[index];
+    if (!item) return fallback;
+    const title = typeof item === "string" ? item : item == null ? void 0 : item.title;
+    const goal = typeof item === "object" ? item == null ? void 0 : item.goal : void 0;
+    const sourceHints = typeof item === "object" && Array.isArray(item == null ? void 0 : item.sourceHints) ? item.sourceHints : void 0;
+    return {
+      title: String(title || fallback.title),
+      goal: goal ? String(goal) : fallback.goal,
+      sourceHints: sourceHints ? sourceHints.map((hint) => String(hint)) : fallback.sourceHints
+    };
+  });
+  return {
+    title: planTitle,
+    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} chapter${targetCount === 1 ? "" : "s"}.
+- If more than one chapter is requested, each chapter must cover a distinct user goal.
+- 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");
@@ -128,75 +450,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, outputFormat } = space.get();
-      const format = outputFormat === "markdown" ? "markdown" : "html";
-      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 = format === "markdown" ? `Please generate a comprehensive user guide in pure Markdown based on the following documents. Output ONLY Markdown content (no HTML wrappers, no code-fence around the whole document).
-
-Documents:
-${documentsText}` : `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);
-      const rawText = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      const updateValues = { status: "completed" };
-      if (format === "markdown") {
-        const rawMarkdown = rawText.replace(/^```(?:markdown|md)?\s*/, "").replace(/```\s*$/, "");
-        const renderedHtml = await import_marked.marked.parse(rawMarkdown, { async: true });
-        const cleanHtml = (0, import_sanitize_html.default)(renderedHtml, SANITIZE_OPTIONS);
-        updateValues.generatedMarkdown = rawMarkdown;
-        updateValues.generatedHtml = cleanHtml;
-      } else {
-        const rawHtml = rawText.replace(/^```html\s*/, "").replace(/```\s*$/, "");
-        const cleanHtml = (0, import_sanitize_html.default)(rawHtml, SANITIZE_OPTIONS);
-        updateValues.generatedHtml = cleanHtml;
-        updateValues.generatedMarkdown = null;
-      }
-      await bgRepo.update({
-        filterByTk,
-        values: updateValues
-      });
-    })();
-    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)
           }
         });
@@ -211,6 +476,7 @@ ${documentsText}`;
       filterByTk,
       values: {
         status: "error",
+        buildPhase: "error",
         buildLog: error.message || String(error)
       }
     });

package/dist/server/actions/getHtml.js

@@ -1,12 +1,3 @@
-/**
- * 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;

package/dist/server/actions/getMarkdown.js

@@ -1,12 +1,3 @@
-/**
- * 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;

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,81 @@
+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"
+    }
+  ]
+});

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

@@ -1,12 +1,3 @@
-/**
- * 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;
@@ -63,6 +54,15 @@ var ai_build_guide_spaces_default = (0, import_database.defineCollection)({
       name: "outputFormat",
       defaultValue: "html"
     },
+    {
+      type: "integer",
+      name: "targetChapterCount",
+      defaultValue: 5
+    },
+    {
+      type: "text",
+      name: "chapterGuidance"
+    },
     {
       type: "text",
       name: "generatedHtml"
@@ -71,6 +71,24 @@ var ai_build_guide_spaces_default = (0, import_database.defineCollection)({
       type: "text",
       name: "generatedMarkdown"
     },
+    {
+      type: "json",
+      name: "planJson"
+    },
+    {
+      type: "string",
+      name: "buildPhase",
+      defaultValue: "idle"
+    },
+    {
+      type: "integer",
+      name: "pageCount",
+      defaultValue: 0
+    },
+    {
+      type: "string",
+      name: "sourceHash"
+    },
     {
       type: "string",
       name: "status",
@@ -84,6 +102,12 @@ var ai_build_guide_spaces_default = (0, import_database.defineCollection)({
       type: "belongsToMany",
       name: "documents",
       target: "attachments"
+    },
+    {
+      type: "hasMany",
+      name: "pages",
+      target: "aiBuildGuidePages",
+      foreignKey: "spaceId"
     }
   ]
 });

package/dist/server/index.js

@@ -1,12 +1,3 @@
-/**
- * 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 __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/server/plugin.d.ts

@@ -1,8 +1,11 @@
 import { InstallOptions, Plugin } from '@nocobase/server';
 export declare class PluginBuildGuideBlockServer extends Plugin {
+    private readonly schemaCollections;
     afterAdd(): void;
     beforeLoad(): void;
     load(): Promise<void>;
+    private ensureCollectionSchema;
+    private ensureSchema;
     install(options?: InstallOptions): Promise<void>;
     upgrade(): Promise<void>;
     afterEnable(): Promise<void>;