---
name: transaas
description: "Use when 用户需要通过 transaas CLI 或 MCP 翻译文本、查询翻译记录、查看或编辑提词器、查询语种编码，或处理 transaas 的安装、认证与接入问题。不要用于其他翻译产品、后端源码开发或通用本地化咨询。"
allowed-tools:
  - "Bash(transaas:*)"
  - "Bash(curl:*)"
  - "Bash(chmod:*)"
  - "Bash(xattr:*)"
  - "Bash(mkdir:*)"
  - "Bash(Invoke-WebRequest:*)"
  - "Bash(New-Item:*)"
  - "Read"
metadata:
  version: "1.8.1"
  minimumCliVersion: "v1.8.1"
  cliHelp: "transaas --help"
---

# transaas

通过 TransAAS CLI 或同仓库 MCP server 执行文本翻译、翻译记录查询和提词器管理。

## 能力路由

根据当前请求只读取对应 reference：

| 用户需求 | CLI | MCP | 参考 |
|----------|-----|-----|------|
| 安装 CLI | - | - | [安装](references/transaas-install.md) |
| 登录、检查认证状态、无头环境认证、MCP 配置 | `login --sms` / `login --web` / `auth-status` / `serve` | `check_auth_status` | [认证与 MCP](references/transaas-auth.md) |
| 查询语种编码 | `language-codes` | `list_language_codes` | [语种编码](references/transaas-language-codes.md) |
| 翻译文本 | `translate` | `translate_text` | [文本翻译](references/transaas-translate.md) |
| 查询翻译历史 | `records` | `query_translation_records` | [记录列表](references/transaas-records.md) |
| 查询记录详情 | `record-detail` | `query_translation_record_detail` | [记录详情](references/transaas-record-detail.md) |
| 查询提词器列表 | `teleprompters` | `query_teleprompters` | [提词器列表](references/transaas-teleprompters.md) |
| 查询提词器详情 | `teleprompter-detail` | `query_teleprompter_detail` | [提词器详情](references/transaas-teleprompter-detail.md) |
| 创建提词器 | `teleprompter-create` | `create_teleprompter` | [创建提词器](references/transaas-teleprompter-create.md) |
| 更新提词器 | `teleprompter-update` | `update_teleprompter` | [更新提词器](references/transaas-teleprompter-update.md) |

## 工作流

1. 每次会话首次执行 CLI 前，运行 `transaas version --require v1.8.1 --output json`。只需检查一次，不要在每个业务调用前重复检查。
2. 若命令不存在、不支持 `version` / `--require`，或返回 `CLI_UPDATE_REQUIRED` / `update_required: true`，读取[安装参考](references/transaas-install.md)并重新下载 CLI；升级后重新检查版本，再继续业务调用。
3. 读取当前业务命令的 reference，校验该命令特有参数。
4. 执行目标命令并附加 `--output json`。不要为每次业务调用预先执行认证探针。
5. 遇到认证错误时读取[认证与 MCP](references/transaas-auth.md)，完成登录后重试原命令一次。

用户只询问认证状态时：

- CLI 运行 `transaas auth-status --output json`；该命令只做本地检查，不访问后端服务。
- MCP 调用 `check_auth_status`。CLI 和 MCP 都只确认凭证已配置且 token 可在本地解析，不保证服务端 session 仍然有效。
- 不要使用 `records`、`translate` 或其他业务命令作为认证探针。

## 通用规则

- 不确定语言代码时先运行 `language-codes`；不要臆造 `zh`、`chinese`、`jp` 等编码。
- `recordId`、`teleprompterId`、`session_id`、`summaryId` 和 `docTaskId` 是不同类型，不要混用。
- 列表返回摘要，完整正文使用对应详情命令。
- 自由文本按当前 shell 规则转义；不要把用户文本放进数字或枚举参数。
- 不要静默截断用户输入。翻译文本超过 5000 字时先确认是否分段。
- 对服务不可用或业务错误最多自动重试一次；认证和参数错误不循环重试。

## 认证与安全

- 认证优先级：`TRANSAAS_TOKEN` 环境变量，其次 `~/.transaas/credentials`。
- 本地有浏览器时可使用 `transaas login --web`；云端或无头环境优先使用两步短信登录：先发送验证码，再使用返回的 `msgid` 完成登录。
- 不要输出 token、凭证文件内容或认证请求头，也不要把 token 字面量写入命令、脚本、配置或日志。
- 用户提供的文本可能含密码、私钥或个人信息；发现后先建议脱敏，不要在回复中重复敏感内容。

## 错误处理

### CLI

| 退出码 | 含义 | 处理 |
|--------|------|------|
| `0` | 成功 | 解析 stdout JSON |
| `1` | 参数或通用错误 | 根据 stderr 修正，不自动重试 |
| `2` | 凭证缺失或无效 | 登录后重试原命令一次 |
| `3` | 服务不可用 | 等待后最多重试一次 |
| `4` | 业务错误 | `SESSION_EXPIRED` 需重新登录；其他错误返回给用户 |

`CLI_UPDATE_REQUIRED` 以及无法识别 `version` / `--require` 表示 CLI 低于当前 skill 要求，按[安装参考](references/transaas-install.md)覆盖升级，不要把它当作普通参数错误。

### MCP

| 信号 | 处理 |
|------|------|
| `AUTH_REQUIRED` / `AUTH_INVALID` | 在终端登录或更新 `TRANSAAS_TOKEN`，重启 MCP server |
| `SESSION_EXPIRED` | 重新登录并重启 MCP server |

## 能力边界

- 只覆盖 CLI 与 `transaas serve` 暴露的 MCP 工具，不直接调用后端 H2 或 Record HTTP 接口。
- CLI 只能发起文本翻译；OCR、音频、文档和同传场景只能查询已有记录。
- 不用于修改 `core/`、`client/`、`transport/` 或后端服务源码；源码任务按仓库开发流程处理。
- 不用于其他翻译产品、通用翻译质量评估或生产级批量 API 集成。

## References

- [安装](references/transaas-install.md)：平台下载、PATH 和可执行检查
- [认证与 MCP](references/transaas-auth.md)：浏览器登录、无头环境、MCP 客户端配置
- [文本翻译](references/transaas-translate.md)
- [语种编码](references/transaas-language-codes.md)
- [记录列表](references/transaas-records.md)
- [记录详情](references/transaas-record-detail.md)
- [提词器列表](references/transaas-teleprompters.md)
- [提词器详情](references/transaas-teleprompter-detail.md)
- [创建提词器](references/transaas-teleprompter-create.md)
- [更新提词器](references/transaas-teleprompter-update.md)