SDK 或文件挂载
自建 Python Agent 优先查看 Python SDK：无需 FUSE，可获取带快照版本的发现列表。现成 Agent 只支持文件目录时使用下文的 Linux 挂载方式。两者的缓存、离线与上下文更新语义不同，见 接入方式对比。以下模式和离线策略说明针对挂载客户端；SDK 默认动态视图、在线校验；重试默认复用显式检查点中的快照。
创建 Profile 和终端身份
先创建 Profile，选择渠道、Skills、dynamic 或 pinned 模式和离线策略。确保渠道已有可用快照。注册挂载终端时选择该 Profile，保存仅展示一次的 Token；丢失时轮换，平台不会再次显示原值。
每个终端使用独立凭据。模式由服务端 Profile 决定，客户端不能自行切换渠道或扩大权限。
在 Linux 上挂载
需要 Linux FUSE 环境、可访问的 /dev/fuse 和相应挂载权限。将对应架构的 skills-mount 可执行文件放入 PATH。当前原生 macOS / Windows 挂载不在已交付范围内。
以下为 dynamic Profile 的示例，将域名和 PROFILE_ID 替换为真实值；Token 保存到本地 client.token 文件：
chmod 600 client.token
skills-mount login \
--server https://skills.example.internal \
--token-file client.token
skills-mount mount \
--profile PROFILE_ID \
--mode dynamic \
--path "$HOME/agent-skills"
mount 在前台运行；从另一个终端执行 status、refresh 或 unmount。每个同时运行的挂载使用不同 --cache 目录，控制命令也要传入对应 --cache。
接入 Agent 的项目目录
在平台项目根目录运行适配脚本，将已挂载目录链接到目标项目：
python3 scripts/agent-link.py \
--source-mount-path /srv/agent-skills \
--project /workspace/my-project \
--agent codex
| Agent 参数 | 项目搜索目录 |
|---|---|
| codex | .agents/skills |
| claude | .claude/skills |
| opencode | .opencode/skills |
脚本拒绝覆盖已有路径，也不修改全局 Agent 配置。沙箱不允许符号链接时，可在允许的搜索目录直接挂载，或由管理员配置只读 bind mount。
日常控制命令
skills-mount status
skills-mount refresh
# pinned 任务结束后才重新绑定
skills-mount refresh --repin
skills-mount unmount --path "$HOME/agent-skills"
若 Profile 设置了固定 pinnedSnapshotId，需要先调整该服务端绑定，客户端 repin 才能切换到新的授权目标。
离线与撤权
- deny_on_disconnect：授权租约到期后拒绝读取，适用于敏感内容。
- allow_cached：断网时可以继续读取已缓存且验证通过的内容，未缓存内容无法凭空读取。
- 在线发现凭据撤销后停止授权读取；断网期间无法保证即时发现撤销。
缓存不会提前下载所有内容。首次使用前若需要离线，应先实际读取所需文件，并验证断网行为。
文件更新不等于上下文更新
dynamic 保留旧文件句柄，新的 open 使用新索引；pinned 固定任务快照。Agent 还可能维护自己的 Skills 索引或提示词缓存，需要重新加载或开启新会话。
Codex、Claude Code、OpenCode 的主机级 Skill 发现已验证。另已通过真实 Pydantic AI + MiniMax 模型读取 Docker Linux FUSE 的完整发布验收。其他 Agent 沙箱与上下文缓存策略仍需分别验证。
运行本地 Pydantic AI 示例
项目内 examples/pydantic-agent/run.sh 会启动独立的 8083 试点后端和数据库。准备 Docker Desktop、uv 及模型环境变量后，在项目根目录运行：
./examples/pydantic-agent/run.sh
示例使用 150 元模拟报销：v1 限额 100 元时拒绝；Git 推送并发布 v2 限额 200 元后，dynamic 通过，pinned 仍拒绝；回滚后 dynamic 恢复拒绝；撤销凭据后两种挂载都无法读取。每个模型回合都会重新从挂载目录读取 SKILL.md。
完整准备步骤与运行说明。本地结果与 OpenTelemetry 记录位于 .data/agent-pilot/，不需要托管追踪服务。