wip

PR_DESCRIPTION_ZH.md

@@ -0,0 +1,53 @@
+## TLDR
+
+修复在容器环境（如 code-server 远程开发）中，IDE 客户端因 `host.docker.internal` 域名不可达而无法连接的问题。
+
+将 `getIdeServerHost()` 函数改为异步，在检测到容器环境后，先通过 DNS 查询验证 `host.docker.internal` 是否可解析，不可达时自动回退到 `127.0.0.1`。
+
+## Dive Deeper
+
+### 问题背景
+
+在 Docker Desktop 中，`host.docker.internal` 会自动配置为指向宿主机的特殊域名。但在以下环境中该域名不一定存在：
+
+- **Linux Docker**：需要手动添加 `--add-host=host.docker.internal:host-gateway`
+- **code-server 远程环境**：不运行在 Docker Desktop 中，没有该域名
+- **Podman 等其他容器运行时**：不一定支持该域名
+
+原有实现只通过 `/.dockerenv` 或 `/run/.containerenv` 文件检测是否在容器中，一旦检测到就直接使用 `host.docker.internal`，但未验证该域名是否实际可达，导致在上述环境中 IDE 连接失败。
+
+### 修改内容
+
+1. **`getIdeServerHost()` 改为异步函数**：新增 `dns.lookup` 检查 `host.docker.internal` 是否可解析
+2. **结果缓存**：首次检测结果缓存到模块级变量 `cachedIdeServerHost`，避免重复 DNS 查询
+3. **debug 日志**：在容器环境下输出 DNS 检查结果，方便排查连接问题
+4. **导出测试辅助函数**：`_resetCachedIdeServerHost()` 用于测试间隔离缓存状态
+5. **完整单元测试**：新增 6 个测试用例覆盖所有场景
+
+### 修改文件
+
+| 文件                                       | 变更         |
+| ------------------------------------------ | ------------ |
+| `packages/core/src/ide/ide-client.ts`      | 核心逻辑修改 |
+| `packages/core/src/ide/ide-client.test.ts` | 新增测试用例 |
+
+## Reviewer Test Plan
+
+1. 拉取分支后运行测试：`npx vitest run packages/core/src/ide/ide-client.test.ts`
+2. 确认所有 24 个测试通过（含 6 个新增）
+3. 在 Docker 容器中（有 `host.docker.internal`）验证 IDE 连接正常
+4. 在 code-server 远程环境中（无 `host.docker.internal`）验证 IDE 自动回退到 `127.0.0.1`
+
+## Testing Matrix
+
+|          | 🍏  | 🪟  | 🐧  |
+| -------- | --- | --- | --- |
+| npm run  | ✅  | ❓  | ❓  |
+| npx      | ❓  | ❓  | ❓  |
+| Docker   | ❓  | ❓  | ❓  |
+| Podman   | ❓  | -   | -   |
+| Seatbelt | ❓  | -   | -   |
+
+## Linked issues / bugs
+
+<!-- 如有相关 issue 请在此处关联 -->