# AgentTerminal

**Repository Path**: hellofss/agent-terminal

## Basic Information

- **Project Name**: AgentTerminal
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-01
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lane / Agent Terminal

在 VS Code 侧栏中按用途管理 Codex、Claude 等已识别 AI Code Agent CLI 终端。当前版本：**0.5.3**。

网页预览和 VS Code 插件复用相同的侧栏脚本、样式与内嵌字体，统一搜索、筛选、分类、终端操作及窄栏排版。配色采用 VS Code Light 风格：白色编辑区、浅灰侧栏、深色文字和蓝色强调色。主题色统一维护在 `vscode-extension/theme.css`。网页右侧的终端内容是演示数据，插件安装后连接 VS Code 原生终端。

![Lane 预览](screenshots/lane-unified-preview.png)

## 安装插件

下载仓库中的 [lane-0.5.3.vsix](public/lane-0.5.3.vsix)，在 VS Code 扩展视图右上角菜单选择「从 VSIX 安装…」。安装后点击活动栏的 Lane 图标。

- `Ctrl+Alt+L` / macOS `⌘⌥L`：搜索并跳转终端。
- `Ctrl+Alt+A` / macOS `⌘⌥A`：为当前终端选择类别。
- 单击分类名或终端名即可编辑，Enter 或失焦保存，Escape 取消；分类名为空时保持原名。
- 分类标题右侧的删除按钮可删除默认或自建分类，终端自动回到未分类并保留名称、固定及运行状态。「未分类」为固定接收区。
- 拖动终端名称或目录归类；点击终端标记或目录打开终端，右侧菜单可固定或关闭。
- 侧栏顶部移除「新开 Agent / 分类」按钮。新建 CLI 可使用 VS Code 命令面板中的 `Lane: 新开 Agent CLI`，归类可直接拖动或使用终端菜单。
- 顶部仅保留「正在回复 / 已完成 / 等待用户回答 / 已中断」四个状态筛选；再次点击当前筛选可恢复全部状态。完成必须有本轮回复结束证据，未知状态只在全部状态中显示。「未分类」仅出现在下方用途分类中。

Agent 身份结合 VS Code shell integration 和每个终端 shell PID 的子进程树判断，本轮回复状态独立取证，启动后约每 1 秒刷新，识别 bash 中的 Codex / Claude / Gemini。Linux 可在 shell integration 不可用或插件中途启动时补识别已有 CLI，并从进程取得目录；权限或 PID 不可用时保留未知状态。进程运行中不等于正在生成回复，不据此推测等待输入或任务完成。用途分类与回复状态分开判断，未归类的 Codex 仍会显示身份与有证据的回复状态。

远程开发时插件运行在工作区扩展宿主，监控对应机器的终端进程；不把其他终端或独立插件面板的 Codex 进程关联到当前 bash。

## 本地开发

需要 Node.js 22.18+ 或 Node.js 24，以及 npm。

```bash
npm ci
npm run dev
```

默认开发端口为 8080；需要其他端口时可使用 `LANE_DEV_PORT=8090 npm run dev`。项目默认不启用登录或业务数据库，无需配置密钥。

## 构建与打包

```bash
npm run typecheck
npm run build
```

构建前会自动生成共享字体和版本信息，并使用固定版本的 `@vscode/vsce` 重新打包插件，输出到 `public/lane-<版本>.vsix`。首次运行打包命令需要访问 npm。

仅打包插件：

```bash
npm run package:extension
```

`vscode-extension/package.json` 是插件版本号的来源，下载链接随版本自动更新。

## 验证

```bash
node scripts/check-extension-package.mjs
node --test scripts/process-monitor.test.mjs scripts/terminal-activity.test.mjs scripts/codex-events.test.mjs scripts/terminal-title.test.mjs
npx playwright install chromium
node scripts/check-extension-render.mjs
node scripts/check-extension-interactions.mjs
```

安装包检查核对归档内文件与源码是否一致，并验证宿主的归类、重命名、固定、跳转、启动和关闭逻辑。渲染检查使用安装包中的真实 Webview HTML，在浏览器中模拟 VS Code API，验证不同宽度、字体、配色和错误输出；交互检查覆盖原生鼠标拖放、筛选下的目标类别、拖动期间的状态刷新，以及重命名时新增终端。这些浏览器检查不替代桌面 VS Code 实装测试。

可通过 `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` 指定已有 Chromium。预览和生产构建的浏览器检查脚本为 `scripts/browser-smoke.mjs`。

## 目录

- `vscode-extension/`：VS Code 插件宿主及共享侧栏界面。
- `src/`：React 网页预览和演示终端状态。
- `scripts/`：打包、资源同步、验证与部署辅助脚本。
- `public/`：可下载的 VSIX 及网页静态资源。
- `server/`、`migrations/`：原模板保留的服务端和认证基础设施。
- `.grok/`：原项目开发规范、技能及预览配置。
- `screenshots/`、`artifacts/`：界面截图与检查结果。

如需启用模板中的预览认证，使用服务端环境变量 `GROK_PREVIEW_CLIENT_SECRET`；部署认证使用 `GROK_AUTH_CLIENT_ID` / `GROK_AUTH_CLIENT_SECRET`。密钥不应写入源码。

## 本轮回复状态与最近输出

顶部只有四个筛选，不再存在「空闲」：

- **正在回复**：有本轮开始、回答恢复或正在生成的明确事件；启动 Agent / 进程存在 / 普通界面输出不能作为依据。
- **已完成**：大模型明确结束本轮回复。CLI 进程还开着也保持完成；进程退出码 0、输出流结束、长时间没输出都不能单独判为完成。
- **等待用户回答**：模型发出提问请求，或最终回复明确向用户追问。空的 CLI 输入提示符、按 Enter 继续、工具授权确认都不是此状态。
- **已中断**：Ctrl+C / 明确中断提示，或 API / 网络不可达、拒绝连接、超时、流断开等明确错误。用户手动中断只在新一轮开始后解除，不能被旧的「进程仍在运行」信息覆盖；网络故障在本轮确实恢复后解除。

信号不足显示「回复状态待确认」，不为了凑四种状态而猜测。输出暂停仅是附加提示，不是新状态，也不表示回复完成。新命令的终端输出通过稳定 Shell Integration API 采集；已经打开的 Codex 会话也可通过后台只读接口或所属会话日志取得当前轮次和最近三行可见输出。缓冲只留在内存，不保留推理内容。

`Conversation interrupted - use /feedback if something went wrong` 是明确手动中断提示，即便同一次输出后面跟着 `›` 提示符，也会保留在已中断中。

默认情况下，插件会在已识别的 Agent 终端、没有选中文本时接管 Ctrl+C，记录中断并只转发一次 ETX（不附加 Enter）。普通终端和选中复制不受影响；原生标签临时切换期间也交给终端原行为，避免发给错误目标；可用 `lane.captureAgentInterruptKey` 关闭。插件贡献了 `terminal.integrated.commandsToSkipShell` 的默认追加项；如果用户自行覆盖了该数组，需要保留 `lane.interruptActive` 才能由 VS Code 接管该键。如果显式开启 `terminal.integrated.sendKeybindingsToShell`，尊重该设置，仍靠输出或会话事件识别中断。

支持的典型诊断包括 `ECONNRESET`、`ECONNREFUSED`、`ETIMEDOUT`、`ENETUNREACH`、`EHOSTUNREACH`、`ENOTFOUND`、`EAI_AGAIN`、HTTP/API 401/403/408/429/5xx，以及明确的中英文连接失败提示。不将用户输入回显或一般讨论错误处理的文字直接当成故障。

## 只关注 AI Code Agent

看板不会关注普通 bash、node、构建 / 测试 / 数据库工具，它们的错误与中断也不会出现在看板。先打开 bash 再启动 Agent 时，Shell Integration 事件或每 1 秒的终端子进程扫描会自动加入；Agent 退出返回 bash 后，立即（有结束事件）或下一次扫描后移出，不关闭终端、不删除别名和用途配置。

执行身份以可执行程序 / Node 或 Python 包入口为准，不按终端标题、目录名称、普通输出中的工具名判断。泛用 `agent` 必须有 Cursor 路径，或位于 `~/.grok/`；`q` 必须是 `q chat`；Pi 需要 coding-agent 包路径；Goose 需要 AI 子命令或品牌路径，`goose up` 数据库迁移不会入看板。

名单维护在 [agent-registry.js](vscode-extension/agent-registry.js)，当前内置 25 种常见 CLI 身份：

| Agent | 可识别入口 |
| --- | --- |
| Grok | `grok` / `@xai-official/grok` / `~/.grok/bin/agent` |
| Codex | `codex` / `@openai/codex` |
| Claude Code | `claude` / `@anthropic-ai/claude-code` |
| Gemini CLI | `gemini` / `@google/gemini-cli` |
| OpenCode | `opencode` / `opencode-ai` |
| Aider | `aider` / Python `aider` |
| Goose | `goose session/run/acp/resume` |
| GitHub Copilot CLI | `copilot` / `@github/copilot` |
| Cursor Agent | `cursor-agent` / 带 Cursor 路径的 `agent` |
| Qwen Code | `qwen` / `@qwen-code/qwen-code` |
| Kiro CLI | `kiro-cli` |
| Amazon Q CLI | `amazon-q` / `q chat` |
| Auggie | `auggie` / `@augmentcode/auggie` |
| Amp | `amp` / `@sourcegraph/amp` |
| Cline CLI | `cline` / `@cline/cli` |
| Crush | `crush` |
| Factory Droid | `droid` |
| Codebuff | `codebuff` |
| Kimi Code CLI | `kimi` / `kimi-cli` / `kimi-code` |
| Mistral Vibe | `vibe` / `mistral-vibe` |
| Continue CLI | `cn` / `@continuedev/cli` |
| Pi Coding Agent | `@mariozechner/pi-coding-agent` 路径 |
| OpenHands | `openhands` / `openhands-cli` |
| Plandex | `plandex` |
| Kilo Code CLI | `kilo` / `kilocode` / `@kilocode/cli` |

另有 3 个本机包装命令，按所包装的 CLI 读取会话状态，卡片上显示各自的名称：

| 包装命令 | 显示名称 | 底层 CLI | 进程 exec 后的识别依据 |
| --- | --- | --- | --- |
| `claude-packy` | Claude Code · Packy | Claude Code | `CLAUDE_CONFIG_DIR` 指向 `.claude-packy` |
| `codex-flash` | Codex · Flash | Codex | `CODEX_HOME` 指向 `.codex-flash` |
| `codex-packy` | Codex · Packy | Codex | `CODEX_HOME` 指向 `.codex-packy` |

这是可审查的内置识别名单，不宣称穷举不断变化的所有产品。每项定义附有项目来源链接；其他工具或企业内部包装可通过 VS Code 设置 `lane.additionalAgents` 补充明确的入口（例如 `{ "id": "my-agent", "name": "My Agent", "executables": ["my-code-agent"], "packages": ["@company/code-agent"] }`）。不得把通用解释器名作为自定义 Agent 身份。

Agent 退出即取消看板关注；因此成功 / 异常退出状态不会作为历史卡片长期保留。Agent 仍在会话内时，明确本轮完成事件可显示绿灯，连接错误红灯，恢复输出自动回到运行。用途分类始终不因状态变化而移动。

## 原生终端标签同步与手动中断

分类与卡片名统一生成完整的「分类名 · 卡片名」，例如「评审 · 你好」，不再截断分类名。原生重命名操作全局串行，先等待目标终端真实激活，再调用 VS Code 命令并核对 `Terminal.name` 的回传；保留原来的终端选择与侧栏 / 编辑器键盘焦点。恢复已有别名时会补同步原生标签。若同步失败，卡片明确显示提示，可从菜单重试；该错误不会被误算为 Agent 已中断。

手动停止一轮对话与退出 CLI 分开处理：CLI 仍在时保留卡片并进入已中断；新一轮开始后自动恢复正在回复；退出 CLI 仍自动移出。终端输出识别会检查整次新输出中的中断提示，不再仅查看最后一行，避免尾部 `›` 提示符遮住中断。

Linux / WSL / SSH 中的 Codex 优先连接该 CLI 的 `CODEX_HOME`（或其 HOME 下 `.codex`）中已有的本机 App Server 控制 socket，只发送 `initialize`、`thread/list`、`thread/read`、`thread/turns/list` 和 `thread/items/list`。不启动或重启后台、不恢复会话、不发送提示、不回答问题，也不改 Codex 配置。轮询约每秒一次；读取当前轮次的真实 `inProgress / completed / interrupted / failed` 和 `waitingOnUserInput` 标记，等待工具授权不当作等待用户回答。新一轮在两次轮询间已结束时，也能直接从旧的中断转为完成，不必先捕获开始事件。

Codex 会话自动对应到当前进程，卡片上不再提供手动绑定。`codex resume <UUID>` 按参数指定。否则优先用该进程正在写入的 rollout，或它持有的 thread writer lock。没有这份进程证据时，使用这个进程启动之后新建或更新过的已加载主会话；CLI 新建的会话优先于只是还开着的 IDE 会话。同一条会话只关联一个终端。两个进程都打得开、又分不出归属时，状态留在「回复状态待确认」，不再弹出选择列表。只识别已确认的 Agent 终端，无 CLI 的独立面板不会自行加入看板。

最近输出来自该轮的可见 Agent 消息、工具执行状态或工具输出，随轮询更新，不需要打开终端；过滤 reasoning / analysis 项。模型提问即使已被后续工具输出移出最近窗口，也保持等待到回答或新一轮。已有后台连接断开后自动重连，临时查询失败不丢掉已经自动对上的会话。

旧版 Codex 保留只读 rollout 兼容：从该终端所属进程打开的可写日志描述符定位文件，核对 `session_meta` 线程 ID，读取生命周期及最多三行可见输出。不同版本格式不兼容或缺少可确认会话时显示「回复状态待确认」，不以进程存在或输出静默推断完成。Claude 读取该进程自己的会话记录：`busy` 是正在回复，本轮正常结束的 `idle` 是已完成，模型在提问则是等待用户回答。Grok 读取该进程打开的 `events.jsonl`：这一轮还没结束是正在回复，`completed` 是已完成，`cancelled` 是已中断，向用户提问且尚未回答是等待用户回答；工具授权仍算正在回复。OpenCode 以只读方式读取它的 `opencode.db`：先在共享日志里找到该进程启动后写下的那一段（同目录、启动后 30 秒内），得到它正在用的会话；最新一步还在生成或以 `tool-calls` 结束是正在回复，以 `stop` 结束是已完成，`question` 工具未答是等待用户回答，`MessageAbortedError` 是已中断（Ctrl+C），其他错误按连接异常算已中断。同一目录两个 OpenCode 几乎同时启动时不猜测，仍显示待确认；需要 Node 22.5+ 的 `node:sqlite`。读不到这份记录时才显示「回复状态待确认」，这不是一种回复结果，只表示还没有证据。其他没有会话记录的 CLI 暂时依靠终端输出信号。

状态只跟着这一轮走。模型正在输出是正在回复，这一轮输出结束是已完成。完成后用户又发出一条请求，回到正在回复。模型发出需要回答或选择的问题时是等待用户回答，用户提交之后进入正在回复或这一轮的下一个结果。API 错误、网络错误、Ctrl+C 和其他中断原因都是已中断；连接恢复后回到中断前的状态，新的一轮或新的输出再进入正在回复、等待或已完成。当前对话如果中断后又点击继续并开始新一轮，最新状态应该是正在回复，不能继续挂在已中断分组。

参考：[VS Code 原生重命名命令](https://github.com/microsoft/vscode/blob/main/src/vs/workbench/contrib/terminal/browser/terminalActions.ts)、[OpenAI Docs：Codex App Server 中断与完成事件](https://learn.chatgpt.com/docs/app-server)。