open-slide current-slide Skill 指南：用 current.json 精准定位 Agent 当前正在查看的幻灯片与元素

【免费下载链接】open-slideA slide framework built for agents.项目地址https://gitcode.com/gh_mirrors/op/open-slide点击查看免费下载本指南以 open-slide 仓库中的 Agent Skill 文档 current-slide/SKILL.md 为核心讲解当用户说出这个页面、这张幻灯片、我正看的这页等指代性deictic表述时Agent 应如何通过 dev server 实时写出的node_modules/.open-slide/current.json文件来定位用户当前所处的幻灯片、页码乃至选中元素。读完本文你将掌握该文件的完整字段语义、读取时机、新鲜度判断规则、失效场景与端到端实现原理从前端 HMR 消息到 Vite 插件的原子写入从而在 open-slide 的 Agent 协作流程中避免改错文件这一最常见的错误。背景Agent 协作中的当前上下文难题open-slide 是一个为 Agent 构建的幻灯片框架详见仓库根目录 README.md开发者会直接对着 dev viewer 说修一下这个页面、把这里放大一点、我正看的那张图换掉——他们几乎不会说出slideId、页码或元素名。此时 Agent 面临一个信息缺口用户指的这里到底对应哪个文件、哪一页、哪一行 JSXcurrent-slideSkill 的答案非常直接不要反问先读文件。open-slide 的 dev server 在用户每一次导航切换幻灯片、翻页和每一次 inspector 选中点击元素时都会把最新的位置信息写入node_modules/.open-slide/current.json。这个文件就是用户现在在哪的权威实时游标是解开一切指代性表述的钥匙。current.json 是什么一条从浏览器到磁盘的数据链路从源码可以确认这条链路的两端。写入端是 dev server 注册的 Vite 插件currentPlugin位于 packages/core/src/vite/current-plugin.ts它通过server.ws.on(open-slide:current, ...)监听浏览器端通过 HMR WebSocket 发来的消息并把最新状态写入path.join(userCwd, node_modules, .open-slide)目录下的current.jsoncurrent-plugin.ts 第 69-70 行。该插件在 vite/config.ts 第 85 行 被装配进核心 Vite 插件链slidesDir默认取slides即用户项目根下存放幻灯片的目录。消息的发送端在浏览器渲染层页面级导航幻灯片路由 packages/core/src/app/routes/slide.tsx 第 160-167 行 在slideId / pageIndex / totalPages / slideTitle / view任一变化时通过import.meta.hot.send(open-slide:current, {...})上报导航状态元素级选中同文件中的SelectionReporter组件slide.tsx 第 1092-1107 行监听 inspector 的选中结果把line / column / tagName / text文本经空白压缩并截断到 120 字符随{ selection }一并发送。插件收到消息后做一层防御性校验非法slideId直接丢弃、pageIndex被钳制到[0, totalPages-1]、selection的字段逐个做类型与范围检查然后以先写current.json.tmp再rename的原子方式落盘避免 Agent 读到半截文件current-plugin.ts 第 132-139 行。文件路径相对于用户项目根目录即包含slides/与package.json的那个目录而不是相对于 open-slide 核心包本身。字段详解current.json 里每一项的准确语义一个典型的current.json内容如下示例取自原 Skill 文档{ slideId: q2-roadmap, pageIndex: 2, pageNumber: 3, totalPages: 8, slideTitle: Q2 Roadmap, view: slides, pagePath: slides/q2-roadmap/index.tsx, selection: { line: 42, column: 6, tagName: h1, text: Q2 Roadmap }, updatedAt: 2026-05-09T14:32:11.123Z }各字段语义如下字段含义使用要点slideIdslides/下的文件夹名直接作为/__slides/id/...系列 API 的参数或 URL 段使用写入端会校验其必须匹配SLIDE_ID_RE /^[a-z0-9_-]$/i见 slide-ops.ts 第 5 行非法 id 会被丢弃pageIndex0 起始的页码对应index.tsx中export default [Cover, Body, ...]数组的下标即index.tsx中的 page 数组位置pageNumber1 起始的页码用于向用户表达第 3 页共 8 页也对应 URL 参数?pN源码中由pageIndex 1计算而来current-plugin.ts 第 117 行pagePath幻灯片源文件相对路径直接交给Read/Edit工具使用由path.join(slidesDir, slideId, index.tsx)生成current-plugin.ts 第 109 行slideTitle幻灯片标题来自slide.meta?.title ?? slideIdslide.tsx 第 164 行即未显式声明meta.title时回退为文件夹名viewslides画布视图或assets资源管理器为assets时用户是在为该幻灯片浏览资源文件而非查看页面Agent 应把焦点转向资源而非页面 JSX浏览器端由 URL 参数?view决定slide.tsx 第 155 行selection用户在 inspector 覆盖层中选中的 JSX 元素未选中时为null见下方专项说明updatedAt最近一次导航或选中变化的 ISO 时间戳用于判断数据是否已过期stalenessselection 子字段的精确语义line1 起始与column0 起始指向pagePath内 JSX开标签的位置。这是权威句柄——Agent 必须对照源文件行而不是渲染后的 DOM 去匹配写入端在 current-plugin.ts 第 59-60 行 把line钳制为不小于 1 的整数、column钳制为不小于 0 的整数tagName是渲染后的 DOM 标签名统一小写h1、div、img并会被截断到 32 字符以内current-plugin.ts 第 52-53 行text是元素textContent的空白压缩、去首尾空白后截断到 ≤120 字符的文本片段用作确认找对了节点的 sanity check选中状态会在用户切换到不同幻灯片或页码时自动清空——写入端在检测到slideId或pageIndex变化时会把selection重置为nullcurrent-plugin.ts 第 111-113 行因此旧选中永远不会跨页残留。使用时机何时必须读 current.json应当使用的场景用户以指代性方式引用当前幻灯片/页面这个、这里、我正看的这页、我正在看的这张幻灯片、我在弄的那个用户引用某个具体元素这个标题、这张图、我刚才点的那个按钮、把这个收紧一点、改一下这个的颜色——如果selection非空它指向的就是用户所指的元素在反问哪张幻灯片或哪个元素之前先读这个文件在依据git log、最近编辑过的文件或最近创建的幻灯片文件夹去猜测之前先读这个文件。不应当使用的场景用户已显式说出幻灯片名如改一下q2-roadmap——直接用这个名字即可无需查文件apply-comments工作流已通过源码内的slide-comment标记定位文件它不需要这个 skill相关流程见 apply-comments/SKILL.md需要列出或发现幻灯片时——直接读slides/目录即可。核心纪律每一轮指代性对话都必须重新读取current.json是一个实时游标live cursor而不是关于对话的事实。用户会在你的两轮思考之间自由地切换幻灯片、页码和元素——包括在你做其他工作期间。因此 Skill 文档强调在每一轮使用指代性引用的新回合开始时都要重新读取该文件即使你在同一段对话中已经读过它你刚刚编辑完它指向的幻灯片用户的新消息听起来像是承接上一轮现在把它再调大一点、顺便把这个也修一下、继续。继续编辑恰恰是最容易踩坑的情况用户很可能刚刚导航到了另一张幻灯片或选中了另一个元素。若还信任上一次读取的值就会静默地改错文件。正确做法是重新读取后把这次的slideId/pageIndex/selection与上次用过的值做比对然后基于新值行动。经验法则如果updatedAt比你上一轮看到的更新那就是用户已经移动位置的正常信号——无需追问直接切到新的slideId/pageIndex/selection。新鲜度判断把 updatedAt 当缓存看待updatedAt是用户最后一次导航的时间。Skill 文档给出的分级策略新鲜约 5 分钟以内直接信任它。打开pagePath开始干活超过约 5 分钟编辑前先与用户确认。dev server 可能已不在运行用户也可能已切换了上下文数小时乃至数天前忽略它直接询问用户指的是哪张幻灯片。文件缺失时的处理以下两种情况会导致current.json不存在dev server 从未在任一幻灯片上被打开过dev server 从未运行过。此时不要自行创建该文件也不要凭空猜测。正确做法是询问用户指的是哪张幻灯片或建议用户先在 dev server 中打开该幻灯片。实战示例示例一页面级指代——收紧这个页面的间距读取node_modules/.open-slide/current.json检查updatedAt是否足够新读取pagePath如slides/q2-roadmap/index.tsx定位 default 导出数组中pageIndex对应的那个页面组件参考slide-authoringskill 中的间距规则见 slide-authoring/SKILL.md就地编辑该页面。如果current.json缺失或已过期可以这样回应您想收紧哪张幻灯片、哪一页的间距dev server 最近没有发布当前页信息。示例二元素级指代——把这个再放大一点读取node_modules/.open-slide/current.json若selection非空用户指的就是该元素。读取pagePath跳到selection.line在附近找到对应的 JSX 开标签并用selection.text片段和tagName确认无误编辑前先查阅slide-authoring中的字号阶梯与布局规则就地编辑该 JSX 节点。如果selection为null则回退到上面的页面级流程——并考虑询问您指的是哪个元素用户用了指代性表述但还没有在 inspector 中选中具体元素。源码级深入写入端如何保证数据可信理解了读取契约后再看写入端的实现current-plugin.ts 全文仅 143 行可以发现几处为Agent 读取安全服务的细节消息即最新状态插件每次收到open-slide:current消息时都以cached为基底合并新值并整体覆盖写盘天然保证每次导航/选中都产生一次完整的最新快照无状态兜底若收到的是仅含selection的消息如 inspector 点击而页面未变化会沿用缓存中的slideId / pageIndex等字段只更新选中与时间戳避免状态回退防御性校验非法slideId不匹配SLIDE_ID_RE直接 returnpageIndex会被Math.max(0, Math.min(totalPages - 1, rawIndex))钳制杜绝越界值污染文件原子写盘先写current.json.tmp再rename为current.json保证 Agent 在任何时刻读取到的都是完整 JSON而非写入中途的半截内容写盘失败被 catch 掉best-effort不会因此崩溃 dev server。这些实现细节意味着只要 dev server 在运行且用户与界面发生过交互current.json就始终是一个结构完整、经过校验、语义一致的位置快照——这正是 Agent 敢直接依赖它的前提。与其余 Skill 的分工协作在 open-slide 的 Agent 技能体系中current-slide的职责被刻意收窄为解析指代性引用具体如何编辑则由其他 Skill 承接current-slide负责把这个页面/这个元素解析为具体的slideId pageIndex selectionslide-authoring/SKILL.md 是页面编辑的技术参考规定了slides/id/index.tsx的文件契约default 导出为按页顺序排列的零参数组件数组、1920×1080 画布、类型阶梯、布局与调色板规则等current-slide的示例流程中编辑前查阅间距/字号规则指向的就是它apply-comments/SKILL.md 通过slide-comment标记自带定位能力因此明确声明不需要 current-slidecreate-slide/SKILL.md 负责起草新幻灯片的完整工作流同样会把具体的怎么写委托给slide-authoring。这套分工意味着Agent 在收到指代性编辑指令时应先读current.json定位再进入slide-authoring的规则体系执行编辑两者缺一不可。掌握current.json的读取纪律是 open-slide 上所有 Agent 安全编辑的前提——它把用户在哪儿从模糊的对话推断变成了一个可读、可校验、可失效判定的文件事实。赞分享【免费下载链接】open-slideA slide framework built for agents.项目地址https://gitcode.com/gh_mirrors/op/open-slide点击查看免费下载相关推荐Pearcleaner你的终极macOS清理管家告别应用残留轻松释放磁盘空间Pearcleaner你的终极macOS清理管家告别应用残留轻松释放磁盘空间 你是否曾经卸载过macOS应用却发现系统里还残留着各种缓存、偏好设置和支持文Pandoc Beamer 幻灯片实战用 --slide-level 与 columns 分栏精准控制帧结构Pandoc Beamer 幻灯片实战用 slide level 与 columns 分栏精准控制帧结构 导读 本文以 pandoc 官方测试用例 test/文档开发工具CLIopen-slide 项目模板完全指南从零开始创作 AI Agent 驱动的 React 幻灯片open slide 项目模板完全指南从零开始创作 AI Agent 驱动的 React 幻灯片 open slide 是一个面向 Agent如 Claud上一篇10分钟上手Suiron自动驾驶RC车快速启动教程下一篇hekate 启动 LogoBootlogo完全指南尺寸规格、ARGB BMP 格式与 logopath 配置详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考