Skip to content

docs: 统一多语言文档生成（源文件驱动、生成文件不入库） - #760

Open
PtJade-Ceramic wants to merge 52 commits into
maboloshi:gh-pagesfrom
PtJade-Ceramic:ISSUE_TEMPLATE-test
Open

docs: 统一多语言文档生成（源文件驱动、生成文件不入库）#760
PtJade-Ceramic wants to merge 52 commits into
maboloshi:gh-pagesfrom
PtJade-Ceramic:ISSUE_TEMPLATE-test

Conversation

@PtJade-Ceramic

@PtJade-Ceramic PtJade-Ceramic commented Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

简介

将议题模板、贡献指南（CONTRIBUTING）与仓库/扩展自述（README）的多语言文档统一为「YAML 源文件 + Jinja2 模板」的自动化生成流程。

生成文件不入库，由云端 CI 在默认分支自动生成并提交；开发者只需维护源文件。

变更内容

  • 源目录：script/multilingual-docs/ 下的 YAML 源文件 + *.md.j2 Jinja2 模板
  • 统一生成：CONTRIBUTING、仓库 README、vscode 扩展 README、议题模板均由 script/manage_templates.py 生成简体/繁体版本
  • 依赖管理：依赖统一从 script/requirements.txt 安装（由 pyproject.toml / --requirements 生成）
  • 生成文件不入库：.gitignore 忽略生成文件并 git rm --cached 移除已跟踪文件；云端 CI 在默认分支用 git add -f 自动生成并提交
  • pre-commit 钩子：源文件变更时自动验证并检测手动修改/过时的生成文件，不一致时提示并交互询问 Y/N；支持 --doc-dir 重定向输出与 GIT_HOOK_NONINTERACTIVE
  • 钩子测试：test/test_pre_commit_hook.sh 覆盖「阻止手动修改 / 放行无关改动 / 生成文件不入库」三场景
  • CI：check_issue_template_consistency.yml 校验 + 钩子测试 + 默认分支自动生成提交
  • 贡献指南：新增 Windows 开发者注意事项（常见坑、WSL 测试环境）与多语言文档工作流说明

验证

  • manage_templates.py --check 全部通过（OpenCC 校验 CN/TW 一致性）
  • test/test_pre_commit_hook.sh 在 Windows 与 WSL 均通过
  • PR CI 检查全部通过

应先于 #758 审查和合并

@PtJade-Ceramic
docs(ISSUE_TEMPLATE): 统一管理议题模板的简体中文和繁体中文版本
413e3d6 
技术性：
- 添加 `script\multilingual-issue-templates\bug-提交.yml` 作为现有议题模板的唯一多语言源文件
- 添加 `script\manage_templates.py` 验证每个语种的纯度（防止简繁混杂），赋能本地验证和云端持续集成（CI）
- 添加 `.githooks\pre-commit` 在提交前验证议题模板，阻止手动更改单语言模板
- 添加 `.github\workflows\check_issue_template_consistency.yml` 在云端验证和生成议题模板
- 添加 `pyproject.toml` 给出依赖；添加 `script\.gitignore` 忽略自动生成的 `requirement.txt`
- 更改 `.gitignore` 将 Python 虚拟环境纳入其中（见 https://docs.python.org/3/library/venv.html ）
- 添加 `CONTRIBUTING.md` 给出今后议题模板的维护指南

编辑性：
- [breaking change] 更改议题模板中“预期”和“实际”小节的 ID
- 议题模板中添加空行，改进排版
@PtJade-Ceramic
🔧 chore(hooks): 统一 pre-commit 对生成文件的校验
af6d1da 
- 区分源文件、生成模板和生成贡献指南三类暂存内容
- 手动修改生成文件时先运行脚本再比对差异并阻止提交
- 源文件变更时自动生成模板并纳入暂存区
- 修复直接编辑 CONTRIBUTING 文档时无法拦截的问题

👷 ci(multilingual): 扩展多语言文件一致性检查

- 将工作流重命名为“多语言文件一致性”
- 新增 CONTRIBUTING.md 与 CONTRIBUTING_zh-TW.md 的一致性校验
- 更新流程图，展示源文件生成议题模板和贡献指南的流程
@PtJade-Ceramic
♻️ refactor(templates): 用 Jinja2 模板替代硬编码文档渲染
f947664 
- 新增 Jinja2 依赖到 pyproject.toml，用于模板化生成多语言文档
- 移除 _render_doc 函数，改用 Jinja2 Environment 加载 .md.j2 模板
- 新增 CONTRIBUTING.md.j2 通用递归模板，结构与层级完全由 YAML 键顺序及 heading 嵌套推断
- 启用 StrictUndefined，模板缺失字段时立即报错，避免生成不完整文档
@PtJade-Ceramic
♻️ refactor(docs): 统一管理多语言文档生成与贡献者墙
8fb126e 
- `README`、`vscode-extension/README` 与 `CONTRIBUTING` 统一走 Jinja2 + YAML 源文件
- 源目录 `multilingual-issue-templates` 更名 `multilingual-docs`
- 贡献者墙自动写入 `README.yml`（`update_contributors_images.yml` + `update_contributors.py`）
- `pre-commit` 钩子覆盖三份生成文档，并强制 LF 行尾
- 单次使用符号内联
@PtJade-Ceramic PtJade-Ceramic changed the title docs(ISSUE_TEMPLATE): 新工作流程统一管理议题模板 docs: 统一管理议题模板、贡献指南与自述的多语言生成 Aug 2, 2026
@PtJade-Ceramic
PtJade-Ceramic marked this pull request as ready for review August 2, 2026 17:15
@PtJade-Ceramic
PtJade-Ceramic marked this pull request as draft August 2, 2026 17:29
@PtJade-Ceramic
🐛 fix(hooks): 阻止手动修改生成文件 + 完整钩子测试
8a9fa51 
- 移除无条件运行的生成脚本，`git diff HEAD` 检测已暂存的手动修改，阻止提交并打印差异
- 新增 `test/test_pre_commit_hook.sh`：临时 git 仓库重演钩子行为
  - 动态检测 GFM 块类型 × 行首/行中/行尾 + 列表/引用/alert 空行断块
  - 源文件变更自动生成纳入、无关改动放行
- CI 接入钩子测试；`chmod +x` 保证 Linux 钩子可执行；trap 清理失败不阻塞
@PtJade-Ceramic
PtJade-Ceramic marked this pull request as ready for review August 2, 2026 18:29
@PtJade-Ceramic
PtJade-Ceramic marked this pull request as draft August 2, 2026 18:31
PtJade-Ceramic and others added 2 commits August 3, 2026 03:32
@PtJade-Ceramic
♻️ refactor(docs): 生成文件不入库，由 CI 自动生成
8e17a19 
- `git rm --cached` + `.gitignore`：自述/贡献指南/扩展自述/议题模板等生成文件不再入库
- 钩子：源文件变更时生成到临时目录与工作区比对，检测手动修改生成文件并阻止
- `manage_templates.py` 加 `--doc-dir` 支持输出重定向
- CI：默认分支 `git add -f` 生成并提交；PR 验证 + 测试钩子
- 测试脚本适配“手动修改阻止 / 生成文件不入库 / 无关放行，全通过”
t
✨ feat(hooks): 不一致时提示重新生成并交互询问 Y/N
3939c1e 
- 检测到生成文件与源文件不一致时，列出文件并提示改源文件或重新生成预览
- 交互询问 y/N：Y 重新生成到工作区并继续提交；N 取消提交
- 钩子 stdin 默认 /dev/null，交互提交时从 /dev/tty 读取
- 新增 GIT_HOOK_NONINTERACTIVE，供测试/CI 非交互环境默认 N
- 测试脚本验证"重新生成"提示，三场景通过
t
📝 docs(contributing): 为 Windows 开发者总结坑并建议在 WSL 测试
68c60cd 
- 新增"Windows 开发者注意事项"：exec 位、CRLF/LF、钩子 stdin、PEP 668 常见坑
- 建议在 WSL 中测试以接近云端 CI，附 venv 准备步骤（依赖从 script/requirements.txt 安装）
@PtJade-Ceramic
PtJade-Ceramic marked this pull request as ready for review August 2, 2026 21:39
@PtJade-Ceramic PtJade-Ceramic changed the title docs: 统一管理议题模板、贡献指南与自述的多语言生成 docs: 统一多语言文档生成（源文件驱动、生成文件不入库） Aug 2, 2026
@maboloshi
maboloshi requested a review from Copilot August 3, 2026 01:30
Copilot AI reviewed Aug 3, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@PtJade-Ceramic
feat: AI 代码审查工作流（DeepSeek，fork 自建实例）
7f32338 
- script/ai_review.py：拉取 PR diff → 调 DeepSeek → 生成结构化中文审查
- .github/workflows/ai-review.yml：pull_request 自动审 + /review 按需 + workflow_dispatch

说明：工作流需位于默认分支才能响应 issue_comment / workflow_dispatch / schedule 触发。
@PtJade-Ceramic
appbot
5fd19fa
@PtJade-Ceramic
generalize
e3df5e0
@PtJade-Ceramic

PtJade-Ceramic commented Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Tip

@maboloshi 请安装 GitHub App gh-chinese-ai-reviewer 到您的账户 + 仅 github-chinese 仓库。
好处：任何用户可随时在 PR 评论 /review 请求 AI 审查，或提交后自动审查；每次审查使用请求者自己的 DeepSeek 额度，仓库不存任何密钥；审查以机器人 gh-chinese-ai-reviewer[bot] 身份发布（不占用任何用户账号）。可随时在 App 设置中撤销安装。
FYI: PtJade-Ceramic#5 (comment)

gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .github/workflows/check_issue_template_consistency.yml
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .githooks/pre-commit
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread script/.gitignore Outdated
@PtJade-Ceramic
fix(review): 增强增量过滤——按任一变更文件判定已解决
e5335e1 
- 路径提取：排除 #! shebang，支持带已知扩展名的裸文件名（如 manage_templates.py）
- 判定：提到任一已变更文件（或其 basename）即视为可能已解决
- 修复 #3/#4/maboloshi#6/maboloshi#7/maboloshi#8 等"已修复却误报未解决"的问题（从保留 6 条降到 3 条）
@PtJade-Ceramic
chore(docs): script/.gitignore 补末尾换行
49dd602
@gh-chinese-ai-reviewer

This comment has been minimized.

Sign in to view
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .gitignore
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .github/workflows/check_issue_template_consistency.yml
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .github/workflows/update_contributors_images.yml
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .githooks/pre-commit
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread script/manage_templates.py
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread script/manage_templates.py
@PtJade-Ceramic
fix(docs): 修复审查提出的健壮性问题（manage_templates 与 contributors workflow）
da83f99 
- _tr: ctypes 控制台代码页调用用 try-except 包裹（#5）
- _generate_requirements: 捕获 tomllib 解析/KeyError 异常（maboloshi#7）
- _collect_headings: 非 dict 节点安全返回 + heading 判空（maboloshi#8）
- _resolve/_check_node: CN/TW 判断去掉 len==2 限制，改为仅检查键存在（maboloshi#9）
- update_contributors_images: 改用 git diff 检测源文件 README.yml（生成文件未跟踪，git diff 检测不到）（#3）
- maboloshi#10(eol=crlf 合理拒绝)、maboloshi#11(已实现 if -not $env:LANG) 不修改
@PtJade-Ceramic
feat(review): 用户明确拒绝的意见放入折叠区块
1eb0237 
- 增量规则：若历史意见已被用户明确拒绝（不采纳/不同意/没必要/NO 等），
  本次审查中若仍存在则用 <details> 折叠区块收纳，标注『用户已拒绝，仅存档参考』
- summary 结构说明补充折叠区块格式示例
- 避免用户已否决的问题在正文反复突出
@gh-chinese-ai-reviewer

This comment has been minimized.

Sign in to view
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .gitignore
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .github/workflows/check_issue_template_consistency.yml
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .githooks/pre-commit
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .gitattributes
@PtJade-Ceramic
feat(ci): 贡献者头像变更由 CI 定时自动检测并更新源文件与生成文件
fd7e8c6 
- update_contributors_images.yml 增加 schedule 每周一 03:00 UTC 自动触发
- 自动检测脚本/multilingual-docs/README.yml 源文件变更，重新生成 README.md 等并自动提交
@gh-chinese-ai-reviewer

gh-chinese-ai-reviewer Bot commented Aug 12, 2026

Copy link
Copy Markdown

🤖 AI 审查（DeepSeek）— PR #760

概览

本次 PR 将多语言文档生成流程重构为「YAML 源文件 + Jinja2 模板」模式，生成文件不入库，由 CI 自动生成提交。整体设计合理，但存在若干关键问题：.gitignore 忽略根目录 README 导致仓库主页空白风险、.gitattributes 对 .cmd 文件使用 CRLF 可能引发跨平台问题、CI 自动提交存在权限与循环触发风险、钩子脚本在 Windows 下可能失效等。

发现的问题

🔴 阻断

  1. .gitignore 忽略根目录 README.md 和 README_zh-TW.md（.gitignore 第 18-19 行）（上次已提出，仍未解决）：

    • 这会导致仓库主页在生成文件未提交时为空，且 PR 合并后若 CI 未及时生成，主页将空白。建议改为忽略 script/multilingual-docs/ 下的生成文件，或确保 CI 在合并后立即生成。

  2. CI 自动提交可能因权限不足而失败（.github/workflows/check_issue_template_consistency.yml 第 66-79 行）：

    • 使用 GITHUB_TOKEN 推送提交到默认分支，但该 token 默认无写权限，且推送会触发新的 workflow 运行，可能导致循环。建议使用具有写权限的 PAT 或 workflow_dispatch 触发，并添加 on: push 的路径过滤避免循环。

  3. .gitattributes 中 script/manage.cmd text eol=crlf 可能导致跨平台问题（.gitattributes 第 6 行）（上次已提出，仍未解决）：

    • 存储为 LF，检出为 CRLF，但若用户 core.autocrlf 设置为 input，可能不一致。建议统一为 text eol=lf。

🟠 重要

  1. pre-commit 钩子中 read -r answer < /dev/tty 在 Windows 下不可用（.githooks/pre-commit 第 44 行）：

    • Windows 的 Git Bash 可能没有 /dev/tty，导致交互失败。建议使用 read -r answer 并依赖 stdin 重定向，或检测平台。

  2. manage_templates.py 中 _tr 函数仅替换少量词汇，繁体转换不完整（script/manage_templates.py 第 27-38 行）：

    • 提示文案的繁体转换仅覆盖少数词汇，可能遗漏其他常用词，导致繁体环境下提示不完整。建议使用 OpenCC 进行完整转换。

  3. update_contributors_images.yml 中 git diff --quiet --exit-code script/multilingual-docs/README.yml 检测源文件变更，但生成文件已 gitignore，若源文件未变更但生成文件有差异，不会触发提交（.github/workflows/update_contributors_images.yml 第 39 行）：

    • 应检测生成文件是否与源文件一致，或直接检测生成文件是否被修改。

🟡 建议

  1. manage_templates.py 中 _generate_requirements 使用 tomllib，但 pyproject.toml 中 requires-python = ">=3.11"，若用户 Python 版本低于 3.11，会跳过生成，可能导致依赖缺失（script/manage_templates.py 第 93-100 行）：

    • 建议在 --requirements 时明确报错，或提供手动安装指引。

  2. .gitignore 中忽略 vscode-extension/README.md 和 README_zh-TW.md，但未忽略 vscode-extension/README_zh-TW.md 的生成文件（.gitignore 第 22-23 行）：

    • 已忽略，但建议确认路径正确。

🔵 nit

  1. .githooks/pre-commit 中 echo -e 在 POSIX shell 中不可移植（.githooks/pre-commit 第 28 行）：
    • 建议使用 printf 代替。

优点

  • 设计清晰，源文件驱动，生成文件不入库，减少维护成本。
  • 提供 --check 和 --doc-dir 选项，便于验证和预览。
  • 钩子测试覆盖关键场景，CI 集成较完善。

重写/改进建议

  • 考虑将生成文件提交到仓库，避免 CI 依赖和主页空白风险。
  • 使用 actions/checkout 的 persist-credentials: false 并显式配置 token。
  • 在钩子中处理 Windows 兼容性。

⚠️ diff 超过 60KB 已截断，本次审查可能不完整。

由 script/ai_review.py 生成，使用请求者自己的 DeepSeek 额度。

gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .gitignore
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .gitattributes
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .githooks/pre-commit Outdated
gh-chinese-ai-reviewer[bot]
gh-chinese-ai-reviewer Bot reviewed Aug 12, 2026
View reviewed changes
Comment thread .github/workflows/check_issue_template_consistency.yml
@PtJade-Ceramic
Merge branch 'gh-pages' into ISSUE_TEMPLATE-test
157f82f
@PtJade-Ceramic
Merge branch 'gh-pages' (upstream) into ISSUE_TEMPLATE-test
4b4e45b 
解决与上游 gh-pages 的合并冲突：
- .gitignore: 合并两侧规则（HEAD 生成文件忽略 + upstream logs）
- README.md / vscode-extension/README.md: 按 PR 设计保留删除（生成文件不入库）
- vscode-extension-README.yml: 同步上游 maboloshi#766 的 browser API 新架构，避免生成回退
- ai-review.yml / docs/ai-review.md / script/ai_review.py: 采用上游 maboloshi#768 版本（已合入，PR 不再包含）
- pre-commit: 增强不一致提示（指导重新生成、警告 --no-verify），并支持 venv python.exe
- test_pre_commit_hook.sh: 适配增强提示断言与 venv python 检测
@PtJade-Ceramic
refactor(docs): 合并重复模板（DRY）、修复类型标注并增强钩子类型检查
7990786 
- 三个内容相同的通用渲染模板（CONTRIBUTING/README/vscode-extension-README 的 .md.j2）
  合并为公共模板 script/multilingual-docs/_common.md.j2
- _doc_config 内联文档输出配置，删除模块级 DOC_TEMPLATES
- 修复 _collect_headings 的 Pylance 类型标注（dict[str, Any] + cast）
- pre-commit 钩子新增：对暂存的 .py 文件自动运行 pyright 类型检查，有错误即阻止提交
@PtJade-Ceramic
feat(hooks): pre-commit 自动对暂存 Python 文件运行 pyright 类型检查
8865d62 
- 钩子新增第一步：收集暂存区 .py 文件，用 pyright 类型检查，有任何错误即阻止提交
- 支持 SKIP_TYPECHECK=1 跳过（供测试等场景）
- CI 的 Install dependencies 步骤补充安装 pyright
- 钩子测试新增场景 D：类型错误应被 pyright 阻止；修复测试脚本 python shim
  （用 wrapper 脚本替代复制 venv exe，避免 pyvenv.cfg 定位失败）
@PtJade-Ceramic
PtJade-Ceramic marked this pull request as ready for review August 12, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
+1 more reviewer
@gh-chinese-ai-reviewer gh-chinese-ai-reviewer[bot] gh-chinese-ai-reviewer[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@PtJade-Ceramic @maboloshi