Zayden-Jung/endorphin-tabularium-docs
1
1
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: add scoped document API and resumable batch uploader

Browse Source
This commit is contained in:
Codex Bot
2026-10-30 18:14:33 +08:00
parent 0c2a909521
commit 6bfeea4e7e
16 changed files with 826 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+68 -2
View File
@@ -8,7 +8,7 @@ Endor 的文档站与 AI 公司研究工作台，包含文档阅读、全文搜
| 内容 | 权威来源与维护方式 |
| --- | --- |
| 文档正文、分类、合集、分组、摘要、草案和推荐状态 | 数据库；通过服务器上的 `docs` 管理工具读写 |
| 文档正文、分类、合集、分组、摘要、草案和推荐状态 | 数据库；通过文档 API 或服务器上的 `docs` 管理工具读写 |
| 文档旧地址与修订历史 | 数据库；改名保留别名，修改追加修订 |
| AI 公司、观测、证据、候选与核查记录 | `content/research` 中的版本化快照；服务端显式按版本导入同库后查询 |
| 页面、组件、管理工具和部署逻辑 | 本仓库，通过工作分支与 PR 评审 |
@@ -32,7 +32,7 @@ Endor 的文档站与 AI 公司研究工作台，包含文档阅读、全文搜
## 管理文档
部署后，管理员可在服务器上使用 `/opt/endorphin-tabularium-docs/docs`。该工具在当前容器中操作数据库，需要服务器运维权限；站点没有公开的文档写入 API。
部署后，管理员可在服务器上使用 `/opt/endorphin-tabularium-docs/docs`。该工具在当前容器中操作数据库，需要服务器运维权限。自动化上传使用下文的文档 API，日常读写无需登录服务器。
```sh
sudo /opt/endorphin-tabularium-docs/docs list
@@ -63,6 +63,72 @@ sudo /opt/endorphin-tabularium-docs/docs save < "$doc_work_dir/document.json"
保存成功后，正文、目录和搜索通过后续请求读取新内容。发生版本冲突时重新读取并合并修改，不能仅改大 `revision` 覆盖并发编辑。调整分类或分组也走同一保存流程；`history` 使用稳定的 `sourceSlug` 查询修订。
## 文档上传 API
文档 API 直接读写同一个数据库，供自动化整理和大量文档上传使用。它只接受独立的文档 API Key，不接受网页 Cookie 或通用网页会话令牌；Key 不能用于研究、登录或其他站点 API。
| 方法与地址 | 用途 |
| --- | --- |
| `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
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>
```
创建命令将完整 Key 写入认证私有目录中的指定新文件，权限 `0600`，终端仅输出 ID、权限和到期信息。文件已存在时拒绝覆盖。权限可选 `read` 或 `read-write`；有效期默认 90 天，可设 1—365 天。数据库仅保存 Key 摘要，列表不返回原文；撤销后不能继续认证。独立 Key 文件和认证 config.json 都不包含在 SQLite 整库备份中。
### 使用上传客户端
`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。
## 研究数据与检查
研究工作台提供公司筛选、经营指标、原始证据、收费与交付模式、技术材料及核查记录。它区分公司披露、支付平台指标、第三方估算、融资和客户收益；未知收入不填零，材料可访问也不代表性能或商业效果已经验证。研究范围、样本限制和个案结论以工作台记录为准。