feat: add DSH AI supervision core

This commit is contained in:
阿白叔 committed 2026-10-30 09:22:40 +08:00
1 parent 12895e9868
commit bf14b20a38
13 files changed
+382

No files matched your search

@@ -0,0 +1,54 @@
# DSH AI Supervision Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Add a tool-first AI supervision layer with deterministic auto-remediation and optional human chat to the task center.
**Architecture:** Keep all mutation in the existing service. Add small Python modules for snapshots, rules, action validation, and an OpenAI-compatible client; connect them to a Qt dialog and the existing error path.
**Tech Stack:** Python 3.12, dataclasses, urllib, PySide6, pytest.
**Spec:** `docs/superpowers/specs/2026-10-30-dsh-ai-supervision-design.md`
## Global Constraints
- Model output is advisory JSON and never execution evidence.
- Only fixed allowlisted actions may reach the service.
- Missing model configuration must not disable deterministic supervision.
---
### Task 1: DSH core contracts
**Files:** Create `src/dx_productivity/dsh/__init__.py`, `snapshot.py`, `rules.py`, `actions.py`, `client.py`, `supervisor.py`; Test `tests/dsh/test_core.py`.
- [ ] Define immutable `TaskSnapshot`, `Issue`, `ActionProposal`, and `ChatReply` records.
- [ ] Implement redaction and issue classification with stable JSON-safe dictionaries.
- [ ] Implement allowlisted action validation and idempotency keys.
- [ ] Implement an OpenAI-compatible HTTP client with strict JSON parsing and a disabled configuration path.
- [ ] Implement supervisor event handling that invokes only injected handlers.
- [ ] Add tests for redaction, classification, malformed JSON, unknown actions, and retry idempotency.
### Task 2: Service adapter and automatic remediation
**Files:** Create `src/dx_productivity/dsh/service_adapter.py`; Modify `src/dx_productivity/trial_task_center/ui/main_window.py`; Test `tests/dsh/test_service_adapter.py`.
- [ ] Adapt `prepare_failed_quick_run`, `pause_task`, and read-only feedback behind fixed action names.
- [ ] Connect UI error reporting to supervisor observation without changing existing error messages.
- [ ] Auto-run only retryable failures and record outcomes.
- [ ] Add tests using a fake service and verify duplicate events do not repeat actions.
### Task 3: Human assistant panel
**Files:** Create `src/dx_productivity/trial_task_center/ui/dsh_panel.py`; Modify `main_window.py`; Test `tests/ui/test_dsh_panel.py`.
- [ ] Add a compact Qt dialog with issue summary, action cards, chat input, send/stop state, and local audit list.
- [ ] Display an explicit unconfigured-model state and keep local actions usable.
- [ ] Require confirmation for proposals marked `requires_confirmation`.
- [ ] Cover offscreen rendering and send/response state with fake client.
### Task 4: Documentation and regression verification
- [ ] Document configuration and limits in `docs/user/dsh-ai-supervision.md`.
- [ ] Run DSH tests and the existing UI/service regression suites.
- [ ] Run `python -m compileall src` and record results.
@@ -0,0 +1,24 @@
# DSH AI 监管与修复设计
## 目标
在 `codex/dsh` 分支为 DxDesigner 器件替换任务中心增加一个工具优先的 AI 监管层:异常时先用本地规则自动处理,复杂情况可人工对话;模型只能给出结构化提案,不能直接操作工程或系统。
## 架构
`dsh.supervisor` 接收任务事件并生成脱敏快照,`dsh.rules` 负责确定性分类和自动动作白名单,`dsh.client` 负责可选的 DeepSeek/OpenAI 兼容 JSON 对话。动作由 `dsh.actions` 校验后委托现有 `TrialTaskCenterService`,UI 仅展示状态、对话和需要确认的动作卡。
## 安全边界
- 自动处理仅允许明确失败重试、只读刷新和安全暂停请求。
- 规则修改、工程写入、恢复不确定状态必须人工确认。
- 模型输入仅为任务状态、进度、错误摘要和规则元数据;不发送路径内容、密钥或工程文件。
- 模型输出必须是 JSON;未知字段、未知动作、超长文本和无效参数一律拒绝。
- 未配置模型时本地监管照常工作。
## 第一版验收
- 可构造脱敏快照并识别 `failed`、`timeout`、`uncertain`、`paused`。
- 明确失败可生成幂等 `retry_failed` 动作并调用现有服务。
- UI 可打开助手面板,发送问题并显示模型回复或未配置提示。
- 所有动作和结果进入监管内存日志,且不替代现有执行证据。
+5
View File
@@ -0,0 +1,5 @@
# DSH AI 监管助手
DSH 是任务中心内的工具型监管入口。它先使用本地规则识别失败、超时和不确定状态;明确失败可生成一次性的重试动作。模型只负责解释和提出结构化建议,不能直接调用 CAD、Shell、文件系统或任意网络工具。
打开任务中心的“DSH AI 监管”后,可以查看当前任务状态并进行人工对话。未配置 DeepSeek/OpenAI 兼容接口时,对话会明确提示,但本地监管和固定动作仍然可用。工程写入、规则修改和不确定状态恢复始终需要人工确认。
+7
View File
@@ -0,0 +1,7 @@
"""Tool-first AI supervision for the task center."""
from .actions import ActionProposal, validate_action
from .snapshot import TaskSnapshot, redact_snapshot
from .supervisor import DshSupervisor
__all__ = ["ActionProposal", "DshSupervisor", "TaskSnapshot", "redact_snapshot", "validate_action"]
+34
View File
@@ -0,0 +1,34 @@
from __future__ import annotations
from dataclasses import dataclass
from hashlib import sha256
from typing import Any, Mapping
ALLOWED_ACTIONS = {"retry_failed", "pause_task", "refresh_snapshot"}
@dataclass(frozen=True)
class ActionProposal:
name: str
task_id: str
reason: str = ""
requires_confirmation: bool = False
@property
def idempotency_key(self) -> str:
return sha256(f"{self.name}:{self.task_id}".encode()).hexdigest()[:20]
def as_dict(self) -> dict[str, Any]:
return {"name": self.name, "task_id": self.task_id, "reason": self.reason,
"requires_confirmation": self.requires_confirmation, "idempotency_key": self.idempotency_key}
def validate_action(raw: Mapping[str, Any]) -> ActionProposal:
if not isinstance(raw, Mapping) or raw.get("name") not in ALLOWED_ACTIONS:
raise ValueError("unknown_dsh_action")
task_id = str(raw.get("task_id", "")).strip()
if not task_id or len(task_id) > 128:
raise ValueError("invalid_dsh_task_id")
reason = str(raw.get("reason", ""))[:500]
return ActionProposal(str(raw["name"]), task_id, reason, bool(raw.get("requires_confirmation", False)))
+47
View File
@@ -0,0 +1,47 @@
from __future__ import annotations
import json
import urllib.error
import urllib.request
from dataclasses import dataclass
from typing import Any, Mapping
class DshClientError(RuntimeError):
pass
@dataclass(frozen=True)
class DshConfig:
base_url: str = ""
model: str = ""
api_key: str = ""
timeout: float = 30.0
@property
def configured(self) -> bool:
return bool(self.base_url and self.model and self.api_key)
class OpenAICompatibleClient:
def __init__(self, config: DshConfig):
self.config = config
def chat(self, message: str, snapshot: Mapping[str, Any]) -> dict[str, Any]:
if not self.config.configured:
raise DshClientError("dsh_model_not_configured")
body = json.dumps({"model": self.config.model, "temperature": 0,
"messages": [{"role": "system", "content": "只返回 JSON:{reply,actions}; 不执行任何操作。"},
{"role": "user", "content": json.dumps({"message": message, "snapshot": snapshot}, ensure_ascii=False)}]}).encode()
request = urllib.request.Request(self.config.base_url.rstrip("/") + "/chat/completions", data=body,
headers={"Content-Type": "application/json", "Authorization": f"Bearer {self.config.api_key}"})
try:
with urllib.request.urlopen(request, timeout=self.config.timeout) as response:
payload = json.loads(response.read().decode("utf-8"))
content = payload["choices"][0]["message"]["content"]
result = json.loads(content)
except (OSError, KeyError, IndexError, TypeError, ValueError, urllib.error.URLError) as exc:
raise DshClientError("dsh_model_response_invalid") from exc
if not isinstance(result, dict) or not isinstance(result.get("reply"), str) or not isinstance(result.get("actions", []), list):
raise DshClientError("dsh_model_response_invalid")
return result
+24
View File
@@ -0,0 +1,24 @@
from __future__ import annotations
from .actions import ActionProposal
from .snapshot import TaskSnapshot
def classify(snapshot: TaskSnapshot) -> str:
status = snapshot.status.casefold()
code = snapshot.issue_code.casefold()
if status in {"uncertain", "blocked"} or "uncertain" in code:
return "manual_review"
if status in {"failed", "error"} and code not in {"invalid_rule", "permission_denied"}:
return "retryable"
if status in {"timeout", "timed_out"}:
return "retryable"
if status == "paused":
return "paused"
return "observe"
def automatic_proposal(snapshot: TaskSnapshot) -> ActionProposal | None:
if classify(snapshot) != "retryable":
return None
return ActionProposal("retry_failed", snapshot.task_id, "明确失败且未进入不确定状态")
@@ -0,0 +1,23 @@
from __future__ import annotations
from typing import Any
from .actions import ActionProposal
class DshServiceAdapter:
"""Fixed action bridge; no model supplied values reach the service."""
def __init__(self, service):
self.service = service
def execute(self, proposal: ActionProposal) -> dict[str, Any]:
if proposal.name == "retry_failed":
self.service.prepare_failed_quick_run(proposal.task_id)
return {"status": "accepted", "action": proposal.name, "task_id": proposal.task_id}
if proposal.name == "pause_task":
self.service.pause_task(proposal.task_id)
return {"status": "accepted", "action": proposal.name, "task_id": proposal.task_id}
if proposal.name == "refresh_snapshot":
return {"status": "observed", "action": proposal.name, "task_id": proposal.task_id}
raise ValueError("unknown_dsh_action")
+35
View File
@@ -0,0 +1,35 @@
from __future__ import annotations
from dataclasses import asdict, dataclass, field
from typing import Any, Mapping
@dataclass(frozen=True)
class TaskSnapshot:
task_id: str
status: str
progress: Mapping[str, Any] = field(default_factory=dict)
issue: str = ""
issue_code: str = ""
rules_count: int = 0
def safe_dict(self) -> dict[str, Any]:
return redact_snapshot(asdict(self))
def redact_snapshot(value: Mapping[str, Any]) -> dict[str, Any]:
"""Keep only bounded diagnostic fields; never leak paths, secrets, or payloads."""
progress = value.get("progress") if isinstance(value.get("progress"), Mapping) else {}
safe_progress = {
key: progress[key]
for key in ("completed", "total", "saved_items", "failed_items", "no_match_items")
if key in progress and isinstance(progress[key], (int, float, str, bool, type(None)))
}
return {
"task_id": str(value.get("task_id", ""))[:128],
"status": str(value.get("status", ""))[:32],
"issue": str(value.get("issue", ""))[:500],
"issue_code": str(value.get("issue_code", ""))[:80],
"rules_count": int(value.get("rules_count", 0) or 0),
"progress": safe_progress,
}
+26
View File
@@ -0,0 +1,26 @@
from __future__ import annotations
from collections.abc import Callable
from typing import Any
from .actions import ActionProposal
from .rules import automatic_proposal, classify
from .snapshot import TaskSnapshot
class DshSupervisor:
def __init__(self, action_handler: Callable[[ActionProposal], Any] | None = None):
self.action_handler = action_handler
self.history: list[dict[str, Any]] = []
self._completed: set[str] = set()
def observe(self, snapshot: TaskSnapshot, *, auto: bool = True) -> dict[str, Any]:
proposal = automatic_proposal(snapshot) if auto else None
result: Any = None
if proposal and proposal.idempotency_key not in self._completed and self.action_handler:
result = self.action_handler(proposal)
self._completed.add(proposal.idempotency_key)
record = {"snapshot": snapshot.safe_dict(), "classification": classify(snapshot),
"proposal": proposal.as_dict() if proposal else None, "result": result}
self.history.append(record)
return record
@@ -0,0 +1,46 @@
from __future__ import annotations
from PySide6.QtWidgets import QDialog, QFormLayout, QHBoxLayout, QLabel, QListWidget, QLineEdit, QMessageBox, QPushButton, QTextEdit, QVBoxLayout
from ...dsh.client import DshClientError, OpenAICompatibleClient
from ...dsh.snapshot import TaskSnapshot
from ...dsh.supervisor import DshSupervisor
class DshPanel(QDialog):
def __init__(self, service, *, task_id: str = "", snapshot: TaskSnapshot | None = None, client=None, parent=None):
super().__init__(parent)
self.setWindowTitle("DSH AI 监管助手")
self.resize(720, 520)
self.client = client
self.snapshot = snapshot or TaskSnapshot(task_id, "observe")
self.supervisor = DshSupervisor()
self.issue = QLabel("本地监管:等待异常事件")
self.issue.setWordWrap(True)
self.chat = QTextEdit(); self.chat.setReadOnly(True)
self.input = QLineEdit(); self.input.setPlaceholderText("描述问题,向助手提问…")
self.send = QPushButton("发送"); self.send.clicked.connect(self._send)
self.actions = QListWidget()
form = QFormLayout(); form.addRow("任务", QLabel(self.snapshot.task_id or "当前任务")); form.addRow("状态", self.issue)
controls = QHBoxLayout(); controls.addWidget(self.input, 1); controls.addWidget(self.send)
layout = QVBoxLayout(self); layout.addLayout(form); layout.addWidget(self.actions); layout.addWidget(self.chat, 1); layout.addLayout(controls)
def observe(self, snapshot: TaskSnapshot):
self.snapshot = snapshot
record = self.supervisor.observe(snapshot, auto=False)
self.issue.setText(f"本地监管:{record['classification']} · {snapshot.issue or '未发现异常'}")
self.actions.addItem("需要人工确认的动作会显示在这里")
def _send(self):
message = self.input.text().strip()
if not message: return
self.input.clear(); self.chat.append(f"你:{message}")
if self.client is None:
self.chat.append("助手:尚未配置 DeepSeek/OpenAI 兼容模型;本地监管仍可用。")
return
try:
result = self.client.chat(message, self.snapshot.safe_dict())
self.chat.append(f"助手:{result['reply']}")
except DshClientError as error:
self.chat.append(f"助手:{error}")
+42
View File
@@ -0,0 +1,42 @@
from dx_productivity.dsh.actions import validate_action
from dx_productivity.dsh.client import DshClientError, DshConfig, OpenAICompatibleClient
from dx_productivity.dsh.rules import classify
from dx_productivity.dsh.snapshot import TaskSnapshot
from dx_productivity.dsh.supervisor import DshSupervisor
def test_snapshot_redacts_paths_and_bounds_progress():
snapshot = TaskSnapshot("task-1", "failed", {"completed": 2, "path": "secret"}, "boom" * 500, "timeout")
safe = snapshot.safe_dict()
assert "path" not in safe["progress"]
assert len(safe["issue"]) == 500
def test_failed_event_auto_retries_once():
calls = []
supervisor = DshSupervisor(calls.append)
snapshot = TaskSnapshot("task-1", "failed", issue_code="worker_error")
first = supervisor.observe(snapshot)
second = supervisor.observe(snapshot)
assert first["proposal"]["name"] == "retry_failed"
assert len(calls) == 1
assert second["result"] is None
def test_uncertain_is_manual_review():
assert classify(TaskSnapshot("t", "uncertain")) == "manual_review"
def test_unknown_action_and_unconfigured_client_fail_closed():
try:
validate_action({"name": "shell", "task_id": "t"})
except ValueError as error:
assert str(error) == "unknown_dsh_action"
else:
raise AssertionError("unknown action accepted")
try:
OpenAICompatibleClient(DshConfig()).chat("hi", {})
except DshClientError as error:
assert str(error) == "dsh_model_not_configured"
else:
raise AssertionError("unconfigured client accepted")
+15
View File
@@ -0,0 +1,15 @@
from dx_productivity.dsh.actions import ActionProposal
from dx_productivity.dsh.service_adapter import DshServiceAdapter
class FakeService:
def __init__(self): self.calls = []
def prepare_failed_quick_run(self, task_id): self.calls.append(("retry", task_id))
def pause_task(self, task_id): self.calls.append(("pause", task_id))
def test_adapter_exposes_only_fixed_service_operations():
service = FakeService()
result = DshServiceAdapter(service).execute(ActionProposal("retry_failed", "task-1"))
assert result["status"] == "accepted"
assert service.calls == [("retry", "task-1")]