@aigne/doc-smith 0.9.8-alpha.15 → 0.9.8-alpha.16

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

@@ -40,6 +40,7 @@ Content Checker 在文档生成流程的最后阶段执行：
 - 自动获取：
   - 从 `PATHS` 常量自动获取文档结构文件路径 (`planning/document-structure.yaml`)
   - 从 `PATHS` 常量自动获取文档目录路径 (`docs/`)
+  - 从 `config.yaml` 自动获取 `translateLanguages` 配置（目标翻译语言列表）
   - `autoFix` 默认为 `true`
   - `checkRemoteImages` 默认为 `true`
 
@@ -72,20 +73,39 @@ Content Checker 在文档生成流程的最后阶段执行：
    - 文档文件夹必须包含 `.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. **检查规则**：
+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秒超时）
 
-5. **Sources 绝对路径规则**：
+6. **Sources 绝对路径规则**：
    - 识别 `/sources/...` 格式的图片路径
    - 从 config.yaml 加载 sources 配置
    - 依次在每个配置的 source 中查找图片：
@@ -124,7 +144,8 @@ Content Checker 在文档生成流程的最后阶段执行：
 1. **检查通过**：
    - 所有文档文件和文件夹存在
    - 所有 `.meta.yaml` 格式正确且包含必需字段
-   - 所有内部链接有效
+   - 所有必需的语言文件存在（source、default、translateLanguages 中的所有语言）
+   - 所有内部链接有效且格式正确
    - 所有本地图片存在
    - 文档内容充实且标题层级规范
 
@@ -140,11 +161,12 @@ Content Checker 在文档生成流程的最后阶段执行：
 1. **文件不存在**：文档结构文件或文档目录不存在
 2. **文档文件夹缺失**：结构中定义的文档文件夹未生成
 3. **元数据错误**：`.meta.yaml` 缺失、格式错误或缺少必需字段
-4. **语言文件缺失**：没有任何语言版本文件或缺少 default/source 语言
-5. **内容问题**：空文档、标题跳级
-6. **链接问题**：内部链接死链、路径超出根目录
-7. **图片问题**：本地图片不存在、远程图片无法访问
-8. **Sources 路径问题**：无法解析的 source name、物理路径上图片不存在
+4. **Source 与 Locale 不一致**：文档的 `source` 字段与项目 `locale` 不一致（应该修改文档的 source 或重新生成文档）
+5. **语言文件缺失**：没有任何语言版本文件、缺少 default/source 语言、或缺少 translateLanguages 中配置的目标语言
+6. **内容问题**：空文档、标题跳级
+7. **链接问题**：内部链接死链、路径超出根目录、链接格式不正确（包含 `.md` 后缀或语言版本后缀如 `/en.md`）
+8. **图片问题**：本地图片不存在、远程图片无法访问
+9. **Sources 路径问题**：无法解析的 source name、物理路径上图片不存在
 
 ### 处理策略
 

package/agents/content-checker/validate-content.mjs

@@ -3,7 +3,7 @@ import { constants } from "node:fs";
 import { parse as yamlParse } from "yaml";
 import path from "node:path";
 import { collectDocumentPaths } from "../../utils/document-paths.mjs";
-import { PATHS } from "../../utils/agent-constants.mjs";
+import { PATHS, ERROR_CODES } from "../../utils/agent-constants.mjs";
 import { isSourcesAbsolutePath, resolveSourcesPath } from "../../utils/sources-path-resolver.mjs";
 import { loadConfigFromFile } from "../../utils/config.mjs";
 
@@ -34,18 +34,33 @@ class DocumentContentValidator {
     this.documents = [];
     this.documentPaths = new Set();
     this.remoteImageCache = new Map();
-    this.sourcesConfig = null; // 缓存 sources 配置
+    this.workspaceConfig = null; // 缓存 workspace 配置
+  }
+
+  /**
+   * 加载 workspace 配置（懒加载）
+   */
+  async loadWorkspaceConfig() {
+    if (this.workspaceConfig === null) {
+      this.workspaceConfig = (await loadConfigFromFile()) || {};
+    }
+    return this.workspaceConfig;
   }
 
   /**
    * 加载 sources 配置（懒加载）
    */
   async loadSourcesConfig() {
-    if (this.sourcesConfig === null) {
-      const config = await loadConfigFromFile();
-      this.sourcesConfig = config?.sources || [];
-    }
-    return this.sourcesConfig;
+    const config = await this.loadWorkspaceConfig();
+    return config.sources || [];
+  }
+
+  /**
+   * 加载 translateLanguages 配置（懒加载）
+   */
+  async loadTranslateLanguages() {
+    const config = await this.loadWorkspaceConfig();
+    return config.translateLanguages || [];
   }
 
   /**
@@ -204,6 +219,22 @@ class DocumentContentValidator {
           suggestion: "修改为 kind: doc",
         });
       }
+
+      // source 与项目 locale 一致性校验
+      if (meta.source) {
+        const config = await this.loadWorkspaceConfig();
+        const projectLocale = config?.locale;
+        if (projectLocale && meta.source !== projectLocale) {
+          this.errors.fatal.push({
+            type: ERROR_CODES.SOURCE_LOCALE_MISMATCH,
+            path: doc.path,
+            source: meta.source,
+            locale: projectLocale,
+            message: `文档 source (${meta.source}) 与项目 locale (${projectLocale}) 不一致: ${doc.path}`,
+            suggestion: `修改文档的 source 为 "${projectLocale}"，或重新生成该文档的主语言版本`,
+          });
+        }
+      }
     } catch (error) {
       this.errors.fatal.push({
         type: "INVALID_META",
@@ -265,6 +296,26 @@ class DocumentContentValidator {
             });
           }
         }
+
+        // 检查 translateLanguages 中配置的目标语言文件是否存在
+        const translateLanguages = await this.loadTranslateLanguages();
+        if (translateLanguages.length > 0) {
+          for (const lang of translateLanguages) {
+            // 跳过源语言（源语言不需要作为翻译目标）
+            if (lang === meta.source) continue;
+
+            const langFile = `${lang}.md`;
+            if (!langFiles.includes(langFile)) {
+              this.errors.fatal.push({
+                type: ERROR_CODES.MISSING_TRANSLATE_LANGUAGE,
+                path: doc.path,
+                lang,
+                message: `翻译语言文件缺失: ${langFile}`,
+                suggestion: `请翻译文档到 ${lang} 语言，或从 config.yaml 的 translateLanguages 中移除 ${lang}`,
+              });
+            }
+          }
+        }
       } catch (_error) {
         // .meta.yaml 错误已在 validateMetaFile 中报告
       }
@@ -530,11 +581,36 @@ class DocumentContentValidator {
   async validateInternalLink(linkUrl, doc, linkText, langFile) {
     let targetPath;
 
-    // 链接预处理：移除锚点、语言文件名和 .md 后缀
-    const cleanLinkUrl = linkUrl
-      .split("#")[0] // 移除锚点
-      .replace(/\/[a-z]{2}(-[A-Z]{2})?\.md$/, "") // 移除 /zh.md 等
-      .replace(/\.md$/, ""); // 移除 .md
+    // 移除锚点部分用于格式检查
+    const urlWithoutAnchor = linkUrl.split("#")[0];
+
+    // 检查链接格式是否正确：内部链接不应包含 .md 后缀
+    const langSuffixPattern = /\/[a-z]{2}(-[A-Z]{2})?\.md$/; // 匹配 /en.md, /zh.md, /en-US.md
+    const mdSuffixPattern = /\.md$/;
+
+    if (mdSuffixPattern.test(urlWithoutAnchor)) {
+      // 链接包含 .md 后缀，这是格式错误
+      // 如果是语言后缀模式，去掉整个 /xx.md 部分；否则只去掉 .md
+      const isLangSuffix = langSuffixPattern.test(urlWithoutAnchor);
+      const suggestedLink = isLangSuffix
+        ? urlWithoutAnchor.replace(langSuffixPattern, "")
+        : urlWithoutAnchor.replace(mdSuffixPattern, "");
+
+      this.stats.brokenLinks++;
+      this.errors.fatal.push({
+        type: ERROR_CODES.INVALID_LINK_FORMAT,
+        path: doc.path,
+        langFile,
+        link: linkUrl,
+        linkText,
+        message: `内部链接格式错误: [${linkText}](${linkUrl})`,
+        suggestion: `链接不应包含 .md 后缀，建议改为: ${suggestedLink}`,
+      });
+      return;
+    }
+
+    // 链接格式正确，继续验证目标是否存在
+    const cleanLinkUrl = urlWithoutAnchor;
 
     // 如果链接只是锚点（如 #section），cleanLinkUrl 会是空字符串，跳过检查
     if (!cleanLinkUrl) {
@@ -632,8 +708,8 @@ class DocumentContentValidator {
 
     // 检查是否为 /sources/... 绝对路径
     if (isSourcesAbsolutePath(imageUrl)) {
-      await this.loadSourcesConfig();
-      const resolved = await resolveSourcesPath(imageUrl, this.sourcesConfig, PATHS.WORKSPACE_BASE);
+      const sourcesConfig = await this.loadSourcesConfig();
+      const resolved = await resolveSourcesPath(imageUrl, sourcesConfig, PATHS.WORKSPACE_BASE);
 
       if (!resolved) {
         this.stats.missingImages++;

package/agents/publish/publish-docs.mjs

@@ -15,7 +15,7 @@ import { PATHS } from "../../utils/agent-constants.mjs";
 import { deploy } from "../../utils/deploy.mjs";
 import { loadConfigFromFile, saveValueToConfig } from "../../utils/config.mjs";
 import { ensureTmpDir } from "../../utils/files.mjs";
-import { getGithubRepoUrl } from "../../utils/git.mjs";
+import { getGithubRepoUrl, isValidGithubUrl } from "../../utils/git.mjs";
 import updateBranding from "../../utils/branding.mjs";
 import { generateSidebar, loadDocumentStructure } from "../../utils/docs.mjs";
 import { copyDocumentsToTemp } from "../../utils/docs-converter.mjs";
@@ -245,9 +245,18 @@ export default async function publishDocs(
     }
 
     // Construct boardMeta object
+    // In standalone mode, get GitHub URL from git-clone type source in sources array
+    // In project mode, use current git repo URL (even if git-clone sources exist as supplements)
+    let githubRepoUrl = getGithubRepoUrl();
+    if (config?.mode === "standalone") {
+      const gitCloneSource = config?.sources?.find((s) => s.type === "git-clone");
+      const configUrl = gitCloneSource?.url;
+      // Only use config URL if it's a valid GitHub URL
+      githubRepoUrl = isValidGithubUrl(configUrl) ? configUrl : "";
+    }
     const boardMeta = {
       category: config?.documentPurpose || [],
-      githubRepoUrl: getGithubRepoUrl(),
+      githubRepoUrl,
       commitSha: config?.lastGitHead || "",
       languages: [
         ...(config?.locale ? [config.locale] : []),

package/agents/save-document/index.mjs

@@ -1,4 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { stringify as yamlStringify } from "yaml";
 import path from "node:path";
 import {
@@ -7,6 +8,7 @@ import {
   isValidDocumentPath,
 } from "../../utils/document-paths.mjs";
 import { PATHS, ERROR_CODES, FILE_TYPES, DOC_META_DEFAULTS } from "../../utils/agent-constants.mjs";
+import { loadLocale } from "../../utils/config.mjs";
 
 /**
  * 创建文档文件夹和文件
@@ -124,10 +126,38 @@ export default async function saveDocument({ path: rawPath, content, options = {
       };
     }
 
-    // 7. 创建文件夹和文件
+    // 7. 检查新建文档时 language 必须等于项目 locale
+    const docFolder = path.join(PATHS.DOCS_DIR, filePath);
+    const metaPath = path.join(docFolder, FILE_TYPES.META);
+    const isNewDocument = !existsSync(metaPath);
+
+    if (isNewDocument) {
+      let projectLocale;
+      try {
+        projectLocale = await loadLocale();
+      } catch (_error) {
+        return {
+          success: false,
+          error: ERROR_CODES.MISSING_CONFIG_FILE,
+          message: "无法读取项目配置文件",
+          suggestion: "请确保 config.yaml 存在且包含 locale 字段",
+        };
+      }
+
+      if (language !== projectLocale) {
+        return {
+          success: false,
+          error: ERROR_CODES.INVALID_LANGUAGE,
+          message: `新建文档时必须使用项目主语言: ${projectLocale}，当前传入: ${language}`,
+          suggestion: `请将 language 参数改为 "${projectLocale}"（项目 locale），首先生成主语言版本`,
+        };
+      }
+    }
+
+    // 8. 创建文件夹和文件
     const files = await createDocumentFiles(filePath, language, content);
 
-    // 8. 返回成功响应
+    // 9. 返回成功响应
     return {
       success: true,
       path: displayPath,
@@ -154,7 +184,7 @@ saveDocument.description =
   `保存文档到 ${PATHS.DOCS_DIR} 目录，自动创建文件夹结构、元信息文件和语言版本文件。` +
   "【重要限制】此工具仅用于新增文档时调用。编辑已有文档时，请直接使用 Edit 工具修改对应的语言文件。" +
   `使用前必须确保 ${PATHS.DOCUMENT_STRUCTURE} 已存在且包含目标文档路径。` +
-  `language 参数必须从 ${PATHS.CONFIG} 的 locale 字段读取并传入。`;
+  `【强制要求】新建文档时 language 必须等于项目 locale（config.yaml 中的 locale 字段），系统会自动验证。`;
 
 // 定义输入 schema
 saveDocument.input_schema = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.8-alpha.15",
+  "version": "0.9.8-alpha.16",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/skills/doc-smith/references/document-content-guide.md

@@ -37,6 +37,7 @@
 
 在每个文档中添加导航链接，引导用户在文档之间流畅跳转。
 只能链接生成的其他文档，不能链接到工作目录中的 markdown 文件，文档发布后会导致无法访问。
+导航链接应该使用文档结构中文档的 `path`
 
 ### 文档开头导航
 

package/skills/doc-smith-docs-detail/SKILL.md

@@ -104,7 +104,7 @@ find . -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.g
   - 文档开头：前置条件（prerequisites）、父主题（parent topic）
   - 文档结尾：相关主题（related topics）、下一步（next steps）、子文档（child documents）
   - 只能链接生成的其他文档，不能链接到工作目录中的 markdown 文件，文档发布后会导致无法访问。
-  - 导航链接可直接使用文件结构中文档的 `path`
+  - 导航链接应该使用文档结构中文档的 `path`
 
 #### 主体内容
 - **结构化章节**：逻辑清晰的信息层次

package/utils/agent-constants.mjs

@@ -70,6 +70,11 @@ export const ERROR_CODES = {
   MISSING_LANGS: "MISSING_LANGS",
   MISSING_SOURCE_FILE: "MISSING_SOURCE_FILE",
 
+  // 内容校验相关
+  SOURCE_LOCALE_MISMATCH: "SOURCE_LOCALE_MISMATCH",
+  MISSING_TRANSLATE_LANGUAGE: "MISSING_TRANSLATE_LANGUAGE",
+  INVALID_LINK_FORMAT: "INVALID_LINK_FORMAT",
+
   // 其他
   SAVE_ERROR: "SAVE_ERROR",
   UNEXPECTED_ERROR: "UNEXPECTED_ERROR",

package/utils/git.mjs

@@ -1,5 +1,16 @@
 import { execSync } from "node:child_process";
 
+/**
+ * Validate if a URL is a valid GitHub repository URL
+ * @param {string} url - The URL to validate
+ * @returns {boolean} - True if valid GitHub URL
+ */
+export function isValidGithubUrl(url) {
+  if (!url || typeof url !== "string") return false;
+  // Match both HTTPS and SSH GitHub URLs
+  return /^(https:\/\/github\.com\/|git@github\.com:)[^/]+\/[^/]+/.test(url);
+}
+
 /**
  * Get GitHub repository URL
  * @returns {string} - GitHub repository URL or empty string