Wrap skill in subdirectory and add repo usage guide
This commit is contained in:
Narylr committed
1 parent
5435ebac6e
commit
4cfe178b41
14 files changed
+231
-87
No files matched your search
@@ -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 工具中的兼容性
|
||||
- 所有小说站点的通用成功率
|
||||
- 所有登录态站点的行为一致性
|
||||
@@ -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
|
||||
```
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Reference in new issue
Block a user