Imported from yaosiyuuu6/odyssey-skill (
AGENTS.md). Install upstream withnpx skills add yaosiyuuu6/odyssey-skill. Copyright stays with the author.
Odyssey Skill Agent 维护说明
本文件面向维护仓库的 Agent,不面向普通用户。README.md 是用户展示页,必须保持用户友好,不放内部采集、整理、发布、测试等维护细节。
维护规则
- 修改目录结构、脚本入口、数据路径、内部 skill 流程、测试命令或发布流程时,必须同步更新本文件。
- 新增文件时,要在“仓库结构”或对应模块说明中补上用途;删除或废弃文件时,也要同步标记。
- 所有新采集数据、转写、storylines、final 产物都必须落在
/Users/chenkai/Desktop/CodeX/odyssey-skill/data下。 OdysseyMap和Lifestory只作为历史参考来源,不再作为运行时数据目录。不要向它们写入新的采集输出、转写、case Markdown、storylines 或 final 文件。- 保留
decision_storylines_v2.json文件名,除非用户明确要求做 schema/文件名迁移。
仓库结构
odyssey-skill/
├── AGENTS.md
├── README.md
├── .gitignore
├── assets/
│ └── cover-odyssey.png
├── config/
│ ├── corrections_zh.json
│ └── hotwords_zh.txt
├── data/
│ ├── decision_storylines_v2.json
│ ├── manifest.json
│ ├── odyssey_search_index.json
│ ├── source_index.json
│ └── intake/
├── internal-skills/
│ └── odyssey-case-ingestion/
│ ├── SKILL.md
│ ├── agents/
│ └── references/
├── odyssey-skill/
│ ├── SKILL.md
│ ├── agents/
│ │ └── openai.yaml
│ ├── references/
│ │ ├── data-contract.md
│ │ ├── response-style.md
│ │ └── search-policy.md
│ └── scripts/
├── scripts/
└── tests/
说明:
AGENTS.md:本文件,维护 Agent 的项目地图和操作规则。结构变化时实时更新。README.md:用户侧说明和安装介绍。不要写内部维护细节。assets/:用户侧展示素材,目前包含封面图。config/:采集/转写辅助配置,包含中文热词和确定性错词修正。data/:唯一的数据归档和发布目录。internal-skills/:仅供维护者/Agent 使用的内部技能。odyssey-skill/:可安装的用户侧 skill 包。scripts/:仓库级辅助脚本,当前主要是历史/运维辅助,不是用户侧 skill 脚本入口。tests/:脚本、索引和数据契约测试。
数据目录
所有新数据都放在 data/:
data/intake/YYYY-MM-DD/:入选 URL、Lark 导出、blocked 列表、采集报告;候选源归档到其下的candidates/。data/assets/YYYY-MM-DD/:下载的字幕、音频、图片、OCR、ASR 转写和采集元数据。data/working/YYYY-MM-DD/:URL 采集后的sources.json、stories.json、report.md、methods.md;重试采集产物归档到其下的retry/。data/case3.0/:人工 deep-read 后写出的 case Markdown,一案一文件。data/final/:由 case3 Markdown 生成的 final JSON、Markdown 和 case index。data/decision_storylines_v2.json:发布给搜索脚本使用的主数据库。data/odyssey_search_index.json:搜索索引。data/source_index.json:来源索引。data/manifest.json:远端数据 manifest。
当前仓库里已有 data/intake/2026-06-10/ 下的候选和入选记录;后续新批次按日期子目录继续归档。
原始音视频文件可保留在本机 data/assets/ 下用于复跑转写,但默认不进入 Git;提交时保留转写文本、字幕、OCR、采集元数据和 final/index 产物。
用户侧 Skill
用户侧 skill 位于 odyssey-skill/:
odyssey-skill/SKILL.md:面向用户的人生决策案例搜索和回答流程。保持轻量,不加入内部采集流程。odyssey-skill/agents/openai.yaml:Codex/OpenAI agent UI 元数据。odyssey-skill/references/data-contract.md:搜索数据字段契约。odyssey-skill/references/response-style.md:用户回答风格。odyssey-skill/references/search-policy.md:搜索、排序和边界策略。
用户侧搜索脚本:
fetch_indexes.py:拉取远端索引并写入本地缓存。search_odyssey.py:根据用户处境广召回真实案例;JSON 默认返回 30 条多样化候选,按 case 分轮补位,附带ranking_evidence和rank_hints供 Agent 最终 rerank。validate_remote_data.py:验证发布数据契约。build_indexes.py:由decision_storylines_v2.json生成 manifest、搜索索引和来源索引;构建搜索文本时不把字段名和原文未提及用作标签触发词,并为每个节点输出ranking_evidence。
内部采集与生成脚本
内部维护脚本位于 odyssey-skill/scripts/:
collect_source_urls.py:从 Markdown URL 列表采集 Bilibili、Podcast、小红书原文,输出 working 和 assets。acquire_bilibili_subtitles.py:针对入选 Bilibili 记录抓官方字幕。acquire_audio_transcripts.py:对已下载音频做 ASR 转写。generate_final_from_case3.py:从data/case3.0/生成data/final/。search_candidate_sources.py:搜索候选案例源。ingestion_candidates.py:把候选源转成 Lark Base 可导入/更新的记录。export_selected_lark_cases.py:规范化 Lark 入选记录。sync_case3_from_odysseymap.py:历史迁移工具,仅用于从旧 OdysseyMap 迁移,不是新流程入口。asr.py、asr_quality.py、ocr.py、completeness.py、report.py、text_normalize.py:采集、转写、OCR、完整度、报告和文本规范化支撑模块。platforms/:平台采集实现,包含bilibili.py、podcast.py、xiaohongshu.py。
补充:
collect_source_urls.py支持直接读取规范化后的 selected cases JSON,并将case_id、record_id、source_id、Base 备注、主题标签等 seed 到 source 记录。collect_source_urls.py支持小宇宙、Firstory、Fireside Podcast 链接;每完成一条 source 会立即 checkpoint 写出sources.json、stories.json、report.md、methods.md,避免长 ASR 中断导致已完成结果丢失。asr.py中--asr-timeout-seconds 0表示不设置单条 ASR 超时。
内部采集脚本可以依赖 requests、beautifulsoup4、yt-dlp、faster-whisper、mlx-whisper、whisperx、pytesseract 等可选依赖;用户侧搜索 runtime 仍保持轻量。
内部 Skill
内部 skill 位于 internal-skills/odyssey-case-ingestion/:
SKILL.md:维护流程总入口,覆盖候选搜索、URL 采集、case3 编写、final 生成、索引重建和验证。references/acquisition-methods.md:Bilibili、Podcast、小红书采集方法。references/case3-authoring.md:case3 Markdown 编写结构和事实边界。agents/:内部 skill UI 元数据目录;如新增/修改内部 skill 展示信息,需要同步更新。
标准流程
从 URL 到发布索引的标准流程:
- 入选 URL 或 Lark 导出放入
data/intake/YYYY-MM-DD/。 - 采集源内容:
python3 odyssey-skill/scripts/collect_source_urls.py \
--input data/intake/YYYY-MM-DD/selected_urls.md \
--output data/working/YYYY-MM-DD \
--asset-root data/assets/YYYY-MM-DD
- 人工 deep-read,把 case Markdown 写入
data/case3.0/。 - 生成 final:
python3 odyssey-skill/scripts/generate_final_from_case3.py \
--case-dir data/case3.0 \
--out-dir data/final
- 发布主数据库并重建索引:
cp data/final/decision_storylines_v2.json data/decision_storylines_v2.json
python3 odyssey-skill/scripts/build_indexes.py \
--source data/decision_storylines_v2.json \
--out-dir data
- 验证:
pytest tests -q
python3 odyssey-skill/scripts/validate_remote_data.py --data-dir data
/opt/anaconda3/bin/python /Users/chenkai/.codex/skills/.system/skill-creator/scripts/quick_validate.py odyssey-skill
本机系统 python3 缺少 PyYAML,运行 quick_validate.py 时使用 /opt/anaconda3/bin/python。
搜索与排序规则
- 保留较丰富的
search_tags用于召回,但build_indexes.py的标签推断只看字段值,不看 schema 字段名;缺失事实原文未提及不参与搜索文本和标签推断。 search_odyssey.py --json默认广召回 30 条候选;排序先做确定性预排序,再做 case-level diversity:每个 case 先取最佳节点,候选不足时再补同 case 的后续节点。- 同分结果使用
query + case_id + node_id的稳定 hash 作为最后 tie-breaker,避免原始索引顺序长期偏置。 - Agent 必须基于候选 JSON 中的
ranking_evidence、matched_terms、matched_dimensions做最终 rerank;默认展示 3 个不同 case,除非用户明确想深入同一个故事。
采集与事实规则
- 不得只根据平台简介、标题、评论或元数据结构化案例。
- 缺失事实写
原文未提及。 - 推断事实必须以
推断:开头。 - 保留可追踪字段:
source_links、source_ids、source_text_paths、case_id、protagonist_id、node_id。 - Bilibili:官方字幕优先,其次
bccdl,最后音频 ASR。 - Podcast:从 Apple
i=episode id、iTunes lookup/RSS 获取音频,再 ASR。 - 小红书:公开正文加可见图片 OCR;不得点赞、评论、关注、私信或修改任何内容。
测试结构
tests/ 覆盖以下内容:
- 数据索引与远端数据验证:
test_build_indexes.py、test_fetch_indexes.py、test_validate_remote_data.py、test_search_odyssey.py。 - 候选和 Lark 相关脚本:
test_search_candidate_sources.py、test_ingestion_candidates.py、test_export_selected_lark_cases.py、test_upload_lark_jsonl.py。 - 采集与转写脚本:
test_collect_source_urls.py、test_acquire_bilibili_subtitles.py、test_acquire_audio_transcripts.py。 - ASR 和平台采集细节:
test_asr.py、test_podcast_platform.py。 - final 生成和历史同步:
test_generate_final_from_case3.py、test_sync_case3.py。
新增脚本时优先补最小单元测试;改变路径默认值时必须补路径断言测试,确保输出仍在 odyssey-skill/data 内。
