# 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 方向候选，但不默认作为国内主入口。
- 国内主入口优先考虑三网优化线路，并以实测为准。