# DETAILED.zh-CN.md — pi-engineering-services 详细说明

> 简明入口见 [README.zh-CN.md](./README.zh-CN.md)。本文件承载详细内容。
> English version: [DETAILED.md](./DETAILED.md).

## 1. 结构

```
pi-engineering-services/
├── lsp/                      @narumitw/pi-lsp fork（src/ + LICENSE + README）
├── dap/                      @piex-dev/dap fork
│   ├── extensions/           DAP client/session/config（defaults.json：17 个 adapter 条目）
│   ├── js-debug/             vendored vscode-js-debug 运行时（dapDebugServer.js，CJS）
│   ├── debugpy/              debugpy 配置/版本钉/健康检查（不 vendor 运行时）
│   └── MAINTENANCE-NOTES.md  全部改动/坑/验证记录（中文）
├── task/                     工具链（task/discovery/runner/non-interactive-env）
├── skills/ide-three-pillars/ 使用指南 skill（中文）
├── README.md / README.zh-CN.md
├── DETAILED.md / DETAILED.zh-CN.md
└── THIRD-PARTY-NOTICES.md    上游来源与许可证
```

划分原则：**按支柱（lsp/dap/task）分目录，不按语言分**——共享的 client/session/config
系统语言无关，语言差异只是配置条目（`adapters.ts` / `defaults.json`）。只有需隔离的
**运行时资产**才建独立目录（`js-debug/`、`debugpy/`）。

## 2. 测试范围（诚实边界）

| 支柱 | 实测 | 只配置未验证 |
|---|---|---|
| LSP | pyright（Python）、tsserver（TS/JS） | rust-analyzer（诊断+声明处 hover 正常；调用点导航有缺口） |
| DAP | **debugpy**（Python）、**js-debug**（JS/TS）：launch/attach/断点/步进/evaluate/terminate 全链路 | gdb, lldb-dap, codelldb, dlv, netcoredbg, kotlin-debug-adapter, rdbg, php-debug-adapter, bash-debug-adapter, dart/flutter, elixir-ls-debugger |
| Task | npm scripts / Makefile / justfile | — |

未验证 adapter 用的是标准 VSCode 默认配置，**按实验性对待**。
LSP 抓类型/回归错误与导航，**不抓逻辑 bug**（运行时/数据流问题靠真会话直驱排查）。

## 3. 运行时说明

- **debugpy 不 vendor**（pip 装得到、33MB native、依赖解释器）。`dap/debugpy/` 只放
  配置、版本钉（`requirements.txt`：`debugpy==1.8.21`）与健康检查（`verify.mjs`）。
- **Python 必须 3.13**：debugpy 1.8.21 与 3.14 深度不兼容（[#1893](https://github.com/microsoft/debugpy/issues/1893)），
  `stopOnEntry` 不发 stopped。defaults.json 用 `${env:PI_DEBUGPY_PYTHON|python3.13}`
  定位解释器 —— 设 `PI_DEBUGPY_PYTHON` 指向你的 3.13 解释器，或确保 `python3.13` 在 PATH。
- **js-debug 是 vendored**（npm 装不到），CommonJS 运行时，靠它自己的
  `package.json` `{"type":"commonjs"}` 与包根 ESM 隔离。
- js-debug 的 `dapDebugServer.js` 路径在 defaults.json 里是相对包根，`resolveAdapter`
  按 config 目录解析，装到哪都能跑。

## 4. 使用策略

`~/.pi/agent/APPEND_SYSTEM.md`（官方 APPEND_SYSTEM 机制，启动时追加到 system prompt 尾部）：

```
# IDE tool usage policy (auto-applied)
- 改完 .ts/.js/.py → lsp_diagnostics（应 0 新增错误）
- 程序崩/报错/要单步 → debug
- 要构建/测试/lint → task list → task run
- 关键：debug action 串行；debugpy 用 Python 3.13
- 细节见 skill ide-three-pillars
```

skill `ide-three-pillars`（按需加载）管"怎么用"：各工具的坑、边界、自指调试配方。

## 5. 验证

```bash
npm run check                        # tsc --noEmit（lsp+dap+task）
PI_DEBUGPY_PYTHON=<python3.13> bun dap/debugpy/verify.mjs   # debugpy 健康检查
```

## 6. 开发

- pi 从 `~/.pi/agent/extensions/<name>/` 自动加载本地扩展（或 `pi install` 安装）；改源码 reload 后生效。
- `node_modules` 仅供本地 tsc 解析 peerDependencies（`.gitignore` 排除，不入库）。
- 改完代码 → `npm run check` + `lsp_diagnostics`（dogfood）→ reload pi 真会话回归。
- DAP 自指调试配方：`dap/MAINTENANCE-NOTES.md` §4.5。

## 7. 上游与许可证

MIT。各上游来源及许可证原文见 [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md)：
`@narumitw/pi-lsp`、`@piex-dev/dap`、`vscode-js-debug`、`vscode-workspace-tasks`、`debugpy`。