VS Code Copy Helper

为AI Agent CLI快捷添加代码位置

虽然CLI都可以通过@来选中某一文件，但若想引用某代码行或选中文本稍显麻烦

该插件用于快速向激活的终端发送当前编辑光标或选中区域所在位置，例如 @src/components/Example.ts:12:8-15:4

连续按下两次复制便可触发插件行为，你可以配置为：

• 复制位置到剪贴板；
• 输入到当前激活的 Terminal；
• 同时复制到剪贴板并输入到 Terminal。

相对路径与绝对路径分别提供独立命令，可以配置不同的快捷键、投递动作和模板。

使用方式

扩展提供两个命令：

默认还会启用双击 Copy，且单次按下 Ctrl+C / Cmd+C 仍然立即执行 VS Code 原生 Copy； 在默认 500ms 内再次按下时，便执行配置的相对路径或绝对路径文件引用。 这样不会因为原生 chord 等待第二段按键而破坏普通复制。

默认模板为：

@{path}:{position}

光标位于第 12 行第 8 列时，相对路径命令输出：

@src/components/Example.ts:12:8

选中第 12 行第 8 列到第 15 行第 4 列时输出：

@src/components/Example.ts:12:8-15:4

坐标从 1 开始。选区终点沿用 VS Code API 的 end-exclusive 语义，即终点指向选中内容之后的位置。

配置快捷键

快捷键由 VS Code 原生 Keyboard Shortcuts 管理：

1. 打开命令面板；
2. 执行 Preferences: Open Keyboard Shortcuts (JSON)；
3. 为两个命令分别设置按键。

[
  {
    "key": "cmd+c",
    "command": "vscodeCopyHelper.handleCopyKey",
    "when": "editorTextFocus && config.vscodeCopyHelper.doubleCopyEnabled"
  },
  {
    "key": "cmd+ctrl+c",
    "command": "vscodeCopyHelper.useRelativeReference",
    "when": "editorTextFocus"
  },
  {
    "key": "cmd+ctrl+shift+c",
    "command": "vscodeCopyHelper.useAbsoluteReference",
    "when": "editorTextFocus"
  }
]

也可以在 Keyboard Shortcuts 图形界面中搜索 Copy Helper 后修改。

双击 Copy 可以关闭，也可以选择触发相对路径或绝对路径模式：

{
  "vscodeCopyHelper.doubleCopyEnabled": true,
  "vscodeCopyHelper.doubleCopyPathMode": "relative",
  "vscodeCopyHelper.doubleCopyInterval": 500
}

• doubleCopyEnabled：设为 false 后快捷键的 when 条件不再满足，扩展不会 接管 Cmd+C / Ctrl+C，无需手动删除快捷键。
• doubleCopyPathMode：支持 relative 和 absolute。
• doubleCopyInterval：双击最大间隔，范围为 100–2000ms。

双击行为复用所选模式的独立配置：

• relative：使用 vscodeCopyHelper.relative.action 和 vscodeCopyHelper.relative.template；
• absolute：使用 vscodeCopyHelper.absolute.action 和 vscodeCopyHelper.absolute.template。

如果双击功能已关闭，仍可使用相对路径和绝对路径各自的独立默认快捷键。

如果命令面板可以执行但快捷键没有响应，可以运行 Developer: Toggle Keyboard Shortcuts Troubleshooting，然后按下快捷键， 在日志中确认最终匹配到的 command。用户自定义快捷键会覆盖扩展提供的默认快捷键。

投递动作

相对路径和绝对路径可以独立配置：

{
  "vscodeCopyHelper.relative.action": "terminal",
  "vscodeCopyHelper.absolute.action": "clipboardAndTerminal"
}

支持的值：

模板

相对路径和绝对路径分别使用以下设置：

{
  "vscodeCopyHelper.relative.template": "@{path}:{position}",
  "vscodeCopyHelper.absolute.template": "File {absolutePath}, range {position}"
}

支持的变量：

如果文件不属于任何 workspace folder，{relativePath} 会退化为文件名。

多光标或多选区会分别渲染模板，并使用 vscodeCopyHelper.selectionSeparator 连接。默认分隔符是一个空格：

{
  "vscodeCopyHelper.selectionSeparator": " "
}

Terminal 行为

默认情况下，扩展只向激活的 Terminal 输入文字，不发送 Enter，因此不会自动执行命令。

{
  "vscodeCopyHelper.terminal.createIfMissing": false,
  "vscodeCopyHelper.terminal.focus": true,
  "vscodeCopyHelper.terminal.addNewLine": false,
  "vscodeCopyHelper.terminal.escapeNewLines": true
}

• createIfMissing：没有激活的 Terminal 时是否创建名为 Copy Helper 的 Terminal。
• focus：输入后是否显示并聚焦目标 Terminal。
• addNewLine：是否在输入后发送 Enter。开启后可能直接执行 Terminal 中的内容。
• escapeNewLines：是否把模板结果中的真实换行转成字面量 \n，避免多行选中文本触发提交或执行。

如果 action 为 clipboardAndTerminal 但当前没有 Terminal：

• 剪贴板写入仍然成功；
• createIfMissing 为 false 时显示警告；
• createIfMissing 为 true 时创建 Terminal 并输入。

完整配置示例

{
  "vscodeCopyHelper.relative.action": "terminal",
  "vscodeCopyHelper.relative.template": "@{relativePath}:{position}",
  "vscodeCopyHelper.absolute.action": "clipboardAndTerminal",
  "vscodeCopyHelper.absolute.template": "{absolutePath}:{startLine}:{startColumn}-{endLine}:{endColumn}",
  "vscodeCopyHelper.selectionSeparator": " ",
  "vscodeCopyHelper.pathSeparator": "forwardSlash",
  "vscodeCopyHelper.doubleCopyEnabled": true,
  "vscodeCopyHelper.doubleCopyPathMode": "relative",
  "vscodeCopyHelper.doubleCopyInterval": 500,
  "vscodeCopyHelper.terminal.createIfMissing": false,
  "vscodeCopyHelper.terminal.focus": true,
  "vscodeCopyHelper.terminal.addNewLine": false,
  "vscodeCopyHelper.terminal.escapeNewLines": true
}

开发

要求 Node.js 20 或更高版本。

npm install
npm run check

在 VS Code 中打开本项目并按 F5，会启动 Extension Development Host。

打包 .vsix：

npm run package

安装生成的扩展：

code --install-extension vscode-copy-helper-0.2.1.vsix

License

MIT，详见扩展包中的 LICENSE 文件。