popo-sheet

popo-sheet 是面向 POPO Sheet 的只读 CLI 项目，用于登录态复用、表格运行时探测、工作簿读取与 Markdown/JSON 导出。

本仓库也是 Codex/Claude 发布产物的源目录。发布时会将 codex-plugin/ 下的插件产物同步到 gl-codex-markplace/plugins/popo-sheet，供 Codex 插件市场消费。

一期范围

一期只支持读取能力：

• 解析 POPO Sheet 链接与表格标识
• 使用浏览器 storage state 复用登录态
• 探测页面运行时对象与工作簿结构
• 读取指定 sheet 或默认 sheet
• 导出 Markdown 或 JSON

一期明确不做：

• 写入单元格、编辑工作簿、插入行列
• 上传、下载附件或图片处理
• 权限绕过、批量抓取、后台任务同步

命令示例

安装 CLI：

npm install -g @kamtotoau/popo-sheet

popo-sheet login
popo-sheet inspect "https://popo.example.com/sheet/xxx"
popo-sheet read "https://popo.example.com/sheet/xxx" --sheet "Sheet1" --format md --output ./sheet.md
popo-sheet read "https://popo.example.com/sheet/xxx" --format json
popo-sheet inspect-runtime "https://popo.example.com/sheet/xxx"

当前代码已实现一期只读读取链路：通过 Playwright 读取 POPO Sheet 页面运行时 workbook，并将 workbook model 转换为 Markdown 或 JSON。

CLI 命令

• login：打开浏览器完成登录，保存 storage state。
• inspect：读取页面元信息、工作簿结构、sheet 列表和范围摘要。
• read：读取 sheet 内容，支持 --storage-state、--sheet、--format md/json、--output。
• inspect-runtime：输出运行时探针结果，用于适配 POPO Sheet 前端运行时变化。

登录态路径

默认登录态路径为 ~/.codex/popo-sheet/storage-state.json。

路径优先级：

1. 命令行显式路径：login --output、--storage-state
2. 环境变量：POPO_SHEET_STORAGE_STATE
3. 默认路径：~/.codex/popo-sheet/storage-state.json

popo-sheet login 会自动创建默认路径的父目录。

读取策略

读取顺序：

1. 解析 POPO Lingxi URL，得到 identity。
2. 使用 storage state 打开真实 sheet 页面。
3. 注入 runtime probe，捕获 webpack runtime。
4. 扫描 controller，调用 getWorkbookData()。
5. 解析 workbook model 的 sheets / rows / cols / cells。
6. 如果 runtime workbook 不可用，命令会失败并提示运行 inspect-runtime 做诊断。

后续如果需要降级路径，应在 popo-sheet 内部实现独立的 Sheet export 或 sharedb snapshot 读取。

目录

bin/                         CLI 入口占位
src/                         TypeScript 源码骨架
docs/                        中文设计文档
codex-plugin/                Codex 插件发布产物