| name | translate-to-chinese |
| description | Translate Python project files (comments, docstrings, instructions, markdown) from English to Chinese. Use when the user asks to translate code comments, README, documentation, or AI prompt instructions to Chinese in a Python project. |
项目文件中英翻译
将 Python 项目中的英文内容翻译为中文，覆盖注释、文档字符串、instructions prompt、markdown 文件等。
翻译范围
Python 文件（.py）
需要翻译的内容：
- 模块顶部的 docstring（
"""..."""）
- 行内注释（
# ...）
- 函数/类的 docstring
instructions = """...""" 变量中的 AI prompt 内容additional_instructions / compression_prompt / message 等 prompt 类变量- 打印输出文本（
print() 中的字符串）
- 用户查询示例（示例对话内容）
- 文件底部
"""...""" 中的说明文字
不翻译的内容：
- 代码逻辑、变量名、函数名、类名
- import 语句
- 字符串常量（非注释/文档用途的，如 API key、URL）
- Pydantic Field 的
description 参数（保留英文，因为是给模型的 schema）
role 参数值（保留英文）- 文件路径和命令（如
python xxx.py）
- 代码块中的代码（仅翻译注释）
Markdown 文件（.md）
全文翻译，包括：
- 标题、段落、列表
- 表格内容
- 代码块中的注释（代码本身不翻译）
其他文件
.yaml / .toml 中的 description 字段- shell 脚本中的注释
工作流程
极小型目录（< 15 个文件）
直接处理，效率最高
- 并行
Glob 查找 .py 和 .md 文件
- Python 文件：
Read + 多次 StrReplace，逐段翻译
- Markdown 文件：
Read + Write 整体写入
- 预计耗时：10-20 分钟
翻译优先级：
- 优先：用户可见文本（示例提示、print 输出、错误信息）
- 其次：模块 docstring、函数 docstring
- 最后：instructions 等 AI prompt（如果时间允许）
小型目录（15-20 个文件）
- 并行
Glob 查找 .py 和 .md 文件
- 逐文件
Read + StrReplace 翻译
- Markdown 用
Write 整体写入（效率更高）
中型目录（20-50 个文件）
- 先并行
Glob .py 和 .md
- 分离处理：
- Python 文件：启动 1 个 Task
- Markdown 文件：启动 1 个 Task（单独处理，效率高）
- 两个 Task 并行运行
大型目录（> 50 个文件）
- 分析文件分布：先
Glob 统计各子目录文件数
- 按文件类型拆分：
- Python 文件：启动 1 个 Task，内部按功能模块批量处理
- Markdown 文件：启动 1 个 Task，全部一起处理（md 文件通常少）
- Python Task 策略：
- 优先翻译高频使用目录（01_quickstart、session、tools、knowledge）
- 次要目录可批量快速处理（仅翻译 docstring + instructions）
- 使用
resume 参数持续推进，直到全部完成
Task 提示词模板
Python 文件 Task（关键要点）：
翻译 <目录路径> 目录下所有 Python 文件的英文内容为中文。
需要翻译：
- 模块顶部 docstring
- 行内注释 # ...
- 函数/类 docstring
- instructions/additional_instructions 等 prompt 变量内容
不翻译：
- 代码逻辑、变量名、import
- Pydantic Field description
- role 参数值
技术术语统一：Agent、Team（团队）、Workflow（工作流）、Knowledge（知识库）、Storage（存储）、Memory（记忆）、Tool（工具）
使用 StrReplace 逐段替换。
【重要】继续翻译直到所有文件完成，不要中途停止总结。即使文件很多也要全部处理完。
关键实践：Python Task 通常需要 2-5 轮 resume 才能完成所有文件。第一轮完成度视文件结构而定：
- 简单结构（文件相似度高、子目录独立）：第一轮可达 60-70%
- 复杂结构（深层嵌套、文件差异大）：第一轮约 25-35%
Markdown 文件 Task：
翻译 <目录路径> 目录下所有 Markdown 文件的英文内容为中文。
全文翻译：标题、段落、列表、表格。代码块中的注释也翻译，代码本身不翻译。
技术术语保留英文或附中文说明：Agent、Team（团队）、Workflow（工作流）等。
使用 Write 直接写入翻译后内容。完成后报告翻译的文件数。
关键实践：Markdown Task 通常能一次性完成所有文件（50+ 个也可以），因为 Write 效率高且 md 文件相对简单。
翻译原则
- 技术术语保留英文或附中文括号说明，如 Agent、Workflow、Knowledge Base（知识库）
- 翻译要自然通顺，不生硬直译
- 保留原有代码结构、缩进、格式不变
- 用户可见文本优先翻译：示例提示、print 输出、错误消息
- 常用术语统一：
- Agent → Agent
- Team → 团队
- Workflow → 工作流
- Knowledge → 知识库
- Storage → 存储
- Memory → 记忆
- Guardrail → 护栏
- Tool → 工具
- Instructions → 指令
- Embedder → 嵌入器
- Vector DB → 向量数据库
- Hybrid search → 混合搜索
- Structured output → 结构化输出
- Human in the loop → 人机协作
- Session → Session
- State → State
- RAG → RAG
- Multimodal → 多模态
- Parser → Parser
- Hook → Hook
- Event → 事件
- Run → Run
- Step → 步骤
性能优化与实战经验
文件类型分离策略（关键优化）
- Python 和 Markdown 分别处理：两种文件翻译方式不同，分离后效率更高
- Python：细致翻译，逐段 StrReplace
- Markdown：整体翻译，Write 直接写入
- 并行启动 2 个 Task：Python Task + Markdown Task 同时运行
Task 数量与分组
- 极小型任务（< 15 文件）：不启动 Task，直接处理（10-20 分钟搞定）
- 小型任务（15-20 文件）：不启动 Task，直接处理
- 中型任务（20-50 文件）：2 个 Task（py + md 分离）
- 大型任务（> 50 文件）：2 个 Task + resume 持续推进
- 避免启动 4 个并行 Task：实际效率不如 2 个 Task + 多次 resume
- 原因：大量文件导致每个 Task 都很重，4 个并行容易超时或不完整
Resume 策略（大型任务核心）
关键经验：Python Task 会自动停止总结，需要主动推进
- 首次启动：2 个 Task（py + md）并行
- 检查进度：Task 返回后立即查看进度
- Markdown Task：通常一次完成 100%（50+ 文件也可以）✅
- Python Task：第一轮通常只完成 25-35%，需要 resume ⚠️
- 立即 Resume Python Task：不要等待，直接用
resume 参数继续推进
- 明确指令：Resume 时明确告诉 Task"继续翻译所有剩余文件"
- 重复 2-4 步：Python Task 通常需要 2-3 轮 resume 才能完成
Resume 提示词模板：
继续翻译 <目录> 所有剩余的 Python 文件。
已完成：<X>/<总数> 文件（<百分比>%）
剩余：约 <Y> 个文件
剩余目录：
- <子目录1>（<文件数>个）
- <子目录2>（<文件数>个）
【关键】继续翻译所有剩余的<Y>个文件，不要中途停止。全部完成后再报告。
使用 StrReplace 逐段翻译。保持高效批量处理。
实战示例（04_workflows 翻译）：
task_py = Task(prompt="翻译所有 Python 文件...", subagent_type="generalPurpose")
task_md = Task(prompt="翻译所有 Markdown 文件...", subagent_type="generalPurpose")
task_py_2 = Task(
prompt="继续翻译剩余的所有 Python 文件（已完成 22/79，剩余 57 个）...",
resume=task_py.agent_id,
subagent_type="generalPurpose"
)
task_py_3 = Task(
prompt="继续翻译所有剩余 Python 文件（已完成 28/79，剩余 51 个）...",
resume=task_py.agent_id,
subagent_type="generalPurpose"
)
关键发现：
- ✅ Markdown Task 一次完成，无需 resume
- ⚠️ Python Task 需要 2-3 轮，第一轮约 25-35%
- 📊 总耗时：3 轮 Task 调用（2 次 resume）
翻译优先级（大型目录）
在 Python Task 中按优先级翻译：
- 高频使用（必须完整）：01_quickstart、session、tools、knowledge
- 核心功能（详细翻译）：context、hooks、guardrails、memory
- 扩展功能（快速翻译）：仅 docstring + instructions
实战经验总结
核心发现：Python Task 第一轮完成度 25-100%，视文件结构而定
- ✅ 极小型目录（< 15 文件）直接处理：启动 Task 反而慢，逐文件翻译 10-20 分钟搞定
- ✅ 预期 Python Task 需要多轮（但短文件目录可能 1 轮完成）：第一轮完成度差异大，需根据结构调整预期
- 短文件+独立子目录（如 10_reasoning）：第一轮 100%，无需 resume ✨
- 简单结构（如 07_knowledge）：第一轮 60-70%，2-3 轮完成
- 复杂结构（如 05_agent_os）：第一轮 25-35%，4-5 轮完成
- ✅ Markdown Task 无需 resume：50+ md 文件通常一次完成（Write 效率高）
- ✅ 立即 Resume Python Task：第一轮返回后立即查看进度，马上 resume 继续
- ✅ Resume 提示词要具体：明确说明"已完成 X/总数，剩余 Y 个"，并列出剩余目录
- ✅ 先 Glob 两次：并行查找 py 和 md，避免串行等待
- ✅ Markdown 用 Write：比 StrReplace 快 3-5 倍
- ✅ Python 用 StrReplace：保持格式和结构完整
- ✅ 2 Task + Resume：比 4 Task 并行更可控、更可靠
- ✅ 分离 Python 和 Markdown：两种文件处理方式不同，分离效率更高
- ✅ 评估文件结构：第一轮前先分析子目录独立性和文件相似度，预测完成轮数
- ✅ 翻译优先级：用户可见文本（示例提示、print）> docstring > instructions
- ✅ 增量翻译天然支持：Task 会自动检测已翻译文件并跳过，无需人工筛选。已翻译目录可直接重跑，安全幂等
- ✅ 部分翻译目录（如多次迭代后）：直接启动 Task，Task 会自动识别哪些文件已完成，只处理剩余文件
- ❌ 避免 4 个并行 Task：大量文件时每个 Task 都太重，容易中断
- ❌ 避免过细拆分：10 个小 Task 不如 2 个大 Task + resume
- ❌ 避免固定预期：不同目录结构差异大，灵活调整 resume 策略
为什么 Python Task 第一轮完成度差异大？
影响完成度的关键因素：
- 文件长度（新增，权重最高）：
- 短文件（< 200 行，如 10_reasoning 的示例脚本）→ 100% 完成
- 中等文件（200-500 行，如 07_knowledge）→ 70% 完成度
- 长文件（500+ 行，如 05_agent_os）→ 30% 完成度
- 文件相似度：
- 高相似度（如 07_knowledge 的多个 embedder 文件）→ 70% 完成度
- 低相似度（如 05_agent_os 的混合功能文件）→ 30% 完成度
- 子目录独立性：
- 独立子目录（如 10_reasoning 的 agents/, tools/, models/）→ 翻译流畅，可 1 轮完成
- 独立子目录（如 readers/, embedders/ 互不依赖）→ 翻译流畅
- 强耦合子目录（如 core/, utils/ 相互引用）→ 翻译慢
- 代码复杂度：
- 示例代码居多（如 10_reasoning、07_knowledge）→ StrReplace 快速
- 核心逻辑复杂（如 05_agent_os）→ StrReplace 慢
技术原因：
- Python 文件翻译复杂度高（需要 StrReplace 逐段替换）
- Token 消耗积累（每个 Python 文件消耗 1000-3000 tokens）
- 上下文过长（已处理文件的历史记录）
- Task 内置的"合理停止点"判断
为什么 Markdown Task 不需要 resume？
- Markdown 文件翻译简单（Write 整体写入）
- 处理速度快（每个文件 500-1500 tokens）
- 文件数量虽多但总 token 消耗低
如何应对？
- 接受 Python Task 需要 2-5 轮 resume（视文件结构而定）
- 第一轮前快速评估：用
ls -R 查看子目录结构，预判相似度
- 看到多个同类子目录（如 embedders/, vector_db/）→ 预期 60-70%
- 看到混合功能文件（如 core/, utils/, hooks/）→ 预期 30-35%
- 每轮 resume 时明确剩余文件数和剩余目录，给出清晰指令
- 使用同一个 agent_id 持续 resume，保持上下文
Token 管理与预期
- 极小型任务（< 15 文件）：3-8k tokens，单次完成，10-20 分钟
- 小型任务（15-20 文件）：8-15k tokens，单次完成
- 中型任务（20-50 文件）：15-30k tokens，1-2 轮
- 大型任务（50-100 文件）：40-80k tokens，2-3 轮 resume
- 超大型任务（100-200 文件）：80-150k tokens，4-5 轮 resume
关键指标：
- 每个 Python 文件平均消耗：500-1500 tokens（取决于复杂度）
- 每个 Markdown 文件平均消耗：1000-3000 tokens
- Task 通常在累计消耗 30-40k tokens 后自动停止
实战案例对比：
| 目录 | Python 文件数 | Markdown 文件数 | Python 轮数 | Markdown 轮数 | 总耗时 |
|---|
| 00_quickstart | 13 | 3 | 直接处理 | 直接处理 | 20 分钟 |
| 03_teams | 118 | 48 | 2 轮（38% 停止） | 1 轮 | 3 次 Task |
| 04_workflows | 79 | 52 | 3 轮（28%→35%→100%） | 1 轮 | 4 次 Task |
| 05_agent_os | 168 | 66 | 5 轮（32%→67%→71%→82%→88%） | 1 轮 | 6 次 Task |
| 07_knowledge | 137 | 63 | 3 轮（70%→85%→100%）✨ | 1 轮 | 4 次 Task |
| 09_evals | 38 | 19 | 1 轮（29/38已译，仅补9个新文件）✨ | 1 轮（已译直接跳过） | 2 次 Task |
| 10_reasoning | 63 | 31 | 1 轮（100%）✨✨ | 1 轮 | 2 次 Task |
经验教训：
- 极小型目录（< 15 文件）直接处理最快：启动 Task 反而慢，直接逐文件翻译 10-20 分钟搞定
- Python Task 第一轮完成度：25-100%（视文件复杂度和结构）
- 简单结构目录（如 10_reasoning、07_knowledge）：第一轮可达 70-100%
- 复杂嵌套目录（如 05_agent_os）：第一轮约 30-35%
- Markdown Task 第一轮完成度：100%（无需 resume）
- Python 文件数 < 15：直接处理（无需 Task）
- Python 文件数 15-50：通常 1-2 轮
- Python 文件数 50-100：通常 1-3 轮（结构简单可 1 轮完成）
- Python 文件数 100-200：通常 3-5 轮（取决于文件结构）
- 超长文件（800+ 行）可能因格式复杂无法完全翻译，需单独处理
关键发现（07_knowledge 案例）：
- ✅ 第一轮达 70%：文件结构清晰、子目录独立时，完成度显著提高
- ✅ 3 轮完成 137 文件：比预期更高效（原预期 4-5 轮）
- 💡 影响因素：
- 文件相似度高（如多个 vector_db 子目录结构相似）→ 完成度高
- 子目录独立性强（如 embedders/, readers/ 互不依赖）→ 翻译效率高
- 代码复杂度低（如示例代码居多）→ StrReplace 速度快
关键发现（10_reasoning 案例）✨✨：
- ✅ 第一轮即达 100%：63 个 Python 文件、31 个 Markdown 文件，2 个 Task 全部一次性完成，零 resume
- ✅ 文件结构特征：多子目录（agents/、tools/、models/、teams/），各子目录独立、文件短小、示例代码为主
- 💡 关键结论：文件短小（< 200 行）+ 子目录高度独立 + 示例代码为主 → 可能 1 轮完成，无需预设 resume
- 📌 新策略：启动 Task 前评估文件平均行数，短文件目录可乐观预期 1 轮完成
常见问题
Q: Python Task 第一轮只完成了 28% 还是 70%，哪个是正常的？
A: 都是正常的，取决于文件结构：
- 70% 完成：文件相似度高、子目录独立（如 07_knowledge 的 embedders/, readers/）
- 28-35% 完成：文件复杂、深层嵌套（如 05_agent_os 的 core/, hooks/）
- 第一轮前快速用
ls -R 评估目录结构，预判完成度
Q: Markdown Task 为什么能一次完成 50+ 文件？
A: 因为使用 Write 工具整体写入，效率极高。且 md 文件相对简单，token 消耗低。
Q: 需要手动检查每个文件的翻译质量吗？
A: 不需要。翻译规则清晰，Task 会保持一致性。最后抽查几个文件即可。
Q: 多次 resume 会不会重复翻译？
A: 不会。Task 保持上下文，知道哪些已完成，哪些未完成。
Q: 什么时候应该放弃 resume，重新启动新 Task？
A: 如果连续 3 轮 resume 进度都很慢（< 10%），可以考虑重新启动。但通常 2-3 轮就能完成。
Q: 超大型任务（150+ Python 文件）需要多少轮 resume？
A: 2-5 轮，取决于文件结构：
- 简单结构（如 07_knowledge 137 文件）：3 轮完成（70%→85%→100%）
- 复杂结构（如 05_agent_os 168 文件）：5 轮完成（32%→67%→71%→82%→88%）
- 核心功能文件优先完成，超长文件（800+ 行）可能需要单独处理
Q: 为什么有些超长文件无法完全翻译？
A: 超长文件（800+ 行）因格式复杂、嵌套深度大，StrReplace 可能遇到格式匹配问题。建议最后单独处理这些文件，或手动分段翻译。
Q: 某个目录之前已部分翻译，现在新增了文件，怎么处理？
A: 直接按正常流程启动 Task 即可。Task 会自动检测哪些文件已翻译（内容为中文）并跳过，只处理新增或未翻译的文件。翻译操作是幂等的，重复运行不会破坏已翻译内容。典型案例：09_evals 有 29/38 个 Python 文件已提前翻译，Task 1 轮内仅翻译了剩余 9 个文件，效率极高。
Q: 如何判断一个目录是否"已经翻译过"，需不需要跳过？
A: 不需要手动判断，直接运行即可。Task 内部会逐文件检查内容语言，已翻译的直接跳过。
