项目性质：升级 存量系统：既有 Java / JSP 检查工具（依据使用手册，见 docs/legacy-analysis.md）改造内容：以分层检查架构（Python 机械引擎 + AI 语义分析）替换旧工具，规则覆盖由 Java 15/54(28%)、JSP 30/32(94%) 提升至机械规则 Java 87% / JSP 94%，配合 AI 语义分析达 100%。

1. 项目概述

code-checker 是一套覆盖【xTrade】/【PR】/WB4 三套日式编码规范的 Java/JSP 代码规则检查工具，目标是替代旧的代码检查流程，让编码规则检查从"人工逐条核对 + 旧工具离散检查"升级为"规则可配置、一键执行、报告可视化、可接入 CI"的完整体系。

维度	说明
目标语言	Java 8（JDK 1.8）/ JSP（JSP 2.x）
规则规模	Java 47 条（机械 41 + 语义 6）/ JSP 31 条（机械 29 + 语义 2）
检查方式	机械规则 87%（Python 静态分析：javalang AST + 行级分析）；语义规则 13%（AI，默认执行）
报告格式	Markdown / HTML（自包含单文件）/ JSON
运行模式	CLI（独立运行，无需 AI）/ AI Skill（`/check-code`）/ Web UI（图形界面）
规则扩展	`rulegen` 自然语言生成新规则（语义 / 声明式 / Python 兜底）

详细设计见 DESIGN.md，开发范式见其中"开发范式流程图"，AI 使用全程记录于 _AI_USAGE_LOG.md。

2. 整体功能说明

2.1 机械规则引擎（CLI）

# 检查单个文件 / 目录
python src/check-engine/main.py Sample.java
python src/check-engine/main.py --dir src/main/java/

# 指定规则类别 / 报告格式 / 失败门槛
python src/check-engine/main.py Sample.java --rules naming,layout
python src/check-engine/main.py Sample.java --format html -o report.html
python src/check-engine/main.py --dir src/ --format json --fail-on error

退出码：0=PASS / 1=违规 / 2=用法错误 / 3=内部错误
每条违规固定含报告三要素：严重程度 / 代码位置（文件:行:列 + 代码片段）/ 修复方案
解析失败容错：单文件解析失败注入 TOOL-PARSE-001，不中断批扫描
--lang generic：语言无关行级规则（自举扫描自身源码）

2.2 AI 语义分析（默认执行）

机械规则无法覆盖的语义规则（catch 块日志、DB NULL 判断、XSS 转义、表单校验等）由 AI Skill 执行：

/check-code Sample.java

审查完成后自动在 reports/ 生成 HTML + Markdown 报告。语义违规与机械违规同构输出（同 JSON 三要素），合并成完整报告。

2.3 Web UI（图形界面）

python src/run_webui.py                # 默认 http://127.0.0.1:8080

浏览器操作：选择目录 / 上传文件（支持 zip）→ 设置规则、门槛 → 一键检查 → KPI 汇总 + 违规详情 + 源码上下文 → 历史报告回看。前端原生 HTML/CSS/JS，零新增依赖。

2.4 规则生成（rulegen）

用自然语言新增规则（宿主无关，GitHub Copilot 亦可用）：

/rulegen 新增规则：禁止直接调用 Thread.sleep，应使用 WaitUtil 等待。

生成到 rules/_staging/ → python src/tools/rulegen.py validate|smoke|register 落盘 rules/custom/，主程序自动加载。

3. 效果总结（核心指标摘要）

指标	旧工具（存量）	code-checker	提升
Java 规则覆盖	15/54（28%）	机械 41/47（87%）；机械+AI 47/47（100%）	机械 +59pt，含 AI 100%
JSP 规则覆盖	30/32（94%）	机械 29/31（94%）；机械+AI 31/31（100%）	含 AI 100%（新增语义能力）
报告格式	Excel / log	Markdown + HTML + JSON	可视化、可分享、可消费
CI 集成	不可	退出码门禁 + JSON 输出	✅
语义分析	无	AI（默认执行）	从无到有
检查速度	慢	秒级（见实验报告计时数据）	显著提升
规则扩展	需改代码	YAML 配置 + rulegen 自然语言	显著提升

完整提效对比数据（旧工具 vs 新工具 + 人工评审 vs 工具）见 tests/EXPERIMENT.md；存量系统分析见 docs/legacy-analysis.md。

4. 团队分工

成员	职责	阶段
张志东	需求分析 / 规则整理 / 存量工具分析	需求、设计
夏伟杰	机械引擎 / 规则定义 / 报告生成	编码
夏伟杰，秦昌清	测试 / 等价性验收 / 覆盖率 / 实验数据	测试
张志东，连强	AI 语义规则 / 演示 / 文档 / 提交	集成、发布

5. 规模与技术难度自我评估

维度	评估
代码规模	约 5000+ 行 Python（引擎 / 检查器 / 报告器 / Web UI / 工具链），规则 YAML 78 条，单元测试 179 个用例 + 等价性验收用例
技术难点	① Java 8 AST 完整解析（lambda / 菱形泛型 / try-with-resources / 接口 default 方法）；② JSP 分层解析（HTML+Java 混排）；③ 启发式规则防误报（豁免清单 + 掩码处理）；④ 旧工具等价性验收（每条规则最小触发样例）
完成度	机械规则全部实现并经 179 用例 + 等价性验收 + 自举语料验证；语义规则由 AI Skill 默认执行；Web UI、rulegen、CI 门禁齐备
创新点	分层检查（机械+AI 各司其职）、规则 YAML 可配置 + rulegen 自然语言扩展、自包含 HTML 报告、`--lang generic` 自举 dogfooding

6. 环境要求与依赖

运行环境：Python 3.10+
依赖（src/requirements.txt）：javalang>=0.13.0、pyyaml>=6.0
测试依赖：pytest、pytest-cov
语义分析：opencode / Claude Code（内置 AI Skill，默认执行语义）

7. 安装与运行

# 1. 安装依赖
pip install -r src/requirements.txt

# 2. 机械检查（无需 AI，即刻可用）
python src/check-engine/main.py Sample.java
python src/check-engine/main.py --dir src/tests/fixtures --format html -o report.html

# 3. 语义深度检查（在 opencode / Claude Code 中，默认执行语义）
# /check-code <path>

# 4. Web UI
python src/run_webui.py

# 5. 自检（交付 Gate）
python src/tools/check_all.py

本工具为本地命令行工具 / 本地 Web UI，无公网服务地址；语义能力需在本机 AI 编程环境中通过 Skill 使用（/check-code 默认开启）。演示视频见 docs/copilot-check-demo.mp4（IDE 扩展演示：Copilot 调用工具审查）、docs/opencode-check-demo.mp4（IDE 扩展演示：opencode /check-code，机械+语义）与 docs/webui-demo.mp4（WebUI 界面执行演示），使用说明与实测记录见 docs/usage.md。

8. 目录结构

2026Technology-Competition/
├── README.md               # 01 项目说明（本文件）
├── DESIGN.md               # 02 设计文档（架构图 / 范式图 / API 清单）
├── src/                    # 03 源码（工具本体）
│   ├── check-engine/       #    CLI 机械引擎
│   ├── rules/              #    规则定义 YAML
│   ├── skill/              #    AI Skill（check-code / rulegen）
│   ├── tools/              #    自检工具链
│   ├── webui/ run_webui.py #    Web UI
│   ├── selftest/           #    自举语料（合规 / 违规）
│   └── tests/              #    单元测试 + fixtures
├── tests/                  # 04 实验报告（coverage/ + logs/ + EXPERIMENT.md）
├── _AI_USAGE_LOG.md        # 05 AI 使用日志
├── AGENTS.md               # AI 协作方式与项目说明
├── data/                   # 样本数据
└── docs/
    ├── copilot-check-demo.mp4  # 06 演示视频①：IDE 扩展（Copilot 调用工具审查，≤5 分钟）
    ├── opencode-check-demo.mp4 #    演示视频②：IDE 扩展（opencode /check-code，≤5 分钟）
    ├── webui-demo.mp4          #    演示视频③：WebUI 界面执行（≤5 分钟）
    ├── legacy-analysis.md  # 存量系统分析（升级项目必填）
    └── usage.md            # 使用手册

README.md Unescape Escape

code-checker — Java/JSP 代码规则检查工具