新增三大股东接口, 补充 SKILLS.md 使用说明书

- 新增 十大流通股东/十大股东明细/股东户数 三个抓取模块并接入 API
- 冒烟测试扩展至 30 用例, 全部通过
- 新增 SKILLS.md (给其他 agent 使用的工具说明书)
- 补充待优化端点清单与文档对齐规范

api.py

@@ -26,6 +26,9 @@ from utils.fin_operate import get_operate_ability
 from utils.fin_growth import get_growth
 from utils.fin_dupont import get_dupont
 from utils.fin_dividend import get_dividend_detail, get_dividend_statics
+from utils.fin_free_holders import get_free_holders
+from utils.fin_holders import get_holders
+from utils.fin_holder_num import get_holder_num
 
 
 app = FastAPI(
@@ -131,6 +134,9 @@ def root():
             "GET /fin/dupont": "拉取杜邦分析",
             "GET /fin/dividend-detail": "拉取分红明细",
             "GET /fin/dividend-statics": "拉取分红统计",
+            "GET /fin/free-holders": "拉取十大流通股东",
+            "GET /fin/holders": "拉取十大股东明细",
+            "GET /fin/holder-num": "拉取股东户数",
             "GET /health": "健康检查",
         },
         "usage": {
@@ -498,6 +504,66 @@ def fin_dividend_statics(
     return payload
 
 
+@app.get("/fin/free-holders")
+def fin_free_holders(
+    stocks: str = Query(..., description="股票代码，逗号分隔，例如 '603233.SH'。仅支持代码，不需要 ORG_CODE。", examples=["603233.SH"]),
+    years: int = Query(3, ge=1, le=20, description="拉取最近多少年的十大流通股东"),
+):
+    """拉取十大流通股东。"""
+    codes = [code.strip() for code in stocks.split(",") if code.strip()]
+    if not codes:
+        raise HTTPException(400, detail="stocks 参数不能为空")
+
+    df = get_free_holders(codes, years=years)
+    if df.empty:
+        return _empty_response("无十大流通股东数据, 请检查股票代码或筛选条件", codes, years=years)
+
+    payload = _df_to_json_payload(df)
+    payload["codes_requested"] = codes
+    payload["years"] = years
+    return payload
+
+
+@app.get("/fin/holders")
+def fin_holders(
+    stocks: str = Query(..., description="股票代码，逗号分隔，例如 '603233.SH'。仅支持代码，不需要 ORG_CODE。", examples=["603233.SH"]),
+    years: int = Query(3, ge=1, le=20, description="拉取最近多少年的十大股东明细"),
+):
+    """拉取十大股东明细。"""
+    codes = [code.strip() for code in stocks.split(",") if code.strip()]
+    if not codes:
+        raise HTTPException(400, detail="stocks 参数不能为空")
+
+    df = get_holders(codes, years=years)
+    if df.empty:
+        return _empty_response("无十大股东明细数据, 请检查股票代码或筛选条件", codes, years=years)
+
+    payload = _df_to_json_payload(df)
+    payload["codes_requested"] = codes
+    payload["years"] = years
+    return payload
+
+
+@app.get("/fin/holder-num")
+def fin_holder_num(
+    stocks: str = Query(..., description="股票代码，逗号分隔，例如 '603233.SH'。仅支持代码，不需要 ORG_CODE。", examples=["603233.SH"]),
+    years: int = Query(3, ge=1, le=20, description="拉取最近多少年的股东户数"),
+):
+    """拉取股东户数。"""
+    codes = [code.strip() for code in stocks.split(",") if code.strip()]
+    if not codes:
+        raise HTTPException(400, detail="stocks 参数不能为空")
+
+    df = get_holder_num(codes, years=years)
+    if df.empty:
+        return _empty_response("无股东户数数据, 请检查股票代码或筛选条件", codes, years=years)
+
+    payload = _df_to_json_payload(df)
+    payload["codes_requested"] = codes
+    payload["years"] = years
+    return payload
+
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(app, host="0.0.0.0", port=8765, log_level="info")