统一:DSH 智能分析、Top100 与图表静默恢复

接入 DSH 专用运行时和对话界面,保留模型原始回答,支持会话分页、连续追问与显式报告。
补齐组合筛选、各维度 Top100、分组查询到排名图的转换,图表故障静默省略并基于保存数据自动恢复。
优化报告风格、图表顺序和表格换行,更新接入说明及构建输入。

验证:独立目录前后端构建通过;118 项 Java、102 项前端、102 项图表、14 项 DSH 应用和 13 项组合筛选检查通过。
仅提交相关源码、锁定依赖与测试;不包含凭据、会话、业务数据或本地产物。
This commit is contained in:
2026-11-12 11:57:41 +08:00
parent cc8832c8e5
commit f1a2fbd494
166 changed files with 26281 additions and 2248 deletions
+3
View File
@@ -0,0 +1,3 @@
/node_modules/
/bin/
/.install-*
+66
View File
@@ -0,0 +1,66 @@
# 质量分析 DSH 执行器
固定 CLI `@deepseek-ai/dsh@0.2.2-rc.1` 与官方 Python SDK commit
`fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159`。Python SDK 原文件、MIT 许可与文件 SHA256
保存在 `vendor/python-sdk/`,npm 的完整依赖图和归档完整性由 `package-lock.json` 固定。
构建独立质量分析应用并检查启动:
```sh
python3 scripts/build_dsh_application.py /path/to/dsh-application
python3 /path/to/dsh-application/scripts/setup_dsh_runtime.py --check
```
后端通过 `QUALITY_ANALYSIS_RUNTIME_SCRIPT` 选择该目录下的 `scripts/quality_analysis_runtime.py`。
`QUALITY_ANALYSIS_MODEL_CONFIG_FILE` 指向 0600 模型设置文件。`QUALITY_ANALYSIS_STATE_DIR`
指定私有运行目录,未设置时使用应用目录的 `.runtime/quality-analysis`。构建产物的
`application.json` 记录 Python 模块校验值。应用链接宿主已固定版本的 DSH 发行目录,宿主依赖需保留。
安装需要 Python 3.10+、Pydantic `>=2.12,<3`、npm 和 Node 24.9+:
```sh
python3 scripts/setup_dsh_runtime.py --node /path/to/node24
python3 scripts/setup_dsh_runtime.py --check
```
安装器把指定 Node 复制到项目 `runtime/dsh/bin/`,不会更新全局 Node。以后可直接运行安装器,
其优先复用项目 Node。`--offline` 只使用 npm 缓存;缺少归档时明确失败。
`npm ci --ignore-scripts` 安装锁定闭包,当前质量 profile 不使用 PTY、终端或插件安装脚本。
`--check` 进行版本、SDK 文件 hash、Python 依赖、操作系统隔离及真实 SDK/MCP/流桥启动检查,
不发送模型推理请求、不读取模型配置。
`scripts/setup_dsh_runtime.py` 提供:
- `inspect_runtime() -> dict`:本地静态检查,`ready/errors` 可用于规划前阻止依赖缺失。
- `check_runtime(*, launch=False) -> dict`:`launch=True` 加做无模型真实启动检查。
- `install(node_path=None, *, offline=False) -> dict`:安装并执行上述启动检查。
`scripts/dsh_agent_runtime.py` 提供 `run_dsh_agent(...)`。授权、正式查询工具及事件输出由调用方
传入;它返回原执行器的 `(ConversationAccumulator, status, reason, stop_succeeded)`。
它不发布最终 result,不替代 Java 任务确认、范围证明、图表与报告收尾。
每轮新建私有 home、workspace、SDK session。`sdk-minimal` 经过受控 patch,关闭 shell、
终端、文件工具、工作目录工具、MCP 资源、官方 provider、会话日志上传与插件清单上传。
子进程使用白名单环境,只持有绑定本轮的随机能力;真实业务令牌与模型网关密钥留在父进程。
质量 MCP 和模型请求均经过不可变本轮 relay,摘要、重试也经当前 Java 授权与同一模型网关。
有整轮 monotonic deadline、请求次数、输入/输出字节、工具调用及累计 token 预算。
无用量返回的模型调用按输入 UTF-8 字节数加输出上限保守扣除 token 预留。
自有 `stream-bridge.mjs` 通过独立有序 HTTP 通道投影真实 DSH stream frame 和 durable event,
DSH stdout 保留 JSON-RPC。失败 attempt 的草稿被撤回,最终文本与已提交消息对账。
子进程能力在 shutdown 前撤销;在途模型响应关闭,随后回收已登记且身份匹配的进程组。
应用 `quality_analysis_runtime.py --stop-all` 根据私有运行目录登记与进程指纹清理 DSH 组。
当前仅实现并验证 macOS `sandbox-exec`。OS 策略只允许读取 runtime、本轮目录与必要系统/
Python 库,只允许写入本轮 home/workspace/tmp,只允许连接本轮 loopback relay。
Linux/Windows 明确拒绝无隔离启动;其等效隔离与进程树支持尚待实现,不能以 npm 的平台声明
视作已完成安装或业务验收。
运行模块专属验证:
```sh
python3 -m unittest verification.test_dsh_agent_runtime verification.test_dsh_application -v
```
验证使用本地编写的 SSE provider fixture 驱动真实 DSH,不使用在线模型或正式业务凭据。
它验证协议、MCP、逐字流、取消、时限、错误、输出截断和 OS 隔离,不代表模型业务分析质量验收。
@@ -0,0 +1,300 @@
#!/usr/bin/env python3
"""Run a DSH quality-analysis turn over the authenticated platform worker protocol."""
from __future__ import annotations
import argparse
import copy
import json
import os
import secrets
import sys
import threading
import time
from quality_runtime_context import (
DelegatedApi, RuntimeErrorSafe, SessionWorkspace, _atomic_json, _emit,
_input_cancel_listener, _normalize_request, _read_initial_request,
_drop_repeated_followup_context, plan_agent_task, write_access_file,
)
from quality_runtime_policy import turn_scope
from quality_report_deliverable import attach
from quality_original_answer import OriginalAnswer, current as original_answer
from quality_thinking_stream import ThinkingPublisher
from quality_tools import SourceCoverageUnavailable
def _validate_request(payload):
if not isinstance(payload, dict):
raise RuntimeErrorSafe("分析请求格式无效。")
context = payload.get("context")
if not isinstance(context, dict):
raise RuntimeErrorSafe("缺少正式分析协议。")
for selected in (payload.get("runtimeEngine"), context.get("_runtimeEngine")):
if selected is not None and selected != "DSH":
raise RuntimeErrorSafe("此运行环境只支持 DeepSeek Harness。")
request = _normalize_request(payload)
protocol = request["context"].get("_protocol")
if not isinstance(protocol, dict) or protocol.get("attemptId") != request["sessionId"]:
raise RuntimeErrorSafe("分析任务授权与运行身份不匹配。")
request["runtimeEngine"] = "DSH"
return request, protocol
def _plan(request, protocol, delegated, connection, workspace, cancel, emit):
from quality_agent_task import bind_task
from quality_product_identification import (
authorized_extra_fields, identify_products, resolve_clarification_choice,
)
context = request["context"]
options = delegated.call("/api/options?releaseId=" + request["releaseId"], method="GET")
catalog = {key: options.get(key, []) for key in (
"years", "periods", "latestDataPeriod", "departments", "groups", "groupDepartments",
)}
catalog.update(identify_products(request["question"], options,
respect_exclusions=protocol.get("autonomousEnabled") is True))
try:
authorized = delegated.call("/api/analysis/tools/catalog", method="GET")
except (RuntimeErrorSafe, ValueError, OSError):
authorized = None
catalog.update(authorized_extra_fields(authorized))
if isinstance(authorized, dict):
for key, expected_type in (("sourceFields", list), ("fineDefects", dict)):
if isinstance(authorized.get(key), expected_type):
catalog[key] = authorized[key]
context["_businessCatalog"] = catalog
request['_analysisDirectory'] = {key: copy.deepcopy(options[key]) for key in
('departments','groups','groupDepartments','periods','latestDataPeriod') if key in options}
previous = protocol.get("previousTask") or None
resolution = resolve_clarification_choice(request["question"], options, previous) if previous else None
if resolution is not None:
catalog.update(resolution)
planning_context = bind_task(context, previous) if previous is not None else context
cleaned, repeated = _drop_repeated_followup_context(request["question"], context)
if repeated:
request["context"] = cleaned
request["restartConversation"] = True
planning_context = cleaned
if resolution is None:
previous = None
if isinstance(catalog.get("groupDepartments"), dict):
request["_scopeDirectory"] = {"groupDepartments": copy.deepcopy(catalog["groupDepartments"])}
emit({"type": "progress", "message": "正在理解本轮目标和连续追问…"})
retry = protocol.get("retryTask")
if isinstance(retry, dict) and retry:
return retry
audit = []
def resolve_source_values(*, release_id, period, filters, field, stages, search, limit, offset):
query = {"releaseId": release_id, "period": period, "filters": filters,
"field": field, "stages": stages, "search": search, "limit": limit, "offset": offset}
started = time.monotonic()
try:
response = delegated.call("/api/analysis/source/values", payload=query, method="POST")
except Exception as error:
audit.append({"field": field, "stages": stages, "errorType": type(error).__name__})
_atomic_json(workspace / "private/source-lookup-audit.json", audit[-100:])
raise
audit.append({"field": field, "stages": stages, "elapsedMs": round((time.monotonic() - started) * 1000),
"candidateCount": response.get("totalCount"), "exactFound": search in response.get("values", []),
"echoMatches": all(response.get(key) == query[key]
for key in ("releaseId", "period", "filters", "field", "offset", "limit"))
and response.get("selectedStages") == stages,
"candidateOnly": response.get("candidateOnly")})
_atomic_json(workspace / "private/source-lookup-audit.json", audit[-100:])
return response
return plan_agent_task(
base_url=connection[0], api_key=connection[1], model=connection[2],
question=request["question"], context=planning_context, previous=previous,
cancel_event=cancel, diagnostic_path=workspace / "private/task-plan-failure.json",
diagnostic_turn_id=request["turnId"], recovery_progress=emit,
semantic_review=request["restartConversation"] or bool(planning_context.get("_serverQuestions")),
fresh_retry=request["restartConversation"], source_value_resolver=resolve_source_values,
checks_enabled=False,
on_proposal=lambda value: _atomic_json(workspace / 'private/model-task-proposal.json', value),
)
def run_turn(payload, *, stdout=sys.stdout, stdin=sys.stdin):
"""Run the authorized DSH loop and publish its original answer directly."""
output_lock = threading.Lock()
with turn_scope(), OriginalAnswer(lambda event: _emit(stdout, output_lock, event)):
return _run_turn(payload, stdout=stdout, stdin=stdin, output_lock=output_lock)
def _run_turn(payload, *, stdout, stdin, output_lock):
from quality_model_gate import ModelGate
from quality_model_settings import model_configuration
from setup_dsh_runtime import inspect_runtime
lock = output_lock
thinking = ThinkingPublisher(lambda block: _emit(stdout, lock, {"type": "progress", "thinkingUpdate": block}))
cancelled = threading.Event()
gate = None
workspace = None
access = None
request = None
session_lock = None
store = None
def emit(event):
# Native drafts travel separately from durable process and answer data.
if event.get("type") == "result":
thinking.close()
event["engine"] = "DSH"
original_answer().settle(event)
event["answerValidation"] = {"mode": "disabled", "originalPreserved": True}
if request is not None:
attach(event, request["question"])
event = dict(event)
if isinstance(event.get("timeline"), list):
event["timeline"] = [entry for entry in event["timeline"]
if isinstance(entry, dict) and entry.get("kind") in ("tool_start", "tool_result")]
_emit(stdout, lock, event)
def cancel():
cancelled.set()
if gate is not None:
gate.revoke()
def failed(reason, message):
if cancelled.is_set():
return {"type": "result", "engine": "DSH", "status": "CANCELLED", "answer": "",
"toolCalls": [], "stopReason": "cancelled", "message": "已停止分析。"}
return {"type": "result", "engine": "DSH", "status": "FAILED", "answer": "",
"toolCalls": [], "stopReason": reason, "message": message}
try:
request, protocol = _validate_request(payload)
_input_cancel_listener(stdin, cancel)
if cancelled.is_set():
result = failed("cancelled", "已停止分析。")
emit(result)
return result
if not inspect_runtime().get("ready"):
raise RuntimeErrorSafe("DeepSeek Harness 运行环境未就绪。")
if protocol.get("autonomousEnabled") is not True:
for key in ("_serverHistory", "_serverQuestions", "lastVisibleAnswer", "_task", "primaryEvidence"):
request["context"].pop(key, None)
emit({"type": "progress", "message": "正在准备独立质量分析环境…"})
store = SessionWorkspace()
workspace, session_lock = store.acquire(request["actorId"], request["sessionId"])
access = write_access_file(workspace, request.pop("accessToken"), request["releaseId"],
expected_actor_id=request["actorId"], expected_session_id=request["sessionId"])
delegated = DelegatedApi(access, runtime_root=store.users_root, expected_actor_id=request["actorId"],
expected_session_id=request["sessionId"]).login()
def authorize():
if cancelled.is_set():
raise RuntimeErrorSafe("已停止分析。")
delegated.call("/api/analysis/model-authorization", method="GET")
authorize()
try:
base, key, model, controls = model_configuration()
except (ValueError, OSError):
raise RuntimeErrorSafe("所选模型配置不可用。") from None
gate_key = secrets.token_urlsafe(32)
gate = ModelGate(upstream_base=base, upstream_key=key, model=model, port=0, client_key=gate_key,
authorize=authorize, thinking_options=controls, on_thinking=thinking.receive,
native_turn_marker="quality-turn:" + request["turnId"])
del key
connection = (gate.base_url, gate_key, model)
emit({"type": "progress", "message": "正在查询质量数据分析平台并整理结论…"})
planning_started = time.monotonic()
task = _plan(request, protocol, delegated, connection, workspace, cancelled, emit)
request["context"].pop("_businessCatalog", None)
if not isinstance(task, dict):
raise RuntimeErrorSafe("未形成可提交的任务提案。")
authorize()
planning_ms = round((time.monotonic() - planning_started) * 1000)
confirmation_started = time.monotonic()
_atomic_json(workspace / "private/proposed-agent-task.json", {"turnId": request["turnId"], "task": task})
authority = delegated.call("/api/analysis/protocol/task", payload=task, method="POST")
if not isinstance(authority.get("task"), dict) or authority.get("attemptId") != request["sessionId"]:
raise RuntimeErrorSafe("后台未确认当前任务。")
request["_autonomousAnswer"] = protocol.get("autonomousEnabled") is True
options = dict(request=request, task=authority["task"], authority=authority, actor_root=workspace,
delegated=delegated, connection=connection, cancel_event=cancelled, emit=emit,
phase_timings={"planningAndReview": planning_ms,
"taskConfirmation": round((time.monotonic() - confirmation_started) * 1000)})
if ((authority["task"].get("executionMode") == "native_agent" and not authority["task"].get("needsClarification"))
or (authority["task"].get("kind") == "report" and not authority["task"].get("needsClarification"))):
from quality_native_run import run_native_exploration
gate.native_agent = True
prior = frozenset(path.name for path in (workspace / "evidence").glob("quality-evidence-*.json"))
return run_native_exploration(**options, prior_evidence_files=prior)
from quality_protocol_execution import execute
return execute(**options)
except SourceCoverageUnavailable as error:
if workspace is not None and request is not None:
_atomic_json(workspace / "private/source-coverage-gap.json", {
"turnId": request["turnId"], "period": error.period, "message": str(error),
})
result = failed("missing_source", str(error))
except RuntimeErrorSafe as error:
result = failed("runtime_error", str(error))
except Exception as error:
if workspace is not None and request is not None:
try:
_atomic_json(workspace / "private/last-runtime-error.json", {
"turnId": request["turnId"], "errorType": type(error).__name__,
})
except (OSError, ValueError):
pass
result = failed("runtime_error", "分析执行未完成,已保留当前问题和条件,请重试本轮。")
finally:
thinking.close()
if gate is not None:
try:
_atomic_json(workspace / "private/last-model-audit.json", {
"model": model, "requests": gate.request_audit,
"rejectedToolCalls": gate.rejected_tool_calls,
"rejectedToolNames": gate.rejected_tool_names,
"toolStreamFailures": gate.tool_stream_failures,
"toolStreamDiagnostics": gate.tool_stream_diagnostics,
"rejectedStaleRequests": gate.rejected_stale_requests,
})
except (OSError, TypeError, ValueError):
pass
finally:
gate.close()
try:
if access is not None:
access.unlink(missing_ok=True)
finally:
if session_lock is not None:
store.release(session_lock)
emit(result)
return result
def main(argv=None):
os.umask(0o077)
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--stop-all", action="store_true")
args = parser.parse_args(argv)
if args.stop_all:
from dsh_agent_runtime import stop_all_dsh
stopped = stop_all_dsh()
print(json.dumps(stopped, ensure_ascii=False))
return 0 if stopped["unconfirmed"] == 0 else 1
try:
request = _read_initial_request(sys.stdin)
except (ValueError, OSError):
print(json.dumps({"type": "result", "engine": "DSH", "status": "FAILED", "answer": "",
"toolCalls": [], "stopReason": "invalid_request", "message": "首行分析请求无效。"},
ensure_ascii=False))
return 2
run_turn(request)
return 0
if __name__ == "__main__":
raise SystemExit(main())
+47
View File
@@ -0,0 +1,47 @@
"""Bounded replacement frames for DSH's provisional assistant text."""
import hashlib
import re
import time
_PRIVATE_OUTPUT = re.compile(
r"(?i)https?://|bearer\s|api[_-]?key\b|authorization\b|clientKey\b|accessToken\b|\bsk-[a-z0-9_-]{10,}|"
r"quality-turn:|(?:scope|execution|attempt|release|actor|session)[_-]?id\b|"
r"(?:^|\n)\s*(?:\{|```)|<\s*/?\s*[a-z][a-z0-9:-]*(?:\s|/?>)|"
r"系统提示词|内部请求归属标记|本轮已确认任务、身份和上下文|本运行时使用DSH|"
r"【平台能力与职责】|【默认业务口径】|【内容组织】"
)
_UUID = re.compile(r"(?i)\b[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\b")
_NONPRINTING = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]")
def display_text(value):
if not isinstance(value, str) or _PRIVATE_OUTPUT.search(value):
return ""
return _NONPRINTING.sub("", _UUID.sub("[标识已隐藏]", value)).strip()[:4000]
class DraftPublisher:
def __init__(self, emit, *, clock=time.monotonic):
self.emit = emit
self.clock = clock
self.last_time = float("-inf")
self.current = ""
def update(self, attempt, text):
candidate = display_text(text)
if len(candidate) < 16:
self.clear()
return
now = self.clock()
if candidate == self.current or now - self.last_time < 0.25:
return
self.current = candidate
self.last_time = now
key = hashlib.sha256(attempt.encode("utf-8")).hexdigest()[:24]
self.emit({"type": "progress", "dshDraft": candidate, "dshAttemptId": key})
def clear(self):
if not self.current:
return
self.current = ""
self.emit({"type": "progress", "dshDraft": ""})
@@ -0,0 +1,210 @@
"""Publish DSH's original answer without content review or recomposition."""
from __future__ import annotations
import copy
import json
import time
import re
def initial_read_arguments(task, question):
"""Read the confirmed business frame before asking a model for prose."""
if task.get('kind') == 'report' or task.get('freshQuery') is not True or not task.get('fields'):
return None
dimensions = task.get('dimensions') or []
if task.get('aggregateSelection') and not task.get('comparisonPeriod') and not task.get('comparisonRequired'):
return {'mode': 'query', 'view': task['aggregateSelection']['dimension']}
stages = task.get('stages') or []
count = re.search(r'(?:top|前)\s*(\d+)', question, re.I)
weights = [field for field in task.get('fields', []) if field in ('totalWeight', 'scrapWeight')]
if (count and not task.get('comparisonPeriod') and not task.get('comparisonRequired')
and len(dimensions) == 1 and dimensions[0] in ('department', 'group', 'product')
and len(stages) == 1 and len(weights) == 1):
return {'mode': 'rank', 'dimension': dimensions[0], 'stage': stages[0],
'metric': weights[0], 'limit': min(100, max(1, int(count[1])))}
return {'mode': 'compare' if task.get('comparisonPeriod') else 'query'}
def _documents(directory, excluded):
"""Read this attempt's saved tool results for optional chart rendering."""
documents = []
for path in directory.glob('quality-evidence-*.json'):
if path.name in excluded or path.is_symlink():
continue
try:
document = json.loads(path.read_text())
if isinstance(document, dict) and isinstance(document.get('result'), dict):
documents.append(document)
except (OSError, ValueError):
continue
return documents
def run_native_exploration(*, request, task, authority, actor_root, delegated, connection,
cancel_event, emit, prior_evidence_files, phase_timings=None):
from dsh_agent_runtime import run_dsh_agent
from quality_agent_task import bind_task
from quality_native_exploration import NativeExplorationTools, native_model_view, _proofs
from quality_protocol_execution import _identity
from quality_runtime_context import _atomic_json, _read_json, ConversationAccumulator
from quality_runtime_policy import turn_deadline
from quality_tools import tool_definition, QualityToolError
timings = dict(phase_timings or {})
identity = _identity(authority)
context = bind_task({key: copy.deepcopy(value) for key, value in request['context'].items()
if key in ('_serverHistory', '_serverQuestions', '_protocol')}, task)
context.update(releaseId=request['releaseId'], _nativeExecutionId=identity['executionId'])
history = task.get('kind') == 'report'
history_snapshot = {}
if history:
started = time.monotonic()
history_snapshot = delegated.call('/api/analysis/protocol/history', payload={}, method='POST')
timings['historySnapshot'] = round((time.monotonic() - started) * 1000)
context['historySnapshot'] = history_snapshot
context['readPolicy'] = '本轮仅使用服务器提供的历史快照生成报告,不重新查询业务数据。'
request['context'] = context
context['analysisDirectory'] = copy.deepcopy(request.get('_analysisDirectory',{}))
_atomic_json(actor_root / 'private/last-agent-task.json', {
'sessionId': request['sessionId'], 'releaseId': request['releaseId'],
'task': task, 'protocol': identity})
tools = None if history else NativeExplorationTools(
delegated=delegated, evidence_dir=actor_root / 'evidence', task=task,
identity={**identity, 'releaseId': request['releaseId']},
state_path=actor_root / 'private/native-exploration-state.json', directory=context['analysisDirectory'])
definition = tool_definition(native_protocol=True, task=task, release_id=request['releaseId'])
allowed_modes = definition['inputSchema']['properties']['mode']['enum']
context['toolPolicy'] = {'allowedModes': allowed_modes,
'guidance': '总体query一次已含全部阶段率、逐月趋势、投入、报废和正式大类。query不传stage,period及comparisonPeriod可省略,由运行时带入;若传必须用对象,不用JSON字符串。需要产业部、业务分组时分别query(view=department/group)一次批量汇总。排名用rank且metric必填:投入重量totalWeight,报废重量scrapWeight。产业部排名用dimension=department,不要先选某个产业部。rank返回行含投入、报废、合格率等辅助字段,不为同一对象再查另一个指标排名或扩大Top数量。按原问题取得足够数据即回答,不为未要求的组织或产品扩展调查。analysisDirectory.periods是全部已发布月份,不等于本轮窗口。相邻月份比较使用query的trend逐月行,窗口合计不是焦点月份值,不另行调用compare。重复查询返回reusedEvidence时直接使用已有结果,不重复工具循环。'}
if task.get('aggregateSelection'):
context['aggregateSelection'] = copy.deepcopy(task['aggregateSelection'])
context['toolPolicy']['guidance'] += ' 本轮按aggregateSelection查询完整分组,initialObservation.rows已先按汇总重量筛选、再按正式合格率排序并取所需Top N(最多100)。保持返回名次和条件,直接撰写回答;不再用重量rank代替合格率排名,不再扩大读取或把summary当作Top N合计。原始需求见aggregateSelection.requestQuestion,当前消息可能只是补充口径。'
from dsh_model_input import adjacent_month_period
adjacent = adjacent_month_period(request['question'], context)
if adjacent:
context['focusPeriod'] = adjacent['focusPeriod']
context['toolPolicy']['guidance'] += ' 本题以focusPeriod月份为主,用query返回的focusMonth获取当月指标和正式报废大类,用trend作前后对比;不把summary窗口合计当作当月。未明确要求具体来源缺陷时,当月正式大类已能说明报废线索,无需再查窗口defects或组织/产品榜单。总体低点不代表各阶段的合格率或报废率也都最低;每个指标独立按trendSummary判断,不推断两阶段一定同向。'
from quality_report_deliverable import requested
context['responsePolicy'] = ('直接回答用户本轮问题,保留必要的口径说明;普通问答不套报告标题、导读、章节或重复结论,不主动生成报告文件。'
if not requested(request['question'], task) else
'报告按问题自主组织:排名重在名次与集中度,诊断重在焦点月份与相邻月差异,结构专题重在类别占比与缺陷。导读控制在三句以内,正文不重复整段导读;一份明细表不在多个章节重复。只呈现题目需要的内容,不为凑章节扩大查询。')
def authorize():
if cancel_event.is_set():
raise RuntimeError('cancelled')
delegated.call('/api/analysis/model-authorization', method='GET')
def query(arguments):
if history:
raise QualityToolError('本轮仅整理已有历史快照,不允许重新查询业务数据。')
if not isinstance(arguments, dict) or arguments.get('mode') not in allowed_modes:
raise QualityToolError('本轮可用mode为 '+', '.join(allowed_modes)+';请选择可用模式。排名用rank并传metric=totalWeight或scrapWeight。')
return native_model_view(tools.quality_data(arguments), compact=True, task=task)
started = time.monotonic()
initial = None
arguments = None if history else initial_read_arguments(task, request['question'])
if arguments:
initial = ConversationAccumulator()
call_id = 'initial-' + request['turnId']
initial.feed({'type': 'tool-input-available', 'toolName': 'mcp_call', 'toolCallId': call_id,
'input': {'tool': 'quality_data', 'arguments': arguments}})
emit({'type': 'progress', 'message': '正在读取本题正式数据…',
'toolCalls': initial.tool_calls, 'toolCount': len(initial.tool_calls), 'timeline': initial.timeline})
try:
observation = query(arguments)
except Exception as error:
observation = {'error': {'code': getattr(error, 'code', 'unavailable'),
'message': str(error) if isinstance(error, QualityToolError) else '本题正式数据读取未完成。'}}
initial.feed({'type': 'tool-output-available', 'toolName': 'mcp_call', 'toolCallId': call_id,
'output': observation})
context['initialObservation'] = observation
context['initialObservationCall'] = arguments
emit({'type': 'progress', 'message': '正在根据查询结果生成回答…',
'toolCalls': initial.tool_calls, 'toolCount': len(initial.tool_calls), 'timeline': initial.timeline})
timings['initialRead'] = round((time.monotonic() - started) * 1000)
if initial.tool_calls[0].get('status') == 'completed':
timings['firstUsefulMs'] = sum(timings.get(k, 0) for k in
('planningAndReview', 'taskConfirmation', 'historySnapshot', 'initialRead'))
def progress(event):
if ('firstUsefulMs' not in timings and any(
call.get('status') == 'completed' and (call.get('input') or {}).get('mode') not in (None, 'catalog')
for call in event.get('toolCalls', []))):
timings['firstUsefulMs'] = (sum(timings.get(k, 0) for k in
('planningAndReview', 'taskConfirmation', 'historySnapshot'))
+ round((time.monotonic() - started) * 1000))
emit(event)
emit({'type': 'progress', 'message': '正在生成回答…', 'executionMode': 'native_agent'})
accumulator, status, reason, stopped = run_dsh_agent(
actor_root=actor_root, connection=connection, question=request['question'],
context=context, task=task, identity=identity, turn_id=request['turnId'],
cancel_event=cancel_event, emit=progress, tool_handler=query, authorize=authorize,
tool_definition=definition, deadline=turn_deadline(), initial_accumulator=initial)
timings['investigation'] = round((time.monotonic() - started) * 1000)
answer = accumulator.answer if isinstance(accumulator.answer, str) else ''
if cancel_event.is_set():
status, reason = 'CANCELLED', 'user_cancel'
elif status not in ('COMPLETED', 'PARTIAL', 'FAILED', 'CANCELLED'):
status, reason = 'FAILED', reason or 'runtime_error'
business_calls = [call for call in accumulator.tool_calls
if (call.get('input') or {}).get('mode') not in (None, 'catalog')]
if status == 'COMPLETED' and business_calls and not any(call.get('status') == 'completed' for call in business_calls):
status, reason = 'FAILED', 'tool_queries_failed'
# Charts are optional presentation. A chart/provenance failure cannot
# suppress the model body or change the actual agent execution status.
documents, receipts = [], []
visuals = {'visualSchemaVersion': 1, 'visualState': 'not_requested', 'visuals': []}
if history:
visuals.update({key: copy.deepcopy(history_snapshot[key]) for key in
('visualSchemaVersion', 'visualState', 'visuals') if key in history_snapshot})
elif status != 'CANCELLED':
started = time.monotonic()
try:
from analysis_visual_evidence import protocol_visual_result
documents = _documents(actor_root / 'evidence', prior_evidence_files)
receipts = [proof for document in documents for proof in _proofs(document['result'])]
snapshot = delegated.call('/api/analysis/protocol/queries', payload={}, method='POST')
visuals = protocol_visual_result(documents, snapshot.get('scopes', []),
request['question'], request['turnId'], release_id=request['releaseId'], base_context=context)
if visuals.get('missingEvidence') or visuals.get('visualState') in ('failed', 'unavailable'):
_atomic_json(actor_root / 'private/chart-render-diagnostics.json', {
'state': visuals.get('visualState'), 'missing': visuals.get('missingEvidence', [])})
except Exception as error:
_atomic_json(actor_root / 'private/chart-render-error.json', {'errorType': type(error).__name__})
timings['visuals'] = round((time.monotonic() - started) * 1000)
state_path = actor_root / 'private/native-exploration-state.json'
try:
timings['formalQuery'] = _read_json(state_path).get('queryElapsedMs', 0) if state_path.is_file() else 0
except (OSError, ValueError):
timings['formalQuery'] = 0
timings['synthesis'] = 0
result = {
'type': 'result', 'engine': 'DSH', 'status': status, 'answer': answer,
'agentTask': task, 'protocol': identity, 'executionMode': 'native_agent',
'completionMethod': 'dsh_direct_answer',
'stopReason': 'stop' if status == 'COMPLETED' else str(reason or status).lower(),
'finishReason': (accumulator.finish_reasons[-1] if accumulator.finish_reasons else
'stop' if status == 'COMPLETED' else str(reason or status).lower()),
'nativeStopReason': reason, 'nativeStopSucceeded': stopped,
'actualModel': connection[2], 'phaseTimingsMs': timings,
'toolCalls': accumulator.tool_calls, 'toolCount': len(accumulator.tool_calls),
'timeline': accumulator.timeline, 'protocolEvidence': receipts,
'queryEvidenceRefs': [doc['evidenceRef'] for doc in documents if isinstance(doc.get('evidenceRef'), str)],
'queryEvidenceBindings': [{'evidenceRef': doc['evidenceRef'],
'queryIds': list(dict.fromkeys(p['queryId'] for p in _proofs(doc['result'])))}
for doc in documents if isinstance(doc.get('evidenceRef'), str)],
'agentContext': {**{key: copy.deepcopy(task[key]) for key in
('filters', 'period', 'comparisonPeriod') if task.get(key) is not None},
'releaseId': request['releaseId']},
'visualSchemaVersion': visuals.get('visualSchemaVersion', 1),
'visualState': visuals.get('visualState', 'not_requested'), 'visuals': visuals.get('visuals', []),
}
if history:
for key in ('historySources', 'historySections', 'historyCoverage', 'historyEvidence', 'historyVisualSources'):
if key in history_snapshot:
result[key] = copy.deepcopy(history_snapshot[key])
emit(result)
return result
@@ -0,0 +1,122 @@
"""Preserve assistant prose independently of evidence and presentation validation."""
from contextvars import ContextVar
import json
import re
import threading
import time
_CURRENT = ContextVar('quality_original_answer', default=None)
def current():
return _CURRENT.get()
def capture(content, *, phase='native_synthesis'):
store = current()
if store is not None and phase == 'native_synthesis':
store.capture_composition(content)
def capture_envelope(raw, *, phase='native_synthesis'):
"""Capture only provider assistant content, including an interrupted finish."""
try:
document = json.loads(raw)
content = document['choices'][0]['message']['content']
except (ValueError, TypeError, KeyError, IndexError):
return
capture(content, phase=phase)
def business_text(content):
"""Unwrap business text fields without rewriting the model's strings."""
if not isinstance(content, str):
return '', None
try:
document = json.loads(content)
except (ValueError, TypeError):
return content, None
if not isinstance(document, dict):
return content, None
title = document.get('reportTitle')
for field in ('blocks', 'answerBlocks'):
blocks = document.get(field)
if isinstance(blocks, list):
texts = [block['text'] for block in blocks
if isinstance(block, dict) and isinstance(block.get('text'), str)]
if texts:
return '\n\n'.join(texts), title if isinstance(title, str) else None
for field in ('answer', 'markdown', 'content', 'text'):
if isinstance(document.get(field), str):
return document[field], title if isinstance(title, str) else None
return content, title if isinstance(title, str) else None
class OriginalAnswer:
def __init__(self, emit):
self.emit = emit
self.text = ''
self.title = None
self.source = None
self.lock = threading.Lock()
self.last_time = float('-inf')
self.token = None
def __enter__(self):
self.token = _CURRENT.set(self)
return self
def __exit__(self, *_args):
_CURRENT.reset(self.token)
def capture_native(self, text):
heading = re.search(r'^#{1,6} +([^\n]+)', text, re.M) if isinstance(text, str) else None
self._capture(text, 'dsh_assistant', title=heading[1] if heading else None, force=False)
def capture_composition(self, content):
with self.lock:
# Review or retry output cannot replace the first business answer.
if self.source is not None:
return
text, title = business_text(content)
self._capture(text, 'model_business_text', title=title, force=True)
def _capture(self, text, source, *, title=None, force):
if not isinstance(text, str) or not text:
return
with self.lock:
self.text, self.source = text, source
if title is not None or source == 'dsh_assistant':
self.title = title
now = time.monotonic()
publish = force or now - self.last_time >= 0.25
if publish:
self.last_time = now
if publish:
self.emit({'type': 'progress', 'modelAnswer': text})
def settle(self, event):
"""Publish raw prose for every terminal status, with validation metadata."""
if self.source is None and event.get('completionMethod') == 'direct_conversation':
self.capture_composition(event.get('answer'))
if self.source is None and event.get('status') == 'NEEDS_CLARIFICATION':
task = event.get('agentTask') or {}
if isinstance(task.get('clarification'), str):
self.capture_composition(task['clarification'])
event['modelAnswer'] = self.text
event['answer'] = self.text
event['answerOrigin'] = self.source or 'no_model_text'
event.pop('readingSummary', None)
event.pop('reportHtml', None)
event.pop('_verifiedReportNarrative', None)
if self.title is not None:
event['reportTitle'] = self.title
elif self.source == 'dsh_assistant':
event.pop('reportTitle', None)
event['answerValidation'] = {
'status': event.get('status'),
'stopReason': event.get('stopReason'),
'answerQuality': event.get('answerQuality'),
'evidenceCompletion': event.get('evidenceCompletion'),
'originalPreserved': True,
}
@@ -0,0 +1,32 @@
"""Deliver the original model body when the user requests a report."""
import re
_REQUEST = re.compile(
r"(?:生成|输出|编写|撰写|写|制作|形成|起草|给我|提供|整理(?:为|成)|出)"
r"[^。!?;\n]{0,38}(?:报告|简报|排查纪要)|(?:分析|对比|质量|复盘|管理|诊断)(?:报告|简报)\s*[。!!??]*$"
)
_SKIP = re.compile(r"(?:不用|不必|不要|无需|不需要|别|避免|不(?=(?:再)?(?:生成|输出|编写|撰写|写|制作|形成|起草|提供|出)))\s*(?:另行|另外|单独|再)?\s*[^。!?;\n]{0,18}(?:报告|简报|排查纪要)")
def requested(question, task=None):
if not isinstance(question, str) or _SKIP.search(question):
return False
selection = (task or {}).get("aggregateSelection") or {}
return bool(_REQUEST.search(question) or _REQUEST.search(selection.get("requestQuestion", "")))
def attach(event, question):
"""Use the original assistant body for an explicitly requested deliverable."""
event.pop("_verifiedReportNarrative", None)
if event.get("type") != "result":
return
event.pop("reportMarkdown", None)
if not requested(question, event.get("agentTask")):
return
answer = event.get("modelAnswer")
if not isinstance(answer, str) or not answer:
return
event["reportMarkdown"] = answer
if not event.get("reportTitle"):
heading = re.search(r"^#{1,6} +([^\n]+)", answer, re.M)
event["reportTitle"] = heading[1] if heading else "质量分析报告"
+10430
View File
File diff suppressed because it is too large Load Diff
+11
View File
@@ -0,0 +1,11 @@
{
"name": "quality-analysis-dsh-runtime",
"private": true,
"type": "module",
"engines": {
"node": ">=24.9.0"
},
"dependencies": {
"@deepseek-ai/dsh": "0.2.2-rc.1"
}
}
+48
View File
@@ -0,0 +1,48 @@
// Project-owned projection of the pinned DSH transient stream. No stdout logging.
export const name = 'quality-turn-stream-bridge';
export const inject = ['agents', 'sessions'];
export async function apply(ctx) {
const endpoint = process.env.QUALITY_DSH_RELAY;
const capability = process.env.QUALITY_DSH_CAPABILITY;
const sessionId = process.env.QUALITY_DSH_SESSION;
if (!/^http:\/\/127\.0\.0\.1:\d+$/.test(endpoint ?? '') || !capability || !sessionId) {
throw new Error('quality stream bridge configuration unavailable');
}
let sequence = 0;
let pendingBytes = 0;
let failed = false;
let tail = Promise.resolve();
const send = async (body) => {
const response = await fetch(endpoint + '/events', {
method: 'POST',
headers: {'Content-Type': 'application/json', Authorization: 'Bearer ' + capability},
body, signal: AbortSignal.timeout(10000),
});
if (!response.ok) throw new Error('quality stream relay refused the event');
await response.arrayBuffer();
};
const enqueue = (value) => {
if (failed) return;
const body = JSON.stringify({sequence: ++sequence, sessionId, ...value});
const bytes = Buffer.byteLength(body);
pendingBytes += bytes;
if (pendingBytes > 16 * 1024 * 1024) {
failed = true;
return;
}
tail = tail.then(() => send(body)).catch(() => { failed = true; }).finally(() => { pendingBytes -= bytes; });
};
ctx.on('agent/assistant-stream', ({agent, frame}) => {
if (String(agent.session.id) === sessionId) enqueue({kind: 'stream', frame});
}, {global: true});
ctx.on('session/event', (session, event) => {
if (String(session.id) === sessionId) enqueue({kind: 'event', event});
}, {global: true});
ctx.on('agent/status', ({agent, status}) => {
if (String(agent.session.id) === sessionId) enqueue({kind: 'status', status});
}, {global: true});
ctx.effect(() => async () => { await tail; }, 'quality.stream.flush');
// Startup is ready only after the parent proves receipt over the actual channel.
await send(JSON.stringify({sequence: ++sequence, sessionId, kind: 'ready'}));
}
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 DeepSeek
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,28 @@
from .api import DeepSeekHarness, DeepSeekHarnessConfig, RunResult, Session
from .client import HarnessClient, HarnessConfig, UserQuestionHandler
from .errors import SdkProtocolError
from .models import (
ApprovalRequestParams, ApprovalRequestResult, IncomingRequest, InitializeResponse,
JsonObject, Notification, ServerInfo, UserQuestionAnswer, UserQuestionAnswerItem, UserQuestionRequest,
)
__all__ = [
"DeepSeekHarness",
"DeepSeekHarnessConfig",
"Session",
"RunResult",
"HarnessClient",
"HarnessConfig",
"UserQuestionHandler",
"UserQuestionRequest",
"UserQuestionAnswer",
"UserQuestionAnswerItem",
"SdkProtocolError",
"ApprovalRequestParams",
"ApprovalRequestResult",
"IncomingRequest",
"InitializeResponse",
"JsonObject",
"Notification",
"ServerInfo",
]
+335
View File
@@ -0,0 +1,335 @@
from __future__ import annotations
import uuid
from dataclasses import dataclass, field
from pathlib import Path
from typing import Callable, Literal
from .client import HarnessClient, HarnessConfig, UserQuestionHandler
from .errors import SdkProtocolError
from .models import CommandExecution, JsonObject, Notification
@dataclass(slots=True)
class DeepSeekHarnessConfig:
"""Configuration for launching the local DeepSeek Harness SDK runtime.
The runtime inherits the caller's environment by default, so existing
DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL settings keep working. Use ``env`` to
intentionally override or inject variables for a subprocess.
These values are startup input, not a live Session state mirror; Session
commands do not rewrite this object.
"""
provider: str = "deepseek-official"
model: str = "deepseek-v4-flash"
reasoning_effort: str | None = None
max_tokens: int | None = None
cwd: str | None = None
runtime_cwd: str | None = None
dsh_bin: str | None = None
profile: str = "sdk"
patches: tuple[str, ...] = ()
dsh_home: str | None = None
env: dict[str, str] = field(default_factory=dict)
initialize_timeout_seconds: float = 30.0
request_timeout_seconds: float | None = None
shutdown_timeout_seconds: float | None = 1.0
base_url: str | None = None
api_key: str | None = None
on_user_question: UserQuestionHandler | None = None
approval_requests: bool = False
@dataclass(slots=True)
class RunResult:
"""Completed input with result text, outcome, root events and Session-tree notifications."""
session_id: str
final_response: str
"""Final assistant text (empty when absent), native state-only result text, or a failure diagnostic."""
finish_reason: str | None
events: list[JsonObject]
notifications: list[Notification]
class _RunActivity:
"""Collect one input's root events and Session-tree notifications from its admission."""
def __init__(self, session_id: str, receipt_kind: Literal["prompt", "command"], receipt_id: str) -> None:
self.session_id = session_id
self.receipt_kind = receipt_kind
self.receipt_id = receipt_id
self.received = False
self.command_done = False
self.events: list[JsonObject] = []
self.notifications: list[Notification] = []
def record(self, notification: Notification, on_notification: Callable[[Notification], None] | None = None) -> bool:
if notification.method == "session.query.completed":
return False
if not self.received:
if self.receipt_kind == "prompt":
if not _is_inbox_receipt(notification, self.session_id, self.receipt_id):
return False
elif not _is_command_event(notification, self.session_id, self.receipt_id, "command/run"):
return False
self.received = True
event = notification.payload.get("event") if (
notification.method == "session.event" and notification.payload.get("sessionId") == self.session_id
) else None
if (self.receipt_kind == "command" and isinstance(event, dict) and event.get("type") == "command/done"
and isinstance(event.get("data"), dict) and event["data"].get("commandId") == self.receipt_id):
self.command_done = True
self.notifications.append(notification)
if on_notification is not None:
on_notification(notification)
if isinstance(event, dict):
self.events.append(event)
return True
def result(self, completed: JsonObject | None = None) -> RunResult:
if completed is not None and not self.command_done:
raise SdkProtocolError("Command completion is missing matching lifecycle events")
return RunResult(
session_id=self.session_id,
final_response=completed["finalResponse"] if completed is not None else final_response(self.events),
finish_reason=completed["finishReason"] if completed is not None else finish_reason(self.events),
events=self.events, notifications=self.notifications,
)
class DeepSeekHarness:
"""Reusable synchronous SDK for running DeepSeek Harness agent turns.
The runtime subprocess starts lazily and remains owned by this instance
across calls to :meth:`run`. Use the instance as a context manager, or call
:meth:`close` explicitly when finished, so the subprocess is always reaped.
"""
def __init__(
self,
config: DeepSeekHarnessConfig | None = None,
*,
_launch_args: tuple[str, ...] | None = None,
**kwargs: object,
) -> None:
if config is not None and kwargs:
raise TypeError("pass either DeepSeekHarnessConfig or keyword options, not both")
self.config = config or DeepSeekHarnessConfig(**kwargs)
cwd = str(Path(self.config.cwd or Path.cwd()).resolve())
runtime_cwd = str(Path(self.config.runtime_cwd).resolve()) if self.config.runtime_cwd is not None else cwd
self._cwd = cwd
env = dict(self.config.env)
if self.config.base_url is not None:
env["DEEPSEEK_BASE_URL"] = self.config.base_url
if self.config.api_key is not None:
env["DEEPSEEK_API_KEY"] = self.config.api_key
self._client = HarnessClient(
HarnessConfig(
dsh_bin=self.config.dsh_bin,
profile=self.config.profile,
patches=self.config.patches,
dsh_home=self.config.dsh_home,
cwd=runtime_cwd,
env=env,
initialize_timeout_seconds=self.config.initialize_timeout_seconds,
request_timeout_seconds=self.config.request_timeout_seconds,
shutdown_timeout_seconds=self.config.shutdown_timeout_seconds,
on_user_question=self.config.on_user_question,
),
_launch_args=_launch_args,
)
self._initialized = False
def __enter__(self) -> "DeepSeekHarness":
self.start()
return self
def __exit__(self, _exc_type, _exc, _tb) -> None:
self.close()
@property
def client(self) -> HarnessClient:
return self._client
def start(self) -> None:
if self._initialized:
return
self._client.start()
self._client.initialize(
cwd=self._cwd,
provider=self.config.provider,
model=self.config.model,
reasoning_effort=self.config.reasoning_effort,
max_tokens=self.config.max_tokens,
approval_requests=self.config.approval_requests,
)
self._initialized = True
def close(self) -> None:
self._client.close()
self._initialized = False
def start_session(self, session_id: str | None = None) -> "Session":
self.start()
return Session(self, session_id or f"session-{uuid.uuid4().hex}")
def resume_session(self, session_id: str) -> "Session":
"""Restore persisted history from the configured Harness home without sending input.
Missing, unreadable, incompatible, or occupied sessions raise instead of creating a new session.
"""
self.start()
self._client.resume_session(session_id)
return Session(self, session_id)
def run(
self,
input: str | list[JsonObject],
*,
session_id: str | None = None,
on_notification: Callable[[Notification], None] | None = None,
) -> RunResult:
"""Run input to completion on a fresh or named Session and return its RunResult."""
return self.start_session(session_id).run(input, on_notification=on_notification)
class Session:
def __init__(self, harness: DeepSeekHarness, session_id: str) -> None:
self.harness = harness
self.id = session_id
def get_working_directory(self) -> str:
"""Read the effective directory, recovering a missing directory to the Session origin."""
self.harness.start()
return self.harness.client.get_working_directory(self.id)
def set_working_directory(self, path: str) -> str:
"""Change the effective directory while existing processes retain their own directories."""
self.harness.start()
return self.harness.client.set_working_directory(self.id, path)
def run(
self,
input: str | list[JsonObject],
*,
on_notification: Callable[[Notification], None] | None = None,
) -> RunResult:
"""Run text or content blocks through native input routing.
Ordinary prompts finish at the next idle after their inbox receipt.
State-only commands finish with their native outcome. Commands that
submit model input wait for that activity; goal creation and resume wait
through automatic rounds and the last reply after the goal stops.
The first text block selects native commands. Matched commands require
one text block with only encoded images beside it; native handlers decide
which commands accept those images. Ordinary prompts retain block order
and are queued through the existing prompt operation. Notifications retain
wire order. Every result retains this Session id, its root events and
Session-tree notifications, including overlapping work. Native refusals
return finish_reason="error". Routing, transport and observer failures
raise without rolling back work.
"""
self.harness.start()
with self.harness.client.subscribe_session_notifications(self.id) as subscription:
response = self.harness.client._query(self.id, input)
if isinstance(response, CommandExecution):
activity = _RunActivity(self.id, "command", response.command_id)
while True:
notification = subscription.next()
payload = notification.payload
if notification.method == "session.query.completed" and payload.get("sessionId") == self.id:
if not isinstance(payload.get("commandId"), str) or not payload["commandId"]:
raise SdkProtocolError("Invalid session.query.completed command identity")
if payload["commandId"] != response.command_id:
continue
if (not isinstance(payload.get("finalResponse"), str)
or not isinstance(payload.get("finishReason"), str) or not payload["finishReason"]):
raise SdkProtocolError("Invalid session.query.completed result")
# Failure completion can precede handler settlement; its lifecycle precedes the RPC response.
while not activity.command_done:
try:
queued = subscription.next(timeout_seconds=0)
except TimeoutError:
break
activity.record(queued, on_notification)
return activity.result(payload)
activity.record(notification, on_notification)
activity = _RunActivity(self.id, "prompt", response)
while True:
notification = subscription.next()
if not activity.record(notification, on_notification):
continue
if (
notification.method == "session.status"
and notification.payload.get("sessionId") == self.id
and notification.payload.get("status") == "idle"
):
break
return activity.result()
def _is_inbox_receipt(notification: Notification, session_id: str, message_id: str) -> bool:
if notification.method != "session.event" or notification.payload.get("sessionId") != session_id:
return False
event = notification.payload.get("event")
if not isinstance(event, dict) or event.get("type") != "agent/inbox/spliced":
return False
data = event.get("data")
inserted = data.get("inserted") if isinstance(data, dict) else None
return isinstance(inserted, list) and any(
isinstance(message, dict) and message.get("id") == message_id for message in inserted
)
def _is_command_event(notification: Notification, session_id: str, command_id: str, event_type: str) -> bool:
if notification.method != "session.event" or notification.payload.get("sessionId") != session_id:
return False
event = notification.payload.get("event")
if not isinstance(event, dict) or event.get("type") != event_type:
return False
data = event.get("data")
return isinstance(data, dict) and data.get("commandId") == command_id
def final_response(events: list[JsonObject]) -> str:
for event in reversed(events):
if event.get("type") != "assistant/message":
continue
data = event.get("data")
if not isinstance(data, dict):
continue
message = data.get("message")
content_owner = message if isinstance(message, dict) else data
content = content_owner.get("content")
if not isinstance(content, list):
continue
parts: list[str] = []
for block in content:
if isinstance(block, dict) and block.get("type") == "text":
parts.append(str(block.get("text") or ""))
return "".join(parts)
return ""
def finish_reason(events: list[JsonObject]) -> str | None:
"""Return the last turn-ending kind.
The input must contain root-session events from one owned run interval.
Raises:
SdkProtocolError: The last ``turn/end`` has no string reason kind.
"""
for event in reversed(events):
if event.get("type") != "turn/end":
continue
data = event.get("data")
reason = data.get("reason") if isinstance(data, dict) else None
kind = reason.get("kind") if isinstance(reason, dict) else None
if not isinstance(kind, str):
raise SdkProtocolError("turn/end event requires a string data.reason.kind")
return kind
return None
+735
View File
@@ -0,0 +1,735 @@
from __future__ import annotations
import json
import os
import queue
import subprocess
import threading
import time
import uuid
from collections import deque
from dataclasses import dataclass
from pathlib import Path
from typing import Callable, TypeAlias, TypeVar
from pydantic import BaseModel, ValidationError
from .errors import JsonRpcError, SdkProtocolError, TransportClosedError
from .models import CommandExecution, IncomingRequest, InitializeResponse, JsonObject, JsonValue, Notification, UserQuestionAnswer, UserQuestionRequest
ModelT = TypeVar("ModelT", bound=BaseModel)
NotificationFilter: TypeAlias = Callable[[Notification], bool]
UserQuestionHandler: TypeAlias = Callable[[UserQuestionRequest, threading.Event], UserQuestionAnswer | JsonObject]
@dataclass(slots=True)
class HarnessConfig:
"""Configuration for launching the local DeepSeek Harness SDK runtime."""
dsh_bin: str | None = None
profile: str = "sdk"
patches: tuple[str, ...] = ()
dsh_home: str | None = None
cwd: str | None = None
env: dict[str, str] | None = None
initialize_timeout_seconds: float = 30.0
request_timeout_seconds: float | None = None
shutdown_timeout_seconds: float | None = 1.0
# Callbacks run outside the reader; observe the Event to release work on cancellation.
on_user_question: UserQuestionHandler | None = None
class HarnessClient:
"""Synchronous JSON-RPC client for the DeepSeek Harness SDK runtime over stdio."""
def __init__(
self,
config: HarnessConfig | None = None,
*,
_launch_args: tuple[str, ...] | None = None,
) -> None:
self.config = config or HarnessConfig()
self._launch_args = _launch_args
self._proc: subprocess.Popen[str] | None = None
self._lock = threading.Lock()
self._write_lock = threading.Lock()
self._responses: dict[str, queue.Queue[JsonValue | BaseException]] = {}
self._notifications: queue.Queue[Notification | BaseException] = queue.Queue()
self._notification_subscribers: dict[
str, tuple[queue.Queue[Notification | BaseException], NotificationFilter | None]
] = {}
self._session_parents: dict[str, str] = {}
self._requests: queue.Queue[IncomingRequest | BaseException] = queue.Queue()
self._stderr_lines: deque[str] = deque(maxlen=400)
self._reader_thread: threading.Thread | None = None
self._stderr_thread: threading.Thread | None = None
self._question_tasks: dict[str, tuple[threading.Event, threading.Thread]] = {}
self._closing = False
self._user_question_handler: UserQuestionHandler | None = None
def __enter__(self) -> "HarnessClient":
self.start()
return self
def __exit__(self, _exc_type, _exc, _tb) -> None:
self.close()
def start(self) -> None:
if self._proc is not None:
return
with self._lock:
self._session_parents.clear()
self._question_tasks.clear()
self._closing = False
self._user_question_handler = self.config.on_user_question
env = os.environ.copy()
if self.config.env:
env.update(self.config.env)
args = list(self._launch_args or self._default_launch_args(env))
self._proc = subprocess.Popen(
args,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
encoding="utf-8",
cwd=None if self.config.cwd is None else str(Path(self.config.cwd).resolve()),
env=env,
bufsize=1,
)
self._start_reader_thread()
self._start_stderr_thread()
def close(self) -> None:
"""Close the runtime after a bounded opportunity to flush durable state."""
with self._lock:
self._closing = True
question_tasks = list(self._question_tasks.values())
for cancelled, _thread in question_tasks:
cancelled.set()
proc = self._proc
if proc is None:
return
shutdown_completed = False
try:
self.request("shutdown", None, response_model=_EmptyResponse, timeout_seconds=self.config.shutdown_timeout_seconds)
shutdown_completed = True
except Exception as exc:
self._stderr_lines.append(f"shutdown request failed: {exc}")
if proc.stdin:
try:
proc.stdin.close()
except Exception as exc:
self._stderr_lines.append(f"stdin close failed: {exc}")
if shutdown_completed:
try:
proc.wait(timeout=self.config.shutdown_timeout_seconds)
except subprocess.TimeoutExpired:
pass
if proc.poll() is None:
try:
proc.terminate()
except ProcessLookupError:
pass
if proc.poll() is None:
try:
proc.wait(timeout=self.config.shutdown_timeout_seconds)
except subprocess.TimeoutExpired:
proc.kill()
proc.wait()
self._proc = None
self._fail_waiters(self._runtime_closed_error("DeepSeek Harness runtime closed"))
if self._reader_thread and self._reader_thread.is_alive():
self._reader_thread.join(timeout=0.5)
if self._stderr_thread and self._stderr_thread.is_alive():
self._stderr_thread.join(timeout=0.5)
deadline = time.monotonic() + 0.5
for _cancelled, thread in question_tasks:
if thread is not threading.current_thread():
thread.join(timeout=max(0, deadline - time.monotonic()))
def initialize(
self,
*,
cwd: str,
provider: str,
model: str,
reasoning_effort: str | None = None,
max_tokens: int | None = None,
approval_requests: bool = False,
) -> InitializeResponse:
"""Initialize the runtime; approval_requests enables approval/request reception.
When enabled, drain next_request() concurrently with blocking waits and
return one-operation decisions through respond(). Omission preserves the
runtime's composed approval answerers.
"""
payload: JsonObject = {
"cwd": str(Path(cwd).resolve()),
"provider": provider,
"model": model,
}
if approval_requests:
payload["approvalRequests"] = True
if reasoning_effort is not None:
payload["reasoningEffort"] = reasoning_effort
if max_tokens is not None:
payload["maxTokens"] = max_tokens
if self._user_question_handler is not None:
payload["capabilities"] = {"userQuestions": True}
try:
return self.request(
"initialize",
payload,
response_model=InitializeResponse,
timeout_seconds=self.config.initialize_timeout_seconds,
)
except TimeoutError as error:
self.close()
raise TimeoutError(f"{error}\nselected dsh profile {self.config.profile!r}") from error
except BaseException as error:
self.close()
diagnostics = self._runtime_diagnostics()
if isinstance(error, JsonRpcError) and diagnostics:
raise JsonRpcError(
error.code,
f"{error.message}\n{diagnostics}",
error.data,
) from error
raise
def session_prompt(
self,
session_id: str,
content_blocks: list[JsonObject],
*,
on_notification: Callable[[Notification], None] | None = None,
notification_subscription: "NotificationSubscription | None" = None,
) -> str:
payload: JsonObject = {"sessionId": session_id, "contentBlocks": content_blocks}
response = self.request(
"session/prompt",
payload,
response_model=_SessionPromptResponse,
on_notification=on_notification,
notification_filter=self._notification_belongs_to_session_tree(session_id),
notification_subscription=notification_subscription,
)
return response.messageId
def resume_session(self, session_id: str) -> None:
"""Restore a persisted session without sending a prompt; propagate restoration failures."""
self.request(
"session/resume",
{"sessionId": session_id},
response_model=_EmptyResponse,
)
def _query(
self, session_id: str, input: str | list[JsonObject],
) -> str | CommandExecution:
"""Return a validated prompt receipt or command result for high-level run callers."""
blocks = [{"type": "text", "text": input}] if isinstance(input, str) else input
result = self._request_raw("session/query", {
"sessionId": session_id, "contentBlocks": blocks,
})
if isinstance(result, dict):
if result.get("kind") == "prompt" and isinstance(result.get("messageId"), str) and result["messageId"]:
return result["messageId"]
if result.get("kind") == "command":
return _command_execution(result.get("execution"))
raise SdkProtocolError("session/query requires a prompt messageId or command execution result")
def get_working_directory(self, session_id: str) -> str:
"""Read the effective directory, recovering a missing directory to the Session origin."""
response = self.request(
"session/working-directory/get",
{"sessionId": session_id},
response_model=_WorkingDirectoryResponse,
)
return response.cwd
def set_working_directory(self, session_id: str, path: str) -> str:
"""Enter an absolute or Session-relative directory without changing origin or permissions."""
response = self.request(
"session/working-directory/set",
{"sessionId": session_id, "path": path},
response_model=_WorkingDirectoryResponse,
)
return response.cwd
def request(
self,
method: str,
params: JsonObject | None,
*,
response_model: type[ModelT],
timeout_seconds: float | None = None,
on_notification: Callable[[Notification], None] | None = None,
notification_filter: NotificationFilter | None = None,
notification_subscription: "NotificationSubscription | None" = None,
) -> ModelT:
result = self._request_raw(
method,
params,
timeout_seconds=timeout_seconds,
on_notification=on_notification,
notification_filter=notification_filter,
notification_subscription=notification_subscription,
)
if not isinstance(result, dict):
raise TypeError(f"{method} response must be a JSON object")
return response_model.model_validate(result)
def notify(self, method: str, params: JsonObject | None = None) -> None:
message: JsonObject = {"jsonrpc": "2.0", "method": method}
if params is not None:
message["params"] = params
self._write_message(message)
def next_notification(self) -> Notification:
item = self._notifications.get()
if isinstance(item, BaseException):
raise item
return item
def subscribe_notifications(
self,
notification_filter: NotificationFilter | None = None,
) -> "NotificationSubscription":
subscription_id = str(uuid.uuid4())
notifications: queue.Queue[Notification | BaseException] = queue.Queue()
with self._lock:
self._notification_subscribers[subscription_id] = (notifications, notification_filter)
return NotificationSubscription(self, subscription_id, notifications)
def subscribe_session_notifications(self, session_id: str) -> "NotificationSubscription":
"""Subscribe to a session and descendants discovered from subagent lifecycle edges."""
return self.subscribe_notifications(self._notification_belongs_to_session_tree(session_id))
def next_request(self) -> IncomingRequest:
item = self._requests.get()
if isinstance(item, BaseException):
raise item
return item
def respond(self, request_id: str | int, result: JsonValue) -> None:
self._write_message({"jsonrpc": "2.0", "id": request_id, "result": result})
def respond_error(
self,
request_id: str | int,
*,
code: int,
message: str,
data: JsonValue | None = None,
) -> None:
error: JsonObject = {"code": code, "message": message}
if data is not None:
error["data"] = data
self._write_message({"jsonrpc": "2.0", "id": request_id, "error": error})
def _request_raw(
self,
method: str,
params: JsonObject | None = None,
*,
timeout_seconds: float | None = None,
on_notification: Callable[[Notification], None] | None = None,
notification_filter: NotificationFilter | None = None,
notification_subscription: "NotificationSubscription | None" = None,
) -> JsonValue:
request_id = str(uuid.uuid4())
waiter: queue.Queue[JsonValue | BaseException] = queue.Queue(maxsize=1)
temp_subscription: NotificationSubscription | None = None
subscription = notification_subscription
with self._lock:
self._responses[request_id] = waiter
if on_notification is not None and subscription is None:
temp_subscription = self.subscribe_notifications(notification_filter)
subscription = temp_subscription
try:
message: JsonObject = {"jsonrpc": "2.0", "id": request_id, "method": method}
if params is not None:
message["params"] = params
self._write_message(message)
except BaseException:
with self._lock:
self._responses.pop(request_id, None)
if temp_subscription is not None:
temp_subscription.close()
raise
timeout = self.config.request_timeout_seconds if timeout_seconds is None else timeout_seconds
deadline = None if timeout is None else time.monotonic() + timeout
try:
while True:
if on_notification is not None and subscription is not None:
subscription.drain(on_notification)
wait_timeout = None
if on_notification is not None:
wait_timeout = 0.05
if deadline is not None:
remaining = deadline - time.monotonic()
if remaining <= 0:
with self._lock:
self._responses.pop(request_id, None)
diagnostics = self._runtime_diagnostics()
suffix = f"\n{diagnostics}" if diagnostics else ""
raise TimeoutError(
f"{method} timed out waiting for DeepSeek Harness runtime{suffix}"
)
wait_timeout = remaining if wait_timeout is None else min(wait_timeout, remaining)
try:
item = waiter.get(timeout=wait_timeout)
if on_notification is not None and subscription is not None:
subscription.drain(on_notification)
break
except queue.Empty:
continue
except BaseException:
with self._lock:
self._responses.pop(request_id, None)
if temp_subscription is not None:
temp_subscription.close()
raise
finally:
if temp_subscription is not None:
temp_subscription.close()
if isinstance(item, BaseException):
raise item
return item
def _write_message(self, message: JsonObject) -> None:
proc = self._proc
if proc is None or proc.stdin is None:
raise TransportClosedError("DeepSeek Harness runtime is not running")
try:
payload = json.dumps(message, separators=(",", ":")) + "\n"
with self._write_lock:
proc.stdin.write(payload)
proc.stdin.flush()
except Exception as exc:
raise self._runtime_closed_error("Failed to write to DeepSeek Harness runtime") from exc
def _start_reader_thread(self) -> None:
self._reader_thread = threading.Thread(target=self._reader_loop, name="dsh-runtime-reader", daemon=True)
self._reader_thread.start()
def _start_stderr_thread(self) -> None:
self._stderr_thread = threading.Thread(target=self._stderr_loop, name="dsh-runtime-stderr", daemon=True)
self._stderr_thread.start()
def _reader_loop(self) -> None:
proc = self._proc
if proc is None or proc.stdout is None:
return
try:
for line in proc.stdout:
if not line.strip():
continue
try:
message = json.loads(line)
except json.JSONDecodeError:
continue
self._handle_message(message)
except BaseException as exc:
self._fail_waiters(exc)
finally:
self._fail_waiters(self._runtime_closed_error("DeepSeek Harness runtime stdout closed"))
def _stderr_loop(self) -> None:
proc = self._proc
if proc is None or proc.stderr is None:
return
for line in proc.stderr:
self._stderr_lines.append(line.rstrip())
def _handle_message(self, message: object) -> None:
if not isinstance(message, dict):
return
msg_id = message.get("id")
method = message.get("method")
if isinstance(msg_id, (str, int)) and isinstance(method, str):
params = message.get("params")
request = IncomingRequest(id=msg_id, method=method, payload=params if isinstance(params, dict) else {})
if method == "user-question/ask" and self._user_question_handler is not None:
self._start_user_question(request)
else:
self._requests.put(request)
return
if isinstance(msg_id, (str, int)):
with self._lock:
waiter = self._responses.pop(str(msg_id), None)
if waiter is None:
return
if isinstance(message.get("error"), dict):
err = message["error"]
waiter.put(JsonRpcError(_int_or_none(err.get("code")), str(err.get("message", "JSON-RPC error")), err.get("data")))
else:
waiter.put(message.get("result"))
return
if isinstance(method, str):
params = message.get("params")
notification = Notification(method=method, payload=params if isinstance(params, dict) else {})
with self._lock:
if method == "user-question.cancelled":
task = self._question_tasks.get(str(notification.payload.get("requestId")))
if task is not None:
task[0].set()
self._record_session_relationship_locked(notification)
subscribers = list(self._notification_subscribers.items())
delivered = False
for subscription_id, (subscriber, predicate) in subscribers:
try:
matches = predicate is None or predicate(notification)
except BaseException as exc:
with self._lock:
current = self._notification_subscribers.get(subscription_id)
if current is not None and current[0] is subscriber:
self._notification_subscribers.pop(subscription_id, None)
subscriber.put(exc)
continue
if matches:
subscriber.put(notification)
delivered = True
if not delivered:
self._notifications.put(notification)
def _fail_waiters(self, exc: BaseException) -> None:
with self._lock:
for cancelled, _thread in self._question_tasks.values():
cancelled.set()
waiters = list(self._responses.values())
self._responses.clear()
subscribers = list(self._notification_subscribers.values())
self._notification_subscribers.clear()
for waiter in waiters:
waiter.put(exc)
for subscriber, _predicate in subscribers:
subscriber.put(exc)
self._notifications.put(exc)
self._requests.put(exc)
def _start_user_question(self, incoming: IncomingRequest) -> None:
"""Keep the reader free to receive cancellation, other responses, and shutdown."""
handler = self._user_question_handler
proc = self._proc
try:
request = UserQuestionRequest.model_validate(incoming.payload)
if any(not isinstance(item.get("id"), str) or not isinstance(item.get("question"), str) for item in request.questions):
raise ValueError("questions require id and question strings")
except ValueError:
self.respond_error(incoming.id, code=-32602, message="invalid user-question/ask parameters")
return
cancelled = threading.Event()
def answer() -> None:
try:
if cancelled.is_set() or handler is None:
return
result = handler(request, cancelled)
wire_result = result.model_dump(exclude_none=True) if isinstance(result, UserQuestionAnswer) else result
with self._lock:
if not cancelled.is_set() and self._proc is proc:
self.respond(incoming.id, wire_result)
except Exception as exc:
with self._lock:
if not cancelled.is_set() and self._proc is proc:
try:
self.respond_error(incoming.id, code=-32603, message=str(exc))
except TransportClosedError:
cancelled.set()
finally:
with self._lock:
current = self._question_tasks.get(request.request_id)
if current is not None and current[0] is cancelled:
self._question_tasks.pop(request.request_id, None)
thread = threading.Thread(target=answer, name="dsh-user-question", daemon=True)
with self._lock:
if self._closing:
return
if request.request_id in self._question_tasks:
self.respond_error(incoming.id, code=-32602, message="duplicate user-question requestId")
return
self._question_tasks[request.request_id] = (cancelled, thread)
try:
thread.start()
except BaseException:
self._question_tasks.pop(request.request_id, None)
cancelled.set()
raise
def _runtime_closed_error(self, reason: str) -> TransportClosedError:
diagnostics = self._runtime_diagnostics()
return TransportClosedError(f"{reason}\n{diagnostics}" if diagnostics else reason)
def _runtime_diagnostics(self) -> str:
"""Return available subprocess state for transport failures and timeouts."""
proc = self._proc
if (
proc is not None
and proc.poll() is not None
and self._stderr_thread is not None
and self._stderr_thread.is_alive()
and threading.current_thread() is not self._stderr_thread
):
self._stderr_thread.join(timeout=0.1)
parts: list[str] = []
if proc is not None:
exit_code = proc.poll()
if exit_code is not None:
parts.append(f"exit code: {exit_code}")
if self._stderr_lines:
parts.append("stderr tail:\n" + "\n".join(self._stderr_lines))
return "\n".join(parts)
def _default_launch_args(self, env: dict[str, str]) -> tuple[str, ...]:
if self.config.dsh_bin is None:
try:
from deepseek_harness_runtime import resolve_bundled_launch_args
except ImportError as exc:
raise FileNotFoundError(
"Unable to locate the bundled DeepSeek Harness dsh runtime. "
"Install deepseek-harness-runtime-bin."
) from exc
base = resolve_bundled_launch_args()
else:
base = (str(Path(self.config.dsh_bin).expanduser().resolve()),)
if self.config.dsh_home is not None:
if not self.config.dsh_home.strip():
raise ValueError("HarnessConfig requires a non-empty dsh_home")
env["DSH_HOME"] = str(Path(self.config.dsh_home).expanduser().resolve())
elif not env.get("DSH_HOME", "").strip():
raise ValueError(
"HarnessConfig requires an explicit dsh_home or non-empty DSH_HOME; "
"the Python SDK never uses ~/.dsh implicitly"
)
patches = tuple(
argument
for patch in self.config.patches
for argument in ("--patch", str(Path(patch).expanduser().resolve()))
)
return (*base, "--profile", self.config.profile, *patches)
def _unsubscribe_notifications(self, subscription_id: str) -> None:
with self._lock:
self._notification_subscribers.pop(subscription_id, None)
def _record_session_relationship_locked(self, notification: Notification) -> None:
if notification.method != "subagent.started":
return
parent_id = notification.payload.get("parentSessionId")
child_id = notification.payload.get("childSessionId")
if (
isinstance(parent_id, str)
and parent_id
and isinstance(child_id, str)
and child_id
and parent_id != child_id
):
self._session_parents[child_id] = parent_id
def _notification_belongs_to_session_tree(self, session_id: str) -> NotificationFilter:
def belongs(notification: Notification) -> bool:
payload = notification.payload
if notification.method in {"subagent.started", "subagent.finished"}:
parent_id = payload.get("parentSessionId")
if (
isinstance(parent_id, str)
and self._session_is_descendant_of(parent_id, session_id)
):
return True
return payload.get("childSessionId") == session_id
related_id = payload.get("sessionId")
return (
isinstance(related_id, str)
and self._session_is_descendant_of(related_id, session_id)
)
return belongs
def _session_is_descendant_of(self, session_id: str, root_session_id: str) -> bool:
current = session_id
visited: set[str] = set()
while current not in visited:
if current == root_session_id:
return True
visited.add(current)
parent = self._session_parents.get(current)
if parent is None:
return False
current = parent
return False
class NotificationSubscription:
def __init__(
self,
client: HarnessClient,
subscription_id: str,
notifications: queue.Queue[Notification | BaseException],
) -> None:
self._client = client
self._subscription_id = subscription_id
self._notifications = notifications
self._closed = False
def __enter__(self) -> "NotificationSubscription":
return self
def __exit__(self, _exc_type, _exc, _tb) -> None:
self.close()
def close(self) -> None:
if self._closed:
return
self._closed = True
self._client._unsubscribe_notifications(self._subscription_id)
def next(self, timeout_seconds: float | None = None) -> Notification:
"""Read one notification; an optional timeout stops only this local wait."""
try:
item = self._notifications.get(timeout=timeout_seconds)
except queue.Empty as exc:
raise TimeoutError("timed out waiting for an SDK notification") from exc
if isinstance(item, BaseException):
raise item
return item
def drain(self, on_notification: Callable[[Notification], None]) -> None:
while True:
try:
item = self._notifications.get_nowait()
except queue.Empty:
return
if isinstance(item, BaseException):
raise item
on_notification(item)
class _SessionPromptResponse(BaseModel):
messageId: str
class _WorkingDirectoryResponse(BaseModel):
cwd: str
class _EmptyResponse(BaseModel):
pass
def _int_or_none(value: object) -> int | None:
return value if isinstance(value, int) else None
def _command_execution(value: JsonValue) -> CommandExecution:
"""Decode native command results and report malformed data as a protocol error."""
try:
return CommandExecution.model_validate(value)
except ValidationError as error:
raise SdkProtocolError("session/query returned an invalid command result") from error
@@ -0,0 +1,23 @@
from __future__ import annotations
class HarnessError(Exception):
"""Base exception for SDK and runtime failures."""
class TransportClosedError(HarnessError):
"""Raised when the runtime subprocess exits or closes stdout."""
class SdkProtocolError(HarnessError):
"""Raised when the runtime sends data outside the SDK protocol."""
class JsonRpcError(HarnessError):
"""Raised when the runtime returns a JSON-RPC error response."""
def __init__(self, code: int | None, message: str, data: object | None = None) -> None:
super().__init__(message)
self.code = code
self.message = message
self.data = data
+107
View File
@@ -0,0 +1,107 @@
from __future__ import annotations
from dataclasses import dataclass
from typing import Annotated, Literal, TypeAlias
from pydantic import BaseModel, Field, JsonValue as PydanticJsonValue, field_validator
JsonScalar: TypeAlias = str | int | float | bool | None
JsonValue: TypeAlias = JsonScalar | dict[str, "JsonValue"] | list["JsonValue"]
JsonObject: TypeAlias = dict[str, JsonValue]
@dataclass(slots=True)
class Notification:
method: str
payload: JsonObject
@dataclass(slots=True)
class IncomingRequest:
id: str | int
method: str
payload: JsonObject
class ServerInfo(BaseModel):
name: str | None = None
version: str | None = None
class InitializeResponse(BaseModel):
serverInfo: ServerInfo | None = None
class CommandSuccessResult(BaseModel):
"""Successful handler result, optionally linked to a Session event."""
kind: Literal["success"]
text: str | None = None
source_event_seq: int | None = Field(default=None, alias="sourceEventSeq", strict=True, ge=0, le=2**53 - 1)
@field_validator("text", "source_event_seq", mode="before")
@classmethod
def _reject_null(cls, value: object) -> object:
if value is None:
raise ValueError("optional command result fields must be omitted instead of null")
return value
class CommandErrorResult(BaseModel):
"""A command handler's reported failure."""
kind: Literal["error"]
text: str
@field_validator("text")
@classmethod
def _non_blank_text(cls, value: str) -> str:
if not value.strip():
raise ValueError("command error text must not be blank")
return value
CommandResult: TypeAlias = Annotated[CommandSuccessResult | CommandErrorResult, Field(discriminator="kind")]
class CommandExecution(BaseModel):
"""Settled command result and the id pairing its command/run and command/done events."""
command_id: str = Field(alias="commandId", min_length=1)
result: CommandResult
class ApprovalRequestParams(BaseModel):
"""Server-to-client approval/request payload after explicit handshake opt-in."""
sessionId: str
toolName: str
callId: str | None = None
reason: str | None = None
class ApprovalRequestResult(BaseModel):
"""One-operation decision; allowed-once is the only grant."""
outcome: Literal["allowed-once", "rejected", "cancelled"]
class UserQuestionRequest(BaseModel):
"""Runtime question batch; questions retain their options, detail, and presentation intent."""
request_id: str = Field(alias="requestId", min_length=1)
session_id: str = Field(alias="sessionId")
questions: list[dict[str, PydanticJsonValue]] = Field(min_length=1)
class UserQuestionAnswerItem(BaseModel):
"""Answer to one original question id, using selected labels or custom text."""
id: str
selected: list[str]
custom: str | None = None
class UserQuestionAnswer(BaseModel):
"""One answer per original question; an empty batch is not an implicit approval."""
answers: list[UserQuestionAnswerItem]
+219
View File
@@ -0,0 +1,219 @@
"""Local Office operations through the runtime wheel's dsoffice CLI.
Calls are synchronous and do not create agents, sessions, or model requests.
The CLI owns conversion deadlines, engine termination, and failed-output cleanup.
Console Ctrl+C waits for CLI cleanup before raising KeyboardInterrupt; a second
interrupt forces termination and can leave partial output. On Windows, callers
must share the CLI's console for Ctrl+C delivery.
"""
from __future__ import annotations
import json
import os
from collections.abc import Sequence
from dataclasses import dataclass, fields
from pathlib import Path
from typing import Literal, TypeVar
import deepseek_harness_runtime
from deepseek_harness_runtime._resources import run_office_process
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from .errors import HarnessError, SdkProtocolError
class OfficeError(HarnessError):
"""A failed Office operation, including its CLI error code and exit status."""
def __init__(self, code: str, message: str, exit_code: int) -> None:
super().__init__(message)
self.code = code
self.exit_code = exit_code
class _OfficeModel(BaseModel):
model_config = ConfigDict(strict=True, frozen=True)
class ConversionResult(_OfficeModel):
"""Saved conversion or recalculation output and missing declared fonts."""
backend: Literal["native", "wasm"]
output_path: Path = Field(alias="outputPath")
missing_fonts: list[str] = Field(alias="missingFonts")
class ImageRectangle(_OfficeModel):
"""Source rectangle in CSS pixels at 96 DPI, before raster scaling."""
x: float
y: float
width: float
height: float
class RenderedImage(_OfficeModel):
"""One saved PNG and its source page, worksheet, or worksheet fragment."""
index: int
path: Path
width: int
height: int
rectangle: ImageRectangle
byte_length: int = Field(alias="byteLength")
page: int | None = None
sheet: str | None = None
range: str | None = None
rtl: bool | None = None
class RenderImagesResult(_OfficeModel):
"""Image manifest for one saved input; page_count includes unselected pages."""
schema_version: Literal[1] = Field(alias="schemaVersion")
backend: Literal["native", "wasm"]
raster_engine: Literal["libreoffice", "pdfium"] = Field(alias="rasterEngine")
source: Literal["saved"]
input_path: Path = Field(alias="inputPath")
source_sha256: str = Field(alias="sourceSha256")
dpi: float
page_count: int = Field(alias="pageCount")
images: list[RenderedImage]
missing_fonts: list[str] = Field(alias="missingFonts")
@dataclass(frozen=True, slots=True)
class OfficeOptions:
"""Kit limits and fonts; omitted values retain the installed kit defaults.
timeout_ms bounds the engine operation, including font work and output,
after explicit resource download. The call waits for engine exit and cleanup.
Font paths may be relative to cwd; fallback groups replace the kit defaults.
"""
timeout_ms: int | None = None
max_input_bytes: int | None = None
max_output_bytes: int | None = None
max_image_resolution: int | None = None
max_archive_entries: int | None = None
max_uncompressed_bytes: int | None = None
max_font_files: int | None = None
max_font_file_bytes: int | None = None
max_loaded_font_bytes: int | None = None
font_directories: Sequence[str | os.PathLike[str]] | None = None
initial_font_families: Sequence[str] | None = None
font_fallbacks: Sequence[Sequence[str]] | None = None
def _arguments(self) -> list[str]:
arguments: list[str] = []
for field in fields(self):
value = getattr(self, field.name)
if value is None:
continue
if field.name == "font_directories":
for path in value:
arguments.extend(("--font-directory", os.fspath(path)))
elif field.name == "initial_font_families":
for family in value:
arguments.extend(("--initial-font-family", family))
elif field.name == "font_fallbacks":
arguments.extend(("--font-fallbacks", json.dumps(value)))
else:
arguments.extend(("--" + field.name.replace("_", "-"), str(value)))
return arguments
class _CliFailure(_OfficeModel):
code: str
error: str
_Result = TypeVar("_Result", bound=_OfficeModel)
def _run(arguments: list[str], options: OfficeOptions | None, result_type: type[_Result]) -> _Result:
process = run_office_process(
[*deepseek_harness_runtime.resolve_office_launch_args(), *arguments,
*(options._arguments() if options is not None else [])],
)
stdout, stderr = process.stdout, process.stderr
if process.returncode != 0:
try:
failure = _CliFailure.model_validate_json(stderr)
except ValidationError:
raise OfficeError("failed", stderr.decode("utf-8", errors="replace").strip()
or "Office CLI exited without a diagnostic.",
process.returncode) from None
raise OfficeError(failure.code, failure.error, process.returncode)
try:
return result_type.model_validate_json(stdout)
except ValidationError as error:
raise SdkProtocolError("Office CLI returned an invalid result.") from error
def render_images(
input_path: str | os.PathLike[str],
output_dir: str | os.PathLike[str],
*,
pages: Literal["all"] | Sequence[int] | None = None,
sheet: str | None = None,
range: str | None = None,
dpi: int | None = None,
max_pages: int | None = None,
max_pixels: int | None = None,
max_dimension: int | None = None,
options: OfficeOptions | None = None,
) -> RenderImagesResult:
"""Render Office or PDF to PNG files and manifest.json in a fresh directory.
Pages are one-based document pages or slides. Worksheets use an exact
sheet name and optional A1 range instead. Paths may be relative to cwd.
The caller owns successful output; failed batches remove the new directory.
Raises OfficeError for CLI failures and SdkProtocolError for invalid JSON.
"""
arguments = ["render", "--input", os.fspath(input_path), "--output-dir", os.fspath(output_dir)]
selections = {
"pages": pages if isinstance(pages, str) or pages is None else ",".join(map(str, pages)),
"sheet": sheet, "range": range, "dpi": dpi, "max-pages": max_pages,
"max-pixels": max_pixels, "max-dimension": max_dimension,
}
for name, value in selections.items():
if value is not None:
arguments.extend(("--" + name, str(value)))
return _run(arguments, options, RenderImagesResult)
def convert(
input_path: str | os.PathLike[str],
output_path: str | os.PathLike[str],
*,
sheet: str | None = None,
options: OfficeOptions | None = None,
) -> ConversionResult:
"""Export Office to the format named by a fresh output file's extension.
Paths may be relative to cwd. CSV export requires an exact sheet name for
multi-sheet input. Existing output is rejected; failed output is removed.
Raises OfficeError for CLI failures and SdkProtocolError for invalid JSON.
"""
arguments = ["convert", "--input", os.fspath(input_path), "--output", os.fspath(output_path)]
if sheet is not None:
arguments.extend(("--sheet", sheet))
return _run(arguments, options, ConversionResult)
def recalculate(
input_path: str | os.PathLike[str],
output_path: str | os.PathLike[str],
*,
options: OfficeOptions | None = None,
) -> ConversionResult:
"""Refresh workbook formula caches into a distinct, fresh XLSX or ODS file.
Input accepts XLS, XLSX, or ODS. Paths may be relative to cwd. Formulas
survive, but recalculation does not verify business logic or Excel fidelity.
Raises OfficeError for CLI failures and SdkProtocolError for invalid JSON.
"""
return _run(["recalculate", "--input", os.fspath(input_path), "--output", os.fspath(output_path)],
options, ConversionResult)
+13
View File
@@ -0,0 +1,13 @@
{
"repository": "https://github.com/deepseek-ai/deepseek-harness",
"commit": "fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159",
"archiveSha256": "44926eb97c791d1b7a640a0146aa1c522aae7c21a8e238576820d01445cff976",
"sdkFiles": {
"__init__.py": "e03dffd1ac4a6e301064e209b1882965c8e78d90e30b19d0d7c9cd7e935c29ff",
"api.py": "9c772909775196fc4070182191738ad227a3bfdccc68d1b6f4e8b90dec08430b",
"client.py": "e0bdbf82d5932d38bb38a2eb8b2ae123487c7c520444c64c859c70e4504028da",
"errors.py": "0d380a8947c7cc64dc1811660816b89fe676fac46b3cfcf18a51ecafc6bf28da",
"models.py": "9b10f6d0b95356f8cd903ba2e897c794d305d17da2cfcc135ccea8c4384b548f",
"office.py": "300d51a882f321d4f417b0c1b9d3ab8e04455e6c8533da858d1d57e8ed30018a"
}
}