academic-repo-analyzer

学术仓库分析器

生成一份简洁的仓库理解文档，以及机器可读的 Semantic Architecture Handoff v1。交接文档描述科学角色和可执行关系，而非仓库的文件夹布局或工程样板。

仅在任务或框架分类不确定时阅读 keywords.md。证据稀少时阅读 references/missing-info-policy.md。

核心原则：叙述优先与非侵入式提取

1. 论文与用户叙述 > 代码实现：
   • 论文图示展现的是科学贡献和概念数据流，而非完整的软件工程产物。
   • 省略工程管线内容（例如 DataLoader、Trainer、Logger、ConfigParser、DeviceManager 或 Optimizer 配置），除非论文具体贡献了训练算法或基础设施系统。
2. 事实核查与参数依据：
   • 如果已有论文草稿或用户提供的架构，仓库分析器应作为辅助事实核查者（核验张量维度、损失公式、确切模块名称和执行方向），而不是重新发明架构。

输入约定

• 优先提供：仓库路径、README、依赖项、入口点、核心模型/算法文件、配置，以及能够说明行为的测试。
• 接受：部分仓库、独立模型文件、核心算法脚本。
• 最低要求：一个 README、入口点或核心实现文件。
• Git 元数据可用时，记录源代码版本。
• 将名称和 README 声明视为线索；对图示中的关键声明，应在代码或测试中核验。

输出约定

将人工撰写的摘要控制在约 30–70 行，然后输出下方的交接块。

1. 仓库概述与科学任务。
2. 证据/完整性说明，列出已检查的内容。
3. 语义组件及其职责。
4. 已执行/建议/反馈/持久化连接。
5. 涉及 Agent、工具、评估器或外部系统时的权限或信任边界。
6. 图示建议（总体框架、网络架构、模块细节、概念/动机、协议/时序）。
7. Semantic Architecture Handoff v1。

工作流程

1. 查找证据

查找 README、依赖文件、入口脚本（train、main、eval、inference、predict、run、simulate、benchmark）、配置和核心算法文件。顶层目录仅用于发现线索，绝不能直接计为架构模块。

对于大型仓库，检查顶层内容及经过合理选择的核心文件样本。说明抽样范围。不要仅凭关键词命中就声称已全面覆盖。

2. 分类任务与实现技术栈

结合文件或符号证据，识别科学目标、主要框架、数据/实验接口和主要执行路径。明确标记未经证实的推断。

3. 构建语义图

仅当一个组件承担独立的科学或执行职责，且适合出现在论文图示中时，才创建该组件。一个组件可以横跨多个文件，一个文件也可以实现多个组件。

为每个组件记录：

• 稳定的 id 和简短的显示 label；
• role：
  • 通用机器学习 / 深度学习：input_data、encoder_backbone、fusion_interaction、loss_objective、task_head、model、output；
  • Agent / 交互式系统：reasoning、decision、deterministic_execution、observation、memory、persistence、advisory、exception；
  • 系统 / 模块化：source、scheduler、processor、storage、sink、other；
• figure_importance：primary 或 secondary；
• 证据指针，例如 path:line、类、函数、测试或配置键；
• 一句话职责说明，以及在科学上重要时明确说明其无权决定的事项。

分别记录连接。将 executed、advisory、feedback、persistence 或 exception 用作连接类型。不得仅因两个文件相互导入就推断存在连接。

4. 推导视觉分组

按职责或叙事阶段对相关组件分组。报告：

• semantic_component_count：有证据支持的组件数量；
• visual_group_count：拟议图示中的有意义区域数量；
• peer_module_count：真正等价的同级组件中，最大集合的数量。

这些计数有助于规划布局。它们本身都不会决定配色方案。

5. 输出交接内容

{
  "schema": "academic-figure/SemanticArchitecture@1",
  "source_revision": "<commit-or-unknown>",
  "domain": "<controlled-domain>",
  "evidence_level": "high|partial|sparse",
  "components": [
    {
      "id": "backbone",
      "label": "Encoder Backbone",
      "role": "encoder_backbone",
      "figure_importance": "primary",
      "responsibility": "Extracts multi-scale feature representations.",
      "evidence": ["models/backbone.py:ResNet"]
    }
  ],
  "connections": [
    {
      "from": "input_data",
      "to": "backbone",
      "kind": "executed",
      "label": "raw inputs",
      "evidence": ["models/pipeline.py:forward"]
    }
  ],
  "authority_boundaries": [],
  "semantic_component_count": 1,
  "visual_group_count": 1,
  "peer_module_count": 0,
  "figure_types": ["Overall Framework"],
  "forbidden_claims": ["<claims the figure must not imply>"]
}

受控领域：CV、NLP、Speech/Audio、RL、Robotics、Multimodal、TimeSeries、Generative、Protein/AI4Science、GNN/ScientificComputing、Systems/Infrastructure、ScientificComputing(non-ML) 或 Other。

证据稀少

• 没有 README：根据代码谨慎推断，并标明推断内容。
• 没有入口点：将结果限制在组件级结构。
• 没有核心实现：仅报告任务和技术栈，并省略缺乏依据的关系。
• 仓库几乎为空：提供最低限度的缺失材料，而不是臆造架构。

停止

交付人工撰写的摘要和有效的交接内容后即停止。只有用户希望进入下一阶段时，才建议规划图示。