# Boss 仓库目录地图

这份文档只回答一个问题：哪些目录是当前有效的，哪些只是参考或占位。

## 1. 当前有效目录

| 路径 | 状态 | 作用 |
| --- | --- | --- |
| `src/app` | 当前有效 | Next.js 页面和 API 路由 |
| `src/components` | 当前有效 | 页面共享 UI 和交互组件 |
| `src/lib` | 当前有效 | 数据模型和聚合投影视图 |
| `local-agent` | 当前有效 | 本地设备端心跳与 thread-context 上报服务 |
| `deployment` | 当前有效 | `Caddy`、`systemd`、`launchd` 配置 |
| `scripts` | 当前有效 | 本地启动、安装、远端部署脚本 |
| `android` | 当前有效 | 原生 Android 客户端工程与 APK 构建目录 |
| `design/pencil` | 当前有效 | Pencil 原稿 |
| `design/exports/ui-codex-ops-mobile-v13` | 当前有效 | 最新导出图 |
| `docs/architecture` | 当前有效 | 当前权威中文文档 |
| `prompts` | 当前有效 | 交给其他 AI 的提示词 |
| `data/boss-state.json` | 当前有效 | 当前 MVP 的真实持久化状态文件 |
| `data/boss-state.json.bak` | 当前有效 | 状态文件解析失败时的自动恢复备份 |
| `.env.server.example` | 当前有效 | 服务器可覆盖环境变量示例 |
| `public/downloads` | 当前有效 | 当前已发布的 OTA APK 与元数据 |
| `local-agent/config.cloud.json` | 当前有效 | 本机常驻 agent 对接 `https://boss.hyzq.net` 的生产配置 |
| `local-agent/config.example.json` | 当前有效 | 本地 `127.0.0.1:3000` 回环开发配置 |
| `android/signing/release-signing.properties.example` | 当前有效 | release 签名参数模板 |

## 2. 当前参考目录

| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `docs/source-material` | 参考材料 | 历史方案、原始文档、图和外部资料备份，不是运行时真相 |
| `docs/diagrams` | 参考材料 | 架构和流程图素材 |

## 3. 当前占位或未启用目录

| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `deploy` | 空占位 | 不参与当前部署 |
| `src/boss_control` | 空占位 | 不参与当前 Web 运行 |
| `src/boss_device_agent` | 空占位 | 不参与当前 device-agent 运行 |
| `docs/deployment` | 预留 | 主要部署文档实际写在 `docs/architecture` |
| `docs/prompts` | 预留 | 当前实际提示词在 `prompts/` |

## 4. 生成目录

| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `.next` | 生成目录 | Next.js 构建产物 |
| `node_modules` | 生成目录 | 依赖安装目录 |

## 5. 当前最值得直接查看的文件

源码：

- `src/app/conversations/page.tsx`
- `src/app/conversations/[projectId]/page.tsx`
- `src/app/conversations/[projectId]/forward/page.tsx`
- `src/app/threads/[threadId]/page.tsx`
- `src/app/devices/page.tsx`
- `src/app/me/ai-accounts/page.tsx`
- `src/app/me/skills/page.tsx`
- `src/app/api/v1/accounts/route.ts`
- `src/app/api/v1/accounts/[accountId]/route.ts`
- `src/app/api/v1/accounts/[accountId]/activate/route.ts`
- `src/app/api/v1/accounts/[accountId]/validate/route.ts`
- `src/app/api/auth/session/route.ts`
- `src/app/api/auth/restore/route.ts`
- `src/app/api/auth/logout/route.ts`
- `src/app/api/v1/master-agent/tasks/claim/route.ts`
- `src/app/api/v1/master-agent/tasks/[taskId]/complete/route.ts`
- `src/app/api/v1/app-logs/route.ts`
- `src/app/api/v1/events/route.ts`
- `src/app/api/v1/user/ota/package/route.ts`
- `src/app/api/v1/devices/[deviceId]/skills/route.ts`
- `src/app/me/settings/page.tsx`
- `src/components/app-runtime.tsx`
- `src/lib/boss-app-client.ts`
- `src/app/api/device-heartbeat/route.ts`
- `src/app/api/v1/conversations/route.ts`
- `src/app/api/v1/projects/[projectId]/route.ts`
- `src/app/api/v1/workers/[workerId]/thread-context/route.ts`
- `src/lib/boss-data.ts`
- `src/lib/boss-auth.ts`
- `src/lib/boss-device-auth.ts`
- `src/lib/boss-events.ts`
- `src/lib/boss-mail.ts`
- `src/lib/boss-master-agent.ts`
- `src/lib/boss-ota.ts`
- `src/lib/boss-projections.ts`
- `local-agent/server.mjs`

部署：

- `deployment/Caddyfile`
- `deployment/mail/install-postfix-dovecot.sh`
- `deployment/mail/sync-caddy-mail-cert.sh`
- `deployment/mail/systemd/boss-mail-cert-sync.service`
- `deployment/mail/systemd/boss-mail-cert-sync.timer`
- `deployment/systemd/boss-web.service`
- `deployment/launchd/com.hyzq.boss.local-agent.plist`
- `scripts/deploy-server.sh`
- `scripts/publish-apk-to-public.sh`
- `scripts/prepare-android-signing.sh`
- `scripts/build-release-apk.sh`
- `scripts/install-server-mail.sh`
- `scripts/bootstrap-server.sh`
- `android/app/src/main/java/com/hyzq/boss/MainActivity.java`
- `android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
- `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
- `android/app/src/main/java/com/hyzq/boss/DeviceDetailActivity.java`
- `android/app/src/main/java/com/hyzq/boss/AiAccountsActivity.java`
- `android/app/src/main/java/com/hyzq/boss/OpsCenterActivity.java`
- `android/app/src/main/java/com/hyzq/boss/WechatSurfaceMapper.java`
- `android/app/src/main/res/layout/activity_project_chat.xml`
- `android/app/build/outputs/apk/debug/app-debug.apk`

文档：

- `README.md`
- `docs/architecture/ai_handoff_index_cn.md`
- `docs/architecture/current_runtime_and_deploy_status_cn.md`
- `docs/architecture/api_and_service_inventory_cn.md`

## 6. 目录判断原则

如果你需要继续开发：

- 以 `src/app`、`src/lib`、`local-agent`、`deployment` 为主线
- 以 `docs/architecture` 为权威描述
- 以 `docs/source-material` 为补充参考
- 不要把空占位目录误认成另一套现成实现