ide-three-pillars

name

ide-three-pillars

description

How to use the three IDE-pillar tool sets installed in this pi — LSP (pi-lsp: diagnostics, navigation, rename), DAP (debug: launch/attach/breakpoints/step/evaluate), Task (task: build/test/lint discovery & structured run). Use when running type checks, navigating/renaming code, debugging a running program, or driving the project toolchain (build/test/lint). Trigger words: LSP, 诊断, hover, 定义/引用/改名, debug/调试/断点, task/构建/测试/工具链.

IDE 三大件使用指南（LSP / DAP / Task）

自动生效：使用策略写在 ~/.pi/agent/APPEND_SYSTEM.md，由 pi 追加到 system prompt 尾部（官方机制）。策略管"用不用"（三条触发），本 skill 管"怎么用"（细节、坑和边界）。

本套件提供三个 IDE 级扩展（pi-engineering-services，本地化在 ~/.pi/agent/extensions/，可直接改源码）。本 skill 讲什么时候用什么、怎么用、有哪些坑。详细维护文档在各插件目录。

快速选择

想干嘛	用哪个	工具
改完代码查类型/回归错误	LSP	lsp_diagnostics
看符号定义/引用/调用实现	LSP	lsp_definition / lsp_references / lsp_implementation / lsp_hover
列文件符号 / 全工作区搜符号	LSP	lsp_symbols / lsp_workspace_symbol
符号感知改名	LSP	lsp_rename（先 preview，确认后 write:true）
查类型定义 / 高亮同符号	LSP	lsp_type_definition / lsp_document_highlight
对话级关掉某语言 LSP	LSP	lsp_toggle
调试运行中的程序（断点/步进/变量）	DAP	debug（28 action）
跑构建/测试/lint/格式化	Task	task list → task run name=...
跑任意命令且要结构化返回	Task	task run command="..."

LSP（语言服务，pi-lsp）

• 当用：改完 .ts/.js/.py 后查回归（lsp_diagnostics 应 0 新增错误）；理解/导航代码；改扩展代码后 dogfood 自查。
• 诚实边界：LSP 抓类型/回归错误和导航，不是逻辑 bug 探测器（运行时/数据流 bug 抓不到）。找逻辑 bug 靠直驱真实代码（bun harness / 真会话）。
• dogfood 工作流：扩展目录有 node_modules junction → 宿主项目 node_modules，所以扩展自己的 .ts 能被 tsserver/pyright 检查。改完扩展代码就 lsp_diagnostics（记得传对 root，如 root=~/.pi/agent/extensions/<pkg>）。
• 工具描述在提示末尾，前缀缓存友好；lsp_toggle 会话级开关。

DAP（调试，debug 工具）

• launch 流程：debug launch(adapter, program, cwd) → set_breakpoint → continue → stack_trace/scopes/variables/evaluate → terminate。
• debugpy attach：target 需 python -m debugpy --listen 127.0.0.1:<port> --wait-for-client script.py 预启动；然后 debug attach(adapter=debugpy, port) → 先设断点再 continue（断点必须在 configurationDone 前设好，否则不命中）。
• 关键坑：
  • debug 工具不排他，action 必须串行（一次一个，等返回再发下一个；并行是 ECONNRESET 崩溃导火索）。
  • Python 用 3.13：debugpy 1.8.21 与 3.14 深度不兼容（#1893），默认 python(3.14) stopOnEntry 会坏。别用默认 python 跑调试（用你的 3.13 解释器，或设 PI_DEBUGPY_PYTHON）。
  • js-debug 测常驻脚本（setInterval/长循环），快脚本断点会 unbound。
  • terminate 已修（socket error handler），不再崩 pi。
• 自指调试（调试扩展自己源码）：bun build --target=node --sourcemap=inline 打包 → node --inspect → debug attach(js-debug-adapter, port)。配方见 dap/MAINTENANCE-NOTES.md §4.5。

Task（工具链，task 工具）

• 发现：task list（package.json scripts / Makefile targets / justfile recipes）；task list source=make 过滤。
• 跑：task run name=build（同名用 source 消歧）；task run command="..." = exec 模式。
• 自指：task run name=check cwd=~/.pi/agent/extensions/pi-engineering-services/task 用 task 工具检查它自己的代码。

详细文档

• ~/.pi/agent/extensions/pi-engineering-services/lsp/ — LSP 扩展（12 工具 + 配置）
• ~/.pi/agent/extensions/pi-engineering-services/dap/MAINTENANCE-NOTES.md — DAP 全部改动/坑/验证记录（含 attach、自指调试）
• ~/.pi/agent/extensions/pi-engineering-services/task/README.md — Task 扩展说明
• ~/.pi/agent/extensions/pi-engineering-services/dap/debugpy/README.md — debugpy 配置/版本锁定/健康检查