Goal for VS Code

把当前工作区的 Markdown 计划变成随时可见的 Goal。状态栏显示进度，侧边栏保存计划；临时切去修 Bug 后，可以恢复原任务，并复制一段提示词让 AI 接着执行。

开始使用

1. 打开工作区中的 Markdown 文件，在命令面板执行 Goal: Set Current File to Goal，或使用文件右键菜单中的同名命令。
2. 状态栏只显示一个紧凑的 Refactor current project · 2/6 · 33% 入口。悬停展开 Goal 卡片，查看进度、当前关注点和下一项任务；鼠标移入卡片即可操作。
3. 在卡片中点击 Copy AI handoff 复制提示词、Open plan 打开计划、Go to next task 跳到下一项；下方可以切换 Goal 或恢复暂停的任务。点击状态栏本身仍直接打开计划。
4. 打开左侧 Activity Bar 的 Goal，查看所有计划与进度（如 2/6 · 33%）。点击一个 Goal 就会打开文件并切换当前目标。

也可以执行 Goal: Add Goal 添加已有文件（可多选），或 Goal: Create Goal 创建新的 Markdown 计划。所有 Goal 文件都属于当前打开的工作区，支持多根工作区。

Markdown 格式

---
title: Refactor current project
description: Simplify the data layer while preserving existing behavior.
focus: Extract the repository interface
ai:
  role: Repository refactor agent
  protocol: Keep public APIs backward compatible and verify every change.
  skills: [typescript, testing]
---

# Refactor current project

- [x] Map the current data flow
- [x] Record compatibility requirements
- [-] Extract the repository interface
  <!-- goal: id=interface depends-on=compatibility -->
- [ ] Move consumers to the new interface
  <!-- goal: id=consumers depends-on=interface -->
- [ ] Remove the old implementation
  <!-- goal: id=cleanup depends-on=consumers -->
- [ ] Run regression tests

Frontmatter 可选，支持 YAML 的引号、多行文本等格式：

支持 -、*、+ 和有序列表，也支持嵌套与引用中的任务列表。

• [ ] 表示未完成，[x] / [X] 表示完成，[-] 表示正在进行。
• 可以在任务后面单独一行加不可见注释 <!-- goal: id=api depends-on=schema -->，为任务建立稳定 ID 和前置依赖。也兼容把注释放在任务行末尾。依赖未完成时任务会显示为 Blocked，不会被推荐为下一步。
• 所有真实任务框都参与计数，包含父任务与子任务；勾选子任务不会自动勾选父任务。
• 下一项任务优先取 [-]，再匹配 focus，最后选择第一个没有未完成子任务的未完成任务。
• 代码块、HTML 注释和 frontmatter 中的示例不会计入进度。普通文本中的 [] 也不会计数。
• 没有任务时显示 0/0；全部完成后提示检查结果。完成不会自动归档。

打开的文件即使尚未保存，进度也会更新。AI 或其他工具修改磁盘文件时，文件监听会刷新进度。侧边栏展开 Goal 后，点击任务可跳转到对应行，点击任务旁的勾选按钮可切换状态；该编辑支持撤销，按正常编辑流程保存。

中断、恢复与归档

侧边栏分为 Current Goal、Paused / Interrupted、Goals 和 Archive：

• 从 Goal A 切换到临时 Goal B，A 会自动暂停，并记录是哪个 Goal 打断了它。
• Goal: Resume Previous Goal 返回最近暂停的 Goal；支持多层中断。
• 右键 Archive Goal 将计划放入归档；如果归档的是当前 Goal，会自动恢复最近暂停的 Goal。
• 归档计划可以打开查看、复制提示词，或通过 Restore Goal 放回列表。
• Remove Goal from Sidebar 只移除记录，之后自动扫描也不会立即重新加入；可通过 Set Current File 或 Add Goal 再次添加。

归档与移除都保留 Markdown 文件。当前 Goal、暂停顺序、归档和排除列表保存在 VS Code 的本地工作区状态中，重启后恢复；文件内容才是任务进度的依据。通过 VS Code 重命名文件或目录时，Goal 会跟随更新。外部工具直接移动文件后，需要重新添加新路径；丢失的文件会显示不可用。

默认自动发现 .goals/、goals/ 中的 Markdown，以及 GOAL.md、GOALS.md。自动发现只添加计划，不会抢走当前 Goal。可通过设置修改匹配模式，或关闭自动发现。

AI 提示词

闪光图标复制的是给执行 AI 的工作交接提示词，包含文件路径、标题、完成数、下一项任务、可执行任务和被依赖阻塞的任务。例如：

Please follow the plan in the Markdown file ".goals/refactor.md".

Goal: Refactor current project
Progress: 2/6 tasks complete.
Next task: Extract the repository interface (line 12)
Ready tasks: Extract the repository interface [interface] (depends on: compatibility) (line 12)
Blocked tasks: Move consumers to the new interface [consumers] (depends on: interface) (line 13)

后续指令要求先读取完整计划与仓库说明，执行并验证任务后更新勾选状态，同时记录阻塞、决策和交接信息。多根工作区会在相对路径中保留文件夹名。协议还规定了 id、depends-on、[-] 和执行切片的写法。计划监督职责由单独的 Supervisor 承担。

机器人图标负责创建或打开仓库本地的 Goal Supervisor。插件会优先使用已经存在的 .claude/agents/ 或 .agents/，也可以通过 goal.subagentDirectory 固定目录；创建后会把绑定路径写入 Goal frontmatter：

subagent:
  path: .agents/goal-refactor.md
  name: goal-refactor
  format: .agents
  role: supervisor

Supervisor 只监督进度、修订计划、维护依赖、评估任务量和上下文成本、拆分可并行的执行切片，并记录 blockers、决策与交接信息。它不会代替执行 AI 编写产品代码。一个 Goal 只绑定一个仓库本地 Supervisor；删除绑定文件后再次点击机器人即可重新生成。

复制操作集中在 Goal 悬停卡片中，也可以执行 Goal: Copy AI Handoff Prompt。悬停本身不会修改剪贴板；若希望打开计划的同时复制提示词，启用 goal.copyPromptOnOpen。扩展通过剪贴板交接提示词，AI 执行后对 Markdown 的修改会反映为最新进度。

自定义模板支持 {path}、{title}、{completed}、{total}、{next}、{ready}、{blocked}、{protocol}、{agent} 和 {subagent}，例如：

{
  "goal.promptTemplate": "Please continue the plan in {path}. Goal: {title}. Progress: {completed}/{total}. Next: {next}. Update the checklist after verifying each task."
}

执行 AI、Goal Supervisor、依赖拓扑与执行切片

悬停卡片和 Goal 右键菜单提供闪光图标的 Copy AI handoff，复制当前 Goal 的执行上下文。机器人图标创建或打开 Goal Supervisor，两者职责分开：执行 AI 处理代码和验证，Supervisor 管理计划与进度。

在有依赖注释的 Goal 上使用 Dependencies 可以打开一份 Markdown 拓扑图。Goal 本身的 dependsOn 和任务的 depends-on 会同时列出，便于人和 AI 检查执行顺序。预览中的任务关系使用固定宽度的 monospace 代码块模拟树状图：|-- 表示还有后续分支，\-- 表示最后一个分支，汇合节点会标记为 (shown above)，缺失的前置任务会标记为 Missing dependency。

当计划很大时，在悬停卡片或右键菜单选择 Make slice，输入要抽出的 Ready 任务数量。插件会在 .goals/.slices/ 生成一个带 sourceGoal 和 sourceTasks frontmatter 的执行切片，任务正文不会再追加同步注释，并把它加入侧边栏。切片中的勾选会同步回源 Goal，源 Goal 仍然是进度事实来源；完成一个切片后可以继续生成下一批，避免每次交给 AI 的上下文包含数百个任务。

Dependencies 使用 VS Code 自带的 Markdown Preview 打开只读拓扑，不会创建可保存的 Untitled 文件，关闭预览即可。

开发与验证

需要 Node.js 22.12+、Bun 1.3.13 和 VS Code 1.95+。

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run package

选择 Run Extension (sample) 并按 F5，打开自带的示例工作区和中文体验指南 sample/README.md。 左侧 Goal 会自动发现四个计划，另有一份手动添加示例，可体验实时进度、AI 提示词、 嵌套任务，以及重构被 Bugfix 打断后恢复的流程。

示例默认直接运行，避免 Extension Host 在等待调试器时卡住。需要断点时，保留示例窗口， 回到源码窗口选择 Attach to Goal (sample) 并按 F5，通过 127.0.0.1:9235 附加调试。 这种方式避开部分 VS Code 内置调试器在 localhost 的 IPv4 / IPv6 连接上的问题。

E2E 默认下载稳定版 VS Code，可用 VSCODE_EXECUTABLE_PATH 指向现有安装，或用 VSCODE_VERSION 指定下载版本。测试使用临时工作区与用户目录，验证后清理。Linux 无显示环境时使用 xvfb-run -a bun run test:e2e。

Markdown 解析、状态转换和提示词模块独立于 VS Code。运行依赖通过 esbuild 打入扩展，vscode 由 Extension Host 提供，因此 VSIX 不需要包含 node_modules/。.vscodeignore 仅放行运行代码、图标、说明与许可证。

CI 执行类型检查、单元测试、打包和 Extension Host 测试。发布流程同样通过这些检查后，才会创建带 VSIX 安装包和版本说明的 GitHub Release。

发布时更新 package.json 的版本和 CHANGELOG.md，提交后推送与版本一致的标签，例如 v0.1.0。若要同时发布市场，在仓库 Actions secrets 中配置 VSCE_PAT（VS Code Marketplace）或 OVSX_PAT（Open VSX）；未配置时只发布 GitHub Release，并在工作流摘要中标明跳过的市场。

图标与许可证

图标使用指定的 JetBrains MarkdownIcons checkmarkList，以原始 SVG 生成扩展 PNG 与 Activity Bar 图标。来源与许可见 NOTICE.md。

项目代码使用 MIT License。