| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 7 | 9 | 0% |
| Commands | 0 | 6 | 6 | 0% |
| Section tags | 2 | 6 | 3 | 18% |
What each file covers
Sections
0 shared · 7 only in A · 9 only in B- − Repository Guidelines
- − Project Structure & Module Organization
- − Build, Test, and Development Commands
- − Coding Style & Naming Conventions
- − Testing Guidelines
- − Commit & Pull Request Guidelines
- − Environment & Configuration Tips
- + Test-Driven Development (TDD)
- + Project Startup and Logging Rules
- + 根目录 (`/`)
- + 1. 停止服务
- + 2. 备份现有数据库
- + 3. 删除数据库文件
- + 4. 清理Redis缓存
- + 5. 重新启动服务
- + 前端API调用规范
Commands
0 shared · 6 only in A · 6 only in B- − docker-compose.yaml
- − go test ./...
- − npm run lint
- − npm run test:coverage
- − git log
- − npm run test
- + go test -v ./backend/api/handler/... | grep FAIL
- + go test -v ./...
- + go test -v ./... -run ^TestSpecificFunction$
- + go.sum
- + go.mod
- + eslint.config.js
Section tags
2 shared · 6 only in A · 3 only in B- − setup
- − build
- − code-style
- − architecture
- − types
- − git-pr
- + testing-strategy
- + api
- + do-not
- test
- lint-format
Line diff
burugo/one-mcp · AGENTS.md
@@ −1 @@
1# Repository Guidelines
2
3## Project Structure & Module Organization
4The Go backend lives under `backend/` with request handlers in `api/handler`, shared utilities in `common/`, data access in `data/`, and business logic in `service/`. The React frontend sits in `frontend/src` with translations in `frontend/public/locales` and build artifacts generated into `frontend/dist`. Persistent assets such as the SQLite database and uploads are stored in `data/` and `upload/`, while deployment aides live in `deploy/`, `Dockerfile`, and `docker-compose.yaml`.
5
6## Build, Test, and Development Commands
7- `./run.sh` — launches the backend on `:3000` and the Vite dev server on `:5173` with hot reload.
8- `PORT=8080 ./build.sh` — produces a production binary and bundles the frontend.
9- `go test ./...` — executes the Go unit tests across the backend.
10- `cd frontend && npm run build` — type-checks, lints, and compiles the React app.
11
12## Coding Style & Naming Conventions
13Go code must pass `gofmt` (tabs for indentation) and follow idiomatic package naming (`lower_case` for directories, `CamelCase` for exported types). Keep API handlers in `backend/api/handler` named `*_handler.go` and tests as `*_test.go`. TypeScript and JSX files use two-space indentation, TypeScript strict mode, and Tailwind utility ordering as emitted by `shadcn`. Run `npm run lint` before pushing to ensure ESLint (flat config) passes.
14
15## Testing Guidelines
16Backend features require table-driven tests under matching `*_test.go` files; ensure new logic is covered by `go test ./...` and update `coverage.out` when reporting coverage. Frontend components should use Vitest with Testing Library—add specs under `frontend/src/**/__tests__/` or alongside components with `.test.tsx` suffix. For UI flows, prefer `npm run test:coverage` to exercise V8 coverage and attach results in PRs touching critical paths.
17
18## Commit & Pull Request Guidelines
19Follow the Conventional Commits style visible in `git log` (e.g., `feat(proxy): add SSE support`). Keep messages scoped, written in the imperative, and limited to 72 characters in the subject. Pull requests should link related issues, summarize behavior changes, note migrations or env needs, and include before/after screenshots for UI updates. Confirm both `go test ./...` and `npm run test` results in the PR description before requesting review.
20
21## Environment & Configuration Tips
22Copy `.env_example` to `.env` and override only the keys you touch; avoid committing secrets. SQLite state is persisted in `data/one-mcp.db`, so remove it if you need a clean slate. When integrating external services, prefer storing credentials in `.env` and referencing them via `config/` structs rather than hardcoding values.
23
burugo/one-mcp · .cursor/rules/tdd.mdc
@@ +1 @@
1---
2description:
3globs: *.tsx,*.go,*.ts
4alwaysApply: false
5---
6## Test-Driven Development (TDD)
7**Final Verification:**
8Always use: `go test -v ./backend/api/handler/... | grep FAIL`
9
10**Debugging & Handling Verbose Output:**
11**Avoid** `go test -v ./...` directly in the terminal due to excessive output.
12**Recommended Alternatives:**
13* **Specific Tests:** `go test -v ./... -run ^TestSpecificFunction$` (Fastest for pinpointing).
14
15## Project Startup and Logging Rules
16
17**Service Startup:**
18- Use `bash ./run.sh` to start the one-mcp service
19- This script automatically loads .env, ensures PATH, kills port 3000 processes, and starts the Go backend in background
20- Logs are output to `backend.log`
21
22**Log Monitoring:**
23- Use `tail -f backend.log` to monitor real-time logs
24- Use `tail -n 50 backend.log` to view recent log entries
25- Use `grep "ERROR\|WARN\|Failed" backend.log` to filter error messages
26**Service Management:**
27- Use `pkill -f one-mcp` to stop the service
28- Check service status with `ps aux | grep one-mcp | grep -v grep`
29- API status endpoint: `curl "http://localhost:3003/api/status"`
30
31## 数据库重置和缓存管理
32
33**数据库重置规则:**
34- **重要：** 删除数据库前必须先备份：`cp data/one-mcp.db data/one-mcp.db.backup.$(date +%Y%m%d_%H%M%S)`
35- 仅删除数据库文件 `rm -f data/one-mcp.db` 是不够的
36- **必须同时清理Redis缓存：** `redis-cli flushdb` 或 `redis-cli flushall`
37- 原因：用户列表查询有缓存机制，如果缓存中存在用户数据，系统不会创建新的root用户
38
39**完整的数据库重置流程:**
40```bash
41# 1. 停止服务
42pkill -f one-mcp
43
44# 2. 备份现有数据库
45cp data/one-mcp.db data/one-mcp.db.backup.$(date +%Y%m%d_%H%M%S)
46
47# 3. 删除数据库文件
48rm -f data/one-mcp.db
49
50# 4. 清理Redis缓存
51redis-cli flushdb
52
53# 5. 重新启动服务
54bash ./run.sh
55```
56
57**验证root用户创建:**
58- 查看日志：`grep "no user exists\|create a root user" backend.log`
59- 检查数据库：`sqlite3 data/one-mcp.db "SELECT id, username, LENGTH(token) as token_length FROM users;"`
60
61## 前端API调用规范
62
63**API路径构建:**
64- 当使用 `frontend/src/utils/api.ts` 中导出的 `api` 实例进行API调用时 (例如 `api.get`, `api.post` 等)，**请勿在请求路径中再次添加 `/api` 前缀**。
65- 这是因为 `api` 实例的 `baseURL` 已经被配置为 `/api`，重复添加会导致 `/api/api/` 这样的错误路径。
66- **正确示例:** `api.get('/user/self')` 或 `api.post('/user', data)`。
67- **错误示例:** `api.get('/api/user/self')`。
68
69# 项目目录结构
70
71## 根目录 (`/`)
72- `backend.log` - 后端服务的运行日志文件。包含服务启动、运行过程中的各种信息，用于调试和监控。
73- `data/` - 数据存储目录。通常包含数据库文件、缓存数据或其它持久化数据。
74- `one-mcp` - 主应用程序可执行文件（Go语言编译产物）。
75- `.git/` - Git版本控制系统目录。包含所有版本历史和配置信息。
76- `.cursor/` - Cursor IDE的配置文件和工作区特定文件，包括Agent的规则和任务文件。
77 - `rules/` - 存放Agent的规则文件，如 `tdd.mdc` 和 `plan-mode.mdc`。
78 - `tdd.mdc` - TDD（测试驱动开发）相关规则和测试指南。
79 - `plan-mode.mdc` - Agent的计划模式（PLAN Mode）操作指南。
80 - `act-mode.mdc` - Agent的执行模式（ACT Mode）操作指南。
81 - (其他可能的Cursor配置或任务文件)
82- `main.go` - Go语言后端服务的主入口文件。
83- `go.sum` - Go模块依赖校验和文件，用于确保依赖的完整性和安全性。
84- `go.mod` - Go模块定义文件，声明项目依赖的外部模块。
85- `.gitignore` - Git忽略文件配置，指定不应被版本控制的文件和目录。
86- `.cursorignore` - Cursor IDE忽略文件配置，指定在IDE中不应被索引或处理的文件和目录。
87- `frontend/` - 前端应用程序的根目录。
88 - `src/` - 前端源代码目录。 (内部文件和子目录待进一步探索和注释，但为了简洁，此处暂不列出)
89 - `package-lock.json` - npm或yarn的锁定文件，记录了项目依赖的精确版本信息。
90 - `package.json` - 前端项目的元数据文件，包含项目信息、脚本命令和依赖列表。
91 - `node_modules/` - Node.js模块安装目录，存放前端项目的所有依赖包。
92 - `dist/` - 前端项目构建后的输出目录，包含用于部署的静态文件（HTML, CSS, JS等）。
93 - `tsconfig.tsbuildinfo` - TypeScript构建信息文件，用于增量编译优化。
94 - `vite.config.ts` - Vite前端构建工具的配置文件（TypeScript版本）。
95 - `vite.config.d.ts` - Vite配置文件的类型声明文件。
96 - `tsconfig.json` - TypeScript编译器的配置文件，定义了如何编译TypeScript代码。
97 - `tailwind.config.js` - Tailwind CSS框架的配置文件，用于自定义CSS样式。
98 - `components.json` - 可能用于UI组件库的配置文件，定义组件路径或配置。
99 - `tsconfig.node.json` - 针对Node.js环境的TypeScript配置文件。
100 - `tsconfig.app.json` - 针对前端应用本身的TypeScript配置文件。
101 - `postcss.config.js` - PostCSS工具的配置文件，用于处理CSS。
102 - `index.html` - 前端应用的HTML入口文件。
103 - `public/` - 静态资源目录，其中文件不会被Webpack等打包工具处理，直接复制到`dist`。
104 - `.gitignore` - 前端项目的Git忽略文件配置。
105 - `README.md` - 前端项目的说明文档。
106 - `eslint.config.js` - ESLint代码风格检查工具的配置文件。
107- `run.sh` - 服务启动脚本。
108- `dev.sh` - 开发环境启动脚本。
109- `.vscode/` - VS Code编辑器的工作区配置目录。
110- `DEVELOPMENT.md` - 开发指南或说明文档。
111- `build.sh` - 项目构建脚本。
112- `config/` - 项目的配置目录，可能包含通用配置文件。
113- `locales/` - 国际化（i18n）文件目录，存放多语言资源。
114- `backend/` - 后端服务的根目录。
115 - `data/` - 后端数据模型或持久化层相关代码。
116 - `model/` - 后端数据模型定义。
117 - `common/` - 后端通用工具函数、常量或共享代码。
118 - `library/` - 后端第三方库的封装或自定义库。
119 - `service/` - 后端业务逻辑服务层代码。
120 - `api/` - 后端API接口定义和处理逻辑。
121 - `config/` - 后端配置相关代码或文件。
122- `.tool-versions` - asdf版本管理工具的配置文件，指定项目所需的工具版本。
123- `doc/` - 项目文档目录。
124- `upload/` - 文件上传存储目录。
125- `Dockerfile` - Docker容器的构建文件，定义了如何构建应用程序的Docker镜像。
126- `LICENSE` - 项目的开源许可证文件。
127- `README.en.md` - 英文版的项目说明文档。
128- `README.md` - 项目的中文说明文档。
129- `VERSION` - 版本号文件。
130
131
@@ −1 +1 @@
1−# Repository Guidelines
1+---
2+description:
3+globs: *.tsx,*.go,*.ts
4+alwaysApply: false
5+---
6+## Test-Driven Development (TDD)
7+**Final Verification:**
8+Always use: `go test -v ./backend/api/handler/... | grep FAIL`
29
3−## Project Structure & Module Organization
4−The Go backend lives under `backend/` with request handlers in `api/handler`, shared utilities in `common/`, data access in `data/`, and business logic in `service/`. The React frontend sits in `frontend/src` with translations in `frontend/public/locales` and build artifacts generated into `frontend/dist`. Persistent assets such as the SQLite database and uploads are stored in `data/` and `upload/`, while deployment aides live in `deploy/`, `Dockerfile`, and `docker-compose.yaml`.
10+**Debugging & Handling Verbose Output:**
11+**Avoid** `go test -v ./...` directly in the terminal due to excessive output.
12+**Recommended Alternatives:**
13+* **Specific Tests:** `go test -v ./... -run ^TestSpecificFunction$` (Fastest for pinpointing).
514
6−## Build, Test, and Development Commands
7−- `./run.sh` — launches the backend on `:3000` and the Vite dev server on `:5173` with hot reload.
8−- `PORT=8080 ./build.sh` — produces a production binary and bundles the frontend.
9−- `go test ./...` — executes the Go unit tests across the backend.
10−- `cd frontend && npm run build` — type-checks, lints, and compiles the React app.
15+## Project Startup and Logging Rules
1116
12−## Coding Style & Naming Conventions
13−Go code must pass `gofmt` (tabs for indentation) and follow idiomatic package naming (`lower_case` for directories, `CamelCase` for exported types). Keep API handlers in `backend/api/handler` named `*_handler.go` and tests as `*_test.go`. TypeScript and JSX files use two-space indentation, TypeScript strict mode, and Tailwind utility ordering as emitted by `shadcn`. Run `npm run lint` before pushing to ensure ESLint (flat config) passes.
17+**Service Startup:**
18+- Use `bash ./run.sh` to start the one-mcp service
19+- This script automatically loads .env, ensures PATH, kills port 3000 processes, and starts the Go backend in background
20+- Logs are output to `backend.log`
1421
15−## Testing Guidelines
16−Backend features require table-driven tests under matching `*_test.go` files; ensure new logic is covered by `go test ./...` and update `coverage.out` when reporting coverage. Frontend components should use Vitest with Testing Library—add specs under `frontend/src/**/__tests__/` or alongside components with `.test.tsx` suffix. For UI flows, prefer `npm run test:coverage` to exercise V8 coverage and attach results in PRs touching critical paths.
22+**Log Monitoring:**
23+- Use `tail -f backend.log` to monitor real-time logs
24+- Use `tail -n 50 backend.log` to view recent log entries
25+- Use `grep "ERROR\|WARN\|Failed" backend.log` to filter error messages
26+**Service Management:**
27+- Use `pkill -f one-mcp` to stop the service
28+- Check service status with `ps aux | grep one-mcp | grep -v grep`
29+- API status endpoint: `curl "http://localhost:3003/api/status"`
1730
18−## Commit & Pull Request Guidelines
19−Follow the Conventional Commits style visible in `git log` (e.g., `feat(proxy): add SSE support`). Keep messages scoped, written in the imperative, and limited to 72 characters in the subject. Pull requests should link related issues, summarize behavior changes, note migrations or env needs, and include before/after screenshots for UI updates. Confirm both `go test ./...` and `npm run test` results in the PR description before requesting review.
31+## 数据库重置和缓存管理
2032
21−## Environment & Configuration Tips
22−Copy `.env_example` to `.env` and override only the keys you touch; avoid committing secrets. SQLite state is persisted in `data/one-mcp.db`, so remove it if you need a clean slate. When integrating external services, prefer storing credentials in `.env` and referencing them via `config/` structs rather than hardcoding values.
33+**数据库重置规则:**
34+- **重要：** 删除数据库前必须先备份：`cp data/one-mcp.db data/one-mcp.db.backup.$(date +%Y%m%d_%H%M%S)`
35+- 仅删除数据库文件 `rm -f data/one-mcp.db` 是不够的
36+- **必须同时清理Redis缓存：** `redis-cli flushdb` 或 `redis-cli flushall`
37+- 原因：用户列表查询有缓存机制，如果缓存中存在用户数据，系统不会创建新的root用户
38+
39+**完整的数据库重置流程:**
40+```bash
41+# 1. 停止服务
42+pkill -f one-mcp
43+
44+# 2. 备份现有数据库
45+cp data/one-mcp.db data/one-mcp.db.backup.$(date +%Y%m%d_%H%M%S)
46+
47+# 3. 删除数据库文件
48+rm -f data/one-mcp.db
49+
50+# 4. 清理Redis缓存
51+redis-cli flushdb
52+
53+# 5. 重新启动服务
54+bash ./run.sh
55+```
56+
57+**验证root用户创建:**
58+- 查看日志：`grep "no user exists\|create a root user" backend.log`
59+- 检查数据库：`sqlite3 data/one-mcp.db "SELECT id, username, LENGTH(token) as token_length FROM users;"`
60+
61+## 前端API调用规范
62+
63+**API路径构建:**
64+- 当使用 `frontend/src/utils/api.ts` 中导出的 `api` 实例进行API调用时 (例如 `api.get`, `api.post` 等)，**请勿在请求路径中再次添加 `/api` 前缀**。
65+- 这是因为 `api` 实例的 `baseURL` 已经被配置为 `/api`，重复添加会导致 `/api/api/` 这样的错误路径。
66+- **正确示例:** `api.get('/user/self')` 或 `api.post('/user', data)`。
67+- **错误示例:** `api.get('/api/user/self')`。
68+
69+# 项目目录结构
70+
71+## 根目录 (`/`)
72+- `backend.log` - 后端服务的运行日志文件。包含服务启动、运行过程中的各种信息，用于调试和监控。
73+- `data/` - 数据存储目录。通常包含数据库文件、缓存数据或其它持久化数据。
74+- `one-mcp` - 主应用程序可执行文件（Go语言编译产物）。
75+- `.git/` - Git版本控制系统目录。包含所有版本历史和配置信息。
76+- `.cursor/` - Cursor IDE的配置文件和工作区特定文件，包括Agent的规则和任务文件。
77+ - `rules/` - 存放Agent的规则文件，如 `tdd.mdc` 和 `plan-mode.mdc`。
78+ - `tdd.mdc` - TDD（测试驱动开发）相关规则和测试指南。
79+ - `plan-mode.mdc` - Agent的计划模式（PLAN Mode）操作指南。
80+ - `act-mode.mdc` - Agent的执行模式（ACT Mode）操作指南。
81+ - (其他可能的Cursor配置或任务文件)
82+- `main.go` - Go语言后端服务的主入口文件。
83+- `go.sum` - Go模块依赖校验和文件，用于确保依赖的完整性和安全性。
84+- `go.mod` - Go模块定义文件，声明项目依赖的外部模块。
85+- `.gitignore` - Git忽略文件配置，指定不应被版本控制的文件和目录。
86+- `.cursorignore` - Cursor IDE忽略文件配置，指定在IDE中不应被索引或处理的文件和目录。
87+- `frontend/` - 前端应用程序的根目录。
88+ - `src/` - 前端源代码目录。 (内部文件和子目录待进一步探索和注释，但为了简洁，此处暂不列出)
89+ - `package-lock.json` - npm或yarn的锁定文件，记录了项目依赖的精确版本信息。
90+ - `package.json` - 前端项目的元数据文件，包含项目信息、脚本命令和依赖列表。
91+ - `node_modules/` - Node.js模块安装目录，存放前端项目的所有依赖包。
92+ - `dist/` - 前端项目构建后的输出目录，包含用于部署的静态文件（HTML, CSS, JS等）。
93+ - `tsconfig.tsbuildinfo` - TypeScript构建信息文件，用于增量编译优化。
94+ - `vite.config.ts` - Vite前端构建工具的配置文件（TypeScript版本）。
95+ - `vite.config.d.ts` - Vite配置文件的类型声明文件。
96+ - `tsconfig.json` - TypeScript编译器的配置文件，定义了如何编译TypeScript代码。
97+ - `tailwind.config.js` - Tailwind CSS框架的配置文件，用于自定义CSS样式。
98+ - `components.json` - 可能用于UI组件库的配置文件，定义组件路径或配置。
99+ - `tsconfig.node.json` - 针对Node.js环境的TypeScript配置文件。
100+ - `tsconfig.app.json` - 针对前端应用本身的TypeScript配置文件。
101+ - `postcss.config.js` - PostCSS工具的配置文件，用于处理CSS。
102+ - `index.html` - 前端应用的HTML入口文件。
103+ - `public/` - 静态资源目录，其中文件不会被Webpack等打包工具处理，直接复制到`dist`。
104+ - `.gitignore` - 前端项目的Git忽略文件配置。
105+ - `README.md` - 前端项目的说明文档。
106+ - `eslint.config.js` - ESLint代码风格检查工具的配置文件。
107+- `run.sh` - 服务启动脚本。
108+- `dev.sh` - 开发环境启动脚本。
109+- `.vscode/` - VS Code编辑器的工作区配置目录。
110+- `DEVELOPMENT.md` - 开发指南或说明文档。
111+- `build.sh` - 项目构建脚本。
112+- `config/` - 项目的配置目录，可能包含通用配置文件。
113+- `locales/` - 国际化（i18n）文件目录，存放多语言资源。
114+- `backend/` - 后端服务的根目录。
115+ - `data/` - 后端数据模型或持久化层相关代码。
116+ - `model/` - 后端数据模型定义。
117+ - `common/` - 后端通用工具函数、常量或共享代码。
118+ - `library/` - 后端第三方库的封装或自定义库。
119+ - `service/` - 后端业务逻辑服务层代码。
120+ - `api/` - 后端API接口定义和处理逻辑。
121+ - `config/` - 后端配置相关代码或文件。
122+- `.tool-versions` - asdf版本管理工具的配置文件，指定项目所需的工具版本。
123+- `doc/` - 项目文档目录。
124+- `upload/` - 文件上传存储目录。
125+- `Dockerfile` - Docker容器的构建文件，定义了如何构建应用程序的Docker镜像。
126+- `LICENSE` - 项目的开源许可证文件。
127+- `README.en.md` - 英文版的项目说明文档。
128+- `README.md` - 项目的中文说明文档。
129+- `VERSION` - 版本号文件。
130+
23131
