@aigne/doc-smith 0.9.8-alpha.7 → 0.9.8-alpha.9

package/README.md

@@ -71,28 +71,74 @@ doc-smith-skill/
 
 ### 2. 使用 Skill
 
-在任何项目中打开 Claude Code，输入：
+#### Workspace 模式 (推荐)
+
+DocSmith 现在使用独立 workspace 目录，不会污染源仓库。
+
+**创建并使用 workspace：**
+
+```bash
+# 1. 创建空目录作为 workspace
+mkdir my-docs-workspace
+cd my-docs-workspace
+
+# 2. 打开 Claude Code 并执行 doc-smith
+# 输入: 使用 doc-smith 生成文档
+```
+
+**初始化流程：**
+DocSmith 会引导你完成初始化：
+1. 询问输出语言（如：zh、en）
+2. 询问源仓库 Git URL（可选，如果源代码在本地可不提供）
+3. 自动创建目录结构
+4. 自动添加源仓库为 git submodule（如果提供了 URL）
+5. 生成 config.yaml 配置文件
+6. 初始化 git 仓库并提交
+
+**后续操作：**
+DocSmith 会：
+1. 分析源仓库内容
+2. 推断用户意图
+3. 规划文档结构
+4. 生成结构化的 Markdown 文档
+5. 询问是否提交到 Git
+
+### 3. Workspace 目录结构
 
 ```
-使用 doc-smith skill 为当前仓库生成文档
+my-docs-workspace/              # 独立 workspace 目录
+├── config.yaml                 # workspace 配置文件
+├── sources/                    # 源仓库 (git submodule)
+│   └── my-project/
+├── intent/
+│   └── user-intent.md          # 用户意图描述
+├── planning/
+│   └── document-structure.yaml # 文档结构计划
+├── docs/                       # 生成的文档
+│   ├── overview.md
+│   ├── getting-started.md
+│   └── api/
+│       └── authentication.md
+└── cache/                      # 临时数据 (不纳入 git)
 ```
 
-然后根据提示操作，DocSmith 会：
-1. 分析你的工作区
-2. 规划文档结构
-3. 生成 `document-structure.yaml`
-4. 创建结构化的 Markdown 文档
+### 4. 版本管理
 
-### 3. 查看生成的文档
+Workspace 是一个独立的 Git 仓库，支持完整的版本管理：
 
-所有文档将生成在：
+```bash
+# 查看历史
+git log
 
-```
-.aigne/doc-smith/
-├── output/
-│   └── document-structure.yaml    # 文档结构定义
-└── docs/
-    └── [生成的文档文件]
+# 查看变更
+git diff
+
+# 回滚版本
+git revert <commit-hash>
+
+# 推送到远程仓库（可选）
+git remote add origin <your-repo-url>
+git push -u origin main
 ```
 
 ## 文档说明
@@ -134,8 +180,16 @@ cp -r doc-smith ~/.claude/skills/
 ## 注意事项
 
 - 确保 Claude Code 已正确安装
-- Skill 需要访问工作区文件
-- 生成的文档会创建在 `.aigne/doc-smith/` 目录
+- 确保 Git 已安装（用于 submodule 和版本管理）
+- Workspace 需要在空目录中初始化
+- 生成的文档在独立的 workspace 目录中，不会污染源仓库
+
+## 迁移说明
+
+如果你之前使用过旧版本（`.aigne/doc-smith/` 目录结构），建议：
+1. 创建新的 workspace 目录
+2. 重新生成文档
+3. 旧版本数据可以手动迁移到新的 workspace 目录结构中
 
 ## 支持
 

package/agents/bash-executor/bash-executor.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+/**
+ * 虚拟 Bash 执行器 - Git 专用
+ * 支持的命令类型:
+ * - Git 操作: init, clone, config, status, log, diff, branch, show, add, commit, fetch, pull, submodule
+ *
+ * 安全限制:
+ * - 仅支持 git 命令,不支持其他 shell 命令
+ * - 所有命令必须来自预定义的安全枚举
+ */
+
+// 支持的命令枚举
+const ALLOWED_COMMANDS = {
+  // Git 命令
+  git: {
+    // 初始化和克隆
+    init: true,
+    clone: true,
+
+    // 配置命令
+    config: true,
+
+    // 查询命令
+    status: true,
+    log: true,
+    diff: true,
+    branch: true,
+    show: true,
+
+    // 提交命令
+    add: true,
+    commit: true,
+
+    // 远程命令
+    fetch: true,
+    pull: true,
+
+    // 子模块命令
+    submodule: true,
+  },
+};
+
+/**
+ * 验证命令是否在允许列表中
+ */
+function validateCommand(command, args = []) {
+  const cmd = command.toLowerCase();
+
+  // 只支持 git 命令
+  if (cmd !== "git") {
+    throw new Error(`不支持的命令: ${cmd},仅支持 git 命令`);
+  }
+
+  if (args.length === 0) {
+    throw new Error("Git 命令需要指定子命令");
+  }
+
+  const subCommand = args[0].toLowerCase();
+  if (!ALLOWED_COMMANDS.git[subCommand]) {
+    throw new Error(`不支持的 git 子命令: ${subCommand}`);
+  }
+
+  return true;
+}
+
+/**
+ * 执行单个命令
+ */
+function executeCommand(command, args = []) {
+  try {
+    // 验证命令
+    validateCommand(command, args);
+
+    // 构建完整命令用于显示和日志
+    const fullCommand = [command, ...args].join(" ");
+
+    // 使用 spawnSync 可以同时捕获 stdout 和 stderr
+    const result = spawnSync(command, args, {
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+      timeout: 60000, // 60秒超时
+    });
+
+    // 检查是否执行成功
+    if (result.status === 0 && !result.error) {
+      return {
+        success: true,
+        command: fullCommand,
+        output: result.stdout?.trim() || "",
+        error: result.stderr?.trim() || "", // 即使成功也返回 stderr,可能包含警告信息
+      };
+    }
+
+    // 命令执行失败
+    return {
+      success: false,
+      command: fullCommand,
+      output: result.stdout?.trim() || "",
+      error: result.stderr?.trim() || result.error?.message || "命令执行失败",
+    };
+  } catch (error) {
+    // 验证失败或其他异常
+    const fullCommand = [command, ...args].join(" ");
+    console.log(`[bash-executor] 异常: ${error.message}`);
+    return {
+      success: false,
+      command: fullCommand,
+      output: "",
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * 按顺序执行多个命令
+ * 如果某个命令失败,立即停止执行后续命令
+ */
+function executeBatch(commands) {
+  const results = [];
+
+  for (const item of commands) {
+    const { command, args = [] } = item;
+
+    if (!command) {
+      const errorResult = {
+        success: false,
+        command: "",
+        output: "",
+        error: "命令不能为空",
+      };
+      results.push(errorResult);
+      // 命令为空视为失败,停止执行
+      break;
+    }
+
+    const result = executeCommand(command, args);
+    results.push(result);
+
+    // 如果命令失败,立即停止执行后续命令
+    if (!result.success) {
+      break;
+    }
+  }
+
+  return results;
+}
+
+/**
+ * 安全执行预定义的 Shell 命令
+ * @param {Object} params - 输入参数
+ * @param {Array} params.commands - 命令列表
+ * @returns {Object} - 执行结果
+ */
+export default function executeSafeShellCommands({ commands }) {
+  // 验证输入
+  if (!Array.isArray(commands)) {
+    return {
+      success: false,
+      error: "参数 commands 必须是一个数组",
+      results: [],
+    };
+  }
+
+  if (commands.length === 0) {
+    return {
+      success: false,
+      error: "命令列表不能为空",
+      results: [],
+    };
+  }
+
+  // 执行命令批次
+  const results = executeBatch(commands);
+
+  // 统计执行结果
+  const successCount = results.filter((r) => r.success).length;
+  const failureCount = results.length - successCount;
+
+  return {
+    success: successCount > 0,
+    total: results.length,
+    succeeded: successCount,
+    failed: failureCount,
+    results,
+  };
+}
+
+// 添加描述信息,帮助 LLM 理解何时调用此 agent
+executeSafeShellCommands.description =
+  "安全执行 Git 命令,支持的子命令包括: init/clone/config/status/log/diff/branch/show/add/commit/fetch/pull/submodule。" +
+  "适用于需要批量执行多个有顺序依赖的 git 操作,如果某个命令失败会立即停止执行后续命令。";
+
+// 定义输入 schema
+executeSafeShellCommands.input_schema = {
+  type: "object",
+  required: ["commands"],
+  properties: {
+    commands: {
+      type: "array",
+      description: "要执行的 Git 命令列表,按顺序执行",
+      items: {
+        type: "object",
+        required: ["command"],
+        properties: {
+          command: {
+            type: "string",
+            description: "命令名称,必须是 git",
+            enum: ["git"],
+          },
+          args: {
+            type: "array",
+            description:
+              "Git 子命令和参数列表,第一个参数必须是支持的子命令(init/clone/config/status/log/diff/branch/show/add/commit/fetch/pull/submodule)",
+            items: {
+              type: "string",
+            },
+            minItems: 1,
+          },
+        },
+      },
+      minItems: 1,
+    },
+  },
+};
+
+// 定义输出 schema
+executeSafeShellCommands.output_schema = {
+  type: "object",
+  required: ["success", "results"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "是否至少有一个命令执行成功",
+    },
+    total: {
+      type: "integer",
+      description: "总命令数(执行命令时存在)",
+    },
+    succeeded: {
+      type: "integer",
+      description: "成功执行的命令数(执行命令时存在)",
+    },
+    failed: {
+      type: "integer",
+      description: "失败的命令数(执行命令时存在)",
+    },
+    error: {
+      type: "string",
+      description: "全局错误信息(验证失败时存在)",
+    },
+    results: {
+      type: "array",
+      description: "每个命令的执行结果",
+      items: {
+        type: "object",
+        required: ["success", "command", "output", "error"],
+        properties: {
+          success: {
+            type: "boolean",
+            description: "该命令是否执行成功",
+          },
+          command: {
+            type: "string",
+            description: "执行的完整命令",
+          },
+          output: {
+            type: "string",
+            description: "命令的标准输出",
+          },
+          error: {
+            type: "string",
+            description: "错误信息,成功时为空字符串,失败时包含错误详情",
+          },
+        },
+      },
+    },
+  },
+};

package/agents/preload-i18n.mjs

@@ -0,0 +1,73 @@
+export default async function preloadI18n(_, options) {
+  const content = `
+  ## 系统架构
+
+  <!-- afs:image id="architecture-overview" key="snap-kit-architecture" desc="Snap Kit system architecture showing React frontend, Express API, and Crawler Engine components with their interactions" -->
+
+  Snap Kit 采用清晰的三层架构设计:
+
+  - **前端层**: React 19.1 + TypeScript + Vite,提供现代化的用户界面和实时仪表板
+  - **API 层**: Express 4.21 + TypeScript,提供 RESTful 接口、DID 认证和速率限制
+  - **引擎层**: Puppeteer + 队列系统 + SQLite,负责核心自动化和数据存储
+    `;
+  const resultWriter = await this.afs.write(
+    "/modules/doc-smith/docs/getting-started-image.md",
+    {
+      content,
+    }
+  );
+
+  const image = await this.afs.getImageBySlot(
+    "/modules/doc-smith/docs/getting-started-image.md",
+    "architecture-overview",
+    {
+      view: {
+        format: "jpg",
+      },
+      context: options.context,
+    }
+  );
+
+  const result = await this.afs.read(
+    "/modules/doc-smith/docs/getting-started.md",
+    {
+      view: {
+        language: "en",
+      },
+      context: options.context,
+    }
+  );
+
+  return {
+    i18n: {
+      result,
+      image,
+    },
+  };
+}
+
+preloadI18n.afs = {
+  modules: [
+    {
+      module: "local-fs",
+      options: {
+        name: "doc-smith",
+        localPath: "${CWD}/.aigne/doc-smith",
+        description:
+          "The Doc Smith workspace for storing intermediate and output files",
+      },
+    },
+  ],
+  drivers: [
+    {
+      driver: "i18n",
+      options: {
+        defaultSourceLanguage: "zh",
+      },
+    },
+    {
+      driver: "image-generate",
+      options: {},
+    },
+  ],
+};

package/agents/publish/check-docs.mjs

@@ -0,0 +1,44 @@
+import chalk from "chalk";
+import { getMainLanguageFiles } from "../../utils/docs.mjs";
+
+/**
+ * Check if documents exist in the docs directory
+ * @param {Object} params
+ * @param {string} params.docsDir - Documentation directory
+ * @param {string} params.locale - Main language locale
+ * @param {Array} params.documentStructure - Document structure
+ * @returns {Promise<Object>} - Result object
+ */
+export default async function checkDocs({ docsDir = "./docs" }) {
+  const mainLanguageFiles = await getMainLanguageFiles(docsDir);
+
+  if (mainLanguageFiles.length === 0) {
+    console.log(`⚠️  No documents found in the docs directory.`);
+    console.log(`💡 Please generate documentation first before publishing.`);
+    process.exit(0);
+  }
+
+  return {
+    message: `Found ${mainLanguageFiles.length} document(s) in the docs directory`,
+  };
+}
+
+checkDocs.description = "Check if documents exist before publishing";
+
+checkDocs.input_schema = {
+  type: "object",
+  properties: {
+    docsDir: {
+      type: "string",
+      description: "Documentation directory",
+    },
+    locale: {
+      type: "string",
+      description: "Main language locale",
+    },
+    documentStructure: {
+      type: "array",
+      description: "Document structure",
+    },
+  },
+};

package/agents/publish/index.yaml

@@ -0,0 +1,12 @@
+type: team
+name: publish
+alias:
+  - pub
+  - p
+description: Publish DocSmith generated documentation to the online platform
+skills:
+  - url: ./init-config.mjs
+    default_input:
+      skipIfExists: true
+  - url: ./check-docs.mjs
+  - url: ./publish-docs.mjs

package/agents/publish/init-config.mjs

@@ -0,0 +1,133 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import chalk from "chalk";
+import { loadConfigFromFile, generateConfigYAML } from "../../utils/config.mjs";
+import { getProjectInfo, detectSystemLanguage } from "../../utils/project.mjs";
+
+/**
+ * Initialize configuration for publishing
+ * @param {Object} params
+ * @param {string} params.outputPath - Output path for config file
+ * @param {string} params.fileName - Config file name
+ * @param {boolean} params.skipIfExists - Skip if config file exists
+ * @param {boolean} params.checkOnly - Only check if config exists
+ * @param {string} params.appUrl - Optional app URL
+ * @returns {Promise<Object>} - Configuration object
+ */
+export default async function initConfig(
+  {
+    fileName = "config.yaml",
+    skipIfExists = false,
+    appUrl,
+    checkOnly = false,
+  } = {},
+  options
+) {
+  // Detect workspace mode (new structure with config.yaml in root)
+  const configPath = "./";
+
+  // Check only mode
+  if (checkOnly) {
+    const filePath = join(configPath, fileName);
+    const configContent = await readFile(filePath, "utf8").catch(() => null);
+
+    if (!configContent || configContent.trim() === "") {
+      console.log("⚠️  No configuration file found.");
+      console.log(
+        `🚀 Configuration will be created automatically when you run the publish command.`
+      );
+      process.exit(0);
+    }
+
+    const config = await loadConfigFromFile();
+    return { ...config, appUrl };
+  }
+
+  // Skip if exists mode
+  if (skipIfExists) {
+    const filePath = join(configPath, fileName);
+    const configContent = await readFile(filePath, "utf8").catch(() => null);
+
+    if (configContent && configContent.trim() !== "") {
+      const config = await loadConfigFromFile();
+      return { ...config, appUrl };
+    }
+  }
+
+  // Create new config with default values
+  const input = {};
+
+  // Detect system language
+  input.locale = detectSystemLanguage();
+
+  // Get project info
+  const projectInfo = await getProjectInfo();
+  input.projectName = projectInfo.name.trim();
+  input.projectDesc = projectInfo.description.trim();
+  input.projectLogo = projectInfo.icon;
+
+  input.docsDir = "./docs";
+  input.sourcesPath = ["sources/"];
+  input.translateLanguages = [];
+
+  // Generate YAML content
+  const yamlContent = generateConfigYAML(input);
+
+  // Save file
+  try {
+    const filePath = join(configPath, fileName);
+    const dirPath = dirname(filePath);
+
+    await mkdir(dirPath, { recursive: true });
+    await writeFile(filePath, yamlContent, "utf8");
+
+    console.log(
+      `\n✅ Configuration created successfully: ${chalk.cyan(filePath)}`
+    );
+    console.log(
+      "💡 You can edit this file to customize your publishing settings.\n"
+    );
+
+    if (skipIfExists) {
+      const config = await loadConfigFromFile();
+      return { ...config, appUrl };
+    }
+
+    return {};
+  } catch (error) {
+    console.error(`❌ Failed to create configuration file: ${error.message}`);
+    return {
+      inputGeneratorStatus: false,
+      inputGeneratorError: error.message,
+    };
+  }
+}
+
+initConfig.description = "Initialize configuration for document publishing";
+
+initConfig.input_schema = {
+  type: "object",
+  properties: {
+    outputPath: {
+      type: "string",
+      description: "Output path for config file",
+    },
+    fileName: {
+      type: "string",
+      description: "Config file name",
+    },
+    skipIfExists: {
+      type: "boolean",
+      description: "Skip if config file exists",
+    },
+    checkOnly: {
+      type: "boolean",
+      description: "Only check if config exists",
+    },
+    appUrl: {
+      type: "string",
+      description: "App URL for publishing",
+    },
+  },
+};