workbuddy-market 2.27.0__tar.gz

workbuddy_market-2.27.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zjs105910
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workbuddy_market-2.27.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: workbuddy-market
+Version: 2.27.0
+Summary: Local-first plugin marketplace for WorkBuddy: package local skills, register into WorkBuddy, browse & install from a 127.0.0.1-only web UI
+Author: zjs105910
+License: MIT
+Project-URL: Homepage, https://github.com/zjs105910/workbuddy-market
+Project-URL: Repository, https://github.com/zjs105910/workbuddy-market
+Project-URL: Documentation, https://github.com/zjs105910/workbuddy-market/blob/main/ADVANCED_GUIDE.md
+Project-URL: Issues, https://github.com/zjs105910/workbuddy-market/issues
+Project-URL: Security, https://github.com/zjs105910/workbuddy-market/blob/main/SECURITY.md
+Project-URL: Changelog, https://github.com/zjs105910/workbuddy-market/blob/main/CHANGELOG.md
+Keywords: workbuddy,skill,plugin,marketplace,agent-skills,ai-agents,developer-tools,local-first
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# WorkBuddy Market
+
+**简体中文** · [English](README_EN.md)
+
+[![CI](https://github.com/zjs105910/workbuddy-market/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/zjs105910/workbuddy-market/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**给 WorkBuddy 用的本机优先插件市场。** 将本机 Skills 打包成插件，在精选社区目录或 GitHub 中查找技能；安装前查看来源、权限声明和兼容性，再通过哈希校验与可恢复事务完成安装、更新和卸载。
+
+*A local-first plugin marketplace for WorkBuddy: package local Skills, explore community and GitHub sources, review declared permissions and compatibility, and manage installs through hash verification and recoverable transactions.*
+
+## 30 秒了解它
+
+- **管理自己的 Skills**：将本机技能打包、同步，并注册到 WorkBuddy 插件面板。
+- **发现社区技能**：浏览精选目录，也可以搜索 GitHub 上的公开仓库。
+- **安装过程更可追溯**：安装前有来源与风险预览；支持内容校验、事务恢复和回收站。
+- **本机优先**：网页服务只监听 `127.0.0.1`；你的私有市场配置和本机技能内容不随仓库提交。
+
+## 快速上手（Windows）
+
+要求：Python 3.10+、Git。想先体验网页，不改动 WorkBuddy 配置，推荐从安全模式开始。
+
+```powershell
+git clone https://github.com/zjs105910/workbuddy-market.git
+cd workbuddy-market
+.\安全模式-只开网页.cmd
+```
+
+启动后打开本机地址（默认 `http://127.0.0.1:8777/`）。**请保持启动窗口打开**；结束时回到窗口按 `Ctrl+C`。
+
+已经准备好要接入 WorkBuddy 时，再运行 `一键启动.cmd`。首次初始化的交互向导中，**直接回车是只浏览**；只有明确输入 `2` 才会请求注册到 WorkBuddy。注册前仍会进行打包与自检前置检查。
+
+不会使用命令行？克隆仓库后，也可以在资源管理器中双击 `安全模式-只开网页.cmd`。想了解其他启动参数、插件配置或 CLI，请看[详细使用与技术参考](ADVANCED_GUIDE.md)。
+
+## 看看界面
+
+| 本机技能 | 精选市场 |
+| --- | --- |
+| ![本机技能管理界面](docs/screenshots/home-local.png) | ![精选社区插件界面](docs/screenshots/home-curated.png) |
+
+安装前的来源、权限与兼容性预览：
+
+![安装前详情预览](docs/screenshots/detail-four-questions.png)
+
+> 截图由项目脚本使用合成数据生成。实际可用操作会根据本机环境与插件来源有所不同。
+
+## 产品演示与正式版本
+
+- [可复现演示：录制方法、中文字幕与隐私边界](docs/demo-video.md)
+- [正式 Release 发布流程](docs/release-process.md)
+- [观看当前演示构建（约 80 秒，MP4 + 中文字幕）](https://github.com/zjs105910/workbuddy-market/actions/runs/38121812213)（Actions 附件有效期 30 天）。
+- 正式版本的 MP4、字幕、Python 安装包与 SHA-256 校验文件将在 [GitHub Releases](https://github.com/zjs105910/workbuddy-market/releases) 中一起发布。当前演示构建是临时附件；`registry-artifacts-*` 是社区插件产物，不是市场本体安装包。
+
+## 安装前请知道
+
+- 卸载时会检查插件是否由本市场管理、内容是否被修改；不属于本市场管理的技能不会被随意删除。回收站与事务恢复用于降低误操作影响。
+- **权限声明和风险预览不是运行时沙箱。** 第三方 Skill 仍可能执行其自身逻辑；安装前请核查来源与内容，不要仅凭“精选”标签就盲目信任。
+- 首次只想体验网页：使用 `安全模式-只开网页.cmd`。想撤销 WorkBuddy 中的市场注册：使用 `撤销注册.cmd`。这与卸载已经安装的技能是不同操作。
+
+## 平台支持矩阵（验证状态）
+
+| 平台 | 当前状态 |
+| --- | --- |
+| Windows 10/11 | 主要使用与验证环境；仓库文档记录了 WorkBuddy 5.7.6 面板实测 |
+| Linux | 有 CI 与部分自动化检查；尚未验证真实 WorkBuddy 宿主集成 |
+| macOS | 尚未验证 |
+
+## 文档与社区
+
+| 你想做什么 | 入口 |
+| --- | --- |
+| 配置市场、使用命令行、了解安全边界 | [详细使用与技术参考](ADVANCED_GUIDE.md) |
+| 了解首次启动、收录和恢复问题 | [FAQ](docs/FAQ.md) |
+| 了解插件包协议与校验 | [插件包协议](docs/plugin-spec.md) |
+| 报告安全问题 | [安全策略](SECURITY.md) |
+| 提交代码或改进文档 | [贡献指南](CONTRIBUTING.md) |
+| 查看版本变化 | [CHANGELOG](CHANGELOG.md) |
+| 提交 Bug / 功能建议 | [GitHub Issues](https://github.com/zjs105910/workbuddy-market/issues) |
+
+欢迎 Star、提 Issue、提交可复现的问题与 PR。项目采用 MIT License。

workbuddy_market-2.27.0/README.md

@@ -0,0 +1,81 @@
+# WorkBuddy Market
+
+**简体中文** · [English](README_EN.md)
+
+[![CI](https://github.com/zjs105910/workbuddy-market/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/zjs105910/workbuddy-market/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**给 WorkBuddy 用的本机优先插件市场。** 将本机 Skills 打包成插件，在精选社区目录或 GitHub 中查找技能；安装前查看来源、权限声明和兼容性，再通过哈希校验与可恢复事务完成安装、更新和卸载。
+
+*A local-first plugin marketplace for WorkBuddy: package local Skills, explore community and GitHub sources, review declared permissions and compatibility, and manage installs through hash verification and recoverable transactions.*
+
+## 30 秒了解它
+
+- **管理自己的 Skills**：将本机技能打包、同步，并注册到 WorkBuddy 插件面板。
+- **发现社区技能**：浏览精选目录，也可以搜索 GitHub 上的公开仓库。
+- **安装过程更可追溯**：安装前有来源与风险预览；支持内容校验、事务恢复和回收站。
+- **本机优先**：网页服务只监听 `127.0.0.1`；你的私有市场配置和本机技能内容不随仓库提交。
+
+## 快速上手（Windows）
+
+要求：Python 3.10+、Git。想先体验网页，不改动 WorkBuddy 配置，推荐从安全模式开始。
+
+```powershell
+git clone https://github.com/zjs105910/workbuddy-market.git
+cd workbuddy-market
+.\安全模式-只开网页.cmd
+```
+
+启动后打开本机地址（默认 `http://127.0.0.1:8777/`）。**请保持启动窗口打开**；结束时回到窗口按 `Ctrl+C`。
+
+已经准备好要接入 WorkBuddy 时，再运行 `一键启动.cmd`。首次初始化的交互向导中，**直接回车是只浏览**；只有明确输入 `2` 才会请求注册到 WorkBuddy。注册前仍会进行打包与自检前置检查。
+
+不会使用命令行？克隆仓库后，也可以在资源管理器中双击 `安全模式-只开网页.cmd`。想了解其他启动参数、插件配置或 CLI，请看[详细使用与技术参考](ADVANCED_GUIDE.md)。
+
+## 看看界面
+
+| 本机技能 | 精选市场 |
+| --- | --- |
+| ![本机技能管理界面](docs/screenshots/home-local.png) | ![精选社区插件界面](docs/screenshots/home-curated.png) |
+
+安装前的来源、权限与兼容性预览：
+
+![安装前详情预览](docs/screenshots/detail-four-questions.png)
+
+> 截图由项目脚本使用合成数据生成。实际可用操作会根据本机环境与插件来源有所不同。
+
+## 产品演示与正式版本
+
+- [可复现演示：录制方法、中文字幕与隐私边界](docs/demo-video.md)
+- [正式 Release 发布流程](docs/release-process.md)
+- [观看当前演示构建（约 80 秒，MP4 + 中文字幕）](https://github.com/zjs105910/workbuddy-market/actions/runs/38121812213)（Actions 附件有效期 30 天）。
+- 正式版本的 MP4、字幕、Python 安装包与 SHA-256 校验文件将在 [GitHub Releases](https://github.com/zjs105910/workbuddy-market/releases) 中一起发布。当前演示构建是临时附件；`registry-artifacts-*` 是社区插件产物，不是市场本体安装包。
+
+## 安装前请知道
+
+- 卸载时会检查插件是否由本市场管理、内容是否被修改；不属于本市场管理的技能不会被随意删除。回收站与事务恢复用于降低误操作影响。
+- **权限声明和风险预览不是运行时沙箱。** 第三方 Skill 仍可能执行其自身逻辑；安装前请核查来源与内容，不要仅凭“精选”标签就盲目信任。
+- 首次只想体验网页：使用 `安全模式-只开网页.cmd`。想撤销 WorkBuddy 中的市场注册：使用 `撤销注册.cmd`。这与卸载已经安装的技能是不同操作。
+
+## 平台支持矩阵（验证状态）
+
+| 平台 | 当前状态 |
+| --- | --- |
+| Windows 10/11 | 主要使用与验证环境；仓库文档记录了 WorkBuddy 5.7.6 面板实测 |
+| Linux | 有 CI 与部分自动化检查；尚未验证真实 WorkBuddy 宿主集成 |
+| macOS | 尚未验证 |
+
+## 文档与社区
+
+| 你想做什么 | 入口 |
+| --- | --- |
+| 配置市场、使用命令行、了解安全边界 | [详细使用与技术参考](ADVANCED_GUIDE.md) |
+| 了解首次启动、收录和恢复问题 | [FAQ](docs/FAQ.md) |
+| 了解插件包协议与校验 | [插件包协议](docs/plugin-spec.md) |
+| 报告安全问题 | [安全策略](SECURITY.md) |
+| 提交代码或改进文档 | [贡献指南](CONTRIBUTING.md) |
+| 查看版本变化 | [CHANGELOG](CHANGELOG.md) |
+| 提交 Bug / 功能建议 | [GitHub Issues](https://github.com/zjs105910/workbuddy-market/issues) |
+
+欢迎 Star、提 Issue、提交可复现的问题与 PR。项目采用 MIT License。

workbuddy_market-2.27.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "workbuddy-market"
+description = "Local-first plugin marketplace for WorkBuddy: package local skills, register into WorkBuddy, browse & install from a 127.0.0.1-only web UI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "zjs105910" }]
+keywords = ["workbuddy", "skill", "plugin", "marketplace", "agent-skills", "ai-agents", "developer-tools", "local-first"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Operating System :: Microsoft :: Windows",
+    # POSIX 的真实 WorkBuddy 宿主集成仍未验证。CI 覆盖 POSIX 语义冒烟与 pytest；
+    # 完整隔离 selftest 硬门槛暂只在 Windows 跑（平台状态见 README / ADVANCED_GUIDE）。
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.13",
+]
+# 版本号唯一来源仍是 src/workbuddy_market/version.py（约定不变），
+# 这里动态读取，避免出现第二个要同步的常量。
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/zjs105910/workbuddy-market"
+Repository = "https://github.com/zjs105910/workbuddy-market"
+Documentation = "https://github.com/zjs105910/workbuddy-market/blob/main/ADVANCED_GUIDE.md"
+Issues = "https://github.com/zjs105910/workbuddy-market/issues"
+Security = "https://github.com/zjs105910/workbuddy-market/blob/main/SECURITY.md"
+Changelog = "https://github.com/zjs105910/workbuddy-market/blob/main/CHANGELOG.md"
+
+[project.scripts]
+# 高级用户入口（在仓库 clone 目录内运行，操作当前 clone 的市场）；
+# Windows 新手入口仍是一键启动.cmd —— 两条路一个内核。
+workbuddy-market = "workbuddy_market.cli:main"
+
+[project.optional-dependencies]
+# 开发者测试框架（v3-roadmap P1：pytest 承担日常回归，selftest 保留为
+# 零依赖一键环境诊断）。`pip install -e .[dev]` 或 CI 里单装 pytest。
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.dynamic]
+version = { attr = "workbuddy_market.version.MARKET_VERSION" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

workbuddy_market-2.27.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

workbuddy_market-2.27.0/src/workbuddy_market/__init__.py

@@ -0,0 +1,12 @@
+"""WorkBuddy 本机插件市场 —— 内核包。
+
+v2.8（R2）起，market_core.py 的实现按 docs/开源重构方案.md §3.1 陆续迁入本包：
+
+* R2（v2.8）：paths / errors / fsutil / hasher / locking / logging（无状态纯函数）
+* R3（v2.9）：config / scanner / sync / version
+* R4（v2.12）：trash / ownership / transactions（注入点经 core 晚绑定保持语义）
+* R5+（后续轮次）：installer / uninstaller / state / diagnostics / cli / api
+
+兼容入口仍是仓库根的 ``market_core.py``：它 re-export 本包的全部公开符号，
+``import market_core`` 与 ``core.X`` 的用法（含 selftest 的属性注入）不受影响。
+"""

workbuddy_market-2.27.0/src/workbuddy_market/__main__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""python -m workbuddy_market —— 与 workbuddy-market 命令行同一入口。"""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workbuddy_market-2.27.0/src/workbuddy_market/adapters/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""adapters —— 宿主适配层（v2.17 新增）。
+
+每个子模块封装「对某一个宿主 / 外部系统内部格式的全部知识」。
+内核与其余模块只经 adapter 触碰宿主；宿主格式变化只改这一层。
+"""

workbuddy_market-2.27.0/src/workbuddy_market/adapters/workbuddy.py

@@ -0,0 +1,301 @@
+# -*- coding: utf-8 -*-
+"""adapters.workbuddy —— WorkBuddy 宿主适配层（v2.17 新增，R6 半程）。
+
+这个包从 v1 起就知道很多 WorkBuddy 的内部细节：known_marketplaces.json
+的形状、marketplace 条目字段、备份目录约定…… v2.16 之前这些知识散落在
+market_core 的注册段里。宿主程序未来最容易变化的就是这些东西
+（WorkBuddy 5.x / 6.x 的市场协议、安装位置、条目格式），所以现在把
+**所有「WorkBuddy 宿主格式」的读写收进这一层**，内核只经它触碰宿主。
+
+职责（全部自 market_core.py 逐字迁入，v2.17）：
+
+  · known_marketplaces.json 的读取（含 strict 口径：坏了宁可报错也不覆盖）；
+  · 备份（纳秒戳）与轮转；
+  · 条目构造（directory 型市场）；
+  · 乐观合并写入（_commit_known，与 WorkBuddy 自身写入竞争的防线）；
+  · register / unregister 编排；
+  · capabilities()：宿主能力矩阵（未来版本探测的落点）；
+  · known_health()：known 文件的健康检查（deep_check 消费）。
+
+注入点纪律（R4/R5 延续）：register() 依赖 core 的 _sync_packaging（注入点），
+在调用点晚绑定 ``import market_core``。本模块内部的互调（register →
+_commit_known → _read_known_or_die）走**本模块命名空间** —— selftest 的
+patch 落点随迁 ``workbuddy_market.adapters.workbuddy``（与 R4 把
+ownership/trash 的 patch 落点迁到包内同一先例）。core 侧名字全部
+re-export，``core.register`` / ``core._read_known_or_die`` 仍是同一对象，
+但 **patch 语义随迁**：要拦截注册链路里的读，请 patch 本模块。
+
+未来 WorkBuddy 6.x 若改了市场格式，改这一个文件就够了 —— 这就是
+adapter 的意义。
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..config import ConfigError, load_config
+from ..fsutil import atomic_write_text, read_json
+from ..locking import locked
+from ..logging import log
+from ..paths import BACKUP_DIR, BACKUP_KEEP, KNOWN_PATH, MARKET_ROOT, WB
+
+WORKBUDDY_ADAPTER_VERSION = 1
+
+# 宿主能力矩阵：未来探测宿主版本后按版本收紧/放开。
+# 现在如实标注当前已实现/已验证的能力（v2.17 口径）。
+_CAPABILITIES = {
+    "marketplace_register": True,      # 写 known_marketplaces.json
+    "marketplace_unregister": True,
+    "directory_market": True,          # directory 型市场源
+    "skill_install_location": True,    # 直写 ~/.workbuddy/skills
+    "security_scan": False,            # 宿主侧安装前扫描：未验证，不虚报
+    "skill_enable": False,             # 宿主侧启用/禁用开关：未实现
+    "auto_update": False,              # 宿主自动更新本市场：显式关闭
+}
+
+
+def capabilities() -> dict:
+    """宿主能力矩阵（诚实口径：没验证过的能力一律 False，不虚报）。"""
+    return dict(_CAPABILITIES)
+
+
+def detect_host_version(host_dir: Path | None = None) -> str | None:
+    """探测宿主 WorkBuddy 版本（v2.20，诚实口径：找不到就 None）。
+
+    来源（按序，全部是**显式**来源）：
+
+      1. 环境变量 ``WORKBUDDY_VERSION``（宿主 / 测试显式注入）；
+      2. ``<宿主目录>/last-launch.json`` 的 ``version`` 字段 —— WorkBuddy
+         每次启动自己写的启动记录（实测 5.7.6 存在）。属**不可信状态
+         文件**：形状不对、不是字符串、不含数字 → 当没有。
+
+    绝不去猜安装目录、注册表或进程参数 —— 探测不到就返回 None，
+    调用方（verify_package / compatibility_report）如实标「宿主版本
+    未知」，绝不把「不知道」说成「满足」或「不满足」。
+    """
+    env = (os.environ.get("WORKBUDDY_VERSION") or "").strip()
+    if env:
+        return env[:32]
+    d = Path(host_dir) if host_dir is not None else WB
+    data = read_json(d / "last-launch.json", None)
+    if not isinstance(data, dict):
+        return None
+    v = data.get("version")
+    if not isinstance(v, str) or not v.strip() or not any(c.isdigit() for c in v):
+        return None
+    return v.strip()[:32]
+
+
+# ---------------------------------------------------------------- known 读取
+
+def read_known(strict: bool = False) -> dict:
+    """读 known_marketplaces.json。
+
+    strict=True 时，文件存在但读不出来会**抛 ConfigError**，而不是当成空表。
+    这一点很关键：如果当成空表，register() 就会拿一个只含自己一条的记录
+    去覆盖原文件 —— 用户其它几个市场（包括 WorkBuddy 自带的）会被直接抹掉。
+    宁可报错让用户去 .backups 里恢复，也不能替用户把数据删了。
+    """
+    data = read_json(KNOWN_PATH, None, strict=strict)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        if strict:
+            raise ConfigError(f"{KNOWN_PATH.name} 的顶层必须是一个对象，实际是 {type(data).__name__}")
+        return {}
+    return data
+
+
+def read_known_or_die() -> dict:
+    """写操作前读 —— 文件坏了就拒绝继续，绝不覆盖。"""
+    if not KNOWN_PATH.is_file():
+        return {}
+    try:
+        return read_known(strict=True)
+    except ConfigError as exc:
+        raise RuntimeError(
+            f"拒绝覆盖：{KNOWN_PATH.name} 已损坏，读不出来。\n"
+            f"  原因：{exc}\n"
+            f"  文件：{KNOWN_PATH}\n"
+            f"  备份：{BACKUP_DIR}（挑一份改名成 known_marketplaces.json 即可恢复）\n"
+            "  修好或删掉它再重试。"
+        ) from exc
+
+
+def backup_known() -> Path | None:
+    """备份 known_marketplaces.json。
+
+    时间戳带纳秒，避免同一秒内两次备份互相覆盖
+    （v1 用秒级戳 + 「已存在就返回」会让第二次修改没有备份）。
+    """
+    if not KNOWN_PATH.is_file():
+        return None
+    BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%d-%H%M%S") + f"-{time.time_ns() % 1_000_000_000:09d}"
+    dst = BACKUP_DIR / f"known_marketplaces.{stamp}.json"
+    shutil.copy2(KNOWN_PATH, dst)
+    log("info", "backup", f"已备份 known_marketplaces.json → {dst.name}")
+    return dst
+
+
+def _prune_backups(keep: int = BACKUP_KEEP) -> None:
+    if not BACKUP_DIR.is_dir():
+        return
+    items = sorted(BACKUP_DIR.glob("known_marketplaces.*.json"))
+    if len(items) <= keep:
+        return
+    for old in items[: len(items) - keep]:
+        try:
+            old.unlink()
+        except OSError:
+            pass
+
+
+def is_registered(cfg: dict | None = None) -> bool:
+    cfg = cfg or load_config()
+    return cfg.get("marketId") in read_known()
+
+
+def entry_for(cfg: dict) -> dict:
+    """本市场在 known_marketplaces.json 里的条目（directory 型）。"""
+    return {
+        "manifestName": cfg.get("marketId", "wb-local-market"),
+        "type": "directory",
+        "source": {"source": "directory", "path": str(MARKET_ROOT)},
+        "installLocation": str(MARKET_ROOT),
+        "description": cfg.get("description", ""),
+        "lastUpdated": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        "autoUpdate": False,
+        "isBuiltIn": False,
+    }
+
+
+def commit_known(mutate, *, attempts: int = 4, what: str = "修改"):
+    """对 known_marketplaces.json 做乐观合并写入。
+
+    WorkBuddy 自己也会改这个文件（autoUpdate 市场刷新 lastUpdated、zip 地址
+    换成带内容哈希的版本），而它**不抢我们这把锁**。原来的
+    「读 → 改 → 原子写 → 读回校验」只能发现「整个条目消失」，
+    发现不了「某个市场的字段在中间被别人改了、又被我们整份覆盖回去」。
+
+    改成：落笔之前再读一次，确认和我们读到的快照一模一样才写；
+    不一样就基于最新内容重新合并。这把竞争窗口从「整个读-改-写过程」
+    压到了「重读到 replace 之间的几十微秒」。
+
+    返回 (before, candidate)。mutate 返回 False 表示无需改动（提前收工）。
+    """
+    for attempt in range(attempts):
+        before = read_known_or_die()
+        candidate = mutate(dict(before))
+        if candidate is False:
+            return before, None
+        latest = read_known_or_die()
+        if latest != before:
+            log("warn", "register",
+                f"{what}前发现 {KNOWN_PATH.name} 已被外部改动"
+                f"（第 {attempt + 1} 次），基于最新内容重新合并")
+            continue
+        backup_known()
+        atomic_write_text(KNOWN_PATH,
+                          json.dumps(candidate, ensure_ascii=False, indent=2) + "\n",
+                          durable=True)
+        _prune_backups()
+        after = read_known()
+        lost = set(before) - set(after)
+        if lost:
+            log("warn", "register",
+                f"检测到写回期间有市场消失：{', '.join(sorted(lost))}（WorkBuddy 可能同时在写）")
+        return before, after
+    raise RuntimeError(
+        f"{what}失败：{KNOWN_PATH.name} 被反复改写（{attempts} 次都撞车）。\n"
+        "如果 WorkBuddy 正在运行，稍后再试一次即可；文件没有被写坏。"
+    )
+
+
+# ---------------------------------------------------------------- 注册 / 撤销
+
+def register(force: bool = False) -> bool:
+    """把本市场写进 known_marketplaces.json。幂等；返回是否发生了改动。
+
+    WorkBuddy 运行时会自己改写这个文件，所以并发保护有两层：
+      · 全程持文件锁 → 防本工具自己的多个进程互相覆盖（lost update）
+      · 乐观合并（读 → 改 → 重读 → 比对 → 写）→ 缩小与 WorkBuddy 自身写入的竞争窗口
+    """
+    import market_core as _core          # noqa: PLC0415 —— _sync_packaging 注入点晚绑定
+    with locked():
+        cfg = load_config()
+        mid = cfg.get("marketId", "wb-local-market")
+
+        if not _core.MANIFEST_PATH.is_file():
+            _core._sync_packaging(quiet=True)
+
+        entry = entry_for(cfg)
+
+        # 比较时忽略 lastUpdated，否则每次启动都会重写一遍这个文件
+        def _same(a: dict, b: dict) -> bool:
+            return ({k: v for k, v in a.items() if k != "lastUpdated"}
+                    == {k: v for k, v in b.items() if k != "lastUpdated"})
+
+        def _mutate(known: dict):
+            if not force and isinstance(known.get(mid), dict) and _same(known[mid], entry):
+                return False
+            known[mid] = entry
+            return known
+
+        before, after = commit_known(_mutate, what="注册")
+        if after is None:
+            log("info", "register", "已注册且条目未变，跳过")
+            return False
+        if mid not in after:
+            log("warn", "register", "写回后本市场条目不见了 —— WorkBuddy 可能同时改写了该文件")
+            raise RuntimeError("写回校验失败：注册条目未生效（可能和 WorkBuddy 的自动更新撞车，重跑一次即可）")
+        log("info", "register", f"已注册市场 {mid} → {MARKET_ROOT}")
+        return True
+
+
+def unregister() -> bool:
+    with locked():
+        cfg = load_config()
+        mid = cfg.get("marketId", "wb-local-market")
+
+        def _mutate(known: dict):
+            if mid not in known:
+                return False
+            del known[mid]
+            return known
+
+        before, after = commit_known(_mutate, what="撤销注册")
+        if after is None:
+            log("info", "unregister", "本来就没注册，跳过")
+            return False
+        log("info", "unregister", f"已撤销注册 {mid}")
+        return True
+
+
+# ---------------------------------------------------------------- 体检
+
+def known_health() -> str | None:
+    """known_marketplaces.json 的健康检查。正常返回 None；有问题返回人话。
+
+    deep_check（core）消费它 —— 宿主格式的问题由 adapter 自己诊断，
+    内核不再直接解读这个文件的形状。
+    """
+    if not KNOWN_PATH.parent.is_dir():
+        return f"WorkBuddy 插件目录不存在：{KNOWN_PATH.parent}"
+    if KNOWN_PATH.is_file():
+        try:
+            read_json(KNOWN_PATH, None, strict=True)
+        except ConfigError as exc:
+            return f"known_marketplaces.json 不可用：{exc}"
+    return None
+
+
+# v2.17 之前的旧名字（market_core / 第三方老脚本可能引用）：同一对象。
+_read_known = read_known
+_read_known_or_die = read_known_or_die
+_entry_for = entry_for
+_commit_known = commit_known