188 lines
18 KiB
Markdown
188 lines
18 KiB
Markdown
# Endor · Tabularium
|
||
|
||
Endor 文档站、研究工作台与制图程序。应用代码在 Git 中评审；全部文档正文、目录元数据和内容修订以站点 SQLite 数据库为唯一权威源。日常写作不需要 commit、构建或部署。
|
||
|
||
## 存储与读取
|
||
|
||
沿用 `AUTH_CONFIG_FILE` 同目录的 `login-state.sqlite` 和 `/auth` 持久挂载。`documents` 存正文及分类、合集、分组、摘要、草案与推荐状态；`document_aliases` 保留旧地址；`document_revisions` 保存每次修改；`document_imports` 标记一次性迁移。没有第二套文档数据库。
|
||
|
||
首页、阅读页、目录和全文搜索按请求查询数据库，使用 `private, no-store`。旧文件式地址与改名前的语义地址通过数据库别名跳转，保留查询参数；不再在构建阶段枚举文档。Markdown 原文通过受认证保护的 `/api/documents/source?slug=...` 获取。
|
||
|
||
仓库不保存日常正文、目录 JSON、数据库文件或内容快照；历史 Git 记录仅用于迁移。页面不再读取 `content/docs` 或 `content/catalog.json`。Markdown 与 GFM 表格仍可用，不解析原始 HTML。图片在写入时检查压缩格式；图形程序与版本化静态资源仍在代码仓库，本轮不迁移媒体存储。研究业务数据留待下一步。
|
||
|
||
## 在服务器上管理文档
|
||
|
||
部署安装 `/opt/endorphin-tabularium-docs/docs`，通过当前容器执行管理 CLI。需要服务器的运维权限；不增加可公开写入的 API，不改变现有动态码登录。
|
||
|
||
```sh
|
||
sudo /opt/endorphin-tabularium-docs/docs list
|
||
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 等字段。
|
||
|
||
```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
|
||
```
|
||
|
||
路径仅为操作示例，应选择实际存在且受保护的目录。运行成功后刷新网页即可看到正文、导航和搜索更新。版本冲突时重新读取并合并修改；不要把旧 revision 改成新数字强行覆盖。草案是现有展示标记，不是按分支或用户隔离的访问控制。
|
||
|
||
新增正文不提交回 Git。奇思妙想这类内容同样通过数据库写入；代码分支与数据发布是不同动作，不能因为迁移程序合并就自动发布其他未合并分支的内容。
|
||
|
||
## 首次迁移与备份
|
||
|
||
迁移前主线的 50 篇正文及目录可从固定历史提交 `25c5e83d08eae4277fe429a692955bd3bb2e717f` 完整导出：
|
||
|
||
```sh
|
||
python3 scripts/export-legacy-documents.py --output .artifacts/documents-migration.json
|
||
```
|
||
|
||
导出文件位于 Git 忽略目录、权限 0600，不进入镜像。脚本也支持显式 `--ref`，但不能用未评审分支替换生产迁移基线。它不会在站点读取时执行。CI 使用历史导出验证全部正文与目录的逐项一致性，构建镜像只含程序，不含文档快照或数据库。
|
||
|
||
首次部署先备份整个共享数据库，再显式事务导入到空文档表。普通部署使用 `import --if-empty`，已有内容时跳过，不以历史数据覆盖数据库编辑；重复同一导入也不会重置内容。导入失败则事务整体回滚，既有登录与研究表保留，部署中止。
|
||
|
||
```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 只导出当前正文与目录，作为空库初始化/外部迁移快照，不代替完整备份或恢复修订历史。输出路径均在容器内，文件已存在时拒绝覆盖。备份含认证状态，应留在私有挂载或受控备份位置，不能放到公开静态目录、仓库或日志。
|
||
|
||
代码回退不会撤销数据库编辑，但回退到旧文件式站点会显示旧正文。恢复完整数据库会同时影响登录和研究状态，必须先停止写入、保留当前备份并由管理员明确选择恢复点；部署脚本不会自动恢复数据库或删除新内容。
|
||
|
||
## 代码验证
|
||
|
||
使用 React、Next.js Pages Router、TypeScript 和 Tailwind CSS。JavaScript 用 pnpm，制图 Python 用 uv。编译、构建、打包和构建产物全部在已确认的 ces-control Runner 执行；`pnpm test:docs` 等测试脚本会调用 esbuild，也只能在 Runner 执行。
|
||
|
||
工作分支与 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管理：
|
||
|
||
```sh
|
||
sudo /opt/endorphin-tabularium-docs/auth qr
|
||
sudo /opt/endorphin-tabularium-docs/auth verify
|
||
```
|
||
|
||
`qr`只允许交互终端显示；`qr-png`用于通过SSH将PNG直接重定向到私有本地文件，不在CI中运行。二维码等同登录凭据，不放入本仓库或网页。只有明确执行 `auth rotate --confirm` 才更换密钥并使旧二维码、会话失效；重新显示或下载二维码不会轮换。
|
||
|
||
构建、打包与会触发构建的测试只在用户确认的 ces-control Runner 上执行。本地不执行 `pnpm dev`、`pnpm build`、`pnpm typecheck` 或打包测试。
|
||
|
||
当前服务器入口为HTTP，与参考项目一致使用 `AUTH_COOKIE_SECURE=false`；配置HTTPS后应在独立production.env设置 `AUTH_COOKIE_SECURE=true`。HTTP本身不加密动态码和会话传输。
|
||
|
||
`pnpm test:auth`运行算法、会话、重放及限流测试。容器验证使用自己的匿名测试卷完成登录/并发重放/CSRF/限流测试，并在重启后检查状态仍存在。生产部署只运行无副作用的 `verify`，不会消耗用户动态码或触发生产限流。
|
||
|
||
## AI 公司研究
|
||
|
||
导航入口为 **其他研究 → AI 公司研究**，页面路径是
|
||
`/docs/other-research/ai-company-research/overview`。工作台提供业务分类、公司搜索与筛选、
|
||
公司明细、收入观测、原始证据和数据核查记录。所有页面与
|
||
`GET /api/research/ai-companies` 均使用文档站现有的登录认证。
|
||
|
||
研究业务数据本轮暂不迁移，仍沿用版本化 JSON 导入机制。研究数据、文档与登录状态**共用文档站现有的 SQLite 数据库文件**：
|
||
`AUTH_CONFIG_FILE` 同目录下的 `login-state.sqlite`。该文件名是历史名称，未创建第二个数据库。
|
||
`login_state` 保留登录限流与重放状态，新增的 `research_*` 表保存数据版本、分类、
|
||
公司、经营指标、证据与核查记录。沿用现有 `/auth` 持久挂载，数据库不会写入镜像或公开目录。
|
||
|
||
`content/research/ai-companies.seed.json` 是可评审的研究导入快照，
|
||
服务端首次读取该版本时将它以事务导入同一数据库，之后从数据库查询记录。
|
||
导入使用外键校验，不删除登录数据，也不覆盖旧研究版本。每次更新快照必须修改 `version`；
|
||
同一版本内容变化会拒绝导入，避免静默读取旧数据。回退代码时继续读取对应旧版本。
|
||
所有修改都经过工作分支和 PR，部署仍等待人工合并主线。
|
||
|
||
当前资料包含 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、总体离散排名或财务造假概率。
|
||
|
||
收入分布：`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分别建档。
|
||
|
||
覆盖核查：从 yc-oss 非官方镜像发现 2025—2026 八个 YC 批次的 1,428 条候选，
|
||
逐条读取对应 YC 官方公开页面，以页面中的成立年份、团队字段和业务描述筛选。
|
||
962 条初筛匹配，其中 34 条与原表 URL 重合，实际新增 928 条；268 条年份不符或缺失、
|
||
192 条 AI 业务待确认、6 条成立年份晚于批次年份未纳入本批新增。
|
||
`content/research/ai-companies.coverage.json` 保留逐条筛选结果、来源与响应摘要，
|
||
数据快照中的 `coverage` 也随版本进入同一 SQLite 数据库。只覆盖该候选池，不能称全球全量。
|
||
|
||
新增业务分类优先匹配主营简介，再参考目录标签；未匹配者进入待分类组。
|
||
初分规则位于 `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 内置任务令牌，不保存检出凭据。
|