SuperAPI AI 工具集

session-log-canvas-update

编程与开发

查看项目

更新于 10-30 03:33

技能介绍

用途

Session Log Canvas Update 是一个用于维护 Session Log 画布准确性的技能。当新的 Copilot 版本改变了会话所记录的内容时,该技能负责找出画布构建所依据的 schema 与当前 schema 之间的差异,然后更新画布,使新增和变更的数据能够正确渲染,同时保证由早期版本记录的会话仍然可读。

该技能属于 HVE Core 仓库,应直接放在 .github/skills/session-log-canvas-update/ 下,位于包目录以及插件或 VSIX 成员之外。它所维护的画布位于 .github/extensions/hve-core/session-log/。

主要能力

  • 对比 schema:运行脚本列出已安装的 Copilot CLI schema,并针对每个相关 schema 生成差异报告,列出已处理类型中发生变化的字段、新增事件类型及其是否持久化、被移除的类型、其他变更类型,以及 schema 不再定义的已处理类型。
  • 检查真实会话而不读取内容:通过画布的 get_session_summary 动作获取 eventHealth.unknownTypes(画布未处理的持久化类型)和 unreadableLines(无法解析的行数)等统计信息。
  • 阅读发布说明:扫描基线版本与新版本之间的 changelog.json,查找会话事件、压缩、钩子、子代理、系统提示、存储以及扩展或画布相关变更。
  • 将变更映射到画布代码并分类:对索引器读取的变更字段先读新位置再回退旧位置;新增持久化类型决定其渲染方式并加入索引器 switch 与 HANDLED_EVENT_TYPES;被移除的类型或字段在旧会话仍可能包含时继续读取;临时类型除非变为持久化否则忽略。
  • 应用更改:为每个新增或变更的形态向画布测试夹具添加合成事件(绝不复制真实会话文本),扩展索引器、服务器和 UI,保持日志语法与风格指南一致,并更新风格指南的 Log Grammar 表和修订日志以及 README。
  • 验证:运行 npm run test:extensions 和 node --test 测试套件、node --check、npm run plugin:validate、Markdown lint 与拼写检查、仅针对合成夹具的浏览器检查,以及宿主重载。
  • 刷新基线:运行 snapshot 命令写入 assets/event-shapes.json,再次运行 diff 确认报告干净,并将基线与画布更改一起提交。

使用方式

该技能通过脚本和命令操作。输入参数包括:

  • mode(可选):check 仅报告变更及其影响而不编辑;update(默认)还会应用更改并刷新基线。
  • schema(可选):指定要对比的 schema,接受 session-events.schema.json 的路径、已安装的 Copilot 版本,或 latest(默认,最新安装的 Copilot CLI 包)。

常用命令示例:

  • 列出已安装 schema:node scripts/event-schema.mjs list(在技能根目录运行),或 node .github/skills/session-log-canvas-update/scripts/event-schema.mjs list(在仓库根目录运行)。
  • 对比 schema:node scripts/event-schema.mjs diff --schema <path|version|latest>,需要处理结果时使用 --json。
  • 刷新基线:node scripts/event-schema.mjs snapshot --schema <已验证的 schema> --write。

对于 VS Code 会话,还需定位 VS Code 捆绑的 schema,路径为 <VS Code app resources>/app/node_modules.asar.unpacked/@github/copilot-sdk-<platform>/schemas/session-events.schema.json,因为 VS Code 宿主可能运行比已安装 CLI 更新的运行时。会话记录的 copilotVersion 来自其 session.start 事件,画布的 get_session_summary 动作会返回它。

适用场景

适用于 Copilot 发布新版本后,会话事件、会话存储、系统提示结构或画布 SDK 发生变化,需要同步更新 Session Log 画布的场景。也适用于需要检查画布对新旧会话兼容性、验证渲染无回归、或刷新 schema 基线的维护工作。

限制

  • 只能通过画布或为了获取事件类型名称、字段名称、计数和大小而读取会话日志。不得打印、粘贴或持久化真实会话中的消息、提示、工具或摘要文本。
  • 脚本会读取 schema 文件、其 package.json 和基线,并导入画布索引器或通过 --indexer 传入的模块以读取其导出的类型列表。该模块在脚本进程中运行,因此只应传入可信模块。脚本仅写入 stdout,或在 snapshot --write 时写入 assets/event-shapes.json。SECURITY.md 记录了其威胁模型。
  • 基线仅保留事件和字段标识符及类型签名,绝不保留 schema 描述。
  • 优先使用许可证允许再分发派生标识符的包中的 schema,例如 VS Code 捆绑的 MIT 许可的 @github/copilot-sdk-<platform> 包。
  • 更改应保持在画布、其测试和文档以及本技能范围内。未经用户请求,不得提交、推送或发布。
  • 停止规则:当未找到已安装 schema 且未提供时,停止并询问 schema 路径;在 check 模式下分类报告后停止;当变更无法从 diff、发布说明和合成复现映射到画布行为时,作为 Blocked 停止并报告类型、字段及所需证据;当验证失败时作为 Revise 停止,报告失败的检查且不刷新基线。
  • 最终响应需报告对比的版本、分类的变更表(类型或表面、变更、画布影响、已采取或建议的操作)、更改的文件、带确切命令的验证结果、基线是否刷新及来自哪个 schema,以及任何阻塞项及其所需证据。