feat: 更新中文文档并添加 l10n 工具

AGENTS.md

@@ -12,7 +12,7 @@
 - `make help`：列出所有 Make 目标，是新人快速上手的入口。
 - `make lint`：使用 `markdownlint-cli` 校验全仓库 Markdown，一旦新增文档请先跑通（需本地 Node/npm 环境，可用 `npm install -g markdownlint-cli` 安装）。
 - `make build` / `make test` / `make clean`：目前为占位，落地具体实现后务必更新脚本和说明；建议在 `Makefile` 旁补充注释并保持幂等，避免修改全局状态。
-- 提示词转换：进入 `i18n/zh/prompts/prompts-library/` 后执行 `python main.py` 按交互提示进行转换，运行前请确认虚拟环境、依赖与输出目录，并在完成后检查生成 Markdown 是否符合 lint 规则。
+- 提示词转换：进入 `libs/external/prompts-library/` 后执行 `python main.py` 按交互提示进行转换，运行前请确认虚拟环境、依赖与输出目录，并在完成后检查生成 Markdown 是否符合 lint 规则。
 
 ## Coding Style & Naming Conventions
 - 文字层：文档、注释、日志使用中文；代码符号（函数 / 变量 / 模块）统一英文且语义直白，避免晦涩缩写。
@@ -35,7 +35,7 @@
 - 外部依赖来源记录在 `libs/external/` 目录下，增减依赖时同步维护，保持可追溯；引入第三方脚本需标明许可证与来源。
 
 ## Architecture Overview & Workflow
-- 工作流倡导「规划 → 上下文固定 → 分步实现 → 自测 → 复盘」，对应资产分别存放在 `i18n/zh/documents/`、`i18n/zh/i18n/zh/prompts/`、`libs/` 与备份脚本中。保持单向数据流和清晰责任边界可以避免后期维护成本激增。
+- 工作流倡导「规划 → 上下文固定 → 分步实现 → 自测 → 复盘」，对应资产分别存放在 `i18n/zh/documents/`、`i18n/zh/prompts/`、`libs/` 与备份脚本中。保持单向数据流和清晰责任边界可以避免后期维护成本激增。
 - 设计决策与目录结构更新后，请同步修订本文件与相关文档，确保团队共享同一真相源，减少口头约定与隐式规则。
 
 ---
@@ -72,7 +72,7 @@ bash backups/一键备份.sh
 
 ### Core Directories
 - **`i18n/zh/prompts/`**: The core asset. A massive, well-organized library of prompts.
-  - `coding_i18n/zh/prompts/`, `system_i18n/zh/prompts/`, `user_i18n/zh/prompts/`
+  - `coding_prompts/`, `system_prompts/`, `user_prompts/`, `meta_prompts/`
 - **`i18n/zh/skills/`**: A modular library of skills for the AI, providing domain-specific knowledge for various tools like `ccxt`, `postgresql`, `telegram-dev`, 
 etc.
 - **`i18n/zh/documents/`**: The project's knowledge base, containing methodology, principles, and guides.
@@ -121,9 +121,10 @@ When modifying this repository:
 
 1.  **AI 提示词库 (`i18n/zh/prompts/`):**
     *   一个极其庞大和精细分类的提示词集合，是项目的核心资产。
-    *   `coding_i18n/zh/prompts/`: 专注于编程和代码生成的提示词。
+    *   `coding_prompts/`: 专注于编程和代码生成的提示词。
-    *   `system_i18n/zh/prompts/`: 用于设定 AI 行为和思维框架的系统级提示词。
+    *   `system_prompts/`: 用于设定 AI 行为和思维框架的系统级提示词。
-    *   `user_i18n/zh/prompts/`: 用户自定义或常用的提示词。
+    *   `user_prompts/`: 用户自定义或常用的提示词。
+    *   `meta_prompts/`: 元提示词与提示工程辅助。
 
 2.  **提示词库管理工具 (`libs/external/prompts-library/`):**
     *   提供 Python 工具 (`main.py`)，用于在 Excel 工作簿 (`prompt_excel/`) 和 Markdown 文档 (`prompt_docs/`) 之间进行提示词的相互转换。
@@ -179,9 +180,10 @@ When modifying this repository:
 │       └── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF 工具。
 │
 ├── i18n/zh/prompts/                     # 核心资产：AI 提示词库。
-│   ├── coding_i18n/zh/prompts/          # 编程与代码生成相关提示词。
+│   ├── coding_prompts/                  # 编程与代码生成相关提示词。
-│   ├── system_i18n/zh/prompts/          # AI 系统级提示词。
+│   ├── system_prompts/                  # AI 系统级提示词（含 CLAUDE 版本目录）。
-│   └── user_i18n/zh/prompts/            # 用户自定义提示词。
+│   ├── user_prompts/                    # 用户自定义提示词。
+│   └── meta_prompts/                    # 元提示词与提示工程辅助。
 │
 └── i18n/zh/skills/                      # 模块化技能库。
     ├── ccxt/                    # CCXT 加密货币交易库技能。

i18n/zh/documents/README.md

@@ -1,11 +1,11 @@
 # 📖 文档库 (Documents)
 
-`documents/` 目录汇总项目的流程文档、架构说明、开发经验与最佳实践，是理解方法论与协作规则的首选入口。
+`i18n/zh/documents/` 目录汇总项目的流程文档、架构说明、开发经验与最佳实践，是理解方法论与协作规则的首选入口。
 
 ## 目录结构
 
 ```
-documents/
+i18n/zh/documents/
 ├── README.md
 │
 ├── Methodology and Principles/

i18n/zh/prompts/README.md

@@ -1,6 +1,6 @@
 # 💡 AI 提示词库 (Prompts)
 
-`prompts/` 存放本仓库的提示词资产：用 **系统提示词** 约束 AI 的边界与品味，用 **任务提示词** 驱动「需求澄清 → 计划 → 执行 → 复盘」的开发流水线。
+`i18n/zh/prompts/` 存放本仓库的提示词资产：用 **系统提示词** 约束 AI 的边界与品味，用 **任务提示词** 驱动「需求澄清 → 计划 → 执行 → 复盘」的开发流水线。
 
 ## 推荐使用路径（从 0 到可控）
 
@@ -11,7 +11,7 @@
 ## 目录结构（以仓库真实目录为准）
 
 ```
-prompts/
+i18n/zh/prompts/
 ├── README.md
 ├── coding_prompts/                 # 编程/研发提示词（当前 41 个 .md）
 │   ├── index.md                    # 自动生成的索引与版本矩阵（请勿手改）
@@ -37,7 +37,7 @@ prompts/
 
 系统提示词用于定义 **工作模式、代码品味、输出格式、安全边界**。目录采用版本化结构：
 
-- 路径约定：`prompts/system_prompts/CLAUDE.md/<版本号>/CLAUDE.md`
+- 路径约定：`i18n/zh/prompts/system_prompts/CLAUDE.md/<版本号>/CLAUDE.md`
 - 推荐版本：
   - `v8`：综合版，适合通用 Vibe Coding
   - `v10`：偏 Augment/上下文引擎的规范化约束
@@ -66,15 +66,15 @@ prompts/
 
 ```bash
 # 查看一个任务提示词
-sed -n '1,160p' prompts/coding_prompts/标准化流程.md
+sed -n '1,160p' i18n/zh/prompts/coding_prompts/标准化流程.md
 
 # 选定系统提示词版本（建议先备份你当前的 CLAUDE.md）
-cp prompts/system_prompts/CLAUDE.md/10/CLAUDE.md ./CLAUDE.md
+cp i18n/zh/prompts/system_prompts/CLAUDE.md/10/CLAUDE.md ./CLAUDE.md
 ```
 
 ## 维护与批量管理（可选）
 
-如果你需要 Excel ↔ Markdown 的批量维护能力，仓库内置了第三方工具：`libs/external/prompts-library/`。建议把它视为“提示词资产的生产工具”，而把 `prompts/` 视为“日常开发的精选集”。
+如果你需要 Excel ↔ Markdown 的批量维护能力，仓库内置了第三方工具：`libs/external/prompts-library/`。建议把它视为“提示词资产的生产工具”，而把 `i18n/zh/prompts/` 视为“日常开发的精选集”。
 
 ## 相关资源
 

i18n/zh/skills/README.md

@@ -1,11 +1,11 @@
 # 🎯 AI Skills 技能库
 
-`skills/` 目录存放 AI 技能（Skills），这些是比提示词更高级的能力封装，可以让 AI 在特定领域表现出专家级水平。当前包含 **14 个**专业技能。
+`i18n/zh/skills/` 目录存放 AI 技能（Skills），这些是比提示词更高级的能力封装，可以让 AI 在特定领域表现出专家级水平。当前包含 **14 个**专业技能。
 
 ## 目录结构
 
 ```
-skills/
+i18n/zh/skills/
 ├── README.md                # 本文件
 │
 ├── # === 元技能（核心） ===
@@ -118,23 +118,23 @@ skill-name/
 
 ```bash
 # 查看元技能
-cat skills/claude-skills/SKILL.md
+cat i18n/zh/skills/claude-skills/SKILL.md
 
 # 查看 PostgreSQL 技能（最详细）
-cat skills/postgresql/SKILL.md
+cat i18n/zh/skills/postgresql/SKILL.md
 
 # 查看 Telegram Bot 开发技能
-cat skills/telegram-dev/SKILL.md
+cat i18n/zh/skills/telegram-dev/SKILL.md
 ```
 
 ### 2. 复制到项目中使用
 
 ```bash
 # 复制整个技能目录
-cp -r skills/postgresql/ ./my-project/
+cp -r i18n/zh/skills/postgresql/ ./my-project/
 
 # 或只复制主文件到 CLAUDE.md
-cp skills/postgresql/SKILL.md ./CLAUDE.md
+cp i18n/zh/skills/postgresql/SKILL.md ./CLAUDE.md
 ```
 
 ### 3. 结合 Claude Code 使用
@@ -145,8 +145,8 @@ cp skills/postgresql/SKILL.md ./CLAUDE.md
 # 项目规则
 
 请参考以下技能文件：
-@skills/postgresql/SKILL.md
+@i18n/zh/skills/postgresql/SKILL.md
-@skills/telegram-dev/SKILL.md
+@i18n/zh/skills/telegram-dev/SKILL.md
 ```
 
 ## 创建自定义 Skill
@@ -154,12 +154,12 @@ cp skills/postgresql/SKILL.md ./CLAUDE.md
 ### 方法一：使用元技能生成（推荐）
 
 1. 准备领域资料（文档、代码、规范）
-2. 将资料和 `skills/claude-skills/SKILL.md` 一起提供给 AI
+2. 将资料和 `i18n/zh/skills/claude-skills/SKILL.md` 一起提供给 AI
 3. AI 会生成针对该领域的专用 Skill
 
 ```bash
 # 示例：让 AI 读取元技能后生成新技能
-cat skills/claude-skills/SKILL.md
+cat i18n/zh/skills/claude-skills/SKILL.md
 # 然后告诉 AI：请根据这个元技能，为 [你的领域] 生成一个新的 SKILL.md
 ```
 
@@ -167,10 +167,10 @@ cat skills/claude-skills/SKILL.md
 
 ```bash
 # 创建技能目录
-mkdir -p skills/my-skill/{assets,scripts,references}
+mkdir -p i18n/zh/skills/my-skill/{assets,scripts,references}
 
 # 创建主文件
-cat > skills/my-skill/SKILL.md << 'EOF'
+cat > i18n/zh/skills/my-skill/SKILL.md << 'EOF'
 # My Skill
 
 ## 概述

libs/external/l10n-tool/README.md

@@ -0,0 +1,34 @@
+# l10n-tool
+
+轻量级多语言翻译脚本，定位：先用机器翻译批量落地，再由 AI/人工逐行润色。
+
+## 特性
+- 保护 Markdown 代码块，不误翻译代码
+- 命令行一条跑完，便于批处理
+- 依赖轻：`deep-translator`（封装 Google 翻译）
+
+## 安装
+```bash
+pip install -r requirements.txt
+```
+
+## 使用示例
+```bash
+# 将中文 README 翻译到英文
+python translate.py --input ../../i18n/zh/README.md --output ../../i18n/en/README.md --src-lang zh --tgt-lang en --overwrite
+
+# 批量翻译 prompts，可在外部脚本中循环调用
+```
+
+## 建议流程（快 ⇒ 精）
+1) 机器翻译初稿：用本工具覆盖生成各语言版本。
+2) AI 校润：对关键文档/提示词逐行复核，重点检查术语一致性与人称语气。
+3) 人工抽检：挑核心页面人工对比源文，修正 AI 可能的误译。
+
+## 语言代码参考
+- 常用：zh, en, es, fr, de, ru, pt, ar, hi, ja, ko, he, it, tr, nl, pl, id, vi, th, fa, uk, bn, ta, ur, ms, sw, ha
+- 更多代码可查 ISO 639-1。
+
+## 注意
+- 若需更高质量，可替换为官方 Google Cloud Translate / DeepL API，只需改写 `translate_blocks` 中的 translator 初始化逻辑。
+- 如遇免费翻译频率限制，可分批或加重试/代理配置。

libs/external/l10n-tool/requirements.txt

@@ -0,0 +1 @@
+deep-translator>=1.11.4

libs/external/l10n-tool/translate.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+轻量级批量翻译工具：将 Markdown/文本从一种语言翻译到另一种语言。
+默认使用 deep-translator 封装的 Google Translator，自带简单的代码块保护。
+用法示例：
+    python translate.py --input ../../i18n/zh/README.md --src-lang zh --tgt-lang en --output ../../i18n/en/README.md
+"""
+
+import argparse
+import os
+import sys
+from typing import List
+
+try:
+    from deep_translator import GoogleTranslator
+except ImportError as exc:  # pragma: no cover - 运行前请安装依赖
+    sys.stderr.write("[错误] 缺少依赖 deep-translator，请先 `pip install -r requirements.txt`\n")
+    raise
+
+
+def translate_blocks(lines: List[str], src: str, tgt: str) -> List[str]:
+    """逐段翻译，保持代码块原样，减少上下文丢失。"""
+    translated: List[str] = []
+    in_code = False
+    buffer: List[str] = []
+    translator = GoogleTranslator(source=src, target=tgt)
+
+    def flush_buffer():
+        if not buffer:
+            return
+        text = "\n".join(buffer)
+        try:
+            result = translator.translate(text)
+        except Exception as exc:  # pragma: no cover
+            raise RuntimeError(f"翻译失败: {exc}") from exc
+        translated.extend(result.split("\n"))
+        buffer.clear()
+
+    for line in lines:
+        if line.strip().startswith("```"):
+            flush_buffer()
+            in_code = not in_code
+            translated.append(line)
+            continue
+        if in_code:
+            translated.append(line)
+            continue
+        # 空行作为段落分割，先刷新再保留空行
+        if not line.strip():
+            flush_buffer()
+            translated.append(line)
+            continue
+        buffer.append(line)
+
+    flush_buffer()
+    return translated
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="批量翻译文本/Markdown，保护代码块")
+    parser.add_argument("--input", required=True, help="源文件路径")
+    parser.add_argument("--output", required=True, help="目标文件路径")
+    parser.add_argument("--src-lang", required=True, help="源语言代码，如 zh")
+    parser.add_argument("--tgt-lang", required=True, help="目标语言代码，如 en")
+    parser.add_argument("--overwrite", action="store_true", help="允许覆盖已有输出文件")
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.input):
+        sys.stderr.write(f"[错误] 源文件不存在: {args.input}\n")
+        return 1
+    if os.path.exists(args.output) and not args.overwrite:
+        sys.stderr.write(f"[错误] 目标文件已存在，加 --overwrite 才会覆盖: {args.output}\n")
+        return 1
+
+    with open(args.input, "r", encoding="utf-8") as f:
+        lines = f.read().splitlines()
+
+    translated = translate_blocks(lines, args.src_lang, args.tgt_lang)
+
+    os.makedirs(os.path.dirname(args.output), exist_ok=True)
+    with open(args.output, "w", encoding="utf-8") as f:
+        f.write("\n".join(translated) + "\n")
+
+    print(f"[完成] {args.input} -> {args.output} ({args.src_lang} -> {args.tgt_lang})")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())