@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/agents/clear/ai/intent.md

@@ -0,0 +1,142 @@
+# Clear Agent 功能意图
+
+## 功能概述
+
+清除 Doc-Smith 工作空间中的授权信息和部署配置。
+
+## 功能意图
+
+在使用 Doc-Smith 进行文档发布后，用户可能需要：
+- 切换到不同的发布站点，需要清除已保存的站点授权
+- 重新配置发布目标，需要清除已保存的 appUrl
+- 排查发布问题时，需要清理授权状态重新认证
+
+本 agent 提供统一的清除入口，支持选择性清除 Authorizations（站点授权）和 Deployment Config（部署配置）。
+
+## 工作流程
+
+```
+用户调用 clear agent
+       ↓
+  检查 targets 参数
+       ↓
+  ┌────┴────┐
+  ↓         ↓
+有参数    无参数
+  ↓         ↓
+直接执行  显示 checkbox 选择界面
+  ↓         ↓
+  └────┬────┘
+       ↓
+  遍历选中的目标
+       ↓
+  调用对应的 clear 子 agent
+       ↓
+  汇总结果并输出
+```
+
+## 核心能力
+
+1. **统一清除入口**：通过单一命令访问所有清除功能
+2. **交互式选择**：无参数时显示 checkbox 让用户选择要清除的项目
+3. **参数化调用**：支持 targets 参数直接指定清除目标，跳过交互
+4. **授权多选**：清除授权时支持选择特定站点或一键清除全部
+5. **结果汇总**：执行后汇总所有清除操作的结果
+
+## 输入输出
+
+### 输入
+
+- 可选输入：
+  - `targets`: 字符串数组，指定要清除的目标，可选值：
+    - `authTokens` - 清除站点授权信息
+    - `deploymentConfig` - 清除部署配置（appUrl）
+
+### 输出
+
+- 输出内容：清除操作的执行结果摘要
+- 输出格式：包含每个操作状态的结构化消息
+
+## 约束条件
+
+### 必须遵循的规范
+
+- 清除授权使用 `utils/store` 模块管理
+- 清除配置使用 `PATHS.CONFIG` 路径，保留配置文件其他内容
+- 使用 yaml 库的 parseDocument/delete 方法删除字段，保留注释
+
+### 职责边界
+
+- 必须执行：
+  - 验证清除目标的有效性
+  - 调用对应的 clear 子 agent 执行清除
+  - 汇总并返回执行结果
+
+- 不应执行：
+  - 不清除文档结构、生成的文档等其他内容（当前版本不包含）
+  - 不自动重新初始化或重新认证
+
+- 协作方式：
+  - 入口 agent 负责选择和调度
+  - 各 clear 子 agent 负责具体清除逻辑
+
+## 预期结果
+
+### 成功标准
+
+- 用户选择的所有目标都被正确清除
+- 清除授权后，store 中对应站点的数据被删除
+- 清除部署配置后，config.yaml 中的 appUrl 字段被删除，其他内容保留
+- 返回清晰的执行结果摘要
+
+## 错误处理
+
+### 常见错误
+
+- 配置文件不存在（清除 deploymentConfig 时）
+- 无授权信息可清除（清除 authTokens 时）
+- 无效的 target 值
+
+### 处理策略
+
+- 配置文件不存在：返回提示信息，不视为错误
+- 无授权信息：返回提示信息，不视为错误
+- 无效 target：跳过并在结果中标记为错误
+
+## 实现方式
+
+### 技术选型
+
+- **类型**：team 类型 agent（YAML 入口 + 多个 function agent）
+- **入口文件**：`index.yaml`
+- **子 agent**：
+  - `choose-contents.mjs` - 选择控制逻辑
+  - `clear-auth-tokens.mjs` - 清除授权
+  - `clear-deployment-config.mjs` - 清除部署配置
+
+### 文件结构
+
+```
+agents/clear/
+├── ai/
+│   └── intent.md           # 本文件
+├── index.yaml              # 入口配置
+├── choose-contents.mjs     # 选择和调度逻辑
+├── clear-auth-tokens.mjs   # 清除授权实现
+└── clear-deployment-config.mjs  # 清除部署配置实现
+```
+
+### 依赖模块
+
+- `utils/store/index.mjs` - 授权数据管理（createStore, listMap, deleteItem, clear）
+- `utils/agent-constants.mjs` - 路径常量（PATHS.CONFIG）
+- `yaml` 库 - 配置文件操作（parseDocument, delete, toString）
+
+### 框架 API
+
+- `options.prompts.checkbox` - 多选交互界面
+- `options.context.agents` - 获取注册的子 agent
+- `options.context.invoke` - 调用子 agent
+
+---
+**注意**：本文档描述功能意图，不包含具体实现细节。

package/agents/clear/choose-contents.mjs

@@ -1,33 +1,6 @@
-import {
-  getConfigFilePath,
-  getMediaDescriptionCachePath,
-  getStructurePlanPath,
-  toDisplayPath,
-} from "../../utils/file-utils.mjs";
+import { PATHS } from "../../utils/agent-constants.mjs";
 
 const TARGET_METADATA = {
-  generatedDocs: {
-    label: "Generated Documents",
-    description: ({ docsDir }) =>
-      `Select and delete specific generated documents in './${toDisplayPath(docsDir)}'. The documentation structure will be preserved.`,
-    agent: "clearGeneratedDocs",
-  },
-  documentStructure: {
-    label: "Documentation Structure",
-    description: ({ docsDir, workDir }) =>
-      `Delete all generated documents in './${toDisplayPath(docsDir)}' and the documentation structure in './${toDisplayPath(
-        getStructurePlanPath(workDir),
-      )}'.`,
-    agent: "clearDocumentStructure",
-  },
-  documentConfig: {
-    label: "Document Configuration",
-    description: ({ workDir }) =>
-      `Delete the configuration file in './${toDisplayPath(
-        getConfigFilePath(workDir),
-      )}'. You will need to run \`aigne doc init\` to regenerate it.`,
-    agent: "clearDocumentConfig",
-  },
   authTokens: {
     label: "Authorizations",
     description: () =>
@@ -36,17 +9,9 @@ const TARGET_METADATA = {
   },
   deploymentConfig: {
     label: "Deployment Config",
-    description: ({ workDir }) =>
-      `Delete the appUrl from './${toDisplayPath(getConfigFilePath(workDir))}'.`,
-    agent: "clearDeploymentConfig",
-  },
-  mediaDescription: {
-    label: "Media File Descriptions",
     description: () =>
-      `Delete AI-generated descriptions in './${toDisplayPath(
-        getMediaDescriptionCachePath(),
-      )}'. They will be regenerated on the next run.`,
-    agent: "clearMediaDescription",
+      `Delete the appUrl from config file. You will need to re-configure the publish target.`,
+    agent: "clearDeploymentConfig",
   },
 };
 
@@ -75,7 +40,7 @@ export default async function chooseContents(input = {}, options = {}) {
       const choices = Object.entries(TARGET_METADATA).map(([value, def]) => ({
         name: def.label,
         value,
-        description: def.description({ docsDir: input.docsDir, workDir: input.workDir }),
+        description: def.description(),
       }));
 
       selectedTargets = await options.prompts.checkbox({
@@ -99,7 +64,6 @@ export default async function chooseContents(input = {}, options = {}) {
 
   const results = [];
   let hasError = false;
-  let configCleared = false;
 
   for (const target of selectedTargets) {
     const metadata = TARGET_METADATA[target];
@@ -118,7 +82,10 @@ export default async function chooseContents(input = {}, options = {}) {
         throw new Error(`The clear agent '${metadata.agent}' was not found.`);
       }
 
-      const result = await options.context.invoke(clearAgent, rest);
+      const result = await options.context.invoke(clearAgent, {
+        ...rest,
+        configPath: PATHS.CONFIG,
+      });
 
       if (result.error) {
         hasError = true;
@@ -131,13 +98,7 @@ export default async function chooseContents(input = {}, options = {}) {
         results.push({
           status,
           message: result.message,
-          path: result.path,
-          suggestions: result.suggestions,
         });
-
-        if (target === "documentConfig" && result.cleared) {
-          configCleared = true;
-        }
       }
     } catch (error) {
       hasError = true;
@@ -149,24 +110,11 @@ export default async function chooseContents(input = {}, options = {}) {
   }
 
   const header = hasError
-    ? "🧹 Cleanup finished with some issues.\n"
-    : "🧹 Cleanup completed successfully!\n";
+    ? "Cleanup finished with some issues.\n"
+    : "Cleanup completed successfully!\n";
   const detailLines = results.map((item) => `${item.message}`).join("\n\n");
 
-  const suggestions = [];
-  results.forEach((result) => {
-    if (result.suggestions) {
-      suggestions.push(...result.suggestions);
-    }
-  });
-
-  if (configCleared && !suggestions.some((s) => s.includes("aigne doc init"))) {
-    suggestions.push("Run `aigne doc init` to generate a fresh configuration file.");
-  }
-
-  const message = [header, "", detailLines, suggestions.length ? "" : null, suggestions.join("\n")]
-    .filter(Boolean)
-    .join("\n");
+  const message = [header, "", detailLines].filter(Boolean).join("\n");
 
   return {
     message,
@@ -187,6 +135,6 @@ chooseContents.input_schema = {
   },
 };
 
-chooseContents.taskTitle = "Select and clear project contents";
+chooseContents.taskTitle = "Select and clear workspace contents";
 chooseContents.description =
-  "Select and clear project contents, such as generated documents, configuration, and authorization tokens.";
+  "Select and clear workspace contents, such as authorization tokens and deployment configuration.";

package/agents/clear/clear-auth-tokens.mjs

@@ -6,27 +6,23 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
 
   try {
     const listMap = await store.listMap();
-    // Get all available sites
     const siteHostnames = Object.keys(listMap);
 
     if (siteHostnames.length === 0) {
       return {
-        message: "🔑 No site authorizations found to clear",
+        message: "No site authorizations found to clear.",
+        cleared: false,
       };
     }
 
-    // Display all sites with their URLs for user selection
-    const choices = siteHostnames.map((hostname) => {
-      return {
-        name: `${chalk.cyan(hostname)}`,
-        value: hostname,
-        checked: false, // Allow multiple selection
-      };
-    });
+    const choices = siteHostnames.map((hostname) => ({
+      name: chalk.cyan(hostname),
+      value: hostname,
+      checked: false,
+    }));
 
-    // Add an option to clear all site authorizations
     choices.push({
-      name: chalk.red("🗑️  Clear ALL site authorizations"),
+      name: chalk.red("Clear ALL site authorizations"),
       value: "__ALL__",
       checked: false,
     });
@@ -40,13 +36,13 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
         validate: (answer) => (answer.length > 0 ? true : "Please select at least one site."),
       });
     } else {
-      // If no prompts available, clear all site authorizations
       selectedSites = ["__ALL__"];
     }
 
     if (selectedSites.length === 0) {
       return {
-        message: "🔑 No sites selected for clearing authorization",
+        message: "No sites selected for clearing authorization.",
+        cleared: false,
       };
     }
 
@@ -54,31 +50,31 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
     let clearedCount = 0;
 
     if (selectedSites.includes("__ALL__")) {
-      // Clear all site authorizations
       await store.clear();
-      results.push(`✔ Cleared site authorization for all sites (${siteHostnames.length} sites)`);
+      results.push(`Cleared site authorization for all sites (${siteHostnames.length} sites)`);
       clearedCount = siteHostnames.length;
     } else {
       for (const hostname of selectedSites) {
         await store.deleteItem(hostname);
-        results.push(`✔ Cleared site authorization for ${chalk.cyan(hostname)}`);
+        results.push(`Cleared site authorization for ${chalk.cyan(hostname)}`);
         clearedCount++;
       }
     }
 
-    const header = `🔑 Successfully cleared site authorizations!`;
-    const detailLines = results.map((item) => `  ${item}`).join("\n");
+    const header = "Successfully cleared site authorizations!";
+    const detailLines = results.map((item) => `  - ${item}`).join("\n");
 
-    const message = [header, "", detailLines, ""].filter(Boolean).join("\n");
+    const message = [header, "", detailLines].filter(Boolean).join("\n");
 
     return {
       message,
+      cleared: true,
       clearedCount,
       clearedSites: selectedSites.includes("__ALL__") ? siteHostnames : selectedSites,
     };
   } catch (error) {
     return {
-      message: `⚠️ Failed to clear site authorizations: ${error.message}`,
+      message: `Failed to clear site authorizations: ${error.message}`,
       error: true,
     };
   }

package/agents/clear/clear-deployment-config.mjs

@@ -1,49 +1,58 @@
 import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import yaml from "yaml";
-import { pathExists, toDisplayPath, getConfigFilePath } from "../../utils/file-utils.mjs";
 
 export default async function clearDeploymentConfig(input = {}) {
-  const { workDir } = input;
+  const { configPath } = input;
 
-  const configFilePath = getConfigFilePath(workDir);
-  const displayPath = toDisplayPath(configFilePath);
+  if (!configPath) {
+    return {
+      error: true,
+      message: "Config path is required.",
+    };
+  }
 
   try {
-    // Check if config file exists
-    const exists = await pathExists(configFilePath);
-    if (!exists) {
+    if (!existsSync(configPath)) {
       return {
-        message: `📦 Config file not found (${displayPath}). No need to clear appUrl.`,
+        message: "Config file not found. No need to clear appUrl.",
+        cleared: false,
       };
     }
 
-    // Remove appUrl field while preserving comments
-    const configContent = await readFile(configFilePath, "utf-8");
+    const configContent = await readFile(configPath, "utf-8");
     const doc = yaml.parseDocument(configContent);
 
-    if (doc.has("appUrl")) {
-      doc.delete("appUrl");
-      await writeFile(
-        configFilePath,
-        doc.toString({
-          keepSourceTokens: true,
-          indent: 2,
-          lineWidth: 0,
-          minContentWidth: 0,
-        }),
-        "utf-8",
-      );
+    if (!doc.has("appUrl")) {
+      return {
+        message: "No appUrl found in config file. Nothing to clear.",
+        cleared: false,
+      };
     }
 
+    doc.delete("appUrl");
+    await writeFile(
+      configPath,
+      doc.toString({
+        keepSourceTokens: true,
+        indent: 2,
+        lineWidth: 0,
+        minContentWidth: 0,
+      }),
+      "utf-8",
+    );
+
     return {
-      message: `📦 Cleared appUrl from config file (${displayPath})`,
+      message: "Cleared appUrl from config file.",
+      cleared: true,
     };
   } catch (error) {
     return {
       error: true,
-      message: `⚠️ Failed to clear deployment config: ${error.message}`,
+      message: `Failed to clear deployment config: ${error.message}`,
     };
   }
 }
 
 clearDeploymentConfig.taskTitle = "Clear deployment configuration";
+clearDeploymentConfig.description = "Clear appUrl from the config file";

package/agents/clear/index.yaml

@@ -2,12 +2,8 @@ type: team
 name: clear
 alias:
   - clear
-description: Clear various types of data including documentation structure, generated documents, configuration, and authorization tokens
+description: Clear authorization tokens and deployment configuration from Doc-Smith workspace
 skills:
-  - url: ../init/index.mjs
-    default_input:
-      skipIfExists: true
-      checkOnly: true
   - ./choose-contents.mjs
 input_schema:
   type: object
@@ -18,9 +14,5 @@ input_schema:
       items:
         type: string
         enum:
-          - documentStructure
-          - generatedDocs
-          - documentConfig
           - authTokens
           - deploymentConfig
-          - mediaDescription

package/agents/content-checker/ai/intent.md

@@ -0,0 +1,209 @@
+# Content Checker Agent 功能意图
+
+## 功能概述
+
+文档内容校验和修复工具，用于在文档生成后检查文档内容的完整性、准确性和规范性。
+
+## 功能意图
+
+文档生成过程中可能出现各种问题：文档文件缺失、元数据格式错误、内部链接断裂、图片路径错误、标题层级不规范等。这些问题会影响文档的可用性和用户体验。Content Checker Agent 提供自动化的多层次检查机制，能够发现这些问题并在可能的情况下自动修复，确保生成的文档符合质量标准。
+
+## 工作流程
+
+Content Checker 在文档生成流程的最后阶段执行：
+
+1. **文档生成完成** → Content Checker Agent 被调用
+2. **Layer 0: 无效文档清理** → 删除文件系统中存在但不应该存在的文档
+3. **Layer 1: 结构检查** → 验证文档文件夹、.meta.yaml、语言文件的存在性和格式
+4. **Layer 2-4: 内容检查** → 逐个检查文档内容、链接、图片
+5. **自动修复** → 如果启用且存在可修复错误，尝试自动修复
+6. **返回结果** → 返回检查报告和统计信息
+
+## 核心能力
+
+1. **无效文档清理**：检查前自动删除不应存在的文档文件
+2. **多层次检查**：从文件存在性到内容细节的全面检查
+3. **错误分类**：区分致命错误、可修复错误和警告
+4. **链接验证**：检查内部文档链接的有效性
+5. **图片验证**：验证本地图片存在性和远程图片可访问性
+6. **Sources 绝对路径支持**：解析 `/sources/<name>/...` 虚拟路径到物理路径并验证
+7. **选择性检查**：支持指定特定文档进行检查，或检查所有文档
+8. **自动修复**：支持自动修复可修复的错误（当前版本预留扩展）
+
+## 输入输出
+
+### 输入
+
+- 可选输入：
+  - `docs`: 要检查的文档路径数组，如 `["/overview", "/api/introduction"]`，如果不提供则检查所有文档
+
+- 自动获取：
+  - 从 `PATHS` 常量自动获取文档结构文件路径 (`planning/document-structure.yaml`)
+  - 从 `PATHS` 常量自动获取文档目录路径 (`docs/`)
+  - 从 `config.yaml` 自动获取 `translateLanguages` 配置（目标翻译语言列表）
+  - `autoFix` 默认为 `true`
+  - `checkRemoteImages` 默认为 `true`
+
+### 输出
+
+- 输出内容：检查结果对象
+  - `success`: 检查是否成功执行
+  - `valid`: 文档内容是否有效
+  - `message`: 格式化的检查报告
+  - `errors`: 错误列表（分类为 fatal、fixable、warnings）
+  - `stats`: 统计信息
+  - `fixed`: 是否执行了修复
+  - `fixedCount`: 修复的错误数量
+  - `cleaned`: 清理统计（删除的无效文档文件夹数量、删除的无效语言文件数量）
+
+- 输出格式：结构化对象，包含详细的错误信息和操作建议
+
+## 约束条件
+
+### 必须遵循的规范
+
+1. **无效文档清理规则**：
+   - 扫描 docs/ 目录下的所有文档文件夹
+   - 删除不在 document-structure.yaml 中定义的文档文件夹
+   - 对于每个有效的文档文件夹，读取 `.meta.yaml` 获取有效语言列表
+   - 删除 `.meta.yaml` 中未定义的语言版本文件（如 `claude-code.md` 不在 languages 列表中）
+   - 清理操作在检查前执行，确保后续检查不会被无效文件干扰
+
+2. **文档结构规范**：
+   - 文档文件夹必须包含 `.meta.yaml` 文件
+   - `.meta.yaml` 必须包含 `kind`、`source`、`default` 字段
+   - `kind` 字段必须为 `"doc"`
+   - **`source` 字段必须与项目 `locale` 一致**（所有文档的源语言必须是项目主语言）
+   - 至少存在一个语言版本文件（如 `zh.md`、`en.md`）
+   - `source` 和 `default` 语言文件必须存在
+   - 如果 `config.yaml` 中配置了 `translateLanguages`，则所有目标语言文件都必须存在（排除 source 语言本身）
+
+3. **内容规范**：
+   - 文档内容不能为空（去除标题后至少 50 字符）
+   - 标题层级不能跳级（H1 → H2 → H3，不能 H1 → H3）
+   - 内部链接必须指向存在的文档
+   - 内部链接格式必须正确（详见下方链接格式规范）
+   - 本地图片必须存在于指定路径
+
+4. **内部链接格式规范**：
+   - **正确格式**：
+     - 绝对路径：`/agent-types/ai-agent`
+     - 相对路径：`../ai-agent` 或 `./sub-doc`
+     - 带锚点：`/agent-types/ai-agent#section`
+   - **错误格式（Fatal 错误）**：
+     - 包含 `.md` 后缀的链接都视为格式错误
+     - 示例：`/agent-types/ai-agent/en.md`、`./ai-agent.md`、`../path.md`
+   - **智能建议**：
+     - 语言后缀模式（`/xx.md`）：建议去掉整个 `/xx.md`，如 `/path/en.md` → `/path`
+     - 普通 `.md` 后缀：建议只去掉 `.md`，如 `./doc.md` → `./doc`
+   - **设计原因**：
+     - 内部链接使用文档路径，语言版本由文档系统在运行时根据用户偏好选择
+     - 硬编码 `.md` 后缀会导致发布流程异常
+
+5. **检查规则**：
+   - 跳过代码块中的链接和图片
+   - 忽略外部链接的有效性检查
+   - 远程图片通过 HTTP HEAD 请求检查可访问性（3秒超时）
+
+6. **Sources 绝对路径规则**：
+   - 识别 `/sources/...` 格式的图片路径
+   - 从 config.yaml 加载 sources 配置
+   - 依次在每个配置的 source 中查找图片：
+     - `local-path`: 相对于 workspace 的路径
+     - `git-clone`: workspace/sources/<name>/ 目录
+   - 返回第一个存在的物理路径
+
+### 职责边界
+
+- **必须执行**：
+  - 清理无效文档：删除不在 document-structure.yaml 中的文档文件夹
+  - 清理无效语言文件：删除 `.meta.yaml` 中未定义的语言版本文件
+  - 读取并解析文档结构文件
+  - 验证文档文件和元数据的存在性和格式（所有文档或指定文档）
+  - 检查文档内容中的链接和图片
+  - 提供详细的错误报告和修复建议
+  - 当 `docs` 参数提供时，仅检查指定的文档路径
+
+- **不应执行**：
+  - 不修改 document-structure.yaml 文件内容
+  - 不生成新的文档内容
+  - 不执行文档翻译或内容转换
+  - 当前版本不实现自动修复（预留扩展点）
+
+- **协作方式**：
+  - 依赖 `document-paths.mjs` 工具收集文档路径
+  - 依赖 `sources-path-resolver.mjs` 解析 `/sources/...` 绝对路径
+  - 依赖 `config.mjs` 加载 config.yaml 中的 sources 配置
+  - 使用 `agent-constants.mjs` 中的路径常量
+  - 作为文档生成流程的最后验证步骤
+
+## 预期结果
+
+### 成功标准
+
+1. **检查通过**：
+   - 所有文档文件和文件夹存在
+   - 所有 `.meta.yaml` 格式正确且包含必需字段
+   - 所有必需的语言文件存在（source、default、translateLanguages 中的所有语言）
+   - 所有内部链接有效且格式正确
+   - 所有本地图片存在
+   - 文档内容充实且标题层级规范
+
+2. **错误处理得当**：
+   - 清晰分类错误类型（fatal/fixable/warnings）
+   - 提供具体的错误位置和修复建议
+   - 统计信息准确完整
+
+## 错误处理
+
+### 常见错误
+
+1. **文件不存在**：文档结构文件或文档目录不存在
+2. **文档文件夹缺失**：结构中定义的文档文件夹未生成
+3. **元数据错误**：`.meta.yaml` 缺失、格式错误或缺少必需字段
+4. **Source 与 Locale 不一致**：文档的 `source` 字段与项目 `locale` 不一致（应该修改文档的 source 或重新生成文档）
+5. **语言文件缺失**：没有任何语言版本文件、缺少 default/source 语言、或缺少 translateLanguages 中配置的目标语言
+6. **内容问题**：空文档、标题跳级
+7. **链接问题**：内部链接死链、路径超出根目录、链接格式不正确（包含 `.md` 后缀或语言版本后缀如 `/en.md`）
+8. **图片问题**：本地图片不存在、远程图片无法访问
+9. **Sources 路径问题**：无法解析的 source name、物理路径上图片不存在
+
+### 处理策略
+
+1. **Layer 0 清理（无效文档）**：
+   - 静默删除无效的文档文件夹和语言文件
+   - 在返回结果中报告删除数量
+   - 不视为错误，而是预处理步骤
+
+2. **Layer 1 错误（文件结构）**：
+   - 立即返回，提供明确的错误原因和解决方案
+   - 提示可能的原因（路径错误、文件名错误、未生成）
+
+3. **Layer 2-4 错误（内容问题）**：
+   - 收集所有错误，完整报告
+   - 提供具体的错误位置（文档路径、语言文件、行号）
+   - 给出操作建议
+
+4. **自动修复**：
+   - 当前版本保留扩展点但不实现自动修复
+   - 未来可添加：链接格式修正、图片路径修正、Markdown 格式优化
+
+5. **缓存机制**：
+   - 远程图片检查结果缓存，避免重复请求
+
+
+### 集成方式
+
+- **作为 Function Agent 使用**：
+  - 在 skill 或其他 agent 中通过 `import checkContent from './agents/content-checker/index.mjs'` 调用
+  - 返回结构化的检查结果对象
+  - 支持两种调用方式：
+    - 检查所有文档：`checkContent()`
+    - 检查指定文档：`checkContent({ docs: ["/overview", "/api/introduction"] })`
+
+- **无需 skills-entry 配置**：
+  - 作为内部工具使用，不直接暴露为 skill
+  - 通过其他 skill（如 doc-smith）间接调用
+
+---
+**注意**：本文档描述功能意图，不包含具体实现细节。