feat: 更新中文文档并添加 l10n 工具
This commit is contained in:
tukuaiai
parent
5c74e3e781
commit
8971d3653c
28
AGENTS.md
28
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/` 与备份脚本中。保持单向数据流和清晰责任边界可以避免后期维护成本激增。
|
||||
- 设计决策与目录结构更新后，请同步修订本文件与相关文档，确保团队共享同一真相源，减少口头约定与隐式规则。
|
||||
|
||||
---
|
||||
|
|
@ -71,8 +71,8 @@ bash backups/一键备份.sh
|
|||
## Architecture & Structure
|
||||
|
||||
### 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/`
|
||||
- **`i18n/zh/prompts/`**: The core asset. A massive, well-organized library of 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.
|
||||
|
|
@ -119,11 +119,12 @@ When modifying this repository:
|
|||
|
||||
## 主要功能与工作流程 (Key Features & Workflow)
|
||||
|
||||
1. **AI 提示词库 (`i18n/zh/prompts/`):**
|
||||
* 一个极其庞大和精细分类的提示词集合，是项目的核心资产。
|
||||
* `coding_i18n/zh/prompts/`: 专注于编程和代码生成的提示词。
|
||||
* `system_i18n/zh/prompts/`: 用于设定 AI 行为和思维框架的系统级提示词。
|
||||
* `user_i18n/zh/prompts/`: 用户自定义或常用的提示词。
|
||||
1. **AI 提示词库 (`i18n/zh/prompts/`):**
|
||||
* 一个极其庞大和精细分类的提示词集合，是项目的核心资产。
|
||||
* `coding_prompts/`: 专注于编程和代码生成的提示词。
|
||||
* `system_prompts/`: 用于设定 AI 行为和思维框架的系统级提示词。
|
||||
* `user_prompts/`: 用户自定义或常用的提示词。
|
||||
* `meta_prompts/`: 元提示词与提示工程辅助。
|
||||
|
||||
2. **提示词库管理工具 (`libs/external/prompts-library/`):**
|
||||
* 提供 Python 工具 (`main.py`)，用于在 Excel 工作簿 (`prompt_excel/`) 和 Markdown 文档 (`prompt_docs/`) 之间进行提示词的相互转换。
|
||||
|
|
@ -178,10 +179,11 @@ When modifying this repository:
|
|||
│ ├── my-nvim/ # 个人 Neovim 配置。
|
||||
│ └── XHS-image-to-PDF-conversion/ # 小红书图片转 PDF 工具。
|
||||
│
|
||||
├── i18n/zh/prompts/ # 核心资产：AI 提示词库。
|
||||
│ ├── coding_i18n/zh/prompts/ # 编程与代码生成相关提示词。
|
||||
│ ├── system_i18n/zh/prompts/ # AI 系统级提示词。
|
||||
│ └── user_i18n/zh/prompts/ # 用户自定义提示词。
|
||||
├── i18n/zh/prompts/ # 核心资产：AI 提示词库。
|
||||
│ ├── coding_prompts/ # 编程与代码生成相关提示词。
|
||||
│ ├── system_prompts/ # AI 系统级提示词（含 CLAUDE 版本目录）。
|
||||
│ ├── user_prompts/ # 用户自定义提示词。
|
||||
│ └── meta_prompts/ # 元提示词与提示工程辅助。
|
||||
│
|
||||
└── i18n/zh/skills/ # 模块化技能库。
|
||||
├── ccxt/ # CCXT 加密货币交易库技能。
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
# 📖 文档库 (Documents)
|
||||
|
||||
`documents/` 目录汇总项目的流程文档、架构说明、开发经验与最佳实践，是理解方法论与协作规则的首选入口。
|
||||
`i18n/zh/documents/` 目录汇总项目的流程文档、架构说明、开发经验与最佳实践，是理解方法论与协作规则的首选入口。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
documents/
|
||||
i18n/zh/documents/
|
||||
├── README.md
|
||||
│
|
||||
├── Methodology and Principles/
|
||||
|
|
|
|||
|
|
@ -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/` 视为“日常开发的精选集”。
|
||||
|
||||
## 相关资源
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
@skills/telegram-dev/SKILL.md
|
||||
@i18n/zh/skills/postgresql/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
|
||||
|
||||
## 概述
|
||||
|
|
|
|||
|
|
@ -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 初始化逻辑。
|
||||
- 如遇免费翻译频率限制，可分批或加重试/代理配置。
|
||||
|
|
@ -0,0 +1 @@
|
|||
deep-translator>=1.11.4
|
||||
|
|
@ -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())
|
||||
Loading…
Reference in New Issue