| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361 |
- """Profile-owned skill storage. Called by the Runner, never by model dispatch.
- The caller supplies the Profile and provenance. Package paths are relative,
- publication is version checked, and host programs from skills are never run.
- """
- import base64
- import contextlib
- import hashlib
- import json
- import os
- from pathlib import Path, PurePosixPath
- import re
- import shutil
- import stat
- import tempfile
- import time
- MAX_FILE = 1024 * 1024
- MAX_PACKAGE = 4 * MAX_FILE
- MAX_FILES = 128
- NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,63}\Z")
- REVISION = re.compile(r"[a-f0-9]{64}\Z")
- EXCLUDED = {"node_modules", "venv", "__pycache__", "site-packages"}
- class SkillError(Exception):
- def __init__(self, code, message):
- self.code = code
- super().__init__(message)
- def require(condition, code="skill_invalid", message="技能包格式或路径无效"):
- if not condition:
- raise SkillError(code, message)
- def file_path(value):
- require(isinstance(value, str) and 0 < len(value) <= 512)
- path = PurePosixPath(value)
- require(not path.is_absolute() and str(path) == value and "\\" not in value)
- require(all(not part.startswith(".") and not re.search(r'[\x00-\x1f\x7f\\:*?"<>|]', part) and part not in EXCLUDED for part in path.parts))
- require(not value.lower().endswith((".pem", ".key", ".p12", ".pfx")))
- return path
- def metadata(content):
- import yaml
- require(len(content.encode()) <= MAX_FILE)
- match = re.match(r"\A\ufeff?---\s*\n(.*?)\n---\s*(?:\n|$)", content, re.S)
- require(match is not None, message="SKILL.md 必须包含 YAML 元数据")
- try:
- meta = yaml.safe_load(match.group(1))
- except Exception:
- raise SkillError("skill_invalid", "技能元数据无法解析") from None
- require(isinstance(meta, dict))
- name, description = meta.get("name"), meta.get("description")
- require(isinstance(name, str) and NAME.fullmatch(name) is not None, message="技能名必须为小写字母、数字和连字符,最多 64 字符")
- require(isinstance(description, str) and 0 < len(description.strip()) <= 1024, message="请提供不超过 1024 字符的技能说明")
- return meta
- def revision(files):
- # Identical to the guest installer; independent of JSON escaping/order.
- digest = hashlib.sha256()
- for name in sorted(files):
- digest.update(name.encode() + b"\0" + hashlib.sha256(files[name]).digest())
- return digest.hexdigest()
- def decode_package(encoded):
- require(isinstance(encoded, dict) and 0 < len(encoded) <= MAX_FILES)
- files = {}
- for name, data in encoded.items():
- file_path(name)
- require(isinstance(data, str) and len(data) <= (MAX_FILE * 4 // 3 + 4))
- try:
- files[name] = base64.b64decode(data, validate=True)
- except Exception:
- raise SkillError("skill_invalid", "技能文件编码无效") from None
- require(len(files[name]) <= MAX_FILE)
- require(sum(map(len, files.values())) <= MAX_PACKAGE and "SKILL.md" in files)
- try:
- meta = metadata(files["SKILL.md"].decode("utf-8"))
- except UnicodeError:
- raise SkillError("skill_invalid", "SKILL.md 必须使用 UTF-8") from None
- return files, meta
- def read_package(directory):
- require(directory.is_dir() and not directory.is_symlink(), "skill_path_unsafe", "技能目录不能是符号链接")
- files = {}
- for root, dirs, names in os.walk(directory, followlinks=False):
- dirs[:] = sorted(d for d in dirs if not d.startswith(".") and d not in EXCLUDED)
- require(not any((Path(root) / d).is_symlink() for d in dirs), "skill_path_unsafe", "技能包不能包含目录链接")
- for name in sorted(names):
- if name.startswith("."):
- continue
- path = Path(root) / name
- relative = path.relative_to(directory).as_posix()
- file_path(relative)
- # O_NOFOLLOW prevents a link substitution between scan and open.
- fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
- with os.fdopen(fd, "rb") as stream:
- info = os.fstat(stream.fileno())
- require(stat.S_ISREG(info.st_mode) and info.st_size <= MAX_FILE, "skill_path_unsafe", "技能文件必须为限额内的普通文件")
- files[relative] = stream.read(MAX_FILE + 1)
- require(len(files) <= MAX_FILES and sum(map(len, files.values())) <= MAX_PACKAGE)
- require("SKILL.md" in files)
- metadata(files["SKILL.md"].decode("utf-8"))
- return files
- def encode(files):
- return {name: base64.b64encode(data).decode() for name, data in files.items()}
- def write_json(path, value):
- require(not path.is_symlink(), "skill_path_unsafe", "技能记录不能重定向")
- fd, temporary = tempfile.mkstemp(prefix=".record-", dir=path.parent)
- try:
- with os.fdopen(fd, "w", encoding="utf-8") as stream:
- json.dump(value, stream, ensure_ascii=False)
- stream.flush()
- os.fsync(stream.fileno())
- os.replace(temporary, path)
- finally:
- Path(temporary).unlink(missing_ok=True)
- def safe_directory(path):
- # Profile root was canonicalized by the configuration reader. Reject all
- # redirects below it, including the internal journal/history directories.
- require(not path.is_symlink(), "skill_path_unsafe", "技能存储目录不能重定向")
- path.mkdir(exist_ok=True, mode=0o700)
- require(path.is_dir())
- return path
- @contextlib.contextmanager
- def locked(path):
- fd = os.open(path, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
- with os.fdopen(fd, "r+b") as stream:
- if os.name == "nt":
- import msvcrt
- stream.write(b"\0"); stream.flush(); stream.seek(0)
- msvcrt.locking(stream.fileno(), msvcrt.LK_LOCK, 1)
- else:
- import fcntl
- fcntl.flock(stream, fcntl.LOCK_EX)
- try:
- yield
- finally:
- if os.name == "nt":
- stream.seek(0); msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
- else:
- fcntl.flock(stream, fcntl.LOCK_UN)
- class ProfileSkills:
- def __init__(self, home, config, provenance, authorize=lambda: None):
- self.home = Path(home).resolve()
- self.config = config
- self.provenance = provenance
- self.authorize = authorize
- self.local = self.home / "skills"
- self.state = self.home / ".yaoyao-skills"
- def roots(self):
- roots = [self.local]
- configured = self.config.get("skills", {}).get("external_dirs", [])
- if isinstance(configured, str):
- configured = [configured]
- for value in configured if isinstance(configured, list) else []:
- if isinstance(value, str):
- path = Path(os.path.expandvars(os.path.expanduser(value)))
- roots.append((self.home / path).resolve())
- return list(dict.fromkeys(roots))
- def entries(self, include_disabled=False):
- disabled = self.config.get("skills", {}).get("disabled", [])
- seen = set()
- for source in self.roots():
- if not source.is_dir() or source.is_symlink():
- continue
- for root, dirs, names in os.walk(source, followlinks=False):
- dirs[:] = sorted(d for d in dirs if not d.startswith((".", "_")) and d not in EXCLUDED and not (Path(root) / d).is_symlink())
- if "SKILL.md" not in names:
- continue
- dirs[:] = [] # Supporting resources are not standalone skills.
- skill = Path(root)
- try:
- require(not (skill / "SKILL.md").is_symlink())
- require((skill / "SKILL.md").stat().st_size <= MAX_FILE)
- meta = metadata((skill / "SKILL.md").read_text(encoding="utf-8"))
- name = meta["name"]
- if name in seen:
- continue
- seen.add(name)
- if not include_disabled and name in disabled:
- continue
- yield name, skill, meta
- except (SkillError, OSError, UnicodeError):
- continue
- def find(self, name, include_disabled=False):
- require(isinstance(name, str) and NAME.fullmatch(name) is not None)
- return next((entry for entry in self.entries(include_disabled) if entry[0] == name), None)
- def summary(self, entry):
- name, path, meta = entry
- extra = meta.get("metadata", {})
- hermes = extra.get("hermes", {}) if isinstance(extra, dict) else {}
- platforms = meta.get("platforms", hermes.get("platforms", []) if isinstance(hermes, dict) else [])
- if isinstance(platforms, str):
- platforms = [platforms]
- if not isinstance(platforms, list):
- platforms = []
- return {"name": name, "description": meta["description"], "compatibility": str(meta.get("compatibility", ""))[:500],
- "platforms": platforms, "linuxCompatible": not platforms or "linux" in platforms,
- "managed": path == self.local / "bot-learned" / name}
- def bundle(self, name):
- entry = self.find(name)
- require(entry is not None, "skill_missing", "当前 Profile 没有启用此技能")
- files = read_package(entry[1])
- return {**self.summary(entry), "revision": revision(files), "files": encode(files)}
- def recover(self, name):
- target = self.local / "bot-learned" / name
- backup = self.state / (name + ".previous")
- pending = self.state / (name + ".pending.json")
- require(not pending.is_symlink() and not target.is_symlink() and not backup.is_symlink(), "skill_path_unsafe", "技能事务路径被修改")
- if pending.exists():
- transaction = json.loads(pending.read_text())
- if target.exists() and revision(read_package(target)) == transaction["revision"]:
- history = safe_directory(self.state / name)
- write_json(history / "history.json", transaction["records"])
- pending.unlink()
- if backup.exists():
- require(not backup.is_symlink() and not target.is_symlink(), "skill_path_unsafe", "技能事务路径被修改")
- if not target.exists():
- os.replace(backup, target)
- else:
- shutil.rmtree(backup)
- def publish(self, name, encoded, expected, validation, restore=None):
- require(isinstance(name, str) and NAME.fullmatch(name) is not None)
- require(expected is None or isinstance(expected, str) and REVISION.fullmatch(expected) is not None)
- require(isinstance(validation, str) and 1 <= len(validation.strip()) <= 4000, message="发布时必须说明验证方式与结果")
- approval = self.config.get("skills", {}).get("write_approval", False)
- require(str(approval).lower() not in ("true", "on", "yes", "1", "approve", "enabled"), "skill_write_disabled", "此 Profile 要求技能写入审核,请在本机 Profile 中发布")
- safe_directory(self.local); safe_directory(self.local / "bot-learned"); safe_directory(self.state)
- with locked(self.state / "publish.lock"):
- self.recover(name)
- existing = self.find(name, True)
- target = self.local / "bot-learned" / name
- require(existing is None or existing[1] == target, "skill_not_managed", "同名技能由用户或外部来源维护,请使用新名称")
- require(not target.is_symlink(), "skill_path_unsafe", "技能目标不能为链接")
- # Never adopt a pre-existing directory without our provenance.
- history = safe_directory(self.state / name)
- journal = history / "history.json"
- require(not journal.is_symlink())
- records = json.loads(journal.read_text()) if journal.exists() else []
- require(not target.exists() or bool(records), "skill_not_managed", "此技能没有 Bot 发布记录,不能自动接管")
- require(not records or records[-1].get("ownerKey") == self.provenance.get("ownerKey"), "skill_not_managed", "此技能由其他账号维护")
- before = read_package(target) if target.exists() else None
- current = revision(before) if before else None
- require(current == expected, "skill_revision_conflict", "技能已被更新,请重新读取后合并")
- if restore:
- require(REVISION.fullmatch(restore) is not None and any(item["revision"] == restore for item in records), "skill_revision_missing", "未找到可回退版本")
- snapshot = history / (restore + ".json")
- require(not snapshot.is_symlink())
- encoded = json.loads(snapshot.read_text())
- files, meta = decode_package(encoded)
- require(not restore or revision(files) == restore, "skill_revision_invalid", "历史版本校验失败")
- require(meta["name"] == name, message="技能名与 SKILL.md 不一致")
- # Keep it discoverable by a macOS Profile. The execution contract is
- # a requirement on the tool target, not on the host OS of the model.
- if not restore:
- import yaml
- meta.pop("platforms", None)
- if isinstance(meta.get("metadata"), dict) and isinstance(meta["metadata"].get("hermes"), dict):
- meta["metadata"]["hermes"].pop("platforms", None)
- meta["compatibility"] = "Requires an assigned Linux virtual machine and computer_shell; dependencies must be installed inside that VM."
- content = files["SKILL.md"].decode("utf-8")
- body = re.sub(r"\A\ufeff?---\s*\n.*?\n---\s*(?:\n|$)", "", content, count=1, flags=re.S)
- note = "本技能在隔离 Linux 电脑执行。使用 computer_skill_view 获取虚拟机路径,通过 computer_shell 执行脚本;请勿在宿主机直接运行。输出和依赖安装在虚拟机工作目录。\n\n"
- if not body.startswith(note):
- body = note + body
- files["SKILL.md"] = ("---\n" + yaml.safe_dump(meta, allow_unicode=True, sort_keys=False) + "---\n" + body).encode()
- require(len(files["SKILL.md"]) <= MAX_FILE and sum(map(len, files.values())) <= MAX_PACKAGE)
- new_revision = revision(files)
- if new_revision == current:
- return {"name": name, "revision": current, "unchanged": True}
- stage = Path(tempfile.mkdtemp(prefix=".publish-", dir=self.local / "bot-learned"))
- try:
- for relative, data in files.items():
- path = stage / relative
- path.parent.mkdir(parents=True, exist_ok=True)
- path.write_bytes(data)
- path.chmod(0o644)
- stage.chmod(0o755)
- if str(self.config.get("skills", {}).get("guard_agent_created", False)).lower() in ("true", "yes", "on", "1"):
- try:
- from tools.skills_guard import scan_skill, should_allow_install
- allowed, _ = should_allow_install(scan_skill(stage, source="agent-created"))
- except Exception:
- raise SkillError("skill_scan_unavailable", "Profile 要求技能扫描,但扫描未能完成") from None
- require(allowed is True, "skill_scan_blocked", "Profile 的技能扫描未通过,请检查草稿")
- self.authorize() # Recheck after staging/scanning, before commit.
- latest = revision(read_package(target)) if target.exists() else None
- require(latest == current, "skill_revision_conflict", "技能在发布前被修改,请重新读取后合并")
- for version, package in [(current, before), (new_revision, files)]:
- if version:
- snapshot = history / (version + ".json")
- require(not snapshot.is_symlink())
- if not snapshot.exists():
- write_json(snapshot, encode(package))
- records.append({"revision": new_revision, "previous": current, "at": int(time.time() * 1000),
- "validation": validation, "restoredFrom": restore, **self.provenance})
- pending = self.state / (name + ".pending.json")
- write_json(pending, {"revision": new_revision, "records": records})
- # Keep the preceding package for recovery if the process dies
- # between the two renames. Readers never see partial files.
- if target.exists():
- os.replace(target, self.state / (name + ".previous"))
- os.replace(stage, target)
- self.recover(name)
- for cache in (self.home / ".skills_prompt_snapshot.json",):
- cache.unlink(missing_ok=True)
- finally:
- if stage.exists():
- shutil.rmtree(stage)
- return {"name": name, "revision": new_revision, "previous": current, "published": True, "profileAvailable": True}
- def call(self, action, args):
- if self.state.exists():
- require(not self.state.is_symlink() and not self.local.is_symlink() and not (self.local / "bot-learned").is_symlink(), "skill_path_unsafe", "技能存储目录不能重定向")
- pending_names = {path.name.removesuffix(".pending.json") for path in self.state.glob("*.pending.json")}
- pending_names.update(path.name.removesuffix(".previous") for path in self.state.glob("*.previous"))
- if pending_names:
- with locked(self.state / "publish.lock"):
- for name in pending_names:
- require(NAME.fullmatch(name) is not None)
- self.recover(name)
- if action == "list":
- values = [self.summary(entry) for entry in self.entries()]
- return {"skills": values[:1000], "truncated": len(values) > 1000}
- if action == "view":
- return self.bundle(args["name"])
- if action == "publish":
- return self.publish(args["name"], args["files"], args.get("expectedRevision"), args["validation"])
- if action == "restore":
- return self.publish(args["name"], None, args["expectedRevision"], args["validation"], args["revision"])
- if action == "history":
- entry = self.find(args["name"])
- require(entry is not None and entry[1] == self.local / "bot-learned" / args["name"], "skill_not_managed", "此技能没有 Bot 发布历史")
- path = self.state / args["name"] / "history.json"
- require(not path.is_symlink())
- return {"name": args["name"], "history": json.loads(path.read_text())[-50:]}
- raise SkillError("skill_invalid", "未知技能操作")
|