Files

T

skycurtain 867bb7d566 docs: 命令登记与 SK_KEY_ENCRYPTION_SECRET 命名对齐

AGENTS 命令表、会话留档约定；骨架搭建指南与设计文档键名对齐代码。

2026-10-06 01:30:52 +08:00

4.2 KiB

Raw Blame History

AGENTS.md

给 AI 协作者的仓库指引。开始任何工作前，先读 README.md——它是全景入口：项目是什么、为什么长这样、走到哪了。

协作约定（长期有效）

Git：仅当项目作者明确说"提交 / commit"时才执行提交；git push 永远由项目作者手工执行，AI 绝不推送
命名：需求 / 设计 / 交互 / 技术 / 计划等文档名用中文（README / AGENTS / LICENSE 等约定俗成除外）、目录用英文；新文档按性质放入 docs/design/（我们定的方案与决策）或 docs/references/（平台可用接口参考——实证事实，不做设计决策），并同步更新 README 的「文档地图」；docs/deprecated/ 只归档已废弃文档——勿引用、勿作依据（本分支暂无此目录，需要时再建）
文档状态：头部表格标「状态」（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；设计文档定稿后不搬家、只改状态；被取代时删除（git 历史即考古）
部署：交付物必须保证「一条命令链」可部署；双形态并行已裁决——完整前后端（运营方服务器）先行，Cloudflare Workers 抽取版（作者自部署）后续（见 docs/design/需求清单.md R13）
不引入版本叙事：不使用 v1/v2/v3 之类版本编号，不以「MVP」等标签或指称显式描述任何历史阶段；文档内容必须自立——不得引用、描述任何当前分支之外、可能被删除的分支内容
本地不入库也不 ignore 的物料（AI 提交时务必避开）：api*.json（上游实测快照）、session-archive/（作者主动备份的会话记录，如 v1-设计-*.md）——不加入 git、不写 .gitignore，靠提交时人工/执行者目视把关；v1-设计-1.md 为历史对话原档，允许保留旧术语，不作现行依据

项目速览（速记）

design（本分支）= 设计文档中心 + 实现主线：实现代码与文档同分支演进（代码落点已定案），monorepo 结构（apps/server · apps/web · packages/core · packages/db）见 docs/design/技术选型.md §4
数据模型：四张基线表（api_keys · usage_logs · payments · qpu_history）+ 三张访问主体表（members · users · sessions）设计见本目录，七篇已定稿（2026-10-01，经作者逐篇审阅）；同步架构（轮询 + request_id 去重 + 攒库）的动因由上游物理约束决定，架构结论不变
需求总集与待裁决项（平台身份体系、费用分摊与账单、充值折算、多订阅、数据资产保护）见 docs/design/需求清单.md；交付形态已裁决（双形态并行，完整形态先行）
上游约束速记：只有 sk-key、无时间过滤接口 → 轮询攒库是唯一路径（README「架构的根本动因」）

命令

Bun 工具链（选型见 docs/design/技术选型.md）。Windows 上 bun 需在 PowerShell 7（pwsh）里跑——mise shim 由 pwsh profile 激活；Windows PowerShell 5.1 会报 command not found，改用 pwsh -c "…" 或绝对路径。

命令	用途
`bun install`	安装 / 链接 workspace 依赖（在仓库根）
`bun test`	全部测试（core 契约 + server HTTP + 集成）；集成需 `DATABASE_URL`（compose 中的 PG），无库时自动跳过
`bun --env-file=.env scripts/seed-from-samples.ts`	从根目录 `api*.json` 实测快照灌开发库（幂等）；验收接口口径用
`bun run typecheck`	根 tsconfig 类型检查（不含 web `.vue`）
`bun run dev:server`	开发跑母体后端（hot reload）
`bun run dev:web`	开发跑前端 Vite
`docker compose up -d`	起开发用 PostgreSQL
`bun run --filter @new-api-key-usage/db db:generate`	生成 SQL 迁移（`packages/db/drizzle/`）
`bun run --filter @new-api-key-usage/db db:push`	推送到本地库（开发期）

环境变量见 .env.example（复制为 .env 后填写）。

默认端口 18456（避开 3000/3001 等本机占用）；NEWAPI_BASE 是上游 NewAPI 地址，与本服务端口无关。在线文档：http://127.0.0.1:18456/api/docs。

4.2 KiB Raw Blame History Unescape Escape

AGENTS.md

协作约定（长期有效）

项目速览（速记）

命令

4.2 KiB

Raw Blame History