开发指南

环境要求

工具	版本	说明
Python	3.x	用于启动静态 HTTP 服务器
Node.js	任意	仅用于 `npm run lint`（可选）
浏览器	现代浏览器	支持 ES Modules、FileReader API

本地开发

# 方式 1：Python（推荐，无需安装依赖）
python3 -m http.server 4173
open http://localhost:4173
 
# 方式 2：npm 脚本（等同于 python3）
npm run dev
 
# 方式 3：任意静态服务器
npx serve . -p 4173
npx http-server . -p 4173

⚠️ 必须通过 HTTP 服务器访问，不能直接双击打开 index.html。原因：ES Modules 和 fetch() 需要 HTTP 协议。

目录说明

jd-matcher/
├── .env              ← 本地配置（不提交 git）
├── .env.example      ← 配置模板
├── CLAUDE.md         ← Harness 开发协议（Claude Code 自动加载）
├── AGENTS.md         ← Harness 开发协议（其他 AI 工具）
├── index.html        ← 入口（重定向到 src/ui/index.html）
├── package.json      ← 仅含 dev/lint 脚本
├── src/              ← 主要源码（6 层架构）
├── skills/           ← AI Skills 定义
├── docs/             ← 项目文档（含 env-config.md）
├── tests/unit/       ← 纯 JS 单元断言
└── docs-site/        ← Fumadocs 文档站（本文档）

添加新技能词

技能词库在 src/config/index.js 的 SKILL_DICTIONARY 中：

// 在对应分类中添加，或新增分类
export const SKILL_DICTIONARY = {
  // ...
  mobile: [
    'react native', 'flutter', 'swift', 'kotlin',
    'ios', 'android',
  ],
};

添加后自动生效，无需重启（刷新浏览器即可）。

调整匹配权重

在 src/config/index.js 中修改 WEIGHTS：

export const WEIGHTS = {
  skill:      0.50,   // 调整此值
  experience: 0.30,
  education:  0.20,
  // 三者之和必须 = 1.0
};

新增 Sprint

遵循 Sprint Contract 格式，在 CLAUDE.md 中添加新 Sprint：

| S9  | 新功能描述  | service/xxx  | 🔲 待开始 |

然后按 Harness 三 Agent 流程：

1. Planner 分析需求 → 制定 Sprint Contract
2. 验证不违反依赖层规则
3. Generator 实现（文件头注明 Sprint 编号和层）
4. Evaluator 验收（tests/unit/ 断言 + 手动）
5. 更新 CLAUDE.md 状态为 ✅

运行测试

# 运行所有单元测试
node tests/unit/run.js
 
# 检查 JS 语法
npm run lint
# 等同于：find src -name '*.js' -exec node --check {} \;

常见问题

fetch 跨域报错

Access to fetch at '/.env' from origin 'null' has been blocked by CORS policy

原因：直接用 file:// 打开文件。解决：通过 npm run dev 或 python3 -m http.server 4173 启动后访问。

PDF 解析失败

原因：pdfjs-dist 需要从 CDN 加载，离线状态下失败。解决：检查网络连接，或改用 JSON / TXT 格式简历。

AI 返回解析错误

原因：AI 返回了非 JSON 格式的内容（例如包含多余解释文字）。处理：系统会自动 fallback 到本地算法，aiAnalysis 字段会说明原因。

技能匹配率异常低

可能原因：

简历格式为 TXT / PDF，skills 数组只有粗解析的少量词
JD 中的技能写法与词库不一致（如 JD 写 k8s，简历写 kubernetes）

解决：

使用 JSON 格式简历，手动填写完整的 skills 数组
在 src/config/index.js 的 SKILL_DICTIONARY 中补充别名词条

构建与部署

项目是纯静态文件，无需构建步骤：

# 直接部署整个目录到静态托管
# Vercel / Netlify / GitHub Pages / Cloudflare Pages 均可
 
# Vercel 一键部署
npx vercel
 
# GitHub Pages
# 将仓库设为 public，在 Settings → Pages 中选择 main 分支根目录

注意：.env 文件包含配置信息，不要上传到公开仓库。部署时在平台的环境变量设置中配置，或使用 .env.example 中的默认值。

开发指南

On this page