# agent-skill-comparison

**Repository Path**: kaiyujiang/agent-skill-comparison

## Basic Information

- **Project Name**: agent-skill-comparison
- **Description**: 用于体验agent skill和直接调用api效果差异的毕设项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI就业信息助手 · 课题三样板

基于 **Agent Skill 渐进式披露** 架构的就业信息问答服务。

---

## 整体工作流

```
        【同学B负责】              【工具自动完成】          【同学A负责】
  ┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────┐
  │  手动/辅助收集数据   │────▶│  build_skills.py │────▶│  FastAPI 服务   │
  │  raw_data/*.csv     │     │  CSV → .md 摘要  │     │  查询 CSV + Skill│
  └─────────────────────┘     └──────────────────┘     └─────────────────┘
         ▲                             │
         │  可选：粘贴杂乱文字          │ skills/*.md（生成物，不手动编辑）
  enhance_with_llm.py 整理
```

> **核心原则**：`raw_data/` 是真实数据源，`skills/` 提供摘要、手写说明和展示材料。
> 问答时后端会先查询 CSV，再只把少量命中结果交给模型。

> 进阶改造方案见 [`docs/progressive_disclosure_query_plan.md`](docs/progressive_disclosure_query_plan.md)：将 `load_relevant_skills()` 从“加载文件全文”升级为“路由 + 查询 CSV + 注入少量结果”。

---

## 项目结构

```
demo-skill-chatbot/
├── raw_data/                  ← 【同学B工作区】手动填写真实数据
│   ├── README.md              ← 数据收集指南（必读）
│   ├── jobs.csv               ← 岗位信息（目标≥50条）
│   ├── salary.csv             ← 薪资行情（目标≥20条）
│   └── interview.csv          ← 面试题库（目标≥30题）
├── tools/
│   ├── build_skills.py        ← CSV → Markdown 生成器（核心工具）
│   └── enhance_with_llm.py   ← 粘贴杂乱文字，Kimi帮整理成CSV（可选）
├── skills/                    ← 【自动生成，勿手动编辑】
│   ├── SKILL.md               ← 总摘要（自动更新数据量）
│   ├── jobs.md                ← 由 jobs.csv 生成
│   ├── salary.md              ← 由 salary.csv 生成
│   ├── interview.md           ← 由 interview.csv 生成
│   ├── directions.md          ← 手写正文 + 自动数据附录的就业方向分析
│   └── resume.md              ← 手写正文 + 自动数据附录的简历指南
├── static/
│   └── index.html             ← 演示前端（含Skill激活可视化）
├── main.py                    ← FastAPI 后端
├── requirements.txt
└── README.md
```

---

## 分工说明

| 同学 | 工作内容 | 使用哪些文件 |
|---|---|---|
| **A（API开发）** | 填API Key、启动服务、部署阿里云 | `main.py`、阿里云ECS |
| **B（知识库）** | 收集数据、填CSV、运行生成脚本 | `raw_data/`、`tools/build_skills.py` |
| **C（测试）** | 设计30题、测试、记录数据、写报告 | 已运行的服务接口 |

---

## 第一步：数据收集（同学B）

详细说明见 [`raw_data/README.md`](raw_data/README.md)

**方式A：手动填写**（推荐新手）
1. 用 Excel 打开 `raw_data/jobs.csv`（编码选 UTF-8）
2. 参考示例行，从 BOSS直聘/前程无忧 复制岗位信息逐行填入
3. 保存为 CSV UTF-8 格式

**方式B：AI辅助整理**（效率更高）
```bash
# 在终端运行，把从网站复制的杂乱文字粘贴进去，Kimi自动整理成CSV
export KIMI_API_KEY=sk-your-api-key-here
python tools/enhance_with_llm.py --type jobs
```

---

## 第二步：生成知识库

数据填完后，运行一条命令：

```bash
python tools/build_skills.py
```

输出示例：
```
🔨 开始生成知识库...

📋 处理 jobs.csv → jobs.md
   ✅ 生成 skills/jobs.md（52 条岗位）
💰 处理 salary.csv → salary.md
   ✅ 生成 skills/salary.md（24 条薪资记录）
🎯 处理 interview.csv → interview.md
   ✅ 生成 skills/interview.md（33 道题）
📌 更新 SKILL.md 总摘要

✨ 完成！岗位: 52 条 | 薪资: 24 条 | 面试题: 33 道
```

---

## 第三步：启动服务

```bash
# 设置 API Key
export LLM_API_KEY=sk-your-api-key-here

# 安装依赖（首次运行）
pip install -r requirements.txt

# 启动服务
uvicorn main:app --reload
```

浏览器访问 **http://localhost:8000** 查看演示界面

---

## 部署到服务器（同学B/A）

我们提供了一键部署脚本，支持从安装依赖到后台运行的全流程：

```bash
# 1. 给脚本执行权限
chmod +x scripts/deploy.sh

# 2. 首次一键部署（安装依赖 + 构建知识库 + 启动后台服务）
./scripts/deploy.sh

# 3. 以后更新了代码或数据后，只需运行：
./scripts/deploy.sh update

# 4. 查看运行状态或日志：
./scripts/deploy.sh status
tail -f server.log
```

---

## API 接口文档

启动后访问：http://localhost:8000/docs

核心接口：
```
POST /ask
Body: {"question": "深圳有哪些AI岗位？"}

Response:
{
  "answer": "根据知识库...",
  "loaded_skills": ["SKILL.md", "jobs.md"],   ← 体现渐进式披露
  "response_time_ms": 1823
}
```

`loaded_skills` 字段是答辩演示的亮点——直接展示本次调用了哪些查询工具和知识片段，而非把全量数据塞给模型。

> 备注：旧实现会把命中的模块文件整体拼接给模型；现在 `/ask` 已改为“路由 + 查询 CSV + 注入少量结果”。`jobs.md` 仍可作为摘要展示文件，但不再是岗位问答的主要数据源。

---

## 项目结构

```
demo-skill-chatbot/
├── skills/
│   ├── SKILL.md          ← 总摘要（Agent每次必读）
│   ├── jobs.md           ← 岗位信息
│   ├── directions.md     ← 就业方向
│   ├── salary.md         ← 薪资行情
│   ├── interview.md      ← 面试题库
│   └── resume.md         ← 简历指南
├── static/
│   └── index.html        ← 演示前端
├── main.py               ← FastAPI 后端
├── requirements.txt
└── README.md
```

---

## 快速启动

### 第一步：填入 API Key

本项目使用 OpenAI 兼容接口。可以用 Kimi，也可以用硅基流动等模型平台。

**方式A（推荐）**：复制 `.env.example` 并填写：

```bash
cp .env.example .env
nano .env
```

硅基流动示例：

```bash
LLM_PROVIDER=siliconflow
LLM_API_KEY=sk-your-api-key-here
LLM_BASE_URL=https://api.siliconflow.cn/v1
LLM_MODEL=Qwen/Qwen2.5-7B-Instruct
```

Kimi 示例：

```bash
LLM_PROVIDER=kimi
LLM_API_KEY=sk-your-api-key-here
LLM_BASE_URL=https://api.moonshot.cn/v1
LLM_MODEL=moonshot-v1-32k
```

### 第二步：安装依赖

```bash
pip install -r requirements.txt
```

### 第三步：启动服务

```bash
uvicorn main:app --reload
```

### 第四步：打开演示页面

浏览器访问：http://localhost:8000

---

## 演示界面说明

- **左侧**：聊天对话框，支持快捷键 Enter 发送
- **右侧上**：🧠 Skill模块激活状态——可视化展示本次加载了哪些知识文件
- **右侧中**：📊 响应时间统计
- **右侧下**：💬 快速提问按钮（演示用）

---

## 渐进式披露核心逻辑

```python
# 每次提问只加载"摘要 + 查询结果 + 必要片段"，不加载全部文件
SKILL.md（常驻）+ query_jobs:10（问岗位时）
SKILL.md（常驻）+ query_jobs:10 + query_salary:N（问薪资时）
SKILL.md（常驻）+ query_interviews:5（问面试时）
SKILL.md（常驻）+ query_jobs:10 + resume.md:片段（问简历时）
```

vs. 全量塞上下文：不会把几百条岗位一次性发给模型，先由后端工具筛选证据。

---

## 部署到云服务器

请参考上面的【部署到服务器】部分，使用 `scripts/deploy.sh` 脚本一键部署。
记得在云服务器的控制台（如阿里云ECS）的安全组中，添加入方向规则开放 **8000** 端口。

---

## API 文档

启动后访问：http://localhost:8000/docs

核心接口：
```
POST /ask
Body: {"question": "深圳有哪些AI岗位？"}
Response: {
  "answer": "...",
  "loaded_skills": ["SKILL.md", "jobs.md"],
  "response_time_ms": 1823
}
```