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.
- Autor
- liduchuan ↗
- Repozytorium
- Atlas-Loop ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 5
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
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. 嗅探语言并澄清范围
- 2. 先读学习者的深度,再决定因果链
- 3. 研究并编写 AtlasGraphData JSON
- 4. 在隔离的 /tmp 工作区中构建与验证
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.