Skip to content

AGENTS.md

Latest commit

 

History

History
273 lines (197 loc) · 18.2 KB

AGENTS.md

File metadata and controls

273 lines (197 loc) · 18.2 KB
Raw

AGENTS.md - Robotics_Notebooks

本仓库从“思维导图资源集合”升级为“机器人研究与工程知识库”。

项目定位

  • 主定位： 面向机器人研究与工程的 markdown wiki
  • 内容核心： 机器人技术栈、控制、强化学习、模仿学习、Sim2Real、系统设计
  • 展示层： 当前思维导图网页先保留，不优先改渲染
  • 知识层： 逐步迁移到 wiki/，并通过 exports/ 给网页提供数据

仓库分层

1. sources/

原始资料层。只收集，不做强结构化改写。

包括但不限于：

  • 论文
  • 博客
  • 课程
  • 视频
  • 外部仓库
  • 旧版笔记原稿

2. wiki/

结构化知识层。是本仓库的核心。

目标：

  • 将分散资料整理成概念页、方法页、任务页、路线页、对比页
  • 强调交叉引用
  • 强调面向研究和工程使用

3. schema/

知识库维护规则。

包括：

  • 页面类型定义
  • 命名规范
  • 链接规范
  • ingest 流程

4. exports/

给网页/思维导图使用的导出层。

当前先占位，后续再把 wiki/ 映射到导图数据。

5. docs/checklists/

项目执行清单与阶段性维护看板。

包括：

这些文件用于记录阶段性工程计划、验收标准和历史推进过程；不要把它们当作 wiki 知识页。若修改前端体验、导出链路或阶段性目标，应同步更新对应 checklist。

写作原则

  1. 原始资料和知识归纳分开

    • 原始来源进 sources/
    • 归纳后的页面进 wiki/

  2. 优先按知识实体组织，而不是按时间堆砌

    • 概念、方法、任务、系统、对比、路线

  3. 允许图结构，不强制单父节点树

    • 同一个概念可以被多个页面引用
    • 底层是知识图，前端才是树/导图

  4. 避免和 Robot_Learning_Paper_Notebooks 重复

  5. 优先可维护性，不追求一次性完美迁移

    • 先搭 schema 和 wiki 骨架
    • 再做试点迁移
    • 最后再考虑前端导出

页面风格要求

所有 wiki 页面优先简洁、直接、可交叉引用。

推荐包含：

  • 一句话定义/总结
  • 为什么重要
  • 核心结构/机制
  • 常见误区或局限
  • 与其他页面的关系
  • 推荐继续阅读

第一阶段目标

第一阶段只做：

  • 建立新目录结构
  • 建立 schema 文件
  • 建立 index/log
  • 建立一批 MVP wiki 页面
  • 不大动旧网页渲染

禁止事项

  • 不要把网页渲染逻辑和知识结构强绑定
  • 不要把所有内容继续塞回一个大纲式 README
  • 不要为了兼容旧导图而牺牲 wiki 结构设计

迁移策略

旧内容暂时保留，逐步迁移。

迁移顺序建议：

  1. humanoid control
  2. reinforcement learning / imitation learning
  3. sim2real
  4. locomotion / manipulation

对 LLM / 维护者的要求

在新增或修改页面时：

  • 同一项目的论文、项目页、官方源码统一在一个 wiki 实体节点；sources/ 按资料类型分别归档。新项目实体必填稳定 project_id 与主论文/官方资源身份字段；建页前检索既有身份，CI 规则见 schema/ingest-workflow.md 与 scripts/check_project_nodes.py。
  • 优先复用现有页面与链接
  • 若知识点已存在，补充而不是重复造页
  • 若是新外部资料，先进入 sources/，再决定是否沉淀到 wiki/
  • 新增页面不需要手动更新 catalog.md（合入 main 后 export.yml 自动重新生成，PR 不得修改它）；只有核心入口或学习路径变化时才更新 index.md 或相关 roadmap 页面

视频内容核对（media/）

  • 做或改 media/ 下的视频时，除本仓库内容外，片中每个定义、术语、公式、数值都要找官方一手资料核对（教材原文、官方规范 / 文档、源码、原始论文），术语按一手资料的严格叫法；借鉴的一手资料列在视频最末尾一页（outro.refs）。细则见 media/zero-to-ppo-video/RELEASE_PLAN.md「内容核对：一手资料」。

浏览器验证工具

后续 agent 如果需要修改或验证 docs/ 下的前端页面，尤其是 graph.html 这类交互页面，应优先安装并使用 Chrome DevTools MCP：

  • 项目地址：https://github.com/ChromeDevTools/chrome-devtools-mcp
  • Codex CLI 可用示例：codex mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
  • 用途：打开本地页面、检查 console/network、模拟点击/键盘交互、截图或验证图谱节点状态。

飞书公开文档抓取

ingest *.feishu.cn/wiki|docx 文档时，WebFetch 会被 302 到登录页；用浏览器打开「互联网公开」文档虽然能进访客视图，但正文是虚拟滚动（只有当前可见的块在 DOM 里），一次性读取只能拿到左侧目录或开头几段。用脚本边滚边按 data-block-id 累积文本：

pip install playwright   # 只需 Python 包；浏览器用云容器预装的 Chromium（/opt/pw-browsers），勿 playwright install
python3 scripts/fetch_feishu_doc.py "https://<tenant>.feishu.cn/wiki/<token>" --links -o /tmp/feishu-doc.txt
  • --links 在文末附「正文超链接」（文字 → 地址），可取到各论文 / 原帖链接（链接里常带 arXiv 编号）。
  • 输出是纯文本，不含图片与表格结构；实测（2026-10-12，WaytoAGI 周报页）70 个块、约 6000 字符，到底即止。
  • 只适用于「互联网公开」文档；需要登录或无权限会停在登录页，脚本以退出码 2 报错。页面结构改版时，容器选择器 .page-block-children 可能失效（未做长期稳定性验证）。
  • 飞书文档多为转载：归档到 sources/ 时保留原文链接与版权声明，只提炼条目线索，不整篇转存。

Ingest 原文与图表要求（必须遵守）

  • ingest 项目时，先获取并通读主要原文（论文全文、官方技术文档或项目原始资料）；不得以摘要、转载或搜索片段代替全文。核对核心机制、实验及局限，并在页面标明原文链接及版本。
  • 每个新建或本次主要更新的项目实体节点必须包含基于原文的 Mermaid 项目流程图，体现主要模块与数据或控制流；不确定的关系不得臆造。
  • 官方源码包含可运行实现时，须阅读相关源码与官方运行入口，在该实体节点添加 Mermaid 源码运行时序图，标注实际入口和模块；不要以通用模板冒充源码分析。无可运行实现时说明原因。
  • 原文或必要源码无法获取、未读完，或流程无法核实：如实记录阻塞与未完成内容，保持 PR 草稿，不得声称已完成或用猜测补图。

LLM Wiki Ops 规范（必须遵守）

本知识库采用 Karpathy LLM Wiki 模式：LLM 是维护者，人类是 curator。

核心操作规范在 schema/ingest-workflow.md，每次维护本仓库前必须先读该文件。规范文件总索引见 schema/README.md。

三种核心 Op：

  • ingest — 新资料进入知识库（先 sources/，再判断是否升格 wiki/）
  • query — 向知识库提问，结果写回 wiki 而非留在聊天记录；独立洞见写入 wiki/queries/
  • lint — 定期健康检查（orphan pages、矛盾、缺失 cross-reference、缺失参考来源等）

关键约束：

  • 不要把 source 直接复制成 wiki — 要提炼，不是转存
  • 不要把 wiki 页写成纯外链列表 — 要有知识归纳
  • 不要为了收集而收集 — 优先服务学习与研究主线
  • 不要在 ingest 时一次性做太多事 — 一次一条资料，深度到位再推进
  • 有项目页的 ingest 必须先打开项目页核查源码/数据是否开放（已开源 / 部分 / 待发布 / 未开源），并写入 sources/sites/、sources/repos/ 与 wiki 局限或工程实践；详见 schema/ingest-workflow.md § 步骤 2.5
  • 每次 ingest 建议记一条日志（叙事：意图 / 开源结论 / 关键页；不必列出全部 wiki 路径）：用 make log OP=ingest DESC="..." 写入 log.d/ 碎片，不要直接改 log.md（合入 main 后自动并入）
  • 每次 query 有好结果都要写回 wiki
  • 每个 wiki 页面必须包含 ## 参考来源 区块，标注该页知识编译自哪些原始资料 （这是 Karpathy"compilation beats retrieval"的核心体现：页面本身即溯源）
  • 每个 wiki 页面必须包含 ## 英文缩写速查 区块（紧跟一句话定义之后；三列：缩写 / 英文全称 / 简要说明；至少 3 行）。格式见 schema/page-types.md；ingest 步骤见 schema/ingest-workflow.md
  • 论文实体页（wiki/entities/paper-*.md）必须包含 ## 结论 区块（评测节之后：1 句总判 + 3–7 条可操作要点）。后续 ingest 一律不得省略；历史页大幅改写时补齐。格式见 schema/page-types.md
  • 论文实体页（wiki/entities/paper-*.md）在官方有可运行代码时，必须增加 ## 源码运行时序图（mermaid sequenceDiagram，节点对齐 sources/repos/ 与 README 入口；无可运行实现时写明「不适用」及原因）。详见 schema/ingest-workflow.md § 步骤 5
  • CI 质量网关（必须通过）：
    • 提交前必须本地运行 make ci-preflight：重新生成 exports/、docs/exports/、搜索索引、sitemap、图谱与首页统计，然后执行 lint/search/export 检查。这些派生产物全部 gitignore、不随提交入库（Pages 部署时现场生成），preflight 生成它们只为本地检查与预览；preflight 不会改动任何入库文件（make ci-check 可验证）。
    • PR 只提交源文件（wiki/、sources/、roadmap/、schema/、log.d/ 碎片、脚本等）。不得修改 catalog.md、log.md（由 main 上的 export.yml 维护），也不要提交 README.md 徽章数字、docs/index.html Hero 数字、docs/sw.js 缓存版本这类统计改动——它们在部署时生成。PR 上的 Wiki Lint 会用 scripts/pr_derived_guard.py 检查。
    • 与 main 冲突 / guard 失败：运行 make sync-main（合入 origin/main，派生文件一律以 main 为准，分支写进 log.md 的条目自动转存为 log.d/ 碎片），然后 push。只有真正的源文件（同一 wiki 页）冲突才需要按内容手工合并。
    • 严禁使用 [[...]] 语法进行内链（代码块内除外），必须使用标准 [text](path) 格式，以确保 lint_wiki.py 的入链统计与断链检查准确。
    • 首页「最新知识节点」：由 git 中 wiki/ / roadmap/ 的首次加入日驱动（最近窗口内的新增节点）；log.md 不再作为站点活动数据源。home-stats.json 等统计不入库，部署时生成。

Git 提交规范 (Git Commit Convention)

为保持仓库历史清晰，所有提交必须使用 中文 描述，并遵循以下格式：

除非用户明确要求不要提交或不要推送，否则 agent 完成修改后应：

  • 只 stage 本次任务相关文件，避免带入无关工作区变化。
  • 按本节格式创建中文 commit，commit 消息参考近期历史提交风格。
  • 将当前分支推送到 GitHub 远端（通常是 origin main 或当前工作分支）。

  1. 知识入库提交 (Ingest)： 格式：[YYYY-MM-DD] ingest | <源文件路径> — <中文描述内容> 示例：[2026-04-23] ingest | sources/repos/robot_lab.md — 接入 IsaacLab 扩展框架并同步全站索引

  2. 结构/功能/修复提交： 格式：<类型>(范围): <中文描述内容>

    • 类型 (type)：feat, fix, chore, docs, refactor, style, test。
    • 范围 (scope)：可选（如 ux, actions, wiki）。 示例：fix(actions): 修复 CLAW 页面格式缺失主要技术路线的问题

Cursor Cloud specific instructions

Environment overview

This is a pure content + tooling repo — no backend services, databases, or Docker required. The stack is:

  • Python 3.12 (scripts, linting, tests) with deps in requirements-dev.txt
  • Node.js 22 + npm (ESLint for docs/main.js only) with deps in package.json
  • GNU Make as the task runner (see Makefile for all targets)

Gotchas

  • pip-audit (used in make ci-test) requires python3-venv to be installed at the system level (apt install python3.12-venv). The update script handles pip install but system packages must be pre-installed.
  • make test / make ci-test 依赖 gitignore 的站点 JSON（exports/site-data-v1.json 等）。全新环境若未先生成，test_community_naming 与 test_wiki_roadmaps_export 会因 FileNotFoundError 失败。跑测试前先执行一次 make export graph（约 30s）生成派生数据，之后 make test/make ci-test 即可全绿。
  • Python tools (ruff, mypy, pytest, pip-audit, etc.) install to ~/.local/bin. Ensure PATH includes $HOME/.local/bin before running Make targets.
  • PYTHONPATH=scripts is required for mypy and pytest (already set in the Makefile targets).

Key commands

Task Command
Full CI gate (mirrors GH Actions) make ci-test
Wiki health check make lint
Pre-commit preflight (regenerates gitignored derived files + checks) make ci-preflight
Merge main & auto-resolve derived-file conflicts make sync-main
Unit tests only make test
Serve static site locally make export graph && cd docs && python3 -m http.server 8080（站点 JSON 不入库，先生成约 40s）

Before committing wiki changes

Always run make ci-preflight — it regenerates derived files (exports/, docs/exports/, search index, sitemap, graph/home stats) and then runs lint + export checks. All of these are gitignored (generated at Pages deploy time), so commit only source files. Never modify catalog.md or log.md in a PR (bot-owned: export.yml regenerates the catalog and folds log.d/ fragments into log.md on main); write log entries with make log (creates a log.d/ fragment). If the PR conflicts with main or the Wiki Lint guard fails, run make sync-main and push.

ingest 提速：交叉更新多个 wiki 后先 make bump-wiki-from-sources（或 bump_wiki_updated_for_sources.py 指定本次 sources/papers/...），再 commit，最后 只跑一轮 make ci-preflight（preflight 内 lint 只执行一次；图谱社区为 schema/topics.json 固定主题，全库约 2–5 分钟量级）。

微信公众号抓取工具（Agent Reach + wechat-article-for-ai，已预装）

用于 ingest mp.weixin.qq.com 公众号长文的工具链已随 VM 快照预装，无需每次重装（Jina Reader 对公众号返回 CAPTCHA，不可用）：

  • agent-reach CLI（v1.5.0）→ ~/.local/bin/agent-reach（PyPI 无此包，装自 https://github.com/Panniantong/agent-reach/archive/main.zip）。
  • wechat-article-for-ai（bzd6661）→ ~/.agent-reach/tools/wechat-article-for-ai/；正文抓取实际走此工具。
  • 反检测浏览器 Camoufox → ~/.cache/camoufox/（约 713MB，含 GeoIP + UBO）；依赖 playwright==1.49.1（勿升级，Camoufox 兼容性钉定版本）。

抓取单篇公众号文章（--no-images 可跳过图片只取正文；去掉即本地化下载图片）：

cd ~/.agent-reach/tools/wechat-article-for-ai
python3 main.py "https://mp.weixin.qq.com/s/<ARTICLE_ID>" -o /tmp/wx-out -v

产物为带 YAML frontmatter（title/author/date/source）的干净 Markdown，落 <output>/<标题>/<标题>.md。这些工具不在 update script 里（Camoufox 体积大、拉取有网络风险），依赖快照持久化；若快照缺失才需按上述来源重装。遇 CAPTCHA/空正文多为限流，等几分钟重试或加 --no-headless。

兜底：预装工具缺失时（Claude Code 云容器等）

Claude Code 云容器没有上述预装，且网络策略对 github.com/.../archive/*.zip、api.github.com（Camoufox 浏览器下载）返回 403，agent-reach 与 Camoufox 都装不上。WebFetch 和 Jina Reader 只会拿到「当前环境异常」验证页。此时直接用容器自带 Chromium（/opt/pw-browsers，勿 playwright install）+ 微信内置浏览器 UA（MicroMessenger）即可读到正文（2026-10-12 实测，两篇公众号周报均成功）：

pip install playwright   # 只需 Python 包；浏览器用预装的 Chromium，脚本自动探测
python3 scripts/fetch_wechat_article.py "https://mp.weixin.qq.com/s/<ARTICLE_ID>" -o /tmp/wx-article.txt
  • 输出是页面纯文本（标题、作者、日期、正文），不下载图片、不转 Markdown；周报类文章的条目格式为 N. 英文标题 / 中文标题 / 机构 / 论文链接 / 解决的问题 / 创新点，可再用脚本解析。
  • 脚本检测到验证页会以退出码 2 报错。为何换 UA 就能过，未经验证（推测是微信对「微信内置浏览器」放行）；若以后失效，按上节「遇 CAPTCHA」处理，或让用户在本机用 wechat-article-for-ai --no-headless 手动验证后交付 Markdown。
  • 只抓取用户明确提供的文章链接；控制频率，勿批量爬取。

Cursor Cloud Agent：PR 与验证截图

Cloud Agent 在推送 PR 后，应在 PR 正文中附上验证截图：默认包含 静态站点 docs/detail.html?id=… 上与本次改动对应的详情页（本地 cd docs && python3 -m http.server 后 headless 截图；合并后可选附 Pages 线上 URL 截图）。可用 HTML <img alt="..." src="<绝对路径>" /> 引用 .cursor-artifacts/screenshots/ 等本地生成文件。详细步骤见 docs/checklists/cloud-agent-pr-workflow.md。