feat: add new folder

2026-03-30 20:49:40 +08:00
commit c7788fdd92
64 changed files with 19910 additions and 0 deletions
--- a/gig_poc_coding_agent_guide.md
+++ b/gig_poc_coding_agent_guide.md
@@ -0,0 +1,784 @@
+# 灵活用工最小 POC：Coding 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. 最终执行结论
+
+> 当前阶段唯一正确的开发顺序，是先把“岗位—工人—技能—检索—匹配—解释”这条链打透。
+
+只要这条底层链路成立，后续再叠加裂变传播、电子合同、支付结算、运营后台，才有意义。
+