Lynx API Docs面向 AI Agent 的引擎文档上下文索引AGENTS.md设计与安装机制【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx本文以 Lynx 引擎仓库中 ai/skills/lynx-api-docs/skills/using-lynx-api-docs/AGENTS.md 这份Agent 上下文索引文件为核心讲清它如何以极小的文件体积为 AI 编码代理提供 Lynx 引擎全量 API 文档的导航骨架并深入解析配套 CLIcli.js如何把该索引以托管代码块形式注入到宿主项目的AGENTS.md以及 SKILL.md 定义的先检索、再编码工作流。读完后你可以理解 Lynx 官方是如何把引擎文档打包成一个可被 Claude Code、Codex、Trae 等 Agent 按需检索的上下文包并在自己的项目中安装使用。一、索引文件本体十行文本承载完整文档地图AGENTS.md 全文只有 10 行却是一个结构高度规整的目录页。逐行拆解它的格式|Lynx API Docs - Engine AI Context|root: ./lynx-api-docs |IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for Lynx engine authoring, CSS/layout, and element tasks | |Core:{quick-reference.md|best-practices.md} |Layout:{layout/linear-layout.md|layout/flex-layout.md|layout/grid-layout.md|layout/relative-layout.md} |CSS:{css/supported-properties.md|css/selectors.md|css/values-and-units.md|css/pseudo-classes.md} |Migration:{lynx-vs-web/css-differences.md|lynx-vs-web/migration-guide.md|lynx-vs-web/unsupported-features.md} |Elements:{elements/page.md|elements/view.md|elements/text.md|elements/image.md|elements/list.md|elements/input.md|elements/scroll-view.md|elements/scroll-coordinator.md|elements/svg.md|elements/textarea.md|elements/blur-view.md|elements/refresh.md|elements/viewpager.md|elements/overlay.md|elements/webview.md} |Patterns:{patterns/theming.md|patterns/responsive.md|patterns/animation.md} |Examples:{examples/card-list.md|examples/sticky-header.md|examples/bottom-nav.md|examples/sidebar-layout.md|examples/waterfall.md}它的语法约定非常清晰首行是标题与根路径声明|Lynx API Docs - Engine AI Context|root: ./lynx-api-docs用|分隔标题与root指针告诉 Agent 整个文档包相对于本文件的根位置。这里写的./lynx-api-docs是源仓库内的占位值——在通过 CLI 安装到别的工程后这一行会被重写成目标工程的真实安装路径下文第五节详述。第二行是行为指令IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning...明确要求 Agent 对 Lynx 引擎代码编写、CSS/布局、元素任务优先使用检索式推理retrieval-led而不是依赖预训练知识。这是整个包的使用契约。空行作为元信息与索引条目的分隔。|分类:{文件1|文件2|...}索引行每一行是一个知识类别花括号内以|分隔的相对路径构成该类别下的文档清单。七类索引对应的文档在仓库中真实存在且与索引一一对应索引分类文档位置仓库内内容Corequick-reference.md、best-practices.md高频 CSS 属性速查、性能与开发建议Layoutlayout/ 下 4 个文件Linear / Flex / Grid / Relative 四种布局系统CSScss/ 下 4 个文件支持属性、选择器、值与单位、伪类Migrationlynx-vs-web/ 下 3 个文件CSS 差异、迁移指南、不支持的特性Elementselements/ 下 15 个文件page、view、text、image、list、input、scroll-view、scroll-coordinator、svg、textarea、blur-view、refresh、viewpager、overlay、webviewPatternspatterns/ 下 3 个文件主题、响应式、动画Examplesexamples/ 下 5 个文件卡片列表、吸顶头、底部导航、侧边栏、瀑布流这种索引行 按需加载的设计解决了 AI 上下文窗口有限的问题Agent 只需把这 10 行放进上下文就能在需要时按任务类型精确定位到某一两个具体文档而无需把全部 40 余篇文档一次性灌入。README.md 中给出的量化口径是速查文档约 8 KB、单个布局系统文档约 8 KB全量文档则按需加载。二、SKILL.mdAgent 的强制工作流——先读文档再写代码SKILL.md 是配套这份索引的 Agent 技能文件YAML frontmatter 声明name: using-lynx-api-docs描述中明确覆盖*.ttml、Lynx*.tsx等文件类型。它与 AGENTS.md 索引是规则 地图的关系核心主张有三1. 预训练知识不足以支撑 Lynx 开发。SKILL.md 开篇即声明Pre-training knowledge is insufficient for LynxLynx 是一个类似浏览器的渲染平台有自己的元素体系、非标准 CSS 行为、独立布局系统和与 Web 不兼容的默认值因此在编写或修改任何 Lynx 页面代码之前必须从已安装的 API 文档中检索。2. 给出了 Web 假设失效的具体清单。例如元素是view/text/image而非div/span/img默认盒模型是border-box且 margin 不折叠默认布局是 Linear 而非 Flow。文件用一句话总结Every web assumption is a potential bug.3. 定义了检索步骤与红旗自查项。检索步骤为识别任务类型layout/CSS/element/migration/pattern→ 查任务对照表定位文档 → 先读文档再写代码 → 应用文档中的约束 → 拿不准时检索elements/或css/目录。红旗项Red Flags则列出必须停下来读文档的典型错误如写出div/span、未经确认就使用margin折叠、假设content-box、猜元素属性、为 Web 兼容代码选用rpxLynx 特有、无 Web 兼容性、裸文本不用text包裹等。这些规则与索引中 Core 分类下的 quick-reference.md 相互印证速查文档明确列出display取值linear为 1.0 版默认、relative自 2.0 起、box-sizing默认auto解析为border-box语义、rpx标注为Lynx-specific, lacks web compatibility、calc()仅支持长度类属性等全部与 SKILL.md 的红旗项一一对应。三、npm 包结构一个可发布的 AI 上下文 Bundle这个文档包同时是一个 npm 包元信息见 package.json包名lynx-js/lynx-api-docs当前版本 0.3.8Apache-2.0 协议engines要求 Node.js 14bin字段把命令lynx-api-docs映射到 cli.jsfiles白名单只包含cli.js、README.md、CHANGELOG.md、LICENSE、verify-package-layout.js和skills/using-lynx-api-docs整个目录test.js不发布两个脚本prepack在发布前执行 verify-package-layout.js 做布局校验test执行 test.js。README.md 对包的定位表述很准确This package is an AI context bundle, not a traditional JavaScript or native runtime API reference——它文档化的是本仓库实际发布的public Lynx surface并明确要求使用包内的公开元素参考而不是依赖未文档化的标签或宿主特定行为。四、安装命令与完整参数将文档包引入另一个 Lynx 工程的标准命令是npx lynx-js/lynx-api-docs install完整可选参数继承自 README.md 并与 cli.js 的parseArgs实现一致参数作用--project path指定目标工程根目录默认为当前工作目录--dest path覆盖默认安装位置默认为项目根下的.ai/lynx-api-docs--dry-run只预览文件变更不落盘--no-link跳过向 Agent 技能目录建立链接--link-claude/--link-codex/--link-trae分别链接到.claude/skills/、.codex/skills/、.trae/skills/--link-all链接到所有已知项目内 Agent 目录默认行为--skills-dir path链接到自定义技能目录--help/-h打印用法从 cli.js 的解析逻辑看所有参数同时支持--flag value与--flagvalue两种写法出现未知参数会直接抛出Unknown argument错误命令本身只接受install一个子命令。五、注入机制详解COPY_ROOTS、托管代码块与 root 路径重写CLI 的安装过程可以拆成四步全部能对应到源码第 1 步复制文档COPY_ROOTS。cli.js 中的COPY_ROOTS常量列出了要复制到目标位置的全部条目AGENTS.md、best-practices.md、quick-reference.md以及css、elements、examples、layout、lynx-vs-web、patterns六个目录外加包内 README 作为README.md索引页。复制由queueCopy递归完成cli.js它先对每个文件做bufferEquals内容比较只有内容有变化才会真正写盘——因此重复执行install是幂等的不会无意义地改写文件。第 2 步向目标工程 AGENTS.md 注入托管代码块。关键函数是renderAgentsContentcli.js它读取本仓库这份源 AGENTS.md然后做两处改写——把首行的root:指针替换为目标工程中的实际相对安装路径默认即.ai/lynx-api-docs并在第 2 行插入一行|entry: path-to-AGENTS.md|index: path-to-README.md指针。这正是本文开头那份文档首行写root: ./lynx-api-docs仓库内位置而安装后变成root: .ai/lynx-api-docs的原因。随后upsertManagedBlockcli.js把改写后的内容包进一对 HTML 注释标记!-- BEGIN MANAGED BLOCK: lynx-js/lynx-api-docs -- ... !-- END MANAGED BLOCK: lynx-js/lynx-api-docs --其 upsert 语义是已存在该块则整块替换从而支持--dest改路径后重跑、索引自动跟随更新不存在则追加到文件末尾并保留原有内容若发现多个托管块则报错要求人工清理。测试用例updates one managed block and preserves project notestest.js验证了两次安装第二次换了--dest .docs/lynx-api之后项目原有注释# Project notes仍在、托管块只有一个、且root指针已更新为新路径。第 3 步安装 Agent 技能目录。技能源目录skills/using-lynx-api-docs会被完整复制到目标工程的.agents/skills/using-lynx-api-docs含 SKILL.md、README.md 与全部文档目录测试断言了安装后.agents/skills/using-lynx-api-docs/SKILL.md的存在test.js。第 4 步向各 Agent 目录建链接。resolveLinkTargetscli.js按--link-*/--skills-dir参数生成目标清单PROJECT_AGENT_DIRScli.js内置了claude、codex、trae三个已知目录linkSkillcli.js优先创建符号链接链接失败时降级为整目录拷贝并在输出中以— linked或— copied区分结果。重跑安装时已存在的旧链接/旧目录会被先清理再重建测试replaces a dangling project-local skill link on reinstall专门验证了悬空链接会被正确替换。--dry-run模式走printDryRunSummarycli.js打印将要写入 X/Y 个文档、AGENTS.md 将 created/updated/unchanged、各技能链接目标但不产生任何写入——测试用例确认了 dry-run 后AGENTS.md与.ai/lynx-api-docs均不存在。六、安全边界路径逃逸防护这个 CLI 虽然是文档工具但其安全校验做得相当完整test.js 有专门的安全回归测试--dest必须是工程内的相对路径。normalizeRelativeDestcli.js拒绝绝对路径、Windows 盘符形式C:...以及归一化后以../开头的路径。测试用../outside、nested/../../outside、/tmp/outside、C:outside、\\server\share等 8 种构造路径全部断言被拒test.js。符号链接不能指向工程外。ensurePathWithinRootcli.js会找到目标路径最近的已存在祖先、对其做realpath解析后再检查是否仍在工程根内。测试构造了项目内 AGENTS.md 是指向外部文件的符号链接的场景断言 CLI 报错AGENTS.md resolves outside the project root且外部文件内容未被改动test.js.codex目录被替换为指向外部目录的链接时同样被拦截test.js。写入前检查可写性并明确区分目标不可写与AGENTS.md 所在目录不可写两类错误ensureWritableParentcli.js。测试还断言 CLI 不出现fs.cpSync/fs.rmSynctest.js即刻意避免使用整目录粗暴拷贝/删除的 API。七、发布前的布局自检verify-package-layout.jsverify-package-layout.js 在npm publishprepack 钩子时运行校验四件事package.json的包名、license、publishConfignpmjs 公开访问与repository.directoryai/skills/lynx-api-docs必须精确匹配关键文件cli.js、CHANGELOG.md、LICENSE、README.md、技能目录下的AGENTS.md/README.md/SKILL.md必须齐备不得包含非公开内容技能目录下不允许存在config/子目录elements/下不允许存在x-*.md这类私有元素文档test.js 在安装测试中同样断言了.ai/lynx-api-docs/elements下无x-*.md文件全仓库的 js/json/md/yml 文件中出现的xxx/lynx-api-docs包名引用必须统一为公开品牌lynx-js/lynx-api-docs。这与 README 中本包只文档化 public surface的承诺形成闭环包内容边界由脚本在发布前强制把关而不是靠约定。八、Agent 侧的检索策略与上下文预算README.md 的Usage Recommendations给出了面向上游 DSL 框架技能的按意图加载示例const loadContext (intent: string) { const base load(quick-reference.md); switch (intent) { case layout: return base load(layout/ layoutType .md); case element: return base load(elements/ elementName .md); case migration: return base load(lynx-vs-web/migration-guide.md); default: return base load(best-practices.md); } };即速查文档打底 按任务加载一篇专项文档这与 AGENTS.md 索引的分类粒度每类 215 篇正好匹配。README 总结的六条关键要点布局选择策略、默认行为、盒模型、单位建议rem/vw、性能优先、用平台能力前先读对应元素参考则与 quick-reference.md 中Simple list →linear默认且最高效、Flexible →flex、2D →grid、Relative positioning →relative的布局速查表互相呼应构成 Agent 决策的最外层摘要。九、小结一份 10 行文件背后的设计回到 AGENTS.md 本身它体现的是一种可复用的Agent 文档工程模式索引与内容分离10 行的索引文件声明root根指针和 7 类文档地图正文分散在 40 余篇按需加载的 Markdown 中上下文成本恒定且小格式机器可改写首行的root:值由 CLI 在安装时替换为宿主工程的真实路径renderAgentsContent同一份源文件既能直接用于本仓库也能被移植到任意第三方工程注入幂等且可追溯托管代码块BEGIN/END MANAGED BLOCK让工具生成的内容与人工维护的内容严格隔离可重复安装、可检测漂移规则文件驱动行为SKILL.md 把检索优先于预训练固化为 Agent 的强制工作流并用 Web 假设失效清单与红旗项降低 Lynx 代码的典型错误率边界由脚本保证路径逃逸防护、dry-run、发布前布局自检三层校验保证了这个把文档 工作流一起分发的机制在任意宿主工程中安全运行。对于在 Lynx 项目中使用 AI 编码代理的开发者推荐的落地方式就是前文给出的npx lynx-js/lynx-api-docs install先用--dry-run预览安装完成后宿主工程的AGENTS.md中会多出一段指向.ai/lynx-api-docs的托管索引块Agent 即获得索引在手、文档按需检索的完整能力。【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考