Daniel/Airtep

Fork 0

Files

Daniel c7788fdd92 feat: add new folder

2026-03-30 20:49:40 +08:00

16 KiB

Raw Blame History

灵活用工最小 POC：Coding Agent 指导文档

1. 文档目的

本指导文档用于直接驱动 coding agent 落地一个“灵活用工最小 POC 内核系统”。

本次实现目标不是完整平台，不是完整招聘系统，也不是完整裂变系统，而是优先打通最核心的底层能力闭环：

岗位理解 → 工人理解 → LightRAG 检索 → 匹配排序 → 推荐解释

coding agent 必须严格围绕这个主线执行，避免在低优先级模块上消耗时间。

2. 项目目标定义

2.1 业务目标

构建一个最小可运行的 POC，用于验证：

平台能否从自然语言中提取岗位需求。
平台能否从自然语言中提取工人技能画像。
平台能否利用 LightRAG 构建“岗位—技能—工人”知识关联。
平台能否完成岗位找人、人找岗位两类匹配。
平台能否为匹配结果给出可解释的推荐原因。

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 必须按以下结构组织项目：

/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 必须实现以下结构：

{
  "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

{
  "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

{
  "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

按以下公式实现第一版排序：

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 示例

[
  "具备签到、引导相关技能",
  "服务区域覆盖南山，与岗位地点一致",
  "周末可接单，与岗位时间要求匹配"
]

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 至少要写清楚：

项目目标
技术栈
目录结构
环境变量说明
启动方式
样本导入方式
API 地址
前端访问地址
演示路径
已实现范围与未实现范围

20. coding agent 禁止事项

coding agent 禁止做以下事情：

禁止擅自扩展到裂变、支付、合同等低优先级模块。
禁止为了“完整性”过度设计微服务。
禁止引入过多基础设施，导致 POC 难以启动。
禁止跳过样本数据准备。
禁止跳过推荐解释能力。
禁止把 prompt、权重、技能词表硬编码到业务逻辑中。
禁止先做 UI 花活而忽视底层检索和匹配内核。

21. coding agent 任务说明（可直接复制执行）

你现在需要实现一个“灵活用工最小 POC 内核系统”。

目标不是做完整平台，而是打通以下闭环：

从自然语言中抽取岗位需求
从自然语言中抽取工人技能画像
将岗位、工人、技能词表写入 LightRAG
支持岗位找人、人找岗位两类检索
对召回结果进行排序打分
对每个推荐结果生成推荐原因
提供一个简单 Web 控制台完成演示

请严格遵守以下原则：

优先完成底层能力，不做裂变、支付、合同等外围模块
使用 FastAPI + PostgreSQL + LightRAG + React/Vite
使用 Docker Compose 保证一键启动
使用统一的 JobCard / WorkerCard / MatchResult schema
所有 prompt、权重、词表必须配置化
必须提供样本数据和 bootstrap 导入脚本
必须输出 README、API 文档、架构说明

交付完成后，系统应支持以下演示：

输入一段岗位描述，抽取出结构化岗位。
输入一段工人描述，抽取出结构化画像。
岗位匹配出 TopN 工人，并显示推荐原因。
工人匹配出 TopN 岗位，并显示推荐原因。
前端页面可完整演示这条流程。

22. 最终执行结论

当前阶段唯一正确的开发顺序，是先把“岗位—工人—技能—检索—匹配—解释”这条链打透。

只要这条底层链路成立，后续再叠加裂变传播、电子合同、支付结算、运营后台，才有意义。

16 KiB Raw Blame History Unescape Escape

灵活用工最小 POC：Coding Agent 指导文档

1. 文档目的

2. 项目目标定义

2.1 业务目标

2.2 POC 成功标准

3. 本次实现边界

3.1 本次必须实现

核心输入能力

核心 AI 能力

核心输出能力

基础交互能力

3.2 本次明确不做

4. 一句话架构原则

5. 技术栈要求

5.1 后端

5.2 数据层

5.3 AI / RAG

5.4 前端

5.5 部署方式

6. 项目目录结构要求

6.1 apps/web

6.2 apps/api

6.3 packages/shared-types

6.4 packages/prompts

6.5 packages/sample-data

7. 统一数据结构定义

7.1 JobCard

7.2 WorkerCard

7.3 MatchResult

8. LightRAG 数据建模要求

8.1 最小实体

8.2 最小关系

8.3 知识入库原则

9. 抽取服务要求

9.1 岗位抽取服务

输入

输出

实现要求

字段抽取重点

9.2 工人抽取服务

输入

输出

实现要求

字段抽取重点

9.3 Prompt 设计要求

10. 匹配引擎要求

10.1 匹配模式

10.2 匹配流程

第一阶段：召回 Recall

第二阶段：排序 Rank

10.3 评分实现约束

SkillScore

RegionScore

TimeScore

ExperienceScore

ReliabilityScore

11. 推荐解释要求

11.1 reasons 生成原则

11.2 示例

11.3 解释生成策略

12. API 设计要求

12.1 系统接口

GET /health

12.2 抽取接口

POST /poc/extract/job

POST /poc/extract/worker

12.3 入库接口

POST /poc/ingest/job

POST /poc/ingest/worker

POST /poc/ingest/bootstrap

12.4 匹配接口

POST /poc/match/workers

POST /poc/match/jobs

GET /poc/match/explain/{match_id}

12.5 查询接口

GET /poc/jobs

GET /poc/workers

GET /poc/jobs/{job_id}

GET /poc/workers/{worker_id}

16 KiB

Raw Blame History

`GET /health`

`POST /poc/extract/job`

`POST /poc/extract/worker`

`POST /poc/ingest/job`

`POST /poc/ingest/worker`

`POST /poc/ingest/bootstrap`

`POST /poc/match/workers`

`POST /poc/match/jobs`

`GET /poc/match/explain/{match_id}`

`GET /poc/jobs`

`GET /poc/workers`

`GET /poc/jobs/{job_id}`

`GET /poc/workers/{worker_id}`