NEARpedia

面向 AI Agent 的实时 NEAR 知识。NEARpedia 是一个 MCP 服务和 REST API，可在编码 Agent 即将编写的 NEAR 代码已经过时时及时告知，并提供替代方案；每条答复都附有来源和日期。同一索引也服务于研究 NEAR 的用户：网站和 /ask 聊天功能涵盖协议升级、House of Stake 投票、验证者、项目和事件。

为 NEAR Hackathon 构建（2026 年 11 月 1 日至 14 日，赛道 open 和 agents）。自 2026 年 11 月 2 日起在 near-pedia.xyz 上线；MCP 端点 https://near-pedia.xyz/mcp 无需密钥。

演示视频，81 秒：youtu.be/L1mbTEWWraE。

提示

Agent 会根据记忆编写 NEAR 代码，而 NEAR 一直在变化。过去一年发生了几项变化，其中前两项就在本次黑客松开始前几周；更早训练的模型无从知晓：

• near-sdk-js 已归档，其 README 写着“请勿使用”。
• nearcore 2.14.0 移除了 DelegateV2。
• NEAR Lake 已停止服务，其教程也已从 docs.near.org 下架。
• @near-js/* 软件包停留在 2.5.1；目前受维护的软件包是 near-api-js 7.x，其中不再提供 keyStores。

软件包注册表很少标记这些变化，因此 Agent 往往要等到构建或交易失败时才会发现。官方 near/agent-skills 是静态指令，而 nearai/near-mcp 执行的是链上操作，而非回答哪些内容是最新的。

工作原理

废弃引擎依据六种信号：已归档的代码库、README 中的“已弃用／请勿使用”、npm 和 crates.io 的弃用或撤回标记、发行说明中的移除信息、文档自身的弃用标记和已删除页面，以及长期不活跃但有活跃后继者的软件包。较弱的信号会标记为“可能已弃用”。动态看板只保留当前有效的信息：每条警报都会在相关事项解决后结束。

三种入口

连接 Agent

claude mcp add --transport http nearpedia https://near-pedia.xyz/mcp

或者，在 Claude Code 中使用插件：同一 MCP 服务外加一项技能，可在编写 NEAR 代码前后进行检查。

/plugin install nearpedia --marketplace UnityNodes/near-pedia

然后让 Claude Code 使用 JavaScript 编写 NEAR 合约，并加入元交易，再用 nearpedia 工具检查：check_code 会指出 near-sdk-js 和 DelegateV2，并给出替代方案。

[mcp_servers.nearpedia]
url = "https://near-pedia.xyz/mcp"

{
  "mcpServers": {
    "nearpedia": { "url": "https://near-pedia.xyz/mcp" }
  }
}

GitHub Action 会对拉取请求所更改的文件运行 check_code，并留下一条评论：指出每一行使用的已弃用、已移除或已更改的 NEAR 内容、替代方案以及来源。添加 .github/workflows/nearpedia.yml：

name: NEARpedia
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: UnityNodes/near-pedia/github-action@main

无需密钥。截至 2026 年 11 月 3 日，near-examples/coin-flip-examples#37 中有 7 行符合此情况：near-api-js 7 替换的 @near-js/* 软件包，以及落后至少一个主版本的依赖项。要查看 Action 写入的评论，请打开 UnityNodes/near-pedia#5，这是一个向此仓库添加过时 NEAR 代码的演示拉取请求：一条评论中有 12 项发现，并在更改的行上添加了注释。输入、输出，以及无需安装任何内容即可对任意公开拉取请求运行它的方法，见 github-action/README.md。

这种情况有多常见：截至 2026 年 11 月 3 日，67 个拥有公开仓库的 NEAR Hackathon 项目中，有 19 个使用了已弃用、已移除或已更改的 NEAR 内容，最常见的是 keyStores 和 @near-js/* 软件包。相关方法，以及一个可在任意一组克隆仓库上运行相同检查且不会点名任何人的脚本，见 docs/demo/hackathon-stale-count.md。为避免特别指出其他团队，这 67 个仓库不会列出；该数字可在任意一组仓库上重新计算，但无法在同一组仓库上重新核验。

对实时 API 进行试用

无需安装，无需密钥：

# a file written from memory: three findings, each with its replacement and sources
curl -s -X POST https://near-pedia.xyz/api/v1/check-code -H 'Content-Type: application/json' \
  -d '{"filename":"contract.ts","code":"import { NearBindgen } from \"near-sdk-js\";\nconst d = { DelegateV2: signed };\nconst ks = new keyStores.InMemoryKeyStore();"}'

# the mainnet protocol version, the upgrade vote by stake and the voting schedule
curl -s 'https://near-pedia.xyz/api/v1/protocol?network=mainnet' | head -c 600

# what is changing now, each alert with what ends it
curl -s https://near-pedia.xyz/api/v1/radar | head -c 600

check_code 会给出以下回答：第 1 行导入了已归档的 near-sdk-js，请改用 Rust 中的 near-sdk；第 2 行构建了 DelegateV2 操作，该操作已在 nearcore 2.14.0 中移除，请改用由常规访问密钥签名的 Delegate；第 3 行使用了 keyStores，而 near-api-js 7 不再包含它，请改用 KeyPairSigner。

自行运行

从干净克隆开始的 judge 流程：

git clone https://github.com/UnityNodes/near-pedia
cd near-pedia
npm ci
npm run db:init
npm run sync:near          # every source is read live, about 25 minutes
npx tsx mcp-server.ts      # MCP and REST on :3131, leave it running

在另一个终端中：

curl -s -X POST http://127.0.0.1:3131/api/v1/check-code -H 'Content-Type: application/json' \
  -d '{"filename":"contract.ts","code":"import { near } from \"near-sdk-js\";\nconst a = { DelegateV2: signed };"}'
curl -s 'http://127.0.0.1:3131/api/v1/protocol?network=mainnet' | head -c 600
curl -s -X POST http://127.0.0.1:3131/api/v1/explain-error -H 'Content-Type: application/json' \
  -d '{"error_text":"wasm execution failed with error: MethodResolveError(MethodNotFound)"}'
curl -s http://127.0.0.1:3131/api/v1/contracts/intents.near | head -c 600
claude mcp add --transport http nearpedia http://127.0.0.1:3131/mcp

没时间进行 25 分钟的同步？将相同的 curl 请求发往 https://near-pedia.xyz，而不是 http://127.0.0.1:3131，即可从实时索引获取响应；npm test 则无需同步。未进行同步时，本地服务会响应 explain-error 和 contracts（精选数据和实时 RPC），但弃用索引为空，也还没有协议快照。

你会看到两个 check_code 发现（第 1 行的 near-sdk-js、第 2 行的 DelegateV2，各自附有来源；若来源注明了日期，也会显示日期）、包含投票日期和已投票权益占比的主网升级信息、MethodNotFound 错误的含义及修复方法，以及通过 RPC 实时读取的 intents.near 上部署的方法。npm run build && npm run start 会使用同一个数据库在 :3130 提供网站服务。npm test 会运行 938 项测试，无需网络或密钥；docs/TESTING.md 说明了各部分检查的内容。

所需条件

• Node 22（better-sqlite3 是针对其 ABI 构建的，见 .nvmrc）
• 以上步骤无需密钥。NEARAI_API_KEY 会为 semantic_search 嵌入语料（否则只会匹配词语；嵌入约需 50 分钟），并启用 /ask；GITHUB_TOKEN 会添加 NEAR 仓库的未关闭议题和讨论

已完成内容

app/            Next.js pages and route handlers
components/     UI components
lib/            database client, search, ranking, embeddings, parsers, shared helpers
scripts/        sync-*.ts (one per source), check-*.ts, backfills, anchor-db.ts
mcp-server.ts   MCP server and REST API v1
contracts/      db-anchor, the Rust contract that records the daily database hash
plugin/         Claude Code plugin: the MCP server and the near-current skill
github-action/  the pull-request check (action.yml, no dependencies)
deploy/         systemd units, Caddyfile, sync-tick.sh, git hooks
docs/           setup (cron) and distribution notes
assets/         the images in this README
tests/          Vitest

黑客松之前和期间完成的工作

黑客松规则将 2026 年 10 月 19 日之后的工作计入黑客松；更早的内容属于基线（黑客松 FAQ 中的 Q-001、Q-002 和 Q-005）。我们的界定更加严格，以模板本身为界。

基线，不属于黑客松工作。 引擎是 pedia-template 的副本，这是我们从早期知识中心 CCPEDIA（Canton）和 Blobpedia（Celestia）中提取的与生态系统无关的引擎。它包含数据库层、搜索和嵌入、MCP 和 REST 服务端、Web UI、同步运行器和常规检查。仓库的首次提交就是该副本，标记为 pre-hackathon，提交日期为 2026 年 11 月 1 日。它还包含 10 月 20 日至 21 日在模板中进行的一般引擎维护，不涉及 NEAR 特定内容；我们也将其计为基线，而不将其宣称为黑客松成果。

黑客松工作。 该标签之后的所有内容：NEAR 品牌重塑、NEAR 来源、弃用引擎、check_code、RPC、验证者和 House of Stake 读取器、生态系统、事件和合作伙伴数据、雷达、27 个工具的 MCP 接口、GitHub Action、Agent Market 迁移 Agent、网站页面、NEAR AI Cloud 集成、数据库哈希约定和分发文件。完整差异见一个链接（FAQ Q-003）：pre-hackathon...main。

来自我们其他项目的代码。 lib/retry.ts 和 lib/polite-fetch.ts 移植自我们的 Monad 知识中心 Monpedia（2026 年 10 月）；移植版本加入了条件请求。

第三方代码。 package.json 中列出的开源库（Next.js、React、better-sqlite3、sqlite-vec、MCP SDK、Express、zod、@nearai/inference-sdk、near-api-js 等）以及 contracts/db-anchor/Cargo.toml 中的 near-sdk，均采用各自的许可证。public/animations/CREDITS.txt 中注明了两段 Lottie 动画的来源。网站和 assets/ 中的图片使用 Space Grotesk 和 JetBrains Mono，两者均遵循 SIL Open Font License 1.1。

AI 协助。 本仓库中的代码，包括基线部分，均使用 Claude Code 编写。

我们的另一个黑客松项目

团队还提交了 Hungry Minds，这是一款 AI 宠物 NFT，会从自己的余额中支付自己的思考费用（跟踪 nfts 和 games）。这两个项目相互独立，不共享代码（Q-015）。

非官方项目

NEARpedia 是一个独立的社区项目。它不是 NEAR Foundation、NEAR AI 或 House of Stake 的产品；它读取这些组织公开的来源，并链接回各自的网站。

License

MIT.

Maintained by Unity Nodes.