@aigne/doc-smith 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.5.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.5.0...v0.5.1) (2025-08-26)
+
+
+### Miscellaneous Chores
+
+* release 0.5.1 ([892d96e](https://github.com/AIGNE-io/aigne-doc-smith/commit/892d96e939a6404a42e8d2521f95bb7acfeabe27))
+
+## [0.5.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.4.5...v0.5.0) (2025-08-26)
+
+
+### Features
+
+* support persistent user feedback as preferences ([#57](https://github.com/AIGNE-io/aigne-doc-smith/issues/57)) ([761a583](https://github.com/AIGNE-io/aigne-doc-smith/commit/761a583297b397a12d848d10d26cd5b675f8a9e7))
+
+
+### Bug Fixes
+
+* polish init question copy ([#65](https://github.com/AIGNE-io/aigne-doc-smith/issues/65)) ([d4e8762](https://github.com/AIGNE-io/aigne-doc-smith/commit/d4e8762f26fd757bde43427860a0c1dade384269))
+
 ## [0.4.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.4.4...v0.4.5) (2025-08-25)
 
 

package/agents/batch-translate.yaml

@@ -6,6 +6,9 @@ skills:
     task_render_mode: collapse
     name: translate
     skills:
+      - url: ./find-user-preferences-by-path.mjs
+        default_input:
+          scope: translation
       - ./translate.yaml
       - type: transform
         jsonata: |

package/agents/check-feedback-refiner.mjs

@@ -0,0 +1,79 @@
+import { stringify } from "yaml";
+import { addPreferenceRule, readPreferences } from "../utils/preferences-utils.mjs";
+
+export default async function checkFeedbackRefiner(
+  { feedback, stage, selectedPaths, structurePlanFeedback },
+  options,
+) {
+  // If feedback is empty, no need to save user preferences
+  if (!feedback && !structurePlanFeedback) {
+    return {};
+  }
+
+  // Read existing preferences as context for deduplication
+  const existingPreferences = readPreferences();
+  const activePreferences = existingPreferences.rules?.filter((rule) => rule.active) || [];
+
+  // Convert active preferences to YAML string format for passing
+  const activePreferencesYaml =
+    activePreferences.length > 0 ? stringify({ rules: activePreferences }, { indent: 2 }) : "";
+
+  const feedbackToUse = feedback || structurePlanFeedback;
+  const result = await options.context.invoke(options.context.agents["feedbackRefiner"], {
+    feedback: feedbackToUse,
+    stage,
+    paths: selectedPaths,
+    existingPreferences: activePreferencesYaml,
+  });
+
+  // If preferences need to be saved, save them to the preference file
+  if (result?.save) {
+    try {
+      const savedRule = addPreferenceRule(result, feedbackToUse, selectedPaths);
+
+      // Add saved preference information to the return result
+      result.savedPreference = {
+        id: savedRule.id,
+        saved: true,
+      };
+    } catch (error) {
+      console.error(
+        "Failed to save user preference rule:",
+        error.message,
+        "\nFeedback:",
+        feedbackToUse,
+      );
+      result.savedPreference = {
+        saved: false,
+        error: error.message,
+      };
+    }
+  }
+
+  return result;
+}
+
+checkFeedbackRefiner.input_schema = {
+  type: "object",
+  properties: {
+    feedback: {
+      type: "string",
+      description: "User feedback to refine",
+    },
+    structurePlanFeedback: {
+      type: "string",
+      description: "Feedback from structure planning stage",
+    },
+    stage: {
+      type: "string",
+      description: "Stage of the feedback",
+    },
+    selectedPaths: {
+      type: "array",
+      items: {
+        type: "string",
+      },
+      description: "Selected paths of documents",
+    },
+  },
+};

package/agents/check-structure-plan.mjs

@@ -1,5 +1,6 @@
 import { access } from "node:fs/promises";
 import { join } from "node:path";
+import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
 import {
   getCurrentGitHead,
   getProjectInfo,
@@ -15,6 +16,7 @@ export default async function checkStructurePlan(
   // Check if we need to regenerate structure plan
   let shouldRegenerate = false;
   let finalFeedback = feedback;
+  let submittedFeedback = feedback;
 
   // Prompt for feedback if originalStructurePlan exists and no feedback provided
   if (originalStructurePlan && !feedback) {
@@ -24,6 +26,7 @@ export default async function checkStructurePlan(
 
     if (userFeedback?.trim()) {
       finalFeedback = userFeedback.trim();
+      submittedFeedback = userFeedback.trim();
     }
   }
 
@@ -84,9 +87,21 @@ export default async function checkStructurePlan(
 
   const panningAgent = options.context.agents["structurePlanning"];
 
+  // Get user preferences for structure planning and global scope
+  const structureRules = getActiveRulesForScope("structure", []);
+  const globalRules = getActiveRulesForScope("global", []);
+
+  // Combine structure and global rules, extract only rule text
+  const allApplicableRules = [...structureRules, ...globalRules];
+  const ruleTexts = allApplicableRules.map((rule) => rule.rule);
+
+  // Convert rule texts to string format for passing to the agent
+  const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
+
   const result = await options.context.invoke(panningAgent, {
     feedback: finalFeedback || "",
     originalStructurePlan,
+    userPreferences,
     ...rest,
   });
 
@@ -140,6 +155,7 @@ export default async function checkStructurePlan(
   return {
     ...result,
     feedback: "", // clear feedback
+    structurePlanFeedback: submittedFeedback,
     projectInfoMessage: message,
     originalStructurePlan: originalStructurePlan
       ? originalStructurePlan

package/agents/detail-generator-and-translate.yaml

@@ -7,6 +7,9 @@ skills:
     task_render_mode: collapse
     name: detailGenerate
     skills:
+      - url: ./find-user-preferences-by-path.mjs
+        default_input:
+          scope: document
       - ./content-detail-generator.yaml
       - type: transform
         jsonata: |

package/agents/detail-regenerator.yaml

@@ -34,6 +34,9 @@ skills:
       - ./detail-generator-and-translate.yaml
     iterate_on: selectedDocs
     concurrency: 3
+  - url: ./check-feedback-refiner.mjs
+    default_input:
+      stage: document_refine
   - url: ./action-success.mjs
     default_input:
       action: "Document updated"

package/agents/docs-generator.yaml

@@ -37,6 +37,9 @@ skills:
       ])
   - ./format-structure-plan.mjs
   - ./batch-docs-detail-generator.yaml
+  - url: ./check-feedback-refiner.mjs
+    default_input:
+      stage: structure_planning
   - ./save-docs.mjs
 
 input_schema:

package/agents/feedback-refiner.yaml

@@ -0,0 +1,48 @@
+name: feedbackRefiner
+description: Analyzes a user's specific feedback on generated documentation and refines it into a general, reusable preference rule for future use.
+
+# The instructions file contains the core logic (the prompt) for this Agent.
+instructions:
+  url: ../prompts/feedback-refiner.md
+
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: User's original feedback
+    stage:
+      type: string
+      description: The command/scenario that generated the feedback (used to infer scope), possible values. structure_planning, document_refine, translation_refine
+    paths:
+      type: array
+      items:
+        type: string
+      description: Optional. Document paths specified by the user in the current command
+    existingPreferences:
+      type: string
+      description: Optional. YAML format string of currently saved user preference rules, used to avoid duplicate saving of similar rules
+  required: 
+    - feedback
+    - stage
+
+output_schema:
+  type: object
+  properties:
+    rule:
+      type: string
+      description: Refine and summarize user feedback into a general rule
+    scope:
+      type: string
+      description: Rule scope. global, structure, document, translation
+    save:
+      type: boolean
+      description: Whether to save as persistent preference (true=save; false=one-time, do not save)
+    limitToInputPaths:
+      type: boolean
+      description: Whether to limit to the "paths specified in current input" when used subsequently
+  required:
+    - rule
+    - scope
+    - save
+    - limitToInputPaths

package/agents/find-items-by-paths.mjs

@@ -95,5 +95,9 @@ export default async function selectedDocs(
   // Add feedback to all results if provided
   foundItems = addFeedbackToItems(foundItems, userFeedback);
 
-  return { selectedDocs: foundItems };
+  return {
+    selectedDocs: foundItems,
+    feedback: userFeedback,
+    selectedPaths: foundItems.map((item) => item.path),
+  };
 }

package/agents/find-user-preferences-by-path.mjs

@@ -0,0 +1,37 @@
+import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
+
+export default async function findUserPreferencesByPath({ path, scope }) {
+  // Get global rules (always applicable)
+  const globalRules = getActiveRulesForScope("global", []);
+
+  // Get scope-specific rules (document/translation based on scope parameter)
+  const scopeRules = getActiveRulesForScope(scope, path ? [path] : []);
+
+  // Combine all applicable rules
+  const allApplicableRules = [...globalRules, ...scopeRules];
+
+  // Extract only rule text and join with double newlines
+  const ruleTexts = allApplicableRules.map((rule) => rule.rule);
+  const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
+
+  return {
+    userPreferences,
+  };
+}
+
+findUserPreferencesByPath.input_schema = {
+  type: "object",
+  properties: {
+    path: {
+      type: "string",
+      description: "Document path to find preferences for",
+    },
+    scope: {
+      type: "string",
+      description:
+        "Preference scope: 'document' for update operations, 'translation' for translate operations",
+      enum: ["document", "translation"],
+    },
+  },
+  required: ["scope"],
+};

package/agents/input-generator.mjs

@@ -47,8 +47,7 @@ export default async function init(
 
   // 1. Primary purpose - what's the main outcome you want readers to achieve?
   const purposeChoices = await options.prompts.checkbox({
-    message:
-      "📝 Step 1/8: What's the main outcome you want readers to achieve? (Select all that apply)",
+    message: "📝 [1/8]: What is the primary goal for your readers? (Select all that apply)",
     choices: Object.entries(DOCUMENT_STYLES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, style]) => ({
@@ -96,7 +95,7 @@ export default async function init(
 
   // 2. Target audience - who will be reading this most often?
   const audienceChoices = await options.prompts.checkbox({
-    message: "👥 Step 2/8: Who will be reading this most often? (Select all that apply)",
+    message: "👥 [2/8]: Who is the primary audience for this documentation?",
     choices: Object.entries(TARGET_AUDIENCES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, audience]) => ({
@@ -130,7 +129,7 @@ export default async function init(
   );
 
   const knowledgeChoice = await options.prompts.select({
-    message: "🧠 Step 3/8: What do readers typically know when they arrive?",
+    message: "🧠 [3/8]: What is your reader's typical starting knowledge level?",
     choices: Object.entries(filteredKnowledgeOptions).map(([key, level]) => ({
       name: `${level.name}`,
       description: level.description,
@@ -175,7 +174,7 @@ export default async function init(
   );
 
   const depthChoice = await options.prompts.select({
-    message: "📊 Step 4/8: How comprehensive should the documentation be?",
+    message: "📊 [4/8]: How comprehensive should the documentation be?",
     choices: Object.entries(filteredDepthOptions).map(([key, depth]) => ({
       name: `${depth.name}`,
       description: depth.description,
@@ -193,7 +192,7 @@ export default async function init(
 
   // Let user select primary language from supported list
   const primaryLanguageChoice = await options.prompts.select({
-    message: "🌐 Step 5/8: Choose primary documentation language:",
+    message: "🌐 [5/8]: Choose primary documentation language:",
     choices: SUPPORTED_LANGUAGES.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -210,7 +209,7 @@ export default async function init(
   );
 
   const translateLanguageChoices = await options.prompts.checkbox({
-    message: "🔄 Step 6/8: Select translation languages:",
+    message: "🔄 [6/8]: Select translation languages:",
     choices: availableTranslationLanguages.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -221,13 +220,13 @@ export default async function init(
 
   // 7. Documentation directory
   const docsDirInput = await options.prompts.input({
-    message: `📁 Step 7/8: Where to save generated docs:`,
+    message: `📁 [7/8]: Where to save generated docs:`,
     default: `${outputPath}/docs`,
   });
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 
   // 8. Source code paths
-  console.log("\n🔍 Step 8/8: Source Code Paths");
+  console.log("\n🔍 [8/8]: Source Code Paths");
   console.log("Enter paths to analyze for documentation (e.g., ./src, ./lib)");
   console.log("💡 If no paths are configured, './' will be used as default");
 

package/agents/manage-prefs.mjs

@@ -0,0 +1,203 @@
+import { readPreferences, removeRule, writePreferences } from "../utils/preferences-utils.mjs";
+
+/**
+ * List all user preferences with formatted display
+ * @returns {Object} Result with formatted message
+ */
+function listPreferences() {
+  const preferences = readPreferences();
+
+  if (preferences.rules.length === 0) {
+    return { message: "No preferences found." };
+  }
+
+  let message = "# User Preferences\n\n";
+
+  // Add format explanation
+  message += "**Format explanation:**\n";
+  message += "- 🟢 = Active preference, ⚪ = Inactive preference\n";
+  message += "- [scope] = Preference scope (global, structure, document, translation)\n";
+  message += "- ID = Unique preference identifier\n";
+  message += "- Paths = Specific file paths (if applicable)\n\n";
+
+  preferences.rules.forEach((rule) => {
+    const status = rule.active ? "🟢" : "⚪";
+    const pathsInfo = rule.paths ? ` | Paths: ${rule.paths.join(", ")}` : "";
+
+    // First line: status, scope, ID and paths info
+    message += `${status} [${rule.scope}] ${rule.id}${pathsInfo}\n`;
+
+    // Second line: rule content (truncated if too long)
+    const maxRuleLength = 120;
+    const ruleText =
+      rule.rule.length > maxRuleLength ? `${rule.rule.substring(0, maxRuleLength)}...` : rule.rule;
+    message += `   ${ruleText}\n `;
+
+    // Add blank line after each record
+    message += `\n`;
+  });
+
+  return { message };
+}
+
+/**
+ * Remove preferences by IDs or interactive selection
+ * @param {string[]} id - Array of preference IDs to remove
+ * @param {Object} options - Options with prompts interface
+ * @returns {Object} Result with success message
+ */
+async function removePreferences(id, options) {
+  const preferences = readPreferences();
+  let targetIds = id;
+
+  if (!targetIds || targetIds.length === 0) {
+    // Interactive selection
+    if (preferences.rules.length === 0) {
+      return { message: "No preferences found to remove." };
+    }
+
+    const choices = preferences.rules.map((rule) => ({
+      name: `${rule.active ? "🟢" : "⚪"} [${rule.scope}] ${rule.rule.substring(0, 60)}${rule.rule.length > 60 ? "..." : ""}`,
+      value: rule.id,
+      description: `ID: ${rule.id}`,
+    }));
+
+    targetIds = await options.prompts.checkbox({
+      message: "Select preferences to remove:",
+      choices,
+      validate: (answer) => {
+        if (answer.length === 0) {
+          return "Please select at least one preference to remove";
+        }
+        return true;
+      },
+    });
+
+    if (!targetIds || targetIds.length === 0) {
+      return { message: "No preferences selected for removal." };
+    }
+  }
+
+  // Process the target IDs
+  const results = [];
+  for (const ruleId of targetIds) {
+    const success = removeRule(ruleId);
+    results.push({ id: ruleId, success });
+  }
+
+  const successCount = results.filter((r) => r.success).length;
+  const failedCount = targetIds.length - successCount;
+  const message =
+    failedCount > 0
+      ? `Successfully removed ${successCount} preferences, ${failedCount} failed.`
+      : `Successfully removed ${successCount} preferences.`;
+
+  return { message };
+}
+
+/**
+ * Toggle preferences active status by IDs or interactive selection
+ * @param {string[]} id - Array of preference IDs to toggle
+ * @param {Object} options - Options with prompts interface
+ * @returns {Object} Result with success message
+ */
+async function togglePreferences(id, options) {
+  const preferences = readPreferences();
+  let targetIds = id;
+
+  if (!targetIds || targetIds.length === 0) {
+    // Interactive selection
+    if (preferences.rules.length === 0) {
+      return { message: "No preferences found to toggle." };
+    }
+
+    const choices = preferences.rules.map((rule) => ({
+      name: `${rule.active ? "🟢" : "⚪"} [${rule.scope}] ${rule.rule.substring(0, 60)}${rule.rule.length > 60 ? "..." : ""}`,
+      value: rule.id,
+      description: `ID: ${rule.id}`,
+    }));
+
+    targetIds = await options.prompts.checkbox({
+      message: "Select preferences to toggle active status:",
+      choices,
+      validate: (answer) => {
+        if (answer.length === 0) {
+          return "Please select at least one preference to toggle";
+        }
+        return true;
+      },
+    });
+
+    if (!targetIds || targetIds.length === 0) {
+      return { message: "No preferences selected for toggling." };
+    }
+  }
+
+  // Process the target IDs
+  const results = [];
+  const prefs = readPreferences();
+
+  for (const ruleId of targetIds) {
+    const rule = prefs.rules.find((r) => r.id === ruleId);
+    if (rule) {
+      rule.active = !rule.active;
+      results.push({ id: ruleId, success: true, newStatus: rule.active });
+    } else {
+      results.push({ id: ruleId, success: false, error: "Rule not found" });
+    }
+  }
+
+  writePreferences(prefs);
+
+  const successCount = results.filter((r) => r.success).length;
+  const failedCount = targetIds.length - successCount;
+  const message =
+    failedCount > 0
+      ? `Successfully toggled ${successCount} preferences, ${failedCount} failed.`
+      : `Successfully toggled ${successCount} preferences.`;
+
+  return { message };
+}
+
+export default async function prefs({ list, remove, toggle, id }, options) {
+  if (list) {
+    return listPreferences();
+  }
+
+  if (remove) {
+    return await removePreferences(id, options);
+  }
+
+  if (toggle) {
+    return await togglePreferences(id, options);
+  }
+
+  return { message: "Please specify an action: --list, --remove, or --toggle." };
+}
+
+prefs.input_schema = {
+  type: "object",
+  properties: {
+    list: {
+      type: "boolean",
+      description: "List all preferences",
+    },
+    remove: {
+      type: "boolean",
+      description: "Remove preferences",
+    },
+    toggle: {
+      type: "boolean",
+      description: "Toggle preferences active status",
+    },
+    id: {
+      type: "array",
+      items: {
+        type: "string",
+      },
+      description: "Preference IDs to manage",
+    },
+  },
+};
+
+prefs.description = "Manage user preferences learned from feedback";

package/agents/publish-docs.mjs

@@ -3,7 +3,7 @@ import { publishDocs as publishDocsFn } from "@aigne/publish-docs";
 import chalk from "chalk";
 import { getAccessToken } from "../utils/auth-utils.mjs";
 import { DISCUSS_KIT_STORE_URL } from "../utils/constants.mjs";
-import { loadConfigFromFile, saveValueToConfig, getGithubRepoUrl } from "../utils/utils.mjs";
+import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
 
 const DEFAULT_APP_URL = "https://docsmith.aigne.io";
 

package/agents/retranslate.yaml

@@ -37,6 +37,9 @@ skills:
           isTranslate: true
     iterate_on: selectedDocs
     concurrency: 3
+  - url: ./check-feedback-refiner.mjs
+    default_input:
+      stage: translation_refine
   - url: ./action-success.mjs
     default_input:
       action: "Document translated"

package/agents/structure-planning.yaml

@@ -26,6 +26,9 @@ input_schema:
     feedback:
       type: string
       description: 结构规划的反馈
+    userPreferences:
+      type: string
+      description: 用户偏好规则，YAML格式的结构规划和全局范围偏好
     docsType:
       type: string
       description: 文档类型，支持：general、getting-started、reference、faq

package/aigne.yaml

@@ -37,6 +37,9 @@ agents:
   - ./docs-mcp/analyze-docs-relevance.yaml
   - ./docs-mcp/read-doc-content.mjs
   - ./docs-mcp/analyze-content-relevance.yaml
+  - ./agents/check-feedback-refiner.mjs
+  - ./agents/feedback-refiner.yaml
+  - ./agents/manage-prefs.mjs
 cli:
   agents:
     - ./agents/input-generator.mjs
@@ -44,6 +47,7 @@ cli:
     - ./agents/detail-regenerator.yaml
     - ./agents/team-publish-docs.yaml
     - ./agents/retranslate.yaml
+    - ./agents/manage-prefs.mjs
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -39,7 +39,8 @@
     "@biomejs/biome": "^2.1.4"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
     "lint": "biome check && pnpm -r run lint",
     "update:deps": "npx -y taze major -r -w -f -n '/@abtnode|@aigne|@arcblock|@blocklet|@did-connect|@did-pay|@did-space|@nft-store|@nft-studio|@ocap/' && pnpm install && pnpm run deduplicate",
     "deduplicate": "pnpm dedupe",

package/prompts/content-detail-generator.md

@@ -56,6 +56,14 @@ parentId: {{parentId}}
 ** 使用 {{ locale }} 语言输出内容 **
 </user_rules>
 
+<user_preferences>
+{{userPreferences}}
+
+用户偏好使用规则：
+- 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
+- 用户偏好的权重低于本次用户提交的反馈
+</user_preferences>
+
 <rules>
 
 目标受众：{{targetAudience}}