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

package/CLAUDE.md

@@ -231,6 +231,11 @@ Intent 文档是设计阶段的产物，实施阶段会基于它创建具体的
 - **文件删除**：必须提供 `dryRun` 选项，允许预览将要删除的内容
 - **批量操作**：在执行前应验证数据源（如 YAML 文件）的完整性
 
+### 代码检查
+
+- **每次修改后检查 lint**：执行 `pnpm lint:fix` 检查并自动修复问题
+- **提交前确保通过**：不要提交带有 lint 错误的代码
+
 ## AIGNE 框架开发指南
 
 ### Function Agent 基本结构
@@ -438,4 +443,40 @@ agentName.task_render_mode = "collapse";
 
 - **入口 Agent**：`skills-entry/doc-smith/index.mjs`
 - **Function Agent**：`agents/content-checker/index.mjs`
-- **共享模块**：`utils/workspace.mjs`、`utils/afs-factory.mjs`
+- **共享模块**：`utils/workspace.mjs`、`utils/afs-factory.mjs`
+
+## 设计决策原则
+
+### KISS 原则应用
+
+在设计功能时，优先考虑最简方案。复杂度不是功能强大的标志，往往是设计不成熟的表现。
+
+**案例：Workspace 与主项目的关系**
+
+| 方案 | 复杂度 | 问题 |
+|------|--------|------|
+| ❌ 自动添加 submodule | 高 | 本地路径无法共享、需要手动同步远程 |
+| ✅ 添加到 .gitignore | 低 | 简单、无副作用、用户自主选择 |
+
+**决策过程**：
+1. 先问"为什么需要这个功能？"而不是"如何实现这个功能？"
+2. 识别出 submodule 解决的是"追踪子项目版本"，但 doc-smith 不需要这种强耦合
+3. 最简方案：独立 git 仓库 + gitignore，用户需要时自行决定如何关联
+
+### 问对的问题
+
+遇到技术问题时，先审视问题本身是否正确：
+
+| 错误的问题 | 正确的问题 |
+|-----------|-----------|
+| 如何让 submodule URL 自动同步？ | 为什么需要 submodule？ |
+| 如何处理复杂的边界情况？ | 这个功能是否应该存在？ |
+| 如何让用户更容易使用？ | 用户真正需要什么？ |
+
+**原则**：如果一个功能需要大量边界处理，可能说明功能本身的抽象层次有问题。
+
+### 默认行为设计
+
+- **默认做最少的事**：不自作主张添加可能有问题的配置
+- **复杂操作由用户显式触发**：提供可选命令而非自动执行
+- **松耦合优于强耦合**：让组件独立存在，用户自主决定关联方式

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/localize/index.yaml

@@ -12,7 +12,7 @@ skills:
     skills:
       - url: ./translate-documents/translate-to-languages.yaml
     iterate_on: translationTasks
-    concurrency: 5
+    concurrency: 3
   - url: ./translate-documents/generate-summary.mjs     # 生成最终总结报告
 input_schema:
   type: object

package/agents/publish/ai/intent.md

@@ -21,7 +21,8 @@ DocSmith 生成的文档存储在本地 workspace 目录中，使用特定的目
    └─ 检查文档内容（checkContent）
     ↓
 2. translate-meta.mjs - 翻译元数据（可选）
-   └─ 将项目名称和描述翻译为多语言
+   ├─ 如果只有一种语言，跳过翻译，直接保存到缓存
+   └─ 如果有多种语言，将项目名称和描述翻译为目标语言
     ↓
 3. publish-docs.mjs - 执行发布
    ├─ 加载文档结构
@@ -48,6 +49,8 @@ DocSmith 生成的文档存储在本地 workspace 目录中，使用特定的目
    - 调整相对路径以适应发布后的目录结构
 4. **多平台支持**：DocSmith Cloud、自有网站、新建网站
 5. **元数据翻译**：支持将项目信息翻译为多语言
+   - 单语言时跳过翻译，直接缓存原始内容
+   - 多语言时才调用 AI 进行翻译
 
 ## 输入输出
 

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/publish/translate-meta.mjs

@@ -59,36 +59,47 @@ export default async function translateMeta({ config }, options) {
   const titleTranslation = parsedTranslationCache[projectName] || {};
   const descTranslation = parsedTranslationCache[projectDesc] || {};
 
-  const titleLanguages = languages.filter((lang) => !titleTranslation[lang]);
-  const descLanguages = languages.filter((lang) => !descTranslation[lang]);
-  const titleTranslationSchema = z.object(
-    titleLanguages.reduce((shape, lang) => {
-      shape[lang] = z.string();
-      return shape;
-    }, {}),
-  );
-  const descTranslationSchema = z.object(
-    descLanguages.reduce((shape, lang) => {
-      shape[lang] = z.string();
-      return shape;
-    }, {}),
-  );
-
-  const agent = AIAgent.from({
-    name: "translateMeta",
-    instructions:
-      "You are an **Elite Polyglot Localization and Translation Specialist** with extensive professional experience across multiple domains. Your core mission is to produce translations that are not only **100% accurate** to the source meaning but are also **natively fluent, highly readable, and culturally appropriate** in the target language.",
-    inputKey: "message",
-    outputSchema: z.object({
-      title: titleTranslationSchema.describe("Translated titles with language codes as keys"),
-      desc: descTranslationSchema.describe(
-        "Translated descriptions with language codes as keys. Each description MUST be within 100 characters.",
-      ),
-    }),
-  });
-  if (titleLanguages.length > 0 || descLanguages.length > 0) {
-    const translatedMetadata = await options.context.invoke(agent, {
-      message: `Translate the following title and description into all target languages except the source language. Provide the translations in a JSON object with the language codes as keys. If the project title or description is empty, return an empty string for that field.
+  // If only one language, skip translation and cache original content directly
+  if (languages.length <= 1) {
+    const singleLang = languages[0] || locale || "en";
+    if (projectName && !titleTranslation[singleLang]) {
+      titleTranslation[singleLang] = projectName;
+    }
+    if (finalProjectDesc && !descTranslation[singleLang]) {
+      descTranslation[singleLang] = finalProjectDesc;
+    }
+  } else {
+    // Multiple languages: need translation
+    const titleLanguages = languages.filter((lang) => !titleTranslation[lang]);
+    const descLanguages = languages.filter((lang) => !descTranslation[lang]);
+    const titleTranslationSchema = z.object(
+      titleLanguages.reduce((shape, lang) => {
+        shape[lang] = z.string();
+        return shape;
+      }, {}),
+    );
+    const descTranslationSchema = z.object(
+      descLanguages.reduce((shape, lang) => {
+        shape[lang] = z.string();
+        return shape;
+      }, {}),
+    );
+
+    const agent = AIAgent.from({
+      name: "translateMeta",
+      instructions:
+        "You are an **Elite Polyglot Localization and Translation Specialist** with extensive professional experience across multiple domains. Your core mission is to produce translations that are not only **100% accurate** to the source meaning but are also **natively fluent, highly readable, and culturally appropriate** in the target language.",
+      inputKey: "message",
+      outputSchema: z.object({
+        title: titleTranslationSchema.describe("Translated titles with language codes as keys"),
+        desc: descTranslationSchema.describe(
+          "Translated descriptions with language codes as keys. Each description MUST be within 100 characters.",
+        ),
+      }),
+    });
+    if (titleLanguages.length > 0 || descLanguages.length > 0) {
+      const translatedMetadata = await options.context.invoke(agent, {
+        message: `Translate the following title and description into all target languages except the source language. Provide the translations in a JSON object with the language codes as keys. If the project title or description is empty, return an empty string for that field.
 
 **IMPORTANT**: The description translations MUST be concise and within 100 characters. If the source description is long, extract and translate only the key points or create a brief summary that captures the essence.
 
@@ -117,23 +128,19 @@ Respond with a JSON object in the following format:
 - Be concise and capture the core essence of the project
 - Use natural, fluent language appropriate for the target culture
 - If the source is very long, create a brief summary instead of a full translation
-
-If no translation is needed, respond with:
-{
-  "title": {},
-  "desc": {}
-}`,
-    });
-    Object.keys(translatedMetadata.title || {}).forEach((lang) => {
-      if (translatedMetadata.title[lang]) {
-        titleTranslation[lang] = translatedMetadata.title[lang];
-      }
-    });
-    Object.keys(translatedMetadata.desc || {}).forEach((lang) => {
-      if (translatedMetadata.desc[lang]) {
-        descTranslation[lang] = translatedMetadata.desc[lang];
-      }
-    });
+`,
+      });
+      Object.keys(translatedMetadata.title || {}).forEach((lang) => {
+        if (translatedMetadata.title[lang]) {
+          titleTranslation[lang] = translatedMetadata.title[lang];
+        }
+      });
+      Object.keys(translatedMetadata.desc || {}).forEach((lang) => {
+        if (translatedMetadata.desc[lang]) {
+          descTranslation[lang] = translatedMetadata.desc[lang];
+        }
+      });
+    }
   }
 
   if (!projectDesc && finalProjectDesc) {

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.14",
+  "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

package/utils/workspace.mjs

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { access, readFile, mkdir, writeFile } from "node:fs/promises";
+import { access, readFile, mkdir, writeFile, appendFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
@@ -24,6 +24,17 @@ export const DOC_SMITH_DIR = ".aigne/doc-smith";
 export const SOURCES_DIR = "sources";
 export const WORKSPACE_SUBDIRS = ["intent", "planning", "docs"];
 
+/**
+ * doc-smith workspace 的 .gitignore 内容
+ */
+export const GITIGNORE_CONTENT = `\
+# Ignore sources directory
+sources/
+
+# Ignore temporary files
+tmp/
+`;
+
 /**
  * 检查路径是否存在
  * @param {string} path - 路径
@@ -48,12 +59,13 @@ export function pathExistsSync(path) {
 }
 
 /**
- * 检查目录是否是 git 仓库
- * @param {string} path - 目录路径
+ * 检查是否在 git 仓库内（支持子目录）
+ * @param {string} cwd - 工作目录
  * @returns {Promise<boolean>}
  */
-export async function isGitRepo(path = ".") {
-  return pathExists(join(path, ".git"));
+export async function isGitRepo(cwd = ".") {
+  const result = await gitExec("rev-parse --is-inside-work-tree", cwd);
+  return result.success && result.output === "true";
 }
 
 /**
@@ -71,6 +83,49 @@ export async function gitExec(command, cwd = ".") {
   }
 }
 
+/**
+ * 获取 git 仓库根目录
+ * @param {string} cwd - 起始目录
+ * @returns {Promise<string | null>}
+ */
+export async function getGitRoot(cwd = ".") {
+  const result = await gitExec("rev-parse --show-toplevel", cwd);
+  if (result.success) {
+    return result.output;
+  }
+  return null;
+}
+
+/**
+ * 向 .gitignore 添加忽略规则（如果不存在）
+ * @param {string} gitRoot - git 仓库根目录
+ * @param {string} pattern - 要忽略的模式
+ * @returns {Promise<boolean>} 是否添加成功
+ */
+export async function addToGitignore(gitRoot, pattern) {
+  const gitignorePath = join(gitRoot, ".gitignore");
+
+  try {
+    // 检查 .gitignore 是否存在
+    if (await pathExists(gitignorePath)) {
+      // 读取现有内容，检查是否已包含该模式
+      const content = await readFile(gitignorePath, "utf8");
+      if (content.includes(pattern)) {
+        return true; // 已存在，无需添加
+      }
+      // 追加到文件末尾（确保换行）
+      const prefix = content.endsWith("\n") ? "" : "\n";
+      await appendFile(gitignorePath, `${prefix}${pattern}\n`, "utf8");
+    } else {
+      // 创建新的 .gitignore
+      await writeFile(gitignorePath, `${pattern}\n`, "utf8");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 检测 workspace 模式（同步版本）
  * 用于需要在模块加载时同步判断的场景
@@ -179,8 +234,7 @@ export async function initProjectMode() {
   await createDirectoryStructure(DOC_SMITH_DIR);
 
   // 创建 .gitignore
-  const gitignoreContent = "# Ignore sources directory\nsources/\n";
-  await writeFile(join(DOC_SMITH_DIR, ".gitignore"), gitignoreContent, "utf8");
+  await writeFile(join(DOC_SMITH_DIR, ".gitignore"), GITIGNORE_CONTENT, "utf8");
 
   // 生成 config.yaml
   const configContent = generateConfig({
@@ -194,7 +248,7 @@ export async function initProjectMode() {
   });
   await writeFile(join(DOC_SMITH_DIR, "config.yaml"), configContent, "utf8");
 
-  // 在 doc-smith repo 中创建初始提交（submodule 需要）
+  // 在 doc-smith repo 中创建初始提交
   await gitExec("add .", DOC_SMITH_DIR);
   const commitResult = await gitExec(
     'commit -m "Initial commit: doc-smith workspace"',
@@ -204,17 +258,20 @@ export async function initProjectMode() {
     console.log(`✅ Created initial commit in ${DOC_SMITH_DIR}`);
   }
 
-  // 如果外层是 git 仓库，添加为 submodule
-  const outerIsGitRepo = await isGitRepo(".");
+  // 如果外层是 git 仓库，在其 .gitignore 中添加忽略规则
+  const gitRoot = await getGitRoot(".");
 
-  if (outerIsGitRepo) {
-    const submoduleCmd = `submodule add ./${DOC_SMITH_DIR} ${DOC_SMITH_DIR}`;
-    const result = await gitExec(submoduleCmd);
+  if (gitRoot) {
+    // 计算相对于 git 根目录的忽略路径
+    const cwd = process.cwd();
+    const relativePath = cwd.startsWith(gitRoot)
+      ? cwd.slice(gitRoot.length + 1) // 去掉 gitRoot 和 /
+      : "";
+    const ignorePattern = relativePath ? `${relativePath}/${DOC_SMITH_DIR}/` : `${DOC_SMITH_DIR}/`;
 
-    if (result.success) {
-      console.log(`✅ Added ${DOC_SMITH_DIR} as git submodule`);
-    } else {
-      console.log(`⚠️ Failed to add submodule: ${result.error}`);
+    const added = await addToGitignore(gitRoot, ignorePattern);
+    if (added) {
+      console.log(`✅ Added ${ignorePattern} to .gitignore`);
     }
   }
 
@@ -239,8 +296,7 @@ export async function initStandaloneMode() {
   await gitExec("init");
 
   // 创建 .gitignore
-  const gitignoreContent = "# Ignore sources directory\nsources/\n";
-  await writeFile(".gitignore", gitignoreContent, "utf8");
+  await writeFile(".gitignore", GITIGNORE_CONTENT, "utf8");
 
   // 创建目录结构（包括 sources/）
   await createDirectoryStructure(".", true);