project-cn

概述

把用户提供的项目根目录 A 复制为同级目录 A-CN，并满足下面三条：

• 原始 A 绝不修改。
• A-CN 中先完整保留所有复制过来的原始文件。
• 仅对文档文件和代码文件额外新增同目录 -CN 副本，其他文件只复制不增强。

默认目标目录策略：

• 如果 A-CN 已存在，默认先删除旧目录再重建。
• 只有用户明确要求保留旧结果时，才使用 --keep-existing。
• 目标目录名只能是“用户给出的目录名 + -CN”，禁止擅自改成 -中文版、-中文, -zh 或其他后缀。

默认排除目录策略：

• 评估和复制时默认跳过 .git、vendor、node_modules、dist、build、.venv、__pycache__、coverage 等明显不该进入翻译流程的目录。
• 如果用户还想额外排除某些目录，可以追加 --exclude-dir <name>。

Python 缓存约束：

• skill 自带的 Python 脚本和测试模块默认要禁用 .pyc 写盘，避免在 skill 目录生成 __pycache__。
• 交付前必须清理已存在的 __pycache__ 目录。

资源导航

• scripts/job_runner.py 结果导向的高层入口。默认把除翻译文件之外的内部产物统一放到 A-CN/AAA-translate-output。
• scripts/prepare_job.py 低层调试入口。用于“整体工作量评估”以及“复制目录并生成清单”。
• scripts/verify_outputs.py 用于在处理完成后检查 -CN 文件是否齐全。
• references/document-rules.md 文档翻译硬约束。
• references/code-rules.md 代码中文注释增强硬约束。

必须遵守的原则

• 先完整评估，再决定是否继续执行。
• 除非任务确实大到明显超出单次承载，否则默认继续整项目执行。
• 不能因为文件多、文本长、预计 token 高就擅自放弃、缩减范围或只做一部分。
• 必须把用户明确给出的路径当作项目根目录，绝不因为“根目录下面只有一个子目录”就自动下钻并把那个子目录当成真正根目录。
• 文档翻译和代码注释增强必须由当前模型直接完成，不能调用外部翻译 API、外部注释 API 或在线机器翻译服务。
• 文档处理必须忠实直译，不总结、不润色、不扩写。
• 代码处理只能翻译或新增中文注释，不能改代码逻辑。
• 默认只对外关注 A-CN 结果目录；其余内部产物必须统一进入 A-CN/AAA-translate-output，不要散落到项目根目录或系统临时目录。

输出目录规则

假设输入目录为：

C:\work\A

则默认输出为：

C:\work\A-CN

其中：

• 项目翻译结果文件直接写在 A-CN 的对应目录下。
• 除翻译结果之外的内部产物统一写到：

C:\work\A-CN\AAA-translate-output

当前内部产物文件名固定为：

• translate-job.json
• translate-manifest.json
• translate-progress.json
• translate-originals-lock.json
• translate-verify-report.json
• translate-final-report.txt

禁止行为：

• 不要把 scan_result.json、manifest.json、report.json、临时日志或任何额外 JSON 写回原项目目录 A。
• 即使使用低层调试入口 prepare_job.py --output 或 job_runner.py report --output，输出路径也不得落在源目录 A 之内。

文件分类

A 类：文档文件

脚本会把下列文件归类为 document：

• .txt
• .md
• .markdown
• .rst
• .adoc
• .text
• .mdx
• 无扩展名但文件名属于 README、CHANGELOG、CONTRIBUTING、LICENSE、NOTES、GUIDE、FAQ、MANUAL

处理结果：

• 原文件保留。
• 新增同目录 -CN 文档副本。

B 类：代码文件

脚本会把常见源码文件归类为 code，包括但不限于：

• .py
• .js
• .ts
• .tsx
• .jsx
• .java
• .go
• .rs
• .c
• .cpp
• .h
• .hpp
• .cs
• .rb
• .php
• .swift
• .kt
• .scala
• .sh
• .bash
• .sql
• .html
• .css
• .scss
• .vue
• .svelte
• Dockerfile
• Makefile
• CMakeLists.txt

处理结果：

• 原文件保留。
• 新增同目录 -CN 代码副本。

C 类：其他文件

配置、资源、Office、PDF、音视频、数据库、压缩包、模型文件、二进制文件等归类为 other。

处理结果：

• 只复制，不生成 -CN 副本。

大项目执行协议（新增）

当项目规模很大、轮次很多、可能跨多次会话或多个 agent 处理时，必须使用下面这套硬协议：

状态与证据：

• 超大项目必须走 manifest + progress 双文件驱动，不能只靠上下文记忆。
• translate-manifest.json 是稳定任务索引，负责 file_id、批次和 priority_tier；translate-progress.json 是动态进度账本，负责记录 pending、in_progress、completed、failed、skipped。
• translate-originals-lock.json 用来保护源目录和复制后的原始文件；最终 report 必须校验这两个区域有没有被误改。
• 预检优先于批量执行；如果 preflight_summary 还没读完，不得直接进入整批处理。
• 不信任子代理自报完成；只有 mark 之后的磁盘结果和最终 report 才算有效证据。
• 禁止绕过自动化脚本；必须通过 job_runner.py、verify_outputs.py、headless_runner.py 这些正式入口推进状态机。
• 禁止将调试/报告文件写到项目根目录；像 scan_result.json、final_report.json、translate-*.json、translate-*.txt 这类运行时产物只能进入 A-CN/AAA-translate-output。
• verify_outputs.py 除了校验目标目录结果，还必须检测 source_root_pollution，用于发现运行时文件被误写回源目录。

上下文装载：

• status.summary.context_usage_hint 是上下文装载控制提示，后续 agent 每次继续任务前都必须先读。
• context_usage_hint.completed_file_context_policy 必须视为硬约束；默认策略是 metadata-only-unless-explicit-reopen。
• 已完成文件默认只保留 file_id、rel_path、category、status 等元数据，禁止把 copied_file 或 cn_file 的全文再次带进上下文。
• 只有在校验失败、单文件排障或用户明确要求回看某个已完成文件时，才允许显式重开该文件；而且只能按单文件最小范围读取，不得把历史完成文件整批重新装入上下文。
• 恢复下一批时，默认只读取 translate-progress.json、translate-manifest.json、SKILL.md、规则文件以及当前批次待处理文件，不回灌已完成文件全文。
• 下一批文件只能从进度账本里取；禁止靠记忆判断哪些文件已经处理过，哪些还没处理；禁止未读取 translate-progress.json 就继续下一批。

分档与用户闸门：

• 大项目评估时必须先理解整个目录，再按“档位 + 文件类型”汇总，而不是直接扎进某个子目录开做。
• 大项目评估时必须先生成 summary.project_profile，先由 AI 判断这个项目更像 skill、Web 应用、Python 应用、后端服务，还是通用工程，再决定哪些目录要动态提升。
• summary.project_profile.user_summary 必须生成一段用户可读摘要，直接告诉后续 agent 这个项目被判断成什么类型、固定 1 档是什么、动态提升到 1 档的是什么、首轮先看什么。
• start、status、report、scope 必须同时给出 user_message 和 internal_reason；为兼容旧调用，可以保留 operator_advice，但它只能等于 user_message。
• 1 档、2 档、3 档内部都要继续区分 document、code、other，不能只按目录粗暴划分。
• 1 档是“核心理解层”，优先放 README、CHANGELOG、CONTRIBUTING、LICENSE、agents/ 目录、核心 API、前后端入口脚本、核心依赖清单等。
• agents/ 目录属于固定进入 1 档的核心目录，不需要再等项目画像命中才提升。
• commands/、hooks/、某些入口目录或根文件，允许根据 summary.project_profile 动态提升到 1 档；也就是说，有些内容永远在 1 档，有些内容要看项目用途再判定。
• 2 档是“重要扩展层”，优先放 docs 目录中的重要说明、指南、参考文档、重要支撑代码和工具脚本。
• 3 档是“外围噪声层”，优先放 tests、fixtures、examples、历史 plan 文档、archive、legacy、draft 等低优先级内容。
• 默认自动开始 1 档。
• 1 档 完成后必须暂停并问用户是否进入 2 档。
• 2 档 完成后必须暂停并问用户是否进入 3 档。
• 用户选择必须通过状态命令写入作业文件，不能只靠聊天记忆。
• 对于超大型项目，agent 不得默认从 3 档开始，也不得在未经确认的情况下直接把 1/2/3 档全部跑完。

批次、验证与并行：

• 超大任务按批次推进，不做超大会话；宁可多轮 resume，也不要在一个超长上下文里硬撑到结束。
• 默认每 20 个文件强制刷新一次规则文件，并重新读取 SKILL.md、references/document-rules.md、references/code-rules.md、translate-progress.json、translate-manifest.json。
• resume 只能继续 pending 或显式允许重试的 failed，completed 不得重跑。
• 每处理完一个文件，就要立刻把结果落盘到 translate-progress.json，不能等整批结束再统一回写。
• 文档和代码都只能写 cn_file，不得改 copied_file，不得改源目录 A。
• 这条规则用 plain text 再写一次：不得改 copied_file，不得改源目录。
• 如果一个批次拆给多个子代理，每个子代理在接手自己的 file_id 后，必须立刻回写一次 heartbeat，后续按固定间隔继续回写子代理心跳。
• 主 agent 或调度器必须定时运行 watchdog 巡检活跃批次，确认子代理没有卡住；不要等到整批超时后才发现问题。
• 如果 watchdog 发现首次心跳缺失、心跳超时或子代理卡住，必须先介入处理卡住项，再决定是否重分配文件或继续当前批次。
• watchdog 的返回结果里必须包含 recommended_actions 建议动作清单；主 agent 先按这份清单做介入、重分配或替换子代理，不要自己凭印象猜下一步。
• 默认按批次顺序推进，不默认并行；多子智能体并行只作为可选模式。
• 如果启用多子智能体，所有子智能体必须共享同一个 AAA-translate-output 状态目录，先明确文件归属，再由主 agent 负责切批、汇总结果和最终校验。

推荐大项目执行顺序：

1. start 生成 translate-manifest.json、translate-progress.json、translate-originals-lock.json
2. 先读取 summary.priority_tiers
3. 再读取 summary.project_profile，看项目画像、识别信号、固定 1 档规则和动态提升规则
4. 先向用户汇报 1 档、2 档、3 档的文件量，以及每档里的 document、code、other
5. 如果 priority_tier_decision_recommended = true，默认自动开始 1 档
6. 1 档 完成后，必须暂停并让用户决定是否放开 2 档
7. 2 档 完成后，必须暂停并让用户决定是否放开 3 档
8. 每处理完一个文件就更新一次进度账本
9. 每满 20 个文件强制刷新一次 skill 规则
10. 如中断，使用 resume
11. 全部处理后，使用 report

标准流程

1. 接收项目根目录

拿到用户给出的项目根目录绝对路径，例如：

C:\work\A

这里的 A 就是唯一合法根目录。

• 如果 A 下面只有一个子目录，也仍然把 A 当根目录处理。
• 只有用户明确说“请处理 A\child”时，才允许把 child 当根目录。

2. 先做整体评估（禁止跳过！）

强制要求：必须运行脚本，禁止手动处理

python "<skill_dir>\scripts\job_runner.py" start "<src_root>"

警告：

• 禁止绕过脚本直接手动扫描文件
• 禁止用自己的判断代替脚本的分类结果
• 如果脚本不存在，立即停止并告知用户，不要手动替代
• 脚本会自动生成 manifest 清单，必须按清单处理，不得遗漏

这个命令会：

• 先完成整体评估。
• 默认删除旧的 A-CN 后重建复制目录。
• 把内部产物写入 A-CN\AAA-translate-output。
• 返回 job_id、job_dir、dst_root 和 summary。
• 生成 translate-manifest.json 清单，列出所有文件及分类（A类文档、B类代码、C类其他）

必须先查看返回结果里的 summary，重点读取：

• total_files
• document_files
• code_files
• other_files
• llm_files
• estimated_text_chars
• estimated_rounds
• estimated_input_tokens
• estimated_tokens_low
• estimated_tokens_high
• estimated_minutes_low
• estimated_minutes_high
• risk_flags
• requires_confirmation
• excluded_dirs
• priority_tiers
• priority_tier_decision_recommended
• priority_tier_recommended_scope

同时必须读取 summary.preflight_summary，至少检查：

• preflight_summary.source_root_signature
• preflight_summary.hidden_dir_count
• preflight_summary.candidate_output_root
• preflight_summary.requires_user_confirmation
• preflight_summary.confirmation_reason

3. 判断是否需要先提醒用户

当 requires_confirmation = true 或 priority_tier_decision_recommended = true 时，必须先告诉用户：

• 为什么这是超大任务。
• 预计总耗时范围。
• 预计 token 范围。
• 风险点是什么。
• 1 档、2 档、3 档各有多少文件。
• 每档中的 document、code、other 各有多少。
• 推荐范围是 priority_tier_recommended_scope 指向的哪一档组合。
• 如果只是“档位闸门建议”，默认先跑 1 档，不要在一开始就默认放开 2/3 档。
• 当 1 档 跑完后，再让用户明确选择：只做 1 档、先做 1+2 档、全部 1+2+3 档、或显式跳过 3 档。

当 preflight_summary.requires_user_confirmation = true 时，还必须额外说明：

• `source_root_