# nowledge

**Repository Path**: dazhuang/nowledge

## Basic Information

- **Project Name**: nowledge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nowledge

> ## **学习任何知识：先看懂，再动手，最后记住。**
> A source-grounded learning skill for Claude Code, Codex, and other coding agents.

Nowledge 不负责再生成一篇更长的教程。它把一个值得掌握的主题，变成一条可以走完的学习闭环：

**现查 → 判断 → 看懂 → 动手 → 复述 → 复训**

会变化的知识先查今天的来源；稳定知识回到权威教材和经典材料。每次只展开一个学习块，配一个能运行的小练习、一道不看答案的回忆题，以及下一次复训时间。

装进 Claude Code、Codex 或支持同类 `SKILL.md` 约定的 agent。核心脚本**零必需 API Key、纯 Python 标准库**；实时来源可按网络和平台条件自动降级。

先别看功能列表。下面用一次 RAG 学习，看看这条闭环实际上怎样发生。

## 一次完整的学习是怎样发生的

```text
你：最近总看到 RAG，想学一下，但不知道从哪儿开始。

Nowledge：你自己做过向量检索吗？平时一次大概能学多久？

你：没做过。晚上大概能抽半小时。

Nowledge：
1. 判断主题：mixed（原理稳定，框架与工具会变化）
2. 选择材料：原始论文 × 1 + 当前实操 × 1 + 失败案例 × 1
3. 第一个学习块：先看懂“找资料 → 带着资料回答”
4. 立即动手：15 分钟跑通一个最小检索示例
5. 合上材料：用自己的话画出准备阶段与提问阶段
6. 复训：答错项在 1 / 3 / 7 / 16 / 35 天重新出现
```

普通 AI 问答通常在“把信息说出来”后结束。上面这六步展示的是深学路线：Nowledge 还会检查来源今天是否有效、你能否亲手完成、不看答案能否复述，以及忘掉以后何时重新想起。

但并不是每个问题都需要一套 45 分钟课程。同一条学习闭环，可以从五个不同位置进入。

## 同一条学习闭环，五种进入方式

1. **先建立直觉**
   你说：“ELI5，用大图少字解释向量检索。”
   Nowledge 用具体故事只讲一个关系，再把“类比 → 真实机制 → 类比失效处”分三层揭开；关键论断标清是已核验、推断还是仅用于理解的比喻，最后留一道轻回顾。

2. **快速了解今天**
   你说：“截至今天，这个新框架发生了什么？”
   Nowledge 现查一手来源，标出 `as-of` 日期，并指出旧资料最可能错在哪里。

3. **真正系统学习**
   你说：“带我从零学 RAG / 动态规划。”
   Nowledge 生成薄路线图，只展开当前学习块，并配可跑练习、掌握门槛和间隔复训。

4. **持续追踪变化**
   你说：“以后只告诉我 MCP 新增了什么。”
   Nowledge 保存基线、自动去重，只报告上次之后的变化。

5. **发现值得关注的东西**
   你说：“这个月有哪些新出现的 Agent 项目？”
   Nowledge 按时间窗发现项目，并把热度线索、官方事实和独立评价分开。

一句话能回答的静态事实、单纯总结 URL、写代码或翻译，不需要启动整套学习闭环。

五种路线的产物不同，但第一步相同：**先判断这是什么知识，再决定应该相信什么来源。**

## 五种路线共享一个底座：信源判断

Nowledge 不把搜索结果数量当成可信度。信源会依次经过三层，每一层只做自己擅长的事。

### 第 1 层：发现线索

GitHub、Hacker News、Reddit、X、AI HOT 和中文社区负责回答：“最近有什么值得继续查？”它们可以很新，但热度、转发和摘要都不是最终证据。

### 第 2 层：回到原始页面核验

发现线索以后，Nowledge 按论断寻找真正能证明它的材料：

- **发布、版本、价格、额度、服务状态** → 官方博客、文档、Changelog、Status；
- **论文结论、是否正式发表** → 论文原文、OpenReview、ACL/PMLR/NeurIPS 等论文集；
- **“更强、更快、更便宜”** → 独立评测，并保留方法、配置、样本和日期；
- **真实体验、失败模式和权衡** → Issue、维护者记录、独立作者与社区复盘。

聚合摘要、员工预告、厂商自测、单个总分和大 V 身份都可以提供线索，但不能独自承担结论。

### 第 3 层：为学习留下互补材料

核验完成后，Nowledge 不会倒给你几十个链接，而是尽量只留下：**原理源 × 1、实操源 × 1、踩坑源 × 1。** 找到一份已经讲得很好的真实材料时，它优先带着你读，而不是重新生成一篇平替教程。

选材之前，主题还会先分成三类：

- **stable**：算法、数学基础等稳定知识，优先权威教材、大学课程和经典错解；
- **fast**：版本、价格、新模型等快变量，优先近期一手信息并标日期；
- **mixed**：RAG、Agent 框架等混合主题，稳定原理与易变工具分开处理。

当前内建或支持 GitHub、arXiv、Hacker News、Reddit、掘金、微信公众号、知乎、Context7、X 和 AI HOT。AI HOT 只作为中文热点 `signal`，[AI Source Map](https://github.com/hjxccc/ai-source-map) 只作为核验入口 `catalog`；它们都不会被当成最终证据。

![Nowledge 对会变化的知识进行现查与旧记忆纠偏](demo/frozen-vs-now.png)

信源放对位置以后，剩下的学习动作才能可靠地继续。如果你想亲手试一次，不需要先研究命令行，把安装交给你正在使用的大模型即可。

## 让大模型帮你装（Install）

把下面这句话复制给 Claude Code、Codex，或其他能操作本机文件并支持 `SKILL.md` 的 Agent：

> 请帮我安装 Nowledge Skill：<https://github.com/hjxccc/nowledge>。

大模型会自行选择适合当前系统和 Agent 的安装方式。你只需要确认它最后给出的安装位置与校验结果。

---

安装完成后，日常使用仍然是说人话。下面的命令行只为想直接调用判断层、复现实验或接入自动化的用户保留。

## 怎么用：先说人话，命令行是可选项

**日常：说人话**——触发词见 `SKILL.md` 的 description。装好后无需碰命令行。

**手动跑引擎**（想直接用判断层时）：
```bash
python scripts/ground.py "RAG 检索增强" --quick --compact          # 快答：只回必要字段
python scripts/gate.py "向量检索-intuition.html" --strict --summary # 单页直觉图质量 gate
python scripts/ground.py "https://github.com/HKUDS/DeepTutor" --quick --compact  # 精确仓库优先
python scripts/ground.py "loop engineering" --out sources/raw.json --compact  # 完整料落盘 + 紧凑视图
python scripts/discover.py --since month --limit 5 --out hot.html --quiet     # 榜单落盘 + 一行摘要
python scripts/track.py "MCP" --dir mcp-track --quiet                       # delta 落盘 + 一行摘要
python scripts/review.py due --file <主题>-nowledge/progress.json             # 复训：到期回考
python scripts/gate.py <主题>-nowledge --strict --summary                    # 通过时只回一行
```

产物落当前目录 `./<主题>-nowledge/`。

**辅导行为评测**（TutorBench-lite）：

```bash
python scripts/eval_tutorbench.py --validate
python scripts/eval_tutorbench.py --responses responses.jsonl --threshold 0.75
```

场景与响应字段合同见 `evals/tutorbench-lite/scenarios.json`。它检查误解纠正、难度适配、官方来源引用、掌握目标推进和追问行为；这是可重复的冒烟评测，**不是**真实学习者长期保持率证明。

看到这里，Nowledge 与搜索工具的区别就更清楚了：搜索负责把材料找回来，Nowledge 还要判断材料、组织学习动作，并确认知识有没有真正进入脑子。

## 为什么它不只是一个搜索合集

1. **形态**：多件套一次打包成"本地可动手的学习套件文件夹"——离线、最小、可动手、理论驱动。竞品要么在线站（roadmap.sh）、要么对话辅导、要么单张绘图。
2. **判断层**：面向**学习材料**的、开源可复现的选材引擎（加权 RRF + 实体聚类 MMR + URL 去重 + 角色三角）；争议主题再做检索后观点、矛盾与论断审计。aihot 证明"判断比抓取值钱"但它是新闻场景且评分不开源——这块是真空。

> 核心理念：last30days/aihot 把料端给你就结束了，而"读一遍点头 = 流畅性错觉"。**Nowledge 接着逼你把料变成脑子里的东西。**

下面是这两层能力在仓库中的对应位置。只想安装使用的话，可以直接跳到最后的“当前状态与边界”。

<details>
<summary><strong>给维护者：仓库结构</strong></summary>

<br>

```
SKILL.md            常驻控制面（意图路由 + 公共状态机 + 硬护栏，≤8KB）
DESIGN.md           设计蓝图（仅维护 Skill 时读取）
references/         mode-intuition/quick/deep/track 按意图加载 · visual/source-fallbacks 按条件加载 · 其余维护参考
templates/          diagram-intuition.html(大图少字) · diagram-dark.html(静态) · diagram-interactive.html(可拖动交互) · ROADMAP.md · perspective-map.md · memory-card.md · checkpoint.md · rank-card.html
scripts/
  ground.py         第0件接地引擎（--compact 紧凑视图 / --out 完整落盘）
  eval_tutorbench.py TutorBench-lite 确定性辅导行为评测
  discover.py       发现模式（github trending + 榜单卡片，支持 --quiet）
  track.py          追踪模式（delta digest，支持 --quiet）
  review.py         间隔复训引擎（1/3/7/16/35 天）
  gate.py           六件套质量 gate（含反 slop 硬验，支持 --summary）
  lib/              planner · fusion(RRF) · cluster(MMR) · dedupe · common
  lib/sources/      hackernews · github · arxiv · reddit · juejin · wechat · zhihu · context7 · x · aihot(signal)
  planner           AI Source Map(catalog) → official / papers / benchmarks / independent 核验路由
evals/tutorbench-lite/        固定学习者画像、历史、问题与行为 rubric
examples/
  loop-engineering-nowledge/   完整深学包样板（六件套 + 接地，过 gate）
  deeplearning-ai-nowledge/    带读外部真源 + 复训 loop 活样板（洞入队、有 lapses）
  hermes-nowledge/             框架原理·深色架构图解样板
  showcase/                    直觉/快答/发现/追踪 四种意图的橱窗样例
```

</details>

## 当前状态与边界（2026-08-25）

当前为 **beta**。直觉图、深学闭环和五种意图已提供可运行实现；明确 GitHub URL/`owner/repo` 会精确命中官方仓库，AI 快变量会先发现、再按论断回到官方/论文/独立评测/独立观点核验，确定性核心和 TutorBench-lite 行为场景由单元测试覆盖，示例包通过质量 gate。HN、GitHub、arXiv、掘金、公众号、context7、X 与 AI HOT 都做过作者环境实测，但实时来源会受登录态、反爬、限流和网络影响。AI HOT 仅作为中文 AI 热点 `signal`，AI Source Map 仅作为 `catalog`，二者都不替代一手证据。

直觉图的证据化叙事合同借鉴 [Fireworks Open ELI5](https://github.com/yizhiyanhua-ai/fireworks-open-eli5) 并独立实现：Nowledge 保留自己的“大图少字 + 学习闭环”，只吸收单一叙事语法、三层真相、论断级证据状态、故障视角与手机重排，不引入对方的阅读器和导出套件。

X 源优先使用已认证的 `twitter-cli` 做 Latest 关键词搜索；未安装、未登录或失败时，仅降级到官方 syndication 的固定账号公开时间线，因此**免登录降级不等于全站 X 搜索**。TutorBench-lite 目前只证明检查器和行为合同可重复，公开发布前仍需补充真实学习者前后测、延迟复测与跨平台安装验证。