Files
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

12 KiB
Executable File

markup, title, import
markup title import
occlusion Native artifact IO for the release handbook
engineering fs net table result text re uuid sys
ext/engineering/index.mq.md lib/fs.mq.md lib/net.mq.md lib/table.mq.md lib/result.mq.md lib/text.mq.md lib/re.mq.md lib/uuid.mq.md lib/sys.mq.md

These functions are the concrete IO used by assets.mq.md. Native Marqdo libraries read, hash, download, stage and clean files. The extension handles authenticated R2 writes and ZIP-format inspection. Source identity, release completeness and publication ordering remain visible Marqdo dataflow.

verify

参数 类型 默认 说明
asset map required Exact GitHub asset record including size and digest
path text required Local file selected inside the granted filesystem root
root text "." Checkout root matching --fs-root; relative to the granted runtime cwd
返回 类型 说明
result map Result with native hash evidence and validated archive metadata

Use asset, path and root="." to verify local bytes before publication. Size and SHA256 come from lib/fs; a GitHub digest, when supplied, must match. The native engineering extension inspects only the ZIP/VSIX format and CRCs. Ordinary file facts stay in Marqdo instead of an external script. A mismatched length or hash remains a failed Result and cannot advance the CDN pointer.

The format layer rejects escaping entries, duplicate names, symlinks and excessive expansion. It does not extract or execute a CLI. Source pack version, native file roles and VSIX version are checked by assets.content after this byte-level stage. This function requires fs.read and plugin; executable-only assets use the same size/hash checks without pretending they contain an archive.

We information = Read the native file information and size = Read its actual byte count) and sha256 = Hash the actual file through the native filesystem and expected = [Read GitHub's optional digest metadata](table.get(map=asset, key="digest")) and name = Retain the asset's exact filename).

  1. size != access(asset, "size") or (expected != None and expected != "sha256:" + sha256) Return [Reject bytes that differ from GitHub metadata](result.error(code="release.asset_digest", message=name, operation="asset_io.verify")).

record =

name size sha256
name size sha256
  1. [This asset is an archive format](text.ends_with(text=name, suffix=".zip") or text.ends_with(text=name, suffix=".vsix")) We archive = [Inspect ZIP entries and their CRCs without extraction](engineering.inspect_zip(path=path, root=root)).
  2. not access(archive, "ok") Return archive with the actual format error. We record = [Retain the inspected format evidence](table.merge(a=record, b=access(archive, "value"))). Return The verified local byte identity.

fetch

参数 类型 默认 说明
asset map required GitHub asset record chosen by the release catalog
directory text required Release-specific destination under --fs-root
root text "." Checkout root matching --fs-root; relative to the granted runtime cwd
返回 类型 说明
result map Result with a reused or freshly downloaded verified local artifact

Use asset, directory and root="." after assets.catalog has checked all required filenames. A local file is reused only after its size, hash and archive format are verified again. Otherwise native net.download streams into an atomic replacement under the granted filesystem root. Failed HTTP transfers do not replace an existing destination. The proxy route is tried before the original GitHub asset URL; explicit fixture URLs remain visible in test metadata.

Downloads have a 64 MiB per-file limit and a 90-second request timeout here. These limits cover the current release matrix; a larger future artifact needs a deliberate documented limit change. No credential is put into a URL or native download header. Role-specific contents are checked by the calling task.

We name = Read the exact catalog filename) and path = directory + "/" + name and prepared = Create the explicit staging directory.

  1. A local candidate already exists We existing = [Recheck its actual byte identity](verify(asset=asset, path=path, root=root)).
  2. access(existing, "ok") Return existing without downloading it again. We original = Read the selected asset's original URL) and proxy = [Select the documented GitHub mirror](text.replace(text=original, old="https://github.com/", new="https://proxy.cflmy.top/github.com/")).

urls =

url
proxy
original

We headers = [Identify this public verification download](table.put(in=None, at="User-Agent", value="marqdo-engineering")).

We last = [Start with no completed transfer](result.error(code="release.download", message=name, operation="asset_io.fetch")).

  • [Try the bounded public download routes](for urls as url) We downloaded = [Stream the official artifact through native IO](net.download(url=url, path=path, headers=headers, timeout_ms=90000, max_bytes=67108864)).
    1. access(downloaded, "ok") We last = [Check the downloaded bytes and archive format](verify(asset=asset, path=path, root=root)).
    2. access(last, "ok") Return last with its real evidence.
    We last = downloaded to preserve the last transport failure. Return last when neither route produced a verified artifact.

cdn

参数 类型 默认 说明
path text required Versioned or latest VERSION/pack path from the release model
返回 类型 说明
result map Result containing public pointer text or native download hash

Use path only for a modeled CDN object. The public base is ext.marqdo.com unless an explicit fixture override is configured. VERSION is read as UTF-8; binary packs use native net.download, fs.file_hash and native cleanup in a UUID-named directory under .marqdo/release-check. No Python body reader or local file writer participates. A handled network failure cleans its owned directory.

A successful HTTP request proves only that URL's bytes; the caller compares the hash with GitHub and decides whether the release is complete. Edge-cache delay remains visible. Unexpected filesystem diagnostics may leave the uniquely owned staging directory for inspection; no unrelated directory is removed. This task needs network.read, fs.write, environment.read and random.read.

We valid = [Accept only modeled public artifact paths](re.is_match(text=path, pattern="^(latest|v[0-9]+\.[0-9]+\.[0-9]+)/(VERSION|marqdo-[A-Za-z0-9._-]+\.zip)$")).

  1. not valid Return [Reject an arbitrary CDN cache path](result.error(code="release.cdn_path", message="expected a modeled release path", operation="asset_io.cdn")). We base = Read the explicit fixture override if configured.
  2. base == None We base = "https://ext.marqdo.com" for normal public verification. We url = base + "/" + path.

We headers = [Identify this public verification download](table.put(in=None, at="User-Agent", value="marqdo-engineering")).

  1. [This object is a version pointer](text.ends_with(text=path, suffix="/VERSION")) We read = [Read the public UTF-8 version pointer](net.get(url=url, headers=headers, timeout_ms=30000)).
  2. not access(read, "ok") Return read with its actual network error. We response = Read the HTTP result).
  3. access(response, "status") != 200 Return [Keep the public pointer HTTP failure](result.error(code="release.cdn_http", message=str(access(response, "status")), operation="asset_io.cdn")). We version = Trim only the pointer's outer whitespace)).

We pointer = [Keep the version as one named result field](table.put(in=None, at="version", value=version)).

Return The actual public version pointer. We parent = Prepare the ignored verification area and identifier = Choose an independent staging identity and directory = ".marqdo/release-check/" + identifier and created = Reserve this verification directory and destination = directory + "/artifact.zip". We downloaded = [Stream public bytes into this owned native stage](net.download(url=url, path=destination, headers=headers, timeout_ms=90000, max_bytes=67108864)).

  1. not access(downloaded, "ok") We removed = Clean only this failed request's owned stage. Return downloaded with its real transport failure. We sha256 = Hash the actual public bytes and information = Read the downloaded file information and size = Read their actual byte count) and removed = Remove this completed request's owned stage.

evidence =

size sha256
size sha256

Return The measured public object identity.

upload

参数 类型 默认 说明
version text required Stable X.Y.Z explicitly chosen by the user
files list required Exactly three verified path/name/sha256 records
root text "." Checkout root matching --fs-root; relative to the granted runtime cwd
返回 类型 说明
result map Result containing the actual R2 write evidence

Use version, files and root="." only for the release already authorized by the user. The caller has checked all three source/native files against GitHub before this operation begins. Marqdo controls the write order explicitly: versioned and latest pack objects first, both VERSION pointers last. Private R2 signing is the only native service boundary. No whole-directory sweep occurs.

An interrupted upload keeps the old pointer until every required pack has succeeded. Existing older versions are never deleted. The tool returns an error on the first failed write and preserves already-written object evidence through the service itself; it does not call a partial batch complete. Public byte-parity checks still follow in assets.status.

We count = Require the source pack and both platform packs.

  1. count != 3 Return [Reject an incomplete CDN upload set](result.error(code="release.cdn_files", message="exactly three verified packs are required", operation="asset_io.upload")).

prefixes =

prefix
"vversion"
latest

We written = Start the service write evidence.

  • [Write both public pack namespaces before pointers](for prefixes as prefix)
    • [Upload only the preverified pack set](for files as file) We key = prefix + "/" + access(file, "name") and uploaded = Sign and upload the exact checked local bytes, key=key, sha256=access(file, "sha256"), root=root)).
      1. not access(uploaded, "ok") Return uploaded before changing any VERSION pointer. We written = [Retain the completed object identity](table.append(list=written, item=access(uploaded, "value"))).
  • [Advance pointers only after all six pack writes succeeded](for prefixes as prefix) We uploaded = [Write the explicit version pointer](engineering.put_text(key=prefix + "/VERSION", text=version + "\n", root=root)).
    1. not access(uploaded, "ok") Return uploaded with the actual pointer failure. We written = [Retain this pointer write](table.append(list=written, item=access(uploaded, "value"))). Return All completed service writes.