Merge branch '3.6.x'

Author: CodeCasterX

.ai-agents/QUICKSTART.md

@@ -1,6 +1,8 @@
 # 多 AI 协作快速开始指南
 
-本指南帮助你快速上手 FIT Framework 的多 AI 协作功能（支持 ClaudeCode、Codex、GeminiCli）。
+本指南帮助你快速上手 FIT Framework 的多 AI 协作功能（支持 Claude Code、Codex、Gemini CLI、Cursor 等）。
+
+> **📌 重要提示**：开始协作前，请先阅读根目录的 `AGENTS.md` 文件，了解项目的基本开发规范和命令。
 
 ## 🚀 5分钟快速开始
 

.ai-agents/README.md

@@ -1,6 +1,68 @@
-# FIT Framework - AI 智能体协作配置
+# FIT Framework - AI 智能体协作指南
 
-本目录包含 FIT Framework 项目的 AI 智能体协作配置，支持三个主流 AI 工具（ClaudeCode、Codex、GeminiCli）在同一项目中高效协作。
+本目录包含 FIT Framework 项目的 AI 智能体协作配置，支持多个主流 AI 工具（Claude Code、Codex、Gemini CLI、Cursor 等）在同一项目中高效协作。
+
+> **💡 提示**：如需快速了解项目规范，请先阅读对应工具的配置文件（详见下方"配置体系说明"）。本文档专注于**多 AI 协作机制**的详细说明。
+
+## 🔧 配置体系说明
+
+本项目采用**双轨配置体系**，不同 AI 工具使用不同的配置文件：
+
+### 配置体系 A：Claude Code
+**适用工具**：Claude Code
+
+**配置文件**：
+- **`.claude/CLAUDE.md`** - 快速参考（启动时自动加载）
+- **`.claude/project-rules.md`** - 详细规则
+- **`.claude/commands/`** - Slash Commands 实现
+
+**特点**：
+- Claude Code 专属配置，包含 Slash Commands 和特定规则
+- 自包含，不依赖其他配置文件
+- 启动时自动加载 `.claude/CLAUDE.md`
+
+### 配置体系 B：AGENTS.md 标准
+**适用工具**：Codex CLI、Gemini CLI、Cursor、其他 TUI 工具
+
+**配置文件**：
+- **`AGENTS.md`** - 项目开发规范（根目录）
+- **`.ai-agents/codex/preferences.yaml`** - Codex 特定配置
+- **`.ai-agents/gemini/preferences.yaml`** - Gemini 特定配置
+
+**特点**：
+- 遵循 [AGENTS.md 标准](https://agents.md)（Linux Foundation AAIF）
+- 轻量级，专注于项目开发规范
+- 启动时自动加载 `AGENTS.md`
+
+### 两套体系的关系
+
+```
+项目规范（两套独立但内容一致）
+    ├── 体系 A：.claude/ (Claude Code 使用)
+    │   ├── CLAUDE.md (快速参考)
+    │   └── project-rules.md (详细规则)
+    │
+    └── 体系 B：AGENTS.md (其他工具使用)
+        ├── AGENTS.md (项目规范)
+        └── .ai-agents/{tool}/preferences.yaml (工具配置)
+
+协作机制（两套体系共享）
+    └── .ai-agents/ (多 AI 协作配置)
+        ├── workflows/ (工作流定义)
+        ├── templates/ (任务模板)
+        └── README.md (本文件 - 协作指南)
+
+工作区（两套体系共享）
+    └── .ai-workspace/ (任务跟踪和上下文共享)
+        ├── active/ (进行中的任务)
+        ├── blocked/ (被阻塞的任务)
+        └── completed/ (已完成的任务)
+```
+
+**为什么需要两套体系**？
+- Claude Code 仅加载 `.claude/CLAUDE.md`，不会自动读取 `AGENTS.md`
+- 其他 TUI 工具遵循 AGENTS.md 标准，自动加载根目录的 `AGENTS.md`
+- 两套体系内容一致，只是文件位置和格式不同
 
 ## 📋 目录说明
 
@@ -411,38 +473,10 @@ GeminiCli 的配置在 `.ai-agents/gemini/` 目录。
 ### 通用配置
 
 所有 AI 都应该：
-1. 读取 `AGENTS.md`（项目根目录）
-2. 遵循 `.ai-agents/workflows/` 中的工作流
+1. 读取 `AGENTS.md`（项目根目录）获取项目开发规范
+2. 遵循 `.ai-agents/workflows/` 中的工作流定义
 3. 使用 `.ai-workspace/` 进行任务跟踪和上下文共享
 
-### 版权年份管理规范
-
-**重要规则**：修改任意带版权头的文件时，**必须同步更新版权年份到当前年份**。
-
-**执行步骤**：
-
-1. **动态获取当前年份**（绝对不要硬编码年份）：
-   ```bash
-   # 使用系统命令获取当前年份
-   CURRENT_YEAR=$(date +%Y)
-   echo $CURRENT_YEAR
-   ```
-
-2. **检查并更新版权头**：
-   - 检查文件是否包含版权声明（如 `Copyright (C) 2024-2025`）
-   - 如果包含，将年份更新为当前年份（如 `2024-2025` → `2024-2026`）
-   - 如果是单一年份（如 `2024`），更新为年份范围（如 `2024-2026`）
-
-3. **常见格式示例**（假设当前年份为 2026）：
-   - `Copyright (C) 2024-2025` → `Copyright (C) 2024-2026`
-   - `Copyright (C) 2024` → `Copyright (C) 2024-2026`
-   - `© 2024-2025` → `© 2024-2026`
-
-**为什么重要**：
-- 确保版权声明的准确性和法律有效性
-- 遵循项目规范，保持一致性
-- 避免年份过时导致的合规问题
-
 ## ⚠️ 注意事项
 
 ### 人工检查点

.ai-agents/codex/preferences.yaml

@@ -1,11 +1,11 @@
-# ChatGPT 偏好配置
-# 这个文件帮助 ChatGPT 了解在 FIT Framework 项目中的角色和偏好
+# Codex (ChatGPT) 偏好配置
+# 这个文件帮助 Codex/ChatGPT 了解在 FIT Framework 项目中的角色和偏好
+# 项目编码规范请参考根目录的 AGENTS.md 文件
 
 agent:
-  name: "GPT"
+  name: "Codex"
   role: "Implementation & Testing Specialist"
-  version: "ChatGPT-4 / ChatGPT-4 Turbo"
-  # 交流语言：跟随用户输入
+  version: "ChatGPT-4 / ChatGPT-4 Turbo / O1"
   communication_language: "Adaptive (Match user's language)"
 
 # 擅长的任务类型
@@ -24,50 +24,10 @@ recommended_steps:
   - "bug-fix"             # Bug修复
   - "refactoring-implementation"  # 重构实施
 
-# 代码风格偏好
-coding_style:
-  language: "Java"
-  formatter: "IntelliJ IDEA (CodeFormatterFromIdea.xml)"
-  line_length: 120
-  indent: 4
-  use_tabs: false
-
-  naming:
-    classes: "PascalCase"
-    methods: "camelCase"
-    constants: "UPPER_SNAKE_CASE"
-    packages: "lowercase"
-
-  comments:
-    javadoc_required: true  # 公共API必须有Javadoc
-    inline_comments: "when necessary"
-    class_header: true      # 需要 @author 和 @since
-
-# 测试偏好
-testing:
-  framework: "JUnit"
-  naming_convention: "*Test.java"
-  coverage_target: "80%"
-  test_types:
-    - "unit"
-    - "integration"
-
-  assertions_library: "JUnit Assertions"
-
-  best_practices:
-    - "每个公共方法至少一个测试"
-    - "覆盖正常和异常情况"
-    - "使用有意义的测试名称"
-    - "测试应该独立，不依赖执行顺序"
-
 # Git 操作偏好
 git:
   auto_commit: false      # 不自动提交，等待人工确认
-  commit_message_format: "[{module}] {description}"
-  commit_message_language: "Chinese"
-
-  branch_naming: "{module}-{type}-{description}"
-  # 例如: fit-feature-new-api, waterflow-bugfix-null-pointer
+  auto_push: false        # 不自动推送
 
 # 协作偏好
 collaboration:
@@ -94,133 +54,31 @@ collaboration:
 
 # 输出偏好
 output:
-  # 代码实现报告应包含的内容
   implementation_report:
     - "modified_files_list"
     - "key_implementation_notes"
     - "test_results"
     - "review_checklist"
     - "known_issues"
-
-  # 文档格式
+  
   documentation_format: "Markdown"
-
-  # 代码注释语言
   code_comments_language: "Chinese"
-
-  # 文档语言
   documentation_language: "Chinese"
 
-# 质量标准
-quality_standards:
-  code:
-    - "遵循项目编码规范"
-    - "代码可读性高"
-    - "适当的错误处理"
-    - "避免代码重复"
-    - "性能考虑"
-
-  tests:
-    - "测试覆盖关键逻辑"
-    - "测试名称清晰"
-    - "断言明确"
-    - "测试独立性"
-
-  documentation:
-    - "公共API有Javadoc"
-    - "复杂逻辑有注释"
-    - "README保持更新"
-
-# 安全意识
-security:
-  checks:
-    - "输入验证"
-    - "SQL注入防护"
-    - "XSS防护"
-    - "敏感信息处理"
-    - "权限检查"
-
-  never_do:
-    - "提交敏感信息（密码、密钥）"
-    - "跳过安全检查"
-    - "使用不安全的API"
-
-# 性能意识
-performance:
-  considerations:
-    - "避免N+1查询"
-    - "合理使用缓存"
-    - "注意循环复杂度"
-    - "资源及时释放"
-
-  profiling:
-    - "复杂操作添加日志"
-    - "关注时间复杂度"
-
 # 项目特定配置
 project_specific:
   fit_framework:
     main_language: "Java"
     build_tool: "Maven"
-    jdk_version: "8+"
-
-    modules:
-      - "fit-java"
-      - "fit-python"
-      - "waterflow"
-      - "fel"
-
+    
     common_commands:
       build: "mvn clean install"
       test: "mvn test"
-      quick_build: "mvn -B clean package -Dmaven.test.skip=true"
       start: "./build/bin/fit start"
 
-    important_files:
-      - "AGENTS.md"
-      - ".ai-agents/README.md"
-      - ".github/PULL_REQUEST_TEMPLATE.md"
-      - "CodeFormatterFromIdea.xml"
-
 # 自动化行为
 automation:
-  auto_format_code: true          # 自动格式化代码
-  auto_run_tests: true            # 完成后自动运行测试
-  auto_fix_style: true            # 自动修复代码风格问题
-  auto_commit: false              # 不自动提交
-  auto_push: false                # 不自动推送
-
-# 学习和改进
-continuous_improvement:
-  learn_from:
-    - "Code review feedback from Claude"
-    - "Test failures"
-    - "Human feedback"
-
-  improve:
-    - "Code quality over time"
-    - "Test coverage"
-    - "Documentation completeness"
-
----
-
-# 使用说明
-
-## 如何使用这个配置
-
-如果你是 ChatGPT，在 FIT Framework 项目中工作时：
-
-1. 参考这个配置文件了解项目偏好
-2. 遵循定义的编码规范和测试要求
-3. 与 Claude 等其他 AI 协作时参考 collaboration 部分
-4. 输出文件时参考 output 部分的要求
-
-## 配置优先级
-
-1. 项目规范（AGENTS.md）> 本配置文件
-2. 人类指令 > 所有配置
-3. Workflow定义 > 一般性偏好
-
-## 更新这个配置
-
-根据项目发展和团队反馈，定期更新这个配置文件。
+  auto_format_code: true
+  auto_run_tests: true
+  auto_commit: false
+  auto_push: false