# 仓库协作指南

## 项目结构与模块组织
- `src/main.ts`：应用入口，注册 Pinia 与 Router。
- `src/views/**`：路由级页面，功能页使用 `*Page.vue` 命名。
- `src/components/layout`：布局壳组件；`src/components/common`：可复用通用组件。
- `src/stores`：Pinia 领域状态（auth、websocket、session、channel、config 等）。
- `src/api`：WebSocket/RPC 集成；共享类型位于 `src/api/types`。
- `src/composables` 与 `src/utils`：可复用逻辑与纯函数工具。
- `src/assets/styles/main.css`：全局样式；`public/`：静态资源。

## 构建、测试与开发命令
- `npm install`：安装依赖。
- `npm run dev`：启动 Vite 开发服务（`http://localhost:3001`）。
- `npm run build`：执行 `vue-tsc -b` 类型检查并产出 `dist/` 生产包。
- `npm run preview`：本地预览生产构建结果。

## 代码风格与命名规范
- 使用 Vue 3 Composition API + `<script setup lang="ts">`。
- 遵循现有格式：2 空格缩进、单引号、尾随逗号、无分号。
- `src` 路径优先使用 `@/` 别名导入。
- 命名约定：
  - 组件：`PascalCase.vue`
  - 路由页面：`*Page.vue`（例如 `SessionsPage.vue`）
  - store/composable/utils：简洁的小写或 camelCase 文件名（例如 `session.ts`、`useTheme.ts`）

## 测试要求
- 当前仓库尚未配置自动化测试框架。
- 合并前必须检查：
  - `npm run build` 通过，无类型与构建错误。
  - 针对改动流程做手工冒烟测试（登录、WebSocket 连接、相关页面），并连接可用 Gateway（`ws://127.0.0.1:18789`）。
- 对于非简单逻辑改动，请在 PR 中附测试计划；后续迭代优先补充 Vitest 单元测试。

## 提交与 PR 规范
- 提交前缀建议使用 Conventional Commit：`feat:`、`fix:`、`refactor:`、`docs:`、`chore:`。
- 每个提交只关注一个主题，避免占位式提交信息。
- PR 需包含：目标、关键改动、关联任务/Issue、验证步骤，以及 UI 改动截图/GIF。

## 安全与配置提示
- 禁止提交真实 Gateway Token、凭证或其他敏感信息。
- 运行时配置放在 `.env.development` / `.env.production`，新增 `VITE_` 变量需同步记录到 `README.md`。

## Codex 宪法（本仓库）
- 事实优先：先读现状再改代码；不得基于猜测修改 RPC、类型或页面行为。
- 单一来源：同一能力只保留一个权威入口与实现，避免页面与 store 双重定义。
- 兼容优先：优先适配现有 Gateway RPC 形态，不引入未经验证的新协议分支。
- 渐进改造：先打通最小闭环（可用），再做视觉与体验增强，避免一次性过度重构。
- 安全默认：凭证永不明文回显；未输入新值不得提交凭证 patch。
- 主题一致：样式优先复用全局变量（`--bg-*`、`--text-*`、`--border-color`），避免硬编码颜色。
- 渲染边界清晰：凡是 `v-html` 注入内容，若页面使用 `<style scoped>`，必须使用 `:deep(...)`（或改为非 scoped 受控样式）覆盖其内部元素；禁止误以为 scoped 选择器可直接命中运行时注入节点。
- 可验证：每次改动后至少保证可构建，并说明影响面与回归点。

## 实施教训（频道管理改造）
- 组件默认样式有“首项特例”（如 `Collapse` 的 first-child 规则），改间距前必须先核对组件源码。
- 间距系统必须“单机制”管理（统一使用 gap 或 margin），混用会造成首行/后续行视觉不一致。
- 暗色适配不能只改颜色值，应以主题变量驱动并限制选择器作用域，避免污染其他页面。
- 遇到“看起来像 spacing 问题”的异常，通常同时涉及 `margin/padding/border` 叠加，需要逐层排查。
- UI 微调应先保证信息架构不变，再收敛 spacing 与密度，避免视觉改善引发交互回归。
