开发工具(Devkit:Mock 与诊断)¶
dashscope.devkit 提供两个可选的开发辅助能力,关闭时几乎零开销,
生产成功路径上不会导入本包。
- Dev mock ——
static/replay/record三种模式在传输层 拦截 HTTP 请求,仅覆盖 HTTP,不覆盖 WebSocket 传输。 代码中用dashscope.enable_dev_mock(...)启用, 或设置DASHSCOPE_DEV_MOCK=<mode>。各模式能力范围见下表。 - 自诊断 —— 本地双语规则表,把失败调用转化为结构化的修复建议,
通过
DashScopeError.diagnosis呈现。
| 模式 | 网络 | 能力范围 |
|---|---|---|
static |
离线 | 仅 chat / multimodal 的解析冒烟:本地合成响应,走通协议适配、SSE 解析与类型化模型。不模拟工具调用、结构化输出或任务状态机;其他资源(向量、rerank 等)会抛出 DevMockMiss |
replay |
离线 | 回放录制的真实响应;未命中抛出 DevMockMiss,不会回落到网络 |
record |
真实请求 | 透传真实服务并录制响应,可能产生费用,供后续离线回放 |
| WebSocket | — | 三种模式均不覆盖 |
根模块转发了 mock 开关:dashscope.enable_dev_mock、
dashscope.disable_dev_mock、dashscope.dev_mock_active。
共享录制文件
record 模式会把完整真实响应写盘,可能包含生成内容、
工具调用参数或账号数据。共享 fixture 前先用 set_redactor
注册脱敏器,但注意:脱敏器只处理能解析为单个 JSON 文档的
响应体,SSE 流与二进制响应原样落盘、不会被脱敏——
注册脱敏器不等于所有 fixture 都已脱敏。
Dev mock 开关¶
enable_dev_mock
¶
enable_dev_mock(
mode: str = "static", fixture_path: Optional[str] = None
) -> None
Turn on the dev mock process-wide (static / replay / record).
Source code in dashscope/devkit/__init__.py
44 45 46 47 48 49 | |
disable_dev_mock
¶
disable_dev_mock() -> None
Turn the dev mock back off.
Source code in dashscope/devkit/__init__.py
52 53 54 | |
is_active
¶
is_active() -> bool
Whether the dev mock is currently active (code or env activation).
Source code in dashscope/devkit/__init__.py
57 58 59 | |
DevMockMiss
¶
DevMockMiss(
message: str,
*,
code: Optional[str] = None,
status_code: Optional[int] = None,
request_id: Optional[str] = None,
body: Any = None,
headers: Optional[Mapping[str, str]] = None
)
Bases: DashScopeError
Replay has no recorded response, or static cannot synthesize one.
Subclasses the v2 error base, so except DashScopeError covers it.
Source code in dashscope/errors.py
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | |
set_redactor
¶
set_redactor(fn: Optional[Callable[[Any], Any]]) -> None
Register a hook that scrubs a recorded JSON body before it is saved.
Record mode persists the full response body, which can contain
generated content, tool-call arguments or account fields. The
redactor receives the parsed JSON (dict / list) and returns
the value to write. It runs only when the body parses as a single
JSON document -- SSE streams and binary bodies are stored verbatim,
so scrub those at the source or do not record them. Pass None to
clear.
Source code in dashscope/devkit/mock.py
85 86 87 88 89 90 91 92 93 94 95 96 97 | |
自诊断¶
Diagnosis
dataclass
¶
Diagnosis(
title: str,
fixes: Tuple[Tuple[str, str], ...],
command: str = "",
)
diagnose
¶
diagnose(
status_code: Optional[int] = None,
code: Optional[str] = None,
message: Optional[str] = None,
) -> Optional[Diagnosis]
Match a failure against the local rule table.
First matching rule wins; rules are ordered most-specific first.
The returned Diagnosis is in the language selected by
DASHSCOPE_DIAGNOSIS_LANG (default zh).
Source code in dashscope/devkit/diagnosis.py
453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 | |
render
¶
render(
diagnosis: Diagnosis, lang: Optional[str] = None
) -> str
Render a diagnosis as a terminal block.
Ends with an escalation hint to the built-in AI expert.
Source code in dashscope/devkit/diagnosis.py
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 | |
install_excepthook
¶
install_excepthook() -> None
Append the diagnosis block to uncaught tracebacks (stderr only).
The normal traceback still prints first; the diagnosis is advisory output appended after it. Idempotent.
Chains to whatever sys.excepthook was installed before this call
(not sys.__excepthook__), so a third-party hook already in place
-- pytest, IPython, an APM agent -- keeps running instead of being
silently dropped.
Source code in dashscope/devkit/diagnosis.py
512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 | |