13 / 90

學習日 13：文字與資料學習專案

將現有的 text_tools 專案變成一條可重現的語料到產物管線。

自主學習與 Python 480 分鐘（8 小時專注學習）
01 120 分鐘

建構 CLI 核心

只有在記錄預測之後才允許代理協助；必須檢查並測試每一處產生的差異。

先決條件

第 01–12 天：字串、字典、檔案、例外、測試與終端機使用。

學習目標

實作或檢查 projects/text_tools/core.py 與 cli.py，涵蓋統計、決定性分割、出處清單（manifest）以及明確的編碼錯誤。

操作說明

必做：先建立本練習專用的私有工作區（WORKDIR=$(mktemp -d)），把小型語料寫入 $WORKDIR/corpus.txt，記錄預測，然後執行完整呼叫 python3 projects/text_tools/cli.py --input "$WORKDIR/corpus.txt" --stats --json --split --output-dir "$WORKDIR/artifacts"；檢查差異，並逐一練習 --input、--stats、--split、--output-dir、--seed、--encoding 和 --errors。選做：比較 Python 文件連結。

練習與預測

使用一個包含重複詞元、中日韓文字、帶重音字元和一個表情符號的小型語料庫。先預測字元數/詞元數，然後驗證 stats.json 和 manifest.json——包括 source_sha256 與原始輸入位元組的 SHA256（如 sha256sum "$WORKDIR/corpus.txt"）一致，且 input_decoding 記錄了編碼、錯誤處理與換行策略。

Learning Project Submission & Evidence

0 / 4096 位元組
Declared Assistance Condition

Current Submitted Evidence Details

No submission recorded yet.
獨立掌握標準

學習者能夠講解並執行真實的 text_tools CLI，記錄預測與證據，且不會把代理寫出的差異當作獨立理解的證明。

來源資源與出處

linking PSF License Version 2

Python Standard Library: Built-in Types

作者 / 機構: Python Software Foundation | 原始出處連結 ↗

對應章節 / 時間戳: str methods and Unicode semantics used by analyze_text (split, join, isalpha, isdigit)

驗證版本與日期: Python 3.12 documentation; verified 2026-10-30

入選理由:

Primary reference for the string methods and Unicode semantics behind corpus statistics.

來源前置條件:

Study Days 01–12 Python fundamentals

安全回退方案（離線彈性）:

The lesson explains all required behavior locally and the reference implementation ships in the repository; pydoc mirrors the same documentation offline.

對比候選資源與選型分析 (2)
GNU coreutils wc/split ↗ compared_rejected_for_day13 [GPL-3.0-or-later]

Powerful system tools, but the learning target is implementing and testing the behavior in Python, not delegating to platform-specific utilities.

Python HOWTO: Unicode ↗ compared_alternative [PSF License Version 2]

Deeper Unicode background for the encoding edge cases; str method reference remains the primary doc.

linking PSF License Version 2

argparse — Parser for command-line options, arguments and subcommands

作者 / 機構: Python Software Foundation | 原始出處連結 ↗

對應章節 / 時間戳: add_argument flags, choices, and type conversion used by cli.py

驗證版本與日期: Python 3.12 documentation; verified 2026-10-30

入選理由:

Primary reference for the CLI flags the learner exercises on the real project.

來源前置條件:

Study Days 01–12 Python fundamentals

安全回退方案（離線彈性）:

argparse is part of the standard library; python3 -c "import argparse; help(argparse)" works fully offline.

對比候選資源與選型分析 (2)
Click package documentation ↗ compared_rejected_for_day13 [BSD-3-Clause]

Strong third-party CLI framework, but the project intentionally uses only the standard library so the exercise needs no extra dependency.

docopt ↗ compared_rejected_for_day13 [MIT]

Usage-string DSL for CLIs, but an external dependency is unjustified when argparse covers the project.

02 120 分鐘

獨立實作核心

獨立掌握檢查：不允許 AI、抄寫答案或代理產生的程式碼。

先決條件

完成第 13 天活動 1，並關閉所有參考分頁。

學習目標

在無 AI 協助的情況下，按照真實專案介面實作一個有邊界的統計或分割函式。

操作說明

必做：獨立實作且只實作一個被評估介面並聲明所選——analyze_text(text) -> dict（統計）或 compute_splits(lines, train_ratio, val_ratio, test_ratio, seed) -> dict（分割）；然後在一個「你事先預測結果的、不同的新無協助輸入」上測試。選做：提交後再與參考對照。正典示例輸出是公開參考，絕非隱藏評估。

練習與預測

選擇一個被評估介面並聲明。路線 A analyze_text(text) -> dict：預測輸入 'a a\n猫🙂' 的完整結果——鍵為 total_chars、total_tokens、vocab_size、char_vocab_size、token_frequencies、char_frequencies、min_token_length、max_token_length、avg_token_length、char_distribution。路線 B compute_splits(lines, train_ratio, val_ratio, test_ratio, seed) -> dict：對 ['a','b','c','d','e']、種子 7、比例 .6/.2/.2，預測計數並證明索引集合兩兩不相交。並說明所選路線依賴的區分規則（B：相同文本值仍需索引級檢查；A：相同文本值不會虛增詞表）。

獨立掌握標準

獨立程式碼在不同的新無協助輸入上通過保留行為檢查，書面解釋能區分索引洩漏、重複記錄、token/字元計數與評估侷限。

來源資源與出處

original_explanation Apache-2.0 AND CC-BY-SA-4.0 share-alike

Text and Data Tools Learning Project

作者 / 機構: Curriculum team (delivered in Ticket 16) | 原始出處連結 ↗

對應章節 / 時間戳: projects/text_tools/core.py: analyze_text and compute_splits interfaces

驗證版本與日期: Verified against the checked-in implementation on 2026-10-30

入選理由:

The actual project whose interfaces the learner re-implements independently, keeping the exercise tied to real artifacts.

來源前置條件:

Study Days 01–12 Python fundamentals

安全回退方案（離線彈性）:

The implementation and its project manifest are committed in the repository and work offline.

對比候選資源與選型分析 (2)
External toy CLI tutorials ↗ compared_rejected_for_day13 [PSF License Version 2]

Generic tutorials duplicate earlier days and disconnect the exercise from the deterministic data artifacts later experiments reuse.

CPython Lib/string.py reference implementation ↗ compared_alternative [PSF License Version 2]

Production string-tooling internals are instructive but heavier than the project's focused interfaces.

03 120 分鐘

保留行為檢查與除錯

代理協助的工程檢查：指揮代理、檢查差異，然後親自執行保留檢查。

先決條件

已有獨立實作的函式，以及一個乾淨的暫時輸出目錄。

學習目標

在不改動課程儲存庫的前提下診斷真實故障：輸入缺失、UTF-8 損毀、空輸入、非法比例以及非決定性排序。

操作說明

必做：在程序隔離的暫時目錄中執行每個除錯案例，記錄結束狀態和標準錯誤，並用保留資料重新產生產物。選做：讓代理提出測試建議，然後拒絕不安全或同義反覆的測試。

練習與預測

保留行為檢查使用空檔案、損毀位元組、多語言行和相同種子連跑兩次。預測哪些呼叫會成功、哪些會失敗、哪些產物位元組必須一致。

Learning Project Submission & Evidence

0 / 4096 位元組
Declared Assistance Condition

Current Submitted Evidence Details

No submission recorded yet.
獨立掌握標準

證據包含命令、結束碼、觀察到的輸出，以及至少三個案例的診斷和修復說明；不把子程序通過等同於掌握。

來源資源與出處

original_explanation Apache-2.0 AND CC-BY-SA-4.0 share-alike

Text and Data Tools Learning Project

作者 / 機構: Curriculum team (delivered in Ticket 16) | 原始出處連結 ↗

對應章節 / 時間戳: cli.py error paths: missing input, strict decoding, --output-dir requirement, ratio validation

驗證版本與日期: Verified against the checked-in implementation on 2026-10-30

入選理由:

Held-out debugging must target the real CLI seams and exit codes, not a simplified re-implementation.

來源前置條件:

Study Days 01–12 Python fundamentals

安全回退方案（離線彈性）:

All debugging cases run on a temporary corpus in a disposable directory with no external services.

對比候選資源與選型分析 (2)
External debugging courses ↗ compared_alternative [PSF License Version 2]

pdb documentation is a useful secondary reference, but the held-out cases exercise CLI behavior end to end.

pytest documentation ↗ compared_alternative [MIT]

Natural next step to formalize the held-out cases; the activity first exercises the CLI seams directly.

04 120 分鐘

專案報告：假設與侷限

獨立掌握檢查：先提交並封存未受協助的報告；之後的 AI 文字潤飾是單獨標記、不計評估的產物，絕不替代獨立證據。

先決條件

完成前面三個活動並保留其證據。

學習目標

撰寫一份簡短報告，把決定性資料準備與後續分詞器和模型實驗連結起來，同時說明假設與侷限。

操作說明

必做：先撰寫並封存（提交、註明日期）無協助的報告——涵蓋來源歸屬、編碼、詞元定義、分割比例/種子、洩漏策略、觀測到的測量值、可重現性和侷限。之後的協助潤飾是單獨標記的產物，不替代已封存版本；若協助暴露出實質缺漏，必須先做一次新的無協助檢查方可計入掌握。選做：在不改動本專案的情況下提出一個後續分詞器實驗。

練習與預測

解釋為什麼固定的訓練/驗證/測試產物可以被 Makemore、minbpe 和 NanoGPT 重複使用，以及為什麼固定分割並不能證明模型泛化。

獨立掌握標準

報告完整，引用真實的專案產物，列出至少三條假設和三條侷限，並能區分已封存的無協助草稿與單獨標記的協助潤飾稿。

來源資源與出處

original_explanation Apache-2.0 AND CC-BY-SA-4.0 share-alike

Text and Data Tools Learning Project

作者 / 機構: Curriculum team (delivered in Ticket 16) | 原始出處連結 ↗

對應章節 / 時間戳: manifest.json fields: source_sha256, split ratios/counts/hashes, leakage_check, environment, created_at

驗證版本與日期: Verified against the checked-in implementation on 2026-10-30

入選理由:

The report must cite the real manifest and artifacts the learner generated, preserving attribution to the project.

來源前置條件:

Study Days 01–12 Python fundamentals

安全回退方案（離線彈性）:

Report evidence consists of local artifacts and command output captured in earlier activities.

對比候選資源與選型分析 (2)
Google Technical Writing One ↗ compared_alternative [CC BY 4.0 (course content)]

Solid general technical-writing training, but the report rubric here is specific to the project's manifest fields and provenance.

Write the Docs: Beginner's guide to documentation ↗ compared_alternative [CC BY-NC-SA 4.0]

General documentation guidance; the report rubric remains bound to this project's manifest fields.