This commit is contained in:
Shaw Kaz
2026-06-07 18:08:04 +08:00
commit cb967a7594
10 changed files with 536 additions and 0 deletions
+124
View File
@@ -0,0 +1,124 @@
# NewAPI 运营项目 Agent 工作规范
本项目是长期运营项目,不只是一次服务器采购。所有 Agent 必须先同步事实,再执行任务;任何关键结论都要能追溯到证据、测试或明确假设。
## 项目目标
- 为主要面向国内用户的 NewAPI 服务和酒馆服务建立可采购、可部署、可压测、可运营的方案。
- 长期维护服务器线路、上游渠道、成本核算、监控验收和故障复盘。
- 用文件作为单一事实源,让多个 AI Agent 可以并行工作但不互相污染结论。
## 非目标
- 首轮文档初始化不购买服务器、不部署服务、不调用生产 API。
- 不在仓库保存 API Key、账号密码、付款信息、Cookie、真实用户隐私。
- 不为未确定需求引入自动化系统、复杂脚本、数据库或额外依赖。
- 不把论坛传闻、搜索摘要、商家宣传直接当作最终事实。
## Agent 启动清单
每个 Agent 开始工作前必须读取:
1. `AGENTS.md`
2. `README.md`
3. `task_plan.md`
4. `findings.md`
5. `progress.md`
6. `decisions.md`
7. 当前任务相关专题目录的 `README.md`
开始前必须能说清:
- 本次只解决什么。
- 明确不解决什么。
- 最小改动范围是什么。
- 如何验证结果。
## Agent 角色
- 主 Agent:维护计划、拆分任务、合并结论、做最终判断。
- 调研 Agent:检索官方资料、论坛反馈、测评数据、压测结果,只输出可追溯事实。
- 运维 Agent:设计 NewAPI、数据库、Redis、反代、备份、监控、压测方案。
- 成本 Agent:维护服务器、上游、域名、备份、冗余节点和用户规模成本模型。
- 审查 Agent:复核证据等级、安全风险、过度工程和验收标准。
## 文件职责
- `README.md`:项目入口、当前结论、目录导航、下一步。
- `task_plan.md`:阶段计划、状态、负责人、验收标准。
- `findings.md`:事实与证据库,只记录来源、命令、测试和摘要。
- `progress.md`:工作流水,每次 Agent 工作后追加记录。
- `decisions.md`:决策记录,记录背景、选项、决定、理由和复查条件。
- `todos.md`CC-Panes 不可用时的手动 Todo 队列。
- `服务器选购/`:供应商、线路、套餐、压测和购买决策。
- `上游比价/`:模型上游、中转渠道、价格、稳定性和风控。
- `成本核算/`:月成本、流量成本、用户规模假设和盈亏线。
## 外部检索规范
外部检索优先使用本机 `smart-search` CLI。每次检索必须在 `findings.md` 记录:
- 运行侧:`PowerShell``cmd``Debian WSL1`
- 命令类型:`doctor``search``exa-search``exa-similar``fetch``map`
- 查询词或 URL。
- 来源链接。
- 证据等级。
- 结论摘要。
- 未验证点。
证据等级:
- A:官方文档、官方购物车、已 `fetch` 成功的原文、自己的压测数据。
- B:可信测评、可复现实验、完整脚本输出。
- C:论坛讨论、搜索高亮、商家宣传但未实测。
- D:推断、经验判断、待验证假设。
事实判断优先引用 A/B 级证据。C/D 级内容只能作为候选线索,必须标注风险。
## 任务分派规范
每个可分派任务必须写清:
- 任务 ID。
- 角色。
- 目标。
- 输入文档。
- 输出位置。
- 禁止事项。
- 验收标准。
- 当前状态。
CC-Panes 可用时,可以用 Todo 批量分派;不可用时,用 `todos.md` 维护同样字段。并行任务不能同时修改同一个文件;如确需修改同一文件,先由主 Agent 拆分输出位置,再统一合并。
## 结束交接模板
每个 Agent 结束前必须更新 `progress.md`,格式如下:
```markdown
## YYYY-MM-DD HH:mm CST - Agent 名称
- 目标:
- 已完成:
- 修改文件:
- 新增事实:
- 决策变化:
- 验证结果:
- 阻塞点:
- 下一步:
```
若新增事实,更新 `findings.md`。若改变路线,更新 `decisions.md`。若新增或完成任务,更新 `todos.md` 或 CC-Panes Todo。
## 安全规则
- 不保存明文密钥、账号密码、支付信息、Cookie、用户隐私。
- 只记录密钥所在系统、用途、轮换周期和负责人。
- 涉及生产 API、真实用户数据、批量删除、权限变更、付款和迁移时,必须先单独确认风险。
- 同一问题最多尝试 3 次;每次失败必须换假设或方法,并在 `progress.md` 记录。
## 当前技术默认
- 服务器规格先按 `4C4G` 规划,最低 `2C2G`,暂不按 `8C8G` 规划。
- 主要瓶颈优先看国内线路、晚高峰质量、流式稳定性和上游可用性,不把 CPU 当作首要瓶颈。
- OVH 可作为源站、备份、大盘或抗 D 方向候选,但不默认作为国内主入口。
- 国内主入口优先考虑三网优化线路,并以实测为准。
+49
View File
@@ -0,0 +1,49 @@
# NewAPI 运营项目
这是一个面向国内用户的 NewAPI 与酒馆服务长期运营项目。项目用 Markdown 文件管理事实、决策、任务和交接,让多个 AI Agent 可以围绕同一个事实源协作。
## 当前结论
| 主题 | 当前判断 | 证据状态 |
| --- | --- | --- |
| 服务器规格 | 优先 `4C4G`,最低 `2C2G`,暂不需要 `8C8G` | 基于 NewAPI/酒馆资源需求判断,待部署压测验证 |
| 网络方向 | 优先三网优化线路,重点看晚高峰和流式稳定性 | 待继续补充官方资料、论坛反馈和实测 |
| OVH | 不默认作为国内主入口,更适合源站、备份、大盘、抗 D | 已形成初步判断,需在 `decisions.md` 追溯 |
| 部署形态 | NewAPI + PostgreSQL/MySQL + Redis + Nginx/Caddy,同机起步 | 待运维方案细化 |
| 协作方式 | 文件制单一事实源 + Todo 分派 | 已作为项目默认 |
## 目录导航
- `AGENTS.md`:所有 Agent 必读的项目工作规范。
- `task_plan.md`:长期阶段计划。
- `findings.md`:事实、来源、命令和证据等级。
- `progress.md`:每次工作的流水记录。
- `decisions.md`:重要决策和复查条件。
- `todos.md`:手动 Todo 队列,CC-Panes 不可用时使用。
- `服务器选购/`:供应商、线路、套餐、测试 IP、购买建议。
- `上游比价/`:模型上游、中转渠道、价格、稳定性和风控。
- `成本核算/`:月成本、不同规模预算、盈亏线。
## 新 Agent 快速开始
1. 读取 `AGENTS.md`,确认工作规则。
2. 读取 `task_plan.md`,确认当前阶段。
3. 读取 `findings.md``decisions.md`,不要重复已经验证或否定的路线。
4. 读取相关专题目录的 `README.md`
5.`todos.md` 中认领任务,或按用户要求执行指定任务。
6. 完成后更新 `progress.md`;如有事实或路线变化,同步更新 `findings.md``decisions.md`
## 下一步
1. 补齐服务器候选的证据:官网套餐、购物车状态、测试 IP、线路说明、论坛反馈。
2. 形成首批采购短名单:主入口、备选入口、源站/备份方案。
3. 写出 NewAPI + 酒馆的最小部署方案和验收脚本。
4. 建立成本模型:小规模、增长期、冗余期三档。
5. 购买前做 24-48 小时压测验收清单。
## 禁止事项
- 不在文档中保存密钥、账号密码、Cookie、付款信息或真实用户隐私。
- 不把搜索摘要、论坛传闻、商家宣传直接写成最终事实。
- 不让多个 Agent 并行修改同一文件。
- 不为了未来可能需要的功能提前引入复杂系统。
+47
View File
@@ -0,0 +1,47 @@
# 决策记录
本文件记录重要路线选择。每条决策都应包含背景、选项、决定、理由、风险和复查条件。
## 记录模板
```markdown
## DEC-YYYYMMDD-序号 - 标题
- 状态:
- 背景:
- 选项:
- 决定:
- 理由:
- 风险:
- 复查条件:
```
## DEC-20260607-01 - 使用文件制单一事实源同步多个 Agent
- 状态:accepted
- 背景:项目将长期覆盖采购、部署、上游、成本、监控和复盘,且会启用多个 AI Agent 并行处理问题。
- 选项:只用文件;只用 CC-Panes;文件 + Todo。
- 决定:采用文件制单一事实源 + Todo 分派。CC-Panes 可用时用工具分派,不可用时用 `todos.md` 手动维护。
- 理由:Markdown 文件可追溯、可审查、跨会话稳定;Todo 适合分派和状态追踪;两者结合不绑定单一工具。
- 风险:多个 Agent 可能同时修改同一文件。
- 复查条件:如果 CC-Panes 工具稳定可用,且并行任务明显增多,再考虑把 Todo 状态迁移到工具为主、文件为备份。
## DEC-20260607-02 - 首轮按 4C4G 规划服务器规格
- 状态:provisional
- 背景:NewAPI 与酒馆服务主要瓶颈预计在国内线路、上游稳定性、数据库和日志,而不是 CPU。
- 选项:2C2G、4C4G、4C8G、8C8G。
- 决定:首轮优先按 `4C4G` 规划,最低 `2C2G`,更稳可看 `4C8G`,暂不按 `8C8G` 规划。
- 理由:`4C4G` 对小规模 NewAPI + 数据库 + Redis + 反代更有余量,成本仍可控;`8C8G` 对当前需求偏高。
- 风险:如果日志量、并发或数据库写入高于预期,4G 内存可能紧张。
- 复查条件:完成实际部署后,用并发 10-30、长输出、日志写入和数据库备份恢复验证资源占用。
## DEC-20260607-03 - 不默认选择 OVH 作为国内主入口
- 状态:provisional
- 背景:用户提到国内站长常用 OVH,并提供 OVH KS-2 GRA 大盘服务器信息。
- 选项:OVH 做主入口;OVH 做源站/备份;三网优化 VPS 做主入口。
- 决定:OVH 不默认作为国内主入口,更适合源站、备份、大盘或抗 D;国内主入口优先看三网优化线路。
- 理由:面向国内用户的 NewAPI/酒馆服务更依赖三网访问质量、晚高峰稳定性和流式不断连,而不是大硬盘或海外大带宽。
- 风险:三网优化 VPS 商家质量参差,宣传需实测。
- 复查条件:如拿到 OVH 与三网优化节点的真实国内三网压测数据,再重新比较入口方案。
+60
View File
@@ -0,0 +1,60 @@
# 事实与证据库
本文件只记录可追溯事实、检索命令、测试结果和证据摘要。不要把未经验证的判断写成最终结论。
## 证据等级
- A:官方文档、官方购物车、已 `fetch` 成功的原文、自己的压测数据。
- B:可信测评、可复现实验、完整脚本输出。
- C:论坛讨论、搜索高亮、商家宣传但未实测。
- D:推断、经验判断、待验证假设。
## 记录模板
```markdown
## YYYY-MM-DD - 主题
- 运行侧:
- 命令类型:
- 查询词或 URL
- 来源:
- 证据等级:
- 摘要:
- 对项目的影响:
- 未验证点:
```
## 已知事实
### 2026-06-07 - 项目目录初始状态
- 运行侧:Debian WSL1
- 命令类型:本地只读检查
- 查询词或 URL`find . -maxdepth 3`
- 来源:`C:\Users\shaw\frist`
- 证据等级:A
- 摘要:项目根目录存在 `服务器选购``上游比价``成本核算` 三个专题目录,初始未发现项目级 Markdown 文档。
- 对项目的影响:适合建立根目录项目控制台,并保留三个专题目录作为长期资料区。
- 未验证点:各专题后续需要补充实际调研资料和压测结果。
### 2026-06-07 - 当前服务器规格默认
- 运行侧:对话上下文
- 命令类型:用户需求与历史讨论整理
- 查询词或 URL:无
- 来源:本项目对话上下文
- 证据等级:D
- 摘要:当前默认按 `4C4G` 规划,最低 `2C2G`,暂不按 `8C8G` 规划;主要瓶颈预期在国内线路和上游稳定性,不在 CPU。
- 对项目的影响:后续采购和成本模型先围绕 `2C2G``4C4G``4C8G` 三档展开。
- 未验证点:需要通过真实部署、并发和流式输出压测验证。
### 2026-06-07 - OVH 方向初步判断
- 运行侧:对话上下文
- 命令类型:用户需求与历史讨论整理
- 查询词或 URL:无
- 来源:本项目对话上下文
- 证据等级:D
- 摘要:OVH 不默认作为国内用户主入口,更适合源站、备份、大盘或抗 D 场景。
- 对项目的影响:服务器选购中需要区分“国内入口机”和“源站/备份机”,避免只看硬件配置。
- 未验证点:如考虑 OVH,仍需补充具体机房、线路、国内三网访问和晚高峰测试。
+14
View File
@@ -0,0 +1,14 @@
# 工作流水
本文件按时间追加记录每次 Agent 工作。不要删除历史记录;如需修正,在新条目中说明。
## 2026-06-07 18:04 CST - Codex
- 目标:初始化 NewAPI 运营项目文档与多 Agent 同步规范。
- 已完成:只读检查项目根目录;确认已有 `服务器选购``上游比价``成本核算` 三个目录;制定根目录文档结构。
- 修改文件:`AGENTS.md``README.md``task_plan.md``findings.md``progress.md``decisions.md``todos.md`、三个专题目录的 `README.md`
- 新增事实:项目初始目录结构已记录到 `findings.md`
- 决策变化:确立“文件制单一事实源 + Todo 分派”为默认协作方式。
- 验证结果:已确认 10 个 Markdown 文档存在且非空;关键字段已覆盖;敏感形态扫描未发现密钥样式内容。
- 阻塞点:当前目录不是 Git 仓库,因此无法用 Git diff 追踪变更。
- 下一步:补齐服务器候选证据和采购短名单。
+43
View File
@@ -0,0 +1,43 @@
# 任务计划
更新时间:2026-06-07 CST
状态说明:
- `todo`:未开始
- `in_progress`:进行中
- `blocked`:阻塞
- `done`:已完成
## 项目目标
建立一个可长期维护的 NewAPI 运营项目,覆盖服务器采购、部署运维、上游渠道、成本核算、监控验收和故障复盘。
## 阶段计划
| 阶段 | 状态 | 目标 | 验收标准 |
| --- | --- | --- | --- |
| P0 文档初始化 | done | 建立项目入口、Agent 规范、计划、事实库、决策库、Todo 队列 | 新 Agent 能只读根目录文档后理解项目目标和下一步 |
| P1 服务器候选复核 | todo | 复核三网优化服务器候选、价格、库存、线路和风险 | 每个候选至少有来源、价格、线路、风险、是否推荐 |
| P2 采购决策 | todo | 选出主入口、备选入口、源站/备份策略 | `decisions.md` 有明确决策和复查条件 |
| P3 部署方案 | todo | 设计 NewAPI、酒馆、数据库、Redis、反代、备份方案 | 有最小部署步骤、端口、数据目录、备份恢复方式 |
| P4 验收压测 | todo | 建立国内三网、晚高峰、流式输出和上游健康检查 | 有可执行验收清单和保留/退款条件 |
| P5 成本模型 | todo | 建立月成本、不同用户规模、盈亏线和冗余成本 | `成本核算/` 中有可更新模型 |
| P6 上线运营 | todo | 建立监控、告警、故障处理和复盘流程 | 有监控指标、告警阈值、故障模板 |
## 当前优先级
1. P1:重新检索并记录服务器候选,不依赖旧记忆。
2. P3:写出最小部署形态,明确 2C2G/4C4G/4C8G 的适用边界。
3. P5:先做 300 元/月以内的成本模型。
## 最小改动范围
当前首轮只维护 Markdown 文档,不购买服务器、不部署服务、不执行生产 API、不保存敏感信息。
## 验证方式
- 文件存在且结构完整。
- 每个文档职责清晰,没有互相矛盾。
- 任何采购或上游结论都能在 `findings.md``decisions.md` 中追溯。
- 新 Agent 可按 `README.md``AGENTS.md` 接手。
+64
View File
@@ -0,0 +1,64 @@
# Todo 队列
CC-Panes 可用时,Todo 可以同步到工具;不可用时,以本文件为准。每个任务应保持独立,避免多个 Agent 同时修改同一输出文件。
状态:`todo``in_progress``blocked``done`
## Todo 模板
```markdown
## TODO-编号 - 标题
- 状态:
- 优先级:
- 角色:
- 目标:
- 输入文档:
- 输出位置:
- 禁止事项:
- 验收标准:
```
## TODO-001 - 复核服务器候选清单
- 状态:todo
- 优先级:high
- 角色:调研 Agent
- 目标:重新检索并记录适合国内用户的三网优化服务器候选,包含价格、规格、线路、库存、测试 IP、风险。
- 输入文档:`AGENTS.md``README.md``服务器选购/README.md`
- 输出位置:`服务器选购/README.md``findings.md`
- 禁止事项:不得把论坛传闻或搜索摘要直接作为最终结论;不得购买服务器。
- 验收标准:至少形成主入口候选、备选入口、源站/备份方向,并标注证据等级。
## TODO-002 - 写 NewAPI 与酒馆最小部署方案
- 状态:todo
- 优先级:high
- 角色:运维 Agent
- 目标:设计单机部署方案,覆盖 NewAPI、酒馆、数据库、Redis、反代、备份和恢复。
- 输入文档:`AGENTS.md``README.md``task_plan.md`
- 输出位置:`findings.md`、后续部署文档
- 禁止事项:不得连接生产 API;不得保存密钥;不得实际部署。
- 验收标准:能说明 2C2G、4C4G、4C8G 的适用边界和压测指标。
## TODO-003 - 建立 300 元/月以内成本模型
- 状态:todo
- 优先级:medium
- 角色:成本 Agent
- 目标:整理服务器、域名、备份、上游渠道和冗余节点的月成本假设。
- 输入文档:`AGENTS.md``成本核算/README.md`
- 输出位置:`成本核算/README.md`
- 禁止事项:不得使用真实支付信息;不得写入账号隐私。
- 验收标准:至少有小规模、增长期、冗余期三档预算。
## TODO-004 - 设计采购后 24-48 小时验收清单
- 状态:todo
- 优先级:medium
- 角色:审查 Agent
- 目标:定义购买后保留或退款的验收标准。
- 输入文档:`AGENTS.md``服务器选购/README.md`
- 输出位置:`服务器选购/README.md`
- 禁止事项:不得实际压测未购买机器;不得攻击第三方服务。
- 验收标准:覆盖国内三网、晚高峰、流式输出、上游健康检查、备份恢复。
+44
View File
@@ -0,0 +1,44 @@
# 上游比价
本目录记录模型上游、中转渠道、价格、稳定性、风控和失败率。核心原则:价格不是唯一指标,失败率、限速、封禁风险和恢复能力同样重要。
## 当前方向
- 先按 OpenAI、Claude、Gemini、自有中转渠道分组记录。
- 每个上游记录价格、模型覆盖、速率限制、错误类型、风控风险和可用性。
- 不同上游应配置独立超时、重试和限速策略。
- 如某些账号型或 OAuth 型上游对 IP 敏感,再单独评估出站代理节点;不要一开始复杂化。
## 上游记录模板
```markdown
## 上游名称
- 官网或控制台:
- 支持模型:
- 计费方式:
- 价格:
- 速率限制:
- 常见错误:
- 风控风险:
- 国内入口访问表现:
- 所需出站线路:
- 证据等级:
- 结论:
```
## 测试指标
- 成功率。
- 首 token 时间。
- 完整输出时间。
- 429、403、5xx、超时比例。
- 长上下文和长输出稳定性。
- 生图、文件、工具调用等特殊接口是否断连。
## 待补充
- 首批上游清单。
- 各渠道单价和折算口径。
- 不同模型的优先级和备用策略。
- NewAPI 渠道分组建议。
+44
View File
@@ -0,0 +1,44 @@
# 成本核算
本目录维护项目月成本、用户规模假设、冗余成本和盈亏线。核心原则:先做能更新的简单模型,不提前构建复杂财务系统。
## 当前预算方向
- 首轮服务器预算优先控制在 300 元/月以内。
- 主入口按 `4C4G` 三网优化 VPS 估算。
- 备份和对象存储应单独计入,不与主入口混在一起。
- 上游 API 成本按模型、用量和失败重试分别估算。
## 成本项
| 成本项 | 当前状态 | 说明 |
| --- | --- | --- |
| 主入口服务器 | 待补充 | 三网优化 VPS,优先月付 |
| 源站/备份服务器 | 待补充 | 可考虑普通国际线路或大盘机 |
| 域名 | 待补充 | 按年费折算月成本 |
| 对象存储/备份 | 待补充 | 数据库备份和配置备份 |
| 上游 API | 待补充 | 按模型和调用量估算 |
| 监控告警 | 待补充 | 优先免费或低成本方案 |
## 预算模型模板
```markdown
## 档位名称
- 假设用户数:
- 日请求量:
- 主入口服务器:
- 备份成本:
- 上游 API 成本:
- 预留冗余:
- 月总成本:
- 风险:
- 适用条件:
```
## 待补充
- 小规模、增长期、冗余期三档预算。
- 300 元/月以内方案边界。
- 上游成本的高低用量敏感性。
- 是否需要额外线路机的触发条件。
+47
View File
@@ -0,0 +1,47 @@
# 服务器选购
本目录记录服务器供应商、线路、套餐、测试 IP、压测结果和购买决策。核心原则:面向国内用户时,线路质量优先于硬件堆料。
## 当前方向
- 主入口优先看三网优化线路,重点验证电信、联通、移动的晚高峰质量。
- 默认规格优先 `4C4G`,最低 `2C2G`,暂不按 `8C8G` 规划。
- OVH 暂不作为国内主入口默认选择,可作为源站、备份、大盘或抗 D 方向候选。
- 不建议只因“便宜大带宽”或“大硬盘”选择普通国际线路做主入口。
## 候选记录模板
```markdown
## 供应商 / 套餐名
- 官网:
- 购物车或购买页:
- 月付价格:
- CPU / 内存 / 磁盘:
- 带宽 / 流量:
- 机房:
- 线路说明:
- 测试 IP
- 国内三网表现:
- 晚高峰表现:
- 上游 API 访问:
- 证据等级:
- 风险:
- 结论:
```
## 验收清单
- 国内三网分别测试 `/v1/models`、流式聊天、长输出。
- 20:00-23:30 连续记录延迟、丢包、首 token 时间、完整输出时间。
- 分别测试 OpenAI、Claude、Gemini 和自有中转渠道。
- 测试 NewAPI 渠道健康检查、并发 10-30、日志写入。
- 测试数据库备份和恢复。
- 24 小时内如出现明显晚高峰丢包、流式断连或国内首包体感差,进入退款或换机流程。
## 待补充
- 三网优化候选短名单。
- 每个候选的官方来源和当前库存。
- 可复现的线路测试和晚高峰测试。
- 主入口、备选入口、源站/备份的最终分工。