@aigne/doc-smith 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.8.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.4...v0.8.5) (2025-09-10)
+
+
+### Features
+
+* support publish docs to enterprise spaces ([#82](https://github.com/AIGNE-io/aigne-doc-smith/issues/82)) ([35b577a](https://github.com/AIGNE-io/aigne-doc-smith/commit/35b577ac0f2c1b860a23185054a55bada3742e8e))
+
+
+### Miscellaneous Chores
+
+* release 0.8.5 ([7a60a03](https://github.com/AIGNE-io/aigne-doc-smith/commit/7a60a03f91a20f378e94b12dd32a6a8b0a4bede5))
+
+## [0.8.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.3...v0.8.4) (2025-09-09)
+
+
+### Bug Fixes
+
+* parse markdown code blocks into custom x-code element ([#89](https://github.com/AIGNE-io/aigne-doc-smith/issues/89)) ([96ea776](https://github.com/AIGNE-io/aigne-doc-smith/commit/96ea7761299b93ea406abe04193f531fc406ccfa))
+* **utils:** update code block regex to support enhanced attributes ([#92](https://github.com/AIGNE-io/aigne-doc-smith/issues/92)) ([bf1fbab](https://github.com/AIGNE-io/aigne-doc-smith/commit/bf1fbabf193e90a83ed6e83e4ff4c5b3b2930477))
+* **ux:** make background transparent for d2 diagrams ([13eed81](https://github.com/AIGNE-io/aigne-doc-smith/commit/13eed81cb6be13c64ad04c41505d9d76f34d54bb))
+* **ux:** make background transparent for d2 diagrams ([#96](https://github.com/AIGNE-io/aigne-doc-smith/issues/96)) ([13eed81](https://github.com/AIGNE-io/aigne-doc-smith/commit/13eed81cb6be13c64ad04c41505d9d76f34d54bb))
+
 ## [0.8.3](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.2...v0.8.3) (2025-09-05)
 
 

package/README.md

@@ -19,9 +19,9 @@ As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https
 
 - **Automated Structure Planning:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
 - **AI-Powered Content Generation:** Populates the document structure with detailed, high-quality content.
-- **Multi-Language Support:** Seamlessly translates your documentation into 12+ languages including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
-- **AIGNE Hub Integration:** Use AIGNE Hub as your LLM provider without needing your own API keys, with easy switching between different large language models.
-- **Discuss Kit Publishing:** Publish documentation to the official platform at [docsmith.aigne.io](https://docsmith.aigne.io/app/) or your own independently deployed Discuss Kit instance.
+- **Multi-Language Support:** Seamlessly translates your documentation into 12 languages including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
+- **AIGNE Hub Integration:** Use [AIGNE Hub](https://www.aigne.io/en/hub) as your LLM provider without needing your own API keys, with easy switching between different large language models.
+- **Document Publishing:** Preview your documentation on the official platform at [docsmith.aigne.io](https://docsmith.aigne.io/app/), or publish to your own [Discuss Kit](https://www.arcblock.io/docs/web3-kit/en/discuss-kit) instance for full control.
 - **Document Update Mechanism:** Automatically detects source code changes and updates documentation accordingly.
 - **Individual Document Optimization:** Regenerate and optimize specific documents with targeted feedback.
 
@@ -29,9 +29,81 @@ As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https
 
 ### Prerequisites
 
-- Node.js and pnpm
+- Node.js and npm
 - AIGNE CLI
 
+### Node.js Installation
+
+#### Windows
+1. Download Node.js installer from [nodejs.org](https://nodejs.org/)
+2. Run the installer (.msi file)
+3. Follow installation wizard steps
+4. Verify installation: `node --version`
+
+#### macOS
+**Option 1: Using Homebrew (Recommended)**
+```bash
+# Install Homebrew if not already installed
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Node.js
+brew install node
+```
+
+**Option 2: Using the Official Installer**
+1. Download the macOS installer from [nodejs.org](https://nodejs.org/)
+2. Double-click the .pkg file to run the installer
+3. Follow the installation wizard
+4. Verify installation: `node --version`
+
+#### Linux
+
+**Ubuntu/Debian:**
+```bash
+# Update package index
+sudo apt update
+
+# Install Node.js
+sudo apt install nodejs npm
+
+# Or install latest LTS version using NodeSource repository
+curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+**CentOS/RHEL/Fedora:**
+```bash
+# For CentOS/RHEL
+sudo yum install nodejs npm
+
+# For Fedora
+sudo dnf install nodejs npm
+
+# Or using NodeSource repository
+curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
+sudo yum install nodejs
+```
+
+**Using Node Version Manager (nvm) - All Linux Distributions:**
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+
+# Restart terminal or run:
+source ~/.bashrc
+
+# Install latest LTS Node.js
+nvm install --lts
+nvm use --lts
+```
+
+#### Verification
+After installation on any platform, verify Node.js and npm are installed correctly:
+```bash
+node --version
+npm --version
+```
+
 ### Installation
 
 Install the latest version of AIGNE CLI globally:
@@ -161,7 +233,7 @@ aigne doc publish
 
 **Interactive Publishing:** When run `aigne doc publish` will present an interactive menu for you to choose between:
 - **Official Platform:** [docsmith.aigne.io](https://docsmith.aigne.io/app/)
-- **Self-Hosted Platform:** Your own deployed Discuss Kit instance
+- **Own Instance:** Your own deployed [Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu) instance
 
 
 

package/agents/input-generator.mjs

@@ -385,12 +385,18 @@ export function generateYAML(input) {
   // Generate comments and structure
   let yaml = "# Project information for documentation publishing\n";
 
-  // Serialize the project info section safely
-  const projectSection = yamlStringify({
-    projectName: config.projectName,
-    projectDesc: config.projectDesc,
-    projectLogo: config.projectLogo,
-  }).trim();
+  // Serialize the project info section safely with string quoting
+  const projectSection = yamlStringify(
+    {
+      projectName: config.projectName,
+      projectDesc: config.projectDesc,
+      projectLogo: config.projectLogo,
+    },
+    {
+      quotingType: '"',
+      defaultStringType: "QUOTE_DOUBLE",
+    },
+  ).trim();
 
   yaml += `${projectSection}\n\n`;
 

package/agents/publish-docs.mjs

@@ -5,6 +5,7 @@ import fs from "fs-extra";
 
 import { getAccessToken } from "../utils/auth-utils.mjs";
 import { DISCUSS_KIT_STORE_URL, TMP_DIR, TMP_DOCS_DIR } from "../utils/constants.mjs";
+import { deploy } from "../utils/deploy.mjs";
 import { beforePublishHook, ensureTmpDir } from "../utils/kroki-utils.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
 
@@ -17,6 +18,8 @@ export default async function publishDocs(
   // move work dir to tmp-dir
   await ensureTmpDir();
 
+  const hasDocSmithBaseUrl = !!process.env.DOC_SMITH_BASE_URL;
+
   const docsDir = join(".aigne", "doc-smith", TMP_DIR, TMP_DOCS_DIR);
   await fs.rm(docsDir, { recursive: true, force: true });
   await fs.mkdir(docsDir, {
@@ -42,18 +45,41 @@ export default async function publishDocs(
   const isDefaultAppUrl = appUrl === DEFAULT_APP_URL;
   const hasAppUrlInConfig = config?.appUrl;
 
+  let token = "";
+
   if (!useEnvAppUrl && isDefaultAppUrl && !hasAppUrlInConfig) {
+    const hasCachedCheckoutId = !!config?.checkoutId;
     const choice = await options.prompts.select({
       message: "Select platform to publish your documents:",
       choices: [
         {
-          name: "Publish to docsmith.aigne.io - free, but your documents will be public accessible, recommended for open-source projects",
+          name:
+            chalk.blue("Publish to docsmith.aigne.io") +
+            " - free, but your documents will be publicly accessible, recommended for open-source projects",
           value: "default",
         },
         {
-          name: "Publish to your own website - you will need to run Discuss Kit by your self ",
+          name: `${chalk.blue("Publish to your existing website")} - use your current website`,
           value: "custom",
         },
+        ...(hasCachedCheckoutId && hasDocSmithBaseUrl
+          ? [
+              {
+                name:
+                  chalk.yellow("Continue your previous website setup") +
+                  " - resume from where you left off",
+                value: "new-instance-continue",
+              },
+            ]
+          : []),
+        ...(hasDocSmithBaseUrl
+          ? [
+              {
+                name: `${chalk.blue("Publish to a new website")} - we'll help you set up a new website`,
+                value: "new-instance",
+              },
+            ]
+          : []),
       ],
     });
 
@@ -63,7 +89,7 @@ export default async function publishDocs(
           `Start here to run your own website:\n${chalk.cyan(DISCUSS_KIT_STORE_URL)}\n`,
       );
       const userInput = await options.prompts.input({
-        message: "Please enter your Discuss Kit platform URL:",
+        message: "Please enter your website URL:",
         validate: (input) => {
           try {
             // Check if input contains protocol, if not, prepend https://
@@ -77,10 +103,31 @@ export default async function publishDocs(
       });
       // Ensure appUrl has protocol
       appUrl = userInput.includes("://") ? userInput : `https://${userInput}`;
+    } else if (hasDocSmithBaseUrl && ["new-instance", "new-instance-continue"].includes(choice)) {
+      // Deploy a new Discuss Kit service
+      try {
+        let id = "";
+        let paymentUrl = "";
+        if (choice === "new-instance-continue") {
+          id = config?.checkoutId;
+          paymentUrl = config?.paymentUrl;
+          console.log(`\nResuming your previous website setup...`);
+        } else {
+          console.log(`\nCreating a new doc website for your documentation...`);
+        }
+        const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentUrl)) || {};
+
+        appUrl = homeUrl;
+        token = ltToken;
+      } catch (error) {
+        const errorMsg = error?.message || "Unknown error occurred";
+        console.error(`${chalk.red("❌ Failed to publish to website:")} ${errorMsg}`);
+        return { message: `❌ Publish failed: ${errorMsg}` };
+      }
     }
   }
 
-  const accessToken = await getAccessToken(appUrl);
+  const accessToken = await getAccessToken(appUrl, token);
 
   process.env.DOC_ROOT_DIR = docsDir;
 
@@ -138,6 +185,8 @@ export default async function publishDocs(
   } catch (error) {
     message = `❌ Failed to publish docs: ${error.message}`;
   }
+  saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
+
   // clean up tmp work dir
   await fs.rm(docsDir, { recursive: true, force: true });
   return message ? { message } : {};

package/docs/_sidebar.md

@@ -14,4 +14,4 @@
 * [Advanced Topics](/advanced.md)
   * [How It Works](/advanced-how-it-works.md)
   * [Quality Assurance](/advanced-quality-assurance.md)
-* [Changelog](/changelog.md)
+* [Changelog](/changelog.md)

package/docs/advanced-how-it-works.md

@@ -1,16 +1,6 @@
----
-labels: ["Reference"]
----
-
 # How It Works
 
-AIGNE DocSmith provides a sophisticated, automated documentation solution by leveraging a multi-agent system built on the AIGNE Framework. Instead of relying on a single, monolithic AI, DocSmith orchestrates a pipeline of specialized AI agents, each an expert in its specific task. This collaborative approach ensures the generation of structured, detailed, and high-quality documentation directly from your source code.
-
-## Architectural Overview
-
-DocSmith is an integral part of the AIGNE ecosystem, a comprehensive platform for AI application development. It seamlessly integrates with other AIGNE components, utilizing the platform's core AI capabilities and infrastructure.
-
-![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+AIGNE DocSmith automates documentation using a multi-agent system. Instead of a single AI model, DocSmith orchestrates a pipeline of specialized AI agents, where each agent is an expert in a specific task. This collaborative approach generates structured and detailed documentation directly from your source code.
 
 At its core, DocSmith operates as a pipeline, processing your source code through several distinct stages, each managed by one or more dedicated AI agents.
 
@@ -21,72 +11,77 @@ The entire process, from analyzing your code to publishing the final documents,
 ```d2
 direction: down
 
-"Source Code & Config": {
-  shape: step
-  label: "Input: Source Code & Configuration"
-}
-
-"Structure Planning": {
-  shape: step
-  label: "1. Structure Planning"
+Input: {
+  label: "Source Code & Config"
+  shape: rectangle
 }
 
-"Content Generation": {
-  shape: step
-  label: "2. Content Generation"
+Pipeline: {
+  label: "Documentation Generation Pipeline"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 40
+
+  Structure-Planning: {
+    label: "1. Structure Planning\n(reflective-structure-planner)"
+    shape: rectangle
+  }
+
+  Content-Generation: {
+    label: "2. Content Generation\n(content-detail-generator)"
+    shape: rectangle
+  }
+
+  Saving: {
+    label: "3. Save Documents\n(save-docs)"
+    shape: rectangle
+  }
 }
 
-"Saving & Output": {
-  shape: step
-  label: "3. Saving & Output"
+User-Feedback: {
+  label: "User Feedback Loop\n(via --feedback flag)"
+  shape: rectangle
 }
 
-"Optional Processes": {
-  shape: diamond
-  label: "4. Optional Processes"
+Optional-Steps: {
+  label: "Optional Steps"
+  shape: rectangle
+  grid-columns: 2
+  grid-gap: 40
+  
+  Translation: {
+    label: "Translate\n(aigne doc translate)"
+    shape: rectangle
+  }
+
+  Publishing: {
+    label: "Publish\n(aigne doc publish)"
+    shape: rectangle
+  }
 }
 
-"Translation": {
-  shape: step
-  label: "Translation"
-}
-
-"Publishing": {
-  shape: step
-  label: "Publishing"
-}
-
-"Feedback Loop": {
-  shape: callout
-  label: "User Feedback Loop"
-}
-
-"Source Code & Config" -> "Structure Planning"
-"Structure Planning" -> "Content Generation"
-"Content Generation" -> "Saving & Output"
-"Saving & Output" -> "Optional Processes"
-
-"Optional Processes" -> "Translation": "Translate Docs"
-"Optional Processes" -> "Publishing": "Publish Docs"
-
-"Structure Planning" <- "Feedback Loop": "Refine Structure"
-"Content Generation" <- "Feedback Loop": "Regenerate Content"
+Input -> Pipeline.Structure-Planning
+Pipeline.Structure-Planning -> Pipeline.Content-Generation
+Pipeline.Content-Generation -> Pipeline.Saving
+Pipeline.Saving -> Optional-Steps
 
+User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
+User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
 ```
 
 1.  **Input Analysis**: The process begins with agents like `load-sources` and `load-config`, which gather your source code, configuration files (`aigne.yaml`), and any user-defined rules.
 
-2.  **Structure Planning**: The `reflective-structure-planner` agent analyzes the codebase to propose a comprehensive and logical document structure. It considers your specified target audience, rules, and feedback to create an optimal outline.
+2.  **Structure Planning**: The `reflective-structure-planner` agent analyzes the codebase to propose a logical document structure. It considers your specified target audience, rules, and feedback to create an optimal outline.
 
-3.  **Content Generation**: Once the structure is approved, the `content-detail-generator` and `batch-docs-detail-generator` agents take over. They populate each section of the document plan with detailed, high-quality content, ensuring technical accuracy and adherence to the defined style.
+3.  **Content Generation**: Once the structure is defined, the `content-detail-generator` and `batch-docs-detail-generator` agents take over. They populate each section of the document plan with detailed content, ensuring technical accuracy and adherence to the defined style.
 
-4.  **Refinement and Updates**: If you provide feedback using `aigne doc update` or `aigne doc generate --feedback`, the `detail-regenerator` and `feedback-refiner` agents are activated. They intelligently update specific documents or adjust the overall structure based on your input.
+4.  **Refinement and Updates**: If you provide feedback using `aigne doc update` or `aigne doc generate --feedback`, the `detail-regenerator` and `feedback-refiner` agents are activated. They update specific documents or adjust the overall structure based on your input.
 
 5.  **Translation and Publishing**: Finally, optional agents like `translate` and `publish-docs` handle multi-language translation and publishing to Discuss Kit platforms, completing the end-to-end workflow.
 
 ## Key AI Agents
 
-DocSmith's power comes from its team of specialized agents. While many agents work behind the scenes, here are some of the key players in the documentation pipeline:
+DocSmith's functionality comes from its team of specialized agents. While many agents work behind the scenes, here are some of the key players in the documentation pipeline:
 
 | Agent Role | Primary Function | Governing File(s) |
 |---|---|---|
@@ -95,10 +90,10 @@ DocSmith's power comes from its team of specialized agents. While many agents wo
 | **Translation Agent** | Translates generated documentation into multiple target languages. | `translate.yaml`, `batch-translate.yaml` |
 | **Refinement Agent** | Regenerates or modifies content and structure based on user feedback. | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
 | **Publishing Agent** | Manages the process of publishing documents to Discuss Kit instances. | `publish-docs.mjs`, `team-publish-docs.yaml` |
-| **Configuration Loader** | Reads and interprets the project's configuration from `aigne.yaml`. | `load-config.mjs` |
+| **Configuration Loader** | Reads and interprets the project's configuration and source files. | `load-config.mjs`, `load-sources.mjs` |
 
-This modular, agent-based architecture makes DocSmith highly flexible and robust, allowing each step of the process to be optimized independently.
+This modular, agent-based architecture makes DocSmith flexible and robust, allowing each step of the process to be optimized independently.
 
 ---
 
-Now that you understand the mechanics behind DocSmith, learn about the measures in place to guarantee high-quality output in the [Quality Assurance](./advanced-quality-assurance.md) section.
+Now that you understand the mechanics behind DocSmith, learn about the measures in place to guarantee output quality in the [Quality Assurance](./advanced-quality-assurance.md) section.

package/docs/advanced-how-it-works.zh.md

@@ -1,104 +1,99 @@
----
-labels: ["Reference"]
----
-
 # 工作原理
 
-AIGNE DocSmith 基于 AIGNE 框架构建的多 Agent 系统，提供了一套精密的自动化文档解决方案。 DocSmith 并非依赖单一、庞大的 AI，而是通过协调一系列专业的 AI Agent 组成的流水线，每个 Agent 都是其特定任务的专家。 这种协作方式确保了能够直接从您的源代码生成结构化、详细且高质量的文档。
-
-## 架构概述
+AIGNE DocSmith 使用一个多 Agent 系统来自动化文档生成。DocSmith 不使用单个 AI 模型，而是协调一个由专业化 AI Agent 组成的流水线，其中每个 Agent 都是特定任务的专家。这种协作方法可以直接从您的源代码生成结构化且详细的文档。
 
-DocSmith 是 AIGNE 生态系统不可或缺的一部分，AIGNE 是一个用于 AI 应用开发的综合平台。 它与其他 AIGNE 组件无缝集成，利用平台的核心 AI 能力和基础设施。
-
-![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
-
-DocSmith 的核心是一个处理流水线，它将您的源代码经过几个不同阶段的处理，每个阶段都由一个或多个专用的 AI Agent 管理。
+其核心是，DocSmith 作为一个流水线运行，通过几个不同的阶段处理您的源代码，每个阶段都由一个或多个专用的 AI Agent 管理。
 
 ## 文档生成流水线
 
-从分析代码到发布最终文档的整个过程，都遵循一个结构化的流水线。 这确保了过程的一致性，并允许在任何阶段进行有针对性的优化。
+从分析代码到发布最终文档的整个过程，都遵循一个结构化的流水线。这确保了一致性，并允许在任何阶段进行有针对性的优化。
 
 ```d2
 direction: down
 
-"Source Code & Config": {
-  shape: step
-  label: "输入：源代码与配置"
-}
-
-"Structure Planning": {
-  shape: step
-  label: "1. 结构规划"
+Input: {
+  label: "Source Code & Config"
+  shape: rectangle
 }
 
-"Content Generation": {
-  shape: step
-  label: "2. 内容生成"
+Pipeline: {
+  label: "Documentation Generation Pipeline"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 40
+
+  Structure-Planning: {
+    label: "1. Structure Planning\n(reflective-structure-planner)"
+    shape: rectangle
+  }
+
+  Content-Generation: {
+    label: "2. Content Generation\n(content-detail-generator)"
+    shape: rectangle
+  }
+
+  Saving: {
+    label: "3. Save Documents\n(save-docs)"
+    shape: rectangle
+  }
 }
 
-"Saving & Output": {
-  shape: step
-  label: "3. 保存与输出"
+User-Feedback: {
+  label: "User Feedback Loop\n(via --feedback flag)"
+  shape: rectangle
 }
 
-"Optional Processes": {
-  shape: diamond
-  label: "4. 可选流程"
+Optional-Steps: {
+  label: "Optional Steps"
+  shape: rectangle
+  grid-columns: 2
+  grid-gap: 40
+  
+  Translation: {
+    label: "Translate\n(aigne doc translate)"
+    shape: rectangle
+  }
+
+  Publishing: {
+    label: "Publish\n(aigne doc publish)"
+    shape: rectangle
+  }
 }
 
-"Translation": {
-  shape: step
-  label: "翻译"
-}
-
-"Publishing": {
-  shape: step
-  label: "发布"
-}
-
-"Feedback Loop": {
-  shape: callout
-  label: "用户反馈循环"
-}
-
-"Source Code & Config" -> "Structure Planning"
-"Structure Planning" -> "Content Generation"
-"Content Generation" -> "Saving & Output"
-"Saving & Output" -> "Optional Processes"
-
-"Optional Processes" -> "Translation": "翻译文档"
-"Optional Processes" -> "Publishing": "发布文档"
-
-"Structure Planning" <- "Feedback Loop": "优化结构"
-"Content Generation" <- "Feedback Loop": "重新生成内容"
+Input -> Pipeline.Structure-Planning
+Pipeline.Structure-Planning -> Pipeline.Content-Generation
+Pipeline.Content-Generation -> Pipeline.Saving
+Pipeline.Saving -> Optional-Steps
 
+User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
+User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
 ```
 
-1.  **输入分析**：该过程始于 `load-sources` 和 `load-config` 等 Agent，它们负责收集您的源代码、配置文件（`aigne.yaml`）以及任何用户定义的规则。
+1.  **输入分析**：该过程始于 `load-sources` 和 `load-config` 等 Agent，它们会收集您的源代码、配置文件（`aigne.yaml`）以及任何用户定义的规则。
 
-2.  **结构规划**：`reflective-structure-planner` Agent 会分析代码库，以提出一个全面且逻辑清晰的文档结构。它会考虑您指定的目标受众、规则和反馈，以创建最佳大纲。
+2.  **结构规划**：`reflective-structure-planner` Agent 会分析代码库，以提出一个逻辑化的文档结构。它会考虑您指定的目标受众、规则和反馈，以创建一个最佳大纲。
 
-3.  **内容生成**：一旦结构获得批准，`content-detail-generator` 和 `batch-docs-detail-generator` Agent 就会接手。它们会用详细、高质量的内容填充文档计划的每个部分，确保技术准确性并遵循定义的风格。
+3.  **内容生成**：一旦结构确定，`content-detail-generator` 和 `batch-docs-detail-generator` Agent 就会接管。它们会用详细内容填充文档计划的每个部分，确保技术准确性并遵循定义的风格。
 
-4.  **优化与更新**：如果您使用 `aigne doc update` 或 `aigne doc generate --feedback` 提供反馈，`detail-regenerator` 和 `feedback-refiner` Agent 将被激活。它们会根据您的输入智能地更新特定文档或调整整体结构。
+4.  **优化与更新**：如果您使用 `aigne doc update` 或 `aigne doc generate --feedback` 提供反馈，`detail-regenerator` 和 `feedback-refiner` Agent 将被激活。它们会根据您的输入更新特定文档或调整整体结构。
 
 5.  **翻译与发布**：最后，像 `translate` 和 `publish-docs` 这样的可选 Agent 会处理多语言翻译和发布到 Discuss Kit 平台的工作，从而完成端到端的工作流。
 
 ## 关键 AI Agent
 
-DocSmith 的强大之处在于其专业的 Agent 团队。虽然许多 Agent 在幕后工作，但以下是文档生成流水线中的一些关键角色：
+DocSmith 的功能源于其专业化的 Agent 团队。虽然许多 Agent 在幕后工作，但以下是文档生成流水线中的一些关键角色：
 
 | Agent 角色 | 主要功能 | 相关文件 |
 |---|---|---|
-| **结构规划器** | 分析源代码和规则，以生成整体的文档大纲。 | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
-| **内容生成器** | 根据计划为每个文档部分撰写详细内容。 | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
+| **Structure Planner** | 分析源代码和规则，生成整体文档大纲。 | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
+| **Content Generator** | 根据计划为每个独立的文档部分撰写详细内容。 | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
 | **Translation Agent** | 将生成的文档翻译成多种目标语言。 | `translate.yaml`, `batch-translate.yaml` |
 | **Refinement Agent** | 根据用户反馈重新生成或修改内容和结构。 | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
 | **Publishing Agent** | 管理将文档发布到 Discuss Kit 实例的过程。 | `publish-docs.mjs`, `team-publish-docs.yaml` |
-| **配置加载器** | 从 `aigne.yaml` 读取并解释项目的配置。 | `load-config.mjs` |
+| **Configuration Loader** | 读取并解析项目的配置文件和源文件。 | `load-config.mjs`, `load-sources.mjs` |
 
-这种模块化的、基于 Agent 的架构使 DocSmith 变得高度灵活和健壮，允许流程的每一步都可以独立优化。
+这种模块化的、基于 Agent 的架构使得 DocSmith 灵活而强大，允许流程中的每一步都能被独立优化。
 
 ---
 
-现在您已经了解了 DocSmith 背后的工作机制，接下来请在 [质量保证](./advanced-quality-assurance.md) 部分了解为确保高质量输出而采取的措施。
+现在您已经了解了 DocSmith 背后的工作原理，请在 [质量保证](./advanced-quality-assurance.md) 部分了解为保证输出质量而采取的措施。