@hupan56/wlkj 3.0.0 → 3.1.2

package/templates/qoder/scripts/capability/adapters/qw.py

@@ -0,0 +1,271 @@
+# -*- coding: utf-8 -*-
+"""
+adapters.qw —— QoderWork 原生能力 Adapter。
+
+设计模式: Adapter（适配 QoderWork 原生工具到 Cap 契约）
+
+实现 QoderWork 提供的 L2 宿主原生能力。其他宿主（ZCode/Codex）不适用，
+未实现的 Cap 由 NoOp 兜底。
+
+QoderWork 提供的相关工具（参考）:
+    memory / memory_search / memory_get  → QwMemoryCap（转发到 MCP 层）
+    qoder_cron                            → QwCronCap（文件 + 系统 crontab）
+    qw_mcp_list/get/call                  → 走 McpCap（L1）
+    delegate_to_im                        → QwNotifyCap（后续补）
+    qoder_show_widget / present_files     → QwPresentCap（后续补）
+
+本模块实现 QwMemoryCap + QwCronCap，其余后续补。
+"""
+from __future__ import annotations
+
+import os
+
+
+def is_qoderwork() -> bool:
+    """探测当前是否运行在 QoderWork 宿主内。
+
+    QoderWork 注入 QODER_SESSION_ID（会话）或 QODER_MCP_AVAILABLE（MCP 网关）。
+    """
+    if os.environ.get("QODER_SESSION_ID"):
+        return True
+    return os.environ.get("QODER_MCP_AVAILABLE", "").lower() in ("1", "true", "yes")
+
+
+class QwMemoryCap:
+    """QoderWork memory 工具适配器。
+
+    设计模式: Adapter（QoderWork → MemoryCap 契约）
+
+    策略: 优先使用 QoderWork 原生 memory 工具，降级到 MCP MemoryProvider。
+    当前实现: 转发到 MCP 层的 McpMemoryProvider（接通 kg.duckdb）。
+    未来: QoderWork 原生 memory 工具可用时，优先用原生。
+    """
+
+    def __init__(self):
+        self._env = is_qoderwork()
+        self._mcp_provider = None
+
+    def _get_mcp_provider(self):
+        """延迟获取 MCP MemoryProvider（避免循环导入）。"""
+        if self._mcp_provider is None:
+            try:
+                from .mcp import McpMemoryProvider
+                self._mcp_provider = McpMemoryProvider()
+            except Exception:
+                pass
+        return self._mcp_provider
+
+    @property
+    def available(self) -> bool:
+        """QoderWork 环境下可用（降级到 MCP 层）。"""
+        if self._env:
+            return True
+        # 非 QoderWork 环境，看 MCP provider 是否可用
+        provider = self._get_mcp_provider()
+        return bool(provider and provider.available)
+
+    def recall(self, query: str) -> list[dict]:
+        """语义检索记忆：优先 QoderWork 原生，降级 MCP。"""
+        # TODO: QoderWork 原生 memory_search 工具可用时优先调用
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            return provider.recall(query)
+        return []
+
+    def remember(self, key: str, content: str) -> None:
+        """写入记忆：优先 QoderWork 原生，降级 MCP。"""
+        # TODO: QoderWork 原生 memory 工具可用时优先调用
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            provider.remember(key, content)
+
+    def get_fact(self, key: str) -> str | None:
+        """按 key 取事实：优先 QoderWork 原生，降级 MCP。"""
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            return provider.get_fact(key)
+        return None
+
+    def list_recent(self, limit: int = 10) -> list[dict]:
+        """最近 N 条记忆：优先 QoderWork 原生，降级 MCP。"""
+        provider = self._get_mcp_provider()
+        if provider and provider.available:
+            return provider.list_recent(limit)
+        return []
+
+
+class QwCronCap:
+    """QoderWork cron 工具适配器。
+
+    设计模式: Adapter（QoderWork → CronCap 契约）
+
+    当前实现: 使用 common.events 的 cron 注册文件（.qoder/data/cron/）。
+    未来: QoderWork 原生 qoder_cron 工具可用时优先用原生。
+    """
+
+    CRON_DIR = ".qoder" + os.sep + "data" + os.sep + "cron"
+
+    def __init__(self):
+        self._env = is_qoderwork()
+
+    @property
+    def available(self) -> bool:
+        """文件系统可写即可用。"""
+        try:
+            from pathlib import Path
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            cron_dir = repo_root / self.CRON_DIR
+            cron_dir.mkdir(parents=True, exist_ok=True)
+            return cron_dir.is_dir()
+        except Exception:
+            return False
+
+    def add(self, cron_expr: str, command: str, label: str = "") -> str:
+        """添加定时任务，返回 job_id。"""
+        import json
+        import time
+        from pathlib import Path
+
+        try:
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            cron_dir = repo_root / self.CRON_DIR
+            cron_dir.mkdir(parents=True, exist_ok=True)
+
+            job_id = "%s-%s" % (label or "job", int(time.time()))
+            job = {
+                "id": job_id,
+                "cron": cron_expr,
+                "command": command,
+                "label": label,
+                "enabled": True,
+            }
+            job_file = cron_dir / ("%s.json" % job_id)
+            with open(job_file, "w", encoding="utf-8") as f:
+                json.dump(job, f, ensure_ascii=False, indent=2)
+            return job_id
+        except Exception as e:
+            return "error: %s" % str(e)[:80]
+
+    def list(self) -> list[dict]:
+        """列出所有定时任务。"""
+        import json
+        from pathlib import Path
+
+        try:
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            cron_dir = repo_root / self.CRON_DIR
+            if not cron_dir.is_dir():
+                return []
+            jobs = []
+            for f in cron_dir.glob("*.json"):
+                try:
+                    with open(f, encoding="utf-8") as fh:
+                        jobs.append(json.load(fh))
+                except Exception:
+                    continue
+            return sorted(jobs, key=lambda j: j.get("id", ""))
+        except Exception:
+            return []
+
+    def remove(self, job_id: str) -> bool:
+        """删除定时任务。"""
+        from pathlib import Path
+
+        try:
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            job_file = repo_root / self.CRON_DIR / ("%s.json" % job_id)
+            if job_file.is_file():
+                job_file.unlink()
+                return True
+        except Exception:
+            pass
+        return False
+
+
+class QwPresentCap:
+    """QoderWork 富展示能力适配器。
+
+    设计模式: Adapter（QoderWork qoder_show_widget → PresentCap 契约）
+
+    把"渲染交互 HTML 到对话流"从宿主原生工具适配到 PresentCap.widget()。
+    降级链: QoderWork 原生 qoder_show_widget → 落盘 HTML 文件(纯 CLI 兜底)。
+    """
+
+    def __init__(self):
+        self._env = is_qoderwork()
+
+    @property
+    def available(self) -> bool:
+        """QoderWork 环境且 qoder_show_widget 工具可达时可用。"""
+        if not self._env:
+            return False
+        # 探测宿主工具是否可达 (走 McpCap, 失败则降级)
+        try:
+            from .mcp import _get_registry
+            reg = _get_registry()
+            return reg.has_tool("qoder_show_widget")
+        except Exception:
+            return False
+
+    def _try_host_widget(self, html: str) -> bool:
+        """尝试调宿主 qoder_show_widget 把 HTML 嵌入对话流。成功返回 True。"""
+        try:
+            from .mcp import _get_registry
+            reg = _get_registry()
+            result = reg.call("qoder_show_widget", {"html": html})
+            return not result.is_error
+        except Exception:
+            return False
+
+    def widget(self, html: str) -> bool:
+        """展示交互 widget。优先嵌入对话流, 降级落盘 HTML 文件。"""
+        if self._try_host_widget(html):
+            return True
+        # 降级: 落盘到 journal (纯 CLI / 工具不可达时)
+        try:
+            from datetime import datetime
+            from pathlib import Path
+            repo_root = Path(__file__).resolve().parent.parent.parent.parent
+            # 找当前 dev
+            dev = "default"
+            dev_file = repo_root / ".qoder" / ".developer"
+            if dev_file.is_file():
+                for line in dev_file.read_text(encoding="utf-8").splitlines():
+                    if "name=" in line:
+                        dev = line.split("name=", 1)[1].strip().split()[0]
+                        break
+            out_dir = repo_root / "workspace" / "members" / dev / "journal"
+            out_dir.mkdir(parents=True, exist_ok=True)
+            out = out_dir / ("dashboard-%s.html" % datetime.now().strftime("%Y%m%d-%H%M%S"))
+            out.write_text(html, encoding="utf-8")
+            print("[PresentCap] qoder_show_widget 不可达, 看板已落盘: %s" % out)
+            return False  # 通知调用方: 未嵌入对话流(但已落盘)
+        except Exception:
+            return False
+
+    def table(self, rows: list, headers: list | None = None) -> str:
+        """渲染 markdown 表格 (兜底, 所有宿主都能看)。"""
+        if not rows:
+            return ""
+        headers = headers or (list(rows[0].keys()) if rows and isinstance(rows[0], dict) else [])
+        lines = ["| " + " | ".join(str(h) for h in headers) + " |",
+                 "| " + " | ".join("---" for _ in headers) + " |"]
+        for r in rows:
+            if isinstance(r, dict):
+                lines.append("| " + " | ".join(str(r.get(h, "")) for h in headers) + " |")
+            else:
+                lines.append("| " + " | ".join(str(x) for x in r) + " |")
+        return "\n".join(lines)
+
+    def files(self, paths: list) -> bool:
+        """以文件卡片展示。降级: 打印路径列表。"""
+        try:
+            from .mcp import _get_registry
+            reg = _get_registry()
+            if reg.has_tool("present_files"):
+                result = reg.call("present_files", {"paths": paths})
+                return not result.is_error
+        except Exception:
+            pass
+        print("[PresentCap] present_files 不可达, 文件列表: " + ", ".join(str(p) for p in paths))
+        return False

package/templates/qoder/scripts/capability/caps/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+nexus.caps —— L2 宿主原生能力契约层。
+
+每个能力 = Protocol（契约）+ NoOp（默认空实现）。
+新增能力（扩展场景 B）= 新建一个文件定义 Protocol + NoOp，在此导出，
+                       再在 registry.Nexus 加属性、_resolve_xxx 加装配。
+"""
+from .memory import MemoryCap, NoOpMemoryCap
+from .repo import RepoCap, NoOpRepoCap
+from .identity import IdentityCap, NoOpIdentityCap
+from .context import ContextCap, NoOpContextCap
+from .cron import CronCap, NoOpCronCap
+from .notify import NotifyCap, NoOpNotifyCap
+from .present import PresentCap, NoOpPresentCap
+from .sandbox import SandboxCap, NoOpSandboxCap
+
+__all__ = [
+    "MemoryCap", "NoOpMemoryCap",
+    "RepoCap", "NoOpRepoCap",
+    "IdentityCap", "NoOpIdentityCap",
+    "ContextCap", "NoOpContextCap",
+    "CronCap", "NoOpCronCap",
+    "NotifyCap", "NoOpNotifyCap",
+    "PresentCap", "NoOpPresentCap",
+    "SandboxCap", "NoOpSandboxCap",
+]

package/templates/qoder/scripts/capability/caps/context.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""
+ContextCap —— 上下文/偏好能力契约。
+
+核心能力（必有降级）。读取 USER 偏好、最近学到的经验等。
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ContextCap(Protocol):
+    """上下文/偏好能力。"""
+
+    available: bool
+
+    def preferences(self) -> dict:
+        """USER 偏好字典。"""
+        ...
+
+    def recent_learnings(self, limit: int = 5) -> list[dict]:
+        """最近学到的经验/事实。"""
+        ...
+
+
+class NoOpContextCap:
+    """ContextCap 空实现。"""
+
+    available = False
+
+    def preferences(self) -> dict:
+        return {}
+
+    def recent_learnings(self, limit: int = 5) -> list[dict]:
+        return []

package/templates/qoder/scripts/capability/caps/cron.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""
+CronCap —— 定时任务能力契约。
+
+增强能力（NoOp 兜底即可）。
+工作流场景: 每周自动拉禅道任务排优先级、每日 git 同步等。
+
+各宿主语义不同（场景 E）:
+    - QoderWork: qoder_cron 工具
+    - CLI:       系统 crontab
+    - 未来:      MCP cron server
+通过 Provider Chain 统一，各 provider 自治。
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CronCap(Protocol):
+    """定时任务能力。"""
+
+    available: bool
+
+    def add(self, name: str, schedule: str, prompt: str) -> str:
+        """添加定时任务，返回 job_id（失败返回空串）。"""
+        ...
+
+    def list(self) -> list[dict]:
+        """列出所有定时任务。"""
+        ...
+
+    def remove(self, job_id: str) -> bool:
+        """删除定时任务。"""
+        ...
+
+
+class NoOpCronCap:
+    """CronCap 空实现 —— 无定时能力时静默返回。"""
+
+    available = False
+
+    def add(self, name: str, schedule: str, prompt: str) -> str:
+        return ""
+
+    def list(self) -> list[dict]:
+        return []
+
+    def remove(self, job_id: str) -> bool:
+        return False

package/templates/qoder/scripts/capability/caps/identity.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""
+IdentityCap —— 操作者身份能力契约。
+
+核心能力（必有降级）。工作流需要知道"谁在操作"（whoami / 角色 / 禅道账号）。
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IdentityCap(Protocol):
+    """操作者身份能力。"""
+
+    available: bool
+
+    def who(self) -> str | None:
+        """developer 名（.developer 文件）。"""
+        ...
+
+    def role(self) -> str | None:
+        """角色: pm / dev / qa。"""
+        ...
+
+    def zentao_account(self) -> str | None:
+        """禅道账号映射（后续接入禅道时用）。"""
+        ...
+
+
+class NoOpIdentityCap:
+    """IdentityCap 空实现。仅占位 —— 核心能力总有文件降级。"""
+
+    available = False
+
+    def who(self) -> str | None:
+        return None
+
+    def role(self) -> str | None:
+        return None
+
+    def zentao_account(self) -> str | None:
+        return None

package/templates/qoder/scripts/capability/caps/memory.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""
+MemoryCap —— 跨会话持久记忆能力契约。
+
+设计模式: Capability Protocol + Null Object
+
+工作流面向能力编程:
+    cap = nexus.resolve()
+    if cap.memory.available:
+        facts = cap.memory.recall("本周执行任务")
+
+L2 宿主原生能力。各宿主实现见 nexus/adapters/。
+未实现的宿主 → NoOpMemoryCap（available=False，方法静默返回空）。
+
+演进: 未来 mem0/Zep MCP server 成熟后，记忆能力 MCP 化，
+      McpMemoryProvider 抢占职责链链头，本契约不变。
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MemoryCap(Protocol):
+    """跨会话记忆能力契约。
+
+    各宿主实现:
+        - QwMemoryCap:      QoderWork 的 qw memory 工具（adapters/qw.py）
+        - FileMemoryCap:    文件降级 journal（adapters/cli.py）
+        - McpMemoryProvider:未来 mem0/Zep MCP server（adapters/mcp.py）
+    """
+
+    available: bool
+
+    def recall(self, query: str) -> list[dict]:
+        """语义检索记忆，返回相关条目列表。"""
+        ...
+
+    def remember(self, key: str, content: str) -> None:
+        """写入一条记忆。"""
+        ...
+
+    def get_fact(self, key: str) -> str | None:
+        """按 key 取一条事实，无则 None。"""
+        ...
+
+    def list_recent(self, limit: int = 10) -> list[dict]:
+        """最近 N 条记忆。"""
+        ...
+
+
+class NoOpMemoryCap:
+    """MemoryCap 空实现 —— Null Object 模式。
+
+    available=False，所有方法静默返回空值，绝不抛错。
+    作为 memory 职责链链尾兜底，保证无记忆能力时工作流不崩。
+    """
+
+    available = False
+
+    def recall(self, query: str) -> list[dict]:
+        return []
+
+    def remember(self, key: str, content: str) -> None:
+        pass
+
+    def get_fact(self, key: str) -> str | None:
+        return None
+
+    def list_recent(self, limit: int = 10) -> list[dict]:
+        return []

package/templates/qoder/scripts/capability/caps/notify.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""
+NotifyCap —— IM 通知能力契约。
+
+增强能力（NoOp 兜底）。
+工作流场景: 日报/任务变更/评审结果推送 IM。
+
+各宿主实现:
+    - QoderWork: 微信/飞书连接器
+    - CLI:       飞书 webhook（已有降级）
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NotifyCap(Protocol):
+    """IM 通知能力。"""
+
+    available: bool
+
+    def send(self, channel: str, message: str) -> bool:
+        """发送消息到指定渠道，返回是否成功。"""
+        ...
+
+    def list_channels(self) -> list[dict]:
+        """列出可用渠道。"""
+        ...
+
+
+class NoOpNotifyCap:
+    """NotifyCap 空实现。"""
+
+    available = False
+
+    def send(self, channel: str, message: str) -> bool:
+        return False
+
+    def list_channels(self) -> list[dict]:
+        return []

package/templates/qoder/scripts/capability/caps/present.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""
+PresentCap —— 富展示能力契约。
+
+增强能力（NoOp 兜底）。
+工作流场景: 任务看板、甘特图、文件卡片、交互 widget。
+
+各宿主实现:
+    - QoderWork: show_widget / present_files
+    - CLI:       markdown 表格降级
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PresentCap(Protocol):
+    """富展示能力。"""
+
+    available: bool
+
+    def table(self, rows: list, headers: list | None = None) -> str:
+        """渲染表格，返回可展示文本。"""
+        ...
+
+    def widget(self, html: str) -> bool:
+        """展示交互 widget（仅富宿主），返回是否成功。"""
+        ...
+
+    def files(self, paths: list) -> bool:
+        """以文件卡片形式展示。"""
+        ...
+
+
+class NoOpPresentCap:
+    """PresentCap 空实现 —— 无富展示时退化为空。"""
+
+    available = False
+
+    def table(self, rows: list, headers: list | None = None) -> str:
+        return ""
+
+    def widget(self, html: str) -> bool:
+        return False
+
+    def files(self, paths: list) -> bool:
+        return False

package/templates/qoder/scripts/capability/caps/repo.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+"""
+RepoCap —— 仓库根发现能力契约。
+
+核心能力（必有降级）。替代散落在 skill 里的 ~/.qoderwork/repo_root.py 硬编码。
+让"仓库根发现"宿主无关：向上找含 .qoder/scripts/ 的目录即可。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class RepoCap(Protocol):
+    """仓库根发现能力。"""
+
+    available: bool
+
+    def root(self) -> Path:
+        """返回项目仓库根路径。"""
+        ...
+
+
+class NoOpRepoCap:
+    """RepoCap 空实现。仅占位 —— 核心能力总有文件降级，不会真用到 NoOp。"""
+
+    available = False
+
+    def root(self) -> Path:
+        return Path.cwd()

package/templates/qoder/scripts/capability/caps/sandbox.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""
+SandboxCap —— 安全执行能力契约。
+
+执行安全类（宿主差异大，NoOp 兜底）。
+工作流场景: 在隔离环境跑命令/测试/构建。
+
+各宿主实现:
+    - Claude Code: container / seatbelt
+    - Codex CLI:    Docker + seatbelt
+    - QoderWork:    （暂无原生沙箱）
+    - CLI:          直接执行（无沙箱，approval 把关）
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SandboxCap(Protocol):
+    """安全执行能力。"""
+
+    available: bool
+
+    def run(self, command: str, cwd: str | None = None, timeout: int = 60) -> dict:
+        """在沙箱内执行命令，返回 {ok, stdout, stderr, returncode}。"""
+        ...
+
+    def approval_mode(self) -> str:
+        """当前自主等级: suggest / auto-edit / full-auto / plan。"""
+        ...
+
+
+class NoOpSandboxCap:
+    """SandboxCap 空实现 —— 无沙箱时拒绝执行。"""
+
+    available = False
+
+    def run(self, command: str, cwd: str | None = None, timeout: int = 60) -> dict:
+        return {"ok": False, "reason": "no sandbox available"}
+
+    def approval_mode(self) -> str:
+        return "suggest"