Files

T

jiantw83 8467b89a09 feat(wiki): 頁型別新增 MONITOR

What：
- resolve_wiki_repo 的型別白名單與檔頭註解加上 MONITOR，check-wiki-rules.sh 的 TYPES 一併加入。
- README 的兩處型別列舉加上 MONITOR，環境變數表補一列 JSC_WIKI_REPO_MONITOR。
- wiki 技能的 allowed types 與行為清單的呼叫端補上這個型別與它的擁有者。
- 三份 manifest 的版本一起提升。

Why：
- 技能助理要把巡檢結果寫進 wiki，落點就是監控頁。型別不在白名單裡，wiki-repo 會直接回「unknown wiki type」而拒絕解析，助理連寫都寫不出去。
- 型別串散在五個檔案，只改一處會讓解析通過但檢核工具漏掉，或反過來。所以一次改齊。

How：
- MONITOR 放在型別串尾端，接在 TOOLING 之後。既有順序是依用途分群，不是字母序，所以不重排。
- 環境變數的規則完全沿用既有型別：先讀 JSC_WIKI_REPO_MONITOR，再退回 JSC_WIKI_REPO，不得跨型別代用。這一條由 resolve_wiki_repo 統一處理，新型別自動繼承，不必另寫分支。
- 雜湊來源的規則不寫在這個存放庫。README 已載明雜湊規則的唯一來源是技能準則的命名總表，這裡不複述。
- wiki 技能的 description 原本逐一列舉呼叫端，已經接近長度上限。這次改成括號標注頁型的濃縮寫法，加了一個呼叫端之後整行反而變短，句數維持在上限內。

Who：
技能助理落地帶出來的頁型別需求，四個存放庫同一批改。

2026-09-01 12:10:40 +08:00

6.8 KiB

Raw Blame History

name, description

name	description
wiki	Read or write a Gitea wiki page through tools/gitea.sh and tools/hash-id. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose. Callers are jsc-ask, jsc-sdlc, jsc-log, jsc-hooks (ERROR), jsc-cli (CHECK), jsc-meta (SKILLSET, TOOLING) and jsc-assist (MONITOR). Use for any wiki page in the skill set; not for repo code files.

name

description

wiki

Read or write a Gitea wiki page through tools/gitea.sh and tools/hash-id. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose. Callers are jsc-ask, jsc-sdlc, jsc-log, jsc-hooks (ERROR), jsc-cli (CHECK), jsc-meta (SKILLSET, TOOLING) and jsc-assist (MONITOR). Use for any wiki page in the skill set; not for repo code files.

wiki — read and write Gitea wiki pages

Every wiki operation in the jsc skill set goes through this skill. One entry point, one permission path.

Resolve the wiki location

Different page types can live in different {owner}/{repo} repos, classified by the page-name prefix.

Host gate. Confirm GITEA_HOST holds a value in the current shell. When it is missing, ask for it per the jsc-ask:ask rules before any tools/gitea.sh call that reaches the API; otherwise the first thing the user sees is the script's GITEA_HOST is required line instead of a decision-tree question. GITEA_TOKEN needs no inventory here — the script resolves it, retries once with the tea CLI login token, and exits 7 when neither works. Done when GITEA_HOST holds a value.
Run tools/gitea.sh wiki-repo {TYPE} (TYPE = the page-name prefix). Allowed types are QUESTION, PLAN, ANALYZE, DELIVER, MAINTAIN, REPO, LOG, LEARN, ERROR, CHECK, REPORT, SKILLSET, TOOLING, and MONITOR. The script reads JSC_WIKI_REPO_{TYPE} first and JSC_WIKI_REPO second, straight from the inherited environment, so take no separate inventory of those two variables. Never borrow another type's repo. Done when the command has printed exactly one {owner}/{repo}, or exited 3 and sent this page type to step 3, or exited 2 on a type outside the list above and stopped the run.
On exit 3 (neither variable is set), ask the user for that page type's {owner}/{repo} per the jsc-ask:ask rules, and suggest setting JSC_WIKI_REPO_{TYPE} (can differ per type) or JSC_WIKI_REPO (shared default). Done when the user has supplied one {owner}/{repo} for that page type.

Operations

Action	Command
list pages	`tools/gitea.sh wiki-list {owner}/{repo}`
read page	`tools/gitea.sh wiki-get {owner}/{repo} {page}`
write page	write the content to a temp file first, then `tools/gitea.sh wiki-put {owner}/{repo} {page} {file}` (asks for confirmation first, then creates or updates)
page URL	`tools/gitea.sh wiki-url {owner}/{repo} {page}` — the page's absolute URL, taken from the API's `html_url`

When writing a page, link same-type pages with the [[display|page]] form (display text on the LEFT) and cross-type pages with the absolute URL from wiki-url, because [[...]] resolves only inside one wiki. Full rules and the direction trap: references/wiki-links.md.

Exit codes

Route every tools/gitea.sh call in this skill on its exit code. A code with no branch below stops the run and gets reported as it is.

Code	Meaning	What this skill does
0	success	use the output
2	usage error, or a page type outside the allowed list	fix the arguments, then call again; never repeat the same call unchanged
3	`wiki-repo`: neither `JSC_WIKI_REPO_{TYPE}` nor `JSC_WIKI_REPO` is set	go to step 3 and ask
4	HTTP 404: `wiki-get` and `wiki-url` found no such page	for a read the caller expects to succeed, stop and report the page name; this is the only code that opens the create path of rule 4 — write the page from the template instead of appending
5	`wiki-url`: the page exists but the API returned no `html_url`	stop and report it. Link inside the same wiki with `[[display\|page]]`; a cross-repo link has no absolute URL to point at, so do not fabricate one
7	HTTP 401 or 403 after the tea-token retry: the key is invalid or lacks permission	stop the whole operation and report the key problem. Never read this as an empty or missing page, and never take the create path of rule 4: writing a fresh page over one you could not read destroys the record that is still there
8	any other API failure, HTTP status in the message	stop and report that status; call again only after the cause is fixed

Rules

Page names must follow the wiki naming table in the skill guidelines (see jsc-meta/references/guidelines.md).
Use tools/hash-id for {HASH} values. It returns the first 8 uppercase SHA-1 hex chars, or H plus the first 7 chars when the raw hash starts with 0-9, A, B, or C. Exit 1 means this machine has neither sha1sum nor shasum: stop, report that one of them has to be installed, and compute no hash by hand — a hand-made page name lands the content on a page nobody else reads.
To update a contents page (*_CONTENTS): wiki-get it first, apply the template to append or modify, then wiki-put the whole page back — the write asks for confirmation before it goes out. Never overwrite entries owned by others. Whether the page may be created from the template instead is decided by rule 4, and by nothing else.
Only exit 4 means the page is not there yet — this rule binds every "create it if it does not exist" path, without exception. It is not limited to contents pages: a content page (*_{HASH}), a work log, an error page, a report, any page at all, follows the same branch.
- Correct branch. Read the page with wiki-get. Exit 0 means the page exists, so append or modify the content that came back and wiki-put the whole page. Exit 4 (HTTP 404) is the one and only code that permits creating a new page from the template.
- Exit 7 and exit 8 abort. Exit 7 (HTTP 401 or 403) and exit 8 (any other API failure) both mean the old content is unknown, never that the page is missing. Stop the operation and report the exit code with its cause. Create no page, write nothing, and do not retry the same call unchanged.
- Why. Wiki writes in this skill set are append-not-overwrite, and that semantics rests entirely on reading the old page back first. Reading a 401 as a 404 makes the caller believe it holds a brand-new page and wiki-put a fresh template over a live one, and the whole earlier record is gone — the write carries no merge and no backup.
Write all wiki content in UTF-8 Traditional Chinese, per the STE100 output rule.
Prefer visual forms for page content: use mermaid diagrams (flowchart, sequence, gantt, pie) and markdown tables wherever the information allows. Prose is capped at 3 sentences per section, and a sentence stays only when neither a mermaid diagram nor a markdown table can carry the same information.
tools/gitea.sh retries once with the tea CLI login token when GITEA_TOKEN is missing or the response is 401/403. Report a failure only after that retry also fails.

6.8 KiB Raw Blame History