跳到主要内容

论文整理与协作规范

本目录用于保存中文译文和来源说明。原始文档、图片、图表和附件在临时目录处理；需要交付的资源上传到 MinIO，通过在线链接引用，不保留在本工程中。默认使用简体中文沟通和撰写文档。

协作原则​

  • 独立判断，优先理解用户的实际目标。不要把用户的诊断或实施方法当作既定事实。发现错误假设或更简单、风险更低的方案时，根据证据直接说明。
  • 能通过代码、文档、日志或只读检查验证的信息，先自行验证。明确区分已验证事实、假设和建议。
  • 不影响产品行为、架构或交付范围的细节，可以采用合理默认值，并简要说明。
  • 自行验证后仍有实质性歧义、涉及未经授权且影响大或难以逆转的操作、需要改变已同意的方向或显著扩大范围时，只提出必要问题，并等待确认。
  • 目标明确、已获授权且变更可局部逆转时，直接执行并验证，不反复请求许可。
  • 用户明确要求讨论、分析或征求意见时，只讨论和进行只读验证，不修改文件。
  • 复杂任务开始前简要说明方法和范围，执行时及时报告关键发现，在确认的方向内持续推进。
  • 回答简洁，使用通俗语言；必要的专业术语应同时解释。说明实际验证范围和未验证内容。

文件组织​

  • 中文译文放在根目录，命名为 YYYY-MM-DD-中文文章名.md。
  • 文件名中的日期默认采用整理日期，时区为 Asia/Shanghai；正文分别记录论文发布日期和翻译日期。
  • Markdown 文件名使用中文译名，产品和算法等专有名词保留原有拼写，以半角连字符分隔日期和标题。去掉冒号等标点，不使用空格。用户指定的中文命名要求优先于参考写作规范中的英文文件名建议。
  • 原始 PDF 仅在翻译和截图时下载到临时目录，交付时不在工程内保留副本或 sources/ 目录。译文和截图清单保留在线原文链接；确需交付原始文件时，将其上传到 MinIO。
  • 图片和图表截图在临时目录生成，分别命名为 cover.png、figure-01.png、table-01.png 和 algorithm-01.png 等，保留原文编号。不要在工程内新建 images/ 等资源目录。
  • 图片和附件使用 MinIO 的永久 HTTPS 链接，不使用本地资源路径或会过期的预签名链接。工程内 Markdown 文档之间的引用可以使用相对路径。向用户交付时提供可点击的文档链接。
  • 协作说明使用标准文件名 AGENTS.md；已有内容应先阅读再修改，不直接覆盖。
  • 临时页面渲染、抽取文本和检查脚本放入临时目录，不混入最终交付文件。

MinIO 资源存储​

  • 连接配置使用下列环境变量。真实访问密钥不得写入 AGENTS.md、译文、脚本、Git 或日志；用户在会话中临时提供的凭据只用于当前进程，不落盘。
环境变量含义与本项目配置
MINIO_ENDPOINT完整服务地址，包含协议及非默认端口；本项目为 https://minio.wangzhy.com，HTTPS 默认端口为 443。
MINIO_ACCESS_KEY访问密钥 ID，必填，不在工程内记录实际值。
MINIO_SECRET_KEY访问密钥，必填，按原值使用，不因外观类似 Base64 而自行解码。
MINIO_BUCKET存储桶，本项目为 picgo。
MINIO_PUBLIC_BASE_URL包含桶路径的公开访问基址，本项目为 https://minio.wangzhy.com/picgo；拼接对象键时不再重复添加桶名。
MINIO_OBJECT_PREFIX对象键前缀，本项目为 paper-blog。
MINIO_ALLOW_INSECURE_CERT是否接受不受信任的服务端证书，取值 true 或 false；按用户配置执行，未设置时为 false。公开链接仍需验证普通 HTTPS 访问是否正常。
MINIO_REGIONS3 签名使用的区域，未设置时为 us-east-1。
  • 对象键采用 ${MINIO_OBJECT_PREFIX}/YYYY-MM-DD-paper-short-name/文件名，例如 paper-blog/2026-11-02-fix-your-life/figure-01.png。日期使用整理日期，时区为 Asia/Shanghai。
  • 使用配置指定的桶，上传时设置正确的 Content-Type。同名文件默认跳过；跳过后仍须校验内容，不能覆盖不同内容或把错误的旧对象写入译文。发生内容冲突时使用新的对象键，或报告冲突。
  • 上传后，用不带认证信息的公开 HTTPS 链接完整读取资源，确认 HTTP 状态、内容类型、字节数和 SHA-256 与源文件一致。不能只凭上传成功就删除源文件。
  • 验证成功后，将 Markdown 中的图片或附件引用替换为 ${MINIO_PUBLIC_BASE_URL}/对象键，再删除本次生成的工程内资源副本及空目录。临时下载、上传清单和辅助脚本放在临时目录，不作为工程交付物。
  • 上传失败或公开访问不可用时，保留临时源文件并说明阻塞，不把无法使用的链接当作已完成的交付。
  • 最终回复说明上传和引用验证结果，并提供包含上述变量名称、可直接复制执行的配置命令；凭据不写入工程文件。

翻译要求​

  • 先核对论文标题、作者、版本、发布日期、原文链接和许可信息。优先下载指定版本，避免网页更新后译文与原文不一致。
  • 默认完整翻译摘要、正文、结论、附录、图注、表注、算法和脚注，不以摘要或解读替代正文翻译。
  • 保留章节、图表、公式、算法和参考文献编号。参考文献的作者、原文题名、出版信息、标识符和链接保留原样，以便检索。
  • 保留公式变量、单位、实验数据、条件、限定词和比较基准。不要把作者报告的实验结果写成独立验证的事实。
  • 首次出现的关键术语给出中文名称和英文名称或缩写，此后统一译法。产品、数据集和算法名称保留规范拼写。
  • PDF 双栏抽取、公式或参考文献存在疑点时，对照页面截图和同版本 HTML 或源码核对。
  • 原文存在疑点时，不擅自更正；确需解释时以“译者注”标明，并与原文区分。
  • 根据原文许可保留署名、原文链接和许可链接，说明翻译及图片裁剪等改动。不要暗示原作者审核或认可了译文。

中文写作规范​

参考阮一峰的《中文技术文档的写作规范》。

  • 使用准确、正式、自然的现代汉语，优先使用短句和主动语态，避免直译腔、过度修饰和指代不明。
  • 一段围绕一个主题，长段落按语义拆分；段落、标题和列表之间留空行。
  • 中文与英文、数字之间统一留一个半角空格；数字与英文单位之间留空格，例如 600 KB。百分数写作 97%。
  • 中文句子使用全角标点；英文标识符、网址、代码和公式保留原有标点。
  • 标题层级连续，不跳级，最多使用四级标题；为方便对照论文，可以保留原文章节层级。
  • 准确区分“提高了”和“提高到”。倍数比较写明基准，不使用“减少了若干倍”这类含义不清的表达。
  • 数值范围优先使用“至”，五位及以上的正文整数添加千分位分隔符。标识符、年份和公式按原样保留。

图表与交付检查​

  • 图表应从原始 PDF 渲染并裁剪，保留完整的坐标轴、图例、标签、单位和表格行列，不用重绘结果替代原图。
  • 截图保持清晰，默认采用 240 dpi 或更高分辨率。不要截入无关正文，也不要裁掉图表内容。
  • 保留图内英文，并在相邻文字中翻译完整图注、表注及必要的标签说明。表格截图之外可补充中文字段解释；算法同时提供可复制的中文步骤。
  • 逐一检查图片，确认无缺失、模糊或截断。记录截图对应的 PDF 页码。
  • 交付前检查章节完整性、公式、数字、引用编号、脚注、图片数量、文档链接及 MinIO 资源链接，确认本次资源已上传并验证，工程内没有遗留本次生成的图片或附件。
  • 未经用户要求，不初始化 Git 仓库、不提交代码、不发布译文。

辅助代码注释​

实现辅助功能时，在关键分支、特殊情况和复杂算法处补充必要的中文注释。用一两句话解释处理原因、实际限制和容易踩的坑，不逐句翻译代码，不编造业务背景。修改逻辑时同步更新相关注释。

最后于 更新