From 4cfe178b413c226536fc9dd871430507ca9fae47 Mon Sep 17 00:00:00 2001 From: Narylr <2378396898@qq.com> Date: Thu, 19 Mar 2026 22:59:36 +0800 Subject: [PATCH] Wrap skill in subdirectory and add repo usage guide --- README.md | 189 ++++++++++-------- book-source-creator/README.md | 129 ++++++++++++ SKILL.md => book-source-creator/SKILL.md | 0 .../references}/examples.md | 0 .../scripts}/analyze_with_playwright.mjs | 0 .../scripts}/analyze_with_playwright.py | 0 .../scripts}/generate_template.mjs | 0 .../scripts}/generate_template.py | 0 .../scripts}/lib/book_source_tools.mjs | 0 .../scripts}/test_rules.mjs | 0 .../scripts}/test_rules.py | 0 .../scripts}/validate_source.mjs | 0 .../scripts}/validate_source.py | 0 .../tests}/book_source_tools.test.mjs | 0 14 files changed, 231 insertions(+), 87 deletions(-) create mode 100644 book-source-creator/README.md rename SKILL.md => book-source-creator/SKILL.md (100%) rename {references => book-source-creator/references}/examples.md (100%) rename {scripts => book-source-creator/scripts}/analyze_with_playwright.mjs (100%) rename {scripts => book-source-creator/scripts}/analyze_with_playwright.py (100%) rename {scripts => book-source-creator/scripts}/generate_template.mjs (100%) rename {scripts => book-source-creator/scripts}/generate_template.py (100%) rename {scripts => book-source-creator/scripts}/lib/book_source_tools.mjs (100%) rename {scripts => book-source-creator/scripts}/test_rules.mjs (100%) rename {scripts => book-source-creator/scripts}/test_rules.py (100%) rename {scripts => book-source-creator/scripts}/validate_source.mjs (100%) rename {scripts => book-source-creator/scripts}/validate_source.py (100%) rename {tests => book-source-creator/tests}/book_source_tools.test.mjs (100%) diff --git a/README.md b/README.md index df3942d..4641aa2 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,63 @@ -# Legado书源创建技能 +# book-source-creator-skill -用于为 Legado 阅读器创建、调试和验证书源。这个技能默认遵循三条原则： +仓库地址：`https://github.com/Narylr350/book-source-creator-skill` -- AI 对页面结构、接口链路和规则语义的判断优先于脚本输出 -- 网站可登录时，优先在登录态下分析 -- 登录需要扫码、验证码、短信或人工确认时，应立即请求人类协助 -- 正式生成书源前，必须先做网站可生成性评估 +这是一个用于为 Legado 阅读器创建、调试和验证书源的技能仓库。仓库根目录用于说明如何使用，真正的技能包放在 [`book-source-creator/`](./book-source-creator/) 目录里，这样不会和技能本身的 `README.md` 冲突。 -## 可生成性评估 +这个 skill 已在 Codex 环境中测试成功。其他 AI 工具目前没有系统测试过，所以不承诺在其他工具里能直接得到同样结果。 -在写规则前，先输出一份站点评估。评级只允许使用以下四类： +## 需要什么 -- `可直接生成` -- `可生成但高风险` -- `需登录后再评估` -- `不建议生成` +- 一个支持技能机制的 Codex 环境 +- 可用的浏览器分析能力，核心依赖是 Browser MCP +- 目标小说网站 URL +- 如果站点需要登录，需要能由人类协助完成登录 +- 如果要运行辅助脚本，建议有 Node.js；只看技能文档则不强依赖本地脚本 +- 一个用于最终导入验证的 Legado 阅读器 -如果评级为 `需登录后再评估` 或 `不建议生成`，仍然允许继续，但必须明确标成 `高风险`，并说明继续生成的理由。 +## 仓库结构 -推荐输出模板： +```text +book-source-creator-skill/ + README.md # 仓库级使用说明 + book-source-creator/ # 技能本体 + SKILL.md + README.md + scripts/ + references/ + tests/ +``` + +技能详细说明见 [`book-source-creator/README.md`](./book-source-creator/README.md)，技能入口说明见 [`book-source-creator/SKILL.md`](./book-source-creator/SKILL.md)。 + +## 如何使用 + +把 [`book-source-creator/`](./book-source-creator/) 整个目录放到你的技能目录中即可。 + +常见做法示例： + +```text +~/.cc-switch/skills/book-source-creator/ +~/.codex/skills/book-source-creator/ +``` + +安装后，在需要为 Legado 阅读器创建、调试或验证书源时调用这个 skill。 + +## 标准流程 + +这个 skill 的推荐流程是： + +1. 先判断目标站点是否需要登录。 +2. 如果需要登录，优先在登录态下分析；如果登录需要扫码、验证码、短信或人工确认，应立即请求人类协助。 +3. 在写任何规则前，先输出一份“网站可生成性评估”。 +4. 再使用 Browser MCP 分析搜索、详情、目录、正文四段链路。 +5. 根据真实页面结构和请求链路生成书源。 +6. 用辅助脚本做结构校验和规则审计。 +7. 最后导入 Legado 做实际可用性验证。 + +## 网站可生成性评估模板 + +在正式写规则前，建议先输出： ```markdown ## 网站可生成性评估 @@ -34,96 +73,72 @@ - 继续生成理由 / 停止理由： ``` -## 脚本现状 +允许使用的评级： -主脚本现在以 Node 为主： +- `可直接生成` +- `可生成但高风险` +- `需登录后再评估` +- `不建议生成` -- `scripts/analyze_with_playwright.mjs` -- `scripts/validate_source.mjs` -- `scripts/test_rules.mjs` -- `scripts/generate_template.mjs` +其中 `需登录后再评估` 和 `不建议生成` 不是硬阻断，但如果继续做，必须明确标记为 `高风险` 并说明理由。 -同名 `.py` 文件保留为兼容入口，会自动转调到对应的 `.mjs` 脚本。 +## 示例 -## 依赖 +### 示例 1：输入 -```bash -npm i playwright +```text +请为 https://www.163zw.com/ 创建一个 Legado 书源，并验证搜索、详情、目录和正文。 ``` -如果只使用 `validate_source.mjs`、`test_rules.mjs` 或 `generate_template.mjs`，不需要额外依赖。 +### 示例 2：期望执行过程 -## 推荐用法 - -```bash -# 分析网站，支持人工登录后继续 -node scripts/analyze_with_playwright.mjs https://novel-site.com --manual-login --save analysis.json - -# 基于分析结果生成模板 -node scripts/generate_template.mjs --analysis analysis.json - -# 审计规则，不伪装成完整 Legado 解析器 -node scripts/test_rules.mjs my_source.json --keyword 凡人修仙传 - -# 验证书源结构 -node scripts/validate_source.mjs my_source.json -``` - -兼容旧命令： - -```bash -python scripts/analyze_with_playwright.py https://novel-site.com --manual-login -python scripts/test_rules.py my_source.json -python scripts/validate_source.py my_source.json -``` - -推荐执行顺序： - -1. 先判断是否需要登录 +```text +1. 判断是否需要登录 2. 输出网站可生成性评估 -3. 再分析搜索、详情、目录、正文 -4. 最后生成和验证书源 +3. 用 Browser MCP 验证搜索入口和结果列表 +4. 进入详情页，确认书名、作者、简介、封面、目录入口 +5. 进入目录，确认是否分页 +6. 进入正文，确认是否多页、是否有广告、是否需要拼接 +7. 生成书源 JSON +8. 做结构校验和规则审计 +9. 导入 Legado 实测 +``` + +### 示例 3：163中文网实测结论 + +这个仓库对应的 skill 已经实际用于 `163中文网` 书源生成与验证： + +- 搜索、详情、目录、正文链路都已通过 Browser MCP 实测 +- 目录存在分页，已纳入规则设计 +- 正文存在单章多页，已纳入规则设计 +- 在当前测试样本下，`163中文网` 书源未发现明显问题 + +这里的“未发现问题”是指在 Codex + Browser MCP + Legado 导入验证这一轮里没有发现明显故障，不代表站点未来不会改版。 ## 脚本说明 -### `analyze_with_playwright.mjs` +技能附带的脚本在 [`book-source-creator/scripts/`](./book-source-creator/scripts/)： -- 打开真实浏览器分析页面 -- 可通过 `--manual-login` 让人类先完成登录 -- 记录登录相关元素、搜索入口、候选结果区块和部分网络请求 -- 适合需要登录态、动态内容或接口观察的站点 +- `analyze_with_playwright.mjs`：辅助分析真实页面 +- `validate_source.mjs`：校验书源 JSON 结构 +- `test_rules.mjs`：审计规则风险和占位问题 +- `generate_template.mjs`：生成模板 -### `validate_source.mjs` +同名 `.py` 文件是兼容入口，会转调到对应的 `.mjs` 脚本。 -- 验证必填字段 -- 验证常见字段类型 -- 检查基础规则组结构 -- 输出错误和警告，适合做结构体检 +脚本是辅助工具，不是判断中心。如果脚本结果和真实页面表现冲突，应以 Browser MCP 看到的真实页面和请求证据为准。 -### `test_rules.mjs` +## 测试状态 -- 审计规则是否仍是占位文案 -- 标记 JS/正则类高风险字段 -- 预览 `searchUrl` 变量替换结果 -- 不声称能完整执行 Legado 规则 +已验证： -### `generate_template.mjs` +- Codex 环境下可正常使用这个 skill +- Browser MCP 驱动的网站分析流程可跑通 +- Node 版本辅助脚本可运行 +- `163中文网` 的样例书源已经过一轮实际验证，当前未见明显问题 -- 支持交互式生成模板 -- 支持基于 `analysis.json` 生成模板 -- 默认禁用发现功能 -- 可填写登录 URL +未验证： -## 调试建议 - -- 先看真实页面和真实请求，再看脚本输出 -- 脚本失败时先判断是脚本问题、环境问题还是站点行为变化 -- 如果脚本结论和页面真实表现冲突，应以页面和接口证据为准 -- 登录前后页面结构不同的站点，必须分别检查搜索、详情、目录和正文 -- 评估结论为 `需登录后再评估` 或 `不建议生成` 时，继续生成必须明确标记为高风险 - -## 测试 - -```bash -node --test tests/book_source_tools.test.mjs -``` +- 其他 AI 工具中的兼容性 +- 所有小说站点的通用成功率 +- 所有登录态站点的行为一致性 diff --git a/book-source-creator/README.md b/book-source-creator/README.md new file mode 100644 index 0000000..df3942d --- /dev/null +++ b/book-source-creator/README.md @@ -0,0 +1,129 @@ +# Legado书源创建技能 + +用于为 Legado 阅读器创建、调试和验证书源。这个技能默认遵循三条原则： + +- AI 对页面结构、接口链路和规则语义的判断优先于脚本输出 +- 网站可登录时，优先在登录态下分析 +- 登录需要扫码、验证码、短信或人工确认时，应立即请求人类协助 +- 正式生成书源前，必须先做网站可生成性评估 + +## 可生成性评估 + +在写规则前，先输出一份站点评估。评级只允许使用以下四类： + +- `可直接生成` +- `可生成但高风险` +- `需登录后再评估` +- `不建议生成` + +如果评级为 `需登录后再评估` 或 `不建议生成`，仍然允许继续，但必须明确标成 `高风险`，并说明继续生成的理由。 + +推荐输出模板： + +```markdown +## 网站可生成性评估 +- 目标站点： +- 登录状态： +- 搜索可用性： +- 详情可用性： +- 目录可用性： +- 正文可用性： +- 特殊风险： +- 可生成性评级： +- 是否继续生成： +- 继续生成理由 / 停止理由： +``` + +## 脚本现状 + +主脚本现在以 Node 为主： + +- `scripts/analyze_with_playwright.mjs` +- `scripts/validate_source.mjs` +- `scripts/test_rules.mjs` +- `scripts/generate_template.mjs` + +同名 `.py` 文件保留为兼容入口，会自动转调到对应的 `.mjs` 脚本。 + +## 依赖 + +```bash +npm i playwright +``` + +如果只使用 `validate_source.mjs`、`test_rules.mjs` 或 `generate_template.mjs`，不需要额外依赖。 + +## 推荐用法 + +```bash +# 分析网站，支持人工登录后继续 +node scripts/analyze_with_playwright.mjs https://novel-site.com --manual-login --save analysis.json + +# 基于分析结果生成模板 +node scripts/generate_template.mjs --analysis analysis.json + +# 审计规则，不伪装成完整 Legado 解析器 +node scripts/test_rules.mjs my_source.json --keyword 凡人修仙传 + +# 验证书源结构 +node scripts/validate_source.mjs my_source.json +``` + +兼容旧命令： + +```bash +python scripts/analyze_with_playwright.py https://novel-site.com --manual-login +python scripts/test_rules.py my_source.json +python scripts/validate_source.py my_source.json +``` + +推荐执行顺序： + +1. 先判断是否需要登录 +2. 输出网站可生成性评估 +3. 再分析搜索、详情、目录、正文 +4. 最后生成和验证书源 + +## 脚本说明 + +### `analyze_with_playwright.mjs` + +- 打开真实浏览器分析页面 +- 可通过 `--manual-login` 让人类先完成登录 +- 记录登录相关元素、搜索入口、候选结果区块和部分网络请求 +- 适合需要登录态、动态内容或接口观察的站点 + +### `validate_source.mjs` + +- 验证必填字段 +- 验证常见字段类型 +- 检查基础规则组结构 +- 输出错误和警告，适合做结构体检 + +### `test_rules.mjs` + +- 审计规则是否仍是占位文案 +- 标记 JS/正则类高风险字段 +- 预览 `searchUrl` 变量替换结果 +- 不声称能完整执行 Legado 规则 + +### `generate_template.mjs` + +- 支持交互式生成模板 +- 支持基于 `analysis.json` 生成模板 +- 默认禁用发现功能 +- 可填写登录 URL + +## 调试建议 + +- 先看真实页面和真实请求，再看脚本输出 +- 脚本失败时先判断是脚本问题、环境问题还是站点行为变化 +- 如果脚本结论和页面真实表现冲突，应以页面和接口证据为准 +- 登录前后页面结构不同的站点，必须分别检查搜索、详情、目录和正文 +- 评估结论为 `需登录后再评估` 或 `不建议生成` 时，继续生成必须明确标记为高风险 + +## 测试 + +```bash +node --test tests/book_source_tools.test.mjs +``` diff --git a/SKILL.md b/book-source-creator/SKILL.md similarity index 100% rename from SKILL.md rename to book-source-creator/SKILL.md diff --git a/references/examples.md b/book-source-creator/references/examples.md similarity index 100% rename from references/examples.md rename to book-source-creator/references/examples.md diff --git a/scripts/analyze_with_playwright.mjs b/book-source-creator/scripts/analyze_with_playwright.mjs similarity index 100% rename from scripts/analyze_with_playwright.mjs rename to book-source-creator/scripts/analyze_with_playwright.mjs diff --git a/scripts/analyze_with_playwright.py b/book-source-creator/scripts/analyze_with_playwright.py similarity index 100% rename from scripts/analyze_with_playwright.py rename to book-source-creator/scripts/analyze_with_playwright.py diff --git a/scripts/generate_template.mjs b/book-source-creator/scripts/generate_template.mjs similarity index 100% rename from scripts/generate_template.mjs rename to book-source-creator/scripts/generate_template.mjs diff --git a/scripts/generate_template.py b/book-source-creator/scripts/generate_template.py similarity index 100% rename from scripts/generate_template.py rename to book-source-creator/scripts/generate_template.py diff --git a/scripts/lib/book_source_tools.mjs b/book-source-creator/scripts/lib/book_source_tools.mjs similarity index 100% rename from scripts/lib/book_source_tools.mjs rename to book-source-creator/scripts/lib/book_source_tools.mjs diff --git a/scripts/test_rules.mjs b/book-source-creator/scripts/test_rules.mjs similarity index 100% rename from scripts/test_rules.mjs rename to book-source-creator/scripts/test_rules.mjs diff --git a/scripts/test_rules.py b/book-source-creator/scripts/test_rules.py similarity index 100% rename from scripts/test_rules.py rename to book-source-creator/scripts/test_rules.py diff --git a/scripts/validate_source.mjs b/book-source-creator/scripts/validate_source.mjs similarity index 100% rename from scripts/validate_source.mjs rename to book-source-creator/scripts/validate_source.mjs diff --git a/scripts/validate_source.py b/book-source-creator/scripts/validate_source.py similarity index 100% rename from scripts/validate_source.py rename to book-source-creator/scripts/validate_source.py diff --git a/tests/book_source_tools.test.mjs b/book-source-creator/tests/book_source_tools.test.mjs similarity index 100% rename from tests/book_source_tools.test.mjs rename to book-source-creator/tests/book_source_tools.test.mjs