# 项目目录说明

日期：2026-05-27

## 目的

这份文档用于回答两个问题：

1. 当前仓库各一级目录分别负责什么
2. 新增文件应该放到哪里，避免继续把运行时脚本、部署资产、验收证据混在一起

它不替代 `README.md`，而是补充更细的目录职责说明。

## 一级目录

### `cmd/`

程序入口：

- `cmd/server`
  - 控制面 HTTP 服务入口
- `cmd/cli`
  - 导入、overlay、验证等命令行入口

### `internal/`

控制面核心实现，按职责拆分：

- `internal/access`
  - access closure、自愈、gateway 验证
- `internal/app`
  - HTTP API、bootstrap、后台任务
- `internal/batch`
  - batch import 请求与状态投影
- `internal/config`
  - 配置装载
- `internal/host/sub2api`
  - 宿主适配器
- `internal/overlay`
  - host overlay 执行器
- `internal/pack`
  - pack 装载、校验、overlay 解析
- `internal/probe`
  - upstream / host smoke probes
- `internal/provision`
  - import / preview / rollback / reconcile 编排
- `internal/reconcile`
  - 后台对账
- `internal/store`
  - SQLite repo 与 migrations
- `internal/testutil`
  - 测试辅助
- `internal/worker`
  - 后台 runner

### `packs/`

版本化模型包资产：

- `packs/openai-cn-pack`
  - provider manifests
  - checksums
  - overlay metadata

这层只放 pack 资产，不放远端站点静态页。

### `deploy/`

面向部署目标的静态资产或配置模板。

当前已经纳入：

- `deploy/tksea-portal/index.html`
  - `sub.tksea.top/portal/` 静态页
- `deploy/tksea-portal/admin/index.html`
  - `sub.tksea.top/portal/admin/` 管理首页
- `deploy/tksea-portal/admin/providers.html`
  - `sub.tksea.top/portal/admin/providers.html` provider 目录、导入页与服务端草稿入口
- `deploy/tksea-portal/admin/batch-import.html`
  - `sub.tksea.top/portal/admin/batch-import.html` 结构化 batch-import 入口
- `deploy/tksea-portal/admin-batch-import.html`
  - `sub.tksea.top/portal/admin-batch-import.html` 最小管理页
- `deploy/tksea-portal/nginx.sub.tksea.top.conf.example`
  - 对应 Nginx 路由示例
  - 同时包含 `/portal-proxy/` 和 `/portal-admin-api/` 两组反代

这层的规则是：

- 放“部署产物模板”
- 不放需要编译的 Go 代码
- 不放临时 `/tmp` 产物

### `scripts/`

运维、验收、部署脚本，当前已经按用途拆成三层目录：

- `scripts/deploy/`
  - 部署与环境拉起脚本
  - 例如 `build_local_image.sh`、`setup_remote43_patched_stack.sh`、`deploy_tksea_portal.sh`
  - 其中 `setup_remote43_patched_stack.sh` 现会同步生成 remote43 固定仓库工作副本：
    - `/home/ubuntu/sub2api-cn-relay-manager-git-current`
    - 供 `SUB2API_CRM_REPO_ROOT` 与 provider 草稿发布链复用
- `scripts/acceptance/`
  - 真实宿主验收与证据处理脚本
  - 例如 `real_host_acceptance.sh`、`import_remote43_provider.sh`、`check_deepseek_completion_split.sh`
- `scripts/test/`
  - 脚本资产回归
  - 例如 `test_real_host_scripts.sh`、`test_tksea_portal_assets.sh`

规则：

- 只放可执行运维脚本
- 新脚本必须先判断属于 `deploy/`、`acceptance/` 还是 `test/`
- 脚本依赖的静态模板应尽量放到 `deploy/` 或 `docs/`

### `docs/`

所有长期保留文档：

- 真相入口
- 执行板
- 验收 runbook
- provider 矩阵
- 外部 OpenClaw 验证
- 目录与部署说明

### `tests/`

集成测试套件：

- `tests/integration`

### `artifacts/`

真实验收产物与归档证据。

规则：

- `artifacts/real-host-acceptance/`
  - 当前最终证据
- `artifacts/real-host-acceptance-archive/`
  - 历史调试样本与归档

不要把部署模板、静态页、脚本说明放到这里。

### `web/`

保留给未来管理端前端实现。

当前公网 portal 已经独立作为 `deploy/tksea-portal/` 静态资产纳管，不应误放进 `web/`，因为它不是控制面管理后台。

## 当前推荐放置规则

新增文件时，优先按下面规则归类：

- 新的 provider / pack 元数据
  - 放 `packs/`
- 新的 Go 业务逻辑
  - 放 `internal/`
- 新的 CLI 或 server 入口
  - 放 `cmd/`
- 新的线上静态部署页 / 反向代理模板
  - 放 `deploy/`
- 新的运维或验收命令脚本
  - 放 `scripts/deploy`、`scripts/acceptance` 或 `scripts/test`
- 新的长期说明文档
  - 放 `docs/`
- 新的验收证据
  - 放 `artifacts/`

## 当前整理结果

截至 2026-05-27，最近一轮目录整理主要做了三件事：

1. 把原来只存在 `/tmp` 的 `sub.tksea.top` portal 静态页与 Nginx 规则正式纳入仓库
2. 把 portal 部署动作收口到 `scripts/deploy/deploy_tksea_portal.sh`
3. 把 `scripts/` 从全平铺整理为 `deploy/`、`acceptance/`、`test/` 三层，减少脚本入口混杂
4. 把“公网 portal / OpenClaw / remote43 验收”相关说明分别挂回 `deploy/`、`scripts/`、`docs/`