docs(skill): 模块自述技能+README同步P1需求挖掘——4工具/架构图/机构隔离定夺/VDB协议/性能铁律(串行540s→并发60s)/params种子/验证脚本用法

skill/SKILL.md

@@ -60,6 +60,10 @@ appbase `params` 表两个键（`opp_common.get_crawler_config` 读取，默认
 | `opp_submit_report(report_id)` | 提交人工确认（创建门禁任务） |
 | `opp_list_approvals` | 审批单列表 |
 | `opp_diagnose` | 产线诊断 |
+| `opp_start_mining(scope,keyword,category,days,sources)` | 启动需求挖掘批次（后台执行立即返回batch_id；scope=top全量TopX / targeted指定类型必带keyword） |
+| `opp_mining_status(batch_id)` | 批次状态轮询（pulling/embedding/clustering/naming/done/failed+原因） |
+| `opp_list_clusters(batch_id)` | 类别排名表（热度/需求数/占比/命名证据）= TopX 热门类别 |
+| `opp_cluster_detail(cluster_id,limit)` | 类内需求明细样例（每条带来源URL可查证） |
 
 角色：`agent.opp_analyst` / `agent.opp_writer`；slash：`/hot` `/ai` `/reports` `/oppdiag`。
 
@@ -75,11 +79,39 @@ draft ──人工确认──> confirmed ──发起──> approval_initiated
 - 非法迁移一律拒绝（`REPORT_TRANSITIONS`）。
 - 报告中的招标数字必须来自工具返回的真实数据，禁止编造；引用带来源链接。
 
+## 需求挖掘（P1，众包需求→语义聚类→TopX/指定类型）
+
+```
+众包需求(爬虫 record_type=demand)
+   → 快照 opp_demand_snap(batch+src_id去重)
+   → embedding(rag /rag/api/embed.dspy ← rag_client.rag_embed_texts Bearer,共享缓存collection一条只嵌一次)
+   → 批次工作集 collection(VDB/Milvus, upapp.rag-vdb)
+   → kNN(/v1/query+vector+pagerows) + τ阈值(默认0.75) + 并查集 → 大簇质心二次细分(>150)
+   → LLM 簇命名(并发Semaphore5, utility purpose, 失败规则兜底)
+   → opp_clusters(heat_rank/share/naming_evidence)
+```
+
+- **编排** opp_mining_flow.py：状态机 pulling→embedding→clustering→naming→done/failed，
+  `asyncio.create_task` 后台跑，进度实时落 `stats_json`，失败落 `error_msg`（可行动报错，
+  禁前端挂起干等）。**算法/VDB/embedding** opp_mining.py。
+- **机构隔离**（用户定夺）：基础数据（需求快照+embedding缓存）全机构共享；分析结果
+  （批次/快照归属/类别）挂 `org_id`，所有查询按 ctx.org_id 强制过滤（伪 org 拒绝实测通过）。
+- **VDB 协议**（实测，详见技能 rag-module-operations）：kNN=`/v1/query`+vector+pagerows
+  （非 /v1/search）；标量过滤=`expr`（非 filter）；kNN+expr 组合可用；output_fields 可取回
+  vector；dropcollection 可用（旧批工作集自动清理，保留最近 opp_mine_keep_batches 个）。
+- **性能**：批量 LLM/embedding 一律并发+缓存禁串行（实测 42簇串行命名 540s→并发 60s）。
+- **算法参数**走 appbase params（init/data.json params 段 build.sh 幂等种子）：
+  opp_mine_tau/topk/min_cluster/big_split/keep_batches、opp_embed_batch、opp_emb_cache_col。
+- **验证脚本** scripts/p1_cluster_analyze.py（多τ对比调参，向量/kNN文件缓存）；
+  E2E 须 P1_PROJECT_ID=真实商机项目（owner→Bearer key），独立脚本要 initEnv() 注入
+  password_decode，凭据走环境变量（密码字面量会被秘密扫描替换成 ***）。
+
 ## 部署清单（宿主侧）
 
-1. `build.sh`（建表+种子+wwwroot 软链+pip install）
+1. `build.sh`（建表+种子 appcodes/pipelines/params+wwwroot 软链+pip install）
 2. app 入口 `load_pipeline_opportunity()`（已接线，try/except 兜底）
 3. `scripts/load_path.py` 注册 RBAC
 4. i18n 合并 `i18n/{zh,en}/msg.txt`
-5. params 表配 `tender_api_base` / `tender_api_token`
-6. 重启 → 驾驶舱验证 `/hot` 或 `opp_diagnose`
+5. params 表配 `tender_api_base` / `tender_api_token`（挖掘依赖 embedding：rag 引擎
+   配置 rag_engine_configs + upapp.rag-vdb，复用宿主已部署的 rag/VDB，无需额外配置）
+6. 重启 → 驾驶舱验证 `/hot` 或 `opp_diagnose`；挖掘验证 opp_start_mining→status→list_clusters