sse-connection-governance-demo

Imported from wsll1215/sse-connection-governance-demo (AGENTS.md). Install upstream with npx skills add wsll1215/sse-connection-governance-demo. Copyright stays with the author.

AGENTS.md

本文件是 AI 协作入口。只放规则和索引——具体内容见下方文件。 任何补充规范先落到 .agents/*.md，本文件保持精简。

技术栈

• Next.js 15（App Router）+ React 19 + TypeScript 5（strict: true）
• 包管理器：npm（存在 package-lock.json）
• 路径别名：@/* → ./*（直接指向项目根，非 src/）
• 格式化：Prettier（双引号 + 有分号 + 2 空格）
• 语言环境：html lang="zh-CN"，界面文案使用中文
• 运行时特性：SSE（fetch + ReadableStream）、BroadcastChannel、SharedWorker

脚本

索引（详细规范）

• .agents/PROJECT_STRUCTURE.md — 目录结构与文件归属
• .agents/CONVENTIONS.md — 编码约定 + 完整 Never 规则
• .agents/ARCHITECTURE.md — 传输层抽象与连接治理架构

个人偏好见 AGENTS.local.md（不入仓库）。

核心 Never 规则（精简版）

1. Never 修改 .next/、.next-stale-*/、tsconfig.tsbuildinfo
2. Never 修改 node_modules/、package-lock.json（除非新增依赖且与用户确认）
3. Never 在组件、Hook、传输层中使用 any 类型
4. Never 在业务代码中直接调用 fetch/EventSource — 通过 lib/*-transport.ts 封装
5. Never 把源码移到 src/ 下或新建 services/、models/、utils/ 等传统分层目录
6. Never 改变 Prettier 风格（双引号、有分号、2 空格、printWidth: 100）
7. Never 在客户端硬编码服务端密钥、连接 ID 或敏感配置
8. Never 跳过 TypeScript 类型检查（@ts-ignore / @ts-nocheck / // @ts-expect-error 无说明）

完整 Never 规则与理由见 .agents/CONVENTIONS.md 与 .agents/ARCHITECTURE.md。

协作约定

• Commit 格式：type(scope): description，类型限于 feat / fix / docs / style / refactor / test / chore
• Never 使用 git stash、切换分支（多 Agent 并发安全）
• 修改 package.json / tsconfig.json / next.config.ts 前先与用户确认
• 任何偏离既有规范（目录、命名、Prettier、传输抽象）的改动，必须先说明理由再实施

本地开发服务器约束

• 同一仓库同时只能运行一个 Next.js 开发服务器，固定使用 http://localhost:3000。
• Never 为同一仓库启动第二个端口（例如 3001），也不要让 Next.js 在 3000 被占用时自动切换端口。
• 每次修改代码后，必须确认现有开发服务器已完成 Fast Refresh/重新编译，并通过 http://localhost:3000 验证页面返回正常；不能只依赖静态构建结果。
• 启动前先检查 3000 端口和现有 Next.js 进程。发现同仓库的重复进程、旧进程或端口漂移时，先停止明确属于本仓库的进程，再只启动一个 3000 实例。
• 不要同时运行 next dev 和 next start，避免多个进程竞争 .next 产物并造成 clientReferenceManifest 不一致。