Daily Xuanzang

每日西域记 Daily Xuanzang

逐段讲读玄奘《大唐西域记》全 12 卷（《大正藏》No.2087），从高昌出发，沿丝绸之路北道穿越中亚，翻越葱岭进入五印度，遍历佛陀生灭四大圣地与那烂陀寺，再原路返回于阗——亲践 110 国、传闻 28 国，共 138 国的地理风土实录。

每讲包含：原文节录 → 白话/英文翻译 → 背景讲解 → 下期预告，并默认配一张中英文路线示意地图标出"今天西行到哪里"。自动追踪进度，支持配图与语音朗读。

本 skill 自带原典全文（data/volumes/vol01.txt .. vol12.txt），无需联网取经文；翻译与讲解由 AI 基于原文生成。

---

🛡️ 弹性优先交付（Resilience First · 重要）

本 skill 默认要稳定交付【文字 + 地图 + 语音】三件，必须做到单步失败不拖垮整体：

1. 文字最先发、必送达。 先把讲稿正文发出去，再去做地图/语音。文字是保底——哪怕地图和语音都失败，用户也已经拿到了今天的讲解。
2. 地图、语音各自独立交付。 三件互不阻塞：地图失败不影响语音，语音失败不影响地图，二者都失败也不影响已发出的文字。
3. 吞错继续，绝不整轮 abort。 任何工具调用报错/中断（尤其是 image_generate 的 abort/超时），都要就地捕获、跳过该件、继续下一件，严禁让单步失败导致整个任务 abort、用户什么都收不到。
4. 进度只在文字发出后推进，避免重复，也避免漏发。
5. 给 image_generate 设合理 timeoutMs（如 180000），失败最多重试 1 次就放弃该件。
6. 若用定时任务驱动，建议再配一个延时校验补发任务（如主任务后 20–30 分钟跑一次），检查今天三件是否齐全、缺哪件补哪件（已送达则不重发）。

经验教训（真实案例）：曾有一期因为地图生成环节 abort，整个定时任务被 abort，导致文字和语音都没发出去（只出了图）。根因就是把文字/地图/语音纳入了同一条「要么全成、要么全挂」的线性流程。修正办法就是上面六条：文字先发、各件独立、吞错继续。

默认交付要求（重要）

• 默认不要只给"短摘要版"；应交付一篇完整讲稿（原文 / 翻译 / 讲解三部分都要展开）。
• 默认按 四步交付：
  1. 文字成稿（完整讲稿，先产出）
  2. 路线地图（中英文标签，标出本期涉及的古国 + 今地名）
  3. 配图（可选：本期最有画面感的圣迹/场景）
  4. 语音（可选：基于成稿正文或精炼朗读稿）
• 只要用户当前配置或当前任务明确包含文字 / 地图 / 图片 / 语音中的任一项，就必须把对应产物全部生成出来。
• 地图是本 skill 的核心特色，默认每期都要有，除非用户明确关闭。
• 如果用户明确只要文字，才可以跳过地图/图/语音；否则默认至少"文字 + 地图"都要有。

---

首次使用 / First Run

第一次触发时，询问语言偏好：

欢迎来到「每日西域记」！请选择语言 / Welcome! Choose your language:

• 中文 (zh): 原文 + 白话翻译 + 中文讲解
• English (en): Original text + English translation + English commentary

用户选择后运行（SKILL_DIR 为本 skill 安装目录）：

python3 SKILL_DIR/scripts/progress.py set-lang --lang zh   # 或 en

进度文件保存在 ~/.openclaw/workspace/daily-xuanzang/progress.json。

---

生成每日讲稿 / Generating a Lecture

Step 1: 取下一段原文

python3 SKILL_DIR/scripts/progress.py next

返回 JSON 字段：

• vol：当前卷号（1–12）
• seg_index：本卷内第几段
• consumed：本段消耗的字符数（advance 时要用）
• text：本段文言原文
• remaining_after：本卷剩余字符
• done_volume: true：本卷已讲完（再次 next 会自动进入下一卷开头）
• done_all: true：全书 12 卷讲完（发祝贺收尾，不再推进）

Step 2: 识别本段地理

读 text，从 XX國 / 至XX國 识别本段讲到的古国/圣迹，并查出对应今地名（如 阿耆尼=焉耆、屈支=龟兹/库车、缚喝=巴尔赫、那烂陀=Nālandā）。这一步既用于起标题，也用于画地图。

可参考 SKILL_DIR/references/structure.md 了解当前卷的时代地理范围。

Step 3: 生成讲稿

读 SKILL_DIR/references/style-guide.md 了解格式与风格，然后据 text 与语言偏好生成讲稿。

中文模式输出格式

## 📖 每日西域记 · 第 X 期

**卷次：** 卷X（某区域 · 某干国）
**今地：** [古国 = 今地名对照]
**本期路线：** [从哪到哪]

---

### 📜 原文节录
> [精选原文]

### 🗣️ 白话翻译
[逐段翻译]

### 📚 背景讲解
[这段讲哪国/哪圣迹、地理今地、历史与佛教价值、相关典故；3–5 要点]

### 🔮 下期预告
[一句话勾起好奇]

---
📍 进度：卷 X / 12

English Mode Output Format

## 📖 Daily Xuanzang · Episode X

**Fascicle:** Vol. X (Region · key kingdom)
**Today:** [ancient name = modern place]
**Route:** [from → to]

---

### 📜 Original Text
> [Selected classical Chinese]

### 🗣️ Translation
[English translation]

### 📚 Background
[Which kingdom/sacred site, modern geography, historical & Buddhist significance, related lore]

### 🔮 Next Time
[Teaser]

---
📍 Progress: Vol. X / 12

Step 4: 生成中英文路线地图（默认执行 · 本 skill 核心）

• 用图像生成工具，优先选当前环境里渲染文字标签最清晰的模型。经验：google/gemini-3.1-flash-image-preview 在标签清晰度上表现好；若 openai/gpt-image-* 在本环境已正确鉴权，它对密集文字标签通常更强，可优先尝试。
• aspectRatio 16:9，分辨率 2K，文件名形如 xiyuji-map-NNN.png。
• prompt 要点：
  • 古地图 / 古籍插图风，强对比、深色线条、标签清晰可读、填满画面
  • 金色虚线标出玄奘西行路线，从东往西推进
  • 标出本期涉及的古国，每个地名同时标 中文古名 + 今地拼音/英文（如 龟兹 Kucha、焉耆 Yanqi、那烂陀 Nālandā）
  • 附指南针、标题横幅、山脉与沙漠/河流地貌；博物馆级参考地图质感
  • 背景随西行进度切换区域：丝路北道（塔里木盆地）→ 中亚 → 阿富汗 → 北/中/南印度
  • 标签以中文为主、辅以英文
• 若地图生成失败，仍照常交付文字讲稿，并诚实说明地图缺失，不要假装有图。

Step 5: 语音朗读（按配置可选 · 默认带轻背景音乐）

• 语音：中文默认生成适合朗读的稿（300–800 字），讲史/诵经般庄重；叙事类默认配轻背景音乐（古琴/箫/古筝），只做氛围铺底、音量低、不盖人声。

• 推荐用封装好的音频助手脚本（已集成 edge-tts 语音 + 古琴/箫氛围 + 侧链压制，且自带容错与 NO_TTS 检查），避免每次手搓 ffmpeg：

  # 1) 先把朗读纯文本写到一个文件（只放可朗读正文，无 markdown / 路径 / JSON）
  # 2) 调用助手（使用方可把脚本放在自己的 scripts/ 下；参考实现见下）
  bash /scripts/xuanzang-audio.sh /tmp/xz_read_NNN.txt /xuanzang-NNN-voice.mp3
  

  脚本 stdout：XZAUDIO_OK = 成功；XZAUDIO_SKIP = NO_TTS 跳过（正常）；XZAUDIO_ERR/WARN = 音频不可用（跳过，别 abort）。

  参考脚本：~/clawd/scripts/xuanzang-audio.sh（合成五声音阶 drone 做古琴/箫氛围，sidechain 让配乐自动避让人声）。

• 投递语音：在 Telegram 用消息工具 asVoice=true + media=<本地mp3> 发语音气泡；只对可朗读正文做 TTS，不要把执行说明/进度播报念出来。

• 配图（可选）：从本期最有画面感的圣迹/场景生成（佛塔、石窟、那烂陀讲堂、雪山垭口、商旅入城等），水墨/工笔/电影分镜感，重氛围不画证件照。

Step 6: 写盘 + 推进进度

交付顺序（弹性优先）： 先写讲稿 → 先发文字（保底） → 推进进度 → 地图（独立交付）→ 语音（独立交付）。

讲稿建议写入使用方工作区的讲解库（如 ~/clawd/data/xiyuji/讲解/NNN-标题.md 或使用方自定路径），并在文件内附地图路径引用。

推进进度（`` 用 Step 1 拿到的值）：

python3 SKILL_DIR/scripts/progress.py advance  --title "本期标题"

• 若本期配置为 文字 + 地图 +（图/语音），缺项不算完成（除非用户接受缺项版本）。
• 不允许"先推进进度、地图/语音以后再补"的默认行为。

Step 6.5: 存副本到回放库（配合 daily-replay · 重要）

为了让「续听 / 重听」以后能稳定调出本期，交付时除了发给用户，还要把文字与音频各存一份 到 ~/.openclaw/media/outbound/，且用 daily-replay 能识别的命名（NNN = 本期集号，零填充三位）：

• 音频：~/.openclaw/media/outbound/xuanzang-NNN-voice.mp3
• 文字：~/.openclaw/media/outbound/xuanzang-NNN.txt（只放可回放的讲稿正文，不含执行说明）
• 地图/配图：~/.openclaw/media/outbound/xuanzang-NNN.jpg（把本期路线地图或主配图 复制一份到此路径；图通常生成在 tool-image-generation/，要用 cp 拷过来）

集号 NNN 取本期在 history 中的序号（即已完成集数 + 1，与既有 xuanzang-012..019 命名延续）。 若当期语音脚本已直接输出到该路径，则无需重复复制；但仍需确认文字副本与地图副本也已写入同名 .txt / .jpg。 三件（音频/文字/图）尽量都落盘，回放库才会和当日交付一致。 这一步失败不阻塞给用户的交付（吞错继续），但要尽量完成，好让回放库不断补齐。

---

投递方式 / Delivery

本 skill 不绑定特定频道或定时任务。使用者可：

• 手动触发： 对话中说「今日西域记」「继续读西域记」「daily xuanzang」等
• 定时任务： 通过 cron / heartbeat 定时调用，配置目标频道
• 图片投递： 在 Telegram 等渠道，地图/配图务必用消息工具的 media 参数发真图，不要只发裸链接文本

示例：每天 19:00 取下一段 → 生成讲稿 + 中英文地图 → 发送到指定频道。

---

进度管理 / Progress Management

进度脚本 SKILL_DIR/scripts/progress.py，数据存于 ~/.openclaw/workspace/daily-xuanzang/progress.json。

进度 JSON 格式

{
  "currentVolume": 1,
  "charOffset": 921,
  "segIndex": 1,
  "segCharsTarget": 900,
  "language": "zh",
  "history": [
    { "volume": 1, "segIndex": 0, "consumed": 921, "title": "阿耆尼国→屈支国", "completedAt": "2026-06-18T..." }
  ]
}

segCharsTarget 控制每段目标长度（默认 900 字，在句末标点处收尾，不硬切句子）。可在 progress.json 手动调大/调小。

---

全书结构速览 / Structure

完整脉络见 references/structure.md。

---

注意事项 / Notes

• 每期只讲"今天这一段"，不要一次把整卷讲完。
• 翻译力求信达：中文要像中文、英文要像英文；不臆造原文没有的内容；生僻地名保留音译并注今地。
• 地图标签必须中英文都有。
• 全书约 39 万字，以每期约 900 字计，约 430+ 期可读完。
• 不要把内部脚本细节 / 路径 / 进度 JSON 输出给用户，用户只看到讲稿 + 地图成品。