From ced493114f8ec40d335832282fa2c01d4faeb36c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=BB=84=E6=B8=A0=E6=88=90?= <1102339344@qq.com>
Date: Mon, 10 Aug 2026 20:33:11 +0800
Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96=20OpenSpec=20?=
=?UTF-8?q?=E5=B9=B6=E6=95=B4=E7=90=86=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.gitignore | 2 +
AGENTS.md | 94 ++++++++++++++++++
README.md | 226 +++++++++++++++++++++++++------------------
openspec/config.yaml | 41 ++++++++
4 files changed, 268 insertions(+), 95 deletions(-)
create mode 100644 AGENTS.md
create mode 100644 openspec/config.yaml
diff --git a/.gitignore b/.gitignore
index d6401dcba..7fae4f8db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,5 +14,7 @@ node_modules/
/app/gradle.properties
package-lock.json
.idea/
+# OpenSpec 为本地智能体生成的上游工作流指令
+.agents/skills/
# Kotlin 2.0
.kotlin/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..4bb682910
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,94 @@
+# AGENTS.md
+
+## 适用范围
+
+- 本文件适用于整个仓库；子目录若有更具体的 `AGENTS.md`，以更深层文件为准。
+- 修改前先查看 `git status --short`，保留用户已有的未提交改动，不要顺手重排或清理无关文件。
+- 变更应小而聚焦；除非任务明确要求，不要同时升级依赖、重构代码或改写生成文件。
+
+## 项目概览
+
+Legado（开源阅读）是一款不内置内容的 Android 阅读器。主工程是使用 Kotlin、Java 17
+和 Gradle 构建的多模块 Android 项目，最低支持 Android 5.0（API 21）。仓库还包含一个
+独立的 Vue 3 Web 子项目。
+
+## 文档语言
+
+- 仓库内新建或维护的项目文档一律使用简体中文，包括 `README`、`AGENTS.md`、开发说明、
+ 设计记录以及 OpenSpec 的提案、设计、规范和任务文件。
+- 文档中的说明、标题、验收条件和提交给维护者的总结必须使用中文，不要中英文混写。
+- 代码标识符、命令、文件路径、协议字段、依赖坐标和无法准确翻译的专有名词可以保留原文，
+ 但相关解释必须使用中文。
+- `English.md` 等明确面向其他语言用户的翻译文件可以保留对应语言；中文文档是内容基准，
+ 中文内容发生实质变化时应同步维护翻译版本。
+
+## 目录与职责
+
+- `app/`：Android 应用、资源、Room 数据库、单元测试和设备测试。
+- `modules/book/`：书籍解析与阅读相关的 Android 库。
+- `modules/rhino/`：Rhino JavaScript 执行支持。
+- `modules/web/`：Vue 3、TypeScript、Vite 和 pnpm 管理的 Web 书架与源编辑器。
+- `gradle/libs.versions.toml`：Gradle 依赖与插件版本目录。
+- `app/schemas/`：Room 导出的数据库结构快照，数据库结构变化时必须同步更新。
+- `app/src/main/assets/`：内置帮助、默认数据和 Web 静态资源；修改时注意格式与向后兼容。
+- `openspec/`：OpenSpec 的规范、变更提案及归档。
+
+## 开发约定
+
+### Android
+
+- 沿用相邻代码的 Kotlin 风格：4 空格缩进、官方 Kotlin 代码风格、清晰的空安全处理，避免无必要的 `!!`。
+- UI 文案放在字符串资源中，并同步考虑已有的多语言资源；不要在业务代码中新增可见硬编码文案。
+- 网络、数据库和文件操作不得阻塞主线程；协程应绑定合适的生命周期和调度器。
+- 修改 Room 实体、DAO 或数据库版本时，同步迁移逻辑、`app/schemas/` 和相关迁移测试。
+- 书源、订阅源、规则解析、备份恢复和导入 URI 属于兼容性敏感接口。除非提案明确要求，不要破坏已有 JSON 字段、规则语义或 URI path。
+- 遵守 `gradle/libs.versions.toml` 中的固定版本说明。带有“不要更新版本”或兼容性注释的依赖不得顺手升级。
+- 不要提交本地签名文件、凭据、`local.properties`、构建产物或 IDE 状态。不要改动 CI 中的签名配置，除非任务明确要求且已确认安全边界。
+
+### 网页端
+
+- `modules/web/` 使用 Node.js 20+、pnpm 9+、Vue 3 和 TypeScript。
+- 遵循 `modules/web/.editorconfig`、ESLint 和 Prettier 配置；优先延续现有 Composition API 与目录组织。
+- `pnpm lint:fix` 和 `pnpm format` 会写文件。仅检查时使用 `pnpm exec eslint .`，不要在无关任务中批量格式化。
+- 网页端构建脚本会把产物同步到 Android 静态资源；提交前检查同步结果，避免混入无关生成差异。
+
+## OpenSpec 工作流
+
+- 新功能、用户可见行为变化、数据格式或兼容性变化，以及跨模块重构，应先在 `openspec/changes/` 建立变更并通过评审，再实现代码。
+- 纯文档、注释和机械格式修复通常无需新建变更；如果它们改变了对外承诺或行为规范，仍应走 OpenSpec。
+- 开始工作前运行 `openspec list` 并查看相关现有规范或变更，避免重复或冲突。
+- 提案必须写明范围、非目标、受影响模块、兼容性与迁移风险，以及可验证的验收条件。
+- 实现过程中保持提案、设计、规范和任务与代码一致；不要把未验证事项标记为完成。
+- 完成后运行 `openspec validate --all --strict`。只有实现与验证均完成后才能归档变更。
+
+## 常用验证命令
+
+按改动范围选择最小充分验证；不要为了文档变更启动完整 Android 构建。
+
+```bash
+# Android 单元测试
+./gradlew :app:testAppDebugUnitTest
+
+# Android 静态检查与可安装调试包
+./gradlew :app:lintAppDebug
+./gradlew :app:assembleAppDebug
+
+# 网页端类型检查、静态检查与构建
+cd modules/web
+pnpm install
+pnpm type-check
+pnpm exec eslint .
+pnpm build
+
+# OpenSpec 与补丁基础检查
+openspec validate --all --strict
+git diff --check
+```
+
+设备测试位于 `app/src/androidTest/`，需要可用的模拟器或真机；若未运行，交付时明确说明。
+
+## 提交与交付
+
+- 提交信息应简短说明意图；可参考仓库现有风格，关联 issue 时保留编号。
+- 交付前检查 `git diff --stat` 和 `git diff --check`，确认没有无关改动、尾随空格或意外生成文件。
+- 汇报实际执行过的验证及结果；没有运行的构建、测试或设备验证不得描述为已通过。
diff --git a/README.md b/README.md
index 08375523e..b6591a14c 100644
--- a/README.md
+++ b/README.md
@@ -1,110 +1,146 @@
-# [English](English.md) [中文](README.md)
+# Legado / 开源阅读
-[](https://play.google.com/store/apps/details?id=io.legado.play.release)
-
-
-
+
-[](#contents) [](#Function-主要功能-) [](#Community-交流社区-) [](#API-) [](#Other-其他-) [](#Grateful-感谢-) [](#Interface-界面-)
+> [!IMPORTANT]
+> 软件不提供任何内容，需要您自行手动添加，例如导入书源。初次使用前请查看
+> [官方帮助文档](https://www.yuque.com/legado/wiki)。
->新用户？
->
->软件不提供内容，需要您自己手动添加，例如导入书源等。
->看看 [官方帮助文档](https://www.yuque.com/legado/wiki)，也许里面就有你要的答案。
+## 目录
-# Function-主要功能 [](#Function-主要功能-)
-[English](English.md)
+- [主要功能](#主要功能)
+- [交流社区](#交流社区)
+- [API](#api)
+- [其他资源](#其他资源)
+- [致谢](#致谢)
+- [界面预览](#界面预览)
-中文
-1.自定义书源，自己设置规则，抓取网页数据，规则简单易懂，软件内有规则说明。
-2.列表书架，网格书架自由切换。
-3.书源规则支持搜索及发现，所有找书看书功能全部自定义，找书更方便。
-4.订阅内容,可以订阅想看的任何内容,看你想看
-5.支持替换净化，去除广告替换内容很方便。
-6.支持本地TXT、EPUB阅读，手动浏览，智能扫描。
-7.支持高度自定义阅读界面，切换字体、颜色、背景、行距、段距、加粗、简繁转换等。
-8.支持多种翻页模式，覆盖、仿真、滑动、滚动等。
-9.软件开源，持续优化，无广告。
-
-
+1. 支持自定义书源，可自行设置规则抓取网页数据；软件内提供规则说明。
+2. 支持列表书架和网格书架自由切换。
+3. 书源规则支持搜索与发现，找书、看书功能均可自定义。
+4. 支持订阅自定义内容。
+5. 支持替换净化，便于去除广告或替换内容。
+6. 支持本地 TXT、EPUB 阅读，可手动浏览或智能扫描。
+7. 阅读界面可高度自定义，包括字体、颜色、背景、行距、段距、加粗和简繁转换等。
+8. 支持覆盖、仿真、滑动、滚动等多种翻页模式。
+9. 软件开源、持续优化且无广告。
-# Community-交流社区 [](#Community-交流社区-)
+## 交流社区
+
+### Telegram
-#### Telegram
[](https://t.me/yueduguanfang) [](https://t.me/legado_channels)
-#### Discord
+### Discord
+
[](https://discord.gg/VtUfRyzRXn)
-#### Other
-https://www.yuque.com/legado/wiki/community
-
-
-
-
-
-# API [](#API-)
-* 阅读3.0 提供了2种方式的API：`Web方式`和`Content Provider方式`。您可以在[这里](api.md)根据需要自行调用。
-* 可通过url唤起阅读进行一键导入,url格式: legado://import/{path}?src={url}
-* path类型: bookSource,rssSource,replaceRule,textTocRule,httpTTS,theme,readConfig,dictRule,[addToBookshelf](/app/src/main/java/io/legado/app/ui/association/AddToBookshelfDialog.kt)
-* path类型解释: 书源,订阅源,替换规则,本地txt小说目录规则,在线朗读引擎,主题,阅读排版,添加到书架
-
-
-
-
-
-# Other-其他 [](#Other-其他-)
-##### 免责声明
-https://gedoor.github.io/Disclaimer
-
-##### 阅读3.0
-* [书源规则](https://mgz0227.github.io/The-tutorial-of-Legado/)
-* [更新日志](/app/src/main/assets/updateLog.md)
-* [帮助文档](/app/src/main/assets/web/help/md/appHelp.md)
-* [web端书架](https://github.com/gedoor/legado_web_bookshelf)
-* [web端源编辑](https://github.com/gedoor/legado_web_source_editor)
-
-
-
-
-
-# Grateful-感谢 [](#Grateful-感谢-)
-> * org.jsoup:jsoup
-> * cn.wanghaomiao:JsoupXpath
-> * com.jayway.jsonpath:json-path
-> * com.github.gedoor:rhino-android
-> * com.squareup.okhttp3:okhttp
-> * com.github.bumptech.glide:glide
-> * org.nanohttpd:nanohttpd
-> * org.nanohttpd:nanohttpd-websocket
-> * cn.bingoogolapple:bga-qrcode-zxing
-> * com.jaredrummler:colorpicker
-> * org.apache.commons:commons-text
-> * io.noties.markwon:core
-> * io.noties.markwon:image-glide
-> * com.hankcs:hanlp
-> * com.positiondev.epublib:epublib-core
-
-
-
-
-# Interface-界面 [](#Interface-界面-)
-
-
-
-
-
-
+更多联系方式见[社区列表](https://www.yuque.com/legado/wiki/community)。
+
+## API
+
+- 阅读 3.0 提供网页接口（`Web`）和内容提供器（`Content Provider`）两种 API 调用方式，详见
+ [API 文档](api.md)。
+- 可通过 URL 唤起阅读并一键导入，格式为
+ `legado://import/{path}?src={url}`。
+- `path` 支持以下类型：
+
+| `path` | 用途 |
+| --- | --- |
+| `bookSource` | 书源 |
+| `rssSource` | 订阅源 |
+| `replaceRule` | 替换规则 |
+| `textTocRule` | 本地 TXT 小说目录规则 |
+| `httpTTS` | 在线朗读引擎 |
+| `theme` | 主题 |
+| `readConfig` | 阅读排版 |
+| `dictRule` | 字典规则 |
+| [`addToBookshelf`](app/src/main/java/io/legado/app/ui/association/AddToBookshelfDialog.kt) | 添加到书架 |
+
+## 其他资源
+
+- [免责声明](https://gedoor.github.io/Disclaimer)
+- [书源规则](https://mgz0227.github.io/The-tutorial-of-Legado/)
+- [更新日志](app/src/main/assets/updateLog.md)
+- [帮助文档](app/src/main/assets/web/help/md/appHelp.md)
+- [网页端书架](https://github.com/gedoor/legado_web_bookshelf)
+- [网页端源编辑](https://github.com/gedoor/legado_web_source_editor)
+
+## 致谢
+
+- `org.jsoup:jsoup`
+- `cn.wanghaomiao:JsoupXpath`
+- `com.jayway.jsonpath:json-path`
+- `com.github.gedoor:rhino-android`
+- `com.squareup.okhttp3:okhttp`
+- `com.github.bumptech.glide:glide`
+- `org.nanohttpd:nanohttpd`
+- `org.nanohttpd:nanohttpd-websocket`
+- `cn.bingoogolapple:bga-qrcode-zxing`
+- `com.jaredrummler:colorpicker`
+- `org.apache.commons:commons-text`
+- `io.noties.markwon:core`
+- `io.noties.markwon:image-glide`
+- `com.hankcs:hanlp`
+- `com.positiondev.epublib:epublib-core`
+
+## 界面预览
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 000000000..6ed79c19d
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,41 @@
+schema: spec-driven
+
+context: |
+ Legado（开源阅读）是一款免费、开源且不提供内容的 Android 阅读器。
+ 主工程是使用 Kotlin、Java 17 和 Gradle 构建的多模块 Android 应用，编译与目标
+ SDK 均为 36，最低 SDK 为 21。模块包括 :app、:modules:book 和 :modules:rhino。
+ modules/web 中另有使用 Vue 3、TypeScript、Vite、Node.js 20+ 和 pnpm 9+ 的网页应用。
+
+ 兼容性敏感区域包括书源和订阅源规则、JavaScript 执行、导入 URI 路径、JSON 数据、
+ 备份、Room 数据库迁移以及持久化阅读数据。Room 数据库结构快照位于 app/schemas。
+ gradle/libs.versions.toml 中带有明确兼容性说明的依赖版本必须保持固定，除非变更本身
+ 专门处理相应依赖。
+
+ 仓库边界、编码约定和验证要求以 AGENTS.md 为准。所有项目维护文档和 OpenSpec 工件
+ 必须使用简体中文，代码标识符、命令、路径和必要专有名词除外。面向用户的说明必须
+ 陈述事实，并明确应用本身不提供内容。
+
+rules:
+ proposal:
+ - 使用简体中文说明用户可感知的问题、范围和明确的非目标。
+ - 列出所有受影响的 Android 或网页端模块。
+ - 说明向后兼容、持久化、迁移和安全风险。
+ - 定义可观察的验收条件，不要只列实现层面的检查。
+ design:
+ - 相关时说明对最低 SDK 21、Room 数据、规则格式、导入接口和备份的影响。
+ - 优先沿用现有模块边界和模式；新增依赖或跨模块耦合必须说明理由。
+ tasks:
+ - 行为变化必须配套聚焦的自动化测试或明确的人工验证步骤。
+ - 适用时包含文档、本地化、数据库结构导出和迁移工作。
+ - 最后执行 OpenSpec 严格校验和最小充分的项目检查。
+
+operations:
+ apply:
+ guidance:
+ - 保留工作区中的无关改动，避免大范围格式化重写。
+ - 不要在批准范围外修改签名材料、凭据或特意固定的依赖版本。
+ - 只有实际运行成功的测试和构建才能报告为通过。
+ archive:
+ guidance:
+ - 归档前确认所有任务和验收条件均已完成。
+ - 记录任何未执行的设备验证或人工验证。
-
-Legado / 开源阅读
-
+ 
+