@aigne/doc-smith 0.8.9 → 0.8.10-beta.1

package/docs/features-update-and-refine.md

@@ -1,17 +1,18 @@
 # Update and Refine
 
-Keeping documentation synchronized with an evolving codebase is essential. AIGNE DocSmith provides direct and flexible methods to keep your content current, whether through automatic updates triggered by code changes or precise, feedback-driven refinements.
+Keeping documentation synchronized with an evolving codebase is a critical task. AIGNE DocSmith provides direct and flexible methods to keep your content current, whether through automatic updates based on code changes or precise, feedback-driven refinements.
 
 This guide covers how to:
-- Automatically update documents when your code changes.
-- Manually regenerate specific documents with targeted feedback.
-- Optimize the overall documentation structure.
+
+- Automatically update documents when your source code changes.
+- Regenerate specific documents using targeted feedback.
+- Adjust the overall documentation structure.
 
 ### Document Update Workflows
 
 The following diagram illustrates the different paths you can take to update your documentation:
 
-```d2
+```d2 Update Workflows
 direction: down
 
 Start: {
@@ -66,9 +67,9 @@ Replan -> End
 
 ## Automatic Updates with Change Detection
 
-When you run the `aigne doc generate` command, DocSmith analyzes your codebase, detects any changes since the last run, and regenerates only the documents that are affected. This process saves time and reduces unnecessary LLM API calls.
+When you run the `aigne doc generate` command, DocSmith analyzes your codebase, detects any changes since the last run, and regenerates only the documents that are affected. This process saves time and reduces unnecessary API calls.
 
-```bash
+```shell icon=lucide:terminal
 # DocSmith will detect changes and update only what's necessary
 aigne doc generate
 ```
@@ -79,7 +80,7 @@ aigne doc generate
 
 If you need to regenerate all documentation from scratch, ignoring any cached or previous state, use the `--forceRegenerate` flag. This is useful after significant configuration changes or when you want to ensure a completely fresh build.
 
-```bash
+```shell icon=lucide:terminal
 # Regenerate all documentation from the ground up
 aigne doc generate --forceRegenerate
 ```
@@ -88,15 +89,15 @@ aigne doc generate --forceRegenerate
 
 ## Refining Individual Documents
 
-To improve a specific document without any corresponding code changes, the `aigne doc update` command allows you to provide targeted feedback to the AI for content refinement.
+To improve a specific document without any corresponding code changes, the `aigne doc update` command allows you to provide targeted instructions for content refinement.
 
 You can use this command in two ways: interactively or directly via command-line arguments.
 
 ### Interactive Mode
 
-For a guided experience, run the command without any arguments. DocSmith will present an interactive menu to select which document you want to update. After you choose, you'll be prompted to enter your feedback.
+For a guided experience, run the command without any arguments. DocSmith will present a menu to select which document you want to update. After you choose, you'll be prompted to enter your feedback.
 
-```bash
+```shell icon=lucide:terminal
 # Start the interactive update process
 aigne doc update
 ```
@@ -107,9 +108,9 @@ aigne doc update
 
 For faster workflows or scripting, you can specify the document and feedback directly using flags. This allows for precise, non-interactive updates.
 
-```bash
+```shell icon=lucide:terminal
 # Update a specific document with feedback
-aigne doc update --docs overview.md --feedback "Add a more comprehensive FAQ section at the end."
+aigne doc update --docs overview.md --feedback "Add a more detailed FAQ section at the end."
 ```
 
 Key parameters for the `update` command:
@@ -117,19 +118,19 @@ Key parameters for the `update` command:
 | Parameter  | Description                                                                                      |
 | ---------- | ------------------------------------------------------------------------------------------------ |
 | `--docs`     | The path to the document you want to update. You can use this flag multiple times for batch updates. |
-| `--feedback` | The specific instructions for the AI to use when regenerating the content.                       |
+| `--feedback` | The specific instructions to use when regenerating the content.                       |
 
 ---
 
 ## Optimizing the Overall Structure
 
-Beyond refining the content of individual documents, you can also adjust the overall documentation structure. If a section is missing or the existing organization could be improved, you can provide feedback to improve the documentation structure using the `generate` command with the `--feedback` flag.
+Beyond refining the content of individual documents, you can also adjust the overall documentation structure. If a section is missing or the existing organization could be improved, you can provide feedback to the `generate` command.
 
-This command instructs DocSmith to reconsider the entire document plan based on your new input.
+This command instructs DocSmith to re-evaluate the entire document plan based on your new input.
 
-```bash
+```shell icon=lucide:terminal
 # Regenerate the documentation structure with specific feedback
-aigne doc generate --feedback "Remove the 'About' section and add a more detailed 'API Reference'."
+aigne doc generate --feedback "Remove the 'About' section and add a detailed 'API Reference'."
 ```
 
 This approach is best for high-level changes to the document's table of contents, rather than line-by-line content edits.

package/docs/features-update-and-refine.zh.md

@@ -1,17 +1,18 @@
-# 更新和优化
+# 更新与优化
 
-保持文档与不断演进的代码库同步至关重要。AIGNE DocSmith 提供了直接且灵活的方法来保持内容最新，无论是通过代码变更触发的自动更新，还是通过精确的、由反馈驱动的优化。
+保持文档与不断演进的代码库同步是一项至关重要的任务。AIGNE DocSmith 提供了直接而灵活的方法来确保内容保持最新，无论是通过基于代码变更的自动更新，还是通过由反馈驱动的精确优化。
 
-本指南涵盖了如何：
-- 当代码变更时自动更新文档。
-- 使用有针对性的反馈手动重新生成特定文档。
-- 优化整体文档结构。
+本指南将介绍如何：
+
+- 在源代码变更时自动更新文档。
+- 使用有针对性的反馈重新生成特定文档。
+- 调整整体文档结构。
 
 ### 文档更新工作流
 
-下图说明了更新文档可以采取的不同路径：
+下图说明了更新文档可采用的不同路径：
 
-```d2
+```d2 Update Workflows
 direction: down
 
 Start: {
@@ -25,12 +26,12 @@ Code-Change: {
 }
 
 Content-Tweak: {
-  label: "需要改进\n内容？"
+  label: "需要内容\n改进？"
   shape: rectangle
 }
 
 Structure-Tweak: {
-  label: "需要改进\n结构？"
+  label: "需要结构\n改进？"
   shape: rectangle
 }
 
@@ -66,20 +67,20 @@ Replan -> End
 
 ## 通过变更检测自动更新
 
-当您运行 `aigne doc generate` 命令时，DocSmith 会分析您的代码库，检测自上次运行以来的任何变更，并仅重新生成受影响的文档。此过程可以节省时间并减少不必要的 LLM API 调用。
+当您运行 `aigne doc generate` 命令时，DocSmith 会分析您的代码库，检测自上次运行以来的所有变更，并仅重新生成受影响的文档。这一过程可以节省时间并减少不必要的 API 调用。
 
-```bash
-# DocSmith 将检测变更并仅更新必要的部分
+```shell icon=lucide:terminal
+# DocSmith 将检测变更并仅更新必要部分
 aigne doc generate
 ```
 
-![DocSmith 会检测变更并仅重新生成所需的文档。](https://docsmith.aigne.io/image-bin/uploads/21a76b2f65d14d16a49c13d800f1e2c1.png)
+![DocSmith 检测变更并仅重新生成所需文档。](https://docsmith.aigne.io/image-bin/uploads/21a76b2f65d14d16a49c13d800f1e2c1.png)
 
 ### 强制完全重新生成
 
-如果您需要从头开始重新生成所有文档，忽略任何缓存或先前的状态，请使用 `--forceRegenerate` 标志。这在进行重大配置更改或希望确保完全重新构建时非常有用。
+如果您需要从头开始重新生成所有文档，忽略任何缓存或先前的状态，请使用 `--forceRegenerate` 标志。这在进行重大配置更改后，或当您希望确保构建一个全新的版本时非常有用。
 
-```bash
+```shell icon=lucide:terminal
 # 从头开始重新生成所有文档
 aigne doc generate --forceRegenerate
 ```
@@ -88,15 +89,15 @@ aigne doc generate --forceRegenerate
 
 ## 优化单个文档
 
-要在没有任何相应代码变更的情况下改进特定文档，`aigne doc update` 命令允许您向 AI 提供有针对性的反馈以进行内容优化。
+如果想在没有相应代码变更的情况下改进特定文档，可以使用 `aigne doc update` 命令提供有针对性的内容优化指令。
 
-您可以通过两种方式使用此命令：交互式或直接通过命令行参数。
+您可以通过两种方式使用此命令：交互式模式或直接通过命令行参数。
 
 ### 交互模式
 
-要获得引导式体验，请在不带任何参数的情况下运行该命令。DocSmith 将呈现一个交互式菜单，供您选择要更新的文档。选择后，系统将提示您输入反馈。
+如需引导式体验，请直接运行该命令，不带任何参数。DocSmith 将会展示一个菜单，供您选择要更新的文档。选择后，系统将提示您输入反馈。
 
-```bash
+```shell icon=lucide:terminal
 # 启动交互式更新流程
 aigne doc update
 ```
@@ -105,33 +106,33 @@ aigne doc update
 
 ### 直接通过命令行更新
 
-对于更快捷的工作流或脚本编写，您可以使用标志直接指定文档和反馈。这允许进行精确的非交互式更新。
+为了实现更快的工作流或用于脚本编写，您可以使用标志直接指定文档和反馈。这支持精确的非交互式更新。
 
-```bash
+```shell icon=lucide:terminal
 # 使用反馈更新特定文档
-aigne doc update --docs overview.md --feedback "在末尾添加一个更全面的常见问题解答部分。"
+aigne doc update --docs overview.md --feedback "在末尾添加一个更详细的 FAQ 部分。"
 ```
 
 `update` 命令的关键参数：
 
 | Parameter  | Description                                                                                      |
 | ---------- | ------------------------------------------------------------------------------------------------ |
-| `--docs`     | 要更新的文档路径。您可以多次使用此标志进行批量更新。 |
-| `--feedback` | 供 AI 在重新生成内容时使用的具体说明。                       |
+| `--docs`     | 您希望更新的文档路径。您可以多次使用此标志进行批量更新。 |
+| `--feedback` | 重新生成内容时要使用的具体指令。                       |
 
 ---
 
 ## 优化整体结构
 
-除了优化单个文档的内容外，您还可以调整整体文档结构。如果缺少某个部分或现有组织结构可以改进，您可以使用带 `--feedback` 标志的 `generate` 命令向结构规划 agent 提供反馈。
+除了优化单个文档的内容，您还可以调整整体文档结构。如果缺少某个部分或现有组织结构有待改进，您可以向 `generate` 命令提供反馈。
 
-此命令指示 DocSmith 根据您的新输入重新考虑整个文档计划。
+该命令会指示 DocSmith 根据您的新输入重新评估整个文档计划。
 
-```bash
-# 使用特定反馈重新生成结构计划
-aigne doc generate --feedback "移除‘关于’部分，并添加一个更详细的‘API 参考’。"
+```shell icon=lucide:terminal
+# 使用特定反馈重新生成文档结构
+aigne doc generate --feedback "删除‘关于’部分，并添加一个详细的‘API 参考’。"
 ```
 
-此方法最适用于文档目录的高层级更改，而非逐行内容编辑。
+这种方法最适合对文档的目录进行高层级的更改，而不是逐行编辑内容。
 
-借助这些工具，您可以维护与项目一同演进的准确文档。内容优化后，您可以将其提供给全球受众。在 [翻译文档](./features-translate-documentation.md) 指南中了解如何操作。
+借助这些工具，您可以维护与项目共同演进的准确文档。内容优化后，您可以将其提供给全球用户。具体方法请参阅[翻译文档](./features-translate-documentation.md)指南。

package/docs-mcp/get-docs-structure.mjs

@@ -13,4 +13,4 @@ export default async function getDocsStructure() {
   return { structure };
 }
 
-getDocsStructure.description = "Get docs structure";
+getDocsStructure.description = "Get documentation structure";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.9",
-  "description": "",
+  "version": "0.8.10-beta.1",
+  "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
   },
@@ -10,7 +10,7 @@
   "bin": "aigne.yaml",
   "keywords": [],
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
-  "license": "MIT",
+  "license": "Elastic-2.0",
   "dependencies": {
     "@aigne/aigne-hub": "^0.9.3",
     "@aigne/anthropic": "^0.13.3",

package/prompts/detail/document-rules.md

@@ -13,7 +13,7 @@
 - 每个 section 需要包含：标题、介绍、代码示例、响应数据示例、示例说明，示例说明跟在示例代码后描述，不需要‘示例说明’这样的小标题
 - 确保文档中的内容是完整、连贯的，用户可以跟着文档一步步顺利执行
 - 说明要尽可能的详细，如果存在配置项或参数，需要解释每个配置项或参数的含义，如果参数有多个可选值，每种可选值需要解释其含义，并尽可能配上代码示例
-- 参数、返回值、上下文数据（Context）、Props 以及与类型相关的内容优先使用 `<x-field>` 自定义组件来展示，支持嵌套结构来清晰描述复杂数据类型
+- 参数、返回值、上下文数据（Context）、Props 以及其它与类型相关的内容优先使用 `<x-field>` 自定义组件来展示，支持嵌套结构来清晰描述复杂数据类型
 - 对于复杂对象类型，使用嵌套的 `<x-field>` 结构来递归描述参数结构，嵌套层级不超过 5 级
 - 所有类型都使用开闭标签格式 `<x-field ...></x-field>`，简单类型 children 为空，复杂类型包含嵌套字段
 - 接口/方法调用的说明必须包含 **响应数据示例**

package/prompts/structure/check-document-structure.md

@@ -5,29 +5,25 @@
 <context>
 - **上一轮的结构规划 (originalDocumentStructure)**:
 <original_document_structure>
-```json
 {{ originalDocumentStructure }}
-```
 </original_document_structure>
 
-- **新生成的结构规划 (documentStructure)**:
-<document_structure>
-```json
-{{ documentStructure }}
-```
-</document_structure>
-
 {% if feedback %}
 - **用户反馈**:
 ```
 {{ feedback }}
 ```
 {% endif %}
+
+- **新生成的结构规划 (documentStructure)**:
+<document_structure>
+{{ documentStructure }}
+</document_structure>
 </context>
 
 <goal>
 你的主要目标是验证三条关键规则：
-1.  **反馈的实现**：新的结构规划**必须**正确地实现用户反馈中要求的所有变更。
+1.  **反馈的实现**：新的结构规划(document_structure)**必须**正确地实现用户反馈中要求的所有变更。
 2.  **无关节点的稳定性**：没有在用户反馈中被提及的节点 ** path、sourcesIds 属性不能被修改 **
   - `path`、`sourcesIds` 是关联现有内容的关键标识符，其稳定性至关重要。
   - 对于用户要求新增节点的场景，新增的节点可能会影响原来节点的顺序，这是允许的。
@@ -36,17 +32,17 @@
 
 <quality_control_rules>
 ### 场景 1：首次运行（没有旧的规划）
-如果 `originalDocumentStructure` 为 null、为空或未提供，这意味着这是第一次生成结构。没有可供比较的对象。
+如果 `original_document_structure` 为 null、为空或未提供，这意味着这是第一次生成结构。没有可供比较的对象。
 你的检查自动通过。
 
 ### 场景 2：迭代运行（存在旧的规划）
 这是主要场景。你必须执行详细的比较。
 
 **分步分析**：
-1.  **分析反馈**：仔细阅读并理解 `<context>` 中 用户反馈 提出的每一项变更要求。明确哪些节点是需要被修改、添加或删除的目标。
-2.  **验证反馈的实现**：对比 `<context>` 中的 `documentStructure` 和 `originalDocumentStructure`，确认所要求的变更是否已执行。例如，如果反馈是“移除‘示例’部分”，你必须检查该部分在 `documentStructure` 中是否已不存在。
-3.  **验证无关节点的稳定性**：这是最关键的检查。遍历 `documentStructure` 中的所有节点。对于每一个在 `originalDocumentStructure` 中也存在、但并未在反馈中被提及的节点：
-    *   **至关重要**：其 `path`、`sourcesIds` 属性**必须**与 `originalDocumentStructure` 中的完全相同。
+1.  **分析反馈**：仔细阅读并理解中用户反馈提出的每一项变更要求。明确哪些节点是需要被修改、添加或删除的目标。
+2.  **验证反馈的实现**：确认所要求的变更在`document_structure`已执行。例如，如果反馈是“移除‘示例’部分”，你必须检查该部分在 `document_structure` 中是否已不存在。
+3.  **验证无关节点的稳定性**：这是最关键的检查。遍历 `document_structure` 中的所有节点。对于每一个在 `original_document_structure` 中也存在、但并未在反馈中被提及的节点：
+    *   **至关重要**：其 `path`、`sourcesIds` 属性**必须**与 `original_document_structure` 中的完全相同。
     *   理想情况下，其他属性（如 `title`、`description`）也应保持稳定，除非这些变更是由某个被要求的变更直接导致的，或者是 DataSource 变更导致。
 </quality_control_rules>
 

package/release-please-config.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "include-component-in-tag": false,
+      "prerelease-type": "beta",
+      "versioning": "prerelease"
+    }
+  }
+}

package/tests/agents/generate/check-need-generate-structure.test.mjs

@@ -21,6 +21,9 @@ describe("check-need-generate-structure", () => {
   let saveValueToConfigSpy;
 
   beforeEach(() => {
+    // Set test environment variable
+    process.env.NODE_ENV = "test";
+
     // Reset all mocks
     mock.restore();
 
@@ -32,6 +35,7 @@ describe("check-need-generate-structure", () => {
     mockOptions = {
       prompts: {
         input: mock(async () => ""),
+        select: mock(async () => ""),
       },
       context: {
         agents: { refineDocumentStructure: {} },
@@ -70,6 +74,9 @@ describe("check-need-generate-structure", () => {
   });
 
   afterEach(() => {
+    // Clean up environment variable
+    delete process.env.NODE_ENV;
+
     // Restore all spies
     accessSpy?.mockRestore();
     getActiveRulesForScopeSpy?.mockRestore();
@@ -92,19 +99,7 @@ describe("check-need-generate-structure", () => {
     expect(mockOptions.context.invoke).not.toHaveBeenCalled();
   });
 
-  test("should prompt for user feedback when originalDocumentStructure exists", async () => {
-    const userFeedback = "Need more API documentation";
-    mockOptions.prompts.input.mockImplementation(async () => userFeedback);
-
-    await checkNeedGenerateStructure({ originalDocumentStructure, docsDir: "./docs" }, mockOptions);
-
-    expect(mockOptions.prompts.input).toHaveBeenCalledWith({
-      message: "How can we improve the documentation structure? (press Enter to skip):",
-    });
-    expect(mockOptions.context.invoke).toHaveBeenCalled();
-  });
-
-  test("should skip prompting if feedback is already provided", async () => {
+  test("should handle pre-existing feedback without prompting", async () => {
     const providedFeedback = "Already provided feedback";
 
     await checkNeedGenerateStructure(
@@ -257,17 +252,6 @@ describe("check-need-generate-structure", () => {
     expect(result.feedback).toBe("");
   });
 
-  test("should preserve documentStructureFeedback", async () => {
-    const feedback = "user submitted feedback";
-
-    const result = await checkNeedGenerateStructure(
-      { originalDocumentStructure, feedback, docsDir: "./docs" },
-      mockOptions,
-    );
-
-    expect(result.documentStructureFeedback).toBe(feedback);
-  });
-
   test("should pass through additional parameters", async () => {
     const additionalParams = {
       customParam1: "value1",
@@ -289,4 +273,17 @@ describe("check-need-generate-structure", () => {
       expect.objectContaining(additionalParams),
     );
   });
+
+  test("should return userDeferred when user selects 'later' and no originalDocumentStructure exists", async () => {
+    mockOptions.prompts.select.mockImplementation(async () => "later");
+
+    const result = await checkNeedGenerateStructure({ docsDir: "./docs" }, mockOptions);
+
+    expect(result).toBeDefined();
+    expect(result.userDeferred).toBe(true);
+    expect(result.documentStructure).toBe(null);
+
+    expect(mockOptions.prompts.select).toHaveBeenCalled();
+    expect(mockOptions.context.invoke).not.toHaveBeenCalled();
+  });
 });