Compare commits
39 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 codex-bot
|
d1466f35a6 | ||
 Zayden-Jung
|
3ab2f8e122 | ||
|
codex-bot
|
15024c3908 | ||
|
codex-bot
|
770be83692 | ||
|
codex-bot
|
083f532609 | ||
|
codex-bot
|
2b3706c90d | ||
|
codex-bot
|
6bfeea4e7e | ||
|
codex-bot
|
f156406265 | ||
|
codex-bot
|
e65d90c78b | ||
|
codex-bot
|
96f1417cda | ||
|
codex-bot
|
347b9587c6 | ||
|
codex-bot
|
677cd73945 | ||
|
codex-bot
|
e075eee8a5 | ||
|
codex-bot
|
d971362a97 | ||
|
codex-bot
|
0e5ccafa30 | ||
|
Zayden-Jung
|
0c2a909521 | ||
|
codex-bot
|
a58a409c38 | ||
|
codex-bot
|
c4ab5caac0 | ||
|
codex-bot
|
4cbb88181a | ||
|
codex-bot
|
ce87abd1cb | ||
|
Zayden-Jung
|
dc7ec078e1 | ||
|
codex-bot
|
bba9fddef1 | ||
|
Zayden-Jung
|
1302287205 | ||
|
codex-bot
|
59a1e4608b | ||
|
codex-bot
|
ed99743730 | ||
|
codex-bot
|
74af205b29 | ||
|
codex-bot
|
cffca6942b | ||
|
codex-bot
|
bf58a27779 | ||
|
codex-bot
|
922835704b | ||
|
codex-bot
|
864a30356d | ||
|
codex-bot
|
9a026a08a5 | ||
|
codex-bot
|
62d3d498bb | ||
|
codex-bot
|
62c015fa9b | ||
|
codex-bot
|
ec95f3be31 | ||
|
codex-bot
|
744e3314b8 | ||
|
codex-bot
|
79a6a8dbd7 | ||
|
codex-bot
|
0dcd178394 | ||
|
codex-bot
|
dca7c81889 | ||
|
codex-bot
|
f27b82b6a5 |
@@ -3,7 +3,7 @@
|
||||
- 本仓库专门维护 Endor 文档与制图脚本。支持本地开发；CI/CD 仅在 main 使用现有 ces-control Runner，验证通过后自动部署；工作分支与 PR 不运行 CI，确认 Runner 不构成扩大触发范围的授权。不得修改其他项目、共享 Runner 配置或清理共享 Docker 缓存。
|
||||
- Web 技术栈为 TypeScript、React、Tailwind CSS、Next.js Pages Router；不要切换到 App Router。
|
||||
- 使用 pnpm 管理 JavaScript workspace，使用 uv 管理 `tools/figures` 的 Python 项目，保留两套锁文件。
|
||||
- 文档正文、目录元数据与修订记录以站点现有 SQLite 数据库为唯一权威源，使用 docs 管理工具直接更新；不得把新正文、目录 JSON、数据库文件或日常内容快照提交到仓库。历史 Git 文档只用于显式的一次性迁移，不作为运行时种子。Python 图形源码放在 `tools/figures/src/endor_figures`，可复现的 SVG 输出放在 `apps/docs/public/figures`。
|
||||
- 文档正文、目录元数据与修订记录以站点现有 SQLite 数据库为唯一权威源，使用文档 API 或 docs 管理工具直接更新；不得把新正文、目录 JSON、数据库文件或日常内容快照提交到仓库。历史 Git 文档只用于显式的一次性迁移，不作为运行时种子。Python 图形源码放在 `tools/figures/src/endor_figures`，可复现的 SVG 输出放在 `apps/docs/public/figures`。
|
||||
- 未确认的架构提议明确标注为草案，不能表述为现有实现。
|
||||
- 本地开发与预览只监听 `127.0.0.1`。部署容器监听 `0.0.0.0:3000`，服务器入口默认 18135，可通过独立 production.env 配置。
|
||||
- 对 gitea.entroia.com 仅使用 codex-bot，提交身份为 Codex Bot <codex-bot@gitea.entroia.local>。SSH 使用隔离配置：`ssh -F /dev/null -o IdentitiesOnly=yes -i /Users/zzyang/.codex/credentials/gitea-entroia/codex_entroia_ed25519 -p 22222`。
|
||||
|
||||
@@ -1,18 +1,38 @@
|
||||
# Endor · Tabularium
|
||||
|
||||
Endor 文档站、研究工作台与制图程序。应用代码在 Git 中评审；全部文档正文、目录元数据和内容修订以站点 SQLite 数据库为唯一权威源。日常写作不需要 commit、构建或部署。
|
||||
Endor 的文档站与 AI 公司研究工作台，包含文档阅读、全文搜索、研究数据展示和制图工具。使用 Next.js Pages Router、React、TypeScript 与 Tailwind CSS；JavaScript workspace 使用 pnpm，制图 Python 项目使用 uv。
|
||||
|
||||
## 存储与读取
|
||||
## 代码与内容放在哪里
|
||||
|
||||
沿用 `AUTH_CONFIG_FILE` 同目录的 `login-state.sqlite` 和 `/auth` 持久挂载。`documents` 存正文及分类、合集、分组、摘要、草案与推荐状态；`document_aliases` 保留旧地址；`document_revisions` 保存每次修改；`document_imports` 标记一次性迁移。没有第二套文档数据库。
|
||||
文档正文、目录元数据和修订记录由站点 SQLite 数据库管理，日常写作直接更新数据库，无需提交代码、构建或部署。研究业务数据仍沿用版本化 JSON 导入机制，后续单独迁移。
|
||||
|
||||
首页、阅读页、目录和全文搜索按请求查询数据库，使用 `private, no-store`。旧文件式地址与改名前的语义地址通过数据库别名跳转，保留查询参数；不再在构建阶段枚举文档。Markdown 原文通过受认证保护的 `/api/documents/source?slug=...` 获取。
|
||||
| 内容 | 权威来源与维护方式 |
|
||||
| --- | --- |
|
||||
| 文档正文、分类、合集、分组、摘要、草案和推荐状态 | 数据库；通过文档 API 或服务器上的 `docs` 管理工具读写 |
|
||||
| 文档旧地址与修订历史 | 数据库；改名保留别名，修改追加修订 |
|
||||
| AI 公司、观测、证据、候选与核查记录 | `content/research` 中的版本化快照；服务端显式按版本导入同库后查询 |
|
||||
| 页面、组件、管理工具和部署逻辑 | 本仓库，通过工作分支与 PR 评审 |
|
||||
| 图形源码与静态资源 | `tools/figures` 与 `apps/docs/public`；生成步骤在远程 Runner 执行 |
|
||||
|
||||
仓库不保存日常正文、目录 JSON、数据库文件或内容快照；历史 Git 记录仅用于迁移。页面不再读取 `content/docs` 或 `content/catalog.json`。Markdown 与 GFM 表格仍可用，不解析原始 HTML。图片在写入时检查压缩格式；图形程序与版本化静态资源仍在代码仓库，本轮不迁移媒体存储。研究业务数据留待下一步。
|
||||
以上数据库数据共用 `AUTH_CONFIG_FILE` 同目录下的 `login-state.sqlite`，该文件名沿用历史命名。生产环境挂载到容器 `/auth`，不随镜像替换。文档使用 `documents`、`document_aliases`、`document_revisions`、`document_imports` 表，研究数据使用 `research_*` 表，登录状态使用 `login_state` 表。
|
||||
|
||||
## 在服务器上管理文档
|
||||
仓库不接收新的文档正文 Markdown、目录 JSON、数据库文件或日常正文快照。历史 Git 正文仅用于一次性迁移；运行时不读取 `content/docs` 或 `content/catalog.json`。README 维护程序使用与运维约定，研究个案、统计数量与内容更新日志在工作台和数据库文档中查看。
|
||||
|
||||
部署安装 `/opt/endorphin-tabularium-docs/docs`，通过当前容器执行管理 CLI。需要服务器的运维权限；不增加可公开写入的 API，不改变现有动态码登录。
|
||||
## 阅读与访问
|
||||
|
||||
首页、阅读页、目录及全文搜索按请求读取数据库，内容更新后刷新即可看到。旧文件式地址和改名前的语义地址继续跳转到当前地址，并保留查询参数。
|
||||
|
||||
- 文档原文：`GET /api/documents/source?slug=<文档地址>`。
|
||||
- 全文搜索：`GET /api/search`。
|
||||
- 研究工作台：`/docs/other-research/ai-company-research/overview`。
|
||||
- 收入样本：`/docs/other-research/ai-company-research/income-snapshot`。
|
||||
- 覆盖与缺项：`/docs/other-research/ai-company-research/coverage`。
|
||||
|
||||
正文、搜索、研究 API 与静态资料均经过站点登录认证，私有响应使用 `private, no-store`。Markdown 支持 GFM 表格，不解析原始 HTML；正文图片写入时检查压缩格式。草案标记用于展示状态，不构成单独的访问权限。
|
||||
|
||||
## 管理文档
|
||||
|
||||
部署后，管理员可在服务器上使用 `/opt/endorphin-tabularium-docs/docs`。该工具在当前容器中操作数据库，需要服务器运维权限。自动化上传使用下文的文档 API，日常读写无需登录服务器。
|
||||
|
||||
```sh
|
||||
sudo /opt/endorphin-tabularium-docs/docs list
|
||||
@@ -20,168 +40,177 @@ sudo /opt/endorphin-tabularium-docs/docs get endor/endor-purpose-draft
|
||||
sudo /opt/endorphin-tabularium-docs/docs history 04-endor-purpose-draft
|
||||
```
|
||||
|
||||
新建或修改使用标准输入传入完整 JSON。必填字段：`slug`、`sourceSlug`、`title`、`category`、`collection`、`group`、`description`、`draft`、`featured`、`content` 和 `revision`。新建时 `revision: 0`；修改时先 get 并使用读到的 revision，避免覆盖别人刚写入的版本。`sourceSlug` 是稳定标识，修改公共 slug 时保持它不变，旧地址继续可用。调整目录直接修改 category、collection、group 等字段。
|
||||
`save` 从标准输入接收完整 JSON。必填字段如下：
|
||||
|
||||
| 字段 | 用途 |
|
||||
| --- | --- |
|
||||
| `slug` | 语义化公开地址，不含数字章节前缀 |
|
||||
| `sourceSlug` | 稳定标识；修改公开地址时保持不变 |
|
||||
| `title`、`content` | 标题与 Markdown 正文 |
|
||||
| `category`、`collection`、`group` | 分类、合集与目录分组 |
|
||||
| `description`、`draft`、`featured` | 摘要、草案状态与推荐状态 |
|
||||
| `revision` | 新建传 `0`；修改传最近一次读取到的版本号 |
|
||||
|
||||
修改现有文档的流程：
|
||||
|
||||
```sh
|
||||
sudo /opt/endorphin-tabularium-docs/docs get endor/endor-purpose-draft > /private/work/purpose.json
|
||||
# 在私有文件中修改正文或目录字段，保留读到的 revision。
|
||||
sudo /opt/endorphin-tabularium-docs/docs save < /private/work/purpose.json
|
||||
umask 077
|
||||
doc_work_dir=$(mktemp -d)
|
||||
sudo /opt/endorphin-tabularium-docs/docs get endor/endor-purpose-draft > "$doc_work_dir/document.json"
|
||||
# 编辑该私有 JSON 文件，保留读取到的 revision 和 sourceSlug。
|
||||
sudo /opt/endorphin-tabularium-docs/docs save < "$doc_work_dir/document.json"
|
||||
```
|
||||
|
||||
路径仅为操作示例，应选择实际存在且受保护的目录。运行成功后刷新网页即可看到正文、导航和搜索更新。版本冲突时重新读取并合并修改；不要把旧 revision 改成新数字强行覆盖。草案是现有展示标记，不是按分支或用户隔离的访问控制。
|
||||
保存成功后，正文、目录和搜索通过后续请求读取新内容。发生版本冲突时重新读取并合并修改，不能仅改大 `revision` 覆盖并发编辑。调整分类或分组也走同一保存流程；`history` 使用稳定的 `sourceSlug` 查询修订。
|
||||
|
||||
新增正文不提交回 Git。奇思妙想这类内容同样通过数据库写入；代码分支与数据发布是不同动作，不能因为迁移程序合并就自动发布其他未合并分支的内容。
|
||||
## 文档上传 API
|
||||
|
||||
## 首次迁移与备份
|
||||
文档 API 直接读写同一个数据库，供自动化整理和大量文档上传使用。它只接受独立的文档 API Key，不接受网页 Cookie 或通用网页会话令牌；Key 不能用于研究、登录或其他站点 API。
|
||||
|
||||
迁移前主线的 50 篇正文及目录可从固定历史提交 `25c5e83d08eae4277fe429a692955bd3bb2e717f` 完整导出：
|
||||
| 方法与地址 | 用途 |
|
||||
| --- | --- |
|
||||
| `GET /api/documents?limit=50&offset=0` | 分页读取目录元数据；不返回全部正文 |
|
||||
| `GET /api/documents/item/<slug>` | 读取单篇完整正文、目录字段和当前 revision；支持旧地址 |
|
||||
| `GET /api/documents/item/<slug>?history=1&limit=50&offset=0` | 分页读取修订元数据与时间，按新到旧排列 |
|
||||
| `GET /api/documents/item/<slug>?revision=1` | 读取指定修订的完整正文 |
|
||||
| `POST /api/documents` | 保存一个完整文档 JSON；字段与 `docs save` 相同 |
|
||||
| `POST /api/documents/batch` | 保存 `{ "documents": [...] }`，每个请求 1—100 篇 |
|
||||
|
||||
写入使用 `Authorization: Bearer <文档 API Key>`。新建传 `revision: 0`；更新先读取当前全文，再使用读到的 revision。每篇正文最多 2,000,000 个 JavaScript 字符单位；每次请求最多 8 MiB。目录和修订分页的 `limit` 范围为 1—100，响应包含 `total` 和 `nextOffset`。
|
||||
|
||||
单个批量请求在同一事务提交，任意一篇格式错误、版本冲突或地址冲突都会整体回滚。成功返回文档地址、稳定标识和新修订号；版本或幂等键冲突返回 `409`，格式错误返回 `400`，超出请求大小返回 `413`。缺少、过期或撤销的 Key 返回 `401`，只读 Key 写入返回 `403`。
|
||||
|
||||
建议写入时提供 `Idempotency-Key`，由 1—128 个字母、数字或 `._:-` 组成。同一个 Key、相同请求 ID 和相同输入重试时，返回原回执并标记 `replayed: true`，不追加修订；相同 ID 改换输入会冲突。回执描述原请求，不代表之后没有其他修改；需要当前内容时重新读取文档。改过正文或 revision 后，应使用新的请求 ID。
|
||||
|
||||
### 创建、查看与撤销 Key
|
||||
|
||||
管理员只需通过已验证的服务器连接进行 Key 管理：
|
||||
|
||||
```sh
|
||||
python3 scripts/export-legacy-documents.py --output .artifacts/documents-migration.json
|
||||
sudo /opt/endorphin-tabularium-docs/docs key-create codex-upload /auth/codex-docs-key.json read-write 90
|
||||
sudo /opt/endorphin-tabularium-docs/docs key-list
|
||||
sudo /opt/endorphin-tabularium-docs/docs key-revoke <key-id>
|
||||
```
|
||||
|
||||
导出文件位于 Git 忽略目录、权限 0600，不进入镜像。脚本也支持显式 `--ref`，但不能用未评审分支替换生产迁移基线。它不会在站点读取时执行。CI 使用历史导出验证全部正文与目录的逐项一致性，构建镜像只含程序，不含文档快照或数据库。
|
||||
创建命令将完整 Key 写入认证私有目录中的指定新文件，权限 `0600`，终端仅输出 ID、权限和到期信息。文件已存在时拒绝覆盖。权限可选 `read` 或 `read-write`；有效期默认 90 天，可设 1—365 天。数据库仅保存 Key 摘要，列表不返回原文；撤销后不能继续认证。独立 Key 文件和认证 config.json 都不包含在 SQLite 整库备份中。
|
||||
|
||||
首次部署先备份整个共享数据库，再显式事务导入到空文档表。普通部署使用 `import --if-empty`，已有内容时跳过，不以历史数据覆盖数据库编辑；重复同一导入也不会重置内容。导入失败则事务整体回滚，既有登录与研究表保留，部署中止。
|
||||
### 使用上传客户端
|
||||
|
||||
`scripts/documents-client.py` 仅使用 Python 标准库。通过 `TABULARIUM_DOCS_URL` 指定站点 origin，通过 `TABULARIUM_DOCS_KEY_FILE` 指定本机私有 Key 文件（支持创建命令输出的 JSON），不把 Key 放入命令行参数。
|
||||
|
||||
客户端要求 HTTPS；尚未配置 HTTPS 时，可通过已验证的 SSH 连接建立本机端口转发，连接 `http://127.0.0.1:18136`。以下 `$DOCS_SSH_TARGET` 应事先设置为受信任的 SSH 别名或 `user@host`：
|
||||
|
||||
```sh
|
||||
ssh -N -L 18136:127.0.0.1:18135 "$DOCS_SSH_TARGET"
|
||||
```
|
||||
|
||||
将服务器私有目录中的 Key 文件复制到受保护的本机位置后，在另一个终端配置客户端。`$TABULARIUM_DOCS_KEY_FILE` 文件须仅本人可读写，不能提交到仓库：
|
||||
|
||||
```sh
|
||||
export TABULARIUM_DOCS_URL=http://127.0.0.1:18136
|
||||
export TABULARIUM_DOCS_KEY_FILE="$HOME/.config/tabularium/codex-docs-key.json"
|
||||
python3 scripts/documents-client.py list --limit 50
|
||||
python3 scripts/documents-client.py get endor/endor-purpose-draft
|
||||
python3 scripts/documents-client.py get endor/endor-purpose-draft --history
|
||||
python3 scripts/documents-client.py get endor/endor-purpose-draft --revision 1
|
||||
```
|
||||
|
||||
修改流程与 CLI 相同：
|
||||
|
||||
```sh
|
||||
umask 077
|
||||
api_work_dir=$(mktemp -d)
|
||||
python3 scripts/documents-client.py get endor/endor-purpose-draft > "$api_work_dir/document.json"
|
||||
# 编辑正文或目录字段，保留 sourceSlug 和读取到的 revision。
|
||||
python3 scripts/documents-client.py save "$api_work_dir/document.json"
|
||||
```
|
||||
|
||||
大量文档可使用仅含 `documents` 数组的私有 JSON 文件。客户端按 100 篇和 8 MiB 请求上限自动分批，并为各批派生固定的幂等请求 ID。每批独立提交；后续批次失败时，前面的成功批次保留。客户端会打印根请求 ID 和各批进度，使用相同 ID 与未修改的输入重试可跳过已完成的批次；可通过 `--request-id` 显式指定根 ID（客户端最多 100 个字符）。若后续批次因业务冲突失败，按进度中已提交的文档数量提取尚未成功的部分，修正后使用新的根 ID 上传。
|
||||
|
||||
客户端只自动重试一次临时网络或 `502/503/504` 错误，保持正文和请求 ID 不变；`409` 等业务错误不会自动覆盖。它不跟随 HTTP 重定向，避免将 Bearer 凭据转发到其他地址。正文和 Key 继续保存在数据库或私有文件中，不因使用 API 而进入 Git。
|
||||
|
||||
## 研究数据与检查
|
||||
|
||||
研究工作台提供公司筛选、经营指标、原始证据、收费与交付模式、技术材料及核查记录。它区分公司披露、支付平台指标、第三方估算、融资和客户收益；未知收入不填零，材料可访问也不代表性能或商业效果已经验证。研究范围、样本限制和个案结论以工作台记录为准。
|
||||
|
||||
| 仓库资料 | 用途 |
|
||||
| --- | --- |
|
||||
| `content/research/ai-companies.seed.json` | 研究数据导入快照；更新必须更换 `version` |
|
||||
| `content/research/ai-companies.sources.json` | 来源范围、用途、覆盖边界与后续缺项 |
|
||||
| `content/research/ai-companies.coverage.json` | 候选池逐条筛选台账 |
|
||||
| `content/research/ai-income-analysis.json` | 独立复算的统计参考快照 |
|
||||
|
||||
服务端以事务导入未载入的版本，保留旧研究版本与登录、文档数据；同一版本标识下内容变化会拒绝导入。页面和 `GET /api/research/ai-companies` 从数据库读取对应研究版本。回退程序可能选择旧研究版本，不能等同于撤销数据库中的正文编辑。
|
||||
|
||||
以下 Python 检查不触发编译或构建，可在工作分支执行：
|
||||
|
||||
```sh
|
||||
PYTHONDONTWRITEBYTECODE=1 python3 scripts/audit-ai-research.py --check
|
||||
PYTHONDONTWRITEBYTECODE=1 python3 scripts/summarize-ai-income.py --check
|
||||
```
|
||||
|
||||
若需对照研究数据检查报告正文，先用 `docs export` 导出当前文档，再给对应脚本传入 `--document-export <导出文件>`。默认 `--check` 核对研究数据的统计与审计不变量，不将历史迁移快照当作当前正文。脚本不带参数时仅在 `.artifacts/reports` 生成候选正文，需审阅后通过 `docs save` 写入数据库。
|
||||
|
||||
## 备份与首次迁移
|
||||
|
||||
```sh
|
||||
sudo /opt/endorphin-tabularium-docs/docs backup /auth/manual-backup.sqlite
|
||||
sudo /opt/endorphin-tabularium-docs/docs export /auth/current-documents.json
|
||||
```
|
||||
|
||||
backup 是包含登录、研究、正文、别名和修订的完整 SQLite 一致性备份；export 只导出当前正文与目录，作为空库初始化/外部迁移快照，不代替完整备份或恢复修订历史。输出路径均在容器内，文件已存在时拒绝覆盖。备份含认证状态，应留在私有挂载或受控备份位置，不能放到公开静态目录、仓库或日志。
|
||||
路径在容器内，输出文件已存在时拒绝覆盖。`backup` 是整个共享 SQLite 数据库的一致性备份，包含登录状态、研究数据、正文、别名和修订；`export` 只保存当前正文与目录，供空库初始化或外部迁移使用，不包含完整修订历史。认证配置单独保存在 `/auth/config.json`，整库备份不包含该配置文件。备份与导出应保存在私有挂载或受控备份位置。
|
||||
|
||||
代码回退不会撤销数据库编辑，但回退到旧文件式站点会显示旧正文。恢复完整数据库会同时影响登录和研究状态，必须先停止写入、保留当前备份并由管理员明确选择恢复点；部署脚本不会自动恢复数据库或删除新内容。
|
||||
首次迁移由 `scripts/export-legacy-documents.py` 从固定历史版本导出正文和目录，基线与研究正文覆盖版本在脚本中明确记录。导出写入 Git 忽略目录，权限为 `0600`，不进入生产镜像：
|
||||
|
||||
## 代码验证
|
||||
```sh
|
||||
python3 scripts/export-legacy-documents.py --output .artifacts/documents-migration.json
|
||||
```
|
||||
|
||||
使用 React、Next.js Pages Router、TypeScript 和 Tailwind CSS。JavaScript 用 pnpm，制图 Python 用 uv。编译、构建、打包和构建产物全部在已确认的 ces-control Runner 执行；`pnpm test:docs` 等测试脚本会调用 esbuild，也只能在 Runner 执行。
|
||||
该命令用于迁移准备，不是日常写作入口；目标文件存在时拒绝覆盖。部署先备份共享数据库，再用 `import --if-empty` 向空文档表事务导入。已有文档时跳过，不覆盖后续编辑；导入失败整体回滚并中止部署。`--ref` 仅用于明确选择历史导出版本。
|
||||
|
||||
工作分支与 PR 不运行 CI，仅做不会触发编译、构建的轻量检查。用户手动合并 main 后，才在 ces-control 执行 lint、类型检查、数据库事务/版本测试、现有认证与研究测试、图形检查、构建与容器冒烟；验证通过才沿用既有部署流程。
|
||||
程序回退不会撤销数据库编辑；回退到旧文件式站点则会显示旧正文。完整数据库恢复会同时影响登录、研究和文档状态，需先停止写入、保留当前备份，再明确选择恢复点。部署脚本只回退镜像，不自动恢复数据库。
|
||||
|
||||
冒烟使用隔离数据库卷：完整导入后逐项核对全部正文与目录，验证新建、更新、重命名、搜索立即变化及容器重启后的持久化，并覆盖全部文档地址、认证、媒体和原文端点。测试卷不会触及生产数据库。
|
||||
## 登录管理
|
||||
|
||||
`tools/figures/src/endor_figures` 与 `apps/docs/public/figures` 仍保存图形源码及可复现的静态资源。图形构建也在远程执行。
|
||||
|
||||
## 动态码登录与二维码
|
||||
|
||||
与 PROMPT 的参考流程一致：共享验证器的6位TOTP动态码，每30秒更新；成功登录的HttpOnly、SameSite=Lax会话有效7天。此方案是动态码单因素登录，不是密码加动态码的双因素组合。
|
||||
|
||||
正文、SVG、文档数据与API都经过认证，仅登录入口、登录所需代码资源和最小健康检查公开。20次/5分钟的共享尝试上限与已用时间步持久保存在SQLite中，跨进程和重启继续生效。缺失或损坏配置时拒绝访问，不自动降为公开站点。
|
||||
|
||||
生产认证文件位于服务器 `/opt/endorphin-tabularium-docs/private-auth`，目录0700、文件0600，只挂载进本项目容器。部署只初始化一次，后续更新保留同一验证器密钥与会话签名密钥。生产镜像、Git、CI日志和网页不包含密钥。
|
||||
|
||||
管理员通过SSH管理：
|
||||
站点使用共享验证器的 6 位 TOTP 动态码，每 30 秒更新。会话使用 HttpOnly、SameSite=Lax Cookie，有效期 7 天；共享尝试上限为每 5 分钟 20 次，重放与限流状态在数据库中持久保存。缺少或损坏认证配置时拒绝私有访问。
|
||||
|
||||
```sh
|
||||
sudo /opt/endorphin-tabularium-docs/auth qr
|
||||
sudo /opt/endorphin-tabularium-docs/auth verify
|
||||
```
|
||||
|
||||
`qr`只允许交互终端显示；`qr-png`用于通过SSH将PNG直接重定向到私有本地文件，不在CI中运行。二维码等同登录凭据，不放入本仓库或网页。只有明确执行 `auth rotate --confirm` 才更换密钥并使旧二维码、会话失效；重新显示或下载二维码不会轮换。
|
||||
认证配置和数据库位于服务器 `/opt/endorphin-tabularium-docs/private-auth`。正常部署保留验证器与会话签名密钥。`qr` 只在交互终端显示，`qr-png` 可导出到私有文件；只有 `auth rotate --confirm` 会轮换密钥并使旧会话失效。二维码和令牌不进入仓库、网页或 CI 日志。
|
||||
|
||||
构建、打包与会触发构建的测试只在用户确认的 ces-control Runner 上执行。本地不执行 `pnpm dev`、`pnpm build`、`pnpm typecheck` 或打包测试。
|
||||
当前 Compose 配置默认 `AUTH_COOKIE_SECURE=false`；实际采用 HTTPS 时，应在独立的生产配置中设置为 `true`。HTTP 不加密动态码与会话传输。生产部署使用无副作用的 `verify`，不执行会消耗动态码和触发限流的 `exercise`。
|
||||
|
||||
当前服务器入口为HTTP，与参考项目一致使用 `AUTH_COOKIE_SECURE=false`；配置HTTPS后应在独立production.env设置 `AUTH_COOKIE_SECURE=true`。HTTP本身不加密动态码和会话传输。
|
||||
## 开发、验证与发布
|
||||
|
||||
`pnpm test:auth`运行算法、会话、重放及限流测试。容器验证使用自己的匿名测试卷完成登录/并发重放/CSRF/限流测试，并在重启后检查状态仍存在。生产部署只运行无副作用的 `verify`，不会消耗用户动态码或触发生产限流。
|
||||
代码依赖要求见 `package.json` 和锁文件；当前要求 Node.js 22.13+、pnpm 11.25.0，制图使用 Python 与 uv。构建、打包、制图及会隐式编译的检查只在已确认的 `ces-control` Runner 执行，本机不执行这些步骤。
|
||||
|
||||
## AI 公司研究
|
||||
工作分支完成轻量检查后推送并创建 PR，由用户手动合并。**CI 仅在 main 推送或针对 main 的手动运行时执行，工作分支和 PR 不运行 CI。** 不自动合并，也不因确认 Runner 而扩大触发范围。
|
||||
|
||||
导航入口为 **其他研究 → AI 公司研究**，页面路径是
|
||||
`/docs/other-research/ai-company-research/overview`。工作台提供业务分类、公司搜索与筛选、
|
||||
公司明细、收入观测、原始证据和数据核查记录。所有页面与
|
||||
`GET /api/research/ai-companies` 均使用文档站现有的登录认证。
|
||||
主线通过 `.gitea/workflows/ci-deploy.yml` 执行 `scripts/ci.py`：
|
||||
|
||||
研究业务数据本轮暂不迁移，仍沿用版本化 JSON 导入机制。研究数据、文档与登录状态**共用文档站现有的 SQLite 数据库文件**：
|
||||
`AUTH_CONFIG_FILE` 同目录下的 `login-state.sqlite`。该文件名是历史名称，未创建第二个数据库。
|
||||
`login_state` 保留登录限流与重放状态，新增的 `research_*` 表保存数据版本、分类、
|
||||
公司、经营指标、证据与核查记录。沿用现有 `/auth` 持久挂载，数据库不会写入镜像或公开目录。
|
||||
1. 检查研究统计、审计与 Python 测试，生成首次迁移所需的历史导出。
|
||||
2. 根据程序、研究快照、图形、锁文件和构建脚本计算内容指纹。命中 verified 镜像时复用，否则安装依赖并执行 lint、类型检查、数据库测试、图形检查与构建。
|
||||
3. 使用隔离数据库卷核对完整迁移、认证、全部文档与资源，以及不重建内容更新和重启持久化；通过后标记镜像为 verified。
|
||||
4. `scripts/deploy.py` 确认仍为最新 main，备份并初始化文档数据，使用 `--no-build` 部署；失败时回退上一版镜像。
|
||||
|
||||
`content/research/ai-companies.seed.json` 是可评审的研究导入快照，
|
||||
服务端首次读取该版本时将它以事务导入同一数据库，之后从数据库查询记录。
|
||||
导入使用外键校验，不删除登录数据，也不覆盖旧研究版本。每次更新快照必须修改 `version`；
|
||||
同一版本内容变化会拒绝导入，避免静默读取旧数据。回退代码时继续读取对应旧版本。
|
||||
所有修改都经过工作分支和 PR，部署仍等待人工合并主线。
|
||||
`pnpm check`、`pnpm typecheck`、`pnpm test:auth`、`pnpm test:research`、`pnpm test:docs`、`pnpm figures`、`pnpm build` 和 `pnpm dev` 等命令涉及编译、构建或产物生成，不在本机运行。图形源码与生成资源保持可复现，前端继续使用 Pages Router。
|
||||
|
||||
当前资料包含 1,015 条公司/产品记录、10 类业务及待分类组、1,091 条证据记录和 183 条经营与技术观测。
|
||||
其中保留 86 家个案资料、913 条目录基础资料，并新增 16 个平台产品/业务样本；目录项不等于完成财务和技术核验。
|
||||
补充ThinkWheel与中国NaiveAI；MiroMind成立年未核，公开研发年份单列。保留灵初智能成立年排除、深度原理日期待核和Naive近名实体复核记录。
|
||||
新增7条Speedrun个案，保留标题/正文冲突、七位数数量级、币种不明、合同管线与履历归属排除记录；相对日期不充当同期收入时点。核查页优先按人工确认的公司ID关联明细，旧版本保留按证据归属回退；54条核查中43条指向具体公司、3条属于全局方法、8条是未纳入候选。明细反向列出关联核查；币种不明的声明保留原值，不绘制美元收入长度条。
|
||||
Bud保留为2025成立且YC标记已收购的案例；Rocket.new按前身2021成立、2025产品上线的转型对照记录，历史ARR不混入新成立公司同期统计。
|
||||
验收按2026-10-30确认的公开来源清单边界逐条核对并标明缺项；YC候选池有完整读取台账，其他来源目前为定向补充，不能把来源出现次数当作覆盖完成。收入披露不足且统计时点不统一，不代表全部 AI 公司。
|
||||
界面将公司自述、第三方估算、融资、客户收入和履历收入分开，未知收入不记为零。
|
||||
保留被撤回的声明作为核查记录，并排除收入比较；并购后业务、管理层预测与历史里程碑单列。
|
||||
团队规模下界在列表中显示比较符，商业成熟度展示公开交付证据，不等于技术能力排名。
|
||||
Emergent的1亿美元ARR里程碑补足至2026年2月；Peec采用规模和Wonderful团队规模各保留其公告日期，不将较新非收入指标当作ARR更新。Wonderful按2026年9月官方综合平台定位归C05。
|
||||
公司披露的 ARR 尚未建立同期同口径比较组。新增平台 MRR 单独计算探索性样本统计，
|
||||
不能称行业平均 ARR、总体离散排名或财务造假概率。
|
||||
根 README 等非构建输入变更不要求重新构建；数据库正文和目录更新也不触发构建。保留 pnpm、uv、Next.js 与 SWC 缓存，不清理共享 Docker 缓存或卷，不修改共享 Runner 或其他项目。
|
||||
|
||||
收入分布：`IncomeDistribution.tsx` 从数据库返回的观测中筛选平台 USD MRR，
|
||||
每个产品只保留符合条件的最新值，默认数据日期距截止日不超过7天。
|
||||
按业务类别、支付来源及可选收费模式分组，显示均值、中位数、样本CV（标准差分母n−1）、
|
||||
均值/中位数和移除最大值后的均值敏感性。n<3标注样本不足；n=1不计算CV。
|
||||
MRR×12仅作为显示单位转换，不改写为公司ARR；公司ARR、估算与近30日收入均不混入。
|
||||
`ai-income-analysis.json` 是独立Python复算的7日/90日快照参考，用于检查统计选择和计算，
|
||||
页面本身从同一SQLite中的公司与观测记录计算，不读取第二个数据库。
|
||||
## 部署位置与仓库
|
||||
|
||||
平台同步时间、连接过期状态、业务描述的可编辑性和产品/法律主体未去重限制均保留。
|
||||
覆盖审计页位于 `/docs/other-research/ai-company-research/coverage`，分类链接 `overview?category=<id>` 的筛选数据。
|
||||
`python3 scripts/audit-ai-research.py --check` 检查候选池逐条计数与来源审计一致性；CI在ces-control运行此检查。
|
||||
收入快照报告位于 `/docs/other-research/ai-company-research/income-snapshot`，样本名称链接 `overview?company=<id>` 的公司明细。
|
||||
`python3 scripts/summarize-ai-income.py --check` 独立复核统计与参考快照一致性；不触发编译或构建。数据变更后先审查方法，再运行不带参数的命令生成 `.artifacts/reports` 下的候选正文，使用 docs 管理工具显式更新数据库；不再生成受 Git 管理的正文。
|
||||
默认7日样本14个产品；90日窗口新增Gojiberry的8月历史点，营销样本的均值和CV随之明显变化。
|
||||
这提示先核查时间与样本构成，不能将高离散度直接解释为造假。两个近名营养应用按不同App Store ID分别建档。
|
||||
| 项目 | 位置或默认值 |
|
||||
| --- | --- |
|
||||
| Compose 项目 | `endorphin-tabularium-docs` |
|
||||
| 容器监听 | `0.0.0.0:3000` |
|
||||
| 服务器入口 | 默认端口 `18135`，由生产配置决定 |
|
||||
| 生产配置 | `/etc/endorphin-tabularium-docs/production.env` |
|
||||
| 发布记录与当前版本 | `/opt/endorphin-tabularium-docs/releases/<commit>` 与 `current` |
|
||||
| 健康检查 | `/api/health` |
|
||||
|
||||
覆盖核查：从 yc-oss 非官方镜像发现 2025—2026 八个 YC 批次的 1,428 条候选，
|
||||
逐条读取对应 YC 官方公开页面，以页面中的成立年份、团队字段和业务描述筛选。
|
||||
962 条初筛匹配，其中 34 条与原表 URL 重合，实际新增 928 条；268 条年份不符或缺失、
|
||||
192 条 AI 业务待确认、6 条成立年份晚于批次年份未纳入本批新增。
|
||||
`content/research/ai-companies.coverage.json` 保留逐条筛选结果、来源与响应摘要，
|
||||
数据快照中的 `coverage` 也随版本进入同一 SQLite 数据库。只覆盖该候选池，不能称全球全量。
|
||||
服务入口使用 `TABULARIUM_BIND`、`TABULARIUM_PORT` 配置。部署前检查端口是否空闲或属于本服务，不停止其他服务抢占端口；本项目不自动修改防火墙、域名或反向代理。
|
||||
|
||||
新增业务分类优先匹配主营简介，再参考目录标签；未匹配者进入待分类组。
|
||||
初分规则位于 `scripts/classify-ai-profiles.py`，只生成待评审标签，不执行抓取或构建。
|
||||
目录基础项保留 `classificationBasis` 和 `directoryTags` 供复核。
|
||||
当前目录基础项中160条已人工复核主营与买家，Contrario及14条收入声明/排除案例已深化为个案。`directoryOrigin`保留原发现来源，`profileOnly`只表示当前资料深度；深化不改变原候选池新增928条的审计分母。
|
||||
分类按主要工作任务和买家判断，例如Paragon归客户与收入运营，Oki归消费者应用，Lucidic归Agent设施。市场支出、采用规模、性能主张及客户收益均不作为公司收入。
|
||||
其中121条原待分类记录已按YC官方业务介绍人工复核主营业务，分类理由保存在公司字段与对应证据摘要中；
|
||||
仍有3条因简介不足保留待分类。人工复核分类不代表独立验证技术水平、客户效果或财务数据。
|
||||
AI 关键词可能出现在业务背景中，收入、买家和交付状态仍须逐家深查，不能把目录项的未知收入当作未披露。
|
||||
技术专项评审用独立字段记录层级、日期、摘要与证据：未评审、已读技术自述、公开代码/模型材料可访问、有第三方独立评测记录。
|
||||
当前7条完成该字段的专项记录，其中3条确认材料可访问、1条记录第三方已发表评测（Gradium TTS Sep 2026）；本轮未自行运行模型测试。缺字段不表示无技术能力，代码或模型卡可读不证明性能。
|
||||
界面支持按资料深度、记录团队规模和技术验证证据筛选；证据列表每页 30 条，避免一次渲染全部来源。
|
||||
|
||||
`pnpm test:research` 在远程 Runner 上验证同库持久化、重复读取、版本导入与回退、
|
||||
登录限流保留、引用完整性及收入排除规则。镜像冒烟检查会验证研究页面与 API 的认证、
|
||||
返回记录数量、只读方法和容器重启后的读取结果。页面筛选交互仍需实际浏览器验证。
|
||||
|
||||
## CI/CD 与缓存
|
||||
|
||||
文档内容已退出构建输入。若需对照研究数据检查数据库中的报告正文，可先导出当前文档，再给研究脚本传入 `--document-export`；默认 `--check` 只核对研究数据本身的统计和审计不变量，避免把历史迁移快照继续当作日常正文源。
|
||||
|
||||
`.gitea/workflows/ci-deploy.yml` 使用已有 ces-control Runner，不修改共享 Runner 配置。
|
||||
工作流仅在 main 推送或针对 main 的手动运行时执行，工作分支与 PR 不触发 CI。确认 ces-control 是构建位置，不构成新增分支 CI 的授权；报告须区分轻量检查与主线 CI。
|
||||
|
||||
1. 对实际构建输入计算 SHA-256：前端源码、图片、Python 制图源码、研究业务快照、依赖锁文件、Dockerfile 和构建脚本。
|
||||
2. 命中 `verified-<scope>-<摘要>` 镜像时跳过依赖安装和 Next.js build，只做认证、实际路由与资源冒烟检查。
|
||||
3. 输入变化时运行 lint、类型检查、制图一致性检查与构建。pnpm store、uv 和 `.next/cache` 使用持久 Docker 卷，main 与每个 PR 独立；额外保留 Next.js SWC 下载缓存。
|
||||
4. 生产镜像只包含 Next.js standalone 产物；Python 留在检查容器，不进入运行镜像。镜像通过动态码认证、重放/限流、重启持久化、健康、全部文档、JS/CSS、SVG 和 404 检查后才标记为 verified。
|
||||
5. 部署前检查是否仍为最新 main，使用 `--no-build` 启动，失败恢复上一版镜像。
|
||||
|
||||
根 README、工作流或部署配置等非构建输入变化不会触发 Next.js 重建；数据库中的正文和目录变化直接通过请求读取，不触发任何构建。首次构建必须安装依赖并完整生成产物。缓存可能因基础镜像、工具链或锁文件变化而失效；不要清理共享 Docker 缓存或卷。
|
||||
|
||||
默认入口为服务器的 **18135** 端口。容器监听 3000，使用独立 Compose 项目 `endorphin-tabularium-docs`。部署前先检查端口是否空闲（或属于本服务），不会停止其他服务以抢占端口。服务器配置位于 `/etc/endorphin-tabularium-docs/production.env`：
|
||||
|
||||
```dotenv
|
||||
TABULARIUM_BIND=0.0.0.0
|
||||
TABULARIUM_PORT=18135
|
||||
```
|
||||
|
||||
发布记录位于 `/opt/endorphin-tabularium-docs/releases/<commit>`，`current` 指向最近成功发布。修改服务器入口配置后手动重跑 main 工作流即可，复用现有镜像。
|
||||
|
||||
健康检查：`/api/health`。本项目不修改 Hestia、PROMPT 或其他服务，也不自动修改防火墙、域名和反向代理。
|
||||
|
||||
## Git 远程
|
||||
|
||||
仓库：[endorphin-tabularium-docs](https://gitea.entroia.com/Zayden-Jung/endorphin-tabularium-docs)。开发者 Git 操作使用 codex-bot 专用 SSH；Actions 检出使用 Gitea 内置任务令牌，不保存检出凭据。
|
||||
仓库：[endorphin-tabularium-docs](https://gitea.entroia.com/Zayden-Jung/endorphin-tabularium-docs)。Git 操作仅使用 `codex-bot` 专用 SSH 身份与仓库级提交配置；Actions 检出使用 Gitea 内置任务令牌且不保存凭据。
|
||||
|
||||
@@ -18,6 +18,7 @@ import {
|
||||
totp,
|
||||
isLoginRedirect,
|
||||
} from "../src/lib/auth";
|
||||
import { createDocumentKey, revokeDocumentKey } from "../src/lib/document-keys";
|
||||
import { readDocument, saveDocument } from "../src/lib/docs";
|
||||
import { consumeCode, initializeStore } from "../src/lib/auth-store";
|
||||
|
||||
@@ -181,10 +182,10 @@ async function main() {
|
||||
assert.equal(researchResponse.status, 200, "authenticated research API");
|
||||
assert.ok(researchResponse.headers.get("cache-control")?.includes("no-store"));
|
||||
const research = await researchResponse.json();
|
||||
assert.equal(research.companies.length, 1015);
|
||||
assert.equal(research.companies.length, 1023);
|
||||
assert.equal(research.categories.length, 11);
|
||||
assert.equal(research.evidence.length, 1091);
|
||||
assert.equal(research.observations.length, 183);
|
||||
assert.equal(research.evidence.length, 1259);
|
||||
assert.equal(research.observations.length, 189);
|
||||
assert.equal((await request("/api/research/ai-companies", { method: "POST", headers })).status, 405);
|
||||
const researchPage = await request("/docs/other-research/ai-company-research/overview", { headers });
|
||||
assert.equal(researchPage.status, 200);
|
||||
@@ -210,6 +211,7 @@ async function main() {
|
||||
assert.equal(raw.status, 200);
|
||||
assert.ok((await raw.text()).startsWith("# Endor"));
|
||||
if (process.env.DOCUMENT_SMOKE_TEST) {
|
||||
if (command === "exercise") await exerciseDocumentApi(request, headers);
|
||||
const sourceSlug = "ci-live-document";
|
||||
const previous = readDocument(sourceSlug);
|
||||
if (command === "exercise") {
|
||||
@@ -221,7 +223,8 @@ async function main() {
|
||||
saveDocument({ ...first, slug: "endor/ci-live-document-renamed", content: "# Runtime document\n\nUpdated without rebuilding" }, first.revision);
|
||||
}
|
||||
const stored = readDocument(sourceSlug);
|
||||
assert.ok(stored?.content.includes("Updated without rebuilding"), "DB content survives restart");
|
||||
assert.ok(stored, "Smoke document must exist after creation or restart");
|
||||
assert.ok(stored.content.includes("Updated without rebuilding"), "DB content survives restart");
|
||||
const live = await request(`/docs/${stored.slug}`, { headers });
|
||||
assert.equal(live.status, 200);
|
||||
assert.ok((await live.text()).includes("Updated without rebuilding"));
|
||||
@@ -355,3 +358,42 @@ main().catch((error) => {
|
||||
);
|
||||
process.exitCode = 1;
|
||||
});
|
||||
|
||||
async function exerciseDocumentApi(request: (path: string, init?: RequestInit) => Promise<Response>, session: Record<string, string>) {
|
||||
const writer = createDocumentKey("isolated API smoke", "read-write", 1);
|
||||
const reader = createDocumentKey("isolated read smoke", "read", 1);
|
||||
const headers = { Authorization: "Bearer " + writer.token, "Content-Type": "application/json", "Idempotency-Key": "smoke-batch" };
|
||||
const readHeaders = { Authorization: "Bearer " + reader.token, "Content-Type": "application/json" };
|
||||
const make = (name: string) => ({ slug: `endor/${name}`, sourceSlug: name, title: "API smoke",
|
||||
category: "Endor", collection: "Endor 文档", group: "CI", description: "Isolated API smoke",
|
||||
draft: true, featured: false, content: "# API smoke", revision: 0 });
|
||||
const payload = { documents: [make("ci-api-first"), make("ci-api-second")] };
|
||||
try {
|
||||
assert.equal((await request("/api/documents")).status, 401);
|
||||
assert.equal((await request("/api/documents", { method: "POST", headers: { ...session, "Content-Type": "application/json" }, body: JSON.stringify(payload.documents[0]) })).status, 401);
|
||||
assert.equal((await request("/api/research/ai-companies", { headers })).status, 401, "Document keys cannot read research");
|
||||
assert.equal((await request("/api/search", { headers })).status, 401, "Document keys cannot authenticate other APIs");
|
||||
assert.equal((await request("/api/documents/batch", { method: "POST", headers: readHeaders, body: JSON.stringify(payload) })).status, 403);
|
||||
const saved = await request("/api/documents/batch", { method: "POST", headers, body: JSON.stringify(payload) });
|
||||
assert.equal(saved.status, 200);
|
||||
assert.equal((await saved.json()).documents.length, 2);
|
||||
const replay = await request("/api/documents/batch", { method: "POST", headers, body: JSON.stringify(payload) });
|
||||
assert.equal(replay.status, 200); assert.equal((await replay.json()).replayed, true);
|
||||
const current = await request("/api/documents/item/endor/ci-api-first", { headers: readHeaders });
|
||||
assert.equal(current.status, 200); assert.equal((await current.json()).revision, 1);
|
||||
const page = await request("/api/documents?limit=1", { headers: readHeaders });
|
||||
assert.equal(page.status, 200);
|
||||
const listing = await page.json();
|
||||
assert.equal(listing.documents.length, 1); assert.equal(listing.documents[0].content, undefined);
|
||||
const bad = { documents: [{ ...payload.documents[0], revision: 1, content: "Must roll back" }, payload.documents[1]] };
|
||||
const conflict = await request("/api/documents/batch", { method: "POST", headers: { ...headers, "Idempotency-Key": "smoke-conflict" }, body: JSON.stringify(bad) });
|
||||
assert.equal(conflict.status, 409);
|
||||
const unchanged = await request("/api/documents/item/endor/ci-api-first", { headers: readHeaders });
|
||||
assert.equal((await unchanged.json()).content, "# API smoke");
|
||||
const history = await request("/api/documents/item/endor/ci-api-first?history=1", { headers });
|
||||
assert.equal(history.status, 200); assert.equal((await history.json()).total, 1);
|
||||
revokeDocumentKey(writer.id);
|
||||
assert.equal((await request("/api/documents", { headers })).status, 401);
|
||||
} finally { revokeDocumentKey(writer.id); revokeDocumentKey(reader.id); }
|
||||
console.log("Document API smoke passed: scoped keys, batch rollback, pagination, history, replay and revocation; no secrets displayed");
|
||||
}
|
||||
|
||||
@@ -1,11 +1,37 @@
|
||||
import { readFileSync, writeFileSync } from "node:fs";
|
||||
import { readFileSync, writeFileSync, openSync, closeSync, unlinkSync } from "node:fs";
|
||||
import { resolve, dirname, sep } from "node:path";
|
||||
import { createDocumentKey, listDocumentKeys, revokeDocumentKey, type DocumentKeyScope } from "../src/lib/document-keys";
|
||||
import { openSiteDatabase } from "../src/lib/site-database";
|
||||
import { allDocuments, readDocument, saveDocument, importDocuments, documentHistory } from "../src/lib/docs";
|
||||
|
||||
process.umask(0o077);
|
||||
const [command, argument] = process.argv.slice(2);
|
||||
const [command, argument, ...extra] = process.argv.slice(2);
|
||||
try {
|
||||
switch (command) {
|
||||
case "key-create": {
|
||||
const authFile = process.env.AUTH_CONFIG_FILE;
|
||||
if (!authFile || !argument || !extra[0]) throw Error("Usage: key-create <name> <private-file> [read|read-write] [days]");
|
||||
const file = resolve(extra[0]);
|
||||
const directory = resolve(dirname(authFile));
|
||||
if (!file.startsWith(directory + sep)) throw Error("Key output must be inside the private authentication directory");
|
||||
const fd = openSync(file, "wx", 0o600);
|
||||
let created: { id: string } | undefined;
|
||||
try {
|
||||
const key = createDocumentKey(argument, (extra[1] ?? "read-write") as DocumentKeyScope, Number(extra[2] ?? 90));
|
||||
created = key;
|
||||
writeFileSync(fd, JSON.stringify(key) + "\n");
|
||||
console.log(JSON.stringify({ id: key.id, scope: key.scope, expiresAt: key.expiresAt, saved: file }));
|
||||
} catch (error) {
|
||||
if (created) revokeDocumentKey(created.id);
|
||||
unlinkSync(file);
|
||||
throw error;
|
||||
} finally { closeSync(fd); }
|
||||
break;
|
||||
}
|
||||
case "key-list": console.log(JSON.stringify(listDocumentKeys(), null, 2)); break;
|
||||
case "key-revoke":
|
||||
if (!argument) throw Error("Provide key id");
|
||||
revokeDocumentKey(argument); console.log("Document key revoked"); break;
|
||||
case "backup": {
|
||||
if (!argument) throw Error("Provide a private backup filename");
|
||||
const db = openSiteDatabase();
|
||||
@@ -36,7 +62,7 @@ try {
|
||||
{ flag: "wx", mode: 0o600 });
|
||||
console.log("Document export created; existing files are never overwritten"); break;
|
||||
}
|
||||
default: throw Error("Usage: docs backup <private-file> | list | get <slug> | save < input.json | history <sourceSlug> | import [--if-empty] < export.json | export <private-file>");
|
||||
default: throw Error("Usage: docs key-create <name> <private-file> [read|read-write] [days] | key-list | key-revoke <id> | backup <private-file> | list | get <slug> | save < input.json | history <sourceSlug> | import [--if-empty] < export.json | export <private-file>");
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(error instanceof Error ? error.message : "Document operation failed");
|
||||
|
||||
@@ -6,9 +6,8 @@ import { spawnSync } from "node:child_process";
|
||||
|
||||
const dir = await mkdtemp(join(tmpdir(), "tabularium-docs-tests-"));
|
||||
try {
|
||||
const file = join(dir, "docs.test.cjs");
|
||||
await build({ entryPoints: ["tests/docs.test.ts"], bundle: true,
|
||||
platform: "node", target: "node22", format: "cjs", outfile: file });
|
||||
const result = spawnSync(process.execPath, ["--test", file], { stdio: "inherit" });
|
||||
await build({ entryPoints: ["tests/docs.test.ts", "tests/documents-api.test.ts"], bundle: true,
|
||||
platform: "node", target: "node22", format: "cjs", outdir: dir, outExtension: { ".js": ".cjs" } });
|
||||
const result = spawnSync(process.execPath, ["--test", join(dir, "docs.test.cjs"), join(dir, "documents-api.test.cjs")], { stdio: "inherit" });
|
||||
process.exitCode = result.status ?? 1;
|
||||
} finally { await rm(dir, { recursive: true, force: true }); }
|
||||
|
||||
@@ -20,6 +20,9 @@ export default function IncomeDistribution({ data, onSelect }: {
|
||||
}), [data, dateWindow, year, annualize]);
|
||||
const groups = useMemo(() => groupIncome(sample.points, splitModels).sort((a, b) =>
|
||||
a.category.localeCompare(b.category) || a.provider.localeCompare(b.provider) || a.model.localeCompare(b.model)), [sample.points, splitModels]);
|
||||
const categoryGroups = [...new Set(groups.map((group) => group.category))].map((category) => ({
|
||||
category, rows: groups.filter((group) => group.category === category),
|
||||
}));
|
||||
const categories = new Map(data.categories.map((category) => [category.id, category.name]));
|
||||
const metric = annualize ? "MRR×12参考年化" : "平台MRR";
|
||||
const values = sample.points.map((point) => point.value);
|
||||
@@ -41,6 +44,7 @@ export default function IncomeDistribution({ data, onSelect }: {
|
||||
<label>显示单位<select value={annualize ? "annualized" : "mrr"} onChange={(event) => setAnnualize(event.target.value === "annualized")}><option value="mrr">MRR（美元/月）</option><option value="annualized">MRR×12参考年化（美元/年）</option></select></label>
|
||||
</div>
|
||||
<div className="income-options"><label><input type="checkbox" checked={splitModels} onChange={(event) => setSplitModels(event.target.checked)} /> 按收费与交付模式细分</label><label><input type="checkbox" checked={logScale} onChange={(event) => setLogScale(event.target.checked)} /> 对数横轴</label></div>
|
||||
<p>{splitModels ? "分组：业务类别 × 支付平台 × 收费与交付模式。同一类别下的多行是不同统计组，各自计算均值和中位数。" : "分组：业务类别 × 支付平台。同一平台内的收费模式已合并，不同支付平台仍分别统计。"}</p>
|
||||
<p className="research-notice">资料截至 {data.asOf}，纳入 {sample.points.length} 个产品，另有 {sample.excluded.length} 个 MRR 观测未纳入。{annualize ? "乘12只改变显示单位，不证明全年收入、续约或ARR；CV与相对敏感性不变。" : "MRR不等于近30日收款；平台数据连接也不等于财务审计。"}{dateWindow === "all" && " 当前包含不同时间的历史观测，不能称为同期对照。"}</p>
|
||||
{sample.points.length ? <>
|
||||
<figure>
|
||||
@@ -48,9 +52,16 @@ export default function IncomeDistribution({ data, onSelect }: {
|
||||
{ticks.map((tick) => <g key={tick}><line x1={x(tick)} x2={x(tick)} y1={15} y2={groups.length * 70 + 10} stroke="#dfe6e0" /><text x={x(tick)} y={groups.length * 70 + 35} textAnchor="middle" fontSize="11" fill="#637066">{usd(tick)}</text></g>)}
|
||||
{groups.map((group, index) => {
|
||||
const y = index * 70 + 40;
|
||||
return <g key={group.key}>
|
||||
<text x={8} y={y - 8} fontSize="12" fill="#202724">{categories.get(group.category)}</text>
|
||||
<text x={8} y={y + 10} fontSize="10" fill="#637066">{group.provider} · {group.model} · n={group.stats.n}</text>
|
||||
const firstInCategory = index === 0 || groups[index - 1].category !== group.category;
|
||||
const categoryRowCount = categoryGroups.find((entry) => entry.category === group.category)!.rows.length;
|
||||
return <g key={group.key} role="group" aria-label={`${categories.get(group.category)}，${group.provider}，${group.model}，${group.stats.n}个产品`}>
|
||||
{firstInCategory && <>
|
||||
{index > 0 && <line x1={8} x2={right} y1={y - 34} y2={y - 34} stroke="#dfe6e0" />}
|
||||
<text x={8} y={y - 8} fontSize="12" fontWeight="600" fill="#202724">{categories.get(group.category)}（{categoryRowCount}组）</text>
|
||||
{categoryRowCount > 1 && <line x1={10} x2={10} y1={y + 3} y2={y + (categoryRowCount - 1) * 70 + 12} stroke="#95b4a6" strokeWidth={2} />}
|
||||
</>}
|
||||
<text x={20} y={y + 10} fontSize="10" fill="#637066">{group.provider} · {group.model} · n={group.stats.n}</text>
|
||||
{group.stats.n < 3 && <text x={20} y={y + 26} fontSize="9" fill="#637066">{group.stats.n === 1 ? "仅1个产品，无法判断组内离散度" : "仅2个产品，不代表领域典型收入"}</text>}
|
||||
<line x1={x(group.stats.min)} x2={x(group.stats.max)} y1={y} y2={y} stroke="#95b4a6" strokeWidth={2} />
|
||||
<line x1={x(group.stats.mean)} x2={x(group.stats.mean)} y1={y - 17} y2={y + 17} stroke="#b17725" strokeWidth={3}><title>样本均值 {usd(group.stats.mean)}</title></line>
|
||||
<path d={`M${x(group.stats.median)},${y - 7} l7,7 l-7,7 l-7,-7 Z`} fill="#8a78ad"><title>样本中位数 {usd(group.stats.median)}</title></path>
|
||||
@@ -62,12 +73,13 @@ export default function IncomeDistribution({ data, onSelect }: {
|
||||
</g>;
|
||||
})}
|
||||
</svg></div>
|
||||
<figcaption>圆点：产品观测 竖线：样本均值 菱形：样本中位数。按业务类别与支付来源分组，点击点或下表产品名可看原始证据。</figcaption>
|
||||
<figcaption>圆点：产品观测 竖线：样本均值 菱形：样本中位数。业务类别标题下各行按支付平台{splitModels && "及收费与交付模式"}分别统计；n为该组产品数。点击点或下表产品名可看原始证据。</figcaption>
|
||||
</figure>
|
||||
<div className="research-table-wrap"><table><caption>{metric}样本统计；金额按显示值计算，CV使用样本标准差</caption><thead><tr><th>类别 / 来源 / 模式</th><th>n</th><th>均值</th><th>中位数</th><th>均值/中位数</th><th>CV</th><th>去除最大值后的均值 / 下降幅度</th><th>产品与限制</th></tr></thead><tbody>{groups.map((group) => <tr key={group.key}>
|
||||
<td>{categories.get(group.category)}<small>{group.provider} · {group.model}</small></td><td>{group.stats.n}</td><td>{usd(group.stats.mean)}</td><td>{usd(group.stats.median)}</td><td>{group.stats.meanMedianRatio?.toFixed(2) ?? "—"}</td><td>{group.stats.cv?.toFixed(2) ?? "—"}</td><td>{usd(group.stats.meanWithoutLargest)}<small>{percent(group.stats.largestRemovalDrop)}</small></td>
|
||||
<div className="research-table-wrap"><table><caption>{metric}样本统计；每行是类别下的一个统计组，CV使用样本标准差</caption><thead><tr><th scope="col">业务类别</th><th scope="col">支付平台 / 收费模式</th><th scope="col">n</th><th scope="col">均值</th><th scope="col">中位数</th><th scope="col">均值/中位数</th><th scope="col">CV</th><th scope="col">去除最大值后的均值 / 下降幅度</th><th scope="col">产品与限制</th></tr></thead>{categoryGroups.map(({ category, rows }) => <tbody key={category}>{rows.map((group, index) => <tr key={group.key}>
|
||||
{index === 0 && <th scope="rowgroup" rowSpan={rows.length}>{categories.get(category)}<small>{rows.length}个统计组</small></th>}
|
||||
<td>{group.provider}<small>{group.model}</small></td><td>{group.stats.n}</td><td>{usd(group.stats.mean)}</td><td>{usd(group.stats.median)}</td><td>{group.stats.meanMedianRatio?.toFixed(2) ?? "—"}</td><td>{group.stats.cv?.toFixed(2) ?? "—"}</td><td>{usd(group.stats.meanWithoutLargest)}<small>{percent(group.stats.largestRemovalDrop)}</small></td>
|
||||
<td>{group.points.map((point) => <span key={point.company.id}><button className="research-company-name" onClick={() => onSelect(point.company.id)}>{point.company.name}</button>{" "}</span>)}<small>{group.stats.n < 3 ? "样本少于3，不能据此判断领域典型收入。" : "自选的小样本，须结合产品年龄、成本与留存评估。"}</small></td>
|
||||
</tr>)}</tbody></table></div>
|
||||
</tr>)}</tbody>)}</table></div>
|
||||
</> : <p className="research-message">当前窗口和创立年份没有符合条件的 MRR 记录。</p>}
|
||||
<details><summary>统计规则与解释</summary><p>每个产品只取符合条件的最新一条平台 MRR；币种为美元，要求有效数据日期、确定数值及支付来源。公司 ARR、估算、融资、目标和近30日收入均不进入这里。未知值不补零。</p><p>CV＝样本标准差÷均值，标准差分母为 n−1；n=1 不算 CV。n=2 时均值必然等于中位数，不能据此认为均值有代表性。较大的均值/中位数差距、CV或移除最大值的变化，仅提示进一步核查样本构成。</p><p>支付商与平台的退款、试用、年付、币种及指标计算可能不同（<a href="https://trustmrr.com/faq" target="_blank" rel="noopener noreferrer">平台方法说明</a>）。不能将 MRR 与收款差异、单个高值或高离散度直接解释为财务造假。比较商业模式还需要毛利、获客成本、留存、人工交付和客户集中度。</p></details>
|
||||
{sample.excluded.length > 0 && <details><summary>未纳入的 MRR 记录（{sample.excluded.length}）</summary><ul>{sample.excluded.map(({ observation, reason }) => <li key={observation.id}><button onClick={() => onSelect(observation.company)}>{observation.name}</button>：{usd(observation.value)} / 月，{observation.observedAt ?? "日期未知"}；{reason}</li>)}</ul></details>}
|
||||
|
||||
@@ -31,7 +31,7 @@ export function Navigation({
|
||||
onNavigate?: () => void;
|
||||
}) {
|
||||
const collection = docs.find((d) => d.slug === current)?.collection;
|
||||
const scopedDocs = docs.filter((d) => d.collection === collection);
|
||||
const scopedDocs = docs.filter((d) => d.collection === collection && d.group !== "归档入口");
|
||||
const groups = [...new Set(scopedDocs.map((d) => d.group))];
|
||||
const collections = collectionEntries(docs);
|
||||
return (
|
||||
|
||||
@@ -43,11 +43,24 @@ export type ResearchCoverage = {
|
||||
otherOrMissingYear: number; unclearAI: number; dateConflicts: number; failedProfiles: number;
|
||||
discoverySha256: string;
|
||||
};
|
||||
export type ResearchCandidateBatch = {
|
||||
id: string; sourceId: string; url: string; accessedAt: string; scope: string; complete: boolean;
|
||||
records: {
|
||||
id: string; name: string; url: string | null; categoryId: string;
|
||||
kind: "product" | "company" | "promotion"; profileStatus: "readable" | "unavailable" | "archive-only";
|
||||
status: "pending-year" | "linked" | "existing-outside-cohort" | "outside-cohort" | "promotion";
|
||||
companyId?: string; evidenceIds?: string[]; note: string;
|
||||
}[];
|
||||
};
|
||||
export type ResearchSnapshot = {
|
||||
version: string; asOf: string; scope: string; limitations: string[];
|
||||
categories: ResearchCategory[]; companies: ResearchCompany[];
|
||||
observations: ResearchObservation[]; evidence: ResearchEvidence[];
|
||||
reviews: ResearchReview[]; coverage?: ResearchCoverage;
|
||||
reviews: ResearchReview[]; coverage?: ResearchCoverage; candidateBatches?: ResearchCandidateBatch[];
|
||||
directoryRechecks?: {
|
||||
ycId: number; originalStatus: "ai-unclear" | "year-outside-or-missing" | "date-conflict";
|
||||
companyId: string; reviewedAt: string; evidenceIds: string[]; reason: string;
|
||||
}[];
|
||||
};
|
||||
|
||||
export function evidenceUrl(value: string): string | undefined {
|
||||
@@ -98,7 +111,40 @@ export function validateResearch(snapshot: ResearchSnapshot) {
|
||||
!Number.isFinite(o.value))
|
||||
throw new Error(`Invalid research observation: ${o.id}`);
|
||||
}
|
||||
unique((snapshot.candidateBatches ?? []).map((b) => b.id), "candidate batches");
|
||||
unique((snapshot.candidateBatches ?? []).flatMap((b) => b.records.map((r) => r.id)), "candidates");
|
||||
for (const batch of snapshot.candidateBatches ?? []) {
|
||||
if (!/^S\d{2}$/.test(batch.sourceId) || !evidenceUrl(batch.url) || !batch.scope.trim() ||
|
||||
typeof batch.complete !== "boolean" || !/^\d{4}-\d{2}-\d{2}$/.test(batch.accessedAt) ||
|
||||
Number.isNaN(Date.parse(batch.accessedAt)) ||
|
||||
new Date(batch.accessedAt).toISOString().slice(0, 10) !== batch.accessedAt ||
|
||||
batch.accessedAt > snapshot.asOf)
|
||||
throw new Error(`Invalid research candidate batch: ${batch.id}`);
|
||||
for (const row of batch.records) {
|
||||
const linked = ["linked", "existing-outside-cohort"].includes(row.status);
|
||||
if (!row.name.trim() || !row.note.trim() || !categories.has(row.categoryId) ||
|
||||
!["product", "company", "promotion"].includes(row.kind) ||
|
||||
!["readable", "unavailable", "archive-only"].includes(row.profileStatus) ||
|
||||
!["pending-year", "linked", "existing-outside-cohort", "outside-cohort", "promotion"].includes(row.status) ||
|
||||
(row.kind !== "promotion" && (!row.url || !evidenceUrl(row.url))) ||
|
||||
(row.url !== null && !evidenceUrl(row.url)) ||
|
||||
linked !== !!row.companyId || (row.companyId && !companies.has(row.companyId)) ||
|
||||
(row.kind === "promotion") !== (row.status === "promotion") ||
|
||||
(row.evidenceIds ?? []).some((id) => !evidence.has(id)) ||
|
||||
(row.status === "outside-cohort" && !row.evidenceIds?.length))
|
||||
throw new Error(`Invalid research candidate: ${row.id}`);
|
||||
}
|
||||
}
|
||||
const coverage = snapshot.coverage;
|
||||
unique((snapshot.directoryRechecks ?? []).map((row) => String(row.ycId)), "directory rechecks");
|
||||
for (const row of snapshot.directoryRechecks ?? []) {
|
||||
if (!Number.isSafeInteger(row.ycId) || row.ycId <= 0 || !companies.has(row.companyId) ||
|
||||
!["ai-unclear", "year-outside-or-missing", "date-conflict"].includes(row.originalStatus) ||
|
||||
!/^\d{4}-\d{2}-\d{2}$/.test(row.reviewedAt) || Number.isNaN(Date.parse(row.reviewedAt)) ||
|
||||
new Date(row.reviewedAt).toISOString().slice(0, 10) !== row.reviewedAt || row.reviewedAt > snapshot.asOf ||
|
||||
!row.reason.trim() || !row.evidenceIds.length || row.evidenceIds.some((id) => !evidence.has(id)))
|
||||
throw new Error(`Invalid directory recheck: ${row.ycId}`);
|
||||
}
|
||||
if (coverage && (coverage.profilesRead + coverage.failedProfiles !== coverage.candidateRecords ||
|
||||
coverage.matchingProfiles !== coverage.existingProfiles + coverage.newProfiles ||
|
||||
coverage.matchingProfiles + coverage.otherOrMissingYear + coverage.unclearAI + coverage.dateConflicts !== coverage.profilesRead ||
|
||||
|
||||
+105
-15
@@ -9,6 +9,9 @@ export type DocLink = {
|
||||
export type Doc = DocLink & { content: string };
|
||||
export type DocInput = Omit<Doc, "revision" | "searchText">;
|
||||
export type DocumentExport = { format: "tabularium-documents-v1"; documents: Doc[] };
|
||||
export class DocumentValidationError extends Error {}
|
||||
export class DocumentConflictError extends Error {}
|
||||
export type DocumentReceipt = Pick<Doc, "slug" | "sourceSlug" | "revision">;
|
||||
export const validSlug = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/;
|
||||
|
||||
function database() {
|
||||
@@ -25,6 +28,10 @@ function database() {
|
||||
document_id TEXT NOT NULL REFERENCES documents(id), revision INTEGER NOT NULL,
|
||||
payload TEXT NOT NULL, created_at TEXT NOT NULL, PRIMARY KEY(document_id, revision)
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS document_write_requests (
|
||||
namespace TEXT NOT NULL, request_id TEXT NOT NULL, digest TEXT NOT NULL,
|
||||
response TEXT NOT NULL, PRIMARY KEY(namespace, request_id)
|
||||
);
|
||||
CREATE TABLE IF NOT EXISTS document_imports (
|
||||
digest TEXT PRIMARY KEY, document_count INTEGER NOT NULL, created_at TEXT NOT NULL
|
||||
);
|
||||
@@ -33,50 +40,51 @@ function database() {
|
||||
}
|
||||
|
||||
export function validateDocument(input: DocInput): void {
|
||||
if (!input || typeof input !== "object") throw Error("Invalid document");
|
||||
if (!input || typeof input !== "object") throw new DocumentValidationError("Invalid document");
|
||||
for (const key of ["slug", "sourceSlug"] as const)
|
||||
if (typeof input[key] !== "string" || !validSlug.test(input[key])) throw Error(`Invalid ${key}`);
|
||||
if (input.slug.split("/").some((part) => /^\d+-/.test(part))) throw Error("Use a semantic public slug");
|
||||
if (typeof input[key] !== "string" || !validSlug.test(input[key])) throw new DocumentValidationError(`Invalid ${key}`);
|
||||
if (input.slug.split("/").some((part) => /^\d+-/.test(part))) throw new DocumentValidationError("Use a semantic public slug");
|
||||
for (const key of ["title", "category", "collection", "group"] as const)
|
||||
if (typeof input[key] !== "string" || !input[key].trim()) throw Error(`Missing ${key}`);
|
||||
if (typeof input[key] !== "string" || !input[key].trim()) throw new DocumentValidationError(`Missing ${key}`);
|
||||
if (typeof input.content !== "string" || typeof input.description !== "string" ||
|
||||
typeof input.draft !== "boolean" || typeof input.featured !== "boolean") throw Error("Invalid document fields");
|
||||
if (input.content.length > 2_000_000) throw Error("Document exceeds content limit");
|
||||
typeof input.draft !== "boolean" || typeof input.featured !== "boolean") throw new DocumentValidationError("Invalid document fields");
|
||||
if (input.content.length > 2_000_000) throw new DocumentValidationError("Document exceeds content limit");
|
||||
const images = [
|
||||
...input.content.matchAll(/!\[[^\]]*\]\(<?([^\s)>]+)/g),
|
||||
...input.content.matchAll(/<img\b[^>]*\bsrc=["']([^"']+)/gi),
|
||||
];
|
||||
if (images.some(([, source]) => /\.(?:png|jpe?g|tiff?|bmp)(?:[?#]|$)/i.test(source)))
|
||||
throw Error("Use compressed WebP images instead of original rasters");
|
||||
throw new DocumentValidationError("Use compressed WebP images instead of original rasters");
|
||||
}
|
||||
|
||||
function write(db: ReturnType<typeof database>, input: DocInput, expectedRevision: number): Doc {
|
||||
validateDocument(input);
|
||||
const existing = db.prepare("SELECT id, revision FROM documents WHERE source_slug=?")
|
||||
.get(input.sourceSlug) as { id: string; revision: number } | undefined;
|
||||
if ((existing?.revision ?? 0) !== expectedRevision) throw Error("Document revision conflict");
|
||||
if ((existing?.revision ?? 0) !== expectedRevision) throw new DocumentConflictError("Document revision conflict");
|
||||
const id = existing?.id ?? randomUUID();
|
||||
const doc: Doc = { slug: input.slug, sourceSlug: input.sourceSlug, category: input.category,
|
||||
title: input.title, group: input.group, collection: input.collection, description: input.description,
|
||||
draft: input.draft, featured: input.featured, content: input.content, revision: expectedRevision + 1 };
|
||||
const payload = JSON.stringify(doc);
|
||||
// Aliases remain reserved after renaming; collision rolls back the whole write.
|
||||
db.prepare(`INSERT INTO documents VALUES (?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET
|
||||
slug=excluded.slug, revision=excluded.revision, payload=excluded.payload`)
|
||||
.run(id, doc.slug, doc.sourceSlug, doc.revision, payload);
|
||||
// Reserve both canonical and historical names before updating any rows.
|
||||
for (const alias of new Set([doc.slug, doc.sourceSlug])) {
|
||||
const prior = db.prepare("SELECT document_id FROM document_aliases WHERE alias=?")
|
||||
.get(alias) as { document_id: string } | undefined;
|
||||
if (prior && prior.document_id !== id) throw Error(`Document alias collision: ${alias}`);
|
||||
db.prepare("INSERT OR IGNORE INTO document_aliases VALUES (?,?)").run(alias, id);
|
||||
if (prior && prior.document_id !== id) throw new DocumentConflictError(`Document alias collision: ${alias}`);
|
||||
}
|
||||
db.prepare(`INSERT INTO documents VALUES (?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET
|
||||
slug=excluded.slug, revision=excluded.revision, payload=excluded.payload`)
|
||||
.run(id, doc.slug, doc.sourceSlug, doc.revision, payload);
|
||||
for (const alias of new Set([doc.slug, doc.sourceSlug]))
|
||||
db.prepare("INSERT OR IGNORE INTO document_aliases VALUES (?,?)").run(alias, id);
|
||||
db.prepare("INSERT INTO document_revisions VALUES (?,?,?,?)")
|
||||
.run(id, doc.revision, payload, new Date().toISOString());
|
||||
return doc;
|
||||
}
|
||||
|
||||
export function saveDocument(input: DocInput, expectedRevision: number): Doc {
|
||||
if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) throw Error("Provide expected revision");
|
||||
if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) throw new DocumentValidationError("Provide expected revision");
|
||||
const db = database();
|
||||
try {
|
||||
db.exec("BEGIN IMMEDIATE");
|
||||
@@ -145,3 +153,85 @@ export function documentHistory(sourceSlug: string): Doc[] {
|
||||
.map((row) => JSON.parse(row.payload) as Doc);
|
||||
} finally { db.close(); }
|
||||
}
|
||||
|
||||
// API batches commit entirely or not at all; receipts make lost-response retries safe.
|
||||
export function saveDocumentBatch(documents: Doc[], request?: { namespace: string; id: string }) {
|
||||
if (!Array.isArray(documents) || !documents.length || documents.length > 100)
|
||||
throw new DocumentValidationError("Provide 1 to 100 documents");
|
||||
const seen = new Set<string>();
|
||||
for (const doc of documents) {
|
||||
validateDocument(doc);
|
||||
if (!Number.isSafeInteger(doc.revision) || doc.revision < 0)
|
||||
throw new DocumentValidationError("Provide expected revision");
|
||||
if (seen.has(doc.sourceSlug)) throw new DocumentValidationError("Duplicate sourceSlug in batch");
|
||||
seen.add(doc.sourceSlug);
|
||||
}
|
||||
if (request && (!request.namespace || !/^[A-Za-z0-9._:-]{1,128}$/.test(request.id)))
|
||||
throw new DocumentValidationError("Invalid Idempotency-Key");
|
||||
const digest = createHash("sha256").update(JSON.stringify(documents)).digest("hex");
|
||||
const db = database();
|
||||
try {
|
||||
db.exec("BEGIN IMMEDIATE");
|
||||
try {
|
||||
if (request) {
|
||||
const prior = db.prepare("SELECT digest,response FROM document_write_requests WHERE namespace=? AND request_id=?")
|
||||
.get(request.namespace, request.id) as { digest: string; response: string } | undefined;
|
||||
if (prior) {
|
||||
if (prior.digest !== digest) throw new DocumentConflictError("Idempotency-Key was used with different content");
|
||||
db.exec("COMMIT");
|
||||
return { documents: JSON.parse(prior.response) as DocumentReceipt[], replayed: true };
|
||||
}
|
||||
}
|
||||
const receipts = documents.map((input) => {
|
||||
const { slug, sourceSlug, revision } = write(db, input, input.revision);
|
||||
return { slug, sourceSlug, revision };
|
||||
});
|
||||
if (request) db.prepare("INSERT INTO document_write_requests VALUES (?,?,?,?)")
|
||||
.run(request.namespace, request.id, digest, JSON.stringify(receipts));
|
||||
db.exec("COMMIT");
|
||||
return { documents: receipts, replayed: false };
|
||||
} catch (error) { db.exec("ROLLBACK"); throw error; }
|
||||
} finally { db.close(); }
|
||||
}
|
||||
|
||||
export function documentPage(limit = 50, offset = 0) {
|
||||
if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(offset) || offset < 0)
|
||||
throw new DocumentValidationError("Invalid pagination");
|
||||
const db = database();
|
||||
try {
|
||||
db.exec("BEGIN");
|
||||
const total = (db.prepare("SELECT COUNT(*) AS n FROM documents").get() as { n: number }).n;
|
||||
const documents = (db.prepare("SELECT json_remove(payload,'$.content') AS payload FROM documents ORDER BY source_slug LIMIT ? OFFSET ?")
|
||||
.all(limit, offset) as { payload: string }[]).map((row) => JSON.parse(row.payload) as DocLink);
|
||||
db.exec("COMMIT");
|
||||
return { documents, total, limit, offset, nextOffset: offset + documents.length < total ? offset + documents.length : null };
|
||||
} finally { db.close(); }
|
||||
}
|
||||
|
||||
export function documentHistoryPage(sourceSlug: string, limit = 50, offset = 0) {
|
||||
if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(offset) || offset < 0)
|
||||
throw new DocumentValidationError("Invalid pagination");
|
||||
const db = database();
|
||||
try {
|
||||
db.exec("BEGIN");
|
||||
const total = (db.prepare(`SELECT COUNT(*) AS n FROM document_revisions r JOIN documents d
|
||||
ON d.id=r.document_id WHERE d.source_slug=?`).get(sourceSlug) as { n: number }).n;
|
||||
const revisions = (db.prepare(`SELECT json_remove(r.payload,'$.content') AS payload, r.created_at AS createdAt
|
||||
FROM document_revisions r JOIN documents d ON d.id=r.document_id
|
||||
WHERE d.source_slug=? ORDER BY r.revision DESC LIMIT ? OFFSET ?`)
|
||||
.all(sourceSlug, limit, offset) as { payload: string; createdAt: string }[])
|
||||
.map((row) => ({ ...JSON.parse(row.payload) as DocLink, createdAt: row.createdAt }));
|
||||
db.exec("COMMIT");
|
||||
return { revisions, total, limit, offset, nextOffset: offset + revisions.length < total ? offset + revisions.length : null };
|
||||
} finally { db.close(); }
|
||||
}
|
||||
|
||||
export function documentRevision(sourceSlug: string, revision: number): Doc | null {
|
||||
if (!Number.isSafeInteger(revision) || revision < 1) throw new DocumentValidationError("Invalid revision");
|
||||
const db = database();
|
||||
try {
|
||||
const row = db.prepare(`SELECT r.payload FROM document_revisions r JOIN documents d
|
||||
ON d.id=r.document_id WHERE d.source_slug=? AND r.revision=?`).get(sourceSlug, revision) as { payload: string } | undefined;
|
||||
return row ? JSON.parse(row.payload) as Doc : null;
|
||||
} finally { db.close(); }
|
||||
}
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
import { createHash, randomBytes, randomUUID } from "node:crypto";
|
||||
import { openSiteDatabase } from "./site-database";
|
||||
|
||||
export type DocumentKeyScope = "read" | "read-write";
|
||||
export type DocumentKey = { id: string; name: string; scope: DocumentKeyScope;
|
||||
createdAt: number; expiresAt: number; revokedAt: number | null; lastUsedAt: number | null };
|
||||
function database() {
|
||||
const db = openSiteDatabase();
|
||||
db.exec(`CREATE TABLE IF NOT EXISTS document_api_keys (
|
||||
id TEXT PRIMARY KEY, name TEXT NOT NULL, digest TEXT NOT NULL UNIQUE,
|
||||
scope TEXT NOT NULL CHECK(scope IN ('read','read-write')), created_at INTEGER NOT NULL,
|
||||
expires_at INTEGER NOT NULL, revoked_at INTEGER, last_used_at INTEGER
|
||||
);`);
|
||||
return db;
|
||||
}
|
||||
export function createDocumentKey(name: string, scope: DocumentKeyScope = "read-write", days = 90) {
|
||||
if (!name.trim() || name.length > 100 || !["read", "read-write"].includes(scope) ||
|
||||
!Number.isSafeInteger(days) || days < 1 || days > 365) throw Error("Invalid key name, scope or lifetime");
|
||||
const id = randomUUID();
|
||||
const token = "tdoc_" + randomBytes(32).toString("base64url");
|
||||
const createdAt = Date.now();
|
||||
const expiresAt = createdAt + days * 86400000;
|
||||
const db = database();
|
||||
try {
|
||||
db.prepare("INSERT INTO document_api_keys(id,name,digest,scope,created_at,expires_at) VALUES (?,?,?,?,?,?)")
|
||||
.run(id, name.trim(), createHash("sha256").update(token).digest("hex"), scope, createdAt, expiresAt);
|
||||
return { id, token, name: name.trim(), scope, createdAt, expiresAt };
|
||||
} finally { db.close(); }
|
||||
}
|
||||
export function authenticateDocumentKey(token: string | undefined, now = Date.now()) {
|
||||
if (!token || !/^tdoc_[A-Za-z0-9_-]{43}$/.test(token)) return null;
|
||||
const db = database();
|
||||
try {
|
||||
const row = db.prepare("SELECT id,scope,last_used_at AS lastUsedAt FROM document_api_keys WHERE digest=? AND revoked_at IS NULL AND expires_at>?")
|
||||
.get(createHash("sha256").update(token).digest("hex"), now) as { id: string; scope: DocumentKeyScope; lastUsedAt: number | null } | undefined;
|
||||
if (!row) return null;
|
||||
if (row.lastUsedAt === null || row.lastUsedAt < now - 60000)
|
||||
db.prepare("UPDATE document_api_keys SET last_used_at=? WHERE id=? AND (last_used_at IS NULL OR last_used_at<?)")
|
||||
.run(now, row.id, now - 60000);
|
||||
return { id: row.id, scope: row.scope };
|
||||
} finally { db.close(); }
|
||||
}
|
||||
export function listDocumentKeys(): DocumentKey[] {
|
||||
const db = database();
|
||||
try {
|
||||
return db.prepare(`SELECT id,name,scope,created_at AS createdAt,expires_at AS expiresAt,
|
||||
revoked_at AS revokedAt,last_used_at AS lastUsedAt FROM document_api_keys ORDER BY created_at,id`).all() as DocumentKey[];
|
||||
} finally { db.close(); }
|
||||
}
|
||||
export function revokeDocumentKey(id: string) {
|
||||
const db = database();
|
||||
try {
|
||||
const result = db.prepare("UPDATE document_api_keys SET revoked_at=COALESCE(revoked_at,?) WHERE id=?").run(Date.now(), id);
|
||||
if (!result.changes) throw Error("Document key not found");
|
||||
} finally { db.close(); }
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
import type { NextApiRequest, NextApiResponse } from "next";
|
||||
import { authenticateDocumentKey } from "./document-keys";
|
||||
import { DocumentConflictError, DocumentValidationError, validateDocument, type Doc } from "./docs";
|
||||
|
||||
export function authorizeDocuments(request: NextApiRequest, response: NextApiResponse, write = false) {
|
||||
response.setHeader("Cache-Control", "private, no-store");
|
||||
response.setHeader("X-Content-Type-Options", "nosniff");
|
||||
const header = request.headers.authorization;
|
||||
const token = typeof header === "string" && header.startsWith("Bearer ") ? header.slice(7) : undefined;
|
||||
const key = authenticateDocumentKey(token);
|
||||
if (!key) {
|
||||
response.status(401).json({ error: "需要有效的文档 API Key", code: "unauthorized" });
|
||||
return null;
|
||||
}
|
||||
if (write && key.scope !== "read-write") {
|
||||
response.status(403).json({ error: "该 API Key 仅允许读取文档", code: "read_only" });
|
||||
return null;
|
||||
}
|
||||
return key;
|
||||
}
|
||||
export function documentApiError(response: NextApiResponse, error: unknown) {
|
||||
if (error instanceof DocumentConflictError)
|
||||
return response.status(409).json({ error: error.message, code: "conflict" });
|
||||
if (error instanceof DocumentValidationError)
|
||||
return response.status(400).json({ error: error.message, code: "invalid_document" });
|
||||
return response.status(503).json({ error: "文档数据库暂时不可用", code: "unavailable" });
|
||||
}
|
||||
export function parseDocument(value: unknown): Doc {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) throw new DocumentValidationError("Expected a document object");
|
||||
const row = value as Record<string, unknown>;
|
||||
const fields = ["slug", "sourceSlug", "title", "category", "collection", "group", "description", "draft", "featured", "content", "revision"];
|
||||
if (Object.keys(row).some((key) => !fields.includes(key))) throw new DocumentValidationError("Unknown document field");
|
||||
const doc = Object.fromEntries(fields.map((key) => [key, row[key]])) as Doc;
|
||||
validateDocument(doc);
|
||||
if (!Number.isSafeInteger(doc.revision) || doc.revision < 0) throw new DocumentValidationError("Provide expected revision");
|
||||
return doc;
|
||||
}
|
||||
export function pagination(request: NextApiRequest) {
|
||||
const number = (value: string | string[] | undefined, fallback: number) => {
|
||||
if (value === undefined) return fallback;
|
||||
if (typeof value !== "string" || !/^\d+$/.test(value)) throw new DocumentValidationError("Invalid pagination");
|
||||
return Number(value);
|
||||
};
|
||||
return { limit: number(request.query.limit, 50), offset: number(request.query.offset, 0) };
|
||||
}
|
||||
export function idempotency(request: NextApiRequest, namespace: string) {
|
||||
const id = request.headers["idempotency-key"];
|
||||
if (id === undefined) return undefined;
|
||||
if (typeof id !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(id)) throw new DocumentValidationError("Invalid Idempotency-Key");
|
||||
return { namespace, id };
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
import type { NextApiRequest, NextApiResponse } from "next";
|
||||
import { DocumentValidationError, saveDocumentBatch } from "@/lib/docs";
|
||||
import { authorizeDocuments, documentApiError, idempotency, parseDocument } from "@/lib/documents-api";
|
||||
|
||||
export const config = { api: { bodyParser: { sizeLimit: "8mb" } } };
|
||||
export default function handler(request: NextApiRequest, response: NextApiResponse) {
|
||||
try {
|
||||
const key = authorizeDocuments(request, response, true);
|
||||
if (!key) return;
|
||||
if (request.method !== "POST") {
|
||||
response.setHeader("Allow", "POST");
|
||||
return response.status(405).end();
|
||||
}
|
||||
const body = request.body;
|
||||
if (!body || typeof body !== "object" || Array.isArray(body) ||
|
||||
Object.keys(body).length !== 1 || !Array.isArray(body.documents) ||
|
||||
!body.documents.length || body.documents.length > 100)
|
||||
throw new DocumentValidationError("Expected { documents: [...] } with 1 to 100 documents");
|
||||
const documents = body.documents.map((row: unknown) => parseDocument(row));
|
||||
return response.status(200).json(saveDocumentBatch(documents, idempotency(request, key.id)));
|
||||
} catch (error) { return documentApiError(response, error); }
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
import type { NextApiRequest, NextApiResponse } from "next";
|
||||
import { documentPage, saveDocumentBatch } from "@/lib/docs";
|
||||
import { authorizeDocuments, documentApiError, idempotency, pagination, parseDocument } from "@/lib/documents-api";
|
||||
|
||||
export const config = { api: { bodyParser: { sizeLimit: "8mb" } } };
|
||||
export default function handler(request: NextApiRequest, response: NextApiResponse) {
|
||||
try {
|
||||
const key = authorizeDocuments(request, response, request.method === "POST");
|
||||
if (!key) return;
|
||||
if (request.method === "GET") {
|
||||
const { limit, offset } = pagination(request);
|
||||
return response.status(200).json(documentPage(limit, offset));
|
||||
}
|
||||
if (request.method === "POST") {
|
||||
const result = saveDocumentBatch([parseDocument(request.body)], idempotency(request, key.id));
|
||||
return response.status(200).json({ document: result.documents[0], replayed: result.replayed });
|
||||
}
|
||||
response.setHeader("Allow", "GET, POST");
|
||||
return response.status(405).end();
|
||||
} catch (error) { return documentApiError(response, error); }
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
import type { NextApiRequest, NextApiResponse } from "next";
|
||||
import { DocumentValidationError, documentHistoryPage, documentRevision, readDocument } from "@/lib/docs";
|
||||
import { authorizeDocuments, documentApiError, pagination } from "@/lib/documents-api";
|
||||
|
||||
export default function handler(request: NextApiRequest, response: NextApiResponse) {
|
||||
try {
|
||||
if (!authorizeDocuments(request, response)) return;
|
||||
if (request.method !== "GET") {
|
||||
response.setHeader("Allow", "GET");
|
||||
return response.status(405).end();
|
||||
}
|
||||
const slug = request.query.slug;
|
||||
if (!Array.isArray(slug)) throw new DocumentValidationError("Invalid document slug");
|
||||
const doc = readDocument(slug.join("/"));
|
||||
if (!doc) return response.status(404).json({ error: "文档不存在", code: "not_found" });
|
||||
if (request.query.revision !== undefined) {
|
||||
if (request.query.history !== undefined || typeof request.query.revision !== "string" || !/^\d+$/.test(request.query.revision))
|
||||
throw new DocumentValidationError("Invalid revision query");
|
||||
const prior = documentRevision(doc.sourceSlug, Number(request.query.revision));
|
||||
if (!prior) return response.status(404).json({ error: "修订不存在", code: "not_found" });
|
||||
return response.status(200).json(prior);
|
||||
}
|
||||
if (request.query.history !== undefined) {
|
||||
if (request.query.history !== "1") throw new DocumentValidationError("Use history=1");
|
||||
const { limit, offset } = pagination(request);
|
||||
return response.status(200).json(documentHistoryPage(doc.sourceSlug, limit, offset));
|
||||
}
|
||||
return response.status(200).json(doc);
|
||||
} catch (error) { return documentApiError(response, error); }
|
||||
}
|
||||
@@ -1,5 +1,6 @@
|
||||
import { NextResponse, type NextRequest } from "next/server";
|
||||
import { authConfig, SESSION_COOKIE, validSession } from "./lib/auth";
|
||||
import { authenticateDocumentKey } from "./lib/document-keys";
|
||||
export function proxy(request: NextRequest) {
|
||||
const path = request.nextUrl.pathname;
|
||||
const headers = {
|
||||
@@ -31,6 +32,14 @@ export function proxy(request: NextRequest) {
|
||||
? authorization.slice(7)
|
||||
: undefined;
|
||||
const token = bearer ?? request.cookies.get(SESSION_COOKIE)?.value;
|
||||
// Document keys are scoped to the document API; they never authenticate other pages or APIs.
|
||||
if (bearer && (path === "/api/documents" || path.startsWith("/api/documents/"))) {
|
||||
try {
|
||||
if (authenticateDocumentKey(bearer)) return NextResponse.next({ headers });
|
||||
} catch {
|
||||
return NextResponse.json({ error: "文档认证暂时不可用" }, { status: 503, headers });
|
||||
}
|
||||
}
|
||||
if (validSession(token, config)) {
|
||||
if (!["GET", "HEAD", "OPTIONS"].includes(request.method) && !bearer) {
|
||||
try {
|
||||
|
||||
@@ -0,0 +1,136 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { test } from "node:test";
|
||||
import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import type { NextApiRequest, NextApiResponse } from "next";
|
||||
import documents from "../src/pages/api/documents/index";
|
||||
import batch from "../src/pages/api/documents/batch";
|
||||
import item from "../src/pages/api/documents/item/[...slug]";
|
||||
import { createDocumentKey, authenticateDocumentKey, revokeDocumentKey, listDocumentKeys } from "../src/lib/document-keys";
|
||||
import { allDocuments, documentHistory, readDocument, saveDocument, type Doc } from "../src/lib/docs";
|
||||
import { newAuthConfig, signSession } from "../src/lib/auth";
|
||||
|
||||
const input: Doc = { slug: "endor/example", sourceSlug: "00-example", title: "Example", category: "Endor",
|
||||
collection: "Endor 文档", group: "讨论", description: "Description", draft: true, featured: false,
|
||||
content: "# Example\n\nOriginal body", revision: 0 };
|
||||
type Options = { method?: string; body?: unknown; headers?: Record<string, string>;
|
||||
query?: Record<string, string | string[]> };
|
||||
function call(handler: (req: NextApiRequest, res: NextApiResponse) => unknown, options: Options = {}) {
|
||||
let status = 200;
|
||||
let body: unknown;
|
||||
const headers: Record<string, string> = {};
|
||||
const response = {
|
||||
status(value: number) { status = value; return this; },
|
||||
setHeader(name: string, value: string) { headers[name.toLowerCase()] = value; return this; },
|
||||
json(value: unknown) { body = value; return this; },
|
||||
end() { return this; },
|
||||
};
|
||||
handler({ method: options.method ?? "GET", body: options.body, headers: options.headers ?? {},
|
||||
query: options.query ?? {} } as unknown as NextApiRequest, response as unknown as NextApiResponse);
|
||||
return { status, body, headers };
|
||||
}
|
||||
function isolated(run: (context: { directory: string; headers: Record<string, string> }) => void) {
|
||||
const directory = mkdtempSync(join(tmpdir(), "tabularium-doc-api-"));
|
||||
const previous = process.env.AUTH_CONFIG_FILE;
|
||||
process.env.AUTH_CONFIG_FILE = join(directory, "config.json");
|
||||
writeFileSync(process.env.AUTH_CONFIG_FILE, JSON.stringify(newAuthConfig()), { mode: 0o600 });
|
||||
try {
|
||||
const key = createDocumentKey("test uploader");
|
||||
run({ directory, headers: { authorization: "Bearer " + key.token } });
|
||||
} finally {
|
||||
if (previous === undefined) delete process.env.AUTH_CONFIG_FILE;
|
||||
else process.env.AUTH_CONFIG_FILE = previous;
|
||||
rmSync(directory, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
test("new API requires document keys, rejects browser cookies and broad web sessions", () => isolated(() => {
|
||||
assert.equal(call(documents).status, 401);
|
||||
assert.equal(call(documents, { headers: { authorization: "Bearer invalid" } }).status, 401);
|
||||
const config = JSON.parse(readFileSync(process.env.AUTH_CONFIG_FILE!, "utf8"));
|
||||
const token = signSession(config);
|
||||
assert.equal(call(documents, { headers: { authorization: "Bearer " + token } }).status, 401);
|
||||
assert.equal(call(documents, { headers: { cookie: "tabularium_session=" + token } }).status, 401);
|
||||
assert.deepEqual(allDocuments(), []);
|
||||
}));
|
||||
|
||||
test("key scopes, revocation, expiry and secret-free listing are persistent", () => isolated(({ directory }) => {
|
||||
const key = createDocumentKey("reader", "read", 1);
|
||||
const headers = { authorization: "Bearer " + key.token };
|
||||
assert.equal(call(documents, { headers }).status, 200);
|
||||
assert.equal(call(documents, { method: "POST", headers, body: input }).status, 403);
|
||||
assert.equal(call(batch, { method: "POST", headers, body: { documents: [input] } }).status, 403);
|
||||
assert.ok(!JSON.stringify(listDocumentKeys()).includes(key.token));
|
||||
assert.ok(!readFileSync(join(directory, "login-state.sqlite")).includes(Buffer.from(key.token)));
|
||||
assert.equal(authenticateDocumentKey(key.token, key.expiresAt), null);
|
||||
revokeDocumentKey(key.id);
|
||||
assert.equal(call(documents, { headers }).status, 401);
|
||||
const revoked = listDocumentKeys().find((row) => row.id === key.id);
|
||||
assert.ok(revoked); assert.equal(typeof revoked.revokedAt, "number");
|
||||
}));
|
||||
|
||||
test("single save, aliases, metadata and historical content are visible without rebuilding", () => isolated(({ headers }) => {
|
||||
assert.equal(call(documents, { method: "POST", headers, body: input }).status, 200);
|
||||
assert.equal((call(item, { headers, query: { slug: input.slug.split("/") } }).body as Doc).revision, 1);
|
||||
const changed = { ...input, revision: 1, slug: "endor/renamed", content: "# Changed", collection: "新合集" };
|
||||
assert.equal(call(documents, { method: "POST", headers, body: changed }).status, 200);
|
||||
assert.equal((call(item, { headers, query: { slug: input.slug.split("/") } }).body as Doc).slug, changed.slug);
|
||||
assert.equal((call(item, { headers, query: { slug: [input.sourceSlug], revision: "1" } }).body as Doc).content, input.content);
|
||||
const history = call(item, { headers, query: { slug: [input.sourceSlug], history: "1", limit: "1" } });
|
||||
const page = history.body as { revisions: Doc[]; total: number; nextOffset: number };
|
||||
assert.equal(page.total, 2);
|
||||
assert.equal(page.nextOffset, 1);
|
||||
assert.equal(page.revisions[0].revision, 2);
|
||||
assert.equal(page.revisions[0].content, undefined);
|
||||
assert.equal(call(item, { headers, query: { slug: [input.sourceSlug], revision: "99" } }).status, 404);
|
||||
assert.equal(call(item, { headers, query: { slug: [input.sourceSlug], revision: "0" } }).status, 400);
|
||||
}));
|
||||
|
||||
test("pagination returns metadata only with strict bounds", () => isolated(({ headers }) => {
|
||||
const second = { ...input, slug: "endor/second", sourceSlug: "01-second" };
|
||||
assert.equal(call(batch, { method: "POST", headers, body: { documents: [input, second] } }).status, 200);
|
||||
const result = call(documents, { headers, query: { limit: "1" } });
|
||||
const page = result.body as { documents: Doc[]; total: number; nextOffset: number };
|
||||
assert.equal(page.total, 2); assert.equal(page.nextOffset, 1);
|
||||
assert.equal(page.documents[0].content, undefined);
|
||||
assert.equal((call(documents, { headers, query: { limit: "1", offset: "1" } }).body as typeof page).documents[0].slug, second.slug);
|
||||
const invalidQueries: Record<string, string | string[]>[] = [
|
||||
{ limit: "101" }, { offset: "-1" }, { limit: ["1", "2"] }, { limit: "1e2" },
|
||||
];
|
||||
for (const query of invalidQueries) assert.equal(call(documents, { headers, query }).status, 400);
|
||||
assert.equal(result.headers["cache-control"], "private, no-store");
|
||||
}));
|
||||
|
||||
test("late batch conflict rolls back earlier rows and their revision history", () => isolated(({ headers }) => {
|
||||
saveDocument({ ...input, slug: "endor/existing", sourceSlug: "existing" }, 0);
|
||||
const conflict = { ...input, slug: "endor/existing", sourceSlug: "existing", revision: 0 };
|
||||
assert.equal(call(batch, { method: "POST", headers, body: { documents: [input, conflict] } }).status, 409);
|
||||
assert.equal(readDocument(input.slug), null);
|
||||
assert.equal(documentHistory(input.sourceSlug).length, 0);
|
||||
assert.equal(documentHistory("existing").length, 1);
|
||||
assert.equal(allDocuments().length, 1);
|
||||
}));
|
||||
|
||||
test("idempotent retries return the original receipt without creating another revision", () => isolated(({ headers }) => {
|
||||
const keyed = { ...headers, "idempotency-key": "upload-1" };
|
||||
const first = call(documents, { method: "POST", headers: keyed, body: input });
|
||||
const second = call(documents, { method: "POST", headers: keyed, body: input });
|
||||
assert.equal(first.status, 200); assert.equal(second.status, 200);
|
||||
assert.equal((second.body as { replayed: boolean }).replayed, true);
|
||||
assert.equal(documentHistory(input.sourceSlug).length, 1);
|
||||
assert.equal(call(documents, { method: "POST", headers: keyed, body: { ...input, content: "Different" } }).status, 409);
|
||||
assert.equal(call(documents, { method: "POST", headers, body: input }).status, 409);
|
||||
}));
|
||||
|
||||
test("invalid batch members, duplicate identifiers, raw images and malformed fields never write", () => isolated(({ headers }) => {
|
||||
for (const body of [{ documents: [] }, { documents: [input, input] },
|
||||
{ documents: [input], unexpected: true }, { documents: Array.from({ length: 101 }, () => input) }])
|
||||
assert.equal(call(batch, { method: "POST", headers, body }).status, 400);
|
||||
for (const body of [{ ...input, revision: undefined }, { ...input, typo: true },
|
||||
{ ...input, slug: "../private" }, { ...input, content: "" }, null])
|
||||
assert.equal(call(documents, { method: "POST", headers, body }).status, 400);
|
||||
assert.deepEqual(allDocuments(), []);
|
||||
assert.equal(call(documents, { method: "DELETE", headers }).status, 405);
|
||||
assert.equal(call(item, { headers, query: { slug: ["missing"] } }).status, 404);
|
||||
}));
|
||||
@@ -23,9 +23,11 @@ test("research revisions share the authentication database and preserve replay l
|
||||
for (let i = 0; i < 20; i++) consumeCode(config, "invalid");
|
||||
assert.equal(consumeCode(config, "invalid"), "limited");
|
||||
const initial = readResearchSnapshot();
|
||||
assert.equal(initial.companies.length, 1015);
|
||||
assert.equal(initial.evidence.length, 1091);
|
||||
assert.equal(initial.observations.length, 183);
|
||||
assert.equal(initial.companies.length, 1023);
|
||||
assert.equal(initial.evidence.length, 1259);
|
||||
assert.equal(initial.observations.length, 189);
|
||||
assert.deepEqual(initial.candidateBatches, seed.candidateBatches, "candidate gaps persist in the same database metadata");
|
||||
assert.deepEqual(initial.directoryRechecks, seed.directoryRechecks, "follow-up classifications persist without rewriting the discovery audit");
|
||||
assert.deepEqual(readResearchSnapshot(), initial, "reopening does not duplicate records");
|
||||
const db = openSiteDatabase();
|
||||
const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
|
||||
@@ -62,9 +64,9 @@ test("research validation rejects broken evidence and unsafe source links", () =
|
||||
|
||||
test("reviews link explicit companies without turning global or excluded cases into companies", () => {
|
||||
const snapshot = structuredClone(seed) as ResearchSnapshot;
|
||||
assert.equal(snapshot.reviews.filter((r) => r.scope === "companies").length, 43);
|
||||
assert.equal(snapshot.reviews.filter((r) => r.scope === "dataset").length, 3);
|
||||
assert.equal(snapshot.reviews.filter((r) => r.scope === "excluded-candidate").length, 8);
|
||||
assert.equal(snapshot.reviews.filter((r) => r.scope === "companies").length, 60);
|
||||
assert.equal(snapshot.reviews.filter((r) => r.scope === "dataset").length, 9);
|
||||
assert.equal(snapshot.reviews.filter((r) => r.scope === "excluded-candidate").length, 29);
|
||||
const review = snapshot.reviews.find((r) => r.id === "R4")!;
|
||||
assert.deepEqual(reviewCompanyIds(snapshot, review), ["AI007", "AI013", "AI021", "AI034"]);
|
||||
assert.deepEqual(reviewCompanyIds(snapshot, snapshot.reviews.find((r) => r.id === "CN-R-PSI")!), []);
|
||||
@@ -83,11 +85,11 @@ test("reviews link explicit companies without turning global or excluded cases i
|
||||
test("disclosure counts exclude client income, biographies, targets and duplicate milestones", () => {
|
||||
const snapshot = seed as ResearchSnapshot;
|
||||
const summary = categorySummary(snapshot);
|
||||
assert.equal(summary.reduce((n, c) => n + c.count, 0), 1015);
|
||||
assert.equal(summary.reduce((n, c) => n + c.count, 0), 1023);
|
||||
assert.equal(summary.reduce((n, c) => n + c.self, 0), 26);
|
||||
assert.equal(summary.reduce((n, c) => n + c.estimate, 0), 1);
|
||||
assert.equal(summary.reduce((n, c) => n + c.platform, 0), 16);
|
||||
assert.equal(summary.reduce((n, c) => n + c.unknown, 0), 972);
|
||||
assert.equal(summary.reduce((n, c) => n + c.unknown, 0), 980);
|
||||
assert.equal(snapshot.companies.find((c) => c.name === "Rork")?.revenueStatus, "unknown");
|
||||
assert.equal(snapshot.companies.find((c) => c.name === "Result")?.revenueStatus, "unknown");
|
||||
assert.ok(snapshot.observations.filter((o) => o.selection === "signal").every((o) => o.scope === "公司整体"));
|
||||
@@ -95,8 +97,8 @@ test("disclosure counts exclude client income, biographies, targets and duplicat
|
||||
|
||||
test("technical reviews keep accessible materials separate from tested capabilities", () => {
|
||||
const snapshot = structuredClone(seed) as ResearchSnapshot;
|
||||
assert.equal(snapshot.companies.filter((c) => c.technicalReview).length, 7);
|
||||
assert.equal(snapshot.companies.filter((c) => c.technicalReview?.level === "public-artifact").length, 3);
|
||||
assert.equal(snapshot.companies.filter((c) => c.technicalReview).length, 16);
|
||||
assert.equal(snapshot.companies.filter((c) => c.technicalReview?.level === "public-artifact").length, 6);
|
||||
assert.equal(snapshot.companies.filter((c) => c.technicalReview?.level === "independent-test").length, 1);
|
||||
assert.equal(snapshot.companies.find((c) => c.id === "AI051")?.revenueStatus, "unknown");
|
||||
assert.match(snapshot.companies.find((c) => c.id === "AI051")!.technicalReview!.testScope!, /Sep 2026/);
|
||||
@@ -149,7 +151,14 @@ test("retracted ARR and projected margins remain excluded", () => {
|
||||
const forecast = snapshot.observations.find((o) => o.kind === "非GAAP毛利率预期")!;
|
||||
assert.equal(forecast.selection, "excluded");
|
||||
const peec = snapshot.companies.find((c) => c.name === "Peec AI")!;
|
||||
assert.equal(peec.teamBound, ">");
|
||||
assert.equal(peec.team, 100);
|
||||
assert.equal(peec.teamBound, "≥");
|
||||
const currentTeam = snapshot.observations.find((o) => o.id === "PEEC-JOB-TEAM")!;
|
||||
assert.equal(currentTeam.value, peec.team);
|
||||
assert.equal(currentTeam.bound, peec.teamBound);
|
||||
const historicalTeam = snapshot.observations.find((o) => o.id === "O067")!;
|
||||
assert.equal(historicalTeam.value, 70);
|
||||
assert.equal(historicalTeam.bound, ">");
|
||||
assert.equal(snapshot.observations.filter((o) => o.company === peec.id && o.selection === "signal").length, 1);
|
||||
assert.ok(snapshot.observations.some((o) => o.company === peec.id && o.selection === "historical-estimate"));
|
||||
});
|
||||
@@ -255,3 +264,88 @@ test("distribution statistics match independently calculated snapshot references
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
test("product launch candidates preserve unresolved years and many launches per company", () => {
|
||||
const snapshot = structuredClone(seed) as ResearchSnapshot;
|
||||
const batch = snapshot.candidateBatches![0];
|
||||
assert.equal(batch.complete, false);
|
||||
assert.equal(batch.records.length, 19);
|
||||
const kilo = batch.records.filter((r) => r.companyId === "AI072");
|
||||
assert.equal(kilo.length, 2, "IDE and hosted products resolve to one company");
|
||||
assert.equal(snapshot.companies.filter((c) => c.id === "AI072").length, 1);
|
||||
assert.ok(batch.records.some((r) => r.status === "pending-year" && !r.companyId));
|
||||
assert.ok(batch.records.some((r) => r.status === "existing-outside-cohort" && r.companyId === "AI054"));
|
||||
kilo[0].companyId = "missing-company";
|
||||
assert.throws(() => validateResearch(snapshot), /research candidate/);
|
||||
});
|
||||
|
||||
test("annual launch archives exclude older companies only with evidence and reuse existing records", () => {
|
||||
const snapshot = structuredClone(seed) as ResearchSnapshot;
|
||||
const batch = snapshot.candidateBatches!.find((b) => b.id === "PH-2025-visible-1")!;
|
||||
assert.equal(batch.complete, false);
|
||||
assert.equal(batch.records.length, 19);
|
||||
const older = batch.records.filter((r) => r.status === "outside-cohort");
|
||||
assert.equal(older.length, 16);
|
||||
assert.ok(older.every((r) => !r.companyId && r.evidenceIds?.length));
|
||||
assert.equal(batch.records.find((r) => r.name === "Trace")?.companyId, "YC30687");
|
||||
const trace = snapshot.companies.find((c) => c.id === "YC30687")!;
|
||||
assert.equal(trace.profileOnly, false);
|
||||
assert.equal(trace.directoryOrigin, "yc-2025-2026");
|
||||
assert.equal(trace.revenueStatus, "unknown");
|
||||
assert.ok(!snapshot.observations.some((o) => o.evidence === "TRACE-HOME"), "demo metrics must not become reported results");
|
||||
older[0].evidenceIds = [];
|
||||
assert.throws(() => validateResearch(snapshot), /research candidate/);
|
||||
older[0].evidenceIds = ["missing-proof"];
|
||||
assert.throws(() => validateResearch(snapshot), /research candidate/);
|
||||
});
|
||||
|
||||
test("unreconciled directory financials remain source reviews instead of income observations", () => {
|
||||
const snapshot = seed as ResearchSnapshot;
|
||||
const review = snapshot.reviews.find((r) => r.id === "PH-R-SOURCE-QUALITY")!;
|
||||
assert.equal(review.scope, "dataset");
|
||||
assert.ok(review.evidenceIds.includes("PH-TANA-DR"));
|
||||
assert.equal(reviewCompanyIds(snapshot, review).length, 0);
|
||||
assert.ok(!snapshot.observations.some((o) => o.evidence === "PH-TANA-DR"));
|
||||
assert.equal(snapshot.candidateBatches!.flatMap((b) => b.records).filter((r) => r.status === "pending-year").length, 8);
|
||||
});
|
||||
|
||||
test("product pivots and founder histories do not become new company years or current revenue", () => {
|
||||
const snapshot = seed as ResearchSnapshot;
|
||||
const pivot = snapshot.companies.find((c) => c.id === "AI073")!;
|
||||
assert.equal(pivot.year, null, "CRM launch is not a verified company founding year");
|
||||
assert.equal(pivot.revenueStatus, "unknown");
|
||||
const candidate = snapshot.candidateBatches!.flatMap((b) => b.records).find((r) => r.id === "PH26-11")!;
|
||||
assert.equal(candidate.status, "existing-outside-cohort");
|
||||
assert.equal(candidate.companyId, pivot.id);
|
||||
assert.ok(!platformIncomeSample(snapshot, { windowDays: null }).points.some((point) => point.company.id === pivot.id));
|
||||
assert.ok(!snapshot.observations.some((o) => ["PH-FUNDRAISLY-ABOUT", "LF-PIVOT", "LF-HISTORY"].includes(o.evidence)), "other ventures' ARR, users and funding must not transfer");
|
||||
});
|
||||
|
||||
test("follow-up evidence can admit an uncertain directory candidate without rewriting its original status", () => {
|
||||
const snapshot = structuredClone(seed) as ResearchSnapshot;
|
||||
const followup = snapshot.directoryRechecks!.find((row) => row.ycId === 36088)!;
|
||||
const original = coverageAudit.records.find((row) => row.ycId === followup.ycId)!;
|
||||
assert.equal(original.status, "ai-unclear");
|
||||
assert.equal(followup.originalStatus, original.status);
|
||||
assert.equal(snapshot.companies.find((c) => c.id === followup.companyId)?.year, 2026);
|
||||
assert.equal(snapshot.candidateBatches!.flatMap((b) => b.records).find((r) => r.name === "OpenSEO")?.companyId, followup.companyId);
|
||||
assert.ok(!snapshot.observations.some((o) => ["SEO-PRICE", "UP-YC", "PAZI-PRICE"].includes(o.evidence)), "pricing, other ventures' ARR and prepaid balances stay outside income observations");
|
||||
followup.companyId = "missing-company";
|
||||
assert.throws(() => validateResearch(snapshot), /directory recheck/);
|
||||
});
|
||||
|
||||
test("Chinese discovery entries preserve unread articles and use separate primary evidence", () => {
|
||||
const snapshot = structuredClone(seed) as ResearchSnapshot;
|
||||
const batch = snapshot.candidateBatches!.find((b) => b.id === "JQ-2026-targeted-1")!;
|
||||
assert.equal(batch.complete, false);
|
||||
assert.equal(batch.records.length, 4);
|
||||
assert.ok(batch.records.every((row) => row.kind === "company" && row.profileStatus === "unavailable"));
|
||||
assert.equal(batch.records.filter((row) => row.status === "linked").length, 2);
|
||||
assert.equal(batch.records.find((row) => row.name === "Utopai")?.status, "outside-cohort");
|
||||
assert.ok(!snapshot.observations.some((o) => ["PS-CODE", "SG-START", "SG-APR", "SSI-HISTORY"].includes(o.evidence)), "task costs, investment, capacity and financing are not revenue");
|
||||
const prism = snapshot.companies.find((c) => c.id === "AI075")!;
|
||||
assert.equal(prism.team, null, "a team range or linked employees must not become exact headcount");
|
||||
batch.records[0].url = null;
|
||||
assert.throws(() => validateResearch(snapshot), /research candidate/);
|
||||
});
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,295 @@
|
||||
{
|
||||
"version": "2026-10-30-19",
|
||||
"scopeConfirmedAt": "2026-10-30",
|
||||
"acceptance": "以确认的公开来源清单为边界，逐条核对并标明缺项。",
|
||||
"provenance": "S01—S12恢复自已提交用户的《AI公司研究_来源与分类模板》来源清单；S13—S16单列后续已使用的补充证据渠道，不将使用次数当作全量覆盖。",
|
||||
"sources": [
|
||||
{
|
||||
"id": "S01",
|
||||
"name": "Y Combinator",
|
||||
"url": "https://www.ycombinator.com/companies",
|
||||
"role": "discovery",
|
||||
"status": "candidate-audit",
|
||||
"hosts": [
|
||||
"www.ycombinator.com"
|
||||
],
|
||||
"initialAccess": "官网目录可访问",
|
||||
"boundary": "已读取八个2025—2026批次镜像候选池1428条，再核YC官方页面；不声称覆盖全部YC历年或未公开公司。",
|
||||
"nextCheck": "当前快照三条原待分类经官网方向补证归类；继续复核规则初分、具体产品与财务缺项，不把领域粗分类当独立能力或收入验证。",
|
||||
"limitation": "批次不等于成立年；不代表全部公司"
|
||||
},
|
||||
{
|
||||
"id": "S02",
|
||||
"name": "TechCrunch AI",
|
||||
"url": "https://techcrunch.com/category/artificial-intelligence/",
|
||||
"role": "reporting",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"techcrunch.com"
|
||||
],
|
||||
"initialAccess": "AI栏目可读取",
|
||||
"boundary": "栏目首页选择的3条公司线索已追溯原始资料：Wabi据公开名录2025年份、Thrive Holdings据公司主页2025自述关联公司，DreamHQ成立年仍待核。Thrive控股改造与收购/有机收入边界单列；非首页全部条目或两年档案，公开分类接口与RSS普通HTTP请求返回403。 已补读2025年度档案入口、AI第二页，并从2025企业竞赛报道定向核5条：复用1条、范围外1条、待核3条；不是完整32项名单或两年全量。",
|
||||
"nextCheck": "沿已验证可读的普通2025档案及AI分页继续补台账；记录未读分页，补DreamHQ、Billow、Cashew Research和Zinnia成立与主体依据，区分竞赛年、批次、产品和公司成立年。",
|
||||
"limitation": "需追溯原始披露，部分文章受访问限制",
|
||||
"accessRecheckedAt": "2026-10-30"
|
||||
},
|
||||
{
|
||||
"id": "S03",
|
||||
"name": "Dealroom",
|
||||
"url": "https://dealroom.co/",
|
||||
"role": "discovery",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"dealroom.co",
|
||||
"app.dealroom.co"
|
||||
],
|
||||
"initialAccess": "官网可读取",
|
||||
"boundary": "已读Tana与Wabi公开公司档案：前者财务字段不一致留缺，后者2025成立字段与官方业务关联入表；尚未取得两年成立筛选结果集，两个个案不等于目录全量。",
|
||||
"nextCheck": "确认公开可取得的两年成立筛选清单；逐项追溯财务原始凭证及字段口径，受权限限制保留缺项。",
|
||||
"limitation": "完整档案需权限；概览及财务表不能未经勾稽直接导入ARR",
|
||||
"accessRecheckedAt": "2026-10-30"
|
||||
},
|
||||
{
|
||||
"id": "S04",
|
||||
"name": "Product Hunt",
|
||||
"url": "https://www.producthunt.com/",
|
||||
"role": "discovery",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"www.producthunt.com",
|
||||
"producthunt.com"
|
||||
],
|
||||
"initialAccess": "官网可读取",
|
||||
"boundary": "两年公开响应各19条，共38条。当前5条关联公司、2条范围外对照、25条范围外/既有业务、4条年份待核、2条推广。旧版本、品牌与法律主体分开，Tapflow据2024原版记录排除，Happycapy仍待核；非两年全量。",
|
||||
"nextCheck": "继续补两年其余分页/日期、仅图片位置及4条年份待核候选；保留Pazi日期冲突，核清品牌与主体，避免转移历史业绩。",
|
||||
"limitation": "上线时间不等于成立时间",
|
||||
"accessRecheckedAt": "2026-10-30"
|
||||
},
|
||||
{
|
||||
"id": "S05",
|
||||
"name": "Sacra",
|
||||
"url": "https://sacra.com/",
|
||||
"role": "estimation",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"sacra.com"
|
||||
],
|
||||
"initialAccess": "官网可读取",
|
||||
"boundary": "已用于定向估算及日期口径交叉核查；无全站公司名录读取台账。",
|
||||
"nextCheck": "保留估算与公司披露差异，核实历史截至日。",
|
||||
"limitation": "部分付费；不能把估算当审计数"
|
||||
},
|
||||
{
|
||||
"id": "S06",
|
||||
"name": "Bessemer",
|
||||
"url": "https://www.bvp.com/atlas/the-state-of-ai-2025",
|
||||
"role": "context",
|
||||
"status": "context",
|
||||
"hosts": [
|
||||
"www.bvp.com",
|
||||
"bvp.com"
|
||||
],
|
||||
"initialAccess": "报告页面可读取",
|
||||
"boundary": "主动选取20家高增长AI企业，含组合内外公司；非随机普查；已核方法与增长/毛利基准段；未取得20家逐公司底表。仅背景基准，不构成两年新公司名录。",
|
||||
"nextCheck": "高增长选样和投资机构利益关系；不能把头部样本均值当各领域平均或新成立公司总体；需要公开可核底表时另补，不把缺项当已完成。",
|
||||
"limitation": "投资机构选样偏差",
|
||||
"accessRecheckedAt": "2026-10-30",
|
||||
"methodology": {
|
||||
"sample": "主动选取20家高增长AI企业，含组合内外公司；非随机普查",
|
||||
"unit": "企业增长与毛利基准，按商业化后的第几年比较",
|
||||
"period": "2025-08-13报告；商业化年数不等法律成立年",
|
||||
"access": "已核方法与增长/毛利基准段；未取得20家逐公司底表",
|
||||
"use": "用于提出留存、毛利、资本效率假设及分类线索",
|
||||
"limit": "高增长选样和投资机构利益关系；不能把头部样本均值当各领域平均或新成立公司总体",
|
||||
"evidenceIds": [
|
||||
"CTX-BVP"
|
||||
],
|
||||
"checkedAt": "2026-10-30"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "S07",
|
||||
"name": "Menlo Ventures",
|
||||
"url": "https://menlovc.com/perspective/2025-the-state-of-generative-ai-in-the-enterprise/",
|
||||
"role": "context",
|
||||
"status": "context",
|
||||
"hosts": [
|
||||
"menlovc.com",
|
||||
"www.menlovc.com"
|
||||
],
|
||||
"initialAccess": "报告页面可读取",
|
||||
"boundary": "495名美国企业AI采购/开发决策者，企业已主动使用AI；已核公开方法、范围及限制；受访个体与公司估算底表未取得。仅背景基准，不构成两年新公司名录。",
|
||||
"nextCheck": "仅美国企业；排除芯片、推理/模型服务及既有软件内嵌AI功能，不能与包含这些项目的总量直接比较或分摊为单家公司ARR；需要公开可核底表时另补，不把缺项当已完成。",
|
||||
"limitation": "口径与样本需查看方法说明",
|
||||
"accessRecheckedAt": "2026-10-30",
|
||||
"methodology": {
|
||||
"sample": "495名美国企业AI采购/开发决策者，企业已主动使用AI",
|
||||
"unit": "采购调查与自下而上的市场支出估算，非公司逐项ARR",
|
||||
"period": "2025-11-07至11-25调查，市场判断截至2025-12",
|
||||
"access": "已核公开方法、范围及限制；受访个体与公司估算底表未取得",
|
||||
"use": "用于买家、采购方式和任务方向假设",
|
||||
"limit": "仅美国企业；排除芯片、推理/模型服务及既有软件内嵌AI功能，不能与包含这些项目的总量直接比较或分摊为单家公司ARR",
|
||||
"evidenceIds": [
|
||||
"CTX-MENLO"
|
||||
],
|
||||
"checkedAt": "2026-10-30"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "S08",
|
||||
"name": "Stripe",
|
||||
"url": "https://stripe.com/annual-updates/2025",
|
||||
"role": "context",
|
||||
"status": "context",
|
||||
"hosts": [
|
||||
"stripe.com",
|
||||
"www.stripe.com",
|
||||
"assets.stripeassets.com"
|
||||
],
|
||||
"initialAccess": "年度信可读取",
|
||||
"boundary": "2025年开始使用Stripe的商户分组，另有Atlas注册企业分组；已读并视觉核对PDF第1、3页；未取得商户明细与完整分组计算底表。仅背景基准，不构成两年新公司名录。",
|
||||
"nextCheck": "开始使用平台不等成立年，也非AI公司专属样本；交易量不等Stripe收入，门槛数量翻倍不等ARR均值翻倍；不与TrustMRR公开者样本混算；需要公开可核底表时另补，不把缺项当已完成。",
|
||||
"limitation": "平台样本不能代表全部AI公司",
|
||||
"accessRecheckedAt": "2026-10-30",
|
||||
"methodology": {
|
||||
"sample": "2025年开始使用Stripe的商户分组，另有Atlas注册企业分组",
|
||||
"unit": "平台交易量、商户增长及达到收入门槛的数量；分母不同",
|
||||
"period": "2025年度；2026-02-24年度信",
|
||||
"access": "已读并视觉核对PDF第1、3页；未取得商户明细与完整分组计算底表",
|
||||
"use": "用于支付、全球市场及首次收费速度假设",
|
||||
"limit": "开始使用平台不等成立年，也非AI公司专属样本；交易量不等Stripe收入，门槛数量翻倍不等ARR均值翻倍；不与TrustMRR公开者样本混算",
|
||||
"evidenceIds": [
|
||||
"CTX-STRIPE"
|
||||
],
|
||||
"checkedAt": "2026-10-30"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "S09",
|
||||
"name": "SaaS Capital",
|
||||
"url": "https://www.saas-capital.com/research/",
|
||||
"role": "context",
|
||||
"status": "context",
|
||||
"hosts": [
|
||||
"www.saas-capital.com",
|
||||
"saas-capital.com"
|
||||
],
|
||||
"initialAccess": "研究页可读取",
|
||||
"boundary": "第15次年度调查，超过1000家私营B2B SaaS公司；仅读公开摘要；完整下载需填写表单，未提交表单或取得完整底表。仅背景基准，不构成两年新公司名录。",
|
||||
"nextCheck": "样本不是两年新AI公司；增长率中位数不能当ARR中位数；完整抽样与指标细节仍缺，不外推至硬件、项目服务或所有AI模式；需要公开可核底表时另补，不把缺项当已完成。",
|
||||
"limitation": "不直接套用硬件与项目制业务",
|
||||
"accessRecheckedAt": "2026-10-30",
|
||||
"methodology": {
|
||||
"sample": "第15次年度调查，超过1000家私营B2B SaaS公司",
|
||||
"unit": "2025年度增长率与留存等公开摘要；非ARR金额分布",
|
||||
"period": "2026报告回顾2025增长；不把报告年当公司成立年",
|
||||
"access": "仅读公开摘要；完整下载需填写表单，未提交表单或取得完整底表",
|
||||
"use": "用于B2B订阅软件的规模、融资和留存分层假设",
|
||||
"limit": "样本不是两年新AI公司；增长率中位数不能当ARR中位数；完整抽样与指标细节仍缺，不外推至硬件、项目服务或所有AI模式",
|
||||
"evidenceIds": [
|
||||
"CTX-SAASCAP"
|
||||
],
|
||||
"checkedAt": "2026-10-30"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "S10",
|
||||
"name": "机器之心",
|
||||
"url": "https://www.jiqizhixin.com/",
|
||||
"role": "reporting",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"www.jiqizhixin.com",
|
||||
"jiqizhixin.com",
|
||||
"pro.jiqizhixin.com"
|
||||
],
|
||||
"initialAccess": "首页可读取",
|
||||
"boundary": "已登记4篇定向检索线索；三篇直达仅登录外壳，一篇读取失败。2项经公开原始资料关联公司，SSI与Utopai经原始历史材料判为范围外，0项成立年待核；未阅读全文或穷尽两年档案。",
|
||||
"nextCheck": "补公开可读文章及2025—2026档案；受限正文留缺，不以搜索摘录代全文，更名与产品发布不新增公司。",
|
||||
"limitation": "全文访问受限；仅作发现时明确标识，技术和财务另追原始资料",
|
||||
"accessRecheckedAt": "2026-10-30"
|
||||
},
|
||||
{
|
||||
"id": "S11",
|
||||
"name": "36氪",
|
||||
"url": "https://www.36kr.com/",
|
||||
"role": "reporting",
|
||||
"status": "access-limited",
|
||||
"hosts": [
|
||||
"www.36kr.com",
|
||||
"36kr.com"
|
||||
],
|
||||
"initialAccess": "安全检测，内容未核验",
|
||||
"boundary": "2026-10-30仍返回安全检测页面，未把首页作为已读文章。",
|
||||
"nextCheck": "使用可公开读取的具体文章或其他原始来源；不绕过访问保护。",
|
||||
"limitation": "暂不作为已读取内容证据",
|
||||
"accessRecheckedAt": "2026-10-30"
|
||||
},
|
||||
{
|
||||
"id": "S12",
|
||||
"name": "公司官网与官方博客",
|
||||
"url": null,
|
||||
"role": "primary",
|
||||
"status": "per-company",
|
||||
"hosts": [],
|
||||
"initialAccess": "按公司逐一核验",
|
||||
"boundary": "公司官网和官方材料逐条绑定证据；不是可预先列尽的全站候选池。",
|
||||
"nextCheck": "核定价、主体、交付与收入定义，自述与独立验证分开。",
|
||||
"limitation": "自述不等于独立审计"
|
||||
},
|
||||
{
|
||||
"id": "S13",
|
||||
"name": "TrustMRR",
|
||||
"url": "https://trustmrr.com/",
|
||||
"role": "platform",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"trustmrr.com"
|
||||
],
|
||||
"initialAccess": "见具体证据访问记录",
|
||||
"boundary": "已采集产品与支付快照；公开者自选，不是全部商户或独立财务审计。",
|
||||
"nextCheck": "核同步日、连接失效、支付平台公式及产品/法人归属。",
|
||||
"limitation": "来源可读不等于声明已独立验证。"
|
||||
},
|
||||
{
|
||||
"id": "S14",
|
||||
"name": "a16z Speedrun",
|
||||
"url": "https://speedrun.a16z.com/",
|
||||
"role": "investor",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"speedrun.a16z.com"
|
||||
],
|
||||
"initialAccess": "见具体证据访问记录",
|
||||
"boundary": "投资机构公司介绍定向样本，收入数字仍多来自公司。",
|
||||
"nextCheck": "核币种、相对时间及管线/履历；未读取的页面保持缺项。",
|
||||
"limitation": "来源可读不等于声明已独立验证。"
|
||||
},
|
||||
{
|
||||
"id": "S15",
|
||||
"name": "Artificial Analysis",
|
||||
"url": "https://artificialanalysis.ai/",
|
||||
"role": "technical",
|
||||
"status": "targeted",
|
||||
"hosts": [
|
||||
"artificialanalysis.ai"
|
||||
],
|
||||
"initialAccess": "见具体证据访问记录",
|
||||
"boundary": "第三方已发表技术评测，仅覆盖所列模型版本和任务。",
|
||||
"nextCheck": "核榜单版本、测评方法及置信区间，不将排名变成企业整体能力。",
|
||||
"limitation": "来源可读不等于声明已独立验证。"
|
||||
},
|
||||
{
|
||||
"id": "S16",
|
||||
"name": "其他公开补充资料",
|
||||
"url": null,
|
||||
"role": "supplement",
|
||||
"status": "targeted",
|
||||
"hosts": [],
|
||||
"initialAccess": "见具体证据访问记录",
|
||||
"boundary": "未归入上述来源的公开材料按原始证据链接逐条保留；不视为新增已批准的完整候选池。",
|
||||
"nextCheck": "逐项核来源归属、可靠性及可读正文，不能将搜索摘要当全文。",
|
||||
"limitation": "来源可读不等于声明已独立验证。"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"sourceVersion": "2026-10-30-depth-4",
|
||||
"sourceVersion": "2026-10-30-archives-1",
|
||||
"asOf": "2026-10-30",
|
||||
"metric": "platform-mrr-usd",
|
||||
"sampleUnit": "product-or-business",
|
||||
|
||||
@@ -9,11 +9,142 @@ from urllib.parse import urlsplit
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
DATA = json.loads((ROOT / 'content/research/ai-companies.seed.json').read_text())
|
||||
AUDIT = json.loads((ROOT / 'content/research/ai-companies.coverage.json').read_text())
|
||||
SOURCES = json.loads((ROOT / 'content/research/ai-companies.sources.json').read_text())
|
||||
TARGET = ROOT / '.artifacts/reports/02-coverage-and-gaps.md'
|
||||
SOURCE_SLUG = 'ai-company-research/02-coverage-and-gaps'
|
||||
|
||||
BASE = '/docs/other-research/ai-company-research/overview'
|
||||
|
||||
|
||||
|
||||
def source_register():
|
||||
sources = SOURCES['sources']
|
||||
ids = {s['id'] for s in sources}
|
||||
assert len(ids) == len(sources) and ids == {f'S{i:02}' for i in range(1, 17)}
|
||||
assert SOURCES['scopeConfirmedAt'] <= DATA['asOf']
|
||||
host_map = {}
|
||||
for source in sources:
|
||||
assert source['status'] in {'candidate-audit', 'targeted', 'pending', 'context', 'access-limited', 'per-company'}
|
||||
assert source['boundary'] and source['nextCheck']
|
||||
if source['url']:
|
||||
assert urlsplit(source['url']).scheme in {'http', 'https'} and urlsplit(source['url']).netloc
|
||||
for host in source['hosts']:
|
||||
assert host not in host_map, f'Duplicate source host: {host}'
|
||||
host_map[host] = source['id']
|
||||
assigned = {key: [] for key in ids}
|
||||
for evidence in DATA['evidence']:
|
||||
owner = host_map.get(urlsplit(evidence['url']).netloc)
|
||||
if owner is None:
|
||||
owner = 'S12' if any(word in evidence['kind'] for word in ('官方', '公司自述', '公司披露')) else 'S16'
|
||||
assigned[owner].append(evidence)
|
||||
assert sum(len(v) for v in assigned.values()) == len(DATA['evidence'])
|
||||
statuses = {'candidate-audit': '候选池逐条已读', 'targeted': '定向使用，未穷尽', 'pending': '候选台账待建',
|
||||
'context': '背景研究', 'access-limited': '访问受限', 'per-company': '随公司逐条核对'}
|
||||
lines = ['', '## 来源清单与验收边界', '', SOURCES['provenance'], '',
|
||||
'每条证据在下表只计入一个渠道：先按所列域名归属，再将类型明确标为官方/公司自述/公司披露的剩余项计入S12，其余计入S16。公司可跨渠道出现，所以公司数不可跨行相加。零条证据表示尚未进入研究表，不表示该来源没有相关公司。背景报告不承担公司发现全集的角色。', '',
|
||||
'| 来源 | 当前状态 | 证据 / 公司 / 观测数 | 已核对范围 | 剩余核查 |', '| --- | --- | --- | --- | --- |']
|
||||
for source in sources:
|
||||
evidence = assigned[source['id']]
|
||||
evidence_ids = {e['id'] for e in evidence}
|
||||
company_ids = {e['companyId'] for e in evidence if e['companyId']}
|
||||
observations = sum(o['evidence'] in evidence_ids for o in DATA['observations'])
|
||||
name = f"[{source['name']}]({source['url']})" if source['url'] else source['name']
|
||||
lines.append(f"| {source['id']} {name} | {statuses[source['status']]} | {len(evidence)} / {len(company_ids)} / {observations} | {source['boundary']} | {source['nextCheck']} |")
|
||||
lines += ['', 'Dealroom、Product Hunt、机器之心与36氪入口于2026-10-30重新访问。官网首页可读不证明已取得完整筛选结果；安全检测页面不作为文章内容。候选池之外的来源边界尚需建立可回查条目，完成前不宣布来源清单已全部覆盖。', '']
|
||||
return lines
|
||||
|
||||
|
||||
|
||||
def context_methods():
|
||||
evidence = {e['id']: e for e in DATA['evidence']}
|
||||
rows = [s for s in SOURCES['sources'] if s.get('methodology')]
|
||||
assert {s['id'] for s in rows} == {'S06', 'S07', 'S08', 'S09'}
|
||||
lines = ['', '## 背景基准适用性与缺项', '',
|
||||
'以下核对背景资料的方法及适用范围，不是公司名录的完整覆盖。原始方法记录与全局核查随研究版本进入同一数据库；没有把行业汇总值新增为任何公司的收入观测。', '',
|
||||
'| 来源与证据 | 样本与统计单位 | 时间 | 本次读取范围 | 可用于什么 | 主要限制 |',
|
||||
'| --- | --- | --- | --- | --- | --- |']
|
||||
for source in rows:
|
||||
m = source['methodology']
|
||||
assert m['checkedAt'] <= DATA['asOf']
|
||||
assert all(m.get(key) for key in ('sample', 'unit', 'period', 'access', 'use', 'limit', 'evidenceIds'))
|
||||
assert all(eid in evidence and evidence[eid]['companyId'] is None for eid in m['evidenceIds'])
|
||||
assert not any(o['evidence'] in m['evidenceIds'] for o in DATA['observations'])
|
||||
proof = '、'.join(f"[{eid}]({evidence[eid]['url']})" for eid in m['evidenceIds'])
|
||||
lines.append(f"| {source['id']} {source['name']}：{proof} | {m['sample']}；{m['unit']} | {m['period']} | {m['access']} | {m['use']} | {m['limit']} |")
|
||||
lines += ['', '本表的应用解释属于研究判断。选样、分母、时间或指标不同会造成表观差异；这些差异不单独证明财务造假，也不能作为给未知公司填补收入的依据。', '']
|
||||
return lines
|
||||
|
||||
|
||||
def candidate_register():
|
||||
batches = DATA.get('candidateBatches', [])
|
||||
companies = {c['id']: c for c in DATA['companies']}
|
||||
categories = {c['id']: c['name'] for c in DATA['categories']}
|
||||
known_sources = {s['id'] for s in SOURCES['sources']}
|
||||
evidence = {e['id']: e for e in DATA['evidence']}
|
||||
assert len({b['id'] for b in batches}) == len(batches)
|
||||
all_ids = [r['id'] for b in batches for r in b['records']]
|
||||
assert len(set(all_ids)) == len(all_ids)
|
||||
lines = []
|
||||
statuses = {'pending-year': '成立年待核', 'linked': '已关联公司',
|
||||
'existing-outside-cohort': '已有关联，年份范围外',
|
||||
'outside-cohort': '范围外或既有业务，不新增公司', 'promotion': '推广活动，非公司新增'}
|
||||
for batch in batches:
|
||||
assert batch['sourceId'] in known_sources
|
||||
assert batch['accessedAt'] <= DATA['asOf']
|
||||
assert any(e['url'] == batch['url'] for e in DATA['evidence'])
|
||||
rows = batch['records']
|
||||
counts = Counter(r['status'] for r in rows)
|
||||
assert sum(counts.values()) == len(rows)
|
||||
lines += ['', f"## {batch['sourceId']} 候选核对（{batch['id']}）", '',
|
||||
f"[发现页面]({batch['url']})，读取于{batch['accessedAt']}。{batch['scope']}", '',
|
||||
f"本批{len(rows)}条：{counts['linked']}条关联公司、{counts['existing-outside-cohort']}条关联范围外对照、{counts['outside-cohort']}条范围外不新增公司、{counts['pending-year']}条成立年待核、{counts['promotion']}条推广活动。完整来源覆盖标记：{'已完成' if batch['complete'] else '未完成'}。主营或产品任务的初分类不计入主公司表数量，只有已关联的公司记录进入对应公司明细。候选与缺项随研究版本保存在文档站同一SQLite的研究元数据中。", '',
|
||||
'| 发现条目 | 主营或产品任务初分 | 核对状态 | 关联公司 | 核对证据 | 限制 |', '| --- | --- | --- | --- | --- | --- |']
|
||||
for row in rows:
|
||||
assert row['categoryId'] in categories
|
||||
assert row['status'] in statuses
|
||||
assert all(eid in evidence for eid in row.get('evidenceIds', []))
|
||||
if row['status'] == 'outside-cohort':
|
||||
assert row.get('evidenceIds') and not row.get('companyId')
|
||||
name = f"[{row['name']}]({row['url']})" if row['url'] else row['name']
|
||||
company = '—'
|
||||
if row.get('companyId'):
|
||||
assert row['companyId'] in companies
|
||||
c = companies[row['companyId']]
|
||||
company = f"[{c['name']}]({BASE}?company={c['id']}#research-company-detail)"
|
||||
proof = '、'.join(f"[{eid}]({evidence[eid]['url']})" for eid in row.get('evidenceIds', [])) or '成立证据待补，产品页读取状态见候选记录'
|
||||
category = f"[{categories[row['categoryId']]}]({BASE}?category={row['categoryId']})"
|
||||
lines.append(f"| {name} | {category} | {statuses[row['status']]} | {company} | {proof} | {row['note']} |")
|
||||
if batch['sourceId'] == 'S04':
|
||||
lines += ['', '产品页可读只表示有可访问的资料；本批未将所有产品页完成公司、技术或财务深查。既有直接HTTP采集返回403，当前采用可读的公开页面响应，不声称取得底层全量列表；后续公开档案与未读页面继续保留缺项。', '']
|
||||
else:
|
||||
lines += ['', '发现条目和可读正文分开记录；登录外壳、读取失败或搜索摘录不充当已阅读全文。关联公司以列出的原始材料补证，仍保留技术、主体与收入未核事项。', '']
|
||||
return lines
|
||||
|
||||
|
||||
def directory_rechecks():
|
||||
rows = DATA.get('directoryRechecks', [])
|
||||
if not rows:
|
||||
return []
|
||||
original = {row['ycId']: row for row in AUDIT['records']}
|
||||
companies = {c['id']: c for c in DATA['companies']}
|
||||
evidence = {e['id']: e for e in DATA['evidence']}
|
||||
assert len({row['ycId'] for row in rows}) == len(rows)
|
||||
lines = ['', '## 原候选池的后续复核', '',
|
||||
'原始1,428条读取快照与初筛计数保持不变；下表记录当时未入表、后续补足证据后进入公司表的项目。初筛未通过不是永久排除。后续入表不回写为当时已匹配，也不重复计入928条原始新增目录项。', '',
|
||||
'| 原候选 | 原始状态 | 后续公司记录 | 复核证据 | 处理与限制 |', '| --- | --- | --- | --- | --- |']
|
||||
for row in rows:
|
||||
baseline = original[row['ycId']]
|
||||
assert baseline['status'] == row['originalStatus']
|
||||
assert row['reviewedAt'] <= DATA['asOf'] and row['reason']
|
||||
assert row['originalStatus'] in {'ai-unclear', 'year-outside-or-missing', 'date-conflict'}
|
||||
company = companies[row['companyId']]
|
||||
assert row['evidenceIds'] and all(eid in evidence for eid in row['evidenceIds'])
|
||||
proof = '、'.join(f"[{eid}]({evidence[eid]['url']})" for eid in row['evidenceIds'])
|
||||
lines.append(f"| [{baseline['name']} · YC{row['ycId']}]({baseline['source']}) | {row['originalStatus']} | [{company['name']}]({BASE}?company={company['id']}#research-company-detail) | {proof} | {row['reviewedAt']}：{row['reason']} |")
|
||||
lines += ['', f"已记录{len(rows)}条后续复核入表；其余未入表候选仍按原状态保留缺项，不能把这一批复核视为完成全部模糊项。", '']
|
||||
return lines
|
||||
|
||||
|
||||
def render():
|
||||
cov = DATA['coverage']
|
||||
companies = DATA['companies']
|
||||
@@ -86,6 +217,10 @@ def render():
|
||||
lines.append(f"| {name} | {len(entries)} | {len({e['url'] for e in entries})} | {note} |")
|
||||
others = [e for e in DATA['evidence'] if urlsplit(e['url']).netloc not in included]
|
||||
lines.append(f"| 其他官网、评测及公开资料 | {len(others)} | {len({e['url'] for e in others})} | 按每条来源限制理解，不能统一当作独立证据 |")
|
||||
lines += directory_rechecks()
|
||||
lines += source_register()
|
||||
lines += context_methods()
|
||||
lines += candidate_register()
|
||||
lines += ['', '## 尚未满足的研究条件', '',
|
||||
'行业ARR比较仍缺统一业务截止日、币种、经常性定义和业务边界。现有平台MRR可描述已采集产品，不足以代表全部新公司。技术评测只覆盖所列版本与任务，不宜跨领域汇总为统一强弱分数。', '',
|
||||
'下一轮优先补收入线索的日期及合同定义、非YC和非英文来源、规则初分的人工复核，以及停止服务或被收购案例。这样能减少“只见赢家”和“只见融资公司”的偏差。公开来源池之外的未披露公司仍无法证明已被穷尽。', '',
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
set -eu
|
||||
cd /opt/endorphin-tabularium-docs/current
|
||||
case "${1:-}" in
|
||||
list|get|save|history|export|backup|import)
|
||||
list|get|save|history|export|backup|import|key-create|key-list|key-revoke)
|
||||
docker compose -p endorphin-tabularium-docs --env-file /etc/endorphin-tabularium-docs/production.env --env-file release.env -f compose.yml exec -T docs node apps/docs/docs-cli.cjs "$@" ;;
|
||||
*) echo 'Usage: docs list | get <slug> | save < JSON | history <sourceSlug> | export <private-file> | backup <private-file> | import < JSON' >&2; exit 1 ;;
|
||||
*) echo 'Usage: docs key-create <name> <private-file> [read|read-write] [days] | key-list | key-revoke <id> | list | get <slug> | save < JSON | history <sourceSlug> | export <private-file> | backup <private-file> | import < JSON' >&2; exit 1 ;;
|
||||
esac
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
"""Upload documents through the database API; credentials stay in a private file."""
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
import stat
|
||||
import sys
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
import uuid
|
||||
|
||||
|
||||
class DocumentClientError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
class NoRedirect(urllib.request.HTTPRedirectHandler):
|
||||
def redirect_request(self, req, fp, code, msg, headers, newurl):
|
||||
# Never forward a bearer credential to a redirected host or protocol.
|
||||
return None
|
||||
|
||||
|
||||
def server_url(value):
|
||||
parsed = urllib.parse.urlsplit(value)
|
||||
if (parsed.username or parsed.password or parsed.query or parsed.fragment
|
||||
or parsed.path not in ('', '/') or not parsed.hostname):
|
||||
raise ValueError('Provide a server origin without credentials, path, query or fragment')
|
||||
if parsed.scheme != 'https' and not (
|
||||
parsed.scheme == 'http' and parsed.hostname in ('localhost', '127.0.0.1', '::1')):
|
||||
raise ValueError('Use HTTPS or an HTTP loopback connection through a trusted SSH tunnel')
|
||||
return value.rstrip('/')
|
||||
|
||||
|
||||
def read_token(filename):
|
||||
path = Path(filename)
|
||||
if stat.S_IMODE(path.stat().st_mode) & 0o077:
|
||||
raise ValueError('API key file must be private (chmod 600)')
|
||||
value = path.read_text().strip()
|
||||
if value.startswith('{'):
|
||||
value = json.loads(value)['token']
|
||||
if not isinstance(value, str) or not value.startswith('tdoc_') or len(value) != 48:
|
||||
raise ValueError('Invalid document API key file')
|
||||
return value
|
||||
|
||||
|
||||
def request(base, token, method, path, payload=None, request_id=None):
|
||||
data = None if payload is None else json.dumps(payload, ensure_ascii=False).encode()
|
||||
if data is not None and len(data) > 8 * 1024 * 1024:
|
||||
raise ValueError('Request exceeds 8 MiB; split into smaller atomic batches')
|
||||
headers = {'Authorization': 'Bearer ' + token, 'Accept': 'application/json'}
|
||||
if data is not None:
|
||||
headers['Content-Type'] = 'application/json'
|
||||
headers['Idempotency-Key'] = request_id
|
||||
opener = urllib.request.build_opener(NoRedirect())
|
||||
for attempt in range(2):
|
||||
req = urllib.request.Request(base + path, data=data, method=method, headers=headers)
|
||||
try:
|
||||
with opener.open(req, timeout=30) as response:
|
||||
return json.load(response)
|
||||
except urllib.error.HTTPError as error:
|
||||
if error.code in (502, 503, 504) and attempt == 0:
|
||||
error.close()
|
||||
time.sleep(1)
|
||||
continue
|
||||
status = error.code
|
||||
error.close()
|
||||
explanations = {400: 'Invalid document or pagination', 401: 'Key missing, expired or revoked',
|
||||
403: 'Read-only key', 404: 'Document or revision not found',
|
||||
409: 'Revision or request-id conflict; read current state before retrying',
|
||||
413: 'Request too large', 503: 'Database unavailable'}
|
||||
raise DocumentClientError(f'HTTP {status}: ' + explanations.get(status, 'Request failed')) from None
|
||||
except (urllib.error.URLError, TimeoutError):
|
||||
if attempt == 0:
|
||||
time.sleep(1)
|
||||
continue
|
||||
raise DocumentClientError('Connection failed; retry using the same request id and unchanged input') from None
|
||||
|
||||
|
||||
def document_batches(documents, max_bytes=8 * 1024 * 1024):
|
||||
if not isinstance(documents, list) or not documents:
|
||||
raise DocumentClientError('Provide a nonempty documents array')
|
||||
batches, chunk, size, seen = [], [], 20, set()
|
||||
for document in documents:
|
||||
if not isinstance(document, dict) or not isinstance(document.get('sourceSlug'), str):
|
||||
raise DocumentClientError('Every document needs a sourceSlug')
|
||||
if document['sourceSlug'] in seen:
|
||||
raise DocumentClientError('Duplicate sourceSlug in upload')
|
||||
seen.add(document['sourceSlug'])
|
||||
encoded = len(json.dumps(document, ensure_ascii=False).encode()) + 2
|
||||
if encoded + 20 > max_bytes:
|
||||
raise DocumentClientError('A document exceeds the request limit')
|
||||
if chunk and (len(chunk) == 100 or size + encoded > max_bytes):
|
||||
batches.append(chunk)
|
||||
chunk, size = [], 20
|
||||
chunk.append(document)
|
||||
size += encoded
|
||||
batches.append(chunk)
|
||||
return batches
|
||||
|
||||
|
||||
def main():
|
||||
os.umask(0o077)
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument('--url', default=os.environ.get('TABULARIUM_DOCS_URL'))
|
||||
parser.add_argument('--key-file', default=os.environ.get('TABULARIUM_DOCS_KEY_FILE'))
|
||||
sub = parser.add_subparsers(dest='command', required=True)
|
||||
listing = sub.add_parser('list')
|
||||
listing.add_argument('--limit', type=int, default=50)
|
||||
listing.add_argument('--offset', type=int, default=0)
|
||||
reading = sub.add_parser('get')
|
||||
reading.add_argument('slug')
|
||||
mode = reading.add_mutually_exclusive_group()
|
||||
mode.add_argument('--history', action='store_true')
|
||||
mode.add_argument('--revision', type=int)
|
||||
reading.add_argument('--limit', type=int, default=50)
|
||||
reading.add_argument('--offset', type=int, default=0)
|
||||
saving = sub.add_parser('save')
|
||||
saving.add_argument('file', help='Private JSON file or - for stdin; one document or {documents: [...]}')
|
||||
saving.add_argument('--request-id', help='Reuse this id only with the same input when retrying')
|
||||
args = parser.parse_args()
|
||||
if not args.url or not args.key_file:
|
||||
parser.error('Set --url and --key-file or TABULARIUM_DOCS_URL and TABULARIUM_DOCS_KEY_FILE')
|
||||
try:
|
||||
base = server_url(args.url)
|
||||
token = read_token(args.key_file)
|
||||
if args.command == 'list':
|
||||
result = request(base, token, 'GET', '/api/documents?' + urllib.parse.urlencode(
|
||||
{'limit': args.limit, 'offset': args.offset}))
|
||||
elif args.command == 'get':
|
||||
path = '/api/documents/item/' + urllib.parse.quote(args.slug, safe='/')
|
||||
if args.history:
|
||||
path += '?' + urllib.parse.urlencode({'history': 1, 'limit': args.limit, 'offset': args.offset})
|
||||
elif args.revision is not None:
|
||||
path += '?' + urllib.parse.urlencode({'revision': args.revision})
|
||||
result = request(base, token, 'GET', path)
|
||||
else:
|
||||
payload = json.load(sys.stdin) if args.file == '-' else json.loads(Path(args.file).read_text())
|
||||
request_id = args.request_id or str(uuid.uuid4())
|
||||
if not request_id or len(request_id) > 100 or any(c not in 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._:-' for c in request_id):
|
||||
raise ValueError('Invalid request id')
|
||||
print('Request id: ' + request_id, file=sys.stderr)
|
||||
if isinstance(payload, dict) and 'documents' in payload:
|
||||
if set(payload) != {'documents'}:
|
||||
raise DocumentClientError('Batch payload must contain only documents')
|
||||
chunks = document_batches(payload['documents'])
|
||||
receipts, replayed = [], 0
|
||||
for index, chunk in enumerate(chunks, 1):
|
||||
batch_id = f'{request_id}:{index}'
|
||||
saved = request(base, token, 'POST', '/api/documents/batch', {'documents': chunk}, batch_id)
|
||||
receipts.extend(saved['documents'])
|
||||
replayed += int(saved['replayed'])
|
||||
print(f'Batch {index}/{len(chunks)} committed; {len(receipts)} documents total; request id: {batch_id}', file=sys.stderr)
|
||||
result = {'documents': receipts, 'batches': len(chunks), 'replayedBatches': replayed, 'requestId': request_id}
|
||||
else:
|
||||
result = request(base, token, 'POST', '/api/documents', payload, request_id)
|
||||
print(json.dumps(result, ensure_ascii=False, indent=2))
|
||||
except DocumentClientError as error:
|
||||
raise SystemExit(str(error)) from None
|
||||
except (ValueError, OSError, KeyError, TypeError):
|
||||
# Never print exception objects that could contain credentials or document data.
|
||||
raise SystemExit('Document request failed. Check the URL, private key file, JSON schema and server response; credentials omitted.') from None
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
@@ -7,14 +7,15 @@ import re
|
||||
import subprocess
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
BASELINE = '25c5e83d08eae4277fe429a692955bd3bb2e717f' # Last main revision before database-backed documents.
|
||||
BASELINE = 'cffca6942b1bc0005321e1685f38593fb0b853d5' # Integration snapshot before database migration.
|
||||
RESEARCH_REVISION = '74af205b2959e1bb6a1fe9f567bc87069ac6d12c' # Final PR 14 update received during integration.
|
||||
|
||||
|
||||
def export(ref):
|
||||
commit = subprocess.check_output(['git', 'rev-parse', '--verify', ref + '^{commit}'], cwd=ROOT, text=True).strip()
|
||||
|
||||
def read(name):
|
||||
return subprocess.check_output(['git', 'show', f'{commit}:{name}'], cwd=ROOT).decode()
|
||||
def read(name, revision=commit):
|
||||
return subprocess.check_output(['git', 'show', f'{revision}:{name}'], cwd=ROOT).decode()
|
||||
|
||||
catalog = json.loads(read('content/catalog.json'))
|
||||
names = subprocess.check_output(['git', 'ls-tree', '-r', '--name-only', commit, '--', 'content/docs'], cwd=ROOT, text=True).splitlines()
|
||||
@@ -23,7 +24,8 @@ def export(ref):
|
||||
source = name.removeprefix('content/docs/').removesuffix('.md')
|
||||
metadata = catalog['documents'][source]
|
||||
collection = next(c for c in catalog['collections'] if not c['path'] or source.startswith(c['path'] + '/'))
|
||||
content = read(name)
|
||||
revision = RESEARCH_REVISION if commit == BASELINE and source.startswith("ai-company-research/") else commit
|
||||
content = read(name, revision)
|
||||
title = re.search(r'^# (.+)$', content, re.M)
|
||||
documents.append(dict(slug=metadata['slug'], sourceSlug=source, category=metadata['category'],
|
||||
title=title[1].strip() if title else source, content=content,
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
"""Lightweight client tests: no HTTP server, compilation or real credentials."""
|
||||
import importlib.util
|
||||
import io
|
||||
import json
|
||||
from pathlib import Path
|
||||
import tempfile
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
|
||||
spec = importlib.util.spec_from_file_location('documents_client', Path(__file__).with_name('documents-client.py'))
|
||||
client = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(client)
|
||||
|
||||
|
||||
class ClientTests(unittest.TestCase):
|
||||
def test_only_tls_or_loopback_origins_are_accepted(self):
|
||||
self.assertEqual(client.server_url('https://docs.example/'), 'https://docs.example')
|
||||
self.assertEqual(client.server_url('http://127.0.0.1:18135'), 'http://127.0.0.1:18135')
|
||||
for url in ['http://docs.example', 'https://user:secret@docs.example', 'file:///tmp/data',
|
||||
'https://docs.example/api', 'https://docs.example/?token=secret']:
|
||||
with self.assertRaises(ValueError):
|
||||
client.server_url(url)
|
||||
|
||||
def test_key_file_permissions_and_formats(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
path = Path(directory) / 'key.json'
|
||||
token = 'tdoc_' + 'x' * 43
|
||||
path.write_text(json.dumps({'token': token}))
|
||||
path.chmod(0o600)
|
||||
self.assertEqual(client.read_token(path), token)
|
||||
path.chmod(0o644)
|
||||
with self.assertRaises(ValueError):
|
||||
client.read_token(path)
|
||||
|
||||
def test_redirects_never_forward_bearer_credentials(self):
|
||||
request = urllib.request.Request('https://docs.example', headers={'Authorization': 'Bearer test-only'})
|
||||
self.assertIsNone(client.NoRedirect().redirect_request(request, None, 302, '', {}, 'https://other.example'))
|
||||
|
||||
def test_network_retry_preserves_idempotency_and_body(self):
|
||||
calls = []
|
||||
|
||||
class Opener:
|
||||
def open(self, request, timeout):
|
||||
calls.append(request)
|
||||
if len(calls) == 1:
|
||||
raise urllib.error.URLError('temporary network failure')
|
||||
return io.BytesIO(b'{"replayed":true}')
|
||||
|
||||
with patch.object(client.urllib.request, 'build_opener', return_value=Opener()), patch.object(client.time, 'sleep'):
|
||||
result = client.request('https://docs.example', 'test-token', 'POST', '/api/documents', {'revision': 0}, 'request-1')
|
||||
self.assertTrue(result['replayed'])
|
||||
self.assertEqual(calls[0].data, calls[1].data)
|
||||
self.assertEqual(calls[0].get_header('Idempotency-key'), 'request-1')
|
||||
self.assertEqual(calls[1].get_header('Idempotency-key'), 'request-1')
|
||||
|
||||
def test_large_uploads_are_split_by_count_and_bytes(self):
|
||||
documents = [{'sourceSlug': str(i), 'content': 'a' * 20} for i in range(201)]
|
||||
batches = client.document_batches(documents)
|
||||
self.assertEqual([len(batch) for batch in batches], [100, 100, 1])
|
||||
self.assertEqual([doc for batch in batches for doc in batch], documents)
|
||||
bounded = client.document_batches(documents[:5], max_bytes=150)
|
||||
self.assertTrue(all(len(json.dumps({'documents': batch}, ensure_ascii=False).encode()) <= 150 for batch in bounded))
|
||||
|
||||
def test_duplicate_identifiers_and_oversized_items_fail_before_upload(self):
|
||||
with self.assertRaises(ValueError):
|
||||
client.document_batches([{'sourceSlug': 'same'}, {'sourceSlug': 'same'}])
|
||||
with self.assertRaises(ValueError):
|
||||
client.document_batches([{'sourceSlug': 'one', 'content': 'a' * 500}], max_bytes=100)
|
||||
|
||||
def test_conflict_is_reported_without_printing_server_content_or_secret(self):
|
||||
class Opener:
|
||||
def open(self, request, timeout):
|
||||
raise urllib.error.HTTPError(request.full_url, 409, 'Conflict', {}, io.BytesIO(b'{"error":"private-content"}'))
|
||||
|
||||
with patch.object(client.urllib.request, 'build_opener', return_value=Opener()):
|
||||
with self.assertRaisesRegex(client.DocumentClientError, 'HTTP 409') as result:
|
||||
client.request('https://docs.example', 'private-token', 'POST', '/api/documents', {}, 'request-1')
|
||||
self.assertNotIn('private-token', str(result.exception))
|
||||
self.assertNotIn('private-content', str(result.exception))
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user