From 8d4a5c4f942a5dac2bc16a130144614f98ff1b4c Mon Sep 17 00:00:00 2001 From: skycurtain Date: Thu, 29 Oct 2026 00:45:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E6=B6=A6=E8=89=B2=E6=94=B6?= =?UTF-8?q?=E5=B0=BE=E2=80=94=E2=80=94=E5=AE=9A=E4=BD=8D=E4=B8=AD=E6=80=A7?= =?UTF-8?q?=E5=8C=96=E3=80=81=E8=A1=A5=E9=80=82=E7=94=A8=E5=9C=BA=E6=99=AF?= =?UTF-8?q?=E4=B8=8E=20AI=20=E5=8D=8F=E4=BD=9C=E7=89=A9=E6=96=99=E8=AF=B4?= =?UTF-8?q?=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 63052c9..1ea0745 100644 --- a/README.md +++ b/README.md @@ -6,30 +6,32 @@ | 项目 | 内容 | |------|------| -| 当前状态 | **实现推进中**——设计文档主体定稿；后端 + 同步引擎 + 前端（管理面与成员视图）已落地；部署链已定（见 [`docs/design/部署方案.md`](docs/design/部署方案.md)）；CFW 衍生形态待做 | +| 当前状态 | **实现推进中**——设计文档主体定稿；后端 + 同步引擎 + 前端（管理面与成员视图）已落地；部署链已定（见 [`docs/design/部署方案.md`](docs/design/部署方案.md)）；Cloudflare Workers 抽取版待做 | | 技术栈 | 全栈 TypeScript（选型见 [`docs/design/技术选型.md`](docs/design/技术选型.md)）：Bun + Hono + Drizzle + PostgreSQL · 前端 Vue 3 + antdv-next | ## 这是什么 -面向 [NewAPI](https://github.com/QuantumNous/new-api) 实例的**独立计费辅助平台**：作者购买订阅额度后，创建多个 sk- API key 分发给多名使用者分摊成本。平台只提供**事实服务**——用量、来源标注、支付参数、多维统计；**不算「谁该付谁多少钱」**（分摊是人和人之间的事）。 +面向 [NewAPI](https://github.com/QuantumNous/new-api) 实例的**独立计费辅助平台**：订阅持有人创建多个 sk- API key 分发给多名使用者，平台把「谁用了多少」的事实记录清楚——用量、来源标注、支付参数、多维统计；**不算「谁该付谁多少钱」**（分摊是人和人之间的事）。 + +**适用场景**：同一份订阅额度由多人共享的小团队 / 成本分担群体。 - 名字直述用途：NewAPI 网关下按 key 查询用量（key usage）；产品展示名 NAKU -- 全场景统一小写 kebab-case：仓库名 / 包名一致 +- 仓库名 / 包名统一小写 kebab-case ## 背景与约束 -- 真实场景：NewAPI（Go + GORM 开源 LLM 网关）实例提供订阅服务，多使用者通过分发 API key 共享订阅额度——**非商业，纯成本分担** -- 项目作者是该实例的**普通用户**：只有 sk-key，**没有实例管理员账号** - - 一切数据获取只能走 key 级接口（账号级接口用 sk-key 访问会 401） - - 交付形态为**双形态并行**：完整前后端部署在实例运营方提供的服务器上（作者不接触服务器）+ Cloudflare Workers 抽取版部署在作者自控账号（见 [`docs/design/需求清单.md`](docs/design/需求清单.md) R13） +- 典型场景：NewAPI（Go + GORM 开源 LLM 网关）实例提供订阅服务，多名使用者通过分发 API key 共享订阅额度——**非商业，纯成本分担** +- 平台持有方通常只是实例的**普通用户**：只有 sk-key，**没有实例管理员账号** + - 一切数据获取只能走 key 级接口（账号级接口用 sk-key 访问会 401）——这是整个数据链路的设计前提 +- 部署形态为**双形态并行**：完整前后端跑在自有或托管服务器上（见 [`docs/design/部署方案.md`](docs/design/部署方案.md)）；Cloudflare Workers 抽取版部署在自己掌控的账号里（见 [`docs/design/需求清单.md`](docs/design/需求清单.md) R13） -**双形态并行的动因**：服务器部署形态下，每次迭代都需实例运营方手工升级；部署到作者自控的 Cloudflare 账号后，迭代部署权回到作者手里。母体完整前后端先行，Workers 抽取版延后至功能全集实现后。 +**双形态并行的动因**：服务器部署形态下，每次迭代都要经服务器管理员手工升级；Workers 形态把迭代部署权收回自己手里。完整前后端先行，抽取版延后至功能全集实现后。 ## 核心能力 | # | 能力 | 说明 | |---|------|------| -| 1 | key 用量查询 | 按时间范围查模型请求日志与用量；作者全员视角在管理面总览，成员视角在成员视图 | +| 1 | key 用量查询 | 按时间范围查模型请求日志与用量；管理端全员视角，成员端各自视角 | | 2 | key 登记 | 管理通道手动登记：入库并加入轮询；生命周期为手动启停（引擎只读 `status`） | | 3 | 支付事实登记 | 订阅权益与充值入账分表登记；`billing_domain` 标账本域，成员同域可见 | | 4 | 多维统计 | 按成员 / key / 计费来源 / 模型的任意时段聚合 | @@ -150,6 +152,7 @@ docker compose ps # migrate 应为 exited(0)，其余 running/healthy - 命名与分区：**目录用英文、文档名用中文**；`docs/design/`（方案与决策）· `docs/references/`（平台可用接口参考——实证事实，不做设计决策） - 生命周期：状态流转（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；定稿后不搬家、只改状态；被取代时删除（git 历史即考古） +- AI 协作物料：[`AGENTS.md`](AGENTS.md)（协作约定）与 `.agents/skills/`（技能包）随仓库分发——参与开发的 Agent 从这里读取项目约定，人工贡献者亦可参考 ## 关键事实清单（实测 / 源码确认，设计时不得违反）