1. 摘要

SeekMoon 是一个面向 MoonBit 消费者的本地包发现工作台。它读取 Mooncakes 公开 API、Mooncakes 静态资产、本地 MoonBit 工具链、本地 registry/cache、当前项目上下文、repository 信号和本地调查记录，把候选发现、证据下钻、API 阅读、源码定位、skill 识别、本地验证、采纳记录和报告输出组织为一组低噪声 CLI 动作。

本书定义 SeekMoon 的证据来源边界、canonical 数据模型、命令契约、输出契约、行动轨迹和验收条件。默认 pretty text 服务终端阅读，JSON 和内置 jq 服务机械处理，shape 和 schema 服务输出契约学习。

版本说明

本文档是 SeekMoon 的独立书籍。

书名：SeekMoon：MoonBit 包发现工作台。

版本：v1.0。

修订日期：2026-06。

文档形态：AsciiDoc book。

公共事实来源以书中参考文献、来源图和可复查 URL 为准。易变 API 字段和计数只在带观测日期的上下文中成立。

前言

MoonBit 包消费者在引入依赖之前，需要识别候选包、理解候选包、比较候选包，并把判断保留为可复查记录。Mooncakes 和 MoonBit 工具链已经提供多个事实表面；消费者侧仍需要一个本地工作台把这些事实表面组织成稳定行动。

依赖消费者沿 Library Discovery Journey 阅读一次完整调查。工具实现者从 Public HTTP Sources、Static Assets、Local Toolchain and Cache、Evidence State Values 和 Command Map 进入公共契约。自动化消费者重点阅读 JSON Output、Built-in jq、Shape Output 和 Schema Output。工具设计者从 CLI Workbench Environment 进入，观察命令结构、输出契约和状态记录如何形成工作台环境。

本书中的命令、字段和状态词构成 SeekMoon 的公共对象。公共对象之外的实现细节不参与读者对工具行为的依赖。

Part I: 工具对象与行为场景

本部定义 SeekMoon 的问题世界、人工制品边界、消费者动作和 CLI 工作台环境。后续证据来源、数据模型、命令和输出契约都以这里的对象边界为前提。

2. MoonBit 包发现处境

MoonBit 包消费者面对的对象不是空白生态。MoonBit 工具链、Mooncakes registry、Mooncakes documentation surface、Mooncakes public API、本地 registry index、registry cache、moon add、moon fetch、moon runwasm 和 Skills API 已经提供多个事实表面。Mooncakes MoonBit

这些事实表面分别回答不同问题。Modules API 给出 module 列表和声明性摘要。Manifest API 给出单个 module 的版本、下载量、build status 和 metadata。module_index.json 给出 module 内 package tree 和紧凑 API index。package_data.json 给出单 package 的类型、函数、trait、docstring、signature 和 source location。moon fetch 获取发布版源码。Skills API 给出可执行 Wasm 或 moon runwasm 条目。

消费者的摩擦来自行动链路，而不是单个事实源缺席。一个开发者寻找 Markdown parser、JSON parser、CLI argument parser 或 terminal output library 时，需要连续完成以下动作：

  • 从功能词生成候选集合。

  • 区分 library module 和 executable skill。

  • 查看候选的 description、license、repository、downloads、build status 和版本。

  • 读取 module 内 package 与 API 结构。

  • 定位发布版源码、测试和示例。

  • 比较多个候选的功能范围、证据完整度和本地可验证性。

  • 在当前 target 或隔离 probe 项目中执行 moon add、moon check、moon test 和 target build。

  • 保存引入、拒绝或继续验证的判断。

这些动作如果散落在 Web 页面、curl、jq、临时 shell 脚本、GitHub 页面、本地 cache 和 probe 项目之间，消费者的主要工作会从“判断包”滑向“拼接调查环境”。包发现工作台的职责，是把这些事实表面组织成稳定动作，使消费者把注意力放回候选判断。

事实表面 回答的问题 不能替代的对象

Modules API

有哪些可见 module，module 的声明性摘要是什么。

不能替代单 module manifest、API 结构、本地 target 验证。

Manifest API

某个 module 的版本、下载量、build status、metadata 和 versions 是什么。

不能证明任意 target 可构建，不能替代源码阅读和 probe。

Module index asset

module 内有哪些 package、类型、函数、trait 和方法摘要。

不能替代单 package 的完整 docstring、signature 和 source location。

Package data asset

某个 package 的 API 详情是什么。

不能替代本地编译验证，也不能替代维护状态判断。

moon fetch

如何按发布坐标获取 published source。

不能替代依赖采纳，也不能证明包适合当前项目。

Skills API

有哪些 executable Wasm / skill entry。

不能替代 library dependency discovery。

SeekMoon 处理的是引入依赖之前的消费者侧 discovery 工作。它不把安装成功等同于采纳成功，也不把下载量、build status 或 repository presence 解释为质量证明。采纳判断必须回到消费者上下文、证据来源和本地验证。

3. SeekMoon

SeekMoon 是面向 MoonBit 消费者的本地 package discovery workbench。它读取公开 API、静态资产、本地工具链、本地缓存、当前项目上下文、repository signal 和本地记录，把分散的包发现事实投影为可执行的 CLI 动作。

SeekMoon 的对象边界由六类输出对象构成：

  • Candidate：由查询产生的 library module 或 skill entry 候选。

  • Module profile：单个 library module 的证据画像。

  • API profile：单个 package 的 API 结构证据。

  • Source resolution：发布版源码定位结果。

  • Probe result：本地工具链验证结果。

  • Adoption record 和 report：采纳判断及其可复查输出。

这些输出对象共同支撑消费者在引入依赖之前的判断。search 产生候选集合；view 展示 module profile；api 展示 API profile；source 定位 published source；skill 处理 executable Wasm 条目；compare 放置多个候选；probe 生成本地验证证据；record 保存采纳判断；report 输出调查记录。

SeekMoon 的命令模型只包含 evidence sources 能产生的字段，以及 SeekMoon 能从已读取事实派生的字段。没有进入命令模型的对象不出现在 pretty text、JSON output、shape 或 schema 中。

对象 SeekMoon 的责任 输出投影

Candidate

从查询、kind、target 和 snapshot 生成候选集合。

Pretty table、JSON SearchResult。

Module profile

汇集 manifest、metadata、docs URL、module index 和来源状态。

view 输出、JSON ManifestProfile。

API profile

读取 package API 结构、docstring、signature 和 source location。

api 输出、JSON PackageData projection。

Source resolution

定位与发布版本对应的源码材料。

source 输出、JSON SourceResolution。

Probe result

执行本地验证并保存命令状态。

probe 输出、JSON ProbeResult。

Adoption record

保存候选、版本、结论、证据引用和未确认事项。

本地 record JSON、report。

SeekMoon 的公共行为不由内部实现目录定义，而由命令契约和输出契约定义。命令契约见 Command Map；输出契约见 Pretty Text、JSON Output、Shape Output 与 Schema Output。

4. Consumer Actions

SeekMoon 按动作区分 consumer。开发者、脚本、CI 作业和 Code Agent 都按当前动作消费对应输出表面；consumer 类型不由主体身份固定。

Terminal reader 读取默认 pretty text。它需要低噪声、稳定列和足以支持下一步判断的事实。开发者和正在观察终端输出的 Code Agent 都可以承担 terminal reader 动作。

Pipeline consumer 处理 JSON output 或 jq result。它需要字段稳定、状态词明确、来源可追溯。Shell pipeline、脚本、CI job、report generator 和一次性 jq 表达式都可以承担 pipeline consumer 动作。

Contract reader 读取 help、shape 或 schema。它需要知道当前命令输出哪些字段、字段类型是什么、状态枚举是什么、JSON Schema 如何校验。Contract reader 的动作发生在写自动化、第一次使用命令或审查输出契约时。

Failure recovery consumer 读取 error surface。它需要知道失败发生在哪个来源、失败状态是什么、该失败是否表示对象不存在、可执行的恢复动作是什么。

Consumer action 读取表面 需要的信息 不需要的信息

终端判断

Pretty text

候选、关键字段、状态、短路径。

完整 raw payload、字段树、重复教程。

机械处理

JSON output、jq result

稳定字段、状态、来源、错误对象。

屏幕排版、宽表对齐。

契约学习

Help、shape、schema

命令语义、字段树、类型、枚举、JSON Schema。

具体调查结果。

失败恢复

Error surface

失败来源、状态含义、恢复动作。

正常工作流说明。

默认 pretty text 和 JSON output 是同一内部对象的不同 projection。Pretty text 不承担机器解析职责；JSON output 不承担终端排版职责。Shape 和 schema 不是业务结果，它们是输出契约表面。

这个动作划分约束命令设计。search 不展开 API 详情，因为终端判断动作只需要候选集合。api 不重新执行搜索，因为 API 阅读动作已经有确定候选。probe 不修改上游事实，因为本地验证只产生 local derived evidence。

5. CLI Workbench Environment

Package discovery workbench 是行为场景，不是提示文本集合。SeekMoon 的环境由命令名、参数、默认输出列、编号引用、snapshot、record、help、shape、schema、error surface 和本地文件边界共同构成。

媒介环境理论说明，工具不是中立管道。命令行工具改变消费者观察对象、形成动作顺序、定义哪些事实容易被看见。生态心理学中的 affordance 说明，人工制品通过形状和标记提供行动条件。HCI 中的 signifier 说明，设计表面可以在无需反复解释的情况下指示动作。CLI 中的 signifier 是命令名、参数名、输出列和状态词。

SeekMoon 的命令结构与消费者动作同形：

消费者动作 命令表面 环境作用

生成候选集合

seekmoon search

把查询词转成 candidate list。

查看单候选证据

seekmoon view

把 module 坐标转成 module profile。

阅读 API

seekmoon api

把 package path 转成 API profile。

定位发布源码

seekmoon source

把 module version 转成 source resolution。

识别 executable skill

seekmoon skill

把 skill query 或 entry 转成 skill profile。

比较候选

seekmoon compare

把多个候选放入同一证据表面。

本地验证

seekmoon probe

把候选放入本地工具链验证场景。

保存判断

seekmoon record

把判断写成 adoption record。

输出报告

seekmoon report

把调查轨迹投影为 report。

正常命令输出只投影当前动作需要的事实。学习动作由 README、top-level help、subcommand help、shape 和 schema 承担。失败恢复动作由 error surface 承担。这个分工让工作台保持低噪声，同时保留完整契约。

编号引用也是环境的一部分。一次 search 产生的候选可以在同一 session 中被 view 1、api 1、compare 1 2 3、probe 1 和 record 1 消费。编号引用减少复制 module coordinate 的局部摩擦，但编号只在 snapshot 和 session 边界内有效。

Snapshot 和 record 让行为场景跨命令保持连续。Snapshot 固定数据口径；record 固定采纳判断；report 把二者组合为可复查文档。没有 snapshot，搜索结果只是瞬时屏幕文本；没有 record，调查结论无法进入长期维护。

CLI 工作台的质量由行动轨迹检查。Library Discovery Journey、Skill Discovery Journey 和 Black-box Acceptance 给出可检查行为。

Part II: 证据来源边界

本部定义 SeekMoon 当前读取的 evidence sources。每个来源只回答它能回答的问题；来源之间不能互相冒充。

6. Public HTTP Sources

Evidence Source SeekMoon 的 public HTTP sources 来自 Mooncakes 公开 API。它们提供 registry 可见数据、单 module 详情、统计快照和 skill entry 列表。HTTP source 的读取结果进入 snapshot，并带有 fetch time、URL、status 和 parse state。

6.1. Modules API

GET https://mooncakes.io/api/v0/modules

Modules API 是 library module search 的基础 input surface。它返回 module summary array。SeekMoon 从该数组读取 module coordinate、version、description、keywords、repository、license、created_at 和 newness flag。

字段 SeekMoon 解释 状态规则

name

完整 module coordinate。

非空值为 present；缺失或空值使该 record 不进入普通候选集合。

version

列表层当前版本。

非空值为 present。

description

作者声明的用途摘要。

空字符串为 missing。

keywords

作者声明的检索词。

空数组为 missing。

repository

源码仓库或维护入口声明。

空字符串为 missing。

license

作者声明的 license 字符串。

空字符串为 missing。

Modules API 不提供 downloads、build status、package tree、API details、target proof、source files、repository activity 或 vulnerability status。search 可以把 modules array 本地过滤和排序；它不能把 list-level fields 解释为完整 package assessment。

6.2. Statistics API

GET https://mooncakes.io/api/v0/modules/statistics

Statistics API 给出 registry 快照规模。SeekMoon 在 sync 和 report 中记录这些计数，用于说明调查时的数据口径。

字段 含义

total_modules

统计口径下的 module 数。

total_packages

统计口径下的 package 数。

total_lines

统计口径下的代码行数。

total_downloads

统计口径下的下载次数。

这些计数是 snapshot value。它们随时间变化，不参与单个候选的质量判断。

6.3. Manifest API

GET https://mooncakes.io/api/v0/manifest/<owner>/<module>

Manifest API 是 view、compare、source 和 asset URL construction 的核心来源。它把单个 module 的 registry profile 暴露为 manifest object。

字段 SeekMoon 用途 边界

module / name

确认 module coordinate。

二者不一致时进入 failure surface。

version

构造 asset URL 和 source resolution。

不是用户项目中的 locked version。

latest_version

显示 latest state。

不替代当前查询指定版本。

downloads

社会使用信号。

不是质量、安全或适配证明。

has_package

Mooncakes package/docs asset 相关状态。

不等于本地可采用。

build_status

Mooncakes 构建或文档相关状态。

不证明所有 target 构建成功。

metadata

开放 metadata object。

不能按闭合 schema 解释。

versions

版本列表和 yanked state。

版本数量由 SeekMoon 派生。

Manifest metadata 是开放对象。当前已知字段拼写包括 repository、license、description、keywords、checksum、readme、deps、source、preferred target 和 supported targets。SeekMoon 只规范化已知字段，并保留 raw metadata 供 JSON 和 raw surface 使用。

6.4. Skills API

GET https://mooncakes.io/api/v0/skills
GET https://mooncakes.io/api/v0/skills/<entry>

Skills API 提供 executable Wasm 或 moon runwasm 条目。Skill entry 属于 execution object，不属于 library dependency candidate。skill search 和 skill view 消费该来源。

字段 SeekMoon 用途 边界

module

所属 module coordinate。

不说明该 module 适合作为 library dependency。

version

skill 发布版本。

未 pin 的 runwasm input 必须解析出版本后记录。

package

executable package path。

空字符串可表示 root/default package marker。

name

skill entry 名称。

可用于 skill search 和 display。

wasm_url

Wasm artifact asset。

不证明 library API 可用。

checksum_url

Wasm checksum asset。

checksum 不等于 provenance。

metadata

skill metadata。

内部字段稀疏，空字符串为 missing。

Skill source 的输出进入 SkillEntry 和 SkillProfile，见 SkillEntry。

7. Static Assets

Mooncakes static assets 把 documentation surface 和 executable surface 暴露为 JSON、Markdown、Wasm 和 checksum 文件。SeekMoon 不抓取 rendered SPA 页面；它读取 asset URL 和 public API payload。

7.1. Module Index Asset

GET https://mooncakes.io/assets/<owner>/<module>@<version>/module_index.json

module_index.json 是 module package tree 与紧凑 API index。view 使用它生成 package count、package list 和 API summary；api 使用它解析 package path 和 package relpath。

当前 asset node 使用 childs 表示子节点。SeekMoon 读取 childs，并可在解析层兼容 children，但书中当前事实表面以 childs 为准。

对象 用途

node name

tree node 名称。

node package

package summary object 或 null。

node childs

子节点数组。

package path

完整 package path。

package types / values / traits

紧凑 API summary。

package methods

type summary 内的方法摘要。

Package relpath 必须从 package path 派生。moonbitlang/core/argparse 相对 moonbitlang/core 的 relpath 是 argparse。Root package 的 relpath 为空。

7.2. Package Data Asset

GET https://mooncakes.io/assets/<owner>/<module>@<version>/<package-relpath>/package_data.json

package_data.json 是单 package API 详情来源。它提供 type、value、trait、error、typealias、misc、docstring、signature 和 source location。

字段 用途 状态规则

name

package 名称。

非空为 present。

types

类型 entry 数组。

空数组表示该类别没有 symbol。

values

函数或 value entry 数组。

空数组表示该类别没有 symbol。

docstring

文档注释。

空字符串为 missing。

signature

上游签名字符串。

raw signature 必须保留。

loc

源码位置。

缺失为 missing。

signature 可包含 HTML link。Plain text signature 是 SeekMoon 派生 projection，不替代 raw signature。

7.3. Resource Asset

GET https://mooncakes.io/assets/<owner>/<module>@<version>/<package-relpath>/resource.json

resource.json 是可选资源资产。它可提供 README content 和 source file links。resource.json 404 的状态是 unavailable，不表示 package 缺失，不表示 API data 缺失，也不表示 module 不存在。

resource.json 的状态进入 view、api 或 report 时必须带 source label。Module index 与 package_data.json 提供 API 证据；published source 提供源码证据。

7.4. Source Zip

GET https://download.mooncakes.io/user/<owner>/<module>/<version>.zip

Source zip 是 published source 的一种来源。请求需要跟随重定向。下载成功时，SeekMoon 可读取 module config、package config、README、LICENSE、.mbt 源码、tests、examples 和 benches 等材料。

Source zip 失败不表示 module 不存在。source 命令继续检查 moon fetch、local registry cache、core local source 或 repository signal。Source resolution 见 SourceResolution。

7.5. Skill Assets

Skills API 给出 wasm_url 和 checksum_url。Skill detail surface 可读取 SKILL.md。

资产 用途

SKILL.md

skill 的人类可读说明。

wasm_url

可执行 Wasm artifact。

checksum_url

Wasm artifact checksum。

Wasm checksum 只说明 artifact 内容可校验，不说明发布身份、构建来源或无漏洞状态。

8. Local Toolchain and Cache

SeekMoon 是本地工作台。它读取 MoonBit 工具链、本地 registry index、registry cache 和 core source。Local sources 让 SeekMoon 能执行 registry 更新、发布源码定位和本地验证。

8.1. Moon Commands

命令 SeekMoon 用途 边界

moon --version

记录工具链版本。

版本信息不是功能完整性证明。

moon update

更新本地 registry 材料。

网络失败或部分失败进入 sync error surface。

moon fetch <module[@version]>

获取 registry 发布源码到 .repos。

该动作修改当前项目或 probe 边界。

moon add <module>

验证依赖引入。

安装成功不等于采纳成功。

moon check / moon test

验证当前工具链下的检查和测试。

验证结果受本地工具链和项目上下文影响。

moon build --target <target>

验证目标 target 构建。

只证明该环境、该版本、该 target 下的结果。

moon runwasm <coordinate>

运行本地或 Mooncakes Wasm asset。

属于 skill/executable 路径。

SeekMoon 调用本地命令时必须记录 command、cwd、environment summary、exit status 和 log path。命令失败不改写上游事实。

8.2. Local Registry Index

~/.moon/registry/index/user/**/*.index

Local registry index 是 JSON Lines。每一行是一个 module version record。它比 Modules API 更接近原始发布记录，也更松散。SeekMoon 用它做 offline search、cross-check 和 raw audit surface。

Local index 可包含 name、version、checksum、license、created_at、repository、readme、keywords、description、deps、source、preferred target、supported targets、include/exclude、authors 等字段。SeekMoon 只规范化当前模型字段，并保留 raw line。

8.3. Registry Cache and Core Source

~/.moon/registry/cache/**
~/.moon/registry/cache/assets/**
~/.moon/lib/core/**

Registry cache 保存已下载的 source zip、registry payload 或 assets。Assets cache 可保存 moon runwasm 下载的 Wasm artifact。Core source 提供本地标准库源码。

source 命令在 HTTP source 或 moon fetch 失败后可检查 local cache。Local cache 命中是当前机器事实，不代表其他机器具备同一缓存。

9. Project Context

Project context 是 SeekMoon 当前运行目录中的 MoonBit 项目事实。它为 search、probe、record 和 report 提供消费者上下文。

moon.mod
moon.mod.json
moon.pkg
moon.pkg.json

SeekMoon 从项目上下文读取 module identity、dependency declarations、package configuration、target hints 和 workspace boundary。读取失败不阻止全局 search，但会影响 contextual probe 和 report。

上下文 用途 边界

Project root

确定命令工作目录和本地记录位置。

不能跨出明确项目边界修改文件。

Module config

读取当前项目身份和依赖声明。

格式差异由 parser 层处理。

Package config

读取 package 与 target 相关上下文。

不能替代候选包 target 证据。

Declared target

作为 search display 或 probe 参数。

没有 evidence 时不能推出候选支持该 target。

Existing dependencies

报告当前项目已引入状态。

不替代 moon tree 或 resolver 结果。

Probe mutation 必须有明确边界。默认 probe 使用 SeekMoon 创建的隔离目录，例如 .seekmoon/probes/<id>。在当前项目中直接执行 moon add 或修改 manifest 需要明确命令表面表达。Probe result 是 local derived evidence；它不修改 Mooncakes、repository 或 module metadata。

Project context 也决定 record storage。.seekmoon/records 和 .seekmoon/reports 属于当前项目的调查记录空间。跨项目复用 record 时必须保留原 project identity 和 snapshot id。

10. Repository Signals

Repository signal 是来自 GitHub 或其他源码仓库的维护与协作证据。SeekMoon 只在 Mooncakes metadata 或 module summary 给出 repository，并且命令实际请求 repository 后，才把这些字段写入输出对象。

Repository signal 回答维护问题：

  • repository 是否可访问。

  • repository 是否 archived。

  • 默认分支最近更新时间。

  • release、issue、PR、CI workflow 是否存在。

  • README、tests、examples、license 文件是否可见。

  • main branch 是否包含未发布变化。

Repository signal 不回答发布事实问题。Registry 发布版本的 published source 优先来自 moon fetch、source zip、local cache 或 core local source。Repository main branch 与 registry 发布版本可以处在不同提交、不同文件集合或不同发布节奏中。

字段 用途 边界

is_archived

维护风险信号。

archived 不解释 registry 包是否仍可安装。

pushed_at

近期维护活动信号。

不是 release timestamp。

licenseInfo

仓库 license 信号。

registry metadata license 仍需单独保留。

CI workflows

工程实践信号。

CI 存在不证明当前 release 通过所有 target。

issues / PRs

协作和问题活动信号。

数量不能直接解释为质量。

README / tests / examples

结构性和使用证据。

repository 文件不必然包含在发布源码中。

Repository enrichment 失败不使 module profile 失败。它只使 repository signal state 变为 failed 或 unknown。默认 search 不请求 repository enrichment；view、compare 或 report 可以显式加载这些信号。

Part III: Canonical 数据模型

本部定义 SeekMoon 的 canonical objects。Evidence sources 提供原始事实；canonical objects 规定 SeekMoon 如何保存、规范化、派生和投影这些事实。

11. Evidence State Values

Evidence state 描述字段值和来源动作的当前状态。状态词用于 JSON output、shape、error surface、record 和 report。Pretty text 只在状态影响当前动作时显示。

状态 定义 例子

present

来源成功给出有效值。

Manifest license 为 MIT。

missing

来源存在字段位置，但值为空字符串、空数组、null 或字段缺失。

Modules API description 为空字符串。

unknown

当前问题需要判断，但已读取来源不能回答。

用户请求 --target js，manifest 和 local index 都没有 target metadata，probe 也未运行。

failed

请求、命令或解析动作已经执行并失败。

Manifest API 返回非 2xx；moon fetch 退出非零；JSON parse 失败。

unavailable

可选来源不存在，或当前对象没有该可选资产。

resource.json 返回 404。

derived

SeekMoon 从当前事实计算得到。

versions_count、search rank、package relpath、runwasm coordinate。

missing 与 unknown 分别回答不同问题。missing 表示某个来源给出的对象里没有值；unknown 表示当前判断没有证据来源可以回答。空 license 是 missing；没有 target evidence 是 unknown。

unavailable 与 failed 也不能混用。可选资源 404 是 unavailable；网络请求超时是 failed。unavailable 不必然中断命令；failed 是否中断由命令契约规定。

没有进入当前命令模型的对象不写入输出对象。状态词只用于命令模型中的字段和已执行来源动作。

字段类别 状态处理 输出行为

当前命令核心字段

必须有 state 或有效值。

Pretty text 显示影响判断的状态；JSON 保留完整 state。

可选 enrichment 字段

只在请求或加载后出现。

加载失败时 JSON 保留 failure；pretty text 视命令而定。

派生字段

标记为 derived 或带 source expression。

JSON 保留派生来源；pretty text 显示结果。

命令模型外对象

无状态。

不进入 pretty text、JSON、shape 或 schema。

Error surface 使用同一组状态词。错误输出见 Error Surface。

12. ModuleSummary and SearchResult

ModuleSummary 是 Modules API item 的 canonical projection。它服务 search、sync、compare 的候选入口。

字段 类型 来源 含义

module

string

Modules API name

完整 owner/module coordinate。

version

string

Modules API version

列表层当前版本。

description

evidence string

Modules API description

用途摘要；空字符串为 missing。

keywords

evidence string array

Modules API keywords

检索词；空数组为 missing。

repository

evidence string

Modules API repository

repository declaration；空字符串为 missing。

license

evidence string

Modules API license

license declaration；空字符串为 missing。

is_new

boolean

Modules API is_new

Mooncakes list-level newness flag。

created_at

string

Modules API created_at

上游时间字符串。

raw

object

Modules API item

原始 item，JSON/raw surface 保留。

12.1. SearchResult

SearchResult 是 search 命令的候选输出对象。它把 ModuleSummary、query、rank 和 match evidence 组合为候选结果。

字段 类型 含义

rank

integer

SeekMoon 派生排序位置。

module

string

候选 module coordinate。

version

string

候选版本。

description

evidence string

用途摘要。

keywords

evidence string array

检索词。

license

evidence string

license declaration。

repository

evidence string

repository declaration。

downloads

evidence integer

Manifest enrichment 提供的下载量；未加载时不进入默认 pretty text。

build_status

evidence string

Manifest enrichment 提供的 Mooncakes build status。

target

evidence object

只在 query 请求 target 上下文时进入结果。

match

object

命中字段、token、score component 或 explainable rank evidence。

snapshot_id

string

产生该结果的 snapshot。

Pretty text 的 search 表只展示终端判断需要的摘要列。JSON output 保留 match，用于复查和 pipeline processing。match 是搜索对象的一部分，不是质量评分。

search 先使用 modules snapshot 生成候选集合，再为默认可见结果窗口读取 Manifest API enrichment。downloads 和 build_status 来自该 enrichment；enrichment 失败时对应字段带 failed state。

Skill search 使用 SkillEntry，不复用 ModuleSummary。Skill model 见 SkillEntry。

13. ManifestProfile

ManifestProfile 是 Manifest API object 的 canonical projection。它服务 view、compare、source、record 和 report。

字段 类型 来源 含义

module

string

Manifest module / name

完整 module coordinate。

version

string

Manifest version

当前 manifest 版本。

latest_version

string

Manifest latest_version

上游声明的 latest version。

downloads

integer

Manifest downloads

下载量信号。

has_package

boolean

Manifest has_package

Mooncakes package/docs asset 相关状态。

build_status

evidence string

Manifest build_status

Mooncakes build status；null 为 missing。

metadata

object

Manifest metadata

开放 metadata object。

versions

array

Manifest versions

版本列表。

versions_count

derived integer

versions.length

版本数量。

docs_url

derived string

module coordinate

Mooncakes docs URL。

Manifest metadata 是开放对象。SeekMoon 规范化以下字段，并保留 raw metadata：

Canonical 字段 来源拼写 规则

description

description

空字符串为 missing。

keywords

keywords

空数组为 missing。

repository

repository

空字符串为 missing。

license

license

空字符串为 missing。

checksum

checksum

checksum 字符串不等于 provenance。

deps

deps

object map 形态进入 canonical field。

preferred_target

preferred-target、preferred_target、preferred-backend

保留 source spelling。

supported_targets

supported-targets、supported_targets、targets

接受 string 或 array，并派生 array projection。

Target metadata 只说明上游声明或 index 记录。Target support 没有证据时是 unknown；probe 成功后才有 local derived target evidence。

14. API Profile

API profile 由 ModuleIndexTree 和 PackageData 组成。view 使用 module index 生成 package summary；api 使用 package data 生成 API details。

14.1. ModuleIndexTree

ModuleIndexTree 来自 module_index.json。它是 package tree 和紧凑 API index。

字段 类型 含义

name

string

Tree node 名称。

package

object/null

Package summary object。

childs

array

子节点数组。

package.path

string

完整 package path。

package.relpath

derived string

相对 module root 的 package path。

traits

array

Trait summary。

errors

array

Error summary。

types

array

Type summary。

typealias

array

Type alias summary。

values

array

Value/function summary。

misc

array

Misc summary。

Package relpath 由 package.path 和 module coordinate 派生。package_data.json URL 必须使用 module index 派生出的 relpath。

14.2. PackageData

PackageData 来自 package_data.json。它是单 package API 详情来源。

字段 类型 含义

name

string

Package name。

traits

array

Trait entries。

errors

array

Error entries。

types

array

Type entries。

typealias

array

Type alias entries。

values

array

Function/value entries。

misc

array

Misc entries。

Type、value 和 method entry 使用共同字段：

字段 类型 含义

name

string

Symbol name。

docstring

evidence string

Docstring；空字符串为 missing。

signature

string

Raw upstream signature。

plain_signature

derived string

SeekMoon 派生的 plain text signature。

loc

evidence object

Source location，包括 path、file、line、column。

methods

array

Type methods。

impls

array

Type implementations。

15. SkillEntry

SkillEntry 是 Skills API item 的 canonical projection。它服务 skill search、skill view、runwasm coordinate 生成和 skill report。

字段 类型 来源 含义

module

string

Skills API module

所属 module coordinate。

author

string

Skills API author

作者或 owner。

author_avatar

evidence string

Skills API author_avatar

空字符串为 missing。

version

string

Skills API version

skill entry 版本。

package

string/root marker

Skills API package

executable package path；空字符串表示 root/default marker。

name

string

Skills API name

entry 名称。

detail_url

string

Skills API detail_url

skill detail relative URL。

wasm_url

string

Skills API wasm_url

Wasm artifact URL。

checksum_url

string

Skills API checksum_url

Checksum URL。

metadata

object

Skills API metadata

开放 metadata object。

repository

evidence string

Skills API repository

repository declaration。

created_at

string

Skills API created_at

上游时间字符串。

SkillProfile 在 SkillEntry 上增加 SKILL.md、asset fetch states 和 runwasm_coordinate。

字段 类型 含义

skill_md

evidence string

SKILL.md 内容；缺失或请求失败按状态词记录。

wasm_asset

evidence object

Wasm asset 的 fetch state。

checksum_asset

evidence object

Checksum fetch state。

runwasm_coordinate

derived string

Pinned moon runwasm coordinate。

SkillEntry 与 library module 使用不同采纳路径。Skill 可记录执行验证；library module 记录依赖引入验证。

16. SourceResolution and ProbeResult

SourceResolution 记录 SeekMoon 如何定位 published source。ProbeResult 记录 SeekMoon 如何在本地验证候选。

16.1. SourceResolution

字段 类型 含义

module

string

Module coordinate。

version

string

目标版本。

moon_fetch

source attempt

moon fetch 状态、path、error。

source_zip

source attempt

Source zip 状态、path、final URL、error。

local_cache

source attempt

Local registry cache 状态和 path。

core_local_source

source attempt

Core 本地源码状态和 path。

repository_source

source attempt

Repository fallback 状态、URL 或 path。

selected_source

object

当前选中的 source method 和 path。

files_summary

object

文件类别摘要。

Source attempt 使用共同字段：

字段 类型 含义

status

state value

present、failed、unavailable 或 unknown。

path

string/null

本地路径。

url

string/null

远程 URL。

error

string/null

失败信息。

Repository fallback 必须标记为 repository signal，不标记为 registry published source。

16.2. ProbeResult

ProbeResult 是 local derived evidence。它由 probe 命令产生。

字段 类型 含义

module

string

候选 module。

version

string

候选版本。

target

string/null

验证 target。

probe_path

string

隔离 probe 目录。

moon_new

command result

创建 probe 项目状态。

moon_add

command result

引入依赖状态。

moon_check

command result

默认 check 状态。

moon_test

command result

默认 test 状态。

moon_check_target

command result

target check 状态。

moon_build_target

command result

target build 状态。

logs

object

日志路径。

result

string

verifiable、failed 或 incomplete。

Command result 包含 command、cwd、exit code、status、stdout/stderr log path。Probe 成功只证明当前环境、当前版本、当前 target 和当前命令序列下可验证。

17. AdoptionRecord and Report

AdoptionRecord 保存消费者判断。它把候选、版本、证据引用和结论写入项目调查记录。

字段 类型 含义

record_id

string

本地记录 ID。

created_at

datetime

记录创建时间。

project

object

项目 identity 和 path。

snapshot_id

string

关联 snapshot。

candidate

object

候选 module 或 skill entry。

version

string

记录版本。

conclusion

enum

采纳结论。

evidence_refs

array

manifest、API、source、probe、repository 等证据引用。

not_confirmed

array

未确认事项。

note

string

消费者备注。

Conclusion enum：

adopt
adopt-with-adapter
continue-verification
contribute-upstream
fork
build-own
reject-for-now

Pretty text 可以渲染中文标签；JSON output 使用稳定英文枚举。

17.1. Report

Report 是调查记录的文档 projection。它汇集 goal、date、toolchain、data sources、query、candidates、local validation、cannot-confirm items 和 conclusion。

章节 内容

Goal

调查目标。

Environment

工具链版本、snapshot、项目上下文。

Data sources

实际读取的来源。

Candidates

候选集合和关键证据。

Inspection

API、source、skill 或 repository 下钻结果。

Validation

probe 或执行验证结果。

Decision

AdoptionRecord 的结论和未确认事项。

Report 不添加未读取来源。没有执行 repository enrichment，就不写 repository activity。没有执行 probe，就不写 local validation 成功或失败。

Part IV: 命令工作台

本部定义 SeekMoon 的 CLI 命令表面。每个命令对应一个消费者动作，并产生一个可投影的 canonical object。

18. Command Map

Command map 是 SeekMoon 工作台的工具布局。命令按消费者动作分组。

分组 命令 消费者动作 主要输出对象

Data

doctor

检查本地环境。

Environment status。

Data

sync

创建数据 snapshot。

Snapshot。

Discovery

search

从 query 生成 library module candidates。

SearchResult array。

Discovery

skill

搜索或查看 executable skill entries。

SkillEntry / SkillProfile。

Inspection

view

查看单个 library module profile。

ManifestProfile with index summary。

Inspection

api

查看 package API profile。

API profile。

Inspection

source

定位 published source。

SourceResolution。

Assessment

compare

比较多个候选的证据。

Comparison table / JSON object。

Assessment

probe

执行本地工具链验证。

ProbeResult。

Recording

record

保存采纳判断。

AdoptionRecord。

Recording

report

输出调查报告。

Report。

Audit

raw

读取原始来源 payload。

带 source status 的 raw payload。

所有输出型命令支持 JSON Output。需要字段树时使用 Shape Output；需要 JSON Schema 时使用 Schema Output。

命令参数使用对象名，而不是底层 URL。消费者输入 query、module coordinate、package path、candidate number、target、record conclusion；SeekMoon 内部解析 API endpoint、asset URL、本地 path 和 cache。

19. seekmoon doctor

doctor 检查 SeekMoon 所需本地环境。它服务 failure recovery consumer 和第一次使用工具的 contract reader。

seekmoon doctor

doctor 读取本地 MoonBit 工具链、registry 路径、registry cache、network reachability、GitHub CLI 可用性和当前项目上下文。它不创建 snapshot，不更新 registry，不写 record。

检查项 输出

Toolchain

moon、moonc、moonrun、mooncake version。

Commands

moon fetch、moon add、moon check、moon test、moon build 是否可用。

Paths

registry index、registry cache、assets cache、core source。

Network

Mooncakes API 和 assets reachability。

Project

当前目录是否包含 MoonBit project context。

默认 pretty text 示例：

moon        0.1.20260608
moonc       v0.10.0
registry    present
network     mooncakes.io ok
project     MoonBit module detected

20. seekmoon sync

sync 创建 dated evidence snapshot。Snapshot 固定当前 API、statistics 和本地 index 口径。

seekmoon sync

sync 执行 moon update，读取 Modules API、Statistics API，统计 local index，并保存 snapshot file。

读取来源 写入 snapshot 的信息

Statistics API

module、package、line、download counters。

Modules API

module summary array fetch status 和 length。

Local registry index

index HEAD、file count、record count。

Toolchain

MoonBit toolchain versions。

默认 pretty text 示例：

snapshot  2026-06-21T22:35:10+08:00
modules   1350
packages  12008
index     1363 files

sync 失败时，error surface 指出失败来源。部分来源失败时，snapshot state 记录 partial result；依赖该来源的后续命令必须读取状态。

search 从 query 和 snapshot 生成 library module candidates。它依赖 ModuleSummary 和 SearchResult。

seekmoon search markdown
seekmoon search markdown --target js

search 默认读取最新 snapshot 中的 Modules API array。没有可用 snapshot 时，它读取 Modules API 并创建 transient snapshot。Query 匹配 module name、description、keywords 和 repository declaration。候选排序完成后，search 为默认可见结果窗口读取 Manifest API enrichment，以填充 downloads 和 build_status。

输入 含义

query

功能词、格式名、包名或相邻关键词。

--target <target>

把 target 放入候选显示和 JSON context。

--limit <n>

限制候选数量。

candidate number

后续 view、api、compare、probe、record 的 session-local 引用。

默认输出只显示候选判断所需字段：

Search: markdown    target: js    kind: library    snapshot: 2026-06-21T22:35

#  module                         version   license   build    downloads   target
1  mizchi/markdown                 0.6.2     MIT       success  7567        unknown
2  moonbit-community/cmark         0.4.4     Apache-2  success  3120        unknown
3  shiguri-01/markdown             0.1.1     MIT       success  91          unknown

target 列只在 target context 存在时显示。Target unknown 不表示 unsupported；它表示当前读取来源不能回答 target support。

22. seekmoon view

view 展示单个 library module evidence profile。它依赖 ManifestProfile 和 ModuleIndexTree。

seekmoon view mizchi/markdown
seekmoon view 1

view 读取 Manifest API，并用 manifest version 构造 module index asset URL。它显示 description、license、repository、downloads、build status、docs URL、package count、API index state、source state 和 target state。

mizchi/markdown 0.6.2

description  Incremental Markdown parser and compiler
license      MIT
repository   https://github.com/mizchi/markdown.mbt
downloads    7567
build        success
docs         https://mooncakes.io/docs/mizchi/markdown

packages     18
api index    available
source       not fetched
target js    unknown

view 不展开所有 API symbols。API details 属于 seekmoon api。Repository activity 只在 enrichment 被请求或 report 需要时进入 output。

23. seekmoon api

api 展示 package API profile。它依赖 API Profile。

seekmoon api mizchi/markdown --package src/api
seekmoon api 1 --package src/api

api 先读取已缓存的 module index；没有缓存时读取 module index asset。随后，api 解析 package path 和 package relpath，再读取同版本 package_data.json。

API: mizchi/markdown src/api

types
  Document
  Node
  ParseOptions
  RenderOptions

functions
  parse(input : String) -> Document
  render(doc : Document) -> String
  to_json(doc : Document) -> Json

source loc  available

Package path 不存在时，error surface 列出 module index 中可见 package paths。resource.json 不可用不阻止 package_data.json API profile。

24. seekmoon source

source 定位 published source。它依赖 SourceResolution。

seekmoon source mizchi/markdown@0.6.2
seekmoon source 1

source 按 source resolution 规则尝试获取或定位源码。默认优先使用本地工具链可表达的发布源码入口，并记录每个 attempt。

Attempt 用途

moon fetch

通过 Moon 工具链获取 registry 发布源码。

Source zip

通过 Mooncakes download URL 下载发布源码。

Local registry cache

使用已有本地缓存。

Core local source

对 core 包读取本地工具链源码。

Repository signal

作为维护仓库或 fallback source 标记。

默认输出：

source  mizchi/markdown@0.6.2
status  fetched
method  moon fetch
path    .repos/mizchi/markdown/0.6.2
files   moon.mod.json, README.md, LICENSE, src/, benches/

moon fetch 修改文件系统。默认 mutation boundary 是 SeekMoon 控制的 probe 或 source directory；在当前项目执行可变更命令时，命令表面必须显式表达目标。

25. seekmoon skill

skill 处理 executable Wasm / runwasm entries。它依赖 SkillEntry。

seekmoon skill search cowsay
seekmoon skill view Yoorkin/cowsay

skill search 读取 Skills API，按 name、module、package 和 metadata description 搜索。skill view 读取 skill detail、SKILL.md、wasm URL、checksum URL，并派生 pinned runwasm coordinate。

字段 用途

module

所属 module。

package

executable package path。

version

可复查版本。

wasm_url

Wasm artifact。

checksum_url

Checksum asset。

runwasm_coordinate

可执行命令坐标。

默认输出示例：

skill   Yoorkin/cowsay
version 0.1.0
package cowsay
wasm    available
sha256  available
run     moon runwasm Yoorkin/cowsay/cowsay@0.1.0

Skill execution verification 与 library dependency probe 分开记录。Skill entry 进入 skill record 和 report，不进入 library adoption conclusion。

26. seekmoon compare

compare 把多个候选放入同一证据表面。它读取 search session、ManifestProfile、module index summary、source state、probe state 和已加载 repository signal。

seekmoon compare 1 2 3
seekmoon compare mizchi/markdown moonbit-community/cmark

默认输出：

field       mizchi/markdown   moonbit-community/cmark   shiguri-01/markdown
version     0.6.2             0.4.4                     0.1.1
license     MIT               Apache-2                  MIT
build       success           success                   success
repo        present           present                   present
packages    18                4                         3
api         loaded            indexed                   indexed
source      fetched           not fetched               not fetched
target js   unverified        unverified                unverified

compare 不生成 quality score。它展示证据差异，消费者根据上下文作出判断。

27. seekmoon probe

probe 在本地验证候选。它依赖 ProbeResult。

seekmoon probe 1 --target js
seekmoon probe mizchi/markdown@0.6.2 --target wasm-gc

默认 probe 在隔离目录中创建 MoonBit 项目，执行 moon add、moon check、moon test 和 target check/build。Probe result 是 local derived evidence。

probe   mizchi/markdown@0.6.2
target  js
path    .seekmoon/probes/mizchi-markdown-0.6.2-js

moon new                 ok
moon add                 ok
moon check               ok
moon test                ok
moon check --target js   ok
moon build --target js   ok

status  verifiable

Probe failure 不证明上游 metadata 错误。它证明当前环境、当前命令序列、当前版本和当前 target 下未通过验证。

28. seekmoon record

record 保存采纳判断。它依赖 AdoptionRecord。

seekmoon record 1 --conclusion continue-verification --note "Need GFM coverage check."

record 写入候选、版本、snapshot、evidence refs、conclusion、note 和 not-confirmed items。Conclusion 使用稳定枚举，见 AdoptionRecord。

recorded  mizchi/markdown@0.6.2
status    continue-verification
file      .seekmoon/records/mizchi-markdown-0.6.2.json

29. seekmoon report

report 输出调查报告。它依赖 Report。

seekmoon report --format markdown
seekmoon report --format json

Report 只列实际使用的来源。没有运行 probe，就不写 local validation 结果。没有请求 repository enrichment，就不写 repository activity。

report  .seekmoon/reports/markdown-2026-06-21.md

30. seekmoon raw

raw 暴露原始 payload。它服务来源审计、字段复查和故障复现，不属于普通 discovery path。

seekmoon raw modules
seekmoon raw manifest mizchi/markdown
seekmoon raw module-index mizchi/markdown@0.6.2
seekmoon raw package-data mizchi/markdown@0.6.2 src/api
seekmoon raw skills

Raw output 保留上游字段名，不规范化字段，不隐藏原始 shape。Raw output 附带 source URL、fetch status 和 timestamp。

Part V: 输出契约

本部定义 SeekMoon 的输出投影。Pretty text、JSON、jq、shape、schema 和 error surface 服务不同消费者动作，并来自同一 canonical object。

31. Pretty Text

Pretty text 是默认终端输出。它服务 Terminal reader，目标是让消费者直接读取当前动作需要的事实。

Pretty text 规则：

  • 使用稳定列和短标签。

  • 只显示当前命令模型中的行动相关字段。

  • 不把 raw payload 展开到终端表面。

  • 不把 JSON 字段树放入业务结果。

  • 不重复工作流教学。

  • 状态只在影响当前动作时显示。

search 的 pretty text 是候选表：

Search: markdown    target: js    kind: library    snapshot: 2026-06-21T22:35

#  module                         version   license   build    downloads   target
1  mizchi/markdown                 0.6.2     MIT       success  7567        unknown
2  moonbit-community/cmark         0.4.4     Apache-2  success  3120        unknown

view 的 pretty text 是 module profile 摘要：

mizchi/markdown 0.6.2

description  Incremental Markdown parser and compiler
license      MIT
repository   https://github.com/mizchi/markdown.mbt
downloads    7567
build        success
docs         https://mooncakes.io/docs/mizchi/markdown

packages     18
api index    available
source       not fetched
target js    unknown

Pretty text 不是解析接口。Pipeline consumer 使用 JSON Output 或 Built-in jq。

32. JSON Output

JSON output 是当前命令 canonical object 的机器投影。它服务 pipeline consumer、record/report generator 和外部自动化。

seekmoon search markdown --json

JSON output 包含 schema id、input、snapshot、result object、evidence states 和 source labels。它不是 pretty text 的 JSON 化。

search JSON shape 示例：

{
  "schema": "seekmoon.search-results.v1",
  "snapshot": {
    "id": "2026-06-21T22:35:10+08:00",
    "sources": ["modules_api", "statistics_api"]
  },
  "query": {
    "text": "markdown",
    "kind": "library",
    "target": "js"
  },
  "results": [
    {
      "rank": 1,
      "module": "mizchi/markdown",
      "version": "0.6.2",
      "description": {
        "status": "present",
        "value": "Incremental Markdown parser and compiler",
        "source": "modules_api"
      },
      "license": {
        "status": "present",
        "value": "MIT",
        "source": "modules_api"
      },
      "target": {
        "status": "unknown",
        "value": null,
        "source": null
      },
      "match": {
        "fields": ["module", "description", "keywords"]
      }
    }
  ]
}

字段缺失或来源差异会影响解释时，JSON output 使用 evidence wrapper。命令模型要求必有的字段保持标量；这类字段缺失时，命令结果进入 failure surface，例如 schema 和 results[].rank。

每个 JSON output 都包含 schema id。输出契约发生不兼容变化时，schema id 随之变化。

33. Built-in jq

Built-in jq 是 SeekMoon 的输出模式。它使用 Go 进程内 jq interpreter 对当前命令的 JSON output 求值，并把求值结果作为 jq result 返回。Go 实现采用 github.com/itchyny/gojq，版本钉选见 附录 F：Go 实现依赖图。

seekmoon search markdown --jq '.results[].module'
seekmoon api 1 --package src/api --jq '.types[].name'
seekmoon source 1 --jq '.selected_source.path'

求值顺序固定：

command input -> canonical object -> JSON output -> embedded gojq interpreter -> jq result

--jq 不读取 pretty text。除非命令选项改变来源加载规则，--jq 不改变 evidence loading；它只转换 JSON projection。

SeekMoon 把 JSON output 解码为 Go value，编译 jq expression，并由 gojq iterator 产生结果。表达式解析失败或求值失败时，命令进入 error surface；错误对象标记为 jq_expression，状态为 failed。

示例：

seekmoon search markdown --jq '.results[] | select(.license.value == "MIT") | .module'
mizchi/markdown

严格自动化把 Schema Output 与 jq 表达式组合使用。Shape Output 在编写 jq 前提供人可读字段树。

34. Shape Output

Shape output 是单个命令 JSON output 的人可读字段树。它服务需要编写 jq、检查字段或理解状态位置的 contract reader；读取 shape 不需要执行真实查询。

seekmoon search --shape

search shape:

seekmoon.search-results.v1

schema: string
snapshot:
  id: string
  sources: string[]
query:
  text: string
  kind: library|skill
  target: string|null
results[]:
  rank: int
  module: string
  version: string
  description:
    status: present|missing
    value: string|null
    source: string
  license:
    status: present|missing
    value: string|null
    source: string
  target:
    status: present|unknown
    value: string[]|null
    source: string|null
  match:
    fields: string[]

Shape 不是样例结果。它描述输出契约。只通过 raw 暴露的原始 payload 字段不进入普通 shape。

Shape 属于拥有该输出的命令。seekmoon search --shape 描述 search；seekmoon api --shape 描述 api。

35. Schema Output

Schema output 是单个命令 JSON output 的 JSON Schema。它服务代码生成、校验和严格自动化。

seekmoon search --schema

Schema output 使用 JSON Schema。它包含 $schema、$id、type、required fields、property definitions，以及复用 evidence wrapper 的 $defs。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "seekmoon.search-results.v1",
  "type": "object",
  "required": ["schema", "snapshot", "query", "results"],
  "properties": {
    "schema": { "const": "seekmoon.search-results.v1" },
    "snapshot": { "$ref": "#/$defs/snapshot" },
    "query": { "$ref": "#/$defs/searchQuery" },
    "results": {
      "type": "array",
      "items": { "$ref": "#/$defs/searchResult" }
    }
  }
}

Schema 比 shape 更严格。Shape 向读者解释字段；schema 为工具校验 JSON output。命令的 schema id 是下游消费者的兼容性边界。

36. Error Surface

Error surface 是命令失败时的投影。它服务 failure recovery consumer，并约束来源失败的报告方式。

Error surface 包含以下字段：

  • command

  • object

  • attempted source

  • state

  • meaning

  • recovery action

  • 本地命令执行后的 log path

资源资产不可用示例：

command  seekmoon view
object   mizchi/markdown@0.6.2 src/api
source   resource.json
state    unavailable
meaning  resource asset is unavailable; package_data is a separate source
recover  seekmoon api mizchi/markdown --package src/api

Package path 不存在示例：

command  seekmoon api
object   mizchi/markdown src/apix
source   module_index.json
state    failed
meaning  package path is not present in module index

known packages
  src
  src/api
  src/toc
  src/slug

jq expression 错误示例：

command  seekmoon search --jq
object   jq_expression
source   embedded gojq interpreter
state    failed
meaning  jq expression cannot be compiled or evaluated against command JSON output
recover  inspect seekmoon search --shape, correct the expression, or use --json

恢复文本只出现在 failure projection 中。正常 pretty text 保持为结果表面。

Error surface 中的状态词由 Evidence State Values 定义。

Part VI: Go 实现架构

本部把前文的公共对象、来源边界、canonical model、命令契约和输出契约投影为 Go 实现架构。它定义 Go module layout、package 边界、依赖方向、运行时组合、数据流、控制流、来源读取、输出管线、持久化边界、错误状态和测试工具链，并规定实现物如何承载已经定义的人工制品。

37. Architecture Premises

SeekMoon 的 Go implementation 是一个 command-line program 和 internal packages 组成的单一 Go module。Go module 的公共进程入口是 cmd/seekmoon；internal packages 承载非公开实现 API。该形态对应 Go 官方 module layout 中的 command-line program 组织方式。

架构前提来自本书已经定义的对象：

前提 已定义对象 架构约束

SeekMoon 是本地 package discovery workbench。

SeekMoon

实现围绕 CLI 动作、证据读取和输出投影组织。

命令按消费者动作分组。

Command Map

Cobra command handler 解析输入并分派 service；evidence source 读取和输出投影由下游 package 承担。

Canonical objects 是输出来源。

ModuleSummary、ManifestProfile、API Profile、SourceResolution、ProbeResult、AdoptionRecord

Go model package 定义 canonical objects；source、service、output 和 store 都依赖 model。

Evidence sources 只回答各自能回答的问题。

Public HTTP Sources、Static Assets、Local Toolchain and Cache、Project Context、Repository Signals

Go source package 读取来源并产生带状态的 source result；采纳判断由 service 和 record flow 承担。

输出投影服务不同消费者动作。

Pretty Text、JSON Output、Built-in jq、Shape Output、Schema Output、Error Surface

Go output package 从同一 canonical object 生成 pretty text、JSON、jq result、shape、schema 和 error surface。

Probe 和 source resolution 具有本地副作用。

SourceResolution、ProbeResult

Go store 和 platform packages 约束路径、日志、命令执行和隔离目录。

架构的中心是不带 I/O 的 canonical model。命令、来源、存储和输出都围绕 canonical model 协作。这个结构使同一事实可以被终端阅读、机器处理、jq expression、schema 校验和报告生成共同消费。

Go implementation 使用 附录 F：Go 实现依赖图 中固定的 source imports 和 test imports。工程质量工具链由 Engineering Quality Toolchain 和 附录 G：Go 工程工具链 固定。第三方依赖和工程工具只进入对应实现或质量门位置；它们不定义 SeekMoon 的对象边界。

38. Go Module Layout

SeekMoon 使用单一 Go module。根目录保存 Go module metadata、命令入口和内部 packages；业务实现由 internal packages 承载。

seekmoon/
  go.mod
  go.sum
  justfile
  .golangci.yml
  .goreleaser.yaml
  cmd/
    seekmoon/
      main.go
  internal/
    app/
      app.go
      runtime.go
      command.go
    cli/
      root.go
      doctor.go
      sync.go
      search.go
      view.go
      api.go
      source.go
      skill.go
      compare.go
      probe.go
      record.go
      report.go
      raw.go
      flags.go
    model/
      evidence.go
      module.go
      manifest.go
      api.go
      skill.go
      source.go
      probe.go
      record.go
      report.go
      snapshot.go
      project.go
      schema.go
    source/
      fetch.go
      mooncakes.go
      assets.go
      skills.go
      local_index.go
      local_cache.go
      repository.go
      mooncli.go
      project.go
    service/
      doctor.go
      sync.go
      search.go
      view.go
      api.go
      source.go
      skill.go
      compare.go
      probe.go
      record.go
      report.go
      raw.go
    output/
      render.go
      pretty.go
      json.go
      jq.go
      shape.go
      schema.go
      error.go
    store/
      paths.go
      snapshot_store.go
      session_store.go
      record_store.go
      report_store.go
      cache_store.go
    platform/
      clock.go
      env.go
      fs.go
      exec.go
      http.go
    contract/
      schemas.go
      shapes.go
    testutil/
      fixture.go
      golden.go
  .artifacts/
    test/

每个目录承担一个实现职责：

Path Responsibility Boundary

cmd/seekmoon

进程入口。

创建 Runtime 并调用 CLI root execution。

internal/app

运行时装配和实现 registry。

创建 platform clients、sources、stores、services 和 renderer。

internal/cli

Cobra command surface。

接收 Runtime，解析 command input，并分派 service calls。

internal/model

Canonical objects、state values 和 shared structured types。

只定义对象、状态词和结构化字段。

internal/source

Evidence source readers。

读取 HTTP、assets、local index/cache、repository、Moon CLI 和 project context。

internal/service

命令用例。

组合 source results、store operations 和 canonical objects。

internal/output

输出投影。

渲染 pretty text、JSON、jq result、shape、schema 和 error surface。

internal/store

文件系统持久化。

管理 snapshot、session、record、report、cache、probe 和 log paths。

internal/platform

可替换 host capability。

封装 clock、filesystem、command runner、HTTP client 和 environment。

internal/contract

Shape 和 schema contract definitions。

定义 output 和 tests 使用的 field trees 与 JSON Schema objects。

internal/testutil

Test fixtures 和 golden helpers。

由 tests 使用。

Engineering files live at the Go implementation root:

Path Responsibility

justfile

定义本地和 CI 共用的工程质量入口，例如 format、lint、test、race、coverage、vulnerability、module integrity 和 release check。

.golangci.yml

定义 aggregate lint gate。它约束 Go source quality，不定义 SeekMoon public command surface。

.goreleaser.yaml

定义 CLI release artifacts、archives 和 checksums 的生成规则。

.artifacts/

保存测试报告、race 报告和覆盖率输出。该目录是生成物，不是 runtime storage contract。

Module layout 让变更靠近被修改对象。Manifest API parsing 的变更落在 internal/source 和 internal/model；search ranking 的变更落在 internal/service；table rendering 的变更落在 internal/output；record path layout 的变更落在 internal/store。

39. Package Boundaries

Go package dependencies follow responsibility direction。Inner packages 定义对象和 host capabilities；outer packages 装配行为和投影。

cmd/seekmoon
  -> internal/app
  -> internal/cli

internal/cli
  -> internal/service
  -> internal/output
  -> internal/model

internal/service
  -> internal/model
  -> internal/source
  -> internal/store
  -> internal/platform

internal/source
  -> internal/model
  -> internal/platform

internal/store
  -> internal/model
  -> internal/platform

internal/output
  -> internal/model
  -> internal/contract

internal/contract
  -> internal/model

internal/model
  -> Go standard library

Dependency rules：

  • internal/model contains canonical types and state values. It imports only Go standard library packages.

  • internal/source returns evidence-bearing source results. Its import surface excludes internal/output.

  • internal/output projects canonical objects. Its import surface excludes internal/source.

  • internal/service owns command use cases. It composes source readers and stores into canonical command results.

  • cmd/seekmoon owns process startup. It creates Runtime through internal/app and passes Runtime into internal/cli.

  • internal/cli owns Cobra command definitions. Cobra types remain in the CLI package.

  • internal/store owns persistence paths and read/write operations. Adoption conclusion belongs to record service flow.

  • internal/platform owns host primitives. It is below SeekMoon business packages.

Third-party dependency placement is fixed:

Dependency Import boundary

github.com/spf13/cobra

internal/cli

github.com/itchyny/gojq

internal/output

github.com/charmbracelet/lipgloss/v2

internal/output

github.com/jedib0t/go-pretty/v6

internal/output

github.com/google/go-github/v88

internal/source

golang.org/x/oauth2

internal/source

github.com/pelletier/go-toml/v2

internal/source

github.com/santhosh-tekuri/jsonschema/v6

internal/contract tests or schema validation tests

github.com/adrg/xdg

internal/store

github.com/cenkalti/backoff/v5

internal/source

github.com/google/go-cmp

Tests only

这些边界保持书中契约。Source readers 只产生来源结果；output renderers 只投影既有对象；canonical models 只承载对象、状态词和结构化字段。

40. Runtime Composition

Runtime 是 Go implementation 的 composition root。它为一次进程执行绑定 platform capabilities、source readers、stores、services 和 renderer。

type Runtime struct {
    Clock    platform.Clock
    FS       platform.FS
    HTTP     *http.Client
    Runner   platform.Runner
    Paths    store.Paths
    Sources  source.Registry
    Stores   store.Registry
    Services service.Registry
    Renderer output.Renderer
}

Process startup order：

process environment
-> path resolution
-> platform clients
-> source readers
-> stores
-> services
-> renderer
-> runtime value
-> CLI command tree

context.Context 贯穿所有可能阻塞、取消或触碰 host environment 的操作。HTTP requests、repository enrichment、Moon CLI commands、source downloads 和 probe commands 接收来自 CLI command invocation 的 context。

Service methods 使用 context-first signatures：

func (s *SearchService) Search(ctx context.Context, input SearchInput) (*model.SearchOutput, error)

Source reader methods 同样使用 context-first signatures：

func (c *MooncakesClient) FetchModules(ctx context.Context) (*model.SourceResult[[]model.ModuleSummary], error)

Runtime objects 通过构造传递。测试用 HTTP clients、clocks、filesystems 和 command runners 可以替换对应 host capability。

Runtime 只装配 command contracts 和 services 已经定义的行为实现。cmd/seekmoon 把 Runtime 交给 CLI command tree。

41. Data Flow

Executable commands transform input into canonical objects and then project those objects. Shape and schema modes read command contracts through Output Pipeline.

41.1. sync

CLI input
-> SyncService
-> moon update command result
-> Modules API fetch result
-> Statistics API fetch result
-> local registry index summary
-> toolchain version result
-> Snapshot
-> snapshot store write
-> output projection

sync fixes a data snapshot. Candidate ranking and adoption decision remain outside the sync flow. Partial source failure is recorded inside the snapshot state.

query + target + limit
-> latest snapshot or transient modules fetch
-> ModuleSummary normalization
-> local match and rank
-> visible-window manifest enrichment
-> SearchResult array
-> session candidate map
-> output projection

search generates library module candidates. Package data, published source and probe evidence belong to later inspection or validation flows.

41.3. view

module coordinate or candidate number
-> candidate resolution
-> Manifest API fetch
-> docs URL derivation
-> module_index asset fetch
-> ManifestProfile with index summary
-> output projection

view shows a module profile. API details remain under api.

41.4. api

module coordinate + package path
-> manifest version resolution
-> module_index load
-> package path to package relpath
-> package_data asset fetch
-> API profile
-> output projection

Package path failure is resolved against module index. The error surface lists known package paths from that index.

41.5. source

module@version
-> source resolution planner
-> moon fetch attempt
-> source zip attempt
-> local cache attempt
-> core local source attempt
-> repository fallback signal
-> selected source
-> files summary
-> SourceResolution
-> output projection

Every source resolution attempt records status, path, URL and error. selected_source is derived from successful attempts.

41.6. skill

skill query or entry
-> Skills API list or detail
-> SkillEntry or SkillProfile
-> skill asset fetch when requested
-> runwasm coordinate derivation
-> output projection

Skill flow uses executable entry objects. Library adoption uses record flow for library module candidates.

41.7. compare

candidate list
-> manifest profiles
-> loaded API/source/probe/repository evidence
-> comparison object
-> output projection

compare aligns evidence fields. Quality judgment remains a consumer decision supported by the comparison object.

41.8. probe

candidate + target
-> isolated probe path
-> moon new command result
-> moon add command result
-> moon check command result
-> moon test command result
-> target check/build command results
-> logs
-> ProbeResult
-> output projection

Probe result is local derived evidence. Upstream metadata remains source evidence.

41.9. record and report

candidate + conclusion + evidence refs + note
-> AdoptionRecord
-> record store write
-> report reads records + snapshot + evidence refs
-> Report
-> output projection

Report output lists only sources actually used by the records and evidence references.

41.10. raw

raw source selector
-> exact source reader
-> raw payload envelope
-> raw output

raw preserves upstream field names and source status. It bypasses ordinary normalization.

42. Control Flow

所有 executable commands 使用同一控制序列：

parse args
-> build command input
-> create or receive context
-> call service
-> render output
-> map process exit

Cobra handlers 保持薄层职责。Command handler 校验 surface syntax，构造 input object，调用一个 service method，并把结果交给 output renderer。

cmd.RunE = func(cmd *cobra.Command, args []string) error {
    ctx := cmd.Context()
    input, err := parseSearchInput(args, flags)
    if err != nil {
        return err
    }
    result, err := rt.Services.Search.Search(ctx, input)
    return rt.Renderer.Render(ctx, output.Request{
        Mode:  flags.OutputMode,
        Value: result,
        Err:   err,
    })
}

Process exit 和 evidence state 是不同对象。Evidence state 描述字段、source action 或 source attempt；process exit 描述命令进程状态。

Exit condition Process behavior

Command succeeds

Exit code 0.

Input parse failure

Exit code 2.

Core command object failure

Exit code 1.

Probe target validation fails

Exit code 1, with ProbeResult output.

jq expression parse/eval fails

Exit code 1, with error surface output.

当 command contract 允许 partial canonical object 投影时，partial source failure 保留为 evidence state。Core object failure 映射为 process failure。

43. Source Reader Boundary

Source readers 把外部事实转换为带证据状态的 Go objects。Reader 记录 attempt、事实来源位置和 parse result。

SourceResult 是 source reader 的共享 envelope。它包含 reader 产生的 normalized value，以及 JSON output、raw output 和 error surface 需要的 source metadata。

All source results carry:

Field Meaning

source

Stable source label, such as modules_api, manifest_api, module_index_asset, local_index, repository_api or moon_cli.

url / path

Remote URL or local path used by the attempt.

fetched_at

Clock time for the source action.

status

Evidence state for the source action.

parse_state

Payload parse result when the source returns structured data.

raw_ref

Pointer to raw payload storage or raw envelope when raw output needs audit data.

error

Failure message when status is failed.

HTTP source readers 共享 fetch behavior：context、timeout、redirect handling、retry policy、status classification 和 JSON decoding。Mooncakes API readers、asset readers 和 source zip readers 使用同一 fetch result envelope。

Local source readers 通过 platform.FS 共享 filesystem behavior。Service code 从 readers 接收 source results。

Moon CLI reader 使用 platform.Runner。Command result 包含 command、cwd、exit code、status 和 log path。Command failure 进入 local command evidence。

Repository reader 在 enrichment 被请求后读取 repository metadata。Repository signal failure 改变 repository source state；module profile 中的其他字段保留各自 evidence state。

44. Output Pipeline

Output pipeline 投影 command result。Result 进入 output projection 之前，evidence loading 已经结束。

canonical object
-> output request
-> selected projection
-> writer

Projection modes：

Mode Input Renderer

Pretty text

Canonical object

稳定终端表格或摘要。

JSON

Canonical object

带 schema id 和 evidence states 的 JSON encoder。

jq

JSON projection

gojq interpreter result。

Shape

Command contract

人可读 field tree。

Schema

Command contract

JSON Schema object。

Error surface

Surface error object

Failure recovery projection。

Pretty text 和 JSON 来自同一 canonical object。Pretty text 服务 terminal reading；JSON 服务 mechanical processing。

--jq 消费 JSON projection。SeekMoon 把 canonical object 编码为 command JSON shape，把该 shape 解码为 Go value，用 gojq 求值 jq expression，并写出 jq result。

--shape 和 --schema 是 contract projections。它们读取 command contract definitions。

当 command execution 无法产生请求的 projection，或 projection-specific error 出现时，output pipeline 选择 error surface。

45. Storage and Side Effects

SeekMoon separates project records from reusable cache. Project records belong to the current project context. Reusable remote cache belongs to the user cache location.

Project storage:

.seekmoon/
  snapshots/
  sessions/
  records/
  reports/
  probes/
  sources/
  logs/

Reusable cache:

$XDG_CACHE_HOME/seekmoon/
  mooncakes/
  assets/
  github/

Storage responsibilities:

Store Responsibility

Snapshot store

Writes and reads dated source snapshots.

Session store

Maps session-local candidate numbers to candidate coordinates.

Record store

Writes adoption records with evidence refs.

Report store

Writes report projections.

Cache store

Stores reusable fetched payloads and assets.

Probe store

Creates isolated probe directories and log paths.

Source store

Stores source resolution material controlled by SeekMoon.

Probe and source resolution are controlled side effects. Their default paths live under .seekmoon/ because they serve the current project’s dependency investigation. Project manifest mutation requires an explicit command surface.

Store packages own path construction and read/write mechanics. Services decide when a record, snapshot, report, probe directory or source directory should be created.

46. Error and State Flow

Error flow 使用三类错误：

Category Trigger Projection

Input error

Command input parse failure.

CLI error with exit code 2.

Source error

HTTP request, local file read, repository request, Moon CLI command or parse action fails.

Evidence state inside canonical object, or error surface for core object failure.

Projection error

JSON, jq, shape, schema or pretty output failure.

Error surface.

Evidence state stays inside model fields and source attempts. Process errors wrap the failed operation.

Error surface object：

type SurfaceError struct {
    Command  string
    Object   string
    Source   string
    State    model.State
    Meaning  string
    Recovery string
    Cause    error
}

Source attempt object：

type SourceAttempt struct {
    Status model.State `json:"status"`
    Path   string      `json:"path,omitempty"`
    URL    string      `json:"url,omitempty"`
    Error  string      `json:"error,omitempty"`
}

Command result object：

type CommandResult struct {
    Command  []string    `json:"command"`
    CWD      string      `json:"cwd"`
    ExitCode int         `json:"exit_code"`
    Status   model.State `json:"status"`
    LogPath  string      `json:"log_path,omitempty"`
}

State values come from Evidence State Values. Implementation code uses that enum as the status vocabulary.

47. Testing and Tooling

Go tests 跟随 SeekMoon 的对象边界。Tests 分别验证 canonical objects、source readers、services、stores、output projections 和 command wiring。

Test layer Scope Tooling

Model tests

Evidence wrapper JSON、state values、coordinate parsing、package relpath derivation。

go test.

Source tests

HTTP status mapping、JSON parse state、asset 404 state、local index parsing、repository enrichment mapping。

httptest.Server 和 fake filesystem。

Service tests

Command data flow、evidence composition、session candidate resolution、source resolution selection。

Fake source readers 和 fake stores。

Output tests

Pretty text、JSON shape、jq result、shape output、schema output、error surface。

Golden fixtures 和 gojq-backed projection tests。

Store tests

Snapshot、session、record、report、cache、probe path read/write behavior。

t.TempDir().

Probe tests

Command sequence、cwd、log paths、target flags 和 result mapping。

Fake platform.Runner.

Schema tests

JSON output validates against command schema。

github.com/santhosh-tekuri/jsonschema/v6.

Fuzz tests

Module coordinate parser、package relpath derivation、local index JSONL parser、source URL/path parser。

Go fuzzing。

Standard tests use Go’s official go test execution core. gotestsum may render those same test events for terminal and CI readers, but it does not define a separate test execution model.

Coverage tests use Go coverage profiles to expose untested source reader、service、output、schema 和 error-surface paths. Coverage result is a test reach signal; it is not the sole acceptance condition.

Fuzz tests target parsers and derivations owned by SeekMoon. The jq parser belongs to github.com/itchyny/gojq; SeekMoon tests jq expression failure mapping and output-pipeline behavior around that interpreter.

Integration tests 在环境显式启用时使用真实 Moon CLI、真实网络、GitHub API、source zip downloads 和 probe project mutation。Default test runs 使用 fake runner、fake filesystem、fake source readers 和 local fixtures，使普通测试保持可重复、离线和无外部副作用。

Required local checks are defined by Engineering Quality Toolchain. Source imports and test imports remain aligned with 附录 F：Go 实现依赖图。

Documentation comments explain object contracts、side effects 和 failure meanings。

48. Engineering Quality Toolchain

Engineering quality toolchain defines the executable checks that a SeekMoon Go implementation must pass before implementation material is treated as shippable. It belongs to the Go implementation layer; it does not define SeekMoon’s public package-discovery CLI contract.

SeekMoon uses Go 1.26.x as the implementation toolchain baseline. go1.26.3 linux/amd64 is the recorded local environment sample for that baseline; CI and release jobs use the same minor toolchain family to avoid local, CI and artifact drift.

Quality concern Primary entry Boundary

Functional tests

go test ./…​

The Go test command is the execution core. It compiles packages, runs unit and package tests, uses Go’s test cache, and supplies JSON event output.

Test presentation

gotestsum --format=pkgname — -count=1 ./…​

gotestsum consumes go test -json output and produces readable local summaries, CI annotations and JUnit reports. It does not replace go test.

Race detection

go test -race ./…​

Race detection checks concurrent source readers, stores, probe runners and output writers in the current Go runtime environment.

Coverage

go test -coverprofile=.artifacts/coverage.out ./…​

Coverage exposes untested model, source, service, output, schema and error-surface paths. Coverage is evidence for test reach, not a quality proof by itself.

Fuzzing

go test -fuzz=Fuzz -run=^$ ./internal/model ./internal/source

Fuzz targets parsers and path derivations owned by SeekMoon. Third-party parser correctness remains with the dependency that provides it.

Static analysis

go vet ./…​ and golangci-lint run ./…​

go vet remains the official static check. golangci-lint is the aggregate lint gate for error handling, unused code, security-oriented linting, style rules and maintainability checks.

Formatting

gofumpt -w . and gofumpt -l .

gofmt is the Go formatting baseline. gofumpt is the stricter formatter used as the project formatting gate; import grouping is handled by goimports or lint configuration.

Module integrity

go mod tidy and go mod verify

go mod tidy keeps go.mod and go.sum aligned with source imports. go mod verify checks module cache content against go.sum.

Vulnerability exposure

govulncheck ./…​

govulncheck uses the Go vulnerability database and call reachability. It is a vulnerability exposure gate, not a linter.

Release artifacts

goreleaser check and goreleaser release --snapshot --clean

GoReleaser validates release configuration and produces CLI artifacts, archives and checksums. It does not run the test or lint gates.

Task orchestration

just ci

just names quality gates and composes commands across Go, documentation and release tasks. It does not replace the underlying Go tools.

gotestsum is the only additional test runner surface in the standard path. The Rust cargo-nextest shape is not copied into SeekMoon because Go’s execution core remains go test; SeekMoon only adds a presentation and CI reporting layer around that core.

Standard quality entrypoints:

just fmt-check
just lint
just test
just test-race
just cover
just fuzz
just vuln
just mod-check
just release-check
just ci

The corresponding just recipes call one primary tool each:

fmt:
    gofumpt -w .

fmt-check:
    test -z "$(gofumpt -l .)"

lint:
    golangci-lint run ./...

test:
    gotestsum --format=pkgname -- -count=1 ./...

test-race:
    gotestsum --format=pkgname -- -race -count=1 ./...

cover:
    go test -coverprofile=.artifacts/coverage.out ./...
    go tool cover -func=.artifacts/coverage.out

fuzz:
    go test -fuzz=Fuzz -run=^$ ./internal/model ./internal/source

vuln:
    govulncheck ./...

mod-check:
    go mod tidy
    git diff --exit-code -- go.mod go.sum
    go mod verify

release-check:
    goreleaser check

release-snapshot:
    goreleaser release --snapshot --clean

ci: fmt-check lint test test-race cover vuln mod-check release-check

CI uses the same gates as local development:

Job Command Artifact or decision

format

gofumpt -l .

The listed files must be empty.

lint

golangci-lint run ./…​

Static quality gate passes or fails.

test

gotestsum --format=github-actions --junitfile=.artifacts/test/unit.xml — -count=1 ./…​

JUnit unit test report.

race

gotestsum --format=github-actions --junitfile=.artifacts/test/race.xml — -race -count=1 ./…​

JUnit race test report.

coverage

go test -coverprofile=.artifacts/coverage.out ./…​

Coverage profile and summary.

vuln

govulncheck ./…​

Reachable vulnerability exposure result.

mod

go mod tidy, git diff --exit-code — go.mod go.sum, go mod verify

Dependency graph cleanliness and module cache verification.

release-check

goreleaser check

Release configuration validity.

Integration tests are opt-in. Tests that use real network, real Moon CLI commands, GitHub API, source zip downloads or probe project mutation run only when an explicit integration environment variable is present. Default test runs use fixtures, fake source readers, fake filesystem and fake command runners.

Tool version pins and installation coordinates are listed in 附录 G：Go 工程工具链. Source imports and test imports are listed separately in 附录 F：Go 实现依赖图.

Part VII: 行动轨迹与验收

本部用行动轨迹检查 SeekMoon 的公共行为。每条旅程由状态、命令、输出和状态变化组成，可作为黑盒验收材料。

49. Library Discovery Journey

一个 MoonBit 项目寻找 Markdown parser 的完整动作链包含环境检查、快照创建、候选搜索、证据下钻、本地验证、记录和报告。目标 target 是 js。初始状态没有 fresh snapshot，也没有已选候选。

49.1. E1：检查环境

seekmoon doctor
moon        0.1.20260608
moonc       v0.10.0
registry    present
network     mooncakes.io ok
project     MoonBit module detected

状态变化：

environment.checked = true
project.context = present

49.2. E2：创建快照

seekmoon sync
snapshot  2026-06-21T22:35:10+08:00
modules   1350
packages  12008
index     1363 files

状态变化：

snapshot.id = 2026-06-21T22:35:10+08:00
modules.snapshot = present
statistics.snapshot = present
local_index.summary = present

49.3. E3：搜索候选

seekmoon search markdown --target js
Search: markdown    target: js    kind: library    snapshot: 2026-06-21T22:35

#  module                         version   license   build    downloads   target
1  mizchi/markdown                 0.6.2     MIT       success  7567        unknown
2  moonbit-community/cmark         0.4.4     Apache-2  success  3120        unknown
3  shiguri-01/markdown             0.1.1     MIT       success  91          unknown

状态变化：

session.candidates[1] = mizchi/markdown@0.6.2
session.candidates[2] = moonbit-community/cmark@0.4.4
session.candidates[3] = shiguri-01/markdown@0.1.1
target.js.evidence = unknown

49.4. E4：查看候选

seekmoon view 1
mizchi/markdown 0.6.2

description  Incremental Markdown parser and compiler
license      MIT
repository   https://github.com/mizchi/markdown.mbt
downloads    7567
build        success
docs         https://mooncakes.io/docs/mizchi/markdown

packages     18
api index    available
source       not fetched
target js    unknown

状态变化：

candidate[1].manifest = present
candidate[1].module_index = present
candidate[1].source = not-fetched

49.5. E5：检查 API

seekmoon api 1 --package src/api
API: mizchi/markdown src/api

types
  Document
  Node
  ParseOptions
  RenderOptions

functions
  parse(input : String) -> Document
  render(doc : Document) -> String
  to_json(doc : Document) -> Json

source loc  available

状态变化：

candidate[1].package[src/api].package_data = present
candidate[1].package[src/api].api_profile = present

49.6. E6：定位源码

seekmoon source 1
source  mizchi/markdown@0.6.2
status  fetched
method  moon fetch
path    .repos/mizchi/markdown/0.6.2
files   moon.mod.json, README.md, LICENSE, src/, benches/

状态变化：

candidate[1].source.selected = moon_fetch
candidate[1].source.path = .repos/mizchi/markdown/0.6.2

49.7. E7：比较候选

seekmoon compare 1 2 3
field       mizchi/markdown   moonbit-community/cmark   shiguri-01/markdown
version     0.6.2             0.4.4                     0.1.1
license     MIT               Apache-2                  MIT
build       success           success                   success
repo        present           present                   present
packages    18                4                         3
api         loaded            indexed                   indexed
source      fetched           not fetched               not fetched
target js   unverified        unverified                unverified

状态变化：

comparison.current = [1, 2, 3]
candidate[1].target[js] = unverified

49.8. E8：验证候选

seekmoon probe 1 --target js
probe   mizchi/markdown@0.6.2
target  js
path    .seekmoon/probes/mizchi-markdown-0.6.2-js

moon new                 ok
moon add                 ok
moon check               ok
moon test                ok
moon check --target js   ok
moon build --target js   ok

status  verifiable

状态变化：

candidate[1].probe[js].status = verifiable
candidate[1].target[js].evidence = local-probe

49.9. E9：记录判断

seekmoon record 1 --conclusion continue-verification --note "Need GFM coverage check."
recorded  mizchi/markdown@0.6.2
status    continue-verification
file      .seekmoon/records/mizchi-markdown-0.6.2.json

状态变化：

record.created = mizchi-markdown-0.6.2
record.conclusion = continue-verification

49.10. E10：输出报告

seekmoon report --format markdown
report  .seekmoon/reports/markdown-2026-06-21.md

状态变化：

report.created = markdown-2026-06-21.md

50. Skill Discovery Journey

Skill discovery 处理 executable Wasm entries。它不产生 library adoption record。

50.1. E1：搜索 Skill

seekmoon skill search cowsay
Search: cowsay    kind: skill    snapshot: 2026-06-21T22:35

#  skill             version   package   wasm       checksum
1  Yoorkin/cowsay    0.1.0     cowsay    present    present

状态变化：

skill_candidates[1] = Yoorkin/cowsay@0.1.0/cowsay

50.2. E2：查看 Skill

seekmoon skill view 1
skill   Yoorkin/cowsay
version 0.1.0
package cowsay
wasm    available
sha256  available
run     moon runwasm Yoorkin/cowsay/cowsay@0.1.0

状态变化：

skill[1].profile = present
skill[1].runwasm_coordinate = derived

50.3. E3：记录 Skill 结果

seekmoon record 1 --kind skill --conclusion continue-verification --note "Project-context execution still needs verification."
recorded  Yoorkin/cowsay@0.1.0/cowsay
status    continue-verification
file      .seekmoon/records/Yoorkin-cowsay-0.1.0-cowsay.json

状态变化：

record.kind = skill
record.conclusion = continue-verification

51. Pipeline Journey

Pipeline journey 展示消费者如何查看输出契约、提取字段并使用 JSON，而不解析 pretty text。

51.1. E1：检查 Shape

seekmoon search --shape
seekmoon.search-results.v1

schema: string
snapshot:
  id: string
  sources: string[]
query:
  text: string
  kind: library|skill
  target: string|null
results[]:
  rank: int
  module: string
  version: string
  license:
    status: present|missing
    value: string|null
    source: string

状态变化：

consumer.field_path = results[].module
consumer.license_path = results[].license.value

51.2. E2：提取 Module

seekmoon search markdown --jq '.results[].module'
mizchi/markdown
moonbit-community/cmark
shiguri-01/markdown

状态变化：

pipeline.output = module-list

51.3. E3：过滤 JSON

seekmoon search markdown --jq '.results[] | select(.license.value == "MIT") | .module'
mizchi/markdown
shiguri-01/markdown

状态变化：

pipeline.output = mit-module-list

51.4. E4：校验 Schema

seekmoon search --schema

状态变化：

consumer.schema = seekmoon.search-results.v1

自动化流程保存 schema result，并用它校验后续 JSON output。

52. Failure Recovery Journey

Failure recovery journey 定义失败如何保持可行动，同时不把正常输出变成教程文本。

52.1. Resource Asset Unavailable

seekmoon view mizchi/markdown --readme
command  seekmoon view
object   mizchi/markdown@0.6.2 src/api
source   resource.json
state    unavailable
meaning  resource asset is unavailable; package_data is a separate source
recover  seekmoon api mizchi/markdown --package src/api

状态变化：

resource.state = unavailable
api.recovery = available

52.2. Package Path Not Found

seekmoon api mizchi/markdown --package src/apix
command  seekmoon api
object   mizchi/markdown src/apix
source   module_index.json
state    failed
meaning  package path is not present in module index

known packages
  src
  src/api
  src/toc
  src/slug

状态变化：

api.request = failed
module_index = present

52.3. Probe Target Failed

seekmoon probe 1 --target wasm-gc
probe   mizchi/markdown@0.6.2
target  wasm-gc
path    .seekmoon/probes/mizchi-markdown-0.6.2-wasm-gc

moon new                         ok
moon add                         ok
moon check                       ok
moon check --target wasm-gc      failed

status  failed
log     .seekmoon/probes/mizchi-markdown-0.6.2-wasm-gc/logs/moon-check-target.log

状态变化：

candidate[1].probe[wasm-gc].status = failed
candidate[1].target[wasm-gc].evidence = local-probe-failed

Probe failure 是 local evidence。它不改变 module metadata。

53. Black-box Acceptance

以下行为从命令表面成立时，SeekMoon 的公共对象成立。

编号 验收行为 检查方式

A1

消费者不手写 Mooncakes API URL 即可生成候选集合。

执行 seekmoon search markdown 并检查候选。

A2

搜索结果可被 session-local number 引用。

搜索后执行 seekmoon view 1。

A3

Library module 与 skill entry 使用不同命令表面。

分别执行 seekmoon search markdown 和 seekmoon skill search cowsay。

A4

单个 module profile 包含 manifest evidence 和 package index state。

执行 seekmoon view <module>。

A5

Package API profile 来自 module index 和 package data。

执行 seekmoon api <module> --package <path>。

A6

Published source 可通过 source resolution 获取或定位。

执行 seekmoon source <module@version>。

A7

没有 evidence 的 target support 是 unknown。

probe 前执行 seekmoon search <query> --target <target>。

A8

Probe 产生 local derived evidence，不修改上游事实。

执行 seekmoon probe 1 --target js。

A9

Adoption decision 保存为带 evidence refs 的 record。

执行 seekmoon record 1 --conclusion continue-verification。

A10

Report 只列实际使用的来源。

执行 seekmoon report --format markdown 并检查 Data sources。

A11

Pretty text 保持低噪声，脚本不解析 pretty text。

检查默认命令输出。

A12

JSON output 包含 schema id 和 evidence states。

执行 seekmoon search markdown --json。

A13

Built-in jq 对命令 JSON output 求值。

执行 seekmoon search markdown --jq '.results[].module'。

A14

Shape 在没有真实查询结果时解释 JSON 字段。

执行 seekmoon search --shape。

A15

Schema 为严格消费者提供 JSON Schema。

执行 seekmoon search --schema。

A16

命令失败时，error surface 给出 source、state、meaning 和 recovery。

用 seekmoon api 请求不存在的 package path。

这些行为不依赖实现语言。它们定义 SeekMoon 的公共工作台表面。

术语表

本术语表定义 SeekMoon 书中使用的核心词。命令字段见 附录 C：命令速查；数据字段见 附录 B：数据字典。

SeekMoon

面向 MoonBit 消费者的本地包发现工作台。它把公开 API、静态资产、本地工具链、本地缓存、项目上下文、repository 信号和本地记录投影为 CLI 动作。

MoonBit

一门通用编程语言及其工具链生态。SeekMoon 把 MoonBit 包和 skill 作为消费对象处理。

Mooncakes

MoonBit 包注册表和文档表面。SeekMoon 读取 Mooncakes 的公开 API 与静态资产。

Package discovery workbench

把候选发现、证据下钻、API 阅读、源码定位、比较、本地验证、记录和报告组织为 CLI 动作的工具环境。

Package discovery

消费者在引入依赖之前识别候选包、理解候选包、比较候选包并形成判断的机制。

Consumer

消费 SeekMoon 输出并执行下一步动作的行动者。开发者、脚本、CI 作业或 Code Agent 都可以按动作成为 consumer。

Terminal reader

读取默认 pretty text 并作出判断的消费者。

Pipeline consumer

通过 JSON 或 jq 处理 SeekMoon 输出的消费者。

Contract reader

通过 help、shape 或 schema 理解输出契约的消费者。

Failure recovery consumer

命令失败后读取错误表面并执行恢复动作的消费者。

Evidence source

SeekMoon 读取的事实来源，包括 HTTP API、静态资产、本地工具链、本地缓存、项目上下文、repository enrichment 和本地记录。

Input surface

某个 evidence source 暴露给 SeekMoon 的具体读取表面，例如 /api/v0/modules、module_index.json、package_data.json、registry index JSONL 和 source zip。

Snapshot

一次带时间戳的数据读取结果。Snapshot 让搜索、比较、记录和报告可以回到同一数据口径。

Candidate

由 search 或 skill search 产生的候选对象。

Library module

可作为 MoonBit 依赖引入的包模块。

Skill entry

Mooncakes Skills API 中的可执行 Wasm 或 moon runwasm 对象。Skill entry 不是 library dependency candidate。

Module profile

单个 library module 的证据画像，由 manifest、module index、metadata、docs URL、source state 和已加载 enrichment 组成。

API profile

某个 package 的类型、函数、trait、docstring、signature 和 source location 的结构化投影。

Published source

与 registry 发布版本对应的源码材料。SeekMoon 优先从 moon fetch、source zip、本地 registry cache 或 core 本地源码定位 published source。

Repository signal

GitHub 等源码仓库提供的维护、协作、CI、issue、release 和未发布状态信号。Repository signal 不自动等同于 published source。

Probe

SeekMoon 在隔离目录或明确项目上下文中执行 moon add、moon check、moon test 和 target build/check 的本地验证动作。

Adoption record

一次采纳判断的本地记录。它包含候选、版本、结论、证据引用和未确认事项。

Report

面向人和审查流程的调查输出。Report 从 snapshot、candidate、profile、probe result 和 adoption record 生成。

Engineering quality toolchain

SeekMoon Go implementation 在本地、CI 和 release 过程中使用的工程质量命令集合。它约束实现物质量，不定义 SeekMoon 面向包消费者的 CLI 行为。

Quality gate

某个工程质量问题的可执行检查入口，例如 format、lint、test、race、coverage、vulnerability、module integrity 或 release configuration check。

Projection

同一内部对象面向不同消费者的输出表面，包括 pretty text、JSON output、shape、schema 和 report。

Pretty text

默认终端阅读输出。

JSON output

当前命令的机器处理输出。它不是 pretty text 的 JSON 化。

jq expression

传递给 SeekMoon 内置 gojq interpreter 的查询表达式。SeekMoon 先生成当前命令 JSON output，再在同一 Go 进程内对该 JSON projection 求值。

Shape

人可读字段树。Shape 说明当前命令 JSON output 的字段、类型和状态枚举。

Schema

当前命令 JSON output 的 JSON Schema。

Error surface

命令失败时的输出表面。它包含失败对象、尝试来源、状态含义和恢复动作。

Relation predicate

xref 边上的 rel 字段。SeekMoon 书使用 depends-on、constrains、projects-to 和 verifies 四个关系谓词。

depends-on

当前标题中的命令、规则或判断依赖目标标题定义的对象。

constrains

当前标题对目标标题的状态、输出范围或合法解释施加约束。

projects-to

当前标题中的对象、命令或命令族投影到目标输出表面。

verifies

当前标题中的行动轨迹或验收条件检查目标对象的公共行为。

Evidence wrapper

带有 status、value、source 和可选 error 的字段包裹对象。它用于表达字段值、来源和缺失状态。

Evidence string

value 为 string 或 null 的 evidence wrapper。

Evidence string array

value 为 string array 或 null 的 evidence wrapper。

Evidence integer

value 为 integer 或 null 的 evidence wrapper。

Evidence object

value 为 object 或 null 的 evidence wrapper。

State value

evidence state 的枚举值。

Source attempt

一次 source resolution 尝试的结果对象，包含 status、path、url 和 error。

Command result

一次本地命令执行的结果对象，包含 command、cwd、exit code、status 和 log path。

API entry

package_data.json 中的 type、value、trait、error 或 method entry。

Root marker

Skills API 中表示 root/default executable package 的空 package 字符串。

present

来源成功给出有效值。

missing

来源存在字段位置，但值为空字符串、空数组、null 或字段缺失。

unknown

当前问题需要判断，但已读取来源不能回答。

failed

HTTP 请求、命令或解析动作已经执行并失败。

unavailable

可选来源不存在，或当前对象没有该可选资产。

derived

SeekMoon 从当前事实计算得到的值。

ManifestProfile

单个 module 的 manifest 证据对象，包含版本、下载量、build status、metadata、versions 和规范化字段。

ModuleIndexTree

module_index.json 中的 module package tree 与紧凑 API index。

PackageData

package_data.json 中的单 package API 详情对象。

SourceResolution

SeekMoon 定位 published source 的结果对象。

ProbeResult

本地验证动作的结果对象。

SearchResult

search 产生的候选结果对象。

Appendix A: 附录 A：公共来源图

Source Surface SeekMoon object Used by

Mooncakes Modules API

GET https://mooncakes.io/api/v0/modules

ModuleSummary

sync、search

Mooncakes Statistics API

GET https://mooncakes.io/api/v0/modules/statistics

Snapshot counters

sync、report

Mooncakes Manifest API

GET https://mooncakes.io/api/v0/manifest/<owner>/<module>;

ManifestProfile

view、compare、source

Mooncakes Skills API

GET https://mooncakes.io/api/v0/skills

SkillEntry

skill search、skill view

Module index asset

GET https://mooncakes.io/assets/<owner>/<module>@<version>/module_index.json

ModuleIndexTree

view、api

Package data asset

GET https://mooncakes.io/assets/<owner>/<module>@<version>/<package-relpath>/package_data.json

PackageData

api

Resource asset

GET https://mooncakes.io/assets/<owner>/<module>@<version>/<package-relpath>/resource.json

Optional resource evidence

view、api、report

Source zip

GET https://download.mooncakes.io/user/<owner>/<module>/<version>.zip

Published source attempt

source

Skill assets

SKILL.md、wasm_url、checksum_url

SkillProfile

skill view

Moon CLI

moon update、moon fetch、moon add、moon check、moon test、moon build

Local command result

sync、source、probe

Local registry index

~/.moon/registry/index/user/*/.index

LocalModuleVersionRecord

sync、search、view、raw

Repository

GitHub or declared repository URL

Repository signal

view、compare、report

每个来源都带 source label、fetch time 和 status。Report output 只列记录的调查实际使用过的来源。

Appendix B: 附录 B：数据字典

54. Evidence Wrapper

Evidence wrapper 是带状态的字段对象。evidence string、evidence string array、evidence integer 和 evidence object 分别表示 value 的类型；它们共享以下字段。

字段 类型 含义

status

state value

present、missing、unknown、failed、unavailable 或 derived。

value

any/null

字段值。

source

string/null

来源 label。

error

string/null

失败信息。

55. Common Structured Types

类型 字段 含义

source attempt

status、path、url、error

一次 source resolution 尝试。

command result

command、cwd、exit_code、status、log_path

一次本地命令执行结果。

api-entry

name、docstring、signature、loc

API symbol entry 的公共字段。

root marker

空字符串

Skills API 中的 root/default executable package marker。

56. ModuleSummary

字段 类型 含义

module

string

完整 owner/module coordinate。

version

string

列表层当前版本。

description

evidence string

用途摘要。

keywords

evidence string array

检索词。

repository

evidence string

repository declaration。

license

evidence string

license declaration。

is_new

boolean

list-level newness flag。

created_at

string

上游时间字符串。

raw

object

原始 item。

57. SearchResult

字段 类型 含义

rank

integer

排序位置。

module

string

候选 module。

version

string

候选版本。

description

evidence string

用途摘要。

license

evidence string

license declaration。

repository

evidence string

repository declaration。

downloads

evidence integer

Manifest enrichment 下载量。

build_status

evidence string

Manifest enrichment 提供的 build status。

target

evidence object

target context 存在时显示。

match

object

命中字段与排序证据。

snapshot_id

string

snapshot ID。

58. ManifestProfile

字段 类型 含义

module

string

module coordinate。

version

string

manifest version。

latest_version

string

latest version。

downloads

integer

下载量。

has_package

boolean

package/docs asset status。

build_status

evidence string

Mooncakes build status。

metadata

object

raw metadata and normalized projection。

versions

array

版本列表。

versions_count

derived integer

版本数量。

docs_url

derived string

Mooncakes docs URL。

59. PackageData Entry

字段 类型 含义

name

string

symbol name。

docstring

evidence string

docstring。

signature

string

raw signature。

plain_signature

derived string

plain text signature。

loc

evidence object

source location。

methods

array

type methods。

impls

array

implementations。

60. SkillEntry

字段 类型 含义

module

string

所属 module。

author

string

作者或 owner。

version

string

版本。

package

string/root marker

executable package path。

name

string

entry 名称。

wasm_url

string

Wasm URL。

checksum_url

string

checksum URL。

repository

evidence string

repository declaration。

runwasm_coordinate

derived string

pinned runwasm coordinate。

61. AdoptionRecord Conclusion

adopt
adopt-with-adapter
continue-verification
contribute-upstream
fork
build-own
reject-for-now

Appendix C: 附录 C：命令速查

命令 Usage Reads Output

doctor

seekmoon doctor

Toolchain、paths、network、project context。

Environment status。

sync

seekmoon sync

Statistics API、Modules API、local index、toolchain。

Snapshot。

search

seekmoon search <query> [--target <target>]

Modules snapshot、visible-result manifest enrichment。

SearchResult array。

view

seekmoon view <module-or-number>

Manifest API、module index asset。

Module profile。

api

seekmoon api <module-or-number> --package <path>

Module index、package data。

API profile。

source

seekmoon source <module-or-number[@version]>

moon fetch、source zip、local cache、core source、repository signal。

SourceResolution。

skill search

seekmoon skill search <query>

Skills API。

SkillEntry candidates。

skill view

seekmoon skill view <entry-or-number>

Skills API、SKILL.md、wasm/checksum assets。

SkillProfile。

compare

seekmoon compare <candidate>…​

已加载 evidence 和请求的 enrichment。

Comparison output。

probe

seekmoon probe <candidate> [--target <target>]

Moon CLI、project/probe context。

ProbeResult。

record

seekmoon record <candidate> --conclusion <value>

Candidate, loaded evidence, probe results。

AdoptionRecord。

report

seekmoon report --format <format>

Records、snapshot、evidence refs。

Report。

raw

seekmoon raw <source> …​

Requested raw source。

Raw payload。

输出型命令的 output mode options：

--json
--jq <expr>
--shape
--schema

--jq <expr> 使用 SeekMoon 内置 gojq interpreter。SeekMoon 把命令 JSON output 作为求值输入，并返回 jq result。

Appendix D: 附录 D：Output Shapes

本附录中的 evidence<T> 表示 value 类型为 T 的 evidence wrapper。api-entry 和 command-result 的字段见 附录 B：数据字典。

62. seekmoon search --shape

seekmoon.search-results.v1

schema: string
snapshot:
  id: string
  sources: string[]
query:
  text: string
  kind: library|skill
  target: string|null
results[]:
  rank: int
  module: string
  version: string
  description: evidence<string>
  license: evidence<string>
  repository: evidence<string>
  downloads: evidence<int>
  build_status: evidence<string>
  target: evidence<string[]>
  match:
    fields: string[]

63. seekmoon view --shape

seekmoon.module-profile.v1

schema: string
module: string
version: string
manifest:
  latest_version: string
  downloads: int
  build_status: evidence<string>
  metadata: object
docs_url: string
packages:
  count: int
  items[]:
    path: string
    relpath: string
source:
  state: not-fetched|present|failed|unavailable
target:
  status: present|unknown|failed

64. seekmoon api --shape

seekmoon.api-profile.v1

schema: string
module: string
version: string
package_path: string
package_relpath: string
types[]:
  name: string
  docstring: evidence<string>
  signature: string
  loc: evidence<object>
  methods[]: api-entry
values[]: api-entry
traits[]: api-entry
errors[]: api-entry

65. seekmoon probe --shape

seekmoon.probe-result.v1

schema: string
module: string
version: string
target: string|null
probe_path: string
steps:
  moon_new: command-result
  moon_add: command-result
  moon_check: command-result
  moon_test: command-result
  moon_check_target: command-result
  moon_build_target: command-result
result:
  status: verifiable|failed|incomplete
logs:
  path: string

Appendix E: 附录 E：状态与错误矩阵

66. State Matrix

状态 触发条件 示例 恢复

present

来源给出有效值。

Manifest license 为 MIT。

不需要恢复。

missing

字段位置存在但无值。

Description 是空字符串。

读取其他来源或记录缺失。

unknown

问题需要判断但已读来源不能回答。

Target support 没有 metadata 或 probe evidence。

执行 probe 或读取更多 evidence。

failed

请求、命令或解析动作失败。

Manifest API timeout；moon fetch 退出非零。

查看 error surface 和 log。

unavailable

可选来源不存在。

resource.json 404。

改读 package data、source 或其他来源。

derived

SeekMoon 从事实计算。

versions_count。

检查来源字段。

67. Error Matrix

错误 State Error surface recovery

Manifest 404

failed

检查 module coordinate 或重新 search。

Module index 404

unavailable or failed

使用 manifest profile 和 source inspection；API index unavailable。

Package path absent

failed

列出 module index 中的已知 package paths。

Resource asset 404

unavailable

继续读取 package data 或 source inspection。

Source zip 404

unavailable

尝试 moon fetch 或 local cache。

moon fetch non-zero

failed

读取 log path；尝试 source zip 或 repository fallback。

Probe target build 失败

failed

记录 local target failure；检查 probe logs。

Repository API unreachable

failed

不加载 repository enrichment，并记录 source failure。

jq expression parse/eval failure

failed

查看对应命令的 --shape，修正表达式，或改用 --json。

Appendix F: 附录 F：Go 实现依赖图

本附录固定 SeekMoon 的 Go 实现依赖选择。实现语言已经确定为 Go；依赖选择只服务本书定义的公共对象、命令契约、输出契约、来源读取、本地验证和记录报告。

本附录只记录 Go source imports 和 test imports。工程质量工具链、CI 入口和 release 工具见 附录 G：Go 工程工具链。

68. Dependency Set

职责 Go module 版本 采纳理由

CLI command surface

github.com/spf13/cobra

v1.10.2

SeekMoon 有多级命令、共享 output mode options、help surface 和 error handling。Cobra 是 Go CLI 事实标准，命令树、flag、completion 和 help 能直接承载 Command Map。

Embedded jq

github.com/itchyny/gojq

v0.12.19

--jq 是进程内输出模式。gojq 是纯 Go jq implementation，可作为 library 编译和运行 jq expression，直接满足 Built-in jq 的对象边界。

Pretty text styling

github.com/charmbracelet/lipgloss/v2

v2.0.4

Pretty text 需要稳定列、状态色和终端宽度处理，但不需要 TUI 框架。Lip Gloss 提供终端样式、布局和宽度控制，覆盖默认阅读输出。

GitHub repository enrichment

github.com/google/go-github/v88

v88.0.0

Repository signal 需要读取 repository、license、release、issue、PR 和 workflow 等 GitHub 事实。go-github 是官方维护的 GitHub REST API Go client，避免手写 endpoint 和分页结构。

GitHub authentication

golang.org/x/oauth2

v0.36.0

GitHub enrichment 需要使用 token 时，OAuth2 transport 是 go-github 的标准认证接入层。匿名请求和 token 请求使用同一 client construction。

MoonBit TOML config parsing

github.com/pelletier/go-toml/v2

v2.4.0

Project context 需要读取 moon.mod 和 moon.pkg TOML 形态。该库是成熟 v2 TOML parser，适合结构化读取；SeekMoon 不把 TOML 当普通字符串处理。

JSON Schema validation

github.com/santhosh-tekuri/jsonschema/v6

v6.0.2

Acceptance 和测试需要验证输出是否满足 schema。该库提供 Draft 2020-12 validation，与本书 Schema Output 对齐。

XDG path resolution

github.com/adrg/xdg

v0.5.3

Snapshot、cache、record 和 report 要落在可解释的本地目录。XDG path resolution 避免手写 Linux/macOS/Windows 目录规则。

Retry policy

github.com/cenkalti/backoff/v5

v5.0.3

HTTP source 读取需要有限重试、退避和上下文取消。backoff 提供小而稳定的 retry primitive，不把网络策略散落在每个 source reader 中。

Table rendering

github.com/jedib0t/go-pretty/v6

v6.8.1

search、compare 和部分 report projection 需要稳定表格。go-pretty 提供表格渲染和宽度控制；Lip Gloss 负责样式，go-pretty 负责表格结构。

Test diff

github.com/google/go-cmp

v0.7.0

Canonical object、JSON output、shape 和 error surface 测试需要结构化 diff。go-cmp 比 reflect.DeepEqual 更适合可维护测试失败输出。

69. Standard Library Responsibilities

以下职责使用 Go standard library，不引入第三方依赖：

职责 包

HTTP client、timeout、redirect、status handling

net/http、context

JSON encoding/decoding

encoding/json

JSON Schema construction

encoding/json

Filesystem traversal、temporary directories、path handling

io/fs、os、path/filepath

Local command execution for Moon CLI

os/exec

Archive handling for source zip

archive/zip

Time, snapshot id, timestamp formatting

time

Hash and checksum verification

crypto/sha256、encoding/hex

70. Derived Implementation Rules

--jq 使用 github.com/itchyny/gojq@v0.12.19。SeekMoon 将当前命令 JSON output 解码为 Go value，交给 gojq interpreter 求值。错误面报告 expression parse/eval failure。

HTTP source reader 使用 net/http、context 和 github.com/cenkalti/backoff/v5@v5.0.3。Mooncakes API、asset 和 source zip 共享同一 fetch result 结构，保留 URL、status、fetch time、parse state 和 error。

Repository enrichment 使用 github.com/google/go-github/v88@v88.0.0 和 golang.org/x/oauth2@v0.36.0。未请求 enrichment 时，repository activity 不进入输出对象；请求失败只改变 repository signal state。

Pretty text 使用 github.com/jedib0t/go-pretty/v6@v6.8.1 生成表格，使用 github.com/charmbracelet/lipgloss/v2@v2.0.4 控制样式。JSON output、shape、schema 和 raw output 不依赖 pretty text 渲染层。

Schema output 使用 Go standard library 构造固定 JSON Schema object，并用 github.com/santhosh-tekuri/jsonschema/v6@v6.0.2 在测试中校验。Schema id 是下游消费者的兼容边界；canonical object struct 不能通过反射自动改写公共 schema。

Appendix G: 附录 G：Go 工程工具链

本附录固定 SeekMoon Go implementation 的工程工具链。工程工具链定义本地开发、CI 和 release artifact 检查使用的命令入口；它不等同于 Go source imports，也不定义 SeekMoon 面向包消费者的 CLI 命令。

71. Tool Version Set

职责 工具 版本或坐标 边界

Go toolchain

go

go1.26.x

编译、测试、fuzz、覆盖率、module 命令和官方静态检查的基础工具链。go1.26.3 linux/amd64 是该基线的本地环境样本。

Test presentation

gotestsum

gotest.tools/gotestsum@v1.13.0

消费 go test -json，提供本地摘要、CI annotation 和 JUnit XML。它不替代 Go test execution core。

Lint aggregation

golangci-lint

github.com/golangci/golangci-lint/v2@v2.12.2

聚合 govet、staticcheck、errcheck、ineffassign、unused、revive、gosec、misspell、gocritic、unparam、nakedret 和 prealloc 等 lint gates。

Formatting

gofumpt

mvdan.cc/gofumpt@v0.10.0

作为 gofmt 的严格超集固定格式化结果。

Import grouping

goimports

Go tools version matched to toolchain policy

整理 imports。该职责可以由编辑器、CI 辅助命令或 lint gate 承担。

Vulnerability exposure

govulncheck

golang.org/x/vuln/cmd/govulncheck@v1.4.0

扫描 Go vulnerability database，并结合调用可达性报告 vulnerability exposure。

Release artifacts

goreleaser

github.com/goreleaser/goreleaser/v2@v2.16.0

检查 release 配置，生成 snapshot 和正式发布 artifacts。

Task orchestration

just

1.50.0

命名并组合工程质量入口。just 是 repo-level task runner，不进入 Go module dependency graph。

72. Installation Coordinates

Go-based tools use pinned go install coordinates:

go install gotest.tools/gotestsum@v1.13.0
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
go install golang.org/x/vuln/cmd/govulncheck@v1.4.0
go install mvdan.cc/gofumpt@v0.10.0
go install github.com/goreleaser/goreleaser/v2@v2.16.0

just is installed as a repository-level command runner through the host package manager, prebuilt binary or CI action. It is not installed through the SeekMoon Go module.

73. Standard Commands

Command Meaning

go test ./…​

Functional test execution.

gotestsum --format=pkgname — -count=1 ./…​

Human-readable local test summary without using cached test success.

gotestsum --format=github-actions --junitfile=.artifacts/test/unit.xml — -count=1 ./…​

CI test output with GitHub Actions annotations and JUnit report.

gotestsum --format=pkgname — -race -count=1 ./…​

Race detector test execution with readable summary.

go test -coverprofile=.artifacts/coverage.out ./…​

Coverage profile generation.

go tool cover -func=.artifacts/coverage.out

Coverage summary.

go test -fuzz=Fuzz -run=^$ ./internal/model ./internal/source

Fuzz target execution for parsers and path derivations owned by SeekMoon.

go vet ./…​

Official Go static checks.

golangci-lint run ./…​

Aggregated lint gate.

gofumpt -w .

Rewrite source formatting.

gofumpt -l .

List files that do not match the formatting gate.

go mod tidy

Synchronize go.mod and go.sum with source imports.

git diff --exit-code — go.mod go.sum

Fail when module metadata changed during go mod tidy.

go mod verify

Verify module cache content against go.sum.

govulncheck ./…​

Report reachable vulnerability exposure.

goreleaser check

Validate release configuration.

goreleaser release --snapshot --clean

Build local snapshot release artifacts.

goreleaser release --clean

Build official release artifacts for a tag release.

74. Lint Configuration Surface

SeekMoon’s lint gate is configured by .golangci.yml at the Go implementation root.

version: "2"
linters:
  enable:
    - govet
    - staticcheck
    - errcheck
    - ineffassign
    - unused
    - revive
    - gosec
    - misspell
    - gocritic
    - unparam
    - nakedret
    - prealloc

gosec enters through golangci-lint. Vulnerability exposure remains the responsibility of govulncheck.

75. Artifact Paths

CI and local quality commands write generated reports under .artifacts/:

.artifacts/
  test/
    unit.xml
    race.xml
  coverage.out

.artifacts/ is generated quality output. It is not a source directory and does not define SeekMoon’s runtime storage contract.

参考文献

索引

本索引 section 为书籍索引生成保留位置。正文中的可见索引词和隐藏索引词是索引入口来源。

核心索引入口包括：

SeekMoon
MoonBit
Mooncakes
Package Discovery
Package discovery workbench
Evidence Source
Input Surface
Snapshot
ModuleSummary
SearchResult
ManifestProfile
ModuleIndexTree
PackageData
SkillEntry
SourceResolution
ProbeResult
AdoptionRecord
Pretty Text
JSON Output
jq
Shape
Schema
Error Surface
published source
repository signal
resource.json
module_index.json
package_data.json
moon fetch
moon runwasm