前言¶
在 DeepSeek Harness（DSH）裏排查線上事故，常見做法是從日誌複製 traceback、pytest 摘要、showmigrations 或 SQL 調試輸出，貼進對話再讓人或模型逐行讀。這個過程容易抄錯行號、漏掉 __cause__ 鏈後面的根因，或把「模型已讀懂」和「文本確實被完整解析」混爲一談。
dsh-py-doctor 是維護者 ax2 發佈的 DSH 插件（社區目錄分類：工作流），面向同一類輸入：不跑 Python、不連庫、不執行 migrate，只把六類已知語法的報告文本解析成結構化 JSON，並附帶「讀懂了多少」的覆蓋率回執。下面介紹它的定位、六個工具、安裝方式與典型用法。
這是什麼¶
一句話：dsh-py-doctor 是離線、確定性的 Python / Django 生產報錯診斷工具集，爲 DeepSeek Harness 提供 6 個工具；純本地、零網絡、有界、可復現。
插件不執行 Python、不起子進程、不讀文件、不連網絡、不看時鐘、不用隨機數——每個工具都是輸入的純函數；輸入超預算就拒絕（不截斷），看不懂的行如實列進 unknown_lines（不靜默丟棄）。npm 包版本爲 0.1.5，許可證 MIT，當前 GitHub 星標爲 0。
- 目錄頁：https://www.skillhub.cn/plugins/ax2/dsh-py-doctor
- 源碼與說明：https://github.com/ax2/dsh-py-doctor
DSH 生態理念是「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
核心功能：六個 python 組工具¶
所有工具參數均爲 text（報錯原文，必填，內聯粘貼）。返回值統一爲回執信封：result 爲解析結果，meta 含 bytesIn、bytesOut、truncated、notes 等。
| 工具 | 讀什麼 | 不讀什麼 |
|---|---|---|
python_traceback |
CPython traceback：異常類型/模塊/消息、幀鏈、__cause__/__context__ 鏈、SyntaxError 的 caret、[Previous line repeated N more times]、project 與 site-packages 幀、常見異常的根因提示 |
非 traceback 散文；截斷的 Traceback (most recent call last 會判爲未識別 |
pytest_summary |
pytest 計數、耗時、FAILURES/ERRORS、E 斷言摘要、short test summary info、--durations |
本次運行未打印的段落在 warnings 裏點名，不猜測 |
django_migrations |
showmigrations 縮進列表、--plan 平鋪、庫橫幅、(no migrations)、每 app 已應用/未應用與總數、plan_needed |
--plan 無勾選框，不會把任何一條說成「已應用」 |
django_sql_n_plus_one |
按歸一化語句分組重複查詢，給出 N+1 候選、次數、動詞、表名、原始樣例 | 歸一化有損，樣例永遠保留；不發查詢 |
django_checks |
manage.py check / check --deploy：級別、診斷 id、消息、HINT、對象、各級計數、部署清單項、彙總 |
彙總數字與 finding 數不一致時兩邊都報，不替任何一邊圓場 |
celery_report |
inspect active/reserved/ping/stats：worker、任務條目與直方圖、reserved 段、worker_count 等 |
純 inspect active 無法與 reserved 區分，只有顯式 'reserved': 段才計入 reserved_tasks |
README 標明測試 75 個通過；各解析器有獨立 parser_version（如 tb-1、pytest-1、migrations-1、sql-1、checks-1、celery-1）。
誠實回執：coverage 與預算¶
每份結果都帶 coverage：total_lines、parsed_lines、unknown_count、unknown_lines（最多 8 條樣例）、unknown_truncated、confidence（讀懂比例，非「模型有多確定」）、parser_version。未識別行會拉低 confidence，不會被吸收進 frame 等結構。
插件在 profile 下 py-doctor id 可配置（全部可選）：例如 maxInputBytes 默認 262144，超過拋 INPUT_TOO_LARGE；maxFrames 默認 200 等。具體字段以 README 與倉庫爲準。
安裝與啓用¶
npm（推薦）：
dsh plugin --profile web add dsh-py-doctor
預構建 tarball（與 npm 同產物）：
dsh plugin --profile web add https://github.com/ax2/dsh-py-doctor/releases/latest/download/dsh-py-doctor.tgz
固定版本可將 URL 中的 latest/download/dsh-py-doctor.tgz 換成 download/v<version>/dsh-py-doctor-<version>.tgz。
裝完後重啓應用（bundle 列表在啓動時讀取）。包內 cordis.patch.yml 會向 profile 的 bundle 列表插入 id: py-doctor，加載 profile 即註冊上述 6 個工具。運行環境要求 Node >=20.10；peer 依賴含 @deepseek-ai/cordis、@deepseek-ai/dsh-tools。
若要與 dsh-deterministic-tools、dsh-jvm-doctor、dsh-win-native 一次裝齊，可使用 dsh-toolbox-bundle；不要與單獨安裝混用。
典型用法¶
traceback：模型調用 python_traceback¶
把 traceback 原文作爲 text 傳入。README 實測輸出示例（節選）：
exception_type: KeyError message: 'user_id'
deepest_frame: svc.py:42 in handle
cause_hint: The mapping has no key 'user_id'; production data is usually
missing the key that test data always has.
coverage: 3/3 lines, 0 unknown, confidence 1 (parser tb-1)
結構化 JSON 中會包含 exception_type、frames、deepest_project_frame、coverage 等；項目幀與 site-packages 幀會區分 origin。
Django N+1：調用 django_sql_n_plus_one¶
輸入爲多行 Django SQL 日誌，例如：
(0.004) SELECT "shop_product"."id" FROM "shop_product" WHERE "shop_product"."order_id" = 11 LIMIT 21; args=(11,)
(0.001) SELECT "shop_product"."id" FROM "shop_product" WHERE "shop_product"."order_id" = 12 LIMIT 21; args=(12,)
(0.001) SELECT "shop_product"."id" FROM "shop_product" WHERE "shop_product"."order_id" = 13 LIMIT 21; args=(13,)
輸出中 candidates[0] 會標記 n_plus_one: true，給出歸一化語句、count、表名與一條 example 原始樣例行。
在 Harness 中的工作方式¶
智能體在對話裏粘貼生產日誌後，由 DSH 調用對應工具；模型拿到的是帶覆蓋率的可審計 JSON，而不是依賴臨時腳本或網絡查詢的二次結論。同一段輸入永遠得到同一份輸出，便於寫進 issue、CI 或復盤文檔。
適用場景與注意¶
適合誰： 日常維護 Django/Celery 生產環境、需要在 DSH 工作流裏快速結構化 traceback、pytest 失敗摘要、未執行 migration、check --deploy 項、SQL N+1 候選或 Celery inspect 輸出的開發者與智能體編排者。
爲什麼堅持離線： 可復現、可審計（不需 settings.py 或數據庫連接串）、不因本地再跑一遍 Django 引入環境差異、無副作用（不 migrate、不發查詢、不重啓 worker）。
安裝前請知悉： 插件以當前 DSH 進程權限運行；安裝前應自行查看 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的安全與合規要求。本介紹中的命令與字段均來自公開 README 與 package.json，未在資料中出現的配置或版本請勿臆測。
結尾¶
dsh-py-doctor 把「粘日誌、人眼找行」改成「粘文本、拿結構化診斷 + 覆蓋率」：六個工具覆蓋 traceback、pytest、migrations、N+1 SQL、Django checks 與 Celery 報告，且全程離線有界。若要在 DSH 裏接入，從 dsh plugin --profile web add dsh-py-doctor 安裝並重啓即可；更多細節見 SkillHub 目錄頁 與 GitHub README。
