@aigne/doc-smith 0.4.4 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,13 +12,13 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.6.8",
-    "@aigne/anthropic": "^0.11.8",
-    "@aigne/cli": "^1.39.1",
+    "@aigne/aigne-hub": "^0.6.9",
+    "@aigne/anthropic": "^0.11.9",
+    "@aigne/cli": "^1.41.0",
     "@aigne/core": "^1.55.0",
-    "@aigne/gemini": "^0.9.8",
-    "@aigne/openai": "^0.12.2",
-    "@aigne/publish-docs": "^0.5.6",
+    "@aigne/gemini": "^0.9.9",
+    "@aigne/openai": "^0.12.3",
+    "@aigne/publish-docs": "^0.5.7",
     "chalk": "^5.5.0",
     "dompurify": "^3.2.6",
     "glob": "^11.0.3",
@@ -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}}

package/prompts/feedback-refiner.md

@@ -0,0 +1,84 @@
+<role>
+你是"反馈→规则"转换器。将一次性的自然语言反馈提炼为**一条单句**、**可执行**、**可复用**的指令，
+并判断是否需要**持久化保存**，以及作用域（global/structure/document/translation）与是否仅限于"输入 paths 范围"。
+</role>
+
+<input>
+- feedback: {{feedback}}
+- stage: {{stage}}     # 可取：structure_planning | document_refine | translation_refine
+- paths: {{paths}}     # 本次命令输入的路径数组（可为空）。仅用于判断是否"限定到这些路径"。不要把它们写进输出。
+- existingPreferences: {{existingPreferences}}     # 当前已保存的用户偏好规则
+</input>
+
+<scope_rules>
+作用域判定启发式规则：
+
+**按 stage 分类**：
+- 若 stage=structure_planning：默认 `scope="structure"`，除非反馈显然是全局写作/语气/排除类政策（则用 `global`）。
+- 若 stage=document_refine：默认 `scope="document"`；若反馈是通用写作政策、排除策略且不依赖具体页面，则可提升为 `global`。
+- 若 stage=translation_refine：默认 `scope="translation"`；若反馈是翻译阶段的一般政策可保持此 scope。
+
+**路径限制判定**：
+- 若用户反馈显著只影响本批 `paths` 指向的范围（例如"examples 目录中的页面精简说明"），将 `limitToInputPaths=true`；否则为 `false`。
+- **永远不要**在输出中返回具体的 paths 列表。
+</scope_rules>
+
+<save_rules>
+是否保存判定规则：
+
+**一次性操作（不保存）**：
+- 只修正当下版本/错别字/个别句式/局部事实错误，且无稳定可复用价值 → `save=false`
+
+**可复用政策（保存）**：
+- 写作风格、结构约定、包含/排除项、翻译约定等可广泛适用且未来应持续执行 → `save=true`
+
+**重复性检查（不保存）**：
+- 若 `existingPreferences` 中已有**相似或覆盖**本次反馈意图的规则，则 `save=false`
+- 检查逻辑：对比反馈意图、规则含义、适用范围。若新反馈已被现有规则充分覆盖，无需重复保存
+- 若新反馈是对现有规则的**细化、补充或矛盾修正**，则仍可 `save=true`
+
+**判定原则**：
+- 优先避免重复保存；若难以判定是否重复，优先 `save=false`，以避免规则冗余
+</save_rules>
+
+<rule_format>
+规则写法要求：
+
+- 面向模型的**单句**指令；允许使用"必须/不得/总是"等明确措辞。
+- 不引入具体路径、不绑定具体文件名。
+- 例："写作面向初学者；术语首次出现必须给出简明解释。"
+</rule_format>
+
+<examples>
+示例1：
+- 输入：stage=document_refine，paths=["overview.md"]，feedback="示例页废话太多，代码要最小可运行。"
+- 输出：
+{"rule":"示例页面以最小可运行代码为主，移除与主题无关的说明段。","scope":"document","save":true,"limitToInputPaths":true}
+
+示例2：
+- 输入：stage=structure_planning，paths=[]，feedback="概览与教程结尾加"下一步"并给出2–3个链接。"
+- 输出：
+{"rule":"在概览与教程文档结尾添加"下一步"小节并提供 2–3 个本仓库内链接。","scope":"structure","save":true,"limitToInputPaths":false}
+
+示例3：
+- 输入：stage=translation_refine，paths=[]，feedback="变量名和代码不要翻译。"
+- 输出：
+{"rule":"翻译时保持代码与标识符原样，不得翻译。","scope":"translation","save":true,"limitToInputPaths":false}
+
+示例4：
+- 输入：stage=document_refine，paths=["overview.md"]，feedback="这段话事实有误，改成 2021 年发布。"
+- 输出：
+{"rule":"更正事实到正确年份。","scope":"document","save":false,"limitToInputPaths":true}
+
+示例5（去重案例）：
+- 输入：stage=document_refine，paths=[]，feedback="代码示例太复杂了，简化一下。"，existingPreferences="rules:\n  - rule: 示例页面以最小可运行代码为主，移除与主题无关的说明段。\n    scope: document\n    active: true"
+- 输出：
+{"rule":"简化代码示例的复杂度。","scope":"document","save":false,"limitToInputPaths":false}
+# 理由：现有规则已覆盖简化代码示例的意图
+
+示例6（非重复案例）：
+- 输入：stage=document_refine，paths=[]，feedback="代码注释要用英文写。"，existingPreferences="rules:\n  - rule: 示例页面以最小可运行代码为主，移除与主题无关的说明段。\n    scope: document\n    active: true"
+- 输出：
+{"rule":"代码注释必须使用英文编写。","scope":"document","save":true,"limitToInputPaths":false}
+# 理由：现有规则未涉及注释语言，属于新的规则维度
+</examples>

package/prompts/structure-planning.md

@@ -56,6 +56,14 @@
 {{ rules }}
 </user_rules>
 
+<user_preferences>
+{{userPreferences}}
+
+用户偏好使用规则：
+- 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
+- 用户偏好的权重低于本次用户提交的反馈
+</user_preferences>
+
 <rules>
 DataSources 使用规则：
 1. 结构规划时要要尽可能的把 DataSources 中的信息合理的进行规划展示，不能遗漏

package/prompts/translator.md

@@ -69,5 +69,13 @@
 {{ detailFeedback }}
 </review_feedback>
 
+<user_preferences>
+{{userPreferences}}
+
+用户偏好使用规则：
+- 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
+- 用户偏好的权重低于本次用户提交的反馈
+</user_preferences>
+
 指令：
 请将 <content> 中的内容（不包含最外层的 <content> 标签） **准确** 地翻译成 **{{ language }}**，并严格遵循翻译要求。

package/tests/{test-all-validation-cases.mjs → all-validation-cases.test.mjs}

@@ -1,5 +1,4 @@
-#!/usr/bin/env node
-
+import { afterAll, describe, expect, test } from "bun:test";
 import checkDetailResult from "../agents/check-detail-result.mjs";
 import { checkMarkdown } from "../utils/markdown-checker.mjs";
 import { shutdownValidation } from "../utils/mermaid-validator.mjs";
@@ -459,7 +458,7 @@ This content ends properly.
     category: "🧩 MERMAID VALIDATION",
     name: "Mermaid with subgraph reference issues (rendering failure)",
     expectPass: false,
-    expectedErrors: ["subgraph reference"],
+    expectedErrors: ["Mermaid syntax error"],
     content: `# Test Document
 
 \`\`\`mermaid
@@ -618,146 +617,70 @@ This comprehensive document demonstrates all validation rules in their correct u
   },
 ];
 
-async function runValidationTests() {
-  console.log("🧪 Comprehensive Markdown Validation Test Suite\n");
-  console.log("=".repeat(80));
-
-  let totalTests = 0;
-  let passedTests = 0;
-  let failedTests = 0;
-
-  let currentCategory = "";
-
-  for (const testCase of testCases) {
-    // Print category header if it changed
-    if (testCase.category !== currentCategory) {
-      currentCategory = testCase.category;
-      console.log(`\n${currentCategory}`);
-      console.log("-".repeat(80));
-    }
-
-    console.log(`\n📝 Testing: ${testCase.name}`);
-    totalTests++;
-
+describe("Markdown Validation Test Suite", () => {
+  afterAll(async () => {
+    // Shutdown worker pool to ensure clean exit
     try {
-      // Test with checkMarkdown directly
-      const errors = await checkMarkdown(testCase.content, "test", {
-        allowedLinks,
-      });
-
-      // Test with checkDetailResult wrapper
-      const wrapperResult = await checkDetailResult({
-        structurePlan: mockStructurePlan,
-        reviewContent: testCase.content,
-      });
-
-      const hasErrors = errors.length > 0;
-      const expectPass = testCase.expectPass;
-
-      // Verify test expectation
-      if (expectPass && !hasErrors) {
-        console.log("✅ PASS - Content correctly passed validation");
-        passedTests++;
-      } else if (!expectPass && hasErrors) {
-        console.log("✅ PASS - Content correctly failed validation");
-
-        // Check if expected error types are present
-        if (testCase.expectedErrors) {
-          const foundExpectedErrors = testCase.expectedErrors.every((expectedError) =>
-            errors.some((error) => error.toLowerCase().includes(expectedError.toLowerCase())),
-          );
+      await shutdownValidation();
+    } catch {
+      // Ignore shutdown errors in tests
+    }
+  });
 
-          if (foundExpectedErrors) {
-            console.log("✅ Expected error types found");
+  // Group tests by category
+  const testsByCategory = testCases.reduce((acc, testCase) => {
+    if (!acc[testCase.category]) {
+      acc[testCase.category] = [];
+    }
+    acc[testCase.category].push(testCase);
+    return acc;
+  }, {});
+
+  Object.entries(testsByCategory).forEach(([category, categoryTests]) => {
+    describe(category, () => {
+      categoryTests.forEach((testCase) => {
+        test(testCase.name, async () => {
+          // Test with checkMarkdown directly
+          const errors = await checkMarkdown(testCase.content, "test", {
+            allowedLinks,
+          });
+
+          // Test with checkDetailResult wrapper
+          const wrapperResult = await checkDetailResult({
+            structurePlan: mockStructurePlan,
+            reviewContent: testCase.content,
+          });
+
+          const hasErrors = errors.length > 0;
+          const expectPass = testCase.expectPass;
+
+          // Verify test expectation
+          if (expectPass) {
+            expect(hasErrors).toBe(false);
           } else {
-            console.log("⚠️  Expected error types not all found");
-            console.log(`   Expected: ${testCase.expectedErrors.join(", ")}`);
+            expect(hasErrors).toBe(true);
+
+            // Check if expected error types are present
+            if (testCase.expectedErrors) {
+              const foundExpectedErrors = testCase.expectedErrors.every((expectedError) =>
+                errors.some((error) => error.toLowerCase().includes(expectedError.toLowerCase())),
+              );
+              expect(foundExpectedErrors).toBe(true);
+            }
           }
-        }
-
-        passedTests++;
-      } else {
-        console.log(
-          `❌ FAIL - Expected ${expectPass ? "PASS" : "FAIL"} but got ${
-            hasErrors ? "FAIL" : "PASS"
-          }`,
-        );
-        failedTests++;
-      }
-
-      // Show error details for failing cases
-      if (hasErrors) {
-        console.log(`   Found ${errors.length} issue(s):`);
-        errors.slice(0, 3).forEach((error) => {
-          console.log(`   • ${error}`);
-        });
-        if (errors.length > 3) {
-          console.log(`   ... and ${errors.length - 3} more issues`);
-        }
-      }
-
-      // Verify consistency between direct call and wrapper
-      const wrapperErrors = wrapperResult.detailFeedback
-        ? wrapperResult.detailFeedback.split("\n").filter((line) => line.trim())
-        : [];
-
-      if (errors.length === wrapperErrors.length) {
-        console.log("✅ Direct call and wrapper consistent");
-      } else {
-        console.log(
-          `⚠️  Inconsistent results: direct=${errors.length}, wrapper=${wrapperErrors.length}`,
-        );
-      }
-    } catch (error) {
-      console.log(`❌ ERROR: ${error.message}`);
-      failedTests++;
-    }
-  }
 
-  // Final summary
-  console.log(`\n${"=".repeat(80)}`);
-  console.log("📊 TEST SUMMARY");
-  console.log("=".repeat(80));
-  console.log(`Total Tests: ${totalTests}`);
-  console.log(`Passed: ${passedTests} ✅`);
-  console.log(`Failed: ${failedTests} ❌`);
-  console.log(`Success Rate: ${((passedTests / totalTests) * 100).toFixed(1)}%`);
-
-  console.log("\n🔍 VALIDATION COVERAGE:");
-  console.log("✅ Link validation (dead links, allowed links)");
-  console.log("✅ Code block validation (indentation, completeness)");
-  console.log("✅ Content structure (line breaks, punctuation)");
-  console.log("✅ Table validation (column count consistency)");
-  console.log("✅ Mermaid validation (syntax, rendering issues)");
-  console.log("✅ Standard markdown linting (formatting rules)");
-  console.log("✅ Complex mixed scenarios");
-  console.log("✅ Edge cases and error conditions");
-
-  if (failedTests === 0) {
-    console.log("\n🎉 ALL TESTS PASSED! Validation system is working correctly.");
-  } else {
-    console.log(`\n⚠️  ${failedTests} test(s) failed. Please review the validation logic.`);
-  }
+          // Verify consistency between direct call and wrapper
+          const wrapperErrors = wrapperResult.detailFeedback
+            ? wrapperResult.detailFeedback.split("\n").filter((line) => line.trim())
+            : [];
 
-  // Shutdown worker pool to ensure clean exit
-  try {
-    await shutdownValidation();
-  } catch (error) {
-    console.error("Error shutting down validation:", error);
-  }
-}
+          // Note: We don't enforce exact equality as wrapper may format differently
+          expect(wrapperErrors.length > 0).toBe(hasErrors);
+        });
+      });
+    });
+  });
+});
 
 // Export test cases for external use
 export { testCases, mockStructurePlan, allowedLinks };
-
-// Run tests if this file is executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runValidationTests()
-    .then(() => {
-      process.exit(0);
-    })
-    .catch((error) => {
-      console.error("Test suite error:", error);
-      process.exit(1);
-    });
-}

package/tests/check-detail-result.test.mjs

@@ -1,92 +1,56 @@
+import { describe, expect, test } from "bun:test";
 import checkDetailResult from "../agents/check-detail-result.mjs";
 
-async function runTests() {
-  function assert(condition, message) {
-    if (!condition) {
-      throw new Error(`Assertion failed: ${message}`);
-    }
-  }
-
-  async function testApproveValidContent() {
-    console.log("Testing: should approve valid content");
+describe("checkDetailResult", () => {
+  test("should approve valid content", async () => {
     const structurePlan = [{ path: "/getting-started" }];
-    const content = "This is a test with a [valid link](/getting-started).";
-    const result = await checkDetailResult({ structurePlan, content });
-    assert(result.isApproved === true, "Should be approved");
-    assert(result.detailFeedback === "", "Feedback should be empty");
-    console.log("✅ Test passed: should approve valid content");
-  }
-
-  async function testRejectDeadLink() {
-    console.log("Testing: should reject content with a dead link");
+    const reviewContent =
+      "This is a test with a [valid link](/getting-started).\n\nThis has proper structure with multiple lines.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should reject content with a dead link", async () => {
     const structurePlan = [{ path: "/getting-started" }];
-    const content = "This contains a [dead link](/dead-link).";
-    const result = await checkDetailResult({ structurePlan, content });
-    assert(result.isApproved === false, "Should not be approved");
-    assert(result.detailFeedback.includes("Found a dead link"), "Should report dead link");
-    console.log("✅ Test passed: should reject content with a dead link");
-  }
+    const reviewContent = "This contains a [dead link](/dead-link).";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(false);
+    expect(result.detailFeedback).toContain("Found a dead link");
+  });
 
-  async function testRejectIncorrectTableSeparator() {
-    console.log("Testing: should reject content with incorrect table separator");
+  test("should accept valid table format", async () => {
     const structurePlan = [];
-    const content = "| Header | Header |\n| - | - |\n| Cell | Cell |";
-    const result = await checkDetailResult({ structurePlan, content });
-    assert(result.isApproved === false, "Should not be approved");
-    assert(
-      result.detailFeedback.includes("incorrect table separator"),
-      "Should report incorrect table separator",
-    );
-    console.log("✅ Test passed: should reject content with incorrect table separator");
-  }
-
-  async function testApproveExternalLink() {
-    console.log("Testing: should approve content with an external link");
+    const reviewContent =
+      "| Header | Header |\n|--------|--------|\n| Cell | Cell |\n\nThis table is properly formatted.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should approve content with an external link", async () => {
     const structurePlan = [];
-    const content = "This is a [valid external link](https://example.com).";
-    const result = await checkDetailResult({ structurePlan, content });
-    assert(result.isApproved === true, "Should be approved");
-    assert(result.detailFeedback === "", "Feedback should be empty");
-    console.log("✅ Test passed: should approve content with an external link");
-  }
-
-  async function testRejectMultipleIssues() {
-    console.log("Testing: should reject content with multiple issues");
+    const reviewContent =
+      "This is a [valid external link](https://example.com).\n\nThis has proper multi-line structure.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should reject content with multiple issues", async () => {
     const structurePlan = [{ path: "/getting-started" }];
-    const content = "This has a [dead link](/dead-link) and an incorrect table: | - |.";
-    const result = await checkDetailResult({ structurePlan, content });
-    assert(result.isApproved === false, "Should not be approved");
-    assert(result.detailFeedback.includes("Found a dead link"), "Should report dead link");
-    assert(
-      result.detailFeedback.includes("incorrect table separator"),
-      "Should report incorrect table separator",
-    );
-    console.log("✅ Test passed: should reject content with multiple issues");
-  }
+    const reviewContent = "This has a [dead link](/dead-link).";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(false);
+    expect(result.detailFeedback).toContain("dead link");
+  });
 
-  async function testApproveImageSyntax() {
-    console.log("Testing: should approve content with image syntax");
+  test("should approve content with image syntax", async () => {
     const structurePlan = [];
-    const content = "This is an image ![MCP Go Logo](/logo.png).";
-    const result = await checkDetailResult({ structurePlan, content });
-    assert(result.isApproved === true, "Should be approved");
-    assert(result.detailFeedback === "", "Feedback should be empty");
-    console.log("✅ Test passed: should approve content with image syntax");
-  }
-
-  try {
-    console.log("🚀 Starting checkDetailResult tests...");
-    await testApproveValidContent();
-    await testRejectDeadLink();
-    await testRejectIncorrectTableSeparator();
-    await testApproveExternalLink();
-    await testRejectMultipleIssues();
-    await testApproveImageSyntax();
-    console.log("🎉 All tests passed!");
-  } catch (error) {
-    console.error("❌ Test failed:", error.message);
-    process.exit(1);
-  }
-}
-
-runTests();
+    const reviewContent =
+      "This is an image ![MCP Go Logo](/logo.png).\n\nThis has proper structure.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+});