- 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。
18 KiB
Executable File
markup, title, import
| markup | title | import | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| occlusion | Observe and update GitHub release evidence |
|
GitHub release tasks keep source identity and publication state explicit. Start with status for an existing version; notes is a separate mutation that consumes a reviewed bilingual file. The same release metadata feeds assets.download and assets.status, so name, size and digest checks do not drift between channels.
Every task returns Result.ok/value/error. Check that inner ok before consuming value, then inspect complete for gates. A successful query may truthfully report an incomplete release. plugin grants the native boundary OS/network authority; credentials are resolved privately from the environment or existing credential stores. They are never parameters, return values or journal bindings.
Example, from the checkout root:
marqdo call skills/marqdo-release/github.mq.md status 'version="2.6.0"' --effects plugin --fs-root . --json
The command is read-only. A future release uses the version the user actually specified. A red EK gate, missing Linux build or wrong-commit green run keeps the release incomplete even if a GitHub download page already exists.
request
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | API path scoped to /repos/cflmy/marqdo/ |
| method | text | "GET" | GET for observation; PATCH for notes; POST for explicit publication |
| data | any | None | JSON request body; credentials are never arguments |
| missing | bool | False | Whether GET 404 is represented as a successful None |
| root | text | "." | Checkout directory; pass --fs-root . from its root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Result containing service JSON or a transport error |
Use path, method="GET", data=None, missing=False and root=".".
This function is the authenticated GitHub boundary used by the tasks below.
The proxy is tried before direct GitHub; GET and idempotent note PATCH may be
retried, while an uncertain POST is returned as failure. API failures retain a
code and service name without exposing tokens, headers or signed download URLs.
Reading requires plugin because the native engineering plugin owns HTTPS.
payload =
| path | method | data | missing |
|---|---|---|---|
path |
method |
data |
missing |
Return [Request GitHub JSON through the maintained transport](bridge.request(operation="github", payload=payload, root=root)).
release
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| version | text | required | Stable X.Y.Z explicitly chosen by the user |
| mode | text | "full" | full, cli or ext; determines the deliverable contract |
| root | text | "." | Checkout directory; pass --fs-root . from its root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Result containing release metadata, or None when not published |
Use version, mode="full" and root=".".
The mode selects vX.Y.Z or ext-vX.Y.Z through the same pure plan used for
packaging. A missing release is an observable state, not proof that a previous
publish command failed before creating anything. Callers can distinguish it
from a network or authentication failure by inspecting Result.ok first.
This query does not create a release and never invokes the old Windows-only
publication script, whose assumptions predate embedded standard libraries.
We planned = [Derive the correct release tag](model.plan(version=version, mode=mode)).
- not access(
planned, "ok") Return planned with its failure intact.
We plan_data = Read the accepted tag contract) and
path = "/repos/cflmy/marqdo/releases/tags/" + access(plan_data, "tag").
Return [Observe this exact release without creating one](request(path=path, missing=True, root=root)).
commit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| tag | text | required | Exact tag from the release plan |
| root | text | "." | Checkout directory; pass --fs-root . from its root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Result with the commit SHA targeted by a lightweight or annotated tag |
Use tag and root=".". Annotated tags point first to a tag object,
whereas lightweight tags already point to a commit. Follow that distinction
before matching a workflow run. Comparing a tag-object SHA with head_sha would
silently fail to find the correct green run. Only the single annotated object
created by this handbook is accepted; nested tag objects remain an error.
A missing tag is reported as a transport failure rather than guessed from main.
We reference = [Read the exact remote tag reference](request(path="/repos/cflmy/marqdo/git/ref/tags/" + tag, root=root)).
- not access(
reference, "ok") Return reference with its failure intact.
We object = Read the tag target, "object")).
- access(
object, "type") == "tag" We annotation = [Resolve the annotated tag object](request(path="/repos/cflmy/marqdo/git/tags/" + access(object, "sha"), root=root)). - not access(
annotation, "ok") Return annotation without substituting main. We object = Read the annotated commit target, "object")). - access(
object, "type") != "commit" Return [Reject an unexpected tag target](result.error(code="release.tag_target", message="tag must resolve to a commit", operation="github.commit")). Return The immutable release commit)).
select_run
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| runs | list | required | Workflow runs ordered newest first by the GitHub API |
| sha | text | required | Exact commit that this gate must cover |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Newest run for this commit, or None |
Use runs and sha to select one observed gate attempt. The first matching
head_sha is the most recent attempt provided by the API; an older successful
attempt cannot mask a later failure for the same commit. Runs for other commits
are irrelevant even if their badges are green. No API access or waiting occurs
here, making this decision directly testable with recorded service responses.
If the bounded query contains no matching run, return None and keep the gate
incomplete. The caller may fetch again after CI starts.
- [Inspect workflow runs in their returned order](for runs as run)
- access(
run, "head_sha") ==shaReturn run as the observed attempt for this source.
- access(
Return None when this commit has no observed run.
gate
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| workflow | text | required | release.yml, extension-release.yml or executable-knowledge.yml |
| sha | text | required | Commit that the workflow must cover |
| required | list | required | Required job names, such as windows and linux |
| root | text | "." | Checkout directory; pass --fs-root . from its root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Result with completion, observed run and required-job evidence |
Use workflow, sha, required and root=".". Completion requires both a
successful run for the exact commit and every named job with conclusion success.
A skipped or missing Linux job cannot pass just because the Windows job created
a release. This query checks at most 100 recent runs, returns immediately for
queued/running CI, and does not rerun or cancel anything. Polling belongs to the
agent's bounded observation cycle, not an unbounded loop hidden in a tool.
Knowledge checks use the same rule, so uploaded assets never replace a green EK
gate. Missing evidence returns complete=False with the observed run retained.
We response = [Read recent attempts for one workflow](request(path="/repos/cflmy/marqdo/actions/workflows/" + workflow + "/runs?per_page=100", root=root)).
- not access(
response, "ok") Return response with its failure intact.
We run = Choose the latest attempt for this commit, "workflow_runs"), sha=sha)).
We complete = False and jobs = Start an empty required-job evidence list.
run!= None We answer = [Read this attempt's actual jobs](request(path="/repos/cflmy/marqdo/actions/runs/" + access(run, "id") + "/jobs?per_page=100", root=root)).- not access(
answer, "ok") Return answer with its failed observation. We jobs = Keep the observed jobs, "jobs")) and complete = Require a successful completed run == "completed" and access(run, "conclusion") == "success").
- [Check that every required platform or knowledge job passed](for required as name)
We matched = False before examining this job name.
- [Match this job against observed evidence](for jobs as job)
- access(
job, "name") ==nameand access(job, "conclusion") == "success" We matched = True because the named job succeeded. We complete = complete and matched to preserve every missing-job failure.
- access(
- [Match this job against observed evidence](for jobs as job)
evidence =
| complete | sha | run | jobs |
|---|---|---|---|
complete |
sha |
run |
jobs |
Return The observed gate and its evidence.
status
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| version | text | required | Stable X.Y.Z explicitly chosen by the user |
| mode | text | "full" | full, cli or ext; determines the deliverable contract |
| root | text | "." | Checkout directory; pass --fs-root . from its root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Result with exact-source Release and executable-knowledge gates |
Use version, mode="full" and root="." to inspect an existing release.
The Release workflow is matched against the resolved release tag; executable
knowledge is matched against the current remote main tip. Both sources are
returned so a reviewer can see if main has advanced. Every mode requires both
Windows and Linux jobs on the tag commit. Independent packs use extension-release.yml;
full/cli use release.yml. Existing assets cannot replace missing build evidence.
A missing release or an unfinished gate leaves complete=False. This task does
not mutate GitHub, push local work, create tags, or change the requested version.
The returned service metadata is evidence for the next task, not a permission
to publish a different version or overwrite a release's existing files.
We published = [Inspect the exact version's release](release(version=version, mode=mode, root=root)).
- not access(
published, "ok") Return published with its failure intact.
We planned = [Read the pure release contract](model.plan(version=version, mode=mode)).
- not access(
planned, "ok") Return planned with its failure intact.
We release_data = Keep the published metadata or None) and
tag = Read the planned tag, "tag")).
We tagged = [Resolve its actual source commit](commit(tag=tag, root=root)).
- not access(
tagged, "ok") Return tagged with its failure intact.
We main = [Observe the remote main tip](request(path="/repos/cflmy/marqdo/git/ref/heads/main", root=root)).
- not access(
main, "ok") Return main with its failure intact.
We main_sha = Read main's commit SHA, "object"), "sha")).
knowledge_jobs =
| name |
|---|
| gate |
We knowledge = [Verify EK on the actual remote main commit](gate(workflow="executable-knowledge.yml", sha=main_sha, required=knowledge_jobs, root=root)).
- not access(
knowledge, "ok") Return knowledge with its failure intact.
We workflow = "release.yml" for a CLI or full release.
mode== "ext" We workflow = "extension-release.yml" for independent extension builds.
platform_jobs =
| name |
|---|
| windows |
| linux |
We platforms = [Require both platform builds for the tagged source](gate(workflow=workflow, sha=access(tagged, "value"), required=platform_jobs, root=root)).
- not access(
platforms, "ok") Return platforms with its failed gate observation. We release_gate = Keep actual platform evidence) and release_complete = Read the exact-tag completion decision).
We all_complete = [Require the published release and both source-specific gates](release_data != None and release_complete and access(access(knowledge, "value"), "complete")), release_sha = Keep the resolved release commit) and knowledge_state = Keep the exact-main knowledge evidence) before forming the record.
status_data =
| complete | release | release_sha | main_sha | release_ci | knowledge_ci |
|---|---|---|---|---|---|
all_complete |
release_data |
release_sha |
main_sha |
release_gate |
knowledge_state |
Return The release's observed gates and source identities.
notes
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| version | text | required | Stable X.Y.Z explicitly chosen by the user |
| path | text | required | Reviewed UTF-8 bilingual notes file under the filesystem root |
| mode | text | "full" | full, cli or ext; determines the deliverable contract |
| root | text | "." | Checkout directory; pass --fs-root . from its root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Result of updating only the existing release body |
Use version, path, mode="full" and root=".". This is an explicit
GitHub mutation and needs the user's release instruction; reading this handbook
or asking for status does not authorize it. The prepared notes must contain
Chinese and English highlights, the actual asset matrix, installation routes,
core-surface delta and validation limits. The author remains responsible for
those claims; this function uploads the reviewed file rather than inventing it.
Reading uses fs.read in addition to plugin. UTF-8 text and its intentional
newlines travel in a structured JSON body, never through shell quoting.
We published = [Locate the existing release to edit](release(version=version, mode=mode, root=root)).
- not access(
published, "ok") Return published with its failure intact.
We release_data = Read its metadata).
release_data== None Return [Do not invent a release when only editing notes](result.error(code="release.missing", message="release does not exist; wait for CI or attach an ext release", operation="github.notes")). We body = Read the exact reviewed bilingual note file.
We data = [Keep the reviewed body as one named API field](table.put(in=None, at="body", value=body)).
Return [Publish the reviewed release body](request(path="/repos/cflmy/marqdo/releases/" + access(release_data, "id"), method="PATCH", data=data, root=root)).
create_ext
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| version | text | required | User-confirmed stable independent extension version |
| path | text | required | Reviewed bilingual notes committed with the release source |
| sha | text | required | Exact source commit expected from the authorized tag |
| root | text | "." | Checkout root matching the granted filesystem root |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Result containing newly created or already existing release metadata |
Use version, path, sha and root="." only for authorized extension publication. This is an explicit GitHub mutation. First resolve ext-vX.Y.Z to its actual commit and require the caller's expected SHA. Read the committed note file through native filesystem operations before requesting creation. The file must describe this version's real changes and validation limits; the task does not synthesize release claims.
An existing release is returned unchanged so a resumed upload cannot overwrite its notes or assets. A missing release is created once through the authenticated service boundary, with its exact existing tag and reviewed body. Uncertain POST completion is a failure, never an automatic replay; inspect the release before resuming. CI uses this task after packaging and then uploads with the existing gh tool without clobbering prior assets.
We planned = [Validate the independent extension version](model.plan(version=version, mode="ext")).
- not access(
planned, "ok") Return planned. We tag = Read the exact immutable extension tag, "tag")) and target = [Resolve the actual remote tag commit](commit(tag=tag, root=root)). - not access(
target, "ok") Return target. - access(
target, "value") !=shaReturn [Refuse publication from a different source](result.error(code="release.source_mismatch", message="extension tag differs from expected commit", operation="create_ext")). We body = Read the reviewed version-specific bilingual notes. body== "" Return [Require actual reviewed notes](result.error(code="release.notes_empty", message="extension notes must not be empty", operation="create_ext")). We existing = [Observe whether an earlier creation completed](release(version=version, mode="ext", root=root)).- not access(
existing, "ok") Return existing. - access(
existing, "value") != None Return existing, preserving the existing release.
data =
| tag_name | name | target_commitish | body | draft | prerelease |
|---|---|---|---|---|---|
tag |
tag |
sha |
body |
False | False |
Return [Create this exact tagged release once](request(path="/repos/cflmy/marqdo/releases", method="POST", data=data, root=root)).