@aigne/doc-smith 0.0.2 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.1.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.1.0...v0.1.1) (2025-07-31)
+
+
+### Bug Fixes
+
+* agent add alias ([7e25014](https://github.com/AIGNE-io/aigne-doc-smith/commit/7e250147309849fe0f4cc554077134d2e443d344))
+* docs mcp add doc search ([de96e0e](https://github.com/AIGNE-io/aigne-doc-smith/commit/de96e0e08455831dc6918d5fbc59d38b6a921373))
+* polish code ([8cb0a5c](https://github.com/AIGNE-io/aigne-doc-smith/commit/8cb0a5ce67cf009c672b2fb1aa9b89ef6d965a86))
+
+## [0.1.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.0.2...v0.1.0) (2025-07-31)
+
+
+### Features
+
+* add entry agents for mcp server and cli ([fa85d65](https://github.com/AIGNE-io/aigne-doc-smith/commit/fa85d651e8dc723e2b97150fc2258b115c6c5bb0))
+
+
+### Bug Fixes
+
+* polish command param ([#3](https://github.com/AIGNE-io/aigne-doc-smith/issues/3)) ([003f6b8](https://github.com/AIGNE-io/aigne-doc-smith/commit/003f6b8ae2c9e1af55ba1841458fa8567a0eb2f0))
+* polish docs mcp agent ([8654cd4](https://github.com/AIGNE-io/aigne-doc-smith/commit/8654cd4ea38034f3af0244f56b27acf66ba704e1))
+
 ## 0.0.2 (2025-07-30)
 
 

package/README.md

@@ -64,14 +64,14 @@ npx --no doc-smith run --entry-agent init
 npx --no doc-smith run --entry-agent generator --model gemini:gemini-2.5-flash
 
 # 重新生成单篇
-npx --no doc-smith run --entry-agent regenerator --input-path bitnet-m4XQ-core-concepts-quantization
+npx --no doc-smith run --entry-agent regenerator --input-path bitnet-getting-started
 
 # 结构规划优化
-npx --no doc-smith run --input @./doc-smith/config.yaml --format yaml --entry-agent generator --input-structurePlanFeedback "补充节点的 sourceIds，确保所有节点 sourceIds 都有值" --model gemini:gemini-2.5-pro
+npx --no doc-smith run --entry-agent generator --input-feedback "补充节点的 sourceIds，确保所有节点 sourceIds 都有值" --model gemini:gemini-2.5-pro
 
 
 # 发布文档
-npx --no doc-smith run --input @./doc-smith/config.yaml --format yaml --entry-agent publish
+npx --no doc-smith run --entry-agent publish
 
 
 ```
@@ -83,14 +83,20 @@ npx --no doc-smith run --input @./doc-smith/config.yaml --format yaml --entry-ag
 aigne doc init
 
 # 生成文档
-aigne doc generator
+aigne doc generate
+
+# 优化结构规划
+aigne doc generate --feedback "删除 About 文档"
 
 # 优化单篇文档
-aigne doc regenerator --path bitnet-m4XQ-core-concepts-quantization # 可使用 structure-plan.json 中的 path ，或 Discuss Kit 中访问的 path
+# 可使用 structure-plan.json 中的 path ，或 Discuss Kit 中访问的 path
+aigne doc update --doc-path /faq --feedback "添加更多的 FAQ" 
 
 # 发布文档
 aigne doc publish
 
+# 将文档作为 MCP Server 
+aigne doc serve-mcp
 
 ```
 

package/agents/check-structure-planning-result.yaml

@@ -11,7 +11,7 @@ input_schema:
     originalStructurePlan:
       $ref: ./schema/structure-plan.yaml
       description: 上一轮生成的结构规划，用于对比。如果不存在，则检查默认通过。
-    structurePlanFeedback:
+    feedback:
       type: string
       description: 用户针对上一轮结果提供的反馈。
   required:

package/agents/check-structure-planning.mjs

@@ -9,11 +9,11 @@ import { OpenAIChatModel } from "@aigne/openai";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 export default async function checkStructurePlanning(
-  { originalStructurePlan, structurePlanFeedback, ...rest },
+  { originalStructurePlan, feedback, ...rest },
   options
 ) {
   // If originalStructurePlan exists, return directly
-  if (originalStructurePlan && !structurePlanFeedback) {
+  if (originalStructurePlan && !feedback) {
     return {
       structurePlan: originalStructurePlan,
     };
@@ -39,14 +39,14 @@ export default async function checkStructurePlanning(
   const panningAgent = aigne.agents["reflective-structure-planner"];
 
   const result = await options.context.invoke(panningAgent, {
-    structurePlanFeedback,
+    feedback: feedback || "",
     originalStructurePlan,
     ...rest,
   });
 
   return {
     ...result,
-    structurePlanFeedback,
+    feedback: "", // clear feedback
     originalStructurePlan: originalStructurePlan
       ? originalStructurePlan
       : JSON.parse(JSON.stringify(result.structurePlan || [])),

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

@@ -35,7 +35,7 @@ input_schema:
     glossary:
       type: string
       description: 术语表
-    currentPath:
+    doc-path:
       type: string
       description: 当前路径
     feedback:

package/agents/detail-regenerator.yaml

@@ -1,5 +1,7 @@
 type: team
-name: regenerator
+name: update
+alias:
+  - up
 description: Optimize and regenerate individual document content and translations
 skills:
   - ./load-config.mjs
@@ -43,7 +45,7 @@ input_schema:
     glossary:
       type: string
       description: Glossary of terms for consistent terminology
-    path:
+    doc-path:
       type: string
       description: Document path to regenerate
     feedback:

package/agents/docs-generator.yaml

@@ -1,5 +1,8 @@
 type: team
-name: generator
+name: generate
+alias:
+  - gen
+  - g
 description: Automatically generates comprehensive project documentation
 skills:
   - ./load-config.mjs
@@ -94,7 +97,7 @@ input_schema:
     #   type: string
     #   description: Type of documentation (general, getting-started, reference, faq)
     #   default: general
-    structurePlanFeedback:
+    feedback:
       type: string
       description: Feedback for structure planning adjustments
     # labels:

package/agents/find-item-by-path.mjs

@@ -1,19 +1,19 @@
 export default async function findItemByPath({
-  path,
+  "doc-path": docPath,
   structurePlanResult,
   boardId,
 }) {
   let foundItem = null;
 
   // First try direct path matching
-  foundItem = structurePlanResult.find((item) => item.path === path);
+  foundItem = structurePlanResult.find((item) => item.path === docPath);
 
   // If not found and boardId is provided, try boardId-flattenedPath format matching
   if (!foundItem && boardId) {
     // Check if path starts with boardId followed by a dash
-    if (path.startsWith(`${boardId}-`)) {
+    if (docPath.startsWith(`${boardId}-`)) {
       // Extract the flattened path part after boardId-
-      const flattenedPath = path.substring(boardId.length + 1);
+      const flattenedPath = docPath.substring(boardId.length + 1);
 
       // Find item by comparing flattened paths
       foundItem = structurePlanResult.find((item) => {
@@ -28,7 +28,7 @@ export default async function findItemByPath({
 
   if (!foundItem) {
     throw new Error(
-      `Item with path "${path}" not found in structurePlanResult`
+      `Item with path "${docPath}" not found in structurePlanResult`
     );
   }
 

package/agents/load-sources.mjs

@@ -155,7 +155,8 @@ export default async function loadSources({
   excludePatterns,
   outputDir,
   docsDir,
-  currentPath,
+  "doc-path": docPath,
+  boardId,
   useDefaultPatterns = true,
 } = {}) {
   let files = Array.isArray(sources) ? [...sources] : [];
@@ -250,15 +251,32 @@ export default async function loadSources({
 
   // Get the last output result of the specified path
   let content;
-  if (currentPath) {
-    const flatName = currentPath.replace(/^\//, "").replace(/\//g, "-");
-    const fileFullName = `${flatName}.md`;
-    const filePath = path.join(docsDir, fileFullName);
+  if (docPath) {
+    let fileFullName;
+
+    // First try direct path matching (original format)
+    const flatName = docPath.replace(/^\//, "").replace(/\//g, "-");
+    fileFullName = `${flatName}.md`;
+    let filePath = path.join(docsDir, fileFullName);
+
     try {
       await access(filePath);
       content = await readFile(filePath, "utf8");
     } catch {
-      // The file does not exist, content remains undefined
+      // If not found and boardId is provided, try boardId-flattenedPath format
+      if (boardId && docPath.startsWith(`${boardId}-`)) {
+        // Extract the flattened path part after boardId-
+        const flattenedPath = docPath.substring(boardId.length + 1);
+        fileFullName = `${flattenedPath}.md`;
+        filePath = path.join(docsDir, fileFullName);
+
+        try {
+          await access(filePath);
+          content = await readFile(filePath, "utf8");
+        } catch {
+          // The file does not exist, content remains undefined
+        }
+      }
     }
   }
 
@@ -298,9 +316,13 @@ loadSources.input_schema = {
       description:
         "Whether to use default include/exclude patterns. Defaults to true.",
     },
-    currentPath: {
+    "doc-path": {
+      type: "string",
+      description: "The document path to load content for",
+    },
+    boardId: {
       type: "string",
-      description: "The current path of the document",
+      description: "The board ID for boardId-flattenedPath format matching",
     },
   },
   required: [],

package/agents/structure-planning.yaml

@@ -23,7 +23,7 @@ input_schema:
     glossary:
       type: string
       description: 术语表
-    structurePlanFeedback:
+    feedback:
       type: string
       description: 结构规划的反馈
     docsType:

package/agents/team-publish-docs.yaml

@@ -1,5 +1,8 @@
 type: team
 name: publish
+alias:
+  - pub
+  - p
 description: Publish the documentation to Discuss Kit
 skills:
   - load-config.mjs

package/aigne.yaml

@@ -29,3 +29,20 @@ agents:
   - ./agents/load-config.mjs
   - ./agents/team-publish-docs.yaml
   - ./agents/find-item-by-path.mjs
+  - ./docs-mcp/get-docs-structure.mjs
+  - ./docs-mcp/get-docs-detail.mjs
+  - ./docs-mcp/docs-search.yaml
+  - ./docs-mcp/analyze-docs-relevance.yaml
+  - ./docs-mcp/read-doc-content.mjs
+  - ./docs-mcp/analyze-content-relevance.yaml
+cli:
+  agents:
+    - ./agents/input-generator.mjs
+    - ./agents/docs-generator.yaml
+    - ./agents/detail-regenerator.yaml
+    - ./agents/team-publish-docs.yaml
+mcp_server:
+  agents:
+    - ./docs-mcp/get-docs-structure.mjs
+    - ./docs-mcp/get-docs-detail.mjs
+    - ./docs-mcp/docs-search.yaml

package/docs-mcp/analyze-content-relevance.yaml

@@ -0,0 +1,50 @@
+name: analyze-content-relevance
+description: Analyze document content relevance to user query and extract relevant information
+instructions: |
+  You are an AI assistant that analyzes the relevance between user queries and document content.
+
+  <user-query>
+  {{ query }}
+  </user-query>
+
+  <document-content>
+  {{ allDocumentsText }}
+  </document-content>
+
+  Given a user query and multiple document contents, your task is to:
+  1. Understand the user's specific information needs from the query
+  2. Analyze document content for relevance to the query
+  3. Extract and synthesize the most relevant information from the documents
+  4. Provide a comprehensive answer that directly addresses the user's query
+  5. Answer user questions based on the given document content, do not return false or non-existent information
+
+  Guidelines:
+  - Focus on information that directly answers the user's question
+  - Extract specific facts, examples, and explanations from the documents
+  - Organize the information logically and coherently
+  - Include relevant code examples, configuration details, or step-by-step instructions when available
+  - Cite the source documents when referencing specific information
+  - If multiple documents contain related information, synthesize them into a unified response
+  - If no relevant information is found, clearly state this
+
+  Format your response as a comprehensive answer that:
+  - Directly addresses the user's query
+  - Includes relevant excerpts from the documents
+  - Provides context and explanations where needed
+  - Is well-structured and easy to understand
+includeInputInOutput: false
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: User search query
+    allDocumentsText:
+      type: string
+      description: Combined text content of all successfully read documents
+output_schema:
+  type: object
+  properties:
+    relevantContent:
+      type: string
+      description: Comprehensive answer synthesizing relevant information from documents

package/docs-mcp/analyze-docs-relevance.yaml

@@ -0,0 +1,59 @@
+name: analyze-docs-relevance
+description: Analyze which documents in the structure plan are relevant to the user query
+instructions: |
+  You are an AI assistant that analyzes the relevance between a user query and documents in a structure plan.
+
+  <structure-plan>
+  {{ originalStructurePlan }}
+  </structure-plan>
+
+  <user-query>
+  {{ query }}
+  </user-query>
+
+  Given a user query and a structure plan containing multiple documents, your task is to:
+  1. Understand the user's search intent from the query
+  2. Analyze each document in the structure plan to determine relevance
+  3. Return a list of relevant documents with their paths, titles, and descriptions
+
+  Consider the following factors for relevance:
+  - Semantic similarity between query and document title/description
+  - Topic alignment
+  - User intent matching
+  - Content scope overlap
+
+  Return only the most relevant documents (top 5-10) to avoid overwhelming results.
+
+  Format your response as a JSON object with:
+  - relevantDocs: array of relevant document paths
+  - reasoning: brief explanation of why these documents were selected
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: User search query
+    originalStructurePlan:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+          title:
+            type: string
+          description:
+            type: string
+      description: Structure plan containing all available documents
+output_schema:
+  type: object
+  properties:
+    relevantDocPaths:
+      type: array
+      items:
+        type: string
+        description: Must be selected from paths in the structure plan, cannot be other paths
+      description: List of relevant documents
+    reasoning:
+      type: string
+      description: Brief explanation of document selection

package/docs-mcp/docs-search.yaml

@@ -0,0 +1,40 @@
+type: team
+name: docs-search
+description: Search relevant documents based on user query
+skills:
+  - ../agents/load-config.mjs
+  - ../agents/load-sources.mjs
+  - analyze-docs-relevance.yaml
+  - read-doc-content.mjs
+  - analyze-content-relevance.yaml
+includeInputInOutput: false
+input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: User search query
+      required: true
+    config:
+      type: string
+      description: Path to the config file
+      default: ./doc-smith/config.yaml
+output_schema:
+  type: object
+  properties:
+    relevantContent:
+      type: string
+      description: AI analyzed relevant content from documents
+    relevantDocs:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+          title:
+            type: string
+          description:
+            type: string
+      description: List of relevant documents from structure plan
+mode: sequential

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

@@ -1,8 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-const docsDir =
-  "/Users/lban/arcblock/code/arcblock-sdk-docs/packages/aigne-framework/docs/";
+const docsDir = path.join(process.cwd(), "doc-smith", "docs");
 
 export default async function getDocDetail({ path: docPath }) {
   try {
@@ -39,4 +38,4 @@ getDocDetail.input_schema = {
   },
 };
 
-getDocDetail.description = "Get AIGNE Framework single docs detail";
+getDocDetail.description = "Get single docs detail";

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

@@ -1,11 +1,16 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 
-const structureDir =
-  "/Users/lban/arcblock/code/arcblock-sdk-docs/packages/aigne-framework/output/structure-plan.json";
+const structureDir = path.join(
+  process.cwd(),
+  "doc-smith",
+  "output",
+  "structure-plan.json"
+);
 
 export default async function getDocsStructure() {
   const structure = await fs.readFile(structureDir, "utf-8");
   return { structure };
 }
 
-getDocsStructure.description = "Get AIGNE Framework docs structure";
+getDocsStructure.description = "Get docs structure";

package/docs-mcp/read-doc-content.mjs

@@ -0,0 +1,93 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const docsDir = path.join(process.cwd(), "doc-smith", "docs");
+
+export default async function readDocContent({
+  relevantDocPaths,
+  docsDir: customDocsDir,
+}) {
+  const targetDocsDir = customDocsDir || docsDir;
+  const docContents = [];
+
+  for (const docPath of relevantDocPaths) {
+    try {
+      // Flatten path: remove leading /, replace all / with - (same logic as utils.mjs)
+      const flatName = docPath.replace(/^\//, "").replace(/\//g, "-");
+      const fileFullName = `${flatName}.md`;
+      const filePath = path.join(targetDocsDir, fileFullName);
+
+      // Read the markdown file
+      const content = await fs.readFile(filePath, "utf8");
+
+      docContents.push({
+        success: true,
+        path: docPath,
+        content,
+        filePath,
+      });
+    } catch (error) {
+      docContents.push({
+        success: false,
+        path: docPath,
+        error: error.message,
+      });
+    }
+  }
+
+  // Combine all successful document contents into a single text
+  const allDocumentsText = docContents
+    .filter((doc) => doc.success)
+    .map((doc) => doc.content)
+    .join("\n\n---\n\n");
+
+  return {
+    docContents,
+    allDocumentsText,
+    totalDocs: relevantDocPaths.length,
+    successfulReads: docContents.filter((doc) => doc.success).length,
+  };
+}
+
+readDocContent.input_schema = {
+  type: "object",
+  properties: {
+    relevantDocPaths: {
+      type: "array",
+      items: { type: "string" },
+      description: "List of document paths to read",
+    },
+    docsDir: {
+      type: "string",
+      description: "Custom docs directory path (optional)",
+    },
+  },
+  required: ["relevantDocPaths"],
+};
+
+readDocContent.output_schema = {
+  type: "object",
+  properties: {
+    docContents: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          success: { type: "boolean" },
+          path: { type: "string" },
+          content: { type: "string" },
+          filePath: { type: "string" },
+          error: { type: "string" },
+        },
+      },
+    },
+    allDocumentsText: {
+      type: "string",
+      description: "Combined text content of all successfully read documents",
+    },
+    totalDocs: { type: "number" },
+    successfulReads: { type: "number" },
+  },
+};
+
+readDocContent.description = "Read markdown content for multiple documents";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,12 +12,12 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/anthropic": "^0.10.2",
-    "@aigne/cli": "^1.27.0",
-    "@aigne/core": "^1.39.0",
-    "@aigne/gemini": "^0.8.6",
-    "@aigne/openai": "^0.10.6",
-    "@aigne/publish-docs": "^0.5.0",
+    "@aigne/anthropic": "^0.10.4",
+    "@aigne/cli": "^1.29.0",
+    "@aigne/core": "^1.41.0",
+    "@aigne/gemini": "^0.8.8",
+    "@aigne/openai": "^0.10.8",
+    "@aigne/publish-docs": "^0.5.1",
     "glob": "^11.0.3",
     "open": "^10.2.0",
     "ufo": "^1.6.1",

package/prompts/check-structure-planning-result.md

@@ -13,16 +13,18 @@
 {{ structurePlan }}
 ```
 
-- **用户反馈 (structurePlanFeedback)**:
+- **用户反馈**:
 ```
-{{ structurePlanFeedback }}
+{{ feedback }}
+
+根据最新的 Data Sources 按需要更新节点的 sourceIds ,更新至状态。
 ```
 </context>
 
 <goal>
 你的主要目标是验证两条关键规则：
 1.  **反馈的实现**：新的结构规划**必须**正确地实现用户反馈中要求的所有变更。
-2.  **无关节点的稳定性**：没有在用户反馈中被提及的节点**绝不能**被修改，特别是它们的 `path` 属性。`path` 是关联现有内容的关键标识符，其稳定性至关重要。
+2.  **无关节点的稳定性**：没有在用户反馈中被提及的节点 ** path 属性不能被修改 **。`path` 是关联现有内容的关键标识符，其稳定性至关重要。
 3.  **数据有效性**: 所有 {{ nodeName }} 都有关联数据源，sourceIds 中都有值。
 </goal>
 
@@ -35,12 +37,12 @@
 这是主要场景。你必须执行详细的比较。
 
 **分步分析**：
-1.  **分析反馈**：仔细阅读并理解 `<context>` 中 `structurePlanFeedback` 提供的每一项变更要求。明确哪些节点是需要被修改、添加或删除的目标。
+1.  **分析反馈**：仔细阅读并理解 `<context>` 中 用户反馈 提出的每一项变更要求。明确哪些节点是需要被修改、添加或删除的目标。
 2.  **验证反馈的实现**：对比 `<context>` 中的 `structurePlan` 和 `originalStructurePlan`，确认所要求的变更是否已执行。例如，如果反馈是“移除‘示例’部分”，你必须检查该部分在 `structurePlan` 中是否已不存在。
 3.  **验证无关节点的稳定性**：这是最关键的检查。遍历 `structurePlan` 中的所有节点。对于每一个在 `originalStructurePlan` 中也存在、但并未在反馈中被提及的节点：
     *   **至关重要**：其 `path` 属性**必须**与 `originalStructurePlan` 中的完全相同。
     *   理想情况下，其他属性（如 `title`）也应保持稳定，除非这些变更是由某个被要求的变更直接导致的。
-    *   **`sourcesIds` 的变更是允许的**，可以根据最新的 DataSources 变更依赖的数据源
+4. **`sourcesIds` 是允许变更的**，每次结构规划可以根据最新的 DataSources 变更依赖的数据源，sourceIds 不能为空。
 </rules>
 
 <output>

package/prompts/structure-planning.md

@@ -28,7 +28,9 @@
 </last_structure_plan>
 
 <structure_plan_feedback>
-{{structurePlanFeedback}}
+{{ feedback }}
+
+根据最新的 Data Sources 按需要更新节点的 sourceIds ,更新至状态。
 </structure_plan_feedback>
 
 <review_structure_plan>

package/docs-mcp/aigne.yaml

@@ -1,8 +0,0 @@
-chat_model:
-  provider: gemini
-  name: gemini-2.5-pro-preview-05-06
-  # name: gemini-2.5-flash-preview-05-20
-  temperature: 0.8
-agents:
-  - get-docs-structure.mjs
-  - get-docs-detail.mjs