From 3d5724dbd7dc652a59431055150ccdb1582082c8 Mon Sep 17 00:00:00 2001
From: Linkon <116425752+Linkon-lcw@users.noreply.github.com>
Date: Sat, 21 Mar 2026 01:52:07 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0AGENTS.MD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

由oMo/init-deep和GPT5.3codex生成
---
 agents.md           | 73 +++++++++++++++++++++++++++++++++++++--------
 old-ss/AGENTS.md    | 32 ++++++++++++++++++++
 src-tauri/AGENTS.md | 47 +++++++++++++++++++++++++++++
 src/AGENTS.md       | 46 ++++++++++++++++++++++++++++
 4 files changed, 186 insertions(+), 12 deletions(-)
 create mode 100644 old-ss/AGENTS.md
 create mode 100644 src-tauri/AGENTS.md
 create mode 100644 src/AGENTS.md

diff --git a/agents.md b/agents.md
index 4791322..436cee3 100644
--- a/agents.md
+++ b/agents.md
@@ -1,15 +1,64 @@
-# Agent Collaboration Rules
+# 项目知识库（SecScore）
 
-## 分支定位
-- 当前分支（`SecScore-tauri`）主要用于推进 Tauri 版本开发与维护。
-- 不以 Electron 版本作为该分支的实现目标。
+**生成时间：** 2026-03-21 01:41:11  
+**分支：** `tauri-dev`  
+**基线提交：** `517ce1e`
 
-## 提交规范
-- 每次代码改动都必须使用中文 `commit message`。
-- 完成提交后必须推送到远程仓库对应分支（`git push`）。
+## 概览
 
-## 执行流程
-1. 完成代码修改。
-2. 自检并确保可构建/可运行。
-3. 使用中文提交信息执行 `git commit`。
-4. 立即执行 `git push` 推送远程。
+SecScore 当前主线为 Tauri 桌面应用：前端 `React + TypeScript + Vite`，后端 `Rust + Tauri + SeaORM`。  
+仓库中存在 `old-ss/`（Electron 历史代码），默认按遗留参考处理，不作为本分支主实现目标。
+
+## 目录结构
+
+```text
+.
+├── src/                 # 前端 UI、状态与共享逻辑
+├── src-tauri/           # Rust/Tauri 后端与数据库
+├── old-ss/              # 历史 Electron 代码（遗留）
+├── scripts/             # 本分支启动脚本（如 tauri-dev）
+└── .github/workflows/   # 构建/发布流程
+```
+
+## 去哪里找
+
+| 任务                 | 位置                                 | 说明                                      |
+| -------------------- | ------------------------------------ | ----------------------------------------- |
+| 前端入口与全局初始化 | `src/main.tsx`                       | 注入 `window.api`、日志桥接、平台标识     |
+| 主应用路由与页面容器 | `src/App.tsx`                        | 页面切换、权限与流程协调                  |
+| Tauri 启动入口       | `src-tauri/src/main.rs`              | 仅调用 `secscore_lib::run()`              |
+| 后端命令注册总线     | `src-tauri/src/lib.rs`               | `invoke_handler` 注册命令与初始化流程     |
+| 数据库连接/同步核心  | `src-tauri/src/commands/database.rs` | 复杂热点文件，改动需重点回归              |
+| 前端构建配置         | `vite.config.ts`                     | `@` 别名、端口 `1420`、排除 `old-ss` 扫描 |
+| Tauri 构建配置       | `src-tauri/tauri.conf.json`          | `beforeDevCommand`、窗口/打包/插件设置    |
+
+## 关键约束
+
+- 当前开发目标：优先 Tauri 版本；不要把 Electron 新功能落在主线目录。
+- 提交信息使用中文；提交后需推送远程（按仓库现有协作约束执行）。
+- 包管理器默认使用 `pnpm`（注意：`src-tauri/tauri.conf.json` 的 `before*Command` 当前仍为 `npm run ...`）。
+- 代码风格以配置文件为准：`.editorconfig`、`eslint.config.mjs`、`.prettierrc.yaml`。
+
+## 反模式
+
+- 不要在 `src-tauri/src/commands/database.rs`、`src/components/Home.tsx` 等超大文件里继续堆叠新职责；先拆分再扩展。
+- 不要将 `old-ss/` 作为新功能主实现目录。
+- 不要绕过静态检查直接交付（至少通过 `lint` 与 `typecheck`）。
+
+## 常用命令
+
+```bash
+pnpm install
+pnpm dev
+pnpm tauri:dev
+pnpm lint
+pnpm typecheck
+pnpm build
+pnpm tauri:build
+```
+
+## 分层文档
+
+- 前端细则：`src/AGENTS.md`
+- Tauri/Rust 细则：`src-tauri/AGENTS.md`
+- 遗留目录边界：`old-ss/AGENTS.md`
diff --git a/old-ss/AGENTS.md b/old-ss/AGENTS.md
new file mode 100644
index 0000000..c5d044e
--- /dev/null
+++ b/old-ss/AGENTS.md
@@ -0,0 +1,32 @@
+# 遗留目录说明（old-ss）
+
+## 作用域
+
+本文件仅说明 `old-ss/` 的边界：该目录为 Electron 历史实现，默认仅作参考。
+
+## 目录定位
+
+- `old-ss/src/main/`：历史主进程实现。
+- `old-ss/src/renderer/`：历史渲染层实现。
+- `old-ss/src/mobile/`：历史移动端实验实现。
+- `old-ss/src/preload/`：历史预加载桥接实现。
+- `old-ss/src/shared/`：历史共享内核与规则引擎。
+
+## 工作边界
+
+- 当前主线开发默认不在 `old-ss/` 落新功能。
+- 仅在“迁移对照、行为回溯、数据兼容核对”场景读取本目录。
+- 若必须修改本目录，请在变更说明中标记“遗留修复”。
+
+## 反模式
+
+- 不要把新业务逻辑先实现到 `old-ss/` 再回迁。
+- 不要把 `old-ss/` 的旧模式直接复制到 Tauri 主线。
+- 不要把 `old-ss/` 构建问题当作主线发布阻塞项。
+
+## 参考命令（仅遗留排查）
+
+```bash
+pnpm --dir old-ss install
+pnpm --dir old-ss dev
+```
diff --git a/src-tauri/AGENTS.md b/src-tauri/AGENTS.md
new file mode 100644
index 0000000..1536600
--- /dev/null
+++ b/src-tauri/AGENTS.md
@@ -0,0 +1,47 @@
+# 后端知识库（src-tauri）
+
+## 作用域
+
+本文件仅约束 `src-tauri/`（Rust + Tauri）后端实现。
+
+## 关键入口
+
+- `src-tauri/src/main.rs`：二进制入口，调用 `secscore_lib::run()`。
+- `src-tauri/src/lib.rs`：应用装配中心（`setup`、`invoke_handler`、托盘/窗口、数据库启动）。
+- `src-tauri/src/state.rs`：全局状态容器。
+
+## 模块分层
+
+- `src-tauri/src/commands/`：Tauri IPC 命令边界层。
+- `src-tauri/src/services/`：业务服务层（鉴权、设置、主题、数据等）。
+- `src-tauri/src/db/`：连接、迁移、实体与仓储。
+- `src-tauri/src/models/`：模型与 DTO。
+
+## 后端约束
+
+- 新命令必须在 `commands/mod.rs` 导出，并在 `lib.rs` 的 `invoke_handler` 注册。
+- 命令层优先做参数校验与权限校验，业务细节下沉至 `services/`。
+- 涉及数据库结构或同步策略变更时，必须同步审阅 `db/migration.rs` 与 `commands/database.rs`。
+- 变更 `board`/SQL 查询相关能力时，优先白名单策略，避免扩散动态 SQL 风险面。
+
+## 后端反模式
+
+- 不要在 `commands/database.rs` 继续堆新职责；优先拆分为更小模块。
+- 不要把 UI 或前端状态逻辑迁入 Rust 命令层。
+- 不要绕过统一状态容器直接创建长期悬挂资源。
+
+## 后端验证
+
+在仓库根目录执行：
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm tauri:build
+```
+
+CI/发布场景还需参考：`.github/workflows/build.yml`。
+
+## 说明
+
+- 当前 `src-tauri/tauri.conf.json` 的 `beforeDevCommand`/`beforeBuildCommand` 使用 `npm run ...`，与仓库默认 `pnpm` 并存；修改构建链路时请同步评估。
diff --git a/src/AGENTS.md b/src/AGENTS.md
new file mode 100644
index 0000000..1783ef4
--- /dev/null
+++ b/src/AGENTS.md
@@ -0,0 +1,46 @@
+# 前端知识库（src）
+
+## 作用域
+
+本文件仅约束 `src/` 前端实现，不覆盖 `src-tauri/` Rust 后端规则。
+
+## 核心入口
+
+- `src/main.tsx`：前端启动、`window.api` 注入、日志桥接、平台 class 注入。
+- `src/App.tsx`：主流程编排（权限、页面路由、同步流程）。
+- `src/preload/types.ts`：前后端 API 类型契约（改动需双端联调）。
+
+## 关键目录
+
+- `src/components/`：主 UI 组件（含多个大文件热点）。
+- `src/contexts/`：全局上下文与服务注入。
+- `src/services/`：前端服务封装。
+- `src/shared/`：共享内核与自动评分规则引擎。
+- `src/i18n/`：国际化文本。
+
+## 前端约束
+
+- 新增功能优先复用已有模式：`Context + Service`，避免平行新架构。
+- 变更 `src/preload/types.ts` 时，必须同步核对后端命令与参数。
+- 对 `Home.tsx`、`Settings.tsx`、`BoardManager.tsx` 等超大组件的改动，优先拆分子组件/Hook，避免继续膨胀。
+- 避免把后端业务判断塞入前端 UI；业务规则优先落在 `src-tauri/`。
+
+## 前端反模式
+
+- 不要在组件内重复实现同一业务规则（统一收敛到 service/shared）。
+- 不要直接写“魔法字符串”调用后端接口，统一走类型化 API。
+- 不要绕过 `i18n` 直接硬编码用户可见文本。
+
+## 前端验证
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm build
+```
+
+若改动涉及界面交互流程，再执行：
+
+```bash
+pnpm tauri:dev
+```