fix: restore README markdown content

FAQ.md

@@ -0,0 +1,373 @@
+# 常见问题 FAQ
+
+> 最后整理：2026-07-23  
+> 内容来源：[FAQ Issue #4](https://gitlink.org.cn/metax-maca/op_optimization/issues/4)  
+> 维护跟踪：[Issue #35](https://gitlink.org.cn/metax-maca/op_optimization/issues/35)
+
+本文档汇总沐曦“揭榜挂帅”两项赛题的常见问题。使用 `Ctrl+F`（Windows/Linux）或 `⌘F`（macOS）搜索关键词。
+
+环境版本、评测配置、时间安排可能调整。请以仓库 README、XPU-OJ 公告、比赛群通知和容器中的实际版本为准。发现内容过期或未覆盖的问题，请[提交 Issue](https://gitlink.org.cn/metax-maca/op_optimization/issues)。
+
+> **比赛标准环境**：`PyTorch-Agent / 2.8.0 / Python 3.12 / MACA 3.7.1.5`。此前部分 Issue、页面和下载链接曾标注 `3.7.2.1`，该版本不作为比赛环境依据。
+
+## 快速导航
+
+- [重要入口与咨询方式](#entry)
+- [报名、组队与资格审核](#registration)
+- [环境、镜像与算力资源](#environment)
+- [XPU-OJ、提交与排行榜](#xpuoj)
+- [赛题一：TileLang 与 Fused MoE](#track-one)
+- [赛题二：AI Agent 与推理算子库](#track-two)
+- [评测规则与通用技术问题](#evaluation)
+
+<a id="entry"></a>
+
+## 重要入口与咨询方式
+
+<a id="q-xpuoj-open"></a>
+
+### XPU-OJ 平台是否已经上线？
+
+XPU-OJ 已开放。账号申领流程和使用指南见[赛事 XPU-OJ 账号申领说明](赛事XPUOJ账号申领说明.md)。
+
+<a id="q-contact"></a>
+
+### 两个赛题的联系人不同，遇到问题应该联系谁？
+
+请先通过 [GitLink Issue](https://gitlink.org.cn/metax-maca/op_optimization/issues) 提问，维护者会把可复用的答案更新到本文档。比赛群用于接收赛事通知和临时信息。需要单独沟通时，请按对应比赛方案联系章老师或杨老师。
+
+<a id="registration"></a>
+
+## 报名、组队与资格审核
+
+<a id="q-register-both"></a>
+
+### 同一团队或个人可以同时参加两个赛题吗？
+
+可以。同一团队或个人可以同时报名两个赛题。
+
+<a id="q-register-multiple-tracks"></a>
+
+### 同一名学生可以报名不同赛道的不同赛题吗？
+
+可以。赛事不统一限制学生报名不同赛道或不同赛题，但同一作品不得用相同核心技术内容重复申报不同赛题。
+
+<a id="q-new-graduate"></a>
+
+### 本科应届毕业、尚未正式入学的研一新生可以报名吗？
+
+可以。参赛者可联系原本科学校完成认证手续，并以本科生身份报名。
+
+<a id="q-advisor-required"></a>
+
+### 参赛必须配备指导教师吗？
+
+不强制。填写指导教师时，每支队伍可以设置 1 至 3 名指导教师。
+
+<a id="q-advisor-team-limit"></a>
+
+### 一名指导教师最多可以指导几支队伍？
+
+赛事暂未设置统一的硬性上限。指导教师应根据可投入的时间控制队伍数量。
+
+<a id="q-cross-school-stamp"></a>
+
+### 跨校组队时，报名表应该由哪所学校盖章？
+
+资格审批阶段，每名参赛者需到本人学校的校团委或院团委完成盖章确认。后续材料由团队牵头学生统一整理和提交。
+
+<a id="q-upload-stamped-form"></a>
+
+### 提交报名后还可以补充已盖章的报名表扫描件吗？
+
+审核人员发现材料缺少盖章时，会退回申请。团队补齐材料后可以重新提交。尚未完成盖章的团队应先与学院、校团委或学校相关部门确认办理方式。
+
+<a id="q-stamp-department"></a>
+
+### 资格审查材料应该加盖哪个部门的公章？
+
+各高校的管理口径不同。教务处、学生处等学籍或学生管理部门通常可以办理，参赛团队应以本校校团委或相关管理部门的要求为准。
+
+<a id="q-no-youth-league"></a>
+
+### 学校未设校团委，可以用院系公章替代吗？
+
+赛事原则上要求校级部门公章。学校未设校团委时，可以联系校级学工、双创或教务部门盖章，并提交情况说明。院系公章不能直接替代校级部门公章。
+
+<a id="q-student-status-proof"></a>
+
+### 学校无法配合盖章，可以用学籍证明替代吗？
+
+不可以。参赛团队应使用报名系统导出的报名表，并按要求完成学校盖章。
+
+<a id="q-public-notice"></a>
+
+### 公示材料需要包含哪些内容？
+
+请参考赛事工作群发布的参考文本，并按学校要求调整。跨校团队涉及的学校应分别在学校官网公示，公示渠道原则上使用学校官网。
+
+<a id="q-review-deadline"></a>
+
+### 报名审核需要在报名截止日前完成吗？
+
+原则上需要。往届出现过系统延后关闭的情况，但本届参赛团队不应据此推迟材料提交或审核。
+
+<a id="q-review-flow"></a>
+
+### 报名材料的审核顺序是什么？
+
+学生提交材料后，学校校团委先审核；学校审核通过后，企业再审核。企业审核通过即视为报名成功。
+
+<a id="q-school-review-account"></a>
+
+### 后台显示“校团委审核”，但学校不了解审核事项，怎么办？
+
+校团委需在报名系统内完成审核。省级团委通常会向各高校团委发放账号和密码。学校未收到或不了解安排时，请学校联系省级团委确认。
+
+<a id="environment"></a>
+
+## 环境、镜像与算力资源
+
+<a id="q-environment-image"></a>
+
+### 比赛使用哪个在线算力环境？
+
+比赛使用模力方舟沐曦算力专区。仓库 README 当前标注的统一镜像为：
+
+```text
+PyTorch-Agent / 2.8.0 / Python 3.12 / MACA 3.7.1.5
+```
+
+创建实例和连接环境的步骤见[模力方舟快速使用 SOP](模力方舟快速使用SOP.md)。
+
+<a id="q-download-maca"></a>
+
+### 如何获取 MACA 镜像或安装包？
+
+参赛者可以在[模力方舟沐曦算力专区](https://ai.gitee.com/compute/metax)选择 `PyTorch-Agent` 镜像。需要单独获取软件包时，请前往[沐曦开发者社区软件中心](https://developer.metax-tech.com/softnova/docker?chip_name=%E6%9B%A6%E4%BA%91C500%E7%B3%BB%E5%88%97&package_kind=AI&dimension=docker)，并选择与比赛标准环境一致的 MACA `3.7.1.5` 版本。
+
+<a id="q-download-pytorch"></a>
+
+### 比赛使用的 PyTorch 镜像可以下载吗？
+
+可以。请在[沐曦开发者社区](https://developer.metax-tech.com/)或其 [PyTorch 镜像列表](https://developer.metax-tech.com/softnova/docker?chip_name=%E6%9B%A6%E4%BA%91C500%E7%B3%BB%E5%88%97&package_kind=AI&dimension=docker&deliver_type=%E5%88%86%E5%B1%82%E5%8C%85&ai_frame=pytorch)中查询。下载前请核对比赛镜像的 Python、PyTorch 和 MACA 版本。
+
+<a id="q-version-mismatch"></a>
+
+### 页面标注的 MACA 版本与容器内版本不一致怎么办？
+
+比赛标准版本为 MACA `3.7.1.5`。页面或历史 Issue 中出现的 `3.7.2.1` 不作为比赛环境依据。容器显示其他版本时，请记录镜像名称、实例创建时间和 `maca` 版本输出，并通过 GitLink Issue 反馈。
+
+<a id="q-pytorch-source"></a>
+
+### MetaX 版本 PyTorch 2.8 的源码开放了吗？
+
+当前 FAQ 记录显示该版本源码尚未开放。参赛团队可以在模力方舟预装环境中开发和调试。
+
+<a id="q-mcprofiler"></a>
+
+### Linux 版本的 mcprofiler 是否可用？
+
+原 FAQ 记录显示 Linux 版本正在打包进入比赛镜像。请检查最新镜像和比赛群公告；镜像中仍未提供时，请提交 Issue 询问进度。
+
+<a id="q-compute-coupons"></a>
+
+### 算力券按团队还是按个人领取？
+
+新人礼和启悟社区算力券按学生个人发放，符合条件的团队成员均可领取。团队主申请人的额度用完后，其他成员可以继续申请资源。
+
+- [沐曦开发者社区新人礼](https://developer.metax-tech.com/activities/6)
+- [启悟社区学生算力券](https://developer.metax-tech.com/activities/11)
+- [赛事算力券活动](https://developer.metax-tech.com/activities/17)
+
+<a id="q-more-compute"></a>
+
+### 算力额度不足时可以追加申请吗？
+
+可以先领取上述活动中的算力券。仍需额外资源时，请发送需求邮件至 `opensource@metax-tech.com`。
+
+<a id="q-commercial-agent-cost"></a>
+
+### 使用 Claude Code、Cursor 等商业 AI 工具的费用由谁承担？
+
+赛事会提供模力方舟资源包 Token，参赛者可以使用模力方舟提供的大模型服务。第三方商业工具产生的订阅或调用费用，请按工具提供方和赛事通知确认。
+
+<a id="xpuoj"></a>
+
+## XPU-OJ、提交与排行榜
+
+<a id="q-xpuoj-environment"></a>
+
+### XPU-OJ 与模力方舟的运行环境一致吗？
+
+赛事 FAQ 说明排行榜评测环境与模力方舟开发环境保持一致。版本调整时以 XPU-OJ 公告为准。
+
+<a id="q-xpuoj-account"></a>
+
+### 如何申请 XPU-OJ 账号？
+
+请按照[赛事 XPU-OJ 账号申领说明](赛事XPUOJ账号申领说明.md)提交申请。账号发放进度以赛事通知和回复邮件为准。
+
+<a id="q-official-ranking"></a>
+
+### 赛题一 MoE 初赛排名以哪个入口为准？
+
+正式排名和初筛结果以 XPU-OJ 的评测结果为准。Sample benchmark 用于本地功能验证、调试和性能对比，不作为正式榜单依据。
+
+<a id="q-test-cases"></a>
+
+### 排行榜测试样例与 `race_tests` 一致吗？
+
+当前 FAQ 说明排行榜样例与 `race_tests` 保持一致。赛事方后续调整测试样例时，以 XPU-OJ 发布的 baseline 和正式评测配置为准。
+
+<a id="q-full-gpu"></a>
+
+### 正式评测使用 GPU 切片还是整卡？
+
+正式评测使用沐曦 C500 64G GPU 整卡环境。开发指南中出现的 `Sliced GPU: 50% Compute, 32000 MiB Vram Quota` 描述不代表正式评测配置。
+
+<a id="q-language-ranking"></a>
+
+### MACA C++、Triton 和 TileLang 是否分别设榜？
+
+不按语言分别设榜。每个任务支持 MACA C++、Triton 和 TileLang，团队可以使用一种或多种语言提交。排行榜采用通过正确性和稳定性测试后的最高成绩。
+
+<a id="q-ranking-metric"></a>
+
+### 排行榜使用 latency、speedup 还是综合 score？
+
+当前 XPU-OJ 以 speedup 作为核心排名指标。赛事方调整计算方式时，以 XPU-OJ 公告为准。
+
+<a id="track-one"></a>
+
+## 赛题一：TileLang 与 Fused MoE
+
+<a id="q-track-one-submission"></a>
+
+### 赛题一的提交要求有哪些调整？
+
+正式提交禁止使用 `MACA Maca running` 方式，也不能使用 PyTorch 实现算子。参赛者需使用 TileLang 实现并提交。
+
+<a id="q-ops-reference"></a>
+
+### OPS 目录中的 TileLang、CUDA、CUTLASS 和 MACA 代码有什么用途？
+
+这些代码用于解释算子的实现原理和设计思路，可作为 TileLang 实现的参考。
+
+<a id="q-baseline-modification"></a>
+
+### 官方 Baseline 可以修改到什么范围？
+
+参赛者可以重新设计和优化算子实现，但需保持与统一 Workload 测试框架的接口兼容。
+
+<a id="q-gemm-optimization"></a>
+
+### GEMM 计算中可以引入其他优化策略吗？
+
+可以，前提是实现符合赛题规则和评测要求。
+
+<a id="q-benchmark-modification"></a>
+
+### 可以优化 `fusedmoe_benchmark` 吗？
+
+本地修改 benchmark 不会提高正式成绩，XPU-OJ 使用赛事方的评测框架。参赛者应把优化工作放在规定的算子实现和允许修改的接口上。
+
+<a id="q-forward-modification"></a>
+
+### 可以修改 `fusedmoe_benchmark.py` 中的 MoE forward 吗？
+
+正式成绩以 XPU-OJ 的独立评测为准。本地修改 forward 不能替代对提交算子的优化，也不会改变赛事方的评测代码。
+
+<a id="q-async-copy"></a>
+
+### 赛题一允许使用异步拷贝吗？
+
+不允许。当前比赛规则禁用异步拷贝。
+
+<a id="q-baseline-performance"></a>
+
+### `tilelang-metax` 的 baseline 性能和提升标准是什么？
+
+原 FAQ 记录显示基线性能和参考值仍需出题老师确认。请以 XPU-OJ 发布的 baseline、硬件配置和榜单规则为准。
+
+<a id="q-fused-moe-final"></a>
+
+### Fused MoE 初赛成绩如何影响决赛？
+
+当前规则只给初赛前 10 名决赛加分，第 11 名及之后不获得额外初赛加分。
+
+<a id="track-two"></a>
+
+## 赛题二：AI Agent 与推理算子库
+
+<a id="q-track-two-update"></a>
+
+### 赛题二的内容有什么调整？
+
+“Agent 推理算子库优化 - FlashAttention KV Cache Decode”新增 `mctlass/cute` 要求。参赛者需基于 `mctlass/cute` 实现或优化对应任务。
+
+<a id="q-track-two-selection"></a>
+
+### 赛题二可以选择几个任务？
+
+参赛团队可以从 FlashInfer、FlashAttention、MCTLASS/Fused MoE 等方向选择一项或多项。提交多个任务时，每个任务按赛事规则取有效最高成绩。支持语言包括 Triton、MXMACA C++ 和 TileLang。
+
+<a id="q-agent-proof"></a>
+
+### 如何证明 AI Agent 参与了优化过程？
+
+原 FAQ 记录显示“Agent / Skill 可复现性”的核验流程仍在完善。参赛团队应保留 Agent 配置、Skill 文件、关键提示词、操作日志、代码变更记录、测试结果和复现实验步骤，等待赛事方发布核验细则。
+
+<a id="q-agent-baseline"></a>
+
+### Agent 赛题的性能 baseline 使用哪个版本？
+
+当前评测使用赛事方提供的 baseline，标准环境为 `PyTorch-Agent / 2.8.0 / Python 3.12 / MACA 3.7.1.5`。赛事方变更 baseline 或评测方式时会发布通知。
+
+<a id="q-mla-dimensions"></a>
+
+### MLA 的 `QK dim = 576, VO dim = 512` 与 `race_tests` 参数冲突吗？
+
+不冲突。`race_tests` 中的 `dim=512, pe_dim=64` 对应 `QK dim = 576, V dim = 512`。
+
+<a id="q-nsa-ranking"></a>
+
+### NSA 的 109 个测试 case 如何计算榜单成绩？
+
+XPU-OJ 通过统一接口统计测试总运行时间，再根据 baseline 计算整体 speedup。
+
+<a id="q-upstream-code"></a>
+
+### 可以引用或修改 FlashInfer、FlashAttention 等上游代码吗？
+
+可以。参赛团队需遵守上游项目许可证，保留版权和许可证声明，并在提交材料中说明引用范围、迁移工作和自主优化内容。
+
+<a id="evaluation"></a>
+
+## 评测规则与通用技术问题
+
+<a id="q-doc-release"></a>
+
+### 技术文档、Baseline、标准测试集和评测脚本何时发布？
+
+TileLang 相关资料已经开放。AI Agent 赛题资料以仓库更新、XPU-OJ 公告和比赛群通知为准。
+
+<a id="q-correctness-and-performance"></a>
+
+### 优化结果需要满足哪些基本条件？
+
+提交需通过赛事方的正确性和稳定性测试。排行榜只统计满足这些条件的有效性能结果。
+
+<a id="q-report-outdated"></a>
+
+### FAQ 内容与最新公告不一致怎么办？
+
+请提交 Issue，并提供冲突条目、最新公告链接或环境截图。维护者确认后更新本文档，在原 Issue 中回复对应锚点链接。
+
+## FAQ 维护约定
+
+1. 参赛者通过 Issue 提交问题。
+2. 维护者确认答案后更新本文档。
+3. 每个答案保留稳定锚点；需要时附上来源 Issue 或公告。
+4. 维护者在原 Issue 中回复 FAQ 锚点链接，并关闭已经解决的问题。
+5. 涉及版本、日期、评测参数的答案应标注确认日期。

README.md

@@ -1,5 +1,10 @@
 # 降低Token 成本，攻坚国产推理生态｜沐曦两大赛题登陆 2026 揭榜挂帅擂台赛，邀青年共破局！
 
+## 常用入口
+
+- [常见问题 FAQ](FAQ.md)
+- [提交问题](https://gitlink.org.cn/metax-maca/op_optimization/issues)
+
 2026 年度中国青年科技创新「揭榜挂帅」擂台赛正式启幕。沐曦股份重磅发布两大 AI 算力硬核榜题，聚焦国产 GPU 大模型推理算子优化，以硬核赛事搭建科研攻关平台，邀全国青年学子、科研人才揭榜攻坚，用技术重构推理效率，用创新拉低每 Token 算力成本！
 
 ## 两大重磅赛题 直击推理成本核心痛点