# 灵活用工最小 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. 最终执行结论 > 当前阶段唯一正确的开发顺序，是先把“岗位—工人—技能—检索—匹配—解释”这条链打透。 只要这条底层链路成立，后续再叠加裂变传播、电子合同、支付结算、运营后台，才有意义。