1. 全局必读上下文

10 号书是 SeekMoon Go implementation 的 Work Breakdown Structure 工作包分解书。它把 9 号书已经定义的人工制品边界、证据来源边界、canonical objects、命令契约、输出契约、Go 架构、工程质量工具链和黑盒验收，投影为可分配、可实现、可审核的工作包。

本章是所有工作包的共同输入。执行者在读取任一工作包前必须读取本章；审核者在审查任一工作包前必须以本章作为判断基准。工作包章节只描述局部交付边界，不重新定义 SeekMoon 的公共对象。

1.1. 术语控制

术语 本书含义

工作包

一个可以交付、测试、审核和追踪的实现责任单元。

执行者

读取工作包并完成对应实现、测试和文档材料的人或 agent。

审核者

使用工作包中的审核尺子检查交付物是否满足 9 号书契约的人或 agent。

全局上下文

所有工作包共享的对象边界、来源边界、架构边界、质量边界和验收边界。

局部依据

某个工作包直接依赖的 9 号书片段。局部依据不能覆盖全局上下文。

完成证据

证明工作包公共行为成立的测试、输出、schema、golden、日志、质量门或黑盒验收结果。

1.2. 阅读契约

工作包的最小消费单元由三个章节组成：全局必读上下文、WBS 依赖图 和一个具体工作包章节。执行者不能只读取工作包标题后进入实现；审核者不能只读取代码 diff 后给出完成判断。

每个工作包的 authored text 规定工作包身份、输入、输出、实现边界、测试责任、审核尺子和完成证据。被 include 的 9 号书材料提供规范依据。规范依据不替代工作包边界；工作包边界不改写规范依据。

1.3. 人工制品边界

1.4. 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。

1.5. 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。

1.6. 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 给出可检查行为。

1.7. 证据来源边界

1.8. Public HTTP Sources

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

1.8.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。

1.8.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。它们随时间变化，不参与单个候选的质量判断。

1.8.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 使用。

1.8.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。

1.9. Static Assets

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

1.9.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 为空。

1.9.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。

1.9.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 提供源码证据。

1.9.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。

1.9.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 内容可校验，不说明发布身份、构建来源或无漏洞状态。

1.10. Local Toolchain and Cache

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

1.10.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。命令失败不改写上游事实。

1.10.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。

1.10.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 命中是当前机器事实，不代表其他机器具备同一缓存。

1.11. 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。

1.12. 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 可以显式加载这些信号。

1.13. 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。

1.14. 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 保留。

1.14.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。

1.15. 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。

1.16. API Profile

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

1.16.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。

1.16.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。

1.17. 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 记录依赖引入验证。

1.18. SourceResolution and ProbeResult

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

1.18.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。

1.18.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 和当前命令序列下可验证。

1.19. 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 使用稳定英文枚举。

1.19.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 成功或失败。

1.20. 命令与输出边界

1.21. 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。

1.22. 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。

1.23. 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 随之变化。

1.24. 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 前提供人可读字段树。

1.25. 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。

1.26. 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 是下游消费者的兼容性边界。

1.27. 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 定义。

1.28. 完整 Go 架构

1.29. 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 的对象边界。

1.30. 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。

1.31. 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 只承载对象、状态词和结构化字段。

1.32. 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。

1.33. Data Flow

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

1.33.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.

1.33.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.

1.33.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.

1.33.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.

1.33.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.

1.33.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.

1.33.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.

1.33.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.

1.33.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.

1.34. 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。

1.35. 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。

1.36. 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。

1.37. 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.

1.38. 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.

1.39. 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。

1.40. 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 实现依赖图.

1.41. 依赖轮子与质量边界

2. 附录 F：Go 实现依赖图

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

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

2.1. 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 更适合可维护测试失败输出。

2.2. 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

2.3. 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。

3. 附录 G：Go 工程工具链

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

3.1. 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。

3.2. 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.

3.3. 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.

3.4. 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.

3.5. 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.

4. 附录 E：状态与错误矩阵

4.1. 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。

检查来源字段。

4.2. 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。

4.3. Library Discovery Journey

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

4.3.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

4.3.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

4.3.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

4.3.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

4.3.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

4.3.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

4.3.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

4.3.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

4.3.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

4.3.10. E10：输出报告

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

状态变化：

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

4.4. Skill Discovery Journey

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

4.4.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

4.4.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

4.4.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

4.5. Pipeline Journey

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

4.5.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

4.5.2. E2：提取 Module

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

状态变化：

pipeline.output = module-list

4.5.3. E3：过滤 JSON

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

状态变化：

pipeline.output = mit-module-list

4.5.4. E4：校验 Schema

seekmoon search --schema

状态变化：

consumer.schema = seekmoon.search-results.v1

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

4.6. Failure Recovery Journey

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

4.6.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

4.6.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

4.6.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。

4.7. 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 的公共工作台表面。

4.8. 全局审核规则

审核结论只接受可观察证据。实现物存在、命令能运行一次、输出看起来完整、测试覆盖率上升，都不能单独构成完成声明。完成声明必须回到公共对象、命令契约、输出投影、状态语义、side effect 边界和质量门。

状态词必须保持 9 号书定义。missing 表示来源位置存在但值为空；unknown 表示当前判断没有证据来源可以回答；unavailable 表示可选来源不存在；failed 表示请求、命令或解析动作已经执行并失败。工作包不得把这些状态合并为普通错误字符串。

来源边界不得互相冒充。Repository signal 不等同于 published source；probe result 不改写 upstream metadata；checksum 不等同于 provenance；download count、build status 和 repository presence 不构成质量证明。

输出投影不得互相代替。Pretty text 服务 terminal reader；JSON output 服务 pipeline consumer；shape 和 schema 服务 contract reader；error surface 服务 failure recovery consumer；report 服务调查审查。任何工作包把一个 projection 的职责塞入另一个 projection，都违反全局上下文。

5. WBS 依赖图

WBS 依赖图规定工作包的批次、先后关系和审核流。它不定义 SeekMoon 的公共功能；公共功能已经由 9 号书定义。它定义实现协作中哪些对象先成立，哪些对象可以并行推进，哪些对象必须在其他对象之后验收。

5.1. 工作包清单

编号 工作包 交付对象

WP01

Go Module Substrate

Go module 骨架、工程入口、质量命令入口。

WP02

Canonical Model and Contracts

Canonical objects、state enum、evidence wrappers、shape/schema contract definitions。

WP03

Platform Runtime and Storage

Runtime composition、platform capabilities、store registries、side effect paths。

WP04

Public HTTP Sources and Snapshot

Mooncakes API readers、fetch envelope、snapshot creation。

WP05

Static Assets and API Profile

Asset readers、API profile construction、package relpath derivation。

WP06

Local Toolchain Source and Probe Primitives

Moon CLI runner、local index/cache readers、project context、probe primitives。

WP07

Repository and Skill Sources

Repository enrichment、Skills API、skill assets、runwasm coordinate derivation。

WP08

Output Pipeline and Error Surface

Pretty text、JSON、jq、shape、schema、error surface renderers。

WP09

CLI Command Surface

Cobra command tree、flags、input parsing、process exit mapping。

WP10

Discovery and Profile Services

doctor、sync、search、view、compare service flows。

WP11

Inspection and Source Services

api、source、skill search、skill view service flows。

WP12

Assessment, Record and Report Services

probe、record、report、raw service flows。

WP13

Black-box Acceptance and Quality Gates

Black-box acceptance、journey tests、quality gates、integration boundaries。

5.2. 批次

Batch A: WP01 -> WP02 -> WP03
Batch B: WP04 || WP05 || WP06 || WP07
Batch C: WP08 -> WP09
Batch D: WP10 || WP11 || WP12
Batch E: WP13

Batch A 建立实现基底。WP01 建立工程壳，WP02 建立对象语言，WP03 建立运行时、平台能力和持久化边界。没有 Batch A，下游 source readers、output projections 和 services 会各自定义对象。

Batch B 建立来源读取能力。WP04、WP05、WP06 和 WP07 在 WP02 与 WP03 后可以并行推进。并行条件是所有 reader 返回带状态的 source result，不直接渲染输出，不直接写 adoption record。

Batch C 建立投影与命令壳。WP08 先让 canonical object 能投影到 pretty text、JSON、jq、shape、schema 和 error surface；WP09 再把 command surface 接入 renderer 和 service registry。

Batch D 建立命令行为。WP10、WP11 和 WP12 使用已经成立的 source readers、stores、output pipeline 和 CLI surface 实现消费者动作。服务层完成声明必须通过输出投影和测试观察。

Batch E 建立验收闭环。WP13 把 A1 到 A16、journey tests 和工程质量门组合为公共对象成立证据。WP13 可以在 Batch A 后建立测试框架，在 Batch B、C、D 中持续接收场景。

5.3. 依赖边

工作包 必须依赖

WP01

无上游工作包。

WP02

WP01 的 Go module 与 test entrypoint。

WP03

WP01 的 module layout，WP02 的 model contracts。

WP04

WP02 的 model/state/source result，WP03 的 HTTP、clock、store path。

WP05

WP02 的 API model，WP03 的 HTTP/FS/cache boundary。

WP06

WP02 的 source/probe model，WP03 的 runner、FS、probe/source paths。

WP07

WP02 的 skill/repository model，WP03 的 HTTP/cache boundary。

WP08

WP02 的 canonical objects 和 contract definitions。

WP09

WP01 的 CLI root，WP03 的 runtime registry，WP08 的 renderer。

WP10

WP04、WP05、WP08、WP09；doctor 还依赖 WP03 和 WP06。

WP11

WP05、WP06、WP07、WP08、WP09。

WP12

WP03、WP06、WP08、WP09、WP10、WP11。

WP13

所有公共 command surface、source readers、services、output projections 和 quality entries。

5.4. 共同完成定义

工作包完成必须满足五项条件。

  • 交付物位于工作包声明的文件边界内。

  • 单元测试或 contract tests 覆盖工作包定义的对象、状态和失败路径。

  • 输出、error surface 或 store artifact 能观察工作包的公共行为。

  • just fmt-check、just lint、just test 和与工作包相关的局部测试通过。

  • 审核者能把交付物映射回本书工作包依据和 9 号书规范依据。

工作包不能用“其他工作包会处理”取消自身边界内的状态语义、错误语义、测试责任或输出契约。下游工作包只能消费已经成立的对象。

6. WP01：Go Module Substrate

6.1. 工作包身份

WP01 建立 SeekMoon Go implementation 的工程基底。该基底包含 Go module metadata、process entrypoint、internal package directories、工程质量入口和生成物目录约定。Mooncakes source readers、canonical model、command services 和 output projections 不属于 WP01 的交付边界。

6.2. 必读依据

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。

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

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 实现依赖图.

职责 工具 版本或坐标 边界

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。

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.

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. 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.

6.3. 输入

WP01 的输入是 9 号书的 Go module layout、Go 1.26.x toolchain baseline、工程质量命令集合、lint configuration surface，以及当前 repository 中 projects/seekmoon 的既有目录约束。

6.4. 输出

输出 内容

go.mod

SeekMoon 单一 Go module metadata。

cmd/seekmoon/main.go

进程入口，只创建 Runtime 并调用 CLI root execution。

internal/ package directories

app、cli、model、source、service、output、store、platform、contract、testutil 的空实现或 package docs。

justfile

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

.golangci.yml

9 号书附录 G 规定的 lint gate。

.goreleaser.yaml

release configuration check 可执行的 release surface。

.artifacts/

测试报告、race 报告和 coverage profile 的生成物位置。

6.5. 实现边界

WP01 交付工程目录和可编译进程入口。cmd/seekmoon 的职责是 process startup；HTTP、filesystem、Moon CLI、public command contract 和业务行为不进入工程基底。

internal 目录可以包含 package-level doc comments。注释只说明 package 的对象职责和边界，不解释显而易见的 Go 语法。

6.6. 测试责任

WP01 的测试责任是 module-level sanity。go test ./…​ 必须在空实现状态下通过；just fmt-check 必须验证格式；go mod tidy 后 go.mod 和 go.sum 不能产生未解释漂移。

6.7. 审核尺子

审核者检查四件事。

  • Go module layout 与 9 号书目录表一致。

  • cmd/seekmoon 只承担 process startup，不承载 source、service 或 output 逻辑。

  • 工程质量入口名称与 9 号书 Engineering Quality Toolchain 一致。

  • .artifacts/ 作为 generated quality output，不进入 runtime storage contract。

6.8. 完成证据

go test ./...
just fmt-check
just mod-check
goreleaser check

这些命令通过时，WP01 只证明工程基底可用。它不证明 SeekMoon 公共 CLI 行为成立。

7. WP02：Canonical Model and Contracts

7.1. 工作包身份

WP02 实现 SeekMoon 的对象语言。对象语言包括 state values、evidence wrappers、common structured types、canonical objects、schema id 和 shape/schema contract definitions。下游 source readers、services、stores 和 output projections 都依赖这些对象。

7.2. 必读依据

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。

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 保留。

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。

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。

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

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。 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。

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 记录依赖引入验证。

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

字段 类型 含义

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。 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 和当前命令序列下可验证。

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 使用稳定英文枚举。 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 成功或失败。

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

失败信息。
类型 字段 含义

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。
字段 类型 含义

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。
字段 类型 含义

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。
字段 类型 含义

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。
字段 类型 含义

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。
字段 类型 含义

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。

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

7.3. 输入

WP02 接收 9 号书 canonical model 与 data dictionary。它不读取真实 HTTP、filesystem 或 command output。所有字段、枚举、schema id 和 wrapper 类型必须来自规范材料。

7.4. 输出

路径 对象

internal/model/evidence.go

State enum、evidence wrappers、source labels、state helpers。

internal/model/module.go

ModuleSummary、SearchResult、match evidence、snapshot reference。

internal/model/manifest.go

ManifestProfile、metadata normalized projection、target metadata state。

internal/model/api.go

ModuleIndexTree、PackageData、API entry、package relpath structures。

internal/model/skill.go

SkillEntry、SkillProfile、root marker、runwasm coordinate field。

internal/model/source.go

SourceResolution、SourceAttempt、selected source、files summary。

internal/model/probe.go

ProbeResult、CommandResult、probe step results。

internal/model/record.go

AdoptionRecord、conclusion enum、evidence refs、not confirmed items。

internal/model/report.go

Report sections 和 report input structures。

internal/model/snapshot.go

Snapshot id、source snapshot status、statistics summary。

internal/model/project.go

Project identity、project context state、path boundary。

internal/contract/shapes.go

Human-readable shape definitions。

internal/contract/schemas.go

JSON Schema objects and schema id constants。

7.5. 实现边界

internal/model 只定义对象、状态词和结构化字段。它只能使用 Go standard library。它不得导入 Cobra、gojq、HTTP client、filesystem implementation、source reader、output renderer 或 store package。

internal/contract 定义 command output contracts。Contract definitions 可以依赖 model 的枚举和 schema id 常量，但不能通过 reflection 自动把 Go struct 变成 public schema。Schema id 是下游消费者兼容边界，必须显式维护。

7.6. 测试责任

WP02 需要 model tests、schema tests 和 fuzz tests 的基础目标。

  • Evidence wrapper 的 JSON round-trip。

  • State enum 的 string parsing 与 validation。

  • missing、unknown、failed、unavailable 的语义单元测试。

  • Module coordinate parser。

  • Package relpath derivation。

  • Adoption conclusion enum validation。

  • Shape output contract snapshots。

  • JSON Schema compilation tests。

  • Coordinate 与 relpath derivations 的 fuzz tests。

7.7. 审核尺子

审核者检查五项。

  • 状态词集合完全等于 9 号书定义。

  • missing 与 unknown 的类型和 helper 不能互相替代。

  • Evidence wrapper 保留 status、value、source 和可选 error。

  • raw payload 字段只出现在规范允许的对象里。

  • Schema id、shape 和 model 字段名称保持一致，但 schema 不由 struct reflection 自动生成。

7.8. 完成证据

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

WP02 完成后，稳定对象语言成为下游来源读取、服务组合和输出投影的依赖。

8. WP03：Platform Runtime and Storage

8.1. 工作包身份

WP03 实现 SeekMoon 的 host capability boundary、runtime composition 和 storage boundary。它把 clock、filesystem、HTTP client、command runner、path resolution、stores、source registry、service registry 和 renderer registry 装配为一次进程执行可消费的 Runtime。

8.2. 必读依据

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。

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.

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。

8.3. 输入

WP03 接收 WP02 的 model types、state values、common structured types，以及 WP01 的 module layout 和工程质量入口。具体 Mooncakes readers、business services 和 renderers 的业务规则不属于 WP03。

8.4. 输出

路径 对象

internal/platform/clock.go

Clock interface 和 system clock implementation。

internal/platform/fs.go

Filesystem interface 和 OS filesystem implementation。

internal/platform/http.go

带 timeout 和 context behavior 的 HTTP client construction。

internal/platform/exec.go

Command runner interface、command result mapping 和 log writer hook。

internal/platform/env.go

Environment summary 和 integration flag access。

internal/store/paths.go

Project storage 和 XDG cache path resolution。

internal/store/snapshot_store.go

Snapshot read/write contract。

internal/store/session_store.go

Session-local candidate number mapping。

internal/store/record_store.go

Adoption record persistence。

internal/store/report_store.go

Report projection persistence。

internal/store/cache_store.go

Reusable remote payload and asset cache。

internal/app/runtime.go

Runtime struct 和 construction sequence。

8.5. 实现边界

WP03 拥有路径构造和 host capability abstraction。Services 决定何时创建 snapshots、records、reports、probe directories 或 source directories。Stores 不决定 adoption conclusions、source priority 或 output shape。

Project storage 位于当前 project context 下的 .seekmoon/。Reusable cache 位于 $XDG_CACHE_HOME/seekmoon/。Probe 与 source resolution paths 是受控 side effects。当前 project manifest mutation 必须由显式 command surface 表达，不能隐藏在 store methods 中。

8.6. 测试责任

WP03 tests 使用 t.TempDir() 和 fake platform implementations。测试覆盖 path construction、XDG fallback、project storage directories、cache storage directories、必要位置的 atomic write behavior、session candidate mapping、record/report path sanitization 和 command log path generation。

8.7. 审核尺子

审核者检查四项。

  • Runtime construction order 遵循 process environment → path resolution → platform clients → source readers → stores → services → renderer → runtime value → CLI command tree。

  • context.Context 能到达 HTTP requests、repository enrichment、Moon CLI commands、downloads 和 probe commands。

  • Store package 拥有读写 mechanics，不拥有 business decisions。

  • Side effect paths 与 9 号书 storage contract 一致。

8.8. 完成证据

go test ./internal/platform ./internal/store ./internal/app

WP03 完成后，Runtime 成为 source readers、services、output pipeline 和 CLI command surface 使用可替换 host capabilities 的装配入口。

9. WP04：Public HTTP Sources and Snapshot

9.1. 工作包身份

WP04 实现 Mooncakes public HTTP sources 和 snapshot creation 所需 source readers。它读取 Modules API、Statistics API 和 Manifest API，把 HTTP result 转换为带 source label、fetch time、status、parse state、raw reference 和 normalized value 的 SourceResult。

9.2. 必读依据

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

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。

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。它们随时间变化，不参与单个候选的质量判断。

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 使用。

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。

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.

9.3. 输入

WP04 接收 WP02 的 ModuleSummary、ManifestProfile、Snapshot 和 source result types，接收 WP03 的 HTTP client、clock、cache store 和 snapshot store。

9.4. 输出

路径 对象

internal/source/fetch.go

Shared HTTP fetch behavior、timeout、redirect handling、retry policy、status classification、JSON decoding。

internal/source/mooncakes.go

Modules API、Statistics API 和 Manifest API readers。

internal/service/sync.go

sync service 的 source composition skeleton 和 snapshot write。

internal/testutil/fixture.go

HTTP fixtures for modules、statistics、manifest success、non-2xx、parse failure。

9.5. 实现边界

Modules API 是 library module search 的基础 input surface。它不提供 downloads、build status、package tree、API details、target proof、source files、repository activity 或 vulnerability status。WP04 不得在 modules reader 中派生质量判断。

Statistics API 给出 registry snapshot counters。Counters 只说明调查时的数据口径，不参与单个候选质量判断。

Manifest API 是单 module profile 的 registry profile 来源。Manifest metadata 是开放对象；WP04 只规范化已知字段并保留 raw metadata。Target metadata 只能作为 source evidence，不能被解释为 probe proof。

9.6. 测试责任

WP04 的测试覆盖：

  • 带有效 JSON 的 HTTP 2xx 映射为 present source action。

  • HTTP timeout 或 non-2xx 映射为带 URL 和 error 的 failed source action。

  • JSON parse failure 记录 parse state。

  • 空 description、keywords、repository、license 映射为 missing evidence fields。

  • Manifest module 与 name 不一致时进入 profile construction 的 failure path。

  • sync 在 snapshot state 中记录 partial source failure。

9.7. 审核尺子

审核者检查五项。

  • Source labels 保持稳定：modules_api、statistics_api、manifest_api。

  • Fetch result 携带 URL、fetched_at、status、parse_state、raw_ref，以及存在时的 error。

  • Modules API reader 不读取 asset 或 repository data。

  • Manifest reader 保留 raw metadata 和 normalized projection。

  • Snapshot failure semantics 不抹除已经成功的部分来源。

9.8. 完成证据

go test ./internal/source ./internal/service -run 'Test(Mooncakes|Sync)'

WP04 完成后，sync 和 search 依赖 public HTTP source snapshots。Candidate ranking 和 adoption decision 仍在本工作包边界之外。

10. WP05：Static Assets and API Profile

10.1. 工作包身份

WP05 实现 Mooncakes static asset readers 和 API profile construction。它读取 module_index.json、package_data.json、可选 resource.json 和 source zip，把 package tree、API detail、resource state 和 source zip attempt 转换为 canonical objects。

10.2. 必读依据

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

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 为空。

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。

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 提供源码证据。

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。

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 内容可校验，不说明发布身份、构建来源或无漏洞状态。

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

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。 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。

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。

10.3. 输入

WP05 接收 WP02 的 ModuleIndexTree、PackageData、API entry、evidence wrappers、source attempt types，接收 WP03 的 HTTP/FS/cache capabilities，并在需要时接收 WP04 的 manifest version resolution。

10.4. 输出

路径 对象

internal/source/assets.go

Module index、package data、resource asset 和 source zip readers。

internal/model/api.go

Asset-specific parsing helpers owned by model where pure derivation is required。

internal/source/fetch.go

需要复用 WP04 时使用的 shared asset fetch behavior。

internal/testutil/fixture.go

Module index、package data、resource 404 和 source zip fixtures。

10.5. 实现边界

module_index.json 当前事实表面使用 childs。Parser 可兼容 children，但 canonical authored surface 仍为 childs。Package relpath 必须由 package path 和 module coordinate 派生。Root package 的 relpath 为空。

package_data.json 保留 raw signature。Plain text signature 是 derived projection，不能替代 raw signature。Source location 的缺失保持为 evidence state，本身不构成 command failure。

resource.json 是 optional source。HTTP 404 映射为 unavailable，不表示 package absence、API data absence 或 module absence。Source zip 失败不证明 module absence，并且必须作为 SourceResolution 中的一个 source attempt 保留。

10.6. 测试责任

WP05 的测试覆盖：

  • 使用 childs 的 module index tree parsing。

  • Root package 和 nested package paths 的 package relpath derivation。

  • Package path absent error data 包含 known package paths。

  • Package data 解析 types、traits、errors、typealias、values、misc 和 methods。

  • HTML signature 在保留 raw signature 的同时生成 plain signature。

  • resource.json 404 映射为 unavailable。

  • Source zip redirect 与 zip reading 生成 files summary。

10.7. 审核尺子

审核者检查五项。

  • Asset URL construction 使用 manifest version 和 derived package relpath。

  • Package relpath derivation 不在各 command 中手写。

  • Resource asset state 不阻断 package data API profile。

  • Raw signature 和 raw payload audit material 对 JSON/raw surfaces 可用。

  • Source zip 是 source attempt，不是唯一 published source route。

10.8. 完成证据

go test ./internal/source ./internal/model -run 'Test(Asset|ModuleIndex|PackageData|Relpath|SourceZip)'

WP05 完成后，view 和 api services 通过 canonical objects 消费 module index 与 package data，HTTP shape details 保持在 source reader 边界内。

11. WP06：Local Toolchain Source and Probe Primitives

11.1. 工作包身份

WP06 实现本地 MoonBit toolchain、local registry index、registry cache、core source、project context 和 probe primitives。它把本地命令和本地文件系统事实转换为 local source result、command result、project context 和 probe-ready path objects。

11.2. 必读依据

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

命令 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。命令失败不改写上游事实。

~/.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。

~/.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 命中是当前机器事实，不代表其他机器具备同一缓存。

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。

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 和当前命令序列下可验证。

11.3. 输入

WP06 接收 WP02 的 SourceAttempt、CommandResult、ProbeResult、project context types，接收 WP03 的 Runner、FS、Paths、Probe store 和 Source store。

11.4. 输出

路径 对象

internal/source/mooncli.go

Moon command invocation 和 command result mapping。

internal/source/local_index.go

Local registry JSONL parser 和 index summary。

internal/source/local_cache.go

Registry cache、assets cache 和 core source readers。

internal/source/project.go

面向 moon.mod、moon.mod.json、moon.pkg、moon.pkg.json 的 MoonBit project context reader。

internal/store/paths.go

Probe、source 和 log path construction。

internal/testutil/fixture.go

Fake runner、fake local index、fake project context fixtures。

11.5. 实现边界

Moon CLI commands 记录 command、cwd、environment summary、exit status 和 log path。Command failure 不改写 upstream facts。moon add success 不等于 adoption success。moon check 与 moon build --target results 是绑定 environment、version 和 target 的 local derived evidence。

Local registry index 是 JSON Lines。WP06 只规范化当前 model 表达的字段，并保留 raw line 供 audit 使用。Local cache hit 是当前机器事实，不推出其他机器具备同一 cache。

Project context 可 enrich search、probe、record 和 report。Read failure 不阻断 global search，但影响 contextual probe 和 report。Probe mutation 的默认位置是 .seekmoon/probes/<id>。

11.6. 测试责任

WP06 的测试覆盖：

  • moon --version command result mapping。

  • Non-zero moon fetch 和 moon build 生成 failed command result 和 log path。

  • Local index JSONL parser 处理 sparse records 和 malformed lines。

  • Project context reader 处理 TOML 与 JSON file variants。

  • Probe path construction 具有 deterministic 和 project-bounded 性质。

  • Core source reader 区分 present、unavailable 和 failed filesystem states。

11.7. 审核尺子

审核者检查五项。

  • Runner calls 具备 context-aware 和 log-bearing 属性。

  • Local command failure 是 source evidence，不是 upstream metadata mutation。

  • Probe default path 位于 .seekmoon/probes/。

  • Project manifest mutation 不隐藏在 local primitives 中。

  • 没有 metadata 或 probe evidence 的 target support 保持 unknown。

11.8. 完成证据

go test ./internal/source ./internal/store -run 'Test(MoonCLI|LocalIndex|LocalCache|Project|ProbePath)'

WP06 完成后，source resolution 和 probe services 复用 local primitives，command execution rules 保持单一实现边界。

12. WP07：Repository and Skill Sources

12.1. 工作包身份

WP07 实现 repository signal reader、Skills API reader、skill asset reader 和 runwasm coordinate derivation。它处理 maintenance evidence 与 executable Wasm entries，不处理 library dependency adoption。

12.2. 必读依据

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 可以显式加载这些信号。

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。

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 记录依赖引入验证。

|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。 --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。

12.3. 输入

WP07 接收 WP02 的 SkillEntry、SkillProfile、repository signal、evidence wrappers，接收 WP03 的 HTTP client、cache path，以及 WP04 的 shared fetch envelope。

12.4. 输出

路径 对象

internal/source/repository.go

GitHub repository enrichment reader 和 repository signal mapping。

internal/source/skills.go

Skills API list/detail reader、SKILL.md reader、wasm/checksum asset reader。

internal/model/skill.go

WP02 尚未完成时使用的 pure runwasm coordinate derivation helper。

internal/testutil/fixture.go

Repository 和 skill fixtures。

12.5. 实现边界

Repository signal 回答 maintenance questions，不回答 registry publication facts。Repository main branch 可能不同于 registry published source。Repository enrichment 只在 command 或 report evidence refs 请求后出现。Repository enrichment failure 只改变 repository signal state，不使无关 manifest 或 module profile fields 失败。

Skill entry 属于 executable path，不属于 library dependency candidate。Skill checksum 校验 artifact content，不证明 publishing identity、build provenance 或 vulnerability status。Skill record 与 report 可以存在；library adoption conclusion 保持独立。

12.6. 测试责任

WP07 的测试覆盖：

  • Repository URL parsing 和 unsupported repository state。

  • GitHub archived、pushed_at、license、release、issue、PR、workflow、README/tests/examples mapping。

  • Repository unreachable 映射为 failed repository signal，且不使 module profile 失败。

  • Skills API list 和 detail parsing。

  • Empty skill package 映射为 root marker。

  • Skill asset fetch 映射 SKILL.md、wasm 和 checksum states。

  • Pinned runwasm coordinate derivation。

12.7. 审核尺子

审核者检查五项。

  • go-github 和 OAuth2 imports 保持在 internal/source 内。

  • Repository signal 不替代 published source resolution。

  • SkillEntry 和 ModuleSummary 保持不同 candidate models。

  • Checksum wording 与 state 不暗示 provenance。

  • 未请求的 enrichment 不进入 output objects。

12.8. 完成证据

go test ./internal/source ./internal/model -run 'Test(Repository|Skill|Runwasm)'

WP07 完成后，skill services 和 optional repository enrichment 消费各自 source readers，library discovery semantics 保持独立。

13. WP08：Output Pipeline and Error Surface

13.1. 工作包身份

WP08 实现 SeekMoon 的 output pipeline。它把 command result 投影为 pretty text、JSON output、built-in jq result、shape output、schema output 和 error surface。Evidence source 读取、business service 执行和 adoption conclusion 决策不属于 WP08。

13.2. 必读依据

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。

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 随之变化。

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 前提供人可读字段树。

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。

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 是下游消费者的兼容性边界。

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 定义。

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。

13.3. 输入

WP08 接收 WP02 的 canonical objects 和 contract definitions。Source readers 不进入 WP08。Writers 和 style configuration 通过 runtime construction 进入 renderer。

13.4. 输出

路径 对象

internal/output/render.go

Renderer interface、output request、mode dispatch。

internal/output/pretty.go

Pretty text rendering for current canonical objects。

internal/output/json.go

带 schema id、input、snapshot、result object、evidence states 和 source labels 的 JSON output。

internal/output/jq.go

gojq-backed expression compilation、evaluation 和 failure mapping。

internal/output/shape.go

Human-readable shape rendering from internal/contract。

internal/output/schema.go

JSON Schema rendering from internal/contract。

internal/output/error.go

Failure recovery projection。

internal/testutil/golden.go

Pretty text、JSON、shape 和 error surface 的 golden helpers。

13.5. 实现边界

Pretty text 是 terminal projection，不能成为 parsing interface。JSON output 是 command canonical object projection，不是 pretty text serialized as JSON。--jq 消费 JSON projection，不读取 pretty text。Shape 和 schema 是 contract projections，不需要真实 query execution。Command failure 或 projection-specific failure 阻止 requested projection 时，output pipeline 生成 error surface。

13.6. 测试责任

WP08 的测试覆盖：

  • search、view、api、probe 和 error cases 的 pretty text golden outputs。

  • JSON output 包含 schema id 和 evidence states。

  • gojq expression 从 command JSON projection 返回预期值。

  • gojq parse/eval failure 映射为带 jq_expression object 的 error surface。

  • Shape output 使用 contract definitions，而不是 sample result values。

  • Schema output 可编译为 Draft 2020-12 JSON Schema。

  • Error surface 包含 command、object、source、state、meaning、recovery，以及存在时的 log path。

13.7. 审核尺子

审核者检查五项。

  • internal/output 不导入 internal/source。

  • Projection modes 只消费 canonical object 或 contract definitions。

  • Normal pretty text 不包含 recovery tutorial text。

  • jq errors 使用 error surface，不 panic，不打印 raw stack traces。

  • Schema id 稳定且显式。

13.8. 完成证据

go test ./internal/output ./internal/contract

WP08 完成后，renderer 承担 command handlers 与 services 的 output decisions。

14. WP09：CLI Command Surface

14.1. 工作包身份

WP09 实现 SeekMoon 的 Cobra command surface。它定义 root command、subcommands、flags、input parsing、output mode options、thin command handlers 和 process exit mapping。Source reading、business service composition 和 rendering internals 不属于 WP09。

14.2. 必读依据

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。

所有 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。

命令 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。

14.3. 输入

WP09 接收 WP03 Runtime、service registry placeholders 和 WP08 Renderer。Command names 与 usage surfaces 来自 9 号书 command map。

14.4. 输出

路径 对象

internal/cli/root.go

Root command、global flags、output mode options、command registration。

internal/cli/doctor.go

seekmoon doctor syntax 和 input object。

internal/cli/sync.go

seekmoon sync syntax 和 input object。

internal/cli/search.go

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

internal/cli/view.go

seekmoon view <module-or-number> syntax。

internal/cli/api.go

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

internal/cli/source.go

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

internal/cli/skill.go

seekmoon skill search 和 seekmoon skill view syntax。

internal/cli/compare.go

seekmoon compare <candidate>…​ syntax。

internal/cli/probe.go

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

internal/cli/record.go

seekmoon record <candidate> --conclusion <value> syntax。

internal/cli/report.go

seekmoon report --format <format> syntax。

internal/cli/raw.go

seekmoon raw <source> …​ syntax。

internal/cli/flags.go

Shared flag parsing 和 output mode validation。

14.5. 实现边界

Cobra types 保持在 internal/cli。Command handlers 校验 surface syntax、构造 input object、调用一个 service method，并把 result/error 交给 renderer。HTTP URLs 构造、file reading、Moon CLI execution、table formatting 和 record writing 不进入 command handlers。

Command parameters 使用对象名：query、module coordinate、package path、candidate number、target、record conclusion。Endpoint URLs、asset URLs、local paths 和 cache paths 保持为 internal implementation details。

14.6. 测试责任

WP09 的测试覆盖：

  • Command registration 与 help surface 包含全部 command names。

  • Required argument 和 flag parse failures 映射为 exit code 2。

  • Output mode flags 可用于 output-capable commands。

  • --jq 缺少 expression 时触发解析失败。

  • Candidate number 和 module coordinate syntax 产生不同 input objects。

  • Thin handler 只调用 expected service method 一次。

  • Service error 传递给 renderer，并映射为 exit code 1。

14.7. 审核尺子

审核者检查五项。

  • internal/cli 导入 Cobra、model/service/output input types，不导入 source readers。

  • Command handlers 遵循 parse args → build input → context → service → render → exit mapping。

  • Help surface 说明 command syntax，不暴露 hidden implementation URLs。

  • Output mode handling 共享且一致。

  • Process exit 与 evidence state 保持为不同对象。

14.8. 完成证据

go test ./internal/cli

WP09 完成后，command surface 支持 fake services 调用和 fake canonical objects 渲染；concrete service work packages 具备独立推进入口。

15. WP10：Discovery and Profile Services

15.1. 工作包身份

WP10 实现 doctor、sync、search、view 和 compare service flows。这些 services 产生 environment status、snapshot、library module candidates、module profiles 和 evidence comparison objects。

15.2. 必读依据

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

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。

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

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。它展示证据差异，消费者根据上下文作出判断。

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.

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.

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.

15.3. 输入

WP10 按需接收 WP04、WP05、WP06 的 source readers，接收 WP03 的 stores、WP08 的 renderer、WP09 的 command inputs 和 WP02 的 model objects。

15.4. 输出

路径 对象

internal/service/doctor.go

Environment status service。

internal/service/sync.go

Snapshot creation service。

internal/service/search.go

Library module search、rank、manifest enrichment、session candidate mapping。

internal/service/view.go

Manifest profile with module index summary。

internal/service/compare.go

Evidence comparison object。

15.5. 实现边界

doctor 读取 environment 并报告 status。它不创建 snapshot，不更新 registry，不写 record。

sync 创建 dated evidence snapshot。它记录 moon update result、Modules API、Statistics API、local registry index 和 toolchain versions。Candidate ranking 与 adoption decision 位于 sync flow 之外。

search 从 query 和 snapshot 生成 library module candidates。它为 visible-window 读取 manifest enrichment，以填充 downloads 与 build status。Package data、published source 和 probe evidence 不属于 search 的读取范围。

view 展示一个 module profile。它读取 Manifest API 和 module index asset，不展开全部 API symbols。Repository activity 只在 requested enrichment 已加载时进入 output。

compare 对齐 loaded evidence fields，并且不生成 quality score。

15.6. 测试责任

WP10 的测试覆盖：

  • Doctor 使用 fake capabilities 报告 toolchain、paths、network 和 project context。

  • Sync 写入带 source status 和 partial failure state 的 snapshot。

  • Search 使用 latest snapshot 或 transient modules fetch。

  • Search rank 包含 match evidence，并写入 session candidate map。

  • Manifest enrichment failure 出现在 result field state。

  • View 读取 manifest 与 module index，并报告 package count/index state。

  • Compare 对齐多个 candidates，且不生成 score。

15.7. 审核尺子

审核者检查五项。

  • Discovery services 不把 downloads/build/repository presence 转换成 quality proof。

  • Session-local candidate numbers 绑定 snapshot/session boundary。

  • Target 在 metadata/probe evidence 出现前保持 unknown。

  • Compare output 是 evidence alignment，不是 ranking 或 recommendation。

  • Services 组合 source results 和 stores，不直接 render。

15.8. 完成证据

go test ./internal/service -run 'Test(Doctor|Sync|Search|View|Compare)'

WP10 完成后，Library Discovery Journey 的 E1 到 E4 和 E7 由 services、fake readers 与 stores 驱动。

16. WP11：Inspection and Source Services

16.1. 工作包身份

WP11 实现 api、source、skill search 和 skill view service flows。这些 services 支持 API reading、published source resolution 和 executable skill discovery。

16.2. 必读依据

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。

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；在当前项目执行可变更命令时，命令表面必须显式表达目标。

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。

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.

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.

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.

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

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
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
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

16.3. 输入

WP11 接收 WP05 的 asset readers、WP06 的 local source primitives、WP07 的 repository/skill sources、WP03 的 stores、WP09 的 CLI inputs 和 WP08 的 output pipeline。

16.4. 输出

路径 对象

internal/service/api.go

Package API profile service。

internal/service/source.go

Source resolution planner 和 selected source derivation。

internal/service/skill.go

Skill search 和 skill profile service。

16.5. 实现边界

api 解析 module version、加载 module index、派生 package relpath，并读取 package data。Package path failure 依据 module index 解释，error surface 列出 known package paths。resource.json unavailable 不阻断 package data。

source 记录每个 source resolution attempt：moon fetch、source zip、local cache、core local source 和 repository fallback signal。selected_source 从 successful attempts 派生。Repository fallback 必须标记为 repository signal，不标记为 registry published source。

skill search 与 skill view 处理 executable entries。Skill execution verification 与 library dependency probe 保持为不同路径。

16.6. 测试责任

WP11 的测试覆盖：

  • API service 在 package data 之前加载 module index。

  • Package relpath 从 canonical package path 派生。

  • Package path absent 返回包含 known package list 的 error surface data。

  • Source resolution 记录所有 attempts，并以 deterministic 规则选择 selected source。

  • Contract 允许时，moon fetch failure 继续进入其他 attempts。

  • Skill search 使用 Skills API，不使用 Modules API。

  • Skill view 加载 SKILL.md、wasm/checksum asset states，并派生 runwasm coordinate。

16.7. 审核尺子

审核者检查五项。

  • api 不重新执行 search；它消费 resolved module/package input。

  • Source resolution 不折叠 failed/unavailable/unknown attempts。

  • Repository fallback wording 不声称 published source。

  • Skill profile 不进入 library adoption conclusion。

  • Services 保留 JSON/raw audit surfaces 所需 raw source metadata。

16.8. 完成证据

go test ./internal/service -run 'Test(API|Source|Skill)'

WP11 完成后，Library Discovery Journey E5、E6 和 Skill Discovery Journey E1/E2 由 fake readers 驱动。

17. WP12：Assessment, Record and Report Services

17.1. 工作包身份

WP12 实现 probe、record、report 和 raw service flows。这些 services 生成 local derived evidence、持久化 adoption decisions、投影 investigation reports，并暴露 raw payloads 供 audit 使用。

17.2. 必读依据

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 下未通过验证。

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

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

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。

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 使用稳定英文枚举。 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 成功或失败。

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。

17.3. 输入

WP12 接收 WP06 的 probe primitives、WP10/WP11 的 candidate/session records、WP03 的 stores、WP02 的 model 与 conclusion enums、WP08 的 renderer 和 WP09 的 CLI inputs。

17.4. 输出

路径 对象

internal/service/probe.go

Probe command sequence 和 ProbeResult construction。

internal/service/record.go

AdoptionRecord creation 和 persistence。

internal/service/report.go

由 records、snapshot 和 evidence refs 生成的 Report projection。

internal/service/raw.go

Raw payload envelope service。

17.5. 实现边界

Probe 创建 local derived evidence。它只证明 current environment、current version、current target 和 current command sequence 下的结果。Probe failure 不证明 upstream metadata 错误。

Record 持久化 candidate、version、snapshot、evidence refs、conclusion、not confirmed items 和 note。Conclusion enum 固定为：adopt、adopt-with-adapter、continue-verification、contribute-upstream、fork、build-own、reject-for-now。

Report 只列出 records 与 evidence refs 实际使用的 sources。Repository enrichment 未执行时，report 不编造 repository activity。Probe 未执行时，report 不声称 validation success 或 failure。

Raw output 保留 upstream field names 和 source status。它为 audit 绕过 ordinary normalization；它不成为 normal discovery path。

17.6. 测试责任

WP12 的测试覆盖：

  • Probe command sequence 使用 isolated probe path。

  • Command results 包含 command、cwd、exit code、status 和 log path。

  • Target build failure 生成带 failed status 与 logs 的 ProbeResult。

  • Record 校验 conclusion enum，并写入 evidence refs。

  • Report 省略 evidence refs 中不存在的 sources。

  • Raw service 返回带 source URL/path、fetch status 和 timestamp 的 raw payload envelope。

17.7. 审核尺子

审核者检查五项。

  • Probe 不自动修改 upstream facts 或 adoption record。

  • Record 不接受任意 conclusion strings。

  • Report 不添加 unobserved sources。

  • Raw service 不 normalize，也不隐藏 upstream fields。

  • Service flow 保持 store-backed 和 renderer-independent。

17.8. 完成证据

go test ./internal/service -run 'Test(Probe|Record|Report|Raw)'

WP12 完成后，Library Discovery Journey E8 到 E10 和 raw audit flows 由 service tests 与 CLI integration tests 执行。

18. WP13：Black-box Acceptance and Quality Gates

18.1. 工作包身份

WP13 把 public behavior 表达为 executable acceptance 和 engineering quality gates。Journey tests、black-box CLI tests、schema validation tests、golden output tests、integration boundaries 和 just ci gate composition 属于 WP13。

18.2. 必读依据

以下行为从命令表面成立时，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 的公共工作台表面。

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。

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 实现依赖图.

18.3. 输入

WP13 接收上游工作包交付的 public command surfaces、source reader fakes、stores、renderer、schemas、golden fixtures 和 quality commands。

18.4. 输出

路径 对象

internal/testutil/fixture.go

Reusable source、service 和 CLI fixtures。

internal/testutil/golden.go

Golden file helpers 和 update policy。

tests/blackbox/

A1 到 A16 的 CLI black-box acceptance tests。

tests/journey/

Library、skill、pipeline 和 failure recovery journey tests。

tests/integration/

Opt-in real network、Moon CLI、GitHub 和 probe mutation tests。

justfile

Final just ci composition 和 integration test commands。

18.5. 实现边界

默认测试具备 offline、repeatable、无 external side effects 三个属性。使用 real network、real Moon CLI、GitHub API、source zip downloads 或 probe project mutation 的测试只在显式 integration environment variables 存在时运行。

Coverage 暴露 test reach。它不是唯一 acceptance condition。质量门通过不取消 black-box behavior checks。Black-box acceptance 保持为与实现语言无关的 public behavior evidence。

18.6. 验收矩阵

范围 验收对象 测试形式

A1-A3

Search candidates、session number、library/skill split。

使用 fake source server 的 black-box CLI tests。

A4-A6

Module profile、API profile、source resolution。

Journey 和 service-backed CLI tests。

A7-A8

Target unknown 与 local derived probe evidence。

Probe fixture tests 和 CLI output checks。

A9-A10

Adoption record 和 report source discipline。

Store-backed black-box tests。

A11-A16

Pretty text、JSON、jq、shape、schema 和 error surface。

Golden、schema validation 和 failure recovery tests。

Engineering gates

format、lint、test、race、coverage、vuln、mod、release check。

just ci 和 individual gate tests。

18.7. 审核尺子

审核者检查五项。

  • A1 到 A16 均映射到 executable test names。

  • 默认测试不依赖 network、Moon CLI mutation 或 GitHub token。

  • Integration tests 是 opt-in，且名称可见。

  • Golden output 变更需要 intentional review。

  • just ci 组合 local development 与 CI policy 使用的同一组 gates。

18.8. 完成证据

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

WP13 完成后，SeekMoon implementation material 按 public behavior、projection contracts 和 engineering quality gates 接受审查。

19. 来源引用图

本章记录 10 号书引用 9 号书的位置。维护者使用本章复查 include 路径、行号范围和交叉引用质量。

19.1. 全局上下文引用

10 号章节 9 号来源

全局必读上下文

parts/010-artifact-and-workbench/020-seekmoon-object-definition.adoc

全局必读上下文

parts/010-artifact-and-workbench/030-consumer-actions.adoc

全局必读上下文

parts/010-artifact-and-workbench/040-cli-workbench-environment.adoc

全局必读上下文

parts/020-evidence-boundary/*.adoc

全局必读上下文

parts/030-canonical-model/010-evidence-state.adoc

全局必读上下文

parts/040-command-workbench/010-command-map.adoc

全局必读上下文

parts/050-output-contracts/*.adoc

全局必读上下文

parts/055-go-implementation-architecture/*.adoc

全局必读上下文

backmatter/appendix-e-status-and-error-matrix.adoc

全局必读上下文

backmatter/appendix-f-go-implementation-dependencies.adoc

全局必读上下文

backmatter/appendix-g-go-engineering-toolchain.adoc

全局必读上下文

parts/060-journeys-and-acceptance/050-black-box-acceptance.adoc

19.2. 工作包局部引用

工作包 主要 9 号来源

WP01

Go Module Layout、Engineering Quality Toolchain、Go 工程工具链。

WP02

Canonical 数据模型、数据字典。

WP03

Runtime Composition、Storage and Side Effects、Project Context。

WP04

Public HTTP Sources、Source Reader Boundary、sync 与 search data flow。

WP05

Static Assets、API Profile、api command。

WP06

Local Toolchain and Cache、Project Context、ProbeResult。

WP07

Repository Signals、Skills API、SkillEntry、Go dependencies。

WP08

Output contracts 与 Output Pipeline。

WP09

Command Map、Control Flow、Command Reference。

WP10

doctor/sync、search/view、compare、Data Flow。

WP11

api/source、skill、Data Flow、Skill Discovery Journey。

WP12

probe、record/report/raw、AdoptionRecord、Failure Recovery Journey。

WP13

Journeys、Black-box Acceptance、Testing and Tooling、Engineering Quality Toolchain。

19.3. 维护规则

9 号书章节行号变化时，维护者检查本书所有 lines= include。整章 include 使用 9 号书章节锚点；局部 include 使用行号范围。局部 include 避开 9 号书原始 anchor 行，避免同一本渲染书中出现重复 id。

当工作包边界变化时，维护者先修改 WBS 依赖图，再修改对应工作包章节，最后更新本来源引用图。来源引用图不定义工作包边界；它只记录引用关系。