Przejdź do treści
Biblioteka skilli
Edukacja · Nauka i wyjaśnianie

atlas-loop

/atlas-loop

Rozkłada dowolny temat na interaktywną, działającą offline mapę nauki w HTML, dopasowaną do tego, co uczący się już umie.

Repozytorium
Atlas-Loop ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Rozkłada dowolny temat na interaktywną, działającą offline mapę nauki w HTML, dopasowaną do tego, co uczący się już umie.

Oryginalny opis (EN)

将任何陌生主题——学科、思维模型、手艺、书籍、软件工具、协议、商业模式或本地项目——拆解为独立离线交互式 HTML 学习地图(Atlas Loop),地图的深浅按学习者已测评的能力自动调整,支持从概览到细节的逐层钻取,以及每个节点上的「↳」深入探究与递归子图提示。当用户希望以交互式可视地图的形式学习、拆解、梳理或递归探索任何主题或代码库时触发。

Jak działa

  1. 1. 嗅探语言并澄清范围
  2. 2. 先读学习者的深度,再决定因果链
  3. 3. 研究并编写 AtlasGraphData JSON
  4. 4. 在隔离的 /tmp 工作区中构建与验证
Sekcje z nagłówków SKILL.md, w oryginale · 116 linii, 401 słów
Podgląd SKILL.md
---
name: atlas-loop
description: 将任何陌生主题——学科、思维模型、手艺、书籍、软件工具、协议、商业模式或本地项目——拆解为独立离线交互式 HTML 学习地图(Atlas Loop),地图的深浅按学习者已测评的能力自动调整,支持从概览到细节的逐层钻取,以及每个节点上的「↳」深入探究与递归子图提示。当用户希望以交互式可视地图的形式学习、拆解、梳理或递归探索任何主题或代码库时触发。
---

# Atlas Loop

把任何值得学习的主题转化为单文件、零 CDN 的交互式 `@xyflow/react` HTML 地图,将**全局因果结构**与**可钻取的内部细节**、**可验证锚点**以及**逐节点 `↳` 递归提问提示**结合在一起。地图画多深不取决于主题,取决于**读者已经会到哪一层**——讲浅了浪费时间,讲深了读不下去。

## 1. 嗅探语言并澄清范围

1. **动态嗅探语言(绝不硬编码)**:
   - 使用用户明确要求的语言。
   - 否则,嗅探用户提问与目标材料的主导语言;两者一致时,所有解释与 UI 标签均使用该语言,但技术标识符、专有名词、命令与原始文件名保持原样。
   - **歧义时询问**:如果用户的请求语言与目标材料冲突,或表述过于简略无法判断,在生成前询问用户偏好哪种输出语言。
2. **主题不受限**:
   - 目标可以是任何陌生主题:科学概念、手艺、历史事件、书籍、论文、CLI/软件工作流、系统架构或本地项目。
   - 严格聚焦于该主题的领域概念、因果机制与一手资料——绝不收集或提及版本控制仓库状态。
3. **确定递归层级(`L0` 与 `L1+`)**:
   - **L0 概览**(无 `drillDownTarget`):只画理解该主题所必需的主干。`入口 → 核心机制 → 分支/权衡 → 基础/背景 → 结果` 是可供参照的骨架,不是必须填满的清单;失败模式、反例或例外只在主题确实存在且影响理解时才画。在 `meta.uncoveredScopes` 中如实列出被略去的范围。
   - **L1+ 聚焦子图**(指定了 `drillDownTarget`):整张图以该特定节点或子主题为根,拆解其内部状态、边界情况、逐步机制与边界契约。设置 `meta.level`(`1`、`2`……)与 `meta.parentMapHtml`(如已知),使页头渲染出指向父图的可点击返回链接。

## 2. 先读学习者的深度,再决定因果链

**深浅不按主题分档,按人分。** 同一个主题,对新手要停在「这是什么、为什么重要」,对熟手要一路推到第一性原理。衡量深浅的只有一个量:**从入口到结论的主干因果链**有多长,主干以外的分支不算。

- `meta.depth`:主干因果链必须连出的跳数,`2`–`6` 的整数。**必填。**
- `meta.depthReason`:一句话写明凭什么选这个跳数——读者大概能自己补上几跳中间环节。
- `meta.audience`:一句话写明这张图假设读者已经会什么。它显示在页头,让读者一眼判断这张图是不是给自己看的。

深度与评分互为反函数:`depth = 分数 / 2 + 1`。2 分→2 跳,4 分→3 跳,6 分→4 跳,8 分→5 跳,10 分→6 跳。

**节点数不是难度。** 二十个互不相干的卡片串不起来,仍然是 2 跳;四个节点一路推到机理,可以是 6 跳。跳数越多,越要求图往下追到「为什么会这样」,而不是停在「这是什么」。

### 2.1 读取学习者的历史评分

在学习者私有档案 `~/.atlas-loop/profile.json` 中按 `领域/职业/职业精分` 三级键记录评分(如 `餐饮/厨师/粤菜`),并按模型分层。动笔前先查:

```bash
node <skill_dir>/scripts/profile.mjs read --domain "餐饮/厨师/粤菜" --model "<当前模型>"
```

- 输出「估计 N 分,建议因果链深度 D 跳」就按 `D` 写 `meta.depth`。
- 输出「没有记录」时按 **3 跳**起步,并在 `depthReason` 里写明这是首次。
- **key 的职责是让观测累积,不是精确描述这张图。** 同一个本领,不管这次画的是哪个具体项目,都必须落进同一个 key;否则每张图都从零开始,追踪能力这件事就不存在了。
- **推断 key 的三条规矩**:
  1. **末段必须是众所周知的分支**——能在招聘网站、课程目录或图书馆书架上找到的名字(`粤菜`、`Raft`、`SKILL`)。为了描述当前这张图而临时拼出来的名字不算。
  2. **绝不用项目名、产品名、文件名或图的标题当精分。** 把本技能用在这个项目上,key 是 `软件开发/AI/SKILL`;写成 `软件开发/开发者工具/Atlas-Loop` 就废了——下一张关于这个项目的图会落到另一个叶子,历史全丢。
  3. **宁可粗,不可细。** 粗一档的代价是估计略糊;细一档的代价是每次从零开始。拿不准就少写一层(`餐饮` 或 `餐饮/厨师`)。
- 检验方法:想一下同一领域里的**下一张**图,它会得到同一个 key 吗?会不同,就是切得太细了。
- 主动推断,**不要为此发起提问**——把推断出的 key 写进交付时的评分提醒里,用户看到不对会纠正。
- 档案是按模型分层的:换了模型,同一领域的历史评分不能直接搬过来。`read` 会优先取当前模型的观测,没有时回退到全部。

### 2.2 把跳数落到图上

1. **每加一跳都要有因果依据**:边说的是「因为 A 所以 B」,不是「A 之后说 B」。凑不出理由就说明这条链到此为止,下调 `meta.depth`。
2. **每个节点都要挣得自己的位置**:删掉它读者就理解不了主题,才值得画。能用 4 个节点讲清楚,就不要画 12 个。
3. **可以省略读者自己补得上的中间环节**——但省略不等于缩短链:略去的步骤仍然算在 `depth` 里,链该到哪一跳还得到哪一跳。
4. **不为凑满模板而注水**:`whyItMatters`、`keyFactors`、`mechanismsAndEffects`、`watchouts`、`anchors` 都是可选字段,只在确有内容时填写;不要为浅图硬造分支、失败模式或第二条脉络。
5. **自重而外扩**:顶层节点超过 20 个时,把细节收进 `detailGraph`,或留给 L1+ 子图。宽度不提升难度,只会稀释视线。
6. **L1+ 子图重新评估**:子图的深度取决于被钻取的节点本身与读者的同一份档案,与父图的深度无关。
7. **用户的要求优先**:用户明确要求更详尽或更精简时照做,并在 `depthReason` 中注明。

`build_atlas.mjs` 会算出顶层最长因果链:短于 `meta.depth` 直接报错(链没连到底),顶层边成环也报错(因果链必须是 DAG)。深度是可证伪的,节点数不是。

## 3. 研究并编写 `AtlasGraphData` JSON

编写 JSON 前,先阅读 [`references/schema.md`](references/schema.md) 了解精确的字段规则。

1. **每个论断都要有依据**:
   - 先检视一手证据(本地文件存在时查看实际文件;否则查阅权威文档、文本或领域原理)。
   - 对证据充分的节点标记 `"confidence": "verified"`。凡某关系、运行时绑定、版本差异或跨章节推断无法从现有证据 100% 确认时,设置 `"confidence": "unverified"`,填写 `unverifiedReason`,并在 `meta.unverifiedNotes` 中汇总。绝不编造路径、行号、引用或 URL。
   - 仅在适合主题时附加多态 `anchors`:`snippet`(公式、命令、清单)、`source`(引用、章节)、`link`(参考 URL),或 `editor`(已验证的本地 `absPath` + `line`,仅用于 `vscode` 或 `zed`,绝不使用裸 `file://`)。
2. **按深度设计清晰度**:
   - 通过将流程归入带有有序 `learningOrder` 的 `streams`,保持概览可读;浅图(`depth <= 2`)只需一条脉络,画布会自动收起搜索与小地图。
   - 深图里,把更细的内部步骤、子论证或调用链放入复杂节点的 `detailGraph`(`nodes` + `edges`),让学习者能展开内部、再折叠返回。`detailGraph` 是「同样的深度往下再展开一层」,不是把跳数硬塞进去;内部没有真实步骤的节点不要加。
3. **连线文案写短,长度由你判断**:
   - 每条顶层边和 `detailGraph` 里的边都要有 `label`,说明因果、顺序或分支条件。
   - 文案画在两张节点卡片之间的空隙中央。写长了会伸到旁边的卡片底下。不设固定字数:这条关系需要几个字,就写几个字,但整句必须落在空隙里,不能被节点盖住。
4. **编写高信噪比的 `↳` 循环提示(`deepDive`)**:
   - 为最值得追问的节点与脉络附加 `deepDive`(至少一个),让学习者永远不会卡在「接下来该问什么」上:
     - `hoverHint`:一句简短的话,点明此节点之下隐藏的复杂性或微妙之处。
     - `askPrompts`:1–2 个精准的追问,锚定该节点的具体机制、边界情况、权衡或 `unverified` 项(适用时附精确的 file:line、命令或章节锚点)。**绝不写「详细解释 X」之类的泛泛填充。**
     - `subAtlasPrompt`:一段可直接复制的递归提示,将该节点命名为新的 `drillDownTarget`,并以当前输出的 HTML 文件名作为 `parentMapHtml`。
   - 主干只到 `meta.depth` 就停,剩下的复杂度全部压在这里——这是深图不靠堆节点也能继续深入的方式。
5. **嵌入当前模型名称**:
   - 将 `meta.generatedByModel` 直接设置为你自己的当前模型名称——绝不为此添加配置开关或环境探测代码。这个字段也是评分分层的依据。

## 4. 在隔离的 `/tmp` 工作区中构建与验证

所有中间文件都放在 `/tmp/atlas-loop-<timestamp>/` 中处理,保持用户工作目录完全干净:

1. **编译独立 HTML**:
   ```bash
   node <skill_dir>/scripts/build_atlas.mjs --data /tmp/atlas-loop-<ts>/graph-data.json --out <output_html>
   ```
   - 省略 `--out` 时的默认文件名:`<safe-subject>-atlas.html`(L0)或 `<safe-subject>-sub-<safe-target>-atlas.html`(L1+)。
   - 修复 `build_atlas.mjs` 报告的任何 schema、因果链长度、行号或密钥扫描错误;输出中的 `warnings`(如链过长、节点过宽)逐条处理或说明理由。
2. **运行无头 Playwright 验证**:
   ```bash
   node <skill_dir>/scripts/verify_atlas.mjs --html <output_html>
   ```
   - 必须通过全部检查:零 `pageerror`、深度徽标与数据一致、读者档位一致、非零包围盒、零严重节点重叠、缩放/平移、锁定/解锁拖拽保护、`detailGraph` 展开/折叠(如有)、`↳` 提示气泡与双标签提示复制、PNG 导出尺寸,以及 **Fit View**(仅调整视口)与 **Reset**(完整恢复到初始位置、过滤器与折叠状态)之间的严格区分。
3. **交付并索取评分**:
   - 删除临时的 `/tmp/atlas-loop-<ts>/` 文件夹。
   - 交付生成的 `.html` 文件并简明汇报:输出路径、语言与层级、因果链深度及 `depthReason`、读者档位、当前模型、覆盖的脉络、代表性的 `↳` 深入方向、Playwright 验证结果(若生成了 `editor` 锚点但未做桌面启动测试,需注明操作系统编辑器启动本身未经过桌面实测),以及任何 `uncoveredScopes` 或 `unverifiedNotes`。
   - **最后必须单独用一句话请用户打分**,写明推断出的领域 key 与五个档位。不要用按钮、表单或任何交互控件,也不要在页面里存本地状态——地图是无状态单文件,评分只通过对话回传。
   - 用户回了数字就立刻落盘,并告诉他下张图的深度:

     ```bash
     node <skill_dir>/scripts/profile.mjs record --domain "餐饮/厨师/粤菜" \
       --score <2|4|6|8|10> --depth <meta.depth> --model "<当前模型>"
     ```

   - 用户不回应就继续,不要重复催促;同一主题下次再来时 `read` 会自己接上。

`scripts/profile.mjs` 的行为(评分吸附、顶格判定、模型分层、前缀继承)由 `node <skill_dir>/scripts/test_profile.mjs` 覆盖,改动它之前先跑一遍。

*(若需对画布模板本身做 UI 定制或样式调试,运行 `node <skill_dir>/template/dev-server.mjs` 获得实时重载,运行 `node <skill_dir>/template/build-shell.mjs` 重建 `assets/viewer-shell.html`。)*
Pliki w paczce (5)
  • .gitignore 1 KB
  • LICENSE 1 KB
  • README.md 8 KB
  • SKILL.md 12 KB
  • package.json 1 KB

Wersje

W bazie nie ma innych skilli o nazwie atlas-loop.

Migawka bazy z 13.11.2026 · wersja paczki 1edf6b0497ac (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100study-atlas
    Buduje interaktywną aplikację do nauki działającą offline w jednym pliku HTML: mapę myśli, fiszki, testy na czas i ściągę.
  • 100novel-atlas
    Zamienia powieść w jednoplikową, offline'ową tablicę interaktywną: czytnik, mapę świata, sieć postaci i oś czasu, jednym poleceniem.
  • 85atlas-help
    Pokazuje kartę referencyjną ATLAS: cztery pokrętła, wszystkie polecenia, subagentów i koszt każdego z nich.
  • 85atlas-help
    Pokazuje kartę referencyjną ATLAS: cztery pokrętła, wszystkie polecenia, subagentów i koszt każdego z nich.
  • 100agent-code-atlas
    Audytuje architekturę kodu frameworków agentowych: pętlę agenta, narzędzia, uprawnienia i pamięć, z lokalizacją w plikach i raportem HTML do przeglądania offline.
  • 95atlas-help
    Pokazuje kartę referencyjną ATLAS z czterema pokrętłami, poleceniami, podagentami i kosztami każdego z nich.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.