profile_skills.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361
  1. """Profile-owned skill storage. Called by the Runner, never by model dispatch.
  2. The caller supplies the Profile and provenance. Package paths are relative,
  3. publication is version checked, and host programs from skills are never run.
  4. """
  5. import base64
  6. import contextlib
  7. import hashlib
  8. import json
  9. import os
  10. from pathlib import Path, PurePosixPath
  11. import re
  12. import shutil
  13. import stat
  14. import tempfile
  15. import time
  16. MAX_FILE = 1024 * 1024
  17. MAX_PACKAGE = 4 * MAX_FILE
  18. MAX_FILES = 128
  19. NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,63}\Z")
  20. REVISION = re.compile(r"[a-f0-9]{64}\Z")
  21. EXCLUDED = {"node_modules", "venv", "__pycache__", "site-packages"}
  22. class SkillError(Exception):
  23. def __init__(self, code, message):
  24. self.code = code
  25. super().__init__(message)
  26. def require(condition, code="skill_invalid", message="技能包格式或路径无效"):
  27. if not condition:
  28. raise SkillError(code, message)
  29. def file_path(value):
  30. require(isinstance(value, str) and 0 < len(value) <= 512)
  31. path = PurePosixPath(value)
  32. require(not path.is_absolute() and str(path) == value and "\\" not in value)
  33. require(all(not part.startswith(".") and not re.search(r'[\x00-\x1f\x7f\\:*?"<>|]', part) and part not in EXCLUDED for part in path.parts))
  34. require(not value.lower().endswith((".pem", ".key", ".p12", ".pfx")))
  35. return path
  36. def metadata(content):
  37. import yaml
  38. require(len(content.encode()) <= MAX_FILE)
  39. match = re.match(r"\A\ufeff?---\s*\n(.*?)\n---\s*(?:\n|$)", content, re.S)
  40. require(match is not None, message="SKILL.md 必须包含 YAML 元数据")
  41. try:
  42. meta = yaml.safe_load(match.group(1))
  43. except Exception:
  44. raise SkillError("skill_invalid", "技能元数据无法解析") from None
  45. require(isinstance(meta, dict))
  46. name, description = meta.get("name"), meta.get("description")
  47. require(isinstance(name, str) and NAME.fullmatch(name) is not None, message="技能名必须为小写字母、数字和连字符,最多 64 字符")
  48. require(isinstance(description, str) and 0 < len(description.strip()) <= 1024, message="请提供不超过 1024 字符的技能说明")
  49. return meta
  50. def revision(files):
  51. # Identical to the guest installer; independent of JSON escaping/order.
  52. digest = hashlib.sha256()
  53. for name in sorted(files):
  54. digest.update(name.encode() + b"\0" + hashlib.sha256(files[name]).digest())
  55. return digest.hexdigest()
  56. def decode_package(encoded):
  57. require(isinstance(encoded, dict) and 0 < len(encoded) <= MAX_FILES)
  58. files = {}
  59. for name, data in encoded.items():
  60. file_path(name)
  61. require(isinstance(data, str) and len(data) <= (MAX_FILE * 4 // 3 + 4))
  62. try:
  63. files[name] = base64.b64decode(data, validate=True)
  64. except Exception:
  65. raise SkillError("skill_invalid", "技能文件编码无效") from None
  66. require(len(files[name]) <= MAX_FILE)
  67. require(sum(map(len, files.values())) <= MAX_PACKAGE and "SKILL.md" in files)
  68. try:
  69. meta = metadata(files["SKILL.md"].decode("utf-8"))
  70. except UnicodeError:
  71. raise SkillError("skill_invalid", "SKILL.md 必须使用 UTF-8") from None
  72. return files, meta
  73. def read_package(directory):
  74. require(directory.is_dir() and not directory.is_symlink(), "skill_path_unsafe", "技能目录不能是符号链接")
  75. files = {}
  76. for root, dirs, names in os.walk(directory, followlinks=False):
  77. dirs[:] = sorted(d for d in dirs if not d.startswith(".") and d not in EXCLUDED)
  78. require(not any((Path(root) / d).is_symlink() for d in dirs), "skill_path_unsafe", "技能包不能包含目录链接")
  79. for name in sorted(names):
  80. if name.startswith("."):
  81. continue
  82. path = Path(root) / name
  83. relative = path.relative_to(directory).as_posix()
  84. file_path(relative)
  85. # O_NOFOLLOW prevents a link substitution between scan and open.
  86. fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
  87. with os.fdopen(fd, "rb") as stream:
  88. info = os.fstat(stream.fileno())
  89. require(stat.S_ISREG(info.st_mode) and info.st_size <= MAX_FILE, "skill_path_unsafe", "技能文件必须为限额内的普通文件")
  90. files[relative] = stream.read(MAX_FILE + 1)
  91. require(len(files) <= MAX_FILES and sum(map(len, files.values())) <= MAX_PACKAGE)
  92. require("SKILL.md" in files)
  93. metadata(files["SKILL.md"].decode("utf-8"))
  94. return files
  95. def encode(files):
  96. return {name: base64.b64encode(data).decode() for name, data in files.items()}
  97. def write_json(path, value):
  98. require(not path.is_symlink(), "skill_path_unsafe", "技能记录不能重定向")
  99. fd, temporary = tempfile.mkstemp(prefix=".record-", dir=path.parent)
  100. try:
  101. with os.fdopen(fd, "w", encoding="utf-8") as stream:
  102. json.dump(value, stream, ensure_ascii=False)
  103. stream.flush()
  104. os.fsync(stream.fileno())
  105. os.replace(temporary, path)
  106. finally:
  107. Path(temporary).unlink(missing_ok=True)
  108. def safe_directory(path):
  109. # Profile root was canonicalized by the configuration reader. Reject all
  110. # redirects below it, including the internal journal/history directories.
  111. require(not path.is_symlink(), "skill_path_unsafe", "技能存储目录不能重定向")
  112. path.mkdir(exist_ok=True, mode=0o700)
  113. require(path.is_dir())
  114. return path
  115. @contextlib.contextmanager
  116. def locked(path):
  117. fd = os.open(path, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
  118. with os.fdopen(fd, "r+b") as stream:
  119. if os.name == "nt":
  120. import msvcrt
  121. stream.write(b"\0"); stream.flush(); stream.seek(0)
  122. msvcrt.locking(stream.fileno(), msvcrt.LK_LOCK, 1)
  123. else:
  124. import fcntl
  125. fcntl.flock(stream, fcntl.LOCK_EX)
  126. try:
  127. yield
  128. finally:
  129. if os.name == "nt":
  130. stream.seek(0); msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
  131. else:
  132. fcntl.flock(stream, fcntl.LOCK_UN)
  133. class ProfileSkills:
  134. def __init__(self, home, config, provenance, authorize=lambda: None):
  135. self.home = Path(home).resolve()
  136. self.config = config
  137. self.provenance = provenance
  138. self.authorize = authorize
  139. self.local = self.home / "skills"
  140. self.state = self.home / ".yaoyao-skills"
  141. def roots(self):
  142. roots = [self.local]
  143. configured = self.config.get("skills", {}).get("external_dirs", [])
  144. if isinstance(configured, str):
  145. configured = [configured]
  146. for value in configured if isinstance(configured, list) else []:
  147. if isinstance(value, str):
  148. path = Path(os.path.expandvars(os.path.expanduser(value)))
  149. roots.append((self.home / path).resolve())
  150. return list(dict.fromkeys(roots))
  151. def entries(self, include_disabled=False):
  152. disabled = self.config.get("skills", {}).get("disabled", [])
  153. seen = set()
  154. for source in self.roots():
  155. if not source.is_dir() or source.is_symlink():
  156. continue
  157. for root, dirs, names in os.walk(source, followlinks=False):
  158. dirs[:] = sorted(d for d in dirs if not d.startswith((".", "_")) and d not in EXCLUDED and not (Path(root) / d).is_symlink())
  159. if "SKILL.md" not in names:
  160. continue
  161. dirs[:] = [] # Supporting resources are not standalone skills.
  162. skill = Path(root)
  163. try:
  164. require(not (skill / "SKILL.md").is_symlink())
  165. require((skill / "SKILL.md").stat().st_size <= MAX_FILE)
  166. meta = metadata((skill / "SKILL.md").read_text(encoding="utf-8"))
  167. name = meta["name"]
  168. if name in seen:
  169. continue
  170. seen.add(name)
  171. if not include_disabled and name in disabled:
  172. continue
  173. yield name, skill, meta
  174. except (SkillError, OSError, UnicodeError):
  175. continue
  176. def find(self, name, include_disabled=False):
  177. require(isinstance(name, str) and NAME.fullmatch(name) is not None)
  178. return next((entry for entry in self.entries(include_disabled) if entry[0] == name), None)
  179. def summary(self, entry):
  180. name, path, meta = entry
  181. extra = meta.get("metadata", {})
  182. hermes = extra.get("hermes", {}) if isinstance(extra, dict) else {}
  183. platforms = meta.get("platforms", hermes.get("platforms", []) if isinstance(hermes, dict) else [])
  184. if isinstance(platforms, str):
  185. platforms = [platforms]
  186. if not isinstance(platforms, list):
  187. platforms = []
  188. return {"name": name, "description": meta["description"], "compatibility": str(meta.get("compatibility", ""))[:500],
  189. "platforms": platforms, "linuxCompatible": not platforms or "linux" in platforms,
  190. "managed": path == self.local / "bot-learned" / name}
  191. def bundle(self, name):
  192. entry = self.find(name)
  193. require(entry is not None, "skill_missing", "当前 Profile 没有启用此技能")
  194. files = read_package(entry[1])
  195. return {**self.summary(entry), "revision": revision(files), "files": encode(files)}
  196. def recover(self, name):
  197. target = self.local / "bot-learned" / name
  198. backup = self.state / (name + ".previous")
  199. pending = self.state / (name + ".pending.json")
  200. require(not pending.is_symlink() and not target.is_symlink() and not backup.is_symlink(), "skill_path_unsafe", "技能事务路径被修改")
  201. if pending.exists():
  202. transaction = json.loads(pending.read_text())
  203. if target.exists() and revision(read_package(target)) == transaction["revision"]:
  204. history = safe_directory(self.state / name)
  205. write_json(history / "history.json", transaction["records"])
  206. pending.unlink()
  207. if backup.exists():
  208. require(not backup.is_symlink() and not target.is_symlink(), "skill_path_unsafe", "技能事务路径被修改")
  209. if not target.exists():
  210. os.replace(backup, target)
  211. else:
  212. shutil.rmtree(backup)
  213. def publish(self, name, encoded, expected, validation, restore=None):
  214. require(isinstance(name, str) and NAME.fullmatch(name) is not None)
  215. require(expected is None or isinstance(expected, str) and REVISION.fullmatch(expected) is not None)
  216. require(isinstance(validation, str) and 1 <= len(validation.strip()) <= 4000, message="发布时必须说明验证方式与结果")
  217. approval = self.config.get("skills", {}).get("write_approval", False)
  218. require(str(approval).lower() not in ("true", "on", "yes", "1", "approve", "enabled"), "skill_write_disabled", "此 Profile 要求技能写入审核,请在本机 Profile 中发布")
  219. safe_directory(self.local); safe_directory(self.local / "bot-learned"); safe_directory(self.state)
  220. with locked(self.state / "publish.lock"):
  221. self.recover(name)
  222. existing = self.find(name, True)
  223. target = self.local / "bot-learned" / name
  224. require(existing is None or existing[1] == target, "skill_not_managed", "同名技能由用户或外部来源维护,请使用新名称")
  225. require(not target.is_symlink(), "skill_path_unsafe", "技能目标不能为链接")
  226. # Never adopt a pre-existing directory without our provenance.
  227. history = safe_directory(self.state / name)
  228. journal = history / "history.json"
  229. require(not journal.is_symlink())
  230. records = json.loads(journal.read_text()) if journal.exists() else []
  231. require(not target.exists() or bool(records), "skill_not_managed", "此技能没有 Bot 发布记录,不能自动接管")
  232. require(not records or records[-1].get("ownerKey") == self.provenance.get("ownerKey"), "skill_not_managed", "此技能由其他账号维护")
  233. before = read_package(target) if target.exists() else None
  234. current = revision(before) if before else None
  235. require(current == expected, "skill_revision_conflict", "技能已被更新,请重新读取后合并")
  236. if restore:
  237. require(REVISION.fullmatch(restore) is not None and any(item["revision"] == restore for item in records), "skill_revision_missing", "未找到可回退版本")
  238. snapshot = history / (restore + ".json")
  239. require(not snapshot.is_symlink())
  240. encoded = json.loads(snapshot.read_text())
  241. files, meta = decode_package(encoded)
  242. require(not restore or revision(files) == restore, "skill_revision_invalid", "历史版本校验失败")
  243. require(meta["name"] == name, message="技能名与 SKILL.md 不一致")
  244. # Keep it discoverable by a macOS Profile. The execution contract is
  245. # a requirement on the tool target, not on the host OS of the model.
  246. if not restore:
  247. import yaml
  248. meta.pop("platforms", None)
  249. if isinstance(meta.get("metadata"), dict) and isinstance(meta["metadata"].get("hermes"), dict):
  250. meta["metadata"]["hermes"].pop("platforms", None)
  251. meta["compatibility"] = "Requires an assigned Linux virtual machine and computer_shell; dependencies must be installed inside that VM."
  252. content = files["SKILL.md"].decode("utf-8")
  253. body = re.sub(r"\A\ufeff?---\s*\n.*?\n---\s*(?:\n|$)", "", content, count=1, flags=re.S)
  254. note = "本技能在隔离 Linux 电脑执行。使用 computer_skill_view 获取虚拟机路径,通过 computer_shell 执行脚本;请勿在宿主机直接运行。输出和依赖安装在虚拟机工作目录。\n\n"
  255. if not body.startswith(note):
  256. body = note + body
  257. files["SKILL.md"] = ("---\n" + yaml.safe_dump(meta, allow_unicode=True, sort_keys=False) + "---\n" + body).encode()
  258. require(len(files["SKILL.md"]) <= MAX_FILE and sum(map(len, files.values())) <= MAX_PACKAGE)
  259. new_revision = revision(files)
  260. if new_revision == current:
  261. return {"name": name, "revision": current, "unchanged": True}
  262. stage = Path(tempfile.mkdtemp(prefix=".publish-", dir=self.local / "bot-learned"))
  263. try:
  264. for relative, data in files.items():
  265. path = stage / relative
  266. path.parent.mkdir(parents=True, exist_ok=True)
  267. path.write_bytes(data)
  268. path.chmod(0o644)
  269. stage.chmod(0o755)
  270. if str(self.config.get("skills", {}).get("guard_agent_created", False)).lower() in ("true", "yes", "on", "1"):
  271. try:
  272. from tools.skills_guard import scan_skill, should_allow_install
  273. allowed, _ = should_allow_install(scan_skill(stage, source="agent-created"))
  274. except Exception:
  275. raise SkillError("skill_scan_unavailable", "Profile 要求技能扫描,但扫描未能完成") from None
  276. require(allowed is True, "skill_scan_blocked", "Profile 的技能扫描未通过,请检查草稿")
  277. self.authorize() # Recheck after staging/scanning, before commit.
  278. latest = revision(read_package(target)) if target.exists() else None
  279. require(latest == current, "skill_revision_conflict", "技能在发布前被修改,请重新读取后合并")
  280. for version, package in [(current, before), (new_revision, files)]:
  281. if version:
  282. snapshot = history / (version + ".json")
  283. require(not snapshot.is_symlink())
  284. if not snapshot.exists():
  285. write_json(snapshot, encode(package))
  286. records.append({"revision": new_revision, "previous": current, "at": int(time.time() * 1000),
  287. "validation": validation, "restoredFrom": restore, **self.provenance})
  288. pending = self.state / (name + ".pending.json")
  289. write_json(pending, {"revision": new_revision, "records": records})
  290. # Keep the preceding package for recovery if the process dies
  291. # between the two renames. Readers never see partial files.
  292. if target.exists():
  293. os.replace(target, self.state / (name + ".previous"))
  294. os.replace(stage, target)
  295. self.recover(name)
  296. for cache in (self.home / ".skills_prompt_snapshot.json",):
  297. cache.unlink(missing_ok=True)
  298. finally:
  299. if stage.exists():
  300. shutil.rmtree(stage)
  301. return {"name": name, "revision": new_revision, "previous": current, "published": True, "profileAvailable": True}
  302. def call(self, action, args):
  303. if self.state.exists():
  304. require(not self.state.is_symlink() and not self.local.is_symlink() and not (self.local / "bot-learned").is_symlink(), "skill_path_unsafe", "技能存储目录不能重定向")
  305. pending_names = {path.name.removesuffix(".pending.json") for path in self.state.glob("*.pending.json")}
  306. pending_names.update(path.name.removesuffix(".previous") for path in self.state.glob("*.previous"))
  307. if pending_names:
  308. with locked(self.state / "publish.lock"):
  309. for name in pending_names:
  310. require(NAME.fullmatch(name) is not None)
  311. self.recover(name)
  312. if action == "list":
  313. values = [self.summary(entry) for entry in self.entries()]
  314. return {"skills": values[:1000], "truncated": len(values) > 1000}
  315. if action == "view":
  316. return self.bundle(args["name"])
  317. if action == "publish":
  318. return self.publish(args["name"], args["files"], args.get("expectedRevision"), args["validation"])
  319. if action == "restore":
  320. return self.publish(args["name"], None, args["expectedRevision"], args["validation"], args["revision"])
  321. if action == "history":
  322. entry = self.find(args["name"])
  323. require(entry is not None and entry[1] == self.local / "bot-learned" / args["name"], "skill_not_managed", "此技能没有 Bot 发布历史")
  324. path = self.state / args["name"] / "history.json"
  325. require(not path.is_symlink())
  326. return {"name": args["name"], "history": json.loads(path.read_text())[-50:]}
  327. raise SkillError("skill_invalid", "未知技能操作")