feat: add DSH AI supervision core
This commit is contained in:
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 可打开助手面板,发送问题并显示模型回复或未配置提示。
|
||||
- 所有动作和结果进入监管内存日志,且不替代现有执行证据。
|
||||
@@ -0,0 +1,5 @@
|
||||
# DSH AI 监管助手
|
||||
|
||||
DSH 是任务中心内的工具型监管入口。它先使用本地规则识别失败、超时和不确定状态;明确失败可生成一次性的重试动作。模型只负责解释和提出结构化建议,不能直接调用 CAD、Shell、文件系统或任意网络工具。
|
||||
|
||||
打开任务中心的“DSH AI 监管”后,可以查看当前任务状态并进行人工对话。未配置 DeepSeek/OpenAI 兼容接口时,对话会明确提示,但本地监管和固定动作仍然可用。工程写入、规则修改和不确定状态恢复始终需要人工确认。
|
||||
@@ -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"]
|
||||
@@ -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)))
|
||||
@@ -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
|
||||
@@ -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")
|
||||
@@ -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,
|
||||
}
|
||||
@@ -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}")
|
||||
|
||||
@@ -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")
|
||||
@@ -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")]
|
||||
Reference in new issue
Block a user