更新 AGENTS.md 文档，重构项目概览、构建与开发命令、代码风格与规范及行为准则部分

Author: miantiao-me

AGENTS.md

@@ -1,59 +1,123 @@
 # AI Agent 开发指南 (AGENTS.md)
 
-## 项目概览
-本项目是一个使用 Cloudflare Containers (支持 Docker 的 Workers) 的 Cloudflare Workers 项目。
-项目完全使用 TypeScript 编写，并依赖 `wrangler` CLI 进行开发和部署。
-
-**⚠️ 重要原则：本项目的官方语言为中文。所有的文档、注释、提交信息（Commit Messages）请务必使用中文。**
-
-## 构建与开发命令
-
-| 命令 | 说明 |
-|------|------|
-| `npm run dev` | 启动本地开发服务器 (`wrangler dev`) |
-| `npm run start` | `npm run dev` 的别名 |
-| `npm run deploy` | 部署到 Cloudflare (`wrangler deploy`) |
-| `npm run cf-typegen` | 生成 Cloudflare Bindings 的类型定义 (`wrangler types`) |
-
-> **关于测试**: 目前仓库中**没有任何测试框架或测试套件**。
-> 请勿尝试运行测试。如果任务要求添加测试，请建议使用 **Vitest**。
-
-## 代码风格与规范
-
-### 格式化 (Formatting)
-- **缩进**: 2 个空格。
-- **分号**: 语句末尾**不使用**分号 (ASI)。
-- **引号**: 字符串使用单引号 `'`。
-- **尾随逗号**: 在有效的地方使用尾随逗号 (ES2017+)。
-
-### 命名规范
-- **文件名**: `camelCase` (小驼峰)，例如 `container.ts`, `sse.ts`, `index.ts`。
-- **变量与函数**: `camelCase` (小驼峰)，例如 `verifyBasicAuth`, `processSSEStream`。
-- **类与组件**: `PascalCase` (大驼峰)，例如 `AgentContainer`。
-- **接口与类型**: `PascalCase` (大驼峰)，例如 `SSEEvent`。
-- **常量**: `UPPER_CASE` (全大写下划线)，例如 `PORT`, `SINGLETON_CONTAINER_ID`。
-
-### TypeScript 与类型
-- **严格模式**: 已启用 (`strict: true`)。尽可能避免使用 `any`。
-- **导出模式**: `index.ts` 的默认导出应使用 `satisfies ExportedHandler<Cloudflare.Env>`。
-- **环境变量**: 通过 `import { env } from 'cloudflare:workers'` 访问。
-
-### 架构模式
-- **Cloudflare 特性**:
-  - 使用 `cloudflare:workers` 和 `@cloudflare/containers`。
-  - `AgentContainer` 继承自 `Container`，用于处理 Durable Object/Container 逻辑。
-- **错误处理**:
-  - 对于预期的流程（如认证失败），优先返回 `null` 或特定的错误对象/Response，而不是抛出异常。
-  - 对于外部 IO/解析（如 SSE 流处理），必须使用 `try-catch` 块。
-- **注释**:
-  - **必须使用中文**编写所有新的注释和文档。
-  - 现有的英文注释在修改时建议翻译为中文。
-
-### 导入顺序
-1. 外部库 (`cloudflare:workers`, `@cloudflare/containers`)。
-2. 本地内部模块 (`./container`, `./sse`)。
-
-## Agent 行为准则
-1. **无测试环境**: 由于没有测试，必须通过仔细的代码审查和类型检查 (`npm run cf-typegen`) 来验证更改。
-2. **Wrangler 为准**: 认定 `wrangler` 配置文件和命令是 Bindings 和配置的唯一真理来源。
-3. **异步/Await**: 确保 Promise 被正确处理。注意：某些后台任务（如 `watchContainer`）在特定生命周期钩子（如 `onStart`）中可能**故意不被 await**，以避免阻塞，但需确保有错误捕获。
+## 1. 项目概览
+本项目是一个基于 **Cloudflare Workers** 和 **Cloudflare Containers** (Durable Objects) 的 TypeScript 项目。
+项目核心目标是利用 Cloudflare 的边缘基础设施来运行和管理容器化工作负载 (`AgentContainer`)。
+
+**⚠️ 核心原则：本项目的官方语言为中文。所有的文档、注释、提交信息（Commit Messages）必须使用中文。**
+
+## 2. 构建与开发命令
+
+由于本项目没有集成测试框架，开发流程严重依赖类型检查和本地模拟。
+
+| 命令 | 说明 | 备注 |
+|------|------|------|
+| `npm run dev` | 启动本地开发服务器 | 等同于 `wrangler dev` |
+| `npm run start` | `npm run dev` 的别名 | - |
+| `npm run deploy` | 部署到 Cloudflare | 等同于 `wrangler deploy` |
+| `npm run cf-typegen` | 生成 Cloudflare Bindings 类型 | 修改 `wrangler.jsonc` 后必须运行 |
+
+> **关于测试**: 
+> 目前仓库中**没有任何测试框架** (Jest/Vitest)。
+> 请勿尝试运行 `npm test`。
+> 如果需要验证逻辑，请依靠 TypeScript 编译器 (`npm run cf-typegen`) 和人工代码审查。
+
+## 3. 代码风格与规范 (Code Style)
+
+### 3.1 格式化 (Formatting)
+- **缩进**: 2 个空格 (2 Spaces)。
+- **分号**: 语句末尾**不使用**分号 (ASI 风格)。
+- **引号**: 字符串优先使用单引号 `'`。
+- **尾随逗号**: 在多行对象/数组定义中保留尾随逗号 (ES2017+)。
+- **代码块**: 始终使用花括号 `{ ... }`，即使是单行 `if` 语句。
+
+### 3.2 命名规范 (Naming Conventions)
+- **文件名**: 使用 `camelCase` (小驼峰)，例如 `container.ts`, `sse.ts`。
+- **类 (Classes)**: 使用 `PascalCase` (大驼峰)，例如 `AgentContainer`。
+- **接口/类型 (Interfaces/Types)**: 使用 `PascalCase`，例如 `SSEEvent`。
+- **变量/函数**: 使用 `camelCase`，例如 `verifyBasicAuth`, `processSSEStream`。
+- **常量**: 使用 `UPPER_CASE` (全大写下划线)，例如 `PORT`, `SINGLETON_CONTAINER_ID`。
+- **私有属性**: 类中的私有属性建议以 `_` 开头（可选），如 `_watchPromise`。
+- **布尔变量**: 建议使用 `is`, `has`, `should` 前缀，如 `isAuthorized`。
+
+### 3.3 TypeScript 最佳实践
+- **Strict Mode**: 严格模式已启用。**禁止**使用 `any`，除非万不得已。
+- **类型定义**: 
+  - 优先使用 `interface` 定义对象结构，使用 `type` 定义联合类型。
+  - 使用 `satisfies` 关键字来验证导出对象 (如 `export default { ... } satisfies ExportedHandler`)。
+- **环境绑定**: 只能通过 `import { env } from 'cloudflare:workers'` 访问环境变量。不要使用 `process.env`。
+- **空值处理**: 优先使用可选链 `?.` 和空值合并 `??`。
+
+### 3.4 导入顺序 (Import Order)
+保持清晰的导入分层：
+1. **外部依赖**: `cloudflare:workers`, `@cloudflare/containers` 等第三方库。
+2. **内部模块**: `./container`, `./sse` 等本地文件。
+3. **类型导入**: `import type { ... }` 显式区分类型导入。
+
+## 4. 架构与设计模式
+
+### 4.1 Worker 入口与路由
+- `src/index.ts` 是 Worker 的入口点。
+- 它负责处理 HTTP 请求路由、基本的身份验证 (`verifyBasicAuth`) 和请求转发。
+- **模式**: 函数优先返回 `null` 表示“无错误/继续处理”，返回 `Response` 对象表示“拦截/错误”。
+  ```typescript
+  // 示例模式
+  function checkAuth(req): Response | null {
+    if (fail) return new Response('401', ...);
+    return null; // Pass
+  }
+  ```
+
+### 4.2 AgentContainer (Durable Object)
+- 位于 `src/container.ts`。
+- 继承自 `Container` (来自 `@cloudflare/containers`)。
+- **Singleton 模式**: 通过 `idFromName(SINGLETON_CONTAINER_ID)` 确保全局唯一实例，便于状态管理。
+- **生命周期**:
+  - `onStart`: 容器启动钩子。用于初始化后台任务。
+  - **重要**: 后台任务 (如 `watchContainer`) 在 `onStart` 中**不应被 await**，以避免阻塞 DO 的启动过程，但必须捕获错误 (fire-and-forget 模式)。
+
+### 4.3 错误处理 (Error Handling)
+- **HTTP 错误**: 优先返回标准的 HTTP 状态码 Response (401, 403, 500)。
+- **外部 I/O**: 对所有网络请求 (fetch, stream reading) 必须使用 `try-catch` 包裹。
+- **SSE 流**: 处理 Server-Sent Events 时，需确保 Reader 的生命周期管理，并在连接断开时优雅退出，避免资源泄漏。
+
+## 5. Agent 行为准则 (Behavior Guidelines)
+
+当作为 AI Agent 修改此代码库时，请严格遵循以下规则：
+
+1.  **语言一致性**: 
+    - 所有的代码注释必须使用**中文**。
+    - Git Commit Message 必须使用**中文**。
+    - **禁止**在代码中混用英文注释。
+
+2.  **无损修改**:
+    - 在没有测试的情况下，修改代码时必须极其谨慎。
+    - 每次修改后，建议运行 `npm run cf-typegen` 确保类型定义与 `wrangler.jsonc` 保持同步。
+    - 修改现有功能前，务必理解其副作用 (Side Effects)。
+
+3.  **配置为王**:
+    - `wrangler.jsonc` 是基础设施配置的唯一真理来源 (Source of Truth)。
+    - 不要硬编码配置值 (如端口、密钥)，应使用 Bindings 或环境变量。
+    - 如果代码中需要新变量，必须先更新 `wrangler.jsonc` 并运行 `cf-typegen`。
+
+4.  **文件操作**:
+    - 优先修改现有文件，避免创建过多的碎片化小文件。
+    - `worker-configuration.d.ts` 是自动生成的，**不要手动修改**它。
+    - 保持目录结构扁平化，不要过度嵌套。
+
+5.  **依赖管理**:
+    - 仅使用 `package.json` 中定义的依赖。
+    - 如需引入新库，需先评估其在 Cloudflare Workers Runtime 中的兼容性 (注意：Node.js API 支持有限)。
+    - 尽量使用 Web Standard APIs (Request, Response, fetch, Streams) 而非 Node.js 特有 API。
+
+## 6. 工具链说明
+
+- **Wrangler**: 核心 CLI 工具。所有部署、开发、配置都通过它完成。
+- **ESLint/Prettier**: 目前项目中未显式配置，请遵循现有代码的风格（参考 3.1 节）。
+- **Git**: 提交前请检查 diff，确保没有引入无用的空白字符变更。
+
+## 7. Cursor/Copilot 规则集成
+*(本项目暂未发现 `.cursorrules` 或 `.github/copilot-instructions.md` 文件。若后续添加，请在此处补充相关规则)*
+
+---
+*此文档由 AI Agent 维护，旨在统一开发标准与行为规范。*