Skip to content

docs: 用平实语言重写用户向文档,补齐英文缺页 - #23

Merged
1w1w11w1 merged 1 commit into
AUTO-MAS-Project:masterfrom
1w1w11w1:docs/plain-language
Aug 27, 2026
Merged

docs: 用平实语言重写用户向文档,补齐英文缺页#23
1w1w11w1 merged 1 commit into
AUTO-MAS-Project:masterfrom
1w1w11w1:docs/plain-language

Conversation

@1w1w11w1

Copy link
Copy Markdown
Contributor

背景

面向普通用户的页面存在几类共同的阅读障碍:

  • 内部实现术语直接暴露:如"脚本实例任务""任务实例序号升序""TaskMapping",以及 weekly_divergent_stable_modeStage.Channel 等配置键名。
  • 自相矛盾:调度队列的提醒块同时写着"脚本串联运行"和"运行队列会同时运行该队列的所有脚本"。
  • 反义病句march7th.mdsra.md 中"以便出现不必要的异常""以便给自己带来不愉快",字面意思与本意相反。
  • 重复解释m9a.md 把配置隔离机制讲了三遍(正文、独立章节、FAQ)。

改动

文案层面

  • 术语换成用户语言。general.md 的成功/失败判定原本是一段嵌套条件从句,改为按"是否填写成功日志"分列的表格。
  • 章节按用户实际看到的症状重组,例如 FAQ 标题从"后端启动失败"改为"软件一直在报 Network Error"。
  • 每个设置项先说清"通常不用改",再说例外情况。
  • hsr.md 去掉 PR 编号与内部标识符,改为按实际界面描述;"找不到 HSR 脚本类型"改为指向下载页更新。
  • m9a.md 合并重复章节,FAQ 从九条精简到三条,只保留正文未覆盖的内容。
  • 删除 script-guide/index.md 末尾与上方目录重复的"阅读建议"。

净减约 280 行。

修正两处事实错误

  1. 模拟器权限因果写反。原文(及我的初版重写)表述为"管理员进程无法接管非管理员实例",实际是已有非管理员实例时无法再以管理员权限启动新实例。中英文均已按实际行为修正。

  2. 配置导出占位符。英文文档写作 C:/ScriptRoot,但该字符串在主仓库中不存在(全仓库搜索零结果)。实际代码 app/core/config.pyremove_privacy_info 硬编码为中文字符串 C:/脚本根目录,未做本地化。已按实际行为修正并注明该字符串不翻译。

    同时补充了两边文档此前均缺失的脱敏行为:

    • 脱敏只覆盖 Info.RootPathScript 下的 ScriptPathConfigPathLogPathTrackProcessExe
    • 这四项若位于 AppData 下会被改写为 %APPDATA%/...,Windows 用户名不会泄漏(对 SRA 用户尤其相关,其配置目录正在 AppData\Roaming\SRA)。
    • Game.Path(游戏/模拟器路径)不脱敏,原样导出。
    • remove_privacy_info 在本地导出 JSON 和上传分享中心两条路径上都会调用。

补齐英文缺页

  • en/docs/script-guide/sra.md —— 修复 .vitepress/config/en.ts 中指向该路径的既有死链。
  • en/docs/advanced-features/game-sign.md —— 此前英文用户完全看不到签到功能,已接入英文侧边栏(位置与中文一致)。

顺带修正中文原文一处编号错误sra.md 方式一第 13 步原写"重复步骤 8-12",但第 8 步是退出配置页,加用户的循环从第 9 步开始,已改为 9-12。

与 master 的关系

本分支基于最新 master(37819b7)。maaend.md 在 master 上被重写过(a1f3673/28320c8,改动了密码字段说明、配置文件来源命名、模拟器版本要求,并将森空岛章节迁至签到工具),因此该文件的文案精简是基于 master 新版重做的,master 引入的新事实全部保留:

  • 模拟器需 v5.4.0 或公测版
  • 密码字段目前无作用
  • 配置文件来源(脚本级/用户级)
  • 接管具体游戏配置
  • 推荐 MAS 自建切号
  • 森空岛已迁至签到工具(并补了指向签到工具页的链接)

已确认未删除 master 的任何文件,planbook 侧边栏条目未受影响。

验证

  • npx vitepress build 通过。
  • 新增两页均正常产出 HTML,sra.md 页内 #differences 锚点可跳转。
  • 新页引用的 15 张图片全部存在(复用中文版共享图)。
  • 两份侧边栏配置的所有链接均能解析到实际文件,无死链。

待确认

英文通知页的 授权码 我保持译为 "authorization code"(与文档原有译法一致),并补充说明 QQ/163 称授权码、Gmail/Outlook/Yahoo 称 app password,是同一事物。若软件界面英文标签实际用的是 "app password",应反过来统一。

面向普通用户的页面此前存在几类阅读障碍:内部实现术语(脚本实例任务、
TaskMapping、内部配置键名)直接暴露给用户;调度队列提醒块自相矛盾;
部分句子字面意思与本意相反;同一机制在多处重复解释。

本次改动:
- 术语改为用户语言,判定逻辑等长句改为表格
- 章节按用户看到的症状重组,先说为什么在意再说怎么做
- 修正 march7th/sra 中"以便出现不必要的异常"等反义病句
- 修正调度队列"串联运行"与"同时运行所有脚本"的矛盾表述
- 合并 m9a 中重复三遍的配置隔离说明,FAQ 去重
- hsr 移除 PR 编号与内部标识符,改为按实际界面描述

同时修正两处事实错误:
- 模拟器权限因果写反,实为已有非管理员实例会阻止新实例以管理员启动
- 配置导出占位符英文文档写作 C:/ScriptRoot,实际代码硬编码为
  C:/脚本根目录;并补充此前两边均缺失的 %APPDATA% 脱敏行为与
  游戏路径不脱敏的说明

新增英文页面:
- en/docs/script-guide/sra.md(修复英文侧边栏既有死链)
- en/docs/advanced-features/game-sign.md(并接入英文侧边栏)

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @1w1w11w1, your pull request is larger than the review limit of 150,000 diff characters

@1w1w11w1
1w1w11w1 merged commit 92ce362 into AUTO-MAS-Project:master Aug 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant