Files
Airtep/gig_poc_coding_agent_guide.md
2026-03-30 20:49:40 +08:00

785 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 灵活用工最小 POCCoding Agent 指导文档
## 1. 文档目的
本指导文档用于直接驱动 coding agent 落地一个“灵活用工最小 POC 内核系统”。
本次实现目标不是完整平台,不是完整招聘系统,也不是完整裂变系统,而是优先打通最核心的底层能力闭环:
> **岗位理解 → 工人理解 → LightRAG 检索 → 匹配排序 → 推荐解释**
coding agent 必须严格围绕这个主线执行,避免在低优先级模块上消耗时间。
---
## 2. 项目目标定义
## 2.1 业务目标
构建一个最小可运行的 POC用于验证
1. 平台能否从自然语言中提取岗位需求。
2. 平台能否从自然语言中提取工人技能画像。
3. 平台能否利用 LightRAG 构建“岗位—技能—工人”知识关联。
4. 平台能否完成岗位找人、人找岗位两类匹配。
5. 平台能否为匹配结果给出可解释的推荐原因。
## 2.2 POC 成功标准
满足以下条件即可判定 POC 成功:
- 输入一段岗位描述,系统返回结构化 JobCard。
- 输入一段工人描述,系统返回结构化 WorkerCard。
- 岗位可召回 TopN 候选工人。
- 工人可召回 TopN 候选岗位。
- 每条推荐结果都附带推荐原因。
- 支持一个简单的 Web 测试台进行演示。
---
## 3. 本次实现边界
## 3.1 本次必须实现
### 核心输入能力
- 岗位自然语言输入
- 工人自然语言输入
- 样本数据导入
### 核心 AI 能力
- 岗位结构化抽取
- 工人技能画像抽取
- LightRAG 数据入库
- LightRAG 查询与召回
- 匹配排序
- 匹配解释
### 核心输出能力
- JobCard 输出
- WorkerCard 输出
- 匹配结果输出
- 推荐原因输出
### 基础交互能力
- 简易 Web 控制台
- API 文档
- 健康检查
- 日志输出
## 3.2 本次明确不做
以下功能全部延后,不进入当前迭代:
- 裂变传播引擎
- 邀请奖励
- 社交分享接入
- 电子合同
- 工时记录
- 薪资结算
- 支付对接
- 短视频岗位展示
- 多角色复杂权限
- 百万并发优化
- 金融级安全全套建设
- 完整后台管理系统
- 真实线上地图派单
- 复杂调度系统
coding agent 必须避免擅自扩展到上述模块。
---
## 4. 一句话架构原则
> **先做一个“可解释的人岗匹配内核”,再考虑把它包装成完整平台。**
---
## 5. 技术栈要求
## 5.1 后端
优先采用:
- Python 3.11+
- FastAPI
- Pydantic
- SQLAlchemy
- Uvicorn
## 5.2 数据层
- PostgreSQL
- Redis可选POC 阶段用于缓存或不启用)
- 本地文件或 MinIO样本附件可选
- pgvector / Qdrant二选一优先 Qdrant 或 pgvector
## 5.3 AI / RAG
- LightRAG
- 一个可调用的 LLM 接口
- 一个 Embedding 接口
## 5.4 前端
优先采用:
- Next.js 或 React Vite
如果 coding agent 需要进一步压缩复杂度,可以直接:
- 使用 React + Vite + 简单组件
## 5.5 部署方式
POC 阶段统一使用:
- Docker Compose
---
## 6. 项目目录结构要求
coding agent 必须按以下结构组织项目:
```text
/gig-poc
/apps
/web
/api
/packages
/shared-types
/prompts
/sample-data
/infrastructure
docker-compose.yml
/sql
/scripts
/docs
README.md
API.md
ARCHITECTURE.md
```
### 6.1 apps/web
包含:
- 岗位输入测试页
- 工人输入测试页
- 匹配结果页
- 系统状态页
### 6.2 apps/api
包含:
- FastAPI 主服务
- 路由定义
- service 层
- repository 层
- rag 适配层
- 匹配引擎
### 6.3 packages/shared-types
包含:
- JobCard schema
- WorkerCard schema
- MatchResult schema
- API request/response schema
### 6.4 packages/prompts
包含:
- job_extract prompt
- worker_extract prompt
- explain_match prompt
### 6.5 packages/sample-data
包含:
- jobs.json
- workers.json
- skills.json
- regions.json
- categories.json
---
## 7. 统一数据结构定义
## 7.1 JobCard
coding agent 必须实现以下结构:
```json
{
"job_id": "job_001",
"title": "会展签到协助",
"category": "活动执行",
"description": "明天下午南山会展中心需要2个签到协助5小时150/人,女生优先",
"skills": ["签到", "引导", "登记"],
"city": "深圳",
"region": "南山",
"location_detail": "南山会展中心",
"start_time": "2026-03-31T13:00:00+08:00",
"duration_hours": 5,
"headcount": 2,
"salary": {
"type": "daily",
"amount": 150,
"currency": "CNY"
},
"work_mode": "排班制",
"tags": ["女生优先", "有会展经验优先"],
"confidence": 0.89
}
```
## 7.2 WorkerCard
```json
{
"worker_id": "worker_001",
"name": "张三",
"description": "我做过商场促销和活动签到,也能做登记和引导,周末都能接,福田南山都方便。",
"skills": [
{"name": "促销", "score": 0.82},
{"name": "活动签到", "score": 0.76},
{"name": "登记", "score": 0.68},
{"name": "引导", "score": 0.70}
],
"cities": ["深圳"],
"regions": ["福田", "南山"],
"availability": ["weekend"],
"experience_tags": ["商场", "会展", "活动执行"],
"reliability_score": 0.76,
"profile_completion": 0.64,
"confidence": 0.86
}
```
## 7.3 MatchResult
```json
{
"match_id": "match_001",
"source_type": "job_to_worker",
"source_id": "job_001",
"target_id": "worker_003",
"match_score": 0.84,
"breakdown": {
"skill_score": 0.91,
"region_score": 1.0,
"time_score": 0.8,
"experience_score": 0.75,
"reliability_score": 0.72
},
"reasons": [
"具备签到、引导、登记相关技能",
"服务区域包含南山,与岗位地点一致",
"周末可接单,与岗位时间匹配",
"有活动执行经验,与岗位类别接近"
]
}
```
---
## 8. LightRAG 数据建模要求
## 8.1 最小实体
coding agent 至少需要支持以下实体:
- Job
- Worker
- Skill
- Region
- Category
- ExperienceTag
## 8.2 最小关系
至少支持以下关系:
- Job REQUIRES_SKILL Skill
- Job LOCATED_IN Region
- Job BELONGS_TO Category
- Job HAS_TAG ExperienceTag
- Worker HAS_SKILL Skill
- Worker AVAILABLE_IN Region
- Worker HAS_EXPERIENCE ExperienceTag
- Skill SIMILAR_TO Skill
## 8.3 知识入库原则
- 所有岗位文本入库前必须先转成结构化 JobCard
- 所有工人文本入库前必须先转成结构化 WorkerCard
- 技能表、区域表、岗位类别表应先作为基础词表导入
---
## 9. 抽取服务要求
## 9.1 岗位抽取服务
### 输入
自然语言岗位描述文本
### 输出
符合 JobCard schema 的 JSON
### 实现要求
- 优先使用 LLM 进行结构化抽取
- 使用固定 JSON Schema
- 必须包含字段校验
- 抽取失败时返回缺失字段和错误信息
- 必须保留原始 description
### 字段抽取重点
- 岗位标题
- 技能要求
- 城市 / 区域 / 地点
- 时间
- 时长
- 人数
- 薪资
- 标签偏好
## 9.2 工人抽取服务
### 输入
自然语言工人描述文本
### 输出
符合 WorkerCard schema 的 JSON
### 实现要求
- 优先使用 LLM 进行结构化抽取
- 使用固定 JSON Schema
- 必须输出技能项及分值
- 必须输出区域和可服务时间
- 必须保留原始 description
### 字段抽取重点
- 技能
- 经验标签
- 服务区域
- 可服务时间
- 基础可信度字段
## 9.3 Prompt 设计要求
coding agent 必须将 prompt 单独文件化,禁止把 prompt 硬编码到业务逻辑中。
要求至少拆成:
- prompts/job_extract.md
- prompts/worker_extract.md
- prompts/match_explain.md
---
## 10. 匹配引擎要求
## 10.1 匹配模式
必须支持两种:
- 岗位找工人
- 工人找岗位
## 10.2 匹配流程
coding agent 必须按两阶段实现:
### 第一阶段:召回 Recall
召回候选集合时,综合以下条件:
- 技能关键词命中
- 技能近义词/邻接技能命中
- 地理区域命中
- 类别/经验标签命中
- 时间标签粗匹配
### 第二阶段:排序 Rank
按以下公式实现第一版排序:
```text
MatchScore =
0.35 * SkillScore
+ 0.20 * RegionScore
+ 0.15 * TimeScore
+ 0.15 * ExperienceScore
+ 0.15 * ReliabilityScore
```
## 10.3 评分实现约束
### SkillScore
- 先算技能命中率
- 必备技能完全缺失时强制降权
- 近义技能通过图谱扩展加分
### RegionScore
- 同区 = 1.0
- 同城不同区 = 0.7
- 跨城 = 0.2
### TimeScore
POC 阶段允许简化为标签匹配:
- weekend
- weekday_am
- weekday_pm
- anytime
### ExperienceScore
按 experience_tags 与岗位 category/tags 的相似度计算
### ReliabilityScore
POC 可直接读取静态字段或默认值
---
## 11. 推荐解释要求
coding agent 必须为每条匹配结果生成 reasons 数组。
## 11.1 reasons 生成原则
每条推荐至少包含 3 条原因,优先覆盖:
- 技能原因
- 区域原因
- 时间原因
- 经验原因
## 11.2 示例
```json
[
"具备签到、引导相关技能",
"服务区域覆盖南山,与岗位地点一致",
"周末可接单,与岗位时间要求匹配"
]
```
## 11.3 解释生成策略
优先使用规则模板生成,必要时可用 LLM 美化文案。
POC 阶段原则:
> 先保证解释真实可靠,再追求语言自然。
---
## 12. API 设计要求
coding agent 必须至少实现以下 API
## 12.1 系统接口
### `GET /health`
返回服务状态、数据库状态、RAG 状态
## 12.2 抽取接口
### `POST /poc/extract/job`
输入岗位自然语言,返回 JobCard
### `POST /poc/extract/worker`
输入工人自然语言,返回 WorkerCard
## 12.3 入库接口
### `POST /poc/ingest/job`
传入 JobCard写入数据库 + LightRAG
### `POST /poc/ingest/worker`
传入 WorkerCard写入数据库 + LightRAG
### `POST /poc/ingest/bootstrap`
导入样本数据与词表
## 12.4 匹配接口
### `POST /poc/match/workers`
输入 JobCard 或 job_id返回 TopN Worker MatchResult
### `POST /poc/match/jobs`
输入 WorkerCard 或 worker_id返回 TopN Job MatchResult
### `GET /poc/match/explain/{match_id}`
返回指定 match 的详细解释
## 12.5 查询接口
### `GET /poc/jobs`
### `GET /poc/workers`
### `GET /poc/jobs/{job_id}`
### `GET /poc/workers/{worker_id}`
---
## 13. 数据库表要求
coding agent 至少需要实现以下表:
## 13.1 jobs
- id
- title
- category
- description
- city
- region
- location_detail
- start_time
- duration_hours
- headcount
- salary_type
- salary_amount
- tags_json
- confidence
- created_at
## 13.2 job_skills
- job_id
- skill_name
- weight
- is_required
## 13.3 workers
- id
- name
- description
- cities_json
- regions_json
- availability_json
- experience_tags_json
- reliability_score
- profile_completion
- confidence
- created_at
## 13.4 worker_skills
- worker_id
- skill_name
- score
## 13.5 matches
- id
- source_type
- source_id
- target_id
- match_score
- breakdown_json
- reasons_json
- created_at
---
## 14. Web 控制台要求
coding agent 必须实现一个最小可演示前端。
## 14.1 页面 A岗位测试页
### 功能
- 输入岗位描述
- 点击“抽取岗位”
- 显示 JobCard
- 点击“入库并匹配工人”
- 显示匹配结果列表
## 14.2 页面 B工人测试页
### 功能
- 输入工人描述
- 点击“抽取工人画像”
- 显示 WorkerCard
- 点击“入库并匹配岗位”
- 显示匹配结果列表
## 14.3 页面 C数据浏览页
### 功能
- 浏览已导入岗位
- 浏览已导入工人
- 查看详情
## 14.4 页面 D系统状态页
### 功能
- 显示服务健康状态
- 显示数据库连接状态
- 显示 RAG 初始化状态
---
## 15. 样本数据要求
coding agent 必须先提供一批演示数据,不能等待真实数据。
## 15.1 样本规模
- jobs: 100 条
- workers: 300 条
- skills: 100 条
- categories: 30 条
- regions: 20 条
## 15.2 样本质量要求
- 覆盖多个岗位类别:促销、地推、导购、会展、分拣、客服、安装、配送等
- 覆盖多种技能组合
- 覆盖多个时间标签
- 覆盖多个区域标签
## 15.3 样本格式要求
统一存放到:
- packages/sample-data/jobs.json
- packages/sample-data/workers.json
- packages/sample-data/skills.json
- packages/sample-data/categories.json
- packages/sample-data/regions.json
---
## 16. 工程规范要求
## 16.1 代码规范
- 后端采用分层结构router / service / repository / domain
- 所有 schema 使用 Pydantic
- 所有配置通过环境变量管理
- 不允许把密钥写死在代码中
## 16.2 日志规范
必须记录:
- 抽取请求
- 入库请求
- 匹配请求
- RAG 查询请求
- 错误堆栈
## 16.3 错误处理
必须对以下情况返回明确错误:
- LLM 抽取失败
- 结构化字段校验失败
- LightRAG 不可用
- 数据库连接失败
- 样本导入失败
## 16.4 可维护性要求
- Prompt 单独文件化
- 打分权重配置化
- 词表配置化
- 召回 TopN 配置化
---
## 17. 推荐实现顺序
coding agent 必须按以下顺序推进,避免无序开发:
## Step 1初始化工程骨架
- 创建目录结构
- 创建 Docker Compose
- 创建 FastAPI 项目
- 创建前端项目
## Step 2定义 schema 与 shared types
- JobCard
- WorkerCard
- MatchResult
- API Request/Response
## Step 3建立数据库与样本导入
- 建表
- 建初始化脚本
- 导入 sample data
## Step 4实现抽取服务
- job_extract prompt
- worker_extract prompt
- schema 校验
- 抽取接口
## Step 5实现 LightRAG 适配层
- ingest job
- ingest worker
- query candidates
- bootstrap glossary
## Step 6实现匹配引擎
- recall
- rank
- explain
- match 接口
## Step 7实现 Web 控制台
- 岗位测试页
- 工人测试页
- 结果展示页
- 系统状态页
## Step 8补充文档与脚本
- README
- API 文档
- 启动脚本
- 演示说明
---
## 18. 交付物要求
coding agent 最终必须产出以下内容:
### 代码交付
- 完整可运行源码
- Docker Compose 启动方案
- 样本数据
- 初始化脚本
### 文档交付
- README.md
- API.md
- ARCHITECTURE.md
- DEMO.md
### 演示能力
- 一键启动
- 导入样本数据
- 前端输入岗位文本
- 前端输入工人文本
- 查看匹配结果与推荐原因
---
## 19. README 必须包含的内容
README 至少要写清楚:
1. 项目目标
2. 技术栈
3. 目录结构
4. 环境变量说明
5. 启动方式
6. 样本导入方式
7. API 地址
8. 前端访问地址
9. 演示路径
10. 已实现范围与未实现范围
---
## 20. coding agent 禁止事项
coding agent 禁止做以下事情:
1. 禁止擅自扩展到裂变、支付、合同等低优先级模块。
2. 禁止为了“完整性”过度设计微服务。
3. 禁止引入过多基础设施,导致 POC 难以启动。
4. 禁止跳过样本数据准备。
5. 禁止跳过推荐解释能力。
6. 禁止把 prompt、权重、技能词表硬编码到业务逻辑中。
7. 禁止先做 UI 花活而忽视底层检索和匹配内核。
---
## 21. coding agent 任务说明(可直接复制执行)
你现在需要实现一个“灵活用工最小 POC 内核系统”。
目标不是做完整平台,而是打通以下闭环:
- 从自然语言中抽取岗位需求
- 从自然语言中抽取工人技能画像
- 将岗位、工人、技能词表写入 LightRAG
- 支持岗位找人、人找岗位两类检索
- 对召回结果进行排序打分
- 对每个推荐结果生成推荐原因
- 提供一个简单 Web 控制台完成演示
请严格遵守以下原则:
- 优先完成底层能力,不做裂变、支付、合同等外围模块
- 使用 FastAPI + PostgreSQL + LightRAG + React/Vite
- 使用 Docker Compose 保证一键启动
- 使用统一的 JobCard / WorkerCard / MatchResult schema
- 所有 prompt、权重、词表必须配置化
- 必须提供样本数据和 bootstrap 导入脚本
- 必须输出 README、API 文档、架构说明
交付完成后,系统应支持以下演示:
1. 输入一段岗位描述,抽取出结构化岗位。
2. 输入一段工人描述,抽取出结构化画像。
3. 岗位匹配出 TopN 工人,并显示推荐原因。
4. 工人匹配出 TopN 岗位,并显示推荐原因。
5. 前端页面可完整演示这条流程。
---
## 22. 最终执行结论
> 当前阶段唯一正确的开发顺序,是先把“岗位—工人—技能—检索—匹配—解释”这条链打透。
只要这条底层链路成立,后续再叠加裂变传播、电子合同、支付结算、运营后台,才有意义。