AIClient2API 目录与文档分层规范
这篇记录的是这次把 AIClient2API 的源码真源、服务器运行边界、GitHub 来源和文档层级补齐后的固定写法。后续同类项目可以直接复用这个结构。
一句话总原则
本机 = 唯一源码真源（开发）
GitHub = 版本与备份（历史）
服务器 = 运行环境（只跑，不开发）当前真值
- 本机工作源码根：
E:\My Project\AIClient2API - 本机 clean 同步副本：
E:\My Project\aiclient2api-clean - 服务器运行目录：
/srv/aiclient-2-api-mock - 服务器容器：
aiclient2api - 服务器主机：
170.106.179.226 - GitHub origin：
https://github.com/emptyinkpot/my-project-root.git
这次补齐了什么
1. README.md
在 E:\My Project\AIClient2API\README.md 里补了：
- 源码 / 部署边界
- 服务器运行信息
- GitHub 来源
- 文档入口
- 项目结构
- 配置层说明
2. docs/architecture.md
在 E:\My Project\AIClient2API\docs\architecture.md 里补了：
- 项目结构树
- 运行边界
- 请求流
- 配置层
- GitHub 来源
3. docs/deploy.md
在 E:\My Project\AIClient2API\docs\deploy.md 里补了：
- 本机源码真源
- 服务器只运行不开发
- 标准部署流程
- 服务器路径
4. docs/runbook.md
在 E:\My Project\AIClient2API\docs\runbook.md 里补了：
- 重启
- 日志
- 健康检查
- 常见问题
- 排障顺序
5. .env.example
在 E:\My Project\AIClient2API\.env.example 里保留了：
- 本地可选覆盖项
- 真实默认值仍回到
configs/config.json
6. 全局记忆
把这套边界写进了 C:\Users\ASUS-KL\.codex\MEMORY.md，避免后续又把 AIClient2API、aiclient2api-clean 和服务器运行目录混掉。
推荐的项目分层
E:\My Project\AIClient2API\
├── README.md
├── docs/
│ ├── architecture.md
│ ├── deploy.md
│ └── runbook.md
├── configs/
│ ├── config.json
│ └── provider_pools.json
├── src/
├── scripts/
├── docker/
├── .env.example
└── package.json写法原则
README.md
只写给第一次打开仓库的人看的内容：
- 这是干什么的
- 源码在哪
- 服务器在哪跑
- 入口地址是什么
- 文档在哪
docs/deploy.md
只写部署流程：
- 本地改哪里
- 怎么同步
- 服务器怎么重启
- 怎么验证
docs/runbook.md
只写运维动作：
- 服务挂了怎么查
- 日志在哪
- 常见错误怎么判断
docs/architecture.md
只写结构和边界：
- 项目目录
- 运行边界
- 请求流
- 配置层级
这次为什么要分层写
因为如果把这些东西全部塞进一个文档里，后面很容易出现三种混乱：
- 本机源码真源和服务器运行目录混写
- 配置模板和真实配置混写
- 结构说明、部署说明、运维说明混写
分层之后，后续任何人都能直接按文件定位：
- 看项目是什么，先看
README.md - 看结构，先看
docs/architecture.md - 看怎么发版，先看
docs/deploy.md - 看怎么排障，先看
docs/runbook.md
这次的结论
项目的真源、运行边界、GitHub 来源和文档层级已经分开了。
以后同类项目就按这个结构写，不要再让本机、服务器、仓库三套东西互相抢真源。
