新增文档上传 API、专用密钥与批量上传客户端 #24

2026-10-30T10:16:03Z

codex-bot commented

2026-10-30 10:16:03 +00:00

问题与行为

文档正文已经由数据库管理，但日常写入仍需要 SSH 到服务器执行 docs CLI。新增可复用的文档 API 和 Python 上传客户端，方便批量整理和反复更新文档；正文继续只写数据库，不进入 repo，不依赖重新构建。

接口与一致性

GET /api/documents：分页目录元数据；GET /api/documents/item/：单篇全文、分页修订信息或指定修订。
POST /api/documents：完整 JSON 新建/更新；POST /api/documents/batch：单请求 1—100 篇、最多 8 MiB，任一冲突整体回滚。
新建 revision=0，更新携带读取到的 revision，避免覆盖并发编辑；保留旧地址与全部修订。
Idempotency-Key 按文档 Key 隔离，同输入重试返回原回执，不重复写入；改换输入返回 409。

身份与使用

独立文档 API Key 仅用于文档接口，有 read/read-write 权限、1—365 天有效期及撤销能力。只存摘要，原文写入私有目录的新文件，不出现在终端或日志中；网页 Cookie 和通用网页会话不能调用新增 API。

客户端支持 HTTPS 或受信任 SSH 隧道上的本机 HTTP，不跟随重定向，不把 Key 放入参数。大量文档自动按数量/字节上限分批，每批独立提交并报告已提交数量，临时网络重试保留请求 ID；业务冲突不自动覆盖。

逐文件修改与目的

AGENTS.md：维护约定允许使用文档 API，继续要求数据库权威源。
README.md：补齐接口、JSON/版本/批量语义、密钥管理、客户端与重试流程，区分备份与独立密钥文件。
apps/docs/src/lib/docs.ts：增加原子批量保存、幂等回执、分页目录/修订与指定修订读取，区分格式错误和冲突。
apps/docs/src/lib/document-keys.ts：新增同库 API Key 摘要、权限、过期、撤销和使用信息管理。
apps/docs/src/lib/documents-api.ts：统一鉴权、输入检查、分页、幂等键与错误状态。
apps/docs/src/pages/api/documents/index.ts：新增目录读取及单篇保存 API。
apps/docs/src/pages/api/documents/batch.ts：新增有界原子批量写入 API。
apps/docs/src/pages/api/documents/item/[...slug].ts：新增单篇与历史修订读取 API。
apps/docs/src/proxy.ts：仅对文档接口接受文档 Key，不放开其他页面与 API。
apps/docs/scripts/docs-cli.ts：新增私有文件方式创建 Key、元数据列表与撤销命令。
scripts/docs-admin.sh：通过现有服务器包装工具暴露 Key 管理命令。
scripts/documents-client.py：新增标准库上传客户端，支持分页、修订、自动分批和受控重试。
scripts/test_documents_client.py：新增客户端传输、私有文件、分批与重试轻量测试。
apps/docs/tests/documents-api.test.ts：新增鉴权、只读权限、撤销/过期、原子回滚、分页与幂等测试。
apps/docs/scripts/test-docs.mjs：将 API 测试接入现有主线文档测试命令。
apps/docs/scripts/auth-cli.ts：在隔离卷的主线冒烟中验证真实 API 路由与 Key 范围，不在生产 verify 中执行写入测试。

检查与发布状态

已通过：11 项 Python 轻量测试（含客户端测试）、研究审计/统计检查、Python/JSON/Shell 语法、文档路径与 git diff --check。
API 的 TypeScript 测试、类型检查、构建和容器冒烟尚未运行，按 main-only 约定留待用户手动合并后的主线 CI；没有新增分支工作流，没有在本机编译或构建。

head: codex/documents-api；base: main；commit: 6bfeea4。已推送工作分支，等待用户手动合并；未合并、未部署、未创建生产 API Key，现有生产文档未改动。

## 问题与行为文档正文已经由数据库管理，但日常写入仍需要 SSH 到服务器执行 docs CLI。新增可复用的文档 API 和 Python 上传客户端，方便批量整理和反复更新文档；正文继续只写数据库，不进入 repo，不依赖重新构建。 ## 接口与一致性 - GET /api/documents：分页目录元数据；GET /api/documents/item/<slug>：单篇全文、分页修订信息或指定修订。 - POST /api/documents：完整 JSON 新建/更新；POST /api/documents/batch：单请求 1—100 篇、最多 8 MiB，任一冲突整体回滚。 - 新建 revision=0，更新携带读取到的 revision，避免覆盖并发编辑；保留旧地址与全部修订。 - Idempotency-Key 按文档 Key 隔离，同输入重试返回原回执，不重复写入；改换输入返回 409。 ## 身份与使用独立文档 API Key 仅用于文档接口，有 read/read-write 权限、1—365 天有效期及撤销能力。只存摘要，原文写入私有目录的新文件，不出现在终端或日志中；网页 Cookie 和通用网页会话不能调用新增 API。客户端支持 HTTPS 或受信任 SSH 隧道上的本机 HTTP，不跟随重定向，不把 Key 放入参数。大量文档自动按数量/字节上限分批，每批独立提交并报告已提交数量，临时网络重试保留请求 ID；业务冲突不自动覆盖。 ## 逐文件修改与目的 - AGENTS.md：维护约定允许使用文档 API，继续要求数据库权威源。 - README.md：补齐接口、JSON/版本/批量语义、密钥管理、客户端与重试流程，区分备份与独立密钥文件。 - apps/docs/src/lib/docs.ts：增加原子批量保存、幂等回执、分页目录/修订与指定修订读取，区分格式错误和冲突。 - apps/docs/src/lib/document-keys.ts：新增同库 API Key 摘要、权限、过期、撤销和使用信息管理。 - apps/docs/src/lib/documents-api.ts：统一鉴权、输入检查、分页、幂等键与错误状态。 - apps/docs/src/pages/api/documents/index.ts：新增目录读取及单篇保存 API。 - apps/docs/src/pages/api/documents/batch.ts：新增有界原子批量写入 API。 - apps/docs/src/pages/api/documents/item/[...slug].ts：新增单篇与历史修订读取 API。 - apps/docs/src/proxy.ts：仅对文档接口接受文档 Key，不放开其他页面与 API。 - apps/docs/scripts/docs-cli.ts：新增私有文件方式创建 Key、元数据列表与撤销命令。 - scripts/docs-admin.sh：通过现有服务器包装工具暴露 Key 管理命令。 - scripts/documents-client.py：新增标准库上传客户端，支持分页、修订、自动分批和受控重试。 - scripts/test_documents_client.py：新增客户端传输、私有文件、分批与重试轻量测试。 - apps/docs/tests/documents-api.test.ts：新增鉴权、只读权限、撤销/过期、原子回滚、分页与幂等测试。 - apps/docs/scripts/test-docs.mjs：将 API 测试接入现有主线文档测试命令。 - apps/docs/scripts/auth-cli.ts：在隔离卷的主线冒烟中验证真实 API 路由与 Key 范围，不在生产 verify 中执行写入测试。 ## 检查与发布状态已通过：11 项 Python 轻量测试（含客户端测试）、研究审计/统计检查、Python/JSON/Shell 语法、文档路径与 git diff --check。 API 的 TypeScript 测试、类型检查、构建和容器冒烟尚未运行，按 main-only 约定留待用户手动合并后的主线 CI；没有新增分支工作流，没有在本机编译或构建。 head: codex/documents-api；base: main；commit: 6bfeea4。已推送工作分支，等待用户手动合并；未合并、未部署、未创建生产 API Key，现有生产文档未改动。

codex-bot added 1 commit 2026-10-30 10:16:03 +00:00

feat: add scoped document API and resumable batch uploader 6bfeea4e7e

codex-bot referenced this issue from a commit

2026-10-30 10:19:41 +00:00

merge: integrate document upload API from PR #24

codex-bot referenced this pull request

2026-10-30 10:19:48 +00:00

汇总 AI 公司核查更新与文档上传 API #25

codex-bot closed this pull request

2026-10-30 10:21:41 +00:00