"""Skill use cases, transaction boundaries and version/approval invariants.""" import re import uuid from typing import Callable from pydantic import ValidationError from src.modules.skill.atomic_registry.catalog import builtin_operations, check_handler from src.modules.skill.domain.models import Actor, Draft, Framework, Issue, Operation, SkillError, digest from src.modules.skill.graph.compiler import compile_graph from src.modules.skill.ports.repository import SkillRepository class SkillService: def __init__(self, repository: SkillRepository, knowledge_resolver: Callable, project_access: Callable | None = None): self.repository = repository self.knowledge_resolver = knowledge_resolver self.project_access = project_access or self._no_project_adapter @staticmethod def _no_project_adapter(actor, project_id): raise SkillError("PROJECT_ADAPTER_REQUIRED", "项目权限适配器未接入。", 503) @staticmethod def require(actor, roles): if not set(actor.roles).intersection(roles): raise SkillError("ROLE_REQUIRED", "当前角色无此管理权限。", 403) @staticmethod def need(tx, actor, kind, key): doc = tx.get(actor.tenant_id, kind, key) if doc is None: raise SkillError("NOT_FOUND", "对象不存在或不可见。", 404) return doc def scope(self, actor, body): project_id = body.get("project_id") if project_id: self.project_access(actor, project_id) def bootstrap(self, actor: Actor): """Install only platform-owned contracts; does not approve Skill/framework/corpus.""" self.require(actor, {"admin"}) with self.repository.transaction(write=True) as tx: for operation in builtin_operations(): key = operation.operation_id + "@" + operation.version if tx.get(actor.tenant_id, "operation", key) is None: tx.create(actor.tenant_id, "operation", key, operation.model_dump(mode="json")) tx.audit(actor.tenant_id, actor.user_id, "catalog.bootstrap", "atomic-operations", digest([o.model_dump(mode="json") for o in builtin_operations()])) def catalog(self, actor, kind): if kind not in {"operation", "framework"}: raise SkillError("INVALID_CATALOG", "未知目录。") with self.repository.transaction() as tx: return tx.listing(actor.tenant_id, kind) def add_operation(self, actor, operation: Operation): self.require(actor, {"admin", "skill_manager"}) check_handler(operation) key = operation.operation_id + "@" + operation.version with self.repository.transaction(write=True) as tx: result = tx.create(actor.tenant_id, "operation", key, operation.model_dump(mode="json")) tx.audit(actor.tenant_id, actor.user_id, "operation.version.create", key, result["digest"]) return result def add_framework(self, actor, framework: Framework): self.require(actor, {"admin", "skill_manager"}) if framework.state == "approved" and not framework.evidence_refs: raise SkillError("FRAMEWORK_EVIDENCE_REQUIRED", "批准框架需要工具链/契约证据引用。") if any(not re.fullmatch(r"[0-9][A-Za-z0-9._-]*", v) or "snapshot" in v.lower() for v in framework.dependencies.values()): raise SkillError("UNPINNED_DEPENDENCY", "依赖必须锁定具体版本。") key = framework.profile_id + "@" + framework.version with self.repository.transaction(write=True) as tx: result = tx.create(actor.tenant_id, "framework", key, framework.model_dump(mode="json")) tx.audit(actor.tenant_id, actor.user_id, "framework.version.create", key, result["digest"]) return result def save_draft(self, actor, draft: Draft, expected_revision=None): self.require(actor, {"admin", "skill_manager"}) self.scope(actor, draft.model_dump()) with self.repository.transaction(write=True) as tx: old = tx.get(actor.tenant_id, "draft", draft.skill_id) body = draft.model_dump(mode="json") body["owner_id"] = old["body"]["owner_id"] if old else actor.user_id body["last_editor_id"] = actor.user_id if old: if expected_revision is None: raise SkillError("REVISION_REQUIRED", "保存已有草稿必须带expected_revision。", 409) # Check the previous project too; a caller cannot move an inaccessible draft out of it. self.scope(actor, old["body"]) result = tx.update(actor.tenant_id, "draft", draft.skill_id, body, expected_revision) else: if expected_revision is not None: raise SkillError("REVISION_CONFLICT", "草稿尚不存在。", 409) result = tx.create(actor.tenant_id, "draft", draft.skill_id, body) tx.audit(actor.tenant_id, actor.user_id, "skill.draft.save", draft.skill_id, result["digest"]) return result def read_draft(self, actor, skill_id): self.require(actor, {"admin", "skill_manager", "reviewer"}) with self.repository.transaction() as tx: result = self.need(tx, actor, "draft", skill_id) self.scope(actor, result["body"]) return result def drafts(self, actor): self.require(actor, {"admin", "skill_manager", "reviewer"}) with self.repository.transaction() as tx: result = [] for item in tx.listing(actor.tenant_id, "draft"): try: self.scope(actor, item["body"]) except SkillError as exc: if exc.status in {403, 404}: continue raise result.append(item) return result def _validate(self, tx, actor, doc): self.scope(actor, doc["body"]) data = {k: v for k, v in doc["body"].items() if k not in {"owner_id", "last_editor_id"}} draft = Draft.model_validate(data) operations = {item["key"]: Operation.model_validate(item["body"]) for item in tx.listing(actor.tenant_id, "operation") if not tx.get(actor.tenant_id, "retirement", "operation:" + item["key"])} framework_doc = tx.get(actor.tenant_id, "framework", draft.framework_ref) framework = Framework.model_validate(framework_doc["body"]) if framework_doc and not tx.get(actor.tenant_id, "retirement", "framework:" + draft.framework_ref) else None report = compile_graph(draft, operations, framework) knowledge = [] for binding in draft.knowledge_bindings: try: knowledge.append(self.knowledge_resolver(actor, binding)) except SkillError as exc: # Never reveal names/body of an invisible source in the report. report.issues.append(Issue(code=exc.code, location="knowledge_bindings." + binding.name, message="知识引用不可用、版本不符或权限不足。")) report.valid = not report.issues report.digest = digest({"compiled": report.digest, "knowledge": knowledge}) return draft, report, knowledge, operations, framework def validate(self, actor, skill_id): self.require(actor, {"admin", "skill_manager", "reviewer"}) with self.repository.transaction() as tx: return self._validate(tx, actor, self.need(tx, actor, "draft", skill_id))[1] def approve(self, actor, skill_id, expected_revision, expected_digest, evidence_refs): self.require(actor, {"admin", "reviewer"}) if not evidence_refs or any(not x.strip() or len(x) > 300 for x in evidence_refs): raise SkillError("REVIEW_EVIDENCE_REQUIRED", "评审必须引用具体评审/测试证据。") with self.repository.transaction(write=True) as tx: doc = self.need(tx, actor, "draft", skill_id) if doc["body"]["last_editor_id"] == actor.user_id: raise SkillError("INDEPENDENT_REVIEW_REQUIRED", "草稿作者不能自行批准发布。", 403) _, report, _, _, _ = self._validate(tx, actor, doc) if not report.valid: raise SkillError("GRAPH_INVALID", "静态校验未通过。", details={"issues": [x.model_dump() for x in report.issues]}) if doc["revision"] != expected_revision or report.digest != expected_digest: raise SkillError("APPROVAL_TARGET_CHANGED", "评审目标或依赖已经变化。", 409) body = {"skill_id": skill_id, "draft_revision": doc["revision"], "compiled_digest": report.digest, "reviewer_id": actor.user_id, "evidence_refs": evidence_refs} key = "approval-" + uuid.uuid4().hex result = tx.create(actor.tenant_id, "approval", key, body) tx.audit(actor.tenant_id, actor.user_id, "skill.review.approve", skill_id, report.digest) return result def publish(self, actor, skill_id, version, expected_revision, approval_id): self.require(actor, {"admin", "skill_manager"}) if not re.fullmatch(r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)", version): raise SkillError("INVALID_VERSION", "发布版本必须为精确语义版本。") with self.repository.transaction(write=True) as tx: doc = self.need(tx, actor, "draft", skill_id) draft, report, knowledge, operations, framework = self._validate(tx, actor, doc) if not report.valid: raise SkillError("GRAPH_INVALID", "静态校验未通过。", details={"issues": [x.model_dump() for x in report.issues]}) approval = self.need(tx, actor, "approval", approval_id)["body"] if doc["revision"] != expected_revision or approval["skill_id"] != skill_id or approval["draft_revision"] != doc["revision"] or approval["compiled_digest"] != report.digest: raise SkillError("APPROVAL_TARGET_CHANGED", "变更后必须重新评审,旧批准不能重用。", 409) body = {"skill_id": skill_id, "version": version, "project_id": draft.project_id, "draft": draft.model_dump(mode="json"), "compiled_digest": report.digest, "execution_order": report.execution_order, "operations_lock": report.operation_locks, "operations": {ref: operations[ref].model_dump(mode="json") for ref in report.operation_locks}, "framework": framework.model_dump(mode="json"), "knowledge": knowledge, "approval_id": approval_id, "review_evidence": approval["evidence_refs"], "publication_scope": "capability-definition", "runtime_verification": "not_executed_by_skill_registry"} key = skill_id + "@" + version result = tx.create(actor.tenant_id, "release", key, body) tx.audit(actor.tenant_id, actor.user_id, "skill.release.publish", key, result["digest"]) return result def retire(self, actor, kind, key, reason): self.require(actor, {"admin", "skill_manager"}) if kind not in {"operation", "framework", "release"}: raise SkillError("INVALID_KIND", "不支持该版本类型。") with self.repository.transaction(write=True) as tx: obj = self.need(tx, actor, kind, key) self.scope(actor, obj["body"]) result = tx.create(actor.tenant_id, "retirement", kind + ":" + key, {"reason": reason, "actor": actor.user_id}) tx.audit(actor.tenant_id, actor.user_id, kind + ".retire", key, obj["digest"]) return result def stage_local_validation(self, actor, skill_id, authorization_ref, *, validation_owner=None, expected_revision=None): """Server-only experimental snapshot; not a published capability release.""" self.require(actor, {'admin'}) if not authorization_ref or len(authorization_ref) > 300: raise SkillError('AUTHORIZATION_REFERENCE_REQUIRED', '本地验证需要明确授权引用。') with self.repository.transaction(write=True) as tx: doc = self.need(tx, actor, 'draft', skill_id) if expected_revision is not None and doc['revision'] != expected_revision: raise SkillError('REVISION_CONFLICT','工作流已被修改,请刷新后重试。',409) draft, report, knowledge, operations, framework = self._validate(tx, actor, doc) if not report.valid: raise SkillError('GRAPH_INVALID', '本地验证图校验失败。', details={'issues': [x.model_dump() for x in report.issues]}) if not draft.project_id: raise SkillError('VALIDATION_PROJECT_REQUIRED', '本地验证版本必须绑定一个明确项目。') body = {'skill_id': skill_id, 'version': 'local-validation', 'project_id': draft.project_id, 'draft_revision':doc['revision'],'draft_digest':doc['digest'], 'draft': draft.model_dump(mode='json'), 'compiled_digest': report.digest, 'execution_order': report.execution_order, 'operations_lock': report.operation_locks, 'operations': {ref: operations[ref].model_dump(mode='json') for ref in report.operation_locks}, 'framework': framework.model_dump(mode='json'), 'knowledge': knowledge, 'approval_id': None, 'review_evidence': [], 'authorization_ref': authorization_ref, 'publication_scope': 'local-validation-only', 'human_review': False, 'validation_owner': validation_owner or actor.user_id} key = skill_id + '@local-' + digest(body)[:16] existing = tx.get(actor.tenant_id, 'release', key) if existing: return existing result = tx.create(actor.tenant_id, 'release', key, body) tx.audit(actor.tenant_id, actor.user_id, 'skill.local-validation.stage', key, result['digest']) return result def releases(self, actor, project_id=None): if project_id: self.project_access(actor, project_id) with self.repository.transaction() as tx: return [item for item in tx.listing(actor.tenant_id, "release") if item['body'].get('publication_scope') != 'local-validation-only' and not tx.get(actor.tenant_id, "retirement", "release:" + item["key"]) and item["body"].get("project_id") in {None, project_id}] def prepare(self, actor, release_ref, project_id, source_digest, idempotency_key, *, inspect_only=False): if not re.fullmatch(r"[a-f0-9]{64}", source_digest) or not 8 <= len(idempotency_key) <= 128: raise SkillError("INVALID_SNAPSHOT_INPUT", "源码摘要或幂等键格式不符。") self.project_access(actor, project_id) with self.repository.transaction(write=True) as tx: release = self.need(tx, actor, "release", release_ref) body = release["body"] if (body.get('publication_scope') == 'local-validation-only' and body.get('validation_owner') != actor.user_id and not (inspect_only and set(actor.roles).intersection({'admin', 'reviewer'}))): raise SkillError('NOT_FOUND', '本地验证版本不对其他用户发布。', 404) self.scope(actor, body) if body.get("project_id") not in {None, project_id}: raise SkillError("NOT_FOUND", "版本不在当前项目范围。", 404) checks = [("release", release_ref), ("framework", body["draft"]["framework_ref"])] + [("operation", ref) for ref in body["operations_lock"]] if any(tx.get(actor.tenant_id, "retirement", kind + ":" + key) for kind, key in checks): raise SkillError("DEPENDENCY_RETIRED", "版本或依赖停用,不能开始新任务。", 409) knowledge = [self.knowledge_resolver(actor, binding) for binding in Draft.model_validate(body["draft"]).knowledge_bindings] if knowledge != body["knowledge"]: raise SkillError("KNOWLEDGE_CHANGED", "知识版本或权限发生变化,需重新检查。", 409) request_digest = digest({"release": release_ref, "project": project_id, "source": source_digest}) request_key = digest({"user": actor.user_id, "idempotency_key": idempotency_key}) previous = tx.get(actor.tenant_id, "prepared-request", request_key) if previous: if previous["body"]["request_digest"] != request_digest: raise SkillError("IDEMPOTENCY_CONFLICT", "同一幂等键不能用于不同源码或版本。", 409) return previous["body"]["snapshot"] snapshot = {"snapshot_id": "snapshot-" + uuid.uuid4().hex, "tenant_id": actor.tenant_id, "user_id": actor.user_id, "project_id": project_id, "release_ref": release_ref, "release_digest": release["digest"], "source_digest": source_digest, "knowledge": knowledge, "framework": body["framework"], "operations_lock": body["operations_lock"], "execution_order": body["execution_order"], "budget": body["draft"]["budget"], "execution_status": "not_started"} if body['draft'].get('instructions'): snapshot['skill_instructions'] = body['draft']['instructions'] snapshot = dict(snapshot, snapshot_digest=digest(snapshot)) tx.create(actor.tenant_id, "snapshot", snapshot["snapshot_id"], snapshot) tx.create(actor.tenant_id, "prepared-request", request_key, {"request_digest": request_digest, "snapshot": snapshot}) tx.audit(actor.tenant_id, actor.user_id, "skill.snapshot.prepare", release_ref, snapshot["snapshot_digest"]) return snapshot