ms

ms — meta_skill 搜索/加载引擎

核心洞见： ms 是跨两个已配置语料库（agentops + jsm）的技能搜索引擎。通过 MCP 使用，通过 CLI 编写/管理。 一条规则：每次重新索引或清除后，都必须终止所有正在运行的 ms mcp serve（会话会重新启动）。未终止的服务会悄悄读取清除前的数据，并在写入孤立文件时返回 recorded:true。

约束

• 当意图是执行技能时，请使用 full: true 或 --full 加载，因为元数据卡片和打包概览会省略可执行的指导。
• 明确区分使用与写入：使用 MCP 进行搜索和加载，但使用 CLI 记录反馈和结果，因为只有 CLI 写入才能确保落入当前数据库。
• 当所附的 mcp__ms__* 工具不可用时，请使用技能本地的一次性 MCP 助手进行搜索。ms search CLI 返回零结果，并不代表 MCP BM25 未找到匹配项，不能悄悄用它取代 MCP 搜索。
• 只能通过 scripts/ms-reindex.sh 重新索引，因为它会清理过期服务，并在重建索引后验证源内容等价。
• 将本地索引视为可丢弃的状态，而非事实来源；不应编辑索引内容来代替编辑 skills/**。
• 在生产技能工作中，ms 仅用于检索。它返回搜索和加载结果；编写内容、验证以及之后的所有决策均由调用方负责。

会话证据与指令变更

对于请求改进指令的任务，请使用 CASS 查找相关片段，并使用 ms 查找可能解释该行为或已解决该问题的现有指导。只加载相关技能，然后在提出修改前检查其规范源文件。更改 AGENTS.md 或任务提示词并不需要另行创建技能或加载无关技能。

上游 MS 还提供 build --from-cass；此适配器有意不调用该编写路径。如果调用方单独选择使用它，请检查 ms build --help。生成的技能、搜索排名、重复提示词或记录的结果，都不能证明后续效果有所改善。

CASS 搜索/打包会提供候选证据。仅当调查需要精确的原始片段、字面字段或指令身份，而所选 CASS 输出无法确定这些内容时，才使用 AO 的有限摘录视图。这些都是可选能力，并非每项任务都必须按固定顺序使用。调用方负责提出有依据的候选修改或判断无需修改、进行独立审查，并在之后测试其效用；检索本身不会带来该结果。

快速开始

查找技能（优先使用 MCP——BM25 目前明显优于 CLI 搜索），然后一次性加载完整、可执行的 SKILL.md（打算使用时始终设置 full: true）：

mcp__ms__search {query: "handle a rate limit switching accounts"}
mcp__ms__load {skill: "account-rotation", full: true}

没有所附的 MCP 工具：启动一个一次性的 stdio 服务，只返回结构化搜索 JSON，并在成功、出错或超时后将其终止：

python3 skills/ms/scripts/mcp-search.py "switch accounts on rate limit"
ms load account-rotation --full -O json | jq -r '.data.content'

状态根目录：~/Library/Application Support/ms/。

---

使用——以 MCP 为主（mcp__ms__*）

只要已连接 ms mcp serve，就优先使用 MCP 工具——这是快速且经过验证的读取路径。

工具	用途
mcp__ms__search {query}	BM25 搜索。目前严格优于 CLI 搜索（参见“易踩坑”——CLI 混合搜索仅使用 BM25；ms 从不存储文档嵌入）。
mcp__ms__load {skill, full: true}	一次调用即可返回完整、可运行的 SKILL.md，无需繁琐提取。full: false 会返回无用的元数据卡片——打算使用该技能时，始终设置为 full: true。
mcp__ms__show {skill}	返回技能的元数据卡片。
mcp__ms__suggest {cwd}	为目录推荐技能。此功能可用——但忽略它对项目语言的检测（会将 Makefile 仓库误判为 C；仅影响显示）。

未连接 MCP 工具时： 使用由服务端支持的一次性辅助脚本，确保检索仍遵循 MCP BM25 路径：

python3 skills/ms/scripts/mcp-search.py "<query>"

该辅助脚本会将干净的搜索对象（query、count、results）写入标准输出，在标准错误中报告传输／协议错误，默认应用 30 秒超时，并负责管理临时服务进程组，直至其终止并回收。可使用 MS_BIN 指定要运行的可执行文件，并通过 MS_MCP_SEARCH_TIMEOUT 或 --timeout 设置超时时间。

搜索后，CLI 仍是受支持的完整加载备用方案：

ms load <id> --full -O json | jq -r '.data.content'   # content lives in .data.content

不要用 ms search 替换该辅助脚本。在检索效果仍存在差距时，CLI 路径仅适用于诊断；尤其要注意，CLI 返回零条结果并不能证明语料库中没有匹配的技能。

---

写入／管理——仅限 CLI（已验证可写入实时数据库）

MCP 反馈工具确实存在，但只有 CLI 写入路径已验证能够成功写入——写入时请信任 CLI。

ms feedback add <skill> --positive --comment "..."   # feedback on a skill
ms feedback add <skill> --negative --comment "..."

ms outcome <skill> --success   # record only AFTER downstream factory use + validation
ms outcome <skill> --failure

ms doctor                      # admin: health
scripts/ms-reindex.sh          # (re)index THE way: rebuild + sweep + probe + source-equivalence check
scripts/ms-reindex.sh --check-source  # read-only freshness proof against current skills/** source
# Optional operator policy only; rebuild completeness is derived from live
# discovered/indexed/errors accounting, not a historical absolute count:
MS_REINDEX_MIN_INDEXED=100 scripts/ms-reindex.sh
ms list -O jsonl --limit 1000  # counting / enumeration
ms config                      # resolved config + skill_paths

输出规范

• 路径： 搜索、加载和管理结果会返回到标准输出；持久化索引状态保留在 ~/Library/Application Support/ms/ 下。
• 文件名： 此技能不会创建结果文件名；调用方需要持久化产物时，应显式捕获 CLI 输出。
• 格式： 已连接的 MCP 会返回结构化工具数据；一次性辅助脚本会将 MCP 内容解包为干净的搜索 JSON；CLI 自动化使用 JSON 或 JSONL，ms load --full -O json 的完整技能文本位于 .data.content。
• 验证命令： 运行 skills/ms/scripts/validate.sh 验证检索边界，并运行 scripts/ms-reindex.sh --check-source 验证规范化后的源内容是否等效。
• 下游交接： 将加载的指导内容及源标识交给调用方。检索绝不会选择或启动工作流。

生产技能交接

生产用途的交接： 查询涉及创建或编辑技能时，ms 会检索相关指导并停止。调用方可另行调用 skill-builder（创建、修复或审计模式）或其他创作工具。

权威边界： skills/** 是规范源；生成器负责生成 ms Codex 副本及其他投影。绝不要将索引、已加载的副本或生成的投影作为源来编辑。

ms 绝不会验证或解释下游工作。搜索、 加载、写入或重新索引失败时，会将其作为证据返回，并结束本次调用。

结果记录时机： 只有在调用方掌握关于下游实用性的独立证据后，才记录 ms outcome；绝不要仅在检索后记录。该观察不会改变核心状态。

---

陷阱（截至 2026-07-15 的实测）

陷阱	事实
MCP 服务在数据库清除／重新索引后仍存活	ms mcp serve 永远不会重新打开句柄——它会跟随重命名后的 inode 进入备份，导致读取过时数据，并静默地将写入定向到错误位置（把 recorded:true 写入孤立文件）。通过 scripts/ms-reindex.sh 重新索引——这是重新索引的唯一正确方式（重建索引，证明每个实时发现的技能都已编入索引，或已报告为允许的错误；终止每个服务，探测一个新服务，然后将规范化后的本地加载结果与当前 skills/** 源文件进行比较）；切勿直接运行 ms index 后让服务继续运行。会话会重新生成全新的服务。
ms load --pack N	陷阱：无论 N 为何，都会限制在被削减的 overview 层级（800 == 20000）——丢弃可执行步骤，返回的内容比不带标志的默认结果还少。使用 --full（CLI）或 full: true（MCP）。
-O plain	在 load 时只打印名称；截断列表输出（[N more lines]）。内容位于 -O json → .data.content。
CLI ms search 的“混合”搜索	实际上仅为 BM25——ms 从不存储文档嵌入（upsert_embedding 只在单元测试中调用），因此无论使用哪种后端，混合搜索 ≡ BM25；更改配置／后端都无法解决（上游缺陷，已注明为功能问题；实测于 2026-07-02，age-s3jf）。即使 MCP BM25 返回了排序后的匹配结果，它也可能返回零结果。未附加工具时，请使用 scripts/mcp-search.py；切勿将 CLI 的零结果视为成功的 MCP 回退。
过期的 ms.lock	对于已死亡的 pid，ms doctor 会打印“Lock held”，但仍报告全部检查通过。可以安全删除死 pid 的锁。
符号链接	ms 不会跟随目录符号链接——skill_paths 必须显式列出这两个根目录：~/.claude 技能目录和 ~/dev/agentops/skills 仓库目录。
二进制文件	仅从源码构建（~/dev/meta_skill，分支 local/frontmatter-id）；0.1.2 发行版二进制文件会破坏 Anthropic-frontmatter 技能的 ID。更新：git fetch && git rebase origin/main && cargo install --path . --locked。

并发

实测并行 CLI + MCP load 表现正常——没有锁错误。锁风险在于上文提到的清除后仍存活的情况（终止 serve），而不是并发读取。

---

场景

Scenario: Load a skill's full runnable guidance
  Given an ms mcp serve is attached
  When I call mcp__ms__load {skill: "account-rotation", full: true}
  Then the full runnable SKILL.md content is returned in one call

Scenario: Search without an attached MCP tool
  Given mcp__ms__search is unavailable
  When I run python3 skills/ms/scripts/mcp-search.py with the query
  Then it returns only structured MCP search JSON
  And its disposable ms mcp serve process is reaped on success, error, or timeout

Scenario: Reindex invalidates every running server
  Given one or more ms mcp serve processes are running
  When I run ms index (or wipe/rebuild the DB)
  Then I kill every ms mcp serve so sessions respawn against fresh data
  And a surviving server would silently read pre-wipe data and mis-land writes

Scenario: A stale local projection fails closed
  Given AgentOps skills are authoritative and ms is a disposable local index
  When a full ms load has a different normalized name or description from source
  Then scripts/ms-reindex.sh exits nonzero and names the stale skill

质量检查清单

• 完整加载会保留完整且可执行的指导内容，而非元数据卡片或打包后的概述。
• 搜索读取使用已附加的 MCP 工具或一次性 MCP 辅助脚本，绝不静默地以零结果 CLI 搜索替代；完整加载使用 MCP 或经过验证的 CLI 格式。
• 任何重建都应纳入每个实时发现的技能，拒绝空的可搜索索引，并在结束时清理过期服务并报告与源文件的一致性。
• 检索后，生产技能的意图应离开 ms；生成的副本和已加载／编入索引的副本绝不能作为源文件手动编辑。
• 搜索和加载结果始终只是参考输入，不能证明下游工作正确。
• 只有在获得独立的下游证据后，ms outcome 才记录观察到的效用。

参考资料

• 上游项目：Jeffrey Emanuel 的 meta_skill（源码位于 ~/dev/meta_skill，分支 local/frontmatter-id）。
• 此仓库中相关的使用工具技能：cass（会话考古）。jsm cass-memory（cm）程序性记忆工具是写入侧的补充工具（单独安装，不在此仓库中）。
• 生命周期契约验证器：scripts/validate.sh。