XYKJ/xykj-plus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
xykj-plus/claude-ecc/README.md
liuhuayong 7e90ae7e14 fix: add actual files (remove submodule refs)
2026-06-13 13:48:51 +08:00

6.6 KiB
Raw Permalink Blame History

claude-ecc

一个面向 admin-xy 生态的 monorepo，当前包含 3 个相对独立的子项目：

  • admin-xy/：企业管理系统，前后端分离，支持 Docker Compose 生产部署
  • log-analyzer/：本地日志会话分析工具，用于查看 .claude/logs/ 下的 trace JSONL
  • dev-assistant/：面向 admin-xy 的页面开发助手，当前仓库内已包含 bridge 服务与默认配置

这个仓库没有统一的根级构建入口。每个子项目都需要在自己的目录中安装依赖、启动和构建。

项目总览

子项目 作用 技术栈 默认端口
admin-xy/server 企业管理系统后端 Spring Boot 3, Java 21, Spring Security, JPA, Flyway 9010
admin-xy/web 企业管理系统前端 React 18, Vite, TypeScript, Zustand, Zod, Radix UI, Tailwind CSS 9001
log-analyzer Trace 日志分析与可视化 React 18, Vite, TypeScript, Recharts 5177
dev-assistant/bridge 页面开发助手桥接服务 Node.js, TypeScript, Hono, WebSocket, Claude Agent SDK 9020

目录结构

.
├── admin-xy/
│   ├── server/          # Spring Boot 后端
│   ├── web/             # React + Vite 前端
│   ├── build-images.sh  # 构建前后端 Docker 镜像
│   └── deploy.sh        # 生产部署脚本
├── log-analyzer/        # 读取 .claude/logs 的本地分析工具
├── dev-assistant/
│   ├── bridge/          # Node bridge 服务
│   └── config/          # 默认模型与桥接配置
└── .claude/logs/        # trace-*.jsonl 会话日志

环境要求

建议本地准备以下环境：

  • Java 21
  • Maven 3.9+
  • Node.js >=24
  • npm 10+
  • Docker 与 Docker Compose

快速开始

1. 启动 admin-xy 后端

cd admin-xy/server
mvn spring-boot:run

默认使用 dev profile，监听 http://localhost:9010，本地开发数据库为 H2 内存库，表结构由 Flyway 迁移管理。

2. 启动 admin-xy 前端

cd admin-xy/web
npm install
npm run dev

前端默认监听 http://localhost:9001，并把 /api 代理到 http://localhost:9010。

3. 启动 log-analyzer

cd log-analyzer
npm install
npm run dev

log-analyzer 会通过 Vite 自定义插件直接读取仓库根目录的 .claude/logs/，适合本地排查会话、trace 和 hook 执行记录。

4. 启动 dev-assistant bridge

cd dev-assistant
npm install
npm run bridge:dev

bridge 默认监听 http://localhost:9020，并允许来自 http://localhost:9001 的浏览器请求。默认配置文件位于 dev-assistant/config/dev-assistant.yaml。

admin-xy

admin-xy 是仓库里的主业务项目，分为后端 server/ 与前端 web/ 两部分。

后端

  • 入口类：com.adminxy.AdminXyApplication
  • 技术栈：Spring Boot 3.3、Java 21、Spring Security、Spring Data JPA、Flyway、JWT
  • 开发环境：默认 dev profile，使用 H2
  • 生产环境：prod profile，使用 MySQL

常用命令：

cd admin-xy/server

# 本地运行
mvn spring-boot:run

# 全量测试
mvn test

# 打包（跳过测试）
mvn -DskipTests clean package

前端

  • 技术栈：React 18、Vite、TypeScript、Zustand、react-hook-form、Zod、Radix UI、Tailwind CSS
  • 路径别名：@ -> src
  • 前端开发端口：9001

常用命令：

cd admin-xy/web

npm install
npm run dev
npm run build
npm run preview

生产部署

admin-xy 的生产部署统一通过脚本完成，不建议手动拆分成单独的 Docker 命令。

cd admin-xy

# 构建镜像
./build-images.sh
./build-images.sh --no-cache

# 生产部署
sudo ./deploy.sh

# 重启已有服务
sudo ./deploy.sh --restart

# 停止并移除容器
sudo ./deploy.sh --stop

部署脚本会：

  1. 初始化 /opt/admin-xy
  2. 校验 /opt/admin-xy/.env
  3. 同步 docker-compose.yml
  4. 构建镜像
  5. 执行 docker compose up -d

生产环境关键变量：

  • SPRING_DATASOURCE_ADMIN_URL
  • SPRING_DATASOURCE_ADMIN_USERNAME
  • SPRING_DATASOURCE_ADMIN_PASSWORD
  • JWT_SECRET

log-analyzer

log-analyzer 是一个纯前端工具，但它在开发模式下通过 Vite 插件内置了本地文件读取接口，用来直接分析 trace 日志。

当前插件会暴露这些本地接口：

  • /api/folders
  • /api/sessions
  • /api/sessions/:sid

日志来源目录是仓库根下的 .claude/logs/，常见文件名格式为：

.claude/logs/trace-<session-id>.jsonl

常用命令：

cd log-analyzer

npm install
npm run dev
npm run build

适用场景：

  • 查看某次 Codex / Claude 会话的 trace
  • 排查 hook 事件时间线
  • 分析本地开发流程中的会话数据

dev-assistant

dev-assistant 用于给 admin-xy 提供页面开发辅助能力。当前仓库中已明确包含：

  • bridge/：Node bridge 服务，负责协议适配、WebSocket 会话和配置加载
  • config/：默认路由、模型目录、日志源和桥接参数

常用命令：

cd dev-assistant

npm install
npm run bridge:dev
npm run bridge:build
npm run bridge:test

默认桥接配置来自 dev-assistant/config/dev-assistant.yaml，其中定义了：

  • 默认模型路由
  • GLM / MiniMax 模型目录
  • 工作目录写入限制
  • 日志源路径
  • bridge 端口与 WebSocket 路径

开发约定

Git 提交

本仓库使用 Conventional Commits 风格：

feat: ...
fix: ...
refactor: ...
docs: ...
test: ...
chore: ...
perf: ...
ci: ...

运行方式

  • 不要在仓库根目录执行统一的 npm install
  • 每个子项目在自己的目录中单独安装依赖
  • admin-xy、log-analyzer、dev-assistant 彼此相对独立

日志与排查

  • trace 日志统一存放在 .claude/logs/
  • log-analyzer 默认读取该目录
  • admin-xy 生产部署通过 deploy.sh 管理

常见任务

我想做什么 进入目录 命令
启动 admin-xy 后端 admin-xy/server mvn spring-boot:run
启动 admin-xy 前端 admin-xy/web npm run dev
构建 admin-xy 前端 admin-xy/web npm run build
运行 admin-xy 后端测试 admin-xy/server mvn test
发布 admin-xy admin-xy sudo ./deploy.sh
启动 log-analyzer log-analyzer npm run dev
构建 log-analyzer log-analyzer npm run build
启动 dev-assistant bridge dev-assistant npm run bridge:dev

说明

这份 README 以当前仓库里的实际目录与配置为准。如果某个子模块后续发生调整，建议同步更新这里的目录结构、启动命令和端口说明。