@hupan56/wlkj 2.7.12 → 3.1.2

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"

package/templates/qoder/scripts/capability/chain.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""
+ProviderChain —— 能力 Provider 职责链。
+
+设计模式:
+    - Chain of Responsibility（职责链）: 按优先级遍历，第一个 available 的命中
+    - Strategy（策略组合）: 每个 provider 是一种策略实现
+    - Decorator（装饰器）: 可选地对命中的 provider 增强（缓存/日志/统计）
+
+透明代理: ProviderChain 把方法调用转发给命中的 provider，
+          对调用方而言与直接用 Cap 无异。
+
+    chain = ProviderChain([McpMemoryProvider(), QwMemoryCap(),
+                           FileMemoryCap(), NoOpMemoryCap()])
+    chain.recall("本周执行")   # 自动代理到第一个 available 的 provider
+
+链尾永远是 NoOp，保证无能力时不抛错（Null Object 兜底）。
+
+演进（扩展场景 C: 能力 MCP 化迁移）:
+    mem0 MCP server 成熟 → 链头插入 McpMemoryProvider →
+    available=True 自动抢占 → 旧的 QwMemoryCap 沉到链尾静默退役 →
+    调用方代码零改动。这就是"未来 vs 现实"的机制化。
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class ProviderChain:
+    """能力 Provider 职责链。
+
+    Args:
+        providers: 按优先级排列的 provider 列表，链尾应为 NoOp。
+        decorators: 可选装饰器列表，每个形式 func(provider_method, provider) -> wrapped，
+                    对命中的 provider 的方法做增强（缓存/日志/降级统计），不改原 provider。
+    """
+
+    def __init__(self, providers: list, decorators: list | None = None):
+        # 用 object.__setattr__ 绕过自定义 __getattr__，避免初始化期递归
+        object.__setattr__(self, "_providers", list(providers))
+        object.__setattr__(self, "_decorators", list(decorators or []))
+        object.__setattr__(self, "_active", None)
+        object.__setattr__(self, "_probed", False)
+
+    @property
+    def available(self) -> bool:
+        """是否有任一 provider 可用。"""
+        return self._probe() is not None
+
+    def _probe(self) -> Any:
+        """返回第一个 available 的 provider，缓存结果（首次探测后不再变）。"""
+        if self._probed:
+            return self._active
+        for p in self._providers:
+            if getattr(p, "available", False):
+                object.__setattr__(self, "_active", p)
+                break
+        object.__setattr__(self, "_probed", True)
+        return self._active
+
+    def providers_status(self) -> list[dict]:
+        """诊断用：每个 provider 的 available 状态 + 是否命中。"""
+        active = self._probe()
+        return [
+            {
+                "provider": type(p).__name__,
+                "available": bool(getattr(p, "available", False)),
+                "hit": p is active,
+            }
+            for p in self._providers
+        ]
+
+    def __getattr__(self, name: str) -> Any:
+        """透明代理：把属性/方法调用转发给命中的 provider。
+
+        调用方写 chain.recall(q) 等价于 active_provider.recall(q)。
+        若无任何 provider available，用链尾（NoOp）兜底，绝不抛错。
+        """
+        if name.startswith("_"):
+            raise AttributeError(name)
+        active = self._probe()
+        if active is None:
+            # 兜底：链尾 NoOp
+            active = self._providers[-1] if self._providers else None
+        if active is None:
+            raise AttributeError(f"ProviderChain 无 provider 可解析 '{name}'")
+        attr = getattr(active, name)
+        # 应用装饰器（仅对可调用方法）
+        if callable(attr) and self._decorators:
+            for dec in self._decorators:
+                attr = dec(attr, active)
+        return attr

package/templates/qoder/scripts/capability/memory_chain.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""
+memory 能力职责链装配。
+
+设计模式: Provider Chain + Strategy
+
+独立成文件的理由: memory 是最复杂的 L2 能力（4 个 provider），
+未来加 provider（如向量库、mem0 MCP）只改本文件，不动 registry ——
+体现 Plugin/SPI：新实现接入不改核心。
+
+优先级（高→低）:
+    ① McpMemoryProvider  —— 未来 mem0/Zep MCP server（现状 available=False）
+    ② QwMemoryCap        —— QoderWork 原生（仅 qoderwork 宿主）
+    ③ FileMemoryCap      —— 文件降级（纯 CLI/任意宿主）
+    ④ NoOpMemoryCap      —— 兜底（绝不抛错）
+
+演进（扩展场景 C）: mem0 MCP 成熟 → 把 McpMemoryProvider 的 available 打开 →
+              自动抢占链头 → FileMemoryCap/QwMemoryCap 静默退役 → 调用方零改动。
+"""
+from __future__ import annotations
+
+from .chain import ProviderChain
+from .caps import NoOpMemoryCap
+
+
+def build_memory_chain(host: str) -> ProviderChain:
+    """装配 memory 职责链。
+
+    Args:
+        host: detect_host() 返回的宿主名。
+    """
+    from .adapters.mcp import McpMemoryProvider
+    from .adapters.cli import FileMemoryCap
+
+    providers: list = [McpMemoryProvider()]
+    if host == "qoderwork":
+        from .adapters.qw import QwMemoryCap
+        providers.append(QwMemoryCap())
+    providers.append(FileMemoryCap())
+    providers.append(NoOpMemoryCap())
+    return ProviderChain(providers)