mcp-local-translate: Instructions file for Codex

AGENTS.md

为 mcp-local-translate 项目工作的 AI 编码 Agent 使用指南。

项目概述

mcp-local-translate 是一个本地翻译 MCP 服务器和 CLI 工具 — 基于 Meta NLLB-200 蒸馏模型，支持 200+ 语言互译，完全私有，零配置。通过 Transformers.js 在本地 CPU 上推理（第一次调用时懒加载模型），提供 translate 和 list_languages 两个 MCP 工具及对应的 CLI 子命令。

• 包名：npm 上的 @damoqiongqiu/mcp-local-translate
• 许可证：MIT
• Node 版本：>= 22
• 包管理器：pnpm（锁文件：pnpm-lock.yaml）
• 语言：TypeScript 6.0，严格模式，ES Modules（"type": "module"）
• 模块系统：Node16（"module": "node16"），相对导入须带 .js 扩展名

常用命令

pnpm install              # 安装依赖
pnpm run build            # TypeScript 编译 → dist/
pnpm run dev              # 通过 tsx 运行（无需构建）
pnpm run test             # 运行全部测试
pnpm run type-check       # tsc --noEmit
pnpm run check:fix        # 自动修复 lint 和格式化问题

项目结构

src/
  index.ts              # 入口 — 路由到 CLI 或 MCP 服务器
  server-main.ts        # MCP 服务器启动
  server/
    index.ts            # MCP 工具处理器（translate、list_languages）
    types.ts            # MCP 工具定义
  translator/
    index.ts            # 核心翻译引擎（NLLB-200 管道、文本分块、懒加载、代理配置）
    connectivity.ts     # 镜像检测与代理配置（三级回退：HF → hf-mirror → ModelScope）
    language-codes.ts   # FLORES-200 语言代码映射 + 多级解析器（精确码 → ISO 639-1 → 中文别名）
  utils/                # 共享工具
skills/                 # 随包发布的 Agent Skills

代码规范

格式化（Biome）

• 缩进：2 空格
• 引号：单引号（'）
• 分号：无（"semicolons": "asNeeded"）
• 尾逗号：ES5（"trailingCommas": "es5"）
• 行宽：100
• 自动修复：pnpm run check:fix

Lint 规则

• Biome 推荐规则

TypeScript 严格模式

全部严格检查均已开启：

• strict: true、noImplicitAny、strictNullChecks、strictFunctionTypes、noUncheckedIndexedAccess、exactOptionalPropertyTypes、noPropertyAccessFromIndexSignature、noImplicitReturns、noUnusedLocals、noUnusedParameters

导入规范

• 相对导入必须带 .js 扩展名（"module": "node16" 要求）
• 从具体模块路径导入，不要使用 barrel re-export

关键设计决策

双接口设计（MCP + CLI）

同一套核心逻辑同时服务于 MCP 工具和 CLI 子命令。入口点（src/index.ts）按第一个参数路由：如果匹配已知子命令 → CLI 路径；如果没有参数 → MCP 服务器。CLI 支持相同的环境变量和等价的命令行标志。

翻译管道（Translation Pipeline）