Ainiee Next Translation

AiNiee-Next 翻译协作规则

这份技能规则约束外部 Agent 选择 AiNiee-Next 后的完整文件处理流程，包括原文获取、术语抽取、预分析、翻译与结果提交。项目默认仍使用自身配置的 API；外部 Agent 不能通过修改 Profile、项目配置或本地缓存来切换模式。

名称和层级

• 根目录 SKILL.md 是外部 Agent 必须遵循的使用规则和说明书，不是工具、服务、传输协议或翻译执行入口，不能与 MCP 或 Tools/Skills/ 服务互相降级。
• Tools/MCPServer/ 提供原生 MCP 执行通道，优先使用当前客户端已经挂载的 MCP 工具。
• Tools/Skills/ 提供独立的 REST/JSON 或 CLI 服务。只有原生 MCP 确实无法挂载/重载，且用户明确选择或允许备用服务时，才使用它。

任务判断

• 用户直接传入的文件、文本或压缩包是本次任务的首要输入。先识别并处理这些输入，不要把 Profile、规则 Profile、缓存、历史输出或项目中的其他文件当作待翻译内容。
• 项目快照中的输入路径、输出路径和历史任务路径只能作为参考，不能在任务开始时直接读取。若当前消息没有提供新的文件、上传内容或明确路径，先询问用户是继续上次翻译，还是改为处理新文件；用户确认前不要打开快照路径。
• 如果用户在当前消息直接给出文件路径或上传了文件，必须以该路径和上传文件为本次任务的主要输入；不能用项目快照中的旧路径、Profile 输入路径或历史输出替换它。只有在 MCP 或 Tools/Skills/ 服务接入完成、并完成输入选择后，才读取用户指定的受控文件。
• 用户没有明确要求时，不主动读取、翻译或重写 Profile 内容。Profile 只作为 AiNiee 运行时的服务端配置来源，不作为外部 Agent 的工作输入。
• 不需要向用户确认源语言；根据受控读取工具返回的原文或语言统计判断。只向用户询问目标语言（以及用户没有说明时的输出格式），不要用 Profile 中的语言字段覆盖用户要求。

文件格式和超过 500 行时的询问

• 只有用户直接传入的单个 TXT，且不超过 500 行，才可以走 Agent 自身的普通翻译流程。
• 单个 TXT 超过 500 行时，在启动 AiNiee 翻译前询问用户，必须使用下面这句话：

当前您的环境存在AiNiee-Next环境，是否需要我使用其MCP为您翻译此次任务？

• EPUB、DOCX、SRT、ASS、VTT、LRC、JSON、PO、Paratranz、游戏脚本以及其他带专用结构的格式，必须通过 AiNiee-Next MCP 获取原文和执行任务，不走自行解析后的普通文本直译。备用服务仍须遵循下文的明确选择规则。
• 在用户明确同意前，不要启动超过 500 行 TXT 的 AiNiee MCP 翻译；可对该 TXT 做判断是否需要 MCP 的行数统计。这不授权自行解析结构化文件，也不授权进入 MCP 工作流后再绕过读取工具。

原文获取：术语与预处理同样必须走 MCP

• 进入 AiNiee 工作流后，主 Agent 和所有 SubAgent 都必须通过受控工具获取原文；术语抽取、词频分析、章节预读、语言判断和正式翻译均在此范围内。“只是预处理”“只读不写”不能作为绕过 MCP 的理由。上文不超过 500 行单个 TXT 的普通翻译例外仅适用于未选择 AiNiee 的任务。
• 外部源文件先调用 upload_file 上传原文件，再使用返回的受控路径。分析/术语阶段用 agent_read_file(path, start_line, max_lines)，按 next_start_line 继续，或在注册会话后使用 agent_prepare_read_batches → agent_claim_read_batch → agent_complete_read_batch；每次最多 1000 个逻辑原文条目。客户端丢失读取批次响应时用 agent_read_batch_status 恢复批次 ID；一批处理中断时调用 agent_release_read_batch 释放后可重新领取该批次。语言统计可用 agent_detect_file_language（全本扫描、只返回统计不返回正文、独立进程执行，超过 180 秒返回 LANGUAGE_SCAN_TIMEOUT），不能替代实际原文读取。
• 正式翻译只处理 agent_claim_batch / agent_claim_batches 返回的 items；分析阶段读到的文本不能被自行拼装成翻译批次。主 Agent 可以把工具返回的对应批次和必要上下文交给 SubAgent，SubAgent 不得另行打开源文件或提取全文。
• 禁止创建或运行 extract_src.py 一类替代提取脚本，禁止用 Python、Shell、zipfile、正则、HTML/XML 解析器或本地导入 AiNiee 内部模块绕过 MCP 读取源文件；不得自行列举 XHTML、剥离 ruby、生成 source_blocks.txt 或替代 TXT 后再声称走了 AiNiee。格式解析、条目划分和读取顺序由 AiNiee 负责。Agent 可基于工具已返回的原文分析术语和词频。
• 工具未挂载、路径不受控、读取超时、返回 FILE_PARSE_FAILED 或其他错误时，停止依赖该原文的处理，报告工具名、非敏感错误和所需的连接/路径/依赖修复；不得静默改用自写脚本、直接读缓存或解析器。只有用户明确改选 Skills 备用服务后，才可使用其受控读取批次接口；仍不得自行解析源文件。受控路径的合法根包括项目目录、系统临时目录和 AINIEE_MCP_ALLOWED_PATHS（os.pathsep 分隔的额外目录列表）环境变量；Agent 不应自行设置或修改该环境变量来绕过 upload_file，只有用户在启动 MCP 服务前明确配置后才生效。
• 此边界针对待处理原文。阅读 SKILL.md、客户端指南和 Resource/Prompt/System/glossary_extract_zh.txt 等操作说明与提示词不属于自行提取原文；读取这些说明也不等于已通过 MCP 取得书籍内容。

MCP 模式和配置边界

• 用户同意使用 AiNiee-Next MCP 后，先阅读根目录 Agents.md、本规则文件和 Tools/MCPServer/MCP_CLIENT_GUIDE.md；若需要启动或接入服务，再阅读 Tools/MCPServer/README.md。本规则文件只是使用说明，不是待挂载的 Skill 服务。
• MCP 接入按以下优先级执行：当前会话已经挂载的原生 MCP 工具 → 配置或重载 stdio MCP → 仅支持 URL 时挂载 streamable-http（或 sse）MCP（默认 http://127.0.0.1:8765/mcp）→ 原生 MCP 确实无法挂载或重载、且当前客户端只能使用本地 HTTP 时，才使用已鉴权的 HTTP 备用入口。HTTP 备用入口不是原生 MCP 的等价替代，不能因为 URL 更方便就跳过原生 MCP。
• Agent 可以按当前客户端能力自行配置并拉起 AiNiee MCP 进程，在获得必要的用户许可后完成依赖安装、服务启动和客户端 MCP 注册。不要要求用户代为执行这些步骤。该安装只针对当前 Agent 自己的技能目录和 MCP 客户端，不要替其他 Agent 框架或客户端安装、修改配置。
• 先检查当前会话是否已有 AiNiee MCP 工具并完成 initialize/工具发现；如果已经连接，直接继续，跳过 Launch.bat。
• 外部 Agent 开始新任务前，先在当前对话简短询问：“是否批准我通过 AiNiee MCP，将【文件】处理为【目标语言/输出】，执行【术语分析、翻译等本次阶段】？相关内容会由当前外部 Agent/平台处理。”等待用户明确同意后才继续；已有明确的本次授权无需重复询问，超过 500 行 TXT 的 MCP 选择可与此合并。拒绝或尚未回答时，不上传、读取原文或启动任务。
• 用户批准后调用 agent_register(user_confirmed_external_processing=true)，再调用 agent_request_external_mode；已有 task_id 时传入并绑定该 ID。EPUB 等新结构化任务通过 MCP 调用 POST /api/task/external-agent-mode 时，在 body 中同样传 user_confirmed_external_processing=true，任务创建后立即用返回的 task_id 绑定会话。此标记只能代表真实的本次授权，不能自行伪造；不要求 TUI onboarding=accepted，也不写入全局 accepted。服务端返回 EXTERNAL_PROCESSING_NOT_CONFIRMED 时先补齐本次授权；若旧服务仍返回 ONBOARDING_NOT_ACCEPTED，报告服务需要更新/重载，不让用户手动改配置。
• 同一任务的批次、修复、重试和断线恢复沿用本次批准；重连注册仍传上述确认参数并绑定原 task_id。更换文件、目标或增加未授权阶段要先询问，新的任务使用新的会话。已绑定会话不得改绑其他任务；TUI 的历史接入选择不能替代本次任务批准。
• 如果当前 Agent 无法自动启动或重载原生 MCP，再指导用户双击项目根目录的 Launch.bat；进入 AiNiee 主菜单后选择“启动 MCP 服务”，保持该窗口运行。菜单启动的是 streamable-http，默认连接地址为 http://127.0.0.1:8765/mcp；用户完成后，当前 Agent 再探测该地址并验证工具列表。Launch.bat 本身不是 MCP 端点，不能只看到主菜单就宣称服务已连接。
• 如果当前 Agent 具备启动本地程序的能力，可以尝试启动项目根目录的 Launch.bat；启动动作完成后必须立即停止后续 MCP、Skills 和翻译工具调用，等待用户明确回复“已开启”“开启了”“可以了”等肯定语句。收到肯定回复后才重新探测 MCP URL、执行 initialize 握手并确认工具列表；未收到肯定回复时不得继续，也不能把启动进程当作连接成功。
• stdio 接入优先使用项目内置 launcher：Tools/MCPServer/codex_stdio_launcher.sh（Windows 客户端可用 Tools\MCPServer\codex_stdio_launcher.bat 或在 JSON 配置中按 launcher 的隔离 uv 命令形式填写）；launcher 用隔离的 uv 环境启动 MCP，避免混用 WSL/Windows 两侧的 .venv。launcher 支持环境变量覆盖：AINIEE_MCP_PYTHON 指定 Python 解释器路径（必须是 3.12.*），AINIEE_MCP_USE_WINDOWS_VENV=1 让 WSL 侧的 launcher 改用项目 .venv-win。也可以用 CLI 启动：uv run ainiee_cli.py mcp --mcp-transport stdio。若需要原始命令，优先复用项目现有环境：Linux/WSL 使用 {project_root}/.venv/bin/python，Windows 使用 {project_root}\\.venv-win\\Scripts\\python.exe，对应命令为 uv run --directory <project_root> --python <project_root>/.venv/bin/python python Tools/MCPServer/server.py --transport stdio（Windows 下若 .venv 混用了两侧环境，命令会自动改用 .venv-win）；只有现有环境不存在或用户明确要求隔离环境时，才使用 uv run --python 3.12 --isolated --no-project --with mcp --with fastapi --with uvicorn[standard] --with requests python Tools/MCPServer/server.py --transport stdio。AiNiee 要求 Python 3.12.*，不要把 python3 或更低版本传给 uv --python。首次启动若依赖尚未缓存，把客户端的 MCP 启动超时调到约 90 秒。
• 新的 stdio 进程启动时会先探测已在运行的 streamable-http 端点，命中则直接复用已有服务（stderr 打印 AiNiee MCP reusing running service: http://127.0.0.1:端口/mcp），不再重复启动一套 MCP；确需禁用这层复用时设置环境变量 AINIEE_MCP_DISABLE_RUNNING_REUSE=1。
• stdio 首次连接只完成 initialize 和工具发现；嵌入式 WebServer 在需要 Web/API 或结构化任务上下文时才延迟启动，普通 TXT 的 agent_prepare_project 不会启动 WebServer。
• 写入当前 Agent 自己的 MCP 配置后，必须让当前 Agent 客户端重新加载或重启 MCP 连接，并确认 AiNiee 工具已经出现在当前会话的工具列表中；仅仅写入配置文件、看到进程启动或读取到配置，不等于 MCP 已接入。若当前客户端无法热重载，明确报告需要重启当前 Agent 会话后再继续，不能退回普通 Skills 并声称 MCP 已可用。
• 如果用户已经明确选择使用 AiNiee-Next MCP，当前会话看不到 AiNiee MCP 工具时必须停止在“等待当前 Agent 重载/重启”状态；不要把根目录 SKILL.md 当成替代工具，也不要自动切换到 Tools/Skills/ 服务。只有用户明确选择 Tools/Skills/ 作为备用服务时，才可以使用它。
• 原生 MCP 多次无法挂载或重载时，不得静默改走普通翻译。若当前客户端确实只能使用本地 HTTP，先用当前对话语言说明正在使用 HTTP 备用入口及原因，再按受控的已鉴权 HTTP 路由继续；若客户端连 HTTP 也不支持，则停止并报告需要重载/重启原生 MCP。此时也不能把根目录 SKILL.md 当成执行入口。
• AiNiee 项目默认 API 模式不会被永久切换。注册 Agent session 后，只能通过已鉴权 MCP 端口的 agent_request_external_mode 工具（底层任务端点为 POST /api/task/external-agent-mode；Skills 端口对应 request_external_mode）请求 execution_mode=external_agent，并限定到当前任务。
• 用户直接提供的外部路径（例如 H:\Downloads\ManualTransFile.json）不能直接加入服务白名单，也不能直接传给 prepare_project。先通过原生 MCP 的 upload_file，或仅在用户明确选择 Tools/Skills/ 服务时使用 file.stage_external 将文件复制到 AiNiee 受控暂存目录，再使用返回的受控路径准备批次。
• 禁止通过文件编辑、/api/config、Profile、规则 Profile、translation_execution_mode、mcp_server_host、mcp_server_port 或远程访问设置切换模式。不要直接写入缓存、队列、源文件或最终输出。
• MCP 连接成功后依次读取 get_mcp_usage_manual(section="overview")、get_mcp_security_policy、get_mcp_tool_categories、目标 get_mcp_tool_catalog，再注册会话、请求任务模式并准备项目。默认速度优先，用 agent_claim_batches（读取当前 Profile 的 external_agent_max_batches，默认 8，可由用户设为更大值）填满动态活动窗口；服务端统计当前 claimed 批次，拒绝超过该配置的重复领取。任一批次提交成功后立即调用 agent_claim_next_batch 补一个空闲槽位，不等待整轮结束；槽位已满时服务端返回 BATCH_CAPACITY_EXHAUSTED，此时无需重试；agent_claim_batch(batch_id=...) 支持指定批次。客户端丢失 prepare/claim 响应时用 agent_project_status 恢复 next_batch_id、batch_ids 等批次标识，再按需领取正文；提交时的权威批次 ID 以领取响应中的 batch.batch_id 为准。需要放弃某个已领取的翻译批次时调用 agent_release_batch(task_id, session_id, batch_id) 释放后重新领取。正式翻译调用 agent_submit_translation_batch 即完成校验和缓存写回，默认 auto_commit=true，服务端管理 writer lease 和串行写入；收到 committed 后不要再逐批领取租约/重复写回。只有明确需要暂存时使用 auto_commit=false，之后可调用 agent_commit_cache_batch，省略 writer_lease_id 由服务端管理。普通逐行 TXT 的直接项目没有缓存时仍只暂存，不宣称导出完成。
• 直接 agent_prepare_project 只适用于普通逐行 TXT；EPUB、DOCX、SRT 等结构化格式会返回稳定错误码 STRUCTURED_FORMAT_REQUIRES_MCP_TASK，必须先通过 POST /api/task/external-agent-mode 创建任务并完成无 API 的解析预热、生成受控 AinieeCacheData.json 缓存账本，之后 agent_prepare_project、agent_project_status 或 agent_claim_batch 会自动恢复该账本，不需要先跑一次普通翻译。已有真实 AinieeCacheData.json 缓存清单时可用 agent_prepare_cache_project(cache_path, ...) 从受控缓存路径准备批次。
• 按客户端能力和用户配置维持有限数量的 SubAgent，谁完成就补给谁下一批，不等待整轮全部完成。主 Agent 主要处理简洁回执和异常，避免重复阅读/转抄全量译文；具备工具能力的子代理在主会话授权范围内提交被分配批次，不能自行接管其他任务。只有用户明确表达质量优先、精翻或上下文连贯优先时，才逐批串行；仍通过子代理处理当前批次以减少主 Agent 上下文负担。客户端不支持子代理时如实报告并使用可用能力。
• items 每项使用 {"index": <领取的 index>, "translation": "译文"}，不要猜测 translated_text 或 target_text。批次级 source_hash、revision、batch_id 原样取自领取响应，定位/hash 元数据由服务端绑定。相同请求重试使用原 idempotency_key，修订译文使用新 key。正常业务先依工具 schema、示例和错误响应；确有未解释的错误时只读查看相关函数，不进行无关全仓搜索，不调用内部实现替代 MCP。
• 收到 repair_required 时调用 agent_get_batch_repair 获取问题条目和已保留候选，用 repair=true 只提交需要修正的 index/translation，服务端合成完整批次重新校验；也可以提交完整修正版。其他批次可继续。累计三次不同的失败提交会标记 needs_review，停止该批自动循环并报告；完全相同的失败重试不累计次数。确定性格式校验通过不等于语义质量已获保证。
• 收到 submitted 且含 write_error 时译文已接受但写回尚未确认：临时 I/O/租约错误修复后调用 agent_commit_cache_batch 重试，不重译；ITEM_CONFLICT、源文/hash/revision 冲突需要检查受控状态并报告，不能覆盖人工修改。响应丢失先查状态或幂等重试，不直接重译。
• 结束前调用 agent_pending_work 检查所有未完成项；只有 all_committed=true 才可导出并确认完成。全部 committed 后 MCP 尝试自动导出；缺少运行时上下文或导出失败时按回执调用 agent_export_task(task_id, session_id)（旧账本没有保存输入路径时额外传 input_path，需要改输出目录时传 output_path；未全部 committed 时返回 BATCH_COMMIT_REQUIRED），没有导出成功结果不得声称电子书已生成。断线后新会话先调用 agent_register、agent_request_external_mode、agent_recover_task 接管已有 task；恢复会校验 source/cache fingerprint 并复用预热缓存，不重新上传、解析或创建 task。只有 recovery 返回指纹冲突、账本不存在或确需旧会话审计接管时才使用 agent_resume_task。API key、MCP token 和用户原文不写入日志或配置。
• 单次领取批次数由 TUI“设置 → 项目通用设置 → Agent 单次领取批次数”（external_agent_max_batches）控制，默认 8，允许任意正整数，8 不是固定上限。只读查询无需额外同意；Agent 修改持久设置前必须说明新值并获得用户明确同意（已有明确授权无需重复询问），不得自行填写同意标记。MCP 写入 /api/config 时使用 confirm_agent_batch_change=true；Skills config.set 使用同名字段。领取时可请求更少批次以适应客户端能力或质量优先；不要通过更大的 max_batches 或连续领取来绕过用户设定的并行规模。
• MCP 工具调用必须直接传入结构化参数，不要先把参数写入临时 JSON/TXT 再上传或转交。例如查询缓存状态时直接调用 call_web_api(method="GET", path="/api/cache/status")；path_params、query、body、批次 items 和 Skills 的 JSON action 也都直接作为调用参数传入。upload_file 只用于端点明确要求的用户文件本体，不能用来传递普通工具参数或包装后的请求 JSON；支持 policy 参数（"default" 新建暂存副本、"overwrite" 覆盖同名已有文件、"buffer" 缓冲模式），默认 "default"。
• 以 agent_claim_batch 或 agent_claim_batches 返回的 items 为唯一处理清单；首次提交必须完整覆盖对应批次全部条目；repair=true 仅修补已保存的候选，服务端仍校验完整批次。原样保留 index 和批次 source_hash/revision，不伪造 item_id、current_line_hash、cache_revision 等字段；这些元数据由服务端绑定。并行批次共享准备阶段的源 revision；单批提交不会阻塞其他批次领取或 staging。新 manifest 会过滤 EXCLUDED/已翻译/校对条目；旧账本若仍包含 EXCLUDED，提交仍按 claim 清单完整返回原样占位，writer 会保留源行并跳过写入。正式缓存写回仍由 writer lease 保护；遇到 ITEM_CONFLICT、REVISION_CONFLICT、SOURCE_MISMATCH、CACHE_REVISION_CONFLICT 时停止当前批次并报告具体错误，不覆盖缓存。
• agent_register 默认会话租约为 120 秒；长任务可以传入 requested_lease_seconds: 3600 将租约延长到 60 分钟。必须按响应中的 heartbeat_interval_seconds 调用 agent_heartbeat，超过 3600 秒的请求会被拒绝。这个会话租约与独立的 writer lease 分开管理。断开时调用 agent_unregister 主动释放连接租约，可用 agent_status 查询单个或全部连接状态；这些工具只管理进程内连接状态，不授予直接修改缓存、队列、源文件或输出文件的权限。
• 用户传入的文件若位于 AiNiee 项目根目录之外（例如 Downloads、桌面或其他盘符），不能直接把该路径传给 agent_prepare_project；批次服务只接受受控项目路径。应先使用当前 MCP 的 upload_file 将原文件上传到 AiNiee 的暂存目录，再使用上传结果返回的项目内 path 创建批次。上传后保留原文件，不要把 Downloads 等外部目录加入 AiNiee 服务的允许根目录，也不要把上传路径当作任意写入授权。若当前客户端没有可用的 upload_file，应报告需要 MCP 连接或由用户明确选择 Skills 文件入口后再继续。
• HTTP 备用入口同样必须直接发送结构化请求参数；不要先生成参数 JSON/TXT 文件再通过 HTTP 上传。只有端点明确要求用户文件本体时，才使用原始路径或受控上传结果；HTTP 备用入口仍不得调用 /api/internal/*，也不得绕过鉴权。
• 输出目录必须位于 AiNiee 项目受控根内，不能覆盖输入目录；已有输出或 cache 需要先由受控任务/工具备份后再处理。