Skip to content

Commit 8cdd322

Browse files
committed
docs: 优化文档站文案
重写首页和各入口页语气,补充准确性边界、发布节奏和规则维护说明。
1 parent 8f84913 commit 8cdd322

17 files changed

Lines changed: 128 additions & 102 deletions

docs/config/categories.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 识别开关
22

3-
设置页第一个 panel,23 个 checkbox。每个 checkbox 对应一个分类,关掉后弹窗里不再显示该分类下的任何技术(包括内置规则与自定义规则)
3+
设置页第一块是分类开关。每个 checkbox 对应一个分类,关掉后弹窗里不再显示该分类下的技术,包括内置规则和自定义规则
44

55
## 全部分类
66

@@ -30,16 +30,16 @@
3030

3131
完整列表:`src/utils/category-order.ts``CATEGORY_ORDER` 数组。
3232

33-
## 全开 / 全关快捷按钮
33+
## 全开 / 全关
3434

35-
panel-head 右上角有两个按钮:「全开」「全关」。一键勾上 / 取消所有 23 个 checkbox
35+
右上角有「全开」「全关」两个按钮,用来批量勾选或取消所有分类
3636

3737
## 关闭分类的常见用途
3838

39-
- **只看技术栈,不看插件**:关「WordPress 插件」「Drupal 模块」,wpscan-style 4000 多条插件名不再涌出来
39+
- **只看技术栈,不看插件**:关「WordPress 插件」「Drupal 模块」,避免插件名把列表撑得太长
4040
- **只看后端不看前端**:关掉前端框架 / UI 框架 / 构建运行时
4141
- **过滤通用 SaaS**:关「广告营销」「统计 / 分析」聚焦核心技术栈
4242

4343
## 实现细节
4444

45-
被关闭的分类不会从 raw JSON 里被剔除——`原始线索` 抽屉仍能看到全部识别结果。识别开关只影响弹窗主列表的过滤显示。所以你随时可以打开看看「关掉的那个分类下到底识别出了什么」
45+
被关闭的分类不会从 raw JSON 里删除。`原始线索` 面板仍能看到完整识别结果。识别开关只影响弹窗主列表的显示

docs/config/custom-css.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 自定义弹窗样式
22

3-
设置页第二个 panel(与「禁用指定技术」并列,two-column 布局)。textarea 里写一段 CSS,保存后会注入到弹窗与设置页的 `<head>` 里,覆盖默认样式
3+
设置页里有一个自定义 CSS 输入框。这里写的 CSS 保存后会注入到弹窗、设置页和帮助页的 `<head>`,用于覆盖默认样式
44

55
## 例子:让置信度药丸更显眼
66

@@ -27,7 +27,7 @@
2727
}
2828
```
2929

30-
弹窗内所有 segment-btn active、tech-link hover、刷新按钮等都会跟着变色,因为它们都是引用 token。
30+
弹窗里的 segment、技术链接 hover、刷新按钮等都引用这些 token,改完会一起变色
3131

3232
## 例子:放大字号
3333

@@ -43,7 +43,7 @@ body {
4343

4444
## 注入位置
4545

46-
所有自定义 CSS 会包在一个固定 ID 的 `<style id="stackPrismCustomCss">` 标签里插入到 `<head>` 末尾。重新保存会替换该 style 内容,不会重复堆积
46+
所有自定义 CSS 会放进固定 ID 的 `<style id="stackPrismCustomCss">` 标签,并插入到 `<head>` 末尾。重新保存会替换旧内容,不会重复追加
4747

4848
## 适用范围
4949

@@ -55,7 +55,7 @@ body {
5555

5656
## 调试技巧
5757

58-
打开弹窗(或设置页),右键 → 检查(DevTools)。你能在 Elements 面板看到自己注入的 style 标签内容,方便调样式
58+
打开弹窗或设置页,右键 → 检查Elements 面板里能看到注入的 style 标签,方便确认选择器是否命中
5959

6060
## 限制
6161

docs/config/custom-rules.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 自定义规则
22

3-
设置页第三个 panel,最大、最常用
3+
自定义规则用于补内置规则没有覆盖到的站点,或在本地先验证一条新规则是否可靠
44

55
## 表单填写
66

@@ -15,7 +15,7 @@
1515

1616
下方还有四个区域:
1717

18-
- **匹配范围**5 个 checkbox。决定下面的 patterns / selectors / globals 在哪些数据源做匹配
18+
- **匹配范围**:决定下面的 patterns / selectors / globals 去哪些数据源里匹配
1919
- 页面 URL:当前网页地址
2020
- 资源 URL:脚本 / 样式 / iframe 加载的资源
2121
- DOM / 源码:页面 outerHTML
@@ -33,11 +33,11 @@
3333
- **添加规则**(绿色主按钮):把当前表单存为新规则
3434
- **更新当前规则**:先在右下角列表点编辑某条规则进入"编辑模式",改完按这个保存
3535

36-
记得最后点页面右上角「保存设置」才会写入 storage。
36+
最后需要点页面右上角「保存设置」,规则才会写入 storage。
3737

3838
## 已添加规则列表
3939

40-
显示在 panel 底部,每条带:
40+
显示在页面底部,每条带:
4141

4242
- 标题:规则的技术名称
4343
- 元信息:分类 · 类型 · 置信度 · 匹配方式 · N 条 patterns
@@ -108,7 +108,7 @@
108108
匹配范围: [x] 资源 URL [x] 动态资源
109109
```
110110

111-
## 减少误报小贴士
111+
## 降低误报
112112

113113
- 别用太通用的关键词,比如 `app` `main` `login`,几乎所有网站都有
114114
- 优先写**完整域名** `pay.example.com` 而不是 `pay`

docs/config/disabled-technologies.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 禁用指定技术
22

3-
「识别开关」是按分类粒度过滤;如果你想精确屏蔽某几个具名技术(不影响整个分类),用这个 textarea
3+
「识别开关」按分类过滤;如果只想屏蔽某几个具名技术,不想关掉整个分类,用这个输入框
44

55
## 用法
66

@@ -16,7 +16,7 @@ Cloudflare
1616
保存后这些技术不会再出现在弹窗主列表里,无论它们属于哪个分类、置信度多少、来源是什么。
1717

1818
::: tip
19-
名称匹配走 `normalizeTechName(name)`:去空格、转小写、去标点。所以 `WordPress``wordpress` 等价,`Google Analytics``google-analytics` 等价。
19+
名称匹配会走 `normalizeTechName(name)`:去空格、转小写、去标点。所以 `WordPress``wordpress` 等价,`Google Analytics``google-analytics` 等价。
2020
:::
2121

2222
## 适合屏蔽的场景
@@ -31,7 +31,7 @@ Cloudflare
3131

3232
## 与原始线索的关系
3333

34-
被禁用的技术**只是不显示**,不会从 raw JSON 里被去掉。「原始线索」面板和「复制 JSON」按钮拿到的数据仍然完整,方便你随时确认有没有错杀
34+
被禁用的技术**只是不显示**,不会从 raw JSON 里删除。「原始线索」面板和「复制 JSON」按钮拿到的数据仍然完整,方便之后复核
3535

3636
## 例子
3737

docs/config/index.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
设置页可以通过弹窗顶部的「设置」按钮打开,或者在 `chrome://extensions/` 找到 StackPrism 卡片点「详情 → 扩展程序选项」。
44

5-
设置页分四个 panel
5+
设置页分五块
66

77
- [识别开关](./categories.md) — 23 个分类的启停(关掉后该分类的技术不再显示在弹窗里)
88
- [禁用指定技术](./disabled-technologies.md) — 用名字精确屏蔽某些技术(无视分类)
@@ -12,15 +12,15 @@
1212

1313
## 配置存储位置
1414

15-
所有配置存在 `chrome.storage.sync`,会随你登录的 Google / Edge 账号自动跨设备同步。Key 是 `stackPrismSettings`如果不想同步可以 disable 浏览器同步
15+
所有配置存在 `chrome.storage.sync`,会随你登录的 Google / Edge 账号跨设备同步。Key 是 `stackPrismSettings`如果不想同步,可以关闭浏览器自己的同步功能
1616

1717
`chrome.storage.sync` 的容量上限是 100KB,单个 key 不超 8KB。这意味着:
1818

1919
- 自定义规则数量有上限(约 100 条以内安全)
2020
- 自定义 CSS 长度有上限(不超 10000 字符)
2121
- 禁用列表不能太长
2222

23-
实际限制由 `src/types/settings.ts` `CUSTOM_RULE_LIMITS` 决定,超出会在保存时报错
23+
实际限制由 `src/types/settings.ts` 里的 `CUSTOM_RULE_LIMITS` 决定,超出后保存会失败并显示错误
2424

2525
## 改完什么时候生效
2626

@@ -30,4 +30,4 @@
3030
| 自定义规则 | 保存后下次刷新页面 + 重新打开弹窗 |
3131
| JSON 导入 | 同上 |
3232

33-
「保存设置」按钮按下后会立即写到 storage,不需要刷新设置页。
33+
「保存设置」后会立即写入 storage,不需要刷新设置页。

docs/config/json-export.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# 规则 JSON 导入导出
22

3-
设置页最后一个 panel。textarea 里展示当前所有自定义规则的 JSON,可以直接编辑、导入、格式化
3+
设置页最后一块会展示当前自定义规则的 JSON。适合备份、搬运和批量编辑
44

55
## 用途
66

77
- 跨设备 / 跨账号搬运自定义规则
88
- 用版本管理工具备份规则
9-
- 批量编辑(textarea 里 ctrl+F 改名比表单逐条改快
9+
- 批量编辑(在输入框里搜索替换,比表单逐条改快
1010
- 直接编程构造规则数组(脚本生成几百条规则)
1111

1212
## 字段结构
@@ -43,10 +43,10 @@
4343

4444
## 操作按钮
4545

46-
panel-head 右上角两个按钮
46+
标题栏右上角有两个按钮
4747

48-
- **从 JSON 导入**parse textarea 内容,校验通过后**整体替换**当前自定义规则列表(不是合并)
49-
- **格式化**parse 后用 `JSON.stringify(rules, null, 2)` 重新写回,缩进规整
48+
- **从 JSON 导入**解析输入框内容,校验通过后**整体替换**当前自定义规则列表(不是合并)
49+
- **格式化**解析后用 `JSON.stringify(rules, null, 2)` 重新写回,缩进规整
5050

5151
## 字符串中的反斜杠
5252

@@ -67,8 +67,8 @@ JSON parser 把 `\\` 解成单个 `\`,扩展拿到 `\.js$`,传给 `new RegEx
6767

6868
## 与表单的关系
6969

70-
- 表单里改 → 自动同步到 JSON textarea
71-
- JSON textarea 改完 → 必须点「从 JSON 导入」才会同步回内部 state
70+
- 表单里改 → 自动同步到 JSON 输入框
71+
- JSON 输入框改完 → 必须点「从 JSON 导入」才会同步回内部规则列表
7272
- 不点导入直接「保存设置」,会用最近一次表单 / 导入操作后的状态保存
7373

7474
## 数量上限

docs/dev/architecture.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ stackprism/
1616
│ │ ├─ wordpress.ts # WordPress 主题 style.css 抓取
1717
│ │ ├─ dynamic-snapshot.ts # 动态快照防抖处理
1818
│ │ ├─ tech-links.ts # tech-links.json 懒加载
19-
│ │ ├─ rule-loader.ts # 47 个规则 JSON 的合并
19+
│ │ ├─ rule-loader.ts # 规则 JSON 的加载与合并
2020
│ │ ├─ rule-matcher.ts # 编译缓存 + auto hint 预过滤
2121
│ │ ├─ detector-settings.ts # 设置 / 规则缓存
2222
│ │ ├─ content-injector.ts # 启动时给已开标签页注入 content script
@@ -49,7 +49,7 @@ stackprism/
4949
│ └─ constants.ts
5050
├─ public/
5151
│ ├─ icons/ # 16/32/48/128 PNG
52-
│ ├─ rules/ # 47 个 JSON 规则文件,3.1 MB
52+
│ ├─ rules/ # 规则 JSON 文件
5353
│ ├─ tech-links.json # 524 KB 的技术名 → 官网链接映射
5454
│ └─ injected/ # build:injected 输出的两个 IIFE
5555
├─ build-scripts/
@@ -117,7 +117,7 @@ Chrome 扩展有四种执行环境,StackPrism 全部用上:
117117

118118
## 注入脚本的双轨问题
119119

120-
`page-detector.ts` 在原生时代既被 background `importScripts` 引入又被 `executeScript({world:'MAIN', func})` 序列化注入。一旦改成 ESM `import type``Function.prototype.toString` 序列化就追不上 import。
120+
`page-detector.ts` 在原生实现里既被 background `importScripts` 引入,又被 `executeScript({world:'MAIN', func})` 序列化注入。切到 ESM `Function.prototype.toString` 不能处理 import,所以这条路走不通
121121

122122
解决方案:用 `executeScript({files})` 替代 `{func}``page-detector.ts` 独立编译为 IIFE 单文件(`vite.injected.config.ts`),通过两次 RPC 注入:
123123

@@ -140,11 +140,11 @@ chrome.scripting.executeScript({
140140
})
141141
```
142142

143-
副作用:background 不再依赖 page-detector,因此 service worker 可以正常切换到 ESM module worker`importScripts` 这条强耦合彻底消失
143+
这样处理后,background 不再直接依赖 page-detector,service worker 也可以使用 ESM module worker。
144144

145145
## 静态资源
146146

147-
`public/rules/` 47 个 JSON(3.1 MB)+ `public/tech-links.json`(524 KB)由 Vite 1:1 复制到 `dist/`,运行时通过 `chrome.runtime.getURL` + `fetch` 加载。**禁止** `import rules from '...'` ——会让 Rollup inline 进 bundle,service worker 启动慢 1-3 秒
147+
`public/rules/` `public/tech-links.json` 由 Vite 1:1 复制到 `dist/`,运行时通过 `chrome.runtime.getURL` + `fetch` 加载。不要用 `import rules from '...'` 直接导入这些大 JSON;那会让 Rollup 把规则内联进 bundle,service worker 冷启动会明显变慢
148148

149149
build 期还有两个 vite plugin 处理这些 JSON:
150150

docs/dev/contribute-rules.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
1. **快速反馈**:在弹窗对应技术卡片点「识别不准确,点击纠正」按钮,会自动打开 GitHub Issue 并填好上下文(页面 URL、当前规则匹配结果、扩展版本)。维护者收到后调整规则。
88
2. **直接 PR**:fork 仓库,编辑 `public/rules/` 下对应 JSON,本地验证后提 PR。
99

10-
后者欢迎,本节讲怎么操作
10+
下面主要讲直接 PR 的流程
1111

1212
## 找到合适的文件
1313

@@ -93,7 +93,7 @@ pnpm run build
9393

9494
或者用「自定义规则」面板先在用户配置层写一遍,确认规则有效后再搬到 `public/rules/`
9595

96-
## 减少误报小贴士
96+
## 降低误报
9797

9898
- **优先用 globals**`window.X` 命中是最稳的,几乎零误报
9999
- **优先用专属 selector**`[data-powered-by='examplecms']``[ng-version]` 这种明显由该技术写入的属性
@@ -110,4 +110,4 @@ pnpm run build
110110
4.[Wappalyzer rules](https://github.com/enthec/webappanalyzer)、官网、文档抓 2-3 条证据放在 PR 描述里
111111
5. 提 PR 到 main 分支
112112

113-
PR 格式参考已合并的:[Pull requests](https://github.com/setube/stackprism/pulls)
113+
PR 描述里至少写清楚新增了哪些技术、用什么页面验证过、为什么这些特征不会误伤其它站点

docs/dev/index.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
11
# 开发手册
22

3-
写给想看代码 / 改代码 / 贡献规则 / 给项目提 PR 的人
3+
这一部分写给准备看源码、改规则或提 PR 的人。只需要安装扩展的话,看 [使用指南](/guide/) 就够了
44

55
## 章节
66

77
- [架构概览](./architecture.md) — 项目目录结构、各模块职责、数据流
88
- [规则文件格式](./rule-format.md)`public/rules/` 下 JSON 怎么组织,nested groups + defaults 继承
99
- [检测流程](./detection-flow.md) — 从 webRequest / 页面注入到弹窗渲染走过哪些环节
1010
- [贡献规则](./contribute-rules.md) — 怎么往内置规则集合加新技术
11-
- [构建与发布](./release.md) — 本地构建、打包、签 crx、release workflow
11+
- [构建与发布](./release.md) — 本地构建、打包、签 crx、发布工作流
1212

13-
## 一句话技术栈
13+
## 技术栈概况
1414

15-
Vite 5 + Vue 3 + TypeScript + `@crxjs/vite-plugin` 2.x,Manifest V3 ESM module worker,pnpm,规则在 `public/rules/` 47 个 JSON 文件里手维护,buildtime 用 vite plugin 预编译注入 `__hints` / `__keywordCombined` 字段。
15+
项目主体是 Vite 5 + Vue 3 + TypeScript + `@crxjs/vite-plugin` 2.x。后台脚本是 Manifest V3 ESM service worker,包管理器用 pnpm。
16+
17+
规则放在 `public/rules/` 下,按页面规则、响应头规则、WordPress / Drupal 生态等方向拆成多个 JSON 文件。构建时会预处理规则,注入 `__hints` / `__keywordCombined` 这类用于匹配加速的字段。
1618

1719
## 开发常用命令
1820

@@ -26,7 +28,7 @@ pnpm run docs:dev # 起本文档站本地预览
2628
pnpm run docs:build # 构建文档静态站
2729
```
2830

29-
dev 模式下扩展是 hot reload 的——改 `src/` 内文件 → 扩展页面会自动刷新,但改 `src/background/` 后台代码需要在 `chrome://extensions/` 手动点扩展卡片上的刷新按钮
31+
dev 模式下,扩展页面支持热更新。改 popup / settings / help 通常会自动刷新;改 `src/background/` 或 content script 后,需要到 `chrome://extensions/` 手动刷新扩展卡片
3032

3133
## Vue 入口
3234

@@ -38,7 +40,7 @@ dev 模式下扩展是 hot reload 的——改 `src/` 内文件 → 扩展页面
3840
| settings | `src/ui/settings/index.html` |`chrome://extensions/` 详情页打开的 options page |
3941
| help | `src/ui/help/index.html` | 设置页里点「使用说明」打开的独立标签页 |
4042

41-
## 仓库链接
43+
## 相关链接
4244

4345
- [GitHub 仓库](https://github.com/setube/stackprism)
4446
- [Issue 列表](https://github.com/setube/stackprism/issues)

docs/dev/release.md

Lines changed: 31 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,21 +31,30 @@ pnpm run typecheck # vue-tsc --noEmit,全工程严格类型检查
3131
pnpm run lint # eslint src
3232
```
3333

34-
每次提交前会跑一遍 prettier 统一格式(见 `feedback_prettier_before_commit` memory)。
34+
提交前统一跑一遍格式化:
35+
36+
```bash
37+
npx prettier --write .
38+
```
3539

3640
## 版本号管理
3741

3842
`package.json``version` 字段是真源。`@crxjs/vite-plugin` 会自动把它同步到 `dist/manifest.json`
3943

40-
发布前需要把版本号 bump 一位 patch`feat` / `fix` / `perf` 类改动)。`feedback_bump_version` memory 里写过这条。
44+
常规功能、规则和修复改动递增 patch。patch 走到 `99` 后进入下一个 minor,不使用 `1.1.100` 这种版本号:
4145

4246
```bash
43-
# 假设当前是 1.0.90,发个 patch
44-
sed -i 's/"version": "1.0.90"/"version": "1.0.91"/' package.json
47+
# 1.1.98 -> 1.1.99
48+
# 1.1.99 -> 1.2.0
49+
```
50+
51+
只有需要发安装包的版本才创建 GitHub Release:`x.y.0``x.y.10``x.y.20`、...、`x.y.90`。例如 `1.2.0``1.2.10` 要发,`1.2.5``1.2.15` 不发。
52+
53+
```bash
54+
# 修改 package.json 版本后
4555
git add package.json
46-
git commit -m "chore: bump 1.0.91"
47-
git tag v1.0.91
48-
git push origin main --tags
56+
git commit -m "chore: bump 1.2.10"
57+
git push origin main
4958
```
5059

5160
## GitHub Release 工作流
@@ -66,6 +75,17 @@ git push origin main --tags
6675
7. `gh release upload --clobber` 把所有产物上传到 release tag
6776
8. `actions/upload-artifact` 同时备一份 artifact
6877

78+
## 发布说明
79+
80+
发布说明从上一个 release tag 到当前提交的 `git log --oneline vPREV..HEAD` 整理,不直接粘 commit 列表。写法按用户能看懂的方向归类,比如:
81+
82+
- 规则增强
83+
- 弹窗与设置页
84+
- 文档站
85+
- 构建与发布流程
86+
87+
发布说明只写用户或维护者关心的变化,不写本地跑了哪些格式化、类型检查、lint 或构建命令。
88+
6989
## CRX 签名密钥
7090

7191
第一次发布前需要生成一个 RSA 私钥,并把它配置到 GitHub repository secrets。
@@ -95,13 +115,15 @@ openssl genrsa -out extension.pem 2048
95115

96116
## 发布检查清单
97117

118+
- [ ] `npx prettier --write .` 已执行
98119
- [ ] `pnpm run typecheck` 通过
99120
- [ ] `pnpm run lint` 通过
100121
- [ ] `pnpm run build` 通过
101122
- [ ] 在 chrome 里加载 `dist/` 手动测试关键路径(弹窗打开、识别一个站点、刷新、复制 JSON、设置页加规则)
102123
- [ ]`package.json` 的 version bump
103-
- [ ] git commit + push + 在 GitHub UI 发布 release(tag 为 `v{version}`,与 package.json 对齐)
104-
- [ ] 等 workflow 跑完,确认 release 资产里有 zip + crx + 两个 sha256
124+
- [ ] git commit + push
125+
- [ ] 如果版本符合 release 节点,在 GitHub UI 发布 release(tag 为 `v{version}`,与 package.json 对齐)
126+
- [ ] 等发布工作流跑完,确认 release 资产里有 zip / crx 与 sha256
105127

106128
## 发布到 Chrome Web Store
107129

0 commit comments

Comments
 (0)