windcode 0.1.0__py3-none-any.whl

windcode/extensions/skills/tools.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from windcode.domain.messages import SourcedContextMessage
+from windcode.domain.tools import ToolContext, ToolEffect, ToolResult
+from windcode.extensions.models import (
+    ActivationState,
+    CapabilityKind,
+    CapabilityRecord,
+    ExtensionSnapshot,
+)
+from windcode.extensions.skills.loader import SkillContent, SkillLoader
+from windcode.extensions.skills.parser import SkillMetadata
+from windcode.tools.registry import ToolRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class SkillSearchResult:
+    capability_id: str
+    name: str
+    description: str
+    source_id: str
+    shadowed_by: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class SkillActivationResult:
+    name: str
+    source_id: str
+    digest: str
+    loaded: bool
+
+
+class SkillCatalog:
+    def __init__(self, snapshot: ExtensionSnapshot, loader: SkillLoader) -> None:
+        self.snapshot = snapshot
+        self.loader = loader
+
+    def search(self, query: str = "") -> tuple[SkillSearchResult, ...]:
+        needle = query.casefold().strip()
+        results: list[SkillSearchResult] = []
+        for record in self.snapshot.capabilities:
+            if record.kind is not CapabilityKind.SKILL:
+                continue
+            if (
+                not record.enabled
+                or not record.trusted
+                or record.shadowed_by is not None
+                or record.activation is ActivationState.FAILED
+            ):
+                continue
+            metadata = self.snapshot.definitions.get(record.capability_id)
+            if not isinstance(metadata, SkillMetadata):
+                continue
+            if (
+                needle
+                and needle not in metadata.name.casefold()
+                and needle not in metadata.description.casefold()
+            ):
+                continue
+            results.append(
+                SkillSearchResult(
+                    record.capability_id,
+                    metadata.name,
+                    metadata.description,
+                    record.source.source_id,
+                    record.shadowed_by,
+                )
+            )
+        return tuple(results)
+
+    def load(self, selector: str) -> tuple[SkillContent, SourcedContextMessage]:
+        normalized = selector.removeprefix("$").casefold()
+        matches: list[tuple[CapabilityRecord, SkillMetadata]] = []
+        for record in self.snapshot.capabilities:
+            metadata = self.snapshot.definitions.get(record.capability_id)
+            if (
+                record.kind is CapabilityKind.SKILL
+                and record.enabled
+                and record.trusted
+                and record.shadowed_by is None
+                and isinstance(metadata, SkillMetadata)
+                and (record.capability_id == selector or metadata.name == normalized)
+            ):
+                matches.append((record, metadata))
+        if len(matches) != 1:
+            raise ValueError(f"Skill selector is missing or ambiguous: {selector}")
+        content = self.loader.load(*matches[0])
+        return content, SourcedContextMessage(content.source_id, content.content)
+
+
+class SkillRuntime:
+    """Per-run Skill catalog, activation state, and pending sourced context."""
+
+    def __init__(self, catalog: SkillCatalog) -> None:
+        self.catalog = catalog
+        self._loaded: set[tuple[str, str]] = set()
+        self._pending_context: list[SourcedContextMessage] = []
+
+    def search(self, query: str = "") -> tuple[SkillSearchResult, ...]:
+        return self.catalog.search(query)
+
+    def activate(self, selector: str) -> SkillActivationResult:
+        content, message = self.catalog.load(selector)
+        key = (content.source_id, content.digest)
+        loaded = key not in self._loaded
+        if loaded:
+            self._loaded.add(key)
+            self._pending_context.append(message)
+        return SkillActivationResult(content.name, content.source_id, content.digest, loaded)
+
+    def drain_context(self) -> tuple[SourcedContextMessage, ...]:
+        messages = tuple(self._pending_context)
+        self._pending_context.clear()
+        return messages
+
+
+class _StrictInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class SearchSkillsInput(_StrictInput):
+    query: str = Field(default="", max_length=2_000)
+
+
+class LoadSkillInput(_StrictInput):
+    name: str = Field(min_length=1, max_length=256)
+
+
+SkillActivator = Callable[[str], Awaitable[SkillActivationResult]]
+
+
+class SearchSkillsTool:
+    name = "search_skills"
+    description = (
+        "Search enabled and trusted Agent Skills by name or description. Results contain compact "
+        "metadata only. Use load_skill with an exact result name to load its instructions."
+    )
+    input_model = SearchSkillsInput
+    effects = frozenset[ToolEffect]()
+
+    def __init__(self, runtime: SkillRuntime) -> None:
+        self.runtime = runtime
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        del context
+        parsed = cast(SearchSkillsInput, arguments)
+        results = self.runtime.search(parsed.query)
+        data = {
+            "skills": [
+                {
+                    "capability_id": item.capability_id,
+                    "name": item.name,
+                    "description": item.description,
+                    "source_id": item.source_id,
+                }
+                for item in results
+            ]
+        }
+        return ToolResult(json.dumps(data, ensure_ascii=False, sort_keys=True), data=data)
+
+
+class LoadSkillTool:
+    name = "load_skill"
+    description = (
+        "Load one enabled and trusted Agent Skill into the next model step. Pass an exact name "
+        "returned by search_skills. Repeated loads in one run do not duplicate instructions."
+    )
+    input_model = LoadSkillInput
+    effects = frozenset({ToolEffect.READ})
+
+    def __init__(self, activate: SkillActivator) -> None:
+        self.activate = activate
+
+    async def execute(self, context: ToolContext, arguments: BaseModel) -> ToolResult:
+        del context
+        parsed = cast(LoadSkillInput, arguments)
+        try:
+            result = await self.activate(parsed.name)
+        except ValueError as exc:
+            data = {
+                "error": "skill_unavailable",
+                "message": str(exc),
+                "name": parsed.name,
+            }
+            return ToolResult(
+                json.dumps(data, ensure_ascii=False, sort_keys=True),
+                is_error=True,
+                data=data,
+            )
+        data = {
+            "name": result.name,
+            "source_id": result.source_id,
+            "status": "loaded" if result.loaded else "already_loaded",
+        }
+        return ToolResult(json.dumps(data, ensure_ascii=False, sort_keys=True), data=data)
+
+
+def register_skill_tools(
+    registry: ToolRegistry,
+    runtime: SkillRuntime,
+    activate: SkillActivator,
+    *,
+    replace: bool = False,
+) -> None:
+    registry.register(SearchSkillsTool(runtime), replace=replace)
+    registry.register(LoadSkillTool(activate), replace=replace)

windcode/extensions/snapshot.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from dataclasses import dataclass
+
+from windcode.extensions.discovery import DiscoveryResult
+from windcode.extensions.models import DiagnosticSeverity, ExtensionSnapshot
+
+
+def config_fingerprint(value: object) -> str:
+    payload = json.dumps(value, sort_keys=True, separators=(",", ":"), default=str).encode()
+    return hashlib.sha256(payload).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotCandidate:
+    snapshot: ExtensionSnapshot
+    publishable: bool
+
+
+def build_candidate(
+    result: DiscoveryResult, *, generation: int, config: object
+) -> SnapshotCandidate:
+    snapshot = ExtensionSnapshot(
+        generation,
+        config_fingerprint(config),
+        result.records,
+        result.definitions,
+        result.diagnostics,
+    )
+    required_sources = {item.source.source_id for item in result.records if item.required}
+    blocked = any(
+        diagnostic.severity is DiagnosticSeverity.ERROR and diagnostic.source_id in required_sources
+        for diagnostic in result.diagnostics
+    )
+    return SnapshotCandidate(snapshot, not blocked)
+
+
+class SnapshotPublisher:
+    def __init__(self, initial: ExtensionSnapshot | None = None) -> None:
+        self._current = initial or ExtensionSnapshot(0, config_fingerprint({}))
+        self._write_lock = threading.Lock()
+
+    @property
+    def current(self) -> ExtensionSnapshot:
+        return self._current
+
+    def publish(self, candidate: SnapshotCandidate) -> bool:
+        if not candidate.publishable:
+            return False
+        with self._write_lock:
+            if candidate.snapshot.generation <= self._current.generation:
+                raise ValueError("snapshot generation must increase")
+            self._current = candidate.snapshot
+        return True

windcode/extensions/state.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, cast
+from uuid import uuid4
+
+from windcode.extensions.models import Diagnostic, DiagnosticSeverity, DiagnosticStage
+
+
+@dataclass(frozen=True, slots=True)
+class InstalledPlugin:
+    plugin_id: str
+    version: str
+    digest: str
+    source_label: str
+    installed_at: str
+    enabled: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceTrust:
+    key: str
+    canonical_path: str
+    device: int
+    inode: int
+    trusted: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ManagementAuditRecord:
+    event_id: str
+    action: str
+    generation: int
+    source_id: str
+    status: str
+    timestamp: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionState:
+    version: int = 1
+    plugins: dict[str, InstalledPlugin] = field(default_factory=dict[str, InstalledPlugin])
+    workspaces: dict[str, WorkspaceTrust] = field(default_factory=dict[str, WorkspaceTrust])
+    enabled: dict[str, bool] = field(default_factory=dict[str, bool])
+    config: dict[str, dict[str, str | int | float | bool]] = field(
+        default_factory=dict[str, dict[str, str | int | float | bool]]
+    )
+    audit: tuple[ManagementAuditRecord, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class StateLoadResult:
+    state: ExtensionState | None
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+
+def workspace_identity(workspace: Path) -> WorkspaceTrust:
+    canonical = workspace.expanduser().resolve(strict=True)
+    info = canonical.stat()
+    raw = f"{canonical}\0{info.st_dev}\0{info.st_ino}".encode()
+    key = hashlib.sha256(raw).hexdigest()
+    return WorkspaceTrust(key, str(canonical), info.st_dev, info.st_ino, trusted=False)
+
+
+class ExtensionStateStore:
+    def __init__(self, path: Path) -> None:
+        self.path = path.expanduser().resolve()
+
+    def load(self) -> StateLoadResult:
+        if not self.path.exists():
+            return StateLoadResult(ExtensionState())
+        try:
+            raw = cast(dict[str, Any], json.loads(self.path.read_text(encoding="utf-8")))
+            plugins = {
+                key: InstalledPlugin(**cast(dict[str, Any], value))
+                for key, value in cast(dict[str, object], raw.get("plugins", {})).items()
+            }
+            workspaces = {
+                key: WorkspaceTrust(**cast(dict[str, Any], value))
+                for key, value in cast(dict[str, object], raw.get("workspaces", {})).items()
+            }
+            state = ExtensionState(
+                version=int(raw.get("version", 1)),
+                plugins=plugins,
+                workspaces=workspaces,
+                enabled={
+                    str(key): bool(value)
+                    for key, value in cast(dict[str, object], raw.get("enabled", {})).items()
+                },
+                config=cast(dict[str, dict[str, str | int | float | bool]], raw.get("config", {})),
+                audit=tuple(
+                    ManagementAuditRecord(**cast(dict[str, Any], value))
+                    for value in cast(list[object], raw.get("audit", []))
+                ),
+            )
+            return StateLoadResult(state)
+        except (OSError, UnicodeError, json.JSONDecodeError, TypeError, ValueError) as exc:
+            diagnostic = Diagnostic(
+                stage=DiagnosticStage.PARSE,
+                severity=DiagnosticSeverity.ERROR,
+                category="state_corrupt",
+                message=f"extension state could not be read: {exc}",
+                source_id="extension-state",
+                suggestion="Repair or restore the state file; Windcode did not overwrite it.",
+            )
+            return StateLoadResult(None, (diagnostic,))
+
+    def save(self, state: ExtensionState) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        os.chmod(self.path.parent, 0o700)
+        temporary = self.path.with_name(f".{self.path.name}.tmp-{uuid4().hex}")
+        payload = json.dumps(asdict(state), sort_keys=True, separators=(",", ":")) + "\n"
+        try:
+            descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+                stream.write(payload)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, self.path)
+            os.chmod(self.path, 0o600)
+            directory_fd = os.open(self.path.parent, os.O_RDONLY)
+            try:
+                os.fsync(directory_fd)
+            finally:
+                os.close(directory_fd)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def set_workspace_trust(
+        self, state: ExtensionState, workspace: Path, trusted: bool
+    ) -> ExtensionState:
+        identity = workspace_identity(workspace)
+        record = WorkspaceTrust(
+            identity.key,
+            identity.canonical_path,
+            identity.device,
+            identity.inode,
+            trusted,
+        )
+        workspaces = dict(state.workspaces)
+        workspaces[record.key] = record
+        return ExtensionState(
+            state.version,
+            dict(state.plugins),
+            workspaces,
+            dict(state.enabled),
+            dict(state.config),
+            state.audit,
+        )
+
+    def is_workspace_trusted(self, state: ExtensionState, workspace: Path) -> bool:
+        identity = workspace_identity(workspace)
+        record = state.workspaces.get(identity.key)
+        return record is not None and record.trusted

windcode/instructions/__init__.py

@@ -0,0 +1,8 @@
+from windcode.instructions.loader import (
+    INSTRUCTION_FILES,
+    InstructionBlock,
+    find_workspace_root,
+    load_instructions,
+)
+
+__all__ = ["INSTRUCTION_FILES", "InstructionBlock", "find_workspace_root", "load_instructions"]

windcode/instructions/loader.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+INSTRUCTION_FILES = ("AGENTS.md", "WINDCODE.md", "CLAUDE.md", "HERMES.md")
+
+
+@dataclass(frozen=True, slots=True)
+class InstructionBlock:
+    path: Path
+    content: str
+
+
+def find_workspace_root(current_dir: Path, workspace_root: Path | None = None) -> Path:
+    current = current_dir.expanduser().resolve()
+    if workspace_root is not None:
+        root = workspace_root.expanduser().resolve()
+        if not current.is_relative_to(root):
+            raise ValueError(f"current directory {current} is outside workspace {root}")
+        return root
+
+    for candidate in (current, *current.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return current
+
+
+def load_instructions(
+    current_dir: Path,
+    *,
+    workspace_root: Path | None = None,
+) -> tuple[InstructionBlock, ...]:
+    current = current_dir.expanduser().resolve()
+    root = find_workspace_root(current, workspace_root)
+    relative = current.relative_to(root)
+    directories = [root]
+    cursor = root
+    for part in relative.parts:
+        cursor /= part
+        directories.append(cursor)
+
+    blocks: list[InstructionBlock] = []
+    for directory in directories:
+        for filename in INSTRUCTION_FILES:
+            path = directory / filename
+            if path.is_file():
+                blocks.append(InstructionBlock(path=path, content=path.read_text(encoding="utf-8")))
+                break
+    return tuple(blocks)

windcode/memory/__init__.py

@@ -0,0 +1,57 @@
+from windcode.memory.extraction import (
+    classify_memory_intent,
+    explicitly_always_project_fact,
+    has_explicit_memory_intent,
+    is_project_fact,
+    is_stable_user_fact,
+    should_assess_experience,
+)
+from windcode.memory.models import (
+    MemoryActivation,
+    MemoryKind,
+    MemoryRecord,
+    MemoryScope,
+    MemorySearchResult,
+    MemorySource,
+    MemoryStatus,
+    default_memory_activation,
+    default_memory_priority,
+)
+from windcode.memory.refiner import (
+    ExperienceAssessment,
+    RefinedMemory,
+    assess_core_project_fact,
+    assess_experience,
+    refine_memory,
+)
+from windcode.memory.security import SensitiveMemoryError, contains_sensitive_data
+from windcode.memory.service import MemoryService
+from windcode.memory.store import MemoryStore, project_identifier
+
+__all__ = [
+    "ExperienceAssessment",
+    "MemoryActivation",
+    "MemoryKind",
+    "MemoryRecord",
+    "MemoryScope",
+    "MemorySearchResult",
+    "MemoryService",
+    "MemorySource",
+    "MemoryStatus",
+    "MemoryStore",
+    "RefinedMemory",
+    "SensitiveMemoryError",
+    "assess_core_project_fact",
+    "assess_experience",
+    "classify_memory_intent",
+    "contains_sensitive_data",
+    "default_memory_activation",
+    "default_memory_priority",
+    "explicitly_always_project_fact",
+    "has_explicit_memory_intent",
+    "is_project_fact",
+    "is_stable_user_fact",
+    "project_identifier",
+    "refine_memory",
+    "should_assess_experience",
+]

windcode/memory/extraction.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import re
+
+from windcode.memory.models import MemoryKind
+
+_USER_FACT_PATTERNS = (
+    re.compile(r"(?:^|[，,。\s])我(?:喜欢|偏好|习惯|希望|通常|总是|不喜欢|不希望).+"),  # noqa: RUF001
+    re.compile(r"(?:^|[，,。\s])我的(?:偏好|习惯|常用|工作方式|沟通方式).+(?:是|为).+"),  # noqa: RUF001
+    re.compile(r"(?i)(?:^|[,.\s])I\s+(?:like|prefer|usually|always|dislike|want).+"),
+    re.compile(r"(?i)(?:^|[,.\s])my\s+(?:preference|workflow|habit).+\s+is\s+.+"),
+)
+_QUESTION_MARKERS = ("?", "？", "什么", "吗", "么", "why", "what", "how")  # noqa: RUF001
+_EXPERIENCE_MARKERS = ("经验", "lesson")
+_REFERENCE_MARKERS = ("参考资料", "这份资料", "以下资料", "reference")
+_SOP_MARKERS = ("sop", "标准操作流程", "操作规程", "执行流程", "工作流程")
+_ALWAYS_PROJECT_MARKERS = ("每次都要记住", "始终适用", "永远适用", "always applies")
+
+
+def is_stable_user_fact(text: str) -> bool:
+    normalized = " ".join(text.strip().split())
+    if not normalized or any(marker in normalized.casefold() for marker in _QUESTION_MARKERS):
+        return False
+    return any(pattern.search(normalized) is not None for pattern in _USER_FACT_PATTERNS)
+
+
+def has_explicit_memory_intent(text: str) -> bool:
+    normalized = text.casefold()
+    return any(
+        marker in normalized
+        for marker in (
+            "记住",
+            "记下来",
+            "记录下来",
+            "以后都",
+            "写入长期记忆",
+            "加入长期记忆",
+            "remember",
+        )
+    )
+
+
+def is_project_fact(text: str) -> bool:
+    normalized = text.casefold()
+    return any(
+        marker in normalized
+        for marker in ("这个项目", "本项目", "仓库", "代码库", "this project", "repository")
+    )
+
+
+def classify_memory_intent(text: str) -> MemoryKind | None:
+    """Classify explicit memory requests before applying stable-fact heuristics."""
+    normalized = " ".join(text.strip().split()).casefold()
+    if has_explicit_memory_intent(normalized):
+        if any(marker in normalized for marker in _EXPERIENCE_MARKERS):
+            return MemoryKind.EXPERIENCE
+        if any(marker in normalized for marker in _SOP_MARKERS):
+            return MemoryKind.SOP
+        if any(marker in normalized for marker in _REFERENCE_MARKERS):
+            return MemoryKind.REFERENCE
+        if is_project_fact(normalized):
+            return MemoryKind.PROJECT_KNOWLEDGE
+        return MemoryKind.USER_PROFILE
+    if is_stable_user_fact(normalized):
+        return MemoryKind.USER_PROFILE
+    return None
+
+
+def explicitly_always_project_fact(text: str) -> bool:
+    normalized = " ".join(text.strip().split()).casefold()
+    return is_project_fact(normalized) and any(
+        marker in normalized for marker in _ALWAYS_PROJECT_MARKERS
+    )
+
+
+def should_assess_experience(
+    *,
+    status: str,
+    changed_files: tuple[str, ...],
+    verification: tuple[str, ...],
+) -> bool:
+    """Require a successful code change before spending a model call on experience extraction."""
+    return status == "completed" and bool(changed_files) and bool(verification)