diff --git a/docs/superpowers/plans/2026-10-30-dsh-ai-supervision.md b/docs/superpowers/plans/2026-10-30-dsh-ai-supervision.md new file mode 100644 index 0000000..ceb317b --- /dev/null +++ b/docs/superpowers/plans/2026-10-30-dsh-ai-supervision.md @@ -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. diff --git a/docs/superpowers/specs/2026-10-30-dsh-ai-supervision-design.md b/docs/superpowers/specs/2026-10-30-dsh-ai-supervision-design.md new file mode 100644 index 0000000..744b8e5 --- /dev/null +++ b/docs/superpowers/specs/2026-10-30-dsh-ai-supervision-design.md @@ -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 可打开助手面板,发送问题并显示模型回复或未配置提示。 +- 所有动作和结果进入监管内存日志,且不替代现有执行证据。 diff --git a/docs/user/dsh-ai-supervision.md b/docs/user/dsh-ai-supervision.md new file mode 100644 index 0000000..fc6aa61 --- /dev/null +++ b/docs/user/dsh-ai-supervision.md @@ -0,0 +1,5 @@ +# DSH AI 监管助手 + +DSH 是任务中心内的工具型监管入口。它先使用本地规则识别失败、超时和不确定状态;明确失败可生成一次性的重试动作。模型只负责解释和提出结构化建议,不能直接调用 CAD、Shell、文件系统或任意网络工具。 + +打开任务中心的“DSH AI 监管”后,可以查看当前任务状态并进行人工对话。未配置 DeepSeek/OpenAI 兼容接口时,对话会明确提示,但本地监管和固定动作仍然可用。工程写入、规则修改和不确定状态恢复始终需要人工确认。 diff --git a/src/dx_productivity/dsh/__init__.py b/src/dx_productivity/dsh/__init__.py new file mode 100644 index 0000000..1004a8c --- /dev/null +++ b/src/dx_productivity/dsh/__init__.py @@ -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"] diff --git a/src/dx_productivity/dsh/actions.py b/src/dx_productivity/dsh/actions.py new file mode 100644 index 0000000..f55f2fd --- /dev/null +++ b/src/dx_productivity/dsh/actions.py @@ -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))) diff --git a/src/dx_productivity/dsh/client.py b/src/dx_productivity/dsh/client.py new file mode 100644 index 0000000..36f0a26 --- /dev/null +++ b/src/dx_productivity/dsh/client.py @@ -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 diff --git a/src/dx_productivity/dsh/rules.py b/src/dx_productivity/dsh/rules.py new file mode 100644 index 0000000..ad962f4 --- /dev/null +++ b/src/dx_productivity/dsh/rules.py @@ -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, "明确失败且未进入不确定状态") diff --git a/src/dx_productivity/dsh/service_adapter.py b/src/dx_productivity/dsh/service_adapter.py new file mode 100644 index 0000000..1c4cdd2 --- /dev/null +++ b/src/dx_productivity/dsh/service_adapter.py @@ -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") diff --git a/src/dx_productivity/dsh/snapshot.py b/src/dx_productivity/dsh/snapshot.py new file mode 100644 index 0000000..254aade --- /dev/null +++ b/src/dx_productivity/dsh/snapshot.py @@ -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, + } diff --git a/src/dx_productivity/dsh/supervisor.py b/src/dx_productivity/dsh/supervisor.py new file mode 100644 index 0000000..8215e41 --- /dev/null +++ b/src/dx_productivity/dsh/supervisor.py @@ -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 diff --git a/src/dx_productivity/trial_task_center/ui/dsh_panel.py b/src/dx_productivity/trial_task_center/ui/dsh_panel.py new file mode 100644 index 0000000..656bd19 --- /dev/null +++ b/src/dx_productivity/trial_task_center/ui/dsh_panel.py @@ -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}") + diff --git a/tests/dsh/test_core.py b/tests/dsh/test_core.py new file mode 100644 index 0000000..95b0acc --- /dev/null +++ b/tests/dsh/test_core.py @@ -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") diff --git a/tests/dsh/test_service_adapter.py b/tests/dsh/test_service_adapter.py new file mode 100644 index 0000000..88b820a --- /dev/null +++ b/tests/dsh/test_service_adapter.py @@ -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")]