安装与首轮验证（Windows 优先）

这份说明用于在当前主机安装公开的 xiaoeskill。先发现本机 Agent 实际支持的路径、命令和浏览器，再复制匹配平台的包；不要猜其他设备的 skill root、浏览器端口或 Obsidian 目录，也不要覆盖未确认的已有安装。

0. 安装前：让目标 Agent 先自报

把 AGENT_COMPATIBILITY.md 末尾的 onboarding prompt 交给目标 Agent。至少得到以下不含秘密的结果后再继续：

Agent/宿主名称和版本、操作系统、shell，以及它从配置中发现的 skill root；
Python 3.10+、ffmpeg、ffprobe、本地 whisper.cpp CLI/模型是否可用；
是否有可验证的浏览器工具、明确 CDP endpoint、系统音频设备和可写 Obsidian 目标；
它准备安装的包目录（Windows 或 macOS）和将运行的 checker 命令。

如果 Agent 无法发现自己的 root 或工具，写 information missing 并暂停，不要以 “通常在某个目录”代替验证。

1. Windows 安装（首选示例）

在 PowerShell 中从本仓库根目录执行。以下命令只检查，不会把凭据写入仓库。

1.1 发现主机与工具

$PSVersionTable.PSVersion
py -3 --version
Get-Command ffmpeg -ErrorAction SilentlyContinue
Get-Command ffprobe -ErrorAction SilentlyContinue
node --version

node 仅在确实使用浏览器 bridge 时需要；不存在时可继续离线路线。再让目标 Agent 从自己的配置报告 $SkillRoot，由使用者确认后再赋值：

$SkillRoot = Read-Host "粘贴 Agent 报告并由你确认的 skill root"
if ([string]::IsNullOrWhiteSpace($SkillRoot) -or
    -not (Test-Path -LiteralPath $SkillRoot -PathType Container)) {
  throw "INSTALLATION_DISCOVERY_BLOCKED: 未验证 skill root"
}

不要把其他设备上的路径替换进 $SkillRoot。若目标已经存在，先停止并由使用者决定备份/迁移；不要静默覆盖：

$Target = Join-Path $SkillRoot "xiaoeskill"
if (Test-Path -LiteralPath $Target) {
  throw "INSTALLATION_TARGET_EXISTS: 请先确认如何处理已有安装"
}
Copy-Item -LiteralPath .\windows\xiaoeskill -Destination $Target -Recurse

1.2 验证包与平台副本

仍在仓库根目录运行：

py -3 shared/checks/verify_package.py
Get-ChildItem .\windows\xiaoeskill\runtime\*.py | ForEach-Object {
  py -3 -m py_compile $_.FullName
}

checker 必须通过，且不能因为个人路径、secret-like 文本或 Windows 平台边界而失败。安装后 Agent 应再次确认 $Target\SKILL.md、runtime、references 和 agents\openai.yaml 同处一个包内。

1.3 设置本机选择并做 writable smoke check

以下值由使用者在本机选择；不要把示例目录当默认真值：

$env:XIAOESKILL_DATA_DIR = "<你确认的私有数据目录>"
$env:XIAOESKILL_JOBS_DIR = "<你确认的数据目录下 jobs 子目录>"
$env:XIAOESKILL_WHISPER_MODEL = "<你确认的本地模型文件>"
$env:XIAOESKILL_WHISPER_CLI = "<你确认的 whisper.cpp CLI>"
$env:XIAOESKILL_FFMPEG = "<不在 PATH 时的 ffmpeg.exe>"
$env:XIAOESKILL_FFPROBE = "<不在 PATH 时的 ffprobe.exe>"
$env:XIAOESKILL_OBSIDIAN_VAULT = "<你确认的主 vault>"
$env:XIAOESKILL_OBSIDIAN_MIRROR = "<可选且独立的 mirror>"

逐项用 Test-Path 验证模型/可执行文件和 vault；对数据/jobs 目录验证可写且不是符号链接或公共同步目录。只有在实际启用浏览器 bridge 时才设置 $env:XIAOESKILL_PYTHON、$env:XIAOESKILL_BROWSER_CDP_URL；CDP endpoint 必须来自 Agent 的当前配置或浏览器工具输出，不能猜端口。

Windows 音频降级使用已安装并获准的 Windows mixer 或 virtual cable，确认设备名称和采样率；没有设备就跳过实时捕获，继续使用本地文件/官方导出。

2. macOS 安装

2.1 发现主机与 skill root

uname -srm
python3 --version
command -v ffmpeg || true
command -v ffprobe || true
node --version || true

请本机 Agent 从其配置报告 skill root，再由使用者确认并显式传入：

read -r XIAOESKILL_INSTALL_ROOT
test -n "$XIAOESKILL_INSTALL_ROOT" || {
  echo "INSTALLATION_DISCOVERY_BLOCKED: 未验证 skill root" >&2
  exit 2
}
test -d "$XIAOESKILL_INSTALL_ROOT" || {
  echo "INSTALLATION_DISCOVERY_BLOCKED: 目录不存在" >&2
  exit 2
}
target="$XIAOESKILL_INSTALL_ROOT/xiaoeskill"
test ! -e "$target" || {
  echo "INSTALLATION_TARGET_EXISTS: 请先确认如何处理已有安装" >&2
  exit 2
}
cp -R macos/xiaoeskill "$target"

2.2 验证包

python3 shared/checks/verify_package.py
python3 -m py_compile macos/xiaoeskill/runtime/*.py

根据 CUSTOMIZATION.md 设置数据、工具、浏览器、音频和 Obsidian 选项。macOS 音频降级需要经批准的系统音频设备（例如 BlackHole 2ch），并确认采样率；没有设备或授权时报告 MEDIA_ACQUISITION_BLOCKED。

3. 浏览器能力验证与降级

浏览器不是安装成功的必要条件。只有 Agent 能指出自己的浏览器工具、明确的 XIAOESKILL_BROWSER_CDP_URL（若适用），并在该会话中打开单个已授权回放页，才进入浏览器 smoke check：读取可见 URL/标题/回放 ID/小范围 video 状态，不读取浏览器存储。page-asset 数量为零、登录重定向、多个候选、加密/DRM/live playlist 或时长不符时，都算 browser-HLS unavailable。

结果按以下三类记录：

BROWSER_HLS_READY：契约通过且观察到一个授权 clear-VOD manifest；仍须单独确认个人离线备份后才能调用 HLS 下载器。
BROWSER_HLS_UNAVAILABLE：浏览器存在但契约不完整或媒体候选不足；转到本地文件、可见官方下载/导出、官方 API 或获准的实时系统音频。
MEDIA_ACQUISITION_BLOCKED：没有浏览器能力，也没有合法的离线/官方/音频输入；保留阻塞状态，不猜 URL 或登录态。

4. 首次作业前的最终核对

安装后按 CUSTOMIZATION.md 完成完整清单，再让 Agent 返回：

实际安装包路径和平台；
每个工具的版本/可执行状态（不返回环境变量 dump）；
数据/jobs、模型、主 vault/mirror 的存在性与可写性；
浏览器契约结果和降级状态；
音频设备（若启用）名称/采样率；
仍缺失的输入和下一步需要使用者确认的事项。

没有这些证据就只算“安装候选”，不算“可处理回放”。完整安全边界仍以各平台 SKILL.md 和 references/ 为准。

FilesExpand file tree

INSTALLATION.md

Latest commit

History