VSCode Agent Sessions 运行命令生成指南基于 tasks.json 的inAgents任务与自动执行的完整实践【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscodeAgent Session智能会话/代理会话工作区顶部标题栏的Run 按钮可以让用户一键执行项目的安装、开发等常用命令。这些出现在 Run 按钮中的运行命令并非特设功能而是以 VSCode 标准任务tasks.json为基础、通过inAgents标记接入的一套机制。本指南以官方内置技能 generate-run-commands/SKILL.md 为主线讲解运行命令的任务模式schema、生成与修改的决策逻辑、文件写入与合并规则并结合仓库源码揭示inAgents、runOptions.runOn worktreeCreated从配置解析到自动调度的完整链路。读完你将能够为任意 Agent Session 工作区正确编写、推断、合并与调试运行命令。Skill 的定位内置技能如何参与运行命令在仓库中generate-run-commands属于 Agent 会话的内置技能skills之一与commit、code-review、create-pr等并列存放于 src/vs/sessions/skills 目录。它的作用由文档头部的 YAML Front Matter 定义name: generate-run-commands description: Generate or modify run commands for the current session. Use when the user wants to set up or update run commands that appear in the sessions Run button.即当用户希望为当前会话设置或更新出现在标题栏 Run 按钮中的运行命令时Agent 就会调用该技能。SKILL.md 本身属于可定制的内置技能——文档第一行注释明确说明在产品内可以自定义并保存副本以覆盖其默认行为删除该副本则恢复内置行为。因此理解这份技能文档的本质就是理解 VSCode 对运行命令这一概念的标准建模。任务模式Task Schema运行命令到底是什么SKILL.md 给出的第一个核心结论是一个运行命令就是一个tasks.json中的任务task它依赖两个关键字段inAgents: true—必填使该任务出现在 Agent会话的 Run 按钮中runOptions: { runOn: worktreeCreated }—可选每当新建 worktree 时自动运行该任务用于 setup/install 类命令。文档给出的最小可用示例为{ tasks: [ { label: Install dependencies, type: shell, command: npm install, inAgents: true, runOptions: { runOn: worktreeCreated } }, { label: Start dev server, type: shell, command: npm run dev, inAgents: true } ] }示例展示了两类典型任务一类是带runOn: worktreeCreated的环境准备命令安装依赖另一类是仅带inAgents: true的常驻/启动命令启动开发服务器。二者的差异正是环境就绪与按需运行两种语义的划分。源码中的字段定义在任务模型 tasks.ts 中inAgents的注释直接印证了它的职责——Show this task in the Agents run action dropdown将该任务显示在 Agents 的 run 操作下拉菜单中它与hide不显示在 run task 快速选择器中是同一层级配置属性。runOn则由内部枚举RunOnOptions支撑export enum RunOnOptions { default 1, folderOpen 2, worktreeCreated 3 }IRunOptions实际包含四个属性任务配置模块 taskConfiguration.ts 在解析时会为未显式给出的属性补齐默认值runOptions 属性默认值说明来自 taskConfiguration.tsreevaluateOnReruntrue重新运行时是否重新评估任务runOndefault触发的时机见下方枚举instanceLimit1可并发运行的最大实例数解析时取max(配置值, 1)instancePolicyprompt实例数达到上限时的策略terminateNewest/terminateOldest/prompt/warn/silent值得注意的是SKILL.md 只用了runOn一个字段但 JSON Schema 层面为runOn定义了三档取值见 jsonSchema_v2.tsdefault、folderOpen文件夹打开时自动运行、worktreeCreated创建 Agent Session worktree 时自动运行。而 taskConfiguration.ts 的 RunOnOptions.fromString 在解析时对值做toLowerCase()后匹配因此folderOpen/worktreeCreated的大小写写法均会被正确识别。校验与自动补全inAgents与runOn均已纳入任务的 JSON Schema 校验见 jsonSchema_v2.ts 对inAgents的描述这意味着在编辑器内手写tasks.json时同样可以获得校验、悬浮提示与取值枚举补全inAgents语法错误的概率很低与技能生成的写法完全一致。决策逻辑Decision Logic先查、后改、必要时再问SKILL.md 为 Agent 规定的决策流程高度务实核心是能推断就不打扰用户先读取现有的.vscode/tasks.json检查是否已存在运行命令即inAgents: true的任务。若已存在运行命令将其视为修改请求modify request——询问用户具体想做什么新增、删除还是更新某条命令。若不存在运行命令尝试根据工作区内容推断合理命令检查package.json、Makefile、pyproject.toml、Cargo.toml、go.mod、.nvmrc等工程文件以识别技术栈与常用命令若 setup 命令明确如npm install、pip install -r requirements.txt直接添加并配置runOptions: { runOn: worktreeCreated }无需询问若主要 run/dev 命令明确如npm run dev、cargo run直接添加仅带inAgents: true仅当命令存在歧义时才询问用户例如存在多个同等合理的选项、无法识别项目结构或项目采用了非标准 setup。推断来源的工程信号上述工程文件覆盖了前端package.json.nvmrc锁定 Node 版本、Make 系项目、Pythonpyproject.toml、RustCargo.toml、Gogo.mod等主流生态。这一从项目清单文件反推启动命令的思路与仓库中SessionsTasksService面向多目标读取任务的设计相呼应——任务既可以从工作区根目录的.vscode/tasks.json读取也可以来自用户级 tasks 配置从而保证不同会话形态都能获得一致的可运行命令集合。读取与修改背后的服务能力技能文档描述的是 Agent 的行为准则而其底层能力由 sessionsTasksService.ts 提供文档中的每一步都能在接口上找到对应实现**先读现有运行命令**对应getSessionTasksOnce()——该方法一次性返回会话任务inAgents: true快照实现即按t !!t.inAgents过滤sessionsTasksService.ts**新增命令**对应createAndAddTask()——创建一个inAgents: true的 shell 任务并写入合适的tasks.json工作区或用户级**修改既有任务/打标**对应addTaskToSessions()与updateTask()——其中addTaskToSessions会按 label 定位既有任务通过 JSON 编辑在路径[tasks, index, inAgents]上写入true实现原地把普通任务变成运行命令**删除命令**对应removeTask()——按任务 label 从目标tasks.json中移除会话中不运行命令的普通任务也并未被忽略——getNonSessionTasks()专门返回不带inAgents: true的任务作为Add Run Action添加运行操作选择器中的候选建议sessionsTasksService.ts。也就是说运行命令并非一套独立的文件格式而是对既有 VSCode Task 体系的一层视图过滤inAgents决定它是否进入 Run 按钮的可见集合其余任务定义能力dependsOn依赖、shell 类型等原样保留。例如getAllTasks()会返回全部任务含无inAgents的以便 agent-host 运行时通过dependsOn解析被运行命令依赖的普通任务。文件写入与合并规则SKILL.md 对落盘行为有两个硬性要求始终写入工作区根目录的.vscode/tasks.json若文件已存在则合并绝不覆盖无关任务mergedo not overwrite unrelated tasks。写入完成后Agent 应简要向用户确认新增了哪些命令以及如何从 Run 按钮触发它们。合并示例若工作区已存在一组用于调试的任务那么新增运行命令的正确结果应如下所示——保留原有任务仅追加两个inAgents条目{ version: 2.0.0, tasks: [ { label: Debug tests, type: shell, command: npm run test -- --debug, problemMatcher: [] }, { label: Install dependencies, type: shell, command: npm install, inAgents: true, runOptions: { runOn: worktreeCreated } }, { label: Start dev server, type: shell, command: npm run dev, inAgents: true } ] }为什么强调不覆盖从实现侧看tasks.json承载的是整个工作区的任务声明其中既包含作为运行命令的inAgents任务也包含大量仅供 Run Task 面板、调试配置或其他工具消费的普通任务。若采用整文件覆写策略会破坏problemMatcher、自定义options.cwd、dependsOn链等既有配置。因此 Agent 端正确的合并策略与 sessionsTasksService.ts 中按 label 定位任务、以属性级 JSON 补丁写入inAgents: true、或仅追加新任务条目的编辑粒度保持一致。运行命令如何被触发Run 按钮与 worktree 自动执行Run 按钮与下拉菜单inAgents: true的任务会出现在会话标题栏 Run 按钮的下拉菜单中点击即运行。这与任务的读取链路getSessionTasks/getSessionTasksOnce的!!t.inAgents过滤一致只有当inAgents为真时任务才会被纳入该视图。worktreeCreated 的自动调度原理runOn: worktreeCreated的真正含义值得深挖它指在Agent Session 创建了实际 git worktree 时自动执行该任务。仓库中的 worktreeCreatedTaskDispatcher.ts 以 workbench 贡献点workbench.contrib.sessions.worktreeCreatedTaskDispatcher实现了这一逻辑其行为要点每个新会话只触发一次当某会话首次报告真实的 git worktree监视条件为session.workspace中存在带workTreeUri的文件夹时调度器拉取该会话全部任务逐个执行runOptions.runOn worktreeCreated的条目避免重复执行若会话的运行时本身已在服务端执行过这些任务通过ISessionCapabilities.runsWorktreeCreatedTasks信号标识调度器会直接跳过防止双重执行随会话生命周期清理被调度任务返回的 stop handles 按会话跟踪当会话被归档archived或移除时统一 dispose避免 setup/构建这类长生命周期进程泄漏可开关Agent host 会话是否自动执行worktreeCreated任务受设置chat.agentHost.runWorktreeCreatedTasks控制默认true关闭后仅影响自动调度手动通过 Run Task 面板运行不受影响。这意味着一个Install dependencies配置了runOn: worktreeCreated后Agent 每创建一个新 worktree 就能自动获得已就绪的依赖环境——这正是 SKILL.md 将 setup 类命令与worktreeCreated绑定的原因用一条配置换取每个新工作区的零手工准备。实战注意事项基于上述机制在实际使用或让 Agent 生成运行命令时值得关注以下几点区分两类语义依赖安装、构建产物准备这类环境就绪命令应加runOptions: { runOn: worktreeCreated }而 dev server、测试等需用户按需触发的命令只加inAgents: true避免在每次建 worktree 时被自动拉起。让 Agent 先探查再写入技能要求 Agent 先读现有.vscode/tasks.json因此当工作区已有运行命令时向 Agent 明确提出新增/删除/更新哪条命令比笼统地帮我配一下更高效。合并优于覆写无论是人工编辑还是让 Agent 修改都应保留文件中的既有任务不确定时可先查看该文件确认任务 label避免与已有条目冲突。利用普通任务的迁移若工作区已有期望出现在 Run 按钮里的任务可通过会话的Add Run Action将非inAgents任务打上标记而无须复制一份命令。验证与回退所有任务字段均在 jsonSchema_v2.ts 定义的 Schema 校验之下若希望从 Agent 生成的运行命令恢复到内置默认行为删除技能的自定义副本即可。深入阅读技能本体src/vs/sessions/skills/generate-run-commands/SKILL.md以及 src/vs/sessions/skills 下的全部内置技能任务数据模型与inAgents/RunOnOptions定义src/vs/workbench/contrib/tasks/common/tasks.ts任务 JSON Schema含inAgents与runOn枚举src/vs/workbench/contrib/tasks/common/jsonSchema_v2.tsrunOn/runOptions解析与默认值任务配置解析 src/vs/workbench/contrib/tasks/common/taskConfiguration.ts会话任务服务读取、打标、新建、删除运行命令src/vs/sessions/contrib/chat/browser/sessionsTasksService.tsworktreeCreated 自动执行调度器src/vs/sessions/contrib/chat/browser/worktreeCreatedTaskDispatcher.ts。综上VSCode Agent Session 的运行命令机制可以总结为一句话标准tasks.json任务 inAgents可见性标记 可选的runOn: worktreeCreated自动触发。掌握这套模式后无论是人工编辑还是借助generate-run-commands技能都能为会话工作区快速搭建出创建即就绪、按钮即启动的完整运行体验。【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VSCode Agent Sessions 运行命令生成指南：基于 tasks.json 的 `inAgents` 任务与自动执行的完整实践
VSCode Agent Sessions 运行命令生成指南基于 tasks.json 的inAgents任务与自动执行的完整实践【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscodeAgent Session智能会话/代理会话工作区顶部标题栏的Run 按钮可以让用户一键执行项目的安装、开发等常用命令。这些出现在 Run 按钮中的运行命令并非特设功能而是以 VSCode 标准任务tasks.json为基础、通过inAgents标记接入的一套机制。本指南以官方内置技能 generate-run-commands/SKILL.md 为主线讲解运行命令的任务模式schema、生成与修改的决策逻辑、文件写入与合并规则并结合仓库源码揭示inAgents、runOptions.runOn worktreeCreated从配置解析到自动调度的完整链路。读完你将能够为任意 Agent Session 工作区正确编写、推断、合并与调试运行命令。Skill 的定位内置技能如何参与运行命令在仓库中generate-run-commands属于 Agent 会话的内置技能skills之一与commit、code-review、create-pr等并列存放于 src/vs/sessions/skills 目录。它的作用由文档头部的 YAML Front Matter 定义name: generate-run-commands description: Generate or modify run commands for the current session. Use when the user wants to set up or update run commands that appear in the sessions Run button.即当用户希望为当前会话设置或更新出现在标题栏 Run 按钮中的运行命令时Agent 就会调用该技能。SKILL.md 本身属于可定制的内置技能——文档第一行注释明确说明在产品内可以自定义并保存副本以覆盖其默认行为删除该副本则恢复内置行为。因此理解这份技能文档的本质就是理解 VSCode 对运行命令这一概念的标准建模。任务模式Task Schema运行命令到底是什么SKILL.md 给出的第一个核心结论是一个运行命令就是一个tasks.json中的任务task它依赖两个关键字段inAgents: true—必填使该任务出现在 Agent会话的 Run 按钮中runOptions: { runOn: worktreeCreated }—可选每当新建 worktree 时自动运行该任务用于 setup/install 类命令。文档给出的最小可用示例为{ tasks: [ { label: Install dependencies, type: shell, command: npm install, inAgents: true, runOptions: { runOn: worktreeCreated } }, { label: Start dev server, type: shell, command: npm run dev, inAgents: true } ] }示例展示了两类典型任务一类是带runOn: worktreeCreated的环境准备命令安装依赖另一类是仅带inAgents: true的常驻/启动命令启动开发服务器。二者的差异正是环境就绪与按需运行两种语义的划分。源码中的字段定义在任务模型 tasks.ts 中inAgents的注释直接印证了它的职责——Show this task in the Agents run action dropdown将该任务显示在 Agents 的 run 操作下拉菜单中它与hide不显示在 run task 快速选择器中是同一层级配置属性。runOn则由内部枚举RunOnOptions支撑export enum RunOnOptions { default 1, folderOpen 2, worktreeCreated 3 }IRunOptions实际包含四个属性任务配置模块 taskConfiguration.ts 在解析时会为未显式给出的属性补齐默认值runOptions 属性默认值说明来自 taskConfiguration.tsreevaluateOnReruntrue重新运行时是否重新评估任务runOndefault触发的时机见下方枚举instanceLimit1可并发运行的最大实例数解析时取max(配置值, 1)instancePolicyprompt实例数达到上限时的策略terminateNewest/terminateOldest/prompt/warn/silent值得注意的是SKILL.md 只用了runOn一个字段但 JSON Schema 层面为runOn定义了三档取值见 jsonSchema_v2.tsdefault、folderOpen文件夹打开时自动运行、worktreeCreated创建 Agent Session worktree 时自动运行。而 taskConfiguration.ts 的 RunOnOptions.fromString 在解析时对值做toLowerCase()后匹配因此folderOpen/worktreeCreated的大小写写法均会被正确识别。校验与自动补全inAgents与runOn均已纳入任务的 JSON Schema 校验见 jsonSchema_v2.ts 对inAgents的描述这意味着在编辑器内手写tasks.json时同样可以获得校验、悬浮提示与取值枚举补全inAgents语法错误的概率很低与技能生成的写法完全一致。决策逻辑Decision Logic先查、后改、必要时再问SKILL.md 为 Agent 规定的决策流程高度务实核心是能推断就不打扰用户先读取现有的.vscode/tasks.json检查是否已存在运行命令即inAgents: true的任务。若已存在运行命令将其视为修改请求modify request——询问用户具体想做什么新增、删除还是更新某条命令。若不存在运行命令尝试根据工作区内容推断合理命令检查package.json、Makefile、pyproject.toml、Cargo.toml、go.mod、.nvmrc等工程文件以识别技术栈与常用命令若 setup 命令明确如npm install、pip install -r requirements.txt直接添加并配置runOptions: { runOn: worktreeCreated }无需询问若主要 run/dev 命令明确如npm run dev、cargo run直接添加仅带inAgents: true仅当命令存在歧义时才询问用户例如存在多个同等合理的选项、无法识别项目结构或项目采用了非标准 setup。推断来源的工程信号上述工程文件覆盖了前端package.json.nvmrc锁定 Node 版本、Make 系项目、Pythonpyproject.toml、RustCargo.toml、Gogo.mod等主流生态。这一从项目清单文件反推启动命令的思路与仓库中SessionsTasksService面向多目标读取任务的设计相呼应——任务既可以从工作区根目录的.vscode/tasks.json读取也可以来自用户级 tasks 配置从而保证不同会话形态都能获得一致的可运行命令集合。读取与修改背后的服务能力技能文档描述的是 Agent 的行为准则而其底层能力由 sessionsTasksService.ts 提供文档中的每一步都能在接口上找到对应实现**先读现有运行命令**对应getSessionTasksOnce()——该方法一次性返回会话任务inAgents: true快照实现即按t !!t.inAgents过滤sessionsTasksService.ts**新增命令**对应createAndAddTask()——创建一个inAgents: true的 shell 任务并写入合适的tasks.json工作区或用户级**修改既有任务/打标**对应addTaskToSessions()与updateTask()——其中addTaskToSessions会按 label 定位既有任务通过 JSON 编辑在路径[tasks, index, inAgents]上写入true实现原地把普通任务变成运行命令**删除命令**对应removeTask()——按任务 label 从目标tasks.json中移除会话中不运行命令的普通任务也并未被忽略——getNonSessionTasks()专门返回不带inAgents: true的任务作为Add Run Action添加运行操作选择器中的候选建议sessionsTasksService.ts。也就是说运行命令并非一套独立的文件格式而是对既有 VSCode Task 体系的一层视图过滤inAgents决定它是否进入 Run 按钮的可见集合其余任务定义能力dependsOn依赖、shell 类型等原样保留。例如getAllTasks()会返回全部任务含无inAgents的以便 agent-host 运行时通过dependsOn解析被运行命令依赖的普通任务。文件写入与合并规则SKILL.md 对落盘行为有两个硬性要求始终写入工作区根目录的.vscode/tasks.json若文件已存在则合并绝不覆盖无关任务mergedo not overwrite unrelated tasks。写入完成后Agent 应简要向用户确认新增了哪些命令以及如何从 Run 按钮触发它们。合并示例若工作区已存在一组用于调试的任务那么新增运行命令的正确结果应如下所示——保留原有任务仅追加两个inAgents条目{ version: 2.0.0, tasks: [ { label: Debug tests, type: shell, command: npm run test -- --debug, problemMatcher: [] }, { label: Install dependencies, type: shell, command: npm install, inAgents: true, runOptions: { runOn: worktreeCreated } }, { label: Start dev server, type: shell, command: npm run dev, inAgents: true } ] }为什么强调不覆盖从实现侧看tasks.json承载的是整个工作区的任务声明其中既包含作为运行命令的inAgents任务也包含大量仅供 Run Task 面板、调试配置或其他工具消费的普通任务。若采用整文件覆写策略会破坏problemMatcher、自定义options.cwd、dependsOn链等既有配置。因此 Agent 端正确的合并策略与 sessionsTasksService.ts 中按 label 定位任务、以属性级 JSON 补丁写入inAgents: true、或仅追加新任务条目的编辑粒度保持一致。运行命令如何被触发Run 按钮与 worktree 自动执行Run 按钮与下拉菜单inAgents: true的任务会出现在会话标题栏 Run 按钮的下拉菜单中点击即运行。这与任务的读取链路getSessionTasks/getSessionTasksOnce的!!t.inAgents过滤一致只有当inAgents为真时任务才会被纳入该视图。worktreeCreated 的自动调度原理runOn: worktreeCreated的真正含义值得深挖它指在Agent Session 创建了实际 git worktree 时自动执行该任务。仓库中的 worktreeCreatedTaskDispatcher.ts 以 workbench 贡献点workbench.contrib.sessions.worktreeCreatedTaskDispatcher实现了这一逻辑其行为要点每个新会话只触发一次当某会话首次报告真实的 git worktree监视条件为session.workspace中存在带workTreeUri的文件夹时调度器拉取该会话全部任务逐个执行runOptions.runOn worktreeCreated的条目避免重复执行若会话的运行时本身已在服务端执行过这些任务通过ISessionCapabilities.runsWorktreeCreatedTasks信号标识调度器会直接跳过防止双重执行随会话生命周期清理被调度任务返回的 stop handles 按会话跟踪当会话被归档archived或移除时统一 dispose避免 setup/构建这类长生命周期进程泄漏可开关Agent host 会话是否自动执行worktreeCreated任务受设置chat.agentHost.runWorktreeCreatedTasks控制默认true关闭后仅影响自动调度手动通过 Run Task 面板运行不受影响。这意味着一个Install dependencies配置了runOn: worktreeCreated后Agent 每创建一个新 worktree 就能自动获得已就绪的依赖环境——这正是 SKILL.md 将 setup 类命令与worktreeCreated绑定的原因用一条配置换取每个新工作区的零手工准备。实战注意事项基于上述机制在实际使用或让 Agent 生成运行命令时值得关注以下几点区分两类语义依赖安装、构建产物准备这类环境就绪命令应加runOptions: { runOn: worktreeCreated }而 dev server、测试等需用户按需触发的命令只加inAgents: true避免在每次建 worktree 时被自动拉起。让 Agent 先探查再写入技能要求 Agent 先读现有.vscode/tasks.json因此当工作区已有运行命令时向 Agent 明确提出新增/删除/更新哪条命令比笼统地帮我配一下更高效。合并优于覆写无论是人工编辑还是让 Agent 修改都应保留文件中的既有任务不确定时可先查看该文件确认任务 label避免与已有条目冲突。利用普通任务的迁移若工作区已有期望出现在 Run 按钮里的任务可通过会话的Add Run Action将非inAgents任务打上标记而无须复制一份命令。验证与回退所有任务字段均在 jsonSchema_v2.ts 定义的 Schema 校验之下若希望从 Agent 生成的运行命令恢复到内置默认行为删除技能的自定义副本即可。深入阅读技能本体src/vs/sessions/skills/generate-run-commands/SKILL.md以及 src/vs/sessions/skills 下的全部内置技能任务数据模型与inAgents/RunOnOptions定义src/vs/workbench/contrib/tasks/common/tasks.ts任务 JSON Schema含inAgents与runOn枚举src/vs/workbench/contrib/tasks/common/jsonSchema_v2.tsrunOn/runOptions解析与默认值任务配置解析 src/vs/workbench/contrib/tasks/common/taskConfiguration.ts会话任务服务读取、打标、新建、删除运行命令src/vs/sessions/contrib/chat/browser/sessionsTasksService.tsworktreeCreated 自动执行调度器src/vs/sessions/contrib/chat/browser/worktreeCreatedTaskDispatcher.ts。综上VSCode Agent Session 的运行命令机制可以总结为一句话标准tasks.json任务 inAgents可见性标记 可选的runOn: worktreeCreated自动触发。掌握这套模式后无论是人工编辑还是借助generate-run-commands技能都能为会话工作区快速搭建出创建即就绪、按钮即启动的完整运行体验。【免费下载链接】vscodeVisual Studio Code项目地址: https://gitcode.com/GitHub_Trending/vscode6/vscode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考