add-description

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Steps

步骤

1. Parse arguments

1. 解析参数

Strip

--dry-run

from the argument list and set

DRY_RUN=true

if present. Remaining tokens are the file path list. If empty, abort:

Error: no files specified.
Usage: /add-description [--dry-run] <file> [<file> ...]

从参数列表中移除

--dry-run

，如果存在则设置

DRY_RUN=true

。剩余标记为文件路径列表。若为空则终止：

Error: no files specified.
Usage: /add-description [--dry-run] <file> [<file> ...]

2. Check Ollama and select model

2. 检查Ollama并选择模型

bash

ollama list 2>/dev/null | grep -qi "Gemma-3-TAIDE"

Exit 0 →

MODEL=hf.co/audreyt/Gemma-3-TAIDE-12b-Chat-2602-GGUF:Q8_0

Non-0 →
```
MODEL=qwen3:1.7b
```
(fallback)

ollama list

itself fails (Ollama not running), abort all files with:

Error: Ollama is not running. Start it with: ollama serve

Report the selected model before processing.

bash

ollama list 2>/dev/null | grep -qi "Gemma-3-TAIDE"

返回值0 →

MODEL=hf.co/audreyt/Gemma-3-TAIDE-12b-Chat-2602-GGUF:Q8_0

返回值非0 →
```
MODEL=qwen3:1.7b
```
（备选）

如果

ollama list

本身执行失败（Ollama未运行），则终止所有文件处理并提示：

Error: Ollama is not running. Start it with: ollama serve

在处理前报告所选模型。

3. For each file

3. 处理每个文件

3a. Read the file

3a. 读取文件

Read the full file content.

读取文件的完整内容。

3b. Guard checks (skip if any fail)

3b. 防护检查（任意检查失败则跳过）

Check	Skip message
File has no leading `---` block	`SKIP <file> — no frontmatter found`
Frontmatter already contains `description:`	`SKIP <file> — description already exists`

检查项	跳过提示
文件无开头 `---` 块	`SKIP <file> — no frontmatter found`
前置元数据已包含 `description:`	`SKIP <file> — description already exists`

3c. Generate description via script

3c. 通过脚本生成描述

Run the generation script, passing the selected model and file path:

bash

uv run scripts/generate_description.py --model "$MODEL" "$FILE"

The script handles language detection, body truncation (first 4 000 + last 2 000 chars for long articles, with a

[……]

omission marker inserted between the two chunks), two-pass prompt construction (coverage-first draft → GEO-style refinement, tech-blogger persona,

temperature=0.5

repeat_penalty=1.1

), Ollama API call, post-processing (prefix stripping, title-repetition retry), and length validation.

stdout: the generated description text
stderr:
```
ABORT: …
```
if too short,
```
WARN: …
```
if too long
exit 0: proceed to write; exit 1: abort this file

Capture stdout as

DESC

and stderr as

SCRIPT_ERR

. If exit code is 1, log

ABORT <file> — <SCRIPT_ERR>

and move to the next file.

运行生成脚本，传入所选模型和文件路径：

bash

uv run scripts/generate_description.py --model "$MODEL" "$FILE"

该脚本会处理语言检测、内容截断（长文章取前4000字符+后2000字符，中间插入

[……]

省略标记）、两轮提示构建（先覆盖核心内容的初稿 → 再以科技博主身份按GEO风格优化，设置

temperature=0.5

repeat_penalty=1.1

）、调用Ollama API、后处理（移除前缀、重复标题时重试）以及长度验证。

标准输出（stdout）：生成的描述文本
标准错误（stderr）：若过短则输出
```
ABORT: …
```
，若过长则输出
```
WARN: …
```
退出码0：继续写入；退出码1：终止当前文件处理

捕获标准输出为

DESC

，标准错误为

SCRIPT_ERR

。若退出码为1，记录

ABORT <file> — <SCRIPT_ERR>

并处理下一个文件。

3d. Write or preview

3d. 写入或预览

Dry-run (
DRY_RUN=true
) — print to stdout only:

[DRY-RUN] wiki/sources/foo.md
  model    : hf.co/audreyt/...
  ────────────────────────────────────────
  <generated description text>
  ────────────────────────────────────────

Normal mode — insert

description:

as the last key before the closing
---
of the frontmatter block using the Edit tool.

Use YAML block scalar style for readability:

yaml

description: >-
  Generated description text here. Multiple sentences flow as a single
  paragraph when rendered.

Use single-line style only if the description contains no special characters and is under 80 characters.

试运行模式（
DRY_RUN=true
） — 仅打印到标准输出：

[DRY-RUN] wiki/sources/foo.md
  model    : hf.co/audreyt/...
  ────────────────────────────────────────
  <generated description text>
  ────────────────────────────────────────

正常模式 — 使用编辑工具将

description:

插入到前置元数据块的闭合
---
前的最后一个键位。

为了可读性，使用YAML块标量格式：

yaml

description: >-
  Generated description text here. Multiple sentences flow as a single
  paragraph when rendered.

仅当描述不含特殊字符且长度小于80字符时，才使用单行格式。

4. Print summary table

4. 打印汇总表

After all files are processed:

STATUS   FILE                                             DETAIL
──────   ──────────────────────────────────────────────   ────────────────────────────
DONE     wiki/sources/foo.md                              zh-TW · 97 chars · TAIDE
DONE     wiki/sources/bar.md                              en · 103 words · qwen3
SKIP     wiki/sources/baz.md                              description already exists
ABORT    wiki/sources/qux.md                              too short (22 chars)
[DRY]    wiki/sources/quux.md                             zh-TW · 88 chars · TAIDE

所有文件处理完成后：

STATUS   FILE                                             DETAIL
──────   ──────────────────────────────────────────────   ────────────────────────────
DONE     wiki/sources/foo.md                              zh-TW · 97 chars · TAIDE
DONE     wiki/sources/bar.md                              en · 103 words · qwen3
SKIP     wiki/sources/baz.md                              description already exists
ABORT    wiki/sources/qux.md                              too short (22 chars)
[DRY]    wiki/sources/quux.md                             zh-TW · 88 chars · TAIDE

Quality rules (reference)

质量规则（参考）

Rule	Detail
No title repetition	Regenerate once if description opens with verbatim title
Minimum length enforced	Abort file if below threshold — do not write short descriptions
Language must match content	zh-TW for CJK-majority files, English otherwise
No meta-commentary	Strip prefixes like `本文摘要：` / `This article discusses:`
No file modification in dry-run	Preview only; the Edit tool must not be called

规则	细节
不重复标题	若描述以完全匹配的标题开头，则重新生成一次
强制最小长度	若低于阈值则终止文件处理 — 不写入过短的描述
语言必须匹配内容	以CJK为主的文件使用zh-TW，其他使用英文
无元注释	移除类似 `本文摘要：` / `This article discusses:` 的前缀
试运行模式不修改文件	仅预览；不得调用编辑工具

Notes

注意事项

Do not append to
```
wiki/log.md
```
— this is a utility, not a knowledge ingest operation.
If a file has no frontmatter, skip it rather than creating one.
Glob expansion (
```
*.md
```
) is done by the shell before the skill receives arguments; pass pre-expanded paths if your shell does not expand them automatically.

请勿追加到
```
wiki/log.md
```
— 这是一个实用工具，而非知识导入操作。
若文件无前置元数据，跳过该文件而非创建新的。
通配符扩展（
```
*.md
```
）由shell在技能接收参数前完成；若你的shell不自动扩展，请传入已扩展的路径。