jiantw83
72ba7b8801
技能以前只寫成功路徑。腳本回非 0 時，模型得自己猜下一步，猜錯就是靜靜 往下走。現在每一支腳本在檔頭宣告自己的結束碼，技能也逐碼寫明要停、要 問、還是要改參數再呼叫一次。兩支技能補上連線變數的解析步驟，讓缺值在 第一步就浮出來，而不是在中途撞出一行英文錯誤。 流程也拉平了。取內容、選範本、問輸出位置這幾件事彼此不相依，改成同一批 送出；存取庫批次同步從逐一處理改成各存取庫同時進行，一個 owner 底下有 上百個存取庫時差距最明顯。 相依的技能組下限寫進外掛設定，版本推進。
28 lines
5.6 KiB
Markdown
28 lines
5.6 KiB
Markdown
---
|
|
name: html-export
|
|
description: Export one Gitea wiki page or issue as a single self-contained HTML file. Parse the link with tools/gitea-link.sh, resolve that kind's layout and style through tools/html-style.sh (kind, then DEFAULT, then the built-in report/minimal), then render with tools/html-render.sh, which puts the markdown through Gitea's own renderer and inlines every asset. A request without a wiki or issue link stops the skill immediately: never guess the repository, the page or the issue number. Use when a page or issue has to leave Gitea as a document; not for choosing which template a kind uses - that is jsc-gitea:html-style.
|
|
---
|
|
|
|
# html-export — a wiki page or issue becomes one HTML file
|
|
|
|
The link is the only input. The output is one file that opens anywhere, with no external asset.
|
|
|
|
## Steps
|
|
|
|
1. **Link gate.** Run `tools/gitea-link.sh parse {url}`. Exit 3, or no link in the request: **stop and report it**. Exit 2 is a usage error — fix the arguments and call again. Never fall back to the working directory's remote or to a page name the user mentioned in passing. This gate runs first because it stops the whole skill more often than any other check, and it costs no API call. Completion condition: `kind` is `wiki` or `issue`, and `repo` plus `page` or `index` are known.
|
|
2. **Host gate.** Confirm `GITEA_HOST` holds a value in the current shell; ask for it per the `jsc-ask:ask` rules when it does not. `GITEA_TOKEN` needs no inventory — `tools/gitea.sh` resolves it, retries once with the tea CLI login token, and exits 7 when neither works. Completion condition: `GITEA_HOST` holds a value.
|
|
3. **Run these three tracks at the same time.** They are independent, so start them in one batch rather than one after another; only the issue branch of track B waits, and only for track A's `labels` line.
|
|
- **Track A — content.** Wiki page: `jsc-gitea:wiki` `wiki-get {repo} {page}` for the markdown, plus `wiki-url {repo} {page}` for the source URL; route its exit codes by that skill's table (4 = no such page, 7 = the key is invalid, 8 = other API failure), and every one of them stops this skill with the page name in the report. Issue: `tools/issue.sh show {repo} {index}`, which returns title, labels and body from **one** API call — never call `title`, `body` and `labels-of` separately on the same issue. Exit 1 means the issue could not be read: stop and report the issue number; exit 2 is a usage error, so fix the arguments and call again.
|
|
- **Track B — template.** Wiki page: `tools/html-style.sh key wiki {page}`. Issue: `tools/html-style.sh key issue {repo} {index} --labels {the names from track A's labels line}`, which spends no extra API call; the labels line arrives before the body, so this track starts well before track A finishes. The script owns both derivation rules — the page-name prefix, and trying each label in order until one is configured. It prints `{key}<TAB>{reason}`; keep the reason, it is how the report says which prefix or label produced the key. Exit 1 means the labels could not be read: **report that first**, then continue with `ISSUE:DEFAULT` and say in the report that the template was picked without labels. Exit 2 is a usage error — fix the arguments and call again. Then run `tools/html-style.sh get {key}`, which always prints `layout<TAB>style<TAB>source`. **Read the third column and report it**: `project` or `global` means the user configured this kind; `default` means it fell back to the DEFAULT row; `builtin` means nothing is configured at all and `report`/`minimal` was used. For `default` and `builtin`, tell the user in one line that `jsc-gitea:html-style` can set this kind's own template.
|
|
- **Track C — destination.** Ask per the `jsc-ask:ask` rules where the file goes, proposing `./.jsc/html/{page-or-issue}.html`. State the impact scope: a path inside a repository gets committed unless it is ignored.
|
|
|
|
Completion condition: the markdown and the document title are in hand, exactly one kind key is chosen with the reason that produced it, the layout, style and source are reported, and the user has confirmed one output path.
|
|
4. **Prepare the markdown — this step MUST run as a sub agent.** Convert `[[display|page]]` wiki links to absolute URLs from `wiki-url`; the renderer does not resolve them, so they would ship as literal brackets. Strip personal data — an exported file travels further than the page it came from. Leave everything else exactly as written; this step never rewrites the content. Completion condition: no `[[...]]` remains, and the diff against the source is limited to link conversion and personal-data removal.
|
|
5. Render: `tools/html-render.sh --markdown {file} --title {title} --layout {layout} --style {style} --source-url {absolute URL} --out {path}`. Route every exit code: 0 → the path it printed is the finished file; 1 → Gitea's renderer or the write failed, so report it and stop, with no half-rendered file left behind; 2 → a usage error or a missing markdown file, so fix the arguments and call again; 4 → the layout or style template file is gone, so report which pair was asked for and send the user to `jsc-gitea:html-style` rather than editing the configuration by hand. Completion condition: the file exists, and the report names its path, the layout, the style and where that pair came from.
|
|
|
|
## Rules
|
|
|
|
- One link, one file. Batch export is a loop the caller runs, not something this skill decides on its own.
|
|
- The rendered file inlines CSS and scripts on purpose: it is usually sent to someone outside Gitea, and an external asset breaks on their machine.
|
|
- The layout and style are never chosen by inspecting the content. The configuration decides, and `jsc-gitea:html-style` owns the configuration.
|