clip2table 0.1.0__tar.gz

clip2table-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# 变更记录
+
+格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.1.0] — 2026-10-23
+
+首个可用版本。四条里程碑加两轮共 16 项整改，每条都有可复核的验收记录，
+不在这里自述（见 [docs/verification.md](docs/verification.md)）。
+
+### 新增
+
+- **三条取数通道**：`http` 直连 / `browser` CDP 发真按键 / `desktop` Win32 `SendInput`。
+  不指定时自动降级，报告首行永远写清楚这次走了哪条、判定依据是什么。
+- **零配置结构反推** `infer`：S0 表格 / S1 周期 / S2 键值 / S3 编号 / S4 原文兜底。
+  有歧义时说出来，不硬猜。
+- **站点卡（TOML）**：通道、翻页、切分规则、字段定义、去重键全部声明在卡里。
+  加一个站点 = 加一个文件，代码一行不动。
+- **数据集**：以「页」为提交单位（先写临时页目录再发布为不可变页）、断点续采、
+  页级去重、冲突四分类审计、卡指纹绑定（同一份数据不允许被两套规则混着写）。
+- **导出**：CSV / Markdown / JSONL / XLSX。无损模式——超出单元格上限的值旁挂
+  `.full.jsonl`，字段名里的 `|` 自动转义，被改动的单元格逐条记账。
+- **字段溯源**：每个值都记着类型、来源（行号 / 正则捕获组 / 单元格）和失败原因。
+- **5 张内置卡**，各带逐字节回归样本，`clip2table test <卡名>` 可自证。
+- `clip2table doctor` 自检（剪贴板 / 卡目录 / 浏览器调试端口），
+  `clip2table selftest` 把文档里出现的命令和真实参数表对账；找不到任何文档时
+  它报错退出，而不是给一个「跳过」的绿。
+
+### 保证
+
+这三条是这个项目的定义，不是宣传语——它们各有一组测试盯着：
+
+- **行数守恒**：记录数 + 未识别行数 = 源行数。切不动的行进 `_unparsed`，不丢。
+- **不补值**：表里没有的就是空。空缺率本身是信息，填平了就再也看不出来。
+- **导出不改内容**：任何被截断或转义的单元格都写进旁挂文件，不静默动手。
+
+### 已知限制
+
+- **仅 Windows**。通道 C 依赖 Win32 API，通道 B 的焦点归还依赖窗口句柄。
+- **通道 B 在浏览器被最小化时要短暂借用前台**，采完把焦点还给原来的窗口。
+  窗口只是被盖住时不动你的前台。三种情形各有实测记录。
+- **纯文本切分是启发式的**。页面结构变了就会切错——所以有行形状校验、独立答案键
+  回归、逐页偏离标记，而不是靠「看起来对」。
+
+[0.1.0]: https://github.com/yjq123-zyh/clip2table/releases/tag/v0.1.0

clip2table-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 clip2table contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clip2table-0.1.0/MANIFEST.in

@@ -0,0 +1,22 @@
+# sdist 里要有足够跑测试的东西，否则「下载源码包」这条路是死的。
+# 之前只有 src/ 和 tests/ 进了 sdist，fixtures/ 没进——单测一跑就红在找不到夹具，
+# 下载 sdist 的人会以为代码坏了。wheel 是给用户的，sdist 是给改代码的人的，
+# 两者要的内容不一样，得分开说。
+
+include LICENSE
+include NOTICE.md
+include README.md
+include SKILL.md
+include CHANGELOG.md
+include pyproject.toml
+
+# 单测直接读 fixtures/，缺了它 472 项里有一批跑不起来
+recursive-include fixtures *
+recursive-include tests *
+
+# selftest 要拿这几份文档跟真实参数表对账；装好的 wheel 没有它们（那时它会报错），
+# sdist 里有，所以从 sdist 跑 selftest 是绿的、从 wheel 跑是非 0 的，两者都对
+recursive-include docs *.md
+
+# 不装包也能跑的子命令启动器，CI 和文档都用它
+include _dev/c2t.py

clip2table-0.1.0/NOTICE.md

@@ -0,0 +1,114 @@
+# 使用须知与权利说明
+
+本文件说明本项目的著作权归属、授权范围、禁止性规定、免责声明、协议终止与争议解决。
+
+**软件许可的正式条款以 [LICENSE](LICENSE)（MIT）为准。** 本文件与其在授权范围或
+条件上不一致时，以 MIT 许可证为准；涉及强制性法律规定的，依法律规定处理。
+
+---
+
+## 一、著作权归属
+
+1. 本项目中受著作权保护的代码、文档及其他原创内容，其著作权由相应作者或其他合法权利人
+   依法享有。具体归属以文件声明、有效协议及相关权利证明为依据。
+2. 除另有有效约定外，贡献者提交代码或文档不构成著作权转让；项目维护者不因接收贡献而
+   取得全部贡献内容的著作权。
+3. 用户对本项目进行修改、扩展或二次开发，可以依法享有其新增原创内容的相应权利，但不得
+   据此否认原有内容的权利归属。
+4. 用户使用本项目处理的数据，其权利归属不因经过本项目采集、解析或导出而改变。项目作者
+   及贡献者不因提供工具而取得用户数据的所有权或使用许可。
+
+上述权利归属原则依据著作权法律规则确定，参见《中华人民共和国著作权法》。
+
+> 与工具行为对应的一句实话：本项目在你自己的机器上运行，不含遥测、不上传数据、不建立
+> 任何回传通道。走 `http` 通道时它会按卡里声明的地址发起请求，走 `browser` / `desktop`
+> 通道时它驱动的是你自己的浏览器和你自己的窗口——没有第三方能从我们这里拿到你的数据，
+> 因为我们本来就拿不到。
+
+---
+
+## 二、授权范围
+
+1. 在遵守 MIT 许可证条件的前提下，任何获得本项目副本的人，均可免费使用、复制、修改、
+   合并、发布、分发、再许可及销售软件副本。
+2. 授权包括个人使用、学习研究、企业内部使用、商业使用和二次开发。MIT 许可证不要求用户
+   公开其自行开发的全部源代码。
+3. 分发软件副本或包含本项目实质性内容的作品时，应按照 MIT 许可证保留相应著作权声明及
+   许可声明。
+4. 本项目的软件许可**不包含**对第三方网站、账户、数据、商标及其他独立权利的授权。能够
+   浏览或复制某项内容，不等于已经取得任意批量采集、公开传播或商业利用该内容的权利。
+
+软件授权的具体条件以项目所附 [MIT 许可证](LICENSE) 为准。
+
+---
+
+## 三、禁止性规定
+
+使用者不得实施以下行为：
+
+1. 在依法应当保留声明的再分发情形下，删除必要的著作权声明和许可声明。
+2. 伪造作者身份、冒认他人作品，或以欺骗方式宣称修改版、衍生产品获得项目作者的官方认可
+   或背书。
+3. 利用本项目实施非法访问、窃取账户凭据、侵犯个人信息权益、侵犯商业秘密或其他违法行为。
+4. 在缺乏合法依据的情况下，获取、使用、披露或传播受法律保护的数据和内容。
+5. 以本项目名义虚构授权、服务承诺或保证，并将相关责任归于未作出该承诺的作者、贡献者或
+   维护者。
+
+上述规定涉及许可证履行及独立的法定义务，**不构成对 MIT 许可证新增的商业用途或行业限制**。
+
+---
+
+## 四、免责声明
+
+1. 本项目按照 MIT 许可证以现状提供。在适用法律允许的范围内，作者及贡献者不提供关于
+   适销性、特定用途适用性或不侵权的明示或默示保证。
+2. 本项目的结构推断、字段提取、分页采集和格式转换可能受到源内容变化、浏览器行为、窗口
+   状态及用户配置的影响。输出结果、质量提示和溯源信息不构成对数据准确性、完整性或业务
+   适用性的保证。
+3. 用户应根据实际用途决定是否复核结果、保留原始数据和进行备份，并对其采集范围、数据
+   使用方式及据此作出的业务决定负责。
+4. 在适用法律允许的范围内，作者及贡献者依 MIT 许可证享有相应责任限制；本说明不排除依法
+   不得免除的责任。
+5. 任何免责约定均不得排除依法应承担的人身损害责任，或因故意、重大过失造成对方财产损失
+   的责任。
+
+免责及责任限制须受强制性法律规定约束，参见《中华人民共和国民法典》第五百零六条。
+
+---
+
+## 五、协议终止与违约处理
+
+1. 用户可以随时停止使用本项目。停止使用不影响此前已发生行为的法律责任。
+2. 对不符合 MIT 许可证条件、且不存在其他合法依据的复制或分发行为，权利人可以依法要求
+   停止侵权、补正声明并承担相应责任。
+3. 是否发生授权终止、终止的范围以及补正后的法律效果，依许可证条件和适用法律确定。本说明
+   不另行设置维护者可以任意撤销既有 MIT 授权的权利。
+4. 项目停止维护、仓库关闭或后续版本变更许可，不因该事实本身撤销用户对既有版本已经合法
+   取得的授权。
+5. 任何终止或违约处理，不影响第三方依据有效许可独立取得的权利，也不影响依法继续有效的
+   责任及争议解决约定。
+
+---
+
+## 六、法律适用与争议解决
+
+1. 对于有关双方另行依法达成、并明确纳入本说明的协议，双方可以约定适用中华人民共和国
+   大陆地区法律；依法必须适用的其他强制性规定不受影响。
+2. 未形成有效法律选择约定的，适用法律按照有关法律规则确定，不因本说明单方发布而当然确定。
+3. 因本项目授权、使用或权利归属发生争议，当事人可以协商解决；协商不成的，依法向有管辖权
+   的人民法院提起诉讼。
+4. 本说明部分条款被认定无效或不能执行的，其他可独立适用条款的效力依法律规定确定。
+5. 本说明与 MIT 许可证在软件授权范围或条件上存在不一致时，以 MIT 许可证为准；涉及强制性
+   法律规定的，依法律规定处理。
+
+---
+
+## 需要说明的三点
+
+- **这不是法律意见。** 本文件是本项目对其权利与责任的说明，不是律师出具的法律意见书，也
+  不构成对任何具体使用场景的合规结论。
+- **第六条若要作为双方合同约定使用**，建议由律师结合权利人所在地及协议订立方式确认后再定稿——
+  单方发布的权利说明本身通常不足以在当事人之间成立一份有效选法约定。
+- **能不能用，取决于你怎么用。** 工具只把你屏幕上已经能看到、有权限看到的内容变成表；这份
+  说明约束的是工具的分发与使用方式，不改变你对自己采集内容所负的责任。第三条已经把话说
+  清楚，这里不再重复免责。

clip2table-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: clip2table
+Version: 0.1.0
+Summary: 把屏幕上看得到、选得中的任何内容，变成一张结构化表
+Author-email: kdy <yangdurant978@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yjq123-zyh/clip2table
+Project-URL: Repository, https://github.com/yjq123-zyh/clip2table
+Project-URL: Documentation, https://github.com/yjq123-zyh/clip2table/blob/main/docs/usage.md
+Project-URL: Issues, https://github.com/yjq123-zyh/clip2table/issues
+Project-URL: Changelog, https://github.com/yjq123-zyh/clip2table/blob/main/CHANGELOG.md
+Keywords: clipboard,scraping,table,windows,cdp,csv,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# clip2table
+
+**把屏幕上看得到、选得中的任何内容，变成一张结构化表。**
+
+[![tests](https://github.com/yjq123-zyh/clip2table/actions/workflows/tests.yml/badge.svg)](https://github.com/yjq123-zyh/clip2table/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)](#环境要求)
+
+不是爬虫。爬虫要假装自己是浏览器、绕过指纹、维护代理池，然后在你和站点之间
+永远打一场你赢不了的军备竞赛。clip2table 换了个思路：**让真浏览器、真程序自己去复制**，
+它只负责把复制出来的文本切成表。
+
+所以它对你自己的登录态、付费墙后的后台、只有客户端才能看到的列表，一视同仁——
+因为那些东西本来就在用户屏幕上，而用户有权限看。
+
+```
+┌ 你的屏幕 ─────────────────────────────┐
+│ 一个需要登录的后台订单页              │
+│ 一个反爬很凶的招聘站                  │
+│ 一个只在 Windows 客户端里存在的台账   │
+└───────────────┬───────────────────────┘
+                │  自动 Ctrl+A / Ctrl+C（真按键，不是 DOM 抓取）
+                ▼
+        剪贴板：纯文本 + CF_HTML
+                │
+                ▼
+   sniff → normalize → segment → extract → assemble → export
+                │
+                ▼
+        CSV / Markdown / JSONL / XLSX
+```
+
+---
+
+## 看一眼真实输出
+
+不配任何规则，直接把一段乱糟糟的复制文本丢给它：
+
+```
+$ clip2table infer --text-file fixtures/sample-ecom.txt --show 1
+file ｜ FILE ｜ S1 ｜ 3 行 × 5 列 ｜ 未识别 0 行
+来源：未知（file 没有提供可核对的地址）
+字段填充：line1 100% ｜ 日期 100% ｜ line3 100% ｜ 规格 100% ｜ line5 100%
+✓ 行数守恒：15 行全部有归属（记录占用 15 行 + 未识别 0 行）
+· S1：按周期锚点切成 3 条记录（每 5 行一条）
+· 列名按每列的形态推断，键值列已去掉「键：」前缀，可在卡里改成业务名
+
+前 1 条：
+  1. line1=星海无线耳机 Pro ｜ 日期=2026-03-14 ｜ line3=包装完好，降噪比上一代强不少，通勤地铁里基本听不到报站 ｜ 规格=黑色 / 降噪版 ｜ line5=有用(128)
+
+依据：
+  · 周期候选 1：每 5 行一条，从第 1 行起，3 条；边界一致 100%，最弱一位的结构占比 100%，完全同形的记录 3/3 条
+```
+
+注意最后那段「依据」。它不是在炫技——**它把「为什么认为这是 3 行 × 5 列」摊开给你看**，
+你才有机会说"你猜错了"。只给结论不给依据的自动推断，是最难发现错误的那种。
+
+---
+
+## 装
+
+```bash
+pip install clip2table
+clip2table doctor       # 自检：剪贴板 / 卡目录 / 浏览器调试端口
+```
+
+零必需依赖，Python 3.11+，Windows 10/11。
+
+> PyPI 上的首次上传还没做（要先配 trusted publisher，见
+> [docs/publishing.md](docs/publishing.md)）。在那之前 `pip install clip2table`
+> 会 404，请从 [Releases](https://github.com/yjq123-zyh/clip2table/releases) 下 wheel 装：
+>
+> ```bash
+> pip install https://github.com/yjq123-zyh/clip2table/releases/download/v0.1.0/clip2table-0.1.0-py3-none-any.whl
+> ```
+
+要给这个项目改代码，从源码装：
+
+```bash
+git clone https://github.com/yjq123-zyh/clip2table.git
+cd clip2table
+pip install -e .
+```
+
+完全不想装包也可以：`python _dev/c2t.py <子命令>`，效果一样（它只是把 `src/` 挂上 `sys.path`）。
+
+## 三条命令
+
+```bash
+clip2table infer                                        # 读剪贴板，反推结构，先看清楚再存
+clip2table run --url https://example.com/list --show 3  # 自动选通道取一页，打印报告
+clip2table harvest -p mysite.toml --max-pages 20 --yes -f csv -f xlsx --dir out
+```
+
+`harvest` 是主线：按卡里的规则翻页、累积、去重、断点续采。卡怎么写、累积采集、
+断点续采、安全边界，全在 **[docs/usage.md](docs/usage.md)**。
+
+---
+
+## 三条不许
+
+这是这个项目存在的理由，也是它跟"剪贴板转表格小工具"的分界线。
+
+**1. 不许静默丢行。** 每条源文本要么进了某条记录，要么进了未识别清单，两者之和必须等于源行数。
+
+**2. 不许把切错的表当好表。** 行数守恒只能证明"没丢"，证明不了"切对了"。
+所以还有独立答案键回归，以及卡里 `record_lines` / `required` 的逐页形状校验。
+
+**3. 不许补值。** 表里没有的值就是空。空缺率本身就是信息——填平了就再也看不出来了。
+
+---
+
+## 三条通道
+
+| 通道 | 引擎 | 用在哪 |
+|---|---|---|
+| `http` | HTTP 直连 | 页面服务端就渲染好了 |
+| `browser` | E1：CDP 发真 Ctrl+A/Ctrl+C | 要登录、要 JS、有反爬 |
+| `desktop` | E2：Win32 `SendInput` | 目标不是浏览器：客户端、Excel、记事本 |
+
+不指定时自动降级，**报告第一行永远写清楚这次走了哪条、为什么**。
+
+---
+
+## 能做什么 / 不能做什么
+
+| 能做 | 说明 |
+|---|---|
+| 需要登录的后台列表 | 用你自己的浏览器、你自己的会话，不碰你的 Cookie |
+| 反爬很凶的站点 | 请求是浏览器自己发的，指纹、IP、UA 全真 |
+| Windows 客户端里的台账 | 只要能 Ctrl+A / Ctrl+C，就能进表 |
+| Excel 选中区域 | 桌面通道直接读，含 CF_HTML 的表格结构 |
+
+| 不能做 | 为什么 |
+|---|---|
+| 图片、Canvas 里的文字 | 它不在文本流里，复制不出来 |
+| 要逐个点开才能看到的内容 | 卡里能写少量准备动作，复杂交互做不了 |
+| 有验证码的页面 | 会停下来报错，不绕过。验证码该由人来过 |
+| 浏览器窗口最小化时的无痛复制 | Chromium 不允许隐藏标签页写剪贴板，会短暂借前台再还回去 |
+| 非 Windows | 通道 C 直接调 Win32 API，通道 B 靠窗口句柄还焦点 |
+
+还有一条要说清楚：**纯文本切分是启发式的**。页面结构变了就会切错——所以才有行形状校验、
+独立答案键回归、逐页偏离标记。它不能保证永远切对，它能保证**切错了你不会不知道**。
+
+---
+
+## 文档地图
+
+| 想知道 | 看这里 |
+|---|---|
+| 现在能做什么、怎么用、卡怎么写 | **[docs/usage.md](docs/usage.md)** |
+| 代码怎么组织、数据怎么流、状态存在哪 | **[docs/architecture.md](docs/architecture.md)** |
+| 为什么这么设计、哪些方案被否掉了 | **[docs/design-notes.md](docs/design-notes.md)** |
+| 十六项整改各自的验收证据 | [docs/verification.md](docs/verification.md) |
+| 怎么发版、PyPI 怎么配 | [docs/publishing.md](docs/publishing.md) |
+| 给 agent 用的决策循环 | [SKILL.md](SKILL.md) |
+| 改了什么 | [CHANGELOG.md](CHANGELOG.md) |
+| 权利归属、能拿去做什么、免责 | [NOTICE.md](NOTICE.md) |
+| 历史方案、实验记录、验收过程 | [docs/history/](docs/history/) —— **不代表当前能力** |
+
+---
+
+## 开发
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -t .     # 472 项
+python _dev/c2t.py selftest                   # 文档里的命令与真实参数表对账
+python _dev/c2t.py test notice-list           # 内置卡的逐字节回归
+```
+
+`SKILL.md` 是给 agent 看的决策循环，不是参数手册——参数手册是 `--help` 的活。
+它里面出现的每条子命令都会被 `selftest` 拿去和真实 argparser 比对，写错了就非 0 退出。
+也就是说，**文档里写了不存在的命令，CI 会红**。它校验的是仓库里的文档，所以要在这个
+目录里跑；装好的副本里没有文档，它会报错退出而不是假装通过。
+
+欢迎 issue 和 PR。提 PR 前请确认 `unittest` 与 `selftest` 都是绿的；
+改内置卡或 fixtures 请连带更新 `.expect.tsv`，那是逐字节比对的基准。
+
+## 环境要求
+
+Windows 10/11、Python 3.11+。通道 B 需要浏览器带 `--remote-debugging-port` 启动，
+`clip2table doctor` 会给你一行可以直接粘贴的命令。
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。
+
+著作权归属、授权范围、禁止性规定、免责与争议解决见 [NOTICE.md](NOTICE.md)。
+软件许可的正式条款以 MIT 许可证为准；两者不一致时以 MIT 为准。

clip2table-0.1.0/README.md

@@ -0,0 +1,191 @@
+# clip2table
+
+**把屏幕上看得到、选得中的任何内容，变成一张结构化表。**
+
+[![tests](https://github.com/yjq123-zyh/clip2table/actions/workflows/tests.yml/badge.svg)](https://github.com/yjq123-zyh/clip2table/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)](#环境要求)
+
+不是爬虫。爬虫要假装自己是浏览器、绕过指纹、维护代理池，然后在你和站点之间
+永远打一场你赢不了的军备竞赛。clip2table 换了个思路：**让真浏览器、真程序自己去复制**，
+它只负责把复制出来的文本切成表。
+
+所以它对你自己的登录态、付费墙后的后台、只有客户端才能看到的列表，一视同仁——
+因为那些东西本来就在用户屏幕上，而用户有权限看。
+
+```
+┌ 你的屏幕 ─────────────────────────────┐
+│ 一个需要登录的后台订单页              │
+│ 一个反爬很凶的招聘站                  │
+│ 一个只在 Windows 客户端里存在的台账   │
+└───────────────┬───────────────────────┘
+                │  自动 Ctrl+A / Ctrl+C（真按键，不是 DOM 抓取）
+                ▼
+        剪贴板：纯文本 + CF_HTML
+                │
+                ▼
+   sniff → normalize → segment → extract → assemble → export
+                │
+                ▼
+        CSV / Markdown / JSONL / XLSX
+```
+
+---
+
+## 看一眼真实输出
+
+不配任何规则，直接把一段乱糟糟的复制文本丢给它：
+
+```
+$ clip2table infer --text-file fixtures/sample-ecom.txt --show 1
+file ｜ FILE ｜ S1 ｜ 3 行 × 5 列 ｜ 未识别 0 行
+来源：未知（file 没有提供可核对的地址）
+字段填充：line1 100% ｜ 日期 100% ｜ line3 100% ｜ 规格 100% ｜ line5 100%
+✓ 行数守恒：15 行全部有归属（记录占用 15 行 + 未识别 0 行）
+· S1：按周期锚点切成 3 条记录（每 5 行一条）
+· 列名按每列的形态推断，键值列已去掉「键：」前缀，可在卡里改成业务名
+
+前 1 条：
+  1. line1=星海无线耳机 Pro ｜ 日期=2026-03-14 ｜ line3=包装完好，降噪比上一代强不少，通勤地铁里基本听不到报站 ｜ 规格=黑色 / 降噪版 ｜ line5=有用(128)
+
+依据：
+  · 周期候选 1：每 5 行一条，从第 1 行起，3 条；边界一致 100%，最弱一位的结构占比 100%，完全同形的记录 3/3 条
+```
+
+注意最后那段「依据」。它不是在炫技——**它把「为什么认为这是 3 行 × 5 列」摊开给你看**，
+你才有机会说"你猜错了"。只给结论不给依据的自动推断，是最难发现错误的那种。
+
+---
+
+## 装
+
+```bash
+pip install clip2table
+clip2table doctor       # 自检：剪贴板 / 卡目录 / 浏览器调试端口
+```
+
+零必需依赖，Python 3.11+，Windows 10/11。
+
+> PyPI 上的首次上传还没做（要先配 trusted publisher，见
+> [docs/publishing.md](docs/publishing.md)）。在那之前 `pip install clip2table`
+> 会 404，请从 [Releases](https://github.com/yjq123-zyh/clip2table/releases) 下 wheel 装：
+>
+> ```bash
+> pip install https://github.com/yjq123-zyh/clip2table/releases/download/v0.1.0/clip2table-0.1.0-py3-none-any.whl
+> ```
+
+要给这个项目改代码，从源码装：
+
+```bash
+git clone https://github.com/yjq123-zyh/clip2table.git
+cd clip2table
+pip install -e .
+```
+
+完全不想装包也可以：`python _dev/c2t.py <子命令>`，效果一样（它只是把 `src/` 挂上 `sys.path`）。
+
+## 三条命令
+
+```bash
+clip2table infer                                        # 读剪贴板，反推结构，先看清楚再存
+clip2table run --url https://example.com/list --show 3  # 自动选通道取一页，打印报告
+clip2table harvest -p mysite.toml --max-pages 20 --yes -f csv -f xlsx --dir out
+```
+
+`harvest` 是主线：按卡里的规则翻页、累积、去重、断点续采。卡怎么写、累积采集、
+断点续采、安全边界，全在 **[docs/usage.md](docs/usage.md)**。
+
+---
+
+## 三条不许
+
+这是这个项目存在的理由，也是它跟"剪贴板转表格小工具"的分界线。
+
+**1. 不许静默丢行。** 每条源文本要么进了某条记录，要么进了未识别清单，两者之和必须等于源行数。
+
+**2. 不许把切错的表当好表。** 行数守恒只能证明"没丢"，证明不了"切对了"。
+所以还有独立答案键回归，以及卡里 `record_lines` / `required` 的逐页形状校验。
+
+**3. 不许补值。** 表里没有的值就是空。空缺率本身就是信息——填平了就再也看不出来了。
+
+---
+
+## 三条通道
+
+| 通道 | 引擎 | 用在哪 |
+|---|---|---|
+| `http` | HTTP 直连 | 页面服务端就渲染好了 |
+| `browser` | E1：CDP 发真 Ctrl+A/Ctrl+C | 要登录、要 JS、有反爬 |
+| `desktop` | E2：Win32 `SendInput` | 目标不是浏览器：客户端、Excel、记事本 |
+
+不指定时自动降级，**报告第一行永远写清楚这次走了哪条、为什么**。
+
+---
+
+## 能做什么 / 不能做什么
+
+| 能做 | 说明 |
+|---|---|
+| 需要登录的后台列表 | 用你自己的浏览器、你自己的会话，不碰你的 Cookie |
+| 反爬很凶的站点 | 请求是浏览器自己发的，指纹、IP、UA 全真 |
+| Windows 客户端里的台账 | 只要能 Ctrl+A / Ctrl+C，就能进表 |
+| Excel 选中区域 | 桌面通道直接读，含 CF_HTML 的表格结构 |
+
+| 不能做 | 为什么 |
+|---|---|
+| 图片、Canvas 里的文字 | 它不在文本流里，复制不出来 |
+| 要逐个点开才能看到的内容 | 卡里能写少量准备动作，复杂交互做不了 |
+| 有验证码的页面 | 会停下来报错，不绕过。验证码该由人来过 |
+| 浏览器窗口最小化时的无痛复制 | Chromium 不允许隐藏标签页写剪贴板，会短暂借前台再还回去 |
+| 非 Windows | 通道 C 直接调 Win32 API，通道 B 靠窗口句柄还焦点 |
+
+还有一条要说清楚：**纯文本切分是启发式的**。页面结构变了就会切错——所以才有行形状校验、
+独立答案键回归、逐页偏离标记。它不能保证永远切对，它能保证**切错了你不会不知道**。
+
+---
+
+## 文档地图
+
+| 想知道 | 看这里 |
+|---|---|
+| 现在能做什么、怎么用、卡怎么写 | **[docs/usage.md](docs/usage.md)** |
+| 代码怎么组织、数据怎么流、状态存在哪 | **[docs/architecture.md](docs/architecture.md)** |
+| 为什么这么设计、哪些方案被否掉了 | **[docs/design-notes.md](docs/design-notes.md)** |
+| 十六项整改各自的验收证据 | [docs/verification.md](docs/verification.md) |
+| 怎么发版、PyPI 怎么配 | [docs/publishing.md](docs/publishing.md) |
+| 给 agent 用的决策循环 | [SKILL.md](SKILL.md) |
+| 改了什么 | [CHANGELOG.md](CHANGELOG.md) |
+| 权利归属、能拿去做什么、免责 | [NOTICE.md](NOTICE.md) |
+| 历史方案、实验记录、验收过程 | [docs/history/](docs/history/) —— **不代表当前能力** |
+
+---
+
+## 开发
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -t .     # 472 项
+python _dev/c2t.py selftest                   # 文档里的命令与真实参数表对账
+python _dev/c2t.py test notice-list           # 内置卡的逐字节回归
+```
+
+`SKILL.md` 是给 agent 看的决策循环，不是参数手册——参数手册是 `--help` 的活。
+它里面出现的每条子命令都会被 `selftest` 拿去和真实 argparser 比对，写错了就非 0 退出。
+也就是说，**文档里写了不存在的命令，CI 会红**。它校验的是仓库里的文档，所以要在这个
+目录里跑；装好的副本里没有文档，它会报错退出而不是假装通过。
+
+欢迎 issue 和 PR。提 PR 前请确认 `unittest` 与 `selftest` 都是绿的；
+改内置卡或 fixtures 请连带更新 `.expect.tsv`，那是逐字节比对的基准。
+
+## 环境要求
+
+Windows 10/11、Python 3.11+。通道 B 需要浏览器带 `--remote-debugging-port` 启动，
+`clip2table doctor` 会给你一行可以直接粘贴的命令。
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。
+
+著作权归属、授权范围、禁止性规定、免责与争议解决见 [NOTICE.md](NOTICE.md)。
+软件许可的正式条款以 MIT 许可证为准；两者不一致时以 MIT 为准。