Skip to content

Commit 1d88fa4

Browse files
CongregalisCongregalis
committed
feat: finish P0-01 and P0-02 pipeline upgrades
1 parent 891d743 commit 1d88fa4

7 files changed

Lines changed: 1139 additions & 101 deletions

File tree

‎NEXTSTEP.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# TransBlog's Next Step
2+
3+
> 用法：每完成一项就把 `[ ]` 改成 `[x]`，并在「完成日期」后写日期（YYYY-MM-DD）。
4+
5+
---
6+
7+
## 0) 验收线
8+
9+
- [ ] **验收-A：稳定性**
10+
- 要求：20 篇真实 URL（技术博客、文档站、社区帖混合）端到端成功率 >= 90%
11+
- 完成日期：
12+
- [ ] **验收-B：结构保真**
13+
- 要求：人工抽检 20 篇，标题/列表/链接/代码块保真率 >= 95%
14+
- 完成日期：
15+
- [ ] **验收-C：失败隔离**
16+
- 要求：单个 URL 或单个 chunk 失败不会导致全任务失败，能输出成功部分
17+
- 完成日期：
18+
- [ ] **验收-D：可发布**
19+
- 要求：支持 `--version`，有可安装发布包（至少 macOS + Linux）
20+
- 完成日期：
21+
- [ ] **验收-E：质量保障**
22+
- 要求：核心链路（fetch/markdown/openai/cli）有测试且 CI 稳定通过
23+
- 完成日期：
24+
25+
---
26+
27+
## 1) P0（必须完成，决定能不能“正式宣发”）
28+
29+
### P0-01 正文提取（降噪）
30+
- [x] 完成
31+
- 目标：避免导航栏、页脚、评论区被翻译，提升译文质量。
32+
- 具体要做：
33+
1. 在 `internal/fetch/fetch.go` 引入正文提取（推荐 `github.com/go-shiori/go-readability`）。
34+
2. 提取失败时自动回退到原始 HTML（不能直接报错中断）。
35+
3. 保留页面标题与最终 URL（后续写入输出元数据）。
36+
- 完成标准：
37+
- 同一 URL 的输入 markdown 噪音显著减少（导航/页脚明显变少）。
38+
- 不因为正文提取失败而终止流程。
39+
- 自测命令：
40+
- `go test ./...`
41+
- 用 3 个站点手测（博客/文档/社区）比对前后输出。
42+
- 完成日期：2026-02-24
43+
44+
### P0-02 多 URL 输出行为明确
45+
- [x] 完成
46+
- 目标：多链接输入时行为稳定、可预测、可复查。
47+
- 具体要做：
48+
1. 在 `internal/cli/run.go` 实现：多 URL 默认「每个 URL 输出一个文件」。
49+
2. 生成任务汇总文件（建议：`out/_summary.json`），记录每个 URL 成功/失败、耗时、输出路径。
50+
3. 终端打印简明汇总（成功数、失败数、总耗时）。
51+
- 完成标准：
52+
- 输入 5 个 URL 时得到 5 个结果文件 + 1 个 summary。
53+
- 某个 URL 失败时其他 URL 仍继续执行。
54+
- 自测命令：
55+
- `./transblog <url1> <url2> <url3>`
56+
- 完成日期：2026-02-24
57+
58+
### P0-03 失败隔离与错误分级
59+
- [ ] 完成
60+
- 目标：失败可定位、可重试、不可拖垮全局。
61+
- 具体要做：
62+
1. 区分错误类型：抓取失败 / 转换失败 / 翻译失败 / 输出失败。
63+
2. 每个 URL 维护独立状态，不因单点失败 `return` 全局失败。
64+
3. 在 summary 中输出 `error_type` 和 `error_message`。
65+
- 完成标准：
66+
- 构造一个坏链接，任务仍能产出其他链接结果。
67+
- summary 能一眼看出失败发生在哪一步。
68+
- 自测命令：
69+
- 混合输入正常 URL + 404 URL + 超时 URL。
70+
- 完成日期：
71+
72+
### P0-04 断点续跑（Resume）
73+
- [ ] 完成
74+
- 目标：中断后可续跑，避免重复翻译消耗成本。
75+
- 具体要做：
76+
1. 新增 `--resume` 开关。
77+
2. 在输出目录写状态文件（建议：`.transblog.state.json`），记录已完成 URL/chunk。
78+
3. 续跑时跳过已完成 chunk，仅补跑未完成部分。
79+
- 完成标准：
80+
- 人为中断后再次执行 `--resume`，可从中断点继续。
81+
- 最终产物与一次性跑完结果一致（内容顺序一致）。
82+
- 自测命令：
83+
- 运行中 `Ctrl+C`，然后 `--resume` 继续。
84+
- 完成日期：
85+
86+
### P0-05 并发与重试参数化
87+
- [ ] 完成
88+
- 目标：给用户可控的性能/稳定性开关。
89+
- 具体要做：
90+
1. 新增 flags：`--workers`、`--max-retries`、`--fail-fast`。
91+
2. 将现有固定并发（4）和固定重试（5）改为可配置并有默认值。
92+
3. 参数非法时给清晰报错（如 `--workers<=0`）。
93+
- 完成标准：
94+
- 参数变化会影响执行策略。
95+
- `--fail-fast=false` 时允许部分成功。
96+
- 自测命令：
97+
- `./transblog --workers 1 --max-retries 2 ...`
98+
- `./transblog --workers 8 --max-retries 6 ...`
99+
- 完成日期：
100+
101+
### P0-06 翻译质量兜底校验
102+
- [ ] 完成
103+
- 目标：降低“空输出/结构损坏”风险。
104+
- 具体要做：
105+
1. 翻译后做结构检查：非空、代码 fence 数量平衡、基本 markdown 结构未塌。
106+
2. 检查不通过时自动重试（可带更严格提示词）。
107+
3. 将兜底触发次数写入 summary（便于后续优化）。
108+
- 完成标准：
109+
- 空翻译或明显破损 markdown 能被拦截并重试。
110+
- 失败原因可追踪。
111+
- 自测命令：
112+
- 构造异常响应（mock OpenAI）验证兜底分支。
113+
- 完成日期：
114+
115+
### P0-07 成本与用量可见
116+
- [ ] 完成
117+
- 目标：让用户知道 token 消耗和成本。
118+
- 具体要做：
119+
1. 在 `internal/openai/responses.go` 解析 `usage` 字段（input/output/total tokens）。
120+
2. 按 URL、按总任务汇总 token。
121+
3. 支持可选价格配置（例如按模型设定每 1M token 单价）并输出估算成本。
122+
- 完成标准：
123+
- 终端与 summary 都能看到 token 和预估成本。
124+
- 缺失 usage 时不崩溃，有降级提示。
125+
- 自测命令：
126+
- mock 两类响应：有 usage / 无 usage。
127+
- 完成日期：
128+
129+
### P0-08 单元测试补齐（核心链路）
130+
- [ ] 完成
131+
- 目标：避免“能跑但不稳”。
132+
- 具体要做：
133+
1. `internal/fetch`：`httptest.Server` 覆盖 200/404/超时/非 html。
134+
2. `internal/markdown`：覆盖 mermaid 包裹、fence 边界、空内容。
135+
3. `internal/openai`：覆盖错误解析、重试逻辑、输出提取。
136+
4. `internal/cli`：覆盖参数解析与多 URL 行为。
137+
- 完成标准：
138+
- 新增测试后 `go test ./...` 稳定通过。
139+
- 核心包都有非 0 覆盖率。
140+
- 自测命令：
141+
- `go test -cover ./...`
142+
- 完成日期：
143+
144+
### P0-09 集成测试（E2E）
145+
- [ ] 完成
146+
- 目标：验证真实流程而不是只测函数。
147+
- 具体要做：
148+
1. 增加 e2e 用例：单 URL 成功。
149+
2. 增加 e2e 用例：多 URL + 部分失败。
150+
3. 增加 e2e 用例：中断后 resume。
151+
4. 用 mock HTTP + mock OpenAI 服务，保证 CI 可重复。
152+
- 完成标准：
153+
- 至少 3 条 e2e 在本地和 CI 都稳定通过。
154+
- 自测命令：
155+
- `go test ./...`（包含 e2e）
156+
- 完成日期：
157+
158+
### P0-10 CI 升级（质量门禁）
159+
- [ ] 完成
160+
- 目标：每次提交自动挡住回归。
161+
- 具体要做：
162+
1. 在 `.github/workflows/ci.yml` 增加覆盖率检查（可先定总覆盖率阈值，例如 >= 45%）。
163+
2. 加入集成测试步骤。
164+
3. 保留并继续执行 gofmt/go vet/go test/go build。
165+
- 完成标准：
166+
- CI 能对低覆盖率或 e2e 失败直接红灯。
167+
- main 分支持续绿灯。
168+
- 自测命令：
169+
- 本地先跑：`gofmt -w . && go vet ./... && go test ./... && go build ./cmd/transblog`
170+
- 完成日期：
171+
172+
### P0-11 版本信息与发布打包
173+
- [ ] 完成
174+
- 目标：让用户拿到“可识别版本”的正式包。
175+
- 具体要做：
176+
1. 增加 `--version` 输出（version/commit/build time）。
177+
2. 补充 Release 构建流程（建议 GoReleaser，至少支持 macOS + Linux）。
178+
3. 在 `CHANGELOG.md` 维护版本条目。
179+
- 完成标准：
180+
- `transblog --version` 输出完整信息。
181+
- 能生成并上传二进制发布资产。
182+
- 自测命令：
183+
- `./transblog --version`
184+
- 本地 dry-run 发布流程（若使用 GoReleaser）。
185+
- 完成日期：
186+
187+
### P0-12 文档与上手体验
188+
- [ ] 完成
189+
- 目标：首次用户 5 分钟内跑通。
190+
- 具体要做：
191+
1. 更新 `README.md`：安装、最小示例、常见错误、成本说明、批量示例。
192+
2. 增加 `docs/troubleshooting.md`（超时/429/解析失败/输出异常）。
193+
3. 增加 `docs/release-checklist.md`（发版前检查清单）。
194+
- 完成标准：
195+
- 新用户按 README 一次跑通。
196+
- 常见报错都有对应排查路径。
197+
- 自测命令：
198+
- 用全新目录按 README 从零执行一次。
199+
- 完成日期：
200+
201+
---
202+
203+
## 2) P1（加分项，至少完成 3 项）
204+
205+
### P1-01 缓存层（省钱提速）
206+
- [ ] 完成
207+
- 目标：避免重复抓取/翻译同一内容。
208+
- 具体要做：实现 URL+配置哈希缓存，支持 `--refresh` 强制刷新。
209+
- 完成标准：二次运行明显更快且少请求。
210+
- 完成日期：
211+
212+
### P1-02 批量输入文件
213+
- [ ] 完成
214+
- 目标：支持运营批处理。
215+
- 具体要做：新增 `--from-file urls.txt`，支持注释行和空行跳过。
216+
- 完成标准：可混合命令行 URL 与文件 URL（并去重）。
217+
- 完成日期：
218+
219+
### P1-03 输出元数据增强
220+
- [ ] 完成
221+
- 目标：方便后续检索与追踪。
222+
- 具体要做：front matter 增加 `title/lang/chunk_count/duration/token_usage`。
223+
- 完成标准：每个输出文件都能看到完整元数据。
224+
- 完成日期：
225+
226+
### P1-04 HTML 阅读页增强
227+
- [ ] 完成
228+
- 目标：提高阅读体验，利于宣发演示。
229+
- 具体要做：增加搜索、字体大小调节、复制代码按钮、锚点深链接。
230+
- 完成标准：移动端与桌面端都可用，无明显布局错位。
231+
- 完成日期：
232+
233+
### P1-05 分发渠道完善
234+
- [ ] 完成
235+
- 目标：降低安装门槛。
236+
- 具体要做：提供 Homebrew 安装方式（或等价的一键安装脚本）。
237+
- 完成标准：用户可通过 1 条命令安装并运行。
238+
- 完成日期：
239+
240+
---
241+
242+
## 3) 宣发前最终检查（Release Gate）
243+
244+
- [ ] 运行 20 篇样本基准并保存结果（成功率、耗时、token、失败类型）
245+
- [ ] 修复所有 P0 阻塞问题（P0 未完成不得发 v1.0.0）
246+
- [ ] 准备宣发素材：30 秒演示 GIF + 3 组前后对比案例
247+
- [ ] 发布 `v1.0.0`，并在 `CHANGELOG.md` 写清核心能力和已知限制
248+
- [ ] 宣发口径统一为“稳定可用版”，不要承诺未完成特性
249+
250+
---
251+
252+
## 4) 执行节奏建议（避免跑偏）
253+
254+
- Week 1：P0-01 ~ P0-04（先做稳定性和输入质量）
255+
- Week 2：P0-05 ~ P0-09（参数化 + 测试 + CI）
256+
- Week 3：P0-10 ~ P0-12 + 至少 3 个 P1（发布与体验）
257+
258+
**规则：**
259+
- 每完成 1 个 P0，就跑一次 `go test ./...` 和一次真实 URL 手测。
260+
- 不允许跳过测试直接堆功能。
261+
- 若新增功能导致成功率下降，立即回退到上一个可用状态再修。

‎go.mod‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,18 @@ module transblog
22

33
go 1.24.0
44

5-
require github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0
5+
require (
6+
github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0
7+
github.com/go-shiori/go-readability v0.0.0-20251205110129-5db1dc9836f0
8+
github.com/joho/godotenv v1.5.1
9+
golang.org/x/net v0.47.0
10+
)
611

712
require (
813
github.com/JohannesKaufmann/dom v0.2.0 // indirect
9-
github.com/joho/godotenv v1.5.1 // indirect
10-
golang.org/x/net v0.47.0 // indirect
14+
github.com/andybalholm/cascadia v1.3.3 // indirect
15+
github.com/araddon/dateparse v0.0.0-20210429162001-6b43995a97de // indirect
16+
github.com/go-shiori/dom v0.0.0-20230515143342-73569d674e1c // indirect
17+
github.com/gogs/chardet v0.0.0-20211120154057-b7413eaefb8f // indirect
18+
golang.org/x/text v0.31.0 // indirect
1119
)

0 commit comments

Comments
 (0)