统一: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
@@ -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)