跳到主要内容
AI教程

MuseAI-Skills 阅读教程：解析 Muse AI 技能、权限与 Agent 工作流

本教程介绍如何获取并安全阅读 MuseAI-Skills，理解技能定义、连接器权限、评测场景与运行环境脚本，并以 Gmail 等技能为例建立可复用的 Agent 工作流分析方法。

AI我搜编辑部阅读约 15 分钟
MuseAI-Skills 阅读教程：解析 Muse AI 技能、权限与 Agent 工作流

项目是什么

MuseAI-Skills 是一份与 muse.ai 相关的 Muse / Hatch 个人 AI Agent 环境快照。仓库保存了产品说明、技能定义、连接器权限清单、行为评测场景、Linux 运行脚本，以及部分随包程序和依赖。

重要边界：它不是完整源码仓库，也不是可以一键部署的安装包。核心程序主要以 Linux x86-64 ELF 二进制提供，而构建源码、完整宿主配置、rootfs 和部分运行资源并未包含。

因此，这个仓库最适合用于静态阅读、Agent 工作流研究、权限模型分析和指令设计参考，而不是直接安装 Muse AI 服务。仓库材料使用 Muse、Hatch 和 Jarvis 等名称，但存档本身不代表官方发布、认可或来源认证。

你能从仓库中学到什么

技能工作流的完整结构

仓库包含 72 个 SKILL.md 路径，其中有 68 个独立技能文件和 4 个符号链接别名。技能覆盖 Agent 工作流、文档产物、旅行预订、办公工具、社交平台、健康数据、媒体生成、设备控制和 Muse 产品操作等领域。

这些技能文档通常能帮助你研究以下问题：

  • 什么用户请求应该触发技能。
  • 任务应由协调者、worker 还是外部连接器处理。
  • 执行前需要哪些账户连接、OAuth scope 或用户授权。
  • 工具失败、输入不完整或权限不足时如何降级。
  • 如何定义输出格式并验证最终交付物。

权限与评测材料

仓库另有 40 个 manifest 路径和 12 份 eval YAML。manifest.yaml 可用于理解连接器元数据、权限默认值、scope 要求和命令映射；eval/scenarios.yaml 则记录行为评测场景、用户目标和期望行为。

注意：存在 manifest 不表示账户已经连接，存在评测场景也不表示评测已经运行或通过。

运行环境的静态线索

opt/hatch/runtime-cell/ 中的脚本展示了部分运行环境生命周期，包括 rootfs 路径解析、启动前准备、内核模块检查、systemd-nspawn 容器启动以及技能和二进制 overlay 的组装。不过，完整宿主 unit、nspawn 配置和实际 rootfs 都不在仓库中。

目录结构速览

  • README.md：中文入口、技能目录和边界说明。
  • README.en.md：英文入口。
  • PROJECT_ANALYSIS.md：架构判断、缺失组件、风险和证据索引。
  • SHA256SUMS：普通文件的内容校验清单，但不是来源签名。
  • home/hatch/docs/：产品、连接器、隐私、调度、文件、设备和媒体等说明。
  • home/hatch/config/：Agent 与技能状态相关配置。
  • opt/hatch/skills/：技能入口、权限 manifest、评测场景和参考资料。
  • opt/hatch/runtime-cell/：运行环境生命周期脚本与配置模板。
  • opt/hatch/bin/：Hatch 相关程序。
  • opt/hatch-image/：镜像侧工具、npm、Bun 和其他随包组件。

仓库根目录只是存档根目录，并不是正在运行的 Linux 根目录。存档中的 home/hatch/ 对应原环境的 /home/hatch，而文档中的 /run、/var/lib 和 /etc 通常指缺失的运行时文件系统。

获取与准备仓库

方案一：只研究技能和文档

如果目标是分析 Markdown、YAML 和 Shell 脚本，可以跳过体积较大的 Git LFS 二进制。这也是最推荐的阅读方式。

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills

这种方式无需执行随包程序。进入仓库后，优先打开 PROJECT_ANALYSIS.md 和 opt/hatch/skills/。

方案二：查看完整存档对象

只有在确实需要检查 LFS 中的 ELF 程序或其他大文件时，才应安装 Git LFS 并获取相关对象。下载二进制并不会补齐缺失的源码、rootfs、凭据或宿主配置，也不会让仓库变成可部署系统。

git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills
git lfs pull

对于来源未经独立认证的二进制，应优先进行离线静态检查，不要直接在生产机器或包含敏感凭据的环境中运行。

校验普通文件

在完整获取相关文件后，可以使用仓库提供的 SHA256SUMS 检查内容完整性：

sha256sum -c SHA256SUMS

校验清单不覆盖清单文件自身和符号链接，也不是发布者身份或来源真实性的密码学签名。它只能帮助判断本地普通文件是否与清单中记录的摘要一致。

基础用法：建立技能阅读流程

第一步：选择一个技能入口

初次阅读可以从以下技能开始：

  • wide-research：研究协调者、worker、统一输出契约和失败覆盖。
  • skill-creator：技能触发描述、目录拆分和按需加载参考资料。
  • artifacts/testing：区分“生成成功”和“交付物可用”。
  • goals：区分首次建立目标与后续跟进。
  • forget：处理副本、衍生状态和可能重新写回的数据。
  • travel-planning：分离行程研究、实时查询和交易执行。
  • gmail：结合技能正文、方法级权限和评测场景分析连接器。

例如，查看 Gmail 技能入口：

sed -n '1,240p' opt/hatch/skills/gmail/SKILL.md

第二步：提取触发条件与边界

阅读 SKILL.md 时，不要只记录“它能做什么”，还要依次回答：

  1. 哪些请求应该触发该技能？
  2. 哪些相似请求不应该触发？
  3. 只读操作和写入操作如何区分？
  4. 发送、删除、购买或预订等高影响操作是否需要确认？
  5. 权限不足、目标歧义或工具失败时应如何处理？
  6. 最终结果需要返回哪些字段或证据？

将这些内容整理为“触发、输入、授权、执行、失败、验收”六个部分，便于迁移到自己的 Agent 设计中。

第三步：对照权限 manifest

对于连接器技能，应继续读取同目录下的 manifest.yaml：

sed -n '1,260p' opt/hatch/skills/gmail/manifest.yaml

重点比较技能正文声称的操作与 manifest 中声明的方法权限、分组默认值、scope 和命令映射。方法级设置可能覆盖分组默认值，因此不能只看顶层权限说明。

复制一个 SKILL.md 到其他 Agent 环境，并不会自动获得 Gmail、Google Drive、Notion 或其他服务的访问能力。实际执行仍依赖对应 CLI 或 MCP、账户连接、OAuth scope 和运行时授权。

第四步：读取评测场景

如果技能带有 eval/scenarios.yaml，可以继续查看它如何把规则转化为可测试行为：

sed -n '1,260p' opt/hatch/skills/gmail/eval/scenarios.yaml

评测场景适合用于检查以下行为：

  • Agent 是否选择了正确的技能。
  • 是否区分读取、草稿、发送、删除等不同风险等级。
  • 信息不足时是否先澄清，而不是猜测收件人或操作目标。
  • 是否在需要时请求授权或确认。
  • 失败后是否诚实报告未完成项。

不要把场景文件当成测试通过报告。若要判断历史问题，还可以结合类似 opt/hatch/skills/flightaware/eval/findings.md 的发现记录，并注意其版本和测试环境。

第五步：检查配套参考资料

部分技能将详细规则拆到 references/、guide/、creation/ 或 guides/。这种结构体现了一个重要设计原则：主技能文件保持精简，只在任务需要时加载更具体的参考资料。

例如，技能编写方法可从以下文件开始：

sed -n '1,260p' opt/hatch/skills/skill-creator/references/authoring_guide.md

实战示例：分析 Gmail 技能

可以用以下模板记录 Gmail 技能的设计，而不实际连接或操作邮箱：

技能入口：opt/hatch/skills/gmail/SKILL.md
权限定义：opt/hatch/skills/gmail/manifest.yaml
评测场景：opt/hatch/skills/gmail/eval/scenarios.yaml

分析维度：
1. 检索和阅读邮件的触发条件
2. 草稿、发送和回复的操作边界
3. 标签和退订流程
4. 方法级权限与 OAuth scope
5. 收件人、邮件线程或操作意图不明确时的处理
6. 工具失败后的报告方式
7. 用户最终应收到的结果与验证信息

完成后，可以将结果转换为自己的 Agent 规范：

  • 触发规则：明确哪些语言模式进入邮件技能。
  • 只读优先：搜索和读取与发送、删除等变更操作分开处理。
  • 授权门槛：根据目标运行环境重新定义确认和 OAuth 规则。
  • 输出契约：规定成功、部分成功和失败时分别返回什么。
  • 验收场景：添加正常请求、歧义请求、权限不足和连接器故障测试。

阅读产品与系统架构

快速理解产品契约

建议依次阅读：

  1. home/hatch/docs/muse.md：产品概览。
  2. home/hatch/docs/goals.md：目标、进展和后台工作的边界。
  3. home/hatch/docs/scheduling-and-watching.md：轮询、调度、运行历史和通知。
  4. home/hatch/docs/self_improvement.md：后台记忆、研究、回顾和证据追踪。
  5. home/hatch/docs/connectors.md：连接状态、OAuth、方法权限和失败处理。
  6. home/hatch/docs/privacy-and-credentials.md：凭据引用、Vault、导出和删除规则。

这些文件描述的是快照中的产品契约。账号特定能力和历史可用性说明，不应直接当作当前所有 Muse 账号都具备的事实。

研究运行时启动链

如果关注 Linux 隔离环境，可以从以下脚本建立调用关系：

opt/hatch/runtime-cell/pre-start.sh
opt/hatch/runtime-cell/ensure-rootfs.sh
opt/hatch/runtime-cell/resolve-rootfs-path.sh
opt/hatch/runtime-cell/require-modules.sh
opt/hatch/runtime-cell/launch-daemon.sh
opt/hatch/runtime-cell/post-start.sh

resolve-rootfs-path.sh 返回的 /var/lib/hatch-runtime/rootfs 是原运行环境中的路径，并不是仓库自带目录。launch-daemon.sh 会启动 systemd-nspawn 容器并组装 overlay；它不能脱离缺失的宿主配置和 rootfs 独立构成启动教程。

高级分析技巧

区分技能、别名和资源目录

仓库有 4 个符号链接别名：facebook 指向 facebook-cli，meta-threads 指向 threads，podcast 指向 generate_podcast，voice-calls 指向 voice-selector。

检查链接实际目标可以避免重复统计：

find opt/hatch/skills -type l -name SKILL.md -print -exec readlink {} \;

尤其不能根据 voice-calls 的名称推断它具备 Agent 代打电话能力；该入口实际指向静态语音目录。spaces 含运行时文档和模板，但没有顶层 SKILL.md，因此不应额外计为一个技能。

同时验证声明、权限和可执行依赖

分析一个技能时，可以采用三层核对法：

  1. 行为层：检查 SKILL.md 声明的触发、边界和输出。
  2. 权限层：检查 manifest 中的方法、scope 和默认权限。
  3. 执行层：确认依赖的 CLI、MCP、辅助程序、账户连接和运行时资源是否存在。

仓库明确缺少部分关键依赖，包括 Artifacts 验证脚本、skill-creator 的连接器脚手架、Magic Moment 的 mm 可执行程序，以及 Spaces 所需的部分 SDK 和构建资源。因此，“文档可读”不等于“执行链完整”。

把产物生成和产物验收分开

artifacts/testing 值得作为通用 Agent 模式研究。它强调生成文件后还要按产物类型检查、重新渲染、目视验收并扫描占位符。迁移到自己的系统时，可以把流程拆成：

  1. 生成文档、表格、PDF 或演示文稿。
  2. 重新打开或渲染生成结果。
  3. 检查结构、布局、公式、链接和缺失资源。
  4. 搜索未替换占位符和临时文本。
  5. 只有通过验收后才把文件标记为可交付。

研究多 Agent 协作

wide-research 展示了多输入并行研究中的关键约束：限制协调者与 worker 的职责、统一输出字段、报告覆盖率，并保留失败项。迁移时应根据自己的编排框架替换工具名和工作区路径，同时保留统一输出契约与失败可见性。

检查数据库说明而不是寻找数据库

opt/hatch/skills/muse_db/references/schema.md 描述受限 SQL 规则、标识符和多个 schema 下的关系，可用于理解数据模型与跨表追踪方式。它不是实际数据库，也不是迁移源码，不能据此恢复完整服务。

保留来源、许可和证据边界

将工作流迁移到其他项目时，应保留来源归属并检查适用许可。建议在内部分析记录中区分：

  • 仓库文件直接陈述的事实。
  • 根据目录、脚本或 manifest 作出的技术推断。
  • 尚未验证的产品声明。
  • 由于缺失运行环境而无法确认的行为。

“存档中可见”并不等于“官方来源已认证”“能够独立运行”或“可以任意重新授权”。

推荐的学习路线

  1. 克隆仓库时跳过 LFS，避免不必要地下载二进制。
  2. 阅读 PROJECT_ANALYSIS.md，了解架构判断与缺失项。
  3. 选择 skill-creator 或 wide-research 学习工作流结构。
  4. 选择 gmail，联合分析技能正文、manifest 和 eval。
  5. 阅读 artifacts/testing，建立交付物验收思维。
  6. 阅读产品文档，区分技能规则与产品契约。
  7. 最后再检查 runtime-cell 脚本，理解运行时线索与缺失依赖。

结语

MuseAI-Skills 的主要价值不在于直接部署，而在于展示一个个人 AI Agent 如何组织技能触发、任务分流、连接器权限、失败处理与结果验收。把 SKILL.md、manifest.yaml、评测场景和运行依赖放在一起阅读，你可以提炼出适用于自己 Agent 系统的设计模式，同时避免把快照误当成完整源码或可执行产品。