前言¶
在 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。
